# 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).