Feature Development Orchestrator

Announce: "I'm using the /do skill to orchestrate feature development with lifecycle tracking."

Overview

This skill orchestrates feature development through a multi-phase state machine with:

•On-disk state stored outside the repo (never committed)
•Specialized subagents for research, planning, implementation, and validation
•Resumable execution from any interruption point
•Atomic commits via /commit skill
•Two interaction modes: Interactive (default) or Autonomous

Hard Rules

•Plan before code. No implementation until research and planning phases complete.
•Workspace isolation first. Create worktree and branch before any code changes (EXECUTE phase).
•Atomic commits only. Commit after every logical change, not batched.
•Hard stop on blockers. When encountering ambiguity or missing information, stop and report rather than guessing.
•State is sacred. Always update state files after significant actions. Never commit state files.

Interaction Modes

Interactive Mode (default):

•User reviews and approves outputs at each phase transition
•User can provide feedback, request changes, or adjust direction
•Best for: complex features, unfamiliar codebases, learning

Autonomous Mode (--auto flag):

•Orchestrator makes best decisions based on research
•Proceeds through all phases without interruption
•Reports summary only at completion or on blockers
•Best for: well-defined tasks, trusted patterns, speed

State Storage

State is stored in the current working directory's .plans/do/<run-id>/.

•Before EXECUTE phase: State lives in the source repo's .plans/
•During EXECUTE phase: State is copied to and maintained in the worktree's .plans/

CRITICAL: Once a worktree is created, all state file updates MUST go to the worktree's .plans/ directory, never back to the source repo. This keeps all working files together in the isolated workspace.

Each run creates:

code

<cwd>/.plans/do/<run-id>/
  FEATURE.md              # Canonical state (YAML frontmatter + markdown)
  RESEARCH.md             # Research phase outputs (codebase map, research brief)
  PLAN.md                 # Execution plan (milestones, tasks, validation strategy)
  REVIEW.md               # Plan review feedback
  VALIDATION.md           # Validation results and evidence

Critical: .plans/ files are NEVER committed to git. Add .plans/ to .gitignore.

Iteration Behavior

Before starting, determine intent from the user's query:

•Analyze the query: Does it reference a state file/run-id (resume) or provide a new feature description (fresh start)?
•If fresh start: Create new run, proceed through RESEARCH phase.
•If resuming: Parse state file, reconcile git state, continue from current phase.
•If iterating: User is providing feedback on existing work. Address the feedback directly within the current phase.

Feedback handling during phases:

•RESEARCH phase feedback: Adjust scope, investigate additional areas
•PLAN_DRAFT feedback: Modify milestones, tasks, or approach
•EXECUTE feedback: Modify code as requested, commit the change
•VALIDATE feedback: Add tests, fix issues, re-run validation

Step 1: Initialize State Directory

bash

REPO_ROOT=$(git rev-parse --show-toplevel)
STATE_ROOT="$REPO_ROOT/.plans/do"
mkdir -p "$STATE_ROOT"

# Ensure .plans/ is gitignored
if ! grep -q "^\.plans/$" "$REPO_ROOT/.gitignore" 2>/dev/null; then
  echo ".plans/" >> "$REPO_ROOT/.gitignore"
fi

Step 2: Discover Existing Runs

Search for active runs (not marked DONE):

bash

# List active runs; produces no output if no runs exist
find "$STATE_ROOT" -name "FEATURE.md" -exec grep -L "current_phase: DONE" {} \; 2>/dev/null || true

For each discovered run, parse the YAML frontmatter to extract:

•run_id
•current_phase (RESEARCH, PLAN_DRAFT, PLAN_REVIEW, EXECUTE, VALIDATE, DONE)
•phase_status (not_started, in_progress, blocked, in_review, complete)
•branch
•last_checkpoint

Step 3: Parse Interaction Mode

Check $ARGUMENTS for the --auto flag:

•If --auto present: set interaction_mode = "autonomous"
•Otherwise: set interaction_mode = "interactive" (default)

Remove the flag from arguments before further processing.

Step 4: Mode Selection

IMPORTANT: Never skip phases. When arguments are a feature description, you MUST start the full workflow (RESEARCH -> PLAN -> EXECUTE). Do not implement directly, regardless of perceived simplicity.

Classification rules — apply in this order:

