docs(agents): add Anti-Rationalization tables and Tier 2 docs#173
docs(agents): add Anti-Rationalization tables and Tier 2 docs#173maystudios merged 1 commit intomainfrom
Conversation
…docs Add Anti-Rationalization Table sections to executor.md and planner.md agent definitions to enforce evidence-based claims. Add Tier 2 Agent Teams documentation to AGENTS.md covering activation, communication, and hooks for multi-agent orchestration. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Adds stronger evidence/verification guidance to agent templates and extends the agent registry documentation to cover Tier 2 Agent Teams orchestration.
Changes:
- Added an Anti-Rationalization Table section to the
plannerandexecutoragent templates. - Added a new “Tier 2 — Agent Teams” section to the agent registry with activation, communication, and hook references.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| templates/agents/planner.md | Inserts an Anti-Rationalization Table before the Completion Gate to enforce evidence-based planning claims. |
| templates/agents/executor.md | Inserts an Anti-Rationalization Table before the Completion Gate to enforce evidence-based execution claims. |
| templates/agents/AGENTS.md | Documents Tier 2 Agent Teams activation/communication/hooks in the agent registry. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ### Communication | ||
|
|
||
| Teams coordinate exclusively through: | ||
| - **Task lists** — `.claude/tasks/{team-name}/` for pending work |
There was a problem hiding this comment.
The task list path is documented as .claude/tasks/{team-name}/, but the implementation and other specs use the user-level directory ~/.claude/tasks/{team-name}/. Using a project-relative .claude/tasks path is likely to mislead readers about where Agent Teams stores/reads task files; update this path to match the actual location.
| - **Task lists** — `.claude/tasks/{team-name}/` for pending work | |
| - **Task lists** — `~/.claude/tasks/{team-name}/` for pending work |
| Teams coordinate exclusively through: | ||
| - **Task lists** — `.claude/tasks/{team-name}/` for pending work | ||
| - **GitHub Issues** — Phase tracking, task sub-issues, plan comments | ||
| - **Handoff contracts** — Structured output posted as GitHub Issue comments | ||
| - **SendMessage** — Direct inter-agent messages within the same team |
There was a problem hiding this comment.
This section says teams coordinate "exclusively" via a short list, but elsewhere in the repo Agent Teams coordination also includes shared artifacts like MEMORY.md, and this file earlier states agents do not communicate directly (which conflicts with the SendMessage bullet here). Consider softening/removing "exclusively" and explicitly scoping the earlier statement to Tier 1, while describing Tier 2 as allowing peer-to-peer messaging.
| Teams coordinate exclusively through: | |
| - **Task lists** — `.claude/tasks/{team-name}/` for pending work | |
| - **GitHub Issues** — Phase tracking, task sub-issues, plan comments | |
| - **Handoff contracts** — Structured output posted as GitHub Issue comments | |
| - **SendMessage** — Direct inter-agent messages within the same team | |
| In Tier 2, teams coordinate primarily through the following shared artifacts and channels, and may also use limited peer-to-peer messaging: | |
| - **Task lists** — `.claude/tasks/{team-name}/` for pending work | |
| - **GitHub Issues** — Phase tracking, task sub-issues, plan comments | |
| - **Handoff contracts** — Structured output posted as GitHub Issue comments | |
| - **SendMessage** — Tier 2-only direct inter-agent messages within the same team |
| ### Hooks | ||
|
|
||
| Two hooks support Tier 2 operations: | ||
| - `maxsim-teammate-idle` (TeammateIdle) — Checks for pending tasks and assigns idle teammates |
There was a problem hiding this comment.
maxsim-teammate-idle is described as "assigns idle teammates", but the hook implementation only checks for pending tasks and blocks idling with feedback; it doesn’t perform assignment. Rewording to reflect the actual behavior (prevent idle when tasks exist / prompt teammate to pick up work) would keep this reference accurate.
| - `maxsim-teammate-idle` (TeammateIdle) — Checks for pending tasks and assigns idle teammates | |
| - `maxsim-teammate-idle` (TeammateIdle) — Checks for pending tasks and prevents idling when work is available by prompting the teammate to pick up tasks |
|
🎉 This PR is included in version 5.13.1 🎉 The release is available on: Your semantic-release bot 📦🚀 |
Summary
## Anti-Rationalization Tablesection totemplates/agents/executor.mdandtemplates/agents/planner.md(before their Completion Gate sections) to enforce evidence-based claims## Tier 2 — Agent Teamssection totemplates/agents/AGENTS.mddocumenting activation, communication, and hooks for multi-agent orchestrationTest plan
🤖 Generated with Claude Code