@curdx/flow 1.1.3 → 1.1.5

package/commands/plan-dx.md

@@ -0,0 +1,104 @@
+---
+name: plan-dx
+description: DevEx planning review — next maintainer's perspective, 8-dimension evaluation (naming/comments/structure/errors/setup/types/tests/dev loop)
+argument-hint: "[spec-name]"
+allowed-tools: [Read, Write, Bash, Task]
+---
+
+# Flow Plan DX — Developer Experience Review
+
+@${CLAUDE_PLUGIN_ROOT}/knowledge/planning-reviews.md
+@${CLAUDE_PLUGIN_ROOT}/gates/devex-gate.md
+
+Review from the **next maintainer's** perspective: in 6 months, can I or a colleague quickly pick this up?
+
+## Step 1: Preflight
+
+```bash
+SPEC_NAME="${ARGUMENTS:-$(cat .flow/.active-spec 2>/dev/null)}"
+[ -z "$SPEC_NAME" ] && { echo "✗ No active spec"; exit 1; }
+[ ! -f ".flow/specs/$SPEC_NAME/design.md" ] && { echo "✗ Missing design.md"; exit 1; }
+```
+
+## Step 2: Dispatch DX Review
+
+```
+Task:
+  subagent_type: general-purpose
+  description: "DX Review: $SPEC_NAME"
+  prompt: |
+    **DevEx Review Mode**
+    
+    You review design.md on DevEx dimensions. Reuse the flow-reviewer agent:
+    ${CLAUDE_PLUGIN_ROOT}/agents/flow-reviewer.md
+    
+    Gate definition:
+    ${CLAUDE_PLUGIN_ROOT}/gates/devex-gate.md
+    
+    Methodology:
+    ${CLAUDE_PLUGIN_ROOT}/knowledge/planning-reviews.md (Review 4)
+    
+    Review targets:
+    - .flow/specs/$SPEC_NAME/design.md
+    - Related source code (if design references existing code)
+    - .flow/codebase-index.md (if present)
+    
+    8-dimension scoring (0-10 per dimension):
+    
+    DX-01 Naming clarity
+    DX-02 Intent comments
+    DX-03 File structure
+    DX-04 Error messages
+    DX-05 Easy setup
+    DX-06 Clear types
+    DX-07 Tests as docs
+    DX-08 Fast dev loop
+    
+    For each dimension:
+    - Observe relevant decisions in the design
+    - If the design specifically mentions a dimension (e.g., "we use strict TypeScript") → basis for scoring
+    - If the design does not mention it (e.g., no word about error-message design) → mark as "missing", score 5
+    
+    Use sequential-thinking ≥ 4 rounds.
+    
+    Output: .flow/specs/$SPEC_NAME/plan-review-dx.md
+    
+    Format:
+    # DX Plan Review: $SPEC_NAME
+    
+    ## Scores
+    DX-01 Naming: 7/10
+    DX-02 Comments: 5/10 (not mentioned)
+    DX-03 Structure: 8/10
+    ...
+    
+    Total: N/80
+    
+    ## Findings
+    
+    ### DX-02 Intent comments
+    Observation: the design does not explicitly state a comment strategy
+    Risk: the implementer may under-comment
+    Recommendation: add a paragraph in the design "key decision points should have why comments"
+    
+    ...
+```
+
+## Step 3: Output
+
+```
+📐 DX Review complete
+
+Total: N/80 ($([ $N -ge 40 ] && echo "pass" || echo "needs improvement"))
+
+Weakest dimensions:
+  - <dimension 1> N/10
+  - <dimension 2> N/10
+
+Report: .flow/specs/$SPEC_NAME/plan-review-dx.md
+
+Next steps:
+- Add strategies in design.md for low-scoring dimensions
+- Or add "DX checkpoint" tasks in tasks.md
+- Pass → /curdx-flow:tasks (execution breakdown)
+```

package/commands/plan-eng.md

