Skip to content

agents.md

Latest commit

 

History

History
73 lines (51 loc) · 8.52 KB

agents.md

File metadata and controls

73 lines (51 loc) · 8.52 KB

Agent templates and codemap agents init

Doc index: README.md. Package layout: packaging.md (templates/ on npm). CLI layering: architecture.md § Key Files.

What it does

The published package ships templates/agents/ (rules + skills). This repo also has .agents/ for Codemap development (CLI from source); it is not identical to templates/agents/ for every file (e.g. the codemap rule/skill). The command codemap agents init writes each bundled template file into <project>/.agents/ with per-file copies (not a wholesale directory sync) — the canonical copy consumers edit (SQL, team conventions, paths).

Query examples in the bundled codemap rule and skill lead with codemap query --json (agents and automation). Omit --json when you want console.table in a terminal — see README.md § CLI.

codemap agents init
codemap agents init --force
codemap agents init --interactive   # or -i; requires a TTY
  • --force — if .agents/ already exists, delete only the same file paths that ship in templates/agents (under rules/ and skills/), then copy those files from the template. Any other files next to them (your custom rules, extra skill dirs, notes at .agents/ root, etc.) are not removed. Use --interactive, not a bare interactive argument (unknown tokens are rejected).
  • --interactive — multiselect which tools to wire (see below); choose symlink vs copy for integrations that mirror .agents/rules (and Cursor also .agents/skills). Uses @clack/prompts; non-TTY runs exit with an error.

Git and .gitignore

If <project>/.git exists, Codemap ensures .codemap.* is listed so SQLite artifacts (e.g. .codemap.db, WAL/SHM) stay untracked:

  • No .gitignore → create one containing .codemap.*.
  • .gitignore exists → append .codemap.* once if missing.

If the project is not a Git working tree, .gitignore is not created.

Optional IDE / tool wiring

All integrations reuse the same bundled content under .agents/. Symlink-style rows use one link mode for the whole run (symlink or copy) when any of them is selected.

Integration What gets created Notes
Cursor .cursor/rules, .cursor/skills → .agents/ Per-file symlink or copy (each rule/skill file, not a directory link).
Windsurf .windsurf/rules → .agents/rules Rules only.
Continue .continue/rules → .agents/rules Continue rules.
Cline .clinerules → .agents/rules Per-file symlink or copy.
Amazon Q .amazonq/rules → .agents/rules AWS rules.
GitHub Copilot .github/copilot-instructions.md Pointer + link to GitHub Docs.
Claude Code CLAUDE.md Root onboarding pointer.
Zed / JetBrains / Aider (generic) AGENTS.md Many tools read root AGENTS.md; JetBrains/Aider have no single mandated path — this file is the shared hook.
Gemini GEMINI.md For integrations that load GEMINI.md.

Pointer files

Root / Copilot pointer files (CLAUDE.md, AGENTS.md, GEMINI.md, .github/copilot-instructions.md) use a managed section between <!-- codemap-pointer:begin --> and <!-- codemap-pointer:end --> (HTML comments — usually hidden in rendered Markdown):

Situation Behavior
File missing Write that section (with markers).
File exists, section present Replace only that section — idempotent re-runs, no duplicate blocks; template updates fix stale text.
File exists, no section, but content looks like an old Codemap-only file Replace whole file with the managed section (one-time migration).
File exists with other content (e.g. your team intro) Append the managed section once.
--force Replace the entire file with the latest managed section.

Append alone would duplicate on every run — markers + replace are what prevent duplicates and staleness.

Implementation (for contributors)

Source Role
src/agents-init.ts runAgentsInit, upsertCodemapPointerFile, listRegularFilesRecursive, applyAgentsInitTargets (per-file copyFileSync / symlinkFilesGranular), ensureGitignoreCodemapPattern, targetsNeedLinkMode.
src/agents-init-interactive.ts @clack/prompts flow; calls runAgentsInit.
src/cli/cmd-agents.ts Lazy-loaded from src/cli/main.ts.

Do not duplicate long IDE matrices, --force / pointer behavior, or codemap-pointer details in README.md or packaging.md — link here instead.

Related