@curdx/flow 3.0.0 → 3.1.0

package/schemas/spec-state.schema.json

@@ -1,165 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://curdx-flow.dev/schemas/spec-state.schema.json",
-  "title": "CurdX-Flow Spec State",
-  "description": "Schema for .flow/specs/<name>/.state.json — tracks phase progress across sessions",
-  "type": "object",
-  "required": ["version", "spec_name", "phase"],
-  "properties": {
-    "version": {
-      "type": "string",
-      "const": "1.0"
-    },
-    "spec_name": {
-      "type": "string",
-      "pattern": "^[a-z0-9][a-z0-9-]*$",
-      "description": "Kebab-case identifier matching the directory name"
-    },
-    "goal": {
-      "type": "string",
-      "description": "One-sentence goal from /curdx-flow:start"
-    },
-    "mode": {
-      "type": "string",
-      "enum": ["fast", "standard", "enterprise"],
-      "default": "standard"
-    },
-    "strategy": {
-      "type": "string",
-      "enum": ["auto", "subagent", "stop-hook", "wave", "linear"],
-      "default": "auto"
-    },
-    "quickMode": {
-      "type": "boolean",
-      "default": false,
-      "description": "When true, execution hooks block AskUserQuestion and agents must record assumptions instead of asking."
-    },
-    "phase": {
-      "type": "string",
-      "enum": [
-        "research",
-        "requirements",
-        "design",
-        "tasks",
-        "execute",
-        "verify",
-        "review",
-        "completed"
-      ]
-    },
-    "phase_status": {
-      "type": "object",
-      "properties": {
-        "research": { "$ref": "#/definitions/phaseStatus" },
-        "requirements": { "$ref": "#/definitions/phaseStatus" },
-        "design": { "$ref": "#/definitions/phaseStatus" },
-        "tasks": { "$ref": "#/definitions/phaseStatus" },
-        "execute": { "$ref": "#/definitions/phaseStatus" },
-        "verify": { "$ref": "#/definitions/phaseStatus" },
-        "review": { "$ref": "#/definitions/phaseStatus" }
-      }
-    },
-    "execute_state": {
-      "type": "object",
-      "description": "Runtime state for Phase 2 (execution engine, post-Phase 1)",
-      "properties": {
-        "poc_complete": { "type": "boolean" },
-        "refactor_complete": { "type": "boolean" },
-        "test_complete": { "type": "boolean" },
-        "quality_gate_complete": { "type": "boolean" },
-        "task_index": { "type": "integer", "minimum": 0 },
-        "total_tasks": { "type": "integer", "minimum": 0 },
-        "task_iteration": { "type": "integer", "minimum": 1 },
-        "global_iteration": { "type": "integer", "minimum": 1 },
-        "failed_attempts": { "type": "integer", "minimum": 0 },
-        "recovery_mode": {
-          "type": "string",
-          "enum": ["manual", "fix-task"],
-          "default": "manual"
-        },
-        "max_fix_tasks_per_original": {
-          "type": "integer",
-          "minimum": 1,
-          "maximum": 5,
-          "default": 2
-        },
-        "fix_task_map": {
-          "type": "object",
-          "description": "Per-original-task recovery attempts created by fix-task mode.",
-          "additionalProperties": {
-            "type": "object",
-            "required": ["attempts", "fix_task_ids"],
-            "properties": {
-              "attempts": { "type": "integer", "minimum": 0 },
-              "fix_task_ids": {
-                "type": "array",
-                "items": { "type": "string" }
-              },
-              "last_error": { "type": "string" }
-            }
-          }
-        },
-        "native_task_map": {
-          "type": "object",
-          "description": "Best-effort mapping from CurDX task ids (for example 1.2 or 4.VF) to Claude native task ids for interactive task-list sync.",
-          "additionalProperties": {
-            "type": "string"
-          }
-        },
-        "native_sync_enabled": {
-          "type": "boolean",
-          "default": true,
-          "description": "When false, execution skips Claude native task-list sync and relies only on tasks.md plus state.json."
-        },
-        "native_sync_failure_count": {
-          "type": "integer",
-          "minimum": 0,
-          "default": 0,
-          "description": "Consecutive best-effort native task sync failures during the current execute run."
-        }
-      }
-    },
-    "decisions": {
-      "type": "array",
-      "description": "Decisions locked in this spec (mirror of what's in STATE.md)",
-      "items": {
-        "type": "object",
-        "required": ["id", "decision"],
-        "properties": {
-          "id": {
-            "type": "string",
-            "pattern": "^D-[0-9]{2,}$"
-          },
-          "decision": { "type": "string" },
-          "rationale": { "type": "string" },
-          "timestamp": {
-            "type": "string",
-            "format": "date-time"
-          }
-        }
-      }
-    },
-    "gates_enabled": {
-      "type": "array",
-      "items": { "type": "string" }
-    },
-    "agents_active": {
-      "type": "array",
-      "items": { "type": "string" }
-    },
-    "created": {
-      "type": "string",
-      "format": "date"
-    },
-    "updated": {
-      "type": "string",
-      "format": "date-time"
-    }
-  },
-  "definitions": {
-    "phaseStatus": {
-      "type": "string",
-      "enum": ["not_started", "in_progress", "completed", "skipped", "failed"]
-    }
-  }
-}

