@curdx/flow 2.2.3 → 2.2.5

package/skills/implement/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: implement
-description: Execute spec tasks — the Strategy Router picks linear/subagent/stop-hook/wave based on task characteristics. Atomic commit per task.
+description: Execute active-spec tasks with strategy routing and atomic progress.
 when_to_use: Use when the active spec already has tasks and the user wants execution, optionally with a chosen strategy or a single task id.
 argument-hint: "[spec-name] [--strategy=auto|linear|subagent|stop-hook|wave] [--task=<id>] [--quick]"
 disable-model-invocation: true
@@ -12,261 +12,85 @@ allowed-tools: [Read, Write, Edit, Bash, Agent, Grep, Glob]
 @${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.
+This skill is the execution orchestrator. Keep the entrypoint focused on
+preflight, routing, state updates, and stop conditions; load supporting files
+for strategy-specific protocols:
 
-## Step 1: Preflight Checks
+- `references/preflight.md`
+- `references/strategy-router.md`
+- `references/state-init.md`
+- `references/linear-execution.md`
+- `references/subagent-execution.md`
+- `references/wave-execution.md`
+- `references/stop-hook-execution.md`
+- `references/progress-contract.md`
+- `references/error-recovery.md`
 
-```bash
-[ ! -d ".flow" ] && { echo "✗ Not a CurdX-Flow project. Run /curdx-flow:init first"; exit 1; }
+## Arguments
 
-ARGS="$ARGUMENTS"
-SPEC_NAME=""
-STRATEGY="auto"
-TASK_ID=""
-QUICK=0
+`$ARGUMENTS` may include:
 
-# 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
+- `[spec-name]`
+- `--strategy=auto|linear|subagent|stop-hook|wave`
+- `--task=<id>`
+- `--quick`
 
-[ -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; }
+## Preflight and Task Stats
 
-DIR=".flow/specs/$SPEC_NAME"
-[ ! -f "$DIR/tasks.md" ] && { echo "✗ Missing tasks.md. Run /curdx-flow:spec first (or /curdx-flow:spec --phase=tasks to rebuild just the tasks phase)"; exit 1; }
-```
+Use `references/preflight.md` for:
 
-## Step 2: Parse Task Characteristics from tasks.md
+- `.flow/` and active-spec resolution
+- argument parsing
+- `tasks.md` presence checks
+- `TOTAL`, `DONE`, `REMAINING`, `PARALLEL`, and `SEQUENTIAL` extraction
 
-```bash
-TOTAL=$(grep -Ec "^- \[[ xX]\] \*\*" "$DIR/tasks.md")
-DONE=$(grep -Ec "^- \[[xX]\] \*\*" "$DIR/tasks.md")
-REMAINING=$((TOTAL - DONE))
-PARALLEL=$(grep -c "^- \[ \] \*\*.*\[P\]" "$DIR/tasks.md")
-SEQUENTIAL=$(grep -c "^- \[ \] \*\*.*\[SEQUENTIAL\]" "$DIR/tasks.md")
+## Strategy Routing
 
-echo "Task stats: remaining $REMAINING, done $DONE, [P] parallel $PARALLEL, [SEQUENTIAL] serial $SEQUENTIAL"
-```
+Use `references/strategy-router.md` for the full decision tree and routing
+signals. The runtime selector is:
 
-## Step 3: Strategy Router
+## Execute State Init
 
-If `STRATEGY=auto` (default), pick via the decision tree:
+Use `references/state-init.md` before dispatching any execution protocol.
 
-```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
+## Run the Selected Execution Protocol
 
-echo "✓ Selected strategy: $STRATEGY"
-```
+- `linear`: stay inline in the main agent and execute the first unchecked task
+  to completion. Full task loop: `references/linear-execution.md`
+- `subagent`: dispatch one isolated `flow-executor` at a time. Full prompt
+  contract: `references/subagent-execution.md`
+- `wave`: dispatch multiple Agent calls in parallel within a single response;
+  the serial/parallel boundaries and conflict rules live in
+  `references/wave-execution.md`
+- `stop-hook`: run one task per round and let the stop watcher decide whether
+  to continue. Full continuation contract:
+  `references/stop-hook-execution.md`
 
-**Decision tree explanation**:
-- Few tasks / strong dependencies → `linear` (main agent executes sequentially)
-- Many parallel opportunities → `wave` (parallel Agent dispatch within a wave)
-- Long chain + quick mode → `stop-hook` (auto-loop, requires hook support)
-- Medium scale → `subagent` (isolated context per task)
+If `STRATEGY` is not one of `linear`, `subagent`, `wave`, `stop-hook`, stop
+immediately rather than guessing.
 
-## Step 4: Initialize execute_state
+For `subagent` and `wave`, after the agent completes, read the output marker
+defined by the supporting file before mutating state or advancing the task
+cursor.
 
-```python
-import json
-p = f'.flow/specs/{SPEC_NAME}/.state.json'
-s = json.load(open(p))
-try:
-    cfg = json.load(open('.flow/config.json'))
-except Exception:
-    cfg = {}
-execution_cfg = cfg.get('execution', {}) if isinstance(cfg, dict) else {}
-recovery_mode = execution_cfg.get('recovery_mode', 'manual')
-max_fix_tasks = execution_cfg.get('max_fix_tasks_per_original', 2)
-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)
-s['execute_state'].setdefault('recovery_mode', recovery_mode)
-s['execute_state'].setdefault('max_fix_tasks_per_original', max_fix_tasks)
-s['execute_state'].setdefault('fix_task_map', {})
-if QUICK:
-    s['quickMode'] = True
-json.dump(s, open(p, 'w'), indent=2, ensure_ascii=False)
-```
+## Progress and Completion Contract
 
-## Step 5: Execution Strategies
+Use `references/progress-contract.md` for both in-flight progress output and
+the execute-complete summary. Do not claim the feature is shipped from execute
+alone. The primary handoff remains:
 
-### Strategy: linear
+- `/curdx-flow:verify` for goal-backward evidence
+- `/curdx-flow:review` for code-quality findings after verification
 
-The main agent (you) executes sequentially:
+## Recovery Rules and Stop Conditions
 
-```
-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
-```
+All retry, fix-task, and stop thresholds are centralized in
+`references/error-recovery.md`.
 
-If there are 5 failures, stop + TASK_FAILED.
+The stop invariant is strict:
 
-### Strategy: subagent
-
-For each remaining task, dispatch flow-executor:
-
-```
-Agent:
-  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
-
-See `skills/implement/references/wave-execution.md` for the full walkthrough.
-Knowledge-layer canonical algorithm: `@${CLAUDE_PLUGIN_ROOT}/knowledge/wave-execution.md`.
-
-**Core**: consecutive `[P]` tasks form a wave; dispatch multiple Agent calls in parallel within a single response; serial across waves. The execution loop is:
-
-1. **DAG analysis** — group remaining `[ ]` tasks by `[P]` / `[SEQUENTIAL]` / `[VERIFY]` tags; conflicting `Files` sets split into a new wave.
-2. **Pre-conflict detection** — within each wave, assert per-task `Files` are disjoint; auto-split if not.
-3. **Dispatch** — list multiple `Agent(...)` tool calls in a single main-agent response (splitting across responses = serial degradation; nested `Agent` dispatches forbidden). Each Agent prompt follows the subagent strategy's uniform format (see `references/wave-execution.md` Step 3).
-4. **Aggregate** — parse each result for `TASK_COMPLETE` / `TASK_FAILED`; run post-hoc conflict detection via git diff to confirm executors only touched declared files.
-5. **Failure handling** — 0 failed → next wave; 1 failed → `config.wave_fail_policy` (`continue-on-single` or `stop-on-any`); ≥2 failed → likely environment issue, stop immediately; cumulative `failed_attempts >= 3` → stop, user intervention.
-6. **Progress feedback** — print a wave summary after each wave (see `references/wave-execution.md` Step 6).
-
-Configuration under `.flow/config.json.execution`: `strategy: "wave"`, `max_parallel: 5` (wave-parallel ceiling), `wave_fail_policy: "continue-on-single" | "stop-on-any"`.
-
-### 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
-```
-
-Stop-hook completion is double-checked: `.state.json` must say execute is complete AND `tasks.md` must have zero unchecked tasks. If either disagrees, the hook blocks and resumes the first unchecked task. During a stop-hook continuation, `stop_hook_active=true` is only a context signal; the hook still evaluates transcript signals, `.state.json`, and `tasks.md` parity before deciding whether to continue or stop.
-
-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
-
-At each wave boundary (or periodically during long linear runs), 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:spec --phase=tasks --regenerate` to fix
-- `TASK_FAILED` default (`recovery_mode: manual`) → do not skip the task; root-cause, retry the first unchecked task, stop at 3 failures
-- `TASK_FAILED` with `recovery_mode: fix-task` → insert one targeted `[FIX <task_id>]` task immediately after the failed task, update `execute_state.fix_task_map`, execute that fix task, then retry the original task; never exceed `max_fix_tasks_per_original`
-- 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 npx @curdx/flow doctor
-- State says complete but tasks.md still has unchecked tasks → trust tasks.md, continue remaining unchecked tasks only
-
-### Fix-Task Recovery Format
-
-When enabled, generated recovery tasks must be narrowly scoped and traceable:
-
-```markdown
-- [ ] **<task_id>.<n>** [FIX <task_id>] Fix: <short root cause>
-  - **Do**: <specific repair steps>
-  - **Files**: <same declared files or narrower>
-  - **Done when**: Original failure no longer reproduces
-  - **Verify**: <original verify command or tighter reproduction>
-  - **Commit**: `fix(<scope>): address <failure>`
-```
-
-Do not execute a newly generated fix task in the same breath that creates it unless the task is already written to `tasks.md` and `fix_task_map` has been updated. The ledger stays ahead of execution.
-
-## 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
-  - /curdx-flow:review   — two-stage code review after verification
-
-Do not claim the feature is shipped from execute alone. Execute completes tasks;
-verify proves user-visible goals; review checks implementation quality.
-```
+- Never skip a failed task implicitly
+- Never continue after git-state corruption
+- Stop after 3 consecutive `TASK_FAILED`
+- If `.state.json` says complete but `tasks.md` still has unchecked tasks, trust
+  `tasks.md` and continue only the unchecked work

package/skills/implement/references/error-recovery.md

@@ -0,0 +1,36 @@
+# Error Recovery — Failure Policy
+
+All implement strategies use the same recovery ledger and stop thresholds.
+
+## Failure Rules
+
+- `Verify` field is `manual` or malformed -> stop and suggest
+  `/curdx-flow:spec --phase=tasks --regenerate`
+- `TASK_FAILED` with `recovery_mode: manual` -> do not skip the task; root-cause
+  it, then retry the first unchecked task
+- `TASK_FAILED` with `recovery_mode: fix-task` -> insert one targeted
+  `[FIX <task_id>]` task immediately after the failed task, update
+  `execute_state.fix_task_map`, execute that fix task, then retry the original
+  task
+- Never exceed `max_fix_tasks_per_original`
+- 3 consecutive `TASK_FAILED` -> stop and require user intervention
+- Git operation failure -> stop immediately to avoid state corruption
+- Missing local test framework -> stop and suggest `npx @curdx/flow doctor`
+- State says complete but `tasks.md` still has unchecked tasks -> trust
+  `tasks.md`
+
+## Fix-Task Recovery Format
+
+Generated repair tasks must stay narrow and traceable:
+
+```markdown
+- [ ] **<task_id>.<n>** [FIX <task_id>] Fix: <short root cause>
+  - **Do**: <specific repair steps>
+  - **Files**: <same declared files or narrower>
+  - **Done when**: Original failure no longer reproduces
+  - **Verify**: <original verify command or tighter reproduction>
+  - **Commit**: `fix(<scope>): address <failure>`
+```
+
+Do not execute a newly generated fix task until both `tasks.md` and
+`fix_task_map` have been updated. The ledger must move ahead of execution.

package/skills/implement/references/linear-execution.md

@@ -0,0 +1,32 @@
+# Linear Execution — Inline Task Loop
+
+Use this mode when the backlog is small, heavily sequential, or the operator
+needs maximum visibility in the main session.
+
+## Main Loop
+
+```text
+for task in remaining tasks:
+    read task fields (Do / Files / Done when / Verify / Commit)
+    execute the task inline in the current session
+    run the task's Verify command
+    make the atomic commit declared by the task
+    mark the task [x] in tasks.md
+    append the outcome to .progress.md
+    print "✓ Task X.Y complete"
+```
+
+## Execution Rules
+
+- Follow the `flow-executor` contract even though you stay inline
+- Respect the declared `Files` scope; do not quietly expand task boundaries
+- Verification must pass before the task can be marked complete
+- One task, one atomic commit
+- If the task is too broad or unsafe, stop and surface `TASK_FAILED` semantics
+  instead of improvising extra subtasks
+
+## Stop Conditions
+
+- Any git operation failure: stop immediately
+- Missing or invalid Verify command: stop and ask for a task regeneration
+- 3 consecutive `TASK_FAILED`: stop and require intervention

package/skills/implement/references/preflight.md

@@ -0,0 +1,43 @@
+# Implement Preflight — Resolve Scope and Task Stats
+
+Before selecting a strategy:
+
+```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
+
+for arg in $ARGS; do
+    case "$arg" in
+        --strategy=*)  STRATEGY="${arg#--strategy=}" ;;
+        --task=*)      TASK_ID="${arg#--task=}" ;;
+        --quick)       QUICK=1 ;;
+        --*)           ;;
+        *)             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:spec first (or /curdx-flow:spec --phase=tasks to rebuild just the tasks phase)"; exit 1; }
+
+TOTAL=$(grep -Ec "^- \[[ xX]\] \*\*" "$DIR/tasks.md")
+DONE=$(grep -Ec "^- \[[xX]\] \*\*" "$DIR/tasks.md")
+REMAINING=$((TOTAL - DONE))
+PARALLEL=$(grep -c "^- \[ \] \*\*.*\[P\]" "$DIR/tasks.md")
+SEQUENTIAL=$(grep -c "^- \[ \] \*\*.*\[SEQUENTIAL\]" "$DIR/tasks.md")
+```
+
+These counters are part of the runtime contract:
+
+- `TOTAL` = all declared task rows
+- `DONE` = checked task rows
+- `REMAINING` = `TOTAL - DONE`
+- `PARALLEL` = unchecked `[P]` tasks
+- `SEQUENTIAL` = unchecked `[SEQUENTIAL]` tasks

package/skills/implement/references/progress-contract.md

@@ -0,0 +1,32 @@
+# Implement Progress Contract — Mid-Run and Completion Output
+
+At each wave boundary, retry, or long linear stretch, print:
+
+```text
+═════ Progress ═════
+Spec:      $SPEC_NAME
+Strategy:  $STRATEGY
+Done:      X / $TOTAL
+Recent commits:
+  - abc123f feat(auth): ...
+  - def456g test(auth): ...
+════════════════════
+```
+
+When all tasks are complete:
+
+```text
+✓ 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
+  - /curdx-flow:review  — two-stage code review after verification
+```
+
+Do not claim the feature is shipped from execute alone. Execute completes
+tasks; verify proves user-visible goals; review checks implementation quality.

package/skills/implement/references/state-init.md

@@ -0,0 +1,33 @@
+# Implement State Init — Seed execute_state Before Running
+
+After strategy selection and before execution begins:
+
+```python
+import json
+p = f'.flow/specs/{SPEC_NAME}/.state.json'
+s = json.load(open(p))
+try:
+    cfg = json.load(open('.flow/config.json'))
+except Exception:
+    cfg = {}
+execution_cfg = cfg.get('execution', {}) if isinstance(cfg, dict) else {}
+recovery_mode = execution_cfg.get('recovery_mode', 'manual')
+max_fix_tasks = execution_cfg.get('max_fix_tasks_per_original', 2)
+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)
+s['execute_state'].setdefault('recovery_mode', recovery_mode)
+s['execute_state'].setdefault('max_fix_tasks_per_original', max_fix_tasks)
+s['execute_state'].setdefault('fix_task_map', {})
+if QUICK:
+    s['quickMode'] = True
+json.dump(s, open(p, 'w'), indent=2, ensure_ascii=False)
+```
+
+The execute-state ledger must be initialized before any task dispatch so hooks,
+recovery, and status views observe the same state transition.

package/skills/implement/references/stop-hook-execution.md

@@ -0,0 +1,36 @@
+# Stop-Hook Execution — Hook-Driven Continuation
+
+Use this mode for long unattended runs where each execution round should end
+naturally and the hook layer decides whether Claude continues.
+
+## Protocol
+
+```text
+1. Execute 1 task (inline or via flow-executor, then wait for completion)
+2. End the response naturally
+3. stop-watcher.sh evaluates transcript markers, .state.json, and tasks.md
+4. If unchecked tasks remain, the hook blocks stop and injects continuation
+5. Repeat until ALL_TASKS_COMPLETE or recovery forces a halt
+```
+
+## Completion Invariant
+
+Stop-hook completion is double-checked:
+
+- `.state.json` must say execute is complete
+- `tasks.md` must have zero unchecked tasks
+
+If either side disagrees, the hook resumes the first unchecked task instead of
+allowing the session to stop cleanly.
+
+## Prerequisites
+
+- `--quick` should be set; otherwise `AskUserQuestion` can stall the loop
+- `.flow/config.json` or `.state.json` should pin `strategy=stop-hook`
+- The hook layer must remain the final authority for continuation
+
+## Context Signal
+
+During a stop-hook continuation, `stop_hook_active=true` is only a hint. The
+hook still checks transcript signals, `.state.json`, and `tasks.md` parity
+before deciding whether to continue or stop.

package/skills/implement/references/strategy-router.md

@@ -0,0 +1,38 @@
+# Strategy Router — Selection Rules
+
+`/curdx-flow:implement` defaults to `--strategy=auto`. The router converts task
+shape into one of four concrete execution modes.
+
+## Runtime Decision Tree
+
+```bash
+if [ "$STRATEGY" != "auto" ]; then
+  use the explicit value
+elif [ $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
+```
+
+## Routing Signals
+
+- Few tasks or dependency-heavy work: `linear`
+- Meaningful `[P]` coverage and disjoint file sets: `wave`
+- Long unattended run with `--quick`: `stop-hook`
+- Mid-sized backlog without safe parallelism: `subagent`
+
+## Guardrails
+
+- `--strategy=<mode>` always wins over auto-routing
+- Unknown strategy values are fatal; do not silently fall back
+- `--task=<id>` narrows execution scope, but does not change the selected
+  strategy by itself
+- `--quick` is a routing hint only; it does not relax verification or commit
+  rules

package/skills/implement/references/subagent-execution.md

@@ -0,0 +1,43 @@
+# Subagent Execution — Serial Isolated Executors
+
+Use this mode when tasks are moderately sized and benefit from fresh context per
+task, but the backlog is not parallel-safe enough for waves.
+
+## Dispatch Contract
+
+Dispatch one `flow-executor` at a time with a uniform prompt:
+
+```text
+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
+- .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 task references 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
+```
+
+## Aggregation Rules
+
+After the agent completes, read the output marker:
+
+- `TASK_COMPLETE` -> mark progress and dispatch the next task
+- `TASK_FAILED` -> increment failure tracking and enter recovery
+- `ALL_TASKS_COMPLETE` -> mark execute complete and move to verify
+
+## Guardrails
+
+- This strategy is serial; a single Agent dispatch is not parallel execution
+- Do not batch multiple independent tasks into one `flow-executor` prompt
+- Do not trust narrative summaries over the end marker