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/architecture-overview.mmd
View on GitHub---
config:
layout: elk
theme: base
---
%% Agentic OS kernel - architecture overview
%% Matches scripts/kernel.py: acquire_lock, release_lock, emit_event, read_events,
%% state_update, state_increment, claim_task. Files: events.jsonl, .locks/, os-state.json,
%% agents.json, agents/<id>.cursor. Wait/inbox/guest-token/failover design ideas from the
%% earlier red-team revision are not implemented and are no longer drawn.
flowchart TB
subgraph OS ["Agentic OS - Project-Scoped Address Space (context/)"]
direction TB
subgraph KernelLayer ["Kernel Layer - kernel.py"]
direction LR
KernelPy["kernel.py command set<BR>emit_event - validated append<BR>read_events - cursor-based delta<BR>acquire_lock --ttl N / release_lock<BR>state_update / state_increment<BR>claim_task - atomic lock + registry"]
AgentReg[("agents.json<BR>Permitted agents")]
OSState[("os-state.json<BR>Task registry<BR>Counters")]
end
subgraph BusLayer ["Event Bus"]
EventBus[("context/events.jsonl<BR>Broadcast events - kernel-gated<BR>Rotated at 10 MB")]
Cursors[("context/agents/id.cursor<BR>Per-agent read offset<BR>Delta reads via kernel")]
end
subgraph LockLayer ["Lease-Based Locks"]
Locks[(".locks/name.lock/<BR>meta.json: pid, acquired_at, expires_at<BR>Stolen on dead PID or expired lease")]
end
subgraph MemoryLayers ["Shared Memory"]
direction LR
L2["L2: Session Logs<BR>context/memory/YYYY-MM-DD.md"]
L3["L3: Long-Term Memory<BR>context/memory.md<BR>Sourced facts only"]
end
end
subgraph Agents ["Agents and Hooks"]
direction LR
LOOP["Coordinating agent<BR>e.g. the `loop` mode of `improving-skills-in-lab` session<BR>Claims tasks, emits events"]
SUB["Sub-agents<BR>e.g. scorer or proposer sessions<BR>Take short leased locks, emit task.complete"]
HOOKS["Hooks<BR>session_start.py, update_memory.py"]
end
subgraph Schema ["Event Schema"]
SchemaBox["Required: id, time, agent, type, action<BR>Optional: status, summary, ttl,<BR>correlation_id, partition_id"]
end
LOOP -- "claim_task, emit, lock" --> KernelPy
SUB -- "emit, read_events delta" --> KernelPy
HOOKS -- "append session actions" --> L2
KernelPy -- "atomic append" --> EventBus
KernelPy -- "update read offset" --> Cursors
KernelPy -- "validates agent" --> AgentReg
KernelPy -- "task registry and counters" --> OSState
KernelPy -- "PID and lease metadata" --> Locks
EventBus -- "the `memory` mode of `improving-skills-in-lab` promotes" --> L2
L2 -- "the `memory` mode of `improving-skills-in-lab` distills" --> L3
classDef agentRole fill:#f9f0ff,stroke:#5e35b1,stroke-width:2px
classDef kernel fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
classDef bus fill:#fffde7,stroke:#fbc02d,stroke-width:3px
classDef lock fill:#fce4ec,stroke:#c62828,stroke-width:2px
classDef mem fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
classDef schema fill:#fff3e0,stroke:#e65100,stroke-width:1px
class LOOP,SUB,HOOKS agentRole
class KernelPy,AgentReg,OSState kernel
class EventBus,Cursors bus
class Locks lock
class L2,L3 mem
class SchemaBox schema
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 |