/plan — Explore + Create Implementation Plan

Explores the codebase and produces a structured implementation plan. Optionally materializes Beads tasks.

Usage

/plan add user settings page
/plan T-42                     # Plan for an existing task
/plan refactor auth module --tasks   # Also create Beads tasks from the plan

---

Step 1 — Load Knowledge (mandatory)

Before any code exploration, load the relevant knowledge files:

cat knowledge/_shared.yaml
cat knowledge/repos/<repo>.yaml 2>/dev/null || echo "no knowledge file for <repo>"   # For each affected repo

A repo has a knowledge file only after /add-repo or /sync-knowledge has been run for it; knowledge/repos/ is empty in a fresh checkout, and the harness itself has none.

If a knowledge file is missing or stale (>50 commits behind HEAD):

• Warn: "knowledge/<repo>.yaml may be missing or stale — consider running /sync-knowledge <repo>"
• Proceed anyway with a note that exploration results may supersede stale knowledge

---

Step 1b — Planner mode (short or vague prompts)

If the user input is only one to four sentences with no Beads task id and no detailed spec:

1. Read .claude/agents/planner.md and adopt the Planner role before deep exploration.
2. Expand the prompt into a product spec (overview, numbered features / user stories, non-goals, testable signals). Save to plans/drafts/<slug>-product-spec.md.
3. Use that spec as the source of truth for exploration in Step 3 and the implementation plan in Step 4.

If the user already provided a detailed spec or bd show task context, skip this step.

---

Step 2 — Reuse Verification

Search for existing implementations before planning anything new:

# Hooks
grep -rE "^export function use" src/ --include="*.ts" --include="*.tsx" -l

# Types and interfaces
grep -rE "^export (interface|type)" src/ --include="*.ts" -l

# Components
grep -rE "^export (default|function|const)" src/components/ --include="*.tsx" -l

# Utilities
grep -rE "^export (function|const|class)" src/utils/ --include="*.ts" -l

Note any existing implementations relevant to the plan.

---

Step 3 — Explore

Use an Explore subagent (or explore directly) to map the codebase:

For small scope (single feature area):

• Read 5-10 key files relevant to the task
• Trace the data flow from entry point to the affected code

For large scope (cross-cutting concern):

• Spawn an Explore agent: "Explore <repo> and map all files related to <topic>. Focus on: <areas>. Report file paths, key functions, and integration points."
• Read the agent's findings, then read the specific files it identifies

Goal: understand the codebase well enough to write a complete, accurate plan with real file paths and function names.

---

Step 4 — Write Plan

Write to plans/drafts/<TASK-ID>.md (create plans/drafts/ if needed). If no task ID: use a slug from the description.

Plan format:

# Plan: <TASK-ID> — <title>
Generated: <date>
Repo: <repo>

## Summary
<~100 tokens: what is being built, why, and the approach in plain language>

## Existing Code to Reuse
- `src/hooks/useAuth.ts` — auth state hook, extend it for settings
- `src/types/user.ts` — UserProfile type already has the needed fields

## Implementation Steps
1. Add settings schema to `src/types/user.ts`
   - Extend `UserProfile` with `settings: UserSettings`
   - Define `UserSettings` interface

2. Create `src/api/settings.ts`
   - `getSettings(userId: string): Promise<UserSettings>`
   - `updateSettings(userId: string, patch: Partial<UserSettings>): Promise<void>`

3. Create `src/hooks/useUserSettings.ts`
   - Wraps `getSettings` / `updateSettings`
   - Returns `{ settings, loading, error, update }`

4. Create `src/components/UserSettingsPage.tsx`
   - Form bound to `useUserSettings`
   - Save/cancel buttons, loading state, error display

5. Add route in `src/App.tsx`
   - `/settings` → `<UserSettingsPage />`

## Files to Modify
| File | Change |
|------|--------|
| `src/types/user.ts` | Add UserSettings interface |
| `src/App.tsx` | Add /settings route |

## Files to Create
| File | Purpose |
|------|---------|
| `src/api/settings.ts` | Settings API calls |
| `src/hooks/useUserSettings.ts` | Settings state hook |
| `src/components/UserSettingsPage.tsx` | Settings UI |
| `src/api/settings.test.ts` | API unit tests |
| `src/hooks/useUserSettings.test.ts` | Hook unit tests |

## Test Strategy
- Unit: `useUserSettings` — loading state, error state, successful update
- Unit: `settings.ts` API — mock fetch, verify request format
- Integration: settings page saves and persists across page refresh
- Edge: empty settings object, network error, validation failure

## Validation Commands
\`\`\`bash
bun run typecheck
bun test src/api/settings.test.ts
bun test src/hooks/useUserSettings.test.ts
\`\`\`

## Estimated Scope
- Files: 5 new, 2 modified
- Complexity: Medium
- Estimated time: 90 minutes

## Interfaces (if this plan produces shared APIs)
\`\`\`typescript
export function useUserSettings(userId: string): {
  settings: UserSettings | null;
  loading: boolean;
  error: Error | null;
  update: (patch: Partial<UserSettings>) => Promise<void>;
}
\`\`\`

---

Step 5 — Present Plan

Output a summary to the user:

Plan ready: plans/drafts/<TASK-ID>.md

Summary: <2-sentence description>
Scope: <n> files (<n> new, <n> modified), ~<n> minutes
Complexity: Low | Medium | High

Key decisions:
- <decision 1 and why>
- <decision 2 and why>

---

Step 6 — Materialize Beads (with --tasks flag only)

If --tasks was passed:

For each implementation step in the plan:

bd create \
  --type task \
  --title "[<repo>] <step description>" \
  --priority <value> \
  --acceptance "<acceptance criterion from the step>"

Pick <value> with .claude/skills/beads-priority-assignment/SKILL.md (critical-path or high-risk steps → high / critical; later optional steps → medium / low).

Add sequential dependencies (step 2 requires step 1):

bd dep add <step-2-id> <step-1-id>   # the later step first, the earlier step second

If there are 4+ tasks: create a parent feature:

bd create --type feature --title "<overall feature title>" --priority <value>
# then add parent relationship to each task

Use the same skill for the parent feature priority (often medium unless the plan is release-blocking).

Report: "Created N Beads tasks. Run /go to start work."

---

Staleness Warning

After loading knowledge files, check commit distance:

git log --oneline knowledge/repos/<repo>.yaml -- | head -1
git rev-list --count HEAD   # compare against knowledge file's last commit

If >50 commits behind: ⚠ knowledge/<repo>.yaml is stale (>50 commits). Run /sync-knowledge <repo>.