Plan

Feature Plan

Plan a feature implementation by understanding the project architecture, decomposing work into service-level and role-level packages, and producing an actionable plan. This is the planning phase — no code is written here. Output feeds into feature-dev skill for execution.

1. Receive Feature Requirements

Gather the feature specification from the user:

• Accepted formats: PRD, ARD, design doc, implementation plan, ticket/issue, verbal description
• Read every provided document thoroughly
• Extract and organize:
  • Goal: What the feature does (1–2 sentences)
  • Requirements: Functional (what it does) and non-functional (performance, security, compliance)
  • Acceptance criteria: How to verify the feature works
  • Constraints: Deadlines, compatibility, dependencies on other teams/services
  • Out of scope: What this feature explicitly does NOT cover

If the specification is ambiguous or incomplete — ask before proceeding. Do not assume missing requirements.

2. Understand Project Architecture

Read and internalize the project's structure to plan correctly:

2a. Read Architecture Documentation

Read the following files (if they exist):

1. ARCHITECTURE.md — system overview, component boundaries, data flow, service map
2. AGENTS.md (root) — tech stack declaration, project structure, conventions
3. Subdirectory AGENTS.md files — per-service/module context and stack info

Extract:

• Service/module boundaries (monolith modules, microservices, frontend/backend split)
• Tech stack per service (language, framework, database, messaging)
• Communication patterns (REST, gRPC, events, shared DB)
• Data flow relevant to the feature
• Deployment topology (monorepo vs polyrepo, shared vs independent deploys)

2b. Scan Project Structure

If documentation is incomplete or absent, scan the filesystem:

// turbo
ls -la (or dir for Windows)

Look for:

• Monorepo signals: packages/, services/, apps/, root package.json with workspaces, Nx/Turborepo config
• Polyrepo signals: Single service, one AGENTS.md, one tech stack
• Infrastructure: terraform/, infra/, k8s/, helm/, docker-compose.yml
• Dependency files: package.json, pom.xml, requirements.txt, go.mod, *.csproj per service

2c. Build Service Map

Create a map of services/modules the feature touches:

## Service Map

| Service/Module | Tech Stack | Role | Affected by Feature |
|---|---|---|---|
| [name] | [lang + framework] | `role-id` | [yes/no — how] |
| [name] | [lang + framework] | `role-id` | [yes/no — how] |
| infrastructure | Terraform / K8s | `devops-engineer` role | [yes/no — how] |

3. Decompose into Work Packages

Break the feature into work packages — each package is a self-contained unit of work scoped to one service/module and one role.

3a. Identify Work Streams

Group changes by responsibility:

Only include work streams that the feature actually requires. Do not add empty streams.

3b. Define Work Packages

For each work stream, create ordered work packages:

### [Work Stream]: [Service Name] — `role-id`

#### WP-[N]: [Title]
- **Description**: What to implement
- **Files**: Expected files to create/modify
- **Dependencies**: Which WPs must complete first
- **Acceptance criteria**: How to verify this WP is done
- **Complexity**: S (hours) / M (day) / L (days) / XL (week+)

Rules for decomposition:

• Each WP is independently testable
• WPs within a stream are ordered by dependency (foundations first)
• Cross-service dependencies are explicitly marked
• Database migrations always come before code that uses them
• API contracts defined before consumer implementation

3c. Define Integration Points

For features spanning multiple services, explicitly document:

4. Dependency Graph

Visualize the execution order:

## Dependency Graph

WP-1: [DB migration]
  └─► WP-2: [Backend API]
        ├─► WP-3: [Frontend integration]
        └─► WP-4: [Infrastructure/config]
WP-5: [Tests] ← depends on WP-2, WP-3

Identify:

• Critical path: Longest chain of dependent WPs — determines minimum timeline
• Parallelizable: WPs that can be worked on simultaneously by different roles
• Blockers: External dependencies (other teams, third-party APIs, approvals)

5. Risk Assessment

Evaluate risks for each work stream:

Common risks to evaluate:

• Breaking changes to existing APIs (backward compatibility)
• Database migration on large tables (performance, downtime)
• Cross-service coordination (deployment order matters)
• New dependencies or services (operational complexity)
• Security implications (new auth flows, data exposure)

6. Present the Plan

Compile the full plan and present to the user:

# Feature Plan: [Feature Name]

## Goal
[1–2 sentences]

## Architecture Impact
- Services affected: [list]
- New services: [if any]
- Database changes: [yes/no — summary]
- Infrastructure changes: [yes/no — summary]

## Work Packages

### Stream 1: [name] — `role-id`
| WP | Title | Complexity | Dependencies | Status |
|----|-------|------------|--------------|--------|
| WP-1 | [title] | M | — | planned |
| WP-2 | [title] | S | WP-1 | planned |

### Stream 2: [name] — `role-id`
| WP | Title | Complexity | Dependencies | Status |
|----|-------|------------|--------------|--------|
| WP-3 | [title] | L | WP-1 | planned |

## Critical Path
WP-1 → WP-2 → WP-5 (estimated: [timeframe])

## Risks
[table from Step 5]

## Next Step
Run `feature-dev` skill per work package, applying the designated role.

Wait for user approval. The user may reorder, split, merge, or remove work packages.

7. Multi-Reviewer Feedback Loop

The Feature Plan MUST pass a mandatory multi-reviewer cycle before handoff. Do not update FEATURES.md or hand off to the feature-dev skill until every reviewer returns approved.

Reviewer Panel

Apply each role below in sequence, treating each as an independent reviewer with its own pass over the plan:

• product-manager role — scope alignment with the PRD, WP coverage of acceptance criteria, risk coverage, correct prioritization, missing requirements
• solution-architect role — end-to-end design coherence, integration points, API contracts, cross-service coordination, tech stack fit per WP, non-functional requirements coverage
• system-architect role — system boundaries, component topology, data flow, ARCHITECTURE.md consistency, scalability and deployment implications of the WP decomposition

Cycle

1. For each role, produce a findings report: Critical (must fix), Major (should fix, justify if waived), Minor (optional), plus an explicit verdict: approved / approved-with-changes / rejected. Keep reports separate per role
2. Collect all three reports before editing
3. Apply all actionable findings to the plan (re-scope WPs, adjust dependencies, add missing streams, revise complexity). Resolve conflicts with priority Critical > Major > Minor; on ties, system-architect > solution-architect > product-manager. Record waivers with a one-line rationale
4. Re-run the same three reviewer passes against the updated plan
5. Loop until every reviewer returns approved with zero remaining critical/major findings

Termination: pass when all three are approved. On divergence (findings not shrinking, mutually exclusive asks) — pause and ask the user to arbitrate. Max 5 cycles before escalation.

Record the review history at the bottom of the plan as a ## Review History section listing each cycle's reviewer verdicts and open issue counts.

8. Update FEATURES.md

After the plan is approved, apply product-manager role and update FEATURES.md:

1. If FEATURES.md does not exist — create it at the project root
2. Add or update the feature entry with status planned
3. If the feature has a PRD or spec — save it in features/ directory and link from FEATURES.md

9. Handoff to Implementation

After approval, guide execution:

• Sequential (single developer): Execute WPs in dependency order using feature-dev skill for each
• Parallel (multiple developers/sessions): Assign independent WPs to separate sessions, each applying the appropriate role
• Track WP status: planned → in_progress → done
• Update the plan if scope changes during implementation

Integration

• Input: PRD, ARD, design doc, or user request
• Preceded by: product skill (produces PRD), architecture skill (produces ARD, design docs, API contracts, engineering estimates)
• Followed by: feature-dev skill (implementation per work package)
• Roles: product-manager role (requirements; Step 7 reviewer), solution-architect role + system-architect role (architecture; Step 7 reviewers), cloud-architect role (cloud platform), devops-architect role (CI/CD architecture), stack-specific roles (work packages)
• Skills: context-engineering skill (context pipeline design, RAG, memory, agent harness — for AI/LLM feature work packages)