-
+# OpenAgents Control — Architect Fork
-# OpenAgents Control (OAC)
+### Spec it · Build it · Verify it · Repeat
-### Control your AI patterns. Get repeatable results.
+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.
-**AI agents that learn YOUR coding patterns and generate matching code every time.**
+**Repository:** `git.lohmar.co.uk/cclohmar/NewOpenAgents`
-🎯 **Pattern Control** - Define your patterns once, AI uses them forever
-✋ **Approval Gates** - Review and approve before execution
-🔁 **Repeatable Results** - Same patterns = Same quality code
-📝 **Editable Agents** - Full control over AI behavior
-👥 **Team-Ready** - Everyone uses the same patterns
-
-**Multi-language:** TypeScript • Python • Go • Rust • Any language*
-**Model Agnostic:** Claude • GPT • Gemini • Local models
-
-
-[](https://github.com/darrenhinde/OpenAgentsControl/stargazers)
-[](https://x.com/DarrenBuildsAI)
-[](https://opensource.org/licenses/MIT)
-[](https://github.com/darrenhinde/OpenAgentsControl/commits/main)
-
-[🚀 Quick Start](#-quick-start) • [💻 Show Me Code](#-example-workflow) • [🗺️ Roadmap](https://github.com/darrenhinde/OpenAgentsControl/projects) • [💬 Community](https://nextsystems.ai)
+*Multi-language:* TypeScript · Python · Go · Rust · any language • *Model-agnostic:* Claude · GPT · Gemini · local models
---
-> **Built on [OpenCode](https://opencode.ai)** - An open-source AI coding framework. OAC extends OpenCode with specialized agents, context management, and team workflows.
+> **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 Problem
+## The idea
-Most AI agents are like hiring a developer who doesn't know your codebase. They write generic code. You spend hours rewriting, refactoring, and fixing inconsistencies. Tokens burned. Time wasted. No actual work done.
+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*:
-**Example:**
-```typescript
-// What AI gives you (generic)
-export async function POST(request: Request) {
- const data = await request.json();
- return Response.json({ success: true });
-}
+| | 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 |
-// What you actually need (your patterns)
-export async function POST(request: Request) {
- const body = await request.json();
- const validated = UserSchema.parse(body); // Your Zod validation
- const result = await db.users.create(validated); // Your Drizzle ORM
- return Response.json(result, { status: 201 }); // Your response format
-}
+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.
+
+```
+ 🧠 Architect writes an instruction (I-nnn)
+ │
+ ▼
+ 🔨 Builder implements a slice ──► commit + push
+ │
+ ▼
+ 🔨 Builder reports (W-nnn)
+ │
+ ▼
+ 🧠 Architect verifies independently ──► the next instruction (I-nnn)
```
-## The Solution
+## What this fork changes vs. upstream
-**OpenAgentsControl teaches agents your patterns upfront.** They understand your coding standards, your architecture, your security requirements. They propose plans before implementing. They execute incrementally with validation.
+| | 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 result:** Production-ready code that ships without heavy rework.
+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.
-### What Makes OAC Different
+## The two tiers
-**🎯 Context-Aware (Your Secret Weapon)**
-Agents load YOUR patterns before generating code. Code matches your project from the start. No refactoring needed.
+### 🧠 Tier 1 — The Controlling Architect (`OpenArchitect`)
-**📝 Editable Agents (Not Baked-In Plugins)**
-Full control over agent behavior. Edit markdown files directly—no compilation, no vendor lock-in. Change workflows, add constraints, customize for your team.
+A `primary` agent. It **reads the code, the docs and the live data** and then:
-**✋ Approval Gates (Human-Guided AI)**
-Agents ALWAYS request approval before execution. Propose → Approve → Execute. You stay in control. No "oh no, what did the AI just do?" moments.
+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.
-**⚡ Token Efficient (MVI Principle)**
-Minimal Viable Information design. Only load what's needed, when it's needed. Context files <200 lines, lazy loading, faster responses.
+> **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`.
-**👥 Team-Ready (Repeatable Patterns)**
-Store YOUR coding patterns once. Entire team uses same standards. Commit context to repo. New developers inherit team patterns automatically.
+### 🔨 Tier 2 — The Builders (`OpenAgent`)
-**🔄 Model Agnostic**
-Use any AI model (Claude, GPT, Gemini, local). No vendor lock-in.
+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**.
-**Full-stack development:** OAC handles both frontend and backend work. The agents coordinate to build complete features from UI to database.
+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
-## 🆚 Quick Comparison
+Every hand-over is a file in the repo, not a message in a chat.
-| Feature | OpenAgentsControl | Cursor/Copilot | Aider | Oh My OpenCode |
-|---------|-------------------|----------------|-------|----------------|
-| **Learn Your Patterns** | ✅ Built-in context system | ❌ No pattern learning | ❌ No pattern learning | ⚠️ Manual setup |
-| **Approval Gates** | ✅ Always required | ⚠️ Optional (default off) | ❌ Auto-executes | ❌ Fully autonomous |
-| **Token Efficiency** | ✅ MVI principle (80% reduction) | ❌ Full context loaded | ❌ Full context loaded | ❌ High token usage |
-| **Team Standards** | ✅ Shared context files | ❌ Per-user settings | ❌ No team support | ⚠️ Manual config per user |
-| **Edit Agent Behavior** | ✅ Markdown files you edit | ❌ Proprietary/baked-in | ⚠️ Limited prompts | ✅ Config files |
-| **Model Choice** | ✅ Any model, any provider | ⚠️ Limited options | ⚠️ OpenAI/Claude only | ✅ Multiple models |
-| **Execution Speed** | ⚠️ Sequential with approval | Fast | Fast | ✅ Parallel agents |
-| **Error Recovery** | ✅ Human-guided validation | ⚠️ Auto-retry (can loop) | ⚠️ Auto-retry | ✅ Self-correcting |
-| **Best For** | Production code, teams | Quick prototypes | Solo developers | Power users, complex projects |
+| 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-CLAUS.md` | **Architect** | the escalation queue — the human's decisions only |
-**Use OAC when:**
-- ✅ You have established coding patterns
-- ✅ You want code that ships without refactoring
-- ✅ You need approval gates for quality control
-- ✅ You care about token efficiency and costs
+The Architect **reads the repo, never the chat**, to verify a batch. That is why a builder must commit and push *before* it reports.
-**Use others when:**
-- **Cursor/Copilot:** Quick prototypes, don't care about patterns
-- **Aider:** Simple file edits, no team coordination
-- **Oh My OpenCode:** Need autonomous execution with parallel agents (speed over control)
+## The agents
-> **Full comparison:** [Read detailed analysis →](https://github.com/darrenhinde/OpenAgentsControl/discussions/116)
+### 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 |
-## 🚀 Quick Start
+## What's included
-**Prerequisites:** [OpenCode CLI](https://opencode.ai/docs) (free, open-source) • Bash 3.2+ • Git
+```
+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)
+```
-### Step 1: Install
+## Install
-**One command:**
+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
-curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh | bash -s developer
+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)
```
-
+curl -fsSL "https://git.lohmar.co.uk/cclohmar/NewOpenAgents/raw/branch/main/install.sh?token=$OAC_TOKEN" \
+ | bash -s -- --global --yes --token "$OAC_TOKEN"
```
-> Use `--install-dir PATH` if you installed to a custom location (e.g. `~/.config/opencode`).
+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.
-### Step 2: Start Building
+### 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
-opencode --agent OpenAgent
-> "Create a user authentication system"
+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/
```
-### Step 3: Approve & Ship
-
-**What happens:**
-1. Agent analyzes your request
-2. Proposes a plan (you approve)
-3. Executes step-by-step with validation
-4. Delegates to specialists when needed
-5. Ships production-ready code
-
-**That's it.** Works immediately with your default model. No configuration required.
-
----
-
-### Alternative: Claude Code Plugin (BETA)
-
-**Prefer Claude Code?** OpenAgents Control is also available as a Claude Code plugin!
-
-**Installation:**
-
-1. Register the marketplace:
-```bash
-/plugin marketplace add darrenhinde/OpenAgentsControl
-```
-
-2. Install the plugin:
-```bash
-/plugin install oac
-```
-
-3. Download context files:
-```bash
-/oac:setup --core
-```
-
-4. Start building:
-```
-Add a login endpoint
-```
-
-**Features:**
-- ✅ 6-stage workflow with approval gates
-- ✅ Context-aware code generation
-- ✅ 7 specialized subagents (task-manager, context-scout, context-manager, coder-agent, test-engineer, code-reviewer, external-scout)
-- ✅ 9 workflow skills + 6 user commands
-- ✅ Flexible context discovery (.oac config, .claude/context, context, .opencode/context)
-- ✅ Add context from GitHub, worktrees, local files, or URLs
-- ✅ Easy feature planning with `/oac:plan`
-
-**Documentation:**
-- [Plugin README](./plugins/claude-code/README.md) - Complete plugin documentation
-- [First-Time Setup](./plugins/claude-code/FIRST-TIME-SETUP.md) - Step-by-step guide
-- [Quick Start](./plugins/claude-code/QUICK-START.md) - Quick reference
-
-**Status:** BETA - Actively tested and ready for early adopters
-
----
-
-## 💡 The Context System: Your Secret Weapon
-
-**The problem with AI code:** It doesn't match your patterns. You spend hours refactoring.
-
-**The OAC solution:** Teach your patterns once. Agents load them automatically. Code matches from the start.
-
-### How It Works
-
-```
-Your Request
- ↓
-ContextScout discovers relevant patterns
- ↓
-Agent loads YOUR standards
- ↓
-Code generated using YOUR patterns
- ↓
-Ships without refactoring ✅
-```
-
-### Add Your Patterns (10-15 Minutes)
+Then start OpenCode and pick your agent:
```bash
-/add-context
+opencode # choose OpenArchitect for the controlling tier, OpenAgent to build
```
-**Answer 6 simple questions:**
-1. What's your tech stack? (Next.js + TypeScript + PostgreSQL + Tailwind)
-2. Show an API endpoint example (paste your code)
-3. Show a component example (paste your code)
-4. What naming conventions? (kebab-case, PascalCase, camelCase)
-5. Any code standards? (TypeScript strict, Zod validation, etc.)
-6. Any security requirements? (validate input, parameterized queries, etc.)
+## The context system — your patterns, loaded first
-**Result:** Agents now generate code matching your exact patterns. No refactoring needed.
+*(Inherited from upstream OAC — the secret weapon stays.)*
-### The MVI Advantage: Token Efficiency
+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.
-**MVI (Minimal Viable Information)** = Only load what's needed, when it's needed.
+- **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.
-**Traditional approach:**
-- Loads entire codebase context
-- Large token overhead per request
-- Slow responses, high costs
+Key files:
-**OAC approach:**
-- Loads only relevant patterns
-- Context files <200 lines (quick to load)
-- Lazy loading (agents load what they need)
-- 80% of tasks use isolation context (minimal overhead)
+| 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 |
-**Real benefits:**
-- **Efficiency:** Lower token usage vs loading entire codebase
-- **Speed:** Faster responses with smaller context
-- **Quality:** Code matches your patterns (no refactoring)
+## Commands
-### For Teams: Repeatable Patterns
+| 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 |
-**The team problem:** Every developer writes code differently. Inconsistent patterns. Hard to maintain.
+## Configuration
-**The OAC solution:** Store team patterns in `.opencode/context/project/`. Commit to repo. Everyone uses same standards.
-
-**Example workflow:**
-```bash
-# Team lead adds patterns once
-/add-context
-# Answers questions with team standards
-
-# Commit to repo
-git add .opencode/context/
-git commit -m "Add team coding standards"
-git push
-
-# All team members now use same patterns automatically
-# New developers inherit standards on day 1
-```
-
-**Result:** Consistent code across entire team. No style debates. No refactoring PRs.
-
----
-
-## 📖 How It Works
-
-### The Core Idea
-
-**Most AI tools:** Generic code → You refactor
-**OpenAgentsControl:** Your patterns → AI generates matching code
-
-### The Workflow
-
-```
-1. Add Your Context (one time)
- ↓
-2. ContextScout discovers relevant patterns
- ↓
-3. Agent loads YOUR standards
- ↓
-4. Agent proposes plan (using your patterns)
- ↓
-5. You approve
- ↓
-6. Agent implements (matches your project)
- ↓
-7. Code ships (no refactoring needed)
-```
-
-### Key Benefits
-
-**🎯 Context-Aware**
-ContextScout discovers relevant patterns. Agents load YOUR standards before generating code. Code matches your project from the start.
-
-**🔁 Repeatable**
-Same patterns → Same results. Configure once, use forever. Perfect for teams.
-
-**⚡ Token Efficient (80% Reduction)**
-MVI principle: Only load what's needed. 8,000 tokens → 750 tokens. Massive cost savings.
-
-**✋ Human-Guided**
-Agents propose plans, you approve before execution. Quality gates prevent mistakes. No auto-execution surprises.
-
-**📝 Transparent & Editable**
-Agents are markdown files you can edit. Change workflows, add constraints, customize behavior. No vendor lock-in.
-
-### What Makes This Special
-
-**1. ContextScout - Smart Pattern Discovery**
-Before generating code, ContextScout discovers relevant patterns from your context files. Ranks by priority (Critical → High → Medium). Prevents wasted work.
-
-**2. Editable Agents - Full Control**
-Unlike Cursor/Copilot where behavior is baked into plugins, OAC agents are markdown files. Edit them directly:
-```bash
-nano .opencode/agent/core/opencoder.md # local project install
-# Or: nano ~/.config/opencode/agent/core/opencoder.md # global install
-# Add project rules, change workflows, customize behavior
-```
-
-**3. ExternalScout - Live Documentation** 🆕
-Working with external libraries? ExternalScout fetches current documentation:
-- Gets live docs from official sources (npm, GitHub, docs sites)
-- No outdated training data - always current
-- Automatically triggered when agents detect external dependencies
-- Supports frameworks, APIs, libraries, and more
-
-**4. Approval Gates - No Surprises**
-Agents ALWAYS request approval before:
-- Writing/editing files
-- Running bash commands
-- Delegating to subagents
-- Making any changes
-
-You stay in control. Review plans before execution.
-
-**5. MVI Principle - Token Efficiency**
-Files designed for quick loading:
-- Concepts: <100 lines
-- Guides: <150 lines
-- Examples: <80 lines
-
-Result: Lower token usage vs loading entire codebase.
-
-**6. Team Patterns - Repeatable Results**
-Store patterns in `.opencode/context/project/`. Commit to repo. Entire team uses same standards. New developers inherit patterns automatically.
-
----
-
-## 🎯 Which Agent Should I Use?
-
-### OpenAgent (Start Here)
-
-**Best for:** Learning the system, general tasks, quick implementations
+Agents are plain Markdown — edit them directly, no build step:
```bash
-opencode --agent OpenAgent
-> "Create a user authentication system" # Building features
-> "How do I implement authentication in Next.js?" # Questions
-> "Create a README for this project" # Documentation
-> "Explain the architecture of this codebase" # Analysis
+nano .opencode/agent/OpenArchitect.md # the controlling tier
+nano .opencode/agent/subagents/openagent.md # the builder persona
```
-**What it does:**
-- Loads your patterns via ContextScout
-- Proposes plan (you approve)
-- Executes with validation
-- Delegates to specialists when needed
+Model selection is optional and lives in your OpenCode config (`.opencode/opencode.json` or global). Nothing here is vendor-locked.
-**Perfect for:** First-time users, simple features, learning the workflow
+## Attributions & license
-### OpenCoder (Production Development)
-
-**Best for:** Complex features, multi-file refactoring, production systems
-
-```bash
-opencode --agent OpenCoder
-> "Create a user authentication system" # Full-stack features
-> "Refactor this codebase to use dependency injection" # Multi-file refactoring
-> "Add real-time notifications with WebSockets" # Complex implementations
-```
-
-**What it does:**
-- **Discover:** ContextScout finds relevant patterns
-- **Propose:** Detailed implementation plan
-- **Approve:** You review and approve
-- **Execute:** Incremental implementation with validation
-- **Validate:** Tests, type checking, code review
-- **Ship:** Production-ready code
-
-**Perfect for:** Production code, complex features, team development
-
-### SystemBuilder (Custom AI Systems)
-
-**Best for:** Building complete custom AI systems tailored to your domain
-
-```bash
-opencode --agent SystemBuilder
-> "Create a customer support AI system"
-```
-
-Interactive wizard generates orchestrators, subagents, context files, workflows, and commands.
-
-**Perfect for:** Creating domain-specific AI systems
-
----
-
-## 🛠️ What's Included
-
-### 🤖 Main Agents
-- **OpenAgent** - General tasks, questions, learning (start here)
-- **OpenCoder** - Production development, complex features
-- **SystemBuilder** - Generate custom AI systems
-
-### 🔧 Specialized Subagents (Auto-delegated)
-- **ContextScout** - Smart pattern discovery (your secret weapon)
-- **TaskManager** - Breaks complex features into atomic subtasks
-- **CoderAgent** - Focused code implementations
-- **TestEngineer** - Test authoring and TDD
-- **CodeReviewer** - Code review and security analysis
-- **BuildAgent** - Type checking and build validation
-- **DocWriter** - Documentation generation
-- **ExternalScout** - Fetches live docs for external libraries (no outdated training data) **NEW!**
-- Plus category specialists: frontend, devops, copywriter, technical-writer, data-analyst
-
-### ⚡ Productivity Commands
-- `/add-context` - Interactive wizard to add your patterns
-- `/commit` - Smart git commits with conventional format
-- `/test` - Testing workflows
-- `/optimize` - Code optimization
-- `/context` - Context management
-- And 7+ more productivity commands
-
-### 📚 Context System (MVI Principle)
-Your coding standards automatically loaded by agents:
-- **Code quality** - Your patterns, security, standards
-- **UI/design** - Design system, component patterns
-- **Task management** - Workflow definitions
-- **External libraries** - Integration guides (18+ libraries supported)
-- **Project-specific** - Your team's patterns
-
-**Key features:**
-- 80% token reduction via MVI
-- Smart discovery via ContextScout
-- Lazy loading (only what's needed)
-- Team-ready (commit to repo)
-- Version controlled (track changes)
-
-### How Context Resolution Works
-
-ContextScout discovers context files using a **local-first** approach:
-
-```
-1. Check local: .opencode/context/core/navigation.md
- ↓ Found? → Use local for everything. Done.
- ↓ Not found?
-2. Check global: ~/.config/opencode/context/core/navigation.md
- ↓ Found? → Use global for core/ files only.
- ↓ Not found? → Proceed without core context.
-```
-
-**Key rules:**
-- **Local always wins** — if you installed locally, global is never checked
-- **Global fallback is only for `core/`** (standards, workflows, guides) — universal files that are the same across projects
-- **Project intelligence is always local** — your tech stack, patterns, and naming conventions live in `.opencode/context/project-intelligence/` and are never loaded from global
-- **One-time check** — ContextScout resolves the core location once at startup (max 2 glob checks), not per-file
-
-**Common setups:**
-
-| Setup | Core files from | Project intelligence from |
-|-------|----------------|--------------------------|
-| Local install (`bash install.sh developer`) | `.opencode/context/core/` | `.opencode/context/project-intelligence/` |
-| Global install + `/add-context` | `~/.config/opencode/context/core/` | `.opencode/context/project-intelligence/` |
-| Both local and global | `.opencode/context/core/` (local wins) | `.opencode/context/project-intelligence/` |
-
----
-
-
-
-## 💻 Example Workflow
-
-```bash
-opencode --agent OpenCoder
-> "Create a user dashboard with authentication and profile settings"
-```
-
-**What happens:**
-
-**1. Discover (~1-2 min)** - ContextScout finds relevant patterns
-- Your tech stack (Next.js + TypeScript + PostgreSQL)
-- Your API pattern (Zod validation, error handling)
-- Your component pattern (functional, TypeScript, Tailwind)
-- Your naming conventions (kebab-case files, PascalCase components)
-
-**2. Propose (~2-3 min)** - Agent creates detailed implementation plan
-```
-## Proposed Implementation
-
-**Components:**
-- user-dashboard.tsx (main page)
-- profile-settings.tsx (settings component)
-- auth-guard.tsx (authentication wrapper)
-
-**API Endpoints:**
-- /api/user/profile (GET, POST)
-- /api/auth/session (GET)
-
-**Database:**
-- users table (Drizzle schema)
-- sessions table (Drizzle schema)
-
-All code will follow YOUR patterns from context.
-
-Approve? [y/n]
-```
-
-**3. Approve** - You review and approve the plan (human-guided)
-
-**4. Execute (~10-15 min)** - Incremental implementation with validation
-- Implements one component at a time
-- Uses YOUR patterns for every file
-- Validates after each step (type check, lint)
-- *This is the longest step - generating quality code takes time*
-
-**5. Validate (~2-3 min)** - Tests, type checking, code review
-- Delegates to TestEngineer for tests
-- Delegates to CodeReviewer for security check
-- Ensures production quality
-
-**6. Ship** - Production-ready code
-- Code matches your project exactly
-- No refactoring needed
-- Ready to commit and deploy
-
-**Total time: ~15-25 minutes** for a complete feature (guided, with approval gates)
-
-### 💡 Pro Tips
-
-**After finishing a feature:**
-- Run `/add-context --update` to add new patterns you discovered
-- Update your context with new libraries, conventions, or standards
-- Keep your patterns fresh as your project evolves
-
-**Working with external libraries?**
-- **ExternalScout** automatically fetches current documentation
-- No more outdated training data - gets live docs from official sources
-- Works with npm packages, APIs, frameworks, and more
-
----
-
-## ⚙️ Advanced Configuration
-
-### Model Configuration (Optional)
-
-**By default, all agents use your OpenCode default model.** Configure models per agent only if you want different agents to use different models.
-
-**When to configure:**
-- You want faster agents to use cheaper models (e.g., Haiku/Flash)
-- You want complex agents to use smarter models (e.g., Opus/GPT-5)
-- You want to test different models for different tasks
-
-**How to configure:**
-
-Edit agent files directly:
-```bash
-nano .opencode/agent/core/opencoder.md # local project install
-# Or: nano ~/.config/opencode/agent/core/opencoder.md # global install
-```
-
-Change the model in the frontmatter:
-```yaml
----
-description: "Development specialist"
-model: anthropic/claude-sonnet-4-5 # Change this line
----
-```
-
-Browse available models at [models.dev](https://models.dev/?search=open) or run `opencode models`.
-
-### Update Context as You Go
-
-Your project evolves. Your context should too.
-
-```bash
-/add-context --update
-```
-
-**What gets updated:**
-- Tech stack, patterns, standards
-- Version incremented (1.0 → 1.1)
-- Updated date refreshed
-
-**Example updates:**
-- Add new library (Stripe, Twilio, etc.)
-- Change patterns (new API format, component structure)
-- Migrate tech stack (Prisma → Drizzle)
-- Update security requirements
-
-Agents automatically use updated patterns.
-
----
-
-
-
-## 🎯 Is This For You?
-
-### ✅ Use OAC if you:
-- Build production code that ships without heavy rework
-- Work in a team with established coding standards
-- Want control over agent behavior (not black-box plugins)
-- Care about token efficiency and cost savings
-- Need approval gates for quality assurance
-- Want repeatable, consistent results
-- Use multiple AI models (no vendor lock-in)
-
-### ⚠️ Skip OAC if you:
-- Want fully autonomous execution without approval gates
-- Prefer "just do it" mode over human-guided workflows
-- Don't have established coding patterns yet
-- Need multi-agent parallelization (use Oh My OpenCode instead)
-- Want plug-and-play with zero configuration
-
-### 🤔 Not Sure?
-
-**Try this test:**
-1. Ask your current AI tool to generate an API endpoint
-2. Count how many minutes you spend refactoring it to match your patterns
-3. If you're spending time on refactoring, OAC will save you that time
-
-**Or ask yourself:**
-- Do you have coding standards your team follows?
-- Do you spend time refactoring AI-generated code?
-- Do you want AI to follow YOUR patterns, not generic ones?
-
-If you answered "yes" to any of these, OAC is for you.
-
----
-
-## 🚀 Advanced Features
-
-### Frontend Design Workflow
-The **OpenFrontendSpecialist** follows a structured 4-stage design workflow:
-1. **Layout** - ASCII wireframe, responsive structure planning
-2. **Theme** - Design system selection, OKLCH colors, typography
-3. **Animation** - Micro-interactions, timing, accessibility
-4. **Implementation** - Single HTML file, semantic markup
-
-### Task Management & Breakdown
-The **TaskManager** breaks complex features into atomic, verifiable subtasks with smart agent suggestions and parallel execution support.
-
-### System Builder
-Build complete custom AI systems tailored to your domain in minutes. Interactive wizard generates orchestrators, subagents, context files, workflows, and commands.
-
----
-
-## ❓ FAQ
-
-### Getting Started
-
-**Q: Does this work on Windows?**
-A: Yes! Use Git Bash (recommended) or WSL.
-
-**Q: What languages are supported?**
-A: Agents are language-agnostic and adapt based on your project files. Primarily tested with TypeScript/Node.js. Python, Go, Rust, and other languages are supported but less battle-tested. The context system works with any language.
-
-**Q: Do I need to add context?**
-A: No, but it's highly recommended. Without context, agents write generic code. With context, they write YOUR code.
-
-**Q: Can I use this without customization?**
-A: Yes, it works out of the box. But you'll get the most value after adding your patterns (10-15 minutes with `/add-context`).
-
-**Q: What models are supported?**
-A: Any model from any provider (Claude, GPT, Gemini, local models). No vendor lock-in.
-
-### For Teams
-
-**Q: How do I share context with my team?**
-A: Commit `.opencode/context/project/` to your repo. Team members automatically use same patterns.
-
-**Q: How do we ensure everyone follows the same standards?**
-A: Add team patterns to context once. All agents load them automatically. Consistent code across entire team.
-
-**Q: Can different projects have different patterns?**
-A: Yes! Use project-specific context (`.opencode/` in project root) to override global patterns.
-
-### Technical
-
-**Q: How does token efficiency work?**
-A: MVI principle: Only load what's needed, when it's needed. Context files <200 lines (scannable in 30s). ContextScout discovers relevant patterns. Lazy loading prevents context bloat. 80% of tasks use isolation context (minimal overhead).
-
-**Q: What's ContextScout?**
-A: Smart pattern discovery agent. Finds relevant context files before code generation. Ranks by priority. Prevents wasted work.
-
-**Q: Can I edit agent behavior?**
-A: Yes! Agents are markdown files. Edit them directly: `nano .opencode/agent/core/opencoder.md` (local) or `nano ~/.config/opencode/agent/core/opencoder.md` (global)
-
-**Q: How do approval gates work?**
-A: Agents ALWAYS request approval before execution (write/edit/bash). You review plans before implementation. No surprises.
-
-**Q: How do I update my context?**
-A: Run `/add-context --update` anytime your patterns change. Agents automatically use updated patterns.
-
-### Comparison
-
-**Q: How is this different from Cursor/Copilot?**
-A: OAC has editable agents (not baked-in), approval gates (not auto-execute), context system (YOUR patterns), and MVI token efficiency.
-
-**Q: How is this different from Aider?**
-A: OAC has team patterns, context system, approval workflow, and smart pattern discovery. Aider is file-based only.
-
-**Q: How does this compare to Oh My OpenCode?**
-A: Both are built on OpenCode. OAC focuses on **control & repeatability** (approval gates, pattern control, team standards). Oh My OpenCode focuses on **autonomy & speed** (parallel agents, auto-execution). [Read detailed comparison →](https://github.com/darrenhinde/OpenAgentsControl/discussions/116)
-
-**Q: When should I NOT use OAC?**
-A: If you want fully autonomous execution without approval gates, or if you don't have established coding patterns yet.
-
-### Setup
-
-**Q: What bash version do I need?**
-A: Bash 3.2+ (macOS default works). Run `bash scripts/tests/test-compatibility.sh` to check.
-
-**Q: Do I need to install plugins/tools?**
-A: No, they're optional. Only install if you want Telegram notifications or Gemini AI features.
-
-**Q: Where should I install - globally or per-project?**
-A: Local (`.opencode/` in your project) is recommended — patterns are committed to git and shared with your team. Global (`~/.config/opencode/`) is good for personal defaults across all projects. The installer asks you to choose. See [OpenCode Config Docs](https://opencode.ai/docs/config/) for how configs merge.
-
----
-
-## 🗺️ Roadmap & What's Coming
-
-**This is only the beginning!** We're actively developing new features and improvements every day.
-
-### 🚀 See What's Coming Next
-
-Check out our [**Project Board**](https://github.com/darrenhinde/OpenAgentsControl/projects) to see:
-- 🔨 **In Progress** - Features being built right now
-- 📋 **Planned** - What's coming soon
-- 💡 **Ideas** - Future enhancements under consideration
-- ✅ **Recently Shipped** - Latest improvements
-
-### 🎯 Current Focus Areas
-
-- **Plugin System** - npm-based plugin architecture for easy distribution
-- **Performance Improvements** - Faster agent execution and context loading
-- **Enhanced Context Discovery** - Smarter pattern recognition
-- **Multi-language Support** - Better Python, Go, Rust support
-- **Team Collaboration** - Shared context and team workflows
-- **Documentation** - More examples, tutorials, and guides
-
-### 💬 Have Ideas?
-
-We'd love to hear from you!
-- 💡 [**Submit Feature Requests**](https://github.com/darrenhinde/OpenAgentsControl/issues/new?labels=enhancement)
-- 🐛 [**Report Bugs**](https://github.com/darrenhinde/OpenAgentsControl/issues/new?labels=bug)
-- 💬 [**Join Discussions**](https://github.com/darrenhinde/OpenAgentsControl/discussions)
-
-**Star the repo** ⭐ to stay updated with new releases!
-
----
-
-## 🤝 Contributing
-
-We welcome contributions!
-
-1. Follow the established naming conventions and coding standards
-2. Write comprehensive tests for new features
-3. Update documentation for any changes
-4. Ensure security best practices are followed
-
-See: [Contributing Guide](docs/contributing/CONTRIBUTING.md) • [Code of Conduct](docs/contributing/CODE_OF_CONDUCT.md)
-
----
-
-## 💬 Community & Support
-
-
-
-**Join the community and stay updated with the latest AI development workflows!**
-
-[](https://youtube.com/@DarrenBuildsAI)
-[](https://nextsystems.ai)
-[](https://x.com/DarrenBuildsAI)
-[](https://buymeacoffee.com/darrenhinde)
-
-**📺 Tutorials & Demos** • **💬 Join Waitlist** • **🐦 Latest Updates** • **☕ Support Development**
-
-*Your support helps keep this project free and open-source!*
-
-
-
----
-
-## License
-
-This project is licensed under the MIT License.
-
----
-
-**Made with ❤️ by developers, for developers. Star the repo if this saves you refactoring time!**
+- **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**.
+- **License:** MIT.
diff --git a/README.upstream.md b/README.upstream.md
new file mode 100644
index 0000000..b010cf5
--- /dev/null
+++ b/README.upstream.md
@@ -0,0 +1,823 @@
+
+
+
+
+# OpenAgents Control (OAC)
+
+### Control your AI patterns. Get repeatable results.
+
+**AI agents that learn YOUR coding patterns and generate matching code every time.**
+
+🎯 **Pattern Control** - Define your patterns once, AI uses them forever
+✋ **Approval Gates** - Review and approve before execution
+🔁 **Repeatable Results** - Same patterns = Same quality code
+📝 **Editable Agents** - Full control over AI behavior
+👥 **Team-Ready** - Everyone uses the same patterns
+
+**Multi-language:** TypeScript • Python • Go • Rust • Any language*
+**Model Agnostic:** Claude • GPT • Gemini • Local models
+
+
+[](https://github.com/darrenhinde/OpenAgentsControl/stargazers)
+[](https://x.com/DarrenBuildsAI)
+[](https://opensource.org/licenses/MIT)
+[](https://github.com/darrenhinde/OpenAgentsControl/commits/main)
+
+[🚀 Quick Start](#-quick-start) • [💻 Show Me Code](#-example-workflow) • [🗺️ Roadmap](https://github.com/darrenhinde/OpenAgentsControl/projects) • [💬 Community](https://nextsystems.ai)
+
+
+
+---
+
+> **Built on [OpenCode](https://opencode.ai)** - An open-source AI coding framework. OAC extends OpenCode with specialized agents, context management, and team workflows.
+
+---
+
+## The Problem
+
+Most AI agents are like hiring a developer who doesn't know your codebase. They write generic code. You spend hours rewriting, refactoring, and fixing inconsistencies. Tokens burned. Time wasted. No actual work done.
+
+**Example:**
+```typescript
+// What AI gives you (generic)
+export async function POST(request: Request) {
+ const data = await request.json();
+ return Response.json({ success: true });
+}
+
+// What you actually need (your patterns)
+export async function POST(request: Request) {
+ const body = await request.json();
+ const validated = UserSchema.parse(body); // Your Zod validation
+ const result = await db.users.create(validated); // Your Drizzle ORM
+ return Response.json(result, { status: 201 }); // Your response format
+}
+```
+
+## The Solution
+
+**OpenAgentsControl teaches agents your patterns upfront.** They understand your coding standards, your architecture, your security requirements. They propose plans before implementing. They execute incrementally with validation.
+
+**The result:** Production-ready code that ships without heavy rework.
+
+### What Makes OAC Different
+
+**🎯 Context-Aware (Your Secret Weapon)**
+Agents load YOUR patterns before generating code. Code matches your project from the start. No refactoring needed.
+
+**📝 Editable Agents (Not Baked-In Plugins)**
+Full control over agent behavior. Edit markdown files directly—no compilation, no vendor lock-in. Change workflows, add constraints, customize for your team.
+
+**✋ Approval Gates (Human-Guided AI)**
+Agents ALWAYS request approval before execution. Propose → Approve → Execute. You stay in control. No "oh no, what did the AI just do?" moments.
+
+**⚡ Token Efficient (MVI Principle)**
+Minimal Viable Information design. Only load what's needed, when it's needed. Context files <200 lines, lazy loading, faster responses.
+
+**👥 Team-Ready (Repeatable Patterns)**
+Store YOUR coding patterns once. Entire team uses same standards. Commit context to repo. New developers inherit team patterns automatically.
+
+**🔄 Model Agnostic**
+Use any AI model (Claude, GPT, Gemini, local). No vendor lock-in.
+
+**Full-stack development:** OAC handles both frontend and backend work. The agents coordinate to build complete features from UI to database.
+
+---
+
+## 🆚 Quick Comparison
+
+| Feature | OpenAgentsControl | Cursor/Copilot | Aider | Oh My OpenCode |
+|---------|-------------------|----------------|-------|----------------|
+| **Learn Your Patterns** | ✅ Built-in context system | ❌ No pattern learning | ❌ No pattern learning | ⚠️ Manual setup |
+| **Approval Gates** | ✅ Always required | ⚠️ Optional (default off) | ❌ Auto-executes | ❌ Fully autonomous |
+| **Token Efficiency** | ✅ MVI principle (80% reduction) | ❌ Full context loaded | ❌ Full context loaded | ❌ High token usage |
+| **Team Standards** | ✅ Shared context files | ❌ Per-user settings | ❌ No team support | ⚠️ Manual config per user |
+| **Edit Agent Behavior** | ✅ Markdown files you edit | ❌ Proprietary/baked-in | ⚠️ Limited prompts | ✅ Config files |
+| **Model Choice** | ✅ Any model, any provider | ⚠️ Limited options | ⚠️ OpenAI/Claude only | ✅ Multiple models |
+| **Execution Speed** | ⚠️ Sequential with approval | Fast | Fast | ✅ Parallel agents |
+| **Error Recovery** | ✅ Human-guided validation | ⚠️ Auto-retry (can loop) | ⚠️ Auto-retry | ✅ Self-correcting |
+| **Best For** | Production code, teams | Quick prototypes | Solo developers | Power users, complex projects |
+
+**Use OAC when:**
+- ✅ You have established coding patterns
+- ✅ You want code that ships without refactoring
+- ✅ You need approval gates for quality control
+- ✅ You care about token efficiency and costs
+
+**Use others when:**
+- **Cursor/Copilot:** Quick prototypes, don't care about patterns
+- **Aider:** Simple file edits, no team coordination
+- **Oh My OpenCode:** Need autonomous execution with parallel agents (speed over control)
+
+> **Full comparison:** [Read detailed analysis →](https://github.com/darrenhinde/OpenAgentsControl/discussions/116)
+
+---
+
+## 🚀 Quick Start
+
+**Prerequisites:** [OpenCode CLI](https://opencode.ai/docs) (free, open-source) • Bash 3.2+ • Git
+
+### Step 1: Install
+
+**One command:**
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh | bash -s developer
+```
+
+The installer will set up OpenCode CLI if you don't have it yet.
+
+**Or interactive:**
+```bash
+curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh -o install.sh
+bash install.sh
+```
+
+### Keep Updated
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/update.sh | bash
+```
+
+> Use `--install-dir PATH` if you installed to a custom location (e.g. `~/.config/opencode`).
+
+### Step 2: Start Building
+
+```bash
+opencode --agent OpenAgent
+> "Create a user authentication system"
+```
+
+### Step 3: Approve & Ship
+
+**What happens:**
+1. Agent analyzes your request
+2. Proposes a plan (you approve)
+3. Executes step-by-step with validation
+4. Delegates to specialists when needed
+5. Ships production-ready code
+
+**That's it.** Works immediately with your default model. No configuration required.
+
+---
+
+### Alternative: Claude Code Plugin (BETA)
+
+**Prefer Claude Code?** OpenAgents Control is also available as a Claude Code plugin!
+
+**Installation:**
+
+1. Register the marketplace:
+```bash
+/plugin marketplace add darrenhinde/OpenAgentsControl
+```
+
+2. Install the plugin:
+```bash
+/plugin install oac
+```
+
+3. Download context files:
+```bash
+/oac:setup --core
+```
+
+4. Start building:
+```
+Add a login endpoint
+```
+
+**Features:**
+- ✅ 6-stage workflow with approval gates
+- ✅ Context-aware code generation
+- ✅ 7 specialized subagents (task-manager, context-scout, context-manager, coder-agent, test-engineer, code-reviewer, external-scout)
+- ✅ 9 workflow skills + 6 user commands
+- ✅ Flexible context discovery (.oac config, .claude/context, context, .opencode/context)
+- ✅ Add context from GitHub, worktrees, local files, or URLs
+- ✅ Easy feature planning with `/oac:plan`
+
+**Documentation:**
+- [Plugin README](./plugins/claude-code/README.md) - Complete plugin documentation
+- [First-Time Setup](./plugins/claude-code/FIRST-TIME-SETUP.md) - Step-by-step guide
+- [Quick Start](./plugins/claude-code/QUICK-START.md) - Quick reference
+
+**Status:** BETA - Actively tested and ready for early adopters
+
+---
+
+## 💡 The Context System: Your Secret Weapon
+
+**The problem with AI code:** It doesn't match your patterns. You spend hours refactoring.
+
+**The OAC solution:** Teach your patterns once. Agents load them automatically. Code matches from the start.
+
+### How It Works
+
+```
+Your Request
+ ↓
+ContextScout discovers relevant patterns
+ ↓
+Agent loads YOUR standards
+ ↓
+Code generated using YOUR patterns
+ ↓
+Ships without refactoring ✅
+```
+
+### Add Your Patterns (10-15 Minutes)
+
+```bash
+/add-context
+```
+
+**Answer 6 simple questions:**
+1. What's your tech stack? (Next.js + TypeScript + PostgreSQL + Tailwind)
+2. Show an API endpoint example (paste your code)
+3. Show a component example (paste your code)
+4. What naming conventions? (kebab-case, PascalCase, camelCase)
+5. Any code standards? (TypeScript strict, Zod validation, etc.)
+6. Any security requirements? (validate input, parameterized queries, etc.)
+
+**Result:** Agents now generate code matching your exact patterns. No refactoring needed.
+
+### The MVI Advantage: Token Efficiency
+
+**MVI (Minimal Viable Information)** = Only load what's needed, when it's needed.
+
+**Traditional approach:**
+- Loads entire codebase context
+- Large token overhead per request
+- Slow responses, high costs
+
+**OAC approach:**
+- Loads only relevant patterns
+- Context files <200 lines (quick to load)
+- Lazy loading (agents load what they need)
+- 80% of tasks use isolation context (minimal overhead)
+
+**Real benefits:**
+- **Efficiency:** Lower token usage vs loading entire codebase
+- **Speed:** Faster responses with smaller context
+- **Quality:** Code matches your patterns (no refactoring)
+
+### For Teams: Repeatable Patterns
+
+**The team problem:** Every developer writes code differently. Inconsistent patterns. Hard to maintain.
+
+**The OAC solution:** Store team patterns in `.opencode/context/project/`. Commit to repo. Everyone uses same standards.
+
+**Example workflow:**
+```bash
+# Team lead adds patterns once
+/add-context
+# Answers questions with team standards
+
+# Commit to repo
+git add .opencode/context/
+git commit -m "Add team coding standards"
+git push
+
+# All team members now use same patterns automatically
+# New developers inherit standards on day 1
+```
+
+**Result:** Consistent code across entire team. No style debates. No refactoring PRs.
+
+---
+
+## 📖 How It Works
+
+### The Core Idea
+
+**Most AI tools:** Generic code → You refactor
+**OpenAgentsControl:** Your patterns → AI generates matching code
+
+### The Workflow
+
+```
+1. Add Your Context (one time)
+ ↓
+2. ContextScout discovers relevant patterns
+ ↓
+3. Agent loads YOUR standards
+ ↓
+4. Agent proposes plan (using your patterns)
+ ↓
+5. You approve
+ ↓
+6. Agent implements (matches your project)
+ ↓
+7. Code ships (no refactoring needed)
+```
+
+### Key Benefits
+
+**🎯 Context-Aware**
+ContextScout discovers relevant patterns. Agents load YOUR standards before generating code. Code matches your project from the start.
+
+**🔁 Repeatable**
+Same patterns → Same results. Configure once, use forever. Perfect for teams.
+
+**⚡ Token Efficient (80% Reduction)**
+MVI principle: Only load what's needed. 8,000 tokens → 750 tokens. Massive cost savings.
+
+**✋ Human-Guided**
+Agents propose plans, you approve before execution. Quality gates prevent mistakes. No auto-execution surprises.
+
+**📝 Transparent & Editable**
+Agents are markdown files you can edit. Change workflows, add constraints, customize behavior. No vendor lock-in.
+
+### What Makes This Special
+
+**1. ContextScout - Smart Pattern Discovery**
+Before generating code, ContextScout discovers relevant patterns from your context files. Ranks by priority (Critical → High → Medium). Prevents wasted work.
+
+**2. Editable Agents - Full Control**
+Unlike Cursor/Copilot where behavior is baked into plugins, OAC agents are markdown files. Edit them directly:
+```bash
+nano .opencode/agent/core/opencoder.md # local project install
+# Or: nano ~/.config/opencode/agent/core/opencoder.md # global install
+# Add project rules, change workflows, customize behavior
+```
+
+**3. ExternalScout - Live Documentation** 🆕
+Working with external libraries? ExternalScout fetches current documentation:
+- Gets live docs from official sources (npm, GitHub, docs sites)
+- No outdated training data - always current
+- Automatically triggered when agents detect external dependencies
+- Supports frameworks, APIs, libraries, and more
+
+**4. Approval Gates - No Surprises**
+Agents ALWAYS request approval before:
+- Writing/editing files
+- Running bash commands
+- Delegating to subagents
+- Making any changes
+
+You stay in control. Review plans before execution.
+
+**5. MVI Principle - Token Efficiency**
+Files designed for quick loading:
+- Concepts: <100 lines
+- Guides: <150 lines
+- Examples: <80 lines
+
+Result: Lower token usage vs loading entire codebase.
+
+**6. Team Patterns - Repeatable Results**
+Store patterns in `.opencode/context/project/`. Commit to repo. Entire team uses same standards. New developers inherit patterns automatically.
+
+---
+
+## 🎯 Which Agent Should I Use?
+
+### OpenAgent (Start Here)
+
+**Best for:** Learning the system, general tasks, quick implementations
+
+```bash
+opencode --agent OpenAgent
+> "Create a user authentication system" # Building features
+> "How do I implement authentication in Next.js?" # Questions
+> "Create a README for this project" # Documentation
+> "Explain the architecture of this codebase" # Analysis
+```
+
+**What it does:**
+- Loads your patterns via ContextScout
+- Proposes plan (you approve)
+- Executes with validation
+- Delegates to specialists when needed
+
+**Perfect for:** First-time users, simple features, learning the workflow
+
+### OpenCoder (Production Development)
+
+**Best for:** Complex features, multi-file refactoring, production systems
+
+```bash
+opencode --agent OpenCoder
+> "Create a user authentication system" # Full-stack features
+> "Refactor this codebase to use dependency injection" # Multi-file refactoring
+> "Add real-time notifications with WebSockets" # Complex implementations
+```
+
+**What it does:**
+- **Discover:** ContextScout finds relevant patterns
+- **Propose:** Detailed implementation plan
+- **Approve:** You review and approve
+- **Execute:** Incremental implementation with validation
+- **Validate:** Tests, type checking, code review
+- **Ship:** Production-ready code
+
+**Perfect for:** Production code, complex features, team development
+
+### SystemBuilder (Custom AI Systems)
+
+**Best for:** Building complete custom AI systems tailored to your domain
+
+```bash
+opencode --agent SystemBuilder
+> "Create a customer support AI system"
+```
+
+Interactive wizard generates orchestrators, subagents, context files, workflows, and commands.
+
+**Perfect for:** Creating domain-specific AI systems
+
+---
+
+## 🛠️ What's Included
+
+### 🤖 Main Agents
+- **OpenAgent** - General tasks, questions, learning (start here)
+- **OpenCoder** - Production development, complex features
+- **SystemBuilder** - Generate custom AI systems
+
+### 🔧 Specialized Subagents (Auto-delegated)
+- **ContextScout** - Smart pattern discovery (your secret weapon)
+- **TaskManager** - Breaks complex features into atomic subtasks
+- **CoderAgent** - Focused code implementations
+- **TestEngineer** - Test authoring and TDD
+- **CodeReviewer** - Code review and security analysis
+- **BuildAgent** - Type checking and build validation
+- **DocWriter** - Documentation generation
+- **ExternalScout** - Fetches live docs for external libraries (no outdated training data) **NEW!**
+- Plus category specialists: frontend, devops, copywriter, technical-writer, data-analyst
+
+### ⚡ Productivity Commands
+- `/add-context` - Interactive wizard to add your patterns
+- `/commit` - Smart git commits with conventional format
+- `/test` - Testing workflows
+- `/optimize` - Code optimization
+- `/context` - Context management
+- And 7+ more productivity commands
+
+### 📚 Context System (MVI Principle)
+Your coding standards automatically loaded by agents:
+- **Code quality** - Your patterns, security, standards
+- **UI/design** - Design system, component patterns
+- **Task management** - Workflow definitions
+- **External libraries** - Integration guides (18+ libraries supported)
+- **Project-specific** - Your team's patterns
+
+**Key features:**
+- 80% token reduction via MVI
+- Smart discovery via ContextScout
+- Lazy loading (only what's needed)
+- Team-ready (commit to repo)
+- Version controlled (track changes)
+
+### How Context Resolution Works
+
+ContextScout discovers context files using a **local-first** approach:
+
+```
+1. Check local: .opencode/context/core/navigation.md
+ ↓ Found? → Use local for everything. Done.
+ ↓ Not found?
+2. Check global: ~/.config/opencode/context/core/navigation.md
+ ↓ Found? → Use global for core/ files only.
+ ↓ Not found? → Proceed without core context.
+```
+
+**Key rules:**
+- **Local always wins** — if you installed locally, global is never checked
+- **Global fallback is only for `core/`** (standards, workflows, guides) — universal files that are the same across projects
+- **Project intelligence is always local** — your tech stack, patterns, and naming conventions live in `.opencode/context/project-intelligence/` and are never loaded from global
+- **One-time check** — ContextScout resolves the core location once at startup (max 2 glob checks), not per-file
+
+**Common setups:**
+
+| Setup | Core files from | Project intelligence from |
+|-------|----------------|--------------------------|
+| Local install (`bash install.sh developer`) | `.opencode/context/core/` | `.opencode/context/project-intelligence/` |
+| Global install + `/add-context` | `~/.config/opencode/context/core/` | `.opencode/context/project-intelligence/` |
+| Both local and global | `.opencode/context/core/` (local wins) | `.opencode/context/project-intelligence/` |
+
+---
+
+
+
+## 💻 Example Workflow
+
+```bash
+opencode --agent OpenCoder
+> "Create a user dashboard with authentication and profile settings"
+```
+
+**What happens:**
+
+**1. Discover (~1-2 min)** - ContextScout finds relevant patterns
+- Your tech stack (Next.js + TypeScript + PostgreSQL)
+- Your API pattern (Zod validation, error handling)
+- Your component pattern (functional, TypeScript, Tailwind)
+- Your naming conventions (kebab-case files, PascalCase components)
+
+**2. Propose (~2-3 min)** - Agent creates detailed implementation plan
+```
+## Proposed Implementation
+
+**Components:**
+- user-dashboard.tsx (main page)
+- profile-settings.tsx (settings component)
+- auth-guard.tsx (authentication wrapper)
+
+**API Endpoints:**
+- /api/user/profile (GET, POST)
+- /api/auth/session (GET)
+
+**Database:**
+- users table (Drizzle schema)
+- sessions table (Drizzle schema)
+
+All code will follow YOUR patterns from context.
+
+Approve? [y/n]
+```
+
+**3. Approve** - You review and approve the plan (human-guided)
+
+**4. Execute (~10-15 min)** - Incremental implementation with validation
+- Implements one component at a time
+- Uses YOUR patterns for every file
+- Validates after each step (type check, lint)
+- *This is the longest step - generating quality code takes time*
+
+**5. Validate (~2-3 min)** - Tests, type checking, code review
+- Delegates to TestEngineer for tests
+- Delegates to CodeReviewer for security check
+- Ensures production quality
+
+**6. Ship** - Production-ready code
+- Code matches your project exactly
+- No refactoring needed
+- Ready to commit and deploy
+
+**Total time: ~15-25 minutes** for a complete feature (guided, with approval gates)
+
+### 💡 Pro Tips
+
+**After finishing a feature:**
+- Run `/add-context --update` to add new patterns you discovered
+- Update your context with new libraries, conventions, or standards
+- Keep your patterns fresh as your project evolves
+
+**Working with external libraries?**
+- **ExternalScout** automatically fetches current documentation
+- No more outdated training data - gets live docs from official sources
+- Works with npm packages, APIs, frameworks, and more
+
+---
+
+## ⚙️ Advanced Configuration
+
+### Model Configuration (Optional)
+
+**By default, all agents use your OpenCode default model.** Configure models per agent only if you want different agents to use different models.
+
+**When to configure:**
+- You want faster agents to use cheaper models (e.g., Haiku/Flash)
+- You want complex agents to use smarter models (e.g., Opus/GPT-5)
+- You want to test different models for different tasks
+
+**How to configure:**
+
+Edit agent files directly:
+```bash
+nano .opencode/agent/core/opencoder.md # local project install
+# Or: nano ~/.config/opencode/agent/core/opencoder.md # global install
+```
+
+Change the model in the frontmatter:
+```yaml
+---
+description: "Development specialist"
+model: anthropic/claude-sonnet-4-5 # Change this line
+---
+```
+
+Browse available models at [models.dev](https://models.dev/?search=open) or run `opencode models`.
+
+### Update Context as You Go
+
+Your project evolves. Your context should too.
+
+```bash
+/add-context --update
+```
+
+**What gets updated:**
+- Tech stack, patterns, standards
+- Version incremented (1.0 → 1.1)
+- Updated date refreshed
+
+**Example updates:**
+- Add new library (Stripe, Twilio, etc.)
+- Change patterns (new API format, component structure)
+- Migrate tech stack (Prisma → Drizzle)
+- Update security requirements
+
+Agents automatically use updated patterns.
+
+---
+
+
+
+## 🎯 Is This For You?
+
+### ✅ Use OAC if you:
+- Build production code that ships without heavy rework
+- Work in a team with established coding standards
+- Want control over agent behavior (not black-box plugins)
+- Care about token efficiency and cost savings
+- Need approval gates for quality assurance
+- Want repeatable, consistent results
+- Use multiple AI models (no vendor lock-in)
+
+### ⚠️ Skip OAC if you:
+- Want fully autonomous execution without approval gates
+- Prefer "just do it" mode over human-guided workflows
+- Don't have established coding patterns yet
+- Need multi-agent parallelization (use Oh My OpenCode instead)
+- Want plug-and-play with zero configuration
+
+### 🤔 Not Sure?
+
+**Try this test:**
+1. Ask your current AI tool to generate an API endpoint
+2. Count how many minutes you spend refactoring it to match your patterns
+3. If you're spending time on refactoring, OAC will save you that time
+
+**Or ask yourself:**
+- Do you have coding standards your team follows?
+- Do you spend time refactoring AI-generated code?
+- Do you want AI to follow YOUR patterns, not generic ones?
+
+If you answered "yes" to any of these, OAC is for you.
+
+---
+
+## 🚀 Advanced Features
+
+### Frontend Design Workflow
+The **OpenFrontendSpecialist** follows a structured 4-stage design workflow:
+1. **Layout** - ASCII wireframe, responsive structure planning
+2. **Theme** - Design system selection, OKLCH colors, typography
+3. **Animation** - Micro-interactions, timing, accessibility
+4. **Implementation** - Single HTML file, semantic markup
+
+### Task Management & Breakdown
+The **TaskManager** breaks complex features into atomic, verifiable subtasks with smart agent suggestions and parallel execution support.
+
+### System Builder
+Build complete custom AI systems tailored to your domain in minutes. Interactive wizard generates orchestrators, subagents, context files, workflows, and commands.
+
+---
+
+## ❓ FAQ
+
+### Getting Started
+
+**Q: Does this work on Windows?**
+A: Yes! Use Git Bash (recommended) or WSL.
+
+**Q: What languages are supported?**
+A: Agents are language-agnostic and adapt based on your project files. Primarily tested with TypeScript/Node.js. Python, Go, Rust, and other languages are supported but less battle-tested. The context system works with any language.
+
+**Q: Do I need to add context?**
+A: No, but it's highly recommended. Without context, agents write generic code. With context, they write YOUR code.
+
+**Q: Can I use this without customization?**
+A: Yes, it works out of the box. But you'll get the most value after adding your patterns (10-15 minutes with `/add-context`).
+
+**Q: What models are supported?**
+A: Any model from any provider (Claude, GPT, Gemini, local models). No vendor lock-in.
+
+### For Teams
+
+**Q: How do I share context with my team?**
+A: Commit `.opencode/context/project/` to your repo. Team members automatically use same patterns.
+
+**Q: How do we ensure everyone follows the same standards?**
+A: Add team patterns to context once. All agents load them automatically. Consistent code across entire team.
+
+**Q: Can different projects have different patterns?**
+A: Yes! Use project-specific context (`.opencode/` in project root) to override global patterns.
+
+### Technical
+
+**Q: How does token efficiency work?**
+A: MVI principle: Only load what's needed, when it's needed. Context files <200 lines (scannable in 30s). ContextScout discovers relevant patterns. Lazy loading prevents context bloat. 80% of tasks use isolation context (minimal overhead).
+
+**Q: What's ContextScout?**
+A: Smart pattern discovery agent. Finds relevant context files before code generation. Ranks by priority. Prevents wasted work.
+
+**Q: Can I edit agent behavior?**
+A: Yes! Agents are markdown files. Edit them directly: `nano .opencode/agent/core/opencoder.md` (local) or `nano ~/.config/opencode/agent/core/opencoder.md` (global)
+
+**Q: How do approval gates work?**
+A: Agents ALWAYS request approval before execution (write/edit/bash). You review plans before implementation. No surprises.
+
+**Q: How do I update my context?**
+A: Run `/add-context --update` anytime your patterns change. Agents automatically use updated patterns.
+
+### Comparison
+
+**Q: How is this different from Cursor/Copilot?**
+A: OAC has editable agents (not baked-in), approval gates (not auto-execute), context system (YOUR patterns), and MVI token efficiency.
+
+**Q: How is this different from Aider?**
+A: OAC has team patterns, context system, approval workflow, and smart pattern discovery. Aider is file-based only.
+
+**Q: How does this compare to Oh My OpenCode?**
+A: Both are built on OpenCode. OAC focuses on **control & repeatability** (approval gates, pattern control, team standards). Oh My OpenCode focuses on **autonomy & speed** (parallel agents, auto-execution). [Read detailed comparison →](https://github.com/darrenhinde/OpenAgentsControl/discussions/116)
+
+**Q: When should I NOT use OAC?**
+A: If you want fully autonomous execution without approval gates, or if you don't have established coding patterns yet.
+
+### Setup
+
+**Q: What bash version do I need?**
+A: Bash 3.2+ (macOS default works). Run `bash scripts/tests/test-compatibility.sh` to check.
+
+**Q: Do I need to install plugins/tools?**
+A: No, they're optional. Only install if you want Telegram notifications or Gemini AI features.
+
+**Q: Where should I install - globally or per-project?**
+A: Local (`.opencode/` in your project) is recommended — patterns are committed to git and shared with your team. Global (`~/.config/opencode/`) is good for personal defaults across all projects. The installer asks you to choose. See [OpenCode Config Docs](https://opencode.ai/docs/config/) for how configs merge.
+
+---
+
+## 🗺️ Roadmap & What's Coming
+
+**This is only the beginning!** We're actively developing new features and improvements every day.
+
+### 🚀 See What's Coming Next
+
+Check out our [**Project Board**](https://github.com/darrenhinde/OpenAgentsControl/projects) to see:
+- 🔨 **In Progress** - Features being built right now
+- 📋 **Planned** - What's coming soon
+- 💡 **Ideas** - Future enhancements under consideration
+- ✅ **Recently Shipped** - Latest improvements
+
+### 🎯 Current Focus Areas
+
+- **Plugin System** - npm-based plugin architecture for easy distribution
+- **Performance Improvements** - Faster agent execution and context loading
+- **Enhanced Context Discovery** - Smarter pattern recognition
+- **Multi-language Support** - Better Python, Go, Rust support
+- **Team Collaboration** - Shared context and team workflows
+- **Documentation** - More examples, tutorials, and guides
+
+### 💬 Have Ideas?
+
+We'd love to hear from you!
+- 💡 [**Submit Feature Requests**](https://github.com/darrenhinde/OpenAgentsControl/issues/new?labels=enhancement)
+- 🐛 [**Report Bugs**](https://github.com/darrenhinde/OpenAgentsControl/issues/new?labels=bug)
+- 💬 [**Join Discussions**](https://github.com/darrenhinde/OpenAgentsControl/discussions)
+
+**Star the repo** ⭐ to stay updated with new releases!
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions!
+
+1. Follow the established naming conventions and coding standards
+2. Write comprehensive tests for new features
+3. Update documentation for any changes
+4. Ensure security best practices are followed
+
+See: [Contributing Guide](docs/contributing/CONTRIBUTING.md) • [Code of Conduct](docs/contributing/CODE_OF_CONDUCT.md)
+
+---
+
+## 💬 Community & Support
+
+
+
+**Join the community and stay updated with the latest AI development workflows!**
+
+[](https://youtube.com/@DarrenBuildsAI)
+[](https://nextsystems.ai)
+[](https://x.com/DarrenBuildsAI)
+[](https://buymeacoffee.com/darrenhinde)
+
+**📺 Tutorials & Demos** • **💬 Join Waitlist** • **🐦 Latest Updates** • **☕ Support Development**
+
+*Your support helps keep this project free and open-source!*
+
+
+
+---
+
+## License
+
+This project is licensed under the MIT License.
+
+---
+
+**Made with ❤️ by developers, for developers. Star the repo if this saves you refactoring time!**
diff --git a/install.sh b/install.sh
new file mode 100755
index 0000000..818caa8
--- /dev/null
+++ b/install.sh
@@ -0,0 +1,402 @@
+#!/usr/bin/env bash
+#
+# OpenAgents Control — Architect Fork · installer
+# ============================================================================
+# Installs the OAC Architect Fork — the agents, subagents, commands, context,
+# skills and tools — into a project's .opencode/ directory or the global
+# ~/.config/opencode/ directory.
+#
+# Adapted from Darren Hinde's OpenAgents Control installer (MIT).
+# upstream: https://github.com/darrenhinde/OpenAgentsControl
+# fork: https://git.lohmar.co.uk/cclohmar/NewOpenAgents
+#
+# Unlike upstream, this fork ships the COMPLETE .opencode payload at the repo
+# root (no registry.json), so the installer syncs the whole payload with
+# collision handling instead of resolving per-component from a registry.
+#
+# Usage:
+# ./install.sh # interactive: choose location
+# ./install.sh --local # into ./.opencode
+# ./install.sh --global # into ~/.config/opencode
+# ./install.sh --install-dir PATH # into an exact path
+# ./install.sh --source DIR # install from a local clone
+# ./install.sh --global --yes # non-interactive, skip existing files
+# ./install.sh --global --force # non-interactive, overwrite existing
+# ./install.sh --dry-run # show the plan, change nothing
+#
+# Environment:
+# OAC_TOKEN Forgejo token with repo:read (for a private remote fetch)
+# OPENCODE_BRANCH branch/tag to install from (default: main)
+# OPENCODE_INSTALL_DIR alternative to --install-dir
+# ============================================================================
+
+set -euo pipefail
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+REPO_HOST="git.lohmar.co.uk"
+REPO_OWNER="cclohmar"
+REPO_NAME="NewOpenAgents"
+REPO_URL="https://${REPO_HOST}/${REPO_OWNER}/${REPO_NAME}"
+BRANCH="${OPENCODE_BRANCH:-main}"
+TOKEN="${OAC_TOKEN:-}"
+
+# The payload that makes up an install (paths relative to the repo root)
+PAYLOAD_DIRS="agent command context skills tool"
+PAYLOAD_FILES="env.example package.json"
+
+# ---------------------------------------------------------------------------
+# Colours (only when writing to a terminal)
+# ---------------------------------------------------------------------------
+if [ -t 1 ]; then
+ RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'
+ BLUE='\033[0;34m'; CYAN='\033[0;36m'; MAGENTA='\033[0;35m'
+ BOLD='\033[1m'; NC='\033[0m'
+else
+ RED=''; GREEN=''; YELLOW=''; BLUE=''; CYAN=''; MAGENTA=''; BOLD=''; NC=''
+fi
+
+info() { printf "${BLUE}ℹ${NC} %s\n" "$1"; }
+success() { printf "${GREEN}✓${NC} %s\n" "$1"; }
+warn() { printf "${YELLOW}⚠${NC} %s\n" "$1"; }
+error() { printf "${RED}✗${NC} %s\n" "$1" >&2; }
+step() { printf "\n${MAGENTA}${BOLD}▶${NC} %s\n\n" "$1"; }
+die() { error "$1"; exit 1; }
+
+print_header() {
+ printf "${CYAN}${BOLD}"
+ cat <<'BANNER'
+╔════════════════════════════════════════════════════════════════╗
+║ ║
+║ OpenAgents Control — Architect Fork · Installer ║
+║ the Controlling Architect + the build agents ║
+║ ║
+╚════════════════════════════════════════════════════════════════╝
+BANNER
+ printf "${NC}\n"
+}
+
+usage() {
+ cat </dev/null 2>&1 || die "tar is required but not installed"
+if [ -z "$SOURCE" ] && [ -z "$TOKEN" ]; then
+ command -v git >/dev/null 2>&1 || die "git is required (or pass --token and install curl)"
+fi
+if [ -n "$TOKEN" ]; then
+ command -v curl >/dev/null 2>&1 || die "curl is required when using --token"
+fi
+
+# ---------------------------------------------------------------------------
+# Resolve the source payload
+# ---------------------------------------------------------------------------
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" >/dev/null 2>&1 && pwd)"
+
+TMP_DIR=""
+cleanup() { if [ -n "$TMP_DIR" ]; then rm -rf "$TMP_DIR" 2>/dev/null || true; fi; }
+trap cleanup EXIT INT TERM
+
+resolve_source() {
+ # 1) explicit --source
+ if [ -n "$SOURCE" ]; then
+ [ -d "$SOURCE/agent" ] || die "--source '$SOURCE' does not look like the OAC repo (no agent/ dir)"
+ SOURCE="$(cd "$SOURCE" && pwd)"
+ info "Using local source: $SOURCE"
+ return
+ fi
+
+ # 2) the script's own directory, when run from a clone
+ if [ -d "$SCRIPT_DIR/agent" ] && [ -d "$SCRIPT_DIR/context" ]; then
+ SOURCE="$SCRIPT_DIR"
+ info "Using the clone this script lives in: $SOURCE"
+ return
+ fi
+
+ # 3) download
+ TMP_DIR="$(mktemp -d 2>/dev/null || mktemp -d -t oac)"
+ if [ -n "$TOKEN" ]; then
+ step "Downloading the fork (branch: ${BRANCH})…"
+ local archive="https://${REPO_HOST}/${REPO_OWNER}/${REPO_NAME}/archive/${BRANCH}.tar.gz"
+ curl -fsSL -H "Authorization: token ${TOKEN}" "$archive" -o "$TMP_DIR/repo.tar.gz" \
+ || die "Download failed. Check --token / --branch."
+ tar -xzf "$TMP_DIR/repo.tar.gz" -C "$TMP_DIR"
+ SOURCE="$(find "$TMP_DIR" -mindepth 1 -maxdepth 1 -type d -print -quit)"
+ [ -n "$SOURCE" ] || die "Could not find the extracted payload"
+ success "Downloaded."
+ else
+ step "Cloning the fork (branch: ${BRANCH})…"
+ git clone --depth 1 --branch "$BRANCH" "$REPO_URL" "$TMP_DIR/repo" \
+ || die "Clone failed. For a private repo, configure git credentials or pass --token."
+ SOURCE="$TMP_DIR/repo"
+ success "Cloned."
+ fi
+}
+
+# ---------------------------------------------------------------------------
+# Resolve the install directory
+# ---------------------------------------------------------------------------
+global_path() { printf '%s/.config/opencode' "$HOME"; }
+
+choose_location_interactive() {
+ local gp; gp="$(global_path)"
+ echo -e "${BOLD}Where should the fork be installed?${NC}\n"
+ echo -e " ${GREEN}1)${NC} Local — ${CYAN}./.opencode${NC} (this project only)"
+ echo -e " ${BLUE}2)${NC} Global — ${CYAN}${gp}${NC} (every project)"
+ echo -e " ${MAGENTA}3)${NC} Custom — enter a path"
+ echo -e " 4) Cancel"
+ echo
+ printf "Enter your choice [1-4]: "
+ read -r choice
+ case "$choice" in
+ 1) INSTALL_DIR="$(pwd)/.opencode" ;;
+ 2) INSTALL_DIR="$gp" ;;
+ 3) printf "Enter installation path: "; read -r custom
+ [ -n "$custom" ] || die "No path entered"
+ case "$custom" in "~"*) custom="${HOME}${custom#\~}" ;; esac
+ INSTALL_DIR="$custom" ;;
+ 4) info "Cancelled."; exit 0 ;;
+ *) die "Invalid choice" ;;
+ esac
+}
+
+resolve_install_dir() {
+ if [ -n "$INSTALL_DIR" ]; then
+ return
+ fi
+ case "$LOCATION" in
+ local) INSTALL_DIR="$(pwd)/.opencode" ;;
+ global) INSTALL_DIR="$(global_path)" ;;
+ custom) die "--install-dir requires a path" ;;
+ *)
+ if [ -t 0 ] && [ -t 1 ]; then
+ choose_location_interactive
+ else
+ INSTALL_DIR="$(pwd)/.opencode"
+ info "No location given — defaulting to ./.opencode"
+ fi
+ ;;
+ esac
+}
+
+# ---------------------------------------------------------------------------
+# Collision strategy
+# ---------------------------------------------------------------------------
+STRATEGY="overwrite" # skip | overwrite | backup
+
+do_choose_strategy() {
+ echo
+ warn "Some items already exist in ${INSTALL_DIR}"
+ echo
+ echo -e "${BOLD}How should existing items be handled?${NC}\n"
+ echo -e " ${GREEN}1)${NC} Skip — keep existing items, install only new ones"
+ echo -e " ${YELLOW}2)${NC} Overwrite — replace existing items (your changes are lost)"
+ echo -e " ${CYAN}3)${NC} Backup — back up existing items, then overwrite"
+ echo -e " ${RED}4)${NC} Cancel"
+ echo
+ printf "Enter your choice [1-4]: "
+ read -r choice
+ case "$choice" in
+ 1) STRATEGY="skip" ;;
+ 2) printf "Type 'yes' to confirm overwrite: "; read -r c
+ [ "$c" = "yes" ] || { info "Cancelled."; exit 0; }
+ STRATEGY="overwrite" ;;
+ 3) STRATEGY="backup" ;;
+ 4) info "Cancelled."; exit 0 ;;
+ *) die "Invalid choice" ;;
+ esac
+}
+
+# ---------------------------------------------------------------------------
+# Install
+# ---------------------------------------------------------------------------
+BACKUP_DIR=""
+
+copy_entry() {
+ local name="$1" kind="$2" src="$3" dest="$4"
+ if [ -e "$dest" ]; then
+ case "$STRATEGY" in
+ skip)
+ info "Skipped existing ${kind}: ${name}"
+ return 0 ;;
+ backup)
+ local rel="${dest#${INSTALL_DIR}/}"
+ mkdir -p "$BACKUP_DIR/$(dirname "$rel")"
+ cp -R "$dest" "$BACKUP_DIR/$rel"
+ ;;
+ esac
+ [ "$DRY_RUN" = 1 ] || rm -rf "$dest"
+ fi
+ if [ "$DRY_RUN" = 1 ]; then
+ info "[dry-run] would install ${kind}: ${name} -> ${dest}"
+ else
+ cp -R "$src" "$(dirname "$dest")/"
+ success "Installed ${kind}: ${name}"
+ fi
+}
+
+perform_install() {
+ local installed=0 skipped=0
+
+ # Scan for collisions to decide the strategy
+ local have_collision=0 e
+ for e in $PAYLOAD_DIRS $PAYLOAD_FILES; do
+ if [ -e "$INSTALL_DIR/$e" ]; then have_collision=1; break; fi
+ done
+
+ if [ "$have_collision" = 1 ]; then
+ if [ "$FORCE" = 1 ]; then
+ STRATEGY="overwrite"
+ elif [ "$ASSUME_YES" = 1 ]; then
+ STRATEGY="skip"
+ info "Non-interactive: existing items will be skipped"
+ elif [ -t 0 ] && [ -t 1 ]; then
+ do_choose_strategy
+ else
+ STRATEGY="skip"
+ info "Non-interactive: existing items will be skipped"
+ fi
+ fi
+
+ if [ "$STRATEGY" = "backup" ] && [ "$DRY_RUN" != 1 ]; then
+ BACKUP_DIR="${INSTALL_DIR}.backup.$(date +%Y%m%d-%H%M%S)"
+ mkdir -p "$BACKUP_DIR"
+ info "Backing up to ${BACKUP_DIR}"
+ fi
+
+ if [ "$DRY_RUN" != 1 ]; then
+ mkdir -p "$INSTALL_DIR"
+ fi
+
+ local d f
+ for d in $PAYLOAD_DIRS; do
+ [ -d "$SOURCE/$d" ] || continue
+ if [ -e "$INSTALL_DIR/$d" ] && [ "$STRATEGY" = "skip" ]; then
+ info "Skipped existing directory: ${d}/"
+ skipped=$((skipped + 1))
+ continue
+ fi
+ copy_entry "$d/" "directory" "$SOURCE/$d" "$INSTALL_DIR/$d"
+ installed=$((installed + 1))
+ done
+ for f in $PAYLOAD_FILES; do
+ [ -f "$SOURCE/$f" ] || continue
+ if [ -e "$INSTALL_DIR/$f" ] && [ "$STRATEGY" = "skip" ]; then
+ info "Skipped existing file: ${f}"
+ skipped=$((skipped + 1))
+ continue
+ fi
+ copy_entry "$f" "file" "$SOURCE/$f" "$INSTALL_DIR/$f"
+ installed=$((installed + 1))
+ done
+
+ echo
+ if [ "$DRY_RUN" = 1 ]; then
+ warn "Dry run complete — nothing was changed."
+ else
+ success "Installation complete."
+ echo -e " Destination: ${CYAN}${INSTALL_DIR}${NC}"
+ [ "$skipped" -gt 0 ] && echo -e " Skipped: ${CYAN}${skipped}${NC}"
+ [ -n "$BACKUP_DIR" ] && echo -e " Backup: ${CYAN}${BACKUP_DIR}${NC}"
+ fi
+}
+
+show_post_install() {
+ step "Next steps"
+ echo "1. Review what was installed in ${CYAN}${INSTALL_DIR}${NC}"
+ if [ -f "$INSTALL_DIR/env.example" ]; then
+ echo "2. (Optional) configure integrations: ${CYAN}cp ${INSTALL_DIR}/env.example .env${NC}"
+ fi
+ echo "3. Start OpenCode and pick an agent:"
+ echo -e " ${CYAN}opencode${NC} → choose ${BOLD}OpenArchitect${NC} to spec/verify, ${BOLD}OpenAgent${NC} to build"
+ echo
+ info "Docs: ${REPO_URL}"
+}
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+main() {
+ print_header
+ resolve_source
+ resolve_install_dir
+
+ info "Source: ${SOURCE}"
+ info "Destination: ${INSTALL_DIR}"
+ [ "$DRY_RUN" = 1 ] && warn "Dry run — no changes will be written"
+
+ perform_install
+ [ "$DRY_RUN" != 1 ] && show_post_install
+}
+
+main