@@ -0,0 +1,108 @@
+---
+name: plan-eng
+description: Engineering planning review — architecture lock-in, risk identification, technical debt assessment. Dispatches flow-architect in review mode.
+argument-hint: "[spec-name]"
+allowed-tools: [Read, Write, Bash, Task]
+---
+
+# Flow Plan Engineering — Engineering-Layer Review
+
+@${CLAUDE_PLUGIN_ROOT}/knowledge/planning-reviews.md
+
+Review design.md once more from the **engineer's perspective**: will the architecture work? Is it maintainable long-term?
+
+## Step 1: Preflight
+
+```bash
+SPEC_NAME="${ARGUMENTS:-$(cat .flow/.active-spec 2>/dev/null)}"
+[ -z "$SPEC_NAME" ] && { echo "✗ No active spec"; exit 1; }
+[ ! -f ".flow/specs/$SPEC_NAME/design.md" ] && { echo "✗ Missing design.md"; exit 1; }
+```
+
+## Step 2: Dispatch Eng Review
+
+```
+Task:
+  subagent_type: general-purpose
+  description: "Eng Review: $SPEC_NAME"
+  prompt: |
+    **Engineering Review Mode**
+    
+    You are an independent engineering reviewer. You read design.md to find risks, holes, and unclarities.
+    
+    Full methodology: ${CLAUDE_PLUGIN_ROOT}/knowledge/planning-reviews.md (Review 2)
+    
+    Review targets:
+    - .flow/specs/$SPEC_NAME/design.md (main body)
+    - .flow/specs/$SPEC_NAME/requirements.md (NFR requirements)
+    - .flow/STATE.md (existing decisions)
+    
+    Review checklist:
+    
+    1. Architecture lock-in
+       - Does each AD-NN have a tradeoff explanation?
+       - Does the rationale reference sequential-thinking rounds?
+       - Is there an explicit cost ("we accepted X")?
+    
+    2. Scalability
+       - What happens at 10x users / 10x data?
+       - Are bottlenecks identified?
+    
+    3. Reasonable dependencies
+       - Is the library / service choice justified?
+       - Risk of deprecation?
+       - Known CVEs / issues?
+    
+    4. Clear data flow
+       - Does the mermaid diagram reflect the real flow?
+       - Are all component boundaries explicit?
+    
+    5. Error paths
+       - Handling of upstream failures?
+       - Handling of downstream failures?
+       - User input anomalies?
+       - Concurrency / retries?
+    
+    6. Test strategy
+       - Reasonable unit / integration / E2E ratio?
+       - Core scenarios covered?
+    
+    7. Deployment feasibility
+       - CI/CD pipeline?
+       - Monitoring / alerting?
+       - Rollback strategy?
+    
+    Use sequential-thinking ≥ 6 rounds (adversarial-style review; "looks fine" is not accepted).
+    Must find ≥ 3 findings.
+    
+    Output: .flow/specs/$SPEC_NAME/plan-review-eng.md
+    
+    Format for each finding:
+    ### [Category] Issue
+    Location: design.md section N / AD-NN
+    Observation: what was specifically seen
+    Risk: high / medium / low + consequences
+    Recommendation: concrete change (command or code snippet)
+```
+
+## Step 3: Output
+
+```
+⚙ Engineering Review complete
+
+Findings:
+  High: $HIGH
+  Medium: $MED
+  Low: $LOW
+
+Verdict: <APPROVED / NEEDS_REVISION>
+
+Key risks:
+  - <top 3>
+
+Report: .flow/specs/$SPEC_NAME/plan-review-eng.md
+
+Next steps:
+- Fix high/medium → /curdx-flow:design to update (bump version)
+- After pass → /curdx-flow:plan-design or /curdx-flow:tasks
+```

package/commands/qa.md

