@coopcli/specplan 5.2.0

package/README.md

@@ -0,0 +1,40 @@
+# @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.
+
+```bash
+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.
+
+## Development (repo)
+
+```bash
+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.