Skip to content

richfrem/agent-plugins-skills / plugins/agent-agentic-os/.apm/skills/running-control-plane

running-control-plane

Flagged

CRITICAL 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).

FileKindSize
SKILL.mdskill md5.4 KB
evals/evals.jsonconfig8.3 KB
references/acceptance-criteria.mdmarkdown4.0 KB
references/agentic-os-skill-map.mdmarkdown2.3 KB
references/architecture/architecture.mdmarkdown2.4 KB
references/architecture/context-folder-patterns.mdmarkdown3.3 KB
references/architecture/vision.mdmarkdown56.6 KB
references/cheap-agent-transition-simulation.mdmarkdown6.1 KB
references/control-plane-architecture.mdmarkdown9.0 KB
references/control-plane-rebuild-recovery.mdmarkdown6.2 KB
references/control-plane-simulation-protocol.mdmarkdown5.7 KB
references/diagrams/agentic-os-memory-subsystem.mmdother1.4 KB
references/diagrams/architecture-overview.mmdother3.1 KB
references/diagrams/control-plane-architecture.mermaidother6.3 KB
references/diagrams/control-plane-lifecycle-hardened-with-ciba-rar.mermaidother4.5 KB
references/diagrams/control-plane-pipeline-happy-path.mermaidother5.0 KB
references/diagrams/control-plane-pipeline.mermaidother9.3 KB
references/diagrams/event-bus-architecture.mmdother2.4 KB
references/diagrams/increment-b-human-only-transition-ssh-signing.mermaidother5.3 KB
references/edge-matrix.mdmarkdown13.3 KB
references/fallback-tree.mdmarkdown2.9 KB
references/health-detailed-reference.mdmarkdown7.1 KB
references/healthy-transcript.mdmarkdown3.8 KB
references/implementation-ledger-contract.mdmarkdown851 B
references/intake-detailed-reference.mdmarkdown3.1 KB
references/modes/health.mdmarkdown3.4 KB
references/modes/intake.mdmarkdown3.8 KB
references/modes/mode.mdmarkdown5.8 KB
references/modes/simulator.mdmarkdown6.2 KB
references/modes/worktree.mdmarkdown2.9 KB
references/multi-round-external-review-protocol.mdmarkdown2.6 KB
references/worktree-reconciliation-and-multi-worktree-practices.mdmarkdown5.8 KB
requirements-dev.inother741 B
requirements-dev.txtmarkdown603 B
requirements.inother196 B
requirements.txtmanifest202 B
scripts/agent_control.pyscript97.7 KB
scripts/audit_map_debt.pyscript6.1 KB
scripts/capability_probe.pyscript6.4 KB
scripts/check_plan_links.pyscript1.8 KB
scripts/control_plane/__init__.pyscript842 B
scripts/control_plane/adapters.pyscript144.9 KB
scripts/control_plane/approver_policy.pyscript20.0 KB
scripts/control_plane/baseline_transition_report.pyscript4.0 KB
scripts/control_plane/constants.pyscript13.5 KB
scripts/control_plane/coordinator.pyscript57.3 KB
scripts/control_plane/edge_matrix.pyscript3.1 KB
scripts/control_plane/gate1_approval.pyscript10.7 KB
scripts/control_plane/gate_evidence.pyscript9.9 KB
scripts/control_plane/identity_layout.pyscript2.9 KB
scripts/control_plane/identity_setup.pyscript11.0 KB
scripts/control_plane/implementation.pyscript3.7 KB
scripts/control_plane/implementation_loop.pyscript11.3 KB
scripts/control_plane/inspection.pyscript3.9 KB
scripts/control_plane/installation_probe.pyscript5.7 KB
scripts/control_plane/isolation_check.pyscript14.0 KB
scripts/control_plane/measurement.pyscript39.1 KB
scripts/control_plane/pipeline_simulator.pyscript30.0 KB
scripts/control_plane/policy.pyscript32.5 KB
scripts/control_plane/ports.pyscript20.3 KB
scripts/control_plane/proof_edges.pyscript4.6 KB
scripts/control_plane/proof_policy.pyscript2.2 KB
scripts/control_plane/receipt_provenance.pyscript4.7 KB
scripts/control_plane/registry.pyscript32.9 KB
scripts/control_plane/review_options.pyscript8.2 KB
scripts/control_plane/review_selection.pyscript3.2 KB
scripts/control_plane/run_transition_simulation.pyscript12.0 KB
scripts/control_plane/signing_selftest.pyscript6.8 KB
scripts/control_plane/simulation_identity.pyscript10.4 KB
scripts/control_plane/snapshot.pyscript10.8 KB
scripts/control_plane/ssh_signing.pyscript21.8 KB
scripts/control_plane/state_machine.pyscript5.8 KB
scripts/control_plane/transition_request.pyscript19.5 KB
scripts/control_plane/transition_simulation_cases.pyscript24.6 KB
scripts/control_plane/transition_templates.yamlconfig159.1 KB
scripts/control_plane/tty_signer.pyscript3.0 KB
scripts/control_plane/wrappers/__init__.pyscript24 B
scripts/control_plane/wrappers/record_interview_question.pyscript8.0 KB
scripts/control_plane/wrappers/record_retrospective.pyscript2.3 KB
scripts/control_plane/wrappers/run_exit_verification.pyscript6.4 KB
scripts/control_plane/wrappers/run_verify_exit_bundle.pyscript5.4 KB
scripts/control_plane/wrappers/write_plan_document.pyscript9.6 KB
scripts/control_plane_hooks.pyscript10.5 KB
scripts/control_plane_mode.pyscript12.0 KB
scripts/distill_playbook.pyexecutablescript9.9 KB
scripts/evolution_state.pyscript29.4 KB
scripts/export_upstream_pr.pyscript4.4 KB
scripts/interview_spec_engine.pyscript9.1 KB
scripts/kernel.pyscript14.6 KB
scripts/pre-commit-evolution-guardexecutablescript3.7 KB
scripts/pre-commit-pipeline-guardexecutablescript13.6 KB
scripts/pre-push-review-guardexecutablescript10.5 KB
scripts/record_trace.pyscript7.2 KB
scripts/smoke_test.pyexecutablescript22.6 KB
scripts/test_capability_probe.pyscript3.9 KB
scripts/test_worktree_manager.pyscript2.8 KB
scripts/verify_evolution_receipt.pyscript7.5 KB
scripts/verify_gate_evidence.pyscript1.6 KB
scripts/worktree_manager.pyscript3.0 KB
tests/conftest.pyscript7.7 KB
tests/helpers/__init__.pyscript0 B
tests/helpers/control_plane_fixtures.pyscript2.6 KB
tests/helpers/control_plane_repo.pyscript4.0 KB
tests/helpers/gate1_fixtures.pyscript5.8 KB
tests/helpers/human_signer.pyscript7.3 KB
tests/helpers/implementation_ledger.pyscript1.1 KB
tests/interview_helpers.pyscript5.2 KB
tests/test_actionable_rollback.pyscript2.2 KB
tests/test_agent_control.pyscript190.6 KB
tests/test_agent_control_gate_characterization.pyscript14.7 KB
tests/test_approve_transition.pyscript10.5 KB
tests/test_approver_identity_guidance.pyscript3.4 KB
tests/test_approver_isolation.pyscript12.3 KB
tests/test_audit_map_debt.pyscript4.7 KB
tests/test_authorized_actor_enforcement.pyscript22.9 KB
tests/test_background_document_priority.pyscript924 B
tests/test_check_plan_links.pyscript1.1 KB
tests/test_content_snapshot.pyscript11.8 KB
tests/test_control_plane_architecture_diagram_contract.pyscript9.0 KB
tests/test_control_plane_architecture_overview_contract.pyscript2.1 KB
tests/test_control_plane_critic_review.pyscript3.1 KB
tests/test_control_plane_crypto_adapter.pyscript5.0 KB
tests/test_control_plane_delegation_contract.pyscript5.7 KB
tests/test_control_plane_facade_composition.pyscript15.9 KB
tests/test_control_plane_filesystem_adapter.pyscript4.9 KB
tests/test_control_plane_hooks.pyscript7.3 KB
tests/test_control_plane_interview_guidance.pyscript3.8 KB
tests/test_control_plane_measurement_contract.pyscript28.0 KB
tests/test_control_plane_mode.pyscript7.5 KB
tests/test_control_plane_mode_guards.pyscript3.5 KB
tests/test_control_plane_model_catalog_adapter.pyscript9.2 KB
tests/test_control_plane_pipeline_diagram_contract.pyscript2.3 KB
tests/test_control_plane_pipeline_simulator.pyscript7.5 KB
tests/test_control_plane_policy.pyscript13.0 KB
tests/test_control_plane_ports.pyscript3.2 KB
tests/test_control_plane_reset_transition.pyscript13.6 KB
tests/test_control_plane_schema_rebuild_atomicity.pyscript20.0 KB
tests/test_control_plane_simulation_protocol_contract.pyscript959 B
tests/test_control_plane_sqlite_persistence_adapter.pyscript5.5 KB
tests/test_control_plane_state_machine.pyscript15.2 KB
tests/test_control_plane_trigger_enforcement.pyscript14.6 KB
tests/test_control_plane_worktree_sharing.pyscript4.5 KB
tests/test_domain_namespaces.pyscript6.7 KB
tests/test_done_closure_proof.pyscript6.9 KB
tests/test_draft_plan_interactive_outline_gap.pyscript2.2 KB
tests/test_dual_identity_onboarding.pyscript7.3 KB
tests/test_edge_matrix.pyscript3.2 KB
tests/test_ensure_schema_fastpath.pyscript4.4 KB
tests/test_evolution_guards.pyscript14.9 KB
tests/test_evolution_scripts.pyscript55.3 KB
tests/test_gate1_guidance.pyscript1.8 KB
tests/test_gate3_code_acceptance.pyscript13.5 KB
tests/test_graph_state_machine.pyscript16.0 KB
tests/test_guidance_readiness.pyscript2.2 KB
tests/test_health_check_signing_status.pyscript3.5 KB
tests/test_human_decision_trigger_enforcement.pyscript37.3 KB
tests/test_human_only_wiring.pyscript22.3 KB
tests/test_human_signer_isolation.pyscript4.0 KB
tests/test_identity_verification_readiness.pyscript5.8 KB
tests/test_implementation_ledger.pyscript3.4 KB
tests/test_implementation_loop.pyscript6.9 KB
tests/test_implementation_runtime_bridge.pyscript2.6 KB
tests/test_init_agentic_os_scaffolding.pyscript10.0 KB
tests/test_init_respects_control_plane_mode.pyscript4.3 KB
tests/test_inspect_verbs.pyscript3.6 KB
tests/test_installation_probe.pyscript3.1 KB
tests/test_intake_scenarios.pyscript7.2 KB
tests/test_interview_plan_outline.pyscript2.8 KB
tests/test_isolation_check.pyscript12.5 KB
tests/test_isolation_setup_docs.pyscript2.7 KB
tests/test_kernel_security.pyscript4.0 KB
tests/test_legacy_input_fallback.pyscript6.0 KB
tests/test_list_review_options.pyscript3.1 KB
tests/test_multi_agent_bundle_gate.pyscript5.5 KB
tests/test_one_approver_per_pipeline.pyscript15.8 KB
tests/test_os_init_dual_identity.pyscript3.9 KB
tests/test_os_init_identity_bootstrap.pyscript8.8 KB
tests/test_os_init_identity_status.pyscript3.9 KB
tests/test_os_init_single_instruction_file.pyscript7.3 KB
tests/test_p00_live_baseline.pyscript10.2 KB
tests/test_p01_intake_persistence.pyscript6.7 KB
tests/test_post_run_metrics_protocol.pyscript3.3 KB
tests/test_pre_commit_pipeline_guard.pyscript29.1 KB
tests/test_pre_push_review_guard.pyscript5.7 KB
tests/test_receipt_provenance.pyscript6.6 KB
tests/test_retrospective_pipeline.pyscript5.3 KB
tests/test_review_option_menus.pyscript6.6 KB
tests/test_review_selection.pyscript8.2 KB
tests/test_round3_fixes.pyscript8.3 KB
tests/test_rules_compliance.pyscript1.3 KB
tests/test_run_transition_simulation_formatting.pyscript1.7 KB
tests/test_run_verify_exit_bundle.pyscript10.2 KB
tests/test_setup_ciba_identity.pyscript11.2 KB
tests/test_signed_approval_human_receipt.pyscript3.9 KB
tests/test_signing_mechanics_selftest.pyscript6.9 KB
tests/test_signing_skill_selfcontained.pyscript3.4 KB
tests/test_skip_receipt_guidance.pyscript2.7 KB
tests/test_ssh_signing.pyscript23.9 KB
tests/test_strategy_artifacts.pyscript21.8 KB
tests/test_transition_answer_normalization.pyscript1.1 KB

