Defame1297
6f6b70781d
A fresh /code-review of the APM-native authoring retarget (PR #93) found several correctness bugs beyond the ones already fixed on this branch: - new-agent.sh silently walked a marker-less subdirectory under $HOME up to user scope, contradicting its own usage text ("user scope is checked directly, no walk-up") and risking scaffolding into shared global ~/.claude or ~/.copilot directories instead of the intended local path. - The hand-copied apm.yml type: manifest detector in new-agent.sh and new-skill.sh accepted mismatched quotes (e.g. `type: "skill'`) that validate.sh's regex correctly rejects, and silently dropped a final apm.yml line lacking a trailing newline — causing the scaffolder and validator to disagree on scope for identical input. - Plugin-scope agent frontmatter could still contain the apm-agent.md template's HTML comments at ship time with no audit signal, yet apm compile copies frontmatter verbatim and <!-- --> breaks YAML parsing on both downstream harnesses. - ADR-0016 asserted agent-audit already implements a SUGGESTION heuristic for tool-restriction-needing plugin-scope agents; it doesn't. - agent-audit/README.md still described the old plugin-pair model this PR replaced with a single-file allowlist model. - validate.sh's project/user-scope CC-only/Copilot-only field checks and counterpart-missing check lost their only test coverage when the old plugin-pair fixture was deleted. Also replaces an echo-into-sed two-value parse (4 forks per call) with a single space-separated echo + read in both scaffolders. Regression tests added for every fix above, including one for a bug this pass introduced and the test suite caught: an initial two-line echo + `read` attempt silently dropped the second value, since `read` consumes only one line regardless of embedded newlines. Full suite: 158 bats tests, 39 shell-script tests, 12/12 summary categories, 0 failures. Refs: #89, #93
agent-author
Creates and improves agent definition files for Claude Code and GitHub Copilot CLI.
What it does
Scaffolds and fills in agent definition files at plugin/APM, project, or user scope. Project and user scope always generate a Claude Code + Copilot CLI file pair (.md + .agent.md) in one pass. Plugin/APM scope generates a single vendor-neutral .apm/agents/<name>.agent.md file instead — no separate Claude Code / Copilot split, since apm compile has no per-target field integrator (see ADR-0016). Also applies improvement signals — grill output, inline feedback, session context — to existing agent files. Bumps the version after every change: the resolved package's apm.yml at plugin/APM scope (minor for new agents, patch for improvements); project/user scope has no manifest to bump.
Before you start
Have ready: the agent's name (kebab-case), the root directory (plugin root, project root, or ~), a one-sentence purpose, and the triggering condition (when should the runtime delegate to this agent?).
Usage
/agent-author
Manual scaffold (human workflow):
bash scripts/new-agent.sh <agent-name> <root>
# Examples:
bash scripts/new-agent.sh code-reviewer packages/my-package/ # plugin/APM scope if packages/my-package/apm.yml has a type: field
bash scripts/new-agent.sh deploy-assistant .
bash scripts/new-agent.sh security-reviewer ~
Files
| File | Purpose |
|---|---|
SKILL.md |
Skill instructions for agents |
scripts/new-agent.sh |
Scaffolds agent definition file(s) from templates — a single .apm/agents/<name>.agent.md at plugin/APM scope, or a Claude Code + Copilot CLI pair at project/user scope |
references/deployment-modes.md |
Plugin/APM vs project vs user scope: restrictions, scoped identifiers, path conventions |
references/scripts.md |
Conventions for new-agent.sh and any future scripts: contract, template variables, file placement, error messages |
references/sources.md |
Research provenance — sources that informed this skill |
assets/templates/claude-code.md |
Annotated Claude Code agent definition template (project/user scope) |
assets/templates/copilot.agent.md |
Annotated Copilot CLI agent definition template (project/user scope) |
assets/templates/apm-agent.md |
Annotated vendor-neutral APM agent definition template (plugin/APM scope) |
tests/new-agent.bats |
bats tests for scripts/new-agent.sh |
assets/README.md |
Directory meta-documentation for assets/ |
references/README.md |
Directory meta-documentation for references/ |
scripts/README.md |
Directory meta-documentation for scripts/ |
tests/README.md |
bats dependency instructions and run command |