richfrem/agent-plugins-skills / plugins/agent-agentic-os/.apm/skills/running-control-plane
running-control-plane
FlaggedCRITICAL INTAKE GATEWAY: use at the start of any non-trivial engineering task, feature, refactor, multi-file bugfix, work package or new idea, including requests to explore, brainstorm, build, fix or change something, before planning or code changes. Enforces read-only discovery, 1-3 structured questions with defaults, control-plane registration and the immutable four-pillar TASK_SPEC.md. Also runs the rest of the control plane: health ("run health check", "check os metrics", "system monitor", event bus, locks, memory, "is my signing identity ready" status check), transition simulation ("dry run transition", "simulate transition", "check edge X -> Y"), worktree selection, and gating on/off ("disable the control plane", "turn off the push guard", "stop gating my commits"). Not for project setup or key creation (use setting-up-agentic-os) or improving skills (use improving-skills-in-lab).
references/diagrams/control-plane-architecture.mermaid
View on GitHubflowchart TB
%% Entry Layer
subgraph Layer_Entry["Entry Points & Orchestration"]
Callers["CLI, agents, and Python consumers"]
Facade["ControlPlane compatibility facade"]
Coordinator["TransitionCoordinator"]
Guidance["Transition guidance: versioned advisory snapshot"]
Lifecycle["Canonical lifecycle states: 13-stage sequence"]
end
%% Governance & Gates
subgraph Layer_Governance["Governance, Policies & Human Boundaries"]
State["StateMachine (control_plane/state_machine.py)"]
Policy["Unified policy engine (control_plane/policy.py)"]
TransitionRequest["transition_request: nonce, expiry & content snapshot (commit SHA, diff hash, untracked hash, retrospective digest)"]
SigningGate["Cryptographic gates: APPROVED, VERIFY_EXIT, DONE\nssh-keygen -Y sign (TTY passphrase) verified vs allowed_signers"]
Registry["TransitionRegistry"]
Templates["transition_templates.yaml: edge contracts & authorized_actor"]
ForceClose["Early close: any active state to DONE (same signed closure gate)"]
HumanClose["Human-signed closure\n(any state → DONE; no force-close string or flag)"]
ArtifactGate["Plan artifact identity/revision gate"]
MainReconciliation["main_worktree_reconciliation (issue #609)"]
Delegation["DelegationContract: scope, authority, budget, receipts"]
end
%% Review Subsystem
subgraph Layer_Review["Review Dispatch & Worktree Convergence"]
ReviewDispatch["Review dispatch: required source + canonical verdict"]
ReviewSelection["review-selection-v1: decision → method → internal runtime/model/effort"]
ReviewReports["Task-scoped raw reviewer reports + receipts"]
ReviewSynthesis["Canonical review synthesis / revision brief"]
PlanBranch["Plan-review disposition only: accept plan or request review\n(not a human gate; Gates 1, 3 and closure have no skip)"]
PlanAcceptance["PLAN_REVIEW convergence: accept plan or return to DRAFT_PLAN"]
InterviewOutline["Atomic interview answer + revisioned outline projection"]
Inventory["Session-wide change inventory + reconciliation manifest"]
Worktree["Registered implementation worktree"]
end
%% Hexagonal Ports
subgraph Layer_Ports["System Ports (Hexagonal Abstraction)"]
PersistencePort["PersistencePort"]
CryptoPort["CryptoPort"]
FilesystemPort["FilesystemPort"]
ModelPort["ModelCatalogPort"]
ClockPort["ClockPort"]
end
%% Concrete Adapters
subgraph Layer_Adapters["Infrastructure Adapters"]
SQLiteAdapter["SqlitePersistenceAdapter"]
CryptoAdapter["CryptoAdapter"]
FilesystemAdapter["FilesystemAdapter"]
ModelAdapter["ModelCatalogAdapter"]
ClockAdapter["ClockAdapter"]
end
%% Physical Storage & OS Targets
subgraph Layer_Storage["Storage, Filesystem & Wall Clock"]
DB[("Production: context/control_plane.db")]
SimDB[("Simulation: context/simulation/simulation_control_plane.db")]
HumanAnchor["Human key: context/identity/allowed_signers"]
SimAnchor["Agent key: context/simulation/identity/allowed_signers"]
Binding["First signed gate binds one approver key per task"]
PushCheck["Production push: complete gate history + exact challenges + human signatures"]
Isolation["Separate constrained runtime required; same OS user is not hostile-agent isolation"]
Receipts["verification_receipts: gate and artifact identities"]
RepoFiles["Repository and verifier files"]
CatalogFiles["Model catalog JSON files"]
Clock["Wall clock"]
end
%% Relationships: Entry to Orchestration & Governance
Callers --> Facade
Facade --> Lifecycle
Facade --> State
Facade --> Policy
Facade --> Coordinator
Facade --> Delegation
Coordinator --> Registry
Coordinator --> Guidance
Coordinator --> ForceClose
Coordinator --> ArtifactGate
Coordinator --> PlanBranch
Coordinator --> PlanAcceptance
Coordinator --> ReviewSelection
Coordinator --> ReviewDispatch
%% Governance & Policy Interactions
Registry --> Templates
Registry -.->|"syncs authorized_actor & questions"| SQLiteAdapter
Policy -.->|"requests policy facts via ctx callables"| PersistencePort
Policy -->|"enforces at APPROVED to IN_WORKTREE"| MainReconciliation
Policy --> TransitionRequest
TransitionRequest --> SigningGate
SigningGate -->|"verified outside the write lock, consumed once in the commit transaction"| PersistencePort
TransitionRequest --> PersistencePort
MainReconciliation --> Worktree
HumanClose --> State
HumanClose --> SigningGate
SigningGate -.->|"proof=sshsig audit receipt: principal + key fingerprint"| Receipts
%% Review Flow Interactions
ReviewDispatch --> ReviewReports
ReviewReports --> ReviewSynthesis
ReviewSynthesis --> PlanAcceptance
ReviewSynthesis --> Worktree
PlanBranch --> PlanAcceptance
PlanAcceptance --> ArtifactGate
Worktree --> Inventory
Inventory --> ReviewDispatch
Inventory --> PersistencePort
%% Ports Wiring
Facade --> PersistencePort
Facade --> CryptoPort
Facade --> FilesystemPort
Facade --> ModelPort
Facade --> ClockPort
ArtifactGate --> FilesystemPort
ArtifactGate --> PersistencePort
InterviewOutline --> PersistencePort
InterviewOutline --> FilesystemPort
ReviewDispatch --> ModelPort
Delegation --> PersistencePort
%% Adapters Wiring
PersistencePort --> SQLiteAdapter
CryptoPort --> CryptoAdapter
FilesystemPort --> FilesystemAdapter
ModelPort --> ModelAdapter
ClockPort --> ClockAdapter
%% Storage Wiring
SQLiteAdapter --> DB
SQLiteAdapter -->|"explicit simulation routing only"| SimDB
SigningGate --> Binding
DB --> HumanAnchor
SimDB --> SimAnchor
DB --> PushCheck
HumanAnchor --> PushCheck
Isolation -.-> HumanAnchor
SimDB -.->|"never authorizes production push"| PushCheck
DB -.-> Receipts
DB -.->|"enforces valid_transitions & required questions; proof edges require a consumed transition_request (no actor-column trust)"| State
CryptoAdapter --> RepoFiles
FilesystemAdapter --> RepoFiles
ModelAdapter --> CatalogFiles
ClockAdapter --> Clock
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |