Agents Md

AGENTS.md Generator

Generate agent instructions for VS Code workspaces only.

Scope

• Target root must contain a *.code-workspace file.
• If no *.code-workspace file exists, stop. Do not generate files.
• Do not support individual project or repo generation.
• Do not generate per-project or per-repo AGENTS.md.
• Generate one workspace-root AGENTS.md.
• Generate one workspace-root CLAUDE.md.
• Support both multi-folder and single-folder .code-workspace files.

Source Of Truth

• AGENTS.md is the single source of truth for Codex CLI, Claude CLI, Antigravity CLI, Cursor CLI, Opencode CLI, and GitHub Copilot CLI.
• CLAUDE.md is only a redirect shim for Claude CLI.
• CLAUDE.md must contain only the @AGENTS.md forward plus the short redirect note shown below. Do not add or read any other context from CLAUDE.md.
• Do not duplicate operating rules in CLAUDE.md.
• Put context, native-memory policy, issue-routing, skill-use, and operating instructions in AGENTS.md.

Use this exact CLAUDE.md:

# Agent Instructions

@AGENTS.md

This file redirects Claude CLI to AGENTS.md. AGENTS.md is the source of truth.

AGENTS.md Tone And Intro

• Generated AGENTS.md must be spartan, direct, concise, and clear.
• No fluff.
• No verbose explanation.
• Start generated AGENTS.md with:

# Agent Instructions

[one concise workspace intro inferred from the .code-workspace name and folder scan]

Workspace Scan

• Use only two input sources: the .code-workspace file and the small-scan of its workspace folders.
• Do not read or copy from the agent's own global or user instruction files. This includes global AGENTS.md, user or global CLAUDE.md, ~/.claude/CLAUDE.md, ~/.codex/, and any personal memory or rules file.
• Never copy the agent's personal global rules (co-author, memory, context, issue-routing, or similar) into the generated AGENTS.md or CLAUDE.md.
• Parse the .code-workspace folders list.
• Build the Project Matrix only from that folders list.
• Derive each project's PROJECT-CODE from the folder's name (see Project Matrix Format). Use path/package metadata only when name is missing.
• Support multi-folder and single-folder .code-workspace files.
• Small-scan every workspace folder before generating AGENTS.md.
• Infer stack details from real files such as composer.json, package.json, requirements.txt, pyproject.toml and other common stack indicators.

• Generate the multi-technology warning from scan results.
• When multiple stacks are detected, the intro must tell agents that the workspace contains multiple technologies and that they must not mix and match conventions or code across projects.

Stack Detection

The Stack cell is fact read from manifests, not a guess from a folder's name or the mere presence of a file.

• Find the real app root. Code often lives in a nested dir (application/, app/, src/), not the folder top. Read the manifest there and note the dir, e.g. (application/).
• Read manifest contents; never infer from a file's existence. A phpunit.xml is not proof of PHPUnit; an application/ dir is not proof of Vite.
• PHP — composer.json: require.php for version, frameworks from require (laravel/framework, livewire/livewire). CodeIgniter version from system/core/CodeIgniter.php CI_VERSION. List every primary framework — a Livewire app must say Livewire.
• Frontend build — read the app's own package.json (usually application/package.json, not the repo root). List Vite/Tailwind only when vite/laravel-vite-plugin/tailwindcss are in its deps. Never assume Laravel implies a frontend build.
• JS / TS — package.json: runtime + version (react-native, next, …); mark TypeScript when a typescript dep or tsconfig.json is present; package manager from the lockfile (package-lock.json → npm, yarn.lock → yarn, pnpm-lock.yaml → pnpm).
• Python — framework from requirements.txt / pyproject.toml (fastapi, django, flask, …); version from Dockerfile FROM python:X.Y, .python-version, or requires-python.
• A test runner is not the stack. Name one (Pest vs PHPUnit, from require-dev) only when there is no app framework — e.g. a plain-PHP site.
• Distrust the `name` field and root-level manifests. A root package.json may be mislabeled or belong to a sibling; trust the app-root manifest and lockfiles.

Project Matrix Format

The Project Matrix is a table in the generated AGENTS.md. One row per .code-workspace folder, in folders order. No extra rows. Never invent projects.

Generate it with these exact columns:

| Project | Path | Stack |
| ------- | ---- | ----- |

• Project: the PROJECT-CODE derived from the folder name — strip emojis, uppercase every letter, replace each run of spaces, separators, or punctuation with a single hyphen, then trim leading/trailing hyphens. Example: Partners API → PARTNERS-API, Web → WEB. This is the single identifier agents use everywhere — chat, docs, ADRs, prompts, issues, PRs, commits, comments, and filenames. When name is missing, derive it from the folder path basename.
• Path: the folder path from the .code-workspace, relative to the workspace root. Use . when a single-folder workspace points at the root.
• Stack: concise summary from the Stack Detection scan — language, every primary framework, build tooling, package manager. One line, terse, but omit nothing defining. No version padding unless a manifest pins it.

Keep cells terse. No prose in cells.

Example:

| Project      | Path           | Stack                        |
| ------------ | -------------- | ---------------------------- |
| PARTNERS-API | ./partners-api | PHP 8.3 / Laravel / Composer |
| WEB          | ./apps/web     | TypeScript / Next.js / pnpm  |

Non-Negotiable Rules

