/cf-plan

Context footprint: (high) — what does this mean?

The /cf-plan skill helps you design solutions before writing code. It clarifies requirements, explores your codebase, brainstorms approaches, and produces a detailed implementation plan — then optionally implements it for you.

Usage

/cf-plan [task description]
/cf-plan --fast [task description]
/cf-plan --hard [task description]
/cf-plan --auto [task description]    # Autopilot: review + fix + commit per phase, no prompts
/cf-plan --add-tests [task description]  # Implement with TDD (alias: --tdd)
/cf-plan --resume [plan-file-path]    # Resume an interrupted plan
/cf-plan --gui [task description]     # Also generate the human overview doc for this run (alias: --human)

Modes

• Normal (default) — Full workflow: discovery, agent-based exploration, brainstorming, validation, plan writing
• Fast (--fast) — Skip discovery and brainstorming. Inline codebase search instead of agents. Go straight to the plan. Single-phase fast plans stay in chat (no file written); multi-phase fast plans still save to disk. --fast --auto always writes a file. Fast mode never generates the human overview doc unless you pass --gui. Best for clear, single-module, additive tasks
• Hard (--hard) — Extra discovery round (risk & rollback), deeper blast-radius exploration, rollback strategy per task, review gates during implementation. Best for breaking changes, migrations, multi-module refactors
• Autopilot (--auto) — Orthogonal flag (combines with fast/hard/normal). After you approve the plan once, every phase runs end-to-end: dispatch tasks → auto /cf-review → if Critical or Important findings, auto-dispatch a fix task → re-review (max 2 review rounds) → single conventional commit per phase → continue to the next phase, never asking for confirmation between phases. Suggestions (💡) are logged in the commit body but don't block. The plan file embeds a ## AUTOPILOT contract section + auto: true frontmatter so the workflow survives long conversations where Claude's context may evict the skill. Resume (--resume) honors auto: true and continues in autopilot mode automatically.
• Resume (--resume <path>) — Resume an interrupted plan from where it left off. Skips already-completed tasks (✅) and re-runs any in-progress or pending ones
• GUI overview (--gui / --human) — Also generate the human-readable overview doc for this run (off by default — it costs extra tokens). Does not affect the agent plan files. Overrides fast mode, which otherwise skips the overview.

If no flag is given, the skill auto-detects the appropriate mode based on task signals (e.g. "just add a command like X" → fast, "rewrite the auth pipeline" → hard). Auto-detected modes are confirmed with you before proceeding. --auto is never auto-detected — it must be opted in explicitly.

Autopilot stop conditions

Autopilot only stops when one of these fires (otherwise it keeps going):

• A task fails after its single retry
• The fix cf-implementer returns failure (does not consume the second review round)
• Review round 2 still has 🚨 Critical or ⚠️ Important findings
• /cf-review output cannot be reliably parsed
• git commit fails repeatedly after hook fixes
• You explicitly interrupt (Ctrl+C, message)
• All phases reach ✅ DONE in the plan file

Workflow

1. Discovery & Brainstorm — Runs a focused discovery session in rounds: first asks probing questions and checks for official/built-in solutions before proposing anything (framework built-ins → official patterns → ecosystem standards), then challenges your initial approach using four attack angles (dependency failure, scale explosion, rollback cost, premise collapse), and finally presents 2–3 alternatives if needed. Respects your choice to skip brainstorming
2. Codebase Exploration — Launches the cf-explorer agent to gather context: project structure, affected files, existing patterns, and relevant tests
3. Brainstorm Approaches — Launches the cf-planner agent to generate 2–3 possible approaches, each with pros, cons, effort estimate, risk, and confidence level. Recommends one with rationale
4. Validate with You — Presents key findings, approaches, and open questions. Waits for your approval before writing anything
5. Write & Save the Plan — Breaks the approved approach into phased tasks with [parallel] or [sequential] markers, specific files, expected outcomes, and verification steps. Saves to docs/plans/
6. Offer Implementation — Asks if you want to start implementing. Executes phases in order: parallel phases launch all tasks concurrently via background cf-implementer agents; sequential phases run one task at a time. By default uses direct implementation; pass --add-tests (alias --tdd) to /cf-plan to enable TDD (RED → GREEN → REFACTOR) for all tasks. If an implementer fails, retries once with error context before escalating. Automatically runs /cf-review when done

