Agent Context

/agent-context

Self-contained execution runbook. Read top-to-bottom. Do not backtrack.

Every output file reads like a human wrote it from real evidence. No [to fill] residue except in docs/agents/testing.md Mock stance. If the graph does not support a section, omit the section entirely — do not scaffold.

Reference files (read on-demand, not required for normal execution):

• references/SCHEMAS.md — full graph schemas, 20-rule lint spec, sample data
• references/TEMPLATES.md — verbatim output file templates numbered 1–28 matching write order

Variables

All variables set during execution. Phases that set each variable are noted.

Phase 0 — Argument parsing

1. Tokenise $ARGUMENTS on whitespace.
2. Extract flags: --force → FORCE=true, --dry-run → DRY_RUN=true, --with-ci → WITH_CI=true, --minimal → MINIMAL=true. Defaults: all false.
3. First non-flag token → target path. Resolve relative to CWD. If absent → PROJECT_ROOT = CWD (current working directory becomes $PROJECT_ROOT).
4. Verify PROJECT_ROOT is a directory. If not → print agent-context: <path> is not a directory. → stop.
5. Run git -C $PROJECT_ROOT rev-parse --git-dir. Success → IS_GIT_REPO=true. Failure → IS_GIT_REPO=false (warn, continue).
6. If MINIMAL=true and WITH_CI=true: print agent-context: --minimal and --with-ci are mutually exclusive. --with-ci ignored. Set WITH_CI=false.

Phase 1 — Prerequisite gates

Run gates A → B → C → D in order. Gate A is hard (stop on failure). Gates B, C, D are soft (warn, continue).

Gate A — Knowledge graph (HARD)

Check $PROJECT_ROOT/.understand-anything/knowledge-graph.json.

Missing — print verbatim and stop:

agent-context: knowledge graph not found.

This plugin needs $PROJECT_ROOT/.understand-anything/knowledge-graph.json in the target
repo to generate useful context files. If you have not set up
Understand-Anything yet, run:

  /plugin marketplace add Lum1104/understand-anything
  /plugin install understand-anything

Then, in the repo you want to generate context for, run:

  /understand

That will produce $PROJECT_ROOT/.understand-anything/knowledge-graph.json. Re-run
/agent-context once it is present.

Present but not valid JSON — print verbatim and stop:

agent-context: knowledge graph is not valid JSON.

$PROJECT_ROOT/.understand-anything/knowledge-graph.json exists but cannot be parsed.
This usually means /understand was interrupted. Re-run:

  /understand

and try again.

Missing required top-level keys (version, project, nodes, edges, layers) — print verbatim and stop:

agent-context: knowledge graph schema does not match what this plugin
expects. Required top-level keys: version, project, nodes, edges, layers.
Missing: <list>.

Update Understand-Anything (/plugin update understand-anything) or file
an issue at github.com/jonaskahn/agent-context describing the schema
mismatch.

Valid — set KNOWLEDGE_GRAPH to parsed object.

Gate B — Freshness (SOFT)

Skip if IS_GIT_REPO=false. Compare git rev-parse HEAD vs project.gitCommitHash.

Mismatch — set GRAPH_STALE=true. Print:

agent-context: knowledge graph was generated against commit <graph_hash>
but the repo is at <head_hash>. Generated files may be out of date.
Re-run /understand for the best results.

Match or no git — set GRAPH_STALE=false.

Also check project.analyzedAt: if older than 14 days from now, print a staleness warning. Continue either way.

Gate C — Domain graph (SOFT)

Check $PROJECT_ROOT/.understand-anything/domain-graph.json.

Missing — set DOMAIN_QUALITY="missing", DOMAIN_GRAPH=null. Print:

agent-context: domain graph not found. Glossary will be stubbed.
Run /understand-domain to populate docs/agents/glossary.md with
domain-level content.

Present — parse it. Set DOMAIN_GRAPH to parsed object. Compute quality grade:

HEURISTIC_COUNT = count of domain-type nodes whose summary contains "Heuristic"
TOTAL_COUNT     = count of domain-type nodes (type == "domain")

if TOTAL_COUNT == 0:             DOMAIN_QUALITY = "missing"
elif HEURISTIC_COUNT / TOTAL_COUNT >= 0.5: DOMAIN_QUALITY = "low"
elif HEURISTIC_COUNT / TOTAL_COUNT >= 0.1: DOMAIN_QUALITY = "mixed"
else:                            DOMAIN_QUALITY = "high"

