Architecture: the general scope and the new-project sequence (for M2.5)
CI / checks (push) Skipped
CI / checks (pull_request) Successful in 3m47s

- 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) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PPQ14L3LikyefCMFBqEbKE
This commit is contained in:
dongarandClaude Opus 5.5 committed 2026-10-06 00:21:34 +00:00
1 parent 3adbcce2a6
commit d301cba362
2 files changed
+47 -17

No files matched your search

+42 -15
View File
@@ -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.
+5 -2
View File
@@ -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