AGENTS.md

AGENTS

Branch Workflow (mainline)

This repo uses mainline (mq) to coordinate the protected main branch. mq is installed globally and auto-discovers the repo from cwd.

The repo root checkout is the canonical protected main. Keep it clean and boring. All feature work happens in topic worktrees.

mq submit queues durably then opportunistically drains the queue itself — no daemon required. This repo has [publish].Mode = 'auto'.

Rules

• Never commit, merge, rebase, push, or reset on main. The root checkout is read-only for development.
• Allowed on main: git status, git diff, git log, git show, git fetch, git worktree add.
• If the repo root checkout is dirty or not on main, treat that as a workflow/setup bug and fix it before continuing.
• Create feature worktrees with wtnew <branch>. Do all work there.
• Run pnpm install once in a new worktree (they don't share node_modules).
• Land through mq, never through manual merge or push.
• Clean up after landing: wtdrop <worktree-path>.

End-to-end flow

# 1. Create a feature worktree and install deps
wtnew my-feature
cd ~/Projects/_wt/recallnet/codecontext/my-feature
pnpm install

# 2. Do all work in the worktree
#    edit, test, commit (repeat as needed)

# 3. Submit — default to waiting for the remote-landed result
mq submit --check-only --json          # dry-run before expensive work
mq submit --wait --for landed --timeout 30m --json

# 4. Clean up
wtdrop ~/Projects/_wt/recallnet/codecontext/my-feature

Follow the submission_id, not the branch name. The default agent path is to wait for landed. Plain mq submit --wait is only an integration result, not the normal end-state to rely on.

mq land --json --timeout 30m                                 # submit + integrate + publish, one shot
mq submit --json                                             # or: capture submission_id
mq wait --submission <id> --for landed --json --timeout 30m  # then wait for remote landing by id

Do not use sleeps, branch-name polling, mq logs, mq events, or mq watch as the primary way to determine completion.

Handling failures

• If integration fails (conflict, check failure), main is untouched. Fix in the feature worktree, commit, then: mq retry --submission <id>
• To abandon: mq cancel --submission <id>
• Check what went wrong with mq status --json, then use mq logs --follow or mq events --follow --json --lifecycle for deeper debugging.
• Auto-repair stuck states: mq doctor --fix

Monitoring

• mq status --json — primary status surface for queue state and current progress
• mq doctor — health check (branch, locks, queue)
• mq repo show --json — config, worktrees, upstream status
• mq repo root --json — canonical root trust status
• mq repo audit --json — local branches not yet merged into main
• mq logs --follow — audit/debug history
• mq watch — interactive debug/status refresh
• mq events --follow --json --lifecycle — lifecycle debug stream

Commit Flow

• All commits happen in feature worktrees, never on main.
• This is a Recall Labs repo. Use the global recall-commit skill for commits here.
• Default commit flow for this repo: stage the intended changes capture any high-leverage learnings in AGENT-LEARNINGS.md if warranted commit with a conventional commit message using the recall-commit format
• Do not use ad hoc one-line commits when the recall-commit guard applies.
• After committing, land through mq submit --wait --for landed --timeout 30m --json.

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. Refs are just pointers to repo files, URLs, skills, 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 repo orientation, run: npx @recallnet/codecontext-cli --report
• Do not use @context for obvious narration, duplicated ADR prose, or generic comments.

Package Publishing

• This repo publishes packages through Changesets, not from every successful merge to main.
• The publish automation lives in .github/workflows/publish-packages.yml.
• The only user-facing package registry for this repo is npmjs.
• Do not send users to GitHub Packages for install or version verification.
• Do not send users to repo git URLs for install when a public npm package exists. The pi extension should be installed as @recallnet/codecontext-pi from npmjs, not from git:github.com/recallnet/codecontext.git.
• npmjs publishing uses GitHub Actions trusted publishing via OIDC, not an NPM_TOKEN secret.
• New npm packages need their own npmjs trusted-publisher entry pointing at recallnet/codecontext and .github/workflows/publish-packages.yml before automated releases will work for that package.
• That workflow only publishes when CI succeeds on main and there is at least one pending file in .changeset/.
• If there is no pending changeset, the workflow does nothing, even if code in a publishable package changed.

What To Do When A Package Fix Must Ship

1. Add a changeset for each publishable package that needs a new release.
2. Commit the changeset with the code fix in the feature worktree.
3. Submit through mq submit --wait --for landed --timeout 30m --json.
4. Wait for CI to pass on main.
5. Wait for Publish Packages to run after CI.
6. Verify the new version is actually on the registry before telling anyone the fix is published.

Important Constraints

• @recallnet/codecontext-cli owns repo-wide file scanning and --report behavior. Parser releases do not ship CLI-only fixes.
• Do not close a bug as "published" just because the fix merged. Confirm the package version changed on the registry.
• For public installs and published-version checks, use npmjs with npm view.
• If a package fix merged without a changeset, publishing will not happen until a new commit adds the missing changeset.

Docs Governance

• Use the repo docs governance stack instead of hand-rolled markdown parsing.
• Keep docs frontmatter valid and review dates current.
• Default active docs to periodic-7. This is the recommended default because active docs drift quickly; if a repo cannot sustain 7-day review, it usually has too many docs.
• Use generated, codebound, or historical only when they are genuinely correct, not as an escape hatch from freshness enforcement.
• Add new docs to the rooted docs graph so orphan checks stay clean.
• Root the graph from docs/INDEX.md unless the repo has a stronger canonical entrypoint.
• Prefer deleting stale docs over re-dating them. Git history already preserves old text; the live docs tree should describe current reality, not accumulate dead docs.
• Removing stale or duplicate docs is a good default behavior. rm is often the right answer.
• Run pnpm docs:lint before merging doc structure or policy changes.

Publishing Skills

This repo uses gh skill publish (GitHub CLI v2.90.0+) to publish skills.

Prerequisite: Ensure GitHub CLI v2.90.0+ is installed: gh --version

When modifying skills:

1. Make changes to skill files in skills/{skill-name}/
2. Commit and merge to main
3. Run gh skill publish --tag vX.Y.Z to create a release
4. The agent-skills topic will be added automatically

Installing skills from this repo:

gh skill install recallnet/codecontext codecontext-setup --agent codex

See: https://cli.github.com/manual/gh_skill_publish