/plan

Create PLAN.md with phase-based breakdown for tasks, spikes, and bugs.

Usage

bash
1/plan 001                    # Create plan for issue 001 (auto-detect project)
2/plan 001 --project coordinatr  # Explicit project
3/plan SPIKE-003              # Plan for a spike (creates exploration plans)
4/plan 003 --second-opinion   # Get peer review from Gemini CLI before finalizing

Issue Type Detection

Execution Flow

For Task/Bug

1. Load Context:

   bash
   1Read: ideas/[project]/issues/###-*/TASK.md (or BUG.md)
   2Read: spaces/[project]/docs/specs/*.md (if implements: field exists)
   3Glob: spaces/[project]/docs/adrs/ADR-*.md
   4Glob: resources/research/*.md

   If the issue has an implements: field, load that specific spec section:

   bash
   1Read: spaces/[project]/docs/specs/required-features.md  # Extract relevant section

2. Cross-Project Pattern Search:

   bash
   1# Search other projects for similar implementations
   2Grep: spaces/*/src/ for relevant patterns

   Include relevant references in plan:

   markdown
   1## Related Implementations
   2
   3Found similar patterns in other projects:
   4- `spaces/yourbench/src/auth/clerk.ts` - Clerk auth setup
   5- `spaces/coordinatr/src/lib/session.ts` - Session handling

3. Library Documentation (automatic for integrations):

   MANDATORY when task involves:

   • Installing/configuring external libraries or SDKs
   • Framework integrations (auth providers, databases, APIs)
   • Third-party services (Clerk, Stripe, AWS services, etc.)

   Process:

   bash
   1# 1. Resolve library ID
   2mcp__context7__resolve-library-id: {libraryName}
   3
   4# 2. Fetch current documentation
   5mcp__context7__query-docs: {context7CompatibleLibraryID}
   6
   7# 3. Search for recent patterns/best practices
   8WebSearch: "{library} {framework} integration 2026"

   Document findings:

   markdown
   1## Library Documentation Validation
   2
   3**{Library Name}** (validated YYYY-MM-DD):
   4- Current version: X.Y.Z
   5- Key integration patterns: [summary]
   6- Recommended approach: [based on current docs]

4. Generate Plan:

   • Break work into logical phases
   • Each phase has clear deliverables
   • Include checkpoints between phases
   • Add "Done When" criteria

5. Write PLAN.md:

   • Present phases, estimated effort, dependencies
   • Include "Library Documentation Validation" section (if applicable)
   • Include "Second Opinion Analysis" section (if requested)

6. Commit Suggestion:

   • Ask: "Commit PLAN.md to ideas repo? (yes/no)"

For Spike (Exploration)

1. Load Context: Read SPIKE.md (questions, success criteria, time box)

2. Gather Approaches:

   • Ask: "How many approaches to explore?" → N
   • For each: "Describe approach N?"

3. Generate: Create PLAN-N.md for each approach

4. Commit Suggestion: Ask to commit all plan files

Task Plan Example

markdown
1# Implementation Plan: 001 Research Auth Patterns
2
3## Overview
4Research authentication patterns for Coordinatr's multi-tenant architecture.
5
6## Phase 1: Survey Existing Solutions
7
8### 1.1 - Research Auth Libraries
9- [ ] Review Better Auth documentation
10- [ ] Compare with Auth.js and Lucia
11- [ ] Document trade-offs
12
13### 1.2 - Multi-Tenant Patterns
14- [ ] Research team-based auth patterns
15- [ ] Review how Slack, Linear handle it
16- [ ] [CHECKPOINT] Summary document complete
17
18## Phase 2: Architecture Proposal
19
20### 2.1 - Draft Architecture
21- [ ] Create architecture diagram
22- [ ] Document token strategy
23- [ ] Define permission model
24
25### 2.2 - Review
26- [ ] Self-critique against requirements
27- [ ] [CHECKPOINT] Architecture doc complete
28
29## Done When
30- [ ] Auth library recommendation documented
31- [ ] Architecture proposal in ideas/coordinatr/docs/
32- [ ] Trade-offs and risks identified

Second Opinion Feature

What: Optional peer review from Gemini CLI before finalizing plans.

Usage: Pass --second-opinion flag to trigger Gemini review with Context7 validation.

Process:

1. Send plan to Gemini CLI for review
2. Validate each recommendation against Context7 docs
3. Claude makes final decision on each:
   • ✅ ACCEPT: Recommendation validated AND improves plan
   • ⚠️ MODIFY: Good idea but needs adjustment
   • ❌ REJECT: Invalid or not applicable
4. Document all decisions in "Second Opinion Analysis" section

Requirements:

• Gemini CLI installed and functional
• --second-opinion flag explicitly passed

Graceful degradation: If Gemini unavailable, proceeds with Claude-only plan.

Workflow

/spec → /issue → /plan {ID} → (work phases) → /complete {ID}
                    ↓
          Load spec section from implements: field

Creates:

• Task/Bug: ideas/{project}/issues/###-*/PLAN.md
• Spike: ideas/{project}/issues/###-*/PLAN-1.md, PLAN-2.md, etc.