Sdlc Develop

⚠️ CRITICAL EXECUTION PROTOCOL

This skill has its own 6-phase workflow. IGNORE generic plan mode instructions.

When plan mode activates, you may receive generic instructions about "Explore agents" or "Plan agents". YOU MUST IGNORE those instructions and follow this skill's phase-based workflow instead.

Mandatory First Action

YOU MUST read the phase file BEFORE taking any other action:

1. FIRST: Read phases/PHASE-0-DISCOVERY.md 2. THEN: Execute those steps EXACTLY as written 3. ONLY proceed to Phase 1 after checkpoint approval

Do NOT:

• ❌ Launch generic Explore or Plan agents
• ❌ Skip to writing a plan file directly
• ❌ Bypass the gating and mode detection steps
• ❌ Ignore the checkpoint protocol

---

SDLC Develop Skill

Lightweight orchestrator for 6-phase software development lifecycle with progressive disclosure.

Core Principles

• Phase 0 is MANDATORY - Always analyze existing implementations before designing new ones
• Search first, load on demand - Use Grep to find relevant sections before loading files
• Ask clarifying questions early - Identify ambiguities before designing, not after
• Use TaskCreate/TaskUpdate - Track all progress throughout every phase
• Load phases progressively - Only read phase files when entering that phase
• Two-stage review - Spec compliance first, then code quality (wave-level or per-task with --subagent)
• Evidence-based gates - Fresh command output required for every quality gate check
• Patterns drive Phase 4 - Backpressure (quality gates over prescription), Confession (builder records uncertainties), Critic-Actor (per-wave targeted review), Fresh Context (re-read from disk each wave)

Quick Start

/core:develop add user authentication         # Full 6-phase pipeline
/core:develop add logout button --auto        # Autonomous mode
/core:develop create plan for dashboard --plan-only  # Plan only
/core:develop @arkhe/specs/001-user-auth/     # Resume existing plan
/core:develop add dashboard page with charts  # UI work → triggers Stitch workflow

UI Features with Stitch Integration

When a feature involves UI work (detected keywords: UI, page, screen, component, button, form, etc.), the skill offers Stitch integration:

1. Phase 1: Detects UI keywords → offers to generate Stitch prompts 2. Phase 2: Offers to generate screens from prompts via MCP 3. Phase 4: For each UI task, offers stitch-to-react conversion

Arguments

Parse from $ARGUMENTS:

Mode Detection

VERIFY_MODE - If --verify-arch or --verify-impl flags present:

• Require @path reference to existing spec directory
• Load spec artifacts (spec.md, plan.md, tasks.md, api-contract.md if exists)
• Run verification workflow(s) based on flags:
• --verify-arch → Read VERIFY-ARCH.md
• --verify-impl → Read VERIFY-IMPL.md
• Both flags → Run both verifications
• Output verification report using verification-report.md.template
• Does NOT execute SDLC phases

RESUME_MODE - If @path reference found AND plan.md exists (no verify flags):

• Read existing plan from path
• Auto-detect wave progress via wave-*-context.md files and tasks.md Status fields
• If wave context found: offer to continue next wave, re-review, or restart from a phase
• If no wave context: ask user which phase to continue from (existing behavior)
• Skip to selected phase, load only that phase file

PLAN_MODE - If keywords "create plan", "plan for", "draft plan" OR --plan-only:

• Execute Phases 0-2 only
• Save spec.md and plan.md
• Stop with resume instructions

FULL_MODE - Default:

• Execute all 6 phases sequentially
• User checkpoints between phases (unless --auto)

Phase Routing

Load phase files only when entering that phase:

Model Tiers

Spec Directory Structure

Plans are persisted to {specs_dir}/ with auto-incrementing prefixes:

{specs_dir}/
├── 001-user-auth/
│   ├── spec.md              # Requirements
│   ├── plan.md              # Architecture
│   ├── tasks.md             # Task breakdown (with Status field)
│   ├── wave-1-context.md    # Wave 1 handoff (generated at checkpoint)
│   ├── wave-2-context.md    # Wave 2 handoff (generated at checkpoint)
│   └── ...
├── 002-dashboard/
└── ...

Note: {specs_dir} references the configured value from .arkhe.yaml (default: arkhe/specs).

Progressive Persistence

Artifacts are saved incrementally at each phase checkpoint to prevent data loss:

Crash Recovery: If session ends mid-phase, resume with /core:develop @{spec_path}/ and artifacts from completed phases are preserved.

Templates

Configuration

On first run or when entering Phase 2d: 1. Read .arkhe.yaml from project root (if exists) 2. Extract develop.specs_dir value (default: arkhe/specs) 3. Use this value for ALL spec directory operations

develop:
  specs_dir: arkhe/specs  # Customize this path
  numbering: true         # NNN- prefix (3-digit, e.g., 001-)
  ticket_format: full     # full | simple

All paths in this skill use `{specs_dir}` to reference the configured value.

First run without config prompts for preferences.

Execution Flow

Parse arguments and detect mode (RESUME/PLAN/FULL), then execute phases sequentially. RESUME loads existing plan and offers wave continuation. PLAN stops after Phase 2. FULL executes all 6 phases with checkpoints between each.

See WORKFLOW.md for the detailed execution flow diagram.

Checkpoints

Two mandatory Tier 1 gates (cannot skip, even with --auto):

• Phase 2c: Architecture Decision
• Step 4.2: Quality & Completion Gate (RULE ZERO + wave review aggregation)

All other checkpoints are Tier 2 (skippable with --auto), including the Domain Research gate (Phase 2a-res) and the Two-Stage Wave Review (Step 4.1e). Conditional escalation to Tier 1 if: DB schema changes, security work, or breaking API changes. Conditional RFC creation offered at Phase 2d when escalation triggers are detected.

See GATES.md for full checkpoint protocol, decision criteria, and prompt patterns.

Examples

See EXAMPLES.md for detailed usage scenarios.

Troubleshooting

See TROUBLESHOOTING.md for common issues.

Evidence-Based Quality Gates

Companion guide to the Wave Quality Gates in Phase 4. Defines evidence requirements and rationalization prevention for each gate.

Core principle: No completion claim without fresh verification evidence.

---

The Iron Rule

Every quality gate check must produce fresh command output in the current context. Cached results, remembered outputs, and assumptions are not valid evidence.

If you haven't run the command THIS wave, you cannot claim it passes.

---

Per-Gate Evidence Requirements

---

Rationalization Prevention

Common thoughts that indicate a gate is about to be skipped without evidence. If you catch yourself thinking any of these, STOP and run the verification.

---

Escalation Protocol

Quality gates are not strictly binary. When a gate cannot be evaluated:

Rules:

• Never force-pass a BLOCKED gate
• Never guess at a NEEDS_CONTEXT gate
• Always explain what prevented evaluation
• User may override with explicit approval (documented in wave-context.md)

---

Evidence Capture Format

When recording gate results, include the actual evidence:

### Gate Results — Wave {N}

| # | Gate | Status | Evidence |
|---|------|--------|----------|
| 1 | Task completion | PASS | tasks.md: T-04 COMPLETED, T-05 COMPLETED |
| 2 | File evidence | PASS | git diff --stat: 4 files changed, 127 insertions(+), 12 deletions(-) |
| 3 | Tests green | PASS | npm test: 47 passing, 0 failing (exit 0) |
| 4 | No placeholders | PASS | grep TODO/FIXME: 0 matches in changed files |
| 5 | Acceptance criteria | PASS | AC-1: src/auth.ts:42, AC-2: src/auth.ts:78, AC-3: tests/auth.test.ts:15 |
| 6 | Confessions | PASS | wave-2-context.md: T-04 confession recorded, T-05 confession recorded |

SDLC Develop Examples

Note: All examples use the default path arkhe/specs/. If you configure a custom specs_dir in .arkhe.yaml, paths will use your configured value instead (e.g., plan/arkhe/specs/).

Full Pipeline (Interactive)

/core:develop add user authentication

What happens: 1. Executes all 6 phases with user checkpoints 2. Creates: arkhe/specs/001-user-auth/ with spec.md, plan.md, tasks.md 3. Implements the feature 4. Validates and summarizes

Output:

arkhe/specs/001-user-auth/
├── spec.md       # Requirements & acceptance criteria
├── plan.md       # Architecture & design decisions
└── tasks.md      # Full ticket breakdown

---

Plan Only

/core:develop create plan for dashboard feature --plan-only

What happens: 1. Executes Phases 0-2 only 2. Saves spec.md and plan.md to arkhe/specs/002-dashboard/ 3. Stops without implementing

Output:

Spec saved to `arkhe/specs/002-dashboard/`

Files created:
- spec.md (requirements)
- plan.md (architecture)

Run `/core:develop @arkhe/specs/002-dashboard/` when ready to implement.

---

Resume Existing Spec

/core:develop @arkhe/specs/001-user-auth/

What happens: 1. Loads existing spec and plan from path 2. Asks which phase to continue from 3. Skips completed phases

Interaction:

Found existing spec: 001-user-auth
Status: Architecture complete (Phase 2)

Which phase would you like to continue from?
1. Phase 3: Workstreams (generate tasks)
2. Phase 4: Implementation (start coding)
3. Phase 0: Start fresh

---

Autonomous Mode

/core:develop add logout button --auto

What happens: 1. Executes all phases without checkpoints 2. Makes reasonable default decisions 3. Reports everything at the end 4. Creates: arkhe/specs/003-logout-button/

Use when:

• Simple, well-understood features
• You trust the default architecture choices
• You want minimal interaction

---

With Deep Validation

/core:develop refactor payment service --validate

What happens: 1. Standard 6-phase pipeline 2. In Phase 4, includes opus-level deep validation 3. Scores implementation 0-100 4. Reports detailed findings

Validation output:

Deep Validation Results:
- Score: 87/100 (Medium-High Confidence)
- Issues found:
  - Missing error handling for timeout scenario
  - Test coverage at 75% (below 80% target)
- Recommendations:
  - Add timeout handling in PaymentProcessor.process()
  - Add unit tests for edge cases

---

Specific Phase Only

/core:develop @arkhe/specs/001-user-auth/ --phase=4

What happens: 1. Loads existing spec from path 2. Executes only Phase 4 (implementation) 3. Skips all other phases 4. Useful for re-running implementation after plan changes

---

First Run (Configuration)

/core:develop add shopping cart

If no `.arkhe.yaml` exists:

No configuration found. Let me set up SDLC preferences.

Where should specs be saved?
1. arkhe/specs/ (Recommended)
2. .sdlc/
3. docs/specs/
4. Custom path...