@@ -0,0 +1,118 @@
+---
+name: qa
+description: Real-browser QA — run user flows with chrome-devtools MCP, capturing bugs / performance / accessibility. Dispatches flow-qa-engineer (Oliver).
+argument-hint: "[spec-name] [--url=<dev-url>]"
+allowed-tools: [Read, Write, Bash, Task, WebFetch]
+---
+
+# Flow QA — Real-Browser Testing
+
+Dispatches `flow-qa-engineer` (Oliver) to run user flows in real Chrome using **chrome-devtools MCP**.
+
+## Step 1: Preflight check
+
+```bash
+[ ! -d ".flow" ] && { echo "✗ Not a CurDX-Flow project"; exit 1; }
+
+ARGS="$ARGUMENTS"
+URL=""
+case "$ARGS" in
+    *--url=*)
+        URL=$(echo "$ARGS" | grep -oE -- '--url=[^[:space:]]+' | cut -d= -f2)
+        ;;
+esac
+SPEC_NAME=$(echo "$ARGS" | sed 's/--url=[^ ]*//g' | xargs)
+[ -z "$SPEC_NAME" ] && SPEC_NAME=$(cat .flow/.active-spec 2>/dev/null)
+[ -z "$SPEC_NAME" ] && { echo "✗ No active spec"; exit 1; }
+```
+
+## Step 2: Detect chrome-devtools MCP
+
+```bash
+# If MCP is not up, flow-qa-engineer will fall back to static QA
+# Do not block here; the agent will handle it
+```
+
+## Step 3: Confirm dev server URL
+
+If `--url` is not given, ask:
+```
+AskUserQuestion:
+  question: "What is your dev server URL?"
+  options:
+    - http://localhost:3000 (common)
+    - http://localhost:5173 (Vite)
+    - Other (custom)
+```
+
+## Step 4: Dispatch Oliver
+
+```
+Task:
+  subagent_type: general-purpose
+  description: "QA: $SPEC_NAME"
+  prompt: |
+    You are the flow-qa-engineer agent (Oliver). Full definition:
+    ${CLAUDE_PLUGIN_ROOT}/agents/flow-qa-engineer.md
+    
+    Target:
+    spec_name: $SPEC_NAME
+    URL: $URL
+    
+    Prerequisites:
+    - .flow/specs/$SPEC_NAME/requirements.md (AC list)
+    - .flow/specs/$SPEC_NAME/design.md (error paths + NFR)
+    
+    Workflow:
+    1. Detect chrome-devtools MCP (mcp__chrome-devtools__*)
+       - Available → real-browser QA
+       - Unavailable → static QA, clearly inform the user
+    2. Run the happy path (once per AC)
+    3. Run edge cases (at least 4 of the 7 categories in edge-case-gate)
+    4. Performance trace (LCP / INP / CLS)
+    5. Accessibility scan
+    6. Save screenshots to .flow/specs/$SPEC_NAME/qa-screenshots/
+    7. Generate .flow/specs/$SPEC_NAME/qa-report.md
+    
+    Return to me:
+    - Bug count (categorized by severity)
+    - Performance data (measured, not estimated)
+    - Accessibility warnings
+    - Recommended next steps
+```
+
+## Step 5: Read + report
+
+```bash
+REPORT=".flow/specs/$SPEC_NAME/qa-report.md"
+[ ! -f "$REPORT" ] && { echo "⚠ QA report was not generated"; exit 1; }
+
+HIGH_BUGS=$(grep -c "\[high\]" "$REPORT" || echo 0)
+MED_BUGS=$(grep -c "\[medium\]" "$REPORT" || echo 0)
+LOW_BUGS=$(grep -c "\[low\]" "$REPORT" || echo 0)
+```
+
+## Step 6: Output to user
+
+```
+🔬 QA complete: $SPEC_NAME
+
+Findings:
+  [high]: $HIGH_BUGS
+  [medium]: $MED_BUGS
+  [low]: $LOW_BUGS
+
+Report: .flow/specs/$SPEC_NAME/qa-report.md
+Screenshots: .flow/specs/$SPEC_NAME/qa-screenshots/
+
+Next steps:
+- Fix high-severity bugs → /curdx-flow:implement --task=QA-fix
+- Or add tasks to Phase 3.X in tasks.md
+- Retest: /curdx-flow:qa
+```
+
+## Error recovery
+
+- chrome-devtools MCP not installed → recommend `/curdx-flow:install-deps` or `claude mcp add chrome-devtools`
+- Dev server not running → prompt the user to start it and rerun
+- URL not accessible → prompt to check (`curl -I $URL`)

package/commands/requirements.md

