Implementation Planner

Implementation Planner

This skill generates comprehensive implementation plans with milestones, tasks, and best practices enforcement.

Prerequisites

• Completed business-requirements.yaml
• Completed technical-requirements.yaml
• Recommended: style-anchors/index.yaml from style-anchors-collection skill

Planning Process

Phase 0: Ordering Strategy Selection

Before analyzing requirements or generating milestones, ask the user which ordering strategy they want to use. Present this prompt verbatim:

---

Before I generate your implementation plan, I need to understand how you want milestones ordered. Choose a strategy:

1. Multi-PR / Trunk-Based — Each milestone is independently PR-able and merged to develop/main continuously. Milestones must each be shippable on their own. Best for teams using trunk-based development. 2. Single Feature Branch — All milestones live on one long-lived branch with a single PR at the end. Ordering is purely by technical dependency. Best for isolated features that must not touch main until complete. 3. Value-First (Demo-Driven) — Milestones reordered to surface user-visible features as early as possible, even at the cost of deferring some infrastructure. Best for projects needing early stakeholder demos or feedback. 4. Risk-First — Highest-uncertainty or most technically unknown milestones come first to surface blockers early. Best for projects with significant unknowns. 5. Vertical Slice / Walking Skeleton — First milestone delivers a thin end-to-end slice spanning all architectural layers. Subsequent milestones flesh out each area. Best for validating architecture early. 6. Foundation-First (Sequential) — Infrastructure and tooling first, then features, then polish. Strict sequential ordering. Best for greenfield builds with clear requirements.

Or say "recommend one" and I'll choose based on your requirements.

---

Record the user's selection as ordering_strategy. If the user says "recommend one", analyze the requirements and select the most appropriate strategy, explaining your reasoning. Apply the corresponding ordering rules throughout Phase 2 (Milestone Identification).

Ordering rules per strategy:

• Multi-PR / Trunk-Based: Each milestone must have a "shippable" success criterion and must not depend on any other in-progress (unmerged) milestone. Milestones are sequenced so each can be independently reviewed and merged.
• Single Feature Branch: Order purely by technical dependency. No shippability constraint per milestone.
• Value-First: Sort milestones by user-facing impact descending. Bundle required foundation work into the first milestone as a prerequisite setup block.
• Risk-First: Sort milestones by uncertainty/risk score descending. High-risk milestones are m0 or m1; de-risk early.
• Vertical Slice: First milestone spans all architectural layers for one thin feature (e.g., one API endpoint + UI + persistence). Remaining milestones group by feature area.
• Foundation-First: Current default ordering. Infrastructure → core features → advanced features → polish/release.

Phase 0.5: Target Audience Selection

After the user selects the ordering strategy, ask which audience the plan is being created for:

---

Who is the primary audience for this implementation plan?

1. AI Agent — Full implementation details with step-by-step instructions, code examples, and explicit constraints. Ideal for Claude Code or other AI-driven development workflows.

2. Human Developers — High-level task descriptions with objectives, style anchor references, and success criteria. Developers determine their own implementation approach. Best for experienced teams who need planning structure without prescriptive steps.

3. Hybrid — Moderate detail level. Includes key implementation guidance and pattern references but assumes developer autonomy for routine decisions. Best for mixed teams, pair programming with AI, or as handoff documentation.

---

Record the user's selection as target_audience: "ai" | "human" | "hybrid".

Default: If the user is unsure, recommend "ai" for autonomous development sessions or "human" for experienced developer teams.

Input Analysis

1. Load Requirements

• Parse business requirements for functional scope
• Parse technical requirements for architectural decisions
• Load style anchors from {base_directory}/artifacts/style-anchors/index.yaml (if exists)
• Identify dependencies and constraints

2. Identify Milestones

• Group related features into logical milestones
• Apply the ordering rules for the chosen ordering_strategy when sequencing milestones and setting dependencies
• Establish dependency order
• Define milestone deliverables

3. Generate Tasks

• Break down milestones into atomic tasks
• Apply task sizing rules (30m - 2.5h)
• Define task dependencies
• Select relevant style anchors from index.yaml based on task type and file patterns
• Embed style anchor references in task instructions
• Add final code review task for each milestone

4. Apply Best Practices

• TDD requirements
• Style anchor references
• Quality constraints
• Drift prevention rules
• Comprehensive code reviews

Best Practices (Embedded)

Core Principles

Layered Verification

Models optimize locally; enforce global constraints with layered verification (prompt → IDE → commit → CI → runtime).

Style Anchors

• Always include 2-3 exemplary files as templates
• Reference exact paths and line numbers
• Prefer concrete repository examples (code + tests + README)
• Enforce anchors early to prevent architectural drift

Task Sizing

• Split work into 30m–2.5h atomic tasks (30–150 minutes optimal)
• Limit scope to specific files
• Commit after each small task
• Revert immediately on drift
• If a task is shorter than 30m, either increase estimate or split it with rationale

Affirmative Instructions

• State permitted actions explicitly
• Avoid negative framing
• Use "ONLY use X, Y, Z" instead of "Don't use A, B, C"

Tiered Rules

• Global: User preferences (format, language, length)
• Project: Persistent rules in CLAUDE.md or .cursor/rules/
• Context-aware: Auto-attached rules per directory or file pattern

Quality Constraints

TDD as Anchor

• Require TDD checklist before implementation
• Tests → minimal code → more tests → refactor
• When tests fail, return failing output with instruction: "Revise implementation to pass this test while keeping all previously passing tests. Do not modify the test. Do not add dependencies."

Drift Handling

• Stop and revert immediately on unexpected dependencies or unfamiliar patterns
• Do not fix mid-stream
• Document learnings and update persistent rules after each session

Prompt Positioning

• Put critical specs, style anchors, and hard rules at the beginning
• Reiterate them at the end of prompts
• Avoid burying requirements in the middle

External Data Validation

• Never use type assertions on external data
• Validate all external inputs with proper error handling
• Use schema validation instead of runtime assertions

Output Formats

Milestones Structure

Generate milestones.yaml with version, project metadata, meta section (ordering strategy, target audience), and a milestones array. The meta section includes ordering_strategy, ordering_rationale, and target_audience (ai/human/hybrid). Each milestone has: id (m0, m1...), name, description, dependencies, estimated_duration, tasks_file, and success_criteria. Optional fields include acceptance_criteria (functional, non_functional, testing, documentation) and exit_checklist.

See [references/milestones-spec.md](references/milestones-spec.md) for the complete document specification with all fields, ordering strategies, and optional fields.

See [references/milestones-example.yaml](references/milestones-example.yaml) for a full example.

Note on Optional Fields:

• success_criteria (required): High-level planning acceptance criteria
• acceptance_criteria (optional): Detailed delivery criteria with requirement tracing, testing requirements, and documentation expectations. Use when rigorous milestone sign-off is needed.
• exit_checklist (optional): Binary go/no-go checklist for code review. Use when formal gate-driven process is required.

Most projects use only success_criteria. Add detailed acceptance criteria when:

• Project requires audit-ready requirement traceability
• Multiple stakeholders need clear sign-off criteria
• QA team needs explicit testing requirements per milestone
• Code review process requires detailed checklists

To add detailed criteria after generation: Run /definition-of-done to enhance milestones.yaml with acceptance_criteria and exit_checklist fields derived from your requirements.

Tasks Structure

Generate milestone-m*.tasks.yaml with task_summaries, style anchors, global constraints, quality gates, and a tasks array.

Required sections:

• task_summaries (map): Task ID to 1-2 sentence plain English summary. Placed at the top for scannable overview. Each summary should be 20-300 characters, focus on what/why not how, using active voice. Example: m1-001: "Creates core User model with validation rules for all user operations."
• global_constraints: Allowed patterns, forbidden patterns, TDD requirements, max task duration, commit strategy
• quality_gates: Pre-task, pre-commit, task-completion, milestone-completion, pre-push stages
• tasks: Array of task objects

Each task has: id (mN-NNN format), name, description, estimate_minutes (30-150), type (code/test/docs/config), dependencies, files (create/modify/touch_only), style_anchor_refs, and detailed instructions.

See [references/milestone-tasks-spec.md](references/milestone-tasks-spec.md) for the complete document specification with task structure, quality gates, and TDD checklists.

See [references/milestone-tasks-example.yaml](references/milestone-tasks-example.yaml) for a full example.

Task Sizing Guidelines

Optimal Task Duration

• Minimum: 30 minutes
• If task is shorter, document rationale
• Consider merging with related tasks
• Optimal: 30-150 minutes
• Atomic, well-scoped changes
• Can be completed in one session
• Clear success criteria
• Maximum: 150 minutes (2.5 hours)
• If task is longer, split into smaller tasks
• Identify natural breakpoints
• Create dependencies between subtasks

