# OpenAgents Control — Architect Fork
### Spec it · Build it · Verify it · Repeat
A fork of **[OpenAgents Control (OAC)](https://github.com/darrenhinde/OpenAgentsControl)** by [Darren Hinde](https://github.com/darrenhinde)
that puts a **Controlling Architect** at the top — an agent that plans, specifies and verifies, and directs the build agents.
**Repository:** `git.lohmar.co.uk/cclohmar/NewOpenAgents`
*Multi-language:* TypeScript · Python · Go · Rust · any language • *Model-agnostic:* Claude · GPT · Gemini · local models
---
> **Built on [OpenCode](https://opencode.ai).** OAC extends OpenCode with specialized agents, a context system and team workflows. **This fork** — maintained by Claus Lohmar — changes the *concept* at the top: instead of a single agent that both plans and builds, it installs a **Controlling Architect** that only specs and verifies, and one or more **build agents** that only build.
---
## The idea
Upstream OAC gives you a capable **OpenAgent** that plans, implements and coordinates, with approval gates between each step. This fork splits that role in two *deliberately*:
| | Role | Does | Never does |
|---|------|------|-----------|
| **🧠 The Architect** | *why* + *how* | reads the code, writes the specs, verifies the work, rules on design/scope/security | write the implementation |
| **🔨 The Builders** | *do* | implement one spec at a time, run the tests, commit and report | decide what should be built |
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 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)
│
▼
🔨 Builder implements a slice ──► commit + push
│
▼
🔨 Builder reports (W-nnn)
│
▼
🧠 Architect verifies independently ──► the next instruction (I-nnn)
```
## What this fork changes vs. upstream
| | Upstream OAC | This fork |
|---|---|---|
| **Top-level agent** | `OpenAgent` (plans *and* builds) | **`OpenArchitect`** (specs, verifies, controls) |
| **Build agents** | `OpenAgent` / `OpenCoder` | **build agents**, directed by the Architect, one slice at a time |
| **Workflow** | Plan → approve → execute | **Spec → build → report → verify → next spec** |
| **Source of truth** | the chat + approval gates | **the repository** — instructions, worklog, channels |
| **Independence** | the agent self-checks | the **Architect** re-runs the evidence itself |
| **Roles, not forks** | one agent fits all | one generic builder; its role (e.g. a second line) is named **in the task prompt** |
The **context system, subagents, commands and skills** are inherited from upstream and work exactly as documented below — the fork adds the *controlling* tier on top.
## The two tiers
### 🧠 Tier 1 — The Controlling Architect (`OpenArchitect`)
A `primary` agent. It **reads the code, the docs and the live data** and then:
1. **Specifies the interfaces, not the outcome** — the routes, params, file names, table names. If the spec doesn't name it, the builder will invent it.
2. **Writes one instruction at a time** into `docs/logs/INSTRUCTIONS.md`, addressed to a named builder.
3. **Verifies every batch independently** — re-runs the build, the tests and the claim's own evidence. "It exists in the code" is never "it works".
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`** — 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 (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.
## The agency — how the two tiers talk
Every hand-over is a file in the repo, not a message in a chat.
| File | Writer | Purpose |
|------|--------|---------|
| `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-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.
## The agents
### Primary agents
| Agent | File | Role |
|-------|------|------|
| **OpenArchitect** | `agent/OpenArchitect.md` | the Controlling Architect — specs, verifies, rules |
| **OpenAgent** | `agent/core/openagent.md` | universal builder / coordinator |
| **OpenCoder** | `agent/core/opencoder.md` | complex coding & multi-file refactoring |
### Subagents (auto-delegated)
| Subagent | Purpose |
|----------|---------|
| `openagent` | the **builder** persona — implements a slice per the Architect's spec |
| `ContextScout` | discovers the project's own context files before work begins |
| `ExternalScout` | fetches current, version-specific docs for external libraries |
| `TaskManager` | breaks a feature into atomic, verifiable subtasks |
| `CoderAgent` | executes coding subtasks in sequence |
| `BuildAgent` | type-check and build validation |
| `CodeReviewer` | code review, security and quality assurance |
| `TestEngineer` | test authoring / TDD |
| `DocWriter` | documentation authoring |
| `ContextOrganizer` | organises and generates context files |
| `OpenDevopsSpecialist` | CI/CD, infrastructure-as-code, deployment |
| `OpenFrontendSpecialist` | design systems, themes, animation |
## What's included
```
agent/ the agents & subagents (OpenArchitect, OpenAgent, OpenCoder, …)
command/ slash commands (/commit, /test, /context, /optimize, …)
context/ the context system — standards, workflows, UI, project templates
skills/ loadable skills (Context7 docs lookup, task management)
tool/ custom OpenCode tools (env loader)
env.example template for the optional .env (Telegram/Gemini integrations)
```
## Install
This repository is **private**, so the installer needs access to it. The simplest path is to clone it once and run the installer from the clone — your existing git credentials are used, no token to paste.
### Recommended — clone, then install
```bash
git clone https://git.lohmar.co.uk/cclohmar/NewOpenAgents.git ~/.oac
~/.oac/install.sh # interactive: choose Local / Global / Custom
~/.oac/install.sh --global # → ~/.config/opencode (every project)
~/.oac/install.sh --local # → ./.opencode (this project)
```
### Bootstrap without a clone (private → pass a token)
```bash
export OAC_TOKEN=
curl -fsSL "https://git.lohmar.co.uk/cclohmar/NewOpenAgents/raw/branch/main/install.sh?token=$OAC_TOKEN" \
| bash -s -- --global --yes --token "$OAC_TOKEN"
```
The installer offers **Local** (`.opencode/` in the current project), **Global** (`~/.config/opencode`) or a **Custom** path, and — when files already exist — lets you **skip**, **overwrite** or **back up & overwrite**. A `--source DIR` flag installs from a local copy; `--dry-run` shows the plan without changing anything.
### Options
| Flag | Meaning |
|------|---------|
| `--local` | install into `./.opencode` (default) |
| `--global` | install into `~/.config/opencode` |
| `--install-dir PATH` | install into an exact path |
| `--source DIR` | install from a local clone instead of downloading |
| `--branch REF` | branch/tag to install from (default `main`) |
| `--yes` / `-y` | non-interactive; skip existing files |
| `--force` | non-interactive; overwrite existing files |
| `--dry-run` | show what would happen, change nothing |
| `--help` | usage |
### Manual install
```bash
git clone https://git.lohmar.co.uk/cclohmar/NewOpenAgents.git /tmp/oac
mkdir -p .opencode
cp -R /tmp/oac/agent /tmp/oac/command /tmp/oac/context \
/tmp/oac/skills /tmp/oac/tool /tmp/oac/env.example \
/tmp/oac/package.json .opencode/
```
Then start OpenCode and pick your agent:
```bash
opencode # choose OpenArchitect for the controlling tier, OpenAgent to build
```
## The context system — your patterns, loaded first
*(Inherited from upstream OAC — the secret weapon stays.)*
Most agents are like hiring a developer who doesn't know your codebase. They write generic code; you spend hours fixing it. **OAC loads YOUR patterns before it writes a line.** The Architect and the builders both read the same context files, so the whole agency agrees on the standards.
- **Minimal Viable Information (MVI)** — context files stay small (<200 lines) and load lazily. Only what's needed, when it's needed.
- **`ContextScout`** finds the project's own rules before any work; **`ExternalScout`** fetches the *current* docs for any external library.
- **Team-ready** — commit your patterns to the repo and every agent (and every teammate) inherits them on day one.
Key files:
| Context | Use |
|---------|-----|
| `context/core/standards/code-quality.md` | before writing code |
| `context/core/standards/documentation.md` | before writing docs |
| `context/core/standards/test-coverage.md` | before writing tests |
| `context/core/workflows/code-review.md` | before reviewing |
| `context/core/workflows/delegation.md` | before delegating to a subagent |
| `context/project-intelligence/` | the living notes: domain, decisions, tech |
## Commands
| Command | What it does |
|---------|--------------|
| `/commit` | create a well-formatted conventional commit and push |
| `/test` | run the full testing pipeline |
| `/context` | harvest / extract / organise context |
| `/add-context` | interactive wizard to add project patterns |
| `/optimize` | analyse for performance & security issues |
| `/clean` | format, sort imports, lint |
| `/analyze-patterns` | find similar implementations in the codebase |
| `/validate-repo` | check consistency across agents, docs and context |
## Configuration
Agents are plain Markdown — edit them directly, no build step:
```bash
nano .opencode/agent/OpenArchitect.md # the controlling tier
nano .opencode/agent/subagents/openagent.md # the builder persona
```
Model selection is optional and lives in your OpenCode config (`.opencode/opencode.json` or global). Nothing here is vendor-locked.
## 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 and the repo-as-source-of-truth workflow — maintained by **Claus Lohmar**.
- **License:** MIT.