{"id":47640224,"url":"https://github.com/insajin/autopus-adk","last_synced_at":"2026-05-30T01:03:07.667Z","repository":{"id":345686823,"uuid":"1186893316","full_name":"Insajin/autopus-adk","owner":"Insajin","description":"Autopus-ADK is of the agents, by the agents. for the agents. Multi-model orchestration (consensus/pipeline/debate/fastest). Architecture-as-Code, Lore decision tracking, SPEC/EARS engine.","archived":false,"fork":false,"pushed_at":"2026-05-16T05:15:13.000Z","size":9280,"stargazers_count":100,"open_issues_count":1,"forks_count":75,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-16T07:16:14.904Z","etag":null,"topics":["agent-framework","agentic-ai","ai-agents","automation","claude-code","cli","codex","coding-agents","developer-tools","gemini-cli","golang","multi-agent","multi-agent-systems","opencode"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Insajin.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-20T05:20:25.000Z","updated_at":"2026-05-16T05:15:15.000Z","dependencies_parsed_at":null,"dependency_job_id":"42d6f162-6c67-4207-bce5-9c496ece42f6","html_url":"https://github.com/Insajin/autopus-adk","commit_stats":null,"previous_names":["insajin/autopus-adk"],"tags_count":215,"template":false,"template_full_name":null,"purl":"pkg:github/Insajin/autopus-adk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Insajin%2Fautopus-adk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Insajin%2Fautopus-adk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Insajin%2Fautopus-adk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Insajin%2Fautopus-adk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Insajin","download_url":"https://codeload.github.com/Insajin/autopus-adk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Insajin%2Fautopus-adk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33386079,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T04:15:53.637Z","status":"ssl_error","status_checked_at":"2026-05-23T04:15:53.242Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-framework","agentic-ai","ai-agents","automation","claude-code","cli","codex","coding-agents","developer-tools","gemini-cli","golang","multi-agent","multi-agent-systems","opencode"],"created_at":"2026-04-02T00:47:41.088Z","updated_at":"2026-05-23T07:05:29.755Z","avatar_url":"https://github.com/Insajin.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# 🐙 Autopus-ADK\n\n### A harness *of* the agents, *by* the agents, *for* the agents.\n\nMake your AI coding tools (Claude Code, Codex, Antigravity CLI, OpenCode) work like a real engineering team — with planning, testing, code review, and security audits built in.\n\n**16 agents. 40 skills. One config. Every platform.**\n\n[![GitHub Stars](https://img.shields.io/github/stars/Insajin/autopus-adk?style=social)](https://github.com/Insajin/autopus-adk/stargazers)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Go Version](https://img.shields.io/badge/Go-1.26-00ADD8?logo=go\u0026logoColor=white)](https://golang.org)\n[![Platforms](https://img.shields.io/badge/Platforms-4-orange)](#-one-config-four-platforms)\n[![Agents](https://img.shields.io/badge/Agents-16-blueviolet)](#-16-specialized-agents)\n[![Skills](https://img.shields.io/badge/Skills-40-ff69b4)](#-all-commands)\n\n**Paste this command into your AI coding agent's chat (Claude Code, Codex, OpenCode, etc.) — the agent will run it and set up everything automatically. Or run it directly in your terminal.**\n\n```bash\n# macOS / Linux\ncurl -sSfL https://raw.githubusercontent.com/Insajin/autopus-adk/main/install.sh | sh\n\n# Windows (CMD or PowerShell)\npowershell -c \"irm https://raw.githubusercontent.com/Insajin/autopus-adk/main/install.ps1 | iex\"\n```\n\n[Why Autopus](#-the-problem) · [**Core Workflow**](#-the-workflow-three-commands-to-ship) · [Features](#-what-makes-autopus-different) · [Pipeline](#-the-pipeline) · [Security](#-security) · [Docs](#-all-commands)\n\n[🇰🇷 한국어](docs/README.ko.md)\n\n\u003c/div\u003e\n\n---\n\n## 🎬 See It In Action\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"demo/hero.gif\" width=\"720\" alt=\"Autopus-ADK demo — version, doctor, platform, status, skills\" /\u003e\u003c/p\u003e\n\n```bash\n# Brainstorm with 3 AI models debating each other\n/auto idea \"Add OAuth2 with Google and GitHub providers\" --multi --ultrathink\n\n# One command does the rest — plan, build with 16 agents, ship with docs\n/auto dev \"Add OAuth2 with Google and GitHub providers\"\n```\n\nOr if you prefer step-by-step control:\n\n```bash\n/auto plan \"Add OAuth2 with Google and GitHub providers\" --auto --multi --ultrathink\n/auto go SPEC-AUTH-001 --auto --loop --team\n/auto sync SPEC-AUTH-001\n```\n\n```\n🐙 Pipeline ─────────────────────────────────────────────\n  ✓ Phase 1:   Planning         planner decomposed 5 tasks\n  ✓ Phase 1.5: Test Scaffold    12 failing tests created (RED)\n  ✓ Phase 2:   Implementation   3 executors in parallel worktrees\n  ✓ Phase 2.5: Annotation       @AX tags applied to 8 files\n  ✓ Phase 3:   Testing          coverage: 62% → 91%\n  ✓ Phase 4:   Review           TRUST 5: APPROVE | Security: PASS\n  ───────────────────────────────────────────────────────\n  ✅ 5/5 tasks │ 91% coverage │ 0 security issues │ 4m 32s\n```\n\n\u003e 💡 One command. Production-ready code with tests, security audit, documentation, and decision history.\n\n---\n\n## ⭐ Star History\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.star-history.com/#Insajin/autopus-adk\u0026Date\"\u003e\n    \u003cimg\n      src=\"https://api.star-history.com/svg?repos=Insajin/autopus-adk\u0026type=Date\"\n      width=\"720\"\n      alt=\"Star history chart for Insajin/autopus-adk\"\n    /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## 😤 The Problem\n\nYou're using AI coding tools. They're powerful. But...\n\n- 🔄 **Platform lock-in** — Switch from Claude to Codex? Rewrite all your rules and prompts from scratch.\n- 🎲 **Hope-driven development** — \"Add auth\" → AI writes code, skips tests, ignores security, forgets docs. *Maybe* it works.\n- 🧠 **Amnesia** — Next session, the AI forgets every decision. \"Why did we use this pattern?\" → silence.\n- 👤 **Solo agent** — One model, one context, one shot. Multi-file refactoring? Good luck.\n\n---\n\n## 🧠 The Philosophy: AX — Agent Experience\n\n\u003e **AX** is not \"AI Transformation.\" AX is **Agent Experience** — how AI agents perceive, navigate, and operate within your codebase. Just as UX designs for users and DX designs for developers, **AX designs for agents.**\n\n```mermaid\nflowchart LR\n    UX[\"🧑 UX\\nUser Experience\"]\n    DX[\"👩‍💻 DX\\nDeveloper Experience\"]\n    AX[\"🤖 AX\\nAgent Experience\"]\n\n    UX --\u003e|\"designs for\"| U[\"Users\"]\n    DX --\u003e|\"designs for\"| D[\"Developers\"]\n    AX --\u003e|\"designs for\"| A[\"AI Agents\"]\n\n    style AX fill:#ff6b6b,stroke:#c92a2a,color:#fff\n```\n\nMost AI coding tools are designed around a simple model: **you prompt, it responds.**\n\nAutopus starts from a different question: *What if the agent is the primary audience of your project's documentation?*\n\nThink about onboarding a new engineer. You wouldn't hand them a blank editor and say \"build the auth system.\" You'd give them:\n- An architecture overview so they understand the system\n- Coding conventions so their code fits in\n- Decision history so they don't repeat past mistakes\n- A review process so mistakes get caught before shipping\n\n**AI agents need the same things.** The difference is that every session is their first day.\n\nAutopus is a **harness** — a structured environment that gives agents the context, constraints, and workflows they need to produce code that a senior engineer would approve. Not through hope. Through design.\n\n### Of the agents. By the agents. For the agents.\n\n```mermaid\nflowchart TB\n    subgraph OF [\"🧬 Of the Agents\"]\n        direction TB\n        O1[\"16 specialized agents\\nform a software team\"]\n        O2[\"Planner · Executor · Tester\\nReviewer · Architect · ...\"]\n    end\n\n    subgraph BY [\"⚡ By the Agents\"]\n        direction TB\n        B1[\"Agents run the pipeline\\nautonomously\"]\n        B2[\"Self-healing gates\\nParallel worktrees\\nMulti-model debate\"]\n    end\n\n    subgraph FOR [\"🎯 For the Agents\"]\n        direction TB\n        F1[\"Every file, rule, and doc\\nis designed for agents to parse\"]\n        F2[\"300-line limit · @AX tags\\nStructured Lore · SPEC format\"]\n    end\n\n    OF --\u003e BY --\u003e FOR\n\n    style OF fill:#4c6ef5,stroke:#364fc7,color:#fff\n    style BY fill:#7950f2,stroke:#5f3dc4,color:#fff\n    style FOR fill:#f06595,stroke:#c2255c,color:#fff\n```\n\n| Principle | What It Means |\n|-----------|--------------|\n| **Of the Agents** | 16 specialized agents form a real engineering team — planner, executor, tester, reviewer, security auditor, and more. Not one chatbot. A team. |\n| **By the Agents** | Agents run the pipeline autonomously — self-healing quality gates, parallel worktrees, multi-model debate. Humans set the goal; agents handle the rest. |\n| **For the Agents** | Every file, rule, and document is designed to be parsed by agents, not just read by humans. Structure over prose. That's AX. |\n| **Every Session is Day One** | Agents lose all context between sessions. The harness provides institutional memory — architecture, decisions, conventions — so they start informed, not blank. |\n\n\u003e 🐙 **Autopus doesn't make agents smarter. It makes them informed. That's AX.**\n\n---\n\n## 🔥 What Makes Autopus Different\n\n### 📏 Code That Agents Can Actually Read\n\nMost codebases aren't written for AI. A 1,200-line file overwhelms context windows. Tangled responsibilities confuse intent. Autopus enforces a **hard 300-line limit** on every source file — not for aesthetics, but because **agents work better when each file has one job and fits in one read.**\n\n```\n❌ Traditional:\n   service.go (1,200 lines) → Agent loses context halfway through\n\n✅ Autopus:\n   service.go       (180 lines)  Handler logic\n   service_auth.go  (120 lines)  Auth middleware\n   service_repo.go  (150 lines)  Data access\n   → Every file fits in one context window. Every file has one job.\n```\n\nThis isn't just about file size. The entire harness is **agent-readable by design:**\n\n| Layer | How It's Agent-Friendly |\n|-------|------------------------|\n| **Rules** | Structured markdown with IMPORTANT markers — agents parse, not skim |\n| **Skills** | YAML frontmatter with triggers — agents auto-activate the right skill |\n| **Docs** | Tables over paragraphs, checklists over prose — parseable, not readable |\n| **Code** | ≤ 300 lines, single responsibility, split by concern — fits in one context |\n\n\u003e 🐙 **Human-readable is a bonus. Agent-readable is the requirement.**\n\n### 🤖 AI Agents That Form a Team, Not a Chatbot\n\nAutopus doesn't give you one AI assistant — it gives you a **software engineering team of 16 specialized agents** with defined roles, quality gates, and retry logic.\n\n```\n🧠 Planner        →  Decomposes requirements into tasks\n⚡ Executor ×N    →  Implements code in parallel worktrees\n🧪 Tester         →  Writes tests BEFORE code (TDD enforced)\n✅ Validator       →  Checks build, lint, vet\n🔍 Reviewer       →  TRUST 5 code review\n🛡️ Security       →  OWASP Top 10 audit\n📝 Annotator      →  Documents code with @AX tags\n🏗️ Architect      →  System design decisions\n🔬 Deep Worker    →  Long-running autonomous exploration + implementation\n... and 7 more\n```\n\n### ⚔️ AI Models That Debate Each Other (`--multi`)\n\nOne model has blind spots. **Three models catch each other's mistakes.**\n\nEvery AI model has its own strengths and biases — Claude is thorough but verbose, Codex is fast but sometimes shallow, Gemini brings a different perspective entirely. When you use `--multi`, they don't just work in parallel — they **review, challenge, and build on each other's ideas.**\n\n```bash\n# Add --multi to any command for multi-model intelligence\n/auto idea \"new feature\" --multi          # 3 models brainstorm → cross-pollinate → ICE score\n/auto plan \"new feature\" --multi          # 3 models review your SPEC independently\n/auto go SPEC-ID --multi                  # 3 models debate your code review\n```\n\n```mermaid\nflowchart TB\n    C[\"🔍 Claude\\nIndependent Analysis\"] --\u003e D[\"⚔️ Cross-Pollination\\nEach model sees others' ideas\"]\n    X[\"🔍 Codex\\nIndependent Analysis\"] --\u003e D\n    G[\"🔍 Gemini\\nIndependent Analysis\"] --\u003e D\n    D --\u003e R[\"🔄 Round 2\\nAcknowledge · Integrate · Risk\"]\n    R --\u003e J[\"🏛️ Blind Judge\\nAnonymized scoring\"]\n```\n\n**Why this matters:**\n- A bug that Claude misses, Codex catches. An edge case Codex ignores, Gemini flags.\n- Ideas that one model would never generate emerge from cross-pollination.\n- The blind judge scores anonymized results — no model favoritism.\n- Research shows multi-agent debate produces higher-quality outputs than any single model alone.\n\n\u003e 💡 **`/auto dev` enables `--multi` by default.** Every plan gets multi-model review. Every code review gets cross-checked. You don't have to think about it.\n\n4 strategies: **Consensus** (merge agreements) · **Debate** (adversarial review + judge) · **Pipeline** (chain outputs) · **Fastest** (first wins)\n\n### 🔁 Self-Healing Pipeline (RALF Loop)\n\nQuality gates don't just fail — they **fix themselves and retry.**\n\n```mermaid\nflowchart LR\n    R[\"🔴 RED\\nRun Phase\"] --\u003e G[\"🟢 GREEN\\nGate Check\"]\n    G --\u003e|PASS| Done[\"✅ Next Phase\"]\n    G --\u003e|FAIL| F[\"🔧 REFACTOR\\nFix Issues\"]\n    F --\u003e L[\"🔁 LOOP\\nRetry\"]\n    L --\u003e R\n    L -.-\u003e|\"3× no progress\"| CB[\"⛔ Circuit Break\"]\n\n    style R fill:#ff6b6b,stroke:#c92a2a,color:#fff\n    style G fill:#51cf66,stroke:#2b8a3e,color:#fff\n    style F fill:#ffd43b,stroke:#f08c00,color:#000\n    style L fill:#748ffc,stroke:#4263eb,color:#fff\n    style CB fill:#868e96,stroke:#495057,color:#fff\n```\n\n```bash\n/auto go SPEC-AUTH-001 --auto --loop\n```\n\n```\n🐙 RALF [Gate 2] ──────────────────\n  Iteration: 1/5 │ Issues: 3\n  → spawning executor to fix golangci-lint warnings...\n\n🐙 RALF [Gate 2] ──────────────────\n  Iteration: 2/5 │ Issues: 3 → 0\n  Status: PASS ✅\n```\n\n**RALF = RED → GREEN → REFACTOR → LOOP** — TDD principles applied to the pipeline itself. Built-in circuit breaker prevents infinite loops.\n\n### 🌳 Parallel Agents in Isolated Worktrees\n\nMultiple executors work **simultaneously** — each in its own git worktree. No conflicts. No corruption.\n\n```\nPhase 2: Implementation\n  ├── ⚡ Executor 1 (worktree/T1) → pkg/auth/provider.go     ✓\n  ├── ⚡ Executor 2 (worktree/T2) → pkg/auth/handler.go      ✓\n  └── ⚡ Executor 3 (worktree/T3) → pkg/auth/middleware.go    ✓\n\nPhase 2.1: Merge (task-ID order)\n  ✓ T1 merged → T2 merged → T3 merged → working branch\n```\n\nFile ownership prevents conflicts. GC suppression prevents corruption. Up to **5 concurrent worktrees.**\n\n### 📜 Lore: Your Codebase Never Forgets\n\nEvery commit captures the **why**, not just the what. Queryable forever.\n\n```\nfeat(auth): add OAuth2 provider abstraction\n\nWhy: Need Google + GitHub support, extensible for future providers\nDecision: Interface-based abstraction over direct SDK usage\nAlternatives: Direct SDK calls (rejected: too coupled)\nRef: SPEC-AUTH-001\n\n🐙 Autopus \u003cnoreply@autopus.co\u003e\n```\n\n9 structured trailers. Query with `auto lore query \"why interface?\"`. Stale decisions auto-detected after 90 days.\n\n### 🧪 Autonomous Experiment Loop\n\nLet AI iterate autonomously — measure, keep or discard, repeat.\n\n```bash\n/auto experiment --metric \"go test -bench=BenchmarkProcess\" --direction lower --max-iter 5\n```\n\n```\n🐙 Experiment ───────────────────────\n  Iter 1: baseline  │ 1200 ns/op\n  Iter 2: optimize  │  850 ns/op  ✓ keep (29% improvement)\n  Iter 3: refactor  │  900 ns/op  ✗ discard (regression)\n  Iter 4: cache     │  620 ns/op  ✓ keep (27% improvement)\n  ─────────────────────────────────────\n  Result: 1200 → 620 ns/op (48% improvement)\n```\n\nBuilt-in **circuit breaker** prevents runaway iterations. **Simplicity scoring** penalizes over-complex solutions. Each iteration is a git commit — easy to review or revert.\n\n\u003e ⚠️ **Status: Experimental** — CLI commands (`auto experiment`) are available but skill-level integration is in progress. Core iteration loop works; full pipeline integration is coming.\n\n### 🧠 Pipeline That Learns From Failures\n\nAutopus pipelines don't just fail — they **remember why** and prevent the same mistake next time.\n\n```\nGate 2 FAIL: golangci-lint — unused variable in pkg/auth/\n→ Auto-recorded to .autopus/learnings/pipeline.jsonl\n→ Next /auto go: learning injected into executor prompt\n→ Same mistake never repeated\n```\n\nEvery pipeline failure is captured as a structured learning entry. On the next run, relevant learnings are automatically injected into agent prompts — giving your pipeline **institutional memory** across sessions.\n\n### 🏥 Post-Deploy Health Check\n\nDeploy first, verify immediately. `canary` runs build verification, E2E tests, and browser health checks against your live deployment.\n\n```bash\n/auto canary                          # Build + E2E + browser auto-verification\n/auto canary --url https://myapp.com  # Target a specific deployment URL\n/auto canary --watch 5m               # Repeat every 5 minutes\n/auto canary --compare                # Compare against previous canary report\n```\n\nGenerates `canary.md` with full diagnostics — build status, test results, accessibility scores, and screenshot diffs.\n\n### 🔀 Smart Model Routing\n\nNot every task needs Opus. Autopus analyzes message complexity and routes to the right model automatically.\n\n```\nSimple query     → Haiku  (fast, cheap)\nCode review      → Sonnet (balanced)\nArchitecture     → Opus   (deep reasoning)\n```\n\nNo configuration needed — the router evaluates token count, code complexity, and domain signals to pick the optimal model. Override anytime with `--quality ultra`.\n\n### 🔌 Provider Connection Wizard\n\nSetting up AI providers shouldn't require reading docs. `auto connect` walks you through a 3-step guided setup.\n\n```bash\nauto connect         # Interactive wizard: server auth → workspace → OpenAI OAuth\nauto connect status  # Deterministic local verify/readiness summary\n```\n\nThe current release authenticates with the Autopus server, saves the selected workspace, and completes the OpenAI OAuth handoff. Use `auto connect status` or `auto desktop status --json` to verify the saved local state.\n\nDesktop runtime ownership note:\n- The packaged `autopus-desktop-runtime` source/build/release provenance now lives in `autopus-desktop/runtime-helper/`.\n- ADK keeps `auto connect`, `auto desktop ...`, and `auto worker ...` as harness or compatibility surfaces, but normal desktop runtime shipping no longer depends on an `autopus-adk` checkout.\n\n### 🤖 ADK Worker — Local Agent Execution\n\nADK Worker runs A2A + MCP hybrid tasks locally with browser login, JWT refresh, and direct platform connectivity.\nNo separate bridge daemon or worker API key exchange is required for the default production path.\n\nWhat it is for:\n- Connecting a local workspace to the Autopus platform worker loop\n- Receiving platform-dispatched tasks and executing them with local tools\n- Reusing the same security, budget, and audit rails as the main harness\n\nWhat to do today:\n- If you're here for `auto init`, Codex `@auto ...`, or OpenCode `/auto ...`, you can ignore Worker for now\n- `auto worker ...` is an optional advanced surface that is still being rolled out and documented\n\n### 💰 Iteration Budget Management\n\nWorkers don't run forever. Each executor gets a tool-call budget — preventing runaway agents while ensuring enough room to complete complex tasks.\n\n### 📦 Context Compression\n\nAs pipelines progress through phases, earlier context gets compacted automatically into a fixed schema: Goal, Constraints, Progress, Decisions, Relevant Files, Next Steps, and Critical Context. Tool calls and results are pruned as pairs, unsafe provider payload bodies are omitted, and every applied compaction emits metadata with summary ids, source refs, reason codes, and budget/blocker state.\n\n### 🔄 Pipeline That Never Dies\n\nCrash mid-pipeline? Resume exactly where you left off.\n\n```bash\n/auto go SPEC-AUTH-001 --continue    # Resume from last checkpoint\n```\n\nYAML-based checkpoints save pipeline state after every phase. Stale detection prevents resuming outdated sessions. Combined with `--auto --loop`, you get a **fully resilient autonomous pipeline.**\n\n### 🧪 E2E Scenarios from Your Code\n\nAuto-generate and execute E2E test scenarios — no manual test writing needed.\n\n```bash\nauto test run                    # Run all scenarios\nauto test run -s init --verbose  # Run a specific scenario\n```\n\nAutopus analyzes your codebase (Cobra commands, API routes, frontend pages) and generates typed scenarios with **verification primitives** (`exit_code`, `stdout_contains`, `status_code`, `json_path`, etc.). Incremental sync keeps scenarios up-to-date as code evolves.\n\n### 🌐 Browser Automation — AI Agents That See and Click\n\nAI agents can directly interact with web pages — open URLs, read accessibility trees, click elements, fill forms, and capture screenshots.\n\n```bash\n/auto browse --url https://example.com/settings\n```\n\n```\n- @e1 heading \"AI Settings\"\n- @e2 button \"Provider Mode\"\n- @e3 switch \"Auto Fallback\" [checked]\n- @e7 button \"Save\"\n```\n\nTerminal-aware: automatically selects `cmux browser` (in cmux) or `agent-browser` (fallback). Snapshot → Act → Verify loop — agents see the page as an accessibility tree and interact by reference.\n\n### 📺 Live Agent Dashboard\n\nIn `--team` mode, each team member gets its own terminal pane with real-time log streaming.\n\n```\n┌─ lead ──────────┬─ builder-1 ───────┐\n│ Phase 1: Plan   │ T1: auth.go       │\n│ 5 tasks created │ implementing...   │\n├─ tester ────────┼─ guardian ────────┤\n│ scaffold: 12    │ waiting...        │\n│ RED state ✓     │                   │\n└─────────────────┴───────────────────┘\n```\n\nWorks in cmux and tmux. Plain terminals degrade gracefully to log-only output.\n\n### 📚 Auto-Documentation with Context7\n\nBefore implementation, Autopus fetches latest library docs automatically — so agents never work with stale API knowledge.\n\n```\nPhase 1.8: Doc Fetch\n  → Detected: cobra v1.9, testify v1.11\n  → Fetched: 2 libraries (6000 tokens)\n  → Injected into executor + tester prompts\n```\n\nContext7 MCP → WebSearch fallback → skip (never blocks pipeline). Adaptive token budget: 1 lib → 5000 tokens, 5 libs → 2000 tokens each.\n\n### 🔌 Hook-Based Result Collection\n\nInstead of scraping terminal output, Autopus uses each provider's native hook system to collect structured JSON results.\n\n| Provider | Hook Type | How |\n|----------|-----------|-----|\n| Claude Code | Stop hook | Extracts `last_assistant_message` |\n| Antigravity CLI | AfterAgent hook | Extracts `prompt_response` |\n| OpenCode | Plugin | Extracts `text` field |\n\nFallback: providers without hooks use ReadScreen + idle detection (SPEC-ORCH-006).\n\n### 🔧 More Power Tools\n\n| Feature | Command | What It Does |\n|---------|---------|-------------|\n| **Reaction Engine** | `auto react check/apply` | Detects CI failures, analyzes logs, generates fix reports automatically |\n| **Meta-Agent Builder** | `auto agent create` / `auto skill create` | Scaffold custom agents and skills from patterns |\n| **Hard Gate** | `auto check --gate` | Enforce mandatory pipeline gates (mandatory/advisory modes) |\n| **Self-Update** | `auto update --self` | Atomic binary update — GitHub Releases check + SHA256 verification |\n| **Cost Tracking** | `auto telemetry cost` | Token-based pipeline cost estimation per model |\n| **Issue Reporter** | `auto issue report` | Auto-collect error context, sanitize secrets, create GitHub issues |\n| **Signature Map** | `auto setup` | Extract exported API signatures (Go + TypeScript) via AST analysis |\n| **Test Runner Detection** | `auto init` | Auto-detect jest, vitest, pytest, cargo test frameworks |\n\n### 🌐 One Config, Four Platforms\n\n```bash\nauto init   # auto-detects supported installed AI coding CLIs\n```\n\nOne `autopus.yaml` generates **native configuration** for every detected supported platform.\n\n| Platform | What Gets Generated |\n|----------|-------------------|\n| **Claude Code** | `.claude/rules/`, `.claude/skills/`, `.claude/agents/`, `CLAUDE.md` |\n| **Codex** | `.codex/`, `.agents/skills/`, `.agents/plugins/marketplace.json`, `.autopus/plugins/auto/`, `AGENTS.md` |\n| **Antigravity CLI** | `.gemini/`, `GEMINI.md` |\n| **OpenCode** | `.opencode/rules/`, `.opencode/agents/`, `.opencode/commands/`, `.opencode/plugins/`, `.agents/skills/`, `AGENTS.md`, `opencode.json` |\nSame 16 agents. Same rules. Shared skills stay full by default. If you want a smaller mixed Codex + OpenCode surface without breaking backward-compatible defaults, keep `skills.shared_surface` as-is and opt into `skills.compiler.mode: split`.\n\nCodex note:\n- Use `$auto plan ...`, `$auto go ...`, `$auto idea ...` immediately after `auto init` or `auto update`\n- Install the generated local plugin from the marketplace entry in `.agents/plugins/marketplace.json` (`.autopus/plugins/auto`) to unlock the friendlier `@auto ...` syntax\n- The local plugin provides the `@auto ...` router surface; detailed workflow instructions stay in repo skills and `.codex/prompts/` so Codex does not see duplicate `auto*` skill entries\n- With `skills.compiler.mode: split`, long-tail Codex skills are emitted under `.autopus/plugins/auto/skills/` while repo-visible helper skills stay under `.codex/skills/`\n- `.codex/hooks.json` is still generated by default. The project-local `.codex/config.toml` uses `[features].hooks`; legacy `[features].codex_hooks` should not be emitted.\n\nOpenCode note:\n- `/auto ...` and direct aliases like `/auto-plan ...` are generated under `.opencode/commands/`\n- Native rule/agent/plugin files live under `.opencode/`, while reusable skills are published under `.agents/skills/`\n- With `skills.compiler.mode: split`, shared/core skills stay under `.agents/skills/` while OpenCode long-tail skills move to `.opencode/skills/`\n- Helper workflows like `/auto status`, `/auto map`, `/auto why`, `/auto verify`, `/auto secure`, `/auto test`, `/auto dev`, and `/auto doctor` are generated as OpenCode-native command wrappers\n- `opencode.json` now registers the managed hook plugin automatically, so `.opencode/plugins/autopus-hooks.js` is live immediately after `auto init` or `auto update`\n\n### Codex vs OpenCode\n\n| Topic | Codex | OpenCode |\n|-------|-------|----------|\n| Primary command syntax | `@auto \u003csubcommand\u003e ...` | `/auto \u003csubcommand\u003e ...` |\n| Works immediately after `auto init` | `$auto ...` repo-skill fallback | `/auto ...` and `/auto-\u003csubcommand\u003e ...` wrappers |\n| Extra install step | Yes. Install the generated local plugin from `.agents/plugins/marketplace.json` to enable `@auto ...` | No extra router install step. `opencode.json` wires the managed plugin automatically |\n| Generated surface | `.codex/`, `.agents/skills/`, `.agents/plugins/marketplace.json`, `.autopus/plugins/auto/`, `AGENTS.md` | `.opencode/commands/`, `.opencode/agents/`, `.opencode/rules/`, `.opencode/plugins/`, `.agents/skills/`, `AGENTS.md`, `opencode.json` |\n| What works well today | Core `auto` workflows, repo skills, local plugin-based `@auto` routing | Core `auto` workflows, native command wrappers, managed hook plugin wiring |\n| Current boundary | `@auto ...` depends on local plugin installation; without it, use `$auto ...` | Current parity target is the core workflow surface. Claude-style native settings/statusline breadth is not claimed |\n| Worker surface | Optional for now. Ignore unless you specifically need platform-connected worker execution | Optional for now. Ignore unless you specifically need platform-connected worker execution |\n\nSplit compiler note:\n- `skills.compiler.mode: split` is opt-in. Default `full` keeps the current backward-compatible surface layout.\n- In split mode, `.agents/skills/` is reserved for shared/core skills, `.opencode/skills/` carries OpenCode long-tail skills, and `.autopus/plugins/auto/skills/` carries Codex plugin-scoped long-tail skills.\n\n---\n\n## 🚀 Quick Start Guide\n\nGet from zero to your first AI-powered feature in under 5 minutes.\n\n### Step 1 · Install (one line)\n\n\u003e **Paste this command into your AI coding agent's chat** (Claude Code, Codex, OpenCode, etc.) — the agent will run it for you. Or run it directly in your terminal.\n\n```bash\n# macOS / Linux — installs the binary and checks required tools\ncd your-project    # go to your project folder (e.g., cd ~/my-app)\ncurl -sSfL https://raw.githubusercontent.com/Insajin/autopus-adk/main/install.sh | sh\n\n# Windows (CMD or PowerShell)\ncd your-project\npowershell -c \"irm https://raw.githubusercontent.com/Insajin/autopus-adk/main/install.ps1 | iex\"\n```\n\n**That's it.** The installer installs the `auto` CLI plus an `autopus` alias, checks required tools, skips anything already present, and auto-installs missing essentials like `git`, GitHub CLI, and Antigravity CLI. It does **not** run `auto init` for you.\n\nPlatform command syntax:\n- Codex: install the generated local plugin, then use `@auto ...`; until then, use `$auto ...`\n- OpenCode: use `/auto ...` or `/auto-\u003csubcommand\u003e ...`\n- Claude Code / Antigravity CLI: use `/auto ...`\n\n\u003e Note: If you run the Windows installer from Git Bash via `powershell -c ...`, restart Git Bash after install so it reloads the updated user `PATH`. The installer prints the exact install directory and a one-line `export PATH=...` fallback for that case.\n\n\u003cdetails\u003e\n\u003csummary\u003eOther install methods\u003c/summary\u003e\n\n```bash\n# Homebrew (macOS)\nbrew install insajin/tap/autopus-adk\n\n# go install (requires Go 1.26+)\ngo install github.com/Insajin/autopus-adk/cmd/auto@latest\n\n# Build from source\ngit clone https://github.com/Insajin/autopus-adk.git\ncd autopus-adk \u0026\u0026 make build \u0026\u0026 make install\n\n# After manual install, initialize:\ncd your-project \u0026\u0026 auto init\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eInstaller options (environment variables)\u003c/summary\u003e\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `INSTALL_DIR` | `/usr/local/bin` | Binary install path |\n| `VERSION` | latest | Specific version to install |\n\n\u003c/details\u003e\n\nAfter install, the script explains these commands:\n\n- `auto init`: initialize the current project and generate `autopus.yaml` plus platform files\n- `auto update --self`: update the `auto` CLI binary itself\n- `auto update`: refresh rules, skills, agents, and other generated harness files in your project\n\n### Step 2 · Initialize the Project\n\n```bash\ncd your-project\nauto init\n```\n\n`auto init` scans your machine for supported installed AI coding CLIs (Claude Code, Codex, Antigravity CLI, OpenCode) and generates **native configuration** for each one — rules, skills, agents, and platform-specific settings — all from a single `autopus.yaml`.\n\nClaude Code statusline note:\n- If `.claude/settings.json` already has a `statusLine.command`, `auto init` / `auto update` now lets you choose `keep`, `merge`, or `replace` in interactive mode.\n- You can force the same behavior non-interactively with `--statusline-mode keep|merge|replace`.\n\n```\n✓ Detected: claude-code, codex, antigravity-cli, opencode\n✓ Generated: .claude/rules/, .claude/skills/, .claude/agents/, CLAUDE.md\n✓ Generated: .codex/, AGENTS.md\n✓ Generated: .gemini/, GEMINI.md\n✓ Generated: .opencode/, .agents/skills/, AGENTS.md, opencode.json\n✓ Created: autopus.yaml\n```\n\n### Step 3 · Set Up Project Context (`/auto setup`)\n\nThis is the most important step. **AI agents lose all memory between sessions** — every conversation is their first day on the job. `/auto setup` creates the \"onboarding documents\" that let agents understand your project instantly.\n\n```bash\n/auto setup     # Claude Code, Antigravity CLI, OpenCode\n@auto setup     # Codex after local plugin install\n$auto setup     # Codex fallback before plugin install\n```\n\nThis analyzes your codebase and generates 5 context documents:\n\n```\nARCHITECTURE.md                    # Domains, layers, dependency map\n.autopus/project/product.md       # What this project does, core features\n.autopus/project/structure.md     # Directory layout, package roles, entry points\n.autopus/project/tech.md          # Tech stack, build system, testing strategy\n.autopus/project/scenarios.md     # E2E test scenarios extracted from code\n```\n\n\u003e 💡 **Why this matters:** Without these documents, an AI agent looking at your project is like a new hire with no onboarding — they'll guess at architecture, miss conventions, and reinvent patterns that already exist. With `/auto setup`, every agent session starts informed.\n\n### Optional `DESIGN.md` for UI Work\n\nFrontend verification and review can use a project-local `DESIGN.md` as lightweight design context. `auto init` creates a starter `DESIGN.md` next to `autopus.yaml` without overwriting an existing one, and `auto update` backfills the starter plus the `design:` config block for older harness installs. Keep it short and include the source of truth, palette roles, typography hierarchy, component guardrails, layout/responsive rules, and agent guidance. If a project has no `DESIGN.md` or configured design baseline, `/auto verify`, Phase 3.5, `/auto review`, and `auto orchestra review` continue normally and report `Design context: skipped (not configured)` as a non-error condition.\n\nDesign context is only injected for UI-related diffs such as `.tsx`, `.jsx`, CSS-family files, theme/token files, or design-system paths. UI findings check palette-role drift, typography hierarchy drift, component guardrail violations, layout/responsive regressions, and source-of-truth mismatch. Review surfaces remain read-only; they report issues and delegate fixes instead of editing files directly.\n\nGenerated platform surfaces are not canonical. Update `autopus-adk` content/templates and run `auto update` to refresh `.claude/*`, `.codex/*`, `.gemini/*`, `.opencode/*`, `.agents/skills/*`, and plugin surfaces in a target project.\n\nExternal design references are untrusted until explicitly promoted. `auto design import` stores sanitized artifacts under `.autopus/design/imports/\u003cimport-id\u003e/`; it must not replace a human-maintained `DESIGN.md` by default. URL imports are public-HTTPS-only and SSRF-guarded: they reject local/private/metadata targets and unsafe redirects, cap redirects, timeout, and response size, and persist only redacted diagnostics when rejected.\n\n### Step 4 · Build Your First Feature\n\nNow you're ready. Describe what you want in plain language:\n\n```bash\n# 1. Plan — AI creates a full SPEC (requirements, tasks, acceptance criteria)\n/auto plan \"Add a health check endpoint at GET /healthz\"\n\n# 2. Build — 16 agents handle implementation, testing, and review\n/auto go SPEC-HEALTH-001 --auto\n\n# 3. Ship — Sync docs, update SPEC status, commit with decision history\n/auto sync SPEC-HEALTH-001\n```\n\n```\n╭────────────────────────────────────╮\n│ 🐙 Pipeline Complete!              │\n│ SPEC-HEALTH-001: Health Check      │\n│ Tasks: 3/3 │ Coverage: 92%         │\n│ Review: APPROVE                    │\n╰────────────────────────────────────╯\n```\n\nThat's it — production-ready code with tests, security audit, and full documentation.\n\n### Quick Reference\n\n| What you want | Command |\n|--------------|---------|\n| **Brainstorm an idea** | `/auto idea \"description\" --multi --ultrathink` |\n| **Full cycle (recommended)** | `/auto dev \"description\"` |\n| Plan a new feature | `/auto plan \"description\"` |\n| Implement a SPEC | `/auto go SPEC-ID --auto --loop --team` |\n| Fix a bug (no SPEC needed) | `/auto fix \"description\"` |\n| Just describe in plain language | `/auto Add 2FA to login page` |\n| Post-deploy health check | `/auto canary` |\n| Code review | `/auto review` |\n| Security audit | `/auto secure` |\n| Resume interrupted pipeline | `/auto go SPEC-ID --continue` |\n| Update docs after changes | `/auto sync SPEC-ID` |\n\n### Keeping Autopus Up to Date\n\nAutopus has two types of updates:\n\n**1. Binary update** — update the `auto` CLI itself:\n\n```bash\nauto update --self\n```\n\nDownloads the latest release from GitHub, verifies SHA256 checksum, and atomically replaces the binary. Check your current version with `auto version`.\n\n**2. Harness update** — update rules, skills, and agents in your project:\n\n```bash\nauto update\n```\n\nRegenerates `.claude/*`, `.codex/*`, `.gemini/*`, `.opencode/*`, `.agents/skills/*`, and other platform-specific files from the latest templates. With `skills.compiler.mode: split`, the update preview/apply flow also manages `.opencode/skills/*` and `.autopus/plugins/auto/skills/*`, including stale artifact pruning. Your custom edits outside `AUTOPUS:BEGIN`~`AUTOPUS:END` markers are preserved. Newly installed platforms are auto-detected.\n\nIf Claude Code already has a user-managed `statusLine.command`, the update flow defaults to preserving it, can merge it with the managed Autopus statusline, or replace it entirely via `--statusline-mode keep|merge|replace`.\n\n**Both at once:**\n\n```bash\nauto update --self \u0026\u0026 auto update\n```\n\n\u003e **When to update:** Run `auto update --self` when a new version is released. Then `auto update` to get new rules, skills, and agents into your project.\n\n### Common Scenarios\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\"I want to fix a bug\"\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\n/auto fix \"500 error on login page\"\n```\n\nThe agent automatically:\n1. Writes a reproduction test (confirms failure)\n2. Analyzes root cause\n3. Applies minimal fix\n4. Verifies all tests pass\n\nNo SPEC needed — runs immediately.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\"I want to add a new feature\"\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\n# Small feature — SPEC only, skip PRD\n/auto plan \"Add GET /healthz health check endpoint\" --skip-prd\n\n# Large feature — full PRD + SPEC\n/auto plan \"OAuth2 Google + GitHub provider support\"\n\n# Exploring an idea first — multi-provider brainstorm\n/auto idea \"Should we migrate to microservices?\" --multi\n```\n\n`/auto idea` runs multi-provider brainstorming with ICE scoring (Impact, Confidence, Ease), generates a BS file, and can chain directly into `/auto plan`.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\"I want a code review\"\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\n/auto review                    # TRUST 5 review of current changes\n/auto secure                    # OWASP Top 10 security scan\n/auto review --multi            # Multi-model cross-review (debate strategy)\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\"I just want to describe what I need in plain language\"\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\n/auto Add 2FA to the login page\n```\n\nAutopus Triage analyzes your request automatically:\n- Complexity assessment (LOW / MEDIUM / HIGH)\n- Impact scope scan\n- Recommended workflow (fix / plan / idea)\n\n```\n🐙 Triage ────────────────────────────\n  Request: \"Add 2FA to the login page\"\n  Complexity: HIGH → /auto idea --multi (recommended)\n```\n\nFor Codex, use `@auto ...` after installing the generated local plugin from `.agents/plugins/marketplace.json`, or use `$auto ...` immediately as the repo-skill fallback. The plugin only adds the router surface; detailed workflow instructions continue to live in repo skills and `.codex/prompts/`.\n\u003c/details\u003e\n\n---\n\n## 🤖 The Pipeline\n\n### 7-Phase Multi-Agent Pipeline\n\nEvery `/auto go` runs this:\n\n```mermaid\nsequenceDiagram\n    participant S as SPEC\n    participant P as 🧠 Planner\n    participant T as 🧪 Tester\n    participant E as ⚡ Executor ×N\n    participant A as 📝 Annotator\n    participant V as ✅ Validator\n    participant R as 🔍 Reviewer + 🛡️\n\n    S-\u003e\u003eP: Phase 1: Task decomposition + agent assignment\n    P-\u003e\u003eT: Phase 1.5: Scaffold failing tests (RED)\n\n    rect rgb(230, 245, 255)\n        Note over E: Phase 2: TDD in parallel worktrees\n        T-\u003e\u003eE: T1, T2, T3 ... (parallel)\n    end\n\n    E-\u003e\u003eA: Phase 2.5: @AX tag management\n    A-\u003e\u003eV: Gate 2: Build + lint + vet\n    V-\u003e\u003eT: Phase 3: Coverage → 85%+\n    T-\u003e\u003eR: Phase 4: TRUST 5 + OWASP audit\n    R--\u003e\u003eS: ✅ APPROVE\n```\n\n### 16 Specialized Agents\n\n| Agent | Role | When |\n|-------|------|------|\n| **Planner** | SPEC decomposition, task assignment, complexity assessment | Phase 1 |\n| **Spec Writer** | Generate spec.md, plan.md, acceptance.md, research.md | `/auto plan` |\n| **Tester** | Test scaffold (RED) + coverage boost (GREEN) | Phase 1.5, 3 |\n| **Executor** | TDD implementation in parallel worktrees | Phase 2 |\n| **Annotator** | @AX tag lifecycle management | Phase 2.5 |\n| **Validator** | Build, vet, lint, file size checks | Gate 2 |\n| **Reviewer** | TRUST 5 code review | Phase 4 |\n| **Security Auditor** | OWASP Top 10 vulnerability scan | Phase 4 |\n| **Architect** | System design, architecture decisions | on-demand |\n| **Debugger** | Reproduction-first bug fixing | `/auto fix` |\n| **DevOps** | CI/CD, Docker, infrastructure | on-demand |\n| **Frontend Specialist** | Playwright E2E + VLM visual regression | Phase 3.5 |\n| **UX Validator** | Frontend component visual validation | Phase 3.5 |\n| **Perf Engineer** | Benchmark, pprof, regression detection | on-demand |\n| **Deep Worker** | Long-running autonomous exploration + implementation | on-demand |\n| **Explorer** | Codebase structure analysis | `/auto map` |\n\n### Quality Modes\n\n```bash\n/auto go SPEC-ID --quality ultra      # All agents on Opus — max quality\n/auto go SPEC-ID --quality balanced   # Adaptive: Opus/Sonnet/Haiku by task complexity\n```\n\n```mermaid\nflowchart LR\n    subgraph Ultra [\"🔥 Ultra — All Opus\"]\n        U1[\"Planner\\nOpus\"] --\u003e U2[\"Executor\\nOpus\"] --\u003e U3[\"Validator\\nOpus\"]\n    end\n\n    subgraph Balanced [\"⚖️ Balanced — Adaptive\"]\n        B1[\"Planner\\nOpus\"] --\u003e B2[\"Executor\\nby complexity\"]\n        B2 --\u003e|HIGH| BH[\"Opus\"]\n        B2 --\u003e|MEDIUM| BM[\"Sonnet\"]\n        B2 --\u003e|LOW| BL[\"Haiku\"]\n    end\n\n    style Ultra fill:#fff3bf,stroke:#f08c00\n    style Balanced fill:#d0ebff,stroke:#1971c2\n```\n\n| Mode | Planner | Executor | Validator | Cost |\n|------|---------|----------|-----------|------|\n| **Ultra** | Opus | Opus | Opus | $$$ |\n| **Balanced** | Opus | Adaptive* | Haiku | $ |\n\n\\* HIGH complexity → Opus · MEDIUM → Sonnet · LOW → Haiku\n\n### Execution Modes\n\n| Flag | Mode | Description |\n|------|------|-------------|\n| *(default)* | Subagent pipeline | Main session orchestrates Agent() calls |\n| `--team` | Agent Teams | Lead / Builder / Guardian role-based teams |\n| `--solo` | Single session | No subagents, direct TDD |\n| `--auto --loop` | Full autonomy | RALF self-healing, no human gates |\n| `--multi` | Multi-provider | Debate/consensus review with multiple models |\n\n---\n\n## 📐 The Workflow\n\n### ⚡ The Fast Path — Two Commands\n\nFor most features, you only need two commands:\n\n```bash\n# 1. Brainstorm — multi-provider debate + deep analysis\n/auto idea \"Add webhook delivery with retry\" --multi --ultrathink\n\n# 2. Build \u0026 Ship — full autonomous pipeline\n/auto dev \"Add webhook delivery with retry\"\n```\n\n`/auto idea` runs multi-provider brainstorming (Claude × Codex × Gemini debate) with deep sequential thinking, scores ideas with ICE, and saves the result.\n\n`/auto dev` does the rest — **plan → go → sync** in one shot with all the power flags on by default:\n\n| Stage | What Happens | Flags (auto-applied) |\n|-------|-------------|---------------------|\n| **plan** | PRD + SPEC + multi-provider review | `--auto --multi --ultrathink` |\n| **go** | 16 agents in Agent Teams + self-healing | `--auto --loop --team` |\n| **sync** | Docs + changelog + Lore commit | — |\n\n\u003e 💡 **Don't want the full power?** Use `--solo` for single-session mode, `--no-multi` to skip multi-provider review, or call `plan` / `go` / `sync` individually for fine-grained control.\n\n### 📋 The Manual Path — Three Commands\n\nFor more control, run each stage separately:\n\n```mermaid\nflowchart LR\n    PLAN[\"📋 plan\\nDescribe\"] --\u003e|SPEC created| GO[\"🚀 go\\nBuild\"]\n    GO --\u003e|Code + Tests| SYNC[\"📦 sync\\nShip\"]\n```\n\n### 📋 Step 1 · `/auto plan` — Describe What You Want\n\nTurn a plain-English description into a full **SPEC** — requirements, tasks, acceptance criteria, and risk analysis.\n\n```bash\n/auto plan \"Add webhook delivery with retry and dead letter queue\"\n```\n\nThe spec-writer agent produces 5 documents:\n\n```\n.autopus/specs/SPEC-HOOK-001/\n├── prd.md          # Product Requirements Document\n├── spec.md         # EARS-format requirements\n├── plan.md         # Task breakdown + agent assignments\n├── acceptance.md   # Given-When-Then criteria\n└── research.md     # Technical research + risks\n```\n\nOptions: `--multi` for multi-provider review · `--prd-mode minimal` for lightweight PRDs · `--skip-prd` to go straight to SPEC\n\n### 🚀 Step 2 · `/auto go` — Build It\n\nFeed the SPEC to **16 agents** that plan, scaffold tests, implement in parallel, validate, annotate, test, and review — all automatically.\n\n```bash\n/auto go SPEC-HOOK-001 --auto --loop\n```\n\n```\nPhase 1    │ 🧠 Planner         │ SPEC → tasks + agent assignments\nPhase 1.5  │ 🧪 Tester          │ Failing test skeletons (RED)\nPhase 2    │ ⚡ Executor ×N      │ TDD in parallel worktrees\nPhase 2.5  │ 📝 Annotator       │ @AX documentation tags\nGate  2    │ ✅ Validator        │ Build + lint + vet\nPhase 3    │ 🧪 Tester          │ Coverage → 85%+\nPhase 4    │ 🔍 Reviewer + 🛡️    │ TRUST 5 + OWASP audit\n```\n\nOptions: `--team` for Agent Teams · `--solo` for single-session TDD · `--quality ultra` for all-Opus execution · `--multi` for multi-model review\n\n### 📦 Step 3 · `/auto sync` — Ship and Document\n\nUpdate SPEC status, regenerate project docs, manage @AX tag lifecycle, and commit with structured Lore history.\n\n```bash\n/auto sync SPEC-HOOK-001\n```\n\n```\n╭────────────────────────────────────╮\n│ 🐙 Pipeline Complete!              │\n│ SPEC-HOOK-001: Webhook Delivery    │\n│ Tasks: 5/5 │ Coverage: 91%         │\n│ Review: APPROVE                    │\n╰────────────────────────────────────╯\n```\n\n**That's it.** Three commands: describe → build → ship. Every decision recorded. Every test enforced.\n\n---\n\n## 🎯 TRUST 5 Code Review\n\nEvery review scores across 5 dimensions:\n\n| | Dimension | What It Checks |\n|---|-----------|----------------|\n| **T** | Tested | 85%+ coverage, edge cases, `go test -race` |\n| **R** | Readable | Clear naming, single responsibility, ≤ 300 LOC |\n| **U** | Unified | gofmt, goimports, golangci-lint, consistent patterns |\n| **S** | Secured | OWASP Top 10, no injection, no hardcoded secrets |\n| **T** | Trackable | Meaningful logs, error context, SPEC/Lore references |\n\n---\n\n## 📊 Multi-Model Orchestration\n\n| Strategy | How It Works | Best For |\n|----------|-------------|----------|\n| **🤝 Consensus** | Independent answers merged by key agreement | Planning, code review |\n| **⚔️ Debate** | 2-phase adversarial review + judge verdict | Critical decisions, security |\n| **🔗 Pipeline** | Provider N's output → Provider N+1's input | Iterative refinement |\n| **⚡ Fastest** | First completed response wins | Quick queries |\n\nProviders: **Claude** · **Codex** · **Gemini** · **OpenCode** — with graceful degradation.\n\n**Interactive debate** with real-time pane visualization (cmux/tmux). **Hook-based result collection** for structured JSON output. **WebSearch fallback** when Context7 docs are unavailable.\n\n---\n\n## 📖 All Commands\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eCLI Commands\u003c/strong\u003e (28 root commands, 110+ total with subcommands)\u003c/summary\u003e\n\n| Command | Description |\n|---------|-------------|\n| `auto init` | Initialize harness — detect platforms, generate files |\n| `auto update` | Update harness (preserves user edits via markers) |\n| `auto doctor` | Health diagnostics |\n| `auto platform` | Manage platforms (list / add / remove) |\n| `auto arch` | Architecture analysis (generate / enforce) |\n| `auto spec` | SPEC management (new / validate / review) |\n| `auto lore` | Decision tracking (context / commit / validate / stale) |\n| `auto orchestra` | Multi-model orchestration (review / plan / secure / brainstorm / job-status / job-wait / job-result) |\n| `auto setup` | Project context documents (generate / update / validate / status) |\n| `auto status` | SPEC dashboard (done / in-progress / draft) |\n| `auto telemetry` | Pipeline telemetry (record / summary / cost / compare) |\n| `auto skill` | Skill management (list / info / create) |\n| `auto search` | Knowledge search (Exa) |\n| `auto docs` | Library documentation lookup (Context7) |\n| `auto lsp` | LSP integration (diagnostics / refs / rename / symbols / definition) |\n| `auto verify` | Frontend UX verification (Playwright + VLM) |\n| `auto check` | Harness rule checks (anti-pattern scanning) |\n| `auto hash` | File hashing (xxhash) |\n| `auto issue` | Auto issue reporter (report / list / search) |\n| `auto experiment` | Autonomous experiment loop (init / metric / record / commit / reset / summary / status) |\n| `auto test` | E2E scenario runner (run) |\n| `auto react` | Reaction engine (check / apply) |\n| `auto agent` | Agent management (create / run) |\n| `auto terminal` | Terminal multiplexer management (detect / workspace / split / send / notify) |\n| `auto pipeline` | Pipeline state management and monitoring |\n| `auto permission` | Permission mode detection (bypass / safe) |\n| `auto browse` | Browser automation (cmux browser / agent-browser) |\n| `auto canary` | Post-deploy health check (build + E2E + browser) |\n| `auto connect` | Provider connection wizard (server auth → workspace → OpenAI OAuth) |\n| `auto connect status` | Local verify/readiness summary for saved connect state |\n| `auto update --self` | CLI binary self-update (GitHub Releases + SHA256) |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eSlash Commands\u003c/strong\u003e (inside AI Coding CLI)\u003c/summary\u003e\n\n| Command | Description |\n|---------|-------------|\n| `/auto plan \"description\"` | Create a SPEC for a new feature |\n| `/auto go SPEC-ID` | Implement with full pipeline |\n| `/auto go SPEC-ID --auto --loop` | Fully autonomous + self-healing |\n| `/auto go SPEC-ID --team` | Agent Teams (Lead/Builder/Guardian) |\n| `/auto go SPEC-ID --multi` | Multi-provider orchestration |\n| `/auto fix \"bug\"` | Reproduction-first bug fix |\n| `/auto review` | TRUST 5 code review |\n| `/auto secure` | OWASP Top 10 security audit |\n| `/auto map` | Codebase structure analysis |\n| `/auto sync SPEC-ID` | Sync docs after implementation |\n| `/auto dev \"description\"` | Full power: plan(--multi --ultrathink) → go(--team --loop) → sync |\n| `/auto setup` | Generate/update project context docs |\n| `/auto stale` | Detect stale decisions and patterns |\n| `/auto why \"question\"` | Query decision rationale |\n| `/auto experiment` | Autonomous experiment loop (metric-driven iteration) |\n| `/auto test` | Run E2E scenarios against your project |\n| `/auto go SPEC-ID --continue` | Resume interrupted pipeline from checkpoint |\n| `/auto browse` | Browser automation — open, snapshot, click, verify |\n| `/auto idea \"description\"` | Multi-provider brainstorm with ICE scoring |\n| `/auto canary` | Post-deploy health check (build + E2E + browser) |\n\n\u003c/details\u003e\n\n---\n\n## ⚙️ Configuration\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\u003ccode\u003eautopus.yaml\u003c/code\u003e\u003c/strong\u003e — single config for everything\u003c/summary\u003e\n\n```yaml\nmode: full                    # full or lite\nproject_name: my-project\nplatforms:\n  - claude-code\n\narchitecture:\n  auto_generate: true\n  enforce: true\n\nlore:\n  enabled: true\n  required_trailers: [Why, Decision]\n  stale_threshold_days: 90\n\nspec:\n  review_gate:\n    enabled: true\n    strategy: debate\n    providers: [claude, gemini]\n    judge: claude\n\nmethodology:\n  mode: tdd\n  enforce: true\n\norchestra:\n  enabled: true\n  default_strategy: consensus\n  providers:\n    claude:\n      binary: claude\n    codex:\n      binary: codex\n    gemini:\n      binary: agy\n    opencode:\n      binary: opencode\n```\n\n\u003c/details\u003e\n\n---\n\n## 🏗️ Architecture\n\n```\nautopus-adk/\n├── cmd/auto/           # Entry point\n├── internal/cli/       # 28 Cobra commands (110+ total with subcommands)\n├── pkg/\n│   ├── adapter/        # 4 platform adapters (Claude, Codex, Gemini, OpenCode)\n│   ├── arch/           # Architecture analysis + rule enforcement\n│   ├── browse/         # Browser automation backend (cmux/agent-browser routing)\n│   ├── config/         # Configuration schema + YAML loading\n│   ├── constraint/     # Anti-pattern scanning\n│   ├── content/        # Agent/skill/hook/profile generation + skill activator\n│   ├── cost/           # Token-based cost estimator\n│   ├── detect/         # Platform/framework/permission detection\n│   ├── e2e/            # E2E scenario generation, execution, verification\n│   ├── experiment/     # Autonomous experiment loop (metric, circuit breaker)\n│   ├── issue/          # Auto issue reporter (context collection, sanitization)\n│   ├── lore/           # Decision tracking (9-trailer protocol)\n│   ├── lsp/            # LSP integration\n│   ├── orchestra/      # Multi-model orchestration (4 strategies + brainstorm + interactive debate + hooks)\n│   ├── pipeline/       # Pipeline state persistence + checkpoint + team monitor\n│   ├── search/         # Knowledge search (Context7/Exa) + hash-based search\n│   ├── selfupdate/     # CLI binary self-update (SHA256, atomic replace)\n│   ├── setup/          # Project doc generation + validation\n│   ├── sigmap/         # AST-based API signature extraction (Go + TypeScript)\n│   ├── spec/           # EARS requirement parsing/validation\n│   ├── telemetry/      # Pipeline telemetry (JSONL event recording)\n│   ├── template/       # Go template rendering\n│   ├── terminal/       # Terminal multiplexer adapters (cmux, tmux, plain)\n│   └── version/        # Build metadata\n├── templates/          # Platform-specific templates\n├── content/            # Embedded content (16 agents, 40 skills)\n└── configs/            # Default configuration\n```\n\n---\n\n## 🔒 Security\n\n### 🛡️ Supply Chain Attack Protection\n\n\u003e *\"A popular Python package with tens of millions of monthly downloads was injected with malicious code. A simple `pip install` could steal SSH keys, AWS credentials, and DB passwords — not from the package you installed, but from somewhere deep in its dependency tree.\"* — [Andrej Karpathy](https://x.com/karpathy)\n\nAI coding environments make this worse: agents auto-install packages, expand dependency trees, and execute code — all without human review. **Autopus builds defense into the pipeline itself.**\n\n#### How Autopus Protects Your Development Workflow\n\n| Layer | Protection | How |\n|-------|-----------|-----|\n| **Pipeline Gate** | Dependency vulnerability scan at every `/auto go` | Security Auditor agent runs `govulncheck ./...` in Phase 4 |\n| **Secret Detection** | Hardcoded credentials caught before commit | `gitleaks detect` scans all changed files |\n| **Dependency Audit** | Known CVE detection in dependency tree | `go list -m -json all \\| nancy sleuth` for Go projects |\n| **Lock File Integrity** | Checksum-verified dependencies | Go's `go.sum` ensures reproducible, tamper-proof builds |\n| **OWASP Top 10** | Injection, auth bypass, SSRF — all checked | Security Auditor covers A01–A10 systematically |\n| **AI Agent Guardrails** | Agents can't blindly install packages | Harness rules constrain agent actions; security gate blocks deploy on FAIL |\n\n#### For Non-Go Projects\n\nThe same principles apply when Autopus manages Python, Node.js, or other ecosystems:\n\n```yaml\n# autopus.yaml — configure per-ecosystem security scans\nsecurity:\n  scanners:\n    go: \"govulncheck ./...\"\n    python: \"pip-audit \u0026\u0026 safety check\"\n    node: \"npm audit --audit-level=high\"\n```\n\n**Best practices enforced by the harness:**\n- **Version pinning** — Lock all dependencies to exact versions (`go.sum`, `package-lock.json`, `requirements.txt`)\n- **Minimal dependencies** — The 300-line file limit and single-responsibility rule naturally reduce unnecessary imports\n- **Isolation** — Parallel executors run in isolated git worktrees; no cross-contamination between tasks\n- **No blind installs** — Security Auditor agent flags unknown or unvetted packages before they enter the codebase\n\n### Binary Distribution Safety\n\nEvery binary release includes **SHA256 checksums** (`checksums.txt`), verified automatically during installation. No blind `curl | sh` — every download is integrity-checked before execution.\n\n**Recommended: Inspect before you install**\n\n```bash\n# 1. Download the script first — review it before running\ncurl -sSfL https://raw.githubusercontent.com/Insajin/autopus-adk/main/install.sh -o install.sh\nless install.sh          # Read what it does\nsh install.sh            # Run only after review\n```\n\n**Or verify manually:**\n\n```bash\n# Download binary + checksums separately\nVERSION=$(curl -s https://api.github.com/repos/Insajin/autopus-adk/releases/latest | grep tag_name | sed 's/.*\"v\\(.*\\)\".*/\\1/')\ncurl -LO \"https://github.com/Insajin/autopus-adk/releases/download/v${VERSION}/autopus-adk_${VERSION}_$(uname -s | tr A-Z a-z)_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz\"\ncurl -LO \"https://github.com/Insajin/autopus-adk/releases/download/v${VERSION}/checksums.txt\"\n\n# Verify SHA256\nshasum -a 256 -c checksums.txt --ignore-missing\n```\n\n`auto update --self` also verifies SHA256 checksums before replacing the binary.\n\n### What We Don't Do\n\n- No telemetry or analytics collection\n- No network calls except explicit commands (`orchestra`, `search`, `update --self`)\n- No access to your AI provider API keys — Autopus orchestrates CLI tools, not API calls\n\n---\n\n## 🤝 Contributing\n\nAutopus-ADK is open source under the MIT license. PRs welcome!\n\n```bash\nmake test       # Run tests with race detection\nmake lint       # Run go vet\nmake coverage   # Generate coverage report\n```\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**🐙 Autopus** — Of the agents. By the agents. For the agents.\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finsajin%2Fautopus-adk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finsajin%2Fautopus-adk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finsajin%2Fautopus-adk/lists"}