Skip to content
Merged
Changes from 1 commit
Commits
Show all changes
27 commits
Select commit Hold shift + click to select a range
5f4687e
docs(plan): Plan v1 milestones, decisions D11-D18, scope and open que…
Oct 30, 2026
77d344c
docs(design): central server, review_by, 13-tool surface, hooks and CLI
Oct 30, 2026
5ca5df6
docs(contract): note the Plan v1 surface changes planned for M1
Oct 30, 2026
489ef7d
docs(contributing): add the Plan v1 engineering rules
Oct 30, 2026
b18efa9
docs(plan): correct the milestone-to-phase mapping
Oct 30, 2026
ff5a734
docs: correct built-state claims and Plan v1 review warnings
Oct 30, 2026
a5051ff
docs: milestone marker and status lines name M1 as current
Oct 30, 2026
1460f8e
docs(plan): milestones replace phases in §3 to §7
Oct 30, 2026
53d54b1
docs(design): central server, milestones and cut surface
Oct 30, 2026
bfa2ef4
docs(contract): milestone references replace phases
Oct 30, 2026
7127de4
docs(readme): operating record category, server required, rename planned
Oct 30, 2026
84f5a21
docs(wiki): milestones, decisions D11 to D18, one-server architecture
Oct 30, 2026
3e0e97b
github: milestone labels m1 to m8 and later; phase labels are history
Oct 30, 2026
c3fb79f
github: roadmap milestones M1 to M8 and Later, with issue mapping
Oct 30, 2026
b74e5e8
github: bootstrap sets a Milestone board field and reads phases from …
Oct 30, 2026
829c1ae
ci: comment names Later for release builds, not phase 10
Oct 30, 2026
27b8e9a
CHANGELOG: link the Plan v1 entry to PR #65
Oct 30, 2026
884f5ef
github: milestone is the built-in board field, not a custom one
Oct 30, 2026
cdc7e50
issue forms: milestone dropdown, decisions D11 to D18, bug environment
Oct 30, 2026
b51f599
ci: docs job named for what it checks
Oct 30, 2026
8ff21ce
docs(wiki): area:server description matches labels.json
Oct 30, 2026
59ba89d
docs: category line is an operating record for coding agents
Oct 30, 2026
af0ab09
docs(readme): serve, mcp and the CLI marked as planned with milestones
Oct 30, 2026
ba67e7d
docs(design): §5 intro points at §5.3 "The server"
Oct 30, 2026
677e12d
docs(wiki): M4, M7 and M8 have no epic yet
Oct 30, 2026
6803709
github: roadmap decision on placing cairn export project
Oct 30, 2026
53d9d6a
Roadmap: M1 children, stale comments for step 9
Oct 30, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
docs(design): central server, milestones and cut surface
The cairn mcp row needs server or CAIRN_SERVER, and every unbuilt command
names its milestone. internal/mcp reaches the server through
internal/client. session-start is planned for M1 in §4.1 and §6.1. The
reviews and notes tables are marked as cut from the v1 agent surface,
and §5.3 describes the server alone.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
  • Loading branch information
Donovan Maidens and claude committed Oct 30, 2026
commit 53d54b166bbf6141fbdd3dfdbfe96fb35b160740
84 changes: 44 additions & 40 deletions docs/DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ Cairn has four jobs:
similar past tasks that apply to it.
4. **Review.** A web page where the operator follows tasks, decides on
findings and ratifies directives. Optional scheduled agents classify
findings and grade finished tasks (PLAN.md phase 8).
findings and grade finished tasks (PLAN.md, Later).

### 1.1 Principles

Expand Down Expand Up @@ -205,6 +205,11 @@ reviews

Events are append-only. There is no update or delete tool.

**Cut from the v1 agent surface.** The `reviews` table is built in the store
today. M1's tool consolidation removes `review_record` from the MCP surface,
and the `review` event carries the verdict, `critical` and `warnings` in
`data` instead (Scope of v1, PLAN.md §3). From M1 no MCP tool writes or reads it.

