@curdx/flow 2.3.11 → 3.1.0

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

@@ -1,36 +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. 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

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

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

@@ -1,162 +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)
-
-```
-# 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}")
-```
-
-## 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)...
-```
-
-## 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.

package/skills/init/references/scaffold-contract.md

@@ -1,27 +0,0 @@
-# Init Scaffold Contract — What Must Be Created
-
-Create the runtime skeleton:
-
-- `.flow/specs/`
-- `.flow/_epics/`
-- `.flow/checkpoints/`
-- `.flow/threads/`
-- `.flow/seeds/`
-
-Render the canonical scaffold files from `${CLAUDE_PLUGIN_ROOT}/templates/`:
-
-- `templates/PROJECT.md.tmpl` -> `.flow/PROJECT.md`
-- `templates/CONTEXT.md.tmpl` -> `.flow/CONTEXT.md`
-- `templates/STATE.md.tmpl` -> `.flow/STATE.md`
-- `templates/ROADMAP.md.tmpl` -> `.flow/ROADMAP.md`
-- `templates/config.json.tmpl` -> `.flow/config.json`
-
-Populate placeholders with:
-
-- `{{PROJECT_NAME}}` from the current directory name unless the user gave a
-  better project label
-- `{{CREATED_DATE}}` from the current date
-- `{{USER_NAME}}` from git config when available
-
-Create missing scaffold files. Do not overwrite user-edited canonical files
-unless the user explicitly asks for a reset.

package/skills/review/SKILL.md

@@ -1,82 +0,0 @@
----
-name: review
-description: Run two-stage review with optional adversarial, edge-case, and DevEx passes.
-when_to_use: Use when implementation exists and the user wants review findings, spec-compliance checks, adversarial review, edge-case hunting, or a DevEx audit.
-argument-hint: "[--stage=<1|2|both>] [--adversarial] [--edge-case] [--devex]"
-disable-model-invocation: true
-allowed-tools: [Read, Bash, Agent, Grep, Glob]
----
-
-# Two-Stage Code Review
-
-Distinct from `/curdx-flow:verify`:
-
-- `verify` checks whether the spec's user-visible goals work
-- `review` checks whether the implementation is correct, aligned, and maintainable
-
-Keep this entrypoint focused on review routing, pass selection, and final
-report handoff.
-
-When this skill is used for follow-up work after prior review comments, apply
-`@${CLAUDE_PLUGIN_ROOT}/knowledge/review-feedback-intake.md` first so accepted
-fixes and technical pushback are recorded in `.progress.md`.
-
-Detailed review protocols live in:
-
-- `references/preflight.md`
-- `references/stage-execution.md`
-- `references/optional-passes.md`
-- `references/report-contract.md`
-- `references/reporting.md`
-
-## Flags
-
-| Flag | Default | Purpose |
-|------|---------|---------|
-| `--stage=<1\|2\|both>` | `both` | Stage 1 = spec compliance only. Stage 2 = code quality only. `both` = sequential. |
-| `--adversarial` | off (`enterprise` -> on) | Add an adversarial review pass across applicable categories. |
-| `--edge-case` | off (`enterprise` -> on) | Add edge-case hunting across applicable categories. Produces a test-gap checklist. |
-| `--devex` | off (`enterprise` -> on) | Add the DevEx audit for naming, comments, structure, error handling, setup, types, tests, and developer loop. |
-
-## Preflight
-
-Use `references/preflight.md` for:
-
-- `.flow/` and active-spec checks
-- required artifact checks
-- mode-aware `--stage`, `--adversarial`, `--edge-case`, and `--devex`
-  normalization
-
-## Stage Execution
-
-Stage responsibilities, reviewer prompts, and pass/fail expectations live in
-`references/stage-execution.md`.
-
-- Stage 1 -> `flow-reviewer` in spec-compliance mode
-- Stage 2 -> `flow-reviewer` in code-quality mode
-
-Optional adversarial, edge-case, and DevEx extensions live in
-`references/optional-passes.md`.
-
-## Report Contract
-
-Landing checks, report shape, and final status output live in
-`references/report-contract.md`.
-
-The report lands at:
-
-- `.flow/specs/$SPEC_NAME/review-report.md`
-
-## Reporting
-
-Use `references/reporting.md` for the final summary and rerun handoff.
-
-## References
-
-- `flow-reviewer` agent: `@${CLAUDE_PLUGIN_ROOT}/agents/flow-reviewer.md`
-- `flow-adversary` agent: `@${CLAUDE_PLUGIN_ROOT}/agents/flow-adversary.md`
-- `flow-edge-hunter` agent: `@${CLAUDE_PLUGIN_ROOT}/agents/flow-edge-hunter.md`
-- `adversarial-review-gate`: `@${CLAUDE_PLUGIN_ROOT}/gates/adversarial-review-gate.md`
-- `edge-case-gate`: `@${CLAUDE_PLUGIN_ROOT}/gates/edge-case-gate.md`
-- `devex-gate`: `@${CLAUDE_PLUGIN_ROOT}/gates/devex-gate.md`
-- Knowledge: `@${CLAUDE_PLUGIN_ROOT}/knowledge/two-stage-review.md`

package/skills/review/references/optional-passes.md

@@ -1,48 +0,0 @@
-# Optional Passes — Adversarial, Edge Cases, DevEx
-
-## Adversarial Review
-
-If `FLAG_ADV=1` after preflight normalization, dispatch `flow-adversary`
-across applicable categories:
-
-1. What's missing?
-2. What's overengineered?
-3. What breaks first in production?
-4. What would a new maintainer misunderstand?
-5. What choice locks out a future option?
-6. What would a skeptical reviewer reject?
-
-Zero findings still requires proof-of-checking.
-
-## Edge-Case Hunting
-
-If `FLAG_EDGE=1` after preflight normalization, dispatch `flow-edge-hunter`
-across:
-
-1. boundary values
-2. concurrency and races
-3. network or partial failure
-4. malformed input
-5. auth and permission failure
-6. resource exhaustion
-7. time, locale, and timezone
-
-Output: a test-gap checklist.
-
-## DevEx Audit
-
-If `FLAG_DEVEX=1` after preflight normalization, inject
-`@${CLAUDE_PLUGIN_ROOT}/gates/devex-gate.md` into `flow-reviewer` so Stage 2
-also evaluates:
-
-1. naming
-2. comments
-3. structure
-4. error handling
-5. setup
-6. types
-7. tests
-8. developer loop
-
-Do not fork a separate custom reviewer for DevEx; keep `flow-reviewer` generic
-and extend it with the gate file.

package/skills/review/references/preflight.md

@@ -1,38 +0,0 @@
-# Review Preflight — Resolve Scope and Flags
-
-Before dispatching any reviewer:
-
-```bash
-[ ! -d ".flow" ] && { echo "✗ Not a CurdX-Flow project."; exit 1; }
-
-SPEC_NAME=$(cat .flow/.active-spec 2>/dev/null)
-[ -z "$SPEC_NAME" ] && { echo "✗ No active spec."; exit 1; }
-
-SPEC_STATE=".flow/specs/$SPEC_NAME/.state.json"
-SPEC_MODE=$(grep -oP '"mode"\\s*:\\s*"\\K[^"]+' "$SPEC_STATE" 2>/dev/null || echo "standard")
-
-for f in design.md; do
-  [ ! -f ".flow/specs/$SPEC_NAME/$f" ] && {
-    echo "✗ Missing $f. Run /curdx-flow:spec first.";
-    exit 1;
-  }
-done
-
-FLAG_STAGE=$(echo "$ARGUMENTS" | grep -oP -- '--stage=\K[^\s]+' || echo "both")
-FLAG_ADV=$(echo "$ARGUMENTS" | grep -q -- '--adversarial' && echo 1 || echo 0)
-FLAG_EDGE=$(echo "$ARGUMENTS" | grep -q -- '--edge-case' && echo 1 || echo 0)
-FLAG_DEVEX=$(echo "$ARGUMENTS" | grep -q -- '--devex' && echo 1 || echo 0)
-
-if [ "$SPEC_MODE" = "enterprise" ]; then
-  FLAG_ADV=1
-  FLAG_EDGE=1
-  FLAG_DEVEX=1
-fi
-```
-
-The entrypoint should resolve flags once, then route all review passes from
-that normalized configuration rather than reparsing later.
-
-`enterprise` mode auto-enables adversarial, edge-case, and DevEx review even
-when the user does not pass those flags explicitly. Manual flags still force
-the same behavior in non-enterprise modes.

package/skills/review/references/report-contract.md

@@ -1,49 +0,0 @@
-# Report Contract — Landing, Shape, Verdict
-
-## Landing Check
-
-Sub-agent responses can truncate before the report is written. After dispatching
-review agents, verify the report actually landed:
-
-```bash
-REPORT=".flow/specs/$SPEC_NAME/review-report.md"
-if [ ! -f "$REPORT" ] || [ "$(wc -c < "$REPORT" 2>/dev/null | tr -d ' ')" -lt 300 ]; then
-  echo "⚠ Report missing or truncated. Re-dispatching flow-reviewer with a terse 'Write the report now, no narration' prompt."
-fi
-```
-
-## Report Shape
-
-```markdown
-# Review Report — <spec-name>
-
-## Stage 1 — Spec Compliance
-...
-
-## Stage 2 — Code Quality
-...
-
-## Adversarial (if run)
-...
-
-## Edge Cases (if run)
-...
-
-## DevEx (if run)
-...
-
-## Verdict
-- [ ] APPROVED
-- [X] CHANGES REQUIRED — <n> blockers
-- [ ] REJECTED
-```
-
-## Final Output
-
-Summarize:
-
-- Stage 1 finding count
-- Stage 2 finding count
-- optional pass finding counts
-- final verdict
-- report path

package/skills/review/references/reporting.md

@@ -1,20 +0,0 @@
-# Review Reporting — Final Summary and Rerun Handoff
-
-End with a compact review summary:
-
-```text
-✓ Review complete
-  Stage 1 findings: <n>
-  Stage 2 findings: <n>
-  Adversarial findings: <n>   (if adversarial pass ran)
-  Edge-case gaps: <n>         (if edge-case pass ran)
-  DevEx findings: <n>         (if DevEx audit ran)
-  Verdict: CHANGES REQUIRED
-
-Report: .flow/specs/<name>/review-report.md
-
-Next: address blockers, then re-run /curdx-flow:review.
-```
-
-Keep the response outcome-focused. The report file is the artifact; the closing
-message only confirms counts, verdict, path, and next action.