@curdx/flow 1.1.4 → 1.1.6

package/commands/start.md

@@ -0,0 +1,189 @@
+---
+name: start
+description: intelligent entry point — create a new spec or resume an existing one, entering the corresponding phase
+argument-hint: "<spec-name> \"<goal>\""
+allowed-tools: [Read, Write, Bash, AskUserQuestion]
+---
+
+# Start a Spec
+
+CurDX-Flow's main entry point. Based on context, automatically:
+- New spec → create directory + templates + enter research phase
+- Existing spec → resume from the last phase
+
+## Step 1: Preflight Check
+
+```bash
+# Must be initialized
+if [ ! -d ".flow" ]; then
+    echo "❌ Current directory is not a CurDX-Flow project. Run /curdx-flow:init first"
+    exit 1
+fi
+```
+
+## Step 2: Parse Arguments
+
+```bash
+ARGS="$ARGUMENTS"
+
+# Extract spec-name and goal
+# Format: flow-start my-feature "Add JWT auth to API"
+#         or: flow-start my-feature  (resume existing spec)
+SPEC_NAME=$(echo "$ARGS" | awk '{print $1}')
+GOAL=$(echo "$ARGS" | sed -E "s/^[a-z0-9-]+\s*//" | sed 's/^["\x27]//;s/["\x27]$//')
+
+if [ -z "$SPEC_NAME" ]; then
+    echo "Usage: /curdx-flow:start <spec-name> \"<goal>\""
+    echo "Example: /curdx-flow:start auth-system \"Add JWT authentication to REST API\""
+    exit 1
+fi
+
+# Validate that spec-name is kebab-case
+if ! echo "$SPEC_NAME" | grep -Eq '^[a-z][a-z0-9-]*$'; then
+    echo "❌ spec-name must be kebab-case (start with lowercase letter, only letters, digits, hyphens)"
+    exit 1
+fi
+```
+
+## Step 3: Determine New vs Resume
+
+```bash
+SPEC_DIR=".flow/specs/$SPEC_NAME"
+
+if [ -d "$SPEC_DIR" ]; then
+    # Resume mode
+    MODE="resume"
+    echo "🔄 Resuming spec: $SPEC_NAME"
+else
+    # New mode
+    MODE="new"
+    echo "🆕 New spec: $SPEC_NAME"
+    
+    if [ -z "$GOAL" ]; then
+        # If no goal given, ask the user
+        echo "Please provide a one-sentence goal, then continue."
+        exit 0
+    fi
+fi
+```
+
+## Step 4a: New Path
+
+If `MODE=new`:
+
+```bash
+# Create directory
+mkdir -p "$SPEC_DIR"
+
+# Generate .state.json
+TODAY=$(date +%Y-%m-%d)
+CONFIG_MODE=$(python3 -c "import json; print(json.load(open('.flow/config.json')).get('mode','standard'))" 2>/dev/null || echo "standard")
+
+cat > "$SPEC_DIR/.state.json" <<EOF
+{
+  "version": "1.0",
+  "spec_name": "$SPEC_NAME",
+  "goal": "$GOAL",
+  "mode": "$CONFIG_MODE",
+  "strategy": "auto",
+  "phase": "research",
+  "phase_status": {
+    "research": "not_started",
+    "requirements": "not_started",
+    "design": "not_started",
+    "tasks": "not_started"
+  },
+  "decisions": [],
+  "created": "$TODAY",
+  "updated": "$TODAY"
+}
+EOF
+
+# Generate progress.md (from template)
+python3 <<PYEOF
+from pathlib import Path
+tmpl = Path("${CLAUDE_PLUGIN_ROOT}/templates/progress.md.tmpl").read_text()
+content = tmpl.replace("{{SPEC_NAME}}", "$SPEC_NAME").replace("{{CREATED_DATE}}", "$TODAY")
+Path("$SPEC_DIR/.progress.md").write_text(content)
+PYEOF
+
+# Set as active spec
+echo "$SPEC_NAME" > ".flow/.active-spec"
+
+echo "✓ Spec directory created: $SPEC_DIR"
+echo "  Goal: $GOAL"
+echo ""
+echo "Next step (automatically entering research):"
+echo "  /curdx-flow:research"
+```
+
+## Step 4b: Resume Path
+
+If `MODE=resume`:
+
+```bash
+# Read current phase
+STATE_FILE="$SPEC_DIR/.state.json"
+if [ ! -f "$STATE_FILE" ]; then
+    echo "✗ Spec directory exists but .state.json is missing. State may be corrupted."
+    # Ask user
+    # AskUserQuestion: "Rebuild state file?" (yes/no)
+    exit 0
+fi
+
+# Set as active
+echo "$SPEC_NAME" > ".flow/.active-spec"
+
+# Show current progress
+python3 <<PYEOF
+import json
+s = json.load(open("$STATE_FILE"))
+print(f"✓ Spec activated: $SPEC_NAME")
+print(f"  Goal:        {s.get('goal','(undefined)')}")
+print(f"  Current phase: {s['phase']}")
+print(f"  Progress:")
+
+ph_emoji = {"completed": "✓", "in_progress": "●", "not_started": "○", "failed": "✗", "skipped": "—"}
+for phase, status in s.get('phase_status',{}).items():
+    emoji = ph_emoji.get(status, "?")
+    print(f"    {emoji} {phase:<15} {status}")
+
+print()
+
+# Recommend next step
+phase_order = ["research", "requirements", "design", "tasks", "execute", "verify", "ship"]
+for p in phase_order:
+    st = s.get('phase_status',{}).get(p, 'not_started')
+    if st in ("not_started", "in_progress"):
+        print(f"Next step: /curdx-flow:{p}")
+        break
+else:
+    print("All phases complete! Use /curdx-flow:status to see details.")
+PYEOF
+```
+
+## Step 5: Summary Prompt
+
+```
+═══════════════════════════════════════════════
+✓ Spec ready: $SPEC_NAME
+
+Workflow:
+  1. /curdx-flow:research       ← research (deep exploration)
+  2. /curdx-flow:requirements   ← requirements (user stories + acceptance criteria)
+  3. /curdx-flow:design         ← design (architectural decisions, freeze choices)
+  4. /curdx-flow:tasks          ← task decomposition (auto-verifiable tasks)
+  
+  One-shot version: /curdx-flow:spec    ← run research/req/design/tasks in sequence
+
+Fast modes:
+  /curdx-flow:fast              ← skip spec and implement directly
+  /curdx-flow:sketch            ← UI prototype exploration
+═══════════════════════════════════════════════
+```
+
+## Error Recovery
+
+- `.flow/` does not exist → prompt `/curdx-flow:init`
+- spec-name invalid → provide kebab-case example
+- Spec directory corrupted → ask user whether to delete-and-rebuild or repair

