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
- New "AI / LLM Features" review scope mapped to the OWASP LLM Top 10
- SSRF question added to third-party integrations
- Rules updated to start from trust boundaries (STRIDE) and to check the
LLM Top 10 and supply-chain risk
Per the Agent Teams docs, a persona body is appended to the teammate's
system prompt as additional instructions — not a replacement. The prior
wording implied the persona owned the whole prompt, which would mislead
a persona author about what coordination instructions they inherit from
the lead (SendMessage, task-list tools, etc.).
Fixes the same inaccuracy in two locations (agents/README.md and
references/orchestration-patterns.md). Flagged in review.
Verify the orchestration design against the official Claude Code docs and
make the platform mapping explicit:
- /ship now names the Agent tool and the subagent_type field directly,
with a fallback note for harnesses that lack an Agent tool.
- AGENTS.md notes that personas work as both subagents and Agent Teams
teammates, and lists the unsupported plugin frontmatter fields.
- agents/README.md gains a Claude Code interop section and notes that
rule #2 is also a hard platform constraint.
- references/orchestration-patterns.md gains a Claude Code compatibility
appendix covering plugin paths, the subagents-vs-teams comparison, the
built-in Explore/Plan/general-purpose subagents, and the parallel
Agent tool call requirement. Pattern 5 now points at Explore first.
No behavior changes; documentation only.
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.
New agents/README.md introduces the three-layer model (skill / persona /
command), a decision matrix for picking the right invocation style, and
worked examples of both valid (parallel fan-out via /ship) and invalid
(router persona) orchestration. Establishes the rule that personas do not
invoke other personas.
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