Examples

# Normal — full workflow with brainstorming and agents
/cf-plan Build a REST API with JWT authentication and rate limiting

# Fast — skip discovery, inline search, straight to plan
/cf-plan --fast Add a new CLI command similar to cf-install

# Hard — deep exploration, rollback strategy, review gates
/cf-plan --hard Migrate from REST to GraphQL across all API endpoints

# Autopilot — approve once, then review+fix+commit per phase, no prompts
/cf-plan --auto Add a /healthz endpoint with tests and OpenAPI doc

# Combine: fast planning + autopilot execution
/cf-plan --fast --auto Add a hello.txt with a greeting

The skill will:

• Ask probing questions about your requirements, challenge assumptions, and suggest alternatives if needed (skipped in fast mode)
• Explore your existing codebase structure (inline search in fast mode, double exploration in hard mode)
• Propose 2–3 approaches with trade-offs (skipped in fast mode, 3–4 approaches with rollback strategies in hard mode)
• Present findings and wait for your approval (skipped in fast mode)
• Create a phased implementation plan with [parallel] and [sequential] markers (with rollback fields per task in hard mode)
• Save the plan to docs/plans/ as a subfolder (unless --fast with a single phase — those stay in chat); single-phase plans get README.md; multi-phase plans add per-phase files. Pass --gui to also generate the human overview doc for one run
• Offer to implement it — parallel phases run concurrently, sequential phases run one at a time (with review gates after every phase in hard mode)

When to Use

• Starting a new feature with uncertain scope → normal mode
• Adding something similar to existing patterns → --fast
• Redesigning a complex system → --hard
• Onboarding to unfamiliar codebases → normal mode
• Planning migrations or refactors → --hard

Output

Plans are saved to docs/plans/ (except --fast single-phase plans, which stay in chat). Every saved plan is a subfolder — even single-phase plans:

docs/plans/
  └── 2026-03-05-add-cli-command/
        ├── README.md          ← entry point with progress table
        └── overview.html      ← human-readable overview (only with --gui or disableGUIPlan: false)

Multi-phase plans (2+ phases) also include per-phase files:

docs/plans/
  └── 2026-03-05-rest-api-auth/
        ├── README.md          ← entry point with progress table + links
        ├── phase-1-setup.md
        ├── phase-2-auth.md
        ├── phase-3-tests.md
        └── overview.html      ← human-readable overview (only with --gui or disableGUIPlan: false)

Human overview doc

Optionally, /cf-plan can generate a concise, human-readable overview doc alongside the agent plan. It is decision-focused (what was chosen and why), includes a Mermaid diagram of the phases, and is a point-in-time snapshot — not updated as tasks complete. It is off by default because it costs extra tokens.

• Enable for one run: pass --gui (alias --human)
• Enable globally: set disableGUIPlan: false in .coding-friend/config.json
• Default format: overview.html — rendered in-browser, no Markdown viewer needed
• Alternate format: overview.md — set guiPlanFormat: "md" in config
• Never generated: in --inline mode (no files written). In fast mode it is skipped unless you pass --gui

Each plan (or chunk) includes:

• Context and problem statement
• Confirmed assumptions with basis
• Chosen approach and rationale
• Not building — explicit out-of-scope list to prevent scope creep during implementation
• Progress table — tracks each task with ⬜ TODO → 🔄 IN PROGRESS → ✅ DONE
• Phased tasks ([parallel] / [sequential]) with specific files and verification steps — no placeholders allowed (TBD, TODO, "implement later" are forbidden)
• Risk assessment and mitigations
• Migration & Rollback section (hard mode only) — overall rollback strategy, point of no return, incremental deployment options
• Next steps — a reminder to run /cf-review before committing

Recommended Workflow

/cf-plan → implement (implicitly via /cf-implementer) → /cf-review → /cf-commit

After implementation, /cf-review runs automatically — no need to trigger it manually before /cf-commit.