package/commands/status.md

@@ -0,0 +1,139 @@
+---
+name: status
+description: view the current state of the CurDX-Flow project (specs, phases, progress)
+argument-hint: "[--all | <spec-name>]"
+allowed-tools: [Read, Bash, Glob]
+---
+
+# Project Status
+
+Shows an overview of the current state of the CurDX-Flow project.
+
+## Execution Steps
+
+### Step 1: Confirm the Project
+
+```bash
+if [ ! -d ".flow" ]; then
+    echo "✗ Current directory is not a CurDX-Flow project. Run /curdx-flow:init to initialize."
+    exit 0
+fi
+```
+
+### Step 2: Load Global State
+
+```bash
+# Active spec
+ACTIVE=$(cat .flow/.active-spec 2>/dev/null || echo "(none)")
+
+# Project config
+if [ -f ".flow/config.json" ]; then
+    MODE=$(python3 -c "import json; print(json.load(open('.flow/config.json')).get('mode','standard'))")
+fi
+```
+
+### Step 3: Scan Specs
+
+```bash
+# List all specs
+SPECS=$(ls -1 .flow/specs/ 2>/dev/null)
+
+# List all Epics
+EPICS=$(ls -1 .flow/_epics/ 2>/dev/null)
+```
+
+For each spec, read `.state.json` to get phase and progress:
+
+```bash
+for spec in $SPECS; do
+    STATE_FILE=".flow/specs/$spec/.state.json"
+    if [ -f "$STATE_FILE" ]; then
+        PHASE=$(python3 -c "import json; print(json.load(open('$STATE_FILE')).get('phase','unknown'))")
+        # Can also fetch task_index, total_tasks, etc.
+    fi
+done
+```
+
+### Step 4: Output Format
+
+**Default (no arguments)** — global overview:
+
+```
+📋 CurDX-Flow Project Status
+═══════════════════════════════════════
+
+Project:       my-awesome-app
+Mode:          standard
+Active spec:   auth-system
+
+Spec list:
+  ● auth-system          design          (45% — tasks pending)
+  ○ user-profile         execute         (60% — 12/20 tasks)
+  ✓ onboarding-flow      completed       (archived)
+
+Epic list:
+  ● payment-system       3/5 sub-specs   (in progress)
+
+Recent decisions (STATE.md):
+  D-05: use JWT instead of session cookie (2026-04-15)
+  D-06: bcrypt cost factor = 12 (2026-04-15)
+
+═══════════════════════════════════════
+Next step suggestion: /curdx-flow:tasks   — generate task list for auth-system
+```
+
+**`<spec-name>`** — detail for a specific spec:
+
+```
+📋 Spec: auth-system
+═══════════════════════════════════════
+
+Phase:      design
+Progress:   45%
+Created:    2026-04-12
+
+Completed phases:
+  ✓ research        (research.md, 320 lines)
+  ✓ requirements    (requirements.md, 8 stories)
+  ● design          (design.md, in progress)
+  ○ tasks
+  ○ execute
+
+Related decisions:
+  D-05: use JWT instead of session cookie
+
+.progress.md summary:
+  - Confirmed JWT + refresh token architecture
+  - Researched bcrypt vs argon2, chose bcrypt (team familiarity)
+  - TODO: design token refresh flow
+
+Next step: /curdx-flow:tasks — generate task list
+```
+
+**`--all`** — detailed mode, every spec expanded.
+
+### Step 5: Empty-State Handling
+
+If `.flow/` exists but no specs:
+
+```
+📋 CurDX-Flow Project
+═══════════════════════════════════════
+
+Project:       my-awesome-app (just initialized)
+Mode:          standard
+Active spec:   (none)
+
+No specs yet.
+
+Start your first feature:
+  /curdx-flow:start <name> "<describe what you want to do>"
+
+Example:
+  /curdx-flow:start auth-system "Add JWT authentication to API"
+```
+
+## Notes
+
+- State data is read-only; this command does not modify any files
+- If `.state.json` is corrupted or missing, degrade gracefully (show "state unknown" instead of failing)

package/commands/switch.md

@@ -0,0 +1,95 @@
+---
+name: switch
+description: switch the active spec (updates .flow/.active-spec)
+argument-hint: "<spec-name>"
+allowed-tools: [Read, Write, Bash]
+---
+
+# Switch Active Spec
+
+Switch between multiple specs. The active spec is the default target for commands like `/curdx-flow:research`, `/curdx-flow:requirements`, etc.
+
+## Step 1: Preflight Check
+
+```bash
+[ ! -d ".flow" ] && { echo "❌ Not a CurDX-Flow project. Run /curdx-flow:init first"; exit 1; }
+
+SPEC_NAME="$ARGUMENTS"
+if [ -z "$SPEC_NAME" ]; then
+    # No arguments → list all specs and prompt
+    echo "Current spec list:"
+    if [ -d ".flow/specs" ]; then
+        for spec in .flow/specs/*/; do
+            name=$(basename "$spec")
+            active=""
+            [ "$name" = "$(cat .flow/.active-spec 2>/dev/null)" ] && active=" ← currently active"
+            
+            # Read phase
+            phase=$(python3 -c "import json; print(json.load(open('$spec/.state.json')).get('phase','?'))" 2>/dev/null || echo "?")
+            echo "  • $name  (phase: $phase)$active"
+        done
+    fi
+    echo ""
+    echo "Usage: /curdx-flow:switch <spec-name>"
+    exit 0
+fi
+```
+
+## Step 2: Verify Target Spec Exists
+
+```bash
+SPEC_DIR=".flow/specs/$SPEC_NAME"
+if [ ! -d "$SPEC_DIR" ]; then
+    echo "❌ Spec does not exist: $SPEC_NAME"
+    echo ""
+    echo "Existing specs:"
+    ls .flow/specs/ 2>/dev/null || echo "  (none)"
+    echo ""
+    echo "Create a new spec: /curdx-flow:start $SPEC_NAME \"<goal>\""
+    exit 1
+fi
+```
+
+## Step 3: Perform the Switch
+
+```bash
+# Save old one for reference
+OLD_ACTIVE=$(cat .flow/.active-spec 2>/dev/null || echo "(none)")
+
+# Update
+echo "$SPEC_NAME" > .flow/.active-spec
+
+echo "✓ Active spec: $OLD_ACTIVE → $SPEC_NAME"
+```
+
+## Step 4: Display New Spec Status
+
+```python
+import json, os
+s = json.load(open(f"$SPEC_DIR/.state.json"))
+
+print(f"\n📋 {s['spec_name']}")
+print(f"   Goal:         {s.get('goal','(undefined)')}")
+print(f"   Current phase: {s['phase']}")
+
+# Phase progress bar
+phases = ["research","requirements","design","tasks","execute","verify","ship"]
+ph_status = s.get('phase_status', {})
+bar = []
+for p in phases:
+    st = ph_status.get(p, 'not_started')
+    bar.append({"completed":"✓","in_progress":"●","not_started":"○","failed":"✗","skipped":"—"}.get(st,"?"))
+print(f"   Progress:     {' → '.join(bar)}")
+print(f"                 {' → '.join(phases)}")
+
+# Suggest next step
+for p in phases:
+    if ph_status.get(p, 'not_started') in ("not_started","in_progress"):
+        print(f"\n   Suggested next step: /curdx-flow:{p}")
+        break
+```
+
+## Error Recovery
+
+- `.flow/.active-spec` permission error → check write permissions on `.flow/`
+- .state.json corrupted → prompt `/curdx-flow:start <name>` to rebuild

package/commands/tasks.md

@@ -0,0 +1,189 @@
+---
+name: tasks
+description: run the task decomposition phase — dispatch the flow-planner agent to decompose along POC-First 5 Phases and perform multi-source coverage audit. Produces tasks.md
+argument-hint: "[spec-name] [--fine | --coarse]"
+allowed-tools: [Read, Write, Bash, Task]
+---
+
+# Task Decomposition Phase
+
+Dispatch the `flow-planner` agent to decompose the design into an auto-verifiable task list.
+
+## Step 1: Parse Arguments
+
+```bash
+# Support --fine / --coarse to override project default
+TASK_SIZE="fine"
+ARGS="$ARGUMENTS"
+case "$ARGS" in
+    *--coarse*) TASK_SIZE="coarse" ;;
+    *--fine*)   TASK_SIZE="fine"   ;;
+    *)
+        # Read default from .flow/config.json
+        TASK_SIZE=$(python3 -c "
+import json
+try:
+    c = json.load(open('.flow/config.json'))
+    print(c.get('specs',{}).get('default_task_size','fine'))
+except: print('fine')
+")
+        ;;
+esac
+
+SPEC_NAME="$(echo "$ARGS" | sed 's/--[a-z]*//g' | xargs)"
+[ -z "$SPEC_NAME" ] && SPEC_NAME=$(cat .flow/.active-spec 2>/dev/null)
+```
+
+## Step 2: Preflight Check
+
+```bash
+DIR=".flow/specs/$SPEC_NAME"
+for f in research.md requirements.md design.md; do
+    [ ! -f "$DIR/$f" ] && { echo "❌ Missing $f"; exit 1; }
+done
+```
+
+## Step 3: Detect Project Commands (for planner reference)
+
+```bash
+# Collect actual project commands
+PKG_MGR="npm"; TEST_CMD=""; LINT_CMD=""; BUILD_CMD=""
+if [ -f "package.json" ]; then
+    command -v pnpm >/dev/null && [ -f "pnpm-lock.yaml" ] && PKG_MGR="pnpm"
+    command -v bun  >/dev/null && [ -f "bun.lockb" ]     && PKG_MGR="bun"
+    command -v yarn >/dev/null && [ -f "yarn.lock" ]     && PKG_MGR="yarn"
+    
+    # Parse scripts
+    TEST_CMD=$(python3 -c "import json; print(json.load(open('package.json')).get('scripts',{}).get('test',''))" 2>/dev/null)
+    LINT_CMD=$(python3 -c "import json; print(json.load(open('package.json')).get('scripts',{}).get('lint',''))" 2>/dev/null)
+    BUILD_CMD=$(python3 -c "import json; print(json.load(open('package.json')).get('scripts',{}).get('build',''))" 2>/dev/null)
+fi
+
+cat > "/tmp/flow-cmds.txt" <<EOF
+Package Manager: $PKG_MGR
+Test:  ${TEST_CMD:-<no test script>}
+Lint:  ${LINT_CMD:-<no lint script>}
+Build: ${BUILD_CMD:-<no build script>}
+EOF
+```
+
+## Step 4: Update State + Dispatch
+
+```python
+import json
+p = f'.flow/specs/{SPEC_NAME}/.state.json'
+s = json.load(open(p))
+s.setdefault('phase_status',{})['tasks']='in_progress'
+s['phase']='tasks'
+s['task_size'] = TASK_SIZE  # 'fine' or 'coarse'
+json.dump(s, open(p,'w'), indent=2, ensure_ascii=False)
+```
+
+Dispatch Task:
+
+```
+Task:
+  subagent_type: general-purpose
+  description: "task decomposition $SPEC_NAME"
+  prompt: |
+    You are the flow-planner agent. Full definition at:
+    ${CLAUDE_PLUGIN_ROOT}/agents/flow-planner.md
+    
+    Prerequisites (must read):
+    - .flow/specs/$SPEC_NAME/research.md
+    - .flow/specs/$SPEC_NAME/requirements.md
+    - .flow/specs/$SPEC_NAME/design.md
+    - .flow/STATE.md
+    - .flow/CONTEXT.md
+    
+    Template:
+    ${CLAUDE_PLUGIN_ROOT}/templates/tasks.md.tmpl
+    
+    Knowledge base:
+    - ${CLAUDE_PLUGIN_ROOT}/knowledge/poc-first-workflow.md (**must read**)
+    
+    Project-detected commands (use these, do not assume):
+    ---
+    $(cat /tmp/flow-cmds.txt)
+    ---
+    
+    Task size: $TASK_SIZE (fine=40-60 tasks, coarse=10-20 tasks)
+    
+    Output:
+    .flow/specs/$SPEC_NAME/tasks.md
+    
+    Mandatory requirements:
+    1. Decompose along POC-First 5 Phases (Phase 1-5)
+    2. Each task has 5 fields: Do / Files / Done-when / Verify / Commit
+    3. Verify **must be an automated command** (no "manual testing")
+    4. At least 1 [VERIFY] checkpoint per Phase
+    5. Mark independent tasks with [P]
+    6. Must end with a **coverage audit table**:
+       - Which tasks correspond to each FR?
+       - Which tasks correspond to each AC?
+       - Which tasks correspond to each AD?
+       - Uncovered items must state the reason
+    
+    Success criteria:
+    - Task count matches task_size requirement
+    - All Verify values are executable commands
+    - Coverage audit table complete
+    - Commit messages follow conventional format
+    
+    Forbidden:
+    - Writing TODO or "manual" in Verify field
+    - Assuming project commands (use the ones detected above)
+    - Skipping FRs for "simplicity"
+    
+    When done, return a brief: task count, Phase distribution, coverage audit result.
+```
+
+## Step 5: Coverage Audit Verification
+
+```bash
+TASKS=".flow/specs/$SPEC_NAME/tasks.md"
+
+# Check that the coverage audit table exists
+grep -q "coverage audit" "$TASKS" || echo "✗ Missing coverage audit table"
+
+# Check that every task has Verify
+# Rough: within 10 lines after each "- [ ]" there should be "Verify:"
+TASKS_COUNT=$(grep -c "^- \[ \] \*\*" "$TASKS" || echo 0)
+VERIFY_COUNT=$(grep -c "^\s*\*\*Verify\*\*:" "$TASKS" || echo 0)
+
+if [ "$VERIFY_COUNT" -lt "$TASKS_COUNT" ]; then
+    echo "⚠ Task count $TASKS_COUNT vs Verify count $VERIFY_COUNT (some tasks may be missing the Verify field)"
+fi
+
+# Check for forbidden words
+if grep -iE "(manual|manual test|todo|tbd)" "$TASKS" > /dev/null; then
+    echo "✗ tasks.md contains forbidden words (manual/TODO/TBD); check the Verify field"
+fi
+```
+
+## Step 6: Output
+
+```
+✓ tasks phase complete
+
+File:         .flow/specs/$SPEC_NAME/tasks.md
+Task size:    $TASK_SIZE
+Total tasks:  N
+Phase distribution:
+  POC:        X
+  Refactor:   Y
+  Testing:    Z
+  Quality:    W
+  PR:         V
+
+Coverage audit: FR / AC / AD all ✓
+
+⚠ Phase 2 (Execution Engine) not yet released. tasks.md can be executed manually in order.
+   The /curdx-flow:implement command will be available in the next version.
+```
+
+## Error Recovery
+
+- design.md missing or status is not completed → return to /curdx-flow:design
+- Agent missed some FRs → rerun or manually append tasks at the end of tasks.md
+- Verify contains the word "manual" → rerun and explicitly state "all Verify must be automated"