Task Sizing Examples

Too Small (< 30m)

- id: m1-001
  name: Add export statement
  estimate_minutes: 10
  rationale: "Simple addition but critical for module system"

Optimal (30-150m)

- id: m1-002
  name: Implement user authentication service
  estimate_minutes: 90
  dependencies: [m1-001]

Too Large (> 150m) - SPLIT

# BEFORE (too large):
- id: m1-003
  name: Build complete API layer
  estimate_minutes: 300

# AFTER (properly split):
- id: m1-003
  name: Define API interface and types
  estimate_minutes: 60

- id: m1-004
  name: Implement API routes
  estimate_minutes: 90
  dependencies: [m1-003]

- id: m1-005
  name: Add API middleware and error handling
  estimate_minutes: 60
  dependencies: [m1-004]

Task Instruction Detail Levels

Task instructions are generated at different detail levels based on the target audience selected in Phase 0.5:

AI Agent Audience (Full Detail)

Structure:

• Objective: Clear statement of what to build
• Style Anchors: Links to pattern files with line numbers
• Reference Files: Specific examples from codebase
• Implementation Steps: Numbered, prescriptive steps (1, 2, 3...)
• Constraints: Explicit "ONLY use" and "NEVER use" statements
• TDD Checklist: Step-by-step test-first requirements
• Validation: Exact commands with expected outputs
• Drift Policy: When to stop and revert

Example:

instructions: |
  **Objective:**
  Define Project and Milestone domain models using Model.Class.

  **Style Anchors:**
  Follow these established patterns:
  - See `artifacts/style-anchors/SA-002.md` — Model.Class with makeRepository
  - See `artifacts/style-anchors/SA-006.md` — Effect Schema domain types

  Reference files:
  - `~/Sites/ai/effect/packages/sql/src/Model.ts:82-157` — Model.Class definition
  - `~/Sites/ai/EffectPatterns/packages/pipeline-state/src/schemas.ts:1-234` — domain patterns

  **Implementation Steps:**
  1. Create `packages/shared/src/schemas/project.ts`:
     - PipelineStatus: Schema.Literal union of all pipeline stages (intake through archived)
     - Priority: Schema.Literal("low", "medium", "high", "critical")
     - Project model using Model.Class with fields:
       id (Model.Generated), slug, name, description, pipelineStatus,
       assignedPeople (Model.JsonFromString array), tags (Model.JsonFromString array),
       priority, createdAt (DateTimeInsert), updatedAt (DateTimeUpdate)
  2. Create `packages/shared/src/schemas/milestone.ts`:
     - MilestoneStatus: Schema.Literal("pending", "in-progress", "blocked", "complete")
     - Milestone model using Model.Class with fields:
       id, projectId, name, description, status, orderIndex, estimatedDays,
       acceptanceCriteria, createdAt, updatedAt
  3. Export all types and schemas from each file
  4. Update schemas/index.ts barrel export

  **Constraints:**
  - ONLY use: Model.Class, Schema.Literal, Schema.Struct
  - Follow **SA-002** for Model.Class structure with variant schemas (insert, update, select)
  - Follow **SA-006** for Schema.Literal enum patterns
  - NEVER use: TypeScript enum keyword or plain interfaces
  - NEVER use: type assertions (as) on external data
  - Include proper JSDoc comments for all exported types

  **TDD Checklist:**
  Before writing implementation:
  - [ ] Write failing test for Project.insert.make() constructor
  - [ ] Write failing test for Milestone.insert.make() constructor
  - [ ] Write failing test for Schema.decodeUnknown validation (valid cases)
  - [ ] Write failing test for Schema.decodeUnknown rejection (invalid cases)

  After implementation:
  - [ ] All tests pass
  - [ ] TypeScript inference works without explicit types
  - [ ] Variant schemas (insert, update, select) generate correctly

  **Validation:**

pnpm test packages/shared/src/schemas/project.test.ts pnpm test packages/shared/src/schemas/milestone.test.ts pnpm run typecheck pnpm run lint

  Expected: All tests pass, no type errors, no lint errors

  **Drift Policy:**
  STOP immediately if:
  - Implementation requires dependencies not listed in constraints
  - Tests fail and you consider modifying the test
  - More than 3 unexpected files need changes
  - Type errors cannot be resolved within listed files

Human Developer Audience (High-Level)

Structure:

• Objective: Clear statement of what to build with key requirements
• Style Anchors: Links to pattern files for reference
• Key Requirements: Bullet list of essential features/fields
• Constraints: Technology choices and architectural patterns only
• Success Criteria: Measurable outcomes without prescribing approach

Example:

instructions: |
  **Objective:**
  Define Project and Milestone domain models using Model.Class with insert, update,
  and select variants. Include pipeline status enum, priority levels, and proper
  field constraints.

  **Style Anchors:**
  - See `artifacts/style-anchors/SA-002.md` — Model.Class with makeRepository pattern
  - See `artifacts/style-anchors/SA-006.md` — Effect Schema domain types

  **Key Requirements:**

  *Project Model:*
  - Fields: id, slug, name, description, pipelineStatus, assignedPeople (JSON array),
    tags (JSON array), priority, timestamps
  - PipelineStatus enum: intake → analysis → planning → development → review → qa →
    deploy → complete → archived
  - Priority: low, medium, high, critical
  - Use Model.Generated for id, Model.JsonFromString for JSON arrays

  *Milestone Model:*
  - Fields: id, projectId, name, description, status, orderIndex, estimatedDays,
    acceptanceCriteria, timestamps
  - MilestoneStatus: pending, in-progress, blocked, complete

  **Constraints:**
  - Use Model.Class, Schema.Literal, Schema.Struct only
  - Follow SA-002 for variant schemas (insert, update, select)
  - No TypeScript enums or plain interfaces
  - All fields must support runtime validation via Effect Schema

  **Success Criteria:**
  - Models compile with full type inference
  - insert.make(), update.make() constructors available
  - Schema.decodeUnknown validates correctly for valid and invalid inputs
  - Tests pass, no type errors, no lint errors

Hybrid Audience (Moderate Detail)

Structure:

• Objective: Clear statement of what to build
• Style Anchors: Links to pattern files
• Implementation Approach: High-level approach with key decision points
• Constraints: Technology and pattern requirements
• Validation: Commands to verify success

Example:

instructions: |
  **Objective:**
  Define Project and Milestone domain models using Model.Class.

  **Style Anchors:**
  - See `artifacts/style-anchors/SA-002.md` — Model.Class pattern
  - See `artifacts/style-anchors/SA-006.md` — Schema.Literal patterns

  **Implementation Approach:**
  1. Create project.ts:
     - Define PipelineStatus as Schema.Literal union covering all stages
     - Define Priority as Schema.Literal("low", "medium", "high", "critical")
     - Define Project using Model.Class with: id (Generated), slug, name, description,
       pipelineStatus, assignedPeople (JsonFromString), tags (JsonFromString),
       priority, timestamps

  2. Create milestone.ts:
     - Define MilestoneStatus as Schema.Literal union
     - Define Milestone using Model.Class with: id, projectId, name, description,
       status, orderIndex, estimatedDays, acceptanceCriteria, timestamps

  3. Update schemas/index.ts to export both schemas

  **Constraints:**
  - Use Model.Class for entities, Schema.Literal for enums
  - Follow SA-002 variant schema pattern (insert, update, select)
  - No TypeScript enum keyword
  - Include JSDoc for exported types

  **Validation:**
  Run tests and typecheck to verify:
  - Model constructors (insert.make, update.make) work correctly
  - Schema.decodeUnknown validates and rejects appropriately
  - Full type inference without explicit type annotations

Implementation Logic

When generating tasks, determine instruction detail level based on target_audience:

• AI audience: Include all sections with maximum detail (steps, TDD, drift policy, explicit validation)
• Human audience: Include only objective, style anchors, key requirements, constraints, and success criteria
• Hybrid audience: Include objective, style anchors, implementation approach (high-level steps), constraints, and validation commands

The same task structure and metadata (id, name, description, estimate, type, dependencies, files, style_anchor_refs) are used for all audiences. Only the instructions field content varies based on detail level.

Code Review Task Requirement

Final Milestone Task

IMPORTANT: Every milestone MUST include a final code review task as its last task. This task ensures quality control and alignment with style anchors before moving to the next milestone.

Code Review Task Template