Generate this section verbatim in AGENTS.md, after the Project Matrix:

````markdown

Non-Negotiable Rules

1. Target a Project

• Every task must target a project from the Project Matrix. If the prompt names no project, stop and ask which one before doing anything.
• When the user says "meta workspace", apply the task to every project in the matrix.
• Use the PROJECT-CODE from the Project Matrix exactly as written in chat, docs, ADRs, prompts, issues, PRs, commits, comments, and filenames. Never alter, abbreviate, or re-case it.
• In chat, identify projects by PROJECT-CODE, not folder names, repo names, domains, or hostnames. Mention paths only when the path itself matters.

2. Think Before Coding

• State assumptions.
• Present real interpretations.
• Push back on weak plans.
• Stop and ask when unclear.

3. Decision Options

Do not make the user infer your recommendation.

• Label decision options — When asking the user to choose, mark each option with Recommended, Currently implemented, both, or neither. Put the label in the option title, not buried in the explanation.
• Offer enough choices — Provide up to six concrete options when useful, plus a final Write your own option for a custom answer. Do not force three options when the analysis found more real paths.
• Recommend one path — If one option is best, label exactly one option Recommended. If no option is safe to recommend, say why before the list.

4. Simplicity First

• Solve only the asked problem.
• Add no speculative features.
• Add no one-use abstractions.
• Remove complexity when a smaller fix works.

5. Surgical Changes

• Touch only required lines.
• Match local style.
• Do not refactor unrelated code.
• Clean only dead code your change creates.

6. Goal-Driven Execution

• Define success before edits.
• Turn bugs into reproductions.
• Turn changes into checks.
• Verify before reporting done.

7. Systematic Debugging

Find the root cause. Don't patch symptoms.

When something breaks:

• Reproduce the failure before changing anything
• Trace to the underlying cause, not the surface symptom
• No hacks, arbitrary waits/sleeps, or guess-and-check fixes
• After fixing, confirm the original reproduction now passes

Why: Symptom patches hide the real fault and resurface later as flakier, harder bugs.

8. Read Before Write

Before editing, understand why the code exists.

Map the surrounding context first:

• Callers and exports that depend on it
• Shared utilities it relies on
• The original intent behind the code

9. Local Orchestration

The main session is sole orchestrator, merger, conflict resolver, and final judge.

Parallelism:

• Parallelize safe independent lanes by default, across all skills
• Run prerequisites first, then parallelize newly unblocked lanes
• Serialize shared-file edits and integration

Background:

• Run long or noisy independent lanes locally — background/async or worktree-isolated
• Spawn them without asking when safe
• Never use cloud or remote agents: Cursor Cloud Agents, Copilot cloud coding agent, Codex Cloud/web, Antigravity managed/remote execution
• Await and integrate every lane

Roles:

• Use local role lanes: Explorer, Researcher, Planner, Implementer, Reviewer, Tester, Tool-runner
• Match tools to role: read-only for discovery/review/planning, write for implementation, shell for tests/tool runs
• Subagents return summaries, not transcripts
• Final synthesis stays in main

10. Honest State & Reporting

Enforced. No exceptions.

• Before any significant step, anchor state explicitly: [verified] (proven true), [current] (in progress), [todo] (not started)
• At phase changes, send a short visible phase update: Stage, Found, Next, and Needs user
• Do not bury phase updates inside long narration, raw tool output, or pre-tool chatter
• Continue within the same phase when the next action follows from the request
• Before entering a new phase, make the transition explicit
• Stop only when user input, approval, or a scope decision is needed
• After discovery, investigation, or broad file reads, give the phase update before planning, edits, tests, commits, PRs, or issue updates
• Never report work done while any part is skipped, stubbed, or unverified
• Surface constraints, risks, and assumptions up front — never bury or omit them
• After every successful task completion, end with Recommended next step: and name the single best follow-up. Include why in one short sentence.
• Then offer Other good options: with up to six labeled choices when useful. Mark each option with Recommended, Currently implemented, both, or neither, following the decision-option rules above.
• Include Write your own as the final option whenever asking the user to choose a next step.
• Suggest only — never chain or auto-advance without the user choosing.

Why: Silent gaps and premature "done" are how broken work ships. Visible phase updates keep the user oriented without blocking routine progress.

11. Zero Attribution

No co-author, AI, tool, or generator attribution.

• Never add Co-authored-by, Co-Authored-By, Generated by, AI-assisted, Made with, or similar attribution to commits, PR titles, PR bodies, issue comments, release notes, generated docs, or code comments.
• If a tool adds attribution automatically, remove it before publishing, committing, pushing, opening a PR, or closing/commenting on an issue.

````

Working With Skills

Generate the gradient table and rules verbatim in AGENTS.md, after the Non-Negotiable Rules:

## Working With Skills

Skills are ad-hoc tools, not a pipeline. Treat every installed skill as available — no distinction between local and third-party.

Work follows this gradient. Pick the skill that fits the step in front of you; there is no required order and no state machine.

| Phase     | Skills                                                    |
| --------- | --------------------------------------------------------- |
| discover  | `/feature-discovery`                                      |
| sharpen   | `/feature-prompt`                                         |
| plan      | `/grill-with-docs` (→ ADR), `/to-prd` (→ PRD)             |
| slice     | `/to-issues`                                              |
| implement | `/tdd`                                                    |
| verify    | `/review`, `/diagnosing-bugs`                             |
| ship      | `/commit-push-close`, `/commit-push-pr`, `/release-notes` |

