bee-dev-cycle

name	bee:dev-cycle
description	Main orchestrator for the 8-gate development cycle system. Loads tasks/subtasks from PM team output and executes through implementation → unit testing → fuzz testing → property testing → integration testing (write) → chaos testing (write) → review → validation gates (Gates 0-7), with state persistence and metrics collection. Gates 4-5 (integration/chaos) write and update test code per unit but only execute tests at end of cycle (deferred execution).
trigger	- Starting a new development cycle with a task file - Resuming an interrupted development cycle (--resume flag) - Need structured, gate-based task execution with quality checkpoints
prerequisite	- Tasks file exists with structured subtasks - Not already in a specific gate skill execution - Human has not explicitly requested manual workflow
NOT_skip_when	- "Task is simple" → Simple ≠ risk-free. Execute gates. - "Tests already pass" → Tests ≠ review. Different concerns. - "Time pressure" → Pressure ≠ permission. Document and proceed. - "Already did N gates" → Sunk cost is irrelevant. Complete all gates.
sequence	{"before":["bee:dev-feedback-loop"]}
related	{"complementary":["bee:dev-implementation","bee:dev-unit-testing","bee:requesting-code-review","bee:dev-validation","bee:dev-feedback-loop"]}
verification	{"automated":[{"command":"test -f docs/bee:dev-cycle/current-cycle.json || test -f docs/bee:dev-refactor/current-cycle.json","description":"State file exists (bee:dev-cycle or bee:dev-refactor)","success_pattern":"exit 0"},{"command":"cat docs/bee:dev-cycle/current-cycle.json 2>/dev/null || cat docs/bee:dev-refactor/current-cycle.json | jq '.current_gate'","description":"Current gate is valid","success_pattern":"[0-5]"}],"manual":["All gates for current task show PASS in state file","No tasks have status 'blocked' for more than 3 iterations"]}
examples	[{"name":"New feature from PM workflow","invocation":"/bee:dev-cycle docs/pre-dev/auth/tasks.md","expected_flow":"1. Load tasks with subtasks from tasks.md\n2. Ask user for checkpoint mode (per-task/per-gate/continuous)\n3. Execute Gate 0→1→2→3→4→5→6→7 for each task sequentially\n4. Generate feedback report after completion\n"},{"name":"Resume interrupted cycle","invocation":"/bee:dev-cycle --resume","expected_state":"Continues from last saved gate in current-cycle.json"},{"name":"Execute with per-gate checkpoints","invocation":"/bee:dev-cycle tasks.md --checkpoint per-gate","expected_flow":"1. Execute Gate 0, pause for approval\n2. User approves, execute Gate 1, pause\n3. Continue until all 8 gates complete\n"},{"name":"Execute with custom context for agents","invocation":"/bee:dev-cycle tasks.md \"Focus on error handling. Use existing UserRepository.\"","expected_flow":"1. Load tasks and store custom_prompt in state\n2. All agent dispatches include custom instructions as context\n3. Custom context visible in execution report\n"},{"name":"Instructions-only mode (no tasks file)","invocation":"/bee:dev-cycle \"Implement multi-tenant support with organization_id in all entities\"","expected_flow":"1. Detect prompt-only mode (no task file provided)\n2. Dispatch bee:codebase-explorer to analyze project\n3. Generate tasks internally from prompt + codebase analysis\n4. Present generated tasks for user confirmation\n5. Execute Gate 0→1→2→3→4→5→6→7 for each generated task\n"}]

Development Cycle Orchestrator

Standards Loading (MANDATORY)

Before any gate execution, you MUST load Bee standards:

<fetch_required> https://raw.githubusercontent.com/luanrodrigues/ia-frmwrk/master/CLAUDE.md </fetch_required>

Fetch URL above and extract: Agent Modification Verification requirements, Anti-Rationalization Tables requirements, and Critical Rules.

<block_condition>

• WebFetch fails or returns empty
• CLAUDE.md not accessible </block_condition>

If any condition is true, STOP and report blocker. Cannot proceed without Bee standards.

Overview

The development cycle orchestrator loads tasks/subtasks from PM team output (or manual task files) and executes through 8 gates (Gate 0–7) with deferred execution for infrastructure-dependent tests:

• Gates 0-3, 6-7 (per unit): Write code + run tests per task/subtask
• Gates 4-5 (per unit): Write/update integration and chaos test code, verify compilation, but do not execute tests (no containers)
• Gates 4-5 (end of cycle): Execute all integration and chaos tests once after all units complete

This keeps test code current with each feature while avoiding redundant container spin-ups during development.

MUST announce at start: "I'm using the bee:dev-cycle skill to orchestrate task execution through 8 gates (Gate 0–7). Gates 4-5 write tests per unit but execute at end of cycle."

⛔ CRITICAL: Specialized Agents Perform All Tasks

See shared-patterns/shared-orchestrator-principle.md for full ORCHESTRATOR principle, role separation, forbidden/required actions, gate-to-agent mapping, and anti-rationalization table.

Summary: You orchestrate. Agents execute. If using Read/Write/Edit/Bash on source code → STOP. Dispatch agent.

---

⛔ ORCHESTRATOR BOUNDARIES (HARD GATE)

This section defines exactly what the orchestrator CAN and CANNOT do.

What Orchestrator CAN Do (PERMITTED)

Action	Tool	Purpose
Read task files	Read	Load task definitions from docs/pre-dev/*/tasks.md or docs/bee:dev-refactor/*/tasks.md
Read state files	Read	Load/verify docs/bee:dev-cycle/current-cycle.json or docs/bee:dev-refactor/current-cycle.json
Read PROJECT_RULES.md	Read	Load project-specific rules
Write state files	Write	Persist cycle state to JSON
Track progress	TodoWrite	Maintain task list
Dispatch agents	Task	Send work to specialist agents
Ask user questions	AskUserQuestion	Get execution mode, approvals
WebFetch standards	WebFetch	Load Bee standards

What Orchestrator CANNOT Do (FORBIDDEN)

- Read source code (`Read` on `*.php`, `*.ts`, `*.tsx`) - Agent reads code, not orchestrator - Write source code (`Write`/`Create` on `*.php`, `*.ts`) - Agent writes code, not orchestrator - Edit source code (`Edit` on `*.php`, `*.ts`, `*.tsx`) - Agent edits code, not orchestrator - Run tests (`Execute` with `php artisan test`, `npm test`) - Agent runs tests in TDD cycle - Analyze code (Direct pattern analysis) - `bee:codebase-explorer` analyzes - Make architectural decisions (Choosing patterns/libraries) - User decides, agent implements

Any of these actions by orchestrator = IMMEDIATE VIOLATION. Dispatch agent instead.

---

The 3-FILE RULE

If a task requires editing MORE than 3 files → MUST dispatch specialist agent.

This is not negotiable:

• 1-3 files of non-source content (markdown, json, yaml) → Orchestrator MAY edit directly
• 1+ source code files (*.php, *.ts, *.tsx) → MUST dispatch agent
• 4+ files of any type → MUST dispatch agent

Orchestrator Workflow Order (MANDATORY)

┌─────────────────────────────────────────────────────────────────┐
│  CORRECT WORKFLOW ORDER                                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. Load task file (Read docs/pre-dev/*/tasks.md or docs/bee:dev-refactor/*/tasks.md) │
│  2. Ask execution mode (AskUserQuestion)                        │
│  3. Determine state path + Check/Load state (see State Path Selection) │
│  4. WebFetch Bee Standards                                     │
│  5. ⛔ LOAD SUB-SKILL for current gate (Skill tool)            │
│  6. Execute sub-skill instructions (dispatch agent via Task)    │
│  7. Wait for agent completion                                   │
│  8. Verify agent output (Standards Coverage Table)              │
│  9. Update state (Write to JSON)                               │
│  10. Proceed to next gate                                       │
│                                                                 │
│  ════════════════════════════════════════════════════════════   │
│  ❌ WRONG: Load → Mode → Standards → Task(agent) directly       │
│  ✅ RIGHT: Load → Mode → Standards → Skill(sub) → Task(agent)   │
│  ════════════════════════════════════════════════════════════   │
└─────────────────────────────────────────────────────────────────┘

⛔ SUB-SKILL LOADING IS MANDATORY (HARD GATE)

Before dispatching any agent, you MUST load the corresponding sub-skill first.

<cannot_skip>

• Gate 0: Skill("bee:dev-implementation") → then Task(subagent_type="bee:backend-engineer-*", ...)
• Gate 1: Skill("bee:dev-unit-testing") → then Task(subagent_type="bee:qa-analyst", test_mode="unit", ...)
• Gate 2: Skill("bee:dev-fuzz-testing") → then Task(subagent_type="bee:qa-analyst", test_mode="fuzz", ...)
• Gate 3: Skill("bee:dev-property-testing") → then Task(subagent_type="bee:qa-analyst", test_mode="property", ...)
• Gate 4: Skill("bee:dev-integration-testing") → per unit: write/update tests + compile check (no execution); end of cycle: execute
• Gate 5: Skill("bee:dev-chaos-testing") → per unit: write/update tests + compile check (no execution); end of cycle: execute
• Gate 6: Skill("bee:requesting-code-review") → then 5x Task(...) in parallel
• Gate 7: Skill("bee:dev-validation") → N/A (verification only) </cannot_skip>

Between "WebFetch standards" and "Task(agent)" there MUST be "Skill(sub-skill)".

