@curdx/flow 3.0.0 → 3.1.0

package/skills/epic/references/epic-artifacts.md

@@ -1,20 +0,0 @@
-# Epic Artifacts — What Must Be Written
-
-`flow-triage-analyst` must return:
-
-- a vertical-slice decomposition
-- a dependency graph between slices
-- shared interfaces that should freeze before parallel work
-- suggested ordering: MVP -> iteration -> polish
-
-## Required Files
-
-- `.flow/_epics/<epic-name>/epic.md`
-- `.flow/specs/<epic-name>-<slice-id>/` skeletons with minimal `.state.json`
-
-`epic.md` should include:
-
-- goal
-- slice table
-- frozen interfaces
-- out-of-scope list

package/skills/epic/references/epic-intake.md

@@ -1,9 +0,0 @@
-# Epic Intake — Confirm the Scope Boundary
-
-Before decomposing, confirm:
-
-- epic name (short kebab-case identifier)
-- one-sentence goal
-- hard out-of-scope boundary
-
-This skill is for vertical-slice decomposition, not horizontal layer splitting.

package/skills/epic/references/slice-handoff.md

@@ -1,16 +0,0 @@
-# Epic Handoff — What the User Does Next
-
-Report:
-
-- epic name
-- slice count
-- suggested slice order
-
-Then route the user to a concrete slice:
-
-```text
-/curdx-flow:start <epic-name>-<slice-id>
-```
-
-Do not tell the user to use `/curdx-flow:start --resume <slice-id>`; slice
-selection is by explicit spec name.

package/skills/fast/SKILL.md

@@ -1,62 +0,0 @@
----
-name: fast
-description: Execute a one-shot small task without creating a spec.
-when_to_use: Use when the task is small, surgical, low-ambiguity, and not worth a full spec workflow.
-argument-hint: "\"<task description>\""
-disable-model-invocation: true
-allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent]
----
-
-# Flow Fast — Ultra-Fast Execution
-
-@${CLAUDE_PLUGIN_ROOT}/agent-preamble/preamble.md
-@${CLAUDE_PLUGIN_ROOT}/knowledge/atomic-commits.md
-
-Fast is a bypass workflow, not a replacement for the main spec pipeline. Keep
-this entrypoint focused on scope gating, lightweight clarification, and the
-final execution contract. Detailed fast-mode rules live in:
-
-- `references/applicability.md`
-- `references/clarification.md`
-- `references/execution-contract.md`
-
-## Arguments
-
-`$ARGUMENTS` must contain the one-shot task description. If it is empty, stop
-with the direct usage hint:
-
-```text
-/curdx-flow:fast "<task description>"
-```
-
-## Applicability
-
-Use `references/applicability.md` to decide whether the task qualifies for the
-fast path.
-
-- If the change is feature-sized, architecture-heavy, or requirement-driven,
-  route the user back to `/curdx-flow:start` -> `/curdx-flow:spec`
-- If the task stays surgical, continue with the fast contract
-
-## Clarification
-
-Run the quick clarification flow from `references/clarification.md` before
-editing. This path still requires explicit assumptions; "obvious" tasks do not
-skip that step.
-
-## Execution Contract
-
-Use `references/execution-contract.md` for:
-
-- lightweight context loading
-- mandatory code/doc lookup before edits
-- surgical execution rules
-- verification requirements
-- atomic commit and final output shape
-
-## Boundary
-
-- `fast` leaves no `.flow/specs/<name>/` audit trail
-- use it only when that traceability tradeoff is acceptable
-- if the work starts expanding, stop treating it as `fast` and switch to the
-  main workflow

package/skills/fast/references/applicability.md

@@ -1,25 +0,0 @@
-# Fast Applicability — When to Use and When to Abort
-
-## Good Fit
-
-- one-shot scripts
-- clear small changes
-- single-file or tightly bounded edits
-- simple bug fixes with low ambiguity
-
-## Not a Fit
-
-- production feature development
-- architecture-level or multi-module changes
-- user-story or acceptance-criteria driven work
-- anything that clearly needs spec artifacts for future traceability
-
-## Decision Rule
-
-If the task no longer looks surgical after initial exploration, stop calling it
-`fast` and route back to:
-
-```text
-/curdx-flow:start <name> "<goal>"
-/curdx-flow:spec
-```

package/skills/fast/references/clarification.md

@@ -1,20 +0,0 @@
-# Fast Clarification — Five Quick Questions
-
-Even in fast mode, do not skip explicit understanding.
-
-## Ask Before Editing
-
-```text
-Quick understanding (please confirm or amend):
-
-1. Task: <restate in your own words>
-2. Files involved: <preliminary assessment>
-3. Expected effect: <success criteria>
-4. Known constraints: <if any>
-5. Assumptions: <list explicitly>
-
-Any ambiguity? (yes: amend then continue / no: proceed directly)
-```
-
-Use `AskUserQuestion`. If the user confirms there is no ambiguity, continue
-directly to execution.

