storymapper 0.1.0

package/README.md

@@ -0,0 +1,239 @@
+# Storymapper
+
+![Story Map view](docs/images/map.png)
+
+**A User Story Map + Kanban board that a product owner and an AI coding agent
+plan together — the same backlog, live, from a browser and from an MCP client —
+with the quality method built in.**
+
+Storymapper is one Node.js package that ships three things:
+
+1. **A browser UI** — a User Story Map (process steps × releases, with epics and
+   stories in the cells), a Kanban board, plus table, dependency-graph,
+   requirements and settings views. Plain HTML + modular JavaScript, no build step.
+2. **An HTTP + WebSocket server** — persists every project in SQLite with a full
+   per-project revision history, and pushes changes to connected browsers within
+   ~100 ms.
+3. **An MCP server** (stdio) **plus a pass-through CLI** — the same ~70 tools,
+   for Claude Desktop / Claude Code via MCP and for scripts or other harnesses
+   as one-shot commands. Anything the agent does appears live in the product
+   owner's browser with a highlight-and-move animation; anything edited by hand
+   flows back to the agent on its next read.
+
+The result is a **shared planning surface**: the agent isn't writing to a
+database the human can't see — the two work the same board in real time.
+
+---
+
+## Why it exists
+
+Planning AI-assisted development breaks down when the plan lives in one place and
+the work in another. Storymapper makes the plan a live, bidirectional artifact:
+
+- You bring the product idea and a rough shape of what to build; the agent lays
+  it out on the board — epics, stories, releases, dependencies — and you watch
+  it appear and rearrange it by hand.
+- You reprioritize, split, annotate — and the agent picks it up on its next
+  read and continues from the current state of the board.
+- Every change is a **revision** you can inspect and restore.
+
+## Quality steering at the product level
+
+When an agent does the building, the human contribution moves up a level: you
+describe the product, review its behavior, and steer the work through the
+process. That
+process is Storymapper's real substance — a complete quality method the engine
+enforces as tool-level rules: a ticket is **specified before it is built**
+(Definition of Ready) and **proven before it counts as done** (Definition of
+Done plus a published test plan with recorded runs), and your requirements stay
+traceably linked to the stories that implement them and the tests that verify
+them. An agent that tries to skip a step gets a structured error naming exactly
+what is missing — and fixes it. This puts professional-grade quality assurance
+into the hands of everyone who thinks in products — founders, domain experts,
+product owners: the method speaks the language of the product and lets you
+hold an agent's work to a standard you can verify. The workflow itself
+(statuses, transitions, gates, board columns) is configurable per project, and
+the companion skill teaches the agent the discipline, not just the tools.
+
+![Ticket detail — acceptance criteria, Definition of Ready / Definition of Done checklists, and typed links](docs/images/Ticket.png)
+
+## Design principles
+
+- **Zero build.** No bundler, no transpiler, no TypeScript. The browser loads
+  classical `<script src>` modules; the server runs the same files under Node via
+  a UMD wrapper. Clone and run.
+- **One source of truth for pure logic.** All domain logic (normalization,
+  operations, the workflow/governance engines, graph algorithms) lives in
+  `shared/core.js` and is *symlinked* into the frontend and *re-exported* by the
+  server — the same code runs in the browser, the HTTP server and the MCP server,
+  with no mirror step to drift.
+- **Raw HTTP, no framework.** `http.createServer` + manual routing. Small,
+  readable, dependency-light.
+- **Synchronous SQLite** via `better-sqlite3`, atomic per-save transactions, a
+  per-project mutex, and count-bounded revision retention.
+- **Single-user, local-first.** One human plus their agent on one machine. See
+  the security model below.
+
+For the full picture — layering, data model, live-sync mechanism, testing
+approach and deliberate non-goals — see **[ARCHITECTURE.md](ARCHITECTURE.md)**.
+
+---
+
+## Requirements
+
+- **Node.js ≥ 20** (developed and tested on 20 and 22; Node 18 is end-of-life).
+- `better-sqlite3` is a native module. Prebuilt binaries cover mainstream
+  platforms (macOS / Linux / Windows on x64 + arm64 for supported Node
+  versions), so `npm install` usually just works. On an unsupported
+  platform/Node combination it compiles from source and needs a C/C++ toolchain
+  (Xcode Command Line Tools, `build-essential`, or the Windows build tools).
+
+## Install
+
+```sh
+git clone <your-fork-url> storymapper
+cd storymapper
+npm install
+```
+
+## Run the browser UI
+
+```sh
+npm start
+# → http://localhost:8770/   (data in ./.storymap-data)
+# → Ctrl-C to stop
+```
+
+![Kanban view](docs/images/kanban.png)
+
+Open <http://localhost:8770/> — that's all. The page connects to the server it
+was loaded from and stores every project there (SQLite, with full revision
+history).
+
+> **Hosting the page somewhere else?** Served from a different origin, the UI
+> runs on browser `localStorage` instead; point it at a running server with
+> `?api=<url>`. The page must be loaded from `localhost` / `127.0.0.1` — opening
+> the HTML directly as a `file://` page is not supported (see the security
+> model).
+
+![Dependency graph view](docs/images/dependency-graph.png)
+
+## Connect it to your Claude (one command per surface)
+
+Storymapper reaches an agent through two parts: the **MCP server** (the tools)
+and the companion **skill** (the working method — the DoR/DoD contract, the
+workflow discipline, when to read the board and when to write to it).
+Installing one does **not** install the
+other, so the setup commands below always install **both**:
+
+| Surface | Command | What remains |
+|---|---|---|
+| **Claude Code** (CLI) | `npm run install-code` | restart your Claude Code session |
+| **Claude Desktop** | `npm run install-desktop` | upload `dist/storymap-skill.zip` under **Settings → Capabilities → Skills**, then fully restart the app — and use a **Chat** (see below) |
+| **claude.ai in the browser** | — | works with remote connectors only; it cannot reach a local server. Use Claude Code or Claude Desktop. |
+
+`npm run install-code` copies the skill to `~/.claude/skills/storymap` and
+registers the MCP server via `claude mcp add` (user scope). If the `claude`
+CLI is unavailable it prints the ready-made command instead.
+
+`npm run install-desktop` writes the server entry into the platform's
+`claude_desktop_config.json` (existing entries survive, a `.bak` backup is
+kept) and builds the skill zip. The skill store in Claude Desktop is managed
+by the app, so the one upload in the UI is the single step no script can do
+for you.
+
+> **Chat, not Cowork.** Claude Desktop reaches local MCP servers from **Chat**
+> conversations only — in **Cowork** mode the Storymapper tools are not
+> available. If Cowork is your default surface, switch to a Chat; when the
+> tools don't show up, this is the first thing to check.
+
+Both commands are idempotent — re-run them after pulling a new Storymapper
+version. `--data-dir=DIR` overrides the data directory (default:
+`<repo>/.storymap-data`).
+
+### Manual setup (other MCP clients, other harnesses)
+
+Any stdio MCP client can run the server with this shape:
+
+```json
+{
+  "mcpServers": {
+    "storymapper": {
+      "command": "node",
+      "args": [
+        "/absolute/path/to/storymapper/server/index.js", "mcp",
+        "--data-dir=/absolute/path/to/storymapper/.storymap-data"
+      ]
+    }
+  }
+}
+```
+
+The skill package (`npm run package-skill` → `dist/storymap-skill.zip`) is
+plain Markdown — `storymap/SKILL.md` plus its `reference/` files. For
+harnesses like Codex, unpack it wherever instructions live and point the
+harness at it, e.g. from an `AGENTS.md`:
+
+```md
+Before planning work on the Storymapper board, read storymap/SKILL.md
+(and the reference/ files it names) and follow that working method.
+```
+
+Point `--data-dir` at the **same** directory the HTTP server uses. Both processes
+can run concurrently against one SQLite file (WAL mode + a busy-timeout);
+the HTTP server relays every MCP write to connected browsers over WebSocket.
+
+### Scripting without MCP: the CLI
+
+Every tool is also a one-shot CLI command running over the same tool core:
+
+```sh
+node server/index.js tool list_projects
+node server/index.js tool ticket_create '{"projectId": "…", "title": "…"}'
+```
+
+The result JSON goes to stdout (exit codes: `0` ok, `1` tool error, `2` unknown
+tool / bad arguments); arguments come from the positional JSON string,
+`--json=<json>`, or piped stdin. This opens the full tool surface to shell
+scripts, CI jobs and harnesses that don't speak MCP.
+
+> Only one `storymapper server` may run per data directory (a PID lock refuses a
+> second; `--force` takes over a stale lock after a crash). The MCP process is
+> exempt and may always share the data dir.
+
+## Security model (single-user, local)
+
+Storymapper is a **local single-user tool** — one human plus their agent on one
+machine. There is deliberately no authentication layer:
+
+- The server binds to `localhost` by default. **Do not expose it on a
+  non-loopback interface** (`--host=0.0.0.0`, a reverse proxy, a Docker port map)
+  without putting your own authentication in front — anyone who can reach the
+  port can read and write every project.
+- CORS is locked to loopback origins: cross-origin browser requests get no
+  `Access-Control-Allow-Origin` and mutating methods are rejected — this stops a
+  random website you visit from driving your local API. WebSocket upgrades are
+  origin-checked the same way.
+- Served HTML carries a Content-Security-Policy; all responses send
+  `X-Content-Type-Options: nosniff`.
+- `X-Actor-*` headers are **attribution, not authentication** — they label who
+  did what in the revision history and are not verified.
+- Verified identity, token-gated remote access and RBAC are a deliberate later
+  stage; the authorization seam (`server/identity.js`) is already in place.
+
+## Testing
+
+```sh
+npm test          # ≈1800 assertions, plain Node scripts, no test framework
+```
+
+The suite is a homegrown runner (`tests/run.js`) over `tests/test-*.js`: pure
+unit tests, storage/mutex/revision tests, in-process and stdio MCP round-trips,
+JSDOM renderer tests, and a real-server end-to-end test. CI runs it on Node 20
+and 22. Tests only ever touch temporary directories — running them never
+touches your data.
+
+## License
+
+Licensed under the **Apache License 2.0** — see [LICENSE](LICENSE) and
+[NOTICE](NOTICE).