⛔ Agent Name Resolution: When dispatching agents, MUST resolve unified bee: names to runtime-qualified names. See shared-patterns/shared-orchestrator-principle.md → "Agent Runtime Resolution" for the full mapping (e.g., bee:backend-engineer-php → bee-dev-team:bee:backend-engineer-php).

The workflow for each gate is:

1. Skill("[sub-skill-name]")     ← Load sub-skill instructions
2. Follow sub-skill instructions  ← Sub-skill tells you HOW to dispatch
3. Task(subagent_type=...)       ← Dispatch agent (use runtime-qualified name)
4. Validate agent output          ← Per sub-skill validation rules
5. Update state                   ← Record results

Custom Instructions (Optional Second Argument)

Validation: See shared-patterns/custom-prompt-validation.md for max length (500 chars), sanitization rules, gate protection, and conflict handling.

If custom_prompt is set in state, inject it into ALL agent dispatches:

Task tool:
  subagent_type: "bee:backend-engineer-php"
  model: "opus"
  prompt: |
    **CUSTOM CONTEXT (from user):**
    {state.custom_prompt}
    
    ---
    
    **Standard Instructions:**
    [... rest of agent prompt ...]

Rules for custom prompt:

1. Inject at TOP of prompt - User context takes precedence
2. Preserve in state - custom_prompt persists for resume
3. Include in execution report - Document what context was used
4. Forward via state - Sub-skills read custom_prompt from state file and inject into their agent dispatches (no explicit parameter passing needed)

Example custom prompts and their effect:

Custom Prompt	Effect on Agents
"Focus on error handling first"	Agents prioritize error-related acceptance criteria
"Use existing UserRepository interface"	Agents integrate with specified interface instead of creating new
"Deprioritize UI polish"	Gate 3 still enforces 85% coverage, but agents deprioritize non-functional UI tweaks
"Prioritize observability gaps"	Implementation focuses on instrumentation; reviewers check observability gaps

Anti-Rationalization for Skipping Sub-Skills

Rationalization	Why It's WRONG	Required Action
"I know what the sub-skill does"	Knowledge ≠ execution. Sub-skill has iteration logic.	Load Skill() first
"Task() directly is faster"	Faster ≠ correct. Sub-skill has validation rules.	Load Skill() first
"Sub-skill just wraps Task()"	Sub-skills have retry logic, fix dispatch, validation.	Load Skill() first
"I'll follow the pattern manually"	Manual = error-prone. Sub-skill is the pattern.	Load Skill() first

Between "WebFetch standards" and "Task(agent)" there MUST be "Skill(sub-skill)".

---

Anti-Rationalization for Direct Coding

Rationalization	Why It's WRONG	Required Action
"It's just one small file"	File count doesn't determine agent need. Language does.	DISPATCH specialist agent
"I already loaded the standards"	Loading standards ≠ permission to implement. Standards are for AGENTS.	DISPATCH specialist agent
"Agent dispatch adds overhead"	Overhead ensures compliance. Skip = skip verification.	DISPATCH specialist agent
"I can write PHP/TypeScript"	Knowing language ≠ having Bee standards loaded. Agent has them.	DISPATCH specialist agent
"Just a quick fix"	"Quick" is irrelevant. all source changes require specialist.	DISPATCH specialist agent
"I'll read the file first to understand"	Reading source → temptation to edit. Agent reads for you.	DISPATCH specialist agent
"Let me check if tests pass first"	Agent runs tests in TDD cycle. You don't run tests.	DISPATCH specialist agent

Red Flags - Orchestrator Violation in Progress

If you catch yourself doing any of these, STOP IMMEDIATELY:

🚨 RED FLAG: About to Read *.php or *.ts file
   → STOP. Dispatch agent instead.

🚨 RED FLAG: About to Write/Create source code
   → STOP. Dispatch agent instead.

🚨 RED FLAG: About to Edit source code
   → STOP. Dispatch agent instead.

🚨 RED FLAG: About to run "php artisan test" or "npm test"
   → STOP. Agent runs tests, not you.

🚨 RED FLAG: Thinking "I'll just..."
   → STOP. "Just" is the warning word. Dispatch agent.

🚨 RED FLAG: Thinking "This is simple enough..."
   → STOP. Simplicity is irrelevant. Dispatch agent.

🚨 RED FLAG: Standards loaded, but next action is not Task tool
   → STOP. After standards, IMMEDIATELY dispatch agent.

Recovery from Orchestrator Violation

If you violated orchestrator boundaries:

1. STOP current execution immediately
2. DISCARD any direct changes (git checkout -- .)
3. DISPATCH the correct specialist agent
4. Agent implements from scratch following TDD
5. Document the violation for feedback loop

Sunk cost of direct work is IRRELEVANT. Agent dispatch is MANDATORY.

---

Blocker Criteria - STOP and Report

<block_condition>

• Gate Failure: Tests not passing, review failed → STOP, cannot proceed to next gate
• Missing Standards: No PROJECT_RULES.md → STOP, report blocker and wait
• Agent Failure: Specialist agent returned errors → STOP, diagnose and report
• User Decision Required: Architecture choice, framework selection → STOP, present options </block_condition>

You CANNOT proceed when blocked. Report and wait for resolution.

Cannot Be Overridden

<cannot_skip>

• All 8 gates must execute (0→1→2→3→4→5→6→7) - Each gate catches different issues
• All testing gates (1-5) are MANDATORY - Comprehensive test coverage ensures quality
• Gates execute in order (0→1→2→3→4→5→6→7) - Dependencies exist between gates
• Gate 6 requires all 6 reviewers - Different review perspectives are complementary
• Coverage threshold ≥ 85% - Industry standard for quality code
• PROJECT_RULES.md must exist - Cannot verify standards without target </cannot_skip>

No exceptions. User cannot override. Time pressure cannot override.

---

Severity Calibration

Severity	Criteria	Examples
CRITICAL	Blocks deployment, security risk, data loss	Gate violation, skipped mandatory step
HIGH	Major functionality broken, standards violation	Missing tests, wrong agent dispatched
MEDIUM	Code quality, maintainability issues	Incomplete documentation, minor gaps
LOW	Best practices, optimization	Style improvements, minor refactoring

Report all severities. Let user prioritize.

Reviewer Verdicts Are Final

MEDIUM issues found in Gate 4 MUST be fixed. No exceptions.

Request	Why It's WRONG	Required Action
"Can reviewer clarify if MEDIUM can defer?"	Reviewer already decided. MEDIUM means FIX.	Fix the issue, re-run reviewers
"Ask if this specific case is different"	Reviewer verdict accounts for context already.	Fix the issue, re-run reviewers
"Request exception for business reasons"	Reviewers know business context. Verdict is final.	Fix the issue, re-run reviewers

Severity mapping is absolute:

• CRITICAL/HIGH/MEDIUM → Fix NOW, re-run all 6 reviewers
• LOW → Add TODO(review): comment
• Cosmetic → Add FIXME(nitpick): comment

No negotiation. No exceptions. No "special cases".

---

Pressure Resistance

See shared-patterns/shared-pressure-resistance.md for universal pressure scenarios.

Gate-specific note: Execution mode selection affects CHECKPOINTS (user approval pauses), not GATES (quality checks). all gates execute regardless of mode.

---

Common Rationalizations - REJECTED

See shared-patterns/shared-anti-rationalization.md for universal anti-rationalizations.

Gate-specific rationalizations:

Excuse	Reality
"Automatic mode means faster"	Automatic mode skips CHECKPOINTS, not GATES. Same quality, less interruption.
"Automatic mode will skip review"	Automatic mode affects user approval pauses, not quality gates. all gates execute regardless.
"Defense in depth exists (frontend validates)"	Frontend can be bypassed. Backend is the last line. Fix at source.
"Backlog the Medium issue, it's documented"	Documented risk ≠ mitigated risk. Medium in Gate 4 = fix NOW, not later.
"Risk-based prioritization allows deferral"	Gates ARE the risk-based system. Reviewers define severity, not you.

---

Red Flags - STOP

See shared-patterns/shared-red-flags.md for universal red flags.

If you catch yourself thinking any of those patterns, STOP immediately and return to gate execution.

---

Incremental Compromise Prevention

The "just this once" pattern leads to complete gate erosion:

Day 1: "Skip review just this once" → Approved (precedent set)
Day 2: "Skip testing, we did it last time" → Approved (precedent extended)
Day 3: "Skip implementation checks, pattern established" → Approved (gates meaningless)
Day 4: Production incident from Day 1 code

Prevention rules:

1. No incremental exceptions - Each exception becomes the new baseline
2. Document every pressure - Log who requested, why, outcome
3. Escalate patterns - If same pressure repeats, escalate to team lead
4. Gates are binary - Complete or incomplete. No "mostly done".

---

Gate Completion Definition (HARD GATE)

A gate is COMPLETE only when all components finish successfully:

Gate	Components Required	Partial = FAIL
0.1	TDD-RED: Failing test written + failure output captured	Test exists but no failure output = FAIL
0.2	TDD-GREEN: Implementation passes test	Code exists but test fails = FAIL
0	Both 0.1 and 0.2 complete	0.1 done without 0.2 = FAIL
1	Unit test coverage ≥ 85% + all AC tested	84% = FAIL
2	Fuzz tests with seed corpus ≥ 5 entries	Missing corpus = FAIL
3	Property-based tests for domain invariants	Missing property tests = FAIL
4	Integration tests with testcontainers	No testcontainers = FAIL
5	Chaos tests for failure scenarios	Missing chaos tests = FAIL
6	All 6 reviewers PASS	5/6 reviewers = FAIL
7	Explicit "APPROVED" from user	"Looks good" = not approved