package/skills/fast/references/execution-contract.md

@@ -1,56 +0,0 @@
-# Fast Execution Contract — Lookup, Verify, Commit
-
-## Lightweight Context
-
-```bash
-[ -f "CLAUDE.md" ] && cat CLAUDE.md | head -50
-[ -f ".flow/CONTEXT.md" ] && cat .flow/CONTEXT.md | head -30
-```
-
-Fast mode may run outside a `.flow/` project. Treat `.flow/CONTEXT.md` as
-optional.
-
-## Mandatory Tool Use
-
-1. If a library or API is involved: use Context7
-2. Use Grep/Glob to find the relevant code
-3. Read current files before editing
-4. Apply Karpathy's surgical principles
-5. Run validation commands before committing
-
-## Commit Requirement
-
-Even in fast mode, do not leave changes scattered:
-
-```bash
-git add <exact files>
-git commit -m "<type>(<scope>): <summary>"
-```
-
-The commit must conform to `atomic-commits.md`.
-
-## Output Shape
-
-```text
-✓ Fast execution complete
-
-Changes:
-  - src/foo.ts (+3 -1)
-  - src/foo.test.ts (+15)
-
-Verification:
-  npm test ✓
-  tsc --noEmit ✓
-
-Commit: abc123f — fix(foo): handle null case
-
-Consider the full flow next time?
-  /curdx-flow:start <name> "<goal>"
-```
-
-## Forbidden
-
-- committing without verification
-- letting the change sprawl across unrelated modules
-- writing library APIs from memory
-- skipping the clarification step

package/skills/help/SKILL.md

@@ -1,55 +0,0 @@
----
-name: help
-description: Show command detail, workflow guidance, and troubleshooting.
-when_to_use: Use when the user asks how CurdX-Flow works, which command to run, what a workflow does, or how to troubleshoot common issues.
-argument-hint: "[<command-name> | workflow | troubleshoot]"
-disable-model-invocation: true
-allowed-tools: [Read, Bash]
----
-
-# CurdX-Flow Help
-
-Keep this skill focused on menuing and discovery. The canonical quick-overview,
-workflow, and troubleshooting payloads live in:
-
-- `references/dispatch.md`
-- `references/overview.md`
-- `references/workflow.md`
-- `references/troubleshoot.md`
-
-## No Argument — Quick Overview
-
-Render the compact command/skill/MCP summary from `references/overview.md`.
-
-## `<command-name>` — Command Detail
-
-Plugin skills are namespaced. When guiding users toward specialty skills, refer
-to them as `/curdx-flow:<name>`, not bare `/name`. E.g., /curdx-flow:security-audit.
-Canonical specialty paths: /curdx-flow:epic, /curdx-flow:browser-qa,
-/curdx-flow:ui-sketch, /curdx-flow:security-audit, /curdx-flow:brownfield-index.
-
-Use `references/dispatch.md` for:
-
-- `<command-name>` lookup against the shipped `skills/` layout
-- unknown-command fallback text
-- zero-argument usage guidance for detail mode
-
-The canonical shipped lookup path is:
-
-```text
-${CLAUDE_PLUGIN_ROOT}/skills/${CMD}/SKILL.md
-```
-
-## `workflow` — Standard Workflow
-
-Render the standard workflow from `references/workflow.md`.
-
-## `troubleshoot` — Common Issues
-
-Render the troubleshooting guide from `references/troubleshoot.md`.
-
-## Output Principles
-
-- Keep it compact. Use tables and lists, not prose.
-- Always point at a concrete next action, not "see the docs".
-- Version number should come from `cli/utils.js` dynamic read, not hard-coded.

package/skills/help/references/dispatch.md

@@ -1,20 +0,0 @@
-# Help Dispatch — Command Detail Routing
-
-When `$ARGUMENTS` is a command or skill name, resolve it from the shipped
-plugin layout:
-
-```bash
-CMD="$ARGUMENTS"
-[ -z "$CMD" ] && { echo "Usage: /curdx-flow:help <name>"; exit 1; }
-if [ -f "${CLAUDE_PLUGIN_ROOT}/skills/${CMD}/SKILL.md" ]; then
-  cat "${CLAUDE_PLUGIN_ROOT}/skills/${CMD}/SKILL.md"
-else
-  echo "Unknown: ${CMD}"
-  echo "Workflows: init start status spec implement cancel verify review fast debug help"
-  echo "Skills:    epic browser-qa ui-sketch security-audit brownfield-index"
-  exit 1
-fi
-```
-
-This lookup must stay inside `${CLAUDE_PLUGIN_ROOT}/skills/`. Do not fall back
-to any removed `commands/` layout or plugin-cache globbing.

