---

description: Update the README CONCEPTS section with the latest Claude Code features and concepts argument-hint: [number of changelog versions to check, default 10]

Workflow Changelog — README Concepts

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 README CONCEPTS section (README.md).

Versions to check: $ARGUMENTS (default: 10 if empty or not a number)

This is a read-then-report workflow. Launch agents, merge results, and produce a report. Only take action if the user approves.

---

Phase 0: Launch Both Agents in Parallel

Immediately spawn both agents using the Task tool in the same message (parallel launch):

Agent 1: workflow-concepts-agent

Spawn using subagent_type: "workflow-concepts-agent". Give it this prompt:

Research the claude-code-best-practice project for README CONCEPTS section drift. Check the last $ARGUMENTS versions (default: 10).

Fetch these 3 external sources:

1. Claude Code Docs Index: https://code.claude.com/docs/en
2. Claude Code Changelog: https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md
3. Claude Code Features Overview: https://code.claude.com/docs/en/overview

Then read the local README.md (specifically the CONCEPTS table), CLAUDE.md, and reports/claude-global-vs-project-settings.md. Analyze differences between what the official docs list as Claude Code concepts/features and what our README CONCEPTS table documents. Return a structured findings report covering missing concepts, changed concepts, deprecated concepts, URL accuracy, description accuracy, and badge accuracy.

Agent 2: claude-code-guide

Spawn using subagent_type: "claude-code-guide". Give it this prompt:

Research the latest Claude Code features and concepts. I need you to find the COMPLETE list of all Claude Code concepts/features that should be documented. For each, provide:

1. Official feature name
2. Official docs URL
3. File system location (e.g., .claude/commands/, ~/.claude/teams/)
4. Brief description (one line)
5. When it was introduced (version/date if known)

Specifically check for these potentially missing concepts:

• Worktrees — git worktree isolation for parallel development
• Agent Teams — multi-agent coordination
• Tasks — persistent task lists across sessions
• Auto Memory — Claude's self-written project learnings
• Keybindings — custom keyboard shortcuts
• Remote Connections — SSH, Docker, cloud development
• IDE Integration — VS Code, JetBrains extensions
• Model Configuration — model selection and routing
• GitHub Integration — PR reviews, issue triage
• Any other concept from recent Claude Code versions

Be thorough — search the web, fetch docs, and provide concrete version numbers and details for everything you find.

Both agents run independently and will return their findings.

---

Phase 0.5: Read Verification Checklist

While agents are running, read changelog/best-practice/concepts/verification-checklist.md if it exists. This file contains accumulated verification rules. If it does not exist yet, skip this step — it will be created in Phase 2.

---

Phase 1: Read Previous Changelog Entries

Before merging findings, read the file changelog/best-practice/concepts/changelog.md if it exists to get previous 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

If the file doesn't exist yet, all items are NEW.

---

Phase 2: Merge Findings & Generate Report

Wait for both agents to complete. Once you have:

• workflow-concepts-agent findings — detailed analysis with local file reads, external doc fetches, and drift detection
• claude-code-guide findings — independent research on latest Claude Code features and concepts

Cross-reference the two. The dedicated agent provides CONCEPTS-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 (if it exists): For every rule in changelog/best-practice/concepts/verification-checklist.md, perform the check. Include a Verification Log section in the report.

Update the checklist if needed: If a finding reveals a new type of drift that no existing checklist rule covers, append a new rule to changelog/best-practice/concepts/verification-checklist.md. If the file doesn't exist, create it. The rule must include: category, what to check, depth level, what source to compare against, date added, and the origin.

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
• RECURRING — appeared in a previous run and is still unresolved (include which run date it first appeared)
• RESOLVED — appeared in a previous run but is now fixed (include resolution date)

Produce a structured report with these sections:

1. Missing Concepts — Features/concepts in official docs but missing from CONCEPTS table, with:
   • Official name and docs URL
   • Recommended Location column value
   • Recommended Description column value — badges and supplementary links only; no prose descriptions (the Description column is conventionally a links column, not a feature summary)
   • Exact markdown table row ready to paste
   • Version introduced (if known)
2. Changed Concepts — Concepts whose name, URL, location, or description has changed
3. Deprecated/Removed Concepts — Concepts in CONCEPTS table but no longer in official docs
4. URL Accuracy — Per-concept URL verification
5. Description Accuracy — Per-concept description/location verification
6. Badge Accuracy — Badge link verification and missing badge recommendations
7. 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. Flag contradictions.