CRITICAL for Gate 6: Running 5 of 6 reviewers is not a partial pass - it's a FAIL. Re-run all 6 reviewers.

Anti-Rationalization for Partial Gates:

Rationalization	Why It's WRONG	Required Action
"5 of 6 reviewers passed"	Gate 6 requires all 6. 5/6 = 0/6.	Re-run all 6 reviewers
"Gate mostly complete"	Mostly ≠ complete. Binary: done or not done.	Complete all components
"Can finish remaining in next cycle"	Gates don't carry over. Complete NOW.	Finish current gate
"Core components done, optional can wait"	No component is optional within a gate.	Complete all components
"Unit tests are enough, skip fuzz/property"	Each test type catches different bugs. All are MANDATORY.	Execute all testing gates (2-6)
"No external dependencies, skip integration"	Integration testing is MANDATORY. Write tests per unit, execute at end of cycle.	Write Gate 4 tests per unit, execute at end

---

Gate Order Enforcement (HARD GATE)

Gates MUST execute in order: 0 → 1 → 2 → 3 → 4(write) → 5(write) → 6 → 7. All 8 gates are MANDATORY.

Deferred Execution Model for Gates 4-5:

• Per unit: Write/update test code + verify compilation (no container execution)
• End of cycle: Execute all integration and chaos tests (containers spun up once)

Violation	Why It's WRONG	Consequence
Skip Gate 2 (Fuzz)	"Unit tests are enough"	Edge cases and crashes not discovered
Skip Gate 3 (Property)	"Too complex"	Domain invariant violations not detected
Skip Gate 4 (Integration)	"No external dependencies"	Internal integration bugs surface in production
Skip Gate 5 (Chaos)	"Infra is reliable"	System fails under real-world conditions
Reorder Gates	"Review before test"	Reviewing untested code wastes reviewer time
Parallel Gates	"Run 1 and 2 together"	Dependencies exist. Order is intentional.

All testing gates (1-5) are MANDATORY. No exceptions. No skip reasons.

Gates are not parallelizable across different gates. Sequential execution is MANDATORY.

The 8 Gates

Gate	Skill	Purpose	Agent	Per Unit	Standards Module
0	bee:dev-implementation	Write code following TDD	Based on task language/domain	Write + Run	core.md, domain.md
1	bee:dev-unit-testing	Unit tests for acceptance criteria	bee:qa-analyst (test_mode: unit)	Write + Run	testing-unit.md
2	bee:dev-fuzz-testing	Fuzz tests for edge cases and crashes	bee:qa-analyst (test_mode: fuzz)	Write + Run	testing-fuzz.md
3	bee:dev-property-testing	Property-based tests for domain invariants	bee:qa-analyst (test_mode: property)	Write + Run	testing-property.md
4	bee:dev-integration-testing	Integration tests with testcontainers	bee:qa-analyst (test_mode: integration)	Write only	testing-integration.md
5	bee:dev-chaos-testing	Chaos tests for failure scenarios	bee:qa-analyst (test_mode: chaos)	Write only	testing-chaos.md
6	bee:requesting-code-review	Parallel code review (6 reviewers)	bee:code-reviewer, bee:business-logic-reviewer, bee:security-reviewer, bee:nil-safety-reviewer, bee:test-reviewer, bee:consequences-reviewer	Run	N/A
7	bee:dev-validation	Final acceptance validation	N/A (verification)	Run	N/A

All gates are MANDATORY. No exceptions. No skip reasons.

Gates 5-6 Deferred Execution: Test code is written/updated per unit to stay current. Actual test execution (with containers) happens once at end of cycle.

Integrated PM → Dev Workflow

PM Team Output → Dev Team Execution (/bee:dev-cycle)

Input Type	Path	Structure
Tasks only	docs/pre-dev/{feature}/tasks.md	T-001, T-002, T-003 with requirements + acceptance criteria
Tasks + Subtasks	docs/pre-dev/{feature}/	tasks.md + subtasks/{task-id}/ST-XXX-01.md, ST-XXX-02.md...

Execution Order

Core Principle: Each execution unit passes through all 8 gates. Gates 4-5 write test code per unit but defer execution to end of cycle.

Per-Unit Flow: Unit → Gate 0→1→2→3→4(write)→5(write)→6→7 → 🔒 Unit Checkpoint → 🔒 Task Checkpoint → Next Unit End-of-Cycle Flow: All units done → Gate 4(execute)→5(execute) → Final Commit → Feedback

Scenario	Execution Unit	Gates Per Unit	End of Cycle
Task without subtasks	Task itself	8 gates (4-5 write only)	Gate 4-5 execute
Task with subtasks	Each subtask	8 gates per subtask (4-5 write only)	Gate 4-5 execute

Why deferred execution for Gates 4-5:

• Integration tests require testcontainers (slow to spin up/tear down)
• Chaos tests require Toxiproxy infrastructure
• Running containers per subtask is wasteful when subsequent subtasks modify the same code
• Test code stays current (written per unit), infrastructure cost is paid once

Commit Timing

User selects when commits happen (Step 7 of initialization).

Option	When Commit Happens	Use Case
(a) Per subtask	After each subtask passes Gate 7	Fine-grained history, easy rollback per subtask
(b) Per task	After all subtasks of a task complete	Logical grouping, one commit per feature chunk
(c) At the end	After entire cycle completes	Single commit with all changes, clean history

Commit Message Format

Timing	Message Format	Example
Per subtask	feat({subtask_id}): {subtask_title}	feat(ST-001-02): implement user authentication handler
Per task	feat({task_id}): {task_title}	feat(T-001): implement user authentication
At the end	feat({cycle_id}): complete dev cycle for {feature}	feat(cycle-abc123): complete dev cycle for auth-system

Commit Timing vs Execution Mode

Execution Mode	Commit Timing	Behavior
Manual per subtask	Per subtask	Commit + checkpoint after each subtask
Manual per subtask	Per task	Checkpoint after subtask, commit after task
Manual per subtask	At end	Checkpoint after subtask, commit at cycle end
Manual per task	Per subtask	Commit after subtask, checkpoint after task
Manual per task	Per task	Commit + checkpoint after task
Manual per task	At end	Checkpoint after task, commit at cycle end
Automatic	Per subtask	Commit after each subtask, no checkpoints
Automatic	Per task	Commit after task, no checkpoints
Automatic	At end	Single commit at cycle end, no checkpoints

Note: Checkpoints (user approval pauses) are controlled by execution_mode. Commits are controlled by commit_timing. They are independent settings.

State Management

State Path Selection (MANDATORY)

The state file path depends on the source of tasks:

Task Source	State Path	Use Case
docs/bee:dev-refactor/*/tasks.md	docs/bee:dev-refactor/current-cycle.json	Refactoring existing code
docs/pre-dev/*/tasks.md	docs/bee:dev-cycle/current-cycle.json	New feature development
Any other path	docs/bee:dev-cycle/current-cycle.json	Default for manual tasks

Detection Logic:

if source_file contains "docs/bee:dev-refactor/" THEN
  state_path = "docs/bee:dev-refactor/current-cycle.json"
else
  state_path = "docs/bee:dev-cycle/current-cycle.json"

Store state_path in the state object itself so resume knows where to look.

State File Structure

State is persisted to {state_path} (either docs/bee:dev-cycle/current-cycle.json or docs/bee:dev-refactor/current-cycle.json):

