@curdx/flow 1.1.3 → 1.1.5

package/commands/autoplan.md

@@ -0,0 +1,184 @@
+---
+name: autoplan
+description: Automatic planning review — run CEO / Engineering / Design / DX reviews in parallel and aggregate findings.
+argument-hint: "[spec-name]"
+allowed-tools: [Read, Write, Bash, Task]
+---
+
+# Flow Autoplan — Automatic Planning Review
+
+@${CLAUDE_PLUGIN_ROOT}/knowledge/planning-reviews.md
+
+Run 4 Planning Reviews **in parallel** and aggregate the results.
+
+## When to use
+
+- Production-grade features (not prototypes)
+- Design is done, before entering tasks
+- Want to ensure "multi-perspective coverage without omission"
+
+## When not to use
+
+- MVP / prototype (use /curdx-flow:tasks directly)
+- Pure backend (skip Design Review)
+- Small changes (a single Review is enough)
+
+## Step 1: Prerequisites
+
+```bash
+SPEC_NAME="${ARGUMENTS:-$(cat .flow/.active-spec 2>/dev/null)}"
+[ -z "$SPEC_NAME" ] && { echo "❌ No active spec"; exit 1; }
+
+DIR=".flow/specs/$SPEC_NAME"
+for f in requirements.md design.md; do
+    [ ! -f "$DIR/$f" ] && { echo "❌ Missing $f"; exit 1; }
+done
+```
+
+## Step 2: Decide how many Reviews are needed
+
+```bash
+# Pure backend spec → skip Design Review
+HAS_UI=0
+grep -qE "(UI|UX|interface|frontend)" "$DIR"/*.md && HAS_UI=1
+
+if [ $HAS_UI -eq 1 ]; then
+    REVIEWS=(ceo eng design dx)
+else
+    REVIEWS=(ceo eng dx)
+    echo "ℹ Pure backend spec, skipping Design Review"
+fi
+```
+
+## Step 3: Dispatch in parallel (key: multiple Tasks in a single message)
+
+**In the same response**, invoke multiple Task tools to run in parallel:
+
+```
+Task (CEO Review):
+  subagent_type: general-purpose
+  description: "CEO: $SPEC_NAME"
+  prompt: <same content as /curdx-flow:plan-ceo Task prompt>
+
+Task (Engineering Review):
+  ... same as /curdx-flow:plan-eng ...
+
+Task (Design Review, if HAS_UI=1):
+  ... same as /curdx-flow:plan-design ...
+
+Task (DX Review):
+  ... same as /curdx-flow:plan-dx ...
+```
+
+**Do not** dispatch across multiple messages (that would run serially, not in parallel).
+
+## Step 4: Wait for all returns + aggregate
+
+Read each review report:
+
+```bash
+CEO_REPORT="$DIR/plan-review-ceo.md"
+ENG_REPORT="$DIR/plan-review-eng.md"
+DESIGN_REPORT="$DIR/plan-review-design.md"  # may not exist
+DX_REPORT="$DIR/plan-review-dx.md"
+```
+
+## Step 5: Generate aggregated report
+
+```markdown
+# Auto Plan Review: $SPEC_NAME
+
+Generated: YYYY-MM-DD
+Ran: CEO + Engineering + Design + DX (parallel)
+
+## Summary
+
+| Review | Verdict | Findings |
+|--------|---------|----------|
+| CEO    | APPROVED_WITH_CONCERNS | 2 |
+| Eng    | NEEDS_REVISION | 5 |
+| Design | APPROVED | 1 |
+| DX     | 50/80 (pass) | 3 |
+
+## Blocking items (must fix)
+
+1. **[Eng] AD-03 missing fallback strategy**
+   - Location: design.md AD-03
+   - Risk: no fallback during production incident
+   - Suggestion: add AD-04 "fall back to in-memory cache when Redis is unavailable"
+
+2. **[CEO] Scope too large**
+   - Observation: current design includes 4 sub-features; MVP needs only 2
+   - Suggestion: trim to MVP (drop sub-features C / D, record as "v2 feature")
+
+## Warnings (recommended to fix)
+
+1. [Eng] AD-01 trade-off explanation not detailed enough
+2. [CEO] ROI not quantified
+3. [Design] error message strategy missing
+4. [DX] comment strategy not mentioned
+5. [DX] test naming convention unspecified
+
+## Observations
+
+- Overall project design quality: medium
+- Largest risk: missing fallback for AD-03
+
+## Suggested fix path
+
+Suggested order (blocking first, warnings later):
+1. /curdx-flow:design re-discuss AD-03 + scope
+2. Add error message strategy in design.md
+3. Add comments / testing strategy sections
+4. Re-run /curdx-flow:autoplan to confirm
+5. After pass → /curdx-flow:tasks
+```
+
+## Step 6: Write aggregation + update .state
+
+```bash
+AUTO_REPORT="$DIR/plan-review-auto.md"
+# write aggregated content
+
+# update state
+python3 <<PY
+import json
+s = json.load(open('$DIR/.state.json'))
+s.setdefault('plan_reviews', {})
+s['plan_reviews']['last_run'] = '$(date +%Y-%m-%d)'
+s['plan_reviews']['blocking'] = 2  # tallied from the report
+s['plan_reviews']['warning'] = 5
+json.dump(s, open('$DIR/.state.json','w'), indent=2, ensure_ascii=False)
+PY
+```
+
+## Step 7: Output
+
+```
+✓ Auto Plan Review complete
+
+Ran 4 reviews (parallel):
+  CEO:    APPROVED_WITH_CONCERNS (2 concerns)
+  Eng:    NEEDS_REVISION (5 issues)
+  Design: APPROVED (1 minor)
+  DX:     50/80 pass (3 issues)
+
+Aggregate:
+  Blocking: 2
+  Warnings: 5
+
+Overall verdict: NEEDS_REVISION
+
+Aggregated report: .flow/specs/$SPEC_NAME/plan-review-auto.md
+
+Next steps:
+- Read the "Blocking items" section of the report
+- After fixing → /curdx-flow:autoplan for re-review
+- After pass → /curdx-flow:tasks
+```
+
+## Error recovery
+
+- A Review fails → continue with the others; mark missing ones during aggregation
+- All 4 fail → possibly design.md is corrupt; check then re-run
+- Parallel timeout → reduce concurrency (run each review manually)