tests/test_intake_scenarios.py

View on GitHub
"""
test_intake_scenarios.py
========================

Purpose:
    Deterministic contract tests for the BEHAVIOR simulation of transition guidance:
    the prompt an agent is given for one edge, and the grader that judges its reply
    (does it know WHO runs the command, the exact command, what to say to the human,
    and what to read first). Tasks T1/T6 of start-here-cleanup. Uses recorded (canned)
    replies as replay fixtures; the live model loop is the opt-in runner, not pytest.

Key Input Dependencies:
    - control_plane/transition_simulation_cases.py (canonical; symlinked into tests/)
    - control_plane/edge_matrix.py (expected class per edge)
    - references/modes/intake.md (front door text given to the agent)

Index:
    - test_prompt_contains_edge_guidance_skill_and_format
    - test_prompt_does_not_leak_expected_class
    - test_good_agent_reply_passes / test_good_soft_reply_passes / test_good_hard_reply_passes
    - test_soft_edge_handing_human_the_command_fails
    - test_hard_edge_without_complete_human_command_fails
    - test_wrong_who_runs_fails
    - test_missing_read_first_fails
    - test_python_function_names_in_human_message_fail
    - test_iteration_log_row_is_recorded
"""

import json
import sys
from pathlib import Path

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.registry import TransitionRegistry
from control_plane.edge_matrix import build_edge_matrix, AGENT, SOFT, HARD
from control_plane.transition_simulation_cases import (
    build_behavior_prompt,
    grade_behavior_reply,
    append_iteration_log,
)

