Agentic OS Control Plane

<!-- ECOSYSTEM_STATS_START -->Current Scale: 6 Plugins · 30 Skills · 19 Sub-Agents<!-- ECOSYSTEM_STATS_END -->

A governed execution harness for AI coding agents. This repository lets Claude Code, Codex, GitHub Copilot, Agy, and compatible tools use their native planning, coding, orchestration, and worktree capabilities while the Agentic OS Control Plane provides the boundaries around that work: recorded decisions, human authority, deterministic checks, isolated execution, verification, and continuous improvement.

It is not just a skills catalog. It is a portable system for making agent-driven engineering work more reliable without attempting to replace the model's reasoning.

The control plane is native to this repository and depends on no external workflow package. Several of its practices were shaped by obra/superpowers; see the acknowledgments.

What the control plane does

For governed work, the control plane persists task state in local SQLite and permits only valid, evidenced transitions. It makes the important decisions visible and durable:

• Understand first: work intake which is interactive interview process to establish scope, acceptance criteria,

verification, and whether a request is trivial or standard.

• Plan deliberately: plan artifacts have a recorded identity; review is either performed or

explicitly skipped with a reason.

• Keep people in charge: implementation requires a real human approval gate. Reset, escalation,

and recovery paths are also governed.

• Execute safely: implementation normally happens in an isolated worktree, with recorded

exceptions rather than silent bypasses.

• Verify outcomes: focused checks, repository-wide test receipts, policy checks, and completion

evidence are required before a task can close.

• Learn continuously: retrospectives, friction records, evaluation loops, map debt, and durable

playbooks turn failures and successful patterns into improvements.

The normal lifecycle is:

Intake → Interview → Draft plan → Plan review / optional independent review
→ Human approval → Worktree implementation → Code review / recorded skip
→ Verification → Retrospective → Done

Tasks can return to interview, planning, review, implementation, escalation, or reset when evidence calls for it. See the canonical happy-path diagram and complete state machine.

Production and simulation approvals

Production work and simulations use separate databases and signing identities:

The first signed gate binds one key for that pipeline. The other context's key is refused; simulation results cannot authorize a production push. The push guard verifies complete signed gate evidence against the production human trust anchor, not merely a stored DONE state. Legacy tasks without captured signature evidence fail closed; do not fabricate historical evidence.

The setting-up-agentic-os skill guides both identities: its init mode creates or reuses the agent's simulation identity additively (on by default; --no-simulation-identity skips it), and its signing-setup mode guides the human-controlled key setup. Human enrollment is never overwritten. Simulations specify their database on each invocation; there is no sticky .env approval-mode switch. This is two approval contexts, not a requirement to spawn two agent processes.

Separate databases alone do not isolate a hostile agent running as your OS user. Protect human keys, trust anchors, and approval tooling using a separate account/container or trusted broker. Account existence is not proof that the agent runtime is isolated; onboarding reports that limit. See isolation setup.

Governance around native capability

The control plane governs before, around, and after agent execution. It does not prescribe a model's chain of thought or force every runtime into one implementation style. A capable native agent may create plans, manage worktrees, delegate, review, or execute in its best available way; the harness establishes the task boundaries, required evidence, human decisions, and exit criteria.

This separation matters: frontier capabilities can improve without weakening approvals, deterministic verification, or the audit trail.

Start here

I want governed agent work in my repository

Install the plugins, then initialize and check the Agentic OS substrate:

# Install via APM (project scope for your active client):
apm install @richfrem/agent-agentic-os

# Or install globally across all clients (Claude Code, GitHub Copilot, Codex, Antigravity):
apm install -g --target claude,copilot,codex,antigravity @richfrem/agent-agentic-os

Then ask your agent to set up Agentic OS for the repository, or use the init mode of setting-up-agentic-os, followed by the health mode of running-control-plane. Start a governed task through the intake mode of running-control-plane when the work needs a plan-to-completion lifecycle. Approving a plan, accepting the code and closing a task each require a signature from a human-held SSH key (ssh-keygen -Y sign); the signing-setup mode of setting-up-agentic-os walks you through creating and testing it. Installation and onboarding has platform-specific and local-development instructions.

