directed-contexts

Directed Contexts

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.

Quickstart

Bootstrap a new context set

Point your agent at a repository and invoke the skill (SKILL.md). It will:

1. Run the deterministic scanner — contextctl scan — to inventory packages, entry points, existing instructions, CODEOWNERS, and commands.
2. Verify the repo's coordinate system (root, monorepo boundaries, source vs. generated trees) before modeling anything.
3. Propose ownership boundaries from weighted evidence, asking only about genuinely ambiguous ones.
4. Generate the contexts, index, router, and route-case fixtures.
5. Validate everything mechanically.

# what the skill runs under the hood
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

Audit an existing context set

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.

What's in this repository

Core vocabulary

Full definitions and invariants live in PATTERN.md.

Design commitments

• 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.

Development

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