Architecture

Agent architecture

Agents are the judgment layer — the only part of OperationKit that has a persona, can refuse work, and routes to other specialists. Everything below them is procedure or raw capability.

What an agent is

OperationKit's three-layer architecture separates capability, procedure, and judgment into distinct file types. The distinction is not cosmetic — it determines which layer a session loads, what authority the session has, and what the session is permitted to do:

The dependency runs one way: agents load skills, skills call tools. A tool never references an agent, and a skill never adopts a persona. This one-way dependency is what makes the layers individually replaceable — you can swap a tool's implementation without touching the skill that uses it, and add a new agent specialty without modifying any existing skill.

Two properties are exclusively agent properties. A file that lacks either is not an agent regardless of where it lives:

• Persona. The agent has an identity, a domain of authority, and a stated point of view. It can be addressed by role ("you are Mike's CTO") and it maintains that role consistently across a session.
• Authority to refuse. The agent can evaluate a request against its domain, its priorities, and its refusal rules — and decline to proceed. A skill that is executing a procedure cannot make this evaluation; it can only complete or fail.

Wang et al. (2024) surveyed the landscape of LLM-based autonomous agents and identified persona stability and goal-directed refusal as the two properties that distinguish goal-directed agents from tool-executing pipelines. OperationKit encodes both as first-class structural properties: persona lives in the agent file's identity section; refusal authority is declared as an explicit scope-limit block.

Why plain markdown files

Agent personas in OperationKit are stored as plain .md files — not database records, not API-managed configs, not serialized objects. This is a deliberate design choice with three specific advantages.

Portability

A markdown file can be read, diffed, and merged by any tool that handles text. An agent persona can be copied to a new install, adapted for a different operator, or submitted as a pull request from any editor. No vendor SDK, no API key, and no running service is required to understand or modify what an agent does. Shanahan et al. (2023) observed that role-play in LLMs is fundamentally a text-conditioning phenomenon — the model adopts a persona through the words in its context, not through structured metadata. Storing the persona as human-readable text aligns the storage format with the mechanism that actually produces the behavior.

Versioning

Agent behavior changes are tracked the same way code changes are tracked: via git commit history. You can git blame a refusal rule to find out why it was added, compare two agent versions with git diff, and roll back a behavioral regression with git revert. The audit trail is native to the toolchain, not bolted on as a separate logging system.

Auditability and "bring your own agent"

Because an agent is a file you can read, an operator can verify exactly what an agent is authorized to do before spawning it. There is no hidden configuration, no server-side behavior that diverges from what the file says. This is the "bring your own agent" property: anyone who can read a markdown file can inspect, fork, and deploy an agent without reading source code. It also means the same agent file can be loaded into different harnesses — the Command Center board, a local Claude session, a CI-triggered workflow — without translation.

---
name: cto
description: "Chief Technology Officer: PRD drafting, feature decomposition,
  developer orchestration, deploys, and codebase documentation."
skills:
  always: [pipeline, project-management, devops, qa-enforcement]
  available: [gitnexus, live-browser-testing, go-test, pr-self-heal]
---

## 1. Identity

You are Mike's Chief Technology Officer. You own the full technical
lifecycle: judging whether an idea is worth building, writing the PRD,
decomposing it, orchestrating developer sub-agents, and shipping
verified code...

## Refusal rules

- Decline any request that bypasses the QA gate established in
  qa-enforcement.md.
- Escalate (do not ignore) if a task conflicts with a stated architectural
  principle or an active blocker in the session context.

The three-question decision rule

When you are deciding where a new file belongs — tool, skill, or agent — ask three questions in order. Stop at the first "yes":

Two shortcuts resolve most edge cases:

• Only agents have a persona and the authority to refuse. If the file cannot decline work, it is not an agent — even if it loads a dozen skills or orchestrates complex workflows.
• Only tools can be described without naming a business process. If you cannot explain what the file does without saying "for a client" or "before launch," it is not a tool.

Sumers et al. (2024) formalized a similar taxonomy in Cognitive Architectures for Language Agents, distinguishing declarative knowledge (facts about the world), procedural knowledge (how to act), and the deliberative control layer (which action to choose). The Tools/Skills/Agents mapping is a direct implementation of this cognitive hierarchy: tools are declarative, skills are procedural, agents are the deliberative layer.

The three-question rule is also the refactoring test. If a file that lives in agents/ fails question 3 — if it has no persona and refuses nothing — it is a skill wearing an agent's clothes. OperationKit's architecture docs call this out explicitly for two current examples: agents/rolodex.md (a constrained tool-loop prompt) and agents/campaign-launcher.md (a deprecated order-of-operations checklist). Both fail question 3. Both remain in agents/ only because they hold live board slots that a move would break — a migration rather than a design principle.

The routing table as specialization

The routing table in ~/.claude/CLAUDE.md is the single entry point for every task in the system. Its left column is a task description; its right column is the agent file to read. When a session starts, it reads this table before anything else and routes to the correct persona.

Each row represents a domain boundary — a claim that some cluster of tasks is handled better by a specialist with bounded scope than by a generalist with unbounded scope. The research literature supports this design. Yao et al. (2022) showed in ReAct that interleaving reasoning and acting traces — i.e., having the model explain its decisions before taking each step — significantly improves task accuracy. A specialist agent who reasons within a narrow, well-defined domain produces more reliable reasoning traces than a generalist navigating an unbounded problem space.

Specialization also constrains the blast radius of a mistake. An error in the CFO agent's financial reasoning cannot touch code; an error in the CTO agent's architectural judgment cannot execute financial transactions. The routing table enforces separation of concerns at the session level — not just at the code level.

The agents/general.md catch-all agent exists for tasks that fit no specialist row, but it is the fallback, not the default. The routing table is ordered to resolve to a specialist first; a general agent gets the task only if no specialist has domain coverage. This mirrors how a real organization routes work: specialists first, generalist as last resort.

Refusal rules as a safety primitive

Every agent file in OperationKit carries an explicit section on what the agent is not licensed to do. This is not a courtesy disclaimer — it is a structural safety primitive that shapes session behavior.

Bai et al. (2022) introduced Constitutional AI: rather than relying solely on human feedback to align model behavior, a set of constitutional principles is injected into the training and evaluation loop so the model can evaluate and revise its own outputs against explicit rules. The OperationKit approach applies the same principle at inference time: each agent's refusal rules act as the agent's constitution. The model reads the rules at session start and applies them throughout — without fine-tuning, without RLHF, and without human review of every output.

Refusal rules encode three distinct categories of constraint:

Domain limits

An agent declines tasks outside its stated domain. The CTO does not draft board-level financial strategy; the CFO does not merge pull requests. Domain limits prevent scope creep, which is the most common source of cross-agent errors in multi-agent systems: a task that starts in one domain silently acquiring cross-domain side effects.

Quality gates

An agent refuses to proceed past a defined quality checkpoint without evidence that the checkpoint was met. The CTO agent will not ship code without a passing build; the QA reviewer will not approve an objective whose ARTIFACT.md contains unfilled placeholder tokens. Quality gates are not negotiable by the session — they are encoded in the agent file and cannot be bypassed by a user instruction within the session.

Escalation triggers

An agent escalates rather than decides unilaterally when certain conditions are met: an architectural conflict with a stated principle, a financial commitment above a threshold, a legal decision that requires human sign-off. Escalation is a form of refusal — the agent is refusing to make a decision it is not licensed to make, and surfacing it to the appropriate authority.

## Escalation register

Tier-2 triggers (pause; tell Mike; wait):
  - Architectural conflict: a requested change contradicts a stated
    architectural principle or a decision in the vault.
  - Priority conflict: the requested task would displace a stated
    top-priority objective without explicit authorization.

Tier-1 triggers (refuse; do not continue):
  - Bypassing the QA gate established in qa-enforcement.md.
  - Committing code without a passing build or test run.

The research basis for encoding refusals explicitly in the agent file — rather than relying on the base model's general alignment — comes from Shanahan et al. (2023): they show that persona conditioning through role-play significantly amplifies a model's tendency to behave consistently with the stated role, including stated constraints. An agent whose file explicitly encodes "I refuse X" will refuse X more reliably than a general model asked not to do X in a system prompt, because the persona identification mechanism reinforces the constraint at each reasoning step.

Refusal rules also serve an organizational function: they make the boundary of an agent's authority legible to humans. An operator reading agents/cfo.md can determine in 60 seconds what the CFO agent will and will not do — without reading source code, without running a test, and without asking the agent itself. This legibility is what "bring your own agent" requires: the file is the contract.

References

The design choices above are grounded in published research. Each citation below explains the specific connection to OperationKit's agent architecture.

• ReAct: Synergizing Reasoning and Acting in Language Models

  Yao, S., Zhao, J., Yu, D., Du, N., Shafran, I., Narasimhan, K., & Cao, Y. (2022). arXiv preprint arXiv:2210.03629.

  Why it matters here: ReAct demonstrates that interleaving chain-of-thought reasoning with action traces produces substantially better task accuracy than either pure reasoning or pure acting. OperationKit's agent-and-skill architecture directly implements this: agents reason about which skill to invoke and why (reasoning trace), then the skill executes the discrete actions. Specialist agents with bounded domains produce more grounded reasoning traces than generalists navigating unbounded problem spaces — the routing table enforces that specialization structurally.

  arxiv.org/abs/2210.03629 ↗

• Role-Play with Large Language Models

  Shanahan, M., McDonell, K., & Reynolds, L. (2023). Nature, 623, 493–498.

  Why it matters here: Shanahan et al. show that role-play in LLMs is a text-conditioning phenomenon — the model adopts a persona through the words in its context, not through structural metadata, and that persona conditioning amplifies the model's tendency to behave consistently with stated constraints. This is why OperationKit stores agent personas as human-readable markdown: the file's prose is the mechanism, not a wrapper around a hidden representation. It also explains why refusal rules embedded in the persona file are more reliable than general alignment: the persona identification reinforces each constraint at every reasoning step.

  arxiv.org/abs/2305.16367 ↗

• Constitutional AI: Harmlessness from AI Feedback

  Bai, Y., Jones, A., Ndousse, K., Askell, A., Chen, A., DasSarma, N., … & Kaplan, J. (2022). arXiv preprint arXiv:2212.08073.

  Why it matters here: Constitutional AI introduces the idea of encoding explicit principles that the model evaluates its own outputs against — rather than relying solely on human feedback for every constraint. OperationKit applies this at inference time: each agent's refusal rules and scope limits act as its constitution. The model reads these rules at session start and applies them throughout without fine-tuning, giving operators a legible, versioned contract for what the agent will and will not do — which is the same legibility goal Constitutional AI pursues at training time.

  arxiv.org/abs/2212.08073 ↗

• Cognitive Architectures for Language Agents

  Sumers, T. R., Yao, S., Narasimhan, K., & Griffiths, T. L. (2024). Transactions on Machine Learning Research.

  Why it matters here: Sumers et al. formalize a cognitive science taxonomy for LLM agents: declarative knowledge (facts), procedural knowledge (how to act), and the deliberative control layer (which action to choose). The Tools/Skills/Agents three-layer graph is a direct implementation of this taxonomy. Tools are declarative world-facts. Skills are procedural memory — repeatable jobs with checkable done-conditions. Agents are the deliberative control layer — the only layer that reasons about which procedure to invoke, and the only layer that can refuse. This paper also documents that agents operating on consistent, structured knowledge representations outperform those reasoning over unstructured or contradictory context, which motivates okit validate's graph-consistency enforcement.

  arxiv.org/abs/2309.02427 ↗

• A Survey on Large Language Model based Autonomous Agents

  Wang, L., Ma, C., Feng, X., Zhang, Z., Yang, H., Zhang, J., … & Wen, J. (2024). Frontiers of Computer Science, 18(6).

  Why it matters here: Wang et al. survey the full landscape of LLM-based autonomous agents, identifying persona stability and goal-directed refusal as the two properties that distinguish autonomous agents from tool-executing pipelines. OperationKit encodes both as first-class structural properties — persona in the agent file's identity section, refusal authority in the explicit scope-limit block. The survey also documents that multi-agent systems with bounded specialist roles and defined handoff rules significantly outperform monolithic single-agent systems on complex multi-step tasks, which is the design principle behind OperationKit's routing table.

  arxiv.org/abs/2308.11432 ↗