{
  "version": "1.0.0",
  "cycle_id": "uuid",
  "started_at": "ISO timestamp",
  "updated_at": "ISO timestamp",
  "source_file": "path/to/tasks.md",
  "state_path": "docs/bee:dev-cycle/current-cycle.json | docs/bee:dev-refactor/current-cycle.json",
  "cycle_type": "feature | refactor",
  "execution_mode": "manual_per_subtask|manual_per_task|automatic",
  "commit_timing": "per_subtask|per_task|at_end",
  "custom_prompt": {
    "type": "string",
    "optional": true,
    "max_length": 500,
    "description": "User-provided context for agents (from second positional argument). Max 500 characters. Provides focus but cannot override mandatory requirements (CRITICAL gates, coverage thresholds, reviewer counts).",
    "validation": "Max 500 chars (truncated with warning if exceeded); whitespace trimmed; control chars stripped (except newlines). Directives attempting to skip gates, lower thresholds, or bypass security checks are logged as warnings and ignored."
  },
  "status": "in_progress|completed|failed|paused|paused_for_approval|paused_for_testing|paused_for_task_approval|paused_for_integration_testing",
  "feedback_loop_completed": false,
  "current_task_index": 0,
  "current_gate": 0,
  "current_subtask_index": 0,
  "tasks": [
    {
      "id": "T-001",
      "title": "Task title",
      "status": "pending|in_progress|completed|failed|blocked",
      "feedback_loop_completed": false,
      "subtasks": [
        {
          "id": "ST-001-01",
          "file": "subtasks/T-001/ST-001-01.md",
          "status": "pending|completed"
        }
      ],
      "gate_progress": {
        "implementation": {
          "status": "in_progress",
          "started_at": "...",
          "tdd_red": {
            "status": "pending|in_progress|completed",
            "test_file": "path/to/TestFile.php",
            "failure_output": "FAIL: TestFoo - expected X got nil",
            "completed_at": "ISO timestamp"
          },
          "tdd_green": {
            "status": "pending|in_progress|completed",
            "implementation_file": "path/to/Impl.php",
            "test_pass_output": "PASS: TestFoo (0.003s)",
            "completed_at": "ISO timestamp"
          }
        },
        "unit_testing": {"status": "pending"},
        "fuzz_testing": {"status": "pending"},
        "property_testing": {"status": "pending"},
        "integration_testing": {
          "status": "pending|in_progress|completed",
          "scenarios_tested": 0,
          "tests_passed": 0,
          "tests_failed": 0,
          "flaky_tests_detected": 0
        },
        "chaos_testing": {"status": "pending"},
        "review": {"status": "pending"},
        "validation": {"status": "pending"}
      },
      "artifacts": {},
      "agent_outputs": {
        "implementation": {
          "agent": "bee:backend-engineer-php",
          "output": "## Summary\n...",
          "timestamp": "ISO timestamp",
          "duration_ms": 0,
          "iterations": 1,
          "standards_compliance": {
            "total_sections": 15,
            "compliant": 14,
            "not_applicable": 1,
            "non_compliant": 0,
            "gaps": []
          }
        },
        "unit_testing": {
          "agent": "bee:qa-analyst",
          "test_mode": "unit",
          "output": "## Summary\n...",
          "verdict": "PASS",
          "coverage_actual": 87.5,
          "coverage_threshold": 85,
          "iterations": 1,
          "timestamp": "ISO timestamp",
          "duration_ms": 0,
          "failures": [],
          "uncovered_criteria": [],
          "standards_compliance": {
            "total_sections": 6,
            "compliant": 6,
            "not_applicable": 0,
            "non_compliant": 0,
            "gaps": []
          }
        },
        "fuzz_testing": {
          "agent": "bee:qa-analyst",
          "test_mode": "fuzz",
          "output": "## Summary\n...",
          "verdict": "PASS",
          "corpus_entries": 5,
          "iterations": 1,
          "timestamp": "ISO timestamp",
          "duration_ms": 0,
          "standards_compliance": {
            "total_sections": 5,
            "compliant": 5,
            "not_applicable": 0,
            "non_compliant": 0,
            "gaps": []
          }
        },
        "property_testing": {
          "agent": "bee:qa-analyst",
          "test_mode": "property",
          "output": "## Summary\n...",
          "verdict": "PASS",
          "properties_tested": 3,
          "iterations": 1,
          "timestamp": "ISO timestamp",
          "duration_ms": 0,
          "standards_compliance": {
            "total_sections": 5,
            "compliant": 5,
            "not_applicable": 0,
            "non_compliant": 0,
            "gaps": []
          }
        },
        "integration_testing": {
          "agent": "bee:qa-analyst",
          "test_mode": "integration",
          "output": "## Summary\n...",
          "verdict": "PASS",
          "scenarios_tested": 5,
          "tests_passed": 5,
          "tests_failed": 0,
          "flaky_tests_detected": 0,
          "iterations": 1,
          "timestamp": "ISO timestamp",
          "duration_ms": 0,
          "standards_compliance": {
            "total_sections": 10,
            "compliant": 10,
            "not_applicable": 0,
            "non_compliant": 0,
            "gaps": []
          }
        },
        "chaos_testing": {
          "agent": "bee:qa-analyst",
          "test_mode": "chaos",
          "output": "## Summary\n...",
          "verdict": "PASS",
          "failure_scenarios_tested": 4,
          "recovery_verified": true,
          "iterations": 1,
          "timestamp": "ISO timestamp",
          "duration_ms": 0,
          "standards_compliance": {
            "total_sections": 5,
            "compliant": 5,
            "not_applicable": 0,
            "non_compliant": 0,
            "gaps": []
          }
        },
        "review": {
          "iterations": 1,
          "timestamp": "ISO timestamp",
          "duration_ms": 0,
          "code_reviewer": {
            "agent": "bee:code-reviewer",
            "output": "...",
            "verdict": "PASS",
            "timestamp": "...",
            "issues": [],
            "standards_compliance": {
              "total_sections": 12,
              "compliant": 12,
              "not_applicable": 0,
              "non_compliant": 0,
              "gaps": []
            }
          },
          "business_logic_reviewer": {
            "agent": "bee:business-logic-reviewer",
            "output": "...",
            "verdict": "PASS",
            "timestamp": "...",
            "issues": [],
            "standards_compliance": {
              "total_sections": 8,
              "compliant": 8,
              "not_applicable": 0,
              "non_compliant": 0,
              "gaps": []
            }
          },
          "security_reviewer": {
            "agent": "bee:security-reviewer",
            "output": "...",
            "verdict": "PASS",
            "timestamp": "...",
            "issues": [],
            "standards_compliance": {
              "total_sections": 10,
              "compliant": 10,
              "not_applicable": 0,
              "non_compliant": 0,
              "gaps": []
            }
          }
        },
        "validation": {
          "result": "approved|rejected",
          "timestamp": "ISO timestamp"
        }
      }
    }
  ],
  "metrics": {
    "total_duration_ms": 0,
    "gate_durations": {},
    "review_iterations": 0,
    "testing_iterations": 0
  }
}

Structured Error/Issue Schemas

These schemas enable bee:dev-feedback-loop to analyze issues without parsing raw output.

Standards Compliance Gap Schema

{
  "section": "Error Handling (MANDATORY)",
  "status": "❌",
  "reason": "Missing error wrapping with context",
  "file": "app/Http/Controllers/UserController.php",
  "line": 45,
  "evidence": "return err // should wrap with additional context"
}

Test Failure Schema

{
  "test_name": "TestUserCreate_InvalidEmail",
  "test_file": "tests/Unit/Handler/UserTest.php",
  "error_type": "assertion",
  "expected": "ErrInvalidEmail",
  "actual": "nil",
  "message": "Expected validation error for invalid email format",
  "stack_trace": "tests/Unit/Handler/UserTest.php:42 → app/Http/Controllers/UserController.php:28"
}

Review Issue Schema

{
  "severity": "MEDIUM",
  "category": "error-handling",
  "description": "Error not wrapped with context before returning",
  "file": "app/Http/Controllers/UserController.php",
  "line": 45,
  "suggestion": "Throw new \\App\\Exceptions\\UserCreationException('Failed to create user', 0, $e)",
  "fixed": false,
  "fixed_in_iteration": null
}

DevOps Verification Error Schema

{
  "check": "docker_build",
  "status": "FAIL",
  "error": "COPY failed: file not found in build context: composer.lock",
  "suggestion": "Ensure composer.lock exists and is not in .dockerignore"
}

Populating Structured Data

Each gate MUST populate its structured fields when saving to state:

Gate	Fields to Populate
Gate 0 (Implementation)	standards_compliance (total, compliant, gaps[])
Gate 1 (Unit Testing)	standards_compliance + failures[] + uncovered_criteria[]
Gate 2 (Fuzz Testing)	standards_compliance + corpus_entries
Gate 3 (Property Testing)	standards_compliance + properties_tested
Gate 4 (Integration Testing)	standards_compliance + scenarios_tested + tests_passed + tests_failed + flaky_tests_detected
Gate 5 (Chaos Testing)	standards_compliance + failure_scenarios_tested + recovery_verified
Gate 6 (Review)	standards_compliance per reviewer + issues[] per reviewer

All gates track standards_compliance:

• total_sections: Count from agent's standards file (via standards-coverage-table.md)
• compliant: Sections marked ✅ in Standards Coverage Table
• not_applicable: Sections marked N/A
• non_compliant: Sections marked ❌ (MUST be 0 to pass gate)
• gaps[]: Detailed info for each ❌ section (even if later fixed)

Empty arrays [] indicate no issues found - this is valid data for feedback-loop.

⛔ State Persistence Rule (MANDATORY)

"Update state" means BOTH update the object and write to file. Not just in-memory.

After every Gate Transition

You MUST execute these steps after completing any gate (0, 1, 2, 3, 4, or 5, or 6):

# Step 1: Update state object with gate results
state.tasks[current_task_index].gate_progress.[gate_name].status = "completed"
state.tasks[current_task_index].gate_progress.[gate_name].completed_at = "[ISO timestamp]"
state.current_gate = [next_gate_number]
state.updated_at = "[ISO timestamp]"

# Step 2: Write to file (MANDATORY - use Write tool)
Write tool:
  file_path: [state.state_path]  # Use state_path from state object
  content: [full JSON state]

# Step 3: Verify persistence (MANDATORY - use Read tool)
Read tool:
  file_path: [state.state_path]  # Use state_path from state object
# Confirm current_gate and gate_progress match expected values

State Persistence Checkpoints

After	MUST Update	MUST Write File
Gate 0.1 (TDD-RED)	tdd_red.status, tdd_red.failure_output	✅ YES
Gate 0.2 (TDD-GREEN)	tdd_green.status, implementation.status	✅ YES
Gate 1 (Unit Testing)	unit_testing.status, agent_outputs.unit_testing	✅ YES
Gate 2 (Fuzz Testing)	fuzz_testing.status, agent_outputs.fuzz_testing	✅ YES
Gate 3 (Property Testing)	property_testing.status, agent_outputs.property_testing	✅ YES
Gate 4 (Integration Testing)	integration_testing.status, agent_outputs.integration_testing	✅ YES
Gate 5 (Chaos Testing)	chaos_testing.status, agent_outputs.chaos_testing	✅ YES
Gate 6 (Review)	review.status, agent_outputs.review	✅ YES
Gate 7 (Validation)	validation.status, task status	✅ YES
Step 9.1 (Unit Approval)	status = "paused_for_approval"	✅ YES
Step 9.2 (Task Approval)	status = "paused_for_task_approval"	✅ YES

