all-for-claudecode 2.0.0 → 2.2.0

package/commands/clarify.md

@@ -3,6 +3,12 @@ name: afc:clarify
 description: "Resolve spec ambiguities"
 argument-hint: "[focus area: security, performance, UI flow]"
 user-invocable: false
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
 model: sonnet
 ---
 # /afc:clarify — Resolve Spec Ambiguities
@@ -16,7 +22,7 @@ model: sonnet
 
 ## Config Load
 
-**Must** read `.claude/afc.config.md` first. Stop if the config file is not present.
+**Must** read `.claude/afc.config.md` first. If the config file is not present, print "`.claude/afc.config.md` not found. Run `/afc:init` first." then **abort**.
 
 ## Execution Steps
 
@@ -32,6 +38,7 @@ Scan across 10 categories:
 
 | # | Category | What to find |
 |---|----------|-------------|
+| 0 | Necessity | Is this feature truly needed? Does it already exist? Is the cost justified by the benefit? |
 | 1 | Feature scope | Features with unclear boundaries |
 | 2 | Domain/data | Incomplete entity relationships or field definitions |
 | 3 | UX flow | Missing user journey steps |

package/commands/debug.md

@@ -2,6 +2,13 @@
 name: afc:debug
 description: "Bug diagnosis and fix"
 argument-hint: "[bug description, error message, or reproduction steps]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
 model: sonnet
 ---
 
@@ -16,7 +23,12 @@ model: sonnet
 
 ## Config Load
 
-**Always** read `.claude/afc.config.md` first. Abort if config file is missing.
+**Always** read `.claude/afc.config.md` first.
+
+If config file is missing:
+1. Ask the user: "`.claude/afc.config.md` not found. Run `/afc:init` to set up the project?"
+2. If user accepts → run `/afc:init`, then **restart this command** with the original `$ARGUMENTS`
+3. If user declines → **abort**
 
 ## Execution Steps
 
@@ -36,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
 
@@ -46,15 +58,28 @@ List possible causes as a **hypothesis list**:
 
 ```markdown
 ### Hypotheses
+0. **[Not a Bug?]** {intended behavior explanation}: {evidence from docs/code/spec}
 1. **[High probability]** {cause1}: {evidence}
 2. **[Medium probability]** {cause2}: {evidence}
 3. **[Low probability]** {cause3}: {evidence}
 ```
 
-Verify starting from highest probability.
+**Always evaluate hypothesis 0 first.** Check:
+- Is this behavior documented or specified? (README, comments, spec, CLAUDE.md)
+- Does the code explicitly handle this case? (intentional logic, not missing logic)
+- Is the user's expectation based on a misunderstanding of the design?
+
+If hypothesis 0 is confirmed (not a bug):
+- Report: "This appears to be intended behavior: {explanation with evidence}."
+- Do **not** modify code. Suggest documentation improvement if the behavior is non-obvious.
+- Skip Steps 4-6. Go directly to Final Output with verdict: `"Not a bug — intended behavior."`
+
+If hypothesis 0 is rejected: verify remaining hypotheses starting from highest probability.
 
 ### 4. Implement Fix
 
+**Precondition**: Only proceed if a genuine bug was confirmed in Step 3 (hypothesis 0 rejected).
+
 1. **Minimal change principle**: change only the minimum code required to fix the bug
 2. **Impact analysis**: verify what effect the fix has on other code
 3. **Apply fix**
@@ -101,6 +126,7 @@ Only write if the pattern is new and actionable. Generic observations are prohib
 
 ### 8. Final Output
 
+**If bug confirmed and fixed:**
 ```
 Debug complete
 ├─ Root cause: {one-line summary}
@@ -110,6 +136,16 @@ Debug complete
 └─ Impact scope: {affected components/features}
 ```
 
+**If not a bug (intended behavior):**
+```
+Debug complete
+├─ Verdict: Not a bug — intended behavior
+├─ Explanation: {why this behavior is correct}
+├─ Evidence: {code path, documentation, or spec reference}
+├─ Fixed files: none
+└─ Suggestion: {documentation improvement if non-obvious, or "none"}
+```
+
 ## Debugging Checklist (applied automatically)
 
 Always check the Debugging Checklist from CLAUDE.md:
@@ -121,6 +157,7 @@ Always check the Debugging Checklist from CLAUDE.md:
 
 ## Notes
 
+- **Not every report is a bug**: Always evaluate "intended behavior" hypothesis first. Do not modify code to match incorrect expectations.
 - **No excessive changes**: change only what is needed to fix the bug. Do not refactor surrounding code.
 - **Symptom vs cause**: find the root cause, not the surface symptom.
 - **3-attempt limit**: if fix fails after 3 attempts, report the situation to the user.

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 |
@@ -58,10 +57,10 @@ Run ALL checks regardless of earlier failures. Do not short-circuit.
 
 | Check | How | Pass | Fail |
 |-------|-----|------|------|
-| Global CLAUDE.md exists | Read `~/.claude/CLAUDE.md` | File exists | ⚠ Warning: no global CLAUDE.md. All-for-ClaudeCode skills won't auto-trigger from intent. Fix: run `/afc:init` |
-| AFC block present | Grep for `<!-- AFC:START -->` and `<!-- AFC:END -->` in `~/.claude/CLAUDE.md` | Both markers found | Fix: run `/afc:init` to inject AFC block |
-| AFC block version | Extract version from `<!-- AFC:VERSION:X.Y.Z -->` in CLAUDE.md. Then read `${CLAUDE_PLUGIN_ROOT}/package.json` to get the actual plugin version. Compare the two. | Block version ≥ plugin version | ⚠ Warning: AFC block is outdated (found {block_version}, current {plugin_version}). Fix: run `/afc:init` to update |
-| No conflicting routing | Grep for conflicting agent patterns (`executor`, `deep-executor`, `debugger`, `code-reviewer`) outside AFC block that could intercept afc intents | No conflicts or conflicts are inside other tool blocks | ⚠ Warning: found agent routing that may conflict with afc skills. Review `~/.claude/CLAUDE.md` |
+| Global CLAUDE.md exists | Read `~/.claude/CLAUDE.md` | File exists | ⚠ Warning: no global CLAUDE.md. all-for-claudecode skills won't auto-trigger from intent. Fix: run `/afc:init` |
+| all-for-claudecode block present | Grep for `<!-- AFC:START -->` and `<!-- AFC:END -->` in `~/.claude/CLAUDE.md` | Both markers found | Fix: run `/afc:init` to inject all-for-claudecode block |
+| all-for-claudecode block version | Extract version from `<!-- AFC:VERSION:X.Y.Z -->` in CLAUDE.md. Then read `${CLAUDE_PLUGIN_ROOT}/package.json` to get the actual plugin version. Compare the two. | Block version ≥ plugin version | ⚠ Warning: all-for-claudecode block is outdated (found {block_version}, current {plugin_version}). Fix: run `/afc:init` to update |
+| No conflicting routing | Grep for conflicting agent patterns (`executor`, `deep-executor`, `debugger`, `code-reviewer`) outside all-for-claudecode block that could intercept afc intents | No conflicts or conflicts are inside other tool blocks | ⚠ Warning: found agent routing that may conflict with afc skills. Review `~/.claude/CLAUDE.md` |
 
 ### Category 4: Legacy Migration (v1.x → v2.0)
 
@@ -69,7 +68,7 @@ Run ALL checks regardless of earlier failures. Do not short-circuit.
 
 | Check | How | Pass | Fail |
 |-------|-----|------|------|