End with a prioritized Action Items summary table:

Priority Actions:
#  | Type                | Action                                     | Status
1  | Missing Concept     | Add <concept> row to CONCEPTS table         | NEW
2  | Changed URL         | Update <concept> docs link                  | NEW
3  | Changed Description | Update <concept> description                | RECURRING (first seen: <date>)
4  | Deprecated Concept  | Remove <concept> row from CONCEPTS table    | NEW
5  | Broken Badge        | Fix badge link for <concept>                | NEW

Also include a Resolved Since Last Run section listing any items from the previous run that are no longer issues.

---

Phase 2.5: Append Summary to Changelog

This phase is MANDATORY — always execute it before presenting the report to the user.

Read the existing changelog/best-practice/concepts/changelog.md file, then append (do NOT overwrite) a new entry at the end. If the file doesn't exist, create it with a Status Legend table then the first entry. The entry format must be exactly:

---

## [<YYYY-MM-DD HH:MM AM/PM PKT>] Claude Code v<VERSION>

| # | Priority | Type | Action | Status |
|---|----------|------|--------|--------|
| 1 | HIGH/MED/LOW | <type> | <action description> | <status> |
| ... | ... | ... | ... | ... |

Status format — MUST use one of these three formats:

• COMPLETE (reason) — action was taken and resolved successfully
• INVALID (reason) — finding was incorrect, not applicable, or intentional
• ON HOLD (reason) — action deferred, waiting on external dependency or user decision

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
• Each entry is separated by ---
• Only include items with HIGH, MEDIUM, or LOW priority — omit NONE priority items

---

Phase 2.6: Update Last Updated Badge

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 README.md (line 3). 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.

Do NOT log badge updates as action items in the changelog or report.

---

Phase 2.7: Validate All CONCEPTS URLs

This phase is MANDATORY — always execute it after Phase 2.6, before presenting the report.

For each concept in the CONCEPTS table:

1. External docs URLs (e.g., https://code.claude.com/docs/en/skills): Fetch each URL using WebFetch and verify it returns a valid page. Flag any dead or moved links.
2. Local badge links (e.g., best-practice/claude-commands.md): Verify the file exists using the Read tool. Flag any broken links.
3. Implementation badge links (e.g., .claude/commands/): Verify the path exists.

Include a URL Validation Log in the report:

URL Validation Log:
#  | Concept     | URL Type  | URL                                           | Status | Notes
1  | Commands    | External  | https://code.claude.com/docs/en/skills         | OK     |
2  | Commands    | Badge     | best-practice/claude-commands.md               | OK     |
3  | Sub-Agents  | External  | https://code.claude.com/docs/en/sub-agents     | OK     |
...

If any URLs are broken, add them as HIGH priority action items.

---

Phase 3: Offer to Take Action

After presenting the report (and confirming changelog was updated), ask the user:

1. Execute all actions — Add missing concepts, update changed ones, remove deprecated ones
2. Execute specific actions — User picks which numbers to execute
3. Just save the report — No changes

When executing:

• Missing concepts: Add a new row to the CONCEPTS table in README.md following the existing format:

  | [**Name**](docs-url) | `location` | [![Best Practice](!/tags/best-practice.svg)](...) [![Implemented](!/tags/implemented.svg)](...) [Supplementary Link](...) |
  

  The third column is badges and links only — never prose. Add badges (best-practice, implemented) only if corresponding files exist. If no badges or links apply, leave the column empty (just | |).
• Changed concepts: Update the specific column(s) that changed
• Deprecated concepts: Confirm with user before removing rows
• Broken URLs: Fix the URL to the current valid one
• Badge fixes: Update badge links to correct file paths
• Maintain alphabetical or logical ordering consistent with the existing table
• After all actions, re-verify the CONCEPTS table for consistency

---

Critical Rules

1. Launch BOTH agents in parallel in a single message — never sequentially
2. Wait for both agents before generating the report
3. Never guess versions, URLs, or dates — use data from the agents
4. Missing concepts are HIGH PRIORITY — the CONCEPTS table is the first thing developers see
5. Verify every URL — broken links degrade trust in the entire project
6. Don't auto-execute — always present the report first
7. *ALWAYS append to changelog