- After finishing a step, suggest a sensible next skill when one fits. Suggest only — never chain or auto-advance.
- Do not assume a skill exists; use what is installed.

### Companion Skills And MCPs

These are optional separate installs. Use them beside this kit when installed and task-fit. Do not vendor them into this kit.

| Companion | Use when |
| --------- | -------- |
| ask-matt | You want Matt's upstream router for choosing a user-invoked skill flow. |
| domain-modeling | Project terminology, aliases, or ADR-backed domain language need sharpening. |
| codebase-design | Module boundaries, seams, or interface design decisions matter. |
| Graphify | Querying a generated code/docs/media graph would save broad file reads. |
| Codex plugin for Claude Code | Claude Code needs Codex for review or delegated work. |
| Impeccable | Frontend design quality, visual polish, or browser-backed UI checks matter. |
| notebooklm-py | The user asks to work with NotebookLM sources or artifacts. |
| agent-browser | Browser automation, app QA, screenshots, scraping, or Electron app control is needed. |
| herdr | Running inside herdr and managing panes, tabs, or worker agents is needed. |
| docker-expert | Dockerfiles, Compose, images, containers, or registry workflows are central. |
| Laravel Boost | A Laravel project has Boost installed and Laravel-specific MCP context helps. |
| Figma MCP | A task references Figma designs, components, frames, tokens, or design-to-code. |
| MySQL/Postgres MCP | Approved local or staging database inspection is needed. Default read-only. |

- Treat companion tools as helpers, not authority. Repo code, tests, ADRs, `CONTEXT.md`, and user instructions still win.
- Never assume a companion is installed. If missing, say so and continue with the best local fallback.
- Use MCPs only for the current task. Do not browse unrelated external data.
- For database MCPs, use the narrowest approved connection and read-only access unless the user approves a specific write.

### Matt Skill Routing

Use `/ask-matt` when the user asks which Matt skill or flow fits. It is a router over user-invoked Matt skills, not an executor. Do not auto-run the flow it suggests.

- Main flow for an idea: `/grill-with-docs` → decide if runnable uncertainty needs `/handoff` + `/prototype` + `/handoff` → for multi-session work, `/to-prd` then `/to-issues`.
- For each sliced issue, start a fresh session. Matt's upstream flow uses `/implement`; this kit still prefers `/tdd` as the implementation discipline when available.
- Use `/triage` only for raw incoming issues. Do not triage issues already created by `/to-issues`.
- Use `/improve-codebase-architecture` for codebase health. A chosen improvement becomes an idea to take into `/grill-with-docs`.
- `/handoff` forks context into a new session. `/compact` continues the same conversation; use it only at intentional phase breaks.

Then, under the same ## Working With Skills heading, generate a ### Runtime Tool-Calling subsection from the kit's tool-calling docs. Read references/tool-calling.md (the "All runtimes (index)", "Parallel & background mechanism by runtime", and "Highest elevated permission by runtime" tables) and the per-runtime *-tools.md files, and emit three compact tables for the supported runtimes: (1) how each runtime invokes a skill, (2) its local parallel/background mechanism, and (3) the highest elevated launch / permission preset. Inline the results in AGENTS.md — do not link to the reference files; they do not ship into the generated workspace. Emit only the per-runtime mechanism; do not restate the Local Orchestration rule. In the elevated-permission table, say to use those presets only when the user explicitly asks for highest/elevated/full/YOLO permission and prefers an isolated container, VM, dev container, or disposable worktree.

Context & Native Memory

Generate this section verbatim in AGENTS.md, after the Working With Skills section. Leave the placeholder paths for the user to fill after project setup:

## Context & Native Memory

### Retrieval order

1. **Binding** — `CONTEXT.md` (<!-- set during setup: path to CONTEXT.md -->) and ADRs (<!-- set during setup: path to docs/adr -->). Read before implementing. These bind.
2. **Current task context** — the user request, active issue or PRD, named local docs, current code, tests, and command evidence.
3. **Native CLI memory** — use only the current CLI's native memory feature when it is enabled.

### Artifact policy

- Do not create repo `MEMORY.md` files, workspace wiki files, discovery files, or knowledge-graph files as default memory.
- Do not add memory MCP servers or third-party graph/index systems as default memory for this kit.
- Optional graph/index companions may be used only when installed and task-fit. Do not treat their artifacts as binding memory.
- Keep shared project context in `AGENTS.md`, `CONTEXT.md`, and ADRs.
- Use native CLI memory only when the current CLI provides it; do not sync memory between CLIs.

### Do not bulk-read

- `docs/` is an on-demand archive, not reading material. Never load it wholesale.
- Retrieve only what the current task names — by search or a discovery skill.
- Reading the whole archive rots context and wastes tokens. Pull the few relevant passages, nothing more.

### Archived context

When the user triggers `/grill-with-docs`, ask up front — before the Q/A starts — whether they have archived context for the feature: prior discussions, original intent, or decision history. Await their reply.

- The user pastes it, or says to continue without. Ask once; do not block repeatedly.
- Capture any pasted context verbatim in the ADR, with provenance. Maximum fidelity — do not summarize it away:

  > Source: "<doc title>" · pasted <date>
  >
  > <verbatim excerpt — unedited>

