Generate bounded codebase ownership contexts that agents can load inline or spawn in isolation.
A Directed Context is a repository-owned instruction module with an explicit domain, owned paths, invariants, adjacent contexts, and verification contract. This repository ships the pattern specification, a generator skill that produces context sets for any repository, a deterministic validation tool, and two golden examples.
The outputs are portable Markdown. They do not require Claude, Codex, Copilot, or any particular subagent implementation — a harness with native subagents can spawn one scoped by a context; a harness without them loads the same context inline.
your-repo/
├── AGENTS.md # Context Router: universal rules + routing tables
└── .subagents/
├── README.md # Context index
├── AGENTS-RUNTIME.md # Directed context (primary owner of paths)
├── AGENTS-WORKER.md # Directed context (primary owner of paths)
├── AGENTS-SECURITY.md # Policy overlay (cross-cutting, owns no paths)
└── route-cases.json # Testable routing fixtures
The codebase is the state.
AGENTS.md
is the map..subagents/*.md
are bounded ownership contexts. The runtime chooses whether to load or spawn.
The pattern was extracted from a working prototype —
leather's seventeen-guide .subagents/
routing table — and hardened with mechanisms from three sibling repositories: it sits beside directed-workflows (processes agents walk users through), borrows its coordinate-verification gate from abductive-triage, and takes its detect-deterministically/ask-only-judgment split from security-context-spec. The full ancestry, including what the prototype still teaches the abstraction, is in LINEAGE.md.
Point your agent at a repository and invoke the skill (SKILL.md
). It will:
- Run the deterministic scanner —
contextctl scan
— to inventory packages, entry points, existing instructions, CODEOWNERS, and commands. - Verify the repo's coordinate system (root, monorepo boundaries, source vs. generated trees) before modeling anything.
- Propose ownership boundaries from weighted evidence, asking only about genuinely ambiguous ones.
- Generate the contexts, index, router, and route-case fixtures.
- Validate everything mechanically.
go run scripts/contextctl.go scan --repo /path/to/your/repo
go run scripts/contextctl.go check --repo /path/to/your/repo
go run scripts/contextctl.go routes --repo /path/to/your/repo --cases .subagents/route-cases.json
For a repo that already has a router and contexts, the skill routes to audit mode:
go run scripts/contextctl.go check --repo /path/to/your/repo
go run scripts/contextctl.go drift --repo /path/to/your/repo
drift
reports unowned packages, deleted owned paths, overlapping claims, stale review dates, missing verification commands, and split/merge candidates.
| Path | Contents |
|---|---|
LINEAGE.mdSKILL.mdreferences/scripts/contextctl.goscan
, check
, routes
, drift
assets/templates/examples/abductive-triage/examples/security-context-spec/| Term | Meaning |
|---|---|
Context Router |
Root AGENTS.md ; maps work signals and paths to contexts |
Directed Context |
One .subagents/AGENTS-{DOMAIN}.md module |
Context Set |
The router plus every directed context |
Primary context |
The sole owner of a package/path |
Policy overlay |
Cross-cutting security, performance, operations, or quality context |
Inline load |
Read the context into the current session |
Isolated spawn |
Start a subagent scoped by that context |
Route case |
A representative task with an expected context selection |
Context drift |
Codebase structure or behavior no longer matching the router/guides |
Full definitions and invariants live in PATTERN.md.
The Markdown is canonical. There is no hidden manifest;contextctl
parses and validates the routing tables and context files directly.Contexts are coordination, not authorization. A spawned subagent inherits the caller's permissions; ownership scopes are never security enforcement.Deterministic where possible, human where necessary. The scanner answers every question that lives on disk; users decide only contested boundaries.Read-only by default. The scanner never writes, never executes repository content, never follows symlinks out of the repo, and generation shows the proposed file set before writing.
Requires Go 1.22+.
make test # unit tests (fixtures + golden examples)
make check # lint + format check + tests + golden validation
make check-examples # validate both golden context sets
make scan REPO=... # run the scanner against any repo