- id: [milestone]-[last-number]
  name: Comprehensive code review for [milestone-name]
  description: |
    Conduct a thorough code review of all work completed in this milestone.
    Review against style anchors, architectural decisions, and best practices.
    Document findings and create actionable recommendations.
  estimate_minutes: 60
  type: code-review
  dependencies: [all other tasks in this milestone]
  files:
    create:
      - code-reviews/[yyyy-mm-dd]-{n}-code-review.yaml
    modify: []
    touch_only: [all files created/modified in this milestone]
  instructions: |
    **Objective:**
    Review all code, tests, and documentation created or modified during this milestone
    for quality, consistency, and alignment with project standards.

    **Review Checklist:**
    1. **Style Anchor Compliance:**
       - [ ] Code follows patterns defined in style anchors
       - [ ] Naming conventions are consistent
       - [ ] File structure matches established patterns
       - [ ] Import organization follows standards

    2. **Code Quality:**
       - [ ] No code duplication or unnecessary complexity
       - [ ] Clear, meaningful variable and function names
       - [ ] Appropriate use of types (no any, proper generics)
       - [ ] Error handling is comprehensive and consistent
       - [ ] No magic numbers or hardcoded values

    3. **Testing:**
       - [ ] All new code has corresponding tests
       - [ ] Tests follow TDD patterns from style anchors
       - [ ] Edge cases are covered
       - [ ] Test names are descriptive

    4. **Architecture:**
       - [ ] Follows technical requirements decisions
       - [ ] Service patterns are consistent
       - [ ] Dependencies are properly injected
       - [ ] No circular dependencies

    5. **Documentation:**
       - [ ] JSDoc comments for public APIs
       - [ ] Complex logic is explained
       - [ ] README updated if needed
       - [ ] Examples are accurate

    **Review Process:**
    1. Review each file modified in this milestone
    2. Compare against referenced style anchors
    3. Run all quality gates (lint, typecheck, tests)
    4. Document problems with specific file:line references
    5. Provide recommended solutions with code examples
    6. Create code-reviews/[yyyy-mm-dd]-{n}-code-review.yaml

    **Output Format:**

milestone: [milestone-id] milestone_name: [milestone-name] review_date: [yyyy-mm-dd] reviewer: claude-code

summary: files_reviewed: [count] issues_found: [count] critical_issues: [count] overall_quality: [excellent|good|fair|needs-improvement]

style_anchor_compliance:

• anchor: [path/to/anchor:lines]

status: [compliant|partial|non-compliant] notes: | [Specific observations]

issues:

• severity: [critical|major|minor]

category: [style|architecture|testing|documentation|security] file: [path:line] description: | [Clear description of the problem] recommendation: | [Specific solution with code example if applicable] related_anchor: [path/to/anchor:lines]

• severity: major

category: testing file: src/example.ts:45 description: | Missing error case test for invalid input scenario recommendation: | Add test case:

          it.effect("should reject invalid input", () =>
            Effect.gen(function* () {
              const result = yield* service.process({ invalid: true })
              expect(result).toMatchError(ValidationError)
            })
          )

related_anchor: test/example.test.ts:20-35

strengths:

• [What was done well]
• [Good patterns observed]

recommendations:

• priority: [high|medium|low]

action: | [Specific action to take] impact: | [Why this matters]

sign_off: ready_for_next_milestone: [yes|no|with-fixes] blocking_issues: [list of critical issues that must be fixed] notes: | [Additional context or observations]

    **Constraints:**
    - ONLY review code from this milestone
    - Reference specific style anchors when citing issues
    - Provide actionable, specific recommendations
    - Include code examples in recommendations when possible

    **Validation:**

Ensure all quality gates pass

npm run lint npm run typecheck npm test

Verify review file is created

ls code-reviews/[yyyy-mm-dd]-*.yaml

    Expected: All quality gates pass, review file exists with complete analysis

    **Drift Policy:**
    If critical issues are found that violate style anchors or architectural
    decisions, mark as blocking and recommend fixes before proceeding to next milestone.

  validation:
    commands:
      - npm run lint
      - npm run typecheck
      - npm test
    expected_output: All quality gates pass
    on_failure: Document failures in review and mark milestone as needing fixes

Code Review Naming Convention

Code review files should be named with:

• Date: YYYY-MM-DD format of when the review was conducted
• Sequence number: Incrementing number for multiple reviews on same date
• Format: code-reviews/YYYY-MM-DD-{n}-code-review.yaml

Examples:

• code-reviews/2025-01-27-1-code-review.yaml (first review on Jan 27)
• code-reviews/2025-01-27-2-code-review.yaml (second review same day)
• code-reviews/2025-01-28-1-code-review.yaml (first review next day)

Integration with Milestone Flow

1. During Milestone Planning:

• Count total tasks planned for milestone
• Add code review task as final task
• Set all other tasks as dependencies

2. During Development:

• Complete all implementation tasks
• Run final code review task
• Address any blocking issues found
• Sign off on milestone completion

3. Before Next Milestone:

• Verify code review sign-off is "yes" or "with-fixes"
• If "with-fixes", address blocking issues first
• Only proceed when quality standards are met

Style Anchor Integration

Loading Style Anchors

If {base_directory}/artifacts/style-anchors/index.yaml exists:

1. Load the index:

   Read {base_directory}/artifacts/style-anchors/index.yaml

2. Parse anchor data:

• Extract categories and anchors
• Load usage_matrix for pattern mapping
• Build lookup table by task type and file patterns

3. For each task generated:

• Determine task type (code/test/docs/config)
• Match file patterns in task against anchor applies_to rules
• Query usage_matrix for recommended anchors
• Select top 2-3 most relevant anchors

Style Anchor Selection Logic

By Task Type:

task.type == "code" → usage_matrix.task_types[type="code"].recommended_anchors
task.type == "test" → usage_matrix.task_types[type="test"].recommended_anchors
task.type == "api"  → usage_matrix.task_types[type="api"].recommended_anchors

By File Pattern:

For each anchor in anchors:
  For each pattern in anchor.applies_to.file_patterns:
    If task.files match pattern:
      Include this anchor

By Milestone Type:

For each anchor in anchors:
  If milestone.type in anchor.applies_to.milestone_types OR "all" in milestone_types:
    Consider this anchor

Embedding Anchors in Task Instructions

When generating task YAML, include style anchor references:

instructions: |
  **Objective:**
  [Task objective]

  **Style Anchors:**
  Follow these established patterns:
  - See `artifacts/style-anchors/[anchor-id].md` - [anchor.name]
  - See `artifacts/style-anchors/[anchor-id].md` - [anchor.name]

  Reference files:
  - `[anchor.source.path]:[anchor.source.lines]` - [what it demonstrates]

  **Implementation Steps:**
  1. [Step 1]
  2. [Step 2]

  **Constraints:**
  - ONLY use: [specific libraries/approaches]
  - Follow pattern in: [anchor reference]
  - File scope: ONLY modify listed files

  [Rest of task instructions...]

What Makes a Good Style Anchor

1. Concrete - Real file paths, not abstract descriptions 2. Specific - Line numbers for precision 3. Complete - Code + tests + documentation 4. Current - Reflects current best practices 5. Exemplary - Demonstrates the pattern correctly

If No Style Anchors Exist

If {base_directory}/artifacts/style-anchors/index.yaml does not exist:

• Display warning: "⚠️ No style anchors found. Tasks will be generated without concrete code examples. Consider running /style-anchors-collection first to reduce drift risk."
• Generate tasks with generic best practices instead
• Include placeholder for style anchors in task instructions:

  instructions: |
    **Style Anchors:**
    (No style anchors collected. Follow general best practices from technical requirements)

Quality Gate Configuration

Pre-Commit Hooks

quality_gates:
  - stage: pre-commit
    commands:
      - npm run lint
      - npm run typecheck
      - npm test
    must_pass: true

CI Pipeline

quality_gates:
  - stage: ci
    commands:
      - npm run lint
      - npm run typecheck
      - npm test
      - npm run test:integration
    coverage_threshold: 80

Task Completion

quality_gates:
  - stage: task-completion
    criteria:
      - All tests passing
      - No lint errors
      - No type errors
      - Code formatted
      - Documentation updated
      - Commit message follows convention

Usage

Generate implementation plan:

/implementation-planner [base-directory]

If no directory is provided, auto-detect by looking for requirements/business-requirements.yaml in the current directory.

If not found, prompt the user: "Where are your requirements documents located?"

Wait for the user to provide a path before proceeding. Store as base_directory.

The skill will:

1. Ask user to choose a milestone ordering strategy (Phase 0) 2. Load and analyze both requirement documents from {base_directory}/requirements/ 3. Load style anchors from {base_directory}/artifacts/style-anchors/index.yaml (if exists) 4. Identify logical milestones based on functionality, sequenced by the chosen strategy 5. Create dependency-ordered milestone breakdown 6. For each milestone:

• Generate detailed task breakdown
• Create task_summaries map with 1-2 sentence plain English summaries for each task (for human scanning)
• Select and embed relevant style anchor references based on task type and file patterns
• Apply task sizing rules
• Add TDD and quality constraints
• Add final code review task as last task

