Routing Layer
File Skeletons

# Agent Governance Framework

This file lives at `~/.claude/agent-governance/CLAUDE.md`. It is the shared process layer for Claude Code: the three-layer hierarchy, the authority order, and the typed routing docs that repos and personal layers adopt and extend.

It is imported from the user's own `~/.claude/CLAUDE.md` via `@agent-governance/CLAUDE.md`.

## Path Convention

- `$CLAUDE_HOME` always means `~/.claude/agent-governance/` (the framework install directory). It is not `~/.claude` and it is not the repo root.
- Framework docs live under `$CLAUDE_HOME/docs/agents/...`.
- Personal docs live under `~/.claude/personal/docs/agents/...`.
- Repo docs use repo-relative paths such as `./CLAUDE.md`, `docs/agents/...`, and `.claude/commands/...`.

## Read This First

Use the typed docs tree for routing and composition detail:
- `$CLAUDE_HOME/docs/agents/router/composition.md`
- `$CLAUDE_HOME/docs/agents/router/capability-map.md`
- `$CLAUDE_HOME/docs/agents/router/authority-order.md` when you need interpretation notes beyond the precedence guidance below

The typed docs tree is the routing layer. Load only the docs that match the current phase and capability.

## Authority Order

Use `$CLAUDE_HOME/docs/agents/router/composition.md` first to decide whether a rule belongs to the framework, the personal layer, or the current repo.

When sources still conflict after that split, use this order:
- direct user instructions for the current task
- repo `./CLAUDE.md` and nearest directory `CLAUDE.md` files for repo-specific routing and conventions
- repo-specific `docs/agents/policy/*` for repo architecture, boundaries, naming, and testing rules
- repo-specific `docs/agents/playbooks/*`, then repo `reference/*`, `facts/*`, `gotchas/*`, `decisions/*`
- personal `~/.claude/CLAUDE.md` and nearest personal `docs/agents/` files
- personal `docs/agents/policy/*`, then personal `playbooks/*`, then personal `reference/*` and `decisions/*`
- framework `$CLAUDE_HOME/docs/agents/policy/*` for shared workflow and documentation discipline
- framework `$CLAUDE_HOME/docs/agents/playbooks/*`, then framework `reference/*` and `decisions/*`
- code and tests
- external memory or prior-session context

External memory is advisory only. Reload canonical docs at phase boundaries instead of relying on memory.

## Capability Summary

- **repo composition / adoption / capability growth**: use `$CLAUDE_HOME/docs/agents/router/composition.md`, then the relevant adoption or extension playbook.
- **personal extension**: the same `add-capability` playbook applies; invoke it with `--scope=personal` to target `~/.claude/personal/docs/agents/`.
- **domain work**: use the repo's capability map when it has one; otherwise start with the shared capability map.
- **routing friction repair**: load `$CLAUDE_HOME/docs/agents/playbooks/improve-docs.md`.

Change-lifecycle capabilities (plan, open, implement, close, record-decision) are defined in the change-rhythm layer. Review, verify, and deploy capabilities are defined in the review-and-verify layer.

## Command Surface

- Framework commands installed under `~/.claude/commands/` must use the reserved `agent-*` namespace.
- Repo commands installed under `.claude/commands/` should use distinct repo-local names.
- Personal commands (non-`agent-*`) may also live under `~/.claude/commands/` if the user wants a custom shortcut, but they must not shadow framework command names.
- Keep framework commands process-oriented. Repo-specific scaffolding belongs in repo-local commands.

# Personal Claude Code memory

@agent-governance/CLAUDE.md

## Personal preferences

- Prefer tabs over spaces in Go.
- No emoji in code comments.
- When suggesting commit messages, avoid marketing tone.

## Personal docs

- Cross-repo policies: `~/.claude/personal/docs/agents/policy/*`
- Cross-repo playbooks: `~/.claude/personal/docs/agents/playbooks/*`

These are loaded after repo-specific docs and before framework defaults, per the authority order.

---
description: Load the framework composition and repo adoption workflow.
---

Load these docs in order:
1. `$CLAUDE_HOME/docs/agents/router/composition.md`
2. `$CLAUDE_HOME/docs/agents/playbooks/adopt-framework.md`
3. `$CLAUDE_HOME/docs/agents/router/authority-order.md`

Pass any `$ARGUMENTS` through to the loaded docs.

---
description: Run the capability-setup wizard for an adopted repo or the personal layer.
---

