From 5fd648b538684d4f925add98ab8c691f32176fac Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 3 Sep 2026 16:32:49 +0000 Subject: [PATCH 1/3] Move planning docs into planning/, add decisions and changelog trackers MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rename FOLLOW_WORK.md to planning/backlog.md and drop the AgentHarness vs. Agent entry, which the runtime never actually chose between on purpose. Add planning/decisions.md for calls a branch already made and planning/changelog.md for what shipped, so the three spans of forward-looking work — open, closed, released — each have one home outside docs/, which stays for design contracts only. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_018aZeuMcM9oDrExXHF7dAVp --- CLAUDE.md | 4 +- demos/README.md | 2 +- docs/exchange.md | 2 +- docs/workspace.md | 10 +-- packages/ambion/src/session.ts | 2 +- FOLLOW_WORK.md => planning/backlog.md | 112 ++++++++------------------ planning/changelog.md | 19 +++++ planning/decisions.md | 27 +++++++ 8 files changed, 90 insertions(+), 88 deletions(-) rename FOLLOW_WORK.md => planning/backlog.md (69%) create mode 100644 planning/changelog.md create mode 100644 planning/decisions.md diff --git a/CLAUDE.md b/CLAUDE.md index d903d4f..421771a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -24,7 +24,7 @@ pnpm workspace, Node >= 22.19, ESM only, TypeScript. | `docs/toolchain.md` | Build, CI, release — read before changing `.github/`, `scripts/`, root configs | | `examples/site` | Runnable example | | `demos/` | One dated report per merged change — regenerate on the branch, then leave it | -| `FOLLOW_WORK.md` | Work a branch decided not to do, and why it is worth doing | +| `planning/` | Forward-looking tracking: `backlog.md`, `decisions.md`, `changelog.md` | ## Thesis @@ -49,7 +49,7 @@ same kind, and every one enters as a message. Keep both framings in `README.md` and `docs/` document what is implemented. Do not write about unbuilt concepts (channels, deployment targets) there; deferred work goes in -`FOLLOW_WORK.md`. +`planning/backlog.md`. ## Commands diff --git a/demos/README.md b/demos/README.md index dcbd540..0506bdb 100644 --- a/demos/README.md +++ b/demos/README.md @@ -126,7 +126,7 @@ is imperative. The second run read every record as a week stale, because the runtime stamps the real date into every context and the scenario is set on 25 August; the goal now names the site's calendar. One artefact remains: a `2>/dev/null` created `dev/null` on the drive, because just-bash treats that -path as a plain file. `FOLLOW_WORK.md` holds it. +path as a plain file. `planning/backlog.md` holds it. **One Assistant, Three Readers.** The run that moved the assistant from the person to the room. `startSession` now takes `assistant` as a required diff --git a/docs/exchange.md b/docs/exchange.md index bf596e6..bb6a99f 100644 --- a/docs/exchange.md +++ b/docs/exchange.md @@ -135,7 +135,7 @@ again, and that question opens a new exchange. A closed exchange is an owner and a range, so it is derivable from the record. Nothing derives it today; a host that wants a history of exchanges records the `exchange_closed` events as they arrive. -[`FOLLOW_WORK.md`](../FOLLOW_WORK.md) holds the work. +[`planning/backlog.md`](../planning/backlog.md) holds the work. --- diff --git a/docs/workspace.md b/docs/workspace.md index 58d42b8..0bc879f 100644 --- a/docs/workspace.md +++ b/docs/workspace.md @@ -48,8 +48,8 @@ credential. A workspace provisions one for it, inside `connect` (§7). leaves the workspace — an external API, a secret, another service — needs a separate mechanism: a credentials provider paired with a sidecar proxy, injecting a credential or issuing a short-lived token per call. -[`FOLLOW_WORK.md`](../FOLLOW_WORK.md) tracks that boundary. This document -leaves it out. +[`planning/backlog.md`](../planning/backlog.md) tracks that boundary. This +document leaves it out. **A workspace is a container of persistent entities, each of a different kind.** The filesystem and shell (§8) are one kind. Reminders and tasks @@ -296,8 +296,6 @@ engine with its own lanes, compaction, and navigation. Ambion's runtime imports Pi's lower-level `Agent` class (`activation.ts`, `session.ts`), and `AgentHarness` appears in no file under `packages/ambion/src`. `ToolContext` is addressed to `defineTool`'s own shape, at the layer Ambion builds on. -`FOLLOW_WORK.md` holds the wider question of which class is Ambion's -foundation. --- @@ -563,8 +561,8 @@ empty `/dev/null` into a fresh `InMemoryFs` and treats it as a file: a command that redirects into it appends to it (probed: `echo hi >/dev/null` leaves three bytes there). `ReadWriteFs` starts without `/dev`, so the same redirect creates `dev/null` under the root, on disk. A directory backend -therefore holds whatever agents discarded, and [`FOLLOW_WORK.md`](../FOLLOW_WORK.md) -tracks it. +therefore holds whatever agents discarded, and +[`planning/backlog.md`](../planning/backlog.md) tracks it. **`env.cwd` is the agent's home for the life of the `env`, and nothing tracks it further.** Pi's `FileSystem` declares `cwd` as a plain property, diff --git a/packages/ambion/src/session.ts b/packages/ambion/src/session.ts index 307c3f2..5456c9d 100644 --- a/packages/ambion/src/session.ts +++ b/packages/ambion/src/session.ts @@ -626,7 +626,7 @@ class SessionImpl implements Session { // The assistant's hands are the runtime's, and it holds them only for the activation // it was woken for. Nothing wakes the assistant today but the close of an // exchange; when something else does — a wider attention, per - // FOLLOW_WORK.md — it must arrive with empty hands until somebody adds a + // planning/backlog.md — it must arrive with empty hands until somebody adds a // `say` here on purpose. assistant.md §12 makes that a deliberate decision. if (this.assistant.is(seat.def.name)) { const closing = this.assistant.closing(); diff --git a/FOLLOW_WORK.md b/planning/backlog.md similarity index 69% rename from FOLLOW_WORK.md rename to planning/backlog.md index 5c0eb1c..621a48a 100644 --- a/FOLLOW_WORK.md +++ b/planning/backlog.md @@ -1,9 +1,10 @@ -# Follow-up work +# Backlog -Work this branch decided not to do, and why it is worth doing. Each item says +Work a branch decided not to do, and why it is worth doing. Each item says what it is, what it costs, and where the reasoning already lives. The design -contracts in [`docs/`](docs) hold the open questions about a design; this file -holds the work. +contracts in [`docs/`](../docs) hold the open questions about a design; this +file holds the work. [`decisions.md`](decisions.md) holds the calls a branch +already made; [`changelog.md`](changelog.md) holds what shipped. ## Steering an exchange from what a person holds @@ -15,7 +16,7 @@ reads what a person holds and what a message is, so the room can run it as a check, and it costs no activation. **Why.** The preferences are in one place already: the `preferences` field on -`defineHuman` ([`docs/assistant.md`](docs/assistant.md) §2), which today +`defineHuman` ([`docs/assistant.md`](../docs/assistant.md) §2), which today reaches the assistant alone, at the close. A person who has said what they act on has said something the room could use while it is still deciding what to say. It is also the cheapest of the three rungs in §12: a check costs @@ -41,9 +42,9 @@ nothing, and rung 3 pays for an activation. (`SUMMARY_PARAGRAPH`) is the precedent. **Where.** `dispatch` and `handsFor` in -[`session.ts`](packages/ambion/src/session.ts), `wakes` in -[`seat.ts`](packages/ambion/src/seat.ts), the assistant's paragraphs in -[`render.ts`](packages/ambion/src/render.ts). +[`session.ts`](../packages/ambion/src/session.ts), `wakes` in +[`seat.ts`](../packages/ambion/src/seat.ts), the assistant's paragraphs in +[`render.ts`](../packages/ambion/src/render.ts). ## Reseating: attention that a running room can change @@ -52,12 +53,12 @@ moves. `session.reseat(name, attention)` would let a host widen or narrow one while the room runs. **Why.** Attention is now the whole of what a seating decides -([`docs/agent.md`](docs/agent.md) rule 6): one widening scale, and one +([`docs/agent.md`](../docs/agent.md) rule 6): one widening scale, and one comparison against a message's reach decides who wakes. Everything that reads it already reads it per activation, so a seat that changes point costs nothing to route. -It is also what [`docs/assistant.md`](docs/assistant.md) §12's rung 3 wants. The assistant is +It is also what [`docs/assistant.md`](../docs/assistant.md) §12's rung 3 wants. The assistant is a seat at `none`; letting it take part in an exchange is a wider attention and a `say` in its hands. With reseating that is a host's decision — _this room lets the assistant speak_ — rather than a code change in the runtime. @@ -82,9 +83,9 @@ lets the assistant speak_ — rather than a code change in the runtime. with the paragraph that says when waking the assistant is worth the money. **Where.** `wakes` in -[`packages/ambion/src/seat.ts`](packages/ambion/src/seat.ts), `Attention` in -[`types.ts`](packages/ambion/src/types.ts), `seated` in -[`define.ts`](packages/ambion/src/define.ts). +[`packages/ambion/src/seat.ts`](../packages/ambion/src/seat.ts), `Attention` in +[`types.ts`](../packages/ambion/src/types.ts), `seated` in +[`define.ts`](../packages/ambion/src/define.ts). ## Waking the assistant costs money, and nothing says when it is worth it @@ -108,7 +109,7 @@ assistant speaks. summary from a failed activation who asks again gets one message covering both exchanges. Nothing pins that behaviour; the tests cover the failure and the -retry separately. See [`docs/assistant.md`](docs/assistant.md) §5. +retry separately. See [`docs/assistant.md`](../docs/assistant.md) §5. ## Exchanges are run state @@ -116,19 +117,19 @@ retry separately. See [`docs/assistant.md`](docs/assistant.md) §5. right for a room mid-question, and a limit for anything that wants to work over past exchanges. A closed exchange is an owner and a range, so it is derivable from the record; nothing derives it today. See -[`docs/exchange.md`](docs/exchange.md) §5. +[`docs/exchange.md`](../docs/exchange.md) §5. ## A second non-seat writer The room owes summaries through a small scheduler: `owe`, `dueAtQuiescence`, `dueAfterDraft` and `activationEnded`, held by `Assistant`. If a room-level compactor ever arrives -([`docs/assistant.md`](docs/assistant.md) §16 forbids it by name today), it wants the +([`docs/assistant.md`](../docs/assistant.md) §16 forbids it by name today), it wants the same scheduler. Two writers is the point at which it should become its own thing rather than three fields on the session. ## A credentials boundary for tool calls leaving the workspace -**What.** [`docs/workspace.md`](docs/workspace.md) §1 draws the workspace's +**What.** [`docs/workspace.md`](../docs/workspace.md) §1 draws the workspace's boundary at the sandbox: what a tool can do inside it, through the runtime's own construction of each `Workspace` value. A tool call that reaches outside — an external API, a secret, another service — needs a second @@ -141,14 +142,14 @@ beyond it. **Why.** Today a tool's `execute` function reaches whatever a host wires it to (`docs/agent.md` §3), with no distinction between a call that stays local and one that leaves. A workspace's filesystem boundary -([`docs/workspace.md`](docs/workspace.md) §1, §8) has no answer for a tool +([`docs/workspace.md`](../docs/workspace.md) §1, §8) has no answer for a tool that calls out to a real API, and a real deployment needs one before it hands an agent anything with network access. **What it needs deciding.** - Whether this is a workspace concern (a third kind of persistent entity, - under [`docs/workspace.md`](docs/workspace.md) §1's model) or a separate + under [`docs/workspace.md`](../docs/workspace.md) §1's model) or a separate primitive entirely. - What a sidecar proxy actually mediates: a network path every outbound call is forced through, or a narrower set of tools the workspace marks @@ -156,22 +157,22 @@ hands an agent anything with network access. - Whether a token is minted per call, per activation, or per agent, and what a "short-lived" window actually is. - How this interacts with `ToolContext` - ([`docs/workspace.md`](docs/workspace.md) §4) and `defineTool`'s own + ([`docs/workspace.md`](../docs/workspace.md) §4) and `defineTool`'s own `execute` shape (`docs/agent.md` §3), neither of which takes any notion of a credential today. -**Where.** [`docs/workspace.md`](docs/workspace.md) §1 names the boundary +**Where.** [`docs/workspace.md`](../docs/workspace.md) §1 names the boundary and scopes it out to this entry; `ToolContext` in -[`docs/workspace.md`](docs/workspace.md) §4 is the most natural place for +[`docs/workspace.md`](../docs/workspace.md) §4 is the most natural place for a credential to reach a tool call now, alongside `defineTool`'s `execute` -in [`docs/agent.md`](docs/agent.md) §3. +in [`docs/agent.md`](../docs/agent.md) §3. ## `/dev/null` on the just-bash backends is a file **What.** just-bash treats `/dev/null` as a plain file. A command that redirects into it appends to it, and on `directoryBackend` the redirect creates `dev/null` under the root, on disk -([`docs/workspace.md`](docs/workspace.md) §8). The first live run of the +([`docs/workspace.md`](../docs/workspace.md) §8). The first live run of the example left one there: a product wrote `cat … 2>/dev/null`, and the drive gained a file. @@ -187,17 +188,17 @@ the `bash` tool's own description promises a Unix shell. - Whether `connect` should seed `/dev` into a `ReadWriteFs` the way just-bash seeds it into an `InMemoryFs`, so the two backends at least agree. -**Where.** `connectOver` in [`just-bash.ts`](packages/ambion/src/just-bash.ts). +**Where.** `connectOver` in [`just-bash.ts`](../packages/ambion/src/just-bash.ts). ## A backend on a real machine **What.** A `WorkspaceBackend` whose `connect` creates a real OS user when one is absent and returns an `env` whose `exec` runs as that user through a -real user switch. [`docs/workspace.md`](docs/workspace.md) §10 sketches it +real user switch. [`docs/workspace.md`](../docs/workspace.md) §10 sketches it and commits to nothing. **Why.** The just-bash backend's boundary is nominal -([`docs/workspace.md`](docs/workspace.md) §8): one instance, one identity, +([`docs/workspace.md`](../docs/workspace.md) §8): one instance, one identity, and nothing stops one agent's `bash` call from reading another's home. A real user turns that into isolation the operating system enforces, the guarantee a multi-user Linux box gives. The shape is already fixed: two @@ -208,58 +209,15 @@ abort signal because `useradd` and a process spawn are real waits. - How an OS user is named from an agent's `name`, and what happens when two workspaces on one host provision the same name - ([`docs/workspace.md`](docs/workspace.md) §7 accepts the collision and + ([`docs/workspace.md`](../docs/workspace.md) §7 accepts the collision and checks nothing). - What `destroy` removes: the users, their homes, or both. - Whether Pi's `NodeExecutionEnv` is the `env`, with a `sudo -u` prefix on every command, or whether the backend spawns as the user itself. **Where.** `WorkspaceBackend` in -[`types.ts`](packages/ambion/src/types.ts); `directoryBackend` in -[`just-bash.ts`](packages/ambion/src/just-bash.ts) is the shape to copy. - -## Whether Agent or AgentHarness is Ambion's foundation - -**What.** Ambion's runtime imports Pi's lower-level `Agent` class -(`activation.ts`, `seat.ts`), not `AgentHarness` -(`@earendil-works/pi-agent-core`'s `harness/agent-harness.ts`) — a -heavier engine Pi ships beside it, with its own session tree, lanes, -compaction, and tree navigation. Nobody chose `Agent` over `AgentHarness` -on purpose; it is what the runtime already used before this question was -ever asked. - -**Why.** [`docs/workspace.md`](docs/workspace.md) §6 reuses part of what -the harness package exports — `Workspace` holds a plain `ExecutionEnv` -as its own `env` property — while keeping `Workspace` itself and -`ToolContext` (§4) outside anything `AgentHarness` provides. That split -holds today because `Agent` and `AgentHarness` overlap only at the edges. -`AgentHarness` also ships its own tool-context mechanism, -`AgentHarnessToolContextSource`, resolved once per turn and handed to an -`AgentHarnessTool`'s `execute`; `ToolContext` covers the same ground at a -narrower scope, resolved once per tool call against `defineTool`'s own -shape. A workspace is the first concept this project has built that sits -this close to ground `AgentHarness` already covers. A concept that sits -closer still is a real possibility once reminders and tasks -(`docs/workspace.md` §11) or anything with its own turn-scoped state -joins it. - -**What it needs deciding.** - -- Whether `Agent` stays the right foundation once a second and a third - workspace-adjacent concept land, or whether `AgentHarness` already - solves problems this project would otherwise rebuild piece by piece. -- What adopting `AgentHarness` would cost: its own session model - (`SessionTree`, lanes), compaction, and tree navigation, none of which - [`agent.md`](docs/agent.md) or `session.ts` has a use for today. -- Whether `ToolContext`'s own resolution (`docs/workspace.md` §4) should - become Ambion's own provider for `AgentHarnessOptions.toolContext`, if - `Agent` is ever replaced by `AgentHarness`. - -**Where.** `packages/ambion/src/activation.ts` and `seat.ts` hold today's -`Agent` imports; [`docs/workspace.md`](docs/workspace.md) §4 and §6 are -where `ExecutionEnv` was adopted without adopting `AgentHarness`; Pi's -own `harness/agent-harness.ts` and `harness/types.ts` -(`@earendil-works/pi-agent-core`) define what `AgentHarness` actually is. +[`types.ts`](../packages/ambion/src/types.ts); `directoryBackend` in +[`just-bash.ts`](../packages/ambion/src/just-bash.ts) is the shape to copy. ## Roles as collaboration patterns @@ -282,10 +240,10 @@ collaboration patterns people and agents work in. differently in two rooms, and a role is probably the same kind of thing. - What a role changes: the seat's instructions, its attention, or the order the room wakes seats in. Only the first keeps the routing rule as - one comparison ([`docs/agent.md`](docs/agent.md) rule 6). + one comparison ([`docs/agent.md`](../docs/agent.md) rule 6). - Who assigns roles. The assistant never runs the room - ([`docs/assistant.md`](docs/assistant.md) §2), so assigning roles is a + ([`docs/assistant.md`](../docs/assistant.md) §2), so assigning roles is a different seat's work, or the host's. -**Where.** `seated` in [`define.ts`](packages/ambion/src/define.ts), the -roster in [`render.ts`](packages/ambion/src/render.ts). +**Where.** `seated` in [`define.ts`](../packages/ambion/src/define.ts), the +roster in [`render.ts`](../packages/ambion/src/render.ts). diff --git a/planning/changelog.md b/planning/changelog.md new file mode 100644 index 0000000..0d41956 --- /dev/null +++ b/planning/changelog.md @@ -0,0 +1,19 @@ +# Changelog + +A log of what shipped, one line per merged pull request. Newest first. +[`demos/`](../demos) holds the run report for a change that warranted one; +this file lists every merge, with or without a report. + +Add a row when a pull request merges into the default branch. Nobody edits a +row after it lands; a change that undoes an earlier one gets its own new +row. + +| Date | Change | PR | +| ---------- | ---------------------------------------------------------------------- | --------------------------------------------------------- | +| 2026-09-02 | Seat one assistant per room at `startSession`, and read preferences off the person | [#39](https://github.com/ambionframework/ambion/pull/39) | +| 2026-09-02 | Rewrite the README around agent-to-agent collaboration | [#38](https://github.com/ambionframework/ambion/pull/38) | +| 2026-09-01 | Implement the workspace: the boundary an agent's tools reach into | [#37](https://github.com/ambionframework/ambion/pull/37) | +| 2026-08-28 | Add presence: visits, rosters, and multi-person sessions | [#13](https://github.com/ambionframework/ambion/pull/13) | +| 2026-08-27 | Add `CLAUDE.md` guidance document for the repository | [#12](https://github.com/ambionframework/ambion/pull/12) | +| 2026-08-26 | Enforce a cognitive complexity budget in CI | [#11](https://github.com/ambionframework/ambion/pull/11) | +| 2026-08-26 | Add the agent core: four primitives on the Pi SDK | [#9](https://github.com/ambionframework/ambion/pull/9) | diff --git a/planning/decisions.md b/planning/decisions.md new file mode 100644 index 0000000..4283ce1 --- /dev/null +++ b/planning/decisions.md @@ -0,0 +1,27 @@ +# Decisions + +A log of calls a branch already made, and why. [`backlog.md`](backlog.md) +holds work still open; this file holds work that is closed. An open question +moves here once a branch answers it, with the answer and the alternative it +rejected. + +Each entry names the date, the decision, the reason, and what it rejected. +Nobody edits an entry after the branch that made it merges. A later decision +that reverses an earlier one adds a new entry; it does not rewrite the old +one. + +## 2026-09-03 — Track forward-looking work under `planning/` + +**Decision.** Move `FOLLOW_WORK.md` into `planning/backlog.md`, and add +`planning/decisions.md` and `planning/changelog.md` beside it. + +**Why.** The backlog, the decisions a branch has already made, and the +record of what shipped are three different spans of time — open, closed, and +released — and each had no fixed home. One folder gives each span its own +file and keeps `docs/` for design contracts only, per +[`CLAUDE.md`](../CLAUDE.md). + +**Rejected.** Keeping `FOLLOW_WORK.md` at the repository root and adding the +other two files beside it. Rejected because a root file competes with +`README.md` and `CLAUDE.md` for a reader's first look, and none of the three +is a design contract or a build instruction. From 39b0c3e756132e363d772cb62b0b387de6177c8c Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 3 Sep 2026 16:40:43 +0000 Subject: [PATCH 2/3] Rewrite changelog as themed entries grouped by release A row per merged PR read like a commit log, not a changelog: it named the mechanism, not what changed for somebody building on Ambion. Group entries by theme under Added/Changed/Fixed instead, and start with an Unreleased section since nothing has tagged a release yet. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_018aZeuMcM9oDrExXHF7dAVp --- planning/changelog.md | 38 +++++++++++++++++++++++--------------- 1 file changed, 23 insertions(+), 15 deletions(-) diff --git a/planning/changelog.md b/planning/changelog.md index 0d41956..9aca226 100644 --- a/planning/changelog.md +++ b/planning/changelog.md @@ -1,19 +1,27 @@ # Changelog -A log of what shipped, one line per merged pull request. Newest first. -[`demos/`](../demos) holds the run report for a change that warranted one; -this file lists every merge, with or without a report. +Changes to Ambion, grouped by release. Newest first. **Unreleased** holds +every change since the last release; a release renames that section and +opens a new **Unreleased** above it. [`demos/`](../demos) holds a run +report for a change that warranted one. -Add a row when a pull request merges into the default branch. Nobody edits a -row after it lands; a change that undoes an earlier one gets its own new -row. +Write an entry as a theme, not a merged pull request. State what changed +for somebody building on Ambion, not the mechanism behind it. Group entries +under **Added**, **Changed**, or **Fixed**, and drop a heading with nothing +under it. An internal change — a CI rule, a refactor, a doc rewrite — gets +no entry unless it changes what a person building on Ambion sees. -| Date | Change | PR | -| ---------- | ---------------------------------------------------------------------- | --------------------------------------------------------- | -| 2026-09-02 | Seat one assistant per room at `startSession`, and read preferences off the person | [#39](https://github.com/ambionframework/ambion/pull/39) | -| 2026-09-02 | Rewrite the README around agent-to-agent collaboration | [#38](https://github.com/ambionframework/ambion/pull/38) | -| 2026-09-01 | Implement the workspace: the boundary an agent's tools reach into | [#37](https://github.com/ambionframework/ambion/pull/37) | -| 2026-08-28 | Add presence: visits, rosters, and multi-person sessions | [#13](https://github.com/ambionframework/ambion/pull/13) | -| 2026-08-27 | Add `CLAUDE.md` guidance document for the repository | [#12](https://github.com/ambionframework/ambion/pull/12) | -| 2026-08-26 | Enforce a cognitive complexity budget in CI | [#11](https://github.com/ambionframework/ambion/pull/11) | -| 2026-08-26 | Add the agent core: four primitives on the Pi SDK | [#9](https://github.com/ambionframework/ambion/pull/9) | +## Unreleased + +### Added + +- Five primitives: `defineAgent`, `defineHuman`, `defineTool`, + `defineWorkspace`, `startSession`. Pi owns the model loop, tools and + transcript; just-bash owns the filesystem and shell behind a workspace. +- Presence. A person can join or leave a room, and every seat's context + shows who is in it. +- A workspace per agent: a shared filesystem and shell, in memory or over a + real directory. +- An assistant, seated automatically at `startSession`. It reads a + person's preferences and writes the one message they read when the room + goes quiet. From 6124574cc9027c55e8cb7d5d617180f8ec5dc229 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 3 Sep 2026 16:43:21 +0000 Subject: [PATCH 3/3] Drop planning/decisions.md, stick to backlog and changelog Two trackers under planning/ for now: open work and what shipped. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_018aZeuMcM9oDrExXHF7dAVp --- CLAUDE.md | 2 +- planning/backlog.md | 3 +-- planning/decisions.md | 27 --------------------------- 3 files changed, 2 insertions(+), 30 deletions(-) delete mode 100644 planning/decisions.md diff --git a/CLAUDE.md b/CLAUDE.md index 421771a..61b556d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -24,7 +24,7 @@ pnpm workspace, Node >= 22.19, ESM only, TypeScript. | `docs/toolchain.md` | Build, CI, release — read before changing `.github/`, `scripts/`, root configs | | `examples/site` | Runnable example | | `demos/` | One dated report per merged change — regenerate on the branch, then leave it | -| `planning/` | Forward-looking tracking: `backlog.md`, `decisions.md`, `changelog.md` | +| `planning/` | Forward-looking tracking: `backlog.md`, `changelog.md` | ## Thesis diff --git a/planning/backlog.md b/planning/backlog.md index 621a48a..614d26f 100644 --- a/planning/backlog.md +++ b/planning/backlog.md @@ -3,8 +3,7 @@ Work a branch decided not to do, and why it is worth doing. Each item says what it is, what it costs, and where the reasoning already lives. The design contracts in [`docs/`](../docs) hold the open questions about a design; this -file holds the work. [`decisions.md`](decisions.md) holds the calls a branch -already made; [`changelog.md`](changelog.md) holds what shipped. +file holds the work. [`changelog.md`](changelog.md) holds what shipped. ## Steering an exchange from what a person holds diff --git a/planning/decisions.md b/planning/decisions.md deleted file mode 100644 index 4283ce1..0000000 --- a/planning/decisions.md +++ /dev/null @@ -1,27 +0,0 @@ -# Decisions - -A log of calls a branch already made, and why. [`backlog.md`](backlog.md) -holds work still open; this file holds work that is closed. An open question -moves here once a branch answers it, with the answer and the alternative it -rejected. - -Each entry names the date, the decision, the reason, and what it rejected. -Nobody edits an entry after the branch that made it merges. A later decision -that reverses an earlier one adds a new entry; it does not rewrite the old -one. - -## 2026-09-03 — Track forward-looking work under `planning/` - -**Decision.** Move `FOLLOW_WORK.md` into `planning/backlog.md`, and add -`planning/decisions.md` and `planning/changelog.md` beside it. - -**Why.** The backlog, the decisions a branch has already made, and the -record of what shipped are three different spans of time — open, closed, and -released — and each had no fixed home. One folder gives each span its own -file and keeps `docs/` for design contracts only, per -[`CLAUDE.md`](../CLAUDE.md). - -**Rejected.** Keeping `FOLLOW_WORK.md` at the repository root and adding the -other two files beside it. Rejected because a root file competes with -`README.md` and `CLAUDE.md` for a reader's first look, and none of the three -is a design contract or a build instruction.