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/health-detailed-reference.md
View on GitHub# the `health` mode — Detailed Reference
Extracted from SKILL.md per Layer-1 procedural-core line budget (issue #551).
## Contents
- [Phase 3.5 — Substrate Completeness Check](#phase-35--substrate-completeness-check-full-commands)
- [Consumer Guidance on Plugin Drift & Gaps](#consumer-guidance-on-plugin-drift--gaps)
- [Phase 5 — Self-Assessment Survey](#phase-5--self-assessment-survey-full-detail)
## Phase 3.5 — Substrate Completeness Check (full commands)
Verify the scaffolding artifacts the `init` mode --retrofit` is responsible for creating. This
check exists because of DEBT-20260905-12/-13/-14 (see the repository-root `map-debt.md` ledger): the retrofit code
path historically diverged from the fresh-setup path and silently skipped substrates —
run this check on every health check, not just once after install, since a stale/pre-fix
`init_agentic_os.py` copy can reintroduce the gap.
```bash
test -f context/control_plane.db && echo "OK control_plane.db" || echo "MISSING control_plane.db"
test -f .claude/hooks/hooks.json && echo "OK hooks.json (Stop turn hook)" || echo "MISSING hooks.json"
test -f .git/hooks/pre-commit-evolution-guard && echo "OK pre-commit-evolution-guard" || echo "MISSING pre-commit-evolution-guard"
test -f .github/workflows/verify-evolution-integrity.yml && echo "OK verify-evolution-integrity.yml (CI Gate)" || echo "MISSING verify-evolution-integrity.yml"
# Verify AGENTS.md (the canonical instruction file) contains the Phase 0 intake rule
grep -q "running-control-plane" AGENTS.md && echo "OK AGENTS.md (intake rule)" || echo "MISSING AGENTS.md intake rule"
# Audit for lingering backup files (.bak) requiring agent review
BAK_FILES=$(find . -maxdepth 2 -name "*.bak" 2>/dev/null)
if [ -n "$BAK_FILES" ]; then
echo "ATTENTION: Lingering backup files detected (.bak):"
echo "$BAK_FILES"
echo "ACTION: Consuming agent must review diffs against active files, reconcile any custom rules, and then remove the .bak files."
else
echo "OK: No unreviewed .bak backup files"
fi
# If local plugins exist, verify each has references/evolution-log.md
if [ -d "plugins" ]; then
for p in plugins/*/; do
[ -d "$p" ] || continue
test -f "${p}references/evolution-log.md" && echo "OK ${p}references/evolution-log.md" || echo "MISSING ${p}references/evolution-log.md"
done
fi
```
### Identity registration (confirm the `init` mode's identity step actually happened)
A first the `init` mode wires the gates but cannot register the human's key (it is agent-run), so confirm it:
```bash
# Run from the `health` mode directory, or activate the skill:
python3 ../setting-up-agentic-os/scripts/setup_ciba_identity.py --check # read-only, no terminal needed
```
Read the "Approval identities" lines and apply the mode table in the skill's Phase 3.6. In short, with the
control plane **enabled**: `Human approval: not ready` is Tier 1 (the human enrolls their key; the `init` mode run in
their own terminal offers to), `Simulation: not set up` is Tier 1 but agent-fixable
(run `../setting-up-agentic-os/scripts/init_agentic_os.py --target . --retrofit` from the `init` mode), `Isolation: not ready` is a
Tier 2 recommendation. With it **disabled**, report all three as informational and raise no finding. Never run
the setup yourself and never edit `allowed_signers*`.
### Control plane mode (run before judging the checks above)
The control plane can be switched off on purpose with the `mode` mode. Read the
declared mode first, because it changes what "healthy" means:
```bash
# Run from the `mode` mode directory, or activate the skill:
python3 scripts/control_plane_mode.py status
```
- **Mode `enabled`, exit 0**: the members are installed and both control-plane guards are wired.
Judge the checks above as normal.
- **Mode `disabled`, exit 0**: report `OK control plane DISABLED (intentional)`. Do **not** raise a
finding for the `intake` mode rule being absent from the instruction files, and do **not** run
`--retrofit` to "repair" it: retrofit honours the mode and would only confuse the picture.
`control_plane.db` is still expected (disable never deletes it).
- **Exit 1 (inconsistent)**: this is a Tier 1 finding. The declared mode and the repo disagree
(for example, mode `disabled` but the `intake` mode is installed, or mode `enabled` but a guard is
unwired). Recommend re-running the toggle for the declared mode, which reconciles it:
`... control_plane_mode.py enable --dry-run` (or `disable`), then `--yes` after the user confirms.
Do not hand-edit hooks or the ownership file.
- **Skill not installed** (older install): skip this step and judge the checks above as before.
**If any report MISSING**: this is a Tier 1 finding, not merely informational.
Recommend re-running the retrofit immediately in the health check summary:
```bash
# Run from the `init` mode directory, or activate the skill:
python3 ../setting-up-agentic-os/scripts/init_agentic_os.py --target . --retrofit
```
All substrates are idempotent to create (skip-if-exists), so re-running retrofit is always safe even
when only one substrate is missing — do not hand-create the individual file as a workaround, as
that bypasses schema/WAL-mode setup for `control_plane.db`, the guard-wiring logic for the
git hook, and the standard evolution header templates.
## Consumer Guidance on Plugin Drift & Gaps
If Phase 3.5 or runtime audits detect modified or drifted local skills/scripts:
1. **Upstream Defect/Gap**: If the local modification fixes an engine, harness, or shared skill bug, follow the **Upstream Contribution Protocol**: test the change, port it to a branch in `richfrem/agent-plugins-skills`, submit a PR, or log an issue with reproduction details.
2. **Local Domain Customization**: If the change is specific to the consuming project, ensure it is housed in `.agent/rules/local-*` or a project-specific plugin under `plugins/<local-name>/` rather than directly diverging shared upstream skills. This ensures the `init` mode --retrofit` can safely update core substrates without clobbering project-specific logic.
## Phase 5 — Self-Assessment Survey (full detail)
Complete the Post-Run Self-Assessment Survey (the post-run survey in the `improving-skills-in-lab` skill) after
every run — reflect on what was found so the OS can improve its own diagnostics.
**Count-Based Signals**: How many anomalies were detected? How many false positives? How many
times was a metric ambiguous or hard to interpret?
**Qualitative Friction**:
1. Which metric was hardest to interpret — why?
2. Was any anomaly detected that the current metrics don't capture well?
3. What pattern in `events.jsonl` was most surprising or concerning?
4. What one additional metric would make the next health check more useful?
**Improvement Recommendation**: What one change to this skill or the metrics definition
should be tested before the next run?
Save to: `${CLAUDE_PROJECT_DIR}/context/memory/retrospectives/survey_[YYYYMMDD]_[HHMM]_os-control-health.md`
```bash
python3 scripts/kernel.py emit_event --agent os-control-health \
--type learning --action survey_completed \
--summary "retrospectives/survey_[DATE]_[TIME]_os-control-health.md"
```
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 |