Plugin scope now authors a single vendor-neutral .apm/agents/<name>.agent.md
file (name/description/model/body only) instead of a Claude Code + Copilot
CLI pair, per ADR-0016: apm compile has no per-target field integrator, so
tools: and all Claude-only fields (isolation/maxTurns/effort/memory/
permissionMode) are omitted entirely rather than shipping a value that's
guaranteed wrong on one harness. Scope detection switches from a flat
plugin.json check to the same apm.yml+type: walk-up agent-audit's
validate.sh already uses. Project scope and user scope are unaffected —
both keep the existing dual-file pair model.
Refs: #89
Deferred item from PR #85 review. Per ADR-0013: cherry-picks two low-noise
rules from trialing write-good/alex against the real corpus (VagueQualifier,
SentenceOpenerThereIs) into styles/Kyberforge rather than adopting either
package wholesale (both are tuned for blog prose and were noisy on this
repo's terse, imperative instruction files - see the ADR's rejected-rule
list). Adds a new skill-size-check pre-commit hook enforcing agentskills.io's
500-line/5,000-token SKILL.md ceiling, currently unenforced. Fixes the 28
resulting violations across 20 existing SKILL.md/agent files so the
enforcing pre-commit hook lands clean.
governance.md/CONTROLS.md were evaluated and excluded as rule sources -
they're org/CI-infrastructure controls, not prose patterns Vale can express.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QUDczvw1H3eEeMD29Q9Lbi
The Prerequisites checklist mixed items to confirm (preconditions) with an
action to perform (capturing git log), so the following "stop and ask if
missing" gate didn't logically apply to the git-log step. The improve flow
also had no reminder to update source_keys/sources.md when an edit touches
research-sourced content, unlike the create flow's explicit step for it.
Refs #69
Independent skill-audit found that agent-author's closing checklists never
verified template <!-- --> comments were stripped from frontmatter (produces
invalid YAML if left in), the Copilot field-exclusion checklist omitted two
fields present in the authoritative list, and the improve flow had no
agent-audit availability check unlike the create flow.
Prior sessions had authoring subagents report completion after only
staging changes (git diff --stat showing output, but no git commit).
agent-author's create and improve flows now require capturing
git log --oneline -1 before and after the authoring pass and asserting
the hash actually changed via a real commit, matching the fix already
applied to skill-author.
Refs #69
`claude plugin validate --strict` auto-discovers every .md under a
plugin's agents/ directory as an agent requiring frontmatter, so the
provenance file there always needs fake agent frontmatter to pass
validation. Confirmed empirically that an explicit `agents` manifest
array can't suppress this discovery. Move the file to <plugin-root>/
sources.md instead, and update agent-author/agent-audit accordingly.
Adds ADR-0010, partially superseding ADR-0005's `agents/sources.md`
convention. Fixes#63.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
- agent-author: convert template comments from YAML (#) to HTML (<!-- -->)
- Easier to spot and distinguish from functional comments
- Add explicit "Delete template comments before shipping" reminders
- Update SKILL.md Steps 2-3 with removal instruction
- agent-audit: add comment-discipline check
- Flag excessive frontmatter documentation comments as padding
- Mirrors skill-audit's body-discipline principle
- Update coverage line to include comment-discipline dimension
This ensures agents follow the same comment-cleanup discipline as skills,
preventing template documentation from shipping with agent definitions.
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
Corrects three FAIL findings from the skill-audit run:
- Scope detection table in SKILL.md and references/scripts.md now lists all
four plugin-marker variants the script actually checks (plugin.json,
.claude-plugin/plugin.json, .plugin/plugin.json, .github/plugin/plugin.json)
- assets/README.md copilot.agent.md description was wrong about field set;
replaced with accurate CLI-format description noting excluded cloud/IDE fields
and the Copilot tool aliases actually used.
Also applies the SUGGESTION: moves the conditional reference
(`If the destination is a plugin directory, read references/deployment-modes.md`)
out of the ## Gotchas section body and into ## Route as a standalone line,
immediately after ## Gotchas closes.
INFO findings (source_keys frontmatter) were already present in both
references/README.md and references/scripts.md — no change needed.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0147vXtL5sP6vorDdqXGJJU9
## Why
agent-author produces agents/sources.md at plugin scope to record which
research sources informed which agent files. agent-audit had no way to
validate this chain, leaving stale or missing provenance undetected.
## Implementation Notes
Validation is per-pair (the given agent file + its counterpart) rather
than plugin-wide, keeping the scope consistent with validate.sh. The
script exits 0 silently for non-plugin-scope agents.
source_keys is top-level in both CC .md and Copilot .agent.md files
(not under metadata:) to avoid conflict with Copilot's own metadata
field semantics. Checks 0, 1, 2, 4, 5, 6 mirror the skill provenance
set; upstream research-doc cross-reference checks (7, 8) are deferred.
agent-author Steps 2, 3, and 4 updated to formally specify the
agents/sources.md format and instruct authors to add source_keys to
both files when research sources are in context.
Refs: #60
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0147vXtL5sP6vorDdqXGJJU9
## Why
The last acceptance criterion from #11: agent-author's close step should
reference agent-audit so authors are prompted to validate the pair before
shipping, matching the pattern skill-author uses with skill-audit.
Refs: #11
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0147vXtL5sP6vorDdqXGJJU9
## Why
Same gap as skill-author: no instruction to bump the plugin version after
creating or modifying an agent inside a plugin.
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
## Why
skill-author explicitly excludes agent definition files ("Do not use to author
agent definition files"). No factory skill existed to create or improve the
.md / .agent.md files that define Claude Code subagents and Copilot CLI agents
in a plugin, project, or user scope. This fills that gap.
## Implementation Notes
Single-root scaffold convention: new-agent.sh <name> <root> derives both
provider file paths from the root by convention — plugin scope (plugin.json
present) writes both files into <root>/agents/; non-plugin scope writes
.claude/agents/<name>.md and .github/agents/<name>.agent.md. This keeps
input minimal while always generating both provider files. See ADR-0015.
Routing is file-level (not directory-level like skill-author): neither file
exists → create flow; at least one exists → improve flow; scaffold is a
file-by-file no-op so retries are safe.
No companion agent-audit skill — inline validation in the close step covers
the simpler agent field contract. agent-audit is tracked as a follow-on.
## Impact
Closes the skill-author gap for agent definitions. Follow-ons tracked in
Gitea #11: agent-audit skill and --copilot-dest override flag for non-standard
Copilot project paths.
---
ADR: docs/adr/0015-agent-author-dual-provider-scaffold.md
Refs: #10
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
