Orchestrating Feature Development

Symptoms this skill addresses:

• Manual orchestration of skills and agents
• Sequential execution when parallel is possible
• Missing security review in architecture
• No feedback loops before escalation
• Lost context between sessions

State Tracking (MANDATORY)

MUST use TodoWrite BEFORE starting any orchestration workflow.

Multi-phase orchestration involves coordinating multiple agents. Without external state tracking, context drift causes forgotten phases, repeated spawns, and missed verification steps.

Create TodoWrite items for each phase BEFORE spawning any agents.

Standard Phase Template

⛔ = Compaction Gate - BLOCKING checkpoint requiring compaction-gates.md protocol before next phase.

Work Types: BUGFIX, SMALL, MEDIUM, LARGE (determined in Phase 2: Triage)

Phase Skip Matrix:

Quick Reference

Configuration

This skill uses .claude/config/orchestration-limits.yaml:

No Unilateral Overrides: Agents MUST NOT override config values. To change limits, update the config file or get user approval via AskUserQuestion.

Core Orchestration Patterns

This skill includes all necessary orchestration patterns inline:

Phase-Specific References

• Phase 1: Setup - Worktree creation, output directory, MANIFEST.yaml
• Phase 2: Triage - Work type classification (BUGFIX/SMALL/MEDIUM/LARGE)
• Phase 3: Codebase Discovery - Explore agent patterns, technology detection
• Phase 4: Skill Discovery - Technology-to-skill mapping, manifest writing
• Phase 5: Complexity - Technical assessment, execution strategy
• Phase 6: Brainstorming - Design refinement with human-in-loop (LARGE only)
• Phase 7: Architecture Plan - Technical design AND task decomposition
• Phase 8: Implementation - Code development patterns
• Phase 9: Design Verification - Plan-to-implementation matching
• Phase 10: Domain Compliance - Feature-specific mandatory patterns
• Phase 11: Code Quality - Code review for maintainability
• Phase 12: Test Planning - Test strategy and plan creation
• Phase 13: Testing - Test implementation and execution
• Phase 14: Coverage Verification - Coverage threshold validation
• Phase 15: Test Quality - Assertion quality, no low-value tests
• Phase 16: Completion - Final verification, PR, cleanup

Compaction Gates

BLOCKING checkpoints at phase transitions where context accumulates:

Protocol: See compaction-gates.md for:

• 5-step compaction procedure
• "What to Compact / What to Keep" tables
• Feature-specific content lists
• Rationalization counters

Agent Matrix for Feature Development

See references/agent-matrix.md for complete agent selection guide with:

• Agent responsibilities by phase
• Mandatory skills per agent
• Selection rules and anti-patterns
• Sequential vs parallel execution patterns

Quick Reference by Feature Type:

Feature-Specific Domain Compliance (Phase 10)

Feature development has specific P0 requirements:

See Phase 10: Domain Compliance for full checklist.

Tight Feedback Loop (Phases 8-11-13)

Implementation→Review→Test cycle with automatic iteration when review or tests fail.

• Max iterations: Read from orchestration-limits.yaml
• Tracks iteration history in {OUTPUT_DIR}/feedback-scratchpad.md

Pattern: See tight-feedback-loop.md

Checkpoint Configuration

Human approval required at specific phases based on work type:

For large plans (>5 tasks), add intermediate checkpoints during implementation.

See checkpoint-configuration.md for feature-specific configuration.

Parallel Execution

When tasks are independent, spawn in a SINGLE message:

// Phase 7: Architecture - spawn leads in parallel
Task("frontend-lead", "Design frontend architecture...");
Task("security-lead", "Security assessment...");

// Phase 13: Testing - spawn testers in parallel
Task("frontend-tester", "Unit tests for components...");
Task("frontend-tester", "Integration tests for API hooks...");
Task("frontend-tester", "E2E tests for user flows...");

Do NOT spawn sequentially when tasks are independent.

File Scope Boundaries

When spawning parallel agents:

See file-scope-boundaries.md for conflict detection protocol.

Rationalization Prevention

MANDATORY at every phase transition:

Read(.claude/skill-library/development/orchestrating-feature-development/references/compaction-gate-counters.md)

This file contains counters for:

• "Phase Transition Momentum Bias" - completing phase N and immediately starting N+1 without gate check
• "Outputs Already Persisted" - confusing file creation with compaction protocol
• "Context Seems Fine" - subjective assessment of token usage
• "Resume Workflow" bypass

MANDATORY at gates:

Read(.claude/skill-library/development/orchestrating-feature-development/references/rationalization-table.md)

This file contains anti-rationalization counters for "Momentum Bias", "Context Seems Fine", and other compaction gate bypass patterns.

Phase Transition Protocol:

1. STOP after completing any phase
2. CHECK: Is this a compaction gate? (3→4, 8→9, 13→14)
3. READ: compaction-gate-counters.md
4. If at gate: Execute 5-step compaction protocol BEFORE any other action
5. ONLY THEN proceed to next phase </EXTREMELY-IMPORTANT>

See rationalization-table.md for feature-specific rationalizations. See compaction-gate-counters.md for phase transition counters.