Gate D — Existing CONVENTIONS.md (SOFT)

Search for CONVENTIONS.md (case-insensitive) in expected locations and report findings.

Step D.1: Grep search in standard locations

Run grep -ri "^" $PROJECT_ROOT/CONVENTIONS.md $PROJECT_ROOT/docs/CONVENTIONS.md 2>/dev/null to find files.

Check in this order:

1. $PROJECT_ROOT/CONVENTIONS.md (case-insensitive)
2. $PROJECT_ROOT/docs/CONVENTIONS.md (case-insensitive)

Step D.2: File found in expected location

Found in root or docs/ — read content. Set EXISTING_CONVENTIONS to content string. Set CONVENTIONS_ACTION=null. Print:

agent-context: found existing CONVENTIONS.md (<N> lines).
Existing conventions will be transformed into AI-targeted directives in docs/agents/conventions.md.
Location: <root or docs/>

Existing conventions are parsed and distilled into docs/agents/conventions.md (terse AI directives, not verbatim copy) and linked from AGENTS.md §6 (Deeper Context). They are NOT inlined into AGENTS.md — the 100-line cap forbids it.

Step D.3: Fallback grep search

If not found in standard locations, run:

find $PROJECT_ROOT -iname "CONVENTIONS.md" -not -path "*/node_modules/*" -not -path "*/.git/*"

Found elsewhere — print diagnostic:

⚠️  CONVENTIONS.md found at unexpected location

Searched the repository — CONVENTIONS.md was found at:
  - <path>

Expected location: $PROJECT_ROOT or docs/ folder

If this is your conventions file, please either:
1. Move it to $PROJECT_ROOT (recommended)
2. Move it to the docs/ folder
3. Provide the exact location in your project context

agent-context will skip loading conventions and use default stub.

Set EXISTING_CONVENTIONS=null. Continue to Step D.4.

Not found anywhere — set EXISTING_CONVENTIONS=null. Print diagnostic:

⚠️  CONVENTIONS.md not found

Searched the repository — no CONVENTIONS.md file exists in:
  - $PROJECT_ROOT: ❌
  - docs/ folder: ❌
  - Anywhere else in the project: ❌

According to your README and SKILL.md documentation, the agent-context plugin expects a CONVENTIONS.md file in $PROJECT_ROOT (case-insensitive lookup). This file should contain team coding standards and directives.

If you have a conventions file:
  • Move it to $PROJECT_ROOT, or
  • Move it to docs/, or
  • Specify its location below

If not, agent-context will create a starter stub.

Continue to Step D.4.

Step D.4: Handle missing CONVENTIONS.md

Only reached if EXISTING_CONVENTIONS=null. Determine CONVENTIONS_ACTION:

• If DRY_RUN=true OR AskUserQuestion is unavailable (headless / script invocation): set CONVENTIONS_ACTION="stub". Print: agent-context: no CONVENTIONS.md — defaulting to starter stub.
• Otherwise call AskUserQuestion with question "No CONVENTIONS.md found. How should /agent-context handle CONVENTIONS.md?" and four options:
  • (a) (default, recommended) Create a starter stub with empty Safety / Naming / Patterns / Workflow sections. → CONVENTIONS_ACTION="stub"
  • (b) Skip — do not create CONVENTIONS.md. → CONVENTIONS_ACTION="skip"
  • (c) Legacy — write a verbatim copy of AGENTS.md. → CONVENTIONS_ACTION="legacy"
  • (d) Provide custom path — I have a CONVENTIONS file elsewhere. → prompt user for path with text input, then attempt to read that file and treat as found.

Do NOT mutate EXISTING_CONVENTIONS. It stays null for this run. The stub written by option (a) is not parsed back as conventions on the same run; on the next run, Gate D detects it via the Found branch.

Phase 2 — Graph indexing

Schema quick-ref

Node key fields: id (opaque, file: or func: prefix), type ("file"|"function"), filePath (always present), lineRange ([start,end], function nodes only), summary (generic if starts with "Source file " or ends with "— function in this module."), complexity ("simple"|"moderate"|"complex").

Edge types: contains (file→function), imports (file→file, one-directional).

Layer: { id, name, description, nodeIds[] }. Pre-computed — do not recompute.

Tour: { order, title, description, nodeIds[] }. Dependency-ordered onboarding steps.

