docs/agents.md and two persona files said /review and /test wrap the
code-reviewer and test-engineer personas. They invoke a skill in the main
session and spawn nothing (#681). The review commands also still asked for
Critical/Important/Suggestion while the skill and persona use
Critical/Required/Optional/Nit, and /ship named the old labels.
The persona used Critical/Important/Suggestion while code-review-and-quality
uses Critical/Required/Optional/Nit, so the same finding got labeled differently
depending on which entry point ran the review. Align the persona to the skill's
four-level scheme (the skill is the source of truth) and note the shared
vocabulary to prevent future drift.
Tools that scan agents/*.md as custom agent definitions (e.g. GitHub Copilot CLI) parse every Markdown file in agents/ and require YAML frontmatter. agents/README.md was docs, not an agent, so it triggered "malformed custom agent" warnings on every session start.
Moving the docs to docs/agents.md keeps agents/ containing only real agent definitions. Updates internal links in the moved file, in the four persona files, AGENTS.md, and adds a pointer from the root README.
Fixes#258
Each persona now ends with a three-bullet block stating when to invoke it
directly, which slash commands wrap it, and the rule that personas do not
invoke other personas. Keeps the persona honest about its place in the
workflow without re-stating the broader orchestration model.
Anthropic's Claude 4 prompting best practices document warns that
newer models overtrigger on strong directive language (Never/Always/MUST)
that was necessary for older models. This replaces aggressive directives
with natural phrasing across skills and agents while preserving all
security-critical rules (OWASP, prompt injection, secrets) unchanged.
Also reframes trunk-based development as "Recommended" with a note
acknowledging alternative branching strategies like gitflow.
Addy Osmani