package/settings.json

@@ -1,8 +0,0 @@
-{
-  "agent": "flow-orchestrator",
-  "subagentStatusLine": {
-    "type": "command",
-    "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/subagent-statusline.sh",
-    "refreshInterval": 5
-  }
-}

package/skills/brownfield-index/SKILL.md

@@ -1,53 +0,0 @@
----
-name: brownfield-index
-description: Use when the user needs structural understanding of an unfamiliar, inherited, legacy, or brownfield codebase.
-when_to_use: Triggers on "legacy code", "brownfield", "unfamiliar", "new to this code", "new to this project", "just joined", "inherited codebase", "explore codebase", "understand structure", "index code", "map modules", "tour", "onboard", "what is this project".
-argument-hint: "[path]"
-context: fork
-agent: flow-brownfield-analyst
-paths:
-  - "package.json"
-  - "pnpm-workspace.yaml"
-  - "turbo.json"
-  - "nx.json"
-  - "pyproject.toml"
-  - "requirements*.txt"
-  - "go.mod"
-  - "Cargo.toml"
-  - "Gemfile"
-  - "composer.json"
-  - "pom.xml"
-  - "build.gradle*"
-  - "mix.exs"
-  - "deno.json*"
-  - "src/**"
-  - "lib/**"
-  - "app/**"
-  - "apps/**"
-  - "packages/**"
-  - "services/**"
----
-
-# Brownfield Index
-
-This is a fast structural mapping skill for inherited codebases. Keep the
-entrypoint focused on when to index, what the analyst must produce, and where
-to route the user next. Detailed rules live in:
-
-- `references/applicability.md`
-- `references/index-contract.md`
-- `references/handoff.md`
-
-## Preconditions
-
-Use `references/applicability.md` to decide whether the repository actually
-needs a brownfield index first.
-
-## Index Contract
-
-`flow-brownfield-analyst` writes the structural map defined in
-`references/index-contract.md`.
-
-## Handoff
-
-Use `references/handoff.md` to route the user to the next relevant command.

package/skills/brownfield-index/references/applicability.md

@@ -1,12 +0,0 @@
-# Brownfield Applicability — When to Index First
-
-Use this skill when:
-
-- the repository is unfamiliar, inherited, or legacy
-- the user needs a quick structural map before feature work
-
-Do not use it for a fresh greenfield repo that should start directly with:
-
-```text
-/curdx-flow:start <name> "<goal>"
-```

package/skills/brownfield-index/references/handoff.md

@@ -1,8 +0,0 @@
-# Brownfield Handoff — What to Do After Indexing
-
-Route to the next concrete action:
-
-- feature work -> `/curdx-flow:start <name> "<goal>"`
-- targeted bug work -> `/curdx-flow:debug "<symptom>"`
-
-For deep framework or library research, use Context7 directly.

package/skills/brownfield-index/references/index-contract.md

@@ -1,10 +0,0 @@
-# Brownfield Index Contract — What the Analyst Must Produce
-
-`flow-brownfield-analyst` should:
-
-1. detect the actual stack from manifests
-2. scan structure, entry points, boundaries, and developer-loop commands
-3. map API or CLI surfaces when they exist
-4. write `.flow/codebase-index.md`
-
-The index should be quick and decision-useful, not exhaustive.

package/skills/browser-qa/SKILL.md