- If a paste reveals an old or current feature name, offer to add it to `CONTEXT.md` aliases.
- Pasted history is advisory. If it contradicts a current ADR, flag the contradiction — never silently drop it.

GitHub Issue Titles

Generate this section verbatim in AGENTS.md, after the Context & Native Memory section. Emit only this concise block — no extra prose. This is the title/label convention every skill and CLI anchors to; the procedure (routing, dependency order, gates) lives in the issue skills, not here:

## GitHub Issue Titles

Issue titles are findable from GitHub search and from the ADR filename. `<PROJECT-CODE>` is the PROJECT-CODE from the Project Matrix — uppercase, hyphenated, no spaces; use it exactly.

**PRD issue** — title starts exactly with:

`PRD: <PROJECT-CODE> ADR-<adr-number> <adr-name>`

- Derive `<adr-number>` and `<adr-name>` from the ADR filename in `docs/adr/` (without `.md`): `0042-stock-transfer-approvals.md` → `ADR-0042 stock-transfer-approvals`.
- Example: `PRD: PAYMENTS ADR-0042 stock-transfer-approvals`

**PRD slice issue** — title starts exactly with:

`Slice NNNN of <PROJECT-CODE> ADR-<adr-number> <adr-name> (#<prd-issue>): <Short heading>`

- `NNNN`: zero-padded four-digit slice number, local to that PRD, starting at `0001`.
- `<prd-issue>`: GitHub issue number of the parent PRD.
- `<Short heading>`: concise, action-oriented, scannable in an issue list.
- Example: `Slice 0001 of PAYMENTS ADR-0042 stock-transfer-approvals (#4812): Add approval state model`

**Non-PRD issue** — not tied to a PRD:

`<PROJECT-CODE>: <short imperative heading>`