### 3.4 Learnings and directives

```
Expand Down Expand Up @@ -261,6 +266,11 @@ search_index FTS5 over tasks (title, goal, context, outcome), events (text),
columns. Each source table has insert, update and delete triggers. Update and
delete find a row by `ref`, which scans the index; that is accepted at v1 scale.

**Cut from the v1 agent surface.** The `notes` table is built in the store
today. M1's tool consolidation removes `note_put` and `note_get` from the MCP
surface, and a long brief goes in the task's `context` (Scope of v1, PLAN.md
§3). No v1 tool writes or reads notes.

### 3.6 Projects and settings

```
Expand All @@ -273,7 +283,7 @@ api_keys (server mode) name, hash, scopes, created_at, last_used_at
(surrogate key `id`; this table names no key of its own)
```

The step-review rule is deferred to phase 8 (#41).
The step-review rule is deferred to Later (#41).

### 3.7 The close policy

Expand Down Expand Up @@ -334,8 +344,8 @@ directives that apply, and one line telling the agent to call `task_current`.
When no task is active it says so in one line. It writes nothing.

Plan v1 (decision D15) sets three hooks: `session-start`, `pre-compact` and
`stop`. `session-start` is designed and not yet built; PLAN.md §3 does not yet
place it in a milestone's work row. `pre-compact` and `stop` are planned for M4.
`stop`. `session-start` is planned, M1, and not yet built; issue #16 carries it.
`pre-compact` and `stop` are planned for M4.
`cairn enable --agent` installs all three.

- `pre-compact` (planned, M4) prints the active task, the current step, the
Expand Down Expand Up @@ -379,10 +389,10 @@ server-only adapter.
| `internal/core` | The `Service` interface and its implementation: every rule (close policy, status transitions, operator-only changes) lives here and nowhere else. |
| `internal/store` | SQLite access, migrations, FTS. Typed queries; no SQL in handlers. |
| `internal/api` | HTTP handlers. Thin: decode, call `core`, encode. |
| `internal/client` | A `Service` implemented over HTTP, for the remote backend. |
| `internal/mcp` | MCP tools. Each tool calls `Service`, so it works the same against the local or the remote backend. |
| `internal/client` | A `Service` implemented over HTTP. It is how every client reaches `cairn serve`. |
| `internal/mcp` | MCP tools. Each tool calls `Service` through `internal/client`, which talks to `cairn serve`. It never touches the store. |
| `internal/cli` | Planned, M4. The CLI sub-commands for tasks, steps, events, learnings, directives, `recall`, `search` and `prime`, all with `--json`. Calls `internal/client`, never the store. |
| `internal/identity` | Project resolution from `CAIRN_PROJECT` and `.cairn.toml` (§2.1) is built. Agent and session resolution come in a later phase. |
| `internal/identity` | Project resolution from `CAIRN_PROJECT` and `.cairn.toml` (§2.1) is built. Agent and session resolution come later. |
| `internal/auth` | API keys and scopes (server mode). |
| `internal/ui` | The web pages, embedded in the binary. |
| `internal/conformance` | The conformance suite that checks any `Service`. |
Expand All @@ -396,37 +406,32 @@ any other backend. A behaviour exists when the conformance suite says so.

| Command | Does |
|---|---|
| `cairn init` | Writes `.cairn.toml` in the current project and registers the project. |
| `cairn mcp` | The MCP stdio server. Local backend unless `server` or `CAIRN_SERVER` is set. |
| `cairn serve` | HTTP API and web UI. Flags for address, TLS and the database path. |
| `cairn hook <event>` | Output for client hooks (`session-start`). |
| `cairn status` | The active task and the backend in use, for a terminal. |
| `cairn export <task>` | A task as Markdown. |
| `cairn key add/list/revoke` | API keys for server mode. |
| `cairn init` | Writes `.cairn.toml` in the current project and registers the project. Planned, M1. |
| `cairn mcp` | The MCP stdio server. Requires `server` or `CAIRN_SERVER` and refuses to start without one (M1, D11). |
| `cairn serve` | HTTP API and web UI. Flags for address, TLS and the database path. Planned, M2; the web UI is M3. |
| `cairn hook <event>` | Output for client hooks. `session-start` is planned, M1; `pre-compact` and `stop` are planned, M4. |
| `cairn status` | The active task and the server in use, for a terminal. Planned, M1. |
| `cairn export <task>` | A task as Markdown (`export task`, planned, M1). `export project` is in Scope of v1 and is not yet placed in a milestone. |
| `cairn key add/list/revoke` | API keys for server mode. Planned, M2. |
| `cairn enable --agent <name>` | Planned, M4. Installs a client's hooks (`session-start`, `pre-compact`, `stop`) and its registration. `claude-code` first; `opencode` and `pi` are written experimental. |
| `cairn backup <path>` | Planned, M2. A SQLite online backup of the database to a path. |
| `cairn restore <path>` | Planned, M2. Restores a backup, behind an interactive confirmation. |
| `cairn import bishop-memory` | One-time migration from a bishop-memory database (PLAN.md §5). |
| `cairn doctor` | Checks the binary, the config, the database or server, and the project file. |

### 5.3 Local and remote backends

- **Local (designed under D2; cut by D11 before it was built):** the design had
`cairn mcp` open `~/.local/share/cairn/cairn.db` (or `CAIRN_DB`) in WAL mode
with a busy timeout, so several MCP processes on one machine would share it.
Task-id allocation is one transaction in the store, which is built. No daemon
would be needed, and `cairn serve` on the same database would show the web UI.
D11 removes this path before it exists: `cairn mcp` refuses to start without a
`server` (M1), and this backend is not a client option. The store stays inside
`cairn serve`.
- **Remote:** `cairn mcp` sends each call to `cairn serve` with the API key.
Used for a home server, a team, or several machines, and the only client
backend from M1.

Under D2 (designed, never built), switching would have been one line in
`.cairn.toml` or one environment variable. D11 removes the choice. A project's
data does not move automatically; `cairn serve` can be pointed at
the local database file to make it the server's.
| `cairn import bishop-memory` | One-time migration from a bishop-memory database (PLAN.md §5). Planned, M6. |
| `cairn doctor` | Checks the binary, the config, the database or server, and the project file. Planned, M1; `--agent` is planned, M4. |

### 5.3 The server

Clients open no database. `cairn mcp` and the CLI send each call to
`cairn serve` over HTTP with the API key (D11). `cairn mcp` refuses to start
without a `server` (M1). The store stays inside `cairn serve`, and the web UI
is served by the same process.

D2 designed a local backend, in which `cairn mcp` would open a SQLite file on
the machine. D11 cut it before it was built, so there is no choice of backend
and no switch in `.cairn.toml`.

A project's data does not move automatically. `cairn serve` can be pointed at
an existing SQLite file to make it the server's own database.

## 6. Clients

Expand All @@ -443,9 +448,9 @@ plugins/claude-code/
bin/cairn-launch finds the cairn binary; if missing, exits
with the one-line install command
hooks/hooks.json SessionStart → cairn hook session-start
(designed, not yet built; milestone not set in
PLAN §3); PreCompact and Stop → cairn hook
pre-compact and stop (planned, M4, D15)
(planned, M1, not yet built; issue #16);
PreCompact and Stop → cairn hook pre-compact
and stop (planned, M4, D15)
skills/cairn/SKILL.md how to work with Cairn: the task loop below
commands/init.md /cairn:init → cairn init
commands/status.md /cairn:status
Expand Down Expand Up @@ -494,8 +499,7 @@ repository. PLAN.md lists what Cairn must provide for it.

## 7. Review loop (optional, later)

Written fresh after the core is in use, guided by bishop-memory (PLAN.md phase
8):
Written fresh after the core is in use, guided by bishop-memory (PLAN.md, Later):

- **Classify**: a scheduled agent assigns a category and a confidence to each
new finding.
Expand Down