all-for-claudecode 2.1.0 → 2.2.0

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Automated pipeline for Claude Code — spec → plan → implement → review → clean",
-    "version": "2.1.0"
+    "version": "2.2.0"
   },
   "plugins": [
     {
       "name": "afc",
       "source": "./",
       "description": "Automated pipeline for Claude Code. Automates the full development cycle: spec → plan → implement → review → clean.",
-      "version": "2.1.0",
+      "version": "2.2.0",
       "category": "automation",
       "tags": ["pipeline", "automation", "spec", "plan", "implement", "review", "critic-loop"]
     }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "afc",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Automated pipeline for Claude Code. Automates the full development cycle: spec → plan → implement → review → clean.",
   "author": { "name": "jhlee0409", "email": "relee6203@gmail.com" },
   "homepage": "https://github.com/jhlee0409/all-for-claudecode",

package/README.md

@@ -1,82 +1,62 @@
+<div align="center">                                                                                                                                        
+  <img src="https://github.com/user-attachments/assets/9e23029e-e326-4cfa-b329-3bdd1006aecd" alt="all-for-claudecode" width="640" />                        
+</div>
+
 # all-for-claudecode
 
 **Claude Code plugin that automates the full development cycle — spec → plan → implement → review → clean.**
 
 [![npm version](https://img.shields.io/npm/v/all-for-claudecode)](https://www.npmjs.com/package/all-for-claudecode)
+[![npm downloads](https://img.shields.io/npm/dm/all-for-claudecode)](https://www.npmjs.com/package/all-for-claudecode)
 [![license](https://img.shields.io/github/license/jhlee0409/all-for-claudecode)](./LICENSE)
-[![test](https://img.shields.io/badge/tests-125%20passed-brightgreen)](#how-it-works)
-[![hooks](https://img.shields.io/badge/hooks-15%20events-blue)](#15-hook-events)
-[![commands](https://img.shields.io/badge/commands-18-orange)](#18-slash-commands)
-
-> Zero-dependency automation pipeline for Claude Code. One command (`/afc:auto`) runs the entire cycle: write specs, design plans, implement code, review quality, and clean up — all with built-in CI gates and critic loops.
-
-## What is all-for-claudecode?
+[![test](https://img.shields.io/badge/tests-passing-brightgreen)](#how-it-works)
 
-all-for-claudecode is a **Claude Code plugin** that transforms your development workflow into a fully automated pipeline. Instead of manually prompting Claude through each development phase, you run a single command and the pipeline handles everything — from writing feature specifications to final code review.
-
-- **18 slash commands** for every phase of development
-- **15 hook events** with 3 handler types (shell scripts, LLM prompts, subagents)
-- **5 project presets** for popular stacks (Next.js, React SPA, Express API, Monorepo)
-- **Persistent memory agents** that learn across sessions
-- **Built-in CI gates** that physically prevent skipping quality checks
+> One command (`/afc:auto`) runs the entire cycle. Zero runtime dependencies — pure markdown commands + bash hook scripts.
 
 ## Quick Start
 
-### Option A: Inside Claude Code (`/plugin`)
-
-```
+```bash
+# Option A: Inside Claude Code
 /plugin marketplace add jhlee0409/all-for-claudecode
 /plugin install afc@all-for-claudecode
-```
-
-Or use the interactive UI: type `/plugin` → Manage → Add marketplace → `jhlee0409/all-for-claudecode` → Discover → install **afc**.
 
-### Option B: One-line install (via npx)
-
-```bash
+# Option B: npx
 npx all-for-claudecode
 ```
 
-Interactive installer — choose scope (user / project / local) and done.
-
-### Option C: Claude Code CLI
-
-```bash
-claude plugin marketplace add jhlee0409/all-for-claudecode
-claude plugin install afc@all-for-claudecode --scope user
-```
-
-### Then, inside Claude Code:
+Then:
 
 ```
 /afc:init                              # Detect your stack, generate config
 /afc:auto "Add user authentication"    # Run the full pipeline
 ```
 
-That's it. The pipeline will:
+The pipeline will:
 1. Write a feature spec with acceptance criteria
-2. Design an implementation plan with file change map and dependency graph
-3. Implement each task with CI verification (tasks auto-generated from plan)
-4. Run a code review with security scan
+2. Design an implementation plan with file change map
+3. Implement tasks with CI gates (auto task decomposition + parallel execution)
+4. Run code review with architecture/security agent analysis
 5. Clean up artifacts and prepare for commit
 
-## Features
-
-### Full Auto Pipeline
+## How It Works
 
 ```
-/afc:auto "feature description"
-```
-
-Runs all 5 phases automatically with **Critic Loop** quality checks at each gate:
+/afc:auto "Add feature X"
 
-```
 Spec (1/5) → Plan (2/5) → Implement (3/5) → Review (4/5) → Clean (5/5)
+  │              │              │                │              │
+  │              │              │                │              └─ Artifact cleanup
+  │              │              │                └─ 8 perspectives + agent review
+  │              │              └─ Auto task decomposition, parallel execution, CI gates
+  │              └─ File change map, ADR recording, research persistence
+  └─ Acceptance criteria, pre-implementation gates
+
+Hooks run automatically at each step.
+CI failure → debug-based RCA (not blind retry).
+Critic Loops verify quality at each gate until convergence.
 ```
 
-### 18 Slash Commands
-
-**User and model (unrestricted):**
+## Slash Commands
 
 | Command | Description |
 |---|---|
@@ -85,14 +65,9 @@ Spec (1/5) → Plan (2/5) → Implement (3/5) → Review (4/5) → Clean (5/5)
 | `/afc:plan` | Design implementation plan with file change map |
 | `/afc:implement` | Execute code implementation with CI gates |
 | `/afc:test` | Test strategy planning and test writing |
-| `/afc:review` | Code review with security scanning |
+| `/afc:review` | Code review with architecture/security scanning |
 | `/afc:research` | Technical research with persistent storage |
 | `/afc:debug` | Bug diagnosis and fix |
-
-**User-only** (`disable-model-invocation: true`):
-
-| Command | Description |
-|---|---|
 | `/afc:init` | Project setup — detects stack and generates config |
 | `/afc:doctor` | Diagnose project health and plugin setup |
 | `/afc:architect` | Architecture analysis (persistent memory) |
@@ -100,16 +75,11 @@ Spec (1/5) → Plan (2/5) → Implement (3/5) → Review (4/5) → Clean (5/5)
 | `/afc:principles` | Project principles management |
 | `/afc:checkpoint` | Save session state |
 | `/afc:resume` | Restore session state |
-
-**Model-only** (`user-invocable: false`):
-
-| Command | Description |
-|---|---|
 | `/afc:tasks` | Task decomposition (auto-generated by implement) |
 | `/afc:analyze` | Verify artifact consistency |
 | `/afc:clarify` | Resolve spec ambiguities |
 
-### 15 Hook Events
+## Hook Events
 
 Every hook fires automatically — no configuration needed after install.
 
@@ -120,7 +90,7 @@ Every hook fires automatically — no configuration needed after install.
 | `PreToolUse` | Blocks dangerous commands (`push --force`, `reset --hard`) |
 | `PostToolUse` | Tracks file changes + auto-formats code |
 | `SubagentStart` | Injects pipeline context into subagents |
-| `Stop` | CI gate (shell) + code completeness check (AI agent) |
+| `Stop` | CI gate (shell) + code completeness check (agent) |
 | `SessionEnd` | Warns about unfinished pipeline |
 | `PostToolUseFailure` | Diagnostic hints for known error patterns |
 | `Notification` | Desktop alerts (macOS/Linux) |
@@ -130,25 +100,32 @@ Every hook fires automatically — no configuration needed after install.
 | `PermissionRequest` | Auto-allows CI commands during implement/review |
 | `ConfigChange` | Audits/blocks settings changes during active pipeline |
 | `TeammateIdle` | Prevents Agent Teams idle during implement/review |
+| `WorktreeCreate` | Sets up worktree isolation for parallel workers |
+| `WorktreeRemove` | Cleans up worktree after worker completion |
+
+Handler types: `command` (shell scripts, all events), `prompt` (LLM single-turn, TaskCompleted), `agent` (subagent with tools, Stop).
 
-### 3 Hook Handler Types
+## Persistent Memory Agents
 
-| Type | Description | Use Case |
-|---|---|---|
-| `command` | Shell script execution (deterministic) | All 15 events |
-| `prompt` | LLM single-turn evaluation (haiku) | TaskCompleted |
-| `agent` | Subagent with file access tools | Stop |
+| Agent | Role |
+|---|---|
+| `afc-architect` | Remembers ADR decisions and architecture patterns across sessions. Auto-invoked during Plan (ADR recording) and Review (architecture compliance). |
+| `afc-security` | Remembers vulnerability patterns and false positives across sessions. Auto-invoked during Review (security scanning). Runs in isolated worktree. |
+| `afc-impl-worker` | Parallel implementation worker. Receives pre-assigned tasks from orchestrator. Ephemeral (no memory). |
 
-### Persistent Memory Agents
+## Task Orchestration
 
-Two custom agents that **learn across sessions**:
+The implement phase automatically selects execution strategy:
+
+| Parallel tasks in phase | Mode |
+|---|---|
+| 0 | Sequential — one task at a time |
+| 1–5 | Parallel Batch — concurrent Task() calls |
+| 6+ | Swarm — orchestrator pre-assigns tasks to worker agents (max 5) |
 
-| Agent | Role | Memory |
-|---|---|---|
-| `afc-architect` | Architecture analysis — remembers ADR decisions and patterns | `.claude/agent-memory/afc-architect/` |
-| `afc-security` | Security scan — remembers vulnerability patterns and false positives | `.claude/agent-memory/afc-security/` |
+Dependencies are tracked via DAG. CI gate + Mini-Review + Auto-Checkpoint run at each phase boundary.
 
-### Project Presets
+## Project Presets
 
 | Preset | Stack |
 |---|---|
@@ -158,56 +135,30 @@ Two custom agents that **learn across sessions**:
 | `express-api` | Express + TypeScript + Prisma + Jest |
 | `monorepo` | Turborepo + pnpm workspace |
 
-## How It Works
-
-```
-┌─────────────────────────────────────────────┐
-│  /afc:auto "Add feature X"              │
-├─────────────────────────────────────────────┤
-│  Phase 1: Spec      → Critic Loop → Gate ✓   │
-│  Phase 2: Plan      → Critic Loop → Gate ✓   │
-│  Phase 3: Implement → Tasks auto-gen → CI ✓  │
-│  Phase 4: Review    → 8 perspectives → Gate ✓│
-│  Phase 5: Clean     → Artifacts removed      │
-├─────────────────────────────────────────────┤
-│  15 hooks run automatically at each step    │
-│  Stop/TaskCompleted gates block if CI fails │
-└─────────────────────────────────────────────┘
-```
-
 ## Configuration
 
-Initialize your project:
-
-```bash
+```
 /afc:init
 ```
 
-This detects your tech stack and generates `.claude/afc.config.md` with:
-- CI/lint/test commands
-- Architecture style and layers
-- Framework-specific settings
-- Code style conventions
+Detects your tech stack and generates `.claude/afc.config.md` with CI/lint/test commands, architecture rules, framework settings, and code style conventions.
 
 ## FAQ
 
-### What is all-for-claudecode?
-A Claude Code plugin that automates the entire development cycle (spec → plan → implement → review → clean) through 18 slash commands and 15 hook events.
-
-### How does it compare to manual Claude Code workflows?
-Instead of manually prompting each step, all-for-claudecode orchestrates the full cycle with built-in quality gates that physically prevent skipping CI or security checks.
-
 ### Does it work with any project?
-Yes. Run `/afc:init` to auto-detect your stack, or use one of the 5 presets (Next.js, React SPA, Express API, Monorepo, or generic template).
+Yes. Run `/afc:init` to auto-detect your stack, or pick a preset.
 
 ### Does it require any dependencies?
-No. Zero runtime dependencies — pure markdown commands + bash hook scripts.
+No. Pure markdown commands + bash hook scripts.
+
+### What happens if CI fails during the pipeline?
+Debug-based RCA: traces the error, forms a hypothesis, applies a targeted fix. Halts after 3 failed attempts with full diagnosis.
 
-### How do I install it?
-Inside Claude Code, run `/plugin marketplace add jhlee0409/all-for-claudecode` then `/plugin install afc@all-for-claudecode`. Alternatively, run `npx all-for-claudecode` from your terminal for a guided install.
+### Can I run individual phases?
+Yes. Each phase has its own command (`/afc:spec`, `/afc:plan`, `/afc:implement`, `/afc:review`). `/afc:auto` runs them all.
 
-### What Claude Code version is required?
-Claude Code with plugin support (2025+). The plugin uses standard hooks, commands, and agents APIs.
+### What are Critic Loops?
+Convergence-based quality checks after each phase. They evaluate output against criteria (completeness, feasibility, architecture compliance) and auto-fix issues until stable. 4 verdicts: PASS, FAIL, ESCALATE (asks user), DEFER.
 
 ## License
 

package/commands/analyze.md

@@ -22,13 +22,12 @@ model: haiku
 
 ## Config Load
 
-Read the following settings from `CLAUDE.md` or `.claude/CLAUDE.md` at the project root and assign to the `config` variable:
+**Always** read `.claude/afc.config.md` first. This file contains free-form markdown sections:
+- `## Architecture` — architecture pattern, layers, import rules (primary reference for this command)
+- `## Code Style` — language, naming conventions, lint rules
+- `## Project Context` — framework, state management, testing, etc.
 
-```
-config.architecture = the architecture pattern used in the project
-                      (e.g., "FSD", "Clean Architecture", "Layered", "Modular Monolith")
-                      → Architecture standard specified in CLAUDE.md. Assume "Layered Architecture" if not present.
-```
+If config file is missing: read `CLAUDE.md` for architecture info. Assume "Layered Architecture" if neither source has it.
 
 ## Execution Steps
 

package/commands/architect.md

@@ -2,7 +2,6 @@
 name: afc:architect
 description: "Architecture analysis and design advice"
 argument-hint: "[analysis target or design question]"
-disable-model-invocation: true
 context: fork
 agent: afc-architect
 allowed-tools:
@@ -27,13 +26,12 @@ model: sonnet
 
 ## Config Load
 
-Read the following settings from `CLAUDE.md` or `.claude/CLAUDE.md` at the project root and assign to the `config` variable:
+**Always** read `.claude/afc.config.md` first. This file contains free-form markdown sections:
+- `## Architecture` — architecture pattern, layers, import rules (primary reference for this command)
+- `## Code Style` — language, naming conventions, lint rules
+- `## Project Context` — framework, state management, testing, etc.
 
-```
-config.architecture = the architecture pattern used in the project
-                      (e.g., "FSD", "Clean Architecture", "Layered", "Modular Monolith")
-                      → Architecture standard specified in CLAUDE.md. Assume "Layered Architecture" if not present.
-```
+If config file is missing: read `CLAUDE.md` for architecture info. Assume "Layered Architecture" if neither source has it.
 
 ## Execution Steps
 

package/commands/auto.md

@@ -22,13 +22,11 @@ argument-hint: "[feature description in natural language]"
 ## Config Load
 
 **Always** read `.claude/afc.config.md` first (read manually if not auto-loaded above). Values defined in this file are referenced below as `{config.*}`:
-- `{config.ci}` — full CI command
-- `{config.gate}` — phase gate command
-- `{config.architecture}` — architecture style and rules
-- `{config.framework}` — framework characteristics (server/client boundary etc.)
-- `{config.code_style}` — code style rules
-- `{config.risks}` — project-specific risk patterns
-- `{config.mini_review}` — Mini-Review checklist items
+- `{config.ci}` — full CI command (from `## CI Commands` YAML)
+- `{config.gate}` — phase gate command (from `## CI Commands` YAML)
+- `{config.test}` — test command (from `## CI Commands` YAML)
+- `{config.architecture}` — architecture style and rules (from `## Architecture` section)
+- `{config.code_style}` — code style rules (from `## Code Style` section)
 
 If config file is missing:
 1. Ask the user: "`.claude/afc.config.md` not found. Run `/afc:init` to set up the project?"
@@ -115,7 +113,11 @@ If all checks pass, proceed to Phase 0.8.
 2. Run `{config.ci}` verification
    - On fail: **abort fast-path**, restart with full pipeline: `⚠ Fast-path aborted — change is more complex than expected. Running full pipeline.`
 3. If change touches > 2 files OR modifies any `.sh` script: **abort fast-path**, restart with full pipeline
-4. **Checkpoint**: `"${CLAUDE_PLUGIN_ROOT}/scripts/afc-pipeline-manage.sh" phase fast-path`
+4. **Checkpoint**:
+   ```bash
+   "${CLAUDE_PLUGIN_ROOT}/scripts/afc-pipeline-manage.sh" phase fast-path
+   "${CLAUDE_PLUGIN_ROOT}/scripts/afc-pipeline-manage.sh" ci-pass
+   ```
 5. Run `/afc:review` logic inline (mini-review only — single Critic pass)
 6. Run Phase 5 Clean logic (artifact cleanup, CI gate, pipeline flag release)
 7. Final output:
@@ -204,8 +206,8 @@ Execute `/afc:plan` logic inline:
      5. Acceptance anchor alignment: Implementation Context Acceptance Anchors faithfully reflect spec acceptance scenarios
    - **RISK criterion mandatory checks**:
      - Enumerate **at least 3** `{config.ci}` failure scenarios and describe mitigation
-     - Check each pattern in `{config.risks}` one by one
-     - Consider `{config.framework}` characteristics (server/client boundary etc.)
+     - Check each risk pattern described in config's Project Context section one by one
+     - Consider framework characteristics from config's Project Context (server/client boundary etc.)
    - **ARCHITECTURE criterion**: explicitly describe import paths for moved/created files and pre-validate against `{config.architecture}` rules
    - Each pass must **explicitly explore what was missed in the previous pass** ("Pass 2: {X} was missed in pass 1. Further review: ...")
    - FAIL → auto-fix and continue. ESCALATE → pause, present options, resume after response. DEFER → record reason, mark clean.
@@ -328,7 +330,7 @@ Execute `/afc:implement` logic inline — **follow all orchestration rules defin
    For each acceptance scenario in spec.md:
    - Map GWT to a test case: Given → Arrange, When → Act, Then → Assert
    - Target file: determined by the component/module referenced in the scenario
-   - Test file location: follows project convention ({config.testing} framework patterns)
+   - Test file location: follows project convention (test framework from Project Context)
    ```
 3. Run `{config.test}` to verify tests pass against the implementation
    - If tests fail → this reveals a gap between spec and implementation:
@@ -402,7 +404,7 @@ Execute `/afc:review` logic inline — **follow all review perspectives defined
    - A. Code Quality — `{config.code_style}` compliance (direct review)
    - B. Architecture — **delegated to afc-architect agent** (persistent memory, ADR-aware)
    - C. Security — **delegated to afc-security agent** (persistent memory, false-positive-aware)
-   - D. Performance — `{config.framework}`-specific patterns (direct review)
+   - D. Performance — framework-specific patterns from Project Context (direct review)
    - E. Project Pattern Compliance — conventions and idioms (direct review)
    - **F. Reusability** — DRY, shared utilities, abstraction level (direct review)
    - **G. Maintainability** — AI/human comprehension, naming clarity, self-contained files (direct review)

package/commands/checkpoint.md

@@ -2,7 +2,6 @@
 name: afc:checkpoint
 description: "Save session state"
 argument-hint: "[checkpoint message]"
-disable-model-invocation: true
 model: haiku
 allowed-tools:
   - Read

package/commands/debug.md

@@ -48,7 +48,7 @@ Proceed in order:
 
 1. **Error trace**: extract file:line from error message/stack trace → read that code
 2. **Data flow**: trace backwards from the problem point (where did the bad data come in?)
-3. **State analysis**: check relevant {config.state_management} cache state
+3. **State analysis**: check relevant state management cache state (from Project Context)
 4. **Recent changes**: check recent changes with `git log --oneline -10 -- {related files}`
 5. **Race conditions**: check for timing issues between async operations
 

package/commands/doctor.md

@@ -2,7 +2,6 @@
 name: afc:doctor
 description: "Diagnose project health and plugin setup"
 argument-hint: "[--verbose]"
-disable-model-invocation: true
 allowed-tools:
   - Read
   - Grep
@@ -49,7 +48,7 @@ Run ALL checks regardless of earlier failures. Do not short-circuit.
 | Check | How | Pass | Fail |
 |-------|-----|------|------|
 | Config file exists | Read `.claude/afc.config.md` | File exists | Fix: run `/afc:init` |
-| Required sections present | Grep for `## CI Commands`, `## Architecture`, `## Code Style`, `## Framework` | All 4 sections found | Fix: add missing section to `.claude/afc.config.md` or re-run `/afc:init` |
+| Required sections present | Grep for `## CI Commands`, `## Architecture`, `## Code Style` | All 3 sections found | Fix: add missing section to `.claude/afc.config.md` or re-run `/afc:init` |
 | Gate command defined | Grep for `gate:` inside `## CI Commands` section | `gate:` field found | Fix: add `gate:` field to `## CI Commands` section |
 | CI command runnable | Extract CI command from config, run it | Exits 0 | ⚠ Warning: CI command failed. Check `{config.ci}` in afc.config.md |
 | Gate command runnable | Extract gate command from config, run it | Exits 0 | ⚠ Warning: gate command failed. Check `{config.gate}` in afc.config.md |

package/commands/ideate.md

@@ -0,0 +1,191 @@
+---
+name: afc:ideate
+description: "Explore and structure a product idea"
+argument-hint: "[rough idea or problem statement]"
+allowed-tools:
+  - Read
+  - Write
+  - Glob
+  - Grep
+  - WebSearch
+  - WebFetch
+model: sonnet
+---
+
+# /afc:ideate — Explore and Structure a Product Idea
+
+> Transforms a rough idea, problem statement, or inspiration into a structured product brief (ideate.md).
+> This is a **pre-spec exploration** tool — use it when you don't yet know exactly what to build.
+> The output feeds directly into `/afc:spec` as input.
+
+## Relationship to Other Commands
+
+```
+afc:ideate (what to build?) → afc:spec (how to specify it) → afc:plan → afc:implement → ...
+```
+
+- **ideate** = "I have an idea but haven't decided the scope, audience, or approach yet"
+- **spec** = "I know what to build and need a formal specification"
+- ideate is **never** part of the auto pipeline — it's a standalone exploration tool
+
+## Arguments
+
+- `$ARGUMENTS` — (required) One of:
+  - Rough idea: `"real-time collaborative whiteboard"`
+  - Problem statement: `"users keep losing unsaved work when the browser crashes"`
+  - Reference URL: `"https://example.com/competitor-product"` (fetched and analyzed)
+  - File path: `"./meeting-notes.md"` (read and extracted)
+
+## Execution Steps
+
+### 1. Parse Input
+
+Determine the input type and extract raw content:
+
+1. **If `$ARGUMENTS` starts with `http://` or `https://`**:
+   - Fetch content via WebFetch
+   - Extract: product name, key features, target audience, value proposition
+   - Frame as: "Build something similar/better that addresses {gap}"
+
+2. **If `$ARGUMENTS` is a file path** (contains `/` or ends with `.md`/`.txt`):
+   - Read the file content
+   - Extract: action items, feature requests, pain points, user feedback
+   - Frame as: structured requirements from raw notes
+
+3. **Otherwise**: treat as a natural language idea/problem statement
+
+### 2. Market & Context Research
+
+Perform lightweight research to ground the idea in reality:
+
+1. **Competitive landscape** (WebSearch):
+   - Search: `"{core concept}" tool OR app OR service {current year}`
+   - Identify 3-5 existing solutions
+   - Note: what they do well, what gaps exist
+
+2. **Technology feasibility** (WebSearch, optional):
+   - If the idea involves unfamiliar tech: search for current state and constraints
+   - Tag findings with `[RESEARCHED]`
+
+3. **Target user validation**:
+   - Who would use this? Why? What's their current workaround?
+
+### 3. Explore Existing Codebase (if applicable)
+
+If running inside a project with source code:
+
+1. Check if any related functionality already exists (Glob/Grep)
+2. If found: note as "Existing foundation" — ideate around extending, not rebuilding
+3. If no codebase or greenfield: skip this step
+
+### 4. Write Product Brief
+
+Create `.claude/afc/ideate.md` (overwrite if exists after confirmation):
+
+```markdown
+# Product Brief: {idea name}
+
+> Created: {YYYY-MM-DD}
+> Status: Exploration
+> Input: {original $ARGUMENTS summary}
+
+## Problem Statement
+{What problem does this solve? Who has this problem? How painful is it?}
+{2-3 sentences, specific and measurable where possible}
+
+## Target Users
+
+### Primary Persona
+- **Who**: {role/demographic}
+- **Context**: {when/where they encounter the problem}
+- **Current workaround**: {what they do today}
+- **Pain level**: {High/Medium/Low — with justification}
+
+### Secondary Persona (if applicable)
+{same format}
+
+## Value Proposition
+{One sentence: "For {persona} who {need}, this {product} provides {benefit} unlike {alternatives}"}
+
+## Core Features (MoSCoW)
+
+### Must Have (MVP)
+1. {feature} — {why it's essential}
+2. {feature} — {why it's essential}
+3. {feature} — {why it's essential}
+
+### Should Have (v1.1)
+1. {feature} — {value added}
+
+### Could Have (future)
+1. {feature} — {potential value}
+
+### Won't Have (explicit scope cut)
+1. {feature} — {why excluded}
+
+## User Journey (primary flow)
+
+```mermaid
+graph LR
+    A[Entry Point] --> B[Core Action]
+    B --> C[Key Decision]
+    C --> D[Success State]
+    C --> E[Error/Edge Case]
+```
+
+{Describe the 3-5 step primary user flow in plain text as well}
+
+## Competitive Analysis
+
+| Aspect | {Competitor 1} | {Competitor 2} | This Product |
+|--------|---------------|---------------|-------------|
+| Core strength | {X} | {X} | {X} |
+| Key weakness | {X} | {X} | {X} |
+| Pricing | {X} | {X} | {X} |
+| Differentiator | — | — | {what makes this unique} |
+
+## Open Questions
+- {Decision that needs user input before proceeding to spec}
+- {Technical uncertainty that affects scope}
+- {Business assumption that should be validated}
+
+## Suggested Next Steps
+1. Resolve Open Questions above
+2. Run `/afc:spec {refined feature description}` to formalize as a specification
+3. {Any other recommended action}
+
+## Research Sources
+- [{source title}]({url}) — {what was learned}
+```
+
+### 5. Interactive Refinement
+
+After writing the initial brief, present key decisions to the user:
+
+1. **Scope check**: "The MVP has {N} features. Does this feel right, or should we cut/add?"
+2. **Persona validation**: "Is {persona} the right primary user?"
+3. **Open questions**: present the top 2 unresolved questions via AskUserQuestion
+
+Apply user feedback directly into ideate.md.
+
+### 6. Final Output
+
+```
+Ideation complete
+├─ .claude/afc/ideate.md
+├─ Personas: {count}
+├─ MVP features: {count}
+├─ Competitors analyzed: {count}
+├─ Open questions: {count}
+├─ Research sources: {count}
+└─ Next step: /afc:spec "{suggested feature description}"
+```
+
+## Notes
+
+- **This is exploration, not specification**. Do not write acceptance criteria, system requirements, or FR/NFR numbers — that belongs in `/afc:spec`.
+- **ideate.md lives at `.claude/afc/ideate.md`** (project-level, not feature-level) because ideation may span multiple features.
+- **Not part of the auto pipeline**. ideate is manually invoked when a developer needs to think through an idea before committing to a spec.
+- **One ideate.md per project** — overwrite on re-run (with confirmation). If you need to preserve a previous ideation, rename it first.
+- **Competitive analysis is lightweight** — 3-5 competitors max. Deep market research is not the goal; grounding the idea in reality is.
+- **Mermaid diagrams are optional** — only include if the user flow benefits from visualization. Do not force diagrams for simple concepts.