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.
Joan Leon