@curdx/flow 1.1.4 → 1.1.6

package/commands/doctor.md

@@ -0,0 +1,124 @@
+---
+name: doctor
+description: Check the dependency health and project configuration of CurDX-Flow
+argument-hint: "[--verbose]"
+allowed-tools: [Bash, Read]
+---
+
+# CurDX-Flow Health Check
+
+Quickly confirm: **Are all the MCPs up? Are the recommended plugins installed? Is the project config valid?**
+
+## Steps
+
+### Step 1: MCP status
+
+```bash
+claude mcp list 2>/dev/null
+```
+
+Expected (auto-injected by CurDX-Flow's plugin.json):
+
+- ✓ `context7` — documentation queries
+- ✓ `sequential-thinking` — structured thinking
+- ✓ `chrome-devtools` — browser QA
+
+If missing, output:
+- `❌ <name> not started. Possible causes: npx connection failed, Node.js < 18, or corrupted npm cache.`
+- Hint: `claude mcp list` to view details, or restart Claude Code.
+
+### Step 2: Plugin status
+
+```bash
+claude plugin list 2>/dev/null
+```
+
+**Required**:
+- `curdx-flow` — this plugin
+
+**Recommended**:
+- `pua` (tanweai/pua) — anti-giving-up
+- `claude-mem` (thedotmack/claude-mem) — auto memory
+- `frontend-design` — UI design
+
+If a recommended plugin is missing, output:
+```
+⚠ <name> is not installed. Run /curdx-flow:install-deps to install, or run in degraded mode.
+Degradation impact:
+  - pua missing → no pressure escalation; rely on the three red lines in the preamble
+  - claude-mem missing → no auto memory; only explicit state in .flow/STATE.md
+  - frontend-design missing → UI falls back to default Tailwind + shadcn
+```
+
+### Step 3: Project status
+
+Check whether `.flow/` exists:
+
+```bash
+if [ -d ".flow" ]; then
+    echo "✓ .flow/ directory exists"
+else
+    echo "⚠ .flow/ directory does not exist. Run /curdx-flow:init to initialize."
+fi
+```
+
+If present, check:
+- `.flow/config.json` — valid JSON?
+- `.flow/PROJECT.md` — has content (not template placeholder)?
+- `.flow/STATE.md` — readable?
+- `.flow/.active-spec` — does the corresponding specs/<name>/ exist?
+
+### Step 4: CLAUDE.md check
+
+```bash
+if [ -f "CLAUDE.md" ]; then
+    echo "✓ Project-level CLAUDE.md exists"
+else
+    echo "ℹ Project has no CLAUDE.md. The Karpathy baseline is still injected via the InstructionsLoaded hook."
+fi
+```
+
+### Step 5: Write diagnostic report (optional --verbose)
+
+In verbose mode, output a full diagnosis, including:
+- Node.js version (`node --version`)
+- Claude Code version (`claude --version`)
+- Plugin data directory: `${CLAUDE_PLUGIN_DATA}`
+- Last dependency check date: `${CLAUDE_PLUGIN_DATA}/.deps-checked`
+
+## Output format
+
+```
+🏥 CurDX-Flow Health Check
+═══════════════════════════════════════
+
+MCP Servers:
+  ✓ context7              (auto-installed)
+  ✓ sequential-thinking   (auto-installed)
+  ✓ chrome-devtools       (auto-installed)
+
+Plugins:
+  ✓ curdx-flow            v0.1.0
+  ✓ pua                   v3.2.1
+  ⚠ claude-mem            not installed  → /curdx-flow:install-deps
+  ✓ frontend-design       v1.x
+
+Project:
+  ✓ .flow/                initialized
+  ✓ config.json           valid (mode: standard)
+  ⚠ PROJECT.md            still the template (please fill in the project vision)
+  ℹ No active spec        run /curdx-flow:start to launch the first one
+
+═══════════════════════════════════════
+Summary: 1 warning, 0 errors. Run /curdx-flow:install-deps to clear the warning.
+```
+
+## Exit status
+
+- 0 errors → fully healthy
+- Warnings only → usable, but recommended to address
+- Errors present → must be fixed before continuing
+
+## Error recovery
+
+For each issue found, provide a concrete recovery command rather than just "check the config".

package/commands/fast.md

@@ -0,0 +1,128 @@
+---
+name: fast
+description: Ultra-fast execution — skip all spec phases and implement directly per the description. Suited for one-shot small tasks.
+argument-hint: "\"<task description>\""
+allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Task]
+---
+
+# Flow Fast — Ultra-Fast Execution
+
+@${CLAUDE_PLUGIN_ROOT}/agent-preamble/preamble.md
+@${CLAUDE_PLUGIN_ROOT}/knowledge/atomic-commits.md
+
+**Fast Mode**: skip research / requirements / design / tasks, just do it.
+
+## Applicable Scenarios
+
+- ✓ One-shot scripts (e.g., "add a CLI command that prints the version number")
+- ✓ Clear small changes (e.g., "swap the deprecated API in foo.ts to bar")
+- ✓ Single-file modifications
+- ✓ Bug fixes (simple types)
+
+## Not Applicable
+
+- ✗ Production feature development (run the full /curdx-flow:start → /curdx-flow:spec → /curdx-flow:implement)
+- ✗ Architecture-level changes spanning multiple files
+- ✗ User-story-driven requirements
+
+**Cost of using this command**: no spec files are left behind; nobody will know later why it was changed this way. If that cost is unacceptable, run the full flow.
+
+## Step 1: Parse Input
+
+```bash
+TASK_DESC="$ARGUMENTS"
+[ -z "$TASK_DESC" ] && { echo "Usage: /curdx-flow:fast \"task description\""; exit 1; }
+```
+
+## Step 2: 5-Question Quick Clarification (Karpathy Principle 1)
+
+Even in fast mode, do not skip thinking. Before executing, explicitly state:
+
+```
+Quick understanding (please confirm or amend):
+
+1. Task: <restate in your own words>
+2. Files involved: <preliminary assessment>
+3. Expected effect: <success criteria>
+4. Known constraints: <if any>
+5. Assumptions: <list explicitly>
+
+Any ambiguity? (yes: amend then continue / no: proceed directly)
+```
+
+Use AskUserQuestion. If the user picks `no`, go straight to Step 3.
+
+## Step 3: Context Loading (Lightweight)
+
+```bash
+# Read project's CLAUDE.md (if any) and .flow/CONTEXT.md (if any)
+# but do not require a flow project — fast mode is allowed in any project
+[ -f "CLAUDE.md" ] && cat CLAUDE.md | head -50
+[ -f ".flow/CONTEXT.md" ] && cat .flow/CONTEXT.md | head -30
+```
+
+## Step 4: Explore + Execute
+
+**Mandatory tool use** (do not rely on training memory):
+
+```
+1. If library/API is involved: mcp__context7__query-docs
+2. Use Grep/Glob to find relevant code
+3. Read files to understand the current state
+4. Apply Karpathy's surgical principles
+5. Run validation commands (tsc/lint/test, per project)
+```
+
+## Step 5: Atomic Commit
+
+Even in fast mode, commit (do not leave changes scattered):
+
+```bash
+git add <exact files>
+git commit -m "<type>(<scope>): <summary>
+
+<body if any>
+"
+```
+
+The commit message must conform to `atomic-commits.md`.
+
+## Step 6: Output
+
+```
+✓ Fast execution complete
+
+Changes:
+  - src/foo.ts (+3 -1)
+  - src/foo.test.ts (+15)
+
+Verification:
+  npm test ✓ 12/12 passed
+  tsc --noEmit ✓
+
+Commit: abc123f — fix(foo): handle null case
+
+Consider the full flow next time?
+  /curdx-flow:start <name> "<goal>"  — if this type of task will recur
+```
+
+## Downgrade Comparison
+
+Fast vs Standard:
+
+| Dimension | Fast | Standard |
+|-----------|------|----------|
+| Time | 5-15 minutes | 1-4 hours |
+| Files | No spec residue | .flow/specs/<name>/*.md |
+| Traceability | git log only | git log + spec docs |
+| Quality | Relies on agent discipline | Multi-Gate enforced |
+| Suited for | Simple & known | Complex / team collaboration |
+
+Choosing the right scenario matters more than forcing the flow.
+
+## Forbidden
+
+- ✗ Committing without running verification
+- ✗ Changes touching more than 5 files (means it is no longer fast — run the full flow)
+- ✗ Writing library APIs from memory
+- ✗ Skipping the Step 2 5-question clarification (even when "obvious," explicit statement still has value)

package/commands/help.md

@@ -0,0 +1,119 @@
+---
+name: help
+description: CurDX-Flow help (command list, workflow overview, troubleshooting)
+argument-hint: "[<command-name> | workflow | troubleshoot]"
+allowed-tools: [Read]
+---
+
+# CurDX-Flow Help
+
+## No Arguments — Quick Overview
+
+```
+🚀 CurDX-Flow — AI Engineering Workflow Meta-Framework
+
+Current version: 0.1.0 (Phase 0 — Foundation)
+
+╔══════════════════════════════════════════════════════════════╗
+║ Command overview (Phase 0 implemented)                        ║
+╠══════════════════════════════════════════════════════════════╣
+║ /curdx-flow:init            Initialize .flow/ project structure     ║
+║ /curdx-flow:install-deps    One-shot install of recommended plugins ║
+║ /curdx-flow:doctor          Health check (deps + project config)    ║
+║ /curdx-flow:status          View spec and phase status              ║
+║ /curdx-flow:help            This help                               ║
+╚══════════════════════════════════════════════════════════════╝
+
+Coming soon (Phase 1+):
+  /curdx-flow:start / /curdx-flow:research / /curdx-flow:requirements / /curdx-flow:design
+  /curdx-flow:tasks / /curdx-flow:implement / /curdx-flow:verify / /curdx-flow:review
+  /curdx-flow:triage / /curdx-flow:party / /curdx-flow:debug / /curdx-flow:qa / /curdx-flow:sketch
+  /curdx-flow:ship / /curdx-flow:land / /curdx-flow:canary / /curdx-flow:retro ...
+
+Usage:
+  /curdx-flow:help <command>       View detailed usage for a command
+  /curdx-flow:help workflow        Introduce the full workflow
+  /curdx-flow:help troubleshoot    Common troubleshooting
+```
+
+## `<command-name>` — Command Details
+
+Based on the argument, read and display the corresponding command file (in a user-friendly format):
+
+```bash
+cat "${CLAUDE_PLUGIN_ROOT}/commands/${COMMAND}.md"
+```
+
+## `workflow` — Workflow Overview
+
+```
+📐 CurDX-Flow Standard Workflow
+
+1. Foundation (one-time)
+   └─ /curdx-flow:install-deps → /curdx-flow:init → /curdx-flow:doctor
+
+2. Per feature (Feature Workflow)
+   ├─ Research     /curdx-flow:research       (optional)
+   ├─ Requirements /curdx-flow:requirements   (required)
+   ├─ Design       /curdx-flow:design         (required)
+   ├─ Tasks        /curdx-flow:tasks          (required)
+   ├─ Execute      /curdx-flow:implement      (required)
+   ├─ Verify       /curdx-flow:verify         (required)
+   ├─ Review       /curdx-flow:review         (recommended)
+   └─ Ship         /curdx-flow:ship           (recommended)
+
+3. Large feature (Epic Workflow)
+   └─ /curdx-flow:triage → split into multiple specs advanced in parallel
+
+4. Ultra-fast path (Fast Path)
+   └─ /curdx-flow:fast "description"  — skip specs and execute directly
+
+5. Prototype exploration (Sketch Path)
+   └─ /curdx-flow:sketch "description" — UI design drafts
+
+Five modes (configured via .flow/config.json):
+  sketch      — Rapid prototyping
+  fast        — One-shot tasks
+  standard    — Regular features (default)
+  enterprise  — Full SDLC + multi-agent collaboration
+  autonomous  — Overnight automation
+```
+
+## `troubleshoot` — Common Issues
+
+```
+🛠️ Common Troubleshooting
+
+Q: 3 MCPs did not start?
+A: Check Node.js >= 18: `node --version`
+   View MCP status: `claude mcp list`
+   Restart Claude Code
+
+Q: Recommended-plugins prompt keeps appearing?
+A: Run /curdx-flow:install-deps to install, or create the marker file manually:
+   touch "${CLAUDE_PLUGIN_DATA}/.deps-checked"
+
+Q: /curdx-flow:init reports "directory already exists"?
+A: An existing .flow/ is already initialized. Run /curdx-flow:status to view, or use --force to overwrite.
+
+Q: Agents do not call context7 / sequential-thinking?
+A: Make sure preamble.md is loaded (InstructionsLoaded hook).
+   Run /curdx-flow:doctor to check MCP status.
+
+Q: Do claude-mem and .flow/STATE.md conflict?
+A: No. claude-mem lives at ~/.claude-mem/ (SQLite), curdx-flow lives at .flow/ (JSON+MD).
+   Division of duties: claude-mem for automatic implicit memory, STATE.md for explicit decisions.
+
+Q: pua is too aggressive, can it be turned off?
+A: pua is an independent plugin, you can /plugin disable pua.
+   Enabling pua does not affect curdx-flow's core features (the three red lines are built into preamble).
+
+Q: Want to contribute / report a bug?
+A: https://github.com/wdx/curdx-flow/issues
+```
+
+## Output Principles
+
+- Stay concise; use tables and lists instead of long prose
+- Every answer points to a specific command; avoid filler like "please consult the docs"
+- Prioritize showing the user's next actionable step