For full field-level documentation, see references/SCHEMAS.md §1–§6.

Build indexes

One pass each:

1. nodes[] → nodesById (Map: node.id → Node).
2. edges[]:
   • type == "contains" → push target into containsOut[source]
   • type == "imports" → push target into importsOut[source], push source into importsIn[target]
3. layers[] → nodesByLayer (Map: layer.name → node.id[]), and for each nodeId: layersByNodeId[nodeId] = layer.name.
4. Filter nodesById values where type == "function" → group by filePath into functionsByFile.
5. If DOMAIN_GRAPH is non-null:
   • total_flow_count = count of DOMAIN_GRAPH.nodes where type == "flow". If DOMAIN_GRAPH is null, set to 0.
   • flowsByDomain = Map of domain.id → flow Node[], built by walking DOMAIN_GRAPH.edges of type contains_flow.
   • cross_domain_edges = ordered list of (source.name, target.name) tuples from edges of type cross_domain, using nodesById lookups against DOMAIN_GRAPH.nodes. Skip if either endpoint is missing.

Integrity assertions (warn, do not stop)

• All edge source/target ids exist in nodesById. Print warning with orphan count if any.
• All layer.nodeIds entries exist in nodesById. Same.
• All tour[].nodeIds entries exist in nodesById. Same.
• No node in more than one layer. If conflict, use first occurrence, warn.

Edge case: empty arrays

• nodes[] empty → all indexes are empty maps. Phase 4 produces zero signals. Phase 5 emits AGENTS.md with header + §3 (if commands found) + §5 (Safety) + §6 (Deeper Context pointing to stubs). Omit §1, §2, §4.
• layers[] empty → layersByNodeId and nodesByLayer are empty. AGENTS.md §2 tagline becomes: **No layers detected. Run /understand with more source files.**
• tour[] empty → AGENTS.md §1 has tagline and test sentence but zero bullets. Tagline becomes: **Layers are the architecture. Read the module map below.**

Phase 3 — Shallow command discovery

The graph does not contain build commands. Read manifests directly from PROJECT_ROOT:

package.json (check first)

If package.json exists, parse it:

• scripts.dev → COMMANDS.dev
• scripts.test → COMMANDS.test
• scripts.lint → COMMANDS.lint
• scripts.build → COMMANDS.build

Infer install command from lockfile. Check in this order, use first found:

1. bun.lockb → bun install
2. pnpm-lock.yaml → pnpm install
3. yarn.lock → yarn install
4. package-lock.json → npm install
5. None found → npm install (default)

Set COMMANDS.install to the inferred command.

pyproject.toml (if no package.json)

• Install: pip install -e .
• Test: pytest

Cargo.toml (if no package.json or pyproject.toml)

• Build: cargo build
• Test: cargo test
• Lint: cargo check

go.mod (if none of the above)

• Build: go build ./...
• Test: go test ./...
• Lint: go vet ./...

No manifest found

COMMANDS is empty. Omit AGENTS.md §3 entirely.

Framework and language detection

Run this step using whichever manifest was found above (or "none" if none found). Set FRAMEWORK, LANG, and PROJECT_SUMMARY.

LANG — infer from which manifest was found:

• package.json → "TypeScript/JavaScript"
• pyproject.toml → "Python"
• Cargo.toml → "Rust"
• go.mod → "Go"
• None found → "" (empty — omit Stack line from architecture.md)

FRAMEWORK — scan the manifest found above for these keys (check in order listed, use first match):

package.json — inspect dependencies and devDependencies keys:

pyproject.toml — inspect [tool.poetry.dependencies] or [project.dependencies]:

Cargo.toml — inspect [dependencies]:

go.mod — inspect require block:

No manifest → FRAMEWORK = "" (empty).

PROJECT_SUMMARY — derive from KNOWLEDGE_GRAPH:

1. If project.description is non-empty → use it (truncate to 120 chars at word boundary).
2. Else if tour is non-empty → use tour[0].description (truncate to 120 chars at word boundary).
3. Else → "" (empty).

Monorepo detection

Run after manifest discovery. Check these signals in order:

If MONOREPO_TOOL is not null: set MONOREPO_WORKSPACES to the list of workspace package paths from the relevant manifest's workspaces / members field. If the field uses glob patterns rather than explicit paths, keep the patterns as-is (e.g., packages/*). If the manifest has no such field, set to [].