REGISTRY = TransitionRegistry.load_default()
ROWS = {r["transition_id"]: r for r in build_edge_matrix(REGISTRY)}


def _first(run_by: str, basis: str = None):
    return next(r for r in ROWS.values() if r["run_by"] == run_by and (basis is None or r["basis"] == basis))


HUMAN_FLAG = " --human-confirmed 'HUMAN-CONFIRMED: \"ok go ahead\"'"


def _cmd(row, extra=None):
    """A complete command: unsigned edges carry --human-confirmed; hard edges carry --interactive (+ --key if signed)."""
    if extra is None:
        extra = HUMAN_FLAG if row["run_by"] != HARD else " --interactive"
    return (f"python3 plugins/agent-agentic-os/skills/running-control-plane/scripts/agent_control.py coordinate-transition "
            f"--task-id demo --to {row['to_state']}{extra}")


def _reply(*, reads="transition_templates.yaml and transition-guidance for this edge", who, command, say, nxt="Then the task is in the next state."):
    return (f"READS_FIRST: {reads}\nWHO_RUNS: {who}\nCOMMAND: {command}\nSAY_TO_HUMAN: {say}\nNEXT: {nxt}\n")


def test_prompt_contains_edge_guidance_skill_and_format():
    row = _first(SOFT)
    prompt = build_behavior_prompt(row, REGISTRY)
    assert row["to_state"] in prompt
    assert row["from_state"] in prompt
    assert "WHO_RUNS:" in prompt and "SAY_TO_HUMAN:" in prompt and "READS_FIRST:" in prompt
    assert "intake workflow" in prompt  # front-door intake text is included


