This directory stores this repo's self-maintained agent definitions (one agent per file, ECC-style architecture: frontmatter name/description/tools/model + input defense baseline / responsibilities / process / output format / criteria or checklist / red flags). It does not depend on the everything-claude-code (ECC) plugin, and is for callers such as design/SKILL.md、update/SKILL.md to reference its definitions when launching the general-purpose subagent. This document is the sole authoritative version of this index and invocation convention; all other documents (README, design/SKILL.md, update/SKILL.md) only keep a one-line pointer to it and do not duplicate its content.
Step 1 — Problem: Choose a Definition File
Before dispatching a subagent, the caller first selects the corresponding definition file from the table below based on task type:
| Definition File | Purpose | When to Use | Referenced By |
|---|---|---|---|
complexity-triage.md |
Task complexity triage (low/medium/multi-session) | Before entering the full planning ritual, first roughly estimate the scope of impact to decide whether to take the fast path or the full process | /design Step 2a |
doc-reviewer.md |
Plan/document review, item-by-item PASS/FAIL fault-finding | After the Plan agent produces a plan, or after document updates are complete, when an isolated context is needed for fault-finding rather than endorsement | /design Step 4a、/update Step 2 |
doc-updater.md |
Document sync (README/docs/CODEMAPS), output a Change Manifest | After code changes require document sync, and the main model needs to verify item by item afterward | /update Step 1 |
tdd-guide.md |
TDD red-green-refactor guidance, 80% coverage threshold | Before a new feature or bug fix, test coverage is lacking and a failing test must be written before implementation | /design Listed in Step 1 resource inventory, referenced in Step 3 plan steps as needed |
Common signs of choosing the wrong definition file: mistaking "review" for "update" (doc-reviewer only reads and does not write, only doc-updater Edits files), mistaking "triage" for "review" (complexity-triage only does a rough impact estimate and does not do item-by-item PASS/FAIL).
Step 2 — Solution: Invocation Convention
Always via general-purpose + an explicit prompt referencing the definition file content for execution, do not directly call the definition file's name as subagent_type：
Agent(subagent_type="general-purpose", model="sonnet") # model 取自定義檔 frontmatter（doc-reviewer/doc-updater/tdd-guide=sonnet、complexity-triage=haiku）
The prompt must include: "Execute <task> according to the definition and checklist in agents/.md" + the context passed in by the caller. For example, when reviewing a plan: "Execute review according to the definition and checklist in agents/doc-reviewer.md" + the complete plan content produced in Step 3.
Name collision prohibition: direct calls such as Agent(subagent_type="tdd-guide")、Agent(subagent_type="doc-updater") are prohibited. In the environment there exist legacy ECC agent types with the same names (tdd-guide、doc-updater are all agent names that the ECC plugin once registered); a direct call will silently load the old ECC definitions rather than the definitions in this directory, and there will be no error or warning prompt of any kind—this is the point most easily bypassed after this directory is decoupled from ECC, and the caller must explicitly use general-purpose + definition reference, and must not switch to subagent_type=<name>。
Step 3 — When to Use: Acceptance
After the subagent reports completion, the caller (main model) checks the report item by item against the definition file's "Output Format" section to see whether it conforms to the contract (for example: whether doc-reviewer's report is an item-by-item PASS/FAIL table rather than a summary-style impression score).
- Additional requirement for doc-updater: The reported "Change Manifest" must not be directly trusted; the main model must personally
git diffCheck each claimed change item by item—this type of agent has a track record of fabricating modification records, seeagents/doc-updater.mdred flag section - doc-reviewer / complexity-triage: The report itself is the review/triage result; the main model's acceptance work is to verify "whether PASS/FAIL or a fixed JSON format was given for each item," rather than reviewing it again.
Context — path resolution
When the caller references agents/*.md , the actual path varies by execution environment:
repo checkout： agents/<name>.md
skills CLI 安裝環境： ~/.agents/skills/agents/<name>.md
When the corresponding file cannot be found, treat it as "theagents/ directory does not exist (incomplete installation)": obtain it from https://github.com/ashe-li/agent-skills 's agents/<name>.md , or ask the user to rerun npx skills update；/design Step 4a and other fallbacks in the caller documentation all point back to this section rather than being repeated separately.