Executing Feature Plans

Plan Locations

Plan Structure

Plans typically contain:

• Executive Summary — what and why
• Phases — ordered implementation steps
• Per-phase details — files to modify, test cases, acceptance criteria
• Dependencies — what must exist before a phase can start
• Documentation Updates — what docs to update when complete

Execution Workflow

1. Read the full plan to understand scope and dependencies
2. Identify which phases/tasks are ready (dependencies met)
3. For each task: a. Read the specific section carefully b. Note the listed files, test cases, and acceptance criteria c. Implement changes d. Run specified tests e. Verify acceptance criteria
4. After completing a phase, run the full test suite
5. Commit with conventional commit message (no plan phase references in title)

Task Decomposition

When breaking a plan into tasks:

• One task per phase subsection (e.g., "1a", "1b", "2a")
• Respect phase ordering — later phases may depend on earlier ones
• Identify parallel tasks — items marked "independent" or "can be implemented in parallel"
• Check for shared infrastructure — multiple tasks may need a common utility first

Complexity Assessment

A task is straightforward (→ @engineer agent) when:

• The plan specifies exact file paths and changes
• Changes are isolated to 1-3 files
• Test cases are provided in the plan
• It follows an established pattern in the codebase

A task is complex (→ @architect agent) when:

• The plan says "investigate", "determine", or "design"
• Changes span 4+ files across multiple modules
• New patterns or shared infrastructure are needed
• Integration with unfamiliar subsystems is required
• The plan has gaps that require codebase research to fill

Using /fleet for Parallel Execution

The /fleet command automatically decomposes work into subtasks and dispatches to custom agents based on their descriptions. When a plan has independent tasks:

1. Switch to plan mode (Shift+Tab) and create the plan
2. Use /fleet to execute — it will route simple tasks to engineer and complex tasks to architect based on the agent descriptions
3. You can also force routing: @engineer fix the dd_version bug or @architect design the new pipeline

Scoring Dimensions

Rate each task 0-3 on each dimension:

Total ≤ 5 → @engineer (Sonnet 4.6 — fast, precise) Total ≥ 6 → @architect (Opus 4.6 — researches then builds)

Plan Lifecycle

plans/features/<name>.md          → Active (implement from here)
plans/features/pending/<name>.md  → Reference material (gaps documented)
DELETE the plan file              → Fully implemented (code is the doc)

Documentation Checklist

Every completed plan must update affected documentation:

Common Plan Types in This Project

• Bug fix plans — Phase 1 items, specific file + line references, test cases provided
• Pipeline plans — Multi-phase, schema → code → tests → docs progression
• Server improvement plans — Tool-level changes with A/B test criteria
• Schema evolution plans — LinkML YAML → build-models → migrate data → update code