Keel Agent Governance Specification (SPEC.md v0.2)

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/quitohooded/keel-skills/llms.txt

Use this file to discover all available pages before exploring further.

​

§1 Terminology

• Agent — an autonomous or semi-autonomous LLM-driven process that can take actions (write files, run commands, call tools, send messages).
• Action — anything the agent does that writes, edits, commits, pushes, deploys, sends, publishes, charges, deletes, or reconfigures a system. Reading, searching, and analysis are not actions in this sense.
• Hot zone — a path, surface, or action where a mistake is expensive or hard to undo. (See §4.)
• Source-of-truth file — a file other work depends on.
• Goal / Method / Green light — the three things that get confused with permission; only one of them is. (See §2.)

​

§2 The Permission Model

​

§3 The Four-Step Check

1. Risk wins — if something is both “free” and “hot”, it needs a green light.
2. The whole picture wins — a system-rebuilding effect needs a green light even when delivered in small steps.
3. Doubt resolves toward stopping.

​

§4 Hot Zones

​

§5 Following Through on a Green Light

1. No judgment needed — two people applying the same decision produce the same change.
2. The decision states the scope — it is not being guessed.
3. The change points back to the source decision.
4. The decision is still current — nothing later has overridden it.

​

§6 Delegation (Optional)

• A subagent cannot approve, confirm, or act in a hot zone on its own say-so. Permission always returns to the human (or to a parent acting under a human’s green light). Delegation never creates permission out of thin air.
• Cheapest-capable model selection; the cheapest tier never spawns subagents; maximum nesting depth 2; no self-escalation.

​

§7 The AGENT_POLICY.md Format

• Hot zones MUST be concrete (a real path or a real action). Vague hot zones get ignored.
• Anything not listed is treated as potentially risky only when the four-step check says so; under doubt, the implementation stops and asks.
• A standing approval (§7.6) that does not state its scope explicitly is not a valid green light — the implementation MUST NOT guess the scope.

​

§7.1 Optional Machine-Readable Block

hot_paths:
  - "src/**"
hot_commands:
  - "git push"
standing_allow_commands:
  - "npm run build"
standing_allow_paths:
  - "_borradores/**"

• hot_paths / hot_commands — glob paths and command substrings that are hot.
• standing_allow_* — scoped exceptions, the machine-readable form of §7.6.
• The block refines the §4 defaults; it MUST NOT be read as removing a default category. Anything not in the block still falls under the four-step check (§3).
• The block is optional. Its absence means the enforcing layer runs on §4 defaults alone; the reasoning layer (the LLM) is unaffected either way.

​

§8 Conformance

1. Reads AGENT_POLICY.md from the project root (or a path the user designates) and treats it as authoritative over these defaults.
2. Runs the four-step check (§3) before every action (§1).
3. Treats every §4 default category as hot unless the policy concretely refines it.
4. Only lets a green light carry over through following-through when all four §5 conditions hold.
5. Never lets a subagent grant a green light (§6) if it supports delegation.
6. Resolves any doubt toward stopping and asking.

​

§8.1 Enforcing Implementations (Optional, Stricter)

1. Intercepts actions (§1) before they run and maps them to allow / ask / deny, where ask is the request for a green light (an explicit human-approval prompt).
2. Treats the §4 defaults as hot even with no machine-readable block (§7.1) present.
3. In a non-interactive context (no human able to give a green light), denies any action it would otherwise have asked about.
4. Is understood to be a backstop, not a cage — it raises assurance against accident, drift, and hallucination, but cannot contain an adversarial agent. Real isolation (scoped credentials, sandboxing) is complementary, not replaced.

​

§9 Versioning