Dev Cycle

Development Cycle Orchestrator

Standards Loading (MANDATORY)

Before ANY gate execution, you MUST load Ring standards:

See CLAUDE.md as the canonical source. This table summarizes the loading process.

Execute WebFetch before proceeding. Do NOT continue until standards are loaded.

If WebFetch fails → STOP and report blocker. Cannot proceed without Ring standards.

Overview

The development cycle orchestrator loads tasks/subtasks from PM team output (or manual task files) and executes through 6 quality gates. Tasks are loaded at initialization - no separate import gate.

Announce at start: "I'm using the dev-cycle skill to orchestrate task execution through 6 gates."

⛔ 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)

What Orchestrator CANNOT Do (FORBIDDEN)

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 (*.go, *.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/refactor/*/tasks.md) │
│  2. Ask execution mode (AskUserQuestion)                        │
│  3. Determine state path + Check/Load state (see State Path Selection) │
│  4. WebFetch Ring 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.

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 as sub-skill instructs
4. Validate agent output          ← Per sub-skill validation rules
5. Update state                   ← Record results

Anti-Rationalization for Skipping Sub-Skills

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

Anti-Rationalization for Direct Coding

Red Flags - Orchestrator Violation in Progress

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

🚨 RED FLAG: About to Read *.go 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 "go 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

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

Cannot Be Overridden

Severity Calibration

Report ALL severities. Let user prioritize.

Reviewer Verdicts Are Final

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

Severity mapping is absolute:

• CRITICAL/HIGH/MEDIUM → Fix NOW, re-run all 3 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:

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:

CRITICAL for Gate 4: Running 2 of 3 reviewers is NOT a partial pass - it's a FAIL. Re-run ALL 3 reviewers.

Anti-Rationalization for Partial Gates:

Gate Order Enforcement (HARD GATE)

Gates MUST execute in order: 0 → 1 → 2 → 3 → 4 → 5. No exceptions.

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

The 6 Gates

Integrated PM → Dev Workflow

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

Execution Order

Core Principle: Each execution unit (task OR subtask) passes through all 6 gates before the next unit.

Flow: Unit → Gate 0-5 → 🔒 Unit Checkpoint (Step 7.1) → 🔒 Task Checkpoint (Step 7.2) → Next Unit

Commit Timing

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

Commit Message Format

Commit Timing vs Execution Mode

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:

Detection Logic:

IF source_file contains "docs/refactor/" THEN
  state_path = "docs/dev-refactor/current-cycle.json"
ELSE
  state_path = "docs/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/dev-cycle/current-cycle.json or docs/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/dev-cycle/current-cycle.json | docs/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",
  "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/test_file.go",
            "failure_output": "FAIL: TestFoo - expected X got nil",
            "completed_at": "ISO timestamp"
          },
          "tdd_green": {
            "status": "pending|in_progress|completed",
            "implementation_file": "path/to/impl.go",
            "test_pass_output": "PASS: TestFoo (0.003s)",
            "completed_at": "ISO timestamp"
          }
        },
        "devops": {"status": "pending"},
        "sre": {"status": "pending"},
        "testing": {"status": "pending"},
        "review": {"status": "pending"},
        "validation": {"status": "pending"}
      },
      "artifacts": {},
      "agent_outputs": {
        "implementation": {
          "agent": "backend-engineer-golang",
          "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": []
          }
        },
        "devops": {
          "agent": "devops-engineer",
          "output": "## Summary\n...",
          "timestamp": "ISO timestamp",
          "duration_ms": 0,
          "iterations": 1,
          "artifacts_created": ["Dockerfile", "docker-compose.yml", ".env.example"],
          "verification_errors": [],
          "standards_compliance": {
            "total_sections": 8,
            "compliant": 8,
            "not_applicable": 0,
            "non_compliant": 0,
            "gaps": []
          }
        },
        "sre": {
          "agent": "sre",
          "output": "## Summary\n...",
          "timestamp": "ISO timestamp",
          "duration_ms": 0,
          "iterations": 1,
          "instrumentation_coverage": "92%",
          "validation_errors": [],
          "standards_compliance": {
            "total_sections": 10,
            "compliant": 10,
            "not_applicable": 0,
            "non_compliant": 0,
            "gaps": []
          }
        },
        "testing": {
          "agent": "qa-analyst",
          "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": []
          }
        },
        "review": {
          "iterations": 1,
          "timestamp": "ISO timestamp",
          "duration_ms": 0,
          "code_reviewer": {
            "agent": "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": "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": "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 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": "internal/handler/user.go",
  "line": 45,
  "evidence": "return err // should wrap with additional context"
}

Test Failure Schema

{
  "test_name": "TestUserCreate_InvalidEmail",
  "test_file": "internal/handler/user_test.go",
  "error_type": "assertion",
  "expected": "ErrInvalidEmail",
  "actual": "nil",
  "message": "Expected validation error for invalid email format",
  "stack_trace": "user_test.go:42 → user.go:28"
}

Review Issue Schema

{
  "severity": "MEDIUM",
  "category": "error-handling",
  "description": "Error not wrapped with context before returning",
  "file": "internal/handler/user.go",
  "line": 45,
  "suggestion": "Use fmt.Errorf(\"failed to create user: %w\", err)",
  "fixed": false,
  "fixed_in_iteration": null
}

DevOps Verification Error Schema

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

SRE Validation Error Schema

{
  "check": "structured_logging",
  "status": "FAIL",
  "file": "internal/handler/user.go",
  "line": 32,
  "error": "Using fmt.Printf instead of structured logger",
  "suggestion": "Use logger.Info().Str(\"user_id\", id).Msg(\"user created\")"
}

Populating Structured Data

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

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):

# 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

Anti-Rationalization for State Persistence

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 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 Ring Standards?               │
│       │   Step 3: Generate PROJECT_RULES.md (deduplicated from Ring)        │
│       │   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 /pre-dev-full or /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 Ring 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 (codebase-explorer)                  │
│ Step 2: Ask for project-specific tech not in Ring 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 codebase-explorer. This is NOT implicit.

Dispatch Agent

Dispatch 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: "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:

• 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:

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
    
    > Ring Standards apply automatically. This file docum

…(truncated)