feature-plan

What this skill does

# 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:**

```bash
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](#feature-target)
- [File Organization](#file-organization)
- [Workflow Overview](#workflow-overview)
- [Phase Details](#phase-details)
- [Completing a Feature](#completing-a-feature)
- [Error Handling](#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](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:
  ```bash
  python3 ${CLAUDE_PLUGIN_ROOT}/skills/shared/lib/statusline.py set <feature-id>
  ```

### Phase 2: Requirements Deep Dive

**See**: [requirements.md](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](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](implementation.md)

- Create plan.md with implementation steps
- **After writing plan.md, regenerate the dashboard** by running:
  ```bash
  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:

```markdown
---
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!**