@coopcli/specplan

Plan a project as a DAG of specs and user stories on a React Flow canvas, and generate OpenSpec changes per spec card. Local-only: the server binds to 127.0.0.1 and model calls run with your own Anthropic credentials.

npx @coopcli/specplan ./openspec

What it does

• DAG planning model — spec→spec edges are dependencies (kept acyclic; a cycle is rejected with the full path named), spec→story edges are containment (the coverage relation). User stories carry no edges of their own and must follow As a <user>, I want to <feature> so that <value proposition>.
• Backlog — anything not contained by a spec is uncovered work and shows in the backlog until a spec contains it.
• Non-destructive chat — a Claude-backed tool-calling assistant that can create_spec, create_user_story, link_dependency, contain_story, and reorder. There is no delete tool, structurally.
• Per-spec generation — each spec card generates its own OpenSpec change (openspec/changes/<specId>/) from the stories it contains; every story maps to a #### Scenario: block and the output must pass openspec validate <specId> --strict. Hand-edited bodies are detected by content hash and never overwritten (metadata-only update).
• Layered YAML storage — the DAG lives at <root>/specplan.yaml, plus one specplan.yaml per change directory (stories, dependencies, generation hash). Comments in hand-edited files survive round trips; the filesystem is the source of truth.

CLI

specplan [rootDir] [--port <n>]           # launch the browser app (default ./openspec, port 8789)
specplan generate <specId> [rootDir]      # headless generation; exit non-zero on strict-validation failure
specplan validate [rootDir]               # schema + acyclicity + story-formula check, named errors
specplan login [--profile] [--web-url]    # CoopCLI account (browser OAuth, ~/.coopcli/config.json)

Credentials

Chat and generation need Anthropic credentials on the machine — ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, or the Anthropic CLI's login profile (ant auth login). Planning works without them.

Troubleshooting

| Symptom | Fix | |---|---| | Startup warning "No Anthropic credentials detected" | Set ANTHROPIC_API_KEY or run ant auth login, then restart — planning works without, chat/generation need one | | Generation fails with the openspec validate --strict report | The model's output didn't validate; hit Generate again (the failed output is tool-owned, so a rerun regenerates freely) | | Regenerate says "metadata only, .md files untouched" | The change body was edited outside specplan (or predates it) — that's the hand-edit guard working. Delete the body files if you want a fresh full emit | | A spec card is missing after openspec archive | Archived change dirs (changes/archive/) deliberately don't land on the canvas; remove the stale node/edges from specplan.yaml if you archived by hand — specplan validate names the dangling references | | Port already in use | Handled automatically — the server scans forward and prints the bound URL; --port <n> sets the start | | @ references don't find your files | The @ scope is the directory you launched specplan from, not the plan root — launch from the repo root |

Development (repo)

pnpm --filter @coopcli/specplan dev      # vite HMR (:5173-ish) + API on :8789
pnpm --filter @coopcli/specplan check    # tsc
pnpm --filter @coopcli/specplan test     # vitest (model, storage, server, chat, generation)
pnpm --filter @coopcli/specplan test:e2e # Playwright against a throwaway fixture tree
pnpm --filter @coopcli/specplan build:cli

The product site (site/) is an assets-only worker (specplan-microsite) served at coopcli.com/products/specplan behind coopcli-router; pnpm site:dev runs it on :4324. See TESTING.md for the scenario→test map.