7. Output milestones.yaml to {base_directory}/implementation/ 8. Output milestone-m*.tasks.yaml files to {base_directory}/implementation/tasks/ 9. If generated, output FEATURE_FLAGS.md and UPDATES.md to {base_directory}/artifacts/

Planning Best Practices

Milestone Identification

1. Start with foundation - Infrastructure and tooling first 2. Build vertically - Complete features end-to-end 3. Minimize dependencies - Parallel work where possible 4. Deliver value early - Working software in early milestones 5. Respect constraints - Timeline, resources, complexity

Task Breakdown

1. Single responsibility - Each task does one thing 2. Clear dependencies - Explicit task ordering 3. Testable - Every task has validation criteria 4. Bounded scope - Limited files and complexity 5. Reversible - Easy to revert if needed

Dependency Management

1. Minimize critical path - Parallelize where possible 2. Clear interfaces - Well-defined contracts between tasks 3. Document assumptions - What each task expects from predecessors 4. Plan for failure - What happens if dependencies fail

Example Workflow

Input Files

project/
├── business-requirements.yaml
├── technical-requirements.yaml
└── examples/
    ├── service.ts
    ├── service.test.ts
    └── schema.ts

Command

/implementation-planner \
  business-requirements.yaml \
  technical-requirements.yaml \
  --style-anchors ./examples

Output Files

Create directories if they don't exist:

mkdir -p {base_directory}/implementation/tasks
mkdir -p {base_directory}/artifacts

Output structure:

{base_directory}/
├── implementation/
│   ├── milestones.yaml
│   └── tasks/
│       ├── milestone-m0.tasks.yaml  # Foundation
│       ├── milestone-m1.tasks.yaml  # Core features
│       ├── milestone-m2.tasks.yaml  # Advanced features
│       └── milestone-m3.tasks.yaml  # Polish & release
└── artifacts/
    ├── FEATURE_FLAGS.md     # If generated
    ├── UPDATES.md          # If generated
    └── style-anchor-references.yaml  # If generated

Review & Gap Analysis

After generating milestones and task files, automatically perform a gap analysis:

Completeness Check

Milestone Structure:

• [ ] All milestones have clear deliverables
• [ ] Dependencies are correctly ordered
• [ ] No circular dependencies
• [ ] Timeline is realistic
• [ ] Success criteria are testable

Task Breakdown:

• [ ] All requirements covered by tasks
• [ ] Task sizing follows 30-150 minute rule
• [ ] Dependencies between tasks are explicit
• [ ] File scopes are clearly defined
• [ ] Each task has validation criteria

Task Quality:

• [ ] Instructions are clear and actionable
• [ ] Constraints are explicit
• [ ] TDD checklist included for code tasks
• [ ] Validation commands specified
• [ ] Drift policy stated

Alignment Check

Business Requirements:

• [ ] All functional requirements mapped to tasks
• [ ] Priority aligns with business priorities
• [ ] MVP scope clearly defined
• [ ] Success criteria can be verified

Technical Requirements:

• [ ] Architecture decisions reflected in structure
• [ ] Technology choices enforced in constraints
• [ ] Testing strategy implemented
• [ ] Security requirements addressed

Task Sizing Analysis

Check for violations:

• Tasks < 30 minutes - merge or document rationale
• Tasks > 150 minutes - split into smaller tasks
• Critical path has appropriate task sizes

Generate sizing report:

task_sizing_analysis:
  total_tasks: [count]
  average_duration: [minutes]

  too_small:
    - task_id: [id]
      estimate: [minutes]
      rationale: [why it's small]
      recommendation: [merge with X or accept]

  too_large:
    - task_id: [id]
      estimate: [minutes]
      recommendation: [split into X, Y, Z]

  optimal_range:
    count: [number]
    percentage: [%]

Dependency Analysis

Critical Path:

• [ ] Identify critical path through milestones
• [ ] Check for parallel execution opportunities
• [ ] Verify no unnecessary dependencies
• [ ] Ensure dependencies are minimal but sufficient

Dependency graph validation:

dependency_analysis:
  critical_path: [m0 → m1 → m3 → m5]
  critical_path_duration: [time]

  parallel_opportunities:
    - [m2 and m3 can run in parallel]
    - [m4 can start after m1]

  dependency_issues:
    - task: [id]
      issue: [unnecessary dependency / missing dependency]
      recommendation: [fix]

Gap Identification

Common Gaps to Check:

• Missing infrastructure tasks (setup, tooling)
• Missing test tasks
• Missing documentation tasks
• Missing error handling tasks
• Missing configuration tasks
• Missing deployment/release tasks
• Undocumented assumptions in tasks
• Missing style anchors for new patterns
• Tasks without clear file boundaries
• Missing integration tasks between components

Coverage Analysis

Requirement Coverage Matrix:

requirement_coverage:
  functional_requirements:
    FR-1: [m1-001, m1-002] # Tasks covering this requirement
    FR-2: [m1-003]
    FR-3: [gap] # Not covered!

  non_functional_requirements:
    performance: [m2-001, m2-002]
    security: [m1-005]
    usability: [gap] # Not covered!

Style Anchor Validation

• [ ] Style anchors reference existing files (if provided)
• [ ] Style anchors demonstrate correct patterns
• [ ] Line numbers are accurate
• [ ] Descriptions are helpful

Review Output

Generate a comprehensive gap analysis report:

gap_analysis:
  completeness_score: [1-10]
  alignment_score: [1-10]
  feasibility_score: [1-10]

  critical_gaps:
    - category: [category]
      issue: [description]
      impact: [high/medium/low]
      affected_requirements: [FR-1, FR-2, etc]
      recommendation: [how to fix]

  missing_coverage:
    requirements:
      - [FR-X not covered]
      - [NFR-Y not covered]

    task_types:
      - [Missing: integration tests]
      - [Missing: documentation]

  sizing_issues:
    too_small_count: [n]
    too_large_count: [n]
    recommendations: [list]

  dependency_issues:
    - [description]

  strong_areas:
    - [what's well-planned]

  optimization_opportunities:
    - [parallel execution: m2 and m3]
    - [combine tasks: m1-002 and m1-003]

  suggestions:
    - [improvement suggestions]

  ready_for_development: [yes/no/with-modifications]

  estimated_timeline:
    optimistic: [time]
    realistic: [time]
    pessimistic: [time]

If critical gaps found, ask:

"I've identified some gaps in the implementation plan:

>

Critical Issues:

>

- [Issue 1]

- [Issue 2]

>

Missing Coverage:

>

- [Requirement FR-X not covered]

- [No integration tests planned]

>

Would you like to:

>

1. Add missing tasks now (I'll generate them)

2. Review and manually adjust the plan

3. Proceed with development (address gaps as needed)"

Integration with Development

Starting a Milestone

# Load milestone tasks into context
Read milestone-m1.tasks.yaml

# Review style anchors
Read examples/service.ts:10-50
Read examples/service.test.ts:1-40

# Begin first task
# Task m1-001: Implement core service

Completing a Task

1. Run validation commands 2. Verify all criteria met 3. Commit changes 4. Update task status 5. Move to next task

Handling Drift

If you encounter unexpected patterns:

1. STOP - Do not continue 2. DOCUMENT - What was unexpected 3. REVERT - Return to last known good state 4. REPORT - Ask for guidance 5. UPDATE - Add rule to prevent recurrence

Examples

See [references/milestones-example.yaml](references/milestones-example.yaml) and [references/milestone-tasks-example.yaml](references/milestone-tasks-example.yaml) for sample output files.

Milestone Tasks YAML Specification

Document Type: milestone-m*.tasks.yaml (e.g., milestone-m0.tasks.yaml, milestone-m1.tasks.yaml) Version: 1.0.0 Generated By: implementation-planner skill Purpose: Detailed task breakdown for a specific milestone, including style anchor references, global constraints, quality gates, and executable task instructions. One tasks file per milestone.

---

Document Structure

Root Level

milestone: string                  # Milestone ID (required, format: m[0-9]+)
name: string                       # Milestone name (required)
generated: string                  # ISO 8601 timestamp (required)
task_summaries: map<string,string> # Task ID to summary mapping (optional)

Validation Rules:

• milestone: Must match pattern m\d+ (e.g., m0, m1, m42)
• Must match corresponding milestone ID in milestones.yaml
• name: 10-100 characters, should match milestone name from milestones.yaml
• generated: ISO 8601 format (e.g., "2026-04-15T10:30:00Z")
• task_summaries: Optional; if present, all task IDs must exist in tasks array

Task Summaries Section

task_summaries:
  m0-001: string                   # Summary for task m0-001 (optional)
  m0-002: string                   # Summary for task m0-002 (optional)
  # ... one entry per task

Purpose:

• Provides a scannable overview of all tasks at the top of the document
• 1-2 sentence plain English description of what each task does and why
• Helps human developers quickly understand the full milestone scope
• Complements the detailed description and instructions in each task

Validation Rules:

• Optional section - can be omitted entirely
• If present, each key must be a valid task ID that exists in the tasks array
• Each summary must be 20-300 characters
• Summaries should be plain English, not technical jargon
• Focus on what/why rather than how

Best Practices:

• Keep summaries concise (1-2 sentences maximum)
• State the purpose and value, not implementation details
• Use active voice ("Creates user model", not "User model is created")
• Mention the relationship to other tasks if relevant
• Examples:
• ✓ "Creates the core User data model with validation rules for all user operations."
• ✓ "Tests User model validation covering edge cases and schema encoding/decoding."
• ✗ "Task to implement stuff" (too vague)
• ✗ "Uses Effect.gen and Schema.Class to create User type with email validation..." (too technical/detailed)

Example:

task_summaries:
  m1-001: "Defines core User model with email/username/password validation using Effect Schema."
  m1-002: "Tests User model validation rules covering edge cases and schema encoding/decoding."
  m1-003: "Implements repository pattern for user CRUD operations encapsulating all database access."
  m1-004: "Integration tests for repository against real database with transaction isolation."
  m1-005: "Service layer coordinating user operations with password hashing and business rules."

Note: Task summaries are intended for human scanning. They do not replace the detailed description or instructions fields in each task object. Think of this as a table of contents for the milestone.

Style Anchor References Section

style_anchor_refs: array<string>   # Style anchor codes (optional)

Purpose:

• Lists style anchors relevant to this milestone's tasks
• Quick reference for developers working on the milestone
• Codes link to detailed pattern documentation in style-anchors/SA-*.md

Validation Rules:

• Each entry must be a valid style anchor code (e.g., "SA-001", "SA-042")
• Codes must match existing style anchor documents
• Optional section - can be empty array or omitted

Example:

style_anchor_refs:
  - SA-001  # Effect.Service with Repository pattern
  - SA-003  # TRPC router with Zod validation
  - SA-015  # Error handling with Result types

Note: These are milestone-level references for convenience. Individual tasks include specific style_anchor_refs with detailed usage guidance in their instructions field.

Global Constraints Section

global_constraints:
  allowed_patterns: array<string>  # Approved patterns (required)
  forbidden_patterns: array<string> # Anti-patterns to avoid (required)
  tdd_required: boolean            # Test-driven development flag (required)
  max_task_duration_minutes: number # Maximum task duration (required)
  commit_strategy: string          # Commit frequency (required)

Validation Rules:

• allowed_patterns: 1-10 items, each 10-200 characters, specific and actionable
• forbidden_patterns: 1-10 items, each 10-200 characters, clear anti-patterns
• tdd_required: Boolean (true/false)
• max_task_duration_minutes: Integer, typically 30-150 (0.5h - 2.5h)
• commit_strategy: Common values: "Commit after each task", "Commit after logical unit", "Feature flag approach"

Purpose:

• Enforces architectural consistency across all milestone tasks
• Prevents common mistakes and anti-patterns
• Establishes testing and commit discipline
• Sets expectations for task granularity

Best Practices:

• Reference specific technologies/frameworks in allowed_patterns
• Make forbidden_patterns concrete (not vague like "don't write bad code")
• Set max_task_duration to enforce proper task breakdown
• Align commit_strategy with ordering_strategy from milestones.yaml

Quality Gates Section

quality_gates:
  - stage: enum                    # Gate stage (required)
    commands: array<string>        # Commands to run (conditional)
    criteria: array<string>        # Success criteria (conditional)

Enums:

• stage: pre-task | pre-commit | task-completion | milestone-completion | pre-push

Stage Purposes:

1. pre-task: Verify preconditions before starting work

• Check dependencies completed
• Verify required files exist
• Validate environment setup
• Example criteria: "All dependency tasks marked complete", "Test database accessible"

2. pre-commit: Automated checks before committing code

• Run linter, type checker, tests
• Format code
• Example commands: npm run lint, npm run type-check, npm test

3. task-completion: Acceptance criteria for marking task done

• All tests passing
• Documentation updated
• Success criteria met
• Example criteria: "Unit tests >80% coverage", "JSDoc added to public methods"

4. milestone-completion: Criteria for milestone acceptance

• All tasks complete
• Integration tests passing
• Code review approved
• Example criteria: "All milestone success criteria met", "Manual smoke test passed"

5. pre-push: Final checks before pushing to remote

• Full test suite
• No merge conflicts
• Branch up to date
• Example commands: npm run test:integration, git fetch && git status

Validation Rules:

• At least 1 quality gate required
• pre-task stage should include criteria (precondition checks)
• pre-commit stage should include commands (linter, type checker, tests)
• task-completion stage should include criteria (acceptance conditions)
• milestone-completion stage should include criteria (milestone acceptance)
• pre-push stage should include commands (full test suite)
• Commands must be executable from project root
• Criteria must be testable and objective

Example:

quality_gates:
  - stage: pre-task
    criteria:
      - All dependency tasks marked complete
      - Development environment running
      - Required files exist (if modifying)
      - Style anchors reviewed
  - stage: pre-commit
    commands:
      - npm run lint
      - npm run type-check
      - npm run test
  - stage: task-completion
    criteria:
      - All tests passing
      - No lint errors
      - Code formatted
      - Documentation updated
  - stage: milestone-completion
    criteria:
      - All milestone success criteria met
      - Code review completed
      - Manual smoke test passed
  - stage: pre-push
    commands:
      - npm run test:integration
      - npm run build
      - git fetch && git status

Purpose:

• Automated quality checks before commits
• Clear definition of "done" for tasks
• Prevents quality drift during implementation
• Catches issues early in development cycle

Tasks Array

tasks:
  - id: string                     # Task ID (required, format: {milestone}-NNN)
    name: string                   # Task name (required)
    description: string            # What to implement (required, multi-line)
    estimate_minutes: number       # Time estimate (required)
    type: enum                     # Task type (required)
    dependencies: array<string>    # Task dependencies (required)
    files: object                  # Files affected (required)
    style_anchor_refs: array<string> # Relevant style anchors (optional)
    instructions: string           # Detailed implementation steps (required, multi-line)

Task ID Format:

• Pattern: {milestone}-{NNN} where NNN is zero-padded 3 digits
• Examples: m0-001, m1-042, m2-123
• Must be sequential within milestone

Task Type Enum:

• code: Feature implementation, refactoring
• test: Test writing, test coverage
• docs: Documentation, README updates
• config: Configuration, setup, tooling

Validation Rules:

• id: Must match pattern m\d+-\d{3} and be sequential
• name: 10-100 characters, clear and actionable
• description: 50-500 characters, explains what and why
• estimate_minutes: Integer, 30-150 (must fit within max_task_duration_minutes)
• dependencies: Array of task IDs within same milestone (can be empty)
• files: Must contain at least one of: create, modify, or touch_only
• instructions: 100-2000 characters, detailed step-by-step guide

Files Object Structure:

files:
  create: array<string>            # New files to create (optional)
  modify: array<string>            # Existing files to modify (optional)
  touch_only: array<string>        # Reference files (optional)

Files Validation:

• All paths relative to project root
• create: Files that don't exist yet
• modify: Files that must exist
• touch_only: Files to reference but not change (style anchors, interfaces)

Style Anchor Refs:

• Optional array of anchor codes (e.g., ["SA-001", "SA-015"])
• Referenced anchors should be relevant to task implementation
• Instructions should explain how to apply each anchor

Instructions Format:

instructions: |
  **Objective:**
  [Clear statement of what needs to be done]

  **Implementation Steps:**
  1. [Step 1 - specific action]
  2. [Step 2 - specific action]
  3. [Step 3 - specific action]

  **Constraints:**
  - ONLY use: [specific libraries/approaches]
  - Follow pattern in: **SA-001** (reference anchor by code)
  - NEVER use: [forbidden approaches]

  **Testing Requirements:**
  - [Test requirement 1]
  - [Test requirement 2]

  **Success Criteria:**
  - [Criterion 1 - testable outcome]
  - [Criterion 2 - testable outcome]

Instructions Best Practices:

• Use markdown formatting for readability
• Reference style anchors by code with bold formatting: SA-001
• Include explicit constraints from global_constraints where relevant
• Make steps sequential and actionable
• Include testing requirements (especially if tdd_required: true)
• Define task-specific success criteria

---

Field Type Reference

---

Validation Summary

Required Root Level

• ✓ milestone (matches milestones.yaml ID)
• ✓ name (matches milestone name)
• ✓ generated (ISO 8601 timestamp)

Required Sections

• ✓ global_constraints (with all 5 sub-fields)
• ✓ quality_gates (at least 1 gate)
• ✓ tasks (at least 1 task)

Required Per Task

• ✓ id (sequential, {milestone}-001, {milestone}-002, ...)
• ✓ name
• ✓ description
• ✓ estimate_minutes (within max_task_duration_minutes)
• ✓ type (code, test, docs, or config)
• ✓ dependencies (array, can be empty)
• ✓ files (with at least one of: create, modify, touch_only)
• ✓ instructions (detailed, multi-line)

Optional Elements

• task_summaries (root-level, scannable overview)
• style_anchor_refs (milestone-level)
• style_anchor_refs (per-task level)

Quality Gates

1. Task IDs are sequential starting from {milestone}-001 2. All dependencies reference valid task IDs within same milestone 3. No circular task dependencies 4. Task estimates sum to reasonable milestone duration 5. Each task has clear success criteria in instructions 6. Style anchor codes reference existing anchors

---

Integration with Other Documents

Input Documents

• milestones.yaml → Provides milestone context, dependencies, success criteria
• business-requirements.yaml → Informs functional scope and priorities
• technical-requirements.yaml → Guides technical approach and constraints
• style-anchors/index.yaml → Source of valid anchor codes
• style-anchors/SA-*.md → Pattern documentation referenced by codes

Output Documents

• timeline.yaml → Task estimates inform delivery dates
• definition-of-done.yaml → Task success criteria feed acceptance criteria

Related Documents

• qa-test-plan.yaml → Test tasks mapped to QA test plan
• implementation-plan-review.yaml → Validates task structure and quality

Workflow Position

business-requirements → technical-requirements → style-anchors
                                                       ↓
                            milestones.yaml ← implementation-planner
                                    ↓
                            milestone-m*.tasks.yaml (per milestone)
                                    ↓
                            Development execution → timeline tracking

---

Task Dependency Patterns

Independent Tasks (Parallel)

tasks:
  - id: m0-001
    dependencies: []
  - id: m0-002
    dependencies: []  # Can run in parallel with m0-001
  - id: m0-003
    dependencies: []  # Can run in parallel with both

Sequential Tasks (Waterfall)

tasks:
  - id: m1-001
    dependencies: []
  - id: m1-002
    dependencies: [m1-001]  # Must complete after m1-001
  - id: m1-003
    dependencies: [m1-002]  # Must complete after m1-002

Fan-Out Pattern

tasks:
  - id: m2-001
    dependencies: []  # Foundation task
  - id: m2-002
    dependencies: [m2-001]  # Depends on foundation
  - id: m2-003
    dependencies: [m2-001]  # Also depends on foundation, parallel with m2-002
  - id: m2-004
    dependencies: [m2-001]  # Also depends on foundation, parallel with m2-002 and m2-003

Join Pattern

tasks:
  - id: m3-001
    dependencies: []
  - id: m3-002
    dependencies: []  # Parallel with m3-001
  - id: m3-003
    dependencies: [m3-001, m3-002]  # Waits for both to complete

---

CLI Tool Support

Validation Command

sherpy validate milestone-m0.tasks.yaml

Checks:

• Schema compliance
• Task ID sequencing
• Dependency references valid
• No circular dependencies
• Estimates within max_task_duration_minutes
• Style anchor codes exist
• File paths relative to project root

Dependency Graph Command

sherpy graph milestone-m0.tasks.yaml

Output:

• Visual task dependency graph (ASCII or DOT format)
• Critical path within milestone
• Parallel execution opportunities
• Estimated completion time

Execution Tracking Command

sherpy track milestone-m0.tasks.yaml

Output:

• Task completion status
• Time spent vs. estimate
• Blockers and dependencies
• Next available tasks

---

Style Anchor Integration

Style anchors are referenced by code (SA-001, SA-002, etc.) at both milestone and task levels:

1. Milestone-Level References (Optional)

milestone: m1
name: "User Authentication"
style_anchor_refs:
  - SA-001  # Effect.Service pattern
  - SA-015  # Error handling

Purpose: Quick reference for all developers working on this milestone.

2. Task-Level References (Recommended)

tasks:
  - id: m1-003
    name: "Implement UserService"
    style_anchor_refs:
      - SA-001  # Service pattern
      - SA-015  # Error handling
    instructions: |
      **Objective:**
      Create UserService following Effect.Service pattern.

      **Implementation Steps:**
      1. Review **SA-001** for service structure
      2. Implement findById and create methods
      3. Apply **SA-015** for error handling

Purpose: Direct developers to specific patterns for each task.

3. Instruction Inline References (Required)

instructions: |
  **Constraints:**
  - Follow pattern in **SA-001** for all service classes
  - Use **SA-015** error handling (never throw exceptions)
  - Reference **SA-003** for TRPC router integration

Purpose: Explicit guidance on how to apply patterns in context.

Workflow

1. Collection Phase (before implementation planning)

• Run style-anchors-collection skill
• Creates style-anchors/index.yaml and SA-*.md files
• Assigns unique codes (SA-001, SA-002, ...)

2. Planning Phase (implementation-planner)

• Generates milestones.yaml (no style anchor refs here)
• Generates milestone-m*.tasks.yaml WITH anchor refs
• Embeds anchor codes in task instructions

3. Development Phase

• Developer reads task from milestone-m*.tasks.yaml
• Sees anchor codes in style_anchor_refs and instructions
• Looks up full pattern in style-anchors/SA-*.md
• Implements following documented pattern

See Also:

• style-anchors/index.yaml specification
• style-anchors/SA-*.md specification (individual anchors)
• milestones.yaml specification (milestone structure)

---

Best Practices

Task Sizing

DO:

• Keep tasks between 30-150 minutes (0.5h - 2.5h)
• Break large features into multiple tasks
• Each task should have one clear objective
• Tasks should be independently testable

DON'T:

• Create tasks > 150 minutes (too risky, hard to estimate)
• Mix setup with feature implementation in one task
• Create "implement entire feature" mega-tasks
• Make task descriptions too vague

Task Naming

DO:

• Start with action verb (Implement, Create, Add, Refactor, Test)
• Be specific about what's being built
• Match technical terminology
• Examples: "Implement UserService with Effect", "Add TRPC router validation"

DON'T:

• Use vague names ("Work on auth", "Fix stuff")
• Omit technical detail
• Use ambiguous verbs ("Update", "Change")

Instructions Quality

DO:

• Include objective, steps, constraints, testing, success criteria
• Reference style anchors by code with bold formatting
• Make steps sequential and actionable
• Include "what" and "why" context
• Specify exact libraries/approaches to use

DON'T:

• Write generic instructions ("implement the feature")
• Omit constraints (leads to inconsistent code)
• Skip testing requirements
• Assume developer knows all context
• Leave success criteria vague

Dependencies Management

DO:

• Minimize dependencies to enable parallel work
• Only add dependencies when truly required
• Document why dependencies exist
• Consider task order to reduce blocking

DON'T:

• Create circular dependencies
• Add unnecessary "nice to have" dependencies
• Make every task depend on previous task
• Forget to validate dependencies exist

Common Pitfalls

1. Oversized Tasks

• ❌ "Implement complete authentication system: 180 minutes"
• ✓ "m0-001: Create User model (45m), m0-002: Implement UserService (60m), m0-003: Add TRPC auth routes (45m)"

2. Vague Instructions

• ❌ "Create the service. Follow best practices."
• ✓ "Create UserService following SA-001 pattern. Use Effect.gen for implementation. Include findById, create, and update methods."

3. Missing Style Anchor References

• ❌ Instructions mention "follow the pattern" but no anchor code
• ✓ "Follow SA-001 for service structure and SA-015 for error handling"

4. Unrealistic Estimates

• ❌ "Complete rewrite of auth system: 60 minutes"
• ✓ Break into 4-5 tasks, each 45-90 minutes with specific scope

5. Weak Success Criteria

• ❌ "Code works"
• ✓ "Unit tests pass (>80% coverage), linter clean, manual test: can create user and fetch by ID"

---

Task Type Guidance

Code Tasks

Purpose: Feature implementation, service creation, API development Example:

- id: m1-001
  name: "Implement AccountService"
  type: code
  estimate_minutes: 60
  instructions: |
    **Objective:** Create AccountService with CRUD operations.

    **Implementation Steps:**
    1. Create `src/services/account-service.ts`
    2. Follow **SA-001** pattern for service structure
    3. Implement findById, create, update, delete methods

Test Tasks

Purpose: Test coverage, test infrastructure, test data Example:

- id: m1-002
  name: "Add AccountService unit tests"
  type: test
  estimate_minutes: 45
  dependencies: [m1-001]
  instructions: |
    **Objective:** Achieve >80% test coverage for AccountService.

    **Implementation Steps:**
    1. Create `src/services/account-service.test.ts`
    2. Follow **SA-004** for service testing pattern
    3. Test all CRUD operations with mocks

Docs Tasks

Purpose: README updates, API documentation, inline comments Example:

- id: m1-003
  name: "Document AccountService API"
  type: docs
  estimate_minutes: 30
  dependencies: [m1-001, m1-002]
  instructions: |
    **Objective:** Document AccountService public API.

    **Implementation Steps:**
    1. Add JSDoc comments to public methods
    2. Update README.md with usage examples
    3. Add entry to API reference docs

Config Tasks

Purpose: Environment setup, CI/CD, build config, dependencies Example:

- id: m0-001
  name: "Setup Effect dependencies"
  type: config
  estimate_minutes: 30
  instructions: |
    **Objective:** Install and configure Effect ecosystem.

    **Implementation Steps:**
    1. Install @effect/schema, @effect/platform
    2. Update tsconfig.json for strict mode
    3. Configure ESLint for Effect patterns

---

Milestone Completion Checklist

Before marking a milestone complete, verify:

• [ ] All tasks marked complete
• [ ] All pre-commit quality gates passing
• [ ] Task-completion criteria met for every task
• [ ] Milestone-completion quality gate criteria met
• [ ] All milestone success criteria from milestones.yaml achieved
• [ ] Code review completed (if required)
• [ ] Documentation updated
• [ ] Tests passing (unit, integration, E2E as applicable)
• [ ] Manual smoke test passed
• [ ] No known blockers or technical debt introduced
• [ ] Ready to proceed to next milestone

---

Schema Version History

• 1.0.0 (2026-04-15): Initial specification
• Complete task structure with code-based style anchor references
• Global constraints and quality gates
• Task dependencies and file tracking
• Detailed instruction format
• Integration with milestones.yaml and style anchors

---

Examples

See example.yaml for a complete, realistic milestone tasks document with multiple task types and dependency patterns.

Milestones YAML Specification

Document Type: milestones.yaml Version: 1.0.0 Generated By: implementation-planner skill Purpose: Defines high-level project milestones with dependencies, deliverables, and success criteria. Each milestone references a detailed tasks file containing executable implementation steps.

---

Document Structure

Root Level

version: string                    # Semantic version (required, format: "X.Y.Z")
project: string                    # Project name (required)
generated: string                  # ISO 8601 timestamp (required)
business_requirements: string      # Path to business requirements (required)
technical_requirements: string     # Path to technical requirements (required)

Validation Rules:

• version: Must be semantic version format (e.g., "1.0.0")
• project: 3-100 characters, kebab-case recommended
• generated: ISO 8601 format (e.g., "2026-04-15T10:30:00Z")
• business_requirements: Relative path from milestones.yaml location
• technical_requirements: Relative path from milestones.yaml location

Meta Section

meta:
  ordering_strategy: enum          # Milestone ordering strategy (required)
  ordering_rationale: string       # Why this strategy chosen (required)

Enums:

• ordering_strategy: multi-pr | single-feature-branch | value-first | risk-first | vertical-slice | foundation-first

Strategy Descriptions:

• multi-pr: Each milestone ships independently as separate PR
• single-feature-branch: All milestones on one feature branch, single PR
• value-first: Prioritize delivering user-visible value early
• risk-first: Tackle highest-risk items first to reduce uncertainty
• vertical-slice: Deliver end-to-end functionality in thin slices
• foundation-first: Build infrastructure/foundations before features

Validation Rules:

• ordering_rationale: 20-300 characters, must explain strategy choice
• Should reference project constraints, team size, or delivery model

Milestones Array

milestones:
  - id: string                     # Milestone ID (required, format: m[0-9]+)
    name: string                   # Milestone name (required)
    description: string            # What this delivers (required, multi-line)
    dependencies: array<string>    # Milestone IDs this depends on (required)
    estimated_duration: string     # Time estimate (required)
    tasks_file: string             # Path to tasks file (required)
    success_criteria: array<string> # High-level acceptance criteria (required, min: 1)
    acceptance_criteria: object    # Detailed acceptance criteria (optional)
    exit_checklist: array<string>  # Sign-off checklist (optional)

Validation Rules:

• id: Must match pattern m\d+ (e.g., m0, m1, m42)
• IDs must be sequential starting from m0
• name: 10-100 characters, clear and descriptive
• description: 50-1000 characters, multi-line YAML string using |
• dependencies: Array of milestone IDs (empty array [] for first milestone)
• Dependencies must reference valid milestone IDs defined earlier
• No circular dependencies allowed
• estimated_duration: Human-readable format (e.g., "2-3 hours", "1 day", "3-4 days")
• tasks_file: Must match pattern milestone-{id}.tasks.yaml
• success_criteria: 1-10 items, each 20-200 characters, specific and testable

Common Milestone Patterns:

• M0: Setup, scaffolding, infrastructure
• M1-M(n-1): Feature implementation, progressive delivery
• M(n): Testing, documentation, deployment readiness

Description Best Practices:

• Start with "what" this milestone delivers
• Include key deliverables as bullet points
• Note risk level if relevant
• Reference related requirements or features

---

Optional Extensions

Real-world implementations may include these optional sections:

Overview Section

overview: string                   # Project summary (optional, multi-line)

Usage:

• High-level project context and strategy
• Solution approach and key principles
• Milestone strategy rationale
• Use multi-line YAML string with |

Project Metadata Section

project_metadata:
  total_estimated_duration: string # Total time estimate (optional)
  parallel_opportunities: array<string> # Milestones that can run in parallel (optional)
  critical_path: array<string>     # Critical path milestones (optional)
  risk_mitigation: string          # Risk handling strategy (optional)
  success_metrics: string          # Overall success measures (optional)
  rollback_strategy: string        # Rollback plan (optional)

Usage:

• Project-level planning metadata
• High-level risk and success tracking
• Helps with timeline and resource planning
• Not required by implementation-planner, but useful for project management

Dependencies and Risks

dependencies:
  [milestone_id]_blocks: array<string> # Milestones blocked by this one (optional)

risks_and_mitigation:
  - risk: string                   # Risk description
    severity: enum                 # Severity level
    mitigation: string             # Mitigation strategy

Usage:

• Alternative dependency tracking format
• Project-level risk register
• Common in larger projects

Detailed Acceptance Criteria (Per-Milestone)

milestones:
  - id: m1
    # ... standard fields ...
    success_criteria:  # Required: High-level planning criteria
      - "Users can sign up and log in"
      - "Password security meets requirements"

    acceptance_criteria:  # Optional: Detailed delivery criteria
      functional:
        - criterion: string              # Verifiable behavior (required)
          requirement_ref: string        # Business requirement ID (optional)
      non_functional:
        - criterion: string              # Measurable quality threshold (required)
          requirement_ref: string        # NFR ID (optional)
      testing:
        unit: string                     # Unit test coverage (required)
        integration: string              # Integration test expectations (required)
        e2e: string                      # E2E scenario expectations (required)
        regression: string               # Regression requirements (required)
      documentation:
        - string                         # Documentation artifact (required)
      cross_milestone_notes:             # Optional spanning requirements
        - string

    exit_checklist:  # Optional: Binary go/no-go checklist for sign-off
      - "[ ] Users can sign up/log in (BR-FUNC-001, BR-FUNC-002)"
      - "[ ] All unit tests pass (≥85% coverage)"
      - "[ ] PR approved"

Purpose:

• success_criteria: Required high-level acceptance criteria for planning
• acceptance_criteria: Optional detailed criteria for rigorous milestone sign-off
• exit_checklist: Optional binary checklist for code review and delivery gates

When to Use:

• Simple projects: Use only success_criteria (required field)
• Rigorous delivery: Add acceptance_criteria for detailed requirement tracing
• Gate-driven process: Add exit_checklist for code review and QA sign-off

acceptance_criteria Structure:

1. functional: Verifiable behaviors derived from business requirements

• Each criterion is observable and testable
• Links to requirement IDs via requirement_ref (format: BR-FUNC-001)
• Avoids vague language ("works well" ✗, "processes 1000 req/min" ✓)

2. non_functional: Measurable quality thresholds from technical requirements

• Must include concrete metrics (response time, throughput, error rate)
• Links to NFR IDs via requirement_ref (format: NFR-PERF-002)
• Scaled to milestone scope (early milestones have relaxed targets)

3. testing: Test coverage requirements by category

• unit: Coverage percentage or "N/A" with justification
• integration: Service boundary tests or "N/A"
• e2e: User flow tests or "N/A"
• regression: Typically "All existing tests pass" or "N/A" for first milestone

4. documentation: Required documentation artifacts

• Specific deliverables (not generic "add docs")
• Examples: "API docs for /auth/* endpoints", "README updated with setup"

5. cross_milestone_notes: Requirements spanning multiple milestones (optional)

• Documents foundational work verified in later milestones
• Example: "Encryption at rest spans m1 (schema), m3 (key mgmt), m5 (rotation)"

exit_checklist Guidelines:

• 3-10 binary checks per milestone
• Each item starts with [ ] (markdown checkbox)
• Summarizes acceptance_criteria into yes/no gates
• Always include: functional checks, testing checks, docs check, PR approval

Validation Rules:

• If acceptance_criteria present, all five categories required (even if empty/N/A)
• If acceptance_criteria.testing present, all four test types required
• exit_checklist items must start with [ ]
• requirement_ref must match IDs from business/technical requirements files

---

Field Type Reference

---

Validation Summary

Required Sections

• ✓ version, project, generated
• ✓ business_requirements, technical_requirements
• ✓ meta (with ordering_strategy, ordering_rationale)
• ✓ milestones (at least 1 milestone)

Required Per Milestone

• ✓ id (sequential, m0, m1, m2, ...)
• ✓ name
• ✓ description (detailed, multi-line)
• ✓ dependencies (array, can be empty)
• ✓ estimated_duration
• ✓ tasks_file
• ✓ success_criteria (at least 1)

Optional Sections

• overview (project context)
• project_metadata (planning metadata)
• dependencies (alternative format)
• risks_and_mitigation (risk register)

Quality Gates

1. Milestone IDs are sequential starting from m0 2. All dependencies reference valid milestone IDs 3. No circular dependencies in dependency graph 4. Each milestone has at least 1 success criterion 5. Estimated durations are realistic (typically 30min - 1 week per milestone) 6. Each tasks_file matches naming convention

---

Integration with Other Documents

Input Documents

• gap-analysis-worksheet.yaml → Pre-requirements gap identification (workflow context)
• business-requirements.yaml → Informs milestone scope and success criteria
• technical-requirements.yaml → Guides technical approach and architecture
• style-anchors/index.yaml → Code examples referenced in task-level instructions

Output Documents

• milestone-m*.tasks.yaml → Detailed task breakdown for each milestone
• timeline.yaml → Timeline with estimated dates (via delivery-timeline skill)
• Optionally embeds detailed acceptance criteria within milestone definitions

Related Documents

• qa-test-plan.yaml → Maps testing to milestones
• architecture-decision-record/*.md → Technical decisions affecting milestones
• implementation-plan-review.yaml → Validates milestone structure and quality

Workflow Position

gap-analysis → business-requirements → technical-requirements → style-anchors
                                                                      ↓
                                              milestones.yaml ← implementation-planner
                                                      ↓
                                              milestone-m*.tasks.yaml (references style anchors)
                                                      ↓
                                              timeline.yaml + definition-of-done.yaml

---

Milestone Dependency Patterns

Linear Dependencies (Waterfall)

milestones:
  - id: m0
    dependencies: []
  - id: m1
    dependencies: [m0]
  - id: m2
    dependencies: [m1]

Parallel Branches

milestones:
  - id: m0
    dependencies: []
  - id: m1
    dependencies: [m0]
  - id: m2
    dependencies: [m0]  # Parallel with m1
  - id: m3
    dependencies: [m1, m2]  # Joins parallel branches

No Dependencies (Fully Parallel)

milestones:
  - id: m0
    dependencies: []
  - id: m1
    dependencies: []
  - id: m2
    dependencies: []

---

CLI Tool Support

Validation Command

sherpy validate milestones.yaml

Checks:

• Schema compliance
• Required sections present
• Milestone ID sequencing (m0, m1, m2, ...)
• Dependency references valid
• No circular dependencies
• Tasks files exist at specified paths

Dependency Graph Command

sherpy graph milestones.yaml

Output:

• Visual dependency graph (ASCII or DOT format)
• Critical path analysis
• Parallel execution opportunities

Timeline Generation Command

sherpy timeline milestones.yaml --deploy-date 2026-06-01

Output:

• timeline.yaml with calendar dates
• Workback schedule from deploy date
• Resource allocation suggestions

---

Style Anchors Integration

Style anchors are referenced at the task level, not in milestones.yaml:

1. Collection Phase (before milestones.yaml generation)

• Run /style-anchors-collection to create style-anchors/index.yaml
• Identify exemplar code patterns from existing codebase
• Document patterns in style-anchors/SA-*.md files with unique codes

2. Milestones.yaml (this document)

• Focuses on high-level milestone structure, dependencies, success criteria
• Does NOT reference style anchors - that's task-specific

3. Task-Level Usage (in milestone-m*.tasks.yaml)

• Implementation-planner embeds relevant anchor codes in task instructions
• Tasks reference specific codes: "Follow SA-001 for service structure"
• Developers look up SA-*.md files for full pattern documentation

Why Not in Milestones.yaml:

• Style anchors are task-specific, not milestone-specific
• Different tasks within same milestone may use different patterns
• Keeps milestones.yaml focused on project structure
• Prevents redundancy with task files

See Also:

• style-anchors/index.yaml specification for anchor collection
• style-anchors/SA-*.md specification for individual anchor documents
• milestone-m*.tasks.yaml specification for task-level anchor embedding

---

Best Practices

Milestone Sizing

DO:

• Keep milestones between 30 minutes and 1 week
• Break large features into progressive milestones
• Each milestone should be independently shippable (for multi-pr strategy)
• Align milestone boundaries with testable deliverables

DON'T:

• Create milestones > 1 week (too risky, hard to estimate)
• Mix infrastructure setup with feature work in one milestone
• Create too many dependencies (reduces parallelization)
• Make milestone descriptions too vague or generic

Dependency Management

DO:

• Minimize dependencies to enable parallel work
• Document why dependencies exist in descriptions
• Consider vertical slicing to reduce inter-milestone dependencies
• Front-load risky/unknown work to reduce downstream impact

DON'T:

• Create circular dependencies
• Add unnecessary "nice to have" dependencies
• Assume sequential execution unless truly required
• Couple unrelated milestones together

Success Criteria

DO:

• Make criteria testable and objective
• Include both functional and technical criteria
• Reference specific features or capabilities
• Consider rollback scenarios

DON'T:

• Use vague criteria ("code works well")
• Make criteria unmeasurable ("users are happy")
• Omit test coverage requirements
• Skip documentation requirements

Common Pitfalls

1. Milestone Scope Creep

• ❌ "Authentication system with user management, roles, and audit logs"
• ✓ "M1: Basic authentication. M2: Role-based access. M3: Audit logging"

2. Vague Success Criteria

• ❌ "Feature works correctly"
• ✓ "All unit tests pass, integration test covers happy path, manual smoke test successful"

3. Hidden Dependencies

• ❌ M2 needs M1's database schema but dependencies: []
• ✓ M2 explicitly lists dependencies: [m0, m1] with rationale in description

4. Over-Optimistic Estimates

• ❌ "Complete rewrite of auth system: 2 hours"
• ✓ "M0: Setup (1h). M1: Core logic (4h). M2: Integration (3h). M3: Testing (2h)"

5. Missing Risk Context

• ❌ "Migrate to new database" (no risk mention)
• ✓ "Migrate to new database. Risk: High (data migration). Includes rollback plan."

---

Ordering Strategy Decision Guide

Choose ordering strategy based on project characteristics:

Multi-PR (Recommended for Most Projects)

• When: Team can review and merge incrementally
• Pros: Fast feedback, reduced merge conflicts, progressive delivery
• Cons: Requires stable trunk, good CI/CD
• Example: SaaS features, API additions, internal tools

Single Feature Branch

• When: Large coordinated changes, risky refactors
• Pros: Atomic delivery, easier rollback, comprehensive review
• Cons: Merge conflicts, stale branch, delayed feedback
• Example: Breaking API changes, major refactors, database migrations

Value-First

• When: Need to demonstrate ROI early
• Pros: Stakeholder visibility, early user feedback
• Cons: May incur technical debt, rework possible
• Example: MVP development, proof-of-concept, beta features

Risk-First

• When: High technical uncertainty
• Pros: Early learning, reduced late-stage surprises
• Cons: Delayed user value, may feel unproductive
• Example: New technology spikes, complex integrations, performance unknowns

Vertical Slice

• When: Full-stack features with UI/API/DB
• Pros: End-to-end validation, realistic progress tracking
• Cons: Requires full-stack capability, more coordination
• Example: User-facing features, workflow implementations

Foundation-First

• When: Building platform/framework
• Pros: Solid base for future work, clean architecture
• Cons: No visible value early, requires upfront design
• Example: Platform builds, shared libraries, infrastructure

---

Schema Version History

• 1.0.0 (2026-04-15): Initial specification
• Complete YAML schema definition
• Ordering strategy patterns
• Validation rules and dependency checking
• Integration with Sherpy workflow
• Optional extension documentation

---

Examples

See example.yaml for a complete, realistic implementation plan with milestones.