subagents best practice added
This commit is contained in:
Shayan Rais
@@ -31,8 +31,9 @@ Read ALL of the following:
|
||||
|
||||
| File | What to check |
|
||||
|------|---------------|
|
||||
| `reports/claude-subagents.md` | Frontmatter Fields table, Memory Scopes table, Invocation section, Examples (minimal + full-featured), Scope and Priority table, Claude Agents section, Sources list |
|
||||
| `best-practice/claude-subagents.md` | Frontmatter Fields table, Memory Scopes table, Invocation section, Examples (minimal + full-featured), Scope and Priority table, Claude Agents section, Sources list |
|
||||
| `CLAUDE.md` | Subagent Definition Structure section, Subagent Orchestration section, any agent-related patterns |
|
||||
| `.claude/agents/**/*.md` | Use Glob to discover ALL agent definition files (including nested directories like `.claude/agents/workflows/`). For each agent file, read its YAML frontmatter to extract: name, model, color, tools, disallowedTools, skills, memory. Compare the full list against the "Agents in This Repository" table in the report. |
|
||||
|
||||
---
|
||||
|
||||
@@ -77,6 +78,21 @@ Verify both examples against current field set:
|
||||
### CLAUDE.md Consistency
|
||||
Verify CLAUDE.md's agent-related sections are consistent with the report. Check the Subagent Definition Structure section lists the same fields as the report.
|
||||
|
||||
### Built-in Agent Completeness
|
||||
Compare the "Official Claude Agents" table against the built-in agent types discovered from official docs and changelog. Check for:
|
||||
- Missing built-in agents not listed in the table
|
||||
- Removed/deprecated agents still listed
|
||||
- Incorrect model, tools, or description for existing entries
|
||||
- New built-in agents introduced in recent versions
|
||||
|
||||
### Repository Agent Completeness
|
||||
Compare the "Agents in This Repository" table against the actual agent files discovered from `.claude/agents/**/*.md`. For each agent file found:
|
||||
- Verify it appears in the table
|
||||
- Verify its model, color, tools, skills, and memory columns match the file's frontmatter
|
||||
- Flag any agents in the table that no longer have a corresponding file
|
||||
- Flag any agent files that are missing from the table
|
||||
- Verify each agent's clickable link in the table resolves to the correct file path
|
||||
|
||||
### Sources Accuracy
|
||||
Verify the Sources section links are still valid and point to the correct documentation pages.
|
||||
|
||||
@@ -95,8 +111,10 @@ Return your findings as a structured report with these sections:
|
||||
7. **Invocation Pattern Accuracy** — Syntax and method comparison
|
||||
8. **Scope & Priority Accuracy** — Table comparison results
|
||||
9. **Example Accuracy** — Per-example verification
|
||||
10. **CLAUDE.md Consistency** — Agent-related section accuracy
|
||||
11. **Sources Accuracy** — Link validity
|
||||
10. **Built-in Agent Completeness** — Missing, removed, or inaccurate built-in agent entries
|
||||
11. **Repository Agent Completeness** — Missing, extra, or inaccurate entries in "Agents in This Repository" table vs actual `.claude/agents/**/*.md` files
|
||||
12. **CLAUDE.md Consistency** — Agent-related section accuracy
|
||||
13. **Sources Accuracy** — Link validity
|
||||
|
||||
Be thorough and specific. Include version numbers, file paths, and line references where possible.
|
||||
|
||||
@@ -111,6 +129,8 @@ Be thorough and specific. Include version numbers, file paths, and line referenc
|
||||
5. **Cross-reference field counts** — the report's field count must match official docs
|
||||
6. **Verify BOTH examples** — minimal must be minimal, full-featured must show all fields
|
||||
7. **Do NOT modify any files** — this is read-only research
|
||||
8. **Scan ALL agent files** — use Glob for `.claude/agents/**/*.md` to discover agents in nested directories, not just the top level
|
||||
9. **Cross-reference repo agents** — every `.md` file in `.claude/agents/` must appear in "Agents in This Repository" and vice versa
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -5,7 +5,7 @@ argument-hint: [number of versions to check, default 10]
|
||||
|
||||
# Workflow Changelog — Subagents Report
|
||||
|
||||
You are a coordinator for the claude-code-best-practice project. Your job is to launch two research agents in parallel, wait for their results, merge findings, and present a unified report about drift in the **Subagents Reference** report (`reports/claude-subagents.md`).
|
||||
You are a coordinator for the claude-code-best-practice project. Your job is to launch two research agents in parallel, wait for their results, merge findings, and present a unified report about drift in the **Subagents Reference** report (`best-practice/claude-subagents.md`).
|
||||
|
||||
**Versions to check:** `$ARGUMENTS` (default: 10 if empty or not a number)
|
||||
|
||||
@@ -28,7 +28,7 @@ Spawn using `subagent_type: "workflow-changelog-claude-subagents-agent"`. Give i
|
||||
> 2. CLI Reference: https://code.claude.com/docs/en/cli-reference
|
||||
> 3. Changelog: https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md
|
||||
>
|
||||
> Then read the local report file (`reports/claude-subagents.md`) and the CLAUDE.md file. Analyze differences between what the official docs say about agent frontmatter fields and what our report documents. Return a structured findings report covering missing fields, changed field types, new field additions, deprecated fields, memory scope changes, invocation pattern changes, scope/priority changes, and example accuracy.
|
||||
> Then read the local report file (`best-practice/claude-subagents.md`) and the CLAUDE.md file. Also scan `.claude/agents/**/*.md` using Glob to discover ALL custom agent files (including nested directories) and read each one's frontmatter. Analyze differences between what the official docs say about agent frontmatter fields and what our report documents. Also compare the "Agents in This Repository" table against the actual agent files found. Return a structured findings report covering missing fields, changed field types, new field additions, deprecated fields, memory scope changes, invocation pattern changes, scope/priority changes, example accuracy, built-in agent completeness, and repository agent completeness.
|
||||
|
||||
### Agent 2: claude-code-guide
|
||||
|
||||
@@ -43,6 +43,7 @@ Spawn using `subagent_type: "claude-code-guide"`. Give it this prompt:
|
||||
> 6. New agent features (isolation, background, hooks, mcpServers, skills preloading)
|
||||
> 7. Changes to agent scope/priority resolution order
|
||||
> 8. Any deprecations or removals of agent frontmatter fields
|
||||
> 9. The complete list of all built-in/default agent types (e.g. general-purpose, Explore, Plan, claude-code-guide, statusline-setup) — verify which ones currently exist, their default model, tools, and descriptions
|
||||
>
|
||||
> Be thorough — search the web, fetch docs, and provide concrete version numbers and details for everything you find.
|
||||
|
||||
@@ -52,13 +53,13 @@ Both agents run independently and will return their findings.
|
||||
|
||||
## Phase 0.5: Read Verification Checklist
|
||||
|
||||
**While agents are running**, read `changelog/reports/claude-subagents/verification-checklist.md`. This file contains accumulated verification rules — each rule specifies what to check, at what depth, and against which source. Every rule MUST be executed during Phase 2. The checklist is the project's regression test suite for drift detection.
|
||||
**While agents are running**, read `changelog/best-practice/claude-subagents/verification-checklist.md`. This file contains accumulated verification rules — each rule specifies what to check, at what depth, and against which source. Every rule MUST be executed during Phase 2. The checklist is the project's regression test suite for drift detection.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Read Previous Changelog Entries
|
||||
|
||||
**Before merging findings**, read the file `changelog/reports/claude-subagents/changelog.md` to get the last 25 changelog entries. Each entry is separated by `---`. Parse the priority actions from those previous entries so you can compare them against the current findings. This lets you identify:
|
||||
**Before merging findings**, read the file `changelog/best-practice/claude-subagents/changelog.md` to get the last 25 changelog entries. Each entry is separated by `---`. Parse the priority actions from those previous entries so you can compare them against the current findings. This lets you identify:
|
||||
- **Recurring items** — issues that appeared before and are still unresolved
|
||||
- **Newly resolved items** — issues from previous runs that are now fixed
|
||||
- **New items** — issues that appear for the first time in this run
|
||||
@@ -73,7 +74,7 @@ Both agents run independently and will return their findings.
|
||||
|
||||
Cross-reference the two. The dedicated agent provides report-specific drift analysis, while the claude-code-guide agent may surface things it missed (e.g. very recent changes, undocumented features, or context from web searches). Flag any contradictions between the two for the user to resolve.
|
||||
|
||||
**Execute the verification checklist:** For every rule in `changelog/reports/claude-subagents/verification-checklist.md`, perform the check at the specified depth using the agent findings as source data. Include a **Verification Log** section in the report showing each rule's result:
|
||||
**Execute the verification checklist:** For every rule in `changelog/best-practice/claude-subagents/verification-checklist.md`, perform the check at the specified depth using the agent findings as source data. Include a **Verification Log** section in the report showing each rule's result:
|
||||
|
||||
```
|
||||
Verification Log:
|
||||
@@ -83,7 +84,7 @@ Rule # | Category | Depth | Result | Notes
|
||||
...
|
||||
```
|
||||
|
||||
**Update the checklist if needed:** If a finding reveals a new type of drift that no existing checklist rule covers (or covers at insufficient depth), append a new rule to `changelog/reports/claude-subagents/verification-checklist.md`. The rule must include: category, what to check, depth level, what source to compare against, date added, and the origin (what error prompted this rule). Do NOT add rules for one-off issues that won't recur.
|
||||
**Update the checklist if needed:** If a finding reveals a new type of drift that no existing checklist rule covers (or covers at insufficient depth), append a new rule to `changelog/best-practice/claude-subagents/verification-checklist.md`. The rule must include: category, what to check, depth level, what source to compare against, date added, and the origin (what error prompted this rule). Do NOT add rules for one-off issues that won't recur.
|
||||
|
||||
Also compare the current findings against the previous changelog entries (from Phase 1). For each priority action, mark it as:
|
||||
- `NEW` — first time this issue appears
|
||||
@@ -100,7 +101,9 @@ Produce a structured report with these sections:
|
||||
6. **Scope & Priority Changes** — Updates to resolution order or new scope locations
|
||||
7. **Example Accuracy** — Whether minimal and full-featured examples reflect current field set
|
||||
8. **Field Type/Description Accuracy** — Per-field verification against official docs
|
||||
9. **claude-code-guide Agent Findings** — Unique insights from the agent that weren't captured by the dedicated agent. Only include findings that add new information. If there are contradictions between the two agents, flag them for the user to resolve. Do NOT list "confirmed agreements".
|
||||
9. **Built-in Agent Completeness** — Compare the "Official Claude Agents" table against the built-in agent types available in Claude Code. Flag any new built-in agents missing from the table, or any listed agents that no longer exist. Verify model, tools, and description accuracy for each built-in agent.
|
||||
10. **Repository Agent Completeness** — Compare the "Agents in This Repository" table against the actual agent files in `.claude/agents/**/*.md`. Flag missing agents, extra table entries with no corresponding file, and any column mismatches (model, color, tools, skills, memory) between the table and file frontmatter.
|
||||
11. **claude-code-guide Agent Findings** — Unique insights from the agent that weren't captured by the dedicated agent. Only include findings that add new information. If there are contradictions between the two agents, flag them for the user to resolve. Do NOT list "confirmed agreements".
|
||||
|
||||
End with a prioritized **Action Items** summary table. Each item must include a `Status` column showing `NEW`, `RECURRING (first seen: <date>)`, or `RESOLVED`:
|
||||
|
||||
@@ -124,7 +127,7 @@ Also include a **Resolved Since Last Run** section listing any items from the pr
|
||||
|
||||
**This phase is MANDATORY — always execute it before presenting the report to the user.**
|
||||
|
||||
Read the existing `changelog/reports/claude-subagents/changelog.md` file, then **append** (do NOT overwrite) a new entry at the end. The entry format must be exactly:
|
||||
Read the existing `changelog/best-practice/claude-subagents/changelog.md` file, then **append** (do NOT overwrite) a new entry at the end. The entry format must be exactly:
|
||||
|
||||
```markdown
|
||||
---
|
||||
@@ -147,7 +150,7 @@ The `(reason)` is mandatory and must briefly explain what was done or why.
|
||||
**Rules for appending:**
|
||||
- Always append — never overwrite or replace previous entries
|
||||
- The date and time is when the command is executed in Pakistan Standard Time (PKT, UTC+5); get it by running `TZ=Asia/Karachi date "+%Y-%m-%d %I:%M %p PKT"`. The version comes from agent findings
|
||||
- If `changelog/reports/claude-subagents/changelog.md` doesn't exist or is empty, create it with the Status Legend table (see top of file) then the first entry
|
||||
- If `changelog/best-practice/claude-subagents/changelog.md` doesn't exist or is empty, create it with the Status Legend table (see top of file) then the first entry
|
||||
- Each entry is separated by `---`
|
||||
- **Only include items with HIGH, MEDIUM, or LOW priority** — omit NONE priority items (things that need no action)
|
||||
|
||||
@@ -157,12 +160,37 @@ The `(reason)` is mandatory and must briefly explain what was done or why.
|
||||
|
||||
**This phase is MANDATORY — always execute it immediately after Phase 2.5, before presenting the report.**
|
||||
|
||||
Update the "Last Updated" badge at the top of `reports/claude-subagents.md`. Run `TZ=Asia/Karachi date "+%b %d, %Y %-I:%M %p PKT"` to get the time, URL-encode it (spaces to `%20`, commas to `%2C`), and replace the date portion in the badge. Also update the Claude Code version in the badge if it has changed.
|
||||
Update the "Last Updated" badge at the top of `best-practice/claude-subagents.md`. Run `TZ=Asia/Karachi date "+%b %d, %Y %-I:%M %p PKT"` to get the time, URL-encode it (spaces to `%20`, commas to `%2C`), and replace the date portion in the badge. Also update the Claude Code version in the badge if it has changed.
|
||||
|
||||
**Do NOT log badge updates as action items in the changelog or report.** Badge syncing is a routine part of every run, not a finding.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2.7: Validate All Hyperlinks
|
||||
|
||||
**This phase is MANDATORY — always execute it after Phase 2.6, before presenting the report.**
|
||||
|
||||
Scan `best-practice/claude-subagents.md` for every hyperlink (both markdown `[text](url)` and inline URLs). For each link:
|
||||
|
||||
1. **Local file links** (relative paths like `../.claude/agents/weather.md`, `../claude-agent-memory.md`): Verify the file exists at the resolved path using the Read tool. Flag any broken links.
|
||||
2. **External URLs** (e.g., `https://code.claude.com/docs/en/sub-agents`): Fetch each URL using WebFetch and verify it returns a valid page (not a 404 or redirect to an error page). Flag any dead or moved links.
|
||||
3. **Anchor links** (e.g., `#section-name`): Verify the target heading exists within the same file.
|
||||
|
||||
Include a **Hyperlink Validation Log** in the report:
|
||||
|
||||
```
|
||||
Hyperlink Validation Log:
|
||||
# | Type | Link | Status | Notes
|
||||
1 | Local | ../.claude/agents/weather.md | OK |
|
||||
2 | External | https://code.claude.com/docs/en/sub-agents | OK |
|
||||
3 | Local | ../claude-agent-memory.md | BROKEN | File not found
|
||||
...
|
||||
```
|
||||
|
||||
**If any links are broken**, add them as HIGH priority action items in the report. Broken links degrade the report's usefulness and must be fixed before any other changes.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Offer to Take Action
|
||||
|
||||
After presenting the report (and confirming both changelog and badge were updated), ask the user:
|
||||
@@ -179,6 +207,9 @@ When executing:
|
||||
- **Example updates**: Update both minimal and full-featured examples to reflect current field set
|
||||
- **Invocation changes**: Update the Invocation section
|
||||
- **Scope/priority changes**: Update the Scope and Priority table
|
||||
- **Missing repo agents**: Add to "Agents in This Repository" table with correct model, color, tools, skills, memory columns and a clickable link to the agent file (relative path from `best-practice/` e.g. `../.claude/agents/<name>.md`)
|
||||
- **Extra repo agents**: Remove entries whose agent file no longer exists (confirm with user first)
|
||||
- **Repo agent column mismatches**: Update table columns to match the agent file's current frontmatter
|
||||
- After all actions, re-run verification to confirm consistency
|
||||
|
||||
---
|
||||
@@ -196,3 +227,6 @@ When executing:
|
||||
9. **ALWAYS execute the verification checklist** — read the verification-checklist.md and execute every rule. Include a Verification Log in the report. Append new rules when a new type of drift is discovered.
|
||||
10. **Checklist rules are append-only** — never remove or weaken existing rules. Only add new rules or upgrade depth levels.
|
||||
11. **ALWAYS update the Last Updated badge** — Phase 2.6 is mandatory. Never skip it.
|
||||
12. **ALWAYS validate all hyperlinks** — Phase 2.7 is mandatory. Never skip it. Broken links are HIGH priority.
|
||||
13. **Audit built-in agents** — verify the "Official Claude Agents" table lists all current built-in agent types with correct model, tools, and descriptions.
|
||||
14. **Audit repo agents** — scan `.claude/agents/**/*.md` and verify the "Agents in This Repository" table is a complete, accurate mirror of all custom agent files in the repo.
|
||||
|
||||
Reference in New Issue
Block a user