curdx-flow

Spec-driven delivery for Claude Code — turn a single prompt into a reviewable, resumable, verifiable delivery record.

English · 简体中文

/curdx-flow:start reads your repo and your goal, then auto-routes: handle directly · light spec · full spec · resume work · or triage one big ask into linked specs.

Why it exists

Claude Code can write code. Real feature work exposes three failure modes the moment it gets serious:

It isn't another project management system. It's an execution discipline layer for Claude Code.

30-second install

Requires Claude Code v2.1.154 or newer (check with claude --version; curdx-flow doctor surfaces the floor as platformFloor).

Native marketplace install is the primary path:

claude plugin marketplace add curdx/curdx-flow
claude plugin install curdx-flow@curdx

Inside Claude Code:

/curdx-flow:help
/curdx-flow:start todo-app build a todo app with create/edit/complete/delete, browser-verified

Optionally, the @curdx/flow npm installer is a convenience bootstrap: it asks for your language (中文 / English), opens an interactive picker for the optional companion plugins and MCP servers, and writes the managed block in ~/.claude/CLAUDE.md. Companion plugins are soft-detected at runtime, not hard dependencies — curdx-flow installs and runs without them (degraded, with a doctor hint):

npx @curdx/flow install

CI / scripted environments? Skip prompts and add everything: npx @curdx/flow install --all --yes --lang en.

Workflow

The typical path:

1. Start — identify repo, goal, risk, and any existing specs.
2. Research — gather code facts, official docs, prior context.
3. Requirements — turn the goal into acceptance criteria and boundaries.
4. Design — capture approach, risks, interfaces, verification strategy.
5. Tasks — slice into value-bearing tasks, each with a verify command.
6. Implement — execute task-by-task via native /goal plus specialist agents.
7. Verify — record command / browser / CI / release / npm evidence into verificationBlocks.

Common commands

Capabilities it coordinates

curdx-flow is a Claude Code plugin. The companions below are soft-detected at runtime — none is a hard dependency in the manifest, so curdx-flow installs and runs without them:

When one is missing, curdx-flow doctor reports the degraded state and the fix — it won't silently skip critical evidence.

CLI

@curdx/flow ships both an installer and a diagnostic tool:

# Show install state
npx @curdx/flow status

# Install or update plugins / MCP capabilities
npx @curdx/flow install --all --yes
npx @curdx/flow update

# Analyze Claude Code session logs
npx @curdx/flow analyze

# Validate verificationBlocks for the current spec
npx @curdx/flow check

The plugin also exposes a runtime curdx-flow CLI for skills and hooks:

curdx-flow doctor
curdx-flow route --compile --goal "release a Claude Code plugin"
curdx-flow dev detect
curdx-flow dev up
curdx-flow dev health
curdx-flow dev verify
curdx-flow dev down

When to use it

Use it for:

• Claude Code plugins, CLIs, full-stack apps, frontend pages, backend services, release flows.
• Work where research → requirements → design → tasks → execution → verification all need to be traceable.
• Release-grade tasks that need browser, CI, npm / GitHub Release evidence.
• Tasks that have failed several times and need a recoverable failure trail.

Skip it for:

• One-off "what does this snippet mean?" questions.
• Requests where you explicitly want answers without file edits.
• Zero-risk one-line tweaks — /curdx-flow:start will route those to direct execution or a light spec anyway.

What a spec looks like

By default, specs land under specs/<name>/:

specs/
└── todo-app/
    ├── research.md
    ├── requirements.md
    ├── design.md
    ├── tasks.md
    ├── .curdx-state.json
    └── .progress.md

Ground rules:

• research.md / requirements.md / design.md / tasks.md are committable context assets.
• .curdx-state.json is execution state: phase, task index, verificationBlocks, recovery info.
• .progress.md is runtime progress + learning — usually .gitignore-d.
• Completion claims must trace back to verificationBlocks — not just to model prose.

Repo structure

src/
  core/                     # differentiated core: capabilities, contracts, evidence, verdict
  hooks/                    # Claude Code hook source + shared runtime libraries (hooks/lib)
  flows/                    # optional npm bootstrap (companion picker + CLAUDE.md sync) + analyze
  registry/                 # legacy companion-install layer (native `claude plugin` is primary)
  i18n/ runner/ ui/         # CLI plumbing for the optional bootstrap
plugins/curdx-flow/         # The Claude Code plugin itself
  .claude-plugin/           # plugin.json (+ $schema)
  skills/                   # /curdx-flow:* slash skills
  agents/                   # executor, reviewer, QA, architect, PM, …
  hooks/                    # Claude Code hook configs + committed script bundles
  schemas/                  # state / evidence / report contract schemas
scripts/                    # build, version bump, validation, Claude Code smoke
tests/                      # Vitest tests

Local development

npm ci
npm run build
npm run build:hooks
npm run typecheck
npm run test:hooks

Release-grade validation:

npm run verify
claude plugin validate ./plugins/curdx-flow
CURDX_FLOW_CLAUDE_BIN=claude npm run test:claudecc

After editing anything under src/hooks/** you must run:

npm run build:hooks
npm run check:hooks-fresh
npm run test:hooks

Release rules

Bump version through the script — never by hand:

node scripts/bump-version.mjs patch

A release requires two tags pushed together:

git tag -a vX.Y.Z -m "@curdx/flow X.Y.Z"
git tag -a curdx-flow--vX.Y.Z -m "curdx-flow X.Y.Z"
git push origin main vX.Y.Z curdx-flow--vX.Y.Z

• vX.Y.Z — triggers the npm publish.
• curdx-flow--vX.Y.Z — the plugin tag Claude Code's marketplace resolves.
• Don't push tags until npm run verify, claude plugin validate, and test:claudecc all pass.

Troubleshooting

References

• Claude Code Plugins: https://docs.claude.com/en/docs/claude-code/plugins
• Claude Code Hooks: https://docs.claude.com/en/docs/claude-code/hooks
• npm package: https://www.npmjs.com/package/@curdx/flow
• Releases: https://github.com/curdx/curdx-flow/releases

License

MIT