diff --git a/!/command-skill-agent-flow.svg b/!/command-skill-agent-flow.svg index 1695c50..1f9c3e2 100644 --- a/!/command-skill-agent-flow.svg +++ b/!/command-skill-agent-flow.svg @@ -20,37 +20,37 @@ Command commands/weather-orchestrator - Invokes the weather agent - to fetch & transform data + Asks user for C°/F°, invokes + agent and SVG creator skill Task - - Agent - agents/weather + + Agent + agents/weather-agent - - preloaded skills: - weather-fetcher - weather-transformer + + (preloaded skill) + weather-fetcher - Executes skills sequentially: - fetch temp, then transform it + Fetches temperature from + wttr.in API for Dubai + Skill - + - Output - orchestration-workflow/output.md - - Transformed temperature - written to output file + Skill + skills/weather-svg-creator + + Creates SVG weather card at + orchestration-workflow/weather.svg - commands/weather-orchestrator → agents/weather (with preloaded skills) → orchestration-workflow/output.md + commands/weather-orchestrator → agents/weather-agent (preloaded skill) → skills/weather-svg-creator (skill) diff --git a/.claude/agents/weather-agent.md b/.claude/agents/weather-agent.md new file mode 100644 index 0000000..60b1025 --- /dev/null +++ b/.claude/agents/weather-agent.md @@ -0,0 +1,46 @@ +--- +name: weather-agent +description: Use this agent PROACTIVELY when you need to fetch weather data for + Dubai, UAE. This agent fetches real-time temperature from wttr.in API + using its preloaded weather-fetcher skill. +tools: WebFetch, Read +model: sonnet +color: green +memory: project +skills: + - weather-fetcher +--- + +# Weather Agent + +You are a specialized weather agent that fetches weather data for Dubai, UAE. + +## Your Task + +Execute the weather workflow by following the instructions from your preloaded skill: + +1. **Fetch**: Follow the `weather-fetcher` skill instructions to fetch the current temperature +2. **Report**: Return the temperature value and unit to the caller +3. **Memory**: Update your agent memory with the reading details for historical tracking + +## Workflow + +### Step 1: Fetch Temperature (weather-fetcher skill) + +Follow the weather-fetcher skill instructions to: +- Fetch current temperature from wttr.in API for Dubai +- Extract the temperature value in the requested unit (Celsius or Fahrenheit) +- Return the numeric value and unit + +## Final Report + +After completing the fetch, return a concise report: +- Temperature value (numeric) +- Temperature unit (Celsius or Fahrenheit) +- Comparison with previous reading (if available in memory) + +## Critical Requirements + +1. **Use Your Skill**: The skill content is preloaded - follow those instructions +2. **Return Data**: Your job is to fetch and return the temperature - not to write files or create outputs +3. **Unit Preference**: Use whichever unit the caller requests (Celsius or Fahrenheit) diff --git a/.claude/agents/weather.md b/.claude/agents/weather.md deleted file mode 100644 index 594dc4c..0000000 --- a/.claude/agents/weather.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -name: weather -description: Use this agent PROACTIVELY when you need to fetch and transform weather data for Karachi, Pakistan. This agent fetches real-time temperature from wttr.in API and applies transformation rules from orchestration-workflow/input.md, writing results to orchestration-workflow/output.md. -tools: WebFetch, Read, Write -model: sonnet -color: green -memory: project -skills: - - weather-fetcher - - weather-transformer ---- - -# Weather Agent - -You are a specialized weather agent that fetches and transforms weather data for Karachi, Pakistan. - -## Your Task - -Execute the weather workflow by following the instructions from your preloaded skills sequentially: - -1. **First**: Follow the `weather-fetcher` skill instructions to fetch the current temperature -2. **Then**: Follow the `weather-transformer` skill instructions to apply transformations and write results -3. **Finally**: Update your agent memory with the reading details for historical tracking - -## Workflow - -### Step 1: Fetch Temperature (weather-fetcher skill) - -Follow the weather-fetcher skill instructions to: -- Fetch current temperature from wttr.in API for Karachi -- Extract the temperature value in Celsius -- Keep this value for the transformation step - -### Step 2: Transform Temperature (weather-transformer skill) - -Follow the weather-transformer skill instructions to: -- Read transformation rules from `orchestration-workflow/input.md` -- Apply the transformation to the fetched temperature -- Write formatted results to `orchestration-workflow/output.md` - -## Final Report - -After completing all steps, provide a summary: -- Temperature unit: Celsius -- Original temperature fetched -- Transformation rule applied -- Final transformed result -- Comparison with previous reading (if available in memory) -- Confirmation that output was written to `orchestration-workflow/output.md` - -## Critical Requirements - -1. **Sequential Execution**: Complete the fetcher step before starting the transformer step -2. **Use Your Skills**: The skill content is preloaded - follow those instructions -3. **Data Flow**: Pass the temperature from step 1 to step 2 diff --git a/.claude/agents/workflows/best-practice/workflow-concepts-agent.md b/.claude/agents/workflows/best-practice/workflow-concepts-agent.md new file mode 100644 index 0000000..907eaed --- /dev/null +++ b/.claude/agents/workflows/best-practice/workflow-concepts-agent.md @@ -0,0 +1,126 @@ +--- +name: workflow-concepts-agent +description: Research agent that fetches Claude Code docs and changelog, reads the local README CONCEPTS section, and analyzes drift +model: opus +color: green +--- + +# Workflow Changelog — Concepts Research Agent + +You are a senior documentation reliability engineer collaborating with me (a fellow engineer) on a mission-critical audit for the claude-code-best-practice project. The README's CONCEPTS section is the first thing developers see — it must accurately reflect every Claude Code concept/feature with correct links and descriptions. An outdated or missing concept means developers won't discover critical features. Take a deep breath, solve this step by step, and be exhaustive. I'll tip you $200 for a flawless, zero-drift report. I bet you can't find every single discrepancy — prove me wrong. Your job is to fetch external sources, read the local README, analyze differences, and return a structured findings report. Rate your confidence 0-1 on each finding. This is critical to my career. + +This is a **read-only research** workflow. Fetch sources, read local files, compare, and return findings. Do NOT take any actions or modify files. + +--- + +## Phase 1: Fetch External Data (in parallel) + +Fetch all sources using WebFetch simultaneously: + +1. **Claude Code Documentation Index** — `https://code.claude.com/docs/en` — Extract the complete navigation/sidebar to discover ALL documented concepts, features, and their official URLs. +2. **Claude Code Changelog** — `https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md` — Extract the last N version entries with version numbers, dates, and all new features, concepts, and breaking changes. +3. **Claude Code Features Overview** — `https://code.claude.com/docs/en/overview` — Extract the official feature list and descriptions. + +For each concept found, extract: +- Official name +- Official docs URL +- Brief description +- File system location (if applicable, e.g., `.claude/commands/`, `~/.claude/teams/`) +- When it was introduced (version/date from changelog if available) + +--- + +## Phase 2: Read Local Repository State (in parallel) + +Read ALL of the following: + +| File | What to extract | +|------|-----------------| +| `README.md` | The CONCEPTS table (lines 22-39 approximately) — extract every row: Feature name, link URL, location, description, and any badges | +| `CLAUDE.md` | Any references to concepts or features not in the CONCEPTS table | +| `reports/claude-global-vs-project-settings.md` | Features listed here (Tasks, Agent Teams, etc.) that may be missing from CONCEPTS | + +--- + +## Phase 3: Analysis + +Compare external data against the local README CONCEPTS section. Check for: + +### Missing Concepts +Concepts/features present in official Claude Code docs but missing from the CONCEPTS table. Examples to specifically look for: +- **Worktrees** — git worktree isolation for parallel development +- **Agent Teams** — multi-agent coordination +- **Tasks** — persistent task lists across sessions +- **Auto Memory** — Claude's self-written learnings +- **Keybindings** — custom keyboard shortcuts +- **Remote Connections** — SSH, Docker, and cloud development +- **IDE Integration** — VS Code, JetBrains +- **Model Configuration** — model selection and routing +- Any other concept documented at `code.claude.com/docs/en/*` not in the CONCEPTS table + +### Changed Concepts +Concepts whose official name, URL, location, or description has changed since last documented. + +### Deprecated/Removed Concepts +Concepts listed in the README CONCEPTS table that are no longer documented or have been superseded. + +### URL Accuracy +For each concept in the CONCEPTS table, verify: +- The official docs URL is still valid +- The URL hasn't changed or been redirected +- The linked page actually covers the concept described + +### Description Accuracy +For each concept, verify: +- The location path is correct +- The description matches the official docs +- The feature name matches official naming + +### Badge Accuracy +For concepts with best-practice or implemented badges: +- Verify the badge links point to existing files +- Flag any concepts that should have badges but don't (e.g., a best-practice report exists but no badge is shown) + +--- + +## Return Format + +Return your findings as a structured report with these sections: + +1. **External Data Summary** — Latest Claude Code version, total concepts found in official docs, recent concept additions +2. **Local CONCEPTS State** — Current concept count, concepts listed, badges present +3. **Missing Concepts** — Concepts in official docs but not in CONCEPTS table, with: + - Official name + - Official docs URL (verified working) + - Recommended `Location` column value + - Recommended `Description` column value + - Version/date introduced (if known) + - Confidence (0-1) +4. **Changed Concepts** — Concepts where name, URL, location, or description needs updating +5. **Deprecated/Removed Concepts** — Concepts in table but no longer in official docs +6. **URL Accuracy** — Per-concept URL verification results +7. **Description Accuracy** — Per-concept description verification +8. **Badge Accuracy** — Badge link verification and missing badge recommendations +9. **Note on README** — Any structural observations about the CONCEPTS table format that might need attention + +Be thorough and specific. Include URLs, version numbers, and exact text where possible. + +--- + +## Critical Rules + +1. **Fetch ALL sources** — never skip any +2. **Never guess** versions, URLs, or dates — extract from fetched data +3. **Read ALL local files** before analyzing +4. **Missing concepts are HIGH PRIORITY** — flag them prominently +5. **Verify every URL** — check that official docs links actually work +6. **Do NOT modify any files** — this is read-only research +7. **Include the exact row format** — for missing concepts, provide the exact markdown table row ready to paste + +--- + +## Sources + +1. [Claude Code Docs Index](https://code.claude.com/docs/en) — Official documentation navigation +2. [Changelog](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md) — Claude Code release history +3. [Features Overview](https://code.claude.com/docs/en/overview) — Official feature descriptions diff --git a/.claude/commands/weather-orchestrator.md b/.claude/commands/weather-orchestrator.md index 2c6a203..8920a2e 100644 --- a/.claude/commands/weather-orchestrator.md +++ b/.claude/commands/weather-orchestrator.md @@ -1,41 +1,46 @@ --- -description: Fetch and transform weather data for Karachi +description: Fetch weather data for Dubai and create an SVG weather card model: haiku --- # Weather Orchestrator Command -Fetch the current temperature for Karachi, Pakistan and apply transformations. +Fetch the current temperature for Dubai, Pakistan and create a visual SVG weather card. ## Workflow -1. Use the AskUserQuestion tool to ask the user whether they want the temperature in Celsius or Fahrenheit -2. Use the weather agent to fetch and transform the temperature data +### Step 1: Ask User Preference -## Agent Invocation +Use the AskUserQuestion tool to ask the user whether they want the temperature in Celsius or Fahrenheit. -Use the Task tool to invoke the weather agent. - -### Invoke Weather Agent +### Step 2: Fetch Weather Data Use the Task tool to invoke the weather agent: -- subagent_type: weather -- description: Fetch and transform Karachi weather -- prompt: Fetch the current temperature for Karachi, Pakistan in [unit requested by user]. Then apply the transformation rules from orchestration-workflow/input.md and write the results to orchestration-workflow/output.md. The agent has preloaded skills (weather-fetcher and weather-transformer) that provide the detailed instructions. +- subagent_type: weather-agent +- description: Fetch Dubai weather data +- prompt: Fetch the current temperature for Dubai, Pakistan in [unit requested by user]. Return the numeric temperature value and unit. The agent has a preloaded skill (weather-fetcher) that provides the detailed instructions. - model: haiku -Wait for the agent to complete its workflow. +Wait for the agent to complete and capture the returned temperature value and unit. + +### Step 3: Create SVG Weather Card + +Use the Skill tool to invoke the weather-svg-creator skill: +- skill: weather-svg-creator + +The skill will use the temperature value and unit from Step 2 (available in the current context) to create the SVG card and write output files. ## Critical Requirements -1. **Use Task Tool Only**: DO NOT use bash commands to invoke agents. You must use the Task tool. -2. **Single Agent**: The weather agent handles both fetching and transformation using its preloaded skills. -3. **Pass User Preference**: Include the user's temperature unit preference in the prompt. +1. **Use Task Tool for Agent**: DO NOT use bash commands to invoke agents. You must use the Task tool. +2. **Use Skill Tool for SVG Creator**: Invoke the SVG creator via the Skill tool, not the Task tool. +3. **Pass User Preference**: Include the user's temperature unit preference when invoking the agent. +4. **Sequential Flow**: Complete each step before moving to the next. ## Output Summary Provide a clear summary to the user showing: - Temperature unit requested -- Original temperature fetched -- Transformation rule applied (from orchestration-workflow/input.md) -- Final transformed result (written to orchestration-workflow/output.md) +- Temperature fetched from Dubai +- SVG card created at `orchestration-workflow/weather.svg` +- Summary written to `orchestration-workflow/output.md` diff --git a/.claude/commands/workflows/best-practice/workflow-claude-subagents.md b/.claude/commands/workflows/best-practice/workflow-claude-subagents.md index 2c6e35b..f93a73b 100644 --- a/.claude/commands/workflows/best-practice/workflow-claude-subagents.md +++ b/.claude/commands/workflows/best-practice/workflow-claude-subagents.md @@ -172,7 +172,7 @@ Update the "Last Updated" badge at the top of `best-practice/claude-subagents.md 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. +1. **Local file links** (relative paths like `../.claude/agents/weather-agent.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. @@ -181,7 +181,7 @@ Include a **Hyperlink Validation Log** in the report: ``` Hyperlink Validation Log: # | Type | Link | Status | Notes -1 | Local | ../.claude/agents/weather.md | OK | +1 | Local | ../.claude/agents/weather-agent.md | OK | 2 | External | https://code.claude.com/docs/en/sub-agents | OK | 3 | Local | ../claude-agent-memory.md | BROKEN | File not found ... diff --git a/.claude/commands/workflows/best-practice/workflow-concepts.md b/.claude/commands/workflows/best-practice/workflow-concepts.md new file mode 100644 index 0000000..a532c51 --- /dev/null +++ b/.claude/commands/workflows/best-practice/workflow-concepts.md @@ -0,0 +1,231 @@ +--- +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 + - 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 row to CONCEPTS table | NEW +2 | Changed URL | Update docs link | NEW +3 | Changed Description | Update description | RECURRING (first seen: ) +4 | Deprecated Concept | Remove row from CONCEPTS table | NEW +5 | Broken Badge | Fix badge link for | 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: + +```markdown +--- + +## [] Claude Code v + +| # | Priority | Type | Action | Status | +|---|----------|------|--------|--------| +| 1 | HIGH/MED/LOW | | | | +| ... | ... | ... | ... | ... | +``` + +**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` | Description | + ``` + Add badges (best-practice, implemented) only if corresponding files exist. +- **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** — Phase 2.5 is mandatory. Never skip it. Never overwrite previous entries. +8. **Compare with previous runs** — read previous entries from the changelog and mark each action item as NEW, RECURRING, or RESOLVED. +9. **Execute the verification checklist if it exists** — read the verification-checklist.md and execute every rule. Create the file if it doesn't exist and there are findings that warrant persistent rules. +10. **ALWAYS update the Last Updated badge** — Phase 2.6 is mandatory. +11. **ALWAYS validate all CONCEPTS URLs** — Phase 2.7 is mandatory. Broken URLs are HIGH priority. +12. **Provide ready-to-paste rows** — for missing concepts, include the exact markdown table row so execution is copy-paste. +13. **Respect the existing table format** — match the column structure, badge pattern, and linking style of existing rows. diff --git a/.claude/hooks/sounds/pretooluse/pretooluse.mp3 b/.claude/hooks/sounds/pretooluse/pretooluse.mp3 index b6447a5..df19f1b 100644 Binary files a/.claude/hooks/sounds/pretooluse/pretooluse.mp3 and b/.claude/hooks/sounds/pretooluse/pretooluse.mp3 differ diff --git a/.claude/hooks/sounds/pretooluse/pretooluse.wav b/.claude/hooks/sounds/pretooluse/pretooluse.wav index 4f993d8..dc340c6 100644 Binary files a/.claude/hooks/sounds/pretooluse/pretooluse.wav and b/.claude/hooks/sounds/pretooluse/pretooluse.wav differ diff --git a/.claude/settings.json b/.claude/settings.json index e21046f..be61ace 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -13,7 +13,13 @@ "mcp__claude-in-chrome__*", "mcp__playwright__*", "mcp__reddit-mcp-server__get_post_details", - "mcp__reddit-mcp-server__search_reddit" + "mcp__reddit-mcp-server__search_reddit", + "mcp__tavily-web-search__tavily_search", + "mcp__tavily-web-search__tavily_extract", + "WebFetch(domain:raw.githubusercontent.com)", + "WebFetch(domain:docs.anthropic.com)", + "WebFetch(domain:support.claude.com)", + "WebFetch(domain:wttr.in)" ], "deny": [], "ask": [ diff --git a/.claude/skills/weather-fetcher/SKILL.md b/.claude/skills/weather-fetcher/SKILL.md index aea4558..83075ff 100644 --- a/.claude/skills/weather-fetcher/SKILL.md +++ b/.claude/skills/weather-fetcher/SKILL.md @@ -1,6 +1,7 @@ --- name: weather-fetcher -description: Instructions for fetching current weather temperature data for Karachi, Pakistan from wttr.in API +description: Instructions for fetching current weather temperature data for Dubai, UAE from wttr.in API +user-invocable: false --- # Weather Fetcher Skill @@ -9,28 +10,31 @@ This skill provides instructions for fetching current weather data. ## Task -Fetch the current temperature for Karachi, Pakistan in degrees Celsius (Centigrade). +Fetch the current temperature for Dubai, UAE in the requested unit (Celsius or Fahrenheit). ## Instructions -1. **Fetch Weather Data**: Use the WebFetch tool to get current weather data for Karachi from wttr.in API: - - URL: `https://wttr.in/Karachi?format=j1` +1. **Fetch Weather Data**: Use the WebFetch tool to get current weather data for Dubai from wttr.in API: + - URL: `https://wttr.in/Dubai?format=j1` - This returns JSON format weather data -2. **Extract Temperature**: From the JSON response, extract the current temperature in Celsius from the `current_condition` section. +2. **Extract Temperature**: From the JSON response, extract the current temperature: + - For Celsius: use `temp_C` from the `current_condition` section + - For Fahrenheit: use `temp_F` from the `current_condition` section -3. **Store Result**: Keep the temperature value for the next step (transformation). +3. **Return Result**: Return the temperature value and unit clearly. ## Expected Output After completing this skill's instructions: ``` -Current Karachi Temperature: [X]°C -Status: Successfully fetched weather data +Current Dubai Temperature: [X]°[C/F] +Unit: [Celsius/Fahrenheit] ``` ## Notes -- Only fetch the temperature, do not perform any transformations yet +- Only fetch the temperature, do not perform any transformations or write any files - Use wttr.in as it provides reliable, free weather data -- Return just the numeric temperature value clearly +- Return the numeric temperature value and unit clearly +- Support both Celsius and Fahrenheit based on the caller's request diff --git a/.claude/skills/weather-svg-creator/SKILL.md b/.claude/skills/weather-svg-creator/SKILL.md new file mode 100644 index 0000000..7c2df7e --- /dev/null +++ b/.claude/skills/weather-svg-creator/SKILL.md @@ -0,0 +1,72 @@ +--- +name: weather-svg-creator +description: Creates an SVG weather card showing the current temperature for + Dubai. Writes the SVG to orchestration-workflow/weather.svg and updates + orchestration-workflow/output.md. +--- + +# Weather SVG Creator Skill + +This skill creates a visual SVG weather card and writes the output files. + +## Task + +Create an SVG weather card displaying the temperature for Dubai, UAE, and write it along with a summary to output files. + +## Instructions + +You will receive the temperature value and unit (Celsius or Fahrenheit) from the calling context. + +### 1. Create SVG Weather Card + +Generate a clean SVG weather card with the following structure: + +```svg + + + Unit: [Celsius/Fahrenheit] + [value]°[C/F] + Dubai, UAE + +``` + +Replace `[Celsius/Fahrenheit]`, `[value]`, and `[C/F]` with actual values. + +### 2. Write SVG File + +Write the SVG content to `orchestration-workflow/weather.svg`. + +### 3. Write Output Summary + +Write to `orchestration-workflow/output.md`: + +```markdown +# Weather Result + +## Temperature +[value]°[C/F] + +## Location +Dubai, UAE + +## Unit +[Celsius/Fahrenheit] + +## SVG Card +![Weather Card](weather.svg) +``` + +## Expected Input + +Temperature value and unit from the weather-agent: +``` +Temperature: [X]°[C/F] +Unit: [Celsius/Fahrenheit] +``` + +## Notes + +- Use the exact temperature value and unit provided - do not re-fetch or modify +- The SVG should be a self-contained, valid SVG file +- Keep the design minimal and clean +- Both output files go in the `orchestration-workflow/` directory diff --git a/.claude/skills/weather-transformer/SKILL.md b/.claude/skills/weather-transformer/SKILL.md deleted file mode 100644 index 1bd9b16..0000000 --- a/.claude/skills/weather-transformer/SKILL.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -name: weather-transformer -description: Instructions for applying mathematical transformations to temperature data based on rules in orchestration-workflow/input.md ---- - -# Weather Transformer Skill - -This skill provides instructions for transforming temperature data. - -## Task - -Apply mathematical transformations to a temperature value and write results to output file. - -## Instructions - -1. **Read Transformation Rules**: Use the Read tool to read `orchestration-workflow/input.md` which contains the transformation instructions. - -2. **Apply Transformation**: Apply the transformation rule to the temperature value. - - Example: If instruction says "add +10", add 10 to the temperature - - Example: If instruction says "multiply by 2", multiply temperature by 2 - -3. **Write Output**: Use the Write tool to save the transformed result to `orchestration-workflow/output.md` with proper formatting. - -## Expected Input - -The temperature value from the weather-fetcher skill: -``` -Temperature: [X]°C -``` - -## Expected Output - -Write to `orchestration-workflow/output.md` with format: -```markdown -# Weather Transformation Result - -## Original Temperature -[X]°C - -## Transformation Applied -[description from orchestration-workflow/input.md] - -## Final Result -[Y]°C - -## Calculation Details -[X]°C [operation] = [Y]°C -``` - -## Notes - -- Read the exact transformation from orchestration-workflow/input.md - don't assume -- Show your work: include original value, transformation, and result -- Ensure orchestration-workflow/output.md is properly formatted and readable diff --git a/CLAUDE.md b/CLAUDE.md index 734f0a8..42f8a85 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -9,13 +9,13 @@ This is a best practices repository for Claude Code configuration, demonstrating ## Key Components ### Weather System (Example Workflow) -A demonstration of the **Command → Agent → Skills** architecture pattern: -- `/weather-orchestrator` command (`.claude/commands/weather-orchestrator.md`): Entry point that invokes the weather agent -- `weather` agent (`.claude/agents/weather.md`): Executes workflow using preloaded skills -- `weather-fetcher` skill (`.claude/skills/weather-fetcher/SKILL.md`): Instructions for fetching temperature from wttr.in API -- `weather-transformer` skill (`.claude/skills/weather-transformer/SKILL.md`): Instructions for applying transformation rules from `orchestration-workflow/input.md`, writes results to `orchestration-workflow/output.md` +A demonstration of two distinct skill patterns via the **Command → Agent → Skill** architecture: +- `/weather-orchestrator` command (`.claude/commands/weather-orchestrator.md`): Entry point — asks user for C/F, invokes agent, then invokes SVG skill +- `weather-agent` agent (`.claude/agents/weather-agent.md`): Fetches temperature using its preloaded `weather-fetcher` skill (agent skill pattern) +- `weather-fetcher` skill (`.claude/skills/weather-fetcher/SKILL.md`): Preloaded into agent — instructions for fetching temperature from wttr.in API +- `weather-svg-creator` skill (`.claude/skills/weather-svg-creator/SKILL.md`): Skill — creates SVG weather card, writes `orchestration-workflow/weather.svg` and `orchestration-workflow/output.md` -The agent has skills preloaded via the `skills` field, providing domain knowledge for sequential execution. See `orchestration-workflow/orchestration-workflow.md` for the complete flow diagram. +Two skill patterns: agent skills (preloaded via `skills:` field) vs skills (invoked via `Skill` tool). See `orchestration-workflow/orchestration-workflow.md` for the complete flow diagram. ### Skill Definition Structure Skills in `.claude/skills//SKILL.md` use YAML frontmatter: diff --git a/README.md b/README.md index a179951..33c3148 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,11 @@ # claude-code-best-practice practice makes claude perfect -![Last Updated](https://img.shields.io/badge/Last_Updated-Feb_28%2C_2026_07%3A59_PM_PKT-white?style=flat&labelColor=555) GitHub Stars +![Last Updated](https://img.shields.io/badge/Last_Updated-Mar_02%2C_2026_11%3A13_AM_PKT-white?style=flat&labelColor=555) GitHub Stars [![Best Practice](!/tags/best-practice.svg)](best-practice/) *Click on this badge to show the latest best practice*
[![Implemented](!/tags/implemented.svg)](implementation/) *Click on this badge to show implementation in this repo*
-[![Orchestration Workflow](!/tags/orchestration-workflow.svg)](orchestration-workflow/orchestration-workflow.md) *Click on this badge to see the Command → Agent → Skills orchestration workflow* +[![Orchestration Workflow](!/tags/orchestration-workflow.svg)](orchestration-workflow/orchestration-workflow.md) *Click on this badge to see the Command → Agent → Skill orchestration workflow*