-| No legacy CLAUDE.md block | Grep `~/.claude/CLAUDE.md` for `<!-- SELFISH:START -->` | Marker not found | ⚠ Warning: legacy `SELFISH:START` block found in `~/.claude/CLAUDE.md`. Fix: run `/afc:init` (will replace with AFC block) |
+| No legacy CLAUDE.md block | Grep `~/.claude/CLAUDE.md` for `<!-- SELFISH:START -->` | Marker not found | ⚠ Warning: legacy `SELFISH:START` block found in `~/.claude/CLAUDE.md`. Fix: run `/afc:init` (will replace with all-for-claudecode block) |
 | No legacy config file | Check `.claude/selfish.config.md` | File does not exist | ⚠ Warning: legacy config `.claude/selfish.config.md` found. Fix: `mv .claude/selfish.config.md .claude/afc.config.md` |
 | No legacy state files | Glob `.claude/.selfish-*` | No files found | ⚠ Warning: legacy state files `.claude/.selfish-*` found. Fix: `cd .claude && for f in .selfish-*; do mv "$f" "${f/.selfish-/.afc-}"; done` |
 | No legacy artifact dir | Check `.claude/selfish/` directory | Directory does not exist | ⚠ Warning: legacy artifact directory `.claude/selfish/` found. Fix: `mv .claude/selfish .claude/afc` |
@@ -80,7 +79,7 @@ Run ALL checks regardless of earlier failures. Do not short-circuit.
 
 | Check | How | Pass | Fail |
 |-------|-----|------|------|
-| No stale pipeline flag | Check `.claude/.afc-active` | File does not exist (no active pipeline) | ⚠ Warning: stale pipeline flag found (feature: {name}). This may block normal operations. Fix: `rm .claude/.afc-active .claude/.afc-phase .claude/.afc-ci-passed` or run `/afc:resume` |
+| No stale pipeline state | Check `.claude/.afc-state.json` via `afc-pipeline-manage.sh status` | File does not exist (no active pipeline) | ⚠ Warning: stale pipeline state found (feature: {name}, phase: {phase}). This may block normal operations. Fix: `"${CLAUDE_PLUGIN_ROOT}/scripts/afc-pipeline-manage.sh" end --force` or run `/afc:resume` |
 | No orphaned artifacts | Glob `.claude/afc/specs/*/spec.md` | No specs directories, or all are from active pipeline | ⚠ Warning: orphaned `.claude/afc/specs/{name}/` found. Left over from a previous pipeline. Fix: `rm -rf .claude/afc/specs/{name}/` |
 | No lingering safety tags | `git tag -l 'afc/pre-*'` | No tags, or tags match active pipeline | ⚠ Warning: lingering safety tag `afc/pre-{x}` found. Fix: `git tag -d afc/pre-{x}` |
 | Checkpoint state | Read `.claude/afc/memory/checkpoint.md` if exists | No checkpoint (clean), or checkpoint is from current session | ⚠ Warning: stale checkpoint from {date}. Fix: run `/afc:resume` to continue or delete `.claude/afc/memory/checkpoint.md` |
@@ -108,7 +107,7 @@ Run ALL checks regardless of earlier failures. Do not short-circuit.
 
 1. Print header:
    ```
-   All-for-ClaudeCode Doctor
+   all-for-claudecode Doctor
    =======================
    ```
 
@@ -133,7 +132,7 @@ Run ALL checks regardless of earlier failures. Do not short-circuit.
 ## Example Output
 
 ```
-All-for-ClaudeCode Doctor
+all-for-claudecode Doctor
 =======================
 
 Environment
@@ -149,8 +148,8 @@ Project Config
 
 CLAUDE.md Integration
   ✓ Global ~/.claude/CLAUDE.md exists
-  ✓ AFC block present
-  ⚠ AFC block version outdated (1.0.0 → 1.1.0)
+  ✓ all-for-claudecode block present
+  ⚠ all-for-claudecode block version outdated (1.0.0 → 1.1.0)
     Fix: /afc:init
   ✓ No conflicting routing
 
@@ -176,4 +175,4 @@ Results: 14 passed, 2 warnings, 0 failures
 - **Always run all checks**: do not stop on first failure. The full picture is the value.
 - **Actionable fixes**: every non-pass result must include a Fix line. Never report a problem without a solution.
 - **Fast execution**: skip CI/gate command checks if `--fast` is in arguments (these are the slowest checks).
-- **Development checks**: Category 6 (Version Sync) only runs when inside the all-for-claudecode source repo.
+- **Development checks**: Category 7 (Version Sync) only runs when inside the all-for-claudecode source repo.

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.