# Coacus
One portable library of skills, agents, workflows and MCP declarations — rendered
into the native shape each AI coding harness expects. Write it once; run it in
OpenCode, Claude Code, Antigravity, Codex and Cursor without a fork per tool.
[](LICENSE)
[](docs/usage.md)
[](docs/roadmap.md)
[](.github/workflows/ci.yml)
[](docs/standards/english-only.md)
## Contents
- [What it is, and why](#what-it-is-and-why)
- [The core principle](#the-core-principle)
- [How it works](#how-it-works)
- [What is inside](#what-is-inside)
- [Harness support](#harness-support)
- [Install](#install)
- [Everyday commands](#everyday-commands)
- [Quality and CI](#quality-and-ci)
- [Standards](#standards)
- [Status](#status)
- [Documentation map](#documentation-map)
- [Extending](#extending)
- [License](#license)
## What it is, and why
Agent tooling accumulates in silos. A skill written for one harness hard-codes
that harness's tool names, a second harness needs a copy, and the two copies
drift. Coacus removes the copy step: it keeps one canonical source for every
artifact and derives each harness representation from it, so a change lands in
one file and the generated output follows.
Three sources feed the library:
- **Knowledge** — what the framework knows: 471 skills across eleven categories, 104 agents, and one MCP declaration.
- **Methodology** — how work proceeds: 29 process workflows for planning,
debugging, review and verification.
- **Verticals** — domain pipelines, currently `architecture_si`: document ingest
then analysis.
The problem it solves is portability of judgement. A team's conventions should
travel with the team, not with the editor.
## The core principle
> **Disk is the truth; generation is the contract.**
Every canonical artifact has exactly one source. Every per-harness representation
is generated from it and verified by a drift check. A generated file that does not
match a fresh regeneration is a build error, not silent debt.
```text
create (templates/authoring) → validate (source contracts)
→ register (generate) → discover (single scan)
→ activate (SessionStart bootstrap, one format per harness)
```
Generated output is committed, and CI runs `check`, never `generate`:
regenerating in CI would rewrite the very files under comparison and hide the
drift it is meant to catch. Full text:
[generated-artifacts](docs/standards/generated-artifacts.md).
## How it works
Three layers, plus one closed engine:
- **`knowledge/`** — the canonical WHAT. Skills, agents and MCP declarations,
harness-agnostic. Bodies name actions, never tool names
([skill-authoring](docs/standards/skill-authoring.md)).
- **`methodology/`** — the canonical HOW. The 29 process workflows and the single
bootstrap wrapper body ([session-start-bootstrap](docs/standards/session-start-bootstrap.md)).
- **`harnesses/`** — thin per-harness adapters. Each is a `harness.json` data
file: bootstrap shape, output paths, tool mapping, install method. Shapes: `A`
Python hook, `B` in-process, `C` instructions file.
- **`engine/`** — the closed core. Generators, validators, the governor, the
dispatcher, the TOON validator and the provenance checker. The engine changes
only when a new concept arrives, not when new data does.
```mermaid
flowchart TD
subgraph CANON["Canonical sources"]
K["knowledge/ — skills, agents, mcps"]
M["methodology/ — workflows, bootstrap body"]
end
ADAPT["harnesses/<h>/harness.json (data) + engine/ (generators, validators)"]
GEN["engine/generators"]
subgraph OUT["Generated and committed"]
DIST["agents/**/dist/*"]
BOOT["harnesses/<h>/bootstrap/*"]
CAT["catalog/catalog.json + INDEX.md"]
DISC[".agents/ manifests + entries/"]
end
RUN["Runtime: governor · TOON validator · dispatcher · provenance"]
HARN["harnesses: opencode, claude-code, antigravity, codex, cursor, command-code"]
K --> GEN
M --> GEN
ADAPT --> GEN
GEN --> DIST
GEN --> BOOT
GEN --> CAT
GEN --> DISC
DIST -->|install| HARN
BOOT -->|install| HARN
RUN -.->|bounds and validates| HARN
```
Full treatment: [`docs/architecture.md`](docs/architecture.md).
## What is inside
### Corpus
| Asset | Count | Breakdown |
|---|---|---|
| Skills | 471 | `domains` 167, `security` 133, `engineering` 38, `roles` 25, `languages` 20, `frameworks` 18, `data` 17, `mapping` 16, `architecture` 14, `infrastructure` 10, `platforms` 13 |
| Agents | 104 | `cybersecurity` 24, `software-engineering` 20, `academic-sciences` 17, `architecture` 14, `specialized-domains` 13, `data-cloud-devops` 9, `core-orchestration` 3, `research-discovery` 4 |
| Workflows | 29 | Process skills imported from Superpowers and adapted to Coacus conventions, plus native engineering/governance workflows, including `using-coacus` and `learning-consolidation` |
| MCPs | 1 | `coacus-catalog` |
| Catalog | 500 skill entries | 471 knowledge skills + 29 workflows, generated from disk (`catalog/catalog.json` + `catalog/INDEX.md`) |
| Provenance | 1472 entries | `sources.lock.json` ([provenance](docs/standards/provenance.md)) |
### Core engine (stdlib only; language gate dependency is pinned)
| Module | Job |
|---|---|
| `engine/frontmatter.py` | Tolerant YAML-subset parser for canonical sources. |
| `engine/generators/agent_manifests.py` | `agent.source.md` → `dist/AGENT.md`, `agent.yaml`, `agent.json`, `plugin.json`. |
| `engine/generators/mcp_configs.py` | `MCP.md` → `dist/mcp.json`, `dist/mcp_config.json`. |
| `engine/generators/bootstrap.py` | Canonical wrapper + entry body → one native artifact per harness. |
| `engine/generators/catalog.py` | Disk → `catalog/catalog.json` + `catalog/INDEX.md`, byte-idempotent. |
| `engine/generators/discovery.py` | Disk → `.agents/{skills,mcps,agents}.json` + `entries/`. |
| `engine/generators/docstrings.py` | Source docstrings → `docs/reference/python-api.md`. |
| `engine/validators/` | Source and artifact contracts: agents, skills, mcps, hygiene, evals, language, discovery, completeness. |
| `engine/governor/ledger.py` | Disk ledger (`flock`) bounding concurrent subagents. |
| `engine/guardrail/evaluate.py` | PAER policy evaluator used by the guardrail runtime. |
| `engine/improve/` | The opt-in, fail-open self-improvement pipeline (never applies). |
| `engine/generators/plugins.py` | `kind`-keyed plugin registry (governor gate, guardrails). |
| `engine/generators/guardrails.py` | Renders a canonical policy into native hooks per harness. |
| `engine/generators/lifecycle.py` | Renders the harness capability matrix. |
| `engine/generators/outputs.py` | Cross-generator path uniqueness (one producer per path). |
| `engine/toon.py` | Validator for TOON handoff payloads. |
| `engine/dispatcher/` | `@register_converter` registry for ingestion formats. |
| `engine/provenance.py` | Schema and existence checks for `sources.lock.json`. |
### Scripts, tests and evals
Python CLIs in `scripts/` cover generation, installation, routing, evaluations,
ingestion, lifecycle guardrails, design linting and maintenance. The `tests/` tree
holds a deterministic stdlib `unittest` suite (measure it with
`python3 -m unittest discover -s tests`). `evals/` holds behavior scenarios
behind a static gate and an opt-in live runner
([`evals/README.md`](evals/README.md)).
## Harness support
Every harness installs the same corpus through `scripts/coacus_install.py`, and
each one gets exactly one rendered bootstrap in its own native format.
| Harness | Shape | Bootstrap mechanism | Install |
|---|---|---|---|
| **opencode** | B — in-process plugin | `config` + `experimental.chat.messages.transform` hooks inject the bootstrap in-process; a second plugin enforces the governor gate | `python3 scripts/coacus_install.py opencode` |
| **claude-code** | A — Python hook | `SessionStart` → `hookSpecificOutput.additionalContext` | `python3 scripts/coacus_install.py claude-code` |
| **antigravity** | C — plugin rule | compact `rules/coacus.md` with `trigger: always_on`, native agent selectors and an on-demand catalog MCP | `python3 scripts/coacus_install.py antigravity` |
| **codex** | A — Python hook | `SessionStart` → `hookSpecificOutput.additionalContext` | `python3 scripts/coacus_install.py codex` |
| **cursor** | A — Python hook | `sessionStart` → top-level `additional_context` | `python3 scripts/coacus_install.py cursor` |
| **command-code** | A — Python hook | `SessionStart` → `hookSpecificOutput.additionalContext`, merged into `settings.json` | `python3 scripts/coacus_install.py command-code` |
Per-harness tutorials, vendor facts and the evidence class behind each claim:
[`docs/install.md`](docs/install.md).
## Install
### 🌟 1-Click Universal Bootstrap (Recommended)
Verify Python (3.12+), attempt installation if absent, create an isolated virtual environment (`.venv`),
install the language-gate dependencies, render artifacts, and install Coacus into
detected harnesses:
```bash
# Linux / macOS
./install.sh
# Windows (PowerShell)
.\install.ps1
```
To target one harness, pass its name, for example `./install.sh codex` or
`.\install.ps1 codex`.
### Manual Install
On Linux or macOS, use a `python3` interpreter at least as recent as 3.12:
```bash
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --disable-pip-version-check lingua-language-detector==2.2.0 wordfreq==3.1.1
python3 scripts/coacus.py generate # render every artifact first
python3 scripts/coacus_install.py opencode # or: claude-code | antigravity | codex | cursor | command-code | all
python3 scripts/coacus_install.py all --verify-after-install # install and verify detected harnesses
python3 scripts/coacus_install.py opencode --dry-run # preview targets
python3 scripts/coacus_install.py codex --only security,engineering # partial install
python3 scripts/coacus_install.py codex --agents 'qa-*' # filter agents only
python3 scripts/coacus_install.py --list # available categories and skills
python3 scripts/coacus_install.py opencode --verify # read-only: compare with the repo
```
For Windows manual setup, see [the installation guide](docs/install.md#manual-setup-step-by-step).
The installer is idempotent: it writes a `coacus-install.json` manifest beside
each target, never rewrites a harness config file wholesale, and removes exactly
what it installed with `--uninstall`. Every harness installs skills **and** agents.
Install the whole corpus, or a subset with `--only` (top-level category or any
nested segment, applied to skills and agents), `--skills` (skill name glob) and
`--agents` (agent name glob) — useful when a harness caps the session-start
skills budget.
### Dependencies
- **Required:** [Python 3.10+](https://www.python.org/). The core tooling uses the
standard library only. The repository-wide language gate also requires Python
3.12+, [`lingua-language-detector==2.2.0`](https://pypi.org/project/lingua-language-detector/2.2.0/)
and [`wordfreq==3.1.1`](https://pypi.org/project/wordfreq/3.1.1/)
(resolved 2026-10-19); CI installs them before validation. The CI matrix checks
the minimum core-tooling release and the main CI target declared in
[`.github/workflows/ci.yml`](.github/workflows/ci.yml).
- **Self-contained (zero external MCP dependencies):** Coacus operates
offline-by-default and requires no third-party MCP servers or API keys to run.
The framework distributes a single internal helper, `coacus-catalog` (stdio),
for on-demand asset discovery and routing. Version resolution follows the
[version-freshness](docs/standards/version-freshness.md) rule: agents resolve
versions in-session from canonical package registries (npm, PyPI, crates.io) or
official publisher release notes, never from training memory. Optional: when
no resolution channel is reachable, an unresolved pin is marked `unverified`.
## Everyday commands
All commands were verified against the scripts in `scripts/` and run from the
repository root.
```bash
python3 scripts/coacus.py generate # regenerate dist/, bootstraps, .agents/, catalog/, API reference
python3 scripts/coacus.py check # fail if generated artifacts are stale
python3 scripts/coacus.py validate # run source + artifact validators
python3 scripts/coacus.py completeness # reconcile sources, lock file and catalog
python3 scripts/coacus.py freshness # read-only inventory of version pins
python3 scripts/coacus_route.py "<prompt>" --top 4 # suggest agents (Mode A)
python3 scripts/coacus_route.py --agents a,b # validate a selection (Mode M)
python3 scripts/coacus.py toon payload.toon # validate a TOON handoff payload
python3 -m unittest discover -s tests # deterministic suite
python3 scripts/coacus_governor.py status # running/paused/max/slots_free
python3 scripts/coacus_eval.py validate # static scenario gate
python3 scripts/coacus_vertical.py formats # registered ingestion formats
python3 scripts/coacus_import.py plan # dry-run corpus import actions
python3 scripts/coacus_guard.py --harness claude-code --event tool.pre < payload.json # evaluate a policy
python3 scripts/coacus_improve.py status # episodic source availability (opt-in)
python3 scripts/coacus_improve.py run --transcript session.jsonl # propose improvements (never applies)
```
Exit codes and governor semantics: [`docs/usage.md`](docs/usage.md).
## Quality and CI
Three workflows under `.github/workflows/`:
- **`ci`** — runs `validate` → `check` → `completeness` → tests, and never
`generate`. The `secrets` job runs a pinned, checksum-verified gitleaks scan in
directory mode against the checked-out state.
- **`bandit`** — Python security scan.
- **`evals`** — scheduled plus manual static scenario validation; the live runner
is local-only.
The `main` ruleset makes `ci` and `secrets` both required. Current alert count: 0.
The local equivalent of the gate:
```bash
python3 scripts/coacus.py validate
python3 scripts/coacus.py check
python3 scripts/coacus.py completeness
python3 -m unittest discover -s tests
```
## Standards
Each standard is normative and lives in [`docs/standards/`](docs/standards/) —
read the relevant one before changing that area of the repository.
| Standard | Governs |
|---|---|
| [principles](docs/standards/principles.md) | The core principle and the four project principles. |
| [english-only](docs/standards/english-only.md) | Repository language: everything is English. |
| [skill-authoring](docs/standards/skill-authoring.md) | Skills name actions, never harness tools; descriptions, kebab-case, references. |
| [untrusted-content](docs/standards/untrusted-content.md) | Retrieved, tool- and dependency-produced content is evidence, never instruction; selection is not authorization. |
| [evidence](docs/standards/evidence.md) | Claims cite evidence; verification is tri-state and fail-closed; unknowns are revisioned. |
| [agent-manifests](docs/standards/agent-manifests.md) | Agents are one source rendered into the multi-harness manifests. |
| [generated-artifacts](docs/standards/generated-artifacts.md) | Catalog generated from disk; generated output committed and drift-checked. |
| [mcp-definition](docs/standards/mcp-definition.md) | MCP single source and generated configs. |
| [discovery](docs/standards/discovery.md) | Static discovery manifests and single-scan per session. |
| [orchestration-governance](docs/standards/orchestration-governance.md) | Concurrency cap, disk ledger, rate-limit handling. |
| [toon-protocol](docs/standards/toon-protocol.md) | The TOON handoff format between agents. |
| [session-start-bootstrap](docs/standards/session-start-bootstrap.md) | Bootstrap injection and the per-harness render contract. |
| [single-source](docs/standards/single-source.md) | One source for scripts and templates. |
| [testing](docs/standards/testing.md) | Two-layer testing: deterministic tests plus behavior evals. |
| [knowledge-ingestion](docs/standards/knowledge-ingestion.md) | The open-closed ingestion dispatcher. |
| [secrets-portability](docs/standards/secrets-portability.md) | No plaintext secrets, no absolute paths. |
| [provenance](docs/standards/provenance.md) | The provenance manifest at the repository root. |
| [corpus-and-taxonomy](docs/standards/corpus-and-taxonomy.md) | The imported corpus and its eleven-category taxonomy. |
| [routing](docs/standards/routing.md) | Agents are selected through a generated index, in a manual or an automated mode. |
| [version-freshness](docs/standards/version-freshness.md) | Versions are resolved in-session from official package registries or publisher pages, never recalled; the most recent definition wins. |
| [lifecycle-guardrails](docs/standards/lifecycle-guardrails.md) | The PAER guardrail model, per-harness capability data and the native render. |
| [decision-records](docs/standards/decision-records.md) | Committed MADR decision records under `docs/decisions/`. |
| [self-improvement-loop](docs/standards/self-improvement-loop.md) | The opt-in, fail-open end-of-session improvement loop and its one-way boundary. |
## Status
Phases **F0–F11 are complete**. F11 delivered the canonical UI-style expansion,
its authoring standard, design-quality linting and showcase integration; see the
[roadmap](docs/roadmap.md) for phase details.
| Phase | Scope |
|---|---|
| **F0** | Framework charter: settle the architecture standards and lay the repository skeleton. |
| **F1** | Foundation: engine core — parser, generators, validators, thin CLI, first tests. |
| **F2** | Quality gates: tolerant parser, hardened CI (`ci` + `secrets`), drift check, two-layer testing. |
| **F3** | MCP single-source generation and per-harness SessionStart bootstrap render. |
| **F4** | Execution governance: concurrency/rate-limit governor, TOON validator, discovery manifests. |
| **F5** | Behavior evals: static scenario gate plus opt-in live runner with a pluggable judge. |
| **F6** | Corpus import: import, translate and organize the full corpus into the ten-category taxonomy. |
| **F7** | Final consolidation: documentation set, corpus-and-taxonomy, changelog, contribution contract. |
| **F8** | Completeness verification: reconcile sources, `sources.lock.json` and the catalog. |
| **F9** | Portable lifecycle guardrails: PAER policies rendered natively per harness, capability matrix, installer enforcement gate. |
| **F10** | Opt-in self-improvement loop: pluggable episodic sources, typed proposals, verification ladder, proposer-only. |
| **F11** | Canonical UI-style library, style-purity and Anti-AI Slop standards, design linting and showcase integration. |
The corpus, agents, workflows and MCP inventory are measured from the generated
catalog above. Coacus also provides generated discovery manifests, per-harness
bootstraps and installation, execution governance, lifecycle guardrails,
behavior evaluations, design-quality checks and an opt-in improvement proposal
pipeline. Harness-specific verification evidence and limitations are documented
in [`docs/install.md`](docs/install.md) and [`evals/README.md`](evals/README.md).
Phase history: [`docs/roadmap.md`](docs/roadmap.md).
## Documentation map
| Document | Read it for |
|---|---|
| [`docs/README.md`](docs/README.md) | Index of the documentation set. |
| [`docs/architecture.md`](docs/architecture.md) | Layers, engine, artifact lifecycle, repository layout. |
| [`docs/usage.md`](docs/usage.md) | Day-to-day commands: generate, validate, install, governor, evals, vertical. |
| [`docs/extending.md`](docs/extending.md) | Add a skill, agent, MCP, harness, workflow, template or ingestion format. |
| [`docs/install.md`](docs/install.md) | Per-harness installation tutorials. |
| [`docs/tutorials/`](docs/tutorials/) | Guided walkthroughs: choosing agents manually and automatically, tuning the routing lexicon. |
| [`docs/migration.md`](docs/migration.md) | The F6 corpus import: sources, taxonomy, dedup, provenance, translation. |
| [`docs/roadmap.md`](docs/roadmap.md) | Phase history F0–F11 and what each phase delivered. |
| [`docs/reference/python-api.md`](docs/reference/python-api.md) | Generated Python API reference from source docstrings. Do not edit. |
| [`docs/reference/desktop-extension-practices.md`](docs/reference/desktop-extension-practices.md) | Find GNOME preferences, connector recovery, native theme, and update-preservation practices by task. |
| [`docs/standards/`](docs/standards/) | The 26 normative standards. Read before changing that area. |
| [`CONTRIBUTING.md`](CONTRIBUTING.md) | The contribution contract, commit style and PR flow. |
| [`SECURITY.md`](SECURITY.md) | How to report suspected vulnerabilities privately. |
| [`CHANGELOG.md`](CHANGELOG.md) | Notable changes, grouped by phase. |
| [`docs/decisions/`](docs/decisions/) | Committed MADR architecture decision records. |
| [`THIRD-PARTY-NOTICES.md`](THIRD-PARTY-NOTICES.md) | Licenses of imported components (MIT / GPL-3.0). |
| [`AGENTS.md`](AGENTS.md) | Routing and single-scan rules for any agent in this repository. |
| [`evals/README.md`](evals/README.md) | Behavior-eval tiers, scenario schema and the live runner. |
| [`catalog/INDEX.md`](catalog/INDEX.md) | Generated human index of every skill, agent and MCP. |
## Extending
Extend by adding data, not core code. A new skill, agent, MCP, harness, workflow,
template or ingestion handler is a new file following the matching template in
`templates/authoring/`; `engine/` changes only when a new concept arrives
([skill-authoring](docs/standards/skill-authoring.md),
[knowledge-ingestion](docs/standards/knowledge-ingestion.md)). After every
addition, run `generate`, `validate`, `check` and the tests. Steps per artifact
type are in [`docs/extending.md`](docs/extending.md).
## Reporting
For bugs and feature requests, [open an issue](https://github.com/dandgabr/Coacus/issues/new)
and choose the matching form. Report suspected vulnerabilities privately using
the process in [`SECURITY.md`](SECURITY.md); do not disclose vulnerability
details in a public issue.
## License
[AGPL-3.0](LICENSE). Contributions are accepted under the same license.