@curdx/flow 3.0.0 → 3.1.0

package/skills/implement/references/native-task-sync.md

@@ -1,107 +0,0 @@
-# Native Task Sync — Mirror `.flow` Execution Into Claude's Task List
-
-Use this layer only as an interactive UX mirror. `.flow/specs/<name>/tasks.md`
-and `.state.json` remain the source of truth.
-
-## Availability Rule
-
-If the current session exposes `TaskCreate`, `TaskList`, and `TaskUpdate`, keep
-Claude's native task list aligned with the active spec. If those tools are not
-available (for example in headless or bare flows), skip all native sync work
-silently and continue with the disk-backed protocol.
-
-## State Fields
-
-Track best-effort sync state under `.state.json` `execute_state`:
-
-- `native_task_map`: `{ "<task-id>": "<claude-task-id>" }`
-- `native_sync_enabled`: `true | false`
-- `native_sync_failure_count`: integer
-
-Default behavior:
-
-- missing fields -> treat as first-run and initialize them
-- `native_sync_enabled = false` -> never attempt native task sync again in this
-  execution run unless the user explicitly resets state
-
-## First Sync
-
-After preflight and execute-state initialization:
-
-1. If native sync is available and `native_task_map` is empty, parse every task
-   row from `tasks.md`.
-2. Create one Claude native task per CurDX task.
-3. Use the CurDX task id in the subject:
-   - regular: `1.2 Add retry guard`
-   - parallel: `[P] 2.1 Build auth DTOs`
-   - verification: `[VERIFY] 3.VF Re-run original repro`
-4. Use a compact description built from:
-   - `Done when`
-   - `Verify`
-5. Immediately mark already-checked `[x]` tasks as `completed`.
-6. Persist the returned Claude task ids in `native_task_map`.
-
-When interactive hook support is available, CurDX also uses `TaskCreated` as a
-guardrail:
-
-- reject CurDX-shaped native tasks whose subject does not map to a real
-  `tasks.md` id
-- reject CurDX-shaped native tasks that omit the compact description derived
-  from `Done when` + `Verify`
-
-Do not block execution if task creation fails. Increment
-`native_sync_failure_count`, log one short note in `.progress.md`, and continue.
-
-## Rebuild Rule
-
-If a stored Claude task id no longer updates cleanly, assume the current
-session is attached to a different native task list:
-
-1. clear `native_task_map`
-2. recreate the native tasks from the current `tasks.md`
-3. keep `.flow` execution state unchanged
-
-This recovers from session changes without corrupting the real spec ledger.
-
-## Per-Task Sync
-
-Before dispatching the current task:
-
-1. reconcile `tasks.md` `[x]` rows against native task state when obvious drift
-   exists
-2. mark the current native task `in_progress`
-3. set `activeForm` to `Executing <task-id>`
-
-After `TASK_COMPLETE` and after disk-backed verification/state updates pass:
-
-1. mark that native task `completed`
-2. reset `native_sync_failure_count` toward zero on success
-
-When interactive hook support is available, `TaskCompleted` should also reject
-any CurDX-shaped native task completion that happens before `tasks.md` marks the
-same task id as checked.
-
-After `TASK_FAILED`:
-
-1. leave the current task visible
-2. update `activeForm` to `Retrying <task-id>` when the tool call is available
-3. never advance the native task to `completed`
-
-## Completion Rule
-
-When execute finishes:
-
-1. ensure every checked task in `tasks.md` is `completed` in the native list
-2. do not invent native tasks for verify/review phases here
-3. keep the final chat summary short; the native task list is only a progress
-   surface, not the evidence surface
-
-## Guardrails
-
-- Native sync is best-effort UX, not correctness.
-- Never trust the native task list over `tasks.md`.
-- Never stop a CurDX run solely because `TaskCreate` or `TaskUpdate` failed.
-- Native task lifecycle guards are allowed to reject malformed CurDX-native
-  tasks, but they must not interfere with unrelated non-CurDX task-list usage.
-- Do not use `TodoWrite` here; interactive Claude sessions should prefer the
-  current Task tool family.

package/skills/implement/references/preflight.md

@@ -1,43 +0,0 @@
-# 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