package/skills/help/references/overview.md

@@ -1,39 +0,0 @@
-# Help Overview — Quick Surface Summary
-
-```text
-🚀 CurdX-Flow v2 — Claude Code Discipline Layer
-
-  11 slash commands (explicit control)
-  ────────────────────────────────────
-  /curdx-flow:init                  Initialize the .flow scaffold for the current repository.
-  /curdx-flow:start                 Create, resume, list, or switch the active feature spec.
-  /curdx-flow:status                Show active spec health, progress, artifacts, and recovery hints.
-  /curdx-flow:spec                  Generate or refresh research, requirements, design, and tasks for the active spec.
-  /curdx-flow:implement             Execute active-spec tasks with strategy routing and atomic progress.
-  /curdx-flow:cancel                Cancel the active execution loop or delete a spec with explicit confirmation.
-  /curdx-flow:verify                Verify the active spec against code, tests, and browser evidence.
-  /curdx-flow:review                Run two-stage review with optional adversarial, edge-case, and DevEx passes.
-  /curdx-flow:fast                  Execute a one-shot small task without creating a spec.
-  /curdx-flow:debug                 Debug a bug or failing test with the root-cause workflow.
-  /curdx-flow:help                  Show command detail, workflow guidance, and troubleshooting.
-
-  5 skills (auto-invoked by Claude based on context)
-  ────────────────────────────────────
-  /curdx-flow:epic                Decompose a large feature into vertical-slice sub-specs
-  /curdx-flow:browser-qa          Real-browser test via chrome-devtools MCP
-  /curdx-flow:ui-sketch           Generate UI design variants (via frontend-design skill)
-  /curdx-flow:security-audit      OWASP + STRIDE + CVE scan
-  /curdx-flow:brownfield-index    Map an unfamiliar / inherited codebase
-
-  3 MCP servers auto-installed
-  ────────────────────────────────────
-  context7                 Latest library docs
-  sequential-thinking      Structured reasoning
-  chrome-devtools          Browser automation
-
-  Usage:
-    /curdx-flow:help <command>    Detail for one command
-    /curdx-flow:help workflow     Standard workflow walkthrough
-    /curdx-flow:help troubleshoot Common problems
-    /curdx-flow:review --devex    Add the DevEx lens to review
-```

package/skills/help/references/troubleshoot.md

@@ -1,47 +0,0 @@
-# Help Troubleshoot — Common Issues
-
-```text
-🛠️  Common issues
-
-Q: After install, /curdx-flow:* commands are not found.
-A: Restart Claude Code. The plugin needs a fresh session to register.
-
-Q: MCP servers not starting?
-A: Check Node >= 18: node --version
-   Check MCPs:      claude mcp list
-   Health overall:  npx @curdx/flow doctor
-
-Q: GitHub slow / blocked during install?
-A: v1.1.5+ defaults to offline install (bundled plugin body).
-   Force-offline:  npx @curdx/flow install --no-deps
-   Force-online:   npx @curdx/flow install --online
-
-Q: claude-mem MCP keeps failing?
-A: It needs bun. Run: npx @curdx/flow doctor
-   If doctor reports bun/uv is installed but not on PATH, run:
-   npx @curdx/flow doctor --fix
-
-Q: /curdx-flow:init says .flow/ already exists?
-A: Use --force, or run /curdx-flow:start directly to begin a new spec in the existing .flow/.
-
-Q: Skills don't auto-invoke reliably?
-A: Invoke explicitly — plugin skills are namespaced. E.g., /curdx-flow:security-audit.
-
-Q: I want the old v1 commands (research, plan-ceo, party…).
-A: They're removed in v2. Use /curdx-flow:help workflow for the current paths, or stay on 1.x:
-   npm i -g @curdx/flow@^1.1
-
-Q: Too many gates blocking progress?
-A: Your spec mode decides gate strictness. Lower via:
-   /curdx-flow:start <name> "<goal>" --mode=fast
-
-Q: Where are decisions logged?
-A: .flow/STATE.md (D-NN entries). Edit directly — no slash command needed.
-
-Q: Stop-hook or execution loop seems stuck?
-A: Run /curdx-flow:status. If state/tasks disagree, run /curdx-flow:cancel, then resume with:
-   /curdx-flow:implement --strategy=subagent
-
-Q: File a bug / request feature
-A: https://github.com/curdx/curdx-flow/issues
-```

package/skills/help/references/workflow.md

@@ -1,37 +0,0 @@
-# Help Workflow — Canonical Main Loop
-
-```text
-📐 CurdX-Flow v2 Standard Workflow
-
-1. One-time setup (outside Claude Code)
-   └─ npx @curdx/flow install --all
-
-2. Per project (in Claude Code)
-   └─ /curdx-flow:init
-
-3. Per feature — the main loop
-   ├─ /curdx-flow:start my-feature "one-line goal"
-   ├─ /curdx-flow:status                        ← optional: see active spec + recovery hints
-   ├─ /curdx-flow:spec                          ← research → requirements → design → tasks
-   ├─ (optional) /curdx-flow:spec --review      ← add multi-dim planning review
-   ├─ /curdx-flow:implement                     ← execute tasks
-   ├─ /curdx-flow:verify                        ← goal-backward check
-   └─ /curdx-flow:review                        ← code review
-
-4. Evidence-backed handoff
-   └─ verification-report.md + review-report.md + atomic commits → human PR/release work
-
-5. Big feature (breaks into multiple specs)
-   └─ Say "this feature is too big, break it down" → epic skill auto-invokes
-
-6. One-off task (skip the spec)
-   └─ /curdx-flow:fast "rename foo to bar in src/"
-
-7. Stuck on a bug
-   └─ /curdx-flow:debug "tests fail intermittently after 3rd run"
-
-Modes (set via /curdx-flow:start --mode=...)
-  fast        One-off task paths
-  standard    Default — spec + gates + review
-  enterprise  Standard + adversarial + edge-case + devex + security-audit
-```

package/skills/implement/SKILL.md

@@ -1,104 +0,0 @@
----
-name: implement
-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
-allowed-tools: [Read, Write, Edit, Bash, Agent, Grep, Glob]
----
-
-# Flow Implement — Execute Spec
-
-@${CLAUDE_PLUGIN_ROOT}/knowledge/execution-strategies.md
-@${CLAUDE_PLUGIN_ROOT}/knowledge/atomic-commits.md
-
-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:
-
-- `references/preflight.md`
-- `references/strategy-router.md`
-- `references/state-init.md`
-- `references/native-task-sync.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`
-
-## Arguments
-
-`$ARGUMENTS` may include:
-
-- `[spec-name]`
-- `--strategy=auto|linear|subagent|stop-hook|wave`
-- `--task=<id>`
-- `--quick`
-
-## Preflight and Task Stats
-
-Use `references/preflight.md` for:
-
-- `.flow/` and active-spec resolution
-- argument parsing
-- `tasks.md` presence checks
-- `TOTAL`, `DONE`, `REMAINING`, `PARALLEL`, and `SEQUENTIAL` extraction
-
-## Strategy Routing
-
-Use `references/strategy-router.md` for the full decision tree and routing
-signals. The runtime selector is:
-
-## Execute State Init
-
-Use `references/state-init.md` before dispatching any execution protocol.
-
-## Native Task Sync
-
-Use `references/native-task-sync.md` to mirror CurDX execution into Claude's
-interactive task list when `TaskCreate` / `TaskUpdate` / `TaskList` are
-available. This is best-effort UX only; never let native task sync override the
-real `.flow` ledger.
-
-## Run the Selected Execution Protocol
-
-- `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`
-
-If `STRATEGY` is not one of `linear`, `subagent`, `wave`, `stop-hook`, stop
-immediately rather than guessing.
-
-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.
-
-## Progress and Completion Contract
-
-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:
-
-- `/curdx-flow:verify` for goal-backward evidence
-- `/curdx-flow:review` for code-quality findings after verification
-
-## Recovery Rules and Stop Conditions
-
-All retry, fix-task, and stop thresholds are centralized in
-`references/error-recovery.md`.
-
-The stop invariant is strict:
-
-- 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

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

@@ -1,43 +0,0 @@
-# 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:
-    if native task sync is active:
-        reconcile obvious tasks.md/native drift
-        mark the current Claude task in_progress
-    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
-    if native task sync is active:
-        mark the current Claude task completed
-    append the outcome to .progress.md
-    print "✓ Task X.Y complete"
-```
-
-## Execution Rules
-
-- Follow the `flow-executor` contract even though you stay inline
-- Treat `references/native-task-sync.md` as a mirror contract layered around
-  the inline loop, not a separate phase
-- 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
-- If `TaskUpdate` fails for the current task, increment
-  `native_sync_failure_count`, keep `.flow` state authoritative, and continue
-  the inline run unless the real task itself failed
-
-## 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
-- Native task sync failure alone is never a stop condition