workflow-concepts

# 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