@@ -1,39 +0,0 @@
----
-name: browser-qa
-description: Use when the user needs real-browser QA for a UI or frontend flow.
-when_to_use: Triggers on "browser test", "test in browser", "UI test", "e2e test", "frontend test", "accessibility", "a11y", "WCAG", "lighthouse", "performance audit", "console error", "network request", "cross-browser", "responsive", "mobile test", "visual regression", "screenshot".
-argument-hint: "\"<url or user flow>\""
-context: fork
-agent: flow-qa-engineer
-paths:
-  - "**/*.{html,css,scss,sass,less,js,jsx,ts,tsx,vue,svelte,astro}"
-  - "app/**"
-  - "pages/**"
-  - "components/**"
-  - "public/**"
----
-
-# Browser QA
-
-This skill orchestrates real-browser validation, not a generic UI review. Keep
-the entrypoint focused on prerequisites, QA artifact requirements, and the
-handoff after findings. Detailed rules live in:
-
-- `references/prerequisites.md`
-- `references/qa-contract.md`
-- `references/handoff.md`
-
-## Preconditions
-
-Use `references/prerequisites.md` to confirm browser MCP availability and the
-URL or flow under test. Real browser execution in this skill depends on
-`mcp__chrome_devtools__*`.
-
-## QA Contract
-
-`flow-qa-engineer` should execute the browser workflow in
-`references/qa-contract.md`.
-
-## Handoff
-
-Post-QA routing and bug follow-up live in `references/handoff.md`.

package/skills/browser-qa/references/handoff.md

@@ -1,6 +0,0 @@
-# Browser QA Handoff — Where Findings Go Next
-
-- if reproducible bugs are found -> `/curdx-flow:debug "<bug title>"`
-- if accessibility issues are found -> report concrete WCAG-linked fixes
-- if the flow is clean -> hand off `qa-report.md` as additional evidence, not a
-  replacement for `verify` or `review`

package/skills/browser-qa/references/prerequisites.md

@@ -1,10 +0,0 @@
-# Browser QA Prerequisites — Browser and URL Required
-
-Before dispatching:
-
-- confirm `mcp__chrome_devtools__*` is available
-- confirm a URL under test exists
-- confirm the flow and success criteria
-
-If browser MCP is missing, fall back to a manual checklist rather than
-pretending a real-browser run happened.

package/skills/browser-qa/references/qa-contract.md

@@ -1,20 +0,0 @@
-# Browser QA Contract — What the QA Agent Must Do
-
-`flow-qa-engineer` should:
-
-1. open the target URL
-2. drive the flow in a real browser
-3. collect console, network, screenshot, and optional Lighthouse evidence
-4. compare observed behavior to expected behavior
-
-## Required Artifacts
-
-- `.flow/specs/<active>/qa-report.md`
-- `.flow/specs/<active>/qa-screenshots/`
-
-The report should include:
-
-- bugs by severity
-- performance metrics
-- accessibility findings
-- console errors

package/skills/cancel/SKILL.md

@@ -1,41 +0,0 @@
----
-name: cancel
-description: Cancel the active execution loop or delete a spec with explicit confirmation.
-when_to_use: Use when the user wants to stop the current execution loop, abort a stuck run, or delete the active spec intentionally.
-argument-hint: "[spec-name] [--delete-spec --yes]"
-disable-model-invocation: true
-allowed-tools: [Read, Bash]
----
-
-# CurdX-Flow Cancel
-
-`cancel` is a recovery control, not an execution path. Keep this entrypoint
-focused on target selection, destructive-mode gating, and the final recovery
-message. Detailed cancel rules live in:
-
-- `references/target-resolution.md`
-- `references/state-recovery.md`
-- `references/destructive-mode.md`
-- `references/reporting.md`
-
-## Target Resolution
-
-Use `references/target-resolution.md` to resolve the target spec.
-
-## Default Behavior
-
-Default mode is non-destructive. Use `references/state-recovery.md` to:
-
-- roll execution state back safely
-- preserve spec artifacts and reports
-- append a recovery note to `.progress.md`
-- recommend the best resume command
-
-## Destructive Behavior
-
-Delete a spec only when both `--delete-spec` and `--yes` are present. The
-deletion rules live in `references/destructive-mode.md`.
-
-## Output
-
-Use `references/reporting.md` for the default and destructive-mode summaries.

package/skills/cancel/references/destructive-mode.md

@@ -1,17 +0,0 @@
-# Cancel Destructive Mode — Explicit and Narrow
-
-Delete the spec directory only when both flags are present:
-
-```text
-/curdx-flow:cancel <spec-name> --delete-spec --yes
-```
-
-## Destructive Flow
-
-1. print the target path and removal scope
-2. delete `.flow/specs/<target>`
-3. if it was active, clear `.flow/.active-spec`
-4. leave all project-level `.flow` files untouched
-
-If `--delete-spec` appears without `--yes`, stop and print the exact command
-required.

