Agentic OS Control Plane

**Current Scale:** 10 Plugins · 130 Skills · 46 Sub-Agents

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 has no hard runtime dependency on obra/superpowers. It adopts compatible ideas from Superpowers—intent-first brainstorming, right-sized plans, TDD, review, and worktree discipline— and may use those workflows only as an optional fallback where the host runtime lacks an equivalent capability. See the Agentic OS boundary and attribution reference for the maintained distinction and thanks to the Superpowers maintainers and contributors.

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.

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:

uvx --from git+https://github.com/richfrem/agent-plugins-skills plugin-add richfrem/agent-plugins-skills

Then ask your agent to set up Agentic OS for the repository, or use os-init, followed by os-health-check. Start a governed task through work-intake 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 os-signing-setup skill 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/scripts/setup_ciba_identity.py in your own terminal (the os-signing-setup skill 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. Use the interactive installer above or install a specific plugin from plugins/<plugin-name>; 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

Layer	Responsibility	Primary components
Control plane	State transitions, human gates, policy checks, verification receipts, retrospectives	agent-agentic-os
Native runtime integration	Discover available CLIs, select suitable models, and delegate without hard runtime coupling	cli-agents
Execution patterns	Composable loops, graph execution, swarms, adversarial review	agent-orchestration
Learning and memory	Filesystem-native memory, retrieval options, experiment and improvement loops	agent-memory, agent-agentic-os
Plugin lifecycle	Create, audit, install, synchronize, and maintain reusable plugins	agent-scaffolders, plugin-manager

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; installers materialize self-contained runtime copies into .agents/.

Plugin	Use it for
agent-agentic-os	Governed task lifecycle, health checks, evaluation, continuous improvement, and repository evolution
cli-agents	CLI-agent discovery, delegation, model catalogs, and project/runtime setup
agent-orchestration	Reusable orchestration and multi-agent execution primitives
agent-memory	Filesystem memory, RLM, and vector-data capabilities
agent-scaffolders	Creating, auditing, packaging, and maintaining plugins and skills
dev-utils	Repository utilities: issues, worktrees, symlinks, context, documentation, and more
exploration-cycle-plugin	Discovery, requirements, prototyping, and handoff into engineering work
obsidian-wiki-engine	Obsidian vault, graph, and wiki workflows
dependency-management	Python dependency and environment management
plugin-manager	Installing, synchronizing, and maintaining the plugin ecosystem

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
docs/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