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).
tests/test_init_agentic_os_scaffolding.py
View on GitHub"""
test_init_agentic_os_scaffolding.py — Contract & Unit Tests for os-control-init Scaffolding Parity
========================================================================================
Purpose:
Verifies that init_agentic_os.py (both fresh setup and --retrofit) correctly:
1. Scaffolds repository-level substrates (control_plane.db, hooks.json, evolution guard, 3-layer memory)
2. Identifies and scaffolds missing plugin-level evolution substrates (references/evolution-log.md)
when local plugins exist under plugins/
3. Directs the user/agent to point to the running-control-plane health mode in print_next_steps()
Key Input Dependencies:
- plugins/agent-agentic-os/skills/setting-up-agentic-os/scripts/init_agentic_os.py
"""
import subprocess
import sys
from pathlib import Path
import pytest
SCRIPTS_DIR = Path(__file__).resolve().parent.parent / "scripts"
if str(SCRIPTS_DIR) not in sys.path:
sys.path.insert(0, str(SCRIPTS_DIR))
from control_plane.constants import (
STATE_WORKTREE_REVIEW,
)
SETUP_SCRIPTS = Path(__file__).resolve().parents[2] / "setting-up-agentic-os" / "scripts" # the setup skill beside this one
REPO_ROOT = Path(__file__).resolve().parents[5]
SKILL_DIR = Path(__file__).resolve().parent.parent
INIT_SCRIPT = SETUP_SCRIPTS / "init_agentic_os.py"
@pytest.fixture
def target_repo(tmp_path):
"""Creates a throwaway repository directory for testing os-control-init."""
repo = tmp_path / "test_project"
repo.mkdir()
subprocess.run(["git", "init"], cwd=repo, check=True, capture_output=True)
subprocess.run(["git", "config", "user.name", "Test User"], cwd=repo, check=True)
subprocess.run(["git", "config", "user.email", "test@example.com"], cwd=repo, check=True)
# create dummy README to allow commit
(repo / "README.md").write_text("# Test Project\n", encoding="utf-8")
subprocess.run(["git", "add", "."], cwd=repo, check=True)
subprocess.run(["git", "commit", "-m", "Initial commit"], cwd=repo, check=True)
return repo
def test_retrofit_scaffolds_plugin_evolution_logs_when_plugins_exist(target_repo):
"""When plugins/ exists, --retrofit must ensure each plugin has references/evolution-log.md."""
# Create two sample plugins
p1 = target_repo / "plugins" / "sample-plugin-a"
(p1 / "skills" / "skill-a").mkdir(parents=True)
(p1 / "skills" / "skill-a" / "SKILL.md").write_text("---\nname: skill-a\n---\n", encoding="utf-8")
p2 = target_repo / "plugins" / "sample-plugin-b"
(p2 / "references").mkdir(parents=True)
existing_log = p2 / "references" / "evolution-log.md"
existing_log.write_text("# Existing Log\n", encoding="utf-8")
# Run init_agentic_os.py --target <target_repo> --retrofit
res = subprocess.run(
[sys.executable, str(INIT_SCRIPT), "--target", str(target_repo), "--retrofit"],
capture_output=True,
text=True,
)
assert res.returncode == 0, f"Retrofit failed with stdout:\n{res.stdout}\nstderr:\n{res.stderr}"
# Verify plugin A received references/evolution-log.md
p1_log = p1 / "references" / "evolution-log.md"
assert p1_log.exists(), "sample-plugin-a should have references/evolution-log.md scaffolded"
assert "sample-plugin-a" in p1_log.read_text(encoding="utf-8")
# Verify plugin B's existing log was preserved (not clobbered)
assert existing_log.read_text(encoding="utf-8") == "# Existing Log\n"
def test_next_steps_directs_to_os_health_check(target_repo):
"""Completion output of init_agentic_os.py must direct the agent to the running-control-plane health mode."""
res = subprocess.run(
[sys.executable, str(INIT_SCRIPT), "--target", str(target_repo), "--retrofit"],
capture_output=True,
text=True,
)
assert res.returncode == 0
assert "running-control-plane (health mode)" in res.stdout, "Completion output must direct user/agent to the health mode"
def test_scaffolds_github_ci_evolution_workflow(target_repo):
"""Both fresh setup and retrofit must scaffold .github/workflows/verify-evolution-integrity.yml."""
res = subprocess.run(
[sys.executable, str(INIT_SCRIPT), "--target", str(target_repo), "--retrofit"],
capture_output=True,
text=True,
)
assert res.returncode == 0
ci_workflow = target_repo / ".github" / "workflows" / "verify-evolution-integrity.yml"
assert ci_workflow.exists(), "CI workflow verify-evolution-integrity.yml must be scaffolded"
assert "Verify Evolution & Map Debt Compliance" in ci_workflow.read_text(encoding="utf-8")
def test_retrofit_enriches_claude_md_with_phase0_and_control_plane(target_repo):
"""--retrofit moves CLAUDE.md content into AGENTS.md (the single instruction file) and enriches AGENTS.md
with the Phase 0 intake rule; CLAUDE.md becomes the pointer (#667)."""
# Seed a basic CLAUDE.md
claude_md = target_repo / "CLAUDE.md"
claude_md.write_text("# Project Instructions\n\n## Overview\nSome custom domain context.\n", encoding="utf-8")
res = subprocess.run(
[sys.executable, str(INIT_SCRIPT), "--target", str(target_repo), "--retrofit"],
capture_output=True,
text=True,
)
assert res.returncode == 0
content = (target_repo / "AGENTS.md").read_text(encoding="utf-8")
assert "Phase 0 Intake & Socratic Gate" in content, "AGENTS.md must be enriched with Phase 0 Intake Gate"
assert "running-control-plane" in content, "AGENTS.md must reference the running-control-plane skill (intake mode)"
assert claude_md.read_text(encoding="utf-8") == "# CLAUDE.md\n\nRead [AGENTS.md](AGENTS.md).\n"
assert "Some custom domain context." in content, "Original project context must be preserved"
def test_scaffolds_plugin_config_with_contribution_mode(target_repo):
"""init_agentic_os.py must scaffold context/plugin-config.json with selected mode."""
res = subprocess.run(
[sys.executable, str(INIT_SCRIPT), "--target", str(target_repo), "--retrofit", "--contribution-mode", "local-patch-and-issue"],
capture_output=True,
text=True,
)
assert res.returncode == 0
config_file = target_repo / "context" / "plugin-config.json"
assert config_file.exists(), "context/plugin-config.json must be scaffolded"
import json
data = json.loads(config_file.read_text(encoding="utf-8"))
assert data.get("contribution_mode") == "local-patch-and-issue"
assert "https://github.com/richfrem/agent-plugins-skills" in data.get("upstream_repo", "")
def test_notifies_consuming_agent_of_backup_files(target_repo):
"""When backup files (.bak) are created during --force or --retrofit, print_next_steps must warn agent to review before deleting."""
# Create an initial CLAUDE.md with standard Overview section
(target_repo / "CLAUDE.md").write_text("# Initial CLAUDE.md\n\n## Overview\nTest project overview.\n", encoding="utf-8")
res = subprocess.run(
[sys.executable, str(INIT_SCRIPT), "--target", str(target_repo), "--retrofit"],
capture_output=True,
text=True,
)
assert res.returncode == 0
assert "ATTENTION: Temporary Backup Files Created (.bak)" in res.stdout
assert "Consuming Agent Directive for Backup Cleanup" in res.stdout
assert "DO NOT blindly delete these .bak files" in res.stdout
def test_scaffolded_control_plane_db_matches_agent_control_schema(target_repo):
"""os-control-init's control_plane.db must match agent_control.py's canonical schema exactly
(task_type column, schema_version table) — not a hand-copied, drifted duplicate that
reproduces the FK-corruption bug on the consumer repo's first agent_control.py run."""
res = subprocess.run(
[sys.executable, str(INIT_SCRIPT), "--target", str(target_repo), "--retrofit"],
capture_output=True,
text=True,
)
assert res.returncode == 0
import sqlite3
db_path = target_repo / "context" / "control_plane.db"
assert db_path.exists()
conn = sqlite3.connect(str(db_path))
tasks_sql = conn.execute("SELECT sql FROM sqlite_master WHERE type='table' AND name='tasks'").fetchone()[0]
assert "task_type" in tasks_sql
assert STATE_WORKTREE_REVIEW in tasks_sql
version_row = conn.execute("SELECT COUNT(*) FROM sqlite_master WHERE type='table' AND name='schema_version'").fetchone()
assert version_row[0] == 1, "schema_version table must exist (same self-healing schema as agent_control.py)"
conn.close()
def test_scaffolded_ci_workflow_has_no_hardcoded_consumer_path(target_repo):
"""The generic scaffolder must not leak a specific consumer's folder names
(investment_screener/) into what it deploys into every repo."""
res = subprocess.run(
[sys.executable, str(INIT_SCRIPT), "--target", str(target_repo), "--retrofit"],
capture_output=True,
text=True,
)
assert res.returncode == 0
workflow_path = target_repo / ".github" / "workflows" / "verify-evolution-integrity.yml"
assert workflow_path.exists()
content = workflow_path.read_text(encoding="utf-8")
assert "investment_screener" not in content
def test_scaffolded_ci_workflow_does_not_interpolate_base_ref_into_shell(target_repo):
"""github.base_ref must be assigned via env:, not interpolated directly into a run:
shell block — the latter is the standard GitHub Actions script-injection anti-pattern."""
res = subprocess.run(
[sys.executable, str(INIT_SCRIPT), "--target", str(target_repo), "--retrofit"],
capture_output=True,
text=True,
)
assert res.returncode == 0
workflow_path = target_repo / ".github" / "workflows" / "verify-evolution-integrity.yml"
content = workflow_path.read_text(encoding="utf-8")
# ${{ github.base_ref }} legitimately appears once, in the env: block (the safe pattern) —
# the anti-pattern is using it directly inside the run: shell block instead of $BASE_REF.
run_block = content.split("run: |", 1)[1]
assert "${{" not in run_block, "No GitHub Actions expression may be interpolated directly into the run: shell block"
assert "env:" in content
assert "BASE_REF: ${{ github.base_ref }}" in content
assert '"$BASE_REF"' in run_block
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: 471k | 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 |