NewOpenAgents/README.md

<div align="center">

# 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

</div>

---

> **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 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`](https://opencode.ai/v2/install)), then installs the fork — and finally offers to set up the **web UI service**.

### Quick install

```bash
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)

```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)
```

**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

```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/
```

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

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

Then start OpenCode and pick your agent:

```bash
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:

```ini
[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):

```bash
./install-service.sh                          # interactive (also asks for a password)
./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 --password secret        # enable OpenCode's HTTP basic auth
./install-service.sh --username admin --password secret
./install-service.sh --no-password            # leave the server unsecured
./install-service.sh --uninstall              # stop and remove the service
./install-service.sh --dry-run                # show the unit, change nothing
```

**Auth (optional).** OpenCode's server has its own HTTP basic auth — enabled purely by setting `OPENCODE_SERVER_PASSWORD` (username defaults to `opencode`, or set `OPENCODE_SERVER_USERNAME`). The installer offers this interactively, or accept it non-interactively with `--password`. The secret is **never written into the unit**: it goes into a root-only env file (`/etc/opencode/opencode.env`, mode `600`) that the unit pulls in via `EnvironmentFile=`. Use this **or** your proxy's basic auth — they don't conflict.

> **The web app is a client.** On first use it shows an **"Add server"** dialog asking for the **server address** and the **password** — the username is *not* asked because it defaults to `opencode`. Enter your server URL and the password you set here. It's remembered after that. Keep the username as `opencode` (a custom one would not be sent by the browser).

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:

```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.