Workflow:
1. Determine scope from `$ARGUMENTS`. Default is repo-local; `--scope=personal` targets `~/.claude/personal/docs/agents/`.
2. Inspect the target scope:
   - repo: `./CLAUDE.md`, repo `docs/agents/...`, `.claude/commands/...`
   - personal: `~/.claude/CLAUDE.md`, `~/.claude/personal/docs/agents/...`
3. Load composition, add-capability playbook, and capability-map.
4. Determine whether the capability needs a policy, playbook, reference, workflow entry, command, or directory `CLAUDE.md`.
5. Produce a concrete setup checklist with exact file paths and required updates.
6. If repo-scope and the repo is not yet adopted, stop and redirect to `/agent-adopt`.

Pass any `$ARGUMENTS` through to the wizard flow.

---
description: Run the framework root-cause routing improvement workflow.
---

Load these docs in order:
1. `$CLAUDE_HOME/docs/agents/policy/core.md`
2. `$CLAUDE_HOME/docs/agents/playbooks/improve-docs.md`

Use this when routing sends Claude to the wrong doc, a playbook is unclear, or the same friction recurs. Patch the canonical typed docs, not the symptom.

Pass any `$ARGUMENTS` through to the loaded docs.

---
kind: router
binding: false
scope: framework
phases: [explore, plan, implement, verify, commit]
source_of_truth: $CLAUDE_HOME/docs/agents/router/composition.md
---

# Composition Contract

## Ownership

- **Framework** owns: `$CLAUDE_HOME/CLAUDE.md`, `$CLAUDE_HOME/docs/agents/*`, and the `agent-*` namespace within `~/.claude/commands/`.
- **User** owns: `~/.claude/CLAUDE.md`, `~/.claude/personal/docs/agents/*`, and any non-`agent-*` commands under `~/.claude/commands/`.
- **Repo** owns: `./CLAUDE.md`, optional directory entrypoints, repo `docs/agents/*`, and repo `.claude/commands/*`.

## Composition Rules

1. `$CLAUDE_HOME` always means `~/.claude/agent-governance/`. It does not mean `~/.claude` and it does not mean the repo root.
2. Repo docs use repo-relative paths.
3. Personal docs use `~/.claude/personal/docs/agents/...`.
4. The user's `~/.claude/CLAUDE.md` begins with `@agent-governance/CLAUDE.md` (or equivalent import), then adds personal preferences.
5. Repo `./CLAUDE.md` points to framework docs it relies on, then adds repo-specific routing.
6. Repos extend with their own capability-map for repo-specific routing and workflow names.
7. Personal docs own one user's cross-repo preferences. Repo docs own repo-specific behavior. Framework docs own shared workflow.
8. Repo commands use distinct repo-local names, not `agent-*` shadowing.
9. Commands in every layer stay process-oriented.

## Recommended Adoption Shape

- Personal: start with `~/.claude/CLAUDE.md` containing the framework import and any preferences. Add `~/.claude/personal/docs/agents/` only when preferences outgrow the single file.
- Repo: start with `./CLAUDE.md`, one policy, one playbook. Add more only when needed.

---
kind: router
binding: false
scope: framework
phases: [explore, plan, implement, verify, commit]
source_of_truth: $CLAUDE_HOME/docs/agents/router/capability-map.md
---

# Capability Map

Covers framework-provided capabilities only. Repos add their own capability-map for repo-specific domains. Personal docs may add a `~/.claude/personal/docs/agents/router/capability-map.md` for cross-repo workflow names.

## Routing Workflows

| Workflow | Canonical doc |
|----------|---------------|
| adopt framework | `$CLAUDE_HOME/docs/agents/playbooks/adopt-framework.md` |
| add capability | `$CLAUDE_HOME/docs/agents/playbooks/add-capability.md` |
| improve docs | `$CLAUDE_HOME/docs/agents/playbooks/improve-docs.md` |

## Change and Review Workflows

These are defined outside the routing layer. The part 2 and part 3 appendixes carry the canonical list:

- change-lifecycle, record-decision: see the change-rhythm layer (part 2)
- verify, review, deploy: see the review-and-verify layer (part 3)

Repos add repo-specific workflow names to their own `docs/agents/router/capability-map.md`.

---
kind: router
binding: false
scope: framework
phases: [explore, plan, implement, verify, commit]
source_of_truth: $CLAUDE_HOME/docs/agents/router/authority-order.md
---

# Authority Order Notes

