codecontext-setup

SKILL.md

Codecontext Setup

Set up codecontext so agents can use it without guessing.

The point of this skill is not just package installation. The real job is to
make the repo's agent contract coherent:

the toolchain is installed where it belongs

AGENTS.md tells agents when and how to use it

inline @context is treated as the required structured layer

supporting refs stay unconstrained and user-owned

Do not invent required sidecar document schemas. Do not require .ctx.md.
Refs can point to Markdown, HTML, text, diagrams, exported docs, or any other
resolvable file the repo uses.

When to use

Use this skill when the user asks to:

install or adopt codecontext

update a repo's AGENTS.md or agent guidance around @context

audit a project's current codecontext setup

reconcile a mismatch between codecontext tooling and repo instructions

improve how agents discover decisions, risks, assumptions, and history

Outcome

By the end of this workflow, the repo should have:

a clear AGENTS.md section for codecontext

a sane CLI workflow for agents

the right enforcement surface for the repo's languages and toolchain

no misleading guidance about structured sidecar docs

Workflow

1. Audit the current state

Inspect:

package manager and workspace layout

whether the repo already depends on @recallnet/codecontext-cli

whether the repo already depends on @recallnet/codecontext-eslint-plugin

whether the repo already has Python, Go, Rust, or other language-native

whether the repo already has Python, Go, Ruby, Rust, or other language-native
checkers where codecontext enforcement belongs

whether ESLint is present and where its shared config lives

whether AGENTS.md exists at repo root and in subtrees/worktrees

whether existing agent docs already mention @context, codecontext, ADRs,
contexts/, or decision logs

Look for the two common failure modes:

tool installed, but no agent workflow or guidance

guidance exists, but it is stale, contradictory, or points to a policy that
does not exist

2. Decide the installation surface

Install the minimum useful surface:

@recallnet/codecontext-cli when agents should run --scope, --diff, or
--report

@recallnet/codecontext-eslint-plugin when the repo uses ESLint and wants
comment validation

a language-native checker or analyzer when the repo's main enforcement
surface is Python, Go, Rust, or something else outside ESLint

@recallnet/codecontext-parser only if the repo has custom code that imports
parser APIs directly

Do not add packages the repo is not going to use.

3. Fix AGENTS.md before or alongside package changes

codecontext setup is incomplete without agent instructions.

Every repo-level AGENTS.md section should cover:

what @context is for

when annotations are required

a small preferred taxonomy

the pre-edit and post-edit workflow

what refs are and are not

anti-patterns

If subtree AGENTS.md files point to a repo-level policy, make sure that
policy actually exists.

Recommended AGENTS.md contract

Keep it short. A good section usually fits in 8-14 bullets.

Use something close to this:

- **codecontext**: Use inline `@context` annotations for non-obvious,
  high-value reasoning that future edits could easily erase.
  - Required for:
    - critical decision logic and invariants
    - security-sensitive behavior and hard-won lessons
    - external integration quirks and contract mismatches
    - regression guards explaining why a simpler change would be wrong
  - Preferred forms: `@context decision`, `@context risk`,
    `@context requirement`, `@context history`
  - Keep notes short and specific: what is true, why it matters, and what
    would break if changed
  - Use `{@link ...}` for supporting material when helpful, but refs are just pointers
    to repo files or docs. Do not require any special doc schema.
  - Before editing critical files, run:
    `npx @recallnet/codecontext-cli --scope <file>`
  - After editing, run:
    `npx @recallnet/codecontext-cli --diff HEAD <file>`
  - For broader orientation in larger repos, run:
    `npx @recallnet/codecontext-cli --report`
  - Do not use `@context` for obvious narration, duplicated ADR prose, or
    generic comments.

Adjust the taxonomy only if the repo clearly needs more than the baseline
(decision, risk, requirement, history). Add extra categories sparingly.

Guidance for repos with ADRs or large docs trees

If the repo already uses ADRs, plans, runbooks, or architecture docs:

keep @context as the inline agent-facing layer

treat refs as optional expansion targets

do not tell agents to browse the entire docs tree by default

do not mirror whole ADRs inline

The correct model is:

@context carries the structured local signal

refs point to arbitrary supporting material

agents expand refs only when needed

Refs policy

Be explicit:

refs are allowed to point to .md, .html, .txt, diagrams, exports, or
other repo artifacts

refs are not required on every annotation

refs should not impose a schema on the target file

Do not write guidance that implies:

.ctx.md is required

frontmatter is required

the linked file must be machine-parseable

CLI workflow guidance

Recommend these commands in agent docs when the CLI is installed:

npx @recallnet/codecontext-cli --scope path/to/file.ts
npx @recallnet/codecontext-cli --diff HEAD path/to/file.ts
npx @recallnet/codecontext-cli --report

Use --report for repo orientation and decision review. Use --scope and
--diff around concrete edits.

Enforcement guidance

If the repo already has a shared ESLint config, integrate the plugin there.
Prefer enforcing syntax and stale/invalid ref checks centrally rather than
telling agents to self-police.

If the repo does not use ESLint, do not force it just for codecontext.
Prefer the native enforcement surface for the repo's actual stack:

Python repo: native checker or PyPI-distributed tool

Go repo: analyzer / golangci-lint integration

Ruby repo: native checker gem or RuboCop-style integration

Rust repo: crate / Clippy-style integration

mixed or tool-agnostic repo: CLI workflow may be enough initially

The important question is not "did we install the ESLint plugin?"
It is "what actually enforces @context correctness in this ecosystem?"

What to look for in a review

Flag these as setup defects:

child AGENTS.md files pointing to a missing repo policy

instructions that mention @context but give no workflow

workflow guidance that ignores --report in large repos

guidance that treats linked docs as required structured sidecars

package installs without corresponding agent documentation

documentation that tells agents to read giant ADR/doc trees by default

Delivery

When you finish setup or audit work:

state what was installed or changed

call out any stale or contradictory AGENTS.md guidance you fixed

mention any remaining gaps

if you did not install an enforcement surface, explain why

Default recommendation

If the repo has no existing codecontext guidance, prefer creating a
codecontext-setup section in the root AGENTS.md rather than scattering
instructions across multiple child docs first.