Anti-Rationalization for State Persistence

Rationalization	Why It's WRONG	Required Action
"I'll save state at the end"	Crash/timeout loses all progress	Save after each gate
"State is in memory, that's updated"	Memory is volatile. File is persistent.	Write to JSON file
"Only save on checkpoints"	Gates without saves = unrecoverable on resume	Save after every gate
"Write tool is slow"	Write takes <100ms. Lost progress takes hours.	Write after every gate
"I updated the state variable"	Variable ≠ file. Without Write tool, nothing persists.	Use Write tool explicitly

Verification Command

After each gate, the state file MUST reflect:

• current_gate = next gate number
• updated_at = recent timestamp
• Previous gate status = "completed"

If verification fails → State was not persisted. Re-execute Write tool.

---

Step 0: Verify PROJECT_RULES.md Exists (HARD GATE)

NON-NEGOTIABLE. Cycle CANNOT proceed without project standards.

Step 0 Flow

┌─────────────────────────────────────────────────────────────────────────────┐
│  Check: Does docs/PROJECT_RULES.md exist?                                   │
│                                                                             │
│  ├── YES → Proceed to Step 1 (Initialize or Resume)                        │
│  │                                                                          │
│  └── no → ASK: "Is this a LEGACY project (created without PM workflow)?"   │
│       │                                                                     │
│       ├── YES (legacy project) → LEGACY PROJECT ANALYSIS:                   │
│       │   Step 1: Dispatch bee:codebase-explorer (technical info only)          │
│       │   Step 2: Ask 3 questions (what agent can't determine):             │
│       │     1. What do you need help with?                                  │
│       │     2. Any external APIs not visible in code?                       │
│       │     3. Any specific technology not in Bee Standards?               │
│       │   Step 3: Generate PROJECT_RULES.md (deduplicated from Bee)        │
│       │   Note: Business rules belong in PRD, not in PROJECT_RULES          │
│       │   → Proceed to Step 1                                               │
│       │                                                                     │
│       └── no (new project) → ASK: "Do you have PRD, TRD, or Feature Map?"  │
│           │                                                                 │
│           ├── YES (has PM docs) → "Please provide the file path(s)"        │
│           │   → Read PRD/TRD/Feature Map → Extract info                    │
│           │   → Generate PROJECT_RULES.md                                  │
│           │   → Ask supplementary questions if info is incomplete          │
│           │   → Save and proceed to Step 1                                 │
│           │                                                                 │
│           └── no (no PM docs) → ⛔ HARD BLOCK:                              │
│               "PM documents are REQUIRED for new projects.                  │
│                Run /bee:pre-dev-full or /bee:pre-dev-feature first."               │
│               → STOP (cycle cannot proceed)                                 │
└─────────────────────────────────────────────────────────────────────────────┘

Step 0.1: Check for PROJECT_RULES.md

# Check if file exists
Read tool:
  file_path: "docs/PROJECT_RULES.md"

# If file exists and has content → Proceed to Step 1
# If file does not exist or is empty → Continue to Step 0.2

Step 0.2: Check if Legacy Project

Ask the User

Use AskUserQuestion:

┌─────────────────────────────────────────────────────────────────┐
│ 📋 PROJECT_RULES.md not FOUND                                   │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│ I need to create docs/PROJECT_RULES.md to understand your       │
│ project's specific conventions and domain.                      │
│                                                                 │
│ First, I need to know: Is this a LEGACY project?                │
│                                                                 │
│ A legacy project is one that was created WITHOUT using the      │
│ PM team workflow (no PRD, TRD, or Feature Map documents).       │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Question

"Is this a legacy project (created without PM team workflow)?"

Options

(a) Yes, this is a legacy project (b) No, this is a new project following Bee workflow

If YES (legacy)

Go to Step 0.2.1 (Legacy Project Analysis)

If no (new project)

Go to Step 0.3 (Check for PM Documents)

Step 0.2.1: Legacy Project Analysis (Technical Only)

Overview

For legacy projects, analyze codebase for TECHNICAL information only:

┌─────────────────────────────────────────────────────────────────┐
│ 📋 LEGACY PROJECT ANALYSIS                                      │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│ Since this is a legacy project, I'll analyze the codebase       │
│ for TECHNICAL information (not business rules).                 │
│                                                                 │
│ Step 1: Automated analysis (bee:codebase-explorer)                  │
│ Step 2: Ask for project-specific tech not in Bee Standards     │
│ Step 3: Generate PROJECT_RULES.md (deduplicated)                │
│                                                                 │
│ Note: Business rules belong in PRD/product docs, not here.      │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Step 0.2.1a: Automated Codebase Analysis (MANDATORY)

⛔ You MUST use the Task tool to dispatch bee:codebase-explorer. This is not implicit.

Dispatch Agent

Dispatch bee:codebase-explorer to analyze the legacy project for TECHNICAL information:

Action: Use Task tool with EXACTLY these parameters:

┌─────────────────────────────────────────────────────────────────────────────────┐
│  ⛔ If Task tool not used → Analysis does not happen → PROJECT_RULES.md INVALID │
└─────────────────────────────────────────────────────────────────────────────────┘

# Agent 1: Codebase Explorer - Technical Analysis
Task tool:
  subagent_type: "bee:codebase-explorer"
  model: "opus"
  description: "Analyze legacy project for PROJECT_RULES.md"
  prompt: |
    Analyze this LEGACY codebase to extract technical information for PROJECT_RULES.md.
    
    This is an existing project created without PM documentation.
    Your job is to understand what exists in the code.
    
    **Extract:**
    1. **Project Structure:** Directory layout, module organization
    2. **Technical Stack:** Languages, frameworks, databases, external services
    3. **Architecture Patterns:** Clean Architecture, MVC, microservices, etc.
    4. **Existing Features:** Main modules, endpoints, capabilities
    5. **Internal Libraries:** Shared packages, utilities
    6. **Configuration:** Environment variables, config patterns
    7. **Database:** Schema patterns, migrations, ORM usage
    8. **External Integrations:** APIs consumed, message queues
    
    **Output format:**
    ## Technical Analysis (Legacy Project)
    
    ### Project Overview
    [What this project appears to do based on code analysis]
    
    ### Technical Stack
    - Language: [detected]
    - Framework: [detected]
    - Database: [detected]
    - External Services: [detected]
    
    ### Architecture Patterns
    [Detected patterns]
    
    ### Existing Features
    [List of features/modules found]
    
    ### Project Structure
    [Directory layout explanation]
    
    ### Configuration
    [Env vars, config files found]
    
    ### External Integrations
    [APIs, services detected]

Note: Business logic analysis is not needed for PROJECT_RULES.md. Business rules belong in PRD/product docs, not technical project rules.

Verification (MANDATORY)

After agent completes, confirm:

• bee:codebase-explorer returned "## Technical Analysis (Legacy Project)" section
• Output contains non-empty content for: Tech Stack, External Integrations, Configuration

If agent failed or returned empty output → Re-dispatch. Cannot proceed without technical analysis.

Step 0.2.1b: Supplementary Questions (Only What Agents Can't Determine)

Post-Analysis Questions

After agents complete, ask only what they couldn't determine from code:

┌─────────────────────────────────────────────────────────────────┐
│ ✓ Codebase Analysis Complete                                    │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│ I've analyzed your codebase. Now I need a few details that      │
│ only you can provide (not visible in the code).                 │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Questions to Ask

Use AskUserQuestion for each:

#	Question	Why Agents Can't Determine This
1	What do you need help with? (Current task/feature/fix)	Future intent, not in code
2	Any external APIs or services not visible in code? (Third-party integrations planned)	Planned integrations, not yet in code
3	Any specific technology not in Bee Standards? (Message broker, cache, etc.)	Project-specific tech not in Bee

Note: Business rules belong in PRD/product docs, not in PROJECT_RULES.md.

Step 0.2.1c: Generate PROJECT_RULES.md

Combine Agent Outputs and User Answers

Create tool:
  file_path: "docs/PROJECT_RULES.md"
  content: |
    # Project Rules
    
    > Bee Standards apply automatically. This file documents only what Bee does not cover.
    > For error handling, logging, testing, architecture, lib-commons → See Bee Standards (auto-loaded by agents)
    > Generated from legacy project analysis.
    
    ## What Bee Standards Already Cover (DO not ADD HERE)
    
    The following are defined in Bee Standards and MUST not be duplicated:
    - Error handling patterns (no panic, wrap errors)
    - Logging standards (structured JSON, zerolog/zap)
    - Testing patterns (table-driven tests, mocks)
    - Architecture patterns (Hexagonal, Clean Architecture)
    - Observability (OpenTelemetry, trace correlation)
    - lib-commons usage and patterns
    - API directory structure
    
    ---
    
    ## Tech Stack (Not in Bee Standards)
    
    [From bee:codebase-explorer: Technologies not covered by Bee Standards]
    [e.g., specific message broker, specific cache, DB if not PostgreSQL]
    
    | Technology | Purpose | Notes |
    |------------|---------|-------|
    | [detected] | [purpose] | [notes] |
    
    ## Non-Standard Directory Structure
    
    [From bee:codebase-explorer: Directories that deviate from Bee's standard API structure]
    [e.g., workers/, consumers/, polling/]
    
    | Directory | Purpose | Pattern |
    |-----------|---------|---------|
    | [detected] | [purpose] | [pattern] |
    
    ## External Integrations
    
    [From bee:codebase-explorer: Third-party services specific to this project]
    
    | Service | Purpose | Docs |
    |---------|---------|------|
    | [detected] | [purpose] | [link] |
    
    ## Environment Configuration
    
    [From bee:codebase-explorer: Project-specific env vars not covered by Bee]
    
    | Variable | Purpose | Example |
    |----------|---------|---------|
    | [detected] | [purpose] | [example] |
    
    ## Domain Terminology
    
    [From codebase analysis: Technical names used in this codebase]
    
    | Term | Definition | Used In |
    |------|------------|---------|
    | [detected] | [definition] | [location] |
    
    ---
    
    *Generated: [ISO timestamp]*
    *Source: Legacy project analysis (bee:codebase-explorer)*
    *Bee Standards Version: [version from WebFetch]*

Present to User

┌─────────────────────────────────────────────────────────────────┐
│ ✓ PROJECT_RULES.md Generated for Legacy Project                 │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│ I analyzed your codebase using:                                 │
│   • bee:codebase-explorer (technical patterns, stack, structure)    │
│                                                                 │
│ Combined with your input on:                                    │
│   • Current development goal                                    │
│   • External integrations                                       │
│   • Project-specific technology                                 │
│                                                                 │
│ Generated: docs/PROJECT_RULES.md                                │
│                                                                 │
│ Note: Bee Standards (error handling, logging, testing, etc.)   │
│ are not duplicated - agents load them automatically via WebFetch│
│                                                                 │
│ Please review the file and make any corrections needed.         │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Ask for Approval

Use AskUserQuestion:

• Question: "PROJECT_RULES.md has been generated. Would you like to review it before proceeding?"
• Options: (a) Proceed (b) Open for editing first

After Approval

Proceed to Step 1

Step 0.3: Check for PM Documents (PRD/TRD/Feature Map)

Check for PM Documents

For NEW projects (not legacy), ask about PM documents:

┌─────────────────────────────────────────────────────────────────┐
│ 📋 NEW PROJECT - PM DOCUMENTS CHECK                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│ Since this is a new project following Bee workflow, you        │
│ should have PM documents from the pre-dev workflow.             │
│                                                                 │
│ Do you have any of these PM documents?                          │
│   • PRD (Product Requirements Document)                         │
│   • TRD (Technical Requirements Document)                       │
│   • Feature Map (from bee:pre-dev-feature-map skill)                │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Question

"Do you have PRD, TRD, or Feature Map documents for this project?"

Options

(a) Yes, I have PM documents (b) No, I don't have these documents

If YES - Ask for File Paths

"Please provide the file path(s) to your PM documents:
 - PRD path (or 'skip' if none): 
 - TRD path (or 'skip' if none): 
 - Feature Map path (or 'skip' if none): "

Example Paths

Typical PM team output structure:

docs/pre-dev/{feature-name}/
├── prd.md              → PRD path: docs/pre-dev/auth-system/prd.md
├── trd.md              → TRD path: docs/pre-dev/auth-system/trd.md
├── feature-map.md      → Feature Map path: docs/pre-dev/auth-system/feature-map.md
├── api-design.md
├── data-model.md
└── tasks.md

Common Patterns

• /bee:pre-dev-full output: docs/pre-dev/{feature}/prd.md, trd.md, feature-map.md
• /bee:pre-dev-feature output: docs/pre-dev/{feature}/prd.md, feature-map.md
• Custom locations: User may have docs in different paths (e.g., requirements/, specs/)

Then

Go to Step 0.3.1 (Generate from PM Documents)

If no

HARD BLOCK (Step 0.3.2)

Step 0.3.1: Generate from PM Documents (PRD/TRD/Feature Map)

Read the Provided Documents

# Read PRD if provided
Read tool:
  file_path: "[user-provided PRD path]"

# Read TRD if provided  
Read tool:
  file_path: "[user-provided TRD path]"

# Read Feature Map if provided
Read tool:
  file_path: "[user-provided Feature Map path]"

Extract PROJECT_RULES.md Content from PM Documents

⛔ DEDUPLICATION RULE: Extract only what Bee Standards DO NOT cover.

From PRD	Extract For PROJECT_RULES.md	Note
Domain terms, entities	Domain Terminology	Technical names only
External service mentions	External Integrations	Third-party APIs
Business rules	N/A	❌ Stays in PRD, not PROJECT_RULES
Architecture	N/A	❌ Bee Standards covers this

From TRD	Extract For PROJECT_RULES.md	Note
Tech stack not in Bee	Tech Stack (Not in Bee)	Only non-standard tech
External APIs	External Integrations	Third-party services
Non-standard directories	Non-Standard Directory Structure	Workers, consumers, etc.
Architecture decisions	N/A	❌ Bee Standards covers this
Database patterns	N/A	❌ Bee Standards covers this

From Feature Map	Extract For PROJECT_RULES.md	Note
Technology choices not in Bee	Tech Stack (Not in Bee)	Only if not in Bee
External dependencies	External Integrations	Third-party services
Architecture	N/A	❌ Bee Standards covers this

Generate PROJECT_RULES.md

Create tool:
  file_path: "docs/PROJECT_RULES.md"
  content: |
    # Project Rules
    
    > ⛔ IMPORTANT: Bee Standards are not automatic. Agents MUST WebFetch them before implementation.
    > This file documents only project-specific information not covered by Bee Standards.
    > Generated from PM documents (PRD/TRD/Feature Map).
    >
    > Bee Standards URLs:
    > - PHP: https://raw.githubusercontent.com/luanrodrigues/ia-frmwrk/master/dev-team/docs/standards/php.md
    > - TypeScript: https://raw.githubusercontent.com/luanrodrigues/ia-frmwrk/master/dev-team/docs/standards/typescript.md

    ## What Bee Standards Cover (DO not DUPLICATE HERE)

    The following are defined in Bee Standards and MUST not be duplicated in this file:
    - Error handling patterns (exceptions, try/catch with context)
    - Logging standards (structured JSON via Monolog/Laravel Log)
    - Testing patterns (Pest/PHPUnit tests, data providers)
    - Architecture patterns (Hexagonal, Clean Architecture)
    - Observability (OpenTelemetry PHP SDK)
    - Laravel framework usage and patterns
    - API directory structure (Lerian pattern)
    - Database connections (PostgreSQL, MongoDB, Redis via Laravel)
    - Bootstrap pattern (config/, Providers/, routes/)
    
    **Agents MUST WebFetch Bee Standards and output Standards Coverage Table.**
    
    ---
    
    ## Tech Stack (Not in Bee Standards)
    
    [From TRD/Feature Map: only technologies not covered by Bee Standards]
    
    | Technology | Purpose | Notes |
    |------------|---------|-------|
    | [detected] | [purpose] | [notes] |
    
    ## Non-Standard Directory Structure
    
    [From TRD: Directories that deviate from Bee's standard API structure]
    
    | Directory | Purpose | Pattern |
    |-----------|---------|---------|
    | [detected] | [purpose] | [pattern] |
    
    ## External Integrations
    
    [From TRD/PRD: Third-party services specific to this project]
    
    | Service | Purpose | Docs |
    |---------|---------|------|
    | [detected] | [purpose] | [link] |
    
    ## Environment Configuration
    
    [From TRD: Project-specific env vars not covered by Bee]
    
    | Variable | Purpose | Example |
    |----------|---------|---------|
    | [detected] | [purpose] | [example] |
    
    ## Domain Terminology
    
    [From PRD: Technical names used in this codebase]
    
    | Term | Definition | Used In |
    |------|------------|---------|
    | [detected] | [definition] | [location] |
    
    ---
    
    *Generated from: [PRD path], [TRD path], [Feature Map path]*
    *Bee Standards Version: [version from WebFetch]*
    *Generated: [ISO timestamp]*

Check for Missing Information

If any section is empty or incomplete, ask supplementary questions:

Missing Section	Supplementary Question
Tech Stack (Not in Bee)	"Any technology not covered by Bee Standards (message broker, cache, etc.)?"
External Integrations	"Any third-party APIs or external services?"
Domain Terminology	"What are the main entities/classes in this codebase?"
Non-Standard Directories	"Any directories that don't follow standard API structure (workers, consumers)?"

Note: Do not ask about architecture, error handling, logging, testing - Bee Standards covers these.

After Generation

Present to user for review, then proceed to Step 1.

Step 0.3.2: HARD BLOCK - No PM Documents (New Projects Only)

When User Has No PM Documents

┌─────────────────────────────────────────────────────────────────┐
│ ⛔ CANNOT PROCEED - PM DOCUMENTS REQUIRED                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│ Development cannot start without PM documents.                  │
│                                                                 │
│ You MUST create PRD, TRD, and/or Feature Map documents first    │
│ using PM team skills:                                           │
│                                                                 │
│   /bee:pre-dev-full     → For features ≥2 days (9 gates)           │
│   /bee:pre-dev-feature  → For features <2 days (4 gates)           │
│                                                                 │
│ These commands will guide you through creating:                 │
│   • PRD (Product Requirements Document)                         │
│   • TRD (Technical Requirements Document)                       │
│   • Feature Map (technology choices, feature relationships)     │
│                                                                 │
│ After completing pre-dev workflow, run /bee:dev-cycle again.        │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Action

STOP EXECUTION. Do not proceed to Step 1.

Step 0 Anti-Rationalization

Rationalization	Why It's WRONG	Required Action
"Skip PM docs, I'll add them later"	Later = never. No PM docs = no project context = agents guessing.	Run /bee:pre-dev-full or /bee:pre-dev-feature NOW
"Project is simple, doesn't need PM docs"	Simple projects still need domain context defined upfront.	Create PM documents first
"I know what I want to build"	Your knowledge ≠ documented knowledge agents can use.	Document in PRD/TRD/Feature Map
"PM workflow takes too long"	PM workflow takes 30-60 min. Rework from unclear requirements takes days.	Invest time upfront
"Just let me start coding"	Coding without requirements = building the wrong thing.	Requirements first, code second
"It's legacy but I don't want to answer questions"	Legacy analysis takes ~5 min. Without it, agents have zero context.	Answer the 4 questions
"Legacy project is too complex to explain"	Start with high-level answers. PROJECT_RULES.md can be refined later.	Provide what you know NOW

Pressure Resistance

User Says	Your Response
"Just skip this, I'll create PM docs later"	"PM documents are REQUIRED for new projects. Without them, agents cannot understand your project's domain context or technical requirements. Run /bee:pre-dev-full or /bee:pre-dev-feature first."
"I don't need formal documents"	"PM documents are the source of truth for PROJECT_RULES.md. Development cannot start without documented requirements."
"This is just a quick prototype"	"Even prototypes need clear requirements. /bee:pre-dev-feature takes ~30 minutes and prevents hours of rework."
"I already explained what I want verbally"	"Verbal explanations cannot be used by agents. Requirements MUST be documented in PRD/TRD/Feature Map files."
"It's a legacy project but skip the questions"	"The legacy analysis (bee:codebase-explorer + 3 questions) is the only way I can understand your project. It takes ~5 minutes and enables me to help you effectively."
"I'll fill in PROJECT_RULES.md myself"	"That works! Create docs/PROJECT_RULES.md with: Tech Stack (not in Bee), External Integrations, Domain Terminology. Do not duplicate Bee Standards content. Then run /bee:dev-cycle again."

---

Step 1: Initialize or Resume

Instructions-Only Mode (no task file)

Input: Custom instructions string without a task file path

Example: /bee:dev-cycle "Implement multi-tenant support with organization_id in all entities"

When custom instructions are provided without a tasks file, bee:dev-cycle generates tasks internally:

1. Detect instructions-only mode: No task file argument AND instructions string provided
2. Analyze prompt: Extract intent, scope, and requirements from the prompt
3. Explore codebase: Dispatch bee:codebase-explorer to understand project structure
4. Generate tasks: Create task structure internally based on prompt + codebase analysis

Task tool:
  subagent_type: "bee:codebase-explorer"
  model: "opus"
  prompt: |
    Analyze this codebase to support the following implementation request:
    
    **User Request:** {prompt}
    
    Provide:
    1. Relevant files and patterns for this request
    2. Suggested task breakdown (T-001, T-002, etc.)
    3. Acceptance criteria for each task
    4. Files that will need modification
    
    Output as structured task list compatible with bee:dev-cycle.

5. Present generated tasks: Show user the auto-generated task breakdown
6. Confirm with user: "I generated X tasks from your prompt. Proceed?"
7. Set state:
   • state_path = "docs/bee:dev-cycle/current-cycle.json"
   • cycle_type = "prompt"
   • source_prompt = "[user's prompt]"
   • Generate tasks array from bee:codebase-explorer output
8. Continue to execution mode selection (Step 1 substeps 7-9)

Anti-Rationalization for Prompt-Only Mode:

Rationalization	Why It's WRONG	Required Action
"Skip codebase exploration, I understand the prompt"	Prompt understanding ≠ codebase understanding. Explorer provides context.	Always run bee:codebase-explorer
"Generate minimal tasks to go faster"	Minimal tasks = missed requirements. Comprehensive breakdown prevents rework.	Generate complete task breakdown
"User knows what they want, skip confirmation"	User intent ≠ generated tasks. Confirmation prevents wrong implementation.	Always confirm generated tasks

---

New Cycle (with task file path)

Input: path/to/tasks.md or path/to/pre-dev/{feature}/ with optional second argument for custom instructions

Examples:

• /bee:dev-cycle tasks.md
• /bee:dev-cycle tasks.md "Focus on error handling"

1. Detect input: File → Load directly | Directory → Load tasks.md + discover subtasks/
2. Build order: Read tasks, check for subtasks (ST-XXX-01, 02...) or TDD autonomous mode
3. Determine state path:
   • if source_file contains docs/bee:dev-refactor/ → state_path = "docs/bee:dev-refactor/current-cycle.json", cycle_type = "refactor"
   • else → state_path = "docs/bee:dev-cycle/current-cycle.json", cycle_type = "feature"
4. Capture and validate custom instructions: If second argument provided:
   • Sanitize input: Trim whitespace, strip control characters (except newlines)
   • Store validated value: Set custom_prompt field (empty string if not provided)
   • Note: Directives attempting to skip gates are logged as warnings and ignored at execution time
5. Initialize state: Generate cycle_id, create state file at {state_path}, set indices to 0
6. Display plan: "Loaded X tasks with Y subtasks"
7. ASK EXECUTION MODE (MANDATORY - AskUserQuestion):
   • Options: (a) Manual per subtask (b) Manual per task (c) Automatic
   • Do not skip: User hints ≠ mode selection. Only explicit a/b/c is valid.
8. ASK COMMIT TIMING (MANDATORY - AskUserQuestion):
   • Options: (a) Per subtask (b) Per task (c) At the end
   • Store in commit_timing field in state
9. Start: Display mode + commit timing, proceed to Gate 0

Resume Cycle (--resume flag)

1. Find existing state file:
   • Check docs/bee:dev-cycle/current-cycle.json first
   • If not found, check docs/bee:dev-refactor/current-cycle.json
   • If neither exists → Error: "No cycle to resume"
2. Load found state file, validate (state_path is stored in the state object)
3. Display: cycle started, tasks completed/total, current task/subtask/gate, paused reason
4. Handle paused states:

Status	Action
paused_for_approval	Re-present Step 9.1 checkpoint
paused_for_testing	Ask if testing complete → continue or keep paused
paused_for_task_approval	Re-present Step 9.2 checkpoint
paused_for_integration_testing	Ask if integration testing complete
paused (generic)	Ask user to confirm resume
in_progress	Resume from current gate

Input Validation

Task files are generated by /pre-dev-* or /bee:dev-refactor, which handle content validation. The bee:dev-cycle performs basic format checks:

Format Checks

Check	Validation	Action
File exists	Task file path is readable	Error: abort
Task headers	At least one ## Task: found	Error: abort
Task ID format	## Task: {ID} - {Title}	Warning: use line number as ID
Acceptance criteria	At least one - [ ] per task	Warning: task may fail validation gate

Step 1.5: Detect External Dependencies (Cycle-Level Auto-Detection)

MANDATORY: Scan the codebase once at cycle start to detect external dependencies. Store in state.detected_dependencies for use by Gates 2, 6, and 7.

detected_dependencies = []

1. Scan docker-compose.yml / docker-compose.yaml for service images:
   - Grep tool: pattern "postgres" in docker-compose* files → add "postgres"
   - Grep tool: pattern "mongo" in docker-compose* files → add "mongodb"
   - Grep tool: pattern "valkey" in docker-compose* files → add "valkey"
   - Grep tool: pattern "redis" in docker-compose* files → add "redis"
   - Grep tool: pattern "rabbitmq" in docker-compose* files → add "rabbitmq"

2. Scan dependency manifests:
   if language == "php":
     - Grep tool: pattern "laravel/framework" in composer.json → add "laravel"
     - Grep tool: pattern "doctrine/dbal" in composer.json → add "postgres"
     - Grep tool: pattern "mongodb/laravel-mongodb" in composer.json → add "mongodb"
     - Grep tool: pattern "predis/predis" in composer.json → add "redis"
     - Grep tool: pattern "phpredis" in composer.json → add "redis"
     - Grep tool: pattern "vladimir-yuldashev/laravel-queue-rabbitmq" in composer.json → add "rabbitmq"
     - Grep tool: pattern "php-amqplib" in composer.json → add "rabbitmq"

   if language == "typescript":
     - Grep tool: pattern "\"pg\"" in package.json → add "postgres"
     - Grep tool: pattern "@prisma/client" in package.json → add "postgres"
     - Grep tool: pattern "\"mongodb\"" in package.json → add "mongodb"
     - Grep tool: pattern "\"mongoose\"" in package.json → add "mongodb"
     - Grep tool: pattern "\"redis\"" in package.json → add "redis"
     - Grep tool: pattern "\"ioredis\"" in package.json → add "redis"
     - Grep tool: pattern "@valkey" in package.json → add "valkey"
     - Grep tool: pattern "\"amqplib\"" in package.json → add "rabbitmq"
     - Grep tool: pattern "amqp-connection-manager" in package.json → add "rabbitmq"

3. Deduplicate detected_dependencies
4. Store: state.detected_dependencies = detected_dependencies
5. Log: "Auto-detected external dependencies: [detected_dependencies]"

**MANDATORY: ⛔ Save state to file — Write tool → [state.state_path]**

<auto_detect_reason> PM team task files often omit external_dependencies. If the codebase uses postgres, mongodb, valkey, or rabbitmq, these MUST be detected and passed to Gates 6 (integration) and 7 (chaos). Auto-detection at cycle level avoids redundant scans per gate. </auto_detect_reason>

---

Step 2: Gate 0 - Implementation (Per Execution Unit)

REQUIRED SUB-SKILL: Use bee:dev-implementation

Execution Unit: Task (if no subtasks) or Subtask (if task has subtasks)

⛔ MANDATORY: Invoke bee:dev-implementation Skill (not inline execution)

See shared-patterns/shared-orchestrator-principle.md for full details.

⛔ FORBIDDEN: Executing TDD-RED/GREEN logic directly from this step. MUST invoke the bee:dev-implementation skill via the Skill tool; it handles all TDD phases, agent selection, agent dispatch, standards verification, and fix iteration.

Step 2.1: Prepare Input for bee:dev-implementation Skill

Gather from current execution unit:

implementation_input = {
  // REQUIRED - from current execution unit
  unit_id: state.current_unit.id,
  requirements: state.current_unit.acceptance_criteria,

  // REQUIRED - detected from project
  language: state.current_unit.language,  // "php" | "typescript" | "python"
  service_type: state.current_unit.service_type,  // "api" | "worker" | "batch" | "cli" | "frontend" | "bff"

  // OPTIONAL - additional context
  technical_design: state.current_unit.technical_design || null,
  existing_patterns: state.current_unit.existing_patterns || [],
  project_rules_path: "docs/PROJECT_RULES.md"
}

Step 2.2: Invoke bee:dev-implementation Skill

1. Record gate start timestamp

2. REQUIRED: Invoke bee:dev-implementation skill with structured input:

   Skill("bee:dev-implementation") with input:
     unit_id: implementation_input.unit_id
     requirements: implementation_input.requirements
     language: implementation_input.language
     service_type: implementation_input.service_type
     technical_design: implementation_input.technical_design
     existing_patterns: implementation_input.existing_patterns
     project_rules_path: implementation_input.project_rules_path

   The skill handles:
   - Selecting appropriate agent (Go/TS/Frontend based on language)
   - TDD-RED phase (writing failing test, capturing failure output)
   - TDD-GREEN phase (implementing code to pass test)
   - Standards compliance verification (iteration loop, max 3 attempts)
   - Re-dispatching agent for compliance fixes
   - Outputting Standards Coverage Table with evidence

3. REQUIRED: Parse skill output for results:

   Expected output sections:
   - "## Implementation Summary" → status (PASS/FAIL), agent used
   - "## TDD Results" → RED/GREEN phase status
   - "## Files Changed" → created/modified files list
   - "## Handoff to Next Gate" → ready_for_gate_1: YES/NO

   if skill output contains "Status: PASS" and "Ready for Gate 1: YES":
     → Gate 0 PASSED. Proceed to Step 2.3.

   if skill output contains "Status: FAIL" or "Ready for Gate 1: NO":
     → Gate 0 BLOCKED.
     → Skill already dispatched fixes to implementation agent
     → Skill already re-ran TDD and standards verification
     → If "ESCALATION" in output: STOP and report to user

4. **MANDATORY: ⛔ Save state to file — Write tool → [state.state_path]**

Step 2.3: Gate 0 Complete

5. When bee:dev-implementation skill returns PASS:

   REQUIRED: Parse from skill output:
   - agent_used: extract from "## Implementation Summary"
   - tdd_red_status: extract from "## TDD Results" table
   - tdd_green_status: extract from "## TDD Results" table
   - files_changed: extract from "## Files Changed" table
   - standards_compliance: extract from Standards Coverage Table

   - agent_outputs.implementation = {
       skill: "bee:dev-implementation",
       agent: "[agent used by skill]",
       output: "[full skill output]",
       timestamp: "[ISO timestamp]",
       duration_ms: [execution time],
       tdd_red: {
         status: "completed",
         test_file: "[from skill output]",
         failure_output: "[from skill output]"
       },
       tdd_green: {
         status: "completed",
         implementation_files: "[from skill output]",
         pass_output: "[from skill output]"
       },
       standards_compliance: {
         total_sections: [N from skill output],
         compliant: [N sections with ✅],
         not_applicable: [N sections with N/A],
         non_compliant: 0
       }
     }

6. Display to user:
   ┌─────────────────────────────────────────────────┐
   │ ✓ GATE 0 COMPLETE                              │
   ├─────────────────────────────────────────────────┤
   │ Skill: bee:dev-implementation                  │
   │ Agent: [agent_used]                             │
   │ TDD-RED:   FAIL captured ✓                     │
   │ TDD-GREEN: PASS verified ✓                     │
   │ STANDARDS: [N]/[N] sections compliant ✓        │
   │                                                 │
   │ Proceeding to Gate 1 (Unit Testing)...         │
   └─────────────────────────────────────────────────┘

7. MANDATORY: ⛔ Save state to file — Write tool → [state.state_path]
   See "State Persistence Rule" section.

8. Proceed to Gate 1

Anti-Rationalization: Gate 0 Skill Invocation

Rationalization	Why It's WRONG	Required Action
"I can run TDD-RED/GREEN directly from here"	Inline TDD = skipping the skill. Skill has iteration logic and validation.	Invoke Skill("bee:dev-implementation")
"I already know which agent to dispatch"	Agent selection is the SKILL's job, not the orchestrator's.	Invoke Skill("bee:dev-implementation")
"The TDD steps are documented here, I'll follow them"	These steps are REFERENCE, not EXECUTABLE. The skill is executable.	Invoke Skill("bee:dev-implementation")
"Skill adds overhead for simple tasks"	Overhead = compliance checks. Simple ≠ exempt.	Invoke Skill("bee:dev-implementation")
"I'll dispatch the agent and verify output myself"	Self-verification skips the skill's re-dispatch loop.	Invoke Skill("bee:dev-implementation")
"Agent already did TDD internally"	Internal ≠ verified by skill. Skill validates output structure.	Invoke Skill("bee:dev-implementation")

Step 3: Gate 1 - Unit Testing (Per Execution Unit)

REQUIRED SUB-SKILL: Use bee:dev-unit-testing

Step 3.1: Prepare Input for bee:dev-unit-testing Skill

Gather from previous gates:

testing_input = {
  // REQUIRED - from current execution unit
  unit_id: state.current_unit.id,
  acceptance_criteria: state.current_unit.acceptance_criteria,  // list of ACs to test
  implementation_files: agent_outputs.implementation.files_changed,
  language: state.current_unit.language,  // "php" | "typescript" | "python"

  // OPTIONAL - additional context
  coverage_threshold: 85,  // Bee minimum, PROJECT_RULES.md can raise
  gate0_handoff: agent_outputs.implementation,  // full Gate 0 output
  existing_tests: [check for existing test files]
}

Step 3.2: Invoke bee:dev-unit-testing Skill

1. Record gate start timestamp

2. Invoke bee:dev-unit-testing skill with structured input:

   Skill("bee:dev-unit-testing") with input:
     unit_id: testing_input.unit_id
     acceptance_criteria: testing_input.acceptance_criteria
     implementation_files: testing_input.implementation_files
     language: testing_input.language
     coverage_threshold: testing_input.coverage_threshold
     gate0_handoff: testing_input.gate0_handoff
     existing_tests: testing_input.existing_tests

   The skill handles:
   - Dispatching bee:qa-analyst agent
   - Test creation following TDD methodology
   - Coverage measurement and validation (85%+ required)
   - Traceability matrix (AC → Test mapping)
   - Dispatching fixes to implementation agent if coverage < threshold
   - Re-validation loop (max 3 iterations)

3. Parse skill output for results:
   
   Expected output sections:
   - "## Testing Summary" → status, iterations
   - "## Coverage Report" → threshold vs actual
   - "## Traceability Matrix" → AC-to-test mapping
   - "## Handoff to Next Gate" → ready_for_review: YES/no
   
   if skill output contains "Status: PASS" and "Ready for Next Gate: YES":
     → Gate 1 PASSED. Proceed to Step 3.3.

   if skill output contains "Status: FAIL" or "Ready for Next Gate: NO":
     → Gate 1 BLOCKED.
     → Skill already dispatched fixes to implementation agent
     → Skill already re-ran coverage check
     → If "ESCALATION" in output: STOP and report to user

4. **MANDATORY: ⛔ Save state to file — Write tool → [state.state_path]**

Step 3.3: Gate 1 Complete

5. When bee:dev-unit-testing skill returns PASS:
   
   Parse from skill output:
   - coverage_actual: extract percentage from "## Coverage Report"
   - coverage_threshold: extract from "## Coverage Report"
   - criteria_covered: extract from "## Traceability Matrix"
   - iterations: extract from "Iterations:" line
   
   - agent_outputs.testing = {
       skill: "bee:dev-unit-testing",
       output: "[full skill output]",
       verdict: "PASS",
       coverage_actual: [X%],
       coverage_threshold: [85%],
       criteria_covered: "[X/Y]",
       iterations: [count],
       timestamp: "[ISO timestamp]",
       duration_ms: [execution time],
       failures: [],  // Empty when PASS; see schema below for FAIL
       uncovered_criteria: []  // Empty when all ACs covered
     }
   
   **If iterations > 1 (tests failed before passing), populate `failures[]`:**
   ```json
   failures: [
     {
       "test_name": "TestUserCreate_InvalidEmail",