NewOpenAgents/README.md

OpenAgents Control — Architect Fork

Spec it · Build it · Verify it · Repeat

A fork of OpenAgents Control (OAC) by Darren Hinde 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. 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 Architect typically runs two in parallel, one per component, so two workstreams can advance at once.

Give them human names — the defaults are Leo and Mia — so a human reading the logs can see at a glance who is doing what. The name is set in the task prompt and in each builder's channel file, so swap Leo/Mia for any pair you like.

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-<NAME>.md	both	append-only discussion between the Architect and one builder (e.g. CHANNEL-LEO.md)

The file names are a convention, not a requirement — keep them as-is or map them to your project's own layout.

Escalation happens in chat, not in a file. The builders ask the Architect; the Architect asks the human only when a decision is genuinely theirs.

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

The repository is public — no token required.

The installer is all-in-one: if OpenCode isn't already installed, it bootstraps the runtime first (from the official installer at opencode.ai/v2/install), then installs the fork — and finally offers to set up the web UI service.

Quick install

curl -fsSL https://git.lohmar.co.uk/cclohmar/NewOpenAgents/raw/branch/main/install.sh | bash

Even though the script arrives over a pipe, it is interactive: it reads your answers from the terminal (/dev/tty). In a non-terminal context (CI), it runs with safe defaults instead of prompting.

Or clone, then install (recommended for updates)

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)

Interactively, the installer walks you through everything — where to install, the OpenCode runtime if it's missing, and finally the optional web UI service. You answer prompts; you rarely need a flag. Flags exist for scripting and CI.

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)
--token TOKEN	Forgejo token — only for a private mirror/fork (not needed here)
--with-opencode	install/update OpenCode even if it is already present
--no-opencode	skip the OpenCode runtime install
--opencode-version V	install a specific OpenCode version
--opencode-no-path	don't let the OpenCode installer edit your shell PATH
--service	set up the web UI service non-interactively (with defaults)
--no-service	never offer the web UI service
--yes / -y	non-interactive; skip existing files
--force	non-interactive; overwrite existing files
--dry-run	show what would happen, change nothing
--help	usage

PATH & activation

The official OpenCode installer appends export PATH="$HOME/.opencode/bin:$PATH" to your shell rc (~/.bashrc for bash) — but it does not activate it in the running shell, and an installer cannot change its parent shell. So:

• New terminal → opencode is on your PATH.
• Same terminal → source ~/.bashrc (or your shell's rc file).
• If the binary is present but not yet reachable, the installer says so at the end and, interactively, offers to symlink it into /usr/local/bin so it works immediately in every shell.

Manual install

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/

This copies the fork only — install the OpenCode runtime first if it's missing:

curl -fsSL https://opencode.ai/v2/install | bash

Then start OpenCode and pick your agent:

opencode            # choose OpenArchitect for the controlling tier, OpenAgent to build

Web UI service — optional, offered at the end of the install

At the end of an interactive install the installer asks whether to set up the OpenCode web UI as a systemd service (Linux):

Set up the OpenCode web UI as a systemd service? [y/N]

Answer y and it prompts for the bind address, port, working directory and whether to enable it on boot, then shows you the unit and asks for a final confirmation:

[Unit]
Description=opencode server (web UI)
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=<you>
Group=<you>
WorkingDirectory=<your project>
ExecStart=<opencode> serve --hostname 127.0.0.1 --port 4096
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

The service step is a separate program — install-service.sh — so you can also run it on its own (the installer just calls it after OpenCode is installed):

./install-service.sh                 # interactive
./install-service.sh --port 4096
./install-service.sh --host 0.0.0.0 --port 8080
./install-service.sh --yes           # non-interactive defaults
./install-service.sh --uninstall     # stop and remove the service
./install-service.sh --dry-run       # show the unit, change nothing

It refuses to run non-interactively unless you pass --yes, and backs up any existing unit before replacing it.

• Default bind is 127.0.0.1 — the server has no authentication of its own, so keep it loopback-only and put a reverse proxy (Zoraxy, nginx, …) in front. Choose 0.0.0.0 only if you deliberately want it exposed on your network.
• Non-systemd hosts: it prints the command to run the web UI manually instead.
• Non-interactive (e.g. curl | bash, CI): the service is not set up unless you pass --service.
• Run it by hand anytime: opencode serve --hostname 127.0.0.1 --port 4096 (or opencode web to also open a browser).

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:

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 by Darren Hinde — MIT. The context system, subagents, commands and skills come from there. The original upstream README is preserved as 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.