Use numbered prefixes (001-, 002-)?
1. Yes (Recommended)
2. No

Creates `.arkhe.yaml`:

develop:
  specs_dir: arkhe/specs
  numbering: true
  ticket_format: full

---

Interaction Modes Comparison

---

Spec Directory Examples

After multiple features:

arkhe/specs/
├── 001-user-auth/
│   ├── spec.md
│   ├── plan.md
│   └── tasks.md
├── 002-dashboard/
│   ├── spec.md
│   └── plan.md        # --plan-only stopped here
├── 003-logout-button/
│   ├── spec.md
│   ├── plan.md
│   └── tasks.md
└── 004-payment-refactor/
    ├── spec.md
    ├── plan.md
    ├── tasks.md
    └── proofs/        # Validation artifacts (if --validate)
        └── validation-report.md

HITL Gate System

Human-in-the-Loop gates ensure appropriate oversight at critical decision points.

Three-Tier Framework

---

Gate Mapping by Phase

---

Conditional Tier 1 Triggers

These auto-elevate ANY checkpoint to Tier 1:

• [ ] Database schema changes (CREATE TABLE, ALTER TABLE, migrations)
• [ ] Security implementation (JWT, OAuth2, encryption, permissions)
• [ ] Breaking API changes (removed endpoints, changed contracts)
• [ ] New service/module creation
• [ ] Architecture decisions affecting multiple services
• [ ] Performance-critical algorithm changes

Detection: Check plan.md, spec.md, and implementation for keywords.

Note: The Quality & Completion Gate (Step 4.2) is always Tier 1 regardless of triggers. The presence of conditional triggers is recorded in the gate log for audit purposes but does not change gate behavior.

---

Gate Decision Criteria

Tier 1: Always Block ⛔

Must have explicit human approval before proceeding:

• Architecture decisions (approach selection)
• Implementation completion (RULE ZERO)
• Any conditional trigger detected
• Constitutional compliance concerns

Tier 2: Recommend Review ⚠️

Review recommended but can skip with --auto:

• Requirements gathering complete
• Existing system analysis complete
• Domain research before architecture design
• Task breakdown complete
• Refactoring >100 LOC
• New third-party dependencies
• Test coverage changes

Tier 3: Auto-Proceed ✅

Proceed automatically, log for post-review:

• Plan file saved
• Documentation updates
• Code formatting
• Template generation

---

Evidence Requirements

All quality gates and review stages must produce fresh verification evidence. No completion claim without fresh command output in the current context.

Per-Gate Required Evidence

Rationalization Prevention

Escalation Paths

Gates are not strictly binary. When a gate cannot be evaluated:

See EVIDENCE-GATES.md for the full rationalization prevention guide and evidence capture format.

---

AskUserQuestion Pattern

For Tier 1 and Tier 2 gates, use the AskUserQuestion tool:

{
  "header": "{Short checkpoint name}",
  "question": "{Summary of what was done/proposed}. How would you like to proceed?",
  "options": [
    { "label": "APPROVE", "description": "Proceed to next phase" },
    { "label": "REVIEW", "description": "Show me more details" },
    { "label": "MODIFY", "description": "I want to change something" },
    { "label": "CANCEL", "description": "Stop here" }
  ]
}

Tool Constraints:

• 2-4 options per question (tool limit)
• "Other" option is automatically provided by the tool
• For dynamic options (architecture), generate at runtime

Example: Architecture Decision (Tier 1)

Present the trade-offs summary, then use AskUserQuestion:

{
  "header": "Architecture",
  "question": "JWT+Redis is scalable but adds Redis dependency. Session-based is simpler but stateful. OAuth2 is standards-based but external. Which approach?",
  "options": [
    { "label": "Option A: JWT + Redis (Recommended)", "description": "Scalable, stateless design" },
    { "label": "Option B: Session-based", "description": "Simple, proven pattern" },
    { "label": "Option C: OAuth2 only", "description": "Standards-based, external auth" },
    { "label": "REQUEST CHANGES", "description": "Modify requirements first" }
  ]
}

Example: Quality & Completion (Tier 1)

Present combined quality review + RULE ZERO status, then use AskUserQuestion:

{
  "header": "Quality & Completion",
  "question": "RULE ZERO: 6/6 checks passed. Wave reviews: 3 waves passed, 0 approved with notes. Mark implementation complete?",
  "options": [
    { "label": "APPROVE — Mark Complete", "description": "All checks pass, proceed to Phase 5 summary" },
    { "label": "REVIEW — Show diff & details", "description": "Show git diff and full validation report" },
    { "label": "FIX — Return to implementation", "description": "Address issues, then re-present this gate" },
    { "label": "VERIFY UI — Test in browser", "description": "Run Playwright verification before approving" }
  ]
}

Example: Requirements (Tier 2)

{
  "header": "Requirements",
  "question": "3 functional requirements defined with 8 acceptance criteria. How would you like to proceed?",
  "options": [
    { "label": "APPROVE", "description": "Proceed to architecture design" },
    { "label": "REVIEW", "description": "Show me full requirements" },
    { "label": "MODIFY", "description": "I want to change requirements" },
    { "label": "CANCEL", "description": "Stop here" }
  ]
}

Example: Wave Checkpoint (Tier 2)

Present wave completion metrics, then use AskUserQuestion:

{
  "header": "Wave Complete",
  "question": "Wave 2 complete: 4 tasks done, 8 files changed, 15/15 tests passing. Wave 3 has 3 remaining tasks (T-05, T-06, T-07). How to proceed?",
  "options": [
    { "label": "CONTINUE", "description": "Proceed to Wave 3 in current session" },
    { "label": "STOP", "description": "Save context, copy resume command to clipboard, and exit" }
  ]
}

Example: Two-Stage Wave Review Result

The two-stage wave review is an agent workflow, not an AskUserQuestion gate. Stage 1 (spec compliance) runs first; if it passes, Stage 2 (code quality) runs. Each stage returns PASS or ISSUES directly. If ISSUES are returned, the builder fixes them and the reviewer re-reviews (bounded to 1 retry across both stages combined). After 1 rejection, approve with notes. The result is recorded in wave-context.md, not presented as a user gate.

---

--auto Mode Behavior

Key: Tier 1 gates ALWAYS require human approval, regardless of flags.

---

Logging Gate Decisions

All gate decisions should be logged:

## Gate Log

| Time | Gate | Tier | Decision | Mode |
|------|------|------|----------|------|
| 10:15 | Existing System | Tier 2 | APPROVED | interactive |
| 10:22 | Requirements | Tier 2 | APPROVED | interactive |
| 10:30 | Domain Research | Tier 2 | Research | interactive |
| 10:45 | Architecture | Tier 1 | Option A | interactive |
| 10:46 | Plan Saved | Tier 3 | AUTO | auto |

This log can be included in the spec directory for audit purposes.

Phase 0: Discovery & Existing System Analysis

Goal: Understand context and prevent duplicate implementations

Model tier: haiku for gating, sonnet for analysis

---

Step 0a: Gating (haiku agent)

Launch a haiku agent to determine if the request is actionable:

Analyze this request and determine if it's actionable:
- Is the request clear enough to proceed?
- Are there obvious blockers (missing context, permissions)?
- Should we proceed, ask clarifying questions, or decline?

Request: [user request]

Return: PROCEED | CLARIFY:[questions] | DECLINE:[reason]

If CLARIFY: Ask the user the questions before continuing. If DECLINE: Explain why and stop.

---

Step 0b: Mode Detection (haiku agent)

Analyze this request to determine execution mode:

**Request:** [user request]

Tasks:
1. Extract path references (@specs/auth/, explicit paths)
2. Check if plan.md exists at extracted path
3. Detect project conventions (.specify/, plan/specs/, specs/)
4. Generate feature slug (lowercase, hyphens, 10-20 chars)
5. Check for PLAN_MODE keywords ("create plan", "draft plan")

Return:
- MODE: RESUME_MODE | PLAN_MODE | FULL_MODE
- PLAN_PATH: [path if found, null otherwise]
- FEATURE_SLUG: [generated slug]

---

Step 0b-resume: Wave Progress Detection (RESUME_MODE only)

Skip if: FULL_MODE or PLAN_MODE

When RESUME_MODE is detected (@path + plan.md exists), check for wave-level progress:

1. Check for Wave Context Files

Use Glob to find {spec_path}/wave-*-context.md files.

2. Check Task Status Fields

Read tasks.md and check for **Status**: fields on each task:

• If Status fields exist: count SELECTED, DEFERRED, COMPLETED tasks
• If Status fields are missing: treat all tasks as Status: SELECTED (backward compatibility)

3. Determine Resume Point

• If wave context files found:
• Find the highest numbered wave-{N}-context.md → Wave N is complete
• Read the latest wave context file for summary data
• Count remaining SELECTED tasks in subsequent waves
• Present summary:

    "Previous session completed Wave {N} ({completed_count} tasks: T-XX to T-YY).
     Wave {N+1} has {remaining_count} remaining tasks: T-ZZ, T-AA, T-BB."

• If no wave context files found:
• Fall through to existing behavior (ask which phase to continue from)
• Skip to the existing RESUME_MODE handling below

4. Wave Resume Checkpoint

Gate: Tier 2 ⚠️ (skippable with --auto — auto-selects "All remaining tasks")

Use AskUserQuestion:

• header: "Resume"
• question: "{Wave progress summary}. Wave {N+1} has {remaining_count} remaining tasks: {task_id_list}. What would you like to do?"
• options:
• { label: "All remaining tasks (Recommended)", description: "Select all remaining tasks and proceed immediately to implementation" }
• { label: "Choose tasks first", description: "Review and select specific tasks before starting" }
• { label: "Re-review completed work", description: "Show git diff of previous waves" }
• { label: "Restart from a phase", description: "Choose which phase to continue from" }

Response Handling:

• All remaining tasks: Auto-mark all non-COMPLETED tasks as Status: SELECTED in tasks.md. Set selection_scope = ALL. Load PHASE-4-IMPLEMENTATION.md, skip Step 4.0 entirely, proceed directly to Step 4a.1 (Wave Confirmation, which auto-proceeds since selection_scope = ALL)
• Choose tasks first: Load PHASE-4-IMPLEMENTATION.md, start at Step 4.0 (Ticket Selection) — user reviews and selects tasks manually
• Re-review completed work: Run git diff for previous wave commits, then re-present this checkpoint
• Restart from a phase: Fall through to existing phase selection behavior

---

Step 0b-post: Create Spec Directory (FULL_MODE/PLAN_MODE only)

Skip if: RESUME_MODE (spec directory already exists)

For new features, create the spec directory immediately after mode detection:

