Skip to content
Back to search

aos-harness

MarketplaceWorks with Claude CodeGitHub

The AOS plugin for Claude Code, served from the AOS Harness repository.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/aos-engineer--harness/badge.svg)](/listings/aos-engineer--harness)

HTML

<a href="/listings/aos-engineer--harness"><img src="/api/listings/aos-engineer--harness/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

You need Claude Code 2.1.295 or later, [Bun](https://bun.sh) 1.3.11 or later on `PATH`, and git. Install the plugin in Claude Code:

/plugin install aos --marketplace aos-engineer/harness

Then install the CLI, which is how you approve gates and check runs:

npm install -g aos-harness@next    # or: bun add -g aos-harness@next

The reference pack's stages name skills from the [superpowers](https://github.com/obra/superpowers) plugin, so installing it is recommended; without it the agent follows each stage's written instructions.

Start a run with `/aos:run <your request>`. [Getting started](docs/1.0/getting-started.md) walks through a first run, the two-step plugin install, pinning a release, and uninstalling.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 15 lines
  1. {
  2. "name": "aos-harness",
  3. "owner": {
  4. "name": "aos-engineer",
  5. "url": "https://github.com/aos-engineer"
  6. },
  7. "description": "The AOS plugin for Claude Code, served from the AOS Harness repository.",
  8. "plugins": [
  9. {
  10. "name": "aos",
  11. "source": "./hosts/claude-code",
  12. "description": "AOS run gates for Claude Code: risk-tiered stages, observed test evidence, and human approvals before an agent may push, open a PR, or deploy."
  13. }
  14. ]
  15. }
README.md · README · 354 lines
  1. # AOS Harness
  2. > **`main` is AOS 1.0 development.** 1.0 prereleases publish on the npm `next` tag. The released 0.x line (npm `latest`) lives on the `release/0.11` branch and tag `v0.11.0`.
  3. [![CI](https://github.com/aos-engineer/harness/actions/workflows/ci.yml/badge.svg)](https://github.com/aos-engineer/harness/actions/workflows/ci.yml)
  4. ## AOS 1.0 on `main`
  5. AOS 1.0 runs inside the coding agent you already use. A run splits one piece of work into stages (for a bounded change: design, build, verify), and each stage ends at a gate that passes only on evidence: test runs AOS observed itself, reviews the agent records, and approvals only a person can give from their own terminal. Push and pull request creation wait for the last gate, and deploys are never allowed inside a run. Every run is an append-only, hash-chained log under `.aos/runs/`, so an edit that breaks the chain is detectable and its gate verdicts can be re-derived from the log. The chain is not signed: a process that rewrites the whole log consistently is not detected.
  6. Claude Code is the first host, and 1.0 is in prerelease. AOS is a guardrail for a cooperating agent, not a security boundary; [the security model](docs/1.0/security.md) says what it does not defend.
  7. ### Install
  8. You need Claude Code 2.1.295 or later, [Bun](https://bun.sh) 1.3.11 or later on `PATH`, and git. Install the plugin in Claude Code:
  9. ```
  10. /plugin install aos --marketplace aos-engineer/harness
  11. ```
  12. Then install the CLI, which is how you approve gates and check runs:
  13. ```bash
  14. npm install -g aos-harness@next # or: bun add -g aos-harness@next
  15. ```
  16. The reference pack's stages name skills from the [superpowers](https://github.com/obra/superpowers) plugin, so installing it is recommended; without it the agent follows each stage's written instructions.
  17. Start a run with `/aos:run <your request>`. [Getting started](docs/1.0/getting-started.md) walks through a first run, the two-step plugin install, pinning a release, and uninstalling.
  18. ### Documentation
  19. - [Getting started](docs/1.0/getting-started.md), [concepts](docs/1.0/concepts.md), and [troubleshooting](docs/1.0/troubleshooting.md)
  20. - Reference: [CLI](docs/1.0/cli.md), [MCP tools](docs/1.0/mcp-tools.md), [packs](docs/1.0/packs.md), and the [security model](docs/1.0/security.md)
  21. - For contributors: [CONTRIBUTING.md](CONTRIBUTING.md), [architecture](docs/1.0/architecture.md), and [releasing](docs/1.0/releasing.md)
  22. - [The docs index](docs/README.md), which also explains the 0.x material under `docs/`
  23. ### Repository layout
  24. ```
  25. kernel/ @aos-harness/kernel: run log, projection, gates, packs, shell semantics, hook logic
  26. src/mcp/ the MCP server, exported as @aos-harness/kernel/mcp
  27. hosts/claude-code/ the Claude Code plugin: manifest, hooks, MCP registration, the /aos:run skill
  28. packs/feature-delivery/ the reference methodology pack (data only)
  29. cli/ the aos CLI: approve, status, doctor, run cancel, mcp
  30. tests/e2e/ bounded and spike runs driven through the MCP tools and the real hook command
  31. core/ 0.x agent, profile, and domain content, still read by the docs site
  32. site/ the docs site (Astro)
  33. ```
  34. ### Development
  35. ```bash
  36. bun install
  37. bun run test # every test suite
  38. bun run lint # YAML safety check and typecheck
  39. bun run scripts/bench-hook.ts # hook latency benchmark
  40. ```
  41. [CONTRIBUTING.md](CONTRIBUTING.md) has the full setup, the rules tests and kernel code follow, and the pull request flow.
  42. ---
  43. ## AOS 0.x
  44. > Everything below documents the 0.x line published on npm as `aos-harness@latest`. Its source, including `runtime/`, `adapters/`, and `plugins/aos-harness/`, is on the [`release/0.11`](https://github.com/aos-engineer/harness/tree/release/0.11) branch.
  45. **Agentic Orchestration System.** Assemble specialized AI agents into deliberation and execution teams.
  46. ## What It Is
  47. AOS Harness is a language-agnostic orchestration system for multi-agent AI workflows. It supports two orchestration patterns:
  48. - **Deliberation**: Agents debate a strategic question, the Arbiter synthesizes ranked recommendations with documented dissent. Output: structured memo.
  49. - **Execution**: A CTO/CIO/CEO orchestrator delegates production work to agents who produce architecture, task breakdowns, security reviews, and implementation plans. Output: execution package.
  50. The harness ships with:
  51. - 15 agent personas with distinct cognitive biases and reasoning frameworks
  52. - 9 orchestration profiles, including strategic-council, cto-execution, security-review, delivery-ops, architecture-review, incident-response, dev-execution, design-variations, and paperclip-worker (the Paperclip control-plane seam)
  53. - 5 domain packs (SaaS, healthcare, fintech, platform-engineering, personal-decisions)
  54. - 6 skill definitions (code-review, security-scan, task-decomposition, mempalace-read-write, mempalace-admin, graphify-query)
  55. - Platform adapters for Pi CLI, Claude Code, Codex, Gemini, and other compatible runtimes
  56. ---
  57. ## Quick Start
  58. > **0.6.0 migration note:** adapters are no longer bundled with the CLI. Install the adapter(s) for the AI CLI(s) you want to drive. See [CHANGELOG](./CHANGELOG.md#060---2026-04-14).
  59. ### Prerequisites
  60. - [Bun](https://bun.sh) 1.0+
  61. ### Install the CLI
  62. Global install:
  63. ```bash
  64. bun add -g aos-harness
  65. # or: npm i -g aos-harness
  66. ```
  67. Project-local install:
  68. ```bash
  69. bun add aos-harness
  70. # or: npm install aos-harness
  71. ```
  72. ### Install at least one adapter
  73. Before you do this, make sure you already have the matching vendor CLI installed and authenticated. AOS adapters augment the CLI you already use:
  74. - `claude` CLI + `@aos-harness/claude-code-adapter`
  75. - `codex` CLI + `@aos-harness/codex-adapter`
  76. - `gemini` CLI + `@aos-harness/gemini-adapter`
  77. - `pi` CLI + `@aos-harness/pi-adapter`
  78. Adapters ship as separate packages. Pin to the same version as the CLI (they publish lockstep):
  79. ```bash
  80. bun add -g @aos-harness/claude-code-adapter # Anthropic's Claude Code
  81. bun add -g @aos-harness/gemini-adapter # Google's Gemini CLI
  82. bun add -g @aos-harness/codex-adapter # OpenAI's Codex CLI
  83. bun add -g @aos-harness/pi-adapter # Pi (https://pi.dev)
  84. ```
  85. Project-local adapter install:
  86. ```bash
  87. bun add @aos-harness/codex-adapter
  88. # or: npm install @aos-harness/codex-adapter
  89. ```
  90. ### Optional host-native installs
  91. Adapters remain the runtime boundary. This repo also ships thin host-native install surfaces on top:
  92. - `Codex`: [plugins/aos-harness](https://github.com/aos-engineer/harness/tree/release/0.11/plugins/aos-harness) local plugin bundle, on the `release/0.11` branch
  93. - `Claude Code`: [plugins/aos-harness/claude-code](https://github.com/aos-engineer/harness/tree/release/0.11/plugins/aos-harness/claude-code) project command pack, on the `release/0.11` branch
  94. - `Pi`: `aos init --adapter pi` writes `.pi/extensions/aos-harness.ts` so `/aos-run` is available when you open `pi` in that project
  95. For Pi across all AOS projects, install the global shim once:
  96. ```bash
  97. aos setup-pi --global
  98. ```
  99. ### Initialize a project
  100. ```bash
  101. cd your-project
  102. aos init
  103. # local install: bunx aos init
  104. # local install with npm: npx aos init
  105. ```
  106. Release line:
  107. - Current repo version: `0.10.0`
  108. - npm latest is published separately via the tag-driven release workflow
  109. - Site image tag: `novashock/aos-harness-site:0.10.0`
  110. `aos init` prints the adapter install commands at the end as a reminder.
  111. It also scans vendor CLI readiness, writes v2 `.aos/config.yaml`, creates a project-local Pi extension shim when Pi is enabled, and supports:
  112. ```bash
  113. aos init --apply # install missing adapter packages
  114. aos init --non-interactive # scan only, write .aos/scan.json
  115. aos init --non-interactive --adapter codex
  116. ```
  117. The generated Pi shim imports `@aos-harness/pi-adapter` and is ignored via `.gitignore`. Re-run `aos init --adapter pi` to regenerate the project shim.
  118. Model selection rules:
  119. - `pi` keeps explicit tier models in config by default.
  120. - `codex`, `claude-code`, and `gemini` now default to the vendor CLI's default model unless you pin tier models explicitly.
  121. - Adapter-scoped runtime settings live under `.aos/config.yaml` `adapter_defaults`.
  122. - Legacy `.aos/adapter.yaml` still works for adapter-specific overrides.
  123. - Existing v2 configs are backfilled automatically on `aos run` if `adapter_defaults` is missing.
  124. ### Run a deliberation
  125. ```bash
  126. aos run strategic-council --brief core/briefs/sample-product-decision/brief.md
  127. ```
  128. ### Run an execution profile
  129. ```bash
  130. aos run cto-execution --brief core/briefs/sample-cto-execution/brief.md
  131. ```
  132. ### Author a brief
  133. If you do not know the brief format, scaffold one interactively:
  134. ```bash
  135. aos create brief
  136. aos create brief my-decision --kind deliberation --idea "We need to decide between X and Y by Q3."
  137. ```
  138. Or use the `/aos-create-brief` skill inside Claude Code, Codex, or Gemini. The host agent will conduct the conversation and validate the result through `aos brief save`.
  139. ```bash
  140. aos brief validate ./briefs/my-decision/brief.md
  141. aos run strategic-council --brief ./briefs/my-decision/brief.md
  142. ```
  143. ### CLI commands
  144. ```bash
  145. aos init # Initialize AOS in the current project
  146. aos setup-pi --global # Make /aos-run available in Pi globally
  147. aos run [profile] # Run a deliberation or execution session
  148. aos run cto-execution --brief ... # Run the CTO execution workflow
  149. aos create brief [slug] # Author a deliberation or execution brief
  150. aos brief validate <path> # Validate a brief shape
  151. aos create agent <name> # Scaffold a new agent
  152. aos create profile <name> # Scaffold a new profile
  153. aos create domain <name> # Scaffold a new domain
  154. aos create skill <name> # Scaffold a new skill
  155. aos validate # Validate all configs
  156. aos list # List all agents, profiles, domains, skills
  157. aos replay <transcript.jsonl> # Replay a session transcript
  158. ```
  159. **Requirements:** [Bun](https://bun.sh) (v1.0+), plus at least one supported vendor CLI already installed.
  160. ---
  161. ## Orchestration Patterns
  162. ### Deliberation (strategic-council)
  163. Submit a brief with a strategic question. 11 agents debate under time and budget constraints. The Arbiter synthesizes a memo with ranked recommendations, agent stances, dissent, and next actions.
  164. ```
  165. Brief → Arbiter frames question → Agents debate (broadcast + targeted rounds)
  166. → Provocateur stress-tests (speaks last) → Arbiter synthesizes → Memo output
  167. ```
  168. ### Execution (cto-execution)
  169. Submit a feature request. The CTO orchestrator drives an 8-step workflow with 3 review gates, producing a complete execution package.
  170. ```
  171. Brief → Requirements (Advocate + Strategist) → Architecture (Architect)
  172. → Architecture Review (Architect vs Operator) → Phase Planning (Strategist + Operator)
  173. → Task Breakdown (Operator) → Security Review (Sentinel)
  174. → Stress Test (Provocateur) → Final Assembly → Execution Package output
  175. ```
  176. ---
  177. ## Agent Roster
  178. | Agent | Category | Role | Core Bias |
  179. |---|---|---|---|
  180. | **Arbiter** | Orchestrator | Session chair, synthesis | Neutral facilitation |
  181. | **CTO Orchestrator** | Orchestrator | Execution leader | Execution quality |
  182. | **Catalyst** | Perspective | Acceleration, monetization | Speed |
  183. | **Sentinel** | Perspective | Protection, sustainability | Trust |
  184. | **Architect** | Perspective | Systems design, feasibility | System durability |
  185. | **Provocateur** | Perspective | Stress-testing (speaks last) | Truth-seeking |
  186. | **Navigator** | Perspective | Market positioning, timing | Positioning |
  187. | **Advocate** | Perspective | User voice, behavior reality | User behavior |
  188. | **Pathfinder** | Perspective | 10x thinking, asymmetric bets | Asymmetric upside |
  189. | **Strategist** | Perspective | Problem selection, sequencing | Impact per effort |
  190. | **Operator** | Operational | Execution reality, capacity | Execution |
  191. | **Steward** | Operational | Ethics, compliance, governance | Compliance |
  192. | **Auditor** | Operational | Retrospective, institutional memory | Learning |
  193. | **Engineering Lead** | Operational | Domain-scoped implementation orchestration | Delivery throughput |
  194. | **Artifact Renderer** | Perspective | Output shaping, packaging, presentation quality | Communication fidelity |
  195. ---
  196. ## Architecture
  197. The 0.x engine (`runtime/`), its adapters (`adapters/pi`, `claude-code`, `codex`, `gemini`), and the 0.x CLI are on the [`release/0.11`](https://github.com/aos-engineer/harness/tree/release/0.11) branch. Its agent, profile, domain, and skill content is still in `core/` on `main`. For the 1.0 layout, see [Repository layout](#repository-layout).
  198. ### 4-Layer Adapter Contract
  199. | Layer | Purpose | Methods |
  200. |---|---|---|
  201. | L1: Agent Runtime | Agent lifecycle | spawnAgent, sendMessage, destroyAgent |
  202. | L2: Event Bus | Hooks and interception | onSessionStart, onToolCall, onMessageEnd |
  203. | L3: User Interface | Rendering and interaction | registerCommand, renderAgentResponse, promptConfirm |
  204. | L4: Workflow Engine | Process orchestration | dispatchParallel, executeCode, invokeSkill, createArtifact |
  205. ---
  206. ## Enhanced Capabilities
  207. AOS Harness includes advanced features for production orchestration:
  208. | Capability | Description | Guide |
  209. |---|---|---|
  210. | [Dev Execution](docs/dev-execution/README.md) | Brief to working code in one session | Planning + hierarchical implementation |
  211. | [Domain Enforcement](docs/domain-enforcement/README.md) | Structural file/tool permission boundaries per agent | Path matching, tool allowlists, bash restrictions |
  212. | [Hierarchical Delegation](docs/hierarchical-delegation/README.md) | Agents spawn and manage sub-agents in Lead→Worker chains | Depth limits, domain inheritance |
  213. | [Memory System](docs/persistent-expertise/README.md) | Pluggable memory: MemPalace, Graphify knowledge-graph, and built-in expertise | Orchestrator-gated recall, session curation, MCP integration |
  214. | [Event Summarization](docs/event-summarization/README.md) | Template summaries plus LLM-needed classification | Platform LLM batching is planned |
  215. | [Session Checkpointing](docs/session-resumption/README.md) | Pause checkpoints with conversation tails | Full automatic resume is planned |
  216. ---
  217. ## Platform (Enterprise Tier)
  218. The harness is fully functional standalone: every session writes a local JSONL transcript you can replay with `aos replay`. For teams that want live, multi-session observability, AOS also streams session events to an optional **hosted Platform** (a separate commercial offering). The open-source harness in this repository is complete on its own and never requires it.
  219. When a platform endpoint is configured, each adapter batches transcript events to it in real time, providing:
  220. - **Live observability dashboard**: watch deliberations and executions stream in as they happen, across every session.
  221. - **Session timeline & history**: a searchable record of agent stances, dissent, costs, and artifacts.
  222. - **Team management**: shared projects, roles, and access control.
  223. - **Analytics**: spend, round counts, and outcome tracking across runs.
  224. Connect the open-source harness to a platform with a URL and an ingest token:
  225. ```bash
  226. export AOS_PLATFORM_TOKEN=... # issued by your platform
  227. aos run strategic-council \
  228. --brief ./briefs/my-decision/brief.md \
  229. --platform-url https://platform.example.com
  230. ```
  231. Adapters advertise `transcript_streaming: "local+platform"`: events always land in the local transcript, and additionally stream to the platform when `--platform-url` (or `AOS_PLATFORM_URL`) is set. No platform, no problem: the harness runs identically without one.
  232. ---
  233. ## Documentation
  234. - **Specs:** `docs/specs/2026-03-23-aos-harness-design.md` (core framework)
  235. - **Execution Profiles:** `docs/specs/2026-03-24-aos-execution-profiles/` (4-document spec suite)
  236. - **Getting Started:** `docs/getting-started/README.md`
  237. - **Creating Agents:** `docs/creating-agents/README.md`
  238. - **Creating Profiles:** `docs/creating-profiles/README.md`
  239. - **Creating Workflows:** `docs/creating-workflows/README.md`
  240. - **Creating Skills:** `docs/creating-skills/README.md`
  241. - **Domain Enforcement:** `docs/domain-enforcement/README.md`
  242. - **Hierarchical Delegation:** `docs/hierarchical-delegation/README.md`
  243. - **Memory System:** `docs/persistent-expertise/README.md`
  244. - **Event Summarization:** `docs/event-summarization/README.md`
  245. - **Session Checkpointing:** `docs/session-resumption/README.md`
  246. - **Release Readiness:** `docs/testing/release-readiness-checklist.md`
  247. ---
  248. ## License
  249. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.