From d301cba362e6139f9dc074f690a5120229d6242c Mon Sep 17 00:00:00 2001 From: Don Garrett Date: Tue, 6 Oct 2026 00:21:34 +0000 Subject: [PATCH 1/2] Architecture: the general scope and the new-project sequence (for M2.5) - L1: `general`, the scope of conversation not (yet) about a project: an item per thread, no repository, build VM or execution; closes after a day idle, a later reply starting a linked item. - L5: every conversation is an item from its first message; chit-chat is answered, only work gets a Gitea issue. - D1: a conversation's record issue is opened once it's work on a project. The new-project sequence: proposal, a provisioning checklist in Matrix, verified when the operator says done, a tracking issue carrying the distilled decisions (not the raw chat), then the architecture PRs. - Q: a scratch build VM for general replaces the answered question about records for pure conversations. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01PPQ14L3LikyefCMFBqEbKE --- docs/Architecture.md | 57 +++++++++++++++++++++++++++++----------- docs/Development-Plan.md | 7 +++-- 2 files changed, 47 insertions(+), 17 deletions(-) diff --git a/docs/Architecture.md b/docs/Architecture.md index cf89b26..075d987 100644 --- a/docs/Architecture.md +++ b/docs/Architecture.md @@ -138,8 +138,15 @@ Everything in this part is used by every agent. |---|---|---|---| | **Duty** | A standing responsibility that produces work items | Watching for issues assigned to it (D1) | Scheduled checks, log monitoring, alert intake | | **Work item** | One effort, opened and eventually closed | A bug, feature or new project | Diagnosing a failure; making one change | -| **Scope** | What a work item operates on; context that outlives it | A repository | A site and service | +| **Scope** | What a work item operates on; context that outlives it | A repository, or `general` | A site and service, or `general` | +- **`general` is the scope of conversation not (yet) about a project:** feasibility, + hardware, how something works. Each conversation is its own item, one per thread + (L5), so unrelated chats stay out of each other's context. It has no repository, + no build VM and no execution, so its context is the conversation and agent memory + (L6). It closes after a day idle, with a summary in its log; a later reply in its + thread starts a new item linked to it. If it turns into work, the work moves to a + project's item (D1). - **Sources of work items:** duties, the operator (always), and other agents. A request from another agent is an issue assigned to the receiving agent, and carries no authority of its own: the receiver applies its own rules. @@ -277,9 +284,10 @@ thread is how the agent knows which item a message is about. ambiguous, so the agent asks which item rather than guessing. Any other message starts a new conversation, and the agent offers to continue an existing item if it clearly belongs there. -- **Any conversation about work is a work item from its first message,** however - vague ("I'm having trouble with X…"). It may end with a project, an issue, or - just an answer. +- **Every conversation is a work item from its first message,** in the `general` + scope until it is about a project (L1), however vague ("I'm having trouble with + X…"). Chit-chat is simply answered in its thread; only work gets a Gitea issue + (D1). It may end with a project, an issue, or just an answer. **What the operator says** is plain language, plus a small command vocabulary that works in every state: `status`, `stop`, `abandon`, `approve [rev-N]`, `go`, and @@ -562,9 +570,10 @@ Work arrives as Gitea issues or conversation, and leaves as reviewed PRs. item's record. Only issues filed or assigned by allowlisted operators count (L11). - **Unassigned issues are backlog,** never work, though the agent will discuss them. - **Open Gitea dependencies make an issue blocked** (L1). -- **Work that starts in conversation gets a record:** the agent opens an issue, - assigned to itself, that carries the work item's ID from the moment it is - created. Intake ignores any issue carrying an ID, so a record is never taken for +- **Work that starts in conversation gets a record** once it is work on a project, + not at its first message: the transcript already keeps the conversation. The + agent opens an issue, assigned to itself, that carries the work item's ID from + the moment it is created. Intake ignores any issue carrying an ID, so a record is never taken for new work, even before the agent has stored the link. This is the only time the agent assigns itself. @@ -588,12 +597,30 @@ mean, how it fits, its first step. Labels steer what happens next: - **A bug:** reproduce (ideally as a failing test), fix, verify, PR. - **A feature:** agree the design in conversation, write a build plan if it's longer than about one PR (D2), work through it as milestones (D4). -- **A new project:** a conversation, however vague. If it becomes a project, the - agent lists what it needs provisioned (a repository with protection and its own - write access, a build VM, and its project entry, D8), which the operator - provides (later `nisse-ops`, O6). It then opens a tracking issue ("implement the - build plan") as the record, and the architecture lands in one or more PRs, then - the plan's milestones. +- **A new project** starts as a `general` conversation, however vague. Nothing + needs Gitea before the repository exists: drafts live in the conversation (a + Markdown file in the thread if long). + 1. **The proposal:** a name, what it's for, and the decisions provisioning + depends on (toolchain, so the build VM template; services; secrets; egress). + The operator agrees as to a restatement. + 2. **A provisioning checklist** in the thread: a repository with protection, the + agent as a collaborator with write access, a build VM, and the project entry + (D8), given as configuration to add. The operator provides them (later + `nisse-ops`, O6). + 3. **Verified, not assumed:** when the operator says done, the agent checks the + repository, a push to a branch, that protection refuses it on the default + branch (D4), and the build VM. + 4. **The record:** a tracking issue ("implement the build plan") whose body is + what was decided, distilled, linking the conversation's item. The raw + conversation isn't carried into the project's context: it holds ideas that + were dropped, and the documents are what gets reviewed and what later work + reads. + 5. **The architecture lands in one or more PRs,** treated as `design`, then the + plan's milestones. + + An experiment before the project exists (does a library parse this format?) has + nowhere to run: the agent says so, and suggests making it a project or using an + existing project's build VM. - **Progress** goes on the record issue: facts posted by the harness, prose by the agent when there's something to say. - **Finishing:** the last PR closes the issue on merge ("Closes #N"; earlier ones say @@ -918,8 +945,8 @@ shared between agents. - **More than one active work item:** needs per-item serialisation, an inference scheduler and per-item intents. Build VMs and threads already separate workspaces and conversations. -- **Whether pure conversations need an external record** (work on a repository - already has its issue). +- **Somewhere to experiment before a project exists:** a shared scratch build VM + for `general` conversations, with tools but no push credential (L1, D1). - **Stacked PRs:** starting a milestone before the previous one merges, after experience with waiting (D4). - **Build VM collection:** how long idle, and whether it needs the operator's word. diff --git a/docs/Development-Plan.md b/docs/Development-Plan.md index a64fad0..e34a1d1 100644 --- a/docs/Development-Plan.md +++ b/docs/Development-Plan.md @@ -184,9 +184,12 @@ between milestones (D2, D4). End-to-end: a two-milestone feature. - Deferred: a milestone with no changes that wasn't expected to change code is still raised with the operator (D4). -**M2.5 Conversations and new projects.** *Needs discussion.* Work started in +**M2.5 Conversations and new projects.** *Needs discussion;* the design was agreed +in this PR (`general` scope, L1, L5; the new-project sequence, D1). Work started in conversation, record issues carrying their item's ID, the new-project flow and its -project entry (D1, D8, #29). End-to-end: a small new project. +project entry (D1, D8, #29). After M1.4. End-to-end: a small new project, in a +repository the test operator creates under its own account for the run and +deletes afterwards. **M2.6 Roles and capability profiles.** *Pre-approved.* `driver`, `helper`, `expert`, `classifier` (L9); escalation triggers; delegation and `ask_expert` on the -- 2.54.0 From b78fd58c85fd85e4703e574b1cabc4ca2d3ee1f2 Mon Sep 17 00:00:00 2001 From: Don Garrett Date: Tue, 6 Oct 2026 00:22:02 +0000 Subject: [PATCH 2/2] general never gets a build VM: an experiment means starting the project Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01PPQ14L3LikyefCMFBqEbKE --- docs/Architecture.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/docs/Architecture.md b/docs/Architecture.md index 075d987..29ca249 100644 --- a/docs/Architecture.md +++ b/docs/Architecture.md @@ -618,9 +618,8 @@ mean, how it fits, its first step. Labels steer what happens next: 5. **The architecture lands in one or more PRs,** treated as `design`, then the plan's milestones. - An experiment before the project exists (does a library parse this format?) has - nowhere to run: the agent says so, and suggests making it a project or using an - existing project's build VM. + `general` never gets a build VM: an experiment that needs one (does a library + parse this format?) is a reason to start the project for real. - **Progress** goes on the record issue: facts posted by the harness, prose by the agent when there's something to say. - **Finishing:** the last PR closes the issue on merge ("Closes #N"; earlier ones say @@ -945,8 +944,6 @@ shared between agents. - **More than one active work item:** needs per-item serialisation, an inference scheduler and per-item intents. Build VMs and threads already separate workspaces and conversations. -- **Somewhere to experiment before a project exists:** a shared scratch build VM - for `general` conversations, with tools but no push credential (L1, D1). - **Stacked PRs:** starting a milestone before the previous one merges, after experience with waiting (D4). - **Build VM collection:** how long idle, and whether it needs the operator's word. -- 2.54.0