Human approval gates: SSH signing (do this once per machine)

The pipeline's three human authorities (plan approval, code acceptance, closure) are cryptographic gates, so an agent can never approve its own work. Only an out-of-band OpenSSH signature from your key advances them. This follows the CIBA/RAR idea (approve one exact, structured request out of band), done locally with SSH instead of an identity provider.

1. Run python3 plugins/agent-agentic-os/skills/setting-up-agentic-os/scripts/setup_ciba_identity.py in your own terminal (the signing-setup mode explains each prompt); --check reports readiness.
2. Your private key stays in ~/.ssh; allowed_signers and context/identity/ are per-machine and never committed.
3. When the agent stops with HUMAN_PROOF_REQUIRED, run its coordinate-transition ... --interactive --key <your key> command (with SSH_AUTH_SOCK unset) and enter your passphrase.

I want one capability or plugin

Plugins are independently installable. Choose only the parts you need—the control plane is not a runtime dependency of standalone skills. Install specific packages with apm install @richfrem/<plugin-name> (or select individual skills via --skill); see INSTALL.md.

I am contributing to this repository

Clone the repository, install local plugin sources, and follow START_HERE.md to initialize the local control-plane substrate. Read architecture.md and the binding ADRs before changing plugin structure, scripts, or shared resources.

The system at a glance

Continuous improvement is part of the product

The control plane follows a practical improvement discipline inspired by Karpathy-style autoresearch: make a bounded change, measure it with an objective verifier, keep or discard it, and preserve the learning either way. This repository applies that discipline at multiple levels:

• task retrospectives identify friction, follow-ups, and issue-worthy work;
• evaluation loops use explicit KEEP/DISCARD outcomes instead of subjective claims;
• map debt and evolution logs preserve unresolved constraints and confirmed lessons;
• architecture, policy, diagram, and test contracts keep the documented system aligned with the

executable one.

The goal is compounding reliability—not blind autonomy. Human approval remains required where authority matters, and evidence is more important than an agent saying that work is complete.

Plugin map

The repository is an upstream source monorepo. plugins/ is authoritative; APM installs self-contained runtime copies into active client harnesses (.claude/skills/, .agents/skills/, or global profiles).

For individual skills, agents, supported surfaces, and version detail, use each plugin's README and manifest rather than treating this landing page as a volatile inventory.

Architectural commitments

• Portable source, self-contained installs: individual skills cannot depend at runtime on a

sibling plugin or this source checkout.

• One canonical owner for shared resources: plugins use managed file-level symlinks in source;

installation dereferences them into portable copies.

• Human authority is explicit: approval, skip, reset, and recovery decisions are recorded—not

inferred from agent behavior.

• Policy is executable: transition templates, SQLite state, Python policy checks, tests, and

diagrams are maintained as a single contract.

• No silent bypasses: a failed or missing capability is friction to diagnose and improve, not

permission to quietly work around it.

Read the full architecture overview, the control-plane module diagram, and the ADRs for the detailed contracts.

What this is not

• Not a replacement for Claude Code, Codex, Copilot, Agy, or another capable native runtime.
• Not a requirement to install every plugin to use one useful skill.
• Not a claim that a local control plane can protect a repository from actors who deliberately

circumvent it outside the configured workflow.

• Not static process documentation: the system is tested, measured, reviewed, and evolved.

Repository layout

plugins/                  canonical plugin sources
  <plugin>/skills/        portable skill definitions
  <plugin>/scripts/       canonical shared Python helpers
  <plugin>/agents/        sub-agent definitions
.agents/                  installer output; generated runtime copies, not source of truth
plugins/agent-agentic-os/skills/running-control-plane/references/diagrams/   control-plane and architecture diagrams
docs/ADRs/                binding architectural decisions
context/                  local control-plane state and memory in a consuming repository
temp/                     local scratch output

Further reading

• Install plugins
• Contributor/session bootstrap
• Repository architecture
• Agentic OS control-plane plugin
• Control-plane happy path
• Complete transition graph
• Architectural decision records