package/commands/debug.md

@@ -0,0 +1,199 @@
+---
+name: debug
+description: Systematic debugging — 4-phase methodology (root cause → pattern → hypothesis → fix); ≥3 failures triggers architectural questioning. Dispatches flow-debugger (David).
+argument-hint: "\"<bug description>\""
+allowed-tools: [Read, Write, Edit, Bash, Task, Grep, Glob]
+---
+
+# Flow Debug — Systematic Debugging
+
+@${CLAUDE_PLUGIN_ROOT}/knowledge/systematic-debugging.md
+
+Dispatches the `flow-debugger` (David) agent to perform systematic 4-phase debugging.
+
+## When to use
+
+- Clearly defined bug (with error message / reproduction steps)
+- Tests suddenly failing
+- Weird production behavior
+- Tasks repeatedly failed by flow-executor
+
+## When not to use
+
+- Still in coding phase → use the normal flow-executor flow
+- Question needs investigation → use /curdx-flow:spike
+- Performance issue needing benchmarks → performance tuning is not debug
+
+## Step 1: Parse bug description
+
+```bash
+BUG_DESC="$ARGUMENTS"
+[ -z "$BUG_DESC" ] && { echo "Usage: /curdx-flow:debug \"<bug description>\""; exit 1; }
+```
+
+## Step 2: Collect prerequisites (main agent, no dispatch)
+
+Before dispatching David, the main agent (you) collects first:
+
+```bash
+# 1. Recent commit history (bug may be introduced by a new commit)
+git log --oneline -20
+
+# 2. Current modifications (uncommitted)
+git status
+git diff --stat
+
+# 3. If there is an active spec, read it
+ACTIVE=$(cat .flow/.active-spec 2>/dev/null)
+```
+
+## Step 3: Dispatch flow-debugger (David)
+
+```
+Task:
+  subagent_type: general-purpose
+  description: "Debug: $BUG_DESC"
+  prompt: |
+    You are the flow-debugger agent (David). Full definition:
+    ${CLAUDE_PLUGIN_ROOT}/agents/flow-debugger.md
+    
+    Methodology knowledge base:
+    ${CLAUDE_PLUGIN_ROOT}/knowledge/systematic-debugging.md
+    
+    Bug description:
+    $BUG_DESC
+    
+    Workspace:
+    $(pwd)
+    
+    Prerequisites:
+    - Recent commits: $(git log --oneline -10)
+    - Current diff: $(git status --short)
+    - Active spec: $ACTIVE
+    - Spec directory (if any): .flow/specs/$ACTIVE/
+    
+    Mandatory 4 phases:
+    
+    Phase 1: Root-cause investigation
+      - Read the error carefully (stack trace + message + location)
+      - Build a minimal reproduction
+      - Check recent changes
+      - Trace the data flow
+      - **By the end of Phase 1 you must state the root cause in one sentence; "maybe it's..." is not allowed**
+    
+    Phase 2: Pattern analysis
+      - Find working examples
+      - Pinpoint the difference
+      - Decide isolated case vs systemic
+    
+    Phase 3: Hypothesis & testing
+      - Single hypothesis
+      - Minimal test (verify in memory, don't commit)
+      - If confirmed, enter Phase 4; if disproved → return to Phase 1
+    
+    Phase 4: Implement the fix
+      - Write a failing test
+      - Test actually fails (commit: test(scope): red - ...)
+      - Fix the root cause (not the symptom)
+      - Test passes (commit: fix(scope): green - ...)
+      - Full regression test passes
+      - Sweep for other isolated cases identified in Phase 2 and fix together
+    
+    **3-failure guard**:
+    If Phase 4 has tried 3 different approaches and all failed, **stop**.
+    Do not try a 4th. Report back to me:
+      - The 3 approaches tried
+      - Why each failed
+      - Possible root issue (architecture / dependency / data)
+      - Recommend user intervention
+    
+    Forbidden:
+    - Prayer-driven programming (retry 10 times)
+    - "Maybe it's..." as a root cause
+    - A fix without a failing test
+    - Bypassing the root cause (adding null check / try-catch to mask it)
+    - Fixing multiple things at once (adds variables)
+    
+    Output to me a brief:
+    - Phase 1 root-cause statement
+    - Phase 2 pattern-analysis conclusion
+    - Phase 3 hypothesis + verification
+    - Phase 4 fix commits
+    - Learnings (suggestions to append to .progress.md)
+```
+
+## Step 4: Report to user
+
+```
+✓ Debug complete
+
+Root cause: <Phase 1 conclusion>
+Pattern: <Phase 2 conclusion>
+
+Fix commits:
+  - <hash>: test - failing test
+  - <hash>: fix - root-cause fix
+  - <hash>: (additional) fixed N similar issues
+
+Verification:
+  - Failing test now PASS ✓
+  - Full test suite has no regressions ✓
+
+📝 Learnings (can be appended to .progress.md):
+  - <lesson 1>
+  - <lesson 2>
+
+Next steps:
+  - Review commits
+  - If the active spec has .progress.md, consider appending learnings
+```
+
+## Special case: 3 failures
+
+If David reports 3 failures:
+
+```
+⚠ Systematic debugging failed (3 attempts)
+
+Attempts:
+  1. <method 1>: <why failed>
+  2. <method 2>: <why failed>
+  3. <method 3>: <why failed>
+
+Possible root issues:
+  - Wrong architectural assumption
+  - Dependency version / compatibility
+  - Data-layer issue
+
+Suggestions:
+  - Review David's detailed report analysis
+  - /curdx-flow:party winston david "what architectural issue does this bug hint at?"
+  - Or temporarily @ts-ignore / skip test and record as tech debt in STATE.md
+```
+
+## Forbidden
+
+- ✗ Omitting the bug description
+- ✗ Expecting "one-shot fix" (debug is a process, not an event)
+- ✗ Skipping David and editing code yourself (loses the systematic methodology)
+- ✗ Accepting "maybe it's..." as a root cause
+
+## Relationship to other commands
+
+- `/curdx-flow:debug`: for **existing bugs**
+- `/curdx-flow:implement`: may encounter bugs, but flow-executor retries 5 times itself before considering `/curdx-flow:debug`
+- `/curdx-flow:verify`: finding a "false implementation" counts as a bug, can spawn `/curdx-flow:debug`
+
+## Typical scenarios
+
+```
+Scenario 1: Test suddenly failing
+  You: "npm test keeps failing a specific test lately but I can't tell why"
+  /curdx-flow:debug "login test in auth.test.ts fails in CI but passes locally"
+
+Scenario 2: Production bug
+  /curdx-flow:debug "production environment returns 500 for some API, stack trace: ..."
+
+Scenario 3: Bug introduced by refactor
+  /curdx-flow:debug "login broken after refactor of auth module; pre-refactor version works"
+```

