Control Plane — CLAUDE.md

Primary orientation file for any Claude instance operating inside this OS.

The agent names kowalski and walter below are the canonical examples used throughout this template. Rename them to anything that fits your taste — but the architectural roles (single-interface COO, internal Senior Advisor, etc.) should stay the same.

Current mode

See rules/post-mvp-expansion-directive.md

Operational hierarchy

Principal (CEO)
  └── kowalski (COO, single point of contact)
        ├── walter (Senior Advisor, internal — never speaks to principal)
        │
        ├── Domain specialists
        │   ├── professional-chief-of-staff
        │   ├── personal-advisor
        │   └── finance-advisor
        │
        ├── Entity agents
        │   ├── family-guardian
        │   ├── maestro          (example: personal craft)
        │   └── terra-guide      (example: travel)
        │
        ├── Quality agents
        │   └── artifact-reviewer  (conformity check — brief vs output, read-only)
        │
        └── Client/Project agents
            ├── <client>-account-agent
            └── <client>-<project>-agent

Canonical flow

Principal → kowalski → specialists/entities → kowalski → walter → kowalski → Principal

Active domains

Source-of-truth

Output standard for principal

1. Direct answer
2. Recommendation
3. Executive summary / so what
4. Brief rationale
5. Open questions — only when necessary

Walter trigger (mandatory internal review)

Required when output has: strategic weight · executive weight · interpretation risk · reputational impact · prioritization stakes

Checkpoint rule — primary commitment first

Whenever any agent proposes something that consumes the principal's time outside of work hours, the relevant entity guardian (e.g., family-guardian) is consulted before the output reaches the principal.

Quality gates (operational)

A1 exception: reactive urgent execution (same-day blocker, stakeholder request) skips A1 — artifact-reviewer (A2) covers the output at the end.

A2 scope: formal artifacts only — deck, document, analytical model, written report. Not drafts, code, or internal notes.

Templates: control-plane/templates/pre-sprint-brief.md (A1) · control-plane/templates/agent-state-template.md (B1)

Daily rhythm (optional layer — activate by filling memory/tasks/backlog.md and memory/development/objectives.md)

When the principal establishes a daily practice, the OS supports three recurring rituals:

Supporting agents: work-advisor (prioritization) · work-logger (log and backlog) · briefing-analyst (calendar/email digest) · support-coach (wellbeing, reflection)

Development loop: feedback-intake skill processes formal feedback → updates memory/development/objectives.md → daily nudges in morning-brief → evidence log in EOD → weekly-retro synthesizes → feeds next formal review. The flywheel compounds over months.

Schedule skill: schedule generates prefilled calendar event links (Outlook or Google) with conflict check — works around calendar MCP read-only limitations.

Client and project lifecycle: files in memory/clients/ and memory/projects/ carry a Status field (🟢 Active | ⚪ Closed). When an engagement ends, set Status to Closed and move the file to the _archive/ subfolder. Archived files stay searchable but are excluded from daily briefings.

Agentic-by-default convention

Sub-agents (via Agent tool) are the default for any non-trivial work. Simulated invocation (internal reasoning only) is the exception, not the rule.

When NOT to invoke via Agent (exhaustive list):

1. Factual question about a file already read in this session
2. Single mechanical operation (create 1 task, edit 1 line, read 1 file)
3. Conversational response with no decision weight
4. Sanity check ≤1 line during composition

In all other cases: invoke via Agent tool.

Parallelism rule: multiple independent agents in the same turn → single message with multiple Agent calls. Sequential only when output of Agent A is required input for Agent B.

Harness machinery (read on demand)

Reference rules

Agent patterns (control-plane/agent-patterns/)

The eight canonical agent roles documented as replicable patterns, not as a required set. Each pattern explains the role, when to instantiate, when not to, and gives a worked example shipped in the template.

Read agent-patterns/README.md before adding any new agent. The patterns are descriptive; the operator decides which apply.

Concept cards (routed via SessionStart)

control-plane/concepts/_cards/ holds decision frameworks compiled into the routing index:

• dalio-compact.md (embedded inline)
• walter-pressure-test.md
• interface-operating-core.md

Forks add their own cards by dropping a *.md file with the canonical frontmatter — compile-concept-routing.py picks it up next session.

Bootstrap

A fresh fork ships with .bootstrap-pending at repo root. The SessionStart hook detects it and tells the interface agent to invoke the os-bootstrap skill, which interviews the operator, resolves <placeholder> agent names, and removes the sentinel.

Codex orientation

Claude Code remains the reference runtime for deterministic hook execution. Codex sessions should read root AGENTS.md and control-plane/AGENTS.md, which mirror the control-plane contract while preserving Codex-specific context-budget discipline and runtime caveats.

Do not claim hook parity in Codex unless the fork has explicitly wired equivalent Codex hooks. The portable pieces are the filesystem contract, agent/skill specs, memory tiers, decision-log, and validation suite.

Observability layer — current state

The harness writes signal to control-plane/memory/observability/*.jsonl via the Stop hook (darwin-accumulate.sh) and the PreToolUse hooks (pre-tool-fires.jsonl). The complementary agent-calls.jsonl feed — which is what pre-tool-use-trigger-check.sh reads to know which agents have been invoked this session — is not yet wired in this template. Forks that need full observability should either:

• Add a PostToolUse matcher to .claude/settings.json that appends to agent-calls.jsonl whenever the Agent tool fires, or
• Treat agent-calls.jsonl as advisory and accept that hooks may surface reminders even when the agent has been invoked but not logged.

Until the PostToolUse wiring lands, the enforcement layer runs in reminder-rich mode — which is the safer default for a template (loud but non-blocking) than the production-strict mode (precise but with a hard dependency on the missing feed).

Non-negotiables

• Do not redesign architecture without explicit instruction
• Do not expand outside the scale-up sequence without instruction
• Do not let the operational system (Notion, etc.) become authoritative for code/identity
• Senior advisor never interfaces directly with the principal
• Do not modify identity files without explicit instruction
• Do not bypass primary-commitment rules