•
State file reference — $ARGUMENTS contains FEATURE.md or is a path to an existing .plans/do/ state file (but NOT a URL starting with http:// or https://):
- •Verify file exists
- •Parse phase status and route to appropriate phase
- •Inherit interaction_mode from state file or use specified flag
•
Feature description, no active runs — $ARGUMENTS is a feature description (including arguments containing URLs) and no active runs exist:
- •new mode: Start fresh workflow
•
Feature description, active runs exist — $ARGUMENTS is a feature description and active runs exist:

code

AskUserQuestion(
  header: "Active runs found",
  question: "Found <N> active feature runs. What would you like to do?",
  options: [
    "Start new feature" -- Begin a fresh workflow for the new feature,
    "<run-id>: <feature-name> (phase: <phase>)" -- Resume this run
  ]
)

•
No arguments:
- •If active runs exist: list them and ask which to resume
- •If no active runs: prompt for feature description

Step 5: Dispatch by Mode

New Mode

Generate a run ID: <timestamp>-<slug> where slug is derived from feature description.

Create the run directory and initial state file at $STATE_ROOT/<run-id>/FEATURE.md:

yaml

---
schema_version: 1
run_id: <run-id>
repo_root: <REPO_ROOT>
branch: null
base_ref: null
current_phase: RESEARCH
phase_status: not_started
milestone_current: null
last_checkpoint: <ISO timestamp>
last_commit: null
interaction_mode: <interactive|autonomous>
---

Dispatch to orchestrator:

code

Task(
  subagent_type = "productivity:do-orchestrator",
  description = "Start feature: <short description>",
  prompt = "
Start a new feature development workflow.

<feature_request>
<the user's feature description>
</feature_request>

<state_path>
<path to FEATURE.md>
</state_path>

<repo_root>
<REPO_ROOT>
</repo_root>

<interaction_mode>
<interactive|autonomous>
</interaction_mode>

<instructions>
- Begin with RESEARCH phase
- You are the single writer of the state files - update them after every significant action
- Write phase artifacts to the current working directory's .plans/do/<run-id>/:
  - RESEARCH.md: codebase map and research brief after RESEARCH phase
  - PLAN.md: milestones, tasks, and validation strategy after PLAN_DRAFT phase
  - REVIEW.md: review feedback after PLAN_REVIEW phase
  - VALIDATION.md: validation results after VALIDATE phase
- Update FEATURE.md frontmatter and living sections (Progress Log, Decisions Made, etc.) continuously
- Once in a worktree, ALL state updates go to the worktree's .plans/ (never back to source repo)
- Coordinate subagents for each phase
- Never commit .plans/ files (they are gitignored)
- BEFORE EXECUTE phase: call /worktree first, then /branch (mandatory, no exceptions)
- Use /commit for atomic commits during EXECUTE (after every logical change)
- Use /pr to create pull request in DONE phase
- Route through: RESEARCH -> PLAN_DRAFT -> PLAN_REVIEW -> EXECUTE -> VALIDATE -> DONE

INTERACTION MODE RULES:
- If interactive: Present findings and ask for user approval at each phase transition
- If autonomous: Make best decisions based on research, proceed without asking
- Both modes: Always stop and ask if you encounter a blocker or ambiguity you cannot resolve
</instructions>
"
)

Resume Mode

Read the state file to determine current phase and status.

Run git reconciliation:

•Check if on correct branch
•Handle dirty working tree per uncommitted_policy in state

Dispatch to orchestrator with resume context:

code

Task(
  subagent_type = "productivity:do-orchestrator",
  description = "Resume feature: <run-id>",
  prompt = "
Resume an interrupted feature development workflow.

<state_path>
<path to FEATURE.md>
</state_path>

<state_content>
<full FEATURE.md content>
</state_content>

<instructions>
- Read FEATURE.md and phase artifacts (RESEARCH.md, PLAN.md, etc.) to understand context and progress
- Reconcile git state (branch, working tree)
- Continue from the current phase and task
- Update state files as you make progress
- Never commit .plans/ files (they are gitignored)
</instructions>
"
)

Status Mode

If user asks for status without wanting to resume:

code

Task(
  subagent_type = "productivity:do-orchestrator",
  description = "Status check: <run-id>",
  prompt = "
Report status of a feature development run without making changes.

<state_path>
<path to FEATURE.md>
</state_path>

<instructions>
- Read and parse the state file
- Report: current phase, progress percentage, last checkpoint, any blockers
- Do not modify state or code
</instructions>
"
)

Phase Flow

code

RESEARCH -> PLAN_DRAFT -> PLAN_REVIEW -> EXECUTE -> VALIDATE -> DONE
              ^                |             ^          |
              |                v             |          v
              +--- (changes requested) ------+-- (fix forward) --+

RESEARCH Phase

•Spawn do-explorer for local codebase mapping (modules, patterns, conventions)
•Spawn do-researcher for Confluence + external research (design docs, RFCs, APIs)
•Output: Context, Assumptions, Constraints, Risks, Open Questions
•Both sources are mandatory - do not skip Confluence search
•Interactive: Present research summary, ask user to confirm assumptions and scope
•Autonomous: Proceed with best interpretation, log assumptions in Decisions Made

PLAN_DRAFT Phase

•Spawn do-planner to create plan (references both codebase findings AND Confluence context)
•Output: Milestones, Task Breakdown, Validation Strategy
•Plan must embed relevant context inline (not just links)
•Interactive: Present plan, ask user to approve or request changes
•Autonomous: Proceed to review, let reviewer catch issues

PLAN_REVIEW Phase

•Spawn do-reviewer for critique
•Output: Review report, required changes
•May loop back to PLAN_DRAFT
•Interactive: Present review findings, ask user for final approval before execution
•Autonomous: Auto-approve if no critical issues, loop back for required changes only

EXECUTE Phase

MANDATORY before any code changes:

•Call /worktree to create isolated workspace
•Call /branch to create feature branch
•Update state file with branch name

Then execute tasks:

•Execute tasks with atomic commits via /commit after EVERY logical change
•Update Progress section continuously
•Commit frequency: after each function, fix, test, or refactor — not batched

VALIDATE Phase

•Spawn do-validator to run checks
•Output: Validation report, pass/fail decision
•May loop back to EXECUTE for fixes
•Interactive: Present validation results, ask user before creating PR
•Autonomous: Auto-proceed to DONE if validation passes

DONE Phase

•Write Outcomes & Retrospective
•Create PR via /pr skill (pushes branch, creates PR with description)
•Report PR URL to user
•Archive run state
•Both modes: Always report final PR URL to user

Error Handling

•State file not found: List discovered runs or prompt for new feature
•Git branch conflict: Report and offer resolution options
•Phase failure: Mark phase as blocked, record blocker, offer manual intervention
•Subagent failure: Log to agent-outputs, update state with failure context

State File Schema

Directory Structure

code

.plans/do/<run-id>/
  FEATURE.md              # Canonical state and living document
  RESEARCH.md             # Codebase map + research brief (written after RESEARCH)
  PLAN.md                 # Milestones, tasks, validation strategy (written after PLAN_DRAFT)
  REVIEW.md               # Review feedback (written after PLAN_REVIEW)
  VALIDATION.md           # Validation results with evidence (written after VALIDATE)

FEATURE.md (main state file)

markdown

---
schema_version: 1
run_id: 20250212-user-auth
repo_root: /path/to/repo
worktree_path: /path/to/worktrees/repo-user-auth  # set during EXECUTE setup
branch: feature/user-auth
base_ref: abc123
current_phase: EXECUTE
phase_status: in_progress
milestone_current: M-002
last_checkpoint: 2025-02-12T10:30:00Z
last_commit: def456
interaction_mode: interactive  # or "autonomous"
---

# <Feature Name>

<Brief description of what this feature does>

## Acceptance Criteria

<What success looks like - verifiable outcomes>

## Progress

- [x] (2025-02-12 10:00Z) RESEARCH phase complete
- [x] (2025-02-12 10:30Z) PLAN_DRAFT phase complete
- [x] (2025-02-12 11:00Z) PLAN_REVIEW phase complete - approved
- [x] (2025-02-12 11:15Z) T-001: Set up project structure (commit abc123)
- [ ] T-002: Implement core logic
- [ ] T-003: Add tests

## Surprises and Discoveries

<Unexpected findings during implementation>

## Decisions Made

<Decision log with rationale>

- Decision: <what was decided>
  Rationale: <why>
  Date: <timestamp>

## Open Questions

<Unresolved questions requiring input>

## Outcomes and Retrospective

<Final summary when complete - what worked, what didn't, lessons learned>

RESEARCH.md

markdown

# Research: <Feature Name>

## Problem Statement
- (Summarize the problem clearly - show deep understanding)

## Current Behavior
- (What happens today)
- (If a bug: include minimal repro and expected vs actual)

## Desired Behavior
- (What "done" means - verifiable outcomes)

## Codebase Map

### Entry Points
- `path/to/file:function` - Description

### Main Execution Call Path
- `caller` → `callee` → `next` (describe the flow)

### Key Types/Functions
- `path/to/file:Type` - Description
- `path/to/file:function` - Description

### Integration Points
- Where to add new functionality
- Existing patterns to follow

### Conventions
- Naming patterns, file organization, testing patterns

### Risk Areas
- Complex or fragile code requiring careful changes

## Findings (facts only)
- (Bullets; each includes `file:symbol` or `MCP:<tool> → <result>` or `websearch:<url> → <result>`)
- (Facts only - no assumptions here)

## Hypotheses (if needed)
- H1: <hypothesis> - <evidence supporting it>
- H2: <hypothesis> - <evidence supporting it>
- (Clearly marked as hypotheses, not facts)

## Solution Direction

### Approach
- (Strategic direction: what pattern/strategy, which components affected)
- (High-level only - NO pseudo-code or code snippets)
- (YES: module names, API/pattern names, data flow descriptions)

### Why This Approach
- (Brief rationale - what makes this the right choice)

### Alternatives Rejected
- (What other options were considered? Why not chosen?)

### Complexity Assessment
- **Level**: Low / Medium / High
- (1-2 sentences on what drives the complexity)

### Key Risks
- (What could go wrong? Areas needing extra attention)

## Research Brief

### Libraries/APIs
- Library name: key methods, usage patterns, gotchas

### Best Practices
- Pattern to follow with brief explanation

### Common Pitfalls
- What to avoid and why

### Internal References (Confluence)
- [Page](url) - Summary of what it covers

### External References
- [Source](url) - Summary of what it covers

## Open Questions
- (Questions that need answers before or during planning)
- (Mark as BLOCKING if it prevents planning)

PLAN.md

markdown

# Plan: <Feature Name>

## Research Reference
- **Source**: path to RESEARCH.md
- **Problem**: 1-2 sentence summary
- **Solution direction**: 1-2 sentence summary from research recommendation

## Scope

### In Scope
- (Bullet list of what this plan covers)

### Out of Scope
- (Bullet list of what is explicitly NOT part of this change)

## File Impact Map

| File | Change Type | Risk | Description |
|------|-------------|------|-------------|
| `path/to/file.ts` | New / Modify / Extend / Delete | Low / Medium / High | Brief description |

Change types:
- **New**: File created from scratch
- **Modify**: Existing file, changing behavior
- **Extend**: Existing file, adding capability without changing existing behavior
- **Delete**: Removing file or significant code block

## Milestones

### M-001: <Milestone Name>
**Scope**: What exists after this milestone
**Verification**: How to prove it works
**Dependencies**: What must be true before starting

### M-002: <Milestone Name>
...

## Task Breakdown

### Milestone M-001
- [ ] T-001 (M-001) Task description
  - Files: `path/to/file.ts`
  - Risk: Low | Medium | High
  - Logic flow: Pseudo-code or step-by-step description
  - Acceptance: What "done" looks like
- [ ] T-002 (M-001) Task description
  - Depends on: T-001
  - Risk: Medium
  - Acceptance: What "done" looks like

### Milestone M-002
- [ ] T-003 (M-002) ...

## Integration Points
- (List boundaries this change touches: APIs, file formats, inter-component contracts)
- (Flag any breaking changes or version considerations)

## Risk Guidelines

| Risk Level | When to Apply | Execution Approach |
|------------|---------------|-------------------|
| Low | Simple changes, additive, well-understood patterns | Execute normally |
| Medium | Multiple files, API interactions, state changes | Review code paths before committing |
| High | Security, data migrations, core logic changes | Think through ALL edge cases before writing code |

## Validation Strategy

### Existing Test Coverage
- (What existing tests already validate parts of this?)

### New Tests Required

| Test Name | Type | File | Description |
|-----------|------|------|-------------|
| test_name | Unit / Integration / E2E | path or "new file" | What it verifies |

### Test Infrastructure Changes
- [ ] None required
- [ ] Extending existing test framework
- [ ] Adding new test files to existing framework
- [ ] Significant test infrastructure changes (describe)

### Per-Milestone Validation
- M-001: Command to run, expected output
- M-002: Command to run, expected output

### Final Acceptance
- [ ] Criterion 1: How to verify
- [ ] Criterion 2: How to verify

## Assumptions
- (List assumptions made during planning that could be wrong)
- (These become verification points before/during implementation)

## Open Questions
- (Questions that must be answered before implementing specific tasks)
- (Flag which task is blocked by each question)

## Recovery and Idempotency

### Safe to Repeat
- Tasks that can run multiple times

### Requires Care
- Tasks with side effects

### Rollback Plan
- How to revert if needed