package/commands/design.md

@@ -0,0 +1,155 @@
+---
+name: design
+description: Run the design phase — dispatch the flow-architect agent to do 8+ rounds of sequential-thinking, producing design.md
+argument-hint: "[spec-name]"
+allowed-tools: [Read, Write, Bash, Task]
+---
+
+# Design Phase
+
+Dispatch the `flow-architect` agent to do architectural design. This is the phase that **freezes technology choices**.
+
+## Step 1: Parse + prerequisite checks
+
+```bash
+SPEC_NAME="${ARGUMENTS:-$(cat .flow/.active-spec 2>/dev/null)}"
+
+[ -z "$SPEC_NAME" ] && { echo "❌ Please run /curdx-flow:start first"; exit 1; }
+
+DIR=".flow/specs/$SPEC_NAME"
+[ ! -f "$DIR/research.md" ]     && { echo "❌ Missing research.md. Run /curdx-flow:research first"; exit 1; }
+[ ! -f "$DIR/requirements.md" ] && { echo "❌ Missing requirements.md. Run /curdx-flow:requirements first"; exit 1; }
+```
+
+## Step 2: Update state
+
+```python
+import json
+p = f'.flow/specs/{SPEC_NAME}/.state.json'
+s = json.load(open(p))
+s.setdefault('phase_status',{})['design']='in_progress'
+s['phase']='design'
+json.dump(s, open(p,'w'), indent=2, ensure_ascii=False)
+```
+
+## Step 3: Dispatch flow-architect
+
+```
+Task:
+  subagent_type: general-purpose
+  description: "Architectural design $SPEC_NAME"
+  prompt: |
+    You are the flow-architect agent. The full definition is at:
+    ${CLAUDE_PLUGIN_ROOT}/agents/flow-architect.md
+    
+    Prerequisites (must read):
+    - .flow/specs/$SPEC_NAME/research.md
+    - .flow/specs/$SPEC_NAME/requirements.md
+    - .flow/PROJECT.md
+    - .flow/STATE.md
+    
+    Template:
+    ${CLAUDE_PLUGIN_ROOT}/templates/design.md.tmpl
+    
+    Knowledge base:
+    - ${CLAUDE_PLUGIN_ROOT}/knowledge/spec-driven-development.md (especially Phase 3)
+    
+    Output:
+    .flow/specs/$SPEC_NAME/design.md
+    
+    **Key rules**:
+    1. Must call mcp__sequential-thinking__sequentialthinking **at least 8 rounds**
+       - Rounds 1-2: constraint identification
+       - Rounds 3-4: option A
+       - Rounds 5-6: option B
+       - Round 7: selection
+       - Round 8+: rebuttal
+    
+    2. Every library must be verified with mcp__context7__:
+       - resolve-library-id
+       - query-docs
+    
+    3. Assign AD-NN to each architectural decision
+       - Include the sequentialthinking source round number
+       - Include trade-off explanation
+    
+    4. Project-level decisions must be synced to .flow/STATE.md (D-NN)
+    
+    5. Must draw ≥1 mermaid diagram
+    
+    6. Every component must have a TypeScript interface or equivalent type definition
+    
+    7. Every NFR must have a corresponding design point in the design
+    
+    Success criteria:
+    - sequential-thinking ≥ 8 rounds (round count reflected in AD references)
+    - AD ≥ 3
+    - Every FR has a component responsible for it in the design
+    - Every NFR has a response
+    - Error paths cover the edge-condition table in requirements.md
+    
+    Forbidden:
+    - Choosing tech from memory
+    - Describing interfaces in natural language
+    - Omitting error paths
+    - Modifying requirements.md
+    
+    When done, return a brief: core ADs, tech stack, component count, D-NN synced to STATE.md.
+```
+
+## Step 4: Validate output
+
+```bash
+DESIGN=".flow/specs/$SPEC_NAME/design.md"
+
+# Required sections
+for sec in "Architectural Decisions" "System Architecture Diagram" "Component Design" "Error Paths"; do
+    grep -q "$sec" "$DESIGN" || echo "⚠ Missing section: $sec"
+done
+
+# AD count
+AD_COUNT=$(grep -c "^### AD-" "$DESIGN" || echo 0)
+[ "$AD_COUNT" -lt 3 ] && echo "⚠ Fewer than 3 architectural decisions (design may not be deep enough)"
+
+# mermaid diagram
+grep -q "mermaid" "$DESIGN" || echo "⚠ No mermaid diagram found"
+
+# sequential-thinking reference
+grep -q "sequentialthinking" "$DESIGN" || echo "⚠ No sequential-thinking round reference in ADs"
+```
+
+## Step 5: STATE.md sync check
+
+```bash
+# The agent should have appended project-level decisions to STATE.md
+# Here we just check whether an append happened
+if ! git diff --quiet .flow/STATE.md 2>/dev/null; then
+    echo "✓ STATE.md updated"
+else
+    echo "ℹ STATE.md unchanged (this spec may have no project-level decisions)"
+fi
+```
+
+## Step 6: Output
+
+```
+✓ design phase complete
+
+File:                .flow/specs/$SPEC_NAME/design.md
+Architectural decisions: N ADs
+Project-level decisions: M synced to STATE.md
+Components:              K
+
+**⚠ Design frozen**: once in tasks phase, any architecture change requires returning to /curdx-flow:design and bumping the version.
+
+Next steps:
+  - Review design.md (especially the AD-NN entries)
+  - If you disagree with a decision, write "Challenge AD-NN: reason" in STATE.md, then re-run /curdx-flow:design
+  - /curdx-flow:tasks  — enter task breakdown
+```
+
+## Error recovery
+
+- sequential-thinking MCP unavailable → agent uses inline `<thinking>` blocks; quality may drop, suggest fixing the MCP then re-running
+- context7 unavailable → supplement with WebSearch; tech pitfall detection will be weaker
+- Agent produced fewer than 3 ADs → design may be too shallow; re-run emphasizing "at least 3 ADs"

