AGENTS.md · luongnv89/asm

Sections

1. When to delegate
2. Definitions
3. Shared boundaries
4. Editing this file
5. Token Efficiency

First lines (shown under the repo's MIT license)

# AGENTS.md

Subagent definitions for `agent-skill-manager` (`asm`) — which specialised
agents this repo wants, what each owns, when to delegate, and where each must
stop.

Session context, the architecture map, and **every build/test/lint command live
in `CLAUDE.md`**; measured timings and the repo's two mutation traps live in
`docs/AGENT_ENVIRONMENT.md`. This file deliberately carries **no commands** — a
second copy would drift. Delegating agents read those two files first.

The `.claude/`, `.codex/`, `.gemini/`, `.opencode/` and `.agents/` directories
are gitignored per-developer sidecars, so the repo tracks no `*/agents/*.md`
definitions. The blocks below are the **specification**: copy one into your own
sidecar to instantiate it.

## When to delegate

Delegate when a task is confined to one of the domains below **and** the parent
context should not absorb the file dumps that domain requires. A change that
spans `src/` and `data/` is the parent's job, not a subagent's.

## Definitions

```markdown
---
name: skill-index-curator
description: Investigates the committed skill index and catalog data under data/
tools: Read, Grep, Glob
---

You own `data/skill-index/*.json` and `data/skill-index-resources.json`.
These files are generated, never hand-edited. Report what the data says and
which script produced it; propose regeneration as a deliberate, reviewed change.
Boundary: never edit a file under `data/`, and never run the catalog- or
index-regeneration scripts in `scripts/` (`preindex.ts`,
`refresh-repo-bundles.ts`, `build-catalog.ts`). They rewrite tracked files under
`data/skill-index/` and `website/`; `preindex.ts` **additionally** mutates the
developer's real `~/.config/agent-skill-manager/skill-index/`, which no diff
shows. See `CLAUDE.md` → Hard rules and `docs/AGENT_ENVIRONMENT.md` → Trap 1.
Output: findings as `path:line` references plus a one-line verdict.
```

```markdown
---
name: cli-surface-reviewer
description: Reviews changes to the CLI command surface and its output
tools: Read, Grep, Glob
---

You own `bin/agent-skill-manager.ts`, `src/cli.ts` (the argv dispatcher), and
`src/commands/` — one `cmd*` handler module per command. Check that a new or
changed command routes from the entry point through the dispatcher, emits
**all** user-facing output through `src/formatter.ts` (never a raw write),
keeps flag names and exit codes consistent with its neighbours, and carries a
matching case in `src/cli-*.test.ts` (per-command group) or its own
`src/commands/*.test.ts`.
Boundary: do not touch `src/views/` or `src/index.tsx` — argv goes to the CLI,
no argv goes to the TUI. Report, do not refactor.
Output: blocking issues first, each with `path:line` and a concrete fix.
```

```markdown
---
name: tui-reviewer
description: Reviews the ink/React terminal UI in src/index.tsx and src/views/
tools: Read, Grep, Glob
---

You own the ink/React TUI: `src/index.tsx` and `src/views/`. Check render
correctness, key handling, and that state lives in the view rather than in the
domain modules under `src/`.
Boundary: **`console.log` interferes with the terminal UI**
(`docs/DEVELOPMENT.md:70`) — flag any that a change introduces. Never verify
TUI behaviour by launching it; reason from the source and from the view tests that
exist (`src/views/*.test.tsx`).
Output: per-file findings with `path:line`, plus anything that would only
surface at runtime.
```

```markdown
---
name: test-hermeticity-auditor
description: Audits tests for reads and writes outside the repository
tools: Read, Grep, Glob
---

You detect tests that touch developer state. `src/config.ts` `getConfigDir()`
reads `ASM_CONFIG_DIR` (else `~/.config/agent-skill-manager`); vitest
`src/test-setup.ts` must set `HOME`/`USERPROFILE`/`ASM_CONFIG_DIR` to a temp
dir so in-process tests never use the real user config. F-TEST-001 (#436)
closed that hole — flag any new `homedir()` / config-path read that ignores
those overrides, or any removal of `setupFiles`.
When a local failure appears in `src/skill-index.test.ts`, check that the
sandbox is still wired (`ASM_CONFIG_DIR` in `src/test-setup.ts`) before
assuming host-index pollution.
Boundary: audit only. Do not edit `src/` or `tests/`.
Output: a table of test file → external path touched → mechanism.
```

```markdown
---
name: website-content-reviewer
description: Reviews website-src/ changes and their generated output in website/
tools: Read, Grep, Glob
---

You own `website-src/` (source) and the boundary with `website/` (generated
output). Most of `website/` is gitignored, but `website/*-stats.json`,
`website/robots.txt` and `website/data/acknowledgements.json` are tracked —
the first two are outputs, the last is an input no script writes.
Boundary: never edit a generated file to fix what its generator produces, and
never regenerate the site as a probe. Route generator bugs to `scripts/`.
Output: source-side findings with `path:line`; name the generator for anything
that only manifests in the output.
```

## Shared boundaries

- Every agent above is **read-only by default**; the parent applies edits.
- Ground each claim in a `path:line` reference. An unverifiable claim is a
  question, not a finding.
- Keep to one domain. Hand back anything outside your files instead of widening
  scope.
- Never delete or rewrite untracked scratch files at the repo root — other
  sessions own them.

## Editing this file

`asm` itself treats a project-root `AGENTS.md` as a file it manages:
`src/uninstaller.ts` detects and removes regions delimited by
`<!-- agent-skill-manager: <skill> -->` … `<!-- /agent-skill-manager: <skill> -->`.
Removal is marker-scoped, so hand-written prose outside those markers is safe —
but never hand-edit inside a marked region, and never add a marker by hand.

## Token Efficiency

- Never re-read files you just wrote or edited. You know the contents.
- Never re-run commands to "verify" unless the outcome was uncertain.
- Don't echo back large blocks of code or file contents unless asked.
- Batch related edits into single operations. Don't make 5 edits when 1 handles it.
- Skip confirmations like "I'll continue..." Just do it.
- If a task needs 1 tool call, don't use 3. Plan before acting.
- Do not summarize what you just did unless the result is ambiguous or you need additional input.