package/skills/cancel/references/reporting.md

@@ -1,18 +0,0 @@
-# Cancel Reporting — Recovery vs Deletion Summary
-
-Default mode:
-
-```text
-✓ Cancelled execution loop: <spec-name>
-  State: execute → cancelled, phase → tasks
-  Preserved: spec artifacts and progress
-  Resume: /curdx-flow:implement --strategy=subagent
-```
-
-Destructive mode:
-
-```text
-✓ Deleted spec: <spec-name>
-  Removed: .flow/specs/<spec-name>
-  Active spec cleared: yes|no
-```

package/skills/cancel/references/state-recovery.md

@@ -1,30 +0,0 @@
-# Cancel State Recovery — Safe Rollback Without Deletion
-
-Default mode preserves all human-readable artifacts.
-
-## Recovery Steps
-
-1. Read `.flow/specs/<target>/.state.json`
-2. Set `phase` to `tasks`
-3. Set `phase_status.execute` to `cancelled`
-4. Remove `execute_state` and `strategy`
-5. If the state file is missing, print `No execution state for <target>. Nothing to cancel.`
-
-Use checkpoint-tracked `Edit` or `Write`, not ad-hoc Bash or Python writers.
-
-## Progress Entry
-
-Append to `.progress.md`:
-
-```markdown
-## Execution Cancelled YYYY-MM-DD
-- Cancelled by: /curdx-flow:cancel
-- Preserved: research.md, requirements.md, design.md, tasks.md, progress, reports
-- Resume: /curdx-flow:implement --strategy=subagent or /curdx-flow:spec --phase=tasks --regenerate
-```
-
-## Safety
-
-- never delete project-level `.flow` files
-- if `.state.json` is corrupt, rename it to `.state.json.corrupt.<timestamp>`
-- prefer `/curdx-flow:status` after cancel to confirm recovery state

package/skills/cancel/references/target-resolution.md

@@ -1,7 +0,0 @@
-# Cancel Target Resolution — Positional Spec Name or Active Spec
-
-1. If `$ARGUMENTS` includes a positional spec name, target `.flow/specs/<name>`
-2. Otherwise read `.flow/.active-spec`
-3. If no target exists, print `No active spec to cancel` and stop
-
-`cancel` uses a positional spec argument, not `--spec=<name>`.

package/skills/debug/SKILL.md

@@ -1,45 +0,0 @@
----
-name: debug
-description: Debug a bug or failing test with the root-cause workflow.
-when_to_use: Use when the user reports a bug, failing test, regression, stack trace, flaky behavior, or wants root-cause analysis instead of trial-and-error edits.
-argument-hint: "\"<bug description>\""
-disable-model-invocation: true
-context: fork
-agent: flow-debugger
----
-
-# Systematic Debug
-
-Use the 4-phase root-cause methodology in
-`@${CLAUDE_PLUGIN_ROOT}/knowledge/systematic-debugging.md`. Keep this entrypoint
-focused on bug intake, required context, and the hard-stop contract. Detailed
-debugging rules live in:
-
-- `references/intake.md`
-- `references/context-gathering.md`
-- `references/phase-workflow.md`
-- `references/failure-guard.md`
-- `references/reporting.md`
-
-## Intake
-
-Use `references/intake.md` to validate `$ARGUMENTS` and anchor the debugging
-target before entering diagnosis.
-
-## Pre-Diagnosis Context
-
-Gather the baseline context from `references/context-gathering.md` before
-entering Phase 1.
-
-## Four Phases
-
-Use `references/phase-workflow.md` as the 4-phase contract.
-
-## Three-Failure Guard
-
-Use `references/failure-guard.md` for the stop contract and required failure
-report.
-
-## Output to User
-
-Use `references/reporting.md` for the compact completion summary.

package/skills/debug/references/context-gathering.md

@@ -1,11 +0,0 @@
-# Debug Context Gathering — Baseline Before Diagnosis
-
-Gather these before diagnosing:
-
-- recent commits: `git log --oneline -20`
-- uncommitted changes: `git status --short`, `git diff --stat`
-- active spec, if any:
-  - read `.flow/.active-spec`
-  - if set, read `.flow/specs/<active>/.progress.md`
-
-The point is to debug against observed repo state, not assumptions.

package/skills/debug/references/failure-guard.md