package/commands/discuss.md

@@ -0,0 +1,162 @@
+---
+name: discuss
+description: Pre-implementation discussion — capture the user's key decisions (D-NN) for the spec, written to .progress.md and STATE.md. Stop the AI from "silently assuming".
+argument-hint: "[spec-name]"
+allowed-tools: [Read, Write, Edit, AskUserQuestion, Bash]
+---
+
+# Flow Discuss — Decision Locking
+
+Before implementation, align with the user on **key decisions** (D-NN format) so the downstream implementer does not have to guess user preferences.
+
+## When to use
+
+- design is done but before tasks (freeze decisions into tasks)
+- before implementation (give executor explicit guidance)
+- user wants to adjust direction halfway through a spec (add decisions)
+
+## Step 1: Prerequisites
+
+```bash
+SPEC_NAME="${ARGUMENTS:-$(cat .flow/.active-spec 2>/dev/null)}"
+[ -z "$SPEC_NAME" ] && { echo "❌ No active spec"; exit 1; }
+
+DIR=".flow/specs/$SPEC_NAME"
+[ ! -f "$DIR/design.md" ] && { echo "❌ Missing design.md. Run /curdx-flow:design first"; exit 1; }
+```
+
+## Step 2: Identify open decisions
+
+Read the open questions in design.md + requirements.md:
+
+```bash
+# Find open-questions sections in design / requirements
+sed -n '/## Open Questions/,/^##/p' "$DIR/design.md" 2>/dev/null
+sed -n '/## Open Questions/,/^##/p' "$DIR/requirements.md" 2>/dev/null
+```
+
+Also scan unresolved TODO / FIXME:
+
+```bash
+grep -i "TBD\|TODO\|pending\|FIXME" "$DIR/"*.md
+```
+
+## Step 3: Interactive questioning (key)
+
+For each open decision, capture the user's choice via AskUserQuestion:
+
+```
+AskUserQuestion:
+  Question: "How to store user data"
+  Options:
+    - A: PostgreSQL (relational, already used in the project)
+    - B: MongoDB (flexible schema, needs a new dependency)
+    - C: Do not decide yet (defer to actual implementation)
+```
+
+**Forbidden**:
+- The agent guesses the answer itself
+- Merging multiple open questions into one ask (user can't answer all)
+
+**Supported**:
+- User picks "C: do not decide yet" → record as `D-NN: deferred, decide at implementation time`
+- User wants to add rationale → append to the D-NN rationale
+- User proposes a new direction (not in the options) → record and tag "user-originated"
+
+## Step 4: Assign D-NN
+
+Read existing STATE.md to get the largest D number:
+
+```python
+import re
+content = open('.flow/STATE.md').read()
+existing = re.findall(r'D-(\d+)', content)
+next_n = max([int(x) for x in existing] + [0]) + 1
+```
+
+For each new decision:
+- Project-level impact (e.g., "the whole project uses PostgreSQL") → D-NN (append to STATE.md)
+- Spec-level impact (e.g., "this spec uses bcrypt cost 12") → append to the spec's .progress.md
+
+## Step 5: Append to STATE.md
+
+```markdown
+## New decisions (append to the Decisions section of .flow/STATE.md)
+
+- **D-07** | 2026-04-19 | auth-system spec decides to use JWT + Redis blocklist | supports cross-domain SPA; token revocation via Redis
+- **D-08** | 2026-04-19 | All user data uses PostgreSQL | already used in the project; avoid introducing a new dependency
+```
+
+**Append only, never modify existing D-NN.** (Once a decision is locked, do not change it.)
+
+## Step 6: Append to .progress.md
+
+```markdown
+# .flow/specs/$SPEC_NAME/.progress.md
+
+## Decisions Made Here (from /curdx-flow:discuss YYYY-MM-DD)
+
+- **D-07**: JWT + Redis blocklist
+  - Project-level → synced to STATE.md
+- **D-08**: PostgreSQL for user data
+  - Project-level → synced to STATE.md
+- **D-local-01**: bcrypt cost factor 12 (spec-level)
+  - Rationale: balance performance (100ms) and security
+  - No need to sync to STATE.md
+```
+
+Project-level use the global D-NN numbering; spec-level use `D-local-NN` without taking a global number.
+
+## Step 7: Update tasks.md references (if already generated)
+
+If tasks.md already exists, append `_Decisions: D-NN` reference to each task (so the executor knows which decision the task must follow).
+
+If tasks.md has not been generated, a later `/curdx-flow:tasks` will generate based on these decisions.
+
+## Step 8: Output to user
+
+```
+✓ Discuss complete: $SPEC_NAME
+
+Captured decisions:
+  Project-level (D-NN):
+    • D-07: JWT + Redis blocklist
+    • D-08: PostgreSQL for user data
+  
+  Spec-level (D-local-NN):
+    • D-local-01: bcrypt cost factor 12
+
+Written to:
+  • .flow/STATE.md (D-07, D-08)
+  • .flow/specs/$SPEC_NAME/.progress.md (all)
+
+These decisions will be honored by flow-executor during subsequent execution without re-asking.
+
+Next steps:
+  - If tasks.md is already generated → /curdx-flow:implement
+  - If not → /curdx-flow:tasks (will automatically reference these decisions)
+```
+
+## Forbidden
+
+- ✗ Agent guessing the user's choice
+- ✗ Asking open questions in bulk (must use AskUserQuestion one by one)
+- ✗ Modifying existing D-NN (append only)
+- ✗ Putting spec-level decisions in STATE.md (only project-level)
+
+## Principles
+
+### Discuss ≠ clarifying requirements
+
+- **Discuss**: design exists; now decide execution details (e.g., "which DB")
+- **Clarifying requirements**: should be done in the requirements phase
+
+If discuss reveals that the requirements themselves are unclear → return to /curdx-flow:requirements.
+
+### A decision is a contract
+
+Once a D-NN is written to STATE.md, all subsequent related code must reference the D-NN. To violate it, explicit challenge is required:
+
+```
+Comment or PR description: "Challenge D-07: using session rather than JWT here because X"
+```