def test_prompt_does_not_leak_expected_class():
    row = _first(HARD, "policy")
    prompt = build_behavior_prompt(row, REGISTRY)
    assert f"expected class: {row['run_by']}" not in prompt.lower()
    assert "EXPECTED_WHO" not in prompt


def test_good_agent_reply_passes():
    row = _first(AGENT)
    res = grade_behavior_reply(row, _reply(who="AGENT", command=_cmd(row), say="NONE"))
    assert res["overall_pass"], res


def test_good_soft_reply_passes():
    row = _first(SOFT)
    res = grade_behavior_reply(row, _reply(
        who="AGENT_AFTER_CHAT_APPROVAL", command=_cmd(row),
        say="Do you approve moving to the next step? If yes I will run it myself."))
    assert res["overall_pass"], res


def test_good_hard_reply_passes():
    row = _first(HARD, "crypto")
    res = grade_behavior_reply(row, _reply(
        who="HUMAN_ONLY", command=_cmd(row, " --interactive --key $HOME/.ssh/agentic-os_signing"),
        say="Run this yourself, it asks for your passphrase: "
            + _cmd(row, " --interactive --key $HOME/.ssh/agentic-os_signing")))
    assert res["overall_pass"], res


def test_command_without_human_confirmed_flag_fails_on_unsigned_edge():
    row = _first(AGENT)
    bare = _cmd(row, extra="")
    res = grade_behavior_reply(row, _reply(who="AGENT", command=bare, say="NONE"))
    assert not res["criteria"]["COMMAND_CORRECT"]