@@ -1,36 +0,0 @@
-# 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): ...
-════════════════════
-```
-
-If native task sync is active, the Claude task list should mirror this same
-progress state. Do not duplicate long task inventories in chat just because the
-task list UI exists.
-
-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

@@ -1,36 +0,0 @@
-# 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', {})
-s['execute_state'].setdefault('native_task_map', {})
-s['execute_state'].setdefault('native_sync_enabled', True)
-s['execute_state'].setdefault('native_sync_failure_count', 0)
-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

@@ -1,50 +0,0 @@
-# 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. Initialize execute_state, including native sync fields
-2. Rebuild native_task_map if the current session cannot update stored task ids
-3. Execute 1 task (inline or via flow-executor, then wait for completion)
-4. End the response naturally
-5. stop-watcher.sh evaluates transcript markers, .state.json, and tasks.md
-6. If unchecked tasks remain, the hook blocks stop and injects continuation
-7. 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.
-
-If native task sync is active during a continuation round:
-
-- `.flow/specs/<name>/tasks.md` stays the source of truth
-- checked rows should be mirrored back to the native task list before the next
-  task starts
-- a stale `native_task_map` should trigger the rebuild rule from
-  `references/native-task-sync.md`, not a run failure
-
-## 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.
-
-Native task sync is session-local UX. Continuations may resume into a different
-Claude-native task list, so recovery must prefer rebuilding the UI mirror over
-mutating `.flow` state.

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

@@ -1,38 +0,0 @@
-# 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

@@ -1,57 +0,0 @@
-# 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
-
-Before each dispatch, if native task sync is active:
-
-- reconcile obvious `tasks.md` vs native-task drift
-- mark the outgoing task `in_progress`
-- set the native active form to `Executing <task-id>` when available
-
-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, mark the native task `completed`, and
-  dispatch the next task
-- `TASK_FAILED` -> increment failure tracking, keep the native task open, and
-  enter recovery
-- `ALL_TASKS_COMPLETE` -> mark execute complete and move to verify
-
-If a stored Claude task id no longer updates, rebuild `native_task_map` from
-the current `tasks.md`, then continue serial dispatch. Do not rewrite
-`.state.json` task cursor or `tasks.md` just because the UI task list changed.
-
-## 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
-- Native task sync belongs to the coordinator around the dispatch loop, not to
-  the `flow-executor` subagent itself

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

@@ -1,180 +0,0 @@
-# Wave Execution Strategy — Detailed Walkthrough
-
-Skill-scoped reference for `skills/implement/SKILL.md`. Loaded only when the
-implement skill routes to the `wave` strategy. The knowledge-layer canonical
-algorithm lives in `@${CLAUDE_PLUGIN_ROOT}/knowledge/wave-execution.md`;
-this file is the walkthrough the skill itself embeds for implementers.
-
-**Core**: consecutive `[P]` tasks form a wave, dispatch multiple Agent calls 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)
-
-Before dispatching the wave, if native task sync is active:
-
-- reconcile obvious `tasks.md` vs native-task drift
-- mark every task in the upcoming wave `in_progress`
-- set the active form to `Executing Wave <n>: <task ids>` when available
-
-```
-# List multiple Agent tool calls in one response of the main agent:
-Agent(description="Execute 1.1", prompt=<...flow-executor + task_id=1.1...>)
-Agent(description="Execute 1.2", prompt=<...flow-executor + task_id=1.2...>)
-Agent(description="Execute 1.3", prompt=<...flow-executor + task_id=1.3...>)
-```
-
-Each Agent 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 Agent calls across multiple responses (that is serial degradation)
-- Nesting another Agent dispatch inside an Agent
-
-## Step 4: Aggregate Wave Results
-
-Wait for all Agent calls 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}")
-```
-
-After aggregation, if native task sync is active:
-
-- mark each `completed` task `completed`
-- leave each `failed` task open for retry/recovery
-- if any `TaskUpdate` call reports a stale or missing Claude task id, rebuild
-  `native_task_map` from `tasks.md` and continue with `.flow` as source of
-  truth
-
-## 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 npx @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)...
-```
-
-When native task sync is active, the Claude task list is the short-form UI
-surface for the same wave progress. Keep chat feedback compact instead of
-relisting the whole backlog after every wave.
-
-## 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 `@${CLAUDE_PLUGIN_ROOT}/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]`

package/skills/init/SKILL.md

@@ -1,49 +0,0 @@
----
-name: init
-description: Initialize the .flow scaffold for the current repository.
-when_to_use: Use when the current repository is not yet a CurdX-Flow project and needs the initial .flow scaffold.
-argument-hint: "[--force]"
-disable-model-invocation: true
-allowed-tools: [Read, Write, Bash, AskUserQuestion]
----
-
-# Initialize CurdX-Flow Project
-
-Bootstrap `.flow/` for the current repository. Keep the entrypoint focused on
-safe preflight checks, scaffold contracts, and next-step routing. Detailed init
-rules live in:
-
-- `references/preflight.md`
-- `references/scaffold-contract.md`
-- `references/gitignore-and-health.md`
-- `references/next-steps.md`
-
-## Arguments
-
-`$ARGUMENTS` may include `--force`.
-
-Use `references/preflight.md` for:
-
-- dangerous-root rejection
-- existing `.flow/` handling
-- `--force` repair semantics
-
-`--force` is for scaffold repair, not blind overwrites.
-
-## Scaffold Contract
-
-Use `references/scaffold-contract.md` for the required directory skeleton,
-template rendering, and placeholder substitution contract.
-
-## Gitignore and Health
-
-Use `references/gitignore-and-health.md` for:
-
-- runtime ignore entries
-- committed-vs-runtime file boundaries
-- doctor / dependency health guidance
-
-## Output and Handoff
-
-The user-facing success output and route to `/curdx-flow:start` live in
-`references/next-steps.md`.

package/skills/init/references/gitignore-and-health.md

@@ -1,26 +0,0 @@
-# Init Gitignore and Health — Runtime Hygiene
-
-Append these runtime-only entries to `.gitignore` if they are missing:
-
-```gitignore
-# CurdX-Flow runtime files
-.flow/checkpoints/
-.flow/threads/
-.flow/seeds/
-.flow/.active-spec
-.flow/specs/*/.state.json
-.flow/specs/*/.progress.md
-.flow/_epics/*/.epic-state.json
-```
-
-The canonical shared files should stay committed:
-
-- `.flow/PROJECT.md`
-- `.flow/CONTEXT.md`
-- `.flow/STATE.md`
-- `.flow/ROADMAP.md`
-- `.flow/config.json`
-
-Do not spawn a separate CLI subprocess from inside the skill just to show the
-doctor output. If the user wants the full environment report, route them to
-run `npx @curdx/flow doctor` in a terminal.

package/skills/init/references/next-steps.md

@@ -1,22 +0,0 @@
-# Init Handoff — What to Tell the User Next
-
-Success output should confirm the scaffold exists and route the user into the
-main workflow:
-
-```text
-✓ CurdX-Flow project initialized
-  .flow/
-  ├── PROJECT.md
-  ├── CONTEXT.md
-  ├── STATE.md
-  ├── ROADMAP.md
-  └── config.json
-
-Next:
-  1. Fill in .flow/PROJECT.md with the project goal
-  2. Run npx @curdx/flow doctor if environment health needs verification
-  3. Start the first spec with /curdx-flow:start <name> "<goal>"
-```
-
-If `--force` repaired a partial scaffold, say that the existing project context
-was preserved and only missing runtime pieces were backfilled.

package/skills/init/references/preflight.md

@@ -1,15 +0,0 @@
-# Init Preflight — Safe Bootstrap Rules
-
-Before writing `.flow/`:
-
-- confirm the current directory is the intended repository root
-- reject dangerous locations such as `/`, the home directory, or other obvious
-  non-project folders
-- if `.flow/` already exists and `--force` is absent, stop and route the user
-  to inspect it or run `/curdx-flow:start --list`
-
-`--force` means "repair or complete the scaffold" rather than "overwrite user
-content". Existing committed files such as `.flow/PROJECT.md`,
-`.flow/CONTEXT.md`, `.flow/STATE.md`, `.flow/ROADMAP.md`, and
-`.flow/config.json` should be preserved unless the user explicitly asks to
-replace them.