Feature Development Workflow

Design in plan mode, implement with task tracking, deliver technical documentation.

Defers to project instructions for testing policy, quality gates, and approval thresholds. Defaults below apply when the project doesn't specify.

Complexity Classification

Assess automatically — do not ask user. Use highest matching criterion.

Feature Complexity (determines Phase 1 depth):

Task Complexity (determines Phase 3 depth):

Pre-Workflow

Before EnterPlanMode: search existing specs, note spec location convention, check test infrastructure, check project quality gates, classify complexity.

Phase 1: Design (Plan Mode)

Skip for Trivial complexity. Call EnterPlanMode, write design in plan file.

Design structure:

• •Part A (What): Context, Decision, Consequences, Alternatives
• •Part B (How): Scope, API/interface, Architecture, Data model, Error handling, Dependencies, Testing

Review process:

1. •Launch general-purpose subagent (see Subagent Strategy for model) to critique
2. •Iterate up to cycle limit
3. •Codex review (Medium+ only): single pass, no iteration
4. •ExitPlanMode for user approval. If user rejects, revise design and repeat from step 1.

Codex unavailable or fails: Ask user whether to retry once or proceed without.

Phase 2: Task Creation

1. •Documentation task: "Write documentation for [feature]" (new) or "Update documentation for [feature]" (extending/modifying existing). If feature partially overlaps an existing doc, update the existing one.
2. •Implementation tasks: Atomic units resulting in working code, ordered by dependencies
3. •Set dependencies: Documentation task blocked by all implementation tasks

Documentation skip evaluation: If all true — <50 lines, 1-2 files, no new APIs/architecture — mark documentation task description as "will skip". Phase 4 checks this flag rather than re-evaluating.

Phase 3: Implementation

For each task: mark in_progress → write tests (per project testing policy) → implement → refactor while green → run project quality gates → code review (per task complexity) → commit → mark completed.

Testing: Follow project testing policy. Default if project doesn't specify: TDD for business logic, algorithms, APIs; skip tests for config, docs, styling, trivial fixes.

Project quality gates: Run whatever the project defines (e.g., linting, type checking, compilation, test suite). Fix failures before proceeding.

Code review:

• •Trivial: Skip
• •Simple: 1 cycle with pr-review-toolkit:code-reviewer (sonnet) → self-verify → commit
• •Complex: Up to 2 cycles; CRITICAL issues (security, logic, broken functionality) must be fixed; ADVISORY issues (style, minor optimizations) are optional

At cycle limit with unresolved criticals: AskUserQuestion with options.

Test failures: Fix before committing.

Fundamental flaws discovered mid-implementation: Stash current work, mark task pending. If completed tasks are affected by the flaw, note which tasks need revisiting. AskUserQuestion with options: (a) revert completed tasks and redesign, (b) fix forward from current state, (c) pause and discuss.

Phase 4: Documentation

Execute documentation task created in Phase 2.

Skip if documentation task was marked "will skip" in Phase 2. Mark completed with skip reason.

Write documentation: Launch general-purpose subagent (sonnet) with feature name, key decisions, files implemented, instruction to match existing format. Location: follow existing pattern or docs/specs/.

Minimum sections: Header (name, date created, date updated, status), Overview. Add API/Interface if public interface exists. Set dates to current date on creation; update "date updated" on modifications.

Updates: Modify in place, add to Change History. Major architectural changes: new doc, mark old as superseded.

Commit: docs(spec): add specification for [feature-name]

Subagent Strategy

Never delegate: MCP calls.

Agent Teams (Complex Only)

Use when: Complex classification AND 3+ independent modules with clear file boundaries. Teams use 3-5x tokens — only use when parallelism provides clear benefit.

How teams work: Lead spawns teammates, each with own context. Teammates message each other directly and coordinate via shared task list. Lead synthesizes results.

Preflight — Before spawning teammates:

Phase 1 (Design review):

1. •Explore feature requirements and existing codebase structure
2. •Identify key architectural areas: data model, API surface, error handling, testing, dependencies
3. •Map specific file sets to each review perspective
4. •Spawn teammates with explicit scope: "Review data model in [files X,Y,Z]", "Review API contracts in [files A,B,C]", etc.

Phase 3 (Parallel implementation):

1. •Analyze Phase 2 tasks and identify file boundaries
2. •Map tasks to distinct file sets with minimal overlap
3. •Identify shared interfaces/contracts between boundaries
4. •Spawn teammates with explicit ownership: "Own [files X,Y], read-only [file Z for context], coordinate on [shared interface in file W]"

Result: No duplicate exploration, clear boundaries, fewer conflicts.

Phase 1 alternative — Design review team: Spawn teammates with distinct perspectives (architecture, API/interface, devil's advocate). Teammates debate and challenge each other's findings. Lead synthesizes. One team iteration replaces 2-3 sequential subagent cycles.

Phase 3 alternative — Parallel implementation: When tasks map to independent file sets (e.g., frontend/backend/tests), spawn implementation team. Each teammate owns specific files — no overlap. Use delegate mode (Shift+Tab) to restrict lead to coordination only. Lead coordinates merging and resolves cross-cutting concerns.

Conflict resolution: If teammates produce conflicting approaches or interface mismatches: (1) lead identifies the conflict, (2) lead decides resolution based on the approved design, (3) affected teammate revises. If the conflict reveals a design gap, pause implementation and escalate to user.

When NOT to use: Same-file edits, sequential dependencies, Simple/Medium complexity.

Quality Gates

• •Phase 1 → 2: No critical design issues, Codex complete (or skipped), user approved
• •Phase 2 → 3: All tasks created, documentation task has correct dependencies
• •Phase 3 → 4: All implementation tasks completed, project quality gates pass
• •Phase 4 done: Documentation accurate (or skip documented), all tasks completed

Usage

/spec add user authentication with OAuth2
/spec update the authentication module to support MFA