1. Load Configuration

Read .arkhe.yaml from project root:

• Extract develop.specs_dir value (default: arkhe/specs)
• Extract develop.numbering value (default: true)

2. Determine Spec Path

If numbering: true: 1. Resolve script path: Glob for **/sdlc-develop/scripts/next_spec_number.py 2. Run script: python3 {script_path} --specs-dir {specs_dir} 3. Parse JSON output: Extract prefix field (e.g., "005") 4. Full path: {specs_dir}/{prefix}-{feature_slug}/

If numbering: false:

• Full path: {specs_dir}/{feature_slug}/

3. Create Directory and Initial Files

Use Bash to create the directory structure:

mkdir -p {specs_dir}/{NNN}-{feature_slug}

Use Write tool to create placeholder files:

spec.md (initial):

# {Feature Name} Specification

**Spec ID:** {NNN}-{feature_slug}
**Status:** In Progress
**Created:** {date}

---

## Summary

{Brief description from user request}

---

_Requirements will be populated in Phase 1._

plan.md (initial):

# {Feature Name} Implementation Plan

**Spec:** {NNN}-{feature_slug}
**Status:** In Progress
**Created:** {date}

---

_Architecture will be populated in Phase 2._

4. Store Path for Later Phases

Set spec_path = {specs_dir}/{NNN}-{feature_slug} for use in subsequent phases.

Log: "Created spec directory: {spec_path}/"

---

Step 0c: Existing System Analysis (MANDATORY)

This step cannot be skipped.

Launch code-explorer agent to analyze existing implementations:

Analyze the codebase to identify existing implementations relevant to this feature:

**Feature:** [user request]

Tasks:
1. Search for similar features already implemented
2. Map existing services/modules that might handle this
3. Identify reusable components, patterns, and abstractions
4. Document integration points

