breadcrumb-the-shire/docs/reference-agents-flow.md

Agent Workflow

Letzte Aktualisierung: 2026-03-06

State Machine

• planned
• executing
• review_guard
• review_acceptance
• finalize
• done

If a reviewer returns FAIL, state goes back to executing with explicit findings.

Minimum Handover Artifacts

• Planner: plan.json
• Executor: execution-report.json
• Reviewer Guards: review-guards.json
• Reviewer Acceptance: review-acceptance.json
• Finalizer: finalize.json

Guard and Gate Binding

• Planner selects required guard IDs from agent-system/checks/guard-catalog.json.
• Planner selects required quality gate IDs from agent-system/checks/quality-gates.json.
• Planner assigns stable success criteria IDs (SC-*) in plan.json.
• Executor must provide guard evidence and gate results by ID.
• Guard reviewer verifies and reports verdict against the same IDs.
• Acceptance reviewer verifies and reports verdict against the same SC-* IDs.

Fail Loop Rule

• No free-text "please improve".
• Every fail must include:
  • id
  • severity
  • file
  • expected fix

Practical Rollout

• Start with one small issue.
• Run workflow manually with templates.
• Stabilize contracts first.
• Add automation only after 3 to 5 successful runs.