If MONOREPO_TOOL is null: set MONOREPO_WORKSPACES = [].

When MONOREPO_TOOL is not null, append a note to COMMANDS.install (if present): <install_command> # monorepo root — see {MONOREPO_TOOL} workspaces

CHANGELOG extraction

Check for CHANGELOG.md, CHANGELOG, CHANGES.md, or HISTORY.md at PROJECT_ROOT (case-insensitive). Use the first match found.

Found — extract the last 3–5 changelog entries. An "entry" is any ## heading block (version or date heading) plus the bullets/lines immediately following it until the next ## heading. Extract text only — strip any markdown formatting except backticks. Truncate each entry to 300 chars. Set CHANGELOG_SNIPPET to the joined entries as a plain-text string.

Not found — set CHANGELOG_SNIPPET = null.

Phase 4 — Convention mining

Apply 5 signals. Each produces zero or more candidate bullets. Rank all candidates by rarity. Take top 3–5. Phrase every bullet negation-forward (lead with "Don't", "No", "Never", or "If X, stop").

Signal 4a — Cross-layer import anomalies

For each imports edge, look up source and target layers via layersByNodeId. For each (source_layer, target_layer) pair, count edges. Pairs with count == 1 or count == 2 are anomalies.

Phrase each anomaly as: - {source_layer} rarely imports {target_layer} directly — the one exception is \{source.filePath}` importing `{target.filePath}`. Don't remove it.`

Rarity per candidate: 1.0 / count (where count is the pair's edge count).

Signal 4b — Naming deviators within a layer

For each layer with >=5 file nodes:

1. Tokenise each file's basename on ., -, and _.
2. Find the modal (most frequent) last-token (e.g. .vue, .ts).
3. If >80% of files share the modal token, the remaining files are deviators.

Phrase as: - Most {layer} files end in \{token}`. Don't rename the exceptions — {list of up to 3 deviators} — they are intentional.`

Rarity per candidate: 1.0 / deviator_count.

Signal 4c — Layer/path disagreements

For each file node, predict its layer from filePath top-level directory prefix:

• app/pages/ or pages/ → "Pages"
• app/components/ or components/ → "Components"
• app/composables/ or composables/ → "Composables"
• server/ → "Server"
• app/utils/ or utils/ or lib/ → "App utils" or "Utility"
• src/ → infer from next directory segment

Compare predicted layer to actual layer from layersByNodeId. Collect disagreements.

If total disagreements > 3: skip this signal entirely (bulk disagreements indicate graph-level misclassification, not conventions).

If <= 3 disagreements, phrase each as: - \{filePath}` lives under {predicted} by path but is classified as {actual}. Don't reorganise it.`

Rarity per candidate: 1.0 / total_disagreement_count.

Signal 4d — Dependency direction violations

Select precedence array based on project.frameworks:

• If frameworks contain "Nuxt" or "Vue" (case-insensitive): ["Pages", "Components", "Composables", "App utils", "Server"]
• Otherwise: ["API", "Service", "Data", "Utility"]

For each imports edge, get source and target layer positions in the precedence array. If target position < source position (target is "higher" than source), it is an upward violation.

Skip edges where either layer is not in the precedence array.

Phrase as: - {source_layer} normally does not import from {target_layer}, but \{source.filePath}` does. If removing it, verify it is not an event callback.`

Rarity per candidate: 1.0 / violation_count_for_this_layer_pair.

Signal 4e — Rarity ranking and selection

1. Collect all candidates from 4a–4d.
2. Sort by rarity descending (highest rarity = rarest = most worth surfacing).
3. Tie-breaker when rarity scores are equal: prefer 4a > 4c > 4d > 4b.
4. Take top 5. If fewer than 3 candidates total, emit only what exists — do not pad.
5. Set NON_OBVIOUS to the selected bullet strings.

Signal 4f — Convention directive extraction (only if EXISTING_CONVENTIONS not null)

Parse EXISTING_CONVENTIONS into AI-targeted directives and set CONVENTIONS_DIRECTIVES.

Step 1 — Identify imperative lines. For each line or bullet in EXISTING_CONVENTIONS, check if it contains any of the following keywords (case-insensitive): must, must not, never, always, don't, do not, avoid, use, prefer, require. Lines matching at least one keyword are rule candidates. Lines that are headings (#-prefixed), blank, or pure prose narrative (no imperative verb) are skipped.

Step 2 — Strip rationale. For each candidate, truncate at the first occurrence of —, because, (this, or . that follows the core directive clause. Keep only the imperative clause.

Step 3 — Normalize prefix.

• If the line contains a negation (must not, never, don't, do not, avoid, no ): normalize prefix to MUST NOT.
• If the line expresses obligation (must, always, require, use, prefer): normalize prefix to MUST.
• Otherwise: keep the original imperative verb.

Step 4 — Categorize each directive into exactly one bucket:

• safety — keywords: secret, credential, env, migration, destructive, delete, drop, test disab, commit
• naming — keywords: name, naming, case, suffix, prefix, file name, variable, module name, casing
• patterns — keywords: import, abstract, class, struct, coupling, layer, circular, depend
• workflow — keywords: phase, PR, pull request, review, gate, branch, deploy, merge, approval
• other — anything not matching the above

Step 5 — Deduplicate. For each directive, check if it semantically overlaps with any string in NON_OBVIOUS (same file path mentioned, or >70% word overlap). If so, skip it — NON_OBVIOUS already surfaces it.

Step 6 — Set result. If at least one directive was extracted: set CONVENTIONS_DIRECTIVES to a map of {safety: [...], naming: [...], patterns: [...], workflow: [...], other: [...]} (omit empty categories). If zero directives were extracted: set CONVENTIONS_DIRECTIVES = null.

Signal 4g — Content-based pattern extraction (from function summaries)

Complements topology signals (4a–4e) with semantic patterns inferred from non-generic function summaries.

Step 1 — Collect substantive function summaries. From nodesById, filter to function nodes where summary is non-generic (does not end with "— function in this module."). Require at least 10 such nodes to proceed; if fewer, set CONTENT_SIGNALS = [] and skip remaining steps.

Step 2 — Identify recurring return-shape patterns. Scan summaries for these phrases (case-insensitive). For each that appears in ≥3 distinct function summaries, record a candidate:

Step 3 — Identify naming conventions from function names. Among the substantive function nodes, tokenise node.name by camelCase / snake_case / kebab-case boundaries. Find the modal prefix (appears in ≥4 function names within any single layer). If that prefix is not already surfaced in NON_OBVIOUS, add: - Functions in {layer} start with \{prefix}` — match it when adding new ones.`

Step 4 — Deduplicate against NON_OBVIOUS. Skip any candidate that overlaps >70% with an existing NON_OBVIOUS bullet (word-overlap check).

Step 5 — Set result. Take up to 3 candidates from Steps 2–3 (Step 2 first). Set CONTENT_SIGNALS to the selected bullet strings. If zero candidates, set CONTENT_SIGNALS = [].

CONTENT_SIGNALS are appended to NON_OBVIOUS after the top-5 topology picks, capped so the total NON_OBVIOUS + CONTENT_SIGNALS list does not exceed 7 bullets going into Phase 5.

Phase 5 — File generation

Write-or-skip decision table

Write order (process sequentially, 1–28)

Items #1–7 are skipped when MINIMAL=true. Items #13–19 and #22–28 are skipped when MINIMAL=true.

Flow output mode (Step 7)

Decide between single-file and folder mode using the indexes from Phase 2:

• total_flow_count <= 8 (or DOMAIN_GRAPH is null): write a single docs/agents/flow.md from TEMPLATES.md §19. If DOMAIN_GRAPH is null or total_flow_count == 0, the template emits the "no flows extracted" stub branch.
• total_flow_count > 8: write a folder docs/agents/flows/ containing:
  • docs/agents/flows/index.md (TEMPLATES.md §20)
  • docs/agents/flows/<domain.slug>.md for each domain in domains_with_flows (TEMPLATES.md §21)

Domain slug derivation (used by §20 and §21):

1. Lowercase domain.name.
2. Strip diacritics. Replace any run of [^a-z0-9]+ with -. Trim leading/trailing -.
3. Reserved word: never emit index. If a domain slugs to index, suffix with -domain.
4. Collisions across domains: append -2, -3, … in domain iteration order. Record the final slug on the domain object so cross-references (§21 "See also") stay consistent.

Format migration (automatic, not gated by --force)

Before writing flow output, detect and clean up leftovers from a prior run that used the other mode:

• Folder mode active and docs/agents/flow.md exists → recognise it as the old single-file version, delete it, then write the folder. Report `↻ docs/agents/flow.md → docs/agents/flows/ (migra

…(truncated)