From 5e84cf7af096e6fce0edc87319ff19af60bd0416 Mon Sep 17 00:00:00 2001 From: cclohmar Date: Mon, 12 Oct 2026 09:11:39 +0000 Subject: [PATCH] docs: adapt README to the Architect fork; add fork installer - README rewritten around the Controlling Architect concept (spec -> build -> report -> verify), the architect/builder agency and the channels; upstream README preserved as README.upstream.md - install.sh: fork-native installer adapted from Darren Hinde's OAC installer. Syncs the complete .opencode payload (no registry), supports local/global/custom, skip/overwrite/backup, --source/--token/--branch/--yes/--force/--dry-run --- README.md | 912 ++++++++------------------------------------- README.upstream.md | 823 ++++++++++++++++++++++++++++++++++++++++ install.sh | 402 ++++++++++++++++++++ 3 files changed, 1386 insertions(+), 751 deletions(-) create mode 100644 README.upstream.md create mode 100755 install.sh diff --git a/README.md b/README.md index b010cf5..6bc92e6 100644 --- a/README.md +++ b/README.md @@ -1,823 +1,233 @@
-![OpenAgents Control Hero](docs/images/hero-image.png) +# 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 - - -[![GitHub stars](https://img.shields.io/github/stars/darrenhinde/OpenAgentsControl?style=flat-square&logo=github&labelColor=black&color=ffcb47)](https://github.com/darrenhinde/OpenAgentsControl/stargazers) -[![X Follow](https://img.shields.io/twitter/follow/DarrenBuildsAI?style=flat-square&logo=x&labelColor=black&color=1DA1F2)](https://x.com/DarrenBuildsAI) -[![License: MIT](https://img.shields.io/badge/License-MIT-3fb950?style=flat-square&labelColor=black)](https://opensource.org/licenses/MIT) -[![Last Commit](https://img.shields.io/github/last-commit/darrenhinde/OpenAgentsControl?style=flat-square&labelColor=black&color=8957e5)](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) ``` -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 +### Bootstrap without a clone (private → pass a token) ```bash -curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/update.sh | bash +export OAC_TOKEN= +curl -fsSL "https://git.lohmar.co.uk/cclohmar/NewOpenAgents/raw/branch/main/install.sh?token=$OAC_TOKEN" \ + | bash -s -- --global --yes --token "$OAC_TOKEN" ``` -> 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!** - -[![YouTube](https://img.shields.io/badge/YouTube-Darren_Builds_AI-red?style=for-the-badge&logo=youtube&logoColor=white)](https://youtube.com/@DarrenBuildsAI) -[![Community](https://img.shields.io/badge/Community-NextSystems.ai-blue?style=for-the-badge&logo=discourse&logoColor=white)](https://nextsystems.ai) -[![X/Twitter](https://img.shields.io/badge/Follow-@DarrenBuildsAI-1DA1F2?style=for-the-badge&logo=x&logoColor=white)](https://x.com/DarrenBuildsAI) -[![Buy Me A Coffee](https://img.shields.io/badge/Support-Buy_Me_A_Coffee-FFDD00?style=for-the-badge&logo=buy-me-a-coffee&logoColor=black)](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 Hero](docs/images/hero-image.png) + +# 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 + + +[![GitHub stars](https://img.shields.io/github/stars/darrenhinde/OpenAgentsControl?style=flat-square&logo=github&labelColor=black&color=ffcb47)](https://github.com/darrenhinde/OpenAgentsControl/stargazers) +[![X Follow](https://img.shields.io/twitter/follow/DarrenBuildsAI?style=flat-square&logo=x&labelColor=black&color=1DA1F2)](https://x.com/DarrenBuildsAI) +[![License: MIT](https://img.shields.io/badge/License-MIT-3fb950?style=flat-square&labelColor=black)](https://opensource.org/licenses/MIT) +[![Last Commit](https://img.shields.io/github/last-commit/darrenhinde/OpenAgentsControl?style=flat-square&labelColor=black&color=8957e5)](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!** + +[![YouTube](https://img.shields.io/badge/YouTube-Darren_Builds_AI-red?style=for-the-badge&logo=youtube&logoColor=white)](https://youtube.com/@DarrenBuildsAI) +[![Community](https://img.shields.io/badge/Community-NextSystems.ai-blue?style=for-the-badge&logo=discourse&logoColor=white)](https://nextsystems.ai) +[![X/Twitter](https://img.shields.io/badge/Follow-@DarrenBuildsAI-1DA1F2?style=for-the-badge&logo=x&logoColor=white)](https://x.com/DarrenBuildsAI) +[![Buy Me A Coffee](https://img.shields.io/badge/Support-Buy_Me_A_Coffee-FFDD00?style=for-the-badge&logo=buy-me-a-coffee&logoColor=black)](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