For each relevant area found, classify as:
- REUSE: Use existing implementation as-is
- ENHANCE: Extend existing implementation
- CREATE: Build new (justify why existing won't work)

Return:
- Existing implementations found (with file:line references)
- Classification decisions with justification
- Key files to read before designing

---

User Checkpoint

Gate: Tier 2 ⚠️ (RECOMMENDED - skippable with --auto)

Present findings to user: 1. Summary of existing implementations found 2. REUSE/ENHANCE/CREATE classifications 3. Key files identified for further analysis

Ask using AskUserQuestion:

Present findings summary, then use AskUserQuestion tool:

• header: "Phase 0"
• question: "[Summary of REUSE/ENHANCE/CREATE findings]. How would you like to proceed?"
• options:
• { label: "APPROVE", description: "Proceed to requirements gathering" }
• { label: "REVIEW", description: "Show me more details about findings" }
• { label: "MODIFY", description: "I want to change classifications" }
• { label: "CANCEL", description: "Stop here" }

Response Handling:

• APPROVE: Proceed to Phase 1
• REVIEW: Show detailed findings, then re-present this checkpoint
• MODIFY: Allow user to change classifications, then re-present
• CANCEL: Stop pipeline

STOP: Unless `--auto` is set, WAIT for user response before proceeding to Phase 1.

---

Output

Phase 0 produces:

• Mode determination (RESUME/PLAN/FULL)
• Feature slug for spec directory
• Existing implementation analysis
• Key files list for Phase 2

Generate Reuse Matrix (if FULL_MODE)

Use reuse-matrix.md.template to document:

• REUSE/ENHANCE/CREATE classifications
• Integration points identified
• Similar components considered

Save as {spec_path}/reuse-matrix.md (directory was created in Step 0b-post)

Next: Proceed to PHASE-1-REQUIREMENTS.md

Phase 1: Requirements

Goal: Understand what needs to be built

Model tier: sonnet

---

Actions

1. Clarify Feature Request

If feature is unclear, ask user for:

• What problem are they solving?
• What should the feature do?
• Any constraints or requirements?

2. Identify Underspecified Aspects

Review and document gaps in:

• Edge cases and error handling
• Integration points and scope boundaries
• Design preferences and backward compatibility
• Performance and security needs

3. Document Requirements

Create structured requirements:

## Functional Requirements

### FR-001: [Requirement Title]
**Description:** [What the system should do]
**Acceptance Criteria:**
- [ ] [Testable criterion 1]
- [ ] [Testable criterion 2]
- [ ] [Testable criterion 3]

### FR-002: [Next Requirement]
...

4. Define Constraints

Document:

• Performance requirements (quantified, e.g., "<200ms response time")
• Security considerations
• Backward compatibility needs
• Dependencies on external systems

5. UI Work Detection

After gathering requirements, scan for UI-related keywords in the feature request and requirements:

UI Keywords:

• Layout: UI, page, screen, layout, view, route
• Components: component, button, form, modal, dialog, panel, card
• Design: design, frontend, style, CSS, Tailwind, animation
• Visual: icon, image, color, theme, responsive

If UI keywords detected:

Set ui_work_detected = true and use AskUserQuestion:

• header: "Design Assets"
• question: "This feature involves UI work ([list detected keywords]). How would you like to handle design assets?"
• options:
• { label: "Generate Stitch prompts (Recommended)", description: "Create design prompts using authoring-stitch-prompts skill" }
• { label: "I have existing designs", description: "Provide Figma/Stitch export locations" }
• { label: "Skip design workflow", description: "Implement UI directly without Stitch" }

Response handling:

• Generate Stitch prompts:

1. Invoke Skill tool with skill: "authoring-stitch-prompts" 2. Pass requirements as context 3. Store generated prompts path for Phase 2 4. Set stitch_prompts_generated = true

• Existing designs:

1. Ask user for asset paths (Figma URL, Stitch exports directory) 2. Store paths for use in plan.md ## Design Assets section 3. Set existing_designs_path = [user provided path]

• Skip:

1. Set skip_stitch_workflow = true 2. Continue without Stitch integration

6. Save Requirements

After documenting requirements, persist to spec.md immediately:

1. Read existing spec.md from {spec_path}/spec.md 2. Update with requirements:

• Functional Requirements (FR-XXX format)
• Acceptance criteria for each requirement
• Constraints and assumptions
• UI work detection results (if applicable)

3. Write updated spec.md using spec.md.template 4. Log: "Requirements saved to {spec_path}/spec.md"

Rationale: Saving after Phase 1 ensures requirements are not lost if session ends before Phase 2.

---

User Checkpoint

Gate: Tier 2 ⚠️ (RECOMMENDED - skippable with --auto)

Present requirements summary: 1. List of FR-XXX requirements with acceptance criteria 2. Identified constraints 3. Any remaining questions or assumptions

Ask using AskUserQuestion:

Present requirements summary, then use AskUserQuestion tool:

• header: "Requirements"
• question: "[FR-XXX list summary with key acceptance criteria]. How would you like to proceed?"
• options:
• { label: "APPROVE", description: "Proceed to architecture design" }
• { label: "REVIEW", description: "Show me more details" }
• { label: "MODIFY", description: "I want to change requirements" }
• { label: "CANCEL", description: "Stop here" }

Response Handling:

• APPROVE: Proceed to Phase 2
• REVIEW: Show full requirements details, then re-present this checkpoint
• MODIFY: Allow user to modify requirements, then re-present
• CANCEL: Stop pipeline

STOP: Unless `--auto` is set, WAIT for user response before proceeding to Phase 2.

---

Output

Phase 1 produces:

• Functional requirements (FR-XXX format)
• Acceptance criteria for each requirement
• Constraints and assumptions
• Resolved clarifications

Next: Proceed to PHASE-2-ARCHITECTURE.md

Phase 2: Architecture

Goal: Design implementation approach with clear trade-offs

Model tier: sonnet (opus for complex architectures)

---

Step 2a-pre: Design Asset Generation (if UI work)

Skip this step if: skip_stitch_workflow = true or no UI keywords detected in Phase 1.

If stitch_prompts_generated = true:

Stitch prompts were generated in Phase 1. Now offer to generate actual screens:

1. Review the generated prompts (read from stored path) 2. Use AskUserQuestion:

• header: "Stitch Generation"
• question: "Stitch prompts are ready. Would you like to generate screens now?"
• options:
• { label: "Generate screens now (Recommended)", description: "Run generating-stitch-screens to create visual assets" }
• { label: "Generate later", description: "Save prompts, I'll generate manually" }
• { label: "Use prompts only", description: "Skip generation, use prompts as design reference" }

3. Response handling:

• Generate screens now:

1. Invoke Skill tool with skill: "generating-stitch-screens" 2. Wait for generation to complete 3. Store export paths: stitch_exports_path = [generated path]

• Generate later / Use prompts only:

1. Note in plan.md that Stitch screens should be generated before implementation 2. Set stitch_exports_path = null

If existing_designs_path was provided:

User provided existing design assets in Phase 1.

1. Verify the path exists using Glob tool 2. If path doesn't exist or is empty:

• Warn user: "Design assets not found at [path]"
• Offer to generate using Stitch or continue without

3. If path exists: Store for use in Phase 4

Store in plan.md

Add to plan.md under ## Design Assets:

## Design Assets

**Source:** Stitch generated | User provided | None
**Prompts:** `{prompts_path}` (if applicable)
**Exports:** `{exports_path}` (if applicable)
**Status:** Ready | Pending generation | Skipped

---

Step 2a: Codebase Exploration

Launch 2-3 code-explorer agents in parallel:

You are analyzing a codebase to prepare for implementing this feature:

**Feature:** [user request]
**Requirements:** [from Phase 1]
**Existing Analysis:** [from Phase 0c]

Focus on: [assign different focus to each agent]
- Similar feature implementations and patterns
- Architecture and relevant abstractions
- UI patterns, testing approaches, extension points

Return:
- Entry points with file:line references
- Key components and their responsibilities
- Patterns that should be followed
- List of 5-10 essential files

---

Step 2a-res: Domain Research

Gate: Tier 2 ⚠️ (RECOMMENDED - skippable with --auto)

Synthesize a targeted research query from Phase 1 spec and Step 2a codebase findings, then offer domain research before architecture design.

1. Derive Research Topic

From the available context, identify the primary domain topic to research:

• Phase 1 spec: Feature domain, functional requirements, constraints
• Step 2a findings: Tech stack, existing patterns, architecture style, frameworks in use

Synthesize a focused research query, e.g.:

• "Best practices for implementing event sourcing with PostgreSQL"
• "React Server Components data fetching patterns"
• "OAuth2 + JWT token refresh strategies for SPAs"

2. Present Research Gate

Use AskUserQuestion:

• header: "Architecture Research"
• question: "Codebase analysis complete. Research industry best practices for {inferred_topic} before architecture design?"
• options:
• { label: "Research (Recommended)", description: "Investigate best practices and patterns via deep-research" }
• { label: "Skip research", description: "Proceed directly to architecture design" }

If `--auto`: Skip research, set research_findings = null, proceed to Step 2b.

3. Execute Research (if accepted)

1. Invoke Skill tool with skill: "deep-research", passing the synthesized research query as argument 2. The deep-research skill handles caching (fast on cache hit) and EXA-based research (on cache miss) 3. Capture the structured research output 4. Set research_findings = [structured brief of key findings]

Key findings to extract for Step 2b:

• Recommended patterns and architectural approaches
• Common pitfalls and anti-patterns to avoid
• Industry-standard solutions for the problem domain
• Relevant trade-offs observed in real-world implementations

4. Skip Handling

If user selects "Skip research" or --auto mode: 1. Set research_findings = null 2. Proceed directly to Step 2b

---

Step 2b: Architecture Design

Launch 2-3 code-architect agents with different approaches:

Design an implementation approach for this feature:

**Feature:** [user request]
**Requirements:** [from Phase 1]
**Codebase Findings:** [from Step 2a]
**Research Findings:** [from Step 2a-res, or "No research conducted" if skipped]

Your approach focus: [assign one per agent]
- Minimal changes (smallest change, maximum reuse)
- Clean architecture (maintainability, elegant abstractions)
- Pragmatic balance (speed + quality)

If research findings are available, incorporate relevant patterns and avoid documented anti-patterns.

Return:
- Overview of approach
- Technical architecture (components, data flow)
- Implementation steps (phased)
- Dependencies and risks

---

Step 2c: Architecture Decision

1. Review all approaches and form your opinion 2. Present to user:

• Brief summary of each approach
• Trade-offs comparison
• Your recommendation with reasoning

3. Ask user which approach they prefer (unless --auto)

---

Step 2c-post: Save Architecture

After user approves architecture decision, persist to plan.md immediately:

1. Read existing plan.md from {spec_path}/plan.md 2. Update with architecture:

• Selected approach and rationale
• Technical architecture (components, data flow)
• Implementation phases
• Design assets section (if UI work)
• Research references (if Step 2a-res conducted): topic, key findings summary, cache path

3. Write updated plan.md using plan.md.template 4. Log: "Architecture saved to {spec_path}/plan.md"

---

Step 2d: Save Additional Artifacts (if applicable)

Note: Spec directory was created in Phase 0 (Step 0b-post). spec.md and plan.md were updated incrementally in Phase 1 and Step 2c-post.

Generate additional files when applicable:

1. adr-{NNN}.md - For significant architectural decisions (use adr.md.template) 2. api-contract.md - When feature includes API endpoints (use api-contract.md.template) 3. data-models.md - When feature involves database changes (use data-models.md.template)

4. RFC (conditional) - When conditional Tier 1 triggers are detected

Check if any escalation triggers from GATES.md are present in the architecture:

• Database schema changes (CREATE TABLE, ALTER TABLE, migrations)
• Security implementation (JWT, OAuth2, encryption, permissions)
• Breaking API changes (removed endpoints, changed contracts)
• New service/module creation
• Architecture decisions affecting multiple services
• Performance-critical algorithm changes

If triggers detected, use AskUserQuestion:

• header: "RFC Creation"
• question: "This feature involves {trigger_type}. Create a formal RFC for team review?"
• options:
• { label: "Create RFC (Recommended)", description: "Draft RFC from spec and architecture context" }
• { label: "Skip RFC", description: "Proceed without formal RFC" }

If `--auto`: Skip RFC creation.

If user accepts: 1. Invoke Skill tool with skill: "create-rfc", passing the feature name as argument 2. The create-rfc skill gathers context from conversation (spec.md, plan.md, research findings) and writes a populated RFC 3. Log: "RFC created — review with /doc:review-rfc <path>"

If user skips: 1. Log: "RFC skipped. Conditional triggers noted in gate log."

Note: Requires doc plugin. Skip RFC offer if plugin is not installed.

First-Run Behavior

Unless `--auto`:

• If no .arkhe.yaml exists (checked in Phase 0), ask user for preferences
• Create .arkhe.yaml with chosen settings

---

User Checkpoint (Architecture Decision)

Gate: Tier 1 ⛔ (MANDATORY - cannot skip even with --auto)

This is a critical decision point. Architecture choices affect the entire implementation.

Present architecture options: 1. Summary of each approach 2. Trade-offs matrix 3. Your recommendation

Ask using AskUserQuestion:

Present architecture comparison, then use AskUserQuestion tool:

• header: "Architecture"
• question: "[Trade-offs summary]. Which approach do you prefer?"
• options: Dynamically generate 2-4 options based on approaches found:
• For each approach: { label: "Option {A/B/C}: {name}", description: "{brief rationale}" }
• Mark recommended option with "(Recommended)" in label
• Always include: { label: "REQUEST CHANGES", description: "Modify requirements first" }

Example with 2 approaches:

{
  "header": "Architecture",
  "question": "Option A optimizes for performance, Option B for simplicity. Which approach?",
  "options": [
    { "label": "Option A: Event-Driven (Recommended)", "description": "Best for scalability" },
    { "label": "Option B: Synchronous", "description": "Simpler implementation" },
    { "label": "REQUEST CHANGES", "description": "Modify requirements first" }
  ]
}

CRITICAL: STOP AND WAIT for user response. This is a Tier 1 checkpoint - it CANNOT be skipped even with `--auto`.

Response Handling:

• Option A/B/C: Proceed with selected architecture to Step 2d
• REQUEST CHANGES: Return to requirements phase for modifications

---

Plan Saved Checkpoint

Gate: Tier 3 ✅ (AUTOMATED - proceeds automatically, logs for review)

After saving plan files, automatically proceed to next phase.

Log: "Artifacts saved to {spec_path}/"

---

PLAN_MODE Stop Point

If `--plan-only` flag:

Stop here with message:

Spec saved to `{spec_path}/`

Files created:
- spec.md (requirements)
- plan.md (architecture)

Run `/core:develop @{spec_path}/` when ready to implement.

---

Output

Phase 2 produces:

• Codebase exploration findings
• Domain research findings (if conducted)
• Architecture design options
• Selected approach with rationale
• Saved spec.md and plan.md files
• RFC draft (if conditional triggers detected and user accepted)

Next: Proceed to PHASE-3-WORKSTREAMS.md

Phase 3: Workstreams

Goal: Break implementation into parallel work streams with full ticket tracking

Model tier: haiku

---

Actions

1. Parse Implementation Phases

Read the saved plan.md for implementation phases from Phase 2.

2. Break into Discrete Tasks

Convert each phase into discrete tasks with full ticket metadata.

For each task, include a verification command that can objectively prove the task is complete (e.g., a test command, curl request, or grep check). This should be a CLI command that produces observable output. The verification section is optional for tasks where no single command can verify completion (e.g., pure refactoring tasks).

3. Organize into Parallel Waves

Group tasks based on dependencies:

• Wave 1: Tasks with no dependencies (can run in parallel)
• Wave 2: Tasks depending on Wave 1
• Wave 3: Tasks depending on Wave 2
• etc.

4. Generate tasks.md Structure

Prepare tasks.md content using tasks.md.template.

Note: The file will be saved in Step 7 after testing recommendations are processed.

5. Generate Dependency Diagram

Create a Mermaid graph showing task dependencies:

1. Create a subgraph for each wave (e.g., subgraph Wave1[Wave 1 - No Dependencies]) 2. Add each task as a node: T-XX[T-XX: Short title] 3. Add edges for each dependency: T-01 --> T-03 (source task points to dependent task) 4. Use graph TD (top-down) for <6 tasks, graph LR (left-right) for 6+ tasks

Include the diagram in tasks.md before the Summary table.

6. Testing Recommendations

After organizing implementation waves, analyze tasks for testing candidates.

High-value test targets (scan tasks for these patterns):

• Hooks: Files matching use*.ts or tasks mentioning "hook", "custom hook"
• Utilities: Files in /lib/, /utils/, or tasks mentioning "utility", "helper"
• API endpoints: Tasks involving HTTP routes, controllers, handlers
• State logic: Tasks involving reducers, stores, state machines
• Data transformations: Tasks involving parsers, formatters, mappers

If test candidates found:

Present to user:

**Testing Recommendation**

The following items are good candidates for unit tests:
- [hook/utility/endpoint name] - [file path]
- [hook/utility/endpoint name] - [file path]

Would you like to add a testing wave?

Use AskUserQuestion:

• header: "Testing"
• question: "[N] test candidates identified. Add a testing wave?"
• options:
• { label: "Yes, add testing wave", description: "Add Wave N+1 with test tasks" }
• { label: "Add to Next Steps", description: "Document as follow-up, don't block completion" }
• { label: "Skip testing", description: "No testing recommendations" }

Response handling:

• Add testing wave:

1. Create tasks for each test candidate:

• Type: test
• Priority: P2
• Effort: S or M
• Dependencies: corresponding implementation task
• Acceptance criteria: "Tests cover public API of [target]"

2. Add as final wave in tasks.md

• Add to Next Steps:

1. Store test candidates list for Phase 5 2. Set testing_recommendations = [list]

• Skip:

1. No testing recommendations generated

7. Save Task Breakdown

After generating tasks and (optional) testing wave, persist to tasks.md immediately:

1. Write tasks.md to {spec_path}/tasks.md

• Use tasks.md.template
• Include all waves with dependencies
• Include dependency diagram

2. Log: "Tasks saved to {spec_path}/tasks.md"

Rationale: Saving tasks immediately ensures the task breakdown is not lost if session ends before Phase 4.

---

Full Ticket Format

Each task uses structured ticket format:

## T-01: {Task Title}

**Type**: feature | bug | task | refactor | test
**Priority**: P0 (critical) | P1 (high) | P2 (medium) | P3 (low)
**Effort**: S (1-2h) | M (2-4h) | L (4-8h) | XL (8h+)
**Dependencies**: [T-02, T-03] or none
**Wave**: 1 | 2 | 3
**Files**: `path/to/file.ts`, `path/to/other.ts`

### Description
What needs to be done - clear, actionable description.

### Acceptance Criteria
- [ ] Criterion 1 - specific, testable
- [ ] Criterion 2 - specific, testable
- [ ] Criterion 3 - specific, testable

### Technical Notes
Implementation hints, patterns to follow, gotchas.

### Verification (optional)

{command to verify this task is complete}

**Expected:** {expected output or exit code}

---

Effort Estimation

---

User Checkpoint

Gate: Tier 2 ⚠️ (RECOMMENDED - skippable with --auto)

Present task breakdown: 1. Total task count by wave 2. Estimated total effort 3. Dependency graph visualization 4. Any questions about scope

Ask using AskUserQuestion:

Present task breakdown summary, then use AskUserQuestion tool:

• header: "Tasks"
• question: "[Task count by wave with total effort estimate]. How would you like to proceed?"
• options:
• { label: "APPROVE", description: "Start implementation" }
• { label: "REVIEW", description: "Show me task details" }
• { label: "MODIFY", description: "I want to change the breakdown" }
• { label: "CANCEL", description: "Stop here" }

Response Handling:

• APPROVE: Proceed to Phase 4
• REVIEW: Show full task details with dependency graph, then re-present this checkpoint
• MODIFY: Allow user to modify task breakdown, then re-present
• CANCEL: Stop pipeline

STOP: Unless `--auto` is set, WAIT for user response before proceeding to Phase 4.

---

Output

Phase 3 produces:

• tasks.md with full ticket breakdown
• Wave-organized implementation plan
• Effort estimates
• Dependency mapping

Next: Proceed to PHASE-4-IMPLEMENTATION.md

Phase 4: Implementation

Goal: Build the feature using quality gates, confession-driven review, and two-stage wave review

Model tier: sonnet for implementation, sonnet for reviewers (opus if --validate)

---

Step 4.0: Ticket Selection

Gate: Tier 2 (skippable with --auto — auto-selects all tasks)

Skip if: RESUME_MODE and user selected "All remaining tasks" at the Resume gate (tasks already marked SELECTED, selection_scope = ALL, proceed directly to Step 4.1).

Before executing any wave, allow the user to select which tasks to implement in this session.

1. Load and Present Tasks

Read tasks.md and present all tasks grouped by wave. Show COMPLETED waves as read-only context:

## Wave 1 (3 tasks) — COMPLETED
- T-01: [title] (Effort: M) — Status: COMPLETED
- T-02: [title] (Effort: S) — Status: COMPLETED
- T-03: [title] (Effort: S) — Status: COMPLETED

## Wave 2 (2 tasks, depends on Wave 1)
- T-04: [title] (Effort: L) — Status: SELECTED
- T-05: [title] (Effort: M) — Status: SELECTED

Note: Completed waves are shown for context but are not selectable. Only non-COMPLETED tasks can be selected or deferred.

2. Ask for Selection

Use AskUserQuestion:

• header: "Task Selection"
• question: "{total_count} tasks across {wave_count} waves. Which tasks to implement this session?"
• options:
• { label: "Select All (Recommended)", description: "Implement all tasks across all waves" }
• { label: "Select by Wave", description: "Choose which waves to include" }
• { label: "Custom Selection", description: "Provide specific task IDs via text input" }

Response Handling:

• Select All: Mark all tasks as Status: SELECTED. Set selection_scope = ALL (Step 4.1b will auto-proceed for each wave).
• Select by Wave: Set selection_scope = BY_WAVE. For each wave, use AskUserQuestion with yes/no:
• header: "Wave {N}"
• question: "Wave {N} has {count} tasks ({effort}). Include this wave?"
• options:
• { label: "Include", description: "Select all tasks in Wave {N}" }
• { label: "Skip", description: "Defer all tasks in Wave {N}" }
• Custom Selection: Set selection_scope = CUSTOM. User provides task IDs (e.g., "T-01, T-02, T-04") via "Other" text input

3. Update tasks.md

For each task, update the **Status**: field:

• Selected tasks → Status: SELECTED
• Non-selected tasks → Status: DEFERRED
• Previously completed tasks remain → Status: COMPLETED

4. Handle Edge Cases

• All tasks already COMPLETED: Skip to Step 4.2 (Quality & Completion Gate)
• Resume with completed waves: Show completed waves as read-only context, only allow selection on remaining (non-COMPLETED) waves
• Resume with no Status fields: Auto-add Status: SELECTED to all tasks (backward compatibility)
• `--auto` mode: Auto-select all non-COMPLETED tasks, skip this step

---

Step 4.1: Wave Execution Loop

Execute selected tasks wave by wave. Each wave iterates through sub-steps 4.1a → 4.1f.

Step 4.1a: Context Refresh (Fresh Context Pattern)

Every wave starts here, including Wave 1.

Re-read from disk to prevent context drift:

1. {spec_path}/spec.md — Extract FR-XXX requirements relevant to this wave's tasks 2. {spec_path}/plan.md — Extract architecture decisions and key patterns to follow 3. {spec_path}/tasks.md — Verify current Status fields, load this wave's task details 4. If wave-{N-1}-context.md exists — Read previous wave's summary, confessions, and review notes

This ensures each wave works from disk truth, not accumulated context.

Step 4.1b: Wave Confirmation

Gate: Conditional

• Tier 3 (auto-proceed, log only) if selection_scope = ALL — log "Wave {N}: auto-proceeded (Select All)" and continue to Step 4.1c
• Tier 2 (skippable with `--auto`) if selection_scope = BY_WAVE or CUSTOM

Auto-skip if: Wave has no SELECTED tasks (all DEFERRED or COMPLETED).

Present the wave's selected tasks:

## Wave {N}: {selected_count} tasks

| Task | Title | Effort | Files |
|------|-------|--------|-------|
| T-XX | [title] | M | `path/to/file` |
| T-YY | [title] | S | `path/to/file` |

**Total effort:** {effort_sum}

Use AskUserQuestion:

• header: "Wave {N}"
• question: "Wave {N} has {selected_count} selected tasks ({effort}). How to proceed?"
• options:
• { label: "PROCEED (Recommended)", description: "Implement all selected tasks in this wave" }
• { label: "SKIP TASKS", description: "Defer specific tasks from this wave" }
• { label: "SKIP WAVE", description: "Defer entire wave, move to next" }

Response Handling:

• PROCEED: Continue to Step 4.1c
• SKIP TASKS: User provides task IDs to defer, update tasks.md, re-present wave
• SKIP WAVE: Mark all wave tasks as DEFERRED in tasks.md, skip to next wave's Step 4.1a

Step 4.1c: Implementation (Backpressure Pattern)

Implement all SELECTED tasks in this wave. The builder chooses HOW — the quality gates define WHAT must be true when done.

Wave Quality Gates

All 6 gates must pass before proceeding to Step 4.1d:

Evidence rules:

• ALL gate checks must produce fresh command output. Cached or remembered results are not valid.
• Gate results must include the actual command output, not a summary of what "should" be true.
• If a check cannot produce fresh evidence, it FAILS (or escalates as BLOCKED/NEEDS_CONTEXT).

Rationalization guards (common false passes — if you think any of these, STOP and run the check):

• "Tests should pass because I only changed X" — RUN the tests
• "No placeholders because I didn't add any" — RUN the grep
• "Files match because I followed the plan" — RUN git diff --stat
• "Acceptance criteria met because the code implements it" — SHOW file:line evidence

See EVIDENCE-GATES.md for the full rationalization prevention guide and evidence capture format.

Status returns (replaces binary pass/fail):

• PASS: Gate passed with fresh evidence
• FAIL: Gate failed, fix required
• BLOCKED: Cannot verify (e.g., no test framework detected) — escalate to user
• NEEDS_CONTEXT: Gate requires information not available — escalate to user

Gate failure: Fix and re-run check with fresh output. Gates are checked once after all wave tasks are implemented, not per-task.

Recommended: Test-Driven Development

When implementing tasks, RED-GREEN-REFACTOR is the recommended workflow:

1. RED: Write a failing test that describes the desired behavior 2. Verify RED: Run the test, confirm it fails for the expected reason (not a typo or import error) 3. GREEN: Write minimal code to make the test pass 4. Verify GREEN: Run the full test suite, confirm all tests pass 5. REFACTOR: Clean up while keeping tests green

This is a recommendation, not a hard gate. Quality Gate #3 (Tests green) enforces that tests pass. TDD enforces that tests are meaningful.

Anti-patterns to avoid:

• Writing implementation first, tests after — tests that pass immediately prove nothing
• "Too simple to test" — simple code breaks; the test takes 30 seconds
• "I'll test after" — tests written after verify the implementation, not the requirement

When to skip TDD: Configuration-only changes, generated code, prototype/spike tasks (but add tests before marking COMPLETED).

Task tracking: Use TaskCreate/TaskUpdate for real-time progress visibility. Update tasks.md Status fields as tasks complete.

Subagent Mode (Conditional)

Activates when: --subagent flag is set. Replaces default Step 4.1c behavior for task implementation.

When in subagent mode, instead of the orchestrator implementing all tasks in the wave, dispatch a fresh subagent per task within the wave. Tasks are executed sequentially (not in parallel, to avoid conflicts).

Read SUBAGENT-MODE.md for the complete per-task execution protocol, including:

• Context preparation and dispatch
• Status handling (DONE/DONE_WITH_CONCERNS/NEEDS_CONTEXT/BLOCKED)
• Per-task two-stage review (spec compliance + code quality)
• Per-task confession recording
• Model selection by task complexity

After all tasks in wave complete (subagent mode): Skip Step 4.1e (already reviewed per task). Proceed to Step 4.1d (aggregate confessions) then Step 4.1f (wave checkpoint).

Default mode (no `--subagent`): Step 4.1c and 4.1e work as described below — wave-level implementation and wave-level two-stage review.

UI Implementation with Stitch (Conditional)

Skip this section if: No ## Design Assets section in plan.md or status is "Skipped".

When starting a UI-related task, check if Stitch exports are available:

1. Read plan.md and locate ## Design Assets section 2. If exports exist (stitch_exports_path is set):

• For each UI component task, match to corresponding Stitch export
• Use AskUserQuestion to offer stitch-to-react conversion
• If accepted: invoke Skill tool with skill: "stitch-to-react"

3. If exports don't exist but were expected (status "Pending generation"):

• Warn user, continue with manual implementation

Step 4.1d: Confession Recording (Confession Pattern)

After implementation passes quality gates, record confessions before the two-stage wave review.

For each completed task in this wave, write a confession block to {spec_path}/wave-{N}-context.md under ## Confessions — Wave {N}:

### T-{XX}: {Task Title}
- **Shortcuts**: [What was done expediently vs. ideally, or "None"]
- **Assumptions**: [Unverified beliefs the code depends on, or "None"]
- **Uncertainties**: [Areas where confidence is low, or "None"]
- **Deviations**: [Where implementation diverged from plan.md, or "None"]

Incentive framing: The confessor is rewarded for surfacing problems, not for appearing competent. Honest confessions lead to focused, efficient review. Minimal confessions lead to broader, slower review.

Step 4.1e: Two-Stage Wave Review (Critic-Actor Pattern)

Launch two sequential review stages for this wave's implementation. Stage 1 must pass before Stage 2 runs.

Skip if: --subagent mode is active AND all tasks in this wave passed per-task review (see SUBAGENT-MODE.md). Proceed directly to Step 4.1f.

Agent model: sonnet (or opus if --validate flag is set)

Stage 1: Spec Compliance Review

Purpose: Verify the wave built what was requested — nothing more, nothing less.

Agent input:

• FR-XXX requirements from spec.md relevant to this wave's tasks
• Task descriptions and acceptance criteria from tasks.md
• Confessions from Step 4.1d
• Git diff for this wave (git diff since wave start)

Agent instructions: Read REVIEW-SPEC.md for the full prompt template.

Key checks: Missing requirements, extra/unneeded work, acceptance criteria verification (file:line), confession validation.

Return: PASS or ISSUES (with file:line refs and affected FR-XXX/criteria)

If ISSUES: Builder fixes listed issues, spec reviewer re-reviews (1 retry bound across both stages).

Stage 2: Code Quality Review

Only runs after Stage 1 passes.

Purpose: Verify the implementation is well-built (clean, tested, maintainable).

Agent input:

• Git diff for this wave
• Confessions from Step 4.1d (shortcuts, assumptions)
• Quality gate results from Step 4.1c

Agent instructions: Read REVIEW-QUALITY.md for the full prompt template.

Key checks: Confessed weak spots (priority), cross-task interactions, file responsibility, test quality.

Exclude: Subjective style preferences, speculative issues, items that linters/tests would catch (quality gates already handle those).

Return: PASS or ISSUES (with file:line refs and severity: Critical/Important/Minor)

Bounded Retry (across both stages)

• If both stages PASS: Proceed to Step 4.1f
• If ISSUES in either stage: Builder fixes, reviewer re-reviews
• After 1 rejection across both stages combined: Approve with notes. Record notes in wave-context.md under ## Wave Review Result

Step 4.1f: Wave Checkpoint

Gate: Tier 2 (skippable with --auto — auto-continues to next wave)

Skip if: Wave was entirely skipped (no tasks executed).

After completing all selected tasks and passing the two-stage wave review:

1. Collect Wave Metrics

• Tasks completed in this wave (count and IDs)
• Files changed (git diff --stat since wave start)
• Test status (run test suite, count passing/failing)
• Commits made during this wave (git log --oneline since wave start)
• Wave review verdict (PASS or notes from both stages)

2. Generate Wave Context File

Use wave-context.md.template to generate {spec_path}/wave-{N}-context.md:

• Fill in feature summary from spec.md
• Fill in architecture overview from plan.md
• Fill in completed wave data from collected metrics
• Fill in confessions from Step 4.1d
• Fill in wave review result from Step 4.1e (both stages)
• Fill in next wave details from tasks.md (SELECTED tasks in Wave {N+1})
• Fill in git state (branch, last commit, diff stat)
• Fill in resume instructions with {spec_path}

Write the file using the Write tool.

3. Check for More Waves

• If more waves with SELECTED tasks remain: Present continue/stop choice
• If all waves complete: Log "All waves complete", proceed to Step 4.2

4. Continue or Stop

Use AskUserQuestion:

• header: "Wave Complete"
• question: "Wave {N} complete: {tasks_done} tasks, {files_changed} files changed, {tests_passing}/{tests_total} tests passing. Review: {verdict}. {next_wave_summary}. How to proceed?"
• options:
• { label: "CONTINUE (Recommended)", description: "Proceed to Wave {N+1} in current session" }
• { label: "STOP", description: "Save context, copy resume command to clipboard, and exit" }

Response Handling:

• CONTINUE: Proceed to Step 4.1a for Wave {N+1}
• STOP: Save wave context, copy resume command to clipboard, display resume instructions, and exit Phase 4 (skip Step 4.2):

1. Use Bash tool: printf '/core:develop @{spec_path}/' | pbcopy (macOS) or equivalent 2. Display:

  Wave {N} context saved to {spec_path}/wave-{N}-context.md
  Resume command copied to clipboard.

  To resume in this session:
  /core:develop @{spec_path}/

  For a fresh context window (recommended for large features):
  1. Run /clear (or start a new conversation)
  2. Paste and run: /core:develop @{spec_path}/

`--auto` mode: Auto-continue to next wave without stopping.

---

Step 4.2: Quality & Completion Gate

TIER 1 CHECKPOINT — MANDATORY STOP

This checkpoint CANNOT be skipped, even with `--auto`.

Before presenting this gate:

1. Aggregate wave review results from all waves (both stages' verdicts + notes) 2. Aggregate confessions from all waves 3. Run RULE ZERO verification with fresh evidence (see EVIDENCE-GATES.md):

• [ ] All tasks marked completed in tasks.md (read from disk, not TaskList memory)
• [ ] All FR-XXX requirements have file:line implementation evidence
• [ ] Files actually modified — fresh git diff --stat output captured
• [ ] Tests pass — fresh test suite output with pass/fail counts captured
• [ ] No placeholder code — fresh grep output: 0 matches for TODO/FIXME/NotImplementedError
• [ ] Subagent/review recommendations were implemented (not just analyzed)

Ask using AskUserQuestion:

Present combined quality review + RULE ZERO status, then use AskUserQuestion tool:

• header: "Quality & Completion"
• question: "[RULE ZERO: N/6 checks passed with fresh evidence]. [Wave reviews: N waves passed, N approved with notes]. Mark implementation complete?"
• options:
• { label: "APPROVE — Mark Complete", description: "All checks pass, proceed to Phase 5 summary" }
• { label: "REVIEW — Show diff & details", description: "Show git diff, full confession report, and review notes" }
• { label: "FIX — Return to implementation", description: "Address issues, then re-present this gate" }
• { label: "VERIFY UI — Test in browser", description: "Run Playwright verification before approving" }

CRITICAL: STOP HERE. DO NOT PROCEED TO PHASE 5 UNTIL USER SELECTS "APPROVE — Mark Complete".

Response Handling:

• APPROVE — Mark Complete: Proceed to Phase 5 (PHASE-5-SUMMARY.md)
• REVIEW — Show diff & details: Execute git diff, display confessions and review notes from all waves, then re-present this gate
• FIX — Return to implementation: Return to implementation work. When done, re-run quality gates and wave review, then re-present this gate
• VERIFY UI — Test in browser: Run UI verification workflow (see below), then re-present this gate

UI Verification Workflow (when VERIFY UI selected)

Live UI verification using Playwright CLI. Refer to the playwright:playwright-cli skill for the full command reference.

1. Ask for verification type:

• SCREENSHOT - Navigate to URL and capture screenshot for visual review
• INTERACTIVE - Take accessibility snapshot, explore and interact with elements
• TEST SCENARIO - Run specific test steps (navigate, click, fill, verify)

2. Execute based on selection:

• SCREENSHOT: Ask for URL, open page, capture screenshot, present for confirmation
• INTERACTIVE: Ask for URL, navigate, capture accessibility snapshot, offer interaction
• TEST SCENARIO: Ask for test steps (or reference task acceptance criteria), execute each step, report pass/fail

3. After verification: Return to Quality & Completion gate with results included

---

Output

Phase 4 produces:

• Implemented feature code
• Wave context files (wave-{N}-context.md) with confessions and review results for each completed wave
• Updated tasks.md with Status fields (SELECTED/DEFERRED/COMPLETED)
• Quality gate results per wave (with fresh evidence)
• Two-stage wave review verdicts per wave
• UI verification status (if performed)

Next: Proceed to PHASE-5-SUMMARY.md

Phase 5: Summary

Goal: Document what was accomplished

Model tier: None (direct output)

---

Actions

0. Sync tasks.md Acceptance Criteria

Before verifying completion, synchronize task status to tasks.md:

1. Read {spec_path}/tasks.md 2. Use TaskList to get all tasks and their status 3. For each task with status completed:

• Find the corresponding ### T-XX: section in tasks.md
• Locate the "#### Acceptance Criteria" subsection
• Replace all - [ ] with - [x] within that section

4. Use Edit tool to update tasks.md with the changes 5. Log: "Synced acceptance criteria: X checkboxes marked complete across Y tasks"

Note: This ensures tasks.md serves as a complete record of completed work, useful for handoffs and documentation.

1. Final Tasks Verification

Task tracking confirmation: 1. Use TaskList to verify all tasks are marked completed 2. If any tasks remain in_progress or pending (should not occur after Step 4.2 gate):

• Use TaskUpdate to mark them completed if the work was verified during Phase 4
• Log a warning if tasks were completed but not updated during implementation

spec.md confirmation: 1. Read {spec_path}/spec.md 2. Confirm all acceptance criteria are marked complete

2. Provide Completion Summary

Generate summary in this format:

## Development Complete

**Feature:** [what was requested]
**Plan:** [path to saved plan]
**Status:** Complete | Partial | Blocked

### What Was Built
- [Key deliverable 1]
- [Key deliverable 2]
- [Key deliverable 3]

### Files Modified
- `path/to/file1.ts` - [what changed]
- `path/to/file2.ts` - [what changed]
- `path/to/file3.ts` - [what changed]

### Validation Results
- Quality gates: [PASS/issues per wave]
- Wave review: [verdicts and notes from both stages]
- RULE ZERO: [N/6 checks passed]

### Verification Steps
1. [How to test the feature]
2. [Commands to run]
3. [Expected behavior]

### Next Steps

**Always include testing recommendations** (pull from `testing_recommendations` if set in Phase 3, otherwise generate based on implemented files):

- [ ] **Unit tests** for:
  - [hook/utility name] (`path/to/file`)
  - [hook/utility name] (`path/to/file`)
- [ ] **Integration tests** for:
  - [API endpoint/data flow] (`path/to/file`)
- [ ] **E2E tests** for:
  - [user flow description] (if UI work was done)

**Other follow-up items:**
- [Recommended follow-up actions]
- [Related features to consider]
- [Technical debt to address]

3. Update Spec Status

Update {spec_path}/spec.md status to "Complete".

4. Save Project Learnings (Persistent Memory Pattern)

Evaluate whether discoveries from this feature should persist as project memory.

Auto-evaluate candidates from:

• Architecture trade-offs from Phase 2 (why option A over B)
• Gotchas discovered during implementation (framework limitations, API quirks)
• Domain knowledge from research phase (if Step 2a-res was conducted)
• Integration patterns established between existing and new code

Filter criteria (only save if):

• Not derivable from reading the code or git history
• Would be useful for future features in this project
• Represents a decision with non-obvious reasoning

If candidates found, use AskUserQuestion:

• header: "Project Learnings"
• question: "{N} learnings identified from this feature. Save to project memory?"
• options:
• { label: "Save all", description: "Write each as a project-type memory file" }
• { label: "Review first", description: "Show candidates, select which to save" }
• { label: "Skip", description: "Don't save any memories" }

Gate: Tier 3 (auto-skip with --auto; no memories saved in autonomous mode)

Response handling:

• Save all: For each learning, write a memory file:

  ---
  name: {feature-slug}-{learning-topic}
  description: {one-line description}
  type: project
  ---

  {Learning content}

  **Why:** {motivation or constraint}
  **How to apply:** {when this should shape future decisions}

Then add a pointer to MEMORY.md.

• Review first: Present each candidate, let user approve/reject individually, save approved ones
• Skip: No memories saved

If no candidates found: Skip silently, no user interaction.

5. Status Document Sync Suggestion

After the completion summary, check if the project has roadmap status documents:

1. Glob for docs/PROJECT-STATUS.md or check .arkhe.yaml for roadmap.status_file 2. If a status document is found, append to the completion summary:

### Status Documents
Project status documents may need updating after this feature.
Run `/roadmap:roadmap update --incremental` to sync PROJECT-STATUS.md.

This is a suggestion only — do NOT auto-execute the roadmap update.

---

Verification Record (RULE ZERO)

RULE ZERO was verified with fresh evidence at the Quality & Completion Gate (Step 4.2) before entering Phase 5. This section records the confirmed state for audit purposes.

Evidence-verified at gate approval (all fresh, not cached):

• [x] All tasks marked completed in tasks.md (read from disk)
• [x] All FR-XXX requirements have file:line implementation evidence
• [x] Acceptance criteria mapped to code with file:line references
• [x] Files actually modified — git diff --stat output captured
• [x] Tests pass — test suite output captured with pass/fail counts
• [x] No placeholder code — grep output: 0 matches for TODO/FIXME/NotImplementedError
• [x] Subagent/review recommendations implemented (not just analyzed)

Evidence artifacts:

• git diff --stat output at gate approval
• Test suite output at gate approval (pass/fail counts, exit code)
• Placeholder grep output at gate approval
• Two-stage wave review verdicts with file:line references

_If any items were noted as exceptions during gate approval, they are documented in the gate log._

---

Output

Phase 5 produces:

• Completion summary
• Updated spec status
• Verification steps
• Next steps recommendations
• Project learnings saved to memory (if applicable)

End of SDLC Pipeline

Implementer Subagent Prompt Template

Used in: --subagent mode only. One subagent dispatched per task within a wave.

---

Agent Prompt Template

You are implementing Task {T-XX}: {Task Title}

## Task Description

{FULL TEXT of task from tasks.md — paste it here, don't make subagent read the file}

## Context

{Scene-setting from spec.md and plan.md:
- Feature summary and purpose
- Architecture approach relevant to this task
- Where this task fits in the wave/dependency graph
- Dependencies on previous tasks (what they built, key patterns)
- Relevant patterns from plan.md (naming, file structure, conventions)}

## Verification Command (if available)

{From task's #### Verification section, if present}
Expected: {expected output}

## Before You Begin

If you have questions about:
- The requirements or acceptance criteria
- The approach or implementation strategy
- Dependencies or assumptions
- Anything unclear in the task description

**Ask them now.** Raise concerns before starting work. It is always OK
to pause and clarify. Don't guess or make assumptions about requirements.

## Your Job

Once you're clear on requirements:

1. **Implement** exactly what the task specifies
2. **Follow TDD where practical** — write test, watch it fail, implement, watch it pass
3. **Run verification command** if one is provided in the task
4. **Verify quality gates pass:**
   - Tests green (run test suite)
   - No placeholders (grep for TODO/FIXME/NotImplementedError)
   - Acceptance criteria have file:line evidence
5. **Commit your work** with a descriptive message
6. **Self-review** (see below)
7. **Report back** with status and confession

## Code Organization

- Follow the file structure defined in the plan
- Each file should have one clear responsibility
- If a file you're creating grows beyond the plan's intent, STOP and report
  as DONE_WITH_CONCERNS — don't restructure without guidance
- Follow established patterns in the codebase

## When You're in Over Your Head

It is always OK to stop and say "this is beyond my scope." Bad work is
worse than no work. You will not be penalized for escalating.

**STOP and escalate when:**
- The task requires architectural decisions with multiple valid approaches
- You need to understand code beyond what was provided
- You feel uncertain about whether your approach is correct
- The task involves restructuring in ways the plan didn't anticipate
- You've been reading file after file without making progress

**How to escalate:** Report back with status BLOCKED or NEEDS_CONTEXT.
Describe specifically what you're stuck on, what you've tried, and what
kind of help you need.

## Before Reporting Back: Self-Review

Review your work with fresh eyes:

**Completeness:** Did I implement everything in the spec? Missing requirements?
**Quality:** Is this my best work? Names clear? Code maintainable?
**Discipline:** Did I avoid overbuilding (YAGNI)? Only build what was requested?
**Testing:** Do tests verify behavior? Are they comprehensive?

If you find issues during self-review, fix them now before reporting.

## Report Format

- **Status:** DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED
- What you implemented
- What you tested and test results
- Files changed
- Self-review findings (if any)
- Verification command output (if applicable)

**Confession (REQUIRED):**
- **Shortcuts**: What was done expediently vs. ideally, or "None"
- **Assumptions**: Unverified beliefs the code depends on, or "None"
- **Uncertainties**: Areas where confidence is low, or "None"
- **Deviations**: Where implementation diverged from plan.md, or "None"

Use DONE_WITH_CONCERNS if you completed the work but have doubts.
Use BLOCKED if you cannot complete the task.
Use NEEDS_CONTEXT if you need information that wasn't provided.
Never silently produce work you're unsure about.

---

Status Handling (Orchestrator)

Never ignore an escalation or retry without changes.

Model Selection

Code Quality Review

Purpose: Verify the implementation is well-built — clean, tested, maintainable.

Only runs after Spec Compliance Review (Stage 1) passes.

When used:

• Default mode (wave-level): Step 4.1e Stage 2 — reviews all tasks in a wave
• Subagent mode (per-task): After spec compliance passes for a single task

---

Agent Prompt Template

You are reviewing code quality for an implementation that has already
passed spec compliance review. The code does what was requested —
your job is to verify it's well-built.

## Changes Under Review

{Git diff for the reviewed scope}

## Builder's Confessions

{Confession block — shortcuts, assumptions, uncertainties, deviations}

## Quality Gate Results

{Results from the 6 quality gates (tasks complete, file evidence,
tests green, no placeholders, acceptance criteria mapped, confessions recorded)}

## Focus Areas (Priority Order)

### 1. Confessed Weak Spots (HIGHEST PRIORITY)
Review confessed shortcuts and assumptions first. These are the areas
where the builder told you they cut corners or feel uncertain.
- Are confessed shortcuts actually acceptable?
- Do confessed assumptions hold under edge cases?
- Are confessed uncertainties risks that need mitigation?

### 2. Cross-Task Interactions
- How do changes in different files interact?
- Are there hidden coupling points between tasks?
- Do cross-file assumptions hold?
- Are shared resources (state, config, DB) handled consistently?

### 3. Code Organization
- Does each file have one clear responsibility?
- Are units decomposed for independent testing?
- Did the implementation create oversized files?
- Does the code follow existing patterns in the codebase?

### 4. Test Quality
- Do tests verify behavior (not mock internals)?
- Are edge cases covered?
- Is test naming clear and descriptive?
- Do tests fail for the right reasons when broken?

## Exclusions — Do NOT Flag

- Subjective style preferences (formatting, naming taste)
- Speculative "what if" issues without concrete risk
- Pre-existing code quality issues (focus on THIS change only)
- Items that linters/formatters would catch (quality gates handle those)
- Suggestions for future improvements unrelated to this change

## Return Format

**PASS** — Code quality is acceptable. Include brief strengths noted.

**ISSUES** — List each issue:
- Description of the problem
- File:line reference
- Severity: Critical (correctness risk) | Important (maintainability) | Minor (polish)
- Suggested fix (brief)

Exclude: style preferences and speculative concerns.

---

Retry Protocol

• If PASS: Proceed to Step 4.1f (Wave Checkpoint)
• If ISSUES: Builder fixes listed issues, quality reviewer re-reviews
• After 1 rejection across both stages combined: Approve with notes rather than rejecting again. Record notes in wave-context.md under ## Wave Review Result

Spec Compliance Review

Purpose: Verify the implementation built what was requested — nothing more, nothing less.

When used:

• Default mode (wave-level): Step 4.1e Stage 1 — reviews all tasks in a wave
• Subagent mode (per-task): After each implementer subagent completes — reviews one task

---

Agent Prompt Template

You are reviewing whether an implementation matches its specification.

## What Was Requested

{FR-XXX requirements relevant to this scope}
{Task descriptions and acceptance criteria from tasks.md}

## What Was Implemented

{Git diff for the reviewed scope}

## Confessions (Builder's Self-Assessment)

{Confession block from wave-context.md or implementer report}

## CRITICAL: Do Not Trust Reports

The builder's report may be incomplete, inaccurate, or optimistic.
You MUST verify everything independently by reading the actual code.

**DO NOT:**
- Take the builder's word for what they implemented
- Trust claims about completeness without file:line evidence
- Accept their interpretation of requirements over what the spec says
- Skim diffs — read them carefully

**DO:**
- Read the actual code changes (git diff)
- Compare implementation to requirements line by line
- Check for missing pieces that were claimed as implemented
- Look for extra features that were not requested

## Review Checklist

### 1. Missing Requirements
- Did they implement everything requested in the relevant FR-XXX items?
- Are there acceptance criteria without corresponding implementation?
- Did they claim something works but didn't actually implement it?
- Are there requirements they skipped or deferred without documenting?

### 2. Extra/Unneeded Work
- Did they build things not in the spec?
- Did they over-engineer or add unnecessary abstractions?
- Did they add "nice to haves" that weren't requested?
- YAGNI violations — features for hypothetical future use?

### 3. Acceptance Criteria Verification
For each acceptance criterion in the task:
- Find the file:line that satisfies it
- If you cannot find evidence, the criterion is NOT MET
- "The code probably does this" is not evidence — find the line

### 4. Confession Validation
- Do confessed deviations from plan explain any spec gaps?
- Are confessed shortcuts acceptable or do they create coverage holes?
- Were confessed assumptions validated by the implementation?

## Return Format

**PASS** — Spec compliant. All acceptance criteria have file:line evidence.
Include a brief summary of what was verified.

**ISSUES** — List each issue:
- What's missing or extra
- File:line references
- Which FR-XXX or acceptance criterion is affected
- Severity: BLOCKER (must fix) or CONCERN (note for quality review)

---

Retry Protocol

• If PASS: Proceed to Stage 2 (Code Quality Review)
• If ISSUES: Builder fixes listed issues, spec reviewer re-reviews
• After 1 rejection across both stages combined: Approve with notes. Record notes in wave-context.md under ## Wave Review Result

Subagent Mode — Per-Task Execution Protocol

Activates when: --subagent flag is set in the /core:develop command.

Default behavior (no flag): Wave-based execution remains unchanged. This document only applies when --subagent is active.

---

Overview

Instead of the orchestrator implementing all tasks in a wave, dispatch a fresh subagent per task. Each subagent gets isolated context and implements exactly one task.

Why subagents:

• Fresh context per task prevents context pollution across tasks
• Escalation — subagents can report BLOCKED/NEEDS_CONTEXT instead of silently producing bad work
• Per-task review — two-stage review after each task catches issues earlier
• Model flexibility — choose the right model tier per task complexity

---

Execution Flow (per task within a wave)

1. Prepare Task Context

Assemble the context package for the implementer subagent:

• Full task text from tasks.md (paste into prompt, don't make subagent read the file)
• Relevant FR-XXX requirements from spec.md
• Architecture decisions from plan.md relevant to this task
• Previous wave context (if Wave N > 1) from wave-{N-1}-context.md
• Files to modify (from task metadata)
• Verification command (from task's #### Verification section, if present)

2. Dispatch Implementer Subagent

Use the prompt template from reviews/implementer-prompt.md.

Model selection:

3. Handle Implementer Status

Rules:

• Never ignore an escalation or retry without changes
• Never re-dispatch with the same context that caused BLOCKED
• If 2 re-dispatches fail for the same task, escalate to user

4. Two-Stage Review (per task)

Same two-stage review as wave-level (Step 4.1e), but scoped to one task:

Stage 1: Spec Compliance — Read reviews/REVIEW-SPEC.md

• Scoped to this task's requirements and acceptance criteria only
• 1 retry bound (shared across both stages for this task)

Stage 2: Code Quality — Read reviews/REVIEW-QUALITY.md

• Only runs after Stage 1 passes
• Scoped to this task's changed files only
• 1 retry bound (shared across both stages for this task)

After 1 rejection across both stages: Approve with notes. Record notes alongside the task's confession.

5. Record Task Confession

Same fields as wave-level confession (Step 4.1d), recorded per task:

### T-{XX}: {Task Title}
- **Shortcuts**: [What was done expediently vs. ideally, or "None"]
- **Assumptions**: [Unverified beliefs the code depends on, or "None"]
- **Uncertainties**: [Areas where confidence is low, or "None"]
- **Deviations**: [Where implementation diverged from plan.md, or "None"]

Source: Confessions come from the implementer's report (required in the report format). Augment with any findings from the two-stage review.

6. Update Task Status

Mark task COMPLETED in tasks.md, record files changed.

---

Wave-Level Aggregation

After all tasks in a wave complete in subagent mode:

1. Skip Step 4.1e — wave-level two-stage review is unnecessary (already done per task) 2. Proceed to Step 4.1d — aggregate all task confessions into wave-{N}-context.md 3. Proceed to Step 4.1f — wave checkpoint with aggregated metrics:

• Tasks completed (count and IDs)
• Aggregate review verdicts (per-task results)
• Combined confession summary
• Files changed across all tasks

---

Combining with Other Flags

---

Backward Compatibility

• Default mode (no --subagent) is completely unchanged
• Wave-based execution and wave-level two-stage review remain the default
• Existing plans work with either mode — task structure is the same
• --subagent can be combined with any other flags

SDLC Develop Troubleshooting

Common issues and solutions when using the /core:develop command.

---

Configuration Issues

No .arkhe.yaml found

Symptom: First run prompts for configuration

Solution: Normal behavior - choose your preferences or accept defaults. Config will be saved.

Spec directory doesn't exist

Symptom: Error when saving spec files

Solution: The skill auto-creates the configured spec directory on first use. If you have a custom specs_dir in .arkhe.yaml, ensure the parent directory exists.

---

Mode Detection Issues

Resume mode not detecting existing plan

Symptom: /core:develop @path/to/spec/ starts fresh instead of resuming

Solution: Ensure path contains plan.md. Check exact path - it should point to the spec directory, not the plan file:

# Correct
/core:develop @arkhe/specs/001-feature/

# Incorrect
/core:develop @arkhe/specs/001-feature/plan.md

Plan-only mode ignored

Symptom: --plan-only flag doesn't stop after Phase 2

Solution: Ensure flag is after the feature description:

# Correct
/core:develop add feature --plan-only

# Incorrect
/core:develop --plan-only add feature

---

Phase Execution Issues

Phase 0 skipping existing analysis

Symptom: No REUSE/ENHANCE/CREATE classifications

Solution: Phase 0c is mandatory. If it's being skipped, ensure the gating step (0a) returned PROCEED. Check if code-explorer agent is available.

Architecture agents not running in parallel

Symptom: Only one architecture option presented

Solution: Verify:

• code-architect agent is available
• Sufficient context for multiple approaches
• No --auto mode (which may consolidate)

Validation not running with --validate

Symptom: No opus-level validation in Phase 4

Solution: --validate enables deep validation. Ensure flag is included:

/core:develop add feature --validate

---

Template Generation Issues

Templates not found

Symptom: Error when generating spec files

Solution: Templates should be in the templates/ directory relative to this skill. Verify plugin installation:

/plugin uninstall core@arkhe-claude-plugins
/plugin install core@arkhe-claude-plugins

Wrong NNN prefix generated

Symptom: Spec directory has unexpected number prefix

Solution: The skill uses scripts/next_spec_number.py to deterministically compute the next number. Debug manually:

python3 scripts/next_spec_number.py --specs-dir arkhe/specs

Check highest_existing in the output. If wrong, look for directories with non-standard naming in your specs directory.

---

Checkpoint Issues

Checkpoints not appearing

Symptom: No user prompts between phases

Solution: You're likely in --auto mode. Run without the flag for interactive checkpoints:

# Interactive (with checkpoints)
/core:develop add feature

# Autonomous (no checkpoints)
/core:develop add feature --auto

Checkpoint stuck

Symptom: Phase doesn't proceed after approval

Solution: Respond clearly with "yes", "proceed", or "continue". Ambiguous responses may trigger clarification.

---

Common Error Messages

---

Getting Help

If issues persist: 1. Check the EXAMPLES.md for correct usage patterns 2. Review SKILL.md for mode detection logic 3. Use /debug to analyze specific errors

Architecture Verification Workflow

Verifies implementation matches plan.md architecture and api-contract.md definitions.

Prerequisites

Required artifacts in spec directory:

• plan.md (REQUIRED) - Architecture design with key files, components, data flow
• api-contract.md (OPTIONAL) - API endpoint definitions

Verification Checks

Execute checks in priority order. For each check, collect evidence with file:line references.

Check 1: Key Files Exist (Confidence: 95%)

Source: plan.md → "Key Files" section

Method: 1. Parse key files list from plan.md 2. Glob for each expected file path 3. Record existence status

Evidence:

| File | Expected | Found | Status |
|------|----------|-------|--------|

Check 2: Component Structure (Confidence: 85%)

Source: plan.md → "Components" or "Architecture" section

Method: 1. Parse component names and expected locations 2. Glob for matching directory/file structures 3. Grep for component exports and class definitions

Evidence:

| Component | Expected Location | Found | Status |
|-----------|------------------|-------|--------|

Check 3: API Contract Accuracy (Confidence: 90%)

Source: api-contract.md (skip if not present)

Method: 1. Parse endpoint definitions (method, path, request/response shapes) 2. Grep for route definitions in implementation 3. Compare request/response types

Patterns to search:

• Express: router.(get|post|put|delete|patch)\s*\(['"]
• FastAPI: @(app|router)\.(get|post|put|delete|patch)\s*\(['"]
• Spring: @(Get|Post|Put|Delete|Patch)Mapping
• Controller files, route handlers

Evidence:

| Endpoint | Contract | Implementation | Status |
|----------|----------|----------------|--------|
| {method} {path} | {request} → {response} | {file:line} | {MATCH|MISMATCH|MISSING} |

Check 4: Pattern Consistency (Confidence: 75%)

Source: plan.md → "Patterns" or existing codebase patterns

Method: 1. Identify patterns mentioned in plan (naming conventions, file organization, etc.) 2. Grep for pattern usage in new code 3. Compare against existing implementations

Evidence:

| Pattern | Expected | Found | Status |
|---------|----------|-------|--------|

Check 5: UI-Contract Alignment (Confidence: 85%)

Source: api-contract.md ↔ Frontend type definitions

Method: 1. Parse response shapes from api-contract.md 2. Grep for corresponding TypeScript interfaces/types in frontend 3. Compare field names and types

Patterns to search:

• TypeScript: interface\s+\w+, type\s+\w+
• Frontend API calls, data fetching hooks

Evidence:

| Data Shape | Backend (contract) | Frontend (consumer) | Status |
|------------|-------------------|---------------------|--------|

Check 6: Property Naming Consistency (Confidence: 80%)

Source: Cross-layer analysis

Method: 1. Extract property names from api-contract.md 2. Grep for same properties in backend models, database schemas, frontend types 3. Flag inconsistencies (e.g., userId vs user_id vs UserId)

Evidence:

| Concept | Backend | API | Frontend | DB | Status |
|---------|---------|-----|----------|----|---------|

Check 7: Data Flow (Confidence: 75%)

Source: plan.md → "Data Flow" section

Method: 1. Parse expected data flow (e.g., UI → API → Service → Repository) 2. Trace import chains in implementation 3. Verify call graph matches expected flow

Evidence:

| Flow Step | Expected | Actual | Status |
|-----------|----------|--------|--------|

Agent Strategy

Confidence Thresholds

Output

Generate Architecture Alignment section of verification report:

• Summary score (weighted average of all checks)
• Per-check evidence tables
• Items flagged for manual review (confidence <75%)

Error Handling

• Missing plan.md: FAIL with "Required artifact missing: plan.md"
• Missing api-contract.md: SKIP contract-related checks, note in report
• Parse errors: Flag specific section, continue with other checks
• No key files section in plan.md: SKIP check 1, reduce overall confidence