@@ -1,25 +0,0 @@
-# Debug Failure Guard — Stop After Three Real Attempts
-
-If Phase 4 has tried three genuinely different approaches and all failed, stop.
-Do not try a fourth.
-
-## Required Failure Report
-
-```text
-⚠ Systematic debug halted after 3 attempts
-
-Attempts:
-  1. <approach 1>: <why it failed>
-  2. <approach 2>: <why it failed>
-  3. <approach 3>: <why it failed>
-
-Root-issue hypothesis: architecture | dependency | data | unknown
-Recommended next step: <user action>
-```
-
-## Forbidden
-
-- prayer-driven retries
-- "maybe it's..." as a Phase 1 conclusion
-- green fix commits without a corresponding red test commit
-- fix claims without BEFORE/AFTER reality evidence

package/skills/debug/references/intake.md

@@ -1,12 +0,0 @@
-# Debug Intake — Require a Concrete Bug Target
-
-The debug target is `$ARGUMENTS`.
-
-If `$ARGUMENTS` is empty, print:
-
-```text
-Usage: /curdx-flow:debug "<bug description>"
-```
-
-Do not begin diagnosis until the failing behavior, test, or regression target is
-concrete enough to reproduce.

package/skills/debug/references/phase-workflow.md

@@ -1,34 +0,0 @@
-# Debug Phases — Root Cause, Pattern, Hypothesis, Fix
-
-## Phase 1 — Root-Cause Investigation
-
-- read the error carefully
-- build a minimal reproduction
-- append `Reality Check (BEFORE)` to `.progress.md` when a spec is active
-- trace recent changes and data flow
-- exit only when the root cause fits in one sentence
-
-## Phase 2 — Pattern Analysis
-
-- find a working counter-example nearby
-- identify the difference from the failing case
-- classify the issue as `isolated` or `systemic`
-
-If systemic, Phase 4 must sweep sibling cases.
-
-## Phase 3 — Hypothesis and Test
-
-- state one hypothesis
-- write the smallest distinguishing test
-- run it before committing
-- if disproved, return to Phase 1 with the new signal
-
-## Phase 4 — Implement the Fix
-
-1. write a failing test and confirm it fails
-2. fix the root cause and confirm the test now passes
-3. run the full regression suite
-4. re-run the original reproduction command and append `Reality Check (AFTER)`
-5. if systemic, sweep sibling occurrences in the same stage
-
-Do not mask the issue with defensive noise that leaves the root cause intact.

package/skills/debug/references/reporting.md

@@ -1,20 +0,0 @@
-# Debug Reporting — Compact Root-Cause Closeout
-
-End with:
-
-```text
-✓ Debug complete
-
-Root cause: <Phase 1 — one sentence>
-Pattern:    <Phase 2 — isolated or systemic>
-
-Fix commits:
-  - <sha>: test(<scope>): red - failing test
-  - <sha>: fix(<scope>): green - root-cause fix
-  - <sha>: fix(<scope>): sweep - N sibling cases    (if systemic)
-
-Verification: failing test now PASS ✓; full suite green ✓
-```
-
-Keep the closeout evidence-first. The root cause and verification outcome
-matter more than narrative.

package/skills/epic/SKILL.md

@@ -1,39 +0,0 @@
----
-name: epic
-description: Use when the user needs to decompose a large feature into smaller vertical-slice specs with dependencies.
-when_to_use: Triggers on "epic", "big feature", "too big", "decompose", "break down", "break into", "split into", "multi-spec", "multiple features", "sub-features", "vertical slice", "parent feature", "large scope", "won't fit in one sprint", "needs splitting".
-argument-hint: "\"<epic goal>\""
-context: fork
-agent: flow-triage-analyst
----
-
-# Epic Decomposition
-
-This is a specialty orchestration skill for multi-spec planning. Keep the
-entrypoint focused on when to use epic decomposition and what artifacts it must
-leave behind. Detailed rules live in:
-
-- `references/epic-intake.md`
-- `references/epic-artifacts.md`
-- `references/slice-handoff.md`
-
-## Preconditions
-
-- a `.flow/` project exists
-- the feature scope is too large for a single spec
-
-## Intake
-
-Use `references/epic-intake.md` to confirm the epic boundary before dispatching
-`flow-triage-analyst`.
-
-## Artifact Contract
-
-Use `references/epic-artifacts.md` for the required outputs:
-
-- `.flow/_epics/<epic-name>/epic.md`
-- one `.flow/specs/<epic-name>-<slice-id>/` skeleton per slice
-
-## Handoff
-
-User-facing next-step routing lives in `references/slice-handoff.md`.