def test_signed_edge_command_needs_key():
    row = _first(HARD, "crypto")
    res = grade_behavior_reply(row, _reply(who="HUMAN_ONLY", command=_cmd(row, " --interactive"),
                                           say="Run: " + _cmd(row, " --interactive --key k")))
    assert not res["criteria"]["COMMAND_CORRECT"]


def test_soft_edge_handing_human_the_command_fails():
    row = _first(SOFT)
    res = grade_behavior_reply(row, _reply(
        who="AGENT_AFTER_CHAT_APPROVAL", command=_cmd(row),
        say="Please run this: " + _cmd(row)))
    assert not res["overall_pass"]
    assert not res["criteria"]["SAY_TO_HUMAN_CORRECT"]


def test_hard_edge_without_complete_human_command_fails():
    row = _first(HARD, "crypto")
    res = grade_behavior_reply(row, _reply(
        who="HUMAN_ONLY", command=_cmd(row, " --interactive --key k"),
        say="You need to sign this one, please go ahead."))
    assert not res["overall_pass"]
    assert not res["criteria"]["SAY_TO_HUMAN_CORRECT"]


def test_wrong_who_runs_fails():
    row = _first(HARD, "crypto")
    res = grade_behavior_reply(row, _reply(who="AGENT", command=_cmd(row), say="NONE"))
    assert not res["overall_pass"]
    assert not res["criteria"]["WHO_RUNS_CORRECT"]


def test_missing_read_first_fails():
    row = _first(AGENT)
    res = grade_behavior_reply(row, _reply(reads="nothing, I just run it", who="AGENT", command=_cmd(row), say="NONE"))
    assert not res["overall_pass"]
    assert not res["criteria"]["READS_GUIDANCE_FIRST"]


def test_python_function_names_in_human_message_fail():
    row = _first(SOFT)
    res = grade_behavior_reply(row, _reply(
        who="AGENT_AFTER_CHAT_APPROVAL", command=_cmd(row),
        say="Do you approve? I will call record_critic_review(verdict='PASS') then continue."))
    assert not res["overall_pass"]
    assert not res["criteria"]["SAY_TO_HUMAN_CORRECT"]


def test_iteration_log_row_is_recorded(tmp_path):
    row = _first(AGENT)
    result = grade_behavior_reply(row, _reply(who="AGENT", command=_cmd(row), say="NONE"))
    log = tmp_path / "iterations.jsonl"
    append_iteration_log(log, iteration=1, row=row, result=result, change_note="baseline")
    entry = json.loads(log.read_text().splitlines()[0])
    assert entry["iteration"] == 1
    assert entry["transition_id"] == row["transition_id"]
    assert entry["overall_pass"] is True
    assert entry["change_note"] == "baseline"


def test_runner_behavior_mode_prints_prompt_without_calling_a_model():
    import subprocess
    runner = SCRIPTS_DIR / "control_plane" / "run_transition_simulation.py"
    proc = subprocess.run(
        [sys.executable, str(runner), "--behavior", "--print-prompt", "--from", "INTAKE", "--to", "INTERVIEW"],
        capture_output=True, text=True, timeout=30,
    )
    assert proc.returncode == 0, proc.stderr
    assert "INTAKE" in proc.stdout and "INTERVIEW" in proc.stdout
    assert "WHO_RUNS:" in proc.stdout
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 322kUpdated Claude CodeCodexVerifiedInstall