@curdx/flow 1.1.4 → 1.1.6

package/commands/implement.md

@@ -0,0 +1,381 @@
+---
+name: implement
+description: Execute spec tasks — the Strategy Router picks linear/subagent/stop-hook/wave based on task characteristics. Atomic commit per task.
+argument-hint: "[spec-name] [--strategy=auto|linear|subagent|stop-hook|wave] [--task=<id>] [--quick]"
+allowed-tools: [Read, Write, Edit, Bash, Task, Grep, Glob]
+---
+
+# Flow Implement — Execute Spec
+
+@${CLAUDE_PLUGIN_ROOT}/knowledge/execution-strategies.md
+@${CLAUDE_PLUGIN_ROOT}/knowledge/atomic-commits.md
+
+Execute spec tasks per tasks.md. Select the best execution strategy based on arguments and task characteristics.
+
+## Step 1: Preflight Checks
+
+```bash
+[ ! -d ".flow" ] && { echo "❌ Not a CurDX-Flow project. Run /curdx-flow:init first"; exit 1; }
+
+ARGS="$ARGUMENTS"
+SPEC_NAME=""
+STRATEGY="auto"
+TASK_ID=""
+QUICK=0
+
+# Simple argument parsing
+for arg in $ARGS; do
+    case "$arg" in
+        --strategy=*)  STRATEGY="${arg#--strategy=}" ;;
+        --task=*)      TASK_ID="${arg#--task=}" ;;
+        --quick)       QUICK=1 ;;
+        --*)           ;;  # ignore unknown flags
+        *)             SPEC_NAME="$arg" ;;
+    esac
+done
+
+[ -z "$SPEC_NAME" ] && SPEC_NAME=$(cat .flow/.active-spec 2>/dev/null)
+[ -z "$SPEC_NAME" ] && { echo "❌ No active spec. Run /curdx-flow:start first"; exit 1; }
+
+DIR=".flow/specs/$SPEC_NAME"
+[ ! -f "$DIR/tasks.md" ] && { echo "❌ Missing tasks.md. Run /curdx-flow:tasks first"; exit 1; }
+```
+
+## Step 2: Parse Task Characteristics from tasks.md
+
+```bash
+TOTAL=$(grep -c "^- \[ \] \*\*" "$DIR/tasks.md")
+DONE=$(grep -c "^- \[x\] \*\*" "$DIR/tasks.md")
+REMAINING=$((TOTAL))
+PARALLEL=$(grep -c "^- \[ \] \*\*.*\[P\]" "$DIR/tasks.md")
+SEQUENTIAL=$(grep -c "^- \[ \] \*\*.*\[SEQUENTIAL\]" "$DIR/tasks.md")
+
+echo "Task stats: remaining $REMAINING, done $DONE, [P] parallel $PARALLEL, [SEQUENTIAL] serial $SEQUENTIAL"
+```
+
+## Step 3: Strategy Router
+
+If `STRATEGY=auto` (default), pick via the decision tree:
+
+```bash
+if [ "$STRATEGY" = "auto" ]; then
+    if [ $REMAINING -lt 5 ] || [ $SEQUENTIAL -gt $((REMAINING / 2)) ]; then
+        STRATEGY="linear"
+    elif [ $PARALLEL -ge $((REMAINING * 4 / 10)) ]; then
+        STRATEGY="wave"
+    elif [ $REMAINING -ge 20 ] && [ $QUICK -eq 1 ]; then
+        STRATEGY="stop-hook"
+    elif [ $REMAINING -ge 8 ]; then
+        STRATEGY="subagent"
+    else
+        STRATEGY="linear"
+    fi
+fi
+
+echo "✓ Selected strategy: $STRATEGY"
+```
+
+**Decision tree explanation**:
+- Few tasks / strong dependencies → `linear` (main agent executes sequentially)
+- Many parallel opportunities → `wave` (parallel Task dispatch within a wave)
+- Long chain + quick mode → `stop-hook` (auto-loop, requires hook support)
+- Medium scale → `subagent` (isolated context per task)
+
+## Step 4: Initialize execute_state
+
+```python
+import json
+p = f'.flow/specs/{SPEC_NAME}/.state.json'
+s = json.load(open(p))
+s['phase'] = 'execute'
+s['strategy'] = STRATEGY
+s.setdefault('phase_status', {})['execute'] = 'in_progress'
+s.setdefault('execute_state', {})
+s['execute_state'].setdefault('task_index', DONE)
+s['execute_state']['total_tasks'] = TOTAL
+s['execute_state'].setdefault('failed_attempts', 0)
+s['execute_state'].setdefault('global_iteration', 1)
+if QUICK:
+    s['quickMode'] = True
+json.dump(s, open(p, 'w'), indent=2, ensure_ascii=False)
+```
+
+## Step 5: Execution Strategies
+
+### Strategy: linear
+
+The main agent (you) executes sequentially:
+
+```
+for task in remaining tasks:
+    read task fields (Do/Files/Done-when/Verify/Commit)
+    execute per the flow-executor agent rules:
+      - follow Karpathy surgical principles
+      - Verify must pass
+      - atomic commit
+      - mark [x]
+      - update .progress.md
+    output "✓ Task X.Y complete"
+    next
+output "ALL_TASKS_COMPLETE" when all tasks are done
+```
+
+If there are 5 failures, stop + TASK_FAILED.
+
+### Strategy: subagent
+
+For each remaining task, dispatch flow-executor:
+
+```
+Task:
+  subagent_type: general-purpose
+  description: "Execute $SPEC_NAME task $TASK_ID"
+  prompt: |
+    You are the flow-executor agent. Full definition at:
+    ${CLAUDE_PLUGIN_ROOT}/agents/flow-executor.md
+    
+    Execute task:
+    spec_name: $SPEC_NAME
+    task_id: next  (or a specific ID)
+    quick_mode: $QUICK
+    
+    Required reading:
+    - .flow/specs/$SPEC_NAME/tasks.md (locate the task)
+    - .flow/specs/$SPEC_NAME/.state.json
+    - .flow/specs/$SPEC_NAME/.progress.md
+    - .flow/specs/$SPEC_NAME/design.md (if task references AD-NN)
+    - .flow/specs/$SPEC_NAME/requirements.md (if referencing FR/AC)
+    
+    On success output: TASK_COMPLETE: <task_id>
+    On failure output: TASK_FAILED: <task_id> + Reason
+    
+    When all tasks are done output: ALL_TASKS_COMPLETE
+```
+
+After the agent completes, read the output marker:
+- `TASK_COMPLETE` → continue to the next
+- `TASK_FAILED` → accumulate failures, stop at >= 3
+- `ALL_TASKS_COMPLETE` → mark phase completed
+
+### Strategy: wave
+
+@${CLAUDE_PLUGIN_ROOT}/knowledge/wave-execution.md
+
+**Core**: consecutive `[P]` tasks form a wave, dispatch multiple Tasks in parallel within a single message, serial across waves.
+
+#### Step 1: DAG Analysis
+
+Read remaining `[ ]` tasks from tasks.md and group per the rules:
+
+```
+for task in remaining tasks:
+    if task has [SEQUENTIAL] or [VERIFY]:
+        → own wave (breaks parallelism)
+    elif task has [P]:
+        → check whether Files conflict with current_wave
+          conflict → start a new wave
+          no conflict → add to current_wave
+    else:
+        → own wave (no [P] = serial)
+```
+
+Output wave list:
+```
+Wave 1 [P×3]: 1.1 1.2 1.3
+Wave 2 [VERIFY]: 1.4
+Wave 3: 1.5
+Wave 4 [P×2]: 1.6 1.7
+```
+
+#### Step 2: Pre-Conflict Detection
+
+For each wave, verify that Files across all tasks are **disjoint**:
+
+```python
+for wave in waves:
+    all_files = []
+    for task in wave:
+        if set(task.files) & set(all_files):
+            warn(f"Within wave, {task.id} modifies the same file as a prior task")
+            # split into the next wave
+        all_files.extend(task.files)
+```
+
+If the planner mis-tagged `[P]` (modifies the same file), split the wave automatically at execution time rather than failing outright.
+
+#### Step 3: Dispatch a Single Wave (**key: within a single response**)
+
+```
+# List multiple Task tool calls in one response of the main agent:
+Task(description="Execute 1.1", prompt=<...flow-executor + task_id=1.1...>)
+Task(description="Execute 1.2", prompt=<...flow-executor + task_id=1.2...>)
+Task(description="Execute 1.3", prompt=<...flow-executor + task_id=1.3...>)
+```
+
+Each Task prompt follows a uniform format (similar to subagent strategy):
+
+```
+You are the flow-executor agent. Full definition:
+${CLAUDE_PLUGIN_ROOT}/agents/flow-executor.md
+
+Execute a single task:
+  spec_name: $SPEC_NAME
+  task_id: <specific ID, e.g., 1.2>
+  quick_mode: $QUICK
+
+**You may only modify the following files** (touching anything else is disallowed):
+  <task.files>
+
+Required reading:
+- .flow/specs/$SPEC_NAME/tasks.md
+- .flow/specs/$SPEC_NAME/.state.json  
+- .flow/specs/$SPEC_NAME/design.md (if referencing AD-NN)
+
+Output:
+- TASK_COMPLETE: <task_id>  or
+- TASK_FAILED: <task_id> + reason
+```
+
+**Not allowed**:
+- Splitting multiple Task calls across multiple responses (that is serial degradation)
+- Nesting another Task dispatch inside a Task
+
+#### Step 4: Aggregate Wave Results
+
+Wait for all Tasks to return:
+
+```python
+completed = []; failed = []
+for task, result in zip(wave, results):
+    if "TASK_COMPLETE" in result:
+        completed.append(task)
+    elif "TASK_FAILED" in result:
+        failed.append(task)
+
+# Post-hoc conflict detection (verify executors did not touch out-of-scope files)
+for task in completed:
+    actual_files = git_diff_files_touched_by(task)
+    declared = set(task.files)
+    unexpected = actual_files - declared
+    if unexpected:
+        warn(f"Task {task.id} modified undeclared files: {unexpected}")
+```
+
+#### Step 5: Wave Failure Handling
+
+```
+len(failed) == 0:
+  → continue to the next wave
+
+len(failed) == 1:
+  → failed_attempts += 1
+  → based on config.wave_fail_policy:
+      "continue-on-single": continue to the next wave, report failure at the end
+      "stop-on-any": stop immediately
+
+len(failed) >= 2:
+  → likely environment issue (missing deps/tsc error/permissions)
+  → stop immediately, suggest /curdx-flow:doctor
+  
+failed_attempts >= 3 (cumulative):
+  → stop, user intervention required
+```
+
+#### Step 6: Progress Feedback
+
+```
+▶ Wave 2/5 complete
+  ✓ 1.1 feat(auth): create module skeleton (abc123)
+  ✓ 1.2 feat(user): create user types (def456)
+  ✓ 1.3 feat(session): init token module (ghi789)
+
+▶ Wave 3/5 starting (VERIFY)...
+```
+
+#### Configuration
+
+`.flow/config.json`:
+```json
+{
+  "execution": {
+    "strategy": "wave",
+    "max_parallel": 5,
+    "wave_fail_policy": "continue-on-single"
+  }
+}
+```
+
+- `max_parallel`: max N parallel within a wave (to avoid API rate limits, default 5)
+- `wave_fail_policy`: single-task failure behavior
+
+#### Pitfalls (see knowledge/wave-execution.md for the detailed version)
+
+- Stray `[P]` → conflict detection as a safety net
+- Wave too large → max_parallel auto-splits
+- Implicit read-write dependencies → planner should avoid this kind of `[P]`
+
+### Strategy: stop-hook
+
+```
+1. Execute 1 task (dispatch flow-executor, wait for completion)
+2. Do not loop manually — rely on the stop-watcher.sh hook
+3. Stop event triggers → hook checks if there are remaining tasks → injects "continue"
+4. Claude auto-starts next round
+5. Repeat until ALL_TASKS_COMPLETE or 3 failures
+```
+
+Prerequisites:
+- `--quick` must be set (otherwise AskUserQuestion will block the loop)
+- `.flow/config.json` or `.state.json` must have strategy=stop-hook
+
+## Step 6: Progress Feedback
+
+Every 5 tasks or every wave, print status:
+
+```
+═════ Progress ═════
+Spec:      $SPEC_NAME
+Strategy:  $STRATEGY
+Done:      X / $TOTAL
+Recent commits:
+  - abc123f feat(auth): ...
+  - def456g test(auth): ...
+════════════════════
+```
+
+## Step 7: Completion Handling
+
+```
+if all tasks done:
+    update .state.json:
+        phase = "verify"
+        phase_status.execute = "completed"
+    append .progress.md: "## execute phase complete YYYY-MM-DD"
+    output "ALL_TASKS_COMPLETE"
+    suggest next step: /curdx-flow:verify
+```
+
+## Error Recovery
+
+- Verify field in tasks.md is "manual" → stop, suggest re-running /curdx-flow:tasks to fix
+- 3 consecutive TASK_FAILED → stop, prompt for user intervention
+- git operation failure → stop immediately, do not continue (avoid state corruption)
+- Test framework not found (npm test not found) → stop, suggest running /curdx-flow:doctor
+
+## Output to User
+
+```
+✓ execute phase complete: $SPEC_NAME
+
+Strategy:       $STRATEGY
+Tasks done:     N / N
+Commits:        M atomic commits
+Verify passed:  K / K
+
+Next steps:
+  - /curdx-flow:verify  — goal-driven reverse verification (after Phase 3 ships)
+  - If verify is not needed, go directly to /curdx-flow:ship (after Phase 6 ships)
+
+Phase 3 (Gates & Review) has not yet shipped.
+You may manually review .flow/specs/$SPEC_NAME/ and git log to confirm quality.
+```

package/commands/index.md

@@ -0,0 +1,261 @@
+---
+name: index
+description: Codebase index — scan brownfield projects and generate a module/component/API index. Provides the foundation for subsequent /curdx-flow:research.
+argument-hint: "[--force]"
+allowed-tools: [Read, Write, Bash, Grep, Glob]
+---
+
+# Flow Index — Codebase Scan and Index
+
+Generate an index for **brownfield projects** (existing code) so that flow-researcher and flow-architect can quickly acquire project-structure information.
+
+## Applicable Scenarios
+
+- Taking over an existing project — run `/curdx-flow:index` first to build understanding
+- Large monorepo requiring indexes of subpackages
+- Want to add a new feature to the current project — index before researching
+
+## Not Applicable
+
+- Greenfield projects (empty codebase)
+- Micro projects (< 20 files)
+
+## Step 1: Preflight
+
+```bash
+[ ! -d ".flow" ] && { echo "❌ Not a CurDX-Flow project. Run /curdx-flow:init first"; exit 1; }
+
+INDEX_FILE=".flow/codebase-index.md"
+
+# If one exists and --force is not set, ask
+if [ -f "$INDEX_FILE" ] && [ "$ARGUMENTS" != "--force" ]; then
+    echo "ℹ Index already exists: $INDEX_FILE"
+    # AskUserQuestion: overwrite / incremental / cancel
+fi
+```
+
+## Step 2: Detect Project Type
+
+```bash
+# Identify project language + build tool
+if [ -f "package.json" ]; then
+    PROJECT_TYPE="node"
+    FRAMEWORK=$(grep -E "(react|vue|next|nuxt|svelte)" package.json | head -3)
+elif [ -f "requirements.txt" ] || [ -f "pyproject.toml" ]; then
+    PROJECT_TYPE="python"
+elif [ -f "Cargo.toml" ]; then
+    PROJECT_TYPE="rust"
+elif [ -f "go.mod" ]; then
+    PROJECT_TYPE="go"
+fi
+```
+
+## Step 3: Scan Directory Structure
+
+```bash
+# Top-level directories
+DIRS=$(ls -d */ 2>/dev/null | grep -vE "(node_modules|dist|build|\.git|\.next)")
+
+# File statistics
+TOTAL_FILES=$(find . -type f -not -path "*/node_modules/*" -not -path "*/.git/*" | wc -l)
+SRC_FILES=$(find src/ -type f 2>/dev/null | wc -l)
+```
+
+## Step 4: Identify Modules
+
+Use Grep + Glob to find module boundaries:
+
+```bash
+# TypeScript / JavaScript: find export default + public API
+# Python: find __init__.py
+# Rust: find mod.rs / lib.rs
+# Go: find package declaration
+
+# Typical pattern (Node project):
+Glob: src/**/index.{ts,tsx,js}
+Grep: "^export (default|const|function|class)" in index files
+```
+
+## Step 5: Identify Components / Services / APIs
+
+```bash
+# UI components
+Glob: src/**/*.{tsx,jsx,vue,svelte}
+
+# API endpoints
+Grep: "router\.\(get\|post\|put\|delete\)" or "app\.(get|post)" or "@app.route"
+
+# DB models
+Grep: "@Entity\|Schema\|Model\|prisma\."
+
+# Services
+Glob: src/**/*Service.{ts,js}
+```
+
+## Step 6: Build the Index Markdown
+
+```markdown
+# Codebase Index: <project name>
+
+Generated: YYYY-MM-DD
+Project type: Node (TypeScript + React)
+Total files: 234 (189 under src/)
+
+## Directory Structure
+
+```
+src/
+├── auth/          ← authentication module
+├── user/          ← user management
+├── orders/        ← orders
+├── ui/            ← shared UI components
+├── api/           ← API routes
+├── db/            ← DB layer
+└── utils/         ← utility functions
+```
+
+## Module List
+
+### Module: auth
+- Path: src/auth/
+- Entry: src/auth/index.ts
+- Exports:
+  - `login(email, password)` - log in
+  - `logout(token)` - log out
+  - `refreshToken(token)` - refresh
+- Dependencies: bcrypt, jsonwebtoken
+- Tests: src/auth/*.test.ts (15 tests)
+
+### Module: user
+- Path: src/user/
+- Entry: src/user/index.ts
+- Exports:
+  - `getUser(id)` - fetch user
+  - `updateProfile(id, data)` - update profile
+- Dependencies: prisma
+- Tests: src/user/*.test.ts (8 tests)
+
+### Module: orders
+...
+
+## UI Component List
+
+### Shared components (src/ui/)
+
+- `<Button>` - src/ui/Button.tsx
+- `<Input>` - src/ui/Input.tsx
+- `<Card>` - src/ui/Card.tsx
+- ...
+
+### Page components (src/pages/)
+
+- `LoginPage` - src/pages/Login.tsx
+- `DashboardPage` - src/pages/Dashboard.tsx
+- ...
+
+## API Endpoints
+
+### /auth
+- POST /auth/login → src/api/auth.ts:login
+- POST /auth/logout → src/api/auth.ts:logout
+- POST /auth/refresh → src/api/auth.ts:refresh
+
+### /users
+- GET /users/me → src/api/users.ts:getCurrent
+- PUT /users/me → src/api/users.ts:update
+- ...
+
+## DB Models
+
+- `User` - src/db/models/User.ts
+- `Order` - src/db/models/Order.ts
+- ...
+
+## Tech Stack
+
+- **Runtime**: Node 20 + TypeScript 5
+- **Framework**: Next.js 14 (App Router)
+- **UI**: React 18 + Tailwind + shadcn/ui
+- **DB**: PostgreSQL + Prisma
+- **Auth**: JWT + bcrypt
+- **Testing**: Vitest + Playwright
+
+## Commands
+
+From package.json:
+- `npm run dev` - dev server (localhost:3000)
+- `npm test` - tests
+- `npm run build` - production build
+- `npm run lint` - ESLint
+
+## Conventions
+
+- File naming: PascalCase for components, camelCase for utilities
+- Tests: `*.test.ts` adjacent to source file
+- Types: standalone `types.ts` or inline interface
+- Exports: each module's `index.ts` as the public API
+
+## Hot Files (most modified recently)
+
+- src/auth/login.ts (12 commits in the past 30 days)
+- src/ui/Button.tsx (8 commits)
+- ...
+
+## Tech Debt / TODO
+
+Scan for `// TODO:` / `// FIXME:`:
+- src/auth/refresh.ts:28 - "TODO: add rate limiting"
+- src/api/orders.ts:45 - "FIXME: handle concurrent updates"
+- ...
+```
+
+## Step 7: Save + Update .state
+
+```bash
+# Write
+echo "$INDEX_CONTENT" > "$INDEX_FILE"
+
+# If .flow/config.json exists, record the index time
+python3 -c "
+import json
+c = json.load(open('.flow/config.json'))
+c.setdefault('codebase_index', {})['last_updated'] = '$(date +%Y-%m-%d)'
+json.dump(c, open('.flow/config.json','w'), indent=2, ensure_ascii=False)
+"
+```
+
+## Step 8: Output
+
+```
+✓ Codebase index complete
+
+File: .flow/codebase-index.md (~N lines)
+
+Statistics:
+  Modules: M
+  UI components: K
+  API endpoints: L
+  DB models: J
+
+You can now:
+- Agents will read this index as context during /curdx-flow:research
+- When running /curdx-flow:start for a new feature, reference this index first to find reusable modules
+- View it manually to understand the project structure
+
+Suggestion:
+- Rerun after major code changes: /curdx-flow:index --force
+- No need to run on every change (30-day stability is OK)
+```
+
+## Notes
+
+- The index is **not full documentation**, it is a **quick guide**. Details still live in the source code.
+- Large project scans may take 1-2 minutes
+- Does not scan node_modules / dist / build / .git
+- Exclusion list configurable (future enhancement)
+
+## Error Recovery
+
+- Project too large (10K+ files) → index by module
+- Project type cannot be identified → provide a template for the user to fill in manually
+- Some paths have permission issues → skip and continue with the rest