@@ -0,0 +1,146 @@
+---
+name: requirements
+description: Run the requirements stage — dispatch the flow-product-designer agent to generate user stories + FR/NFR, producing requirements.md
+argument-hint: "[spec-name]"
+allowed-tools: [Read, Write, Bash, Task, AskUserQuestion]
+---
+
+# Requirements Stage
+
+Dispatch the `flow-product-designer` agent to translate research directions into user stories.
+
+## Step 1: Resolve spec + preflight checks
+
+```bash
+SPEC_NAME="${ARGUMENTS:-$(cat .flow/.active-spec 2>/dev/null)}"
+
+[ -z "$SPEC_NAME" ] && { echo "❌ Run /curdx-flow:start first"; exit 1; }
+[ ! -f ".flow/specs/$SPEC_NAME/research.md" ] && {
+    echo "❌ research.md missing. Run /curdx-flow:research first"
+    exit 1
+}
+```
+
+Verify the status of research:
+
+```bash
+python3 -c "
+import re
+fm = open('.flow/specs/$SPEC_NAME/research.md').read()[:500]
+m = re.search(r'status:\s*(\w+)', fm)
+status = m.group(1) if m else 'unknown'
+if status not in ('completed', 'approved'):
+    print(f'⚠ research status: {status}')
+    print('Recommend completing the research stage before continuing')
+"
+```
+
+## Step 2: Open question check
+
+If research.md lists open questions but no user answers are visible, prompt:
+
+```
+⚠ research.md has unanswered open questions:
+  Q1: ...
+  Q2: ...
+
+You can:
+  1. Answer the questions first (write them to STATE.md or state them), then run /curdx-flow:requirements
+  2. Let the agent continue based on reasonable assumptions (assumptions will be listed explicitly in requirements.md)
+
+Continue? (continue / answer / skip)
+```
+
+Use AskUserQuestion.
+
+## Step 3: Update state + dispatch agent
+
+```python
+# Mark in_progress
+import json
+s = json.load(open(f'.flow/specs/{SPEC_NAME}/.state.json'))
+s.setdefault('phase_status',{})['requirements']='in_progress'
+s['phase']='requirements'
+json.dump(s, open(f'.flow/specs/{SPEC_NAME}/.state.json','w'), indent=2, ensure_ascii=False)
+```
+
+Task dispatch:
+
+```
+Task:
+  subagent_type: general-purpose
+  description: "Requirements design $SPEC_NAME"
+  prompt: |
+    You are the flow-product-designer agent. Full definition at:
+    ${CLAUDE_PLUGIN_ROOT}/agents/flow-product-designer.md
+    
+    Prerequisite files:
+    - .flow/specs/$SPEC_NAME/research.md (must read)
+    - .flow/PROJECT.md
+    - .flow/CONTEXT.md
+    
+    Template:
+    ${CLAUDE_PLUGIN_ROOT}/templates/requirements.md.tmpl
+    
+    Output:
+    .flow/specs/$SPEC_NAME/requirements.md
+    
+    Workflow:
+    1. Read research.md to understand recommended directions
+    2. Generate user stories (US-NN) — at least 2
+    3. At least 3 acceptance criteria per US (AC-X.Y), must cover happy path + edges + errors
+    4. Extract FR (functional requirements) + NFR (at least performance and security)
+    5. Explicit Out of Scope (at least 3 items)
+    6. List open questions (if user decisions are needed)
+    7. Update .state.json and .progress.md
+    
+    If multiple reasonable interpretations exist, you MUST AskUserQuestion — do not silently pick a direction.
+    
+    Success criteria:
+    - At least 2 US, all from the user's perspective (non-technical language)
+    - Each AC testable (can be written as curl / assert)
+    - At least 3 FR, NFR covers at least P and S
+    - Out of Scope lists at least 3 items
+    
+    Return a brief when finished.
+```
+
+## Step 4: Output verification
+
+```bash
+REQ_FILE=".flow/specs/$SPEC_NAME/requirements.md"
+
+# Count US / FR / AC
+US_COUNT=$(grep -c "^### US-" "$REQ_FILE" || echo 0)
+FR_COUNT=$(grep -c "^- \*\*FR-" "$REQ_FILE" || echo 0)
+AC_COUNT=$(grep -c "^- AC-" "$REQ_FILE" || echo 0)
+
+echo "  US: $US_COUNT, FR: $FR_COUNT, AC: $AC_COUNT"
+
+# Minimum requirements
+[ "$US_COUNT" -lt 2 ] && echo "⚠ Fewer than 2 user stories"
+[ "$FR_COUNT" -lt 3 ] && echo "⚠ Fewer than 3 functional requirements"
+[ "$AC_COUNT" -lt 6 ] && echo "⚠ Fewer than 6 acceptance criteria (average < 3 per US)"
+```
+
+## Step 5: Output
+
+```
+✓ requirements stage complete
+
+File:                .flow/specs/$SPEC_NAME/requirements.md
+User stories:        N
+Functional reqs:     M
+Acceptance criteria: K
+
+Next steps:
+  - Review requirements.md
+  - If the agent listed open questions, answer them before entering design
+  - /curdx-flow:design  — enter design stage
+```
+
+## Error recovery
+
+- research.md missing → prompt to run /curdx-flow:research first
+- Agent times out → requirements may be too complex, consider splitting into an Epic (/curdx-flow:triage, see Phase 4)
+- Agent made a major interpretation without asking the user → the user can annotate requirements.md and request a correction

package/commands/research.md

@@ -0,0 +1,141 @@
+---
+name: research
+description: Run the research stage — dispatch the flow-researcher agent to deeply explore the problem, producing research.md
+argument-hint: "[spec-name]"
+allowed-tools: [Read, Write, Bash, Task]
+---
+
+# Research Stage
+
+Dispatch the `flow-researcher` agent to complete the research stage of a spec.
+
+## Step 1: Resolve target spec
+
+```bash
+# Use the argument if provided; otherwise use the active spec
+if [ -n "$ARGUMENTS" ]; then
+    SPEC_NAME="$ARGUMENTS"
+else
+    SPEC_NAME=$(cat .flow/.active-spec 2>/dev/null)
+fi
+
+if [ -z "$SPEC_NAME" ] || [ ! -d ".flow/specs/$SPEC_NAME" ]; then
+    echo "❌ Spec does not exist. Use /curdx-flow:start <name> \"<goal>\" to create a new spec"
+    exit 1
+fi
+```
+
+## Step 2: Preflight checks
+
+```bash
+# The research stage has no prerequisites; just verify the spec directory is ready
+if [ ! -f ".flow/specs/$SPEC_NAME/.state.json" ]; then
+    echo "❌ Spec state file missing. Run /curdx-flow:start to re-initialize"
+    exit 1
+fi
+```
+
+If research.md already exists with status=completed:
+- Ask the user whether to overwrite (AskUserQuestion)
+- Default: do not overwrite; suggest `/curdx-flow:requirements` to move to the next step
+
+## Step 3: Update state
+
+```bash
+# Mark the research stage as in_progress
+python3 <<'EOF'
+import json
+from pathlib import Path
+state_file = Path(f".flow/specs/$SPEC_NAME/.state.json")
+state = json.loads(state_file.read_text())
+state.setdefault("phase_status", {})["research"] = "in_progress"
+state["phase"] = "research"
+state_file.write_text(json.dumps(state, indent=2, ensure_ascii=False))
+EOF
+```
+
+## Step 4: Dispatch the flow-researcher agent
+
+Using the Task tool:
+
+```
+Task:
+  subagent_type: general-purpose
+  description: "Research $SPEC_NAME"
+  prompt: |
+    You are the flow-researcher agent. Your full responsibilities and workflow are at:
+    ${CLAUDE_PLUGIN_ROOT}/agents/flow-researcher.md
+    
+    Spec prerequisites to read:
+    - .flow/specs/$SPEC_NAME/.state.json (goal + state)
+    - .flow/PROJECT.md
+    - .flow/CONTEXT.md  
+    - .flow/STATE.md
+    
+    Template (you must populate and write to research.md):
+    ${CLAUDE_PLUGIN_ROOT}/templates/research.md.tmpl
+    
+    Output file:
+    .flow/specs/$SPEC_NAME/research.md
+    
+    Workflow requirements:
+    1. Load context (Step 1)
+    2. Call mcp__claude_mem__search to retrieve history (Step 2)
+    3. sequential-thinking 5+ rounds for problem understanding (Step 3)
+    4. Glob/Grep to scan existing code (Step 4)
+    5. context7 to look up the latest docs for 2-3 technical options (Step 5)
+    6. WebSearch to supplement (Step 6, if needed)
+    7. Write research.md (based on the template, replacing placeholders)
+    8. Update .state.json and .progress.md (Step 8)
+    
+    Success criteria:
+    - research.md exists and matches the template structure
+    - Problem understanding section has 3+ explicit assumptions
+    - 2-3 technical options, each referencing context7 results
+    - Code analysis includes actual file paths found
+    - Recommended direction + rationale is clear
+    - At least 1 open question (unless the research is fully unambiguous)
+    
+    Forbidden:
+    - Writing library APIs from memory
+    - Skipping context7 queries
+    - sequentialthinking < 5 rounds
+    - Creating any new files outside research.md
+    
+    When done, return a brief (findings, recommendations, open questions).
+```
+
+## Step 5: After the agent completes
+
+Read the agent-generated research.md and verify that key sections exist:
+
+```bash
+for section in "Problem Understanding" "Technical Options" "Existing Code Analysis" "Feasibility" "Recommended Direction"; do
+    if ! grep -q "$section" ".flow/specs/$SPEC_NAME/research.md" 2>/dev/null; then
+        echo "⚠ research.md missing section: $section"
+    fi
+done
+```
+
+If any section is missing, emit a warning but do not block (the user decides whether to re-run).
+
+## Step 6: Output suggestions
+
+```
+✓ research stage complete
+
+File:     .flow/specs/$SPEC_NAME/research.md
+
+Next steps:
+  - Read research.md and confirm the recommended direction is reasonable
+  - Answer the open questions listed by the agent (if any)
+  - /curdx-flow:requirements  — enter the requirements stage
+  
+  To re-research, just run /curdx-flow:research again
+```
+
+## Error recovery
+
+- research.md generation fails → check MCP status (/curdx-flow:doctor), retry
+- Agent exceeds 40 turns → the research is too complex, narrow the target scope
+- context7 unavailable → the agent falls back to WebSearch, but must explicitly inform the user