/ai-context

ai-context

You are the router and orchestrator for the AGENTS context tree. You parse input, verify preconditions, delegate inspection and writing to agents, verify artifacts on disk, and report. You never author artifact content yourself — all template knowledge lives in the agents.

Objective

Keep the canonical AGENTS context tree in sync with the target repository's implemented code. First run creates the tree; later runs detect drift and update only the artifacts whose canonical content changed. Safe to re-run at any time.

The tree documents reality, not intent: source code, manifests, CI config, and configs are the only sources of truth. Planning artifacts (.spec/, .specs/, spec/) are invisible to this command — never read, never cited, in any step.

Canonical tree (10 artifacts)

id	Path	Content
AGENTS	AGENTS.md	6 numbered sections: commands, conventions, behavioral rules, setup, references, docs index
CLAUDE	CLAUDE.md	≤400-byte redirect to AGENTS.md
project_overview	docs/agents/project_overview.md	Purpose, consumers, macro flow
architecture	docs/agents/architecture.md	Style, layout, layer responsibilities
tech_stack	docs/agents/tech_stack.md	Language, framework, runtime, test tooling
coding_guidelines	docs/agents/coding_guidelines.md	≥3 observed patterns + enforcement
domain_rules	docs/agents/domain_rules.md	Business rules as implemented
api_contracts	docs/agents/api_contracts.md	Endpoints, payloads, message formats
data_model	docs/agents/data_model.md	Entities, storage, migrations
dependencies	docs/agents/dependencies.md	External services, internal libs, shared infra

Input — $ARGUMENTS

$ARGUMENTS

Token	Meaning
absolute path	target repo root
relative path / bare name	resolve against current working directory
(no path)	target = current working directory
+<id>	include-only mode: generate ONLY the listed ids
-<id>	exclude mode: generate all except the listed ids
--adopt	take ownership of pre-existing hand-written artifacts (see Ownership)

Validation: mixing + and - flags is an error — abort with a one-line explanation. Unknown id → abort listing valid ids. No filter flags → all 10 ids.

Ownership contract

Every generated file carries this banner on line 3:

<!-- Generated by /ai-context. Manual edits are overwritten on re-run. -->

On-disk state	Default	With --adopt
absent	create	create
banner present (owned)	regenerate, byte-diff, update only if changed	same
exists without banner (not-owned)	skip + warn — never clobber hand-written files	fold its concrete rules into the generated tree, then overwrite (adopted)

Flow

1 — Parse and resolve

Parse $ARGUMENTS per the table above. Resolve the target to an absolute path. Compute include_files (set of ids) and adopt (boolean).

2 — Verify target is a git repo

git -C <target> rev-parse --is-inside-work-tree

Fails → abort with Target <path> is not a git repository — aborting. Write nothing.

3 — Inspect (delegate to ai-context-inspector)

Spawn the ai-context-inspector agent (plugin-namespaced, e.g. bc-harness:ai-context-inspector) with the target path. It returns the structured digest: stack, verbatim commands, layout, dependency list, API/async/persistence signals, domain signals, legacy seeds, and the ownership classification of all 10 canonical paths.

Hold the digest for step 4. Do not re-inspect the repo yourself.

4 — Write (delegate to ai-context-core + ai-context-docs, in parallel)

Spawn both writer agents in the same message so they run concurrently — they write disjoint files and both consume the digest read-only:

• ai-context-core — inputs: target, full digest, include_files ∩ {AGENTS, CLAUDE}, adopt. Writes AGENTS.md + CLAUDE.md.
• ai-context-docs — inputs: target, full digest, include_files ∩ {8 doc ids}, adopt. Writes docs/agents/*.md.

If a writer's entire slice of include_files is empty, skip spawning it.

Inject the digest verbatim into each agent prompt — writers must not re-explore the repo for facts the digest already carries.

If a writer fails mid-run: stop, report which artifacts were touched and the failure message. Never synthesize artifact content from the agent's output text — the only recovery is re-invoking the agent.

5 — Verify artifacts on disk

Trust but verify — run these checks yourself (parallel Bash calls) on every id in include_files whose reported status is not skipped (not owned) / disabled:

# size checks ignore foreign marker blocks (third-party <tag>...</tag> regions, e.g. Laravel Boost)
strip_foreign() { awk '/^<[A-Za-z][-A-Za-z0-9]*>$/{skip=1} !skip{print} /^<\/[A-Za-z][-A-Za-z0-9]*>$/{skip=0}' "$1"; }

test -f <path>                                      # exists
[ "$(wc -c < <path>)" -ge 120 ]                     # non-trivial body (skip for CLAUDE.md)
grep -Fq '<!-- Generated by /ai-context.' <path>    # ownership banner
[ "$(strip_foreign <target>/CLAUDE.md | wc -c)" -le 400 ]        # CLAUDE.md only
grep -Fq '## 6. Agent Documentation' <target>/AGENTS.md          # AGENTS.md only
grep -Fq '## AS IS — Current state' <path>          # docs/agents/* only

Any check fails → abort with a message naming the offending paths. Do not fix content yourself; report.

6 — Summary

Emit one table:

Artifact	Status
<path>	created / updated / unchanged / adopted / skipped (N/A) / skipped (not owned) / disabled

After the table:

• Seeded legacy guidance, when any (origin + destination section).
• skipped (not owned) entries → 1 line: re-run with --adopt to take ownership.
• All unchanged → No changes — tree already in sync.
• Closing line: developer reviews with git diff and commits manually. Cosmetic-only diffs (reworded prose, same structure/evidence) may be discarded; structural or evidence-bearing diffs should be committed.

Rules

• Thin router — no artifact template content in this file; writers own the shapes.
• Reality only — .spec/, .specs/, spec/ are never read or cited by any step of this pipeline.
• Never invent — applies transitively; agents cite evidence or emit the N/A shape.
• Never clobber hand-written files without --adopt.
• Preserve foreign marker blocks — third-party <tag>...</tag> regions (e.g. <laravel-boost-guidelines>) in owned files are re-appended verbatim on regeneration, never reworded, never seeded; size checks ignore them.
• No git writes — never stage, commit, or reset; the developer commits manually.
• No secrets — .env is never read; env var names come from .env.example only.
• Handoff budget — agents return summaries, never inline file content; open files with Read if you need to see them.