Claude Code mascot jumping @@ -24,18 +24,15 @@ practice makes claude perfect | Feature | Location | Description | |---------|----------|-------------| | [**Commands**](https://code.claude.com/docs/en/skills) | `.claude/commands/.md` | [![Best Practice](!/tags/best-practice.svg)](best-practice/claude-commands.md) [![Implemented](!/tags/implemented.svg)](.claude/commands/) Entry-point prompts for workflows — invoke with `/command-name` | -| [**Sub-Agents**](https://code.claude.com/docs/en/sub-agents) | `.claude/agents/.md` | [![Best Practice](!/tags/best-practice.svg)](best-practice/claude-subagents.md) [![Implemented](!/tags/implemented.svg)](implementation/claude-subagents-implementation.md) Custom agents with their own name, color, tools, permissions, and model — usable as main agent or isolated subagents via the Task tool | +| [**Sub-Agents**](https://code.claude.com/docs/en/sub-agents) | `.claude/agents/.md` | [![Best Practice](!/tags/best-practice.svg)](best-practice/claude-subagents.md) [![Implemented](!/tags/implemented.svg)](implementation/claude-subagents-implementation.md) Custom agents with their own name, color, tools, permissions, and model · [Agent Teams](https://code.claude.com/docs/en/agent-teams) | | [**Skills**](https://code.claude.com/docs/en/skills) | `.claude/skills//SKILL.md` | [![Best Practice](!/tags/best-practice.svg)](best-practice/claude-commands.md#skills-frontmatter-fields) [![Implemented](!/tags/implemented.svg)](.claude/skills/) Reusable knowledge, workflows, and slash commands — load on-demand or invoke with `/skill-name` | -| [**Memory**](https://code.claude.com/docs/en/memory) | `CLAUDE.md` | Persistent context via CLAUDE.md files and `@path` imports that Claude sees every session | -| [**Rules**](https://code.claude.com/docs/en/memory#modular-rules-with-clauderules) | `.claude/rules/*.md` | Modular topic-specific instructions with optional path-scoping via frontmatter | -| [**Hooks**](https://code.claude.com/docs/en/hooks) | `.claude/hooks/` | Deterministic scripts that run outside the agentic loop on specific events | -| [**MCP Servers**](https://code.claude.com/docs/en/mcp) | `.claude/settings.json` | Model Context Protocol connections to external tools, databases, and APIs | -| [**Plugins**](https://code.claude.com/docs/en/plugins) | distributable packages | Bundles of skills, subagents, hooks, and MCP servers | -| [**Marketplaces**](https://code.claude.com/docs/en/discover-plugins) | plugin registries | Host and discover plugin collections | -| [**Sandboxing**](https://code.claude.com/docs/en/sandboxing) | runtime config | File and network isolation that improves safety while reducing permission prompts | -| [**Output Styles**](https://code.claude.com/docs/en/output-styles) | `.claude/settings.json` | Configurable response tone and format — Explanatory, Learning, or Custom | -| [**Settings**](https://code.claude.com/docs/en/settings) | `.claude/settings.json` | [![Best Practice](!/tags/best-practice.svg)](best-practice/claude-settings.md) [![Implemented](!/tags/implemented.svg)](.claude/settings.json) Hierarchical configuration system for Claude Code behavior (37 settings, 84 env vars) | -| [**Permissions**](https://code.claude.com/docs/en/iam) | `.claude/settings.json` | Fine-grained access control for tools and operations with wildcard syntax | +| [**Hooks**](https://code.claude.com/docs/en/hooks) | `.claude/hooks/` | [![Implemented](!/tags/implemented.svg)](.claude/hooks/) Deterministic scripts that run outside the agentic loop on specific events | +| [**MCP Servers**](https://code.claude.com/docs/en/mcp) | `.claude/settings.json`, `.mcp.json` | [![Implemented](!/tags/implemented.svg)](.mcp.json) Model Context Protocol connections to external tools, databases, and APIs | +| [**Plugins**](https://code.claude.com/docs/en/plugins) | distributable packages | Bundles of skills, subagents, hooks, and MCP servers · [Marketplaces](https://code.claude.com/docs/en/discover-plugins) | +| [**Settings**](https://code.claude.com/docs/en/settings) | `.claude/settings.json` | [![Best Practice](!/tags/best-practice.svg)](best-practice/claude-settings.md) [![Implemented](!/tags/implemented.svg)](.claude/settings.json) Hierarchical configuration system · [Permissions](https://code.claude.com/docs/en/permissions) · [Model Config](https://code.claude.com/docs/en/model-config) · [Output Styles](https://code.claude.com/docs/en/output-styles) · [Sandboxing](https://code.claude.com/docs/en/sandboxing) · [Keybindings](https://code.claude.com/docs/en/keybindings) · [Status Line](https://code.claude.com/docs/en/statusline) · [Fast Mode](https://code.claude.com/docs/en/fast-mode) | +| [**Memory**](https://code.claude.com/docs/en/memory) | `CLAUDE.md`, `~/.claude/projects//memory/` | [![Implemented](!/tags/implemented.svg)](CLAUDE.md) Persistent context via CLAUDE.md files and `@path` imports · [Auto Memory](https://code.claude.com/docs/en/memory) · [Rules](https://code.claude.com/docs/en/memory#organize-rules-with-clauderules) | +| [**Checkpointing**](https://code.claude.com/docs/en/checkpointing) | automatic (git-based) | Automatic tracking of file edits with rewind (`Esc Esc` or `/rewind`) and targeted summarization | +| [**Remote Control**](https://code.claude.com/docs/en/remote-control) | CLI / claude.ai | Continue local sessions from any device — phone, tablet, or browser · [Headless Mode](https://code.claude.com/docs/en/headless) | > **Note:** Custom slash commands have been merged into skills. Files in `.claude/commands/` still work, but skills (`.claude/skills/`) are recommended as they support additional features like supporting files, invocation control, and subagent execution. @@ -43,7 +40,7 @@ practice makes claude perfect ## Orchestration Workflow -Workflow orchestration using the **Command → Agent → Skills** pattern. +Workflow orchestration using the **Command → Agent → Skill** pattern.

Command Skill Agent Architecture Flow @@ -51,9 +48,9 @@ Workflow orchestration using the **Command → Agent → Skills** pattern. | Component | Role | Example | |-----------|------|---------| -| **Command** | Entry point, user interaction | `/weather-orchestrator` | -| **Agent** | Orchestrates workflow with preloaded skills | `weather` agent | -| **Skills** | Domain knowledge injected at startup | `weather-fetcher`, `weather-transformer` | +| **Command** | Entry point, user interaction | [`/weather-orchestrator`](.claude/commands/weather-orchestrator.md) | +| **Agent** | Fetches data with preloaded skill (agent skill) | [`weather-agent`](.claude/agents/weather-agent.md) with [`weather-fetcher`](.claude/skills/weather-fetcher/SKILL.md) | +| **Skill** | Creates output independently (skill) | [`weather-svg-creator`](.claude/skills/weather-svg-creator/SKILL.md) | See [orchestration-workflow](orchestration-workflow/orchestration-workflow.md) for implementation details. diff --git a/best-practice/claude-commands.md b/best-practice/claude-commands.md index 4372756..7453925 100644 --- a/best-practice/claude-commands.md +++ b/best-practice/claude-commands.md @@ -58,11 +58,11 @@ Custom commands are invoked by typing `/command-name` in Claude Code's interacti ```yaml --- -description: Fetch and transform weather data for Karachi +description: Fetch weather data for Dubai and create an SVG weather card model: haiku --- -Fetch the current temperature for Karachi, Pakistan and apply transformations. +Fetch the current temperature for Dubai, UAE and create a visual SVG weather card. ``` ## Example: Full-Featured Command (All Fields) @@ -161,7 +161,7 @@ Custom commands defined in `.claude/commands/` for this project: | Command | Description | Model | |---------|-------------|-------| -| [`weather-orchestrator`](../.claude/commands/weather-orchestrator.md) | Fetch and transform weather data for Karachi | haiku | +| [`weather-orchestrator`](../.claude/commands/weather-orchestrator.md) | Fetch weather data for Dubai and create an SVG weather card | haiku | | [`workflows/best-practice/workflow-claude-subagents`](../.claude/commands/workflows/best-practice/workflow-claude-subagents.md) | Track Claude Code subagents report changes and find what needs updating | — | --- diff --git a/best-practice/claude-subagents.md b/best-practice/claude-subagents.md index 57dd329..325c551 100644 --- a/best-practice/claude-subagents.md +++ b/best-practice/claude-subagents.md @@ -161,7 +161,7 @@ Custom agents defined in `.claude/agents/` for this project: | Agent | Model | Color | Tools | Skills | Memory | |-------|-------|-------|-------|--------|--------| | [`presentation-curator`](../.claude/agents/presentation-curator.md) | sonnet | magenta | Read, Write, Edit, Grep, Glob | presentation/vibe-to-agentic-framework, presentation/presentation-structure, presentation/presentation-styling | — | -| [`weather`](../.claude/agents/weather.md) | sonnet | green | WebFetch, Read, Write | weather-fetcher, weather-transformer | project | +| [`weather-agent`](../.claude/agents/weather-agent.md) | sonnet | green | WebFetch, Read | weather-fetcher | project | | [`workflow-claude-subagents-agent`](../.claude/agents/workflows/best-practice/workflow-claude-subagents-agent.md) | opus | blue | All (inherited) | — | — | --- diff --git a/changelog/best-practice/claude-subagents/verification-checklist.md b/changelog/best-practice/claude-subagents/verification-checklist.md index 33c2919..ec0aa05 100644 --- a/changelog/best-practice/claude-subagents/verification-checklist.md +++ b/changelog/best-practice/claude-subagents/verification-checklist.md @@ -97,6 +97,6 @@ Rules that verify all hyperlinks in the report are valid. | # | Category | Check | Depth | Compare Against | Added | Origin | |---|----------|-------|-------|-----------------|-------|--------| -| 8A | Local File Links | Verify all relative file links (e.g. `../.claude/agents/weather.md`) resolve to existing files | exists | local filesystem | 2026-02-28 | File moves (reports/ → best-practice/) broke relative links — must catch future breakage | +| 8A | Local File Links | Verify all relative file links (e.g. `../.claude/agents/weather-agent.md`) resolve to existing files | exists | local filesystem | 2026-02-28 | File moves (reports/ → best-practice/) broke relative links — must catch future breakage | | 8B | External URL Links | Verify all external URLs (e.g. `https://code.claude.com/docs/en/sub-agents`) return valid pages | exists | HTTP response | 2026-02-28 | External docs pages can be restructured or removed — must validate on each run | | 8C | Cross-File Reference Links | Verify links to other report files (e.g. `../claude-agent-memory.md`) resolve to existing files | exists | local filesystem | 2026-02-28 | Reports can be moved or renamed — cross-references must stay in sync | diff --git a/changelog/best-practice/concepts/changelog.md b/changelog/best-practice/concepts/changelog.md new file mode 100644 index 0000000..219041c --- /dev/null +++ b/changelog/best-practice/concepts/changelog.md @@ -0,0 +1,46 @@ +# Changelog — README CONCEPTS Section + +Tracks drift between the README CONCEPTS table and official Claude Code documentation. + +## Status Legend + +| Status | Meaning | +|--------|---------| +| `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 | + +--- + +## [2026-03-02 11:14 AM PKT] Claude Code v2.1.63 + +| # | Priority | Type | Action | Status | +|---|----------|------|--------|--------| +| 1 | HIGH | Broken URL | Fix Permissions URL from `/iam` to `/permissions` | COMPLETE (URL updated to /permissions) | +| 2 | HIGH | Missing Concept | Add Agent Teams row to CONCEPTS table | COMPLETE (row added with ~\/\.claude\/teams\/ location) | +| 3 | HIGH | Missing Concept | Add Keybindings row to CONCEPTS table | COMPLETE (row added with ~\/\.claude\/keybindings\.json location) | +| 4 | HIGH | Missing Concept | Add Model Configuration row to CONCEPTS table | COMPLETE (row added with \.claude\/settings\.json location) | +| 5 | HIGH | Missing Concept | Add Auto Memory row to CONCEPTS table | COMPLETE (row added with ~\/\.claude\/projects\/\/memory\/ location) | +| 6 | HIGH | Stale Anchor | Fix Rules URL anchor from `#modular-rules-with-clauderules` to `#organize-rules-with-clauderules` | COMPLETE (anchor updated) | +| 7 | MED | Missing Concept | Add Checkpointing row to CONCEPTS table | COMPLETE (row added with automatic git-based location) | +| 8 | MED | Missing Concept | Add Status Line row to CONCEPTS table | COMPLETE (row added with ~\/\.claude\/settings\.json location) | +| 9 | MED | Missing Concept | Add Remote Control row to CONCEPTS table | COMPLETE (row added with CLI \/ claude\.ai location) | +| 10 | MED | Missing Concept | Add Fast Mode row to CONCEPTS table | COMPLETE (row added with \.claude\/settings\.json location) | +| 11 | MED | Missing Concept | Add Headless Mode row to CONCEPTS table | COMPLETE (row added with CLI flag -p location) | +| 12 | LOW | Changed Description | Update Memory description to mention auto memory | COMPLETE (description and location updated) | +| 13 | LOW | Changed Location | Update MCP Servers location to include `.mcp.json` | COMPLETE (location updated to include .mcp.json) | +| 14 | LOW | Missing Badge | Add Implemented badge to Hooks row | COMPLETE (Implemented badge added linking to .claude/hooks/) | + +--- + +## [2026-03-02 11:57 AM PKT] Claude Code v2.1.63 + +| # | Priority | Type | Action | Status | +|---|----------|------|--------|--------| +| 1 | HIGH | Table Consolidation | Consolidate CONCEPTS table from 22 rows to 10 rows — fold related concepts as inline doc links | COMPLETE (22 → 10 rows) | +| 2 | MED | Merged Concept | Fold Marketplaces into Plugins row as inline link | COMPLETE (linked to /discover-plugins) | +| 3 | MED | Merged Concept | Fold Agent Teams into Sub-Agents row as inline link | COMPLETE (linked to /agent-teams) | +| 4 | MED | Merged Concept | Fold Permissions, Model Config, Output Styles, Sandboxing, Keybindings, Status Line, Fast Mode into Settings row as inline links | COMPLETE (7 concepts folded with doc links) | +| 5 | MED | Merged Concept | Fold Auto Memory and Rules into Memory row as inline links | COMPLETE (linked to /memory and /memory#organize-rules-with-clauderules) | +| 6 | MED | Merged Concept | Fold Headless Mode into Remote Control row as inline link | COMPLETE (linked to /headless) | +| 7 | LOW | Reorder | Reorder table by logical grouping: building blocks → extension → config → context → runtime | COMPLETE (grouped by concern, not chronology) | diff --git a/changelog/best-practice/concepts/verification-checklist.md b/changelog/best-practice/concepts/verification-checklist.md new file mode 100644 index 0000000..eb45f45 --- /dev/null +++ b/changelog/best-practice/concepts/verification-checklist.md @@ -0,0 +1,45 @@ +# Verification Checklist — README CONCEPTS Section + +Rules for verifying CONCEPTS table accuracy. Each rule is checked during every workflow run. + +## Rules + +### 1. External URL Liveness +- **Category**: URL Accuracy +- **What to check**: Every external URL in the CONCEPTS table (docs links) returns a valid page +- **Depth**: Fetch each URL and confirm it loads the expected page (not a redirect to wrong page) +- **Source to compare against**: `https://code.claude.com/docs/llms.txt` for canonical URL list +- **Date added**: 2026-03-02 +- **Origin**: Permissions URL `/iam` was found to redirect to Authentication page instead of Permissions + +### 2. Anchor Fragment Validity +- **Category**: URL Accuracy +- **What to check**: Any URL with an anchor fragment (`#section-name`) matches an actual heading on the target page +- **Depth**: Fetch the page and verify the heading exists with the expected anchor +- **Source to compare against**: Fetched page content +- **Date added**: 2026-03-02 +- **Origin**: Rules anchor `#modular-rules-with-clauderules` was stale; section renamed to `#organize-rules-with-clauderules` + +### 3. Missing Docs Pages +- **Category**: Missing Concepts +- **What to check**: Every page in the official docs index (`llms.txt`) that represents a user-facing feature has a corresponding row in the CONCEPTS table +- **Depth**: Compare full docs index against CONCEPTS table entries +- **Source to compare against**: `https://code.claude.com/docs/llms.txt` +- **Date added**: 2026-03-02 +- **Origin**: Multiple missing concepts found (Agent Teams, Keybindings, Model Configuration, etc.) + +### 4. Local Badge Link Validity +- **Category**: Badge Accuracy +- **What to check**: Every badge target path in the CONCEPTS table (`best-practice/*.md`, `implementation/*.md`, `.claude/*/`) points to a file or directory that exists +- **Depth**: Use Read/Glob to verify file existence +- **Source to compare against**: Local filesystem +- **Date added**: 2026-03-02 +- **Origin**: Initial checklist creation + +### 5. Description Currency +- **Category**: Description Accuracy +- **What to check**: Each concept's description accurately reflects the current official docs description +- **Depth**: Compare README description against the official page's meta description or first paragraph +- **Source to compare against**: Official docs page content +- **Date added**: 2026-03-02 +- **Origin**: Memory description missing auto memory; MCP Servers location missing `.mcp.json` diff --git a/implementation/claude-subagents-implementation.md b/implementation/claude-subagents-implementation.md index 3dd2601..df94f9b 100644 --- a/implementation/claude-subagents-implementation.md +++ b/implementation/claude-subagents-implementation.md @@ -1,6 +1,6 @@ # Sub-agents Implementation -![Last Updated](https://img.shields.io/badge/Last_Updated-Feb_28%2C_2026_07%3A59_PM_PKT-white?style=flat&labelColor=555) +![Last Updated](https://img.shields.io/badge/Last_Updated-Mar_02%2C_2026_07%3A59_PM_PKT-white?style=flat&labelColor=555) @@ -13,52 +13,48 @@ Implemented -The weather agent is implemented in this repo as an example of the **Command → Agent → Skills** architecture pattern. +The weather agent is implemented in this repo as an example of the **Command → Agent → Skill** architecture pattern, demonstrating two distinct skill patterns. --- ## Weather Agent -**File**: [`.claude/agents/weather.md`](../.claude/agents/weather.md) +**File**: [`.claude/agents/weather-agent.md`](../.claude/agents/weather-agent.md) ```yaml --- -name: weather -description: Use this agent PROACTIVELY when you need to fetch and transform - weather data for Karachi, Pakistan. This agent fetches real-time temperature - from wttr.in API and applies transformation rules from - orchestration-workflow/input.md, writing results to - orchestration-workflow/output.md. -tools: WebFetch, Read, Write +name: weather-agent +description: Use this agent PROACTIVELY when you need to fetch weather data for + Dubai, UAE. This agent fetches real-time temperature from wttr.in API + using its preloaded weather-fetcher skill. +tools: WebFetch, Read model: sonnet color: green memory: project skills: - weather-fetcher - - weather-transformer --- # Weather Agent -You are a specialized weather agent that fetches and transforms weather data -for Karachi, Pakistan. +You are a specialized weather agent that fetches weather data for Dubai, +Pakistan. ## Your Task Execute the weather workflow by following the instructions from your preloaded -skills sequentially: +skill: -1. **First**: Follow the `weather-fetcher` skill instructions to fetch the +1. **Fetch**: Follow the `weather-fetcher` skill instructions to fetch the current temperature -2. **Then**: Follow the `weather-transformer` skill instructions to apply - transformations and write results -3. **Finally**: Update your agent memory with the reading details for +2. **Report**: Return the temperature value and unit to the caller +3. **Memory**: Update your agent memory with the reading details for historical tracking ... ``` -The agent has two skills preloaded (`weather-fetcher` and `weather-transformer`) that provide step-by-step instructions for fetching from the wttr.in API and applying transformation rules. +The agent has one preloaded skill (`weather-fetcher`) that provides instructions for fetching from the wttr.in API. It returns the temperature value and unit to the calling command. --- @@ -66,14 +62,14 @@ The agent has two skills preloaded (`weather-fetcher` and `weather-transformer`) ```bash $ claude -> What is the weather in Karachi? +> /weather-orchestrator ``` --- Orchestration Workflow -The weather agent is the **Agent** in the Command → Agent → Skills orchestration pattern. It receives the workflow from the `/weather-orchestrator` command and executes it using two preloaded skills (`weather-fetcher`, `weather-transformer`) within a single execution context. +The weather agent is the **Agent** in the Command → Agent → Skill orchestration pattern. It receives the workflow from the `/weather-orchestrator` command and fetches temperature using its preloaded skill (`weather-fetcher`). The command then invokes the standalone `weather-svg-creator` skill to create the visual output.

Command Skill Agent Architecture Flow @@ -82,6 +78,5 @@ The weather agent is the **Agent** in the Command → Agent → Skills orchestra | Component | Role | This Repo | |-----------|------|-----------| | **Command** | Entry point, user interaction | `/weather-orchestrator` | -| **Agent** | Orchestrates workflow with preloaded skills | `weather` agent | -| **Skills** | Domain knowledge injected at startup | `weather-fetcher`, `weather-transformer` | - +| **Agent** | Fetches data with preloaded skill (agent skill) | `weather-agent` with `weather-fetcher` | +| **Skill** | Creates output independently (skill) | `weather-svg-creator` | diff --git a/orchestration-workflow/input.md b/orchestration-workflow/input.md deleted file mode 100644 index 09bb87a..0000000 --- a/orchestration-workflow/input.md +++ /dev/null @@ -1 +0,0 @@ -add +20 in the result. \ No newline at end of file diff --git a/orchestration-workflow/orchestration-workflow.md b/orchestration-workflow/orchestration-workflow.md index 51f1a9a..74ac8c4 100644 --- a/orchestration-workflow/orchestration-workflow.md +++ b/orchestration-workflow/orchestration-workflow.md @@ -1,6 +1,6 @@ # Orchestration Workflow -This document describes the **Command → Agent → Skills** orchestration workflow, demonstrated through a weather data fetching and transformation system. +This document describes the **Command → Agent (with skill) → Skill** orchestration workflow, demonstrated through a weather data fetching and SVG rendering system.

@@ -11,10 +11,14 @@ This document describes the **Command → Agent → Skills** orchestration workf ## System Overview -The weather system demonstrates the **Command → Agent → Skills** architecture pattern, where: -- A command orchestrates the workflow -- An agent executes tasks using preloaded skills -- Skills provide domain-specific knowledge and instructions +The weather system demonstrates two distinct skill patterns within a single orchestration workflow: +- **Agent Skills** (preloaded): `weather-fetcher` is injected into the `weather-agent` at startup as domain knowledge +- **Skills** (independent): `weather-svg-creator` is invoked directly by the command via the Skill tool + +This showcases the **Command → Agent → Skill** architecture pattern, where: +- A command orchestrates the workflow and handles user interaction +- An agent fetches data using its preloaded skill +- A skill creates the visual output independently ## Flow Diagram @@ -22,58 +26,60 @@ The weather system demonstrates the **Command → Agent → Skills** architectur ┌─────────────────────────────────────────────────┐ │ User Interaction │ └─────────────────────────────────────────────────┘ - │ - ▼ - ┌───────────────────────────┐ - │ /weather-orchestrator │ - │ Command │ - │ (Entry point) │ - └───────────────────────────┘ - │ - │ Task tool invocation - ▼ - ┌───────────────────────────┐ - │ weather │ - │ Agent │ - │ (Orchestrates flow) │ - │ │ - │ skills: │ - │ - weather-fetcher │ - │ - weather-transformer │ - └───────────────────────────┘ - │ - ┌────────────────┴────────────────┐ - │ │ - ▼ ▼ - ┌───────────────────────────┐ ┌───────────────────────────┐ - │ weather-fetcher │ │ weather-transformer │ - │ Skill │ │ Skill │ - │ (Preloaded knowledge) │ │ (Preloaded knowledge) │ - └───────────────────────────┘ └───────────────────────────┘ - │ │ - ▼ ▼ - ┌───────────────────────────┐ ┌───────────────────────────┐ - │ wttr.in API │ │ orchestration-workflow/ │ - │ Fetch Temperature │ │ Read Transform Rules │ - │ for Karachi │ └───────────────────────────┘ - └───────────────────────────┘ │ - │ ▼ - │ Returns: 26°C ┌───────────────────────────┐ - │ │ Apply Transform │ - └──────────────────▶│ 26 + 10 = 36°C │ - └───────────────────────────┘ - │ - ▼ - ┌─────────────────────────────────────┐ - │ orchestration-workflow/output.md │ - │ Write Results │ - └─────────────────────────────────────┘ - │ - ▼ - ┌───────────────────────────┐ - │ Display Summary │ - │ to User │ - └───────────────────────────┘ + │ + ▼ + ┌───────────────────────────┐ + │ /weather-orchestrator │ + │ Command │ + │ (Entry point) │ + └───────────────────────────┘ + │ + ┌─────────────┤ + │ │ + ▼ │ + ┌──────────────┐ │ + │ AskUser │ │ + │ C° or F°? │ │ + └──────────────┘ │ + │ │ + ▼ │ + Step 2: Task tool │ + │ │ + ▼ │ + ┌───────────────────────────┐ + │ weather-agent │ + │ Agent │ + │ │ + │ preloaded skill: │ + │ - weather-fetcher │ + └───────────────────────────┘ + │ + │ Returns: temperature + unit + │ + ▼ + Step 3: Skill tool + │ + ▼ + ┌───────────────────────────┐ + │ weather-svg-creator │ + │ Skill │ + │ │ + │ Creates SVG card │ + │ Writes output files │ + └───────────────────────────┘ + │ + ┌────────┴────────┐ + │ │ + ▼ ▼ +┌──────────────────┐ ┌──────────────────┐ +│ weather.svg │ │ output.md │ +└──────────────────┘ └──────────────────┘ + │ + ▼ + ┌───────────────────────────┐ + │ Display Summary │ + │ to User │ + └───────────────────────────┘ ``` ## Component Details @@ -82,116 +88,118 @@ The weather system demonstrates the **Command → Agent → Skills** architectur #### `/weather-orchestrator` (Command) - **Location**: `.claude/commands/weather-orchestrator.md` -- **Purpose**: Entry point for weather operations -- **Action**: Invokes the weather agent via Task tool +- **Purpose**: Entry point — orchestrates the workflow and handles user interaction +- **Actions**: + 1. Asks user for temperature unit preference (Celsius/Fahrenheit) + 2. Invokes weather-agent via Task tool + 3. Invokes weather-svg-creator via Skill tool - **Model**: haiku -### 2. Agent with Skills +### 2. Agent with Preloaded Skill (Agent Skill) -#### `weather` (Agent) -- **Location**: `.claude/agents/weather.md` -- **Purpose**: Execute the weather workflow using preloaded skills -- **Skills**: `weather-fetcher`, `weather-transformer` -- **Tools Available**: WebFetch, Read, Write -- **Model**: haiku +#### `weather-agent` (Agent) +- **Location**: `.claude/agents/weather-agent.md` +- **Purpose**: Fetch weather data using its preloaded skill +- **Skills**: `weather-fetcher` (preloaded as domain knowledge) +- **Tools Available**: WebFetch, Read +- **Model**: sonnet - **Color**: green +- **Memory**: project -The agent has skills preloaded into its context at startup. It follows the instructions from each skill sequentially. +The agent has `weather-fetcher` preloaded into its context at startup. It follows the skill's instructions to fetch the temperature and returns the value to the command. -### 3. Skills +### 3. Skill + +#### `weather-svg-creator` (Skill) +- **Location**: `.claude/skills/weather-svg-creator/SKILL.md` +- **Purpose**: Create a visual SVG weather card and write output files +- **Invocation**: Via Skill tool from the command (not preloaded into any agent) +- **Outputs**: + - `orchestration-workflow/weather.svg` — SVG weather card + - `orchestration-workflow/output.md` — Weather summary + +### 4. Preloaded Skill #### `weather-fetcher` (Skill) - **Location**: `.claude/skills/weather-fetcher/SKILL.md` - **Purpose**: Instructions for fetching real-time temperature data -- **Data Source**: wttr.in API for Karachi, Pakistan -- **Output**: Temperature in Celsius (numeric value) - -#### `weather-transformer` (Skill) -- **Location**: `.claude/skills/weather-transformer/SKILL.md` -- **Purpose**: Instructions for applying mathematical transformations -- **Input Source**: `orchestration-workflow/input.md` (transformation rules) -- **Output Destination**: `orchestration-workflow/output.md` (formatted results) - -### 4. Data Files - -#### `orchestration-workflow/input.md` -- **Purpose**: Stores transformation rules -- **Format**: Natural language instructions (e.g., "add +10 in the result") -- **Access**: Read by weather agent following weather-transformer skill - -#### `orchestration-workflow/output.md` -- **Purpose**: Stores formatted transformation results -- **Format**: Structured markdown with sections: - - Original Temperature - - Transformation Applied - - Final Result - - Calculation Details +- **Data Source**: wttr.in API for Dubai, UAE +- **Output**: Temperature value and unit (Celsius or Fahrenheit) +- **Note**: This is an agent skill — preloaded into `weather-agent`, not invoked directly ## Execution Flow 1. **User Invocation**: User runs `/weather-orchestrator` command 2. **User Prompt**: Command asks user for preferred temperature unit (Celsius/Fahrenheit) -3. **Agent Invocation**: Command invokes weather agent via Task tool +3. **Agent Invocation**: Command invokes `weather-agent` via Task tool 4. **Skill Execution** (within agent context): - - **Step 1**: Agent follows `weather-fetcher` skill instructions to fetch temperature from wttr.in - - **Step 2**: Agent follows `weather-transformer` skill instructions to: - - Read transformation rules from `orchestration-workflow/input.md` - - Apply rules to the fetched temperature - - Write formatted results to `orchestration-workflow/output.md` -5. **Result Display**: Summary shown to user with: + - Agent follows `weather-fetcher` skill instructions to fetch temperature from wttr.in + - Agent returns the temperature value and unit to the command +5. **SVG Creation**: Command invokes `weather-svg-creator` via Skill tool + - Skill creates SVG weather card at `orchestration-workflow/weather.svg` + - Skill writes summary to `orchestration-workflow/output.md` +6. **Result Display**: Summary shown to user with: - Temperature unit requested - - Original temperature - - Transformation rule applied - - Final transformed result + - Temperature fetched + - SVG card location + - Output file location ## Example Execution ``` Input: /weather-orchestrator -├─ Asks: Celsius or Fahrenheit? -├─ User: Celsius -├─ Task: weather agent (via Task tool) -│ ├─ Skills Preloaded: -│ │ ├─ weather-fetcher (knowledge) -│ │ └─ weather-transformer (knowledge) -│ ├─ Step 1 (weather-fetcher skill): -│ │ └─ Fetches from wttr.in → 26°C -│ ├─ Step 2 (weather-transformer skill): -│ │ ├─ Reads: orchestration-workflow/input.md ("add +10") -│ │ ├─ Calculates: 26 + 10 = 36°C -│ │ └─ Writes: orchestration-workflow/output.md -│ └─ Returns: Complete report +├─ Step 1: Asks: Celsius or Fahrenheit? +│ └─ User: Celsius +├─ Step 2: Task tool → weather-agent +│ ├─ Preloaded Skill: +│ │ └─ weather-fetcher (domain knowledge) +│ ├─ Fetches from wttr.in → 26°C +│ └─ Returns: temperature=26, unit=Celsius +├─ Step 3: Skill tool → /weather-svg-creator +│ ├─ Creates: orchestration-workflow/weather.svg +│ └─ Writes: orchestration-workflow/output.md └─ Output: ├─ Unit: Celsius - ├─ Original: 26°C - ├─ Transform: Add +10 - └─ Result: 36°C + ├─ Temperature: 26°C + ├─ SVG: orchestration-workflow/weather.svg + └─ Summary: orchestration-workflow/output.md ``` ## Key Design Principles -1. **Command → Agent → Skills**: Three-tier architecture for clean separation -2. **Skills as Knowledge**: Skills provide domain knowledge preloaded into agent context -3. **Single Agent**: One agent handles multiple related tasks using its skills -4. **Sequential Execution**: Agent follows skill instructions in order -5. **Configurable Transformations**: Rules stored externally in input files -6. **Structured Output**: Results formatted consistently in output files +1. **Two Skill Patterns**: Demonstrates both agent skills (preloaded) and skills (invoked directly) +2. **Command as Orchestrator**: The command handles user interaction and coordinates the workflow +3. **Agent for Data Fetching**: The agent uses its preloaded skill to fetch data, then returns it +4. **Skill for Output**: The SVG creator runs independently, receiving data from the command context +5. **Clean Separation**: Fetch (agent) → Render (skill) — each component has a single responsibility -## Architecture Pattern: Agent-Skills +## Architecture Patterns -This system demonstrates the **agent-skills pattern** where: +### Agent Skill (Preloaded) ```yaml -# In agent definition (.claude/agents/weather.md) +# In agent definition (.claude/agents/weather-agent.md) --- -name: weather +name: weather-agent skills: - - weather-fetcher - - weather-transformer + - weather-fetcher # Preloaded into agent context at startup --- ``` - **Skills are preloaded**: Full skill content is injected into agent's context at startup - **Agent uses skill knowledge**: Agent follows instructions from preloaded skills -- **No dynamic invocation**: Skills are not invoked separately; they're reference material -- **Single execution context**: All work happens within one agent's context +- **No dynamic invocation**: Skills are reference material, not invoked separately + +### Skill (Direct Invocation) + +```yaml +# In skill definition (.claude/skills/weather-svg-creator/SKILL.md) +--- +name: weather-svg-creator +description: Creates an SVG weather card... +--- +``` + +- **Invoked via Skill tool**: Command calls `Skill(skill: "weather-svg-creator")` +- **Independent execution**: Runs in the command's context, not inside an agent +- **Receives data from context**: Uses temperature data already available in the conversation diff --git a/orchestration-workflow/output.md b/orchestration-workflow/output.md index 717c4da..eceb653 100644 --- a/orchestration-workflow/output.md +++ b/orchestration-workflow/output.md @@ -1,13 +1,13 @@ -# Weather Transformation Result +# Weather Result -## Original Temperature -27°C +## Temperature +32°C -## Transformation Applied -Add +20 to the result +## Location +Dubai, UAE -## Final Result -47°C +## Unit +Celsius -## Calculation Details -27°C + 20 = 47°C +## SVG Card +![Weather Card](weather.svg) diff --git a/orchestration-workflow/weather.svg b/orchestration-workflow/weather.svg new file mode 100644 index 0000000..bb3abc4 --- /dev/null +++ b/orchestration-workflow/weather.svg @@ -0,0 +1,6 @@ + + + Unit: Celsius + 32°C + Dubai, UAE +