Emergency Abort Protocol

See emergency-abort.md for abort triggers, cleanup options, and procedures.

Quick Triggers:

• User requests stop
• 3+ escalations in same phase
• Critical security finding
• Unrecoverable error
• Context window exhausted (>85% tokens)
• MAX_RETRIES exceeded on critical path

Flow: Stop work → Capture state → Present cleanup options → Execute cleanup → Report final state.

Feature Directory Structure

.worktrees/{feature-name}/
├── .feature-development/
│   ├── MANIFEST.yaml              # Feature metadata, status, metrics
│   ├── progress.md                # Session progress tracking
│   ├── skill-manifest.yaml        # Phase 4 output: technology-to-skill mapping
│   ├── discovery.md               # Phase 3 output: codebase patterns
│   ├── architecture.md            # Phase 7 output: technical design
│   ├── plan.md                    # Phase 7 output: implementation tasks
│   ├── feedback-scratchpad.md     # Iteration history for tight feedback loop
│   └── agents/                    # Agent output files
│       ├── frontend-lead.md
│       ├── frontend-developer.md
│       └── ...
└── [feature code]                 # Actual implementation

Exit Criteria

Feature development is complete when:

• ✅ All applicable phases marked "complete" in MANIFEST.yaml (based on work type)
• ✅ Discovery artifacts generated (discovery.md, skill-manifest.yaml)
• ✅ All reviewers returned verdict: APPROVED
• ✅ Test plan created and all tests implemented (quality_score >= 70)
• ✅ Final verification passed (build, lint, tests)
• ✅ Metrics tracked in MANIFEST.yaml (tokens, cost, iterations)
• ✅ Worktree cleaned up (merged and removed, OR kept per user request)
• ✅ User approves final result
• ✅ No rationalization phrases; all gate checklists passed; overrides documented

Integration

Called By

• /feature command - Primary entry point for users
• Parent orchestrators (multi-repo, epic) - Via workflow handoff protocol

Requires (invoke before or at start)

• using-git-worktrees (LIBRARY) - Phase 1
  • Purpose: Create isolated workspace for feature development
  • Read(".claude/skill-library/workflow/using-git-worktrees/SKILL.md")
• persisting-agent-outputs (CORE) - Phase 1
  • Purpose: Discover output directory, set up workspace
• discovering-codebases-for-planning (CORE) - Phase 3
  • Purpose: Parallel discovery with dynamic agent count

Calls (skill-invocation via Skill tool)

• brainstorming (CORE) - Phase 6
  • Purpose: Design refinement with human-in-loop
• writing-plans (CORE) - Phase 7
  • Purpose: Create detailed implementation plan
• finishing-a-development-branch (LIBRARY) - Phase 16
  • Purpose: Verify, PR options, cleanup
  • Read(".claude/skill-library/workflow/finishing-a-development-branch/SKILL.md")

Spawns (agent-dispatch via Task tool)

• {domain}-lead + security-lead - Phase 7
  • Key Mandatory Skills: adhering-to-dry, adhering-to-yagni
• {domain}-developer - Phase 8
  • Key Mandatory Skills: developing-with-tdd, verifying-before-completion
• {domain}-reviewer + {domain}-security - Phase 11
  • Key Mandatory Skills: adhering-to-dry
• test-lead - Phase 12, 15
• {domain}-tester ×3 - Phase 13
  • Key Mandatory Skills: developing-with-tdd

Pairs With (conditional)

• developing-with-subagents (CORE) - Plan has >3 independent tasks
  • Purpose: Fresh subagent per task + two-stage review
• dispatching-parallel-agents (CORE) - 3+ independent failures
  • Purpose: Parallel investigation of unrelated issues
• verifying-before-completion (CORE) - Phase 16 completion
  • Purpose: Final verification checklist
• debugging-systematically (CORE) - Review/test failures
  • Purpose: Systematic debugging when failures repeat

References

Phase Files

• [Phase 1-16 references listed above]

Supporting Documentation

• Agent Matrix - Agent selection by feature type
• Checkpoint Configuration - Human approval points
• Compaction Gates - BLOCKING context management
• Delegation Templates - Agent prompt templates
• Directory Structure - Feature workspace organization
• Emergency Abort - Safe workflow termination
• File Scope Boundaries - Parallel agent conflict prevention
• Progress Persistence - Cross-session resume
• Rationalization Table - Feature-specific rationalizations
• Tight Feedback Loop - Implementation→Review→Test cycles
• Troubleshooting - Common issues and solutions

Prompt Templates

• prompts/architect-prompt.md - Phase 7 leads
• prompts/developer-prompt.md - Phase 8 developers
• prompts/reviewer-prompt.md - Phase 11 reviewers
• prompts/tester-prompt.md - Phase 13 testers

External Sources

Related Skills

• orchestrating-capability-development - Similar pattern for security capabilities
• orchestrating-integration-development - Similar pattern for third-party integrations
• persisting-progress-across-sessions - Cross-session persistence for long-running features
• developing-with-subagents - Same-session subagent execution with code review