From 424e3eb9b730c3f710899d27cf13ff2680daff6b Mon Sep 17 00:00:00 2001 From: cclohmar Date: Mon, 12 Oct 2026 10:51:27 +0000 Subject: [PATCH] docs: make README project-agnostic (drop GMS-specific references) - remove the GMS reference project, the Codi/Sam role names and the FOR-CLAUS escalation file - rename the escalation queue to FOR-HUMAN.md and note the file names are a convention - state that the Architect + builders pattern is project-agnostic and reusable across repositories --- README.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 6bc92e6..8b4238e 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,7 @@ Upstream OAC gives you a capable **OpenAgent** that plans, implements and coordi The Architect is the **single point of contact**. The builders never ask the human directly — they ask the Architect, who resolves everything that already has an answer and escalates only the decisions that are genuinely the human's. -The result is a loop with **one source of truth: the repository**. Chat is not the record — the repo is. +The result is a loop with **one source of truth: the repository**. Chat is not the record — the repo is. **The pattern is project-agnostic:** drop the same Architect + builders setup into any repository and it works the same way. ``` 🧠 Architect writes an instruction (I-nnn) @@ -70,11 +70,11 @@ A `primary` agent. It **reads the code, the docs and the live data** and then: 4. **Rules on the flags** the builders raise (security, schema, scope, contradictions) and records the ruling. 5. **Is the human's single point of contact** — it escalates only the unavoidable gates. -> **The Architect's full rulebook is `ARCHITECTS.md`.** The GMS reference project keeps it at the repo root, next to its `AGENTS.md`; the agent definition itself is `agent/OpenArchitect.md`. +> **The Architect's full rulebook is `ARCHITECTS.md`** — keep it at your project root, next to the builders' `AGENTS.md`. The agent definition itself is `agent/OpenArchitect.md`. ### 🔨 Tier 2 — The Builders (`OpenAgent`) -The builders implement. They are **one generic agent** — the same persona, given a role for the run by the Architect's task prompt. On the reference project the main line is **Codi** and the second line is **Sam**. +The builders implement. They are **one generic agent** — the same persona, given a role for the run by the Architect's task prompt (the main line, a parallel line, a hotfix, …). Nothing about the role is baked into the agent; it comes from the spec. They read, in order: their persona → the history and current state (`docs/logs/WORKLOG.md`, `INSTRUCTIONS.md`, the hand-off) → the task prompt. Then they build, run the definition-of-done themselves, **commit and push before reporting**, and write exactly one `W-nnn` entry in the worklog. @@ -87,7 +87,9 @@ Every hand-over is a file in the repo, not a message in a chat. | `docs/logs/INSTRUCTIONS.md` | **Architect** | the **active task** (`I-nnn`) — only the newest is live | | `docs/logs/WORKLOG.md` | **Builders** | one report per instruction (`W-nnn`) | | `docs/logs/CHANNEL-*.md` | both | append-only discussion between the Architect and one builder | -| `docs/logs/FOR-CLAUS.md` | **Architect** | the escalation queue — the human's decisions only | +| `docs/logs/FOR-HUMAN.md` | **Architect** | the escalation queue — the human's decisions only | + +> The file names are a **convention**, not a requirement — keep them as-is or map them to your project's own layout. The Architect **reads the repo, never the chat**, to verify a batch. That is why a builder must commit and push *before* it reports. @@ -229,5 +231,5 @@ Model selection is optional and lives in your OpenCode config (`.opencode/openco ## Attributions & license - **Upstream:** [OpenAgents Control](https://github.com/darrenhinde/OpenAgentsControl) by **Darren Hinde** — MIT. The context system, subagents, commands and skills come from there. The original upstream README is preserved as [`README.upstream.md`](README.upstream.md). -- **This fork:** the **Controlling Architect** concept, the architect/builder agency, the channels and the GMS-flavoured rules — maintained by **Claus Lohmar**. +- **This fork:** the **Controlling Architect** concept, the architect/builder agency and the repo-as-source-of-truth workflow — maintained by **Claus Lohmar**. - **License:** MIT.