**Labels:** every triaged issue carries exactly one category (`bug` or `enhancement`) and exactly one state (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`).

Output Style

Generate this section verbatim in AGENTS.md, after the GitHub Issue Titles section:

## Output Style

Chat only. Does not apply to code, docs, PRDs, release notes, PR bodies, or prompts.

### 1. Plain-Language Chat

- Be extremely concise. Sacrifice grammar for the sake of concision.
- Use short, complete sentences when clarity would otherwise suffer. Clarity beats compression.
- Lead with the conclusion.
- Use everyday words. Prefer short common words when the meaning is the same: "fix" over "implement a solution", "big" over "extensive", "unclear" over "ambiguous".
- Default to simple but technical English. Say what failed, then why, in one clear sentence when possible.
- Write for users who may not read English fluently.
- Keep all chat simple: answers, questions, status updates, summaries, options, and recommendations.
- Use short sentences. One idea per sentence.
- Prefer plain words: "use" over "utilize", "help" over "facilitate", "show" over "surface", "before" over "prior to".
- Explain practical effect first. Put code names and system terms after the plain explanation.
- Explain technical terms once, in simple words.
- Rewrite dense findings into simple cause, effect, and choice.
- Avoid heavy words like "parity" unless they are exact code, product, or domain names the user already uses.
- Keep exact code, DB, API, route, screen, and file names verbatim.
- Explain what those names do when they matter to the answer.
- Split dense technical chains into `Correction`, `Why`, `Scope`, `Change`.
- For questions and options, start with the real decision in simple words. Add technical details only where needed.
- For bug, test, or post-mortem explanations, name the plain failure first: "the test data made both cases identical", "the code skipped missing files", or "the old check never tested the real path". Put project terms after the plain failure, not before it.
- Avoid arrow-only flows unless followed by plain words.
- If one sentence has more than three identifiers, split it.
- Do not use unexplained shorthand like "keys off", "guarded", "live path", "canonical flow", or "shared screen".
- Optional brevity skills are user-invoked only.

### 2. Understanding Checks

When the user asks you to repeat, confirm, or restate their understanding:

- Restate only what you understand.
- Ask the user to approve or correct it.
- Stop there. Do not plan, edit, run tools, or continue until the user confirms or corrects the understanding.

Tool-calling index: `tool-calling.md`.

Key Notes:

• @ references files/context (e.g. @src/main.go), not agents.
• Parallelism comes from the Agent Manager and start_subagent: the orchestrator decomposes a goal and spawns dynamic subagents that can share the parent's workspace or run in an isolated Git worktree (clean context window, same model).
• Antigravity CLI reads AGENTS.md directly from the active workspace as a supported context file. This kit treats AGENTS.md as the canonical instruction file for Antigravity CLI and emits no Antigravity-specific shim.
• Memory: No native memory file store in this kit's supported model. Use generated AGENTS.md and binding context files. Do not create repo memory files or add memory MCP servers for this kit. See `memory-global-defaults.md`.
• Multi-repo workspace policy: use workspace-root MCP config.
• For exact config-file placement by tool, use `tool-calling.md`.

Agents: parallel, background & roles

Parallelism is built into the Agent Manager: start_subagent spawns dynamic, dependency-aware subagents (parallel execution; specific concurrency limit is not publicly documented). Local background: /schedule runs cron-style tasks that survive app close, and Artifacts (plans, diffs, walkthroughs) are written to a folder you review on return. Managed Agents API / remote managed execution is cloud — do not use it.

MCP: project .agents/mcp_config.json; remote HTTP entries use serverUrl. Skills: project .agents/skills/<name>/SKILL.md; user-global ~/.gemini/antigravity/skills/<name>/ (also .agent/skills/ accepted as a back-compat path).

Permissions, hooks, slash commands

• Permission resources (config + /permissions): read_file, write_file, plus MCP-tool filtering. Rules use action(target) form with Allow / Deny / Ask lists.
• Permission modes: request-review (default), proceed-in-sandbox, always-proceed, strict.
• Highest elevated permission launch: agy --dangerously-skip-permissions. Do not combine it with --sandbox when the goal is full elevation; --sandbox enables terminal restrictions.
• Hooks: PreToolUse / PostToolUse with regex matcher on tool name; JSON schema includes toolCall.name, toolCall.args, stepIdx, plus common fields (conversationId, workspacePaths, transcriptPath, artifactDirectoryPath). Hook decision values: allow, deny, ask.
• Useful slash commands: /goal, /grill-me, /schedule, /browser, /artifact, /permissions, /context, /btw, /model, /config.
• Non-interactive: agy -p "<prompt>" for pipelines.

Tool-calling index: `tool-calling.md`.

Authoritative tool reference: https://code.claude.com/docs/en/tools-reference

Key Notes:

• Tool names are the exact strings used in permission rules (permissions.allow/deny), subagent tools lists, and hook matchers. Permission patterns also accept file globs and domain filters: Read(~/secrets/**), Edit(/src/**), Agent(Explore), WebFetch(domain:example.com).
• The subagent tool is Agent. It runs autonomously in a separate context window and returns a single text result; parallel work means multiple Agent calls in one turn.
• Skills run through the built-in Skill tool — there is no separate per-skill tool entry. Invoke directly with /skill-name, or let Claude CLI auto-load a skill when the request matches its description.
• Task tracking uses TaskCreate / TaskGet / TaskList / TaskUpdate / TaskStop. TodoWrite is disabled by default; set CLAUDE_CODE_ENABLE_TASKS=0 to re-enable it.
• Skills support allowed-tools frontmatter to restrict which tools a skill may use.
• Claude CLI reads CLAUDE.md as its canonical workspace file, not AGENTS.md. To share rules across runtimes, keep AGENTS.md canonical and write a CLAUDE.md shim that imports only it (e.g. @AGENTS.md) — this is the pattern the agents-md skill emits.
• Memory: Auto memory is on by default (autoMemoryEnabled in settings; /memory to toggle). Native project memory is user-local. Do not create, import, symlink, or sync repo memory files. See `memory-global-defaults.md`.
• Other built-in tools available for permission / hook matchers: AskUserQuestion, EnterPlanMode / ExitPlanMode, EnterWorktree / ExitWorktree, LSP, Monitor, NotebookEdit, PowerShell (Windows default; opt-in elsewhere via CLAUDE_CODE_USE_POWERSHELL_TOOL=1), ToolSearch, WaitForMcpServers, ScheduleWakeup, PushNotification, RemoteTrigger, SendMessage, ShareOnboardingGuide, TeamCreate / TeamDelete (gated by CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1), CronCreate / CronList / CronDelete, ListMcpResourcesTool / ReadMcpResourceTool.
• Multi-repo workspace policy: use workspace-root MCP config.
• Highest elevated permission launch: claude --dangerously-skip-permissions, equivalent to claude --permission-mode bypassPermissions. This bypasses the permission layer; use only in isolated containers, VMs, or disposable worktrees.
• For exact config-file placement by tool, use `tool-calling.md`.

Agents: parallel, background & roles

Parallel: issue multiple Agent calls in one turn (each runs in its own context window and returns one summary). The subagent selector parameter is agent_type. Local background: run_in_background: true on Bash; mark a subagent background: true in .claude/agents/<name>.md (background subagents auto-deny permission prompts) or press Ctrl+B; add isolation: worktree for file isolation. List/stop background Bash tasks with /tasks (also via TaskList / TaskStop); manage background subagents via /agents (Running tab). Subagents cannot spawn subagents. Fork the current conversation via the Agent tool's fork mode (a forked Agent inherits the parent conversation and always runs in background). Cloud features (Routines via /schedule / RemoteTrigger, agent teams behind CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1, background agents on claude.ai) are out of scope here — kit policy is local-only.

Custom-agent frontmatter: name, description, tools / disallowedTools, model, permissionMode, maxTurns, background, isolation: worktree, skills, mcpServers, hooks, memory, effort, color, initialPrompt. To restrict which subagents a main-thread agent can spawn, use Agent(type1, type2) in tools. Task tracking uses TaskCreate / TaskGet / TaskList / TaskUpdate / TaskStop.

Tool-calling index: `tool-calling.md`.

Key Notes:

• Subagent workflows are on by default. Config lives in ~/.codex/config.toml (global) or <workspace-root>/.codex/config.toml (project).
• Codex CLI reads AGENTS.md (and AGENTS.override.md, which wins) hierarchically from ~/.codex and from repo root down to CWD, capped at project_doc_max_bytes (32 KiB default). The child_agents_md feature flag layers additional per-directory guidance.
• Memory: Off by default. Enable globally with [features] memories = true and [memories] use_memories / generate_memories in ~/.codex/config.toml. Native store: ~/.codex/memories/. Do not create or sync repo memory files. See `memory-global-defaults.md`.
• Multi-repo workspace policy: use workspace-root MCP config.
• Highest elevated permission launch: codex --dangerously-bypass-approvals-and-sandbox (or explicit codex --sandbox danger-full-access --ask-for-approval never). This removes sandboxing and approval prompts; use only in an external sandbox or disposable worktree.
• For exact config-file placement by tool, use `tool-calling.md`.

Agents: parallel, background & roles

The orchestrator dispatches workers via spawn_agent / send_input / resume_agent / wait_agent / close_agent, plus spawn_agents_on_csv for batch fan-out (each worker calls report_agent_job_result once). Limits live under [agents]: max_threads (default 6), max_depth (default 1 — workers cannot spawn workers), job_max_runtime_seconds (fallback 1800). Switch between live threads with /agent. Worktrees and Automations are Codex app features, not CLI features. Codex Web runs tasks remotely — kit policy is local-only, so do not use it.

Built-in roles: default, worker, explorer. Custom roles live in standalone .codex/agents/<name>.toml or ~/.codex/agents/<name>.toml files. Required fields: name, description, developer_instructions. Optional: model, model_reasoning_effort, sandbox_mode, mcp_servers, skills.config, nickname_candidates.

Tool-calling index: `tool-calling.md`.

Key Notes:

• Background: promote a running task or shell with Ctrl+X → b; inspect backgrounded shells with read_bash / list_bash / stop_bash / write_bash.
• Modes: Shift+Tab cycles standard → plan → autopilot. Plan is a mode, not a subagent.
• Skills are invoked explicitly (e.g. /skill-name); plugins bundle agents, skills, hooks, and MCP server configs for distribution.
• Cloud handoff: /delegate ships a task to the remote Copilot coding agent (opens PRs). Kit policy: do not use.
• The GitHub MCP server ships built in; custom MCP servers add to it.
• Multi-repo workspace policy: use workspace-root MCP config.
• Memory: Enable in GitHub Copilot settings (account); CLI: /memory on, /memory off, /memory show (persists). store_memory stores recall in GitHub. Do not create or sync repo memory files. See `memory-global-defaults.md`.
• Highest elevated permission launch: copilot --allow-all (alias --yolo). This is equivalent to --allow-all-tools --allow-all-paths --allow-all-urls; combine with --autopilot only when the user wants autonomous multi-step continuation.
• For exact config-file placement by tool, use `tool-calling.md`.

Agents: parallel, background & roles

Parallel: /fleet makes the main agent decompose a prompt into independent subtasks and run them as context-isolated subagents; the underlying primitive is the task tool (with list_agents / read_agent for inspection). Built-in agents the orchestrator delegates to: explore, task, general-purpose, code-review, research. Local background: Ctrl+X → b promotes a running task / shell to the background. Cloud coding agent (runs in GitHub Actions, opens PRs; reachable via /delegate) is remote — do not use it.

Custom agents: .github/agents/<name>.md or .agent.md (repo) or ~/.copilot/agents/<name>.md (user). Frontmatter fields: name (optional), description (required), tools, model, target (vscode | github-copilot), mcp-servers, disable-model-invocation, user-invocable, metadata. The agent's prompt is the markdown body (max 30,000 chars), not a frontmatter field.

Cursor CLI Tool Mapping

Mechanics and permissions: `tool-calling.md`.

Key Notes:

• Cursor CLI command is agent (interactive: agent, non-interactive: agent -p "...").
• AGENTS.md is the canonical workspace instruction file; no extra shim is required for Cursor.
• Memory: No documented memory flag in ~/.cursor/cli-config.json. IDE “Generate Memories” (Settings → Rules) is IDE-local recall. Do not create repo memory files or add memory MCP servers for this kit. See `memory-global-defaults.md`.
• Cursor MCP config files: <workspace-root>/.cursor/mcp.json (recommended for multi-repo workspaces), ~/.cursor/mcp.json (global fallback).
• Skills load from .cursor/skills/, .agents/skills/, ~/.cursor/skills/, ~/.agents/skills/, plus compat dirs .claude/skills/, .codex/skills/, ~/.claude/skills/, ~/.codex/skills/.
• Subagent dirs: .cursor/agents/, .claude/agents/, .codex/agents/ (project) and ~/.cursor/agents/, ~/.claude/agents/, ~/.codex/agents/ (user).
• CLI permissions: per-project <root>/.cursor/cli.json (layered git-root → cwd), global ~/.cursor/cli-config.json. IDE-only auto-run allowlist (separate): ~/.cursor/permissions.json.
• Highest elevated permission launch: agent --yolo --sandbox=disabled --approve-mcps for interactive sessions; cursor-agent -p --force --sandbox=disabled --trust --approve-mcps "prompt" for headless. --yolo is the --force alias.
• Built-in subagents Explore, Bash, and Browser are delegated automatically when appropriate; see Subagents.

Agents: parallel, background & roles

Parallel: issue multiple Task calls in one turn (practical cap ~4). Local background: set is_background: true in .cursor/agents/<name>.md and rejoin with Await; for heavier isolation, run up to 8 local agents in separate git worktrees. Cloud Agents (formerly "Background Agents") are remote — do not use them; keep everything local. Custom-agent frontmatter: name, description, model (inherit or an ID), readonly, is_background.

The shell subagent type is bash (not shell). ~/.cursor/permissions.json is the IDE auto-run allowlist; CLI permissions live in ~/.cursor/cli-config.json (global) and <root>/.cursor/cli.json (project).

Native Memory Defaults By CLI

Copy-paste snippets for user-level config. Merge into existing files; do not overwrite unrelated keys.

This kit no longer creates repo MEMORY.md, wiki, discovery, or default knowledge-graph memory. Use each supported CLI's native memory only when that runtime provides it. Optional graph/index companions may be used when installed and task-fit, but their artifacts are not binding memory. Keep generated AGENTS.md as the shared workspace instruction file, and keep CONTEXT.md / docs/adr/ as binding project context when those files exist.

---

Codex CLI

File: ~/.codex/config.toml Docs: Memories, Config reference

[features]
memories = true

[memories]
use_memories = true
generate_memories = true
disable_on_external_context = true

• Native store: ~/.codex/memories/.
• Treat Codex memories as user-local recall. Do not sync them into repo files.
• Keep team/project rules in generated AGENTS.md, CONTEXT.md, and ADRs.
• EEA/UK/CH: native memories may be unavailable.

---

Claude CLI

Files: ~/.claude/settings.json, optional ~/.claude/CLAUDE.md Docs: Memory

{
  "autoMemoryEnabled": true
}

Optional global reminder in ~/.claude/CLAUDE.md:

## Native Memory

- Use Claude's native project memory for user-local recall.
- Do not create or sync repo MEMORY.md files.
- Shared project rules come from AGENTS.md, CONTEXT.md, and ADRs.

• autoMemoryDirectory is user/local settings only (not project settings.json).
• Do not symlink Claude memory into a repo file.

---

GitHub Copilot CLI

Account: GitHub → profile → Copilot settings → Copilot Memory → Enabled (Pro/Pro+ default on; org/enterprise may be off).

File: ~/.copilot/copilot-instructions.md

## Memory

- Prefer `/memory on` in CLI sessions (`/memory show` to verify).
- Use Copilot Memory for GitHub-hosted user/repo recall when enabled.
- Do not create or sync repo MEMORY.md files.
- Shared project rules come from AGENTS.md, CONTEXT.md, and ADRs.

• No memory key in ~/.copilot/settings.json; enablement is account + /memory slash commands.

---

Cursor CLI

File: ~/.cursor/cli-config.json — no built-in memory toggle (CLI config).

• Cursor CLI has no documented native memory toggle in CLI config.
• Cursor IDE may offer Settings → Rules → Generate Memories. Treat those as IDE-local recall.
• Do not create repo MEMORY.md files or add MCP memory servers as default memory for this kit.

---

Opencode CLI

File: ~/.config/opencode/opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["AGENTS.md", "CONTEXT.md"]
}

• Opencode has no native memory store in this kit's supported model.
• Use instructions only to point at generated AGENTS.md and binding context files.
• Do not include repo MEMORY.md paths.

---

Antigravity CLI

File: ~/.gemini/antigravity-cli/settings.json — no native memory file store.

• Antigravity CLI has no native memory file store in this kit's supported model.
• Use generated AGENTS.md plus binding context files.
• Do not add repo MEMORY.md files or third-party memory MCP servers as default memory for this kit.

---

Quick reference

Tool-calling index: `tool-calling.md`.

Key Notes:

• opencode exposes plain tool names (read, write, edit, bash, grep, glob, task, …) — no POSIX (cat / tee / sed / sh) aliasing. Discovery walks up for AGENTS.md (preferred) then CLAUDE.md (Claude-Code compat); globals at ~/.config/opencode/AGENTS.md and ~/.claude/CLAUDE.md.
• Memory: No native memory store in this kit's supported model. Use opencode.json instructions for generated AGENTS.md and binding context files only. Do not include repo memory paths. See `memory-global-defaults.md`.
• websearch requires the opencode provider or OPENCODE_ENABLE_EXA.
• Skills resolve from .opencode/skills/, ~/.config/opencode/skills/, plus compat dirs .claude/skills/, .agents/skills/, ~/.claude/skills/, ~/.agents/skills/.
• Multi-repo workspace policy: use workspace-root MCP config.
• Highest elevated permission launch: opencode run --dangerously-skip-permissions "prompt". For persistent custom agents, set the agent permission keys needed for the task to allow; wildcard {"*":"allow"} is the full tool permission form.
• For exact config-file placement by tool, use `tool-calling.md`.

Agents: parallel, background & roles

Parallel: the primary agent issues multiple task calls in one turn (each runs a child session and returns one <task_result>). task takes subagent_type, prompt, optional task_id (resume a child session), and optional background. Local background: task(background=true) runs async and returns a task_id; poll with task_status (gated by OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true; otherwise task is synchronous). opencode is fully local — no cloud agent.

Built-in agents: build (primary, full access), plan (primary, analysis-only), general (subagent, multi-step executor), explore (subagent, read-only), scout (subagent, read-only — external docs and dependency research). Hidden system agents (compaction, title, summary) run automatically. Users can also dispatch a subagent manually by mentioning @<agent-name> in a message; task permissions (allow / deny / ask per subagent) gate which children a primary may dispatch. Custom agents: .opencode/agents/<name>.md (project), ~/.config/opencode/agents/<name>.md (global), or inline under "agent" in opencode.json; frontmatter accepts description, mode (primary | subagent | all), model, permission, temperature, top_p, steps, color, disable, hidden, and tools (per-tool toggles, e.g. tools: { skill: false }).

Tool Calling Reference

How the six supported CLI runtimes invoke tools, and how this kit maps generic skill instructions to each runtime.

Supported runtimes are Codex CLI, Claude CLI, Antigravity CLI, Cursor CLI, Opencode CLI, and GitHub Copilot CLI only. Compatibility filenames used by those tools do not imply support for any other runtime.

Agent Orchestration Model

The main session is the orchestrator. It decomposes work into role-typed lanes, dispatches each lane to a local subagent (or a focused in-process tool pass when the runtime has no subagents), runs independent lanes in parallel, pushes long or noisy lanes to local background/async, and keeps the only seat for merge, conflict resolution, and final judgment. Subagents return summaries, not raw transcripts. This model is enforced by the AGENTS.md Non-Negotiable Rule Local Orchestration.

Local-only policy (no cloud agents)

Use only local subagents and local background/async execution. Local worktree-isolated parallel agents are allowed. Never delegate to cloud or remote background-agent products, even when the runtime makes them one keystroke away:

Canonical role lanes

Standard lane roles used across this kit. Each runtime's *-tools.md maps these to that runtime's concrete mechanism. Where a runtime has no dedicated built-in for a role, use its general-purpose subagent with the listed tool profile.

Parallel & background mechanism by runtime

Per-runtime role-to-mechanism maps and corrections live in each *-tools.md.

Highest elevated permission by runtime

Use these only when the user explicitly asks for highest/elevated/full/YOLO permission, and prefer isolated containers, VMs, dev containers, or disposable worktrees.

Cursor CLI

Cursor CLI uses the agent command and the same tool-calling loop: the model emits a structured tool request, the runtime executes it, and results are appended to context before the next turn. There is no practical limit on tool calls per task.

Docs: Tool calling fundamentals, Agent tools overview, CLI usage, Subagents.

Tool names (runtime / hooks)

These are the identifiers used in hook matchers (preToolUse, postToolUse) and in agent traces:

Agent also uses built-in Explore, Bash, and Browser subagents automatically for heavy search, shell series, and browser work. Custom subagents live in .cursor/agents/*.md and are invoked via Task or /subagent-name in chat.

Skill invocation (not a hook tool type)

Skills are separate from the table above:

• Explicit: /skill-name in chat (e.g. /release-notes)
• Auto: agent loads skills whose description matches the request (unless disable-model-invocation: true)

Skill directories: project .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/; user ~/.cursor/skills/, ~/.agents/skills/, ~/.claude/skills/, ~/.codex/skills/ (compat).

Subagents (Task tool)

Parallel work: multiple Task calls in one assistant turn (practical cap ~4 parallel subagents). Local async: set is_background: true in a subagent's .cursor/agents/<name>.md frontmatter and rejoin with the Await tool. For heavier isolation, Cursor can run up to 8 local agents in separate git worktrees. Resume with the agent ID from a prior subagent run.

Cursor Cloud Agents (formerly "Background Agents") run remotely and are out of policy here — use local subagents/worktrees instead (see Agent Orchestration Model).

Cursor CLI subagent support is documented in Subagents.

Modes and write access

Non-interactive CLI: agent -p "prompt" (--print) runs with full tools unless mode restricts edits. Use --sandbox=disabled only when the user wants auto-approved shell.

Highest elevated launch: agent --yolo --sandbox=disabled --approve-mcps for interactive sessions; in headless automation use cursor-agent -p --force --sandbox=disabled --trust --approve-mcps "prompt". --yolo is an alias for --force.

Headless output: --output-format text|json|stream-json (with --stream-partial-output for incremental deltas). Auth via CURSOR_API_KEY. Useful CLI flags: --worktree, --workspace <path>, --resume [thread-id]; sessions managed with agent ls / agent resume.

Permissions

Tool allow/deny uses pattern strings. Examples:

• Shell(git) — prefix match: any git subcommand. Shell(**) — all shell commands.
• Mcp(server:tool) — colon-separated (e.g. Mcp(datadog:*), Mcp(*:read_*)).
• Read(src/**/*.ts), Write(<glob>), WebFetch(*.example.com) — file / web allowlists.
• Deny rules take precedence over allow rules.

Permission files:

• CLI: ~/.cursor/cli-config.json (global) and <root>/.cursor/cli.json (per-project, layered git-root → cwd).
• IDE only (separate auto-run allowlist for editor): ~/.cursor/permissions.json — uses server:tool for MCP and prefix matching for shell.

Kit mapping (generic → Cursor)

See `cursor-tools.md` for the full skill-kit → Cursor equivalence table.

All runtimes (index)

Context files (multi-repo workspaces)

Native CLI memory defaults: `memory-global-defaults.md`.

MCP placement (multi-repo workspaces)

Keep MCP configuration at workspace root for supported coding tools:

• Codex CLI: <workspace-root>/.codex/config.toml
• Claude CLI: <workspace-root>/.claude/settings.local.json
• Antigravity CLI: <workspace-root>/.agents/mcp_config.json
• Cursor CLI: <workspace-root>/.cursor/mcp.json (plus optional ~/.cursor/mcp.json fallback)
• Opencode CLI: workspace-root opencode.json / MCP config where used
• GitHub Copilot CLI: <workspace-root>/.mcp.json or <workspace-root>/.github/mcp.json (user fallback: ~/.copilot/mcp-config.json)