breadcrumb-the-shire/.agents/workflow.md

Agent Workflow

Last updated: 2026-03-19

Overview

This project uses a 7-role workflow for issue and feature delivery.

Analyst → Planner → Executor → Code Reviewer ──┐
                                                ├→ Finalizer
                        Security Reviewer ──────┤
                        Acceptance Tester ───────┘

Primary goals:

• Front-load context gathering (Analyst) so downstream roles start informed
• Separate code quality review from security review for focused attention
• Explicit guard IDs (GR-*), gate IDs (QG-*), and success criteria (SC-*) across all roles
• Fast retry loop from reviewers back to executor

Source of truth:

• Guard catalog (22 guards): .agents/checks/guard-catalog.json
• Quality gates (9 gates): .agents/checks/quality-gates.json
• Enforcement policy (workflow trigger + gate enforcement): .agents/checks/enforcement-policy.json
• Guard enforcement map (guard -> automated/hybrid/reviewer evidence): .agents/checks/guard-enforcement-map.json
• Contracts: .agents/contracts/

---

Roles

Analyst

• Input: issue description or feature request
• Output: analysis.json (see .agents/contracts/analyst.schema.json)
• Gathers context: affected layers, files, patterns, tests, security surface
• Does NOT propose solutions — only structures facts for the Planner

Planner

• Input: analysis.json
• Output: plan.json (see .agents/contracts/planner.schema.json)
• Defines scope, guard selection, success criteria, implementation steps, risks
• References concrete file paths from analysis — does not re-explore codebase

Executor

• Input: approved plan.json
• Output: execution-report.json (see .agents/contracts/executor.schema.json)
• Implements plan, runs quality gates, provides guard evidence

Code Reviewer

• Input: code diff + execution-report.json
• Output: review-code.json (see .agents/contracts/reviewer-code.schema.json)
• Scope: architecture, conventions, testing, UI standards (13 guards)
• Guards: GR-CORE-*, GR-TEST-*, GR-UI-*

Security Reviewer

• Input: code diff + execution-report.json
• Output: review-security.json (see .agents/contracts/reviewer-security.schema.json)
• Scope: authz, tenant scope, CSRF, input validation, crypto, file storage (9 guards)
• Guards: GR-SEC-*
• Any critical or high finding forces fail verdict

Acceptance Tester

• Input: code diff + plan.json
• Output: review-acceptance.json (see .agents/contracts/reviewer-acceptance.schema.json)
• Verifies each SC-* success criterion is met

Finalizer

• Input: review-code.json + review-security.json + review-acceptance.json
• Output: finalize.json (see .agents/contracts/finalizer.schema.json)
• All three reviews must pass. CI must be green. Otherwise: hold.

---

State Machine

analyzed → planned → executing → reviewing → finalize → done
                        ↑            |
                        └────────────┘  (on any FAIL)

The reviewing state runs Code Reviewer, Security Reviewer, and Acceptance Tester. If any reviewer returns FAIL, state goes back to executing with explicit findings.

Workflow Trigger Policy

Workflow triggering is risk-based and centrally defined in:

• .agents/checks/enforcement-policy.json (full_workflow_required_when)
• .agents/checks/enforcement-policy.json (quick_fix_allowlist)

Interpretation:

• Full workflow is mandatory for risk/security/data-boundary/module/cross-layer changes
• Quick fixes are only exempt if they match the explicit allowlist
• >1 layer remains a useful heuristic but is no longer the sole trigger

Handover Artifacts

Role	Artifact
Analyst	analysis.json
Planner	plan.json
Executor	execution-report.json
Code Reviewer	review-code.json
Security Reviewer	review-security.json
Acceptance Tester	review-acceptance.json
Finalizer	finalize.json

Fail Loop Rule

No free-text "please improve". Every fail must include:

• id
• severity
• file
• expected fix

Guard Assignment

Guards are split by reviewer role (see reviewer field in guard-catalog.json):

Code Reviewer (13 guards): GR-CORE-003, GR-CORE-007, GR-CORE-010, GR-CORE-011, GR-CORE-012, GR-TEST-001, GR-TEST-002, GR-UI-014, GR-UI-LIST, GR-UI-DETAIL, GR-UI-A11Y, GR-UI-I18N, GR-UI-REUSE

Security Reviewer (9 guards): GR-SEC-001 through GR-SEC-009

What automated tests already enforce

The following concerns are covered by QG-001/QG-003/QG-004 and do NOT need manual guard review:

• Layering boundaries (CoreStarterkitContractTest)
• No direct service instantiation in pages (structural rg checks)
• No superglobals in pages (architecture tests)
• PSR-4 namespace alignment (autoloader + QG-003)
• PHP code style (QG-006)
• Module namespace isolation (ModuleStructureContractTest)
• Module UI via slots only (NoBookmarksHardcodingTest, NoAddressBookHardcodingTest)
• Runtime fingerprint (web/index.php fail-fast)
• Repository sanitizeLimitOffset (RepositoryInterfaceContractTest)
• List init standard, legacy filter toggle, template RBAC (architecture tests)
• Component lifecycle contract (architecture tests)
• Guard reference integrity (GR-*/QG-*) across docs/agents/tests/bin
• Guard enforcement mapping completeness and automated evidence file existence