The canonical precedence guidance lives in `$CLAUDE_HOME/CLAUDE.md`.

Interpretation notes:
- Use composition.md first to decide framework vs personal vs repo ownership.
- Repo docs own repo-specific architecture, domain rules, and terminology.
- Personal docs own one user's cross-repo preferences. They sit above framework defaults (user preferences beat framework defaults) and below repo docs (project-specific beats personal).
- Framework policy owns shared process, not domain rules.
- Policy defines binding rules. Playbooks define sequencing. Reference explains systems. Decisions explain why.
- Code and tests show reality when docs are stale, but do not override binding workflow policy.
- Historical change records are context, not live convention.
- External memory is advisory only.
- Reload canonical docs at every phase boundary.

---
kind: policy
binding: true
scope: framework
phases: [plan, implement, verify, commit]
source_of_truth: $CLAUDE_HOME/docs/agents/policy/core.md
---

# Core Policy

## Non-negotiables

- Proactively flag improvements when producing weak results.
- Tests must test behavior, not merely prove code does not panic.
- New code ships with tests in the same commit.
- Fix pre-existing gaps in the touched area.
- Extract duplicated patterns when the shared abstraction is clear.
- Ask instead of guessing on unclear architecture choices.
- Main is evergreen. Do not leave broken tests, stale docs, or weak implementations.
- Fix holistically, not just the first symptom.
- Use repo-supported mechanisms over workarounds.
- Do not treat prior plans as scripture.
- Do not use bare literals for domain concepts.

## Layering

- Routing is a framework concern. Do not duplicate routing rules inside repo or personal docs; extend the routing categories instead.
- Personal docs can override framework defaults for a single user. They must not contain binding rules meant for shared workflow.
- Repo docs can override personal preferences. They must not claim framework-wide authority.

---
kind: playbook
binding: false
scope: framework
phases: [explore]
source_of_truth: $CLAUDE_HOME/docs/agents/playbooks/adopt-framework.md
---

# Adopt Framework Playbook

## Adoption Steps

1. Read composition.md and decide what stays framework vs personal vs repo-local.
2. Create or update repo `./CLAUDE.md`.
3. Add repo capability-map if needed.
4. Fold workflow entries into the repo capability-map if named recurring workflows exist.
5. Add first repo-local policies and playbooks for highest-friction domains.
6. Add repo commands only for repeated workflows.

## Minimal Shape

Small repo: `./CLAUDE.md`, one policy, one playbook.
Larger repo: add capability-map with workflow entries, multiple domain policies, directory entrypoints.

## Rules

- Do not copy framework docs into the repo.
- Put repo architecture in repo docs, not the framework.
- Prefer explicit references to `$CLAUDE_HOME/...` (resolves to `~/.claude/agent-governance/`).

---
kind: playbook
binding: false
scope: framework
phases: [explore]
source_of_truth: $CLAUDE_HOME/docs/agents/playbooks/add-capability.md
---

# Add Capability Playbook

## Scope

- Repo scope: grow a repo's local routing. Default.
- Personal scope: grow the user's cross-repo preferences under `~/.claude/personal/docs/agents/`. Invoked with `--scope=personal`.

## Choose The Right Doc Type

- policy: binding domain rules
- playbook: ordered recurring workflow
- reference: deep subsystem detail
- Decision Record: durable rationale (see change-rhythm layer for when to write one)
- repo or personal command: only when invoked repeatedly

## Growth Steps

1. Decide if new domain, workflow, or reference topic.
2. Add minimal local doc(s) in the chosen scope.
3. Update the scope's capability-map.
4. Update the capability-map with a workflow entry if a named workflow is being added.
5. Update the scope's entrypoint (`./CLAUDE.md` or `~/.claude/CLAUDE.md`) only if routing changes.
6. Add a directory-level `CLAUDE.md` only if startup routing in a subtree matters.

---
kind: playbook
binding: true
scope: framework
phases: [explore, implement, verify]
source_of_truth: $CLAUDE_HOME/docs/agents/playbooks/improve-docs.md
---

# Improve Docs Playbook

1. Classify the friction (wrong route, unclear playbook, missing reference, stale entry).
2. Patch the canonical typed docs first.
3. Update entrypoints, adapters, or checks if routing caused the failure.
4. Leave compatibility docs as redirects only.
5. Re-read the new route and confirm it answers the problem directly.
6. If the friction is specific to one user, patch the personal layer instead of the framework.