feature-plan

name	feature-plan
description	Start implementing a feature from the backlog with adaptive agent dispatch. Use when user wants to begin work on a backlog item, start implementation, or mentions a specific feature ID to work on.
user-invocable	true

Implement Feature Command

You are executing the IMPLEMENT FEATURE workflow - a comprehensive feature kickoff process that ensures proper planning before any implementation begins.

First Step (Do This Now)

Scan the feature directories to generate a live dashboard:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/shared/lib/run_dashboard.py <project_root> --stdout

This scans docs/features/*/ to show all features by status. If it fails or docs/features/ doesn't exist, the project hasn't been set up for feature tracking yet.

Note: To start a feature, create docs/features/[id]/plan.md. The PostToolUse hook automatically updates the local DASHBOARD.md - do NOT edit it directly.

Contents

• Feature Target
• File Organization
• Workflow Overview
• Phase Details
• Completing a Feature
• Error Handling

---

Feature Target

$ARGUMENTS

If no specific feature ID was provided above, you will help the user select from the backlog.

If $ARGUMENTS starts with cat:, filter the backlog to only show features matching that category (case-insensitive) and let the user select from the filtered list.

---

File Organization

Features are stored in directories with status determined by file presence:

docs/features/
├── DASHBOARD.md              # Auto-generated, read-only for Claude
├── my-feature/
│   ├── idea.md               # Problem statement + metadata (backlog)
│   ├── plan.md               # Implementation plan (in-progress)
│   └── shipped.md            # Completion notes (completed)
└── another-feature/
    └── idea.md

Status Detection by File Presence

Files Present	Status
idea.md only	backlog
idea.md + plan.md	in-progress
idea.md + plan.md + shipped.md	completed

Key Principles:

• /feature-capture creates idea.md only (backlog status)
• /feature-plan adds plan.md (changes to in-progress)
• /feature-review-plan opens a draft PR for external plan review
• /feature-review-impl submits implementation for external code review
• /feature-ship adds shipped.md and merges the PR (changes to completed)
• DASHBOARD.md is auto-regenerated by hooks - never edit directly

---

Workflow Overview

This command orchestrates a 6-phase workflow:

Phase	Name	Purpose
1	Feature Selection	Choose from backlog or validate provided ID
2	Requirements Analysis	Deep dive with project-manager agent
3	System Design	Architecture planning (adaptive based on feature type)
4	Implementation Plan	Create detailed plan document
5	Write plan.md	Write plan.md to transition to in-progress
6	Kickoff Summary	Create todos and provide clear next steps

---

Phase Details

Phase 1: Feature Selection

See: selection.md

• Run run_dashboard.py --stdout and find/select feature from Backlog section
• Read the feature's idea.md for full details
• Verify feature is in backlog status (no plan.md exists yet)
• Handle already-in-progress features with user options

State Guard

After reading idea.md, check the state: field:

State	Action
active (or absent)	Proceed normally
paused	Stop. Tell the user: "<id> is paused (waiting on: <pausedReason>). Resume with /feature-state <id> active before planning."
replaced	Stop. Tell the user: "<id> was replaced by <replacedBy>. Plan that one instead, or /feature-state <id> active to revive."
abandoned	Stop. Tell the user: "<id> was abandoned (<abandonedReason>). /feature-state <id> active to revive."

In all stop cases, do NOT create a plan.md.

• Set statusline immediately after selection by running:

  python3 ${CLAUDE_PLUGIN_ROOT}/skills/shared/lib/statusline.py set <feature-id>
  

Phase 2: Requirements Deep Dive

See: requirements.md

• Read idea.md for problem statement and context
• Optional: Run code-archaeologist for legacy code
• Run project-manager agent for requirements analysis
• Effort-based scaling (Small/Medium/Large)

Phase 3: System Design (Adaptive)

See: design.md

• Classify feature type (Backend/Frontend/Full-Stack/Infrastructure)
• Dispatch appropriate specialized agents
• Save design documents to feature directory

Feature Type	Agents Used
Backend-Only	api-designer
Frontend-Only	ux-optimizer + frontend-architect
Full-Stack	api-designer + frontend-architect + integration-designer
UI-Heavy	ux-optimizer → then full-stack agents
Infrastructure	system-designer

Phases 4-6: Implementation & Kickoff

See: implementation.md

• Create plan.md with implementation steps
• After writing plan.md, regenerate the dashboard by running:

  python3 ${CLAUDE_PLUGIN_ROOT}/skills/shared/lib/run_dashboard.py <project_root>
  

• Stage changes with git
• Display kickoff summary with next steps

---

plan.md Format

Write plan.md with YAML frontmatter followed by content:

---
started: YYYY-MM-DD
---

# Implementation Plan: [Feature Name]

## Overview
Brief summary of what will be implemented...

## Implementation Steps
- [ ] Step 1: Description
- [ ] Step 2: Description
- [ ] Step 3: Description

## Technical Decisions
Key architectural choices made during design...

## Testing Strategy
How this feature will be tested...

## Risks & Mitigations
Any identified risks and how they'll be addressed...

---

Next Steps After Planning

The end-to-end workflow is:

/feature-capture → /feature-plan → /feature-review-plan → /feature-implement → /feature-review-impl → /feature-ship

The immediate next step after planning:

1. /feature-review-plan [feature-id] — create a feature branch, open a draft PR, submit the plan for external review (Gemini/Codex)
2. /feature-review-plan [feature-id] --respond — address plan review feedback (repeat as needed)
3. /feature-implement [feature-id] — write code following the approved plan
4. /feature-review-impl [feature-id] — submit implementation for external code review
5. /feature-review-impl [feature-id] --respond — address code review feedback (repeat as needed)
6. /feature-ship [feature-id] — write shipped.md, merge the PR into dev, clean up the branch

Do NOT skip review steps. /feature-review-plan gets the plan reviewed before coding. /feature-review-impl gets the code reviewed before shipping.

---

Error Handling

Error	Resolution
DASHBOARD.md not found	Create it with generate-dashboard.sh
Feature not found	List available items, ask to select
Agent errors	Retry with more context or continue without that design phase
Directory missing	Create docs/features/ if needed
Already in progress	Ask if user wants to continue existing work

---

Philosophy: "Never Code Without a Plan"

By completing these 6 phases, you ensure:

• Requirements are clearly understood
• Architecture is properly designed
• Implementation is broken into manageable steps
• Documentation will stay current
• Testing is considered upfront
• Risks are identified and mitigated

---

Let's get started!