From d291519452021138c051fc04c3f56a34f25cd868 Mon Sep 17 00:00:00 2001 From: Luong NGUYEN Date: Wed, 24 Dec 2025 23:22:58 +0100 Subject: [PATCH] chore: Archive add-context-usage-hook-example change --- .../proposal.md | 0 .../specs/hooks-documentation/spec.md | 0 .../tasks.md | 0 .../changes/update-skills-lesson/tasks.md | 28 ++--- .../update-subagents-lesson/proposal.md | 92 ++++++++++++++++ .../specs/subagents-lesson/spec.md | 101 ++++++++++++++++++ .../changes/update-subagents-lesson/tasks.md | 90 ++++++++++++++++ openspec/specs/hooks-documentation/spec.md | 15 +++ 8 files changed, 312 insertions(+), 14 deletions(-) rename openspec/changes/{add-context-usage-hook-example => archive/2025-12-24-add-context-usage-hook-example}/proposal.md (100%) rename openspec/changes/{add-context-usage-hook-example => archive/2025-12-24-add-context-usage-hook-example}/specs/hooks-documentation/spec.md (100%) rename openspec/changes/{add-context-usage-hook-example => archive/2025-12-24-add-context-usage-hook-example}/tasks.md (100%) create mode 100644 openspec/changes/update-subagents-lesson/proposal.md create mode 100644 openspec/changes/update-subagents-lesson/specs/subagents-lesson/spec.md create mode 100644 openspec/changes/update-subagents-lesson/tasks.md diff --git a/openspec/changes/add-context-usage-hook-example/proposal.md b/openspec/changes/archive/2025-12-24-add-context-usage-hook-example/proposal.md similarity index 100% rename from openspec/changes/add-context-usage-hook-example/proposal.md rename to openspec/changes/archive/2025-12-24-add-context-usage-hook-example/proposal.md diff --git a/openspec/changes/add-context-usage-hook-example/specs/hooks-documentation/spec.md b/openspec/changes/archive/2025-12-24-add-context-usage-hook-example/specs/hooks-documentation/spec.md similarity index 100% rename from openspec/changes/add-context-usage-hook-example/specs/hooks-documentation/spec.md rename to openspec/changes/archive/2025-12-24-add-context-usage-hook-example/specs/hooks-documentation/spec.md diff --git a/openspec/changes/add-context-usage-hook-example/tasks.md b/openspec/changes/archive/2025-12-24-add-context-usage-hook-example/tasks.md similarity index 100% rename from openspec/changes/add-context-usage-hook-example/tasks.md rename to openspec/changes/archive/2025-12-24-add-context-usage-hook-example/tasks.md diff --git a/openspec/changes/update-skills-lesson/tasks.md b/openspec/changes/update-skills-lesson/tasks.md index e62de94..6b0b771 100644 --- a/openspec/changes/update-skills-lesson/tasks.md +++ b/openspec/changes/update-skills-lesson/tasks.md @@ -2,26 +2,26 @@ ## 1. Update Main README (03-skills/README.md) -- [ ] 1.1 Add "Managing Skills" section with viewing, testing, updating, removing guidance -- [ ] 1.2 Expand "Troubleshooting Guide" with debugging tips for skipped skills, YAML errors, script permissions, path formats -- [ ] 1.3 Add "Version History Best Practice" section with example -- [ ] 1.4 Enhance "allowed-tools" documentation with use cases and security examples -- [ ] 1.5 Add "Multi-File Skill Example" showing complex skill structure with multiple reference files +- [x] 1.1 Add "Managing Skills" section with viewing, testing, updating, removing guidance +- [x] 1.2 Expand "Troubleshooting Guide" with debugging tips for skipped skills, YAML errors, script permissions, path formats +- [x] 1.3 Add "Version History Best Practice" section with example +- [x] 1.4 Enhance "allowed-tools" documentation with use cases and security examples +- [x] 1.5 Add "Multi-File Skill Example" showing complex skill structure with multiple reference files ## 2. Update Blog Post (blog-posts/03-skills.md) -- [ ] 2.1 Add "Managing Skills" section mirroring README updates -- [ ] 2.2 Expand troubleshooting with debugging guidance from official docs -- [ ] 2.3 Add version history best practice -- [ ] 2.4 Enhance allowed-tools explanation -- [ ] 2.5 Add multi-file skill example +- [x] 2.1 Add "Managing Skills" section mirroring README updates +- [x] 2.2 Expand troubleshooting with debugging guidance from official docs +- [x] 2.3 Add version history best practice +- [x] 2.4 Enhance allowed-tools explanation +- [x] 2.5 Add multi-file skill example ## 3. Update Example Skills -- [ ] 3.1 Add version history section to `03-skills/code-review/SKILL.md` +- [x] 3.1 Add version history section to `03-skills/code-review/SKILL.md` ## 4. Validation -- [ ] 4.1 Verify all code examples are syntactically correct -- [ ] 4.2 Ensure consistency between README and blog post -- [ ] 4.3 Test that existing examples still work with updated documentation +- [x] 4.1 Verify all code examples are syntactically correct +- [x] 4.2 Ensure consistency between README and blog post +- [x] 4.3 Test that existing examples still work with updated documentation diff --git a/openspec/changes/update-subagents-lesson/proposal.md b/openspec/changes/update-subagents-lesson/proposal.md new file mode 100644 index 0000000..87ae471 --- /dev/null +++ b/openspec/changes/update-subagents-lesson/proposal.md @@ -0,0 +1,92 @@ +# Proposal: update-subagents-lesson + +## Summary + +Update the `04-subagents` lesson to align with the official Claude Code documentation at https://code.claude.com/docs/en/sub-agents. The current lesson is missing several key features and uses outdated configuration formats. + +## Motivation + +The existing subagents lesson lacks critical features documented in the official docs: + +1. **Missing `/agents` command** - The interactive management interface +2. **Incomplete configuration fields** - Missing `model`, `permissionMode`, `skills` fields +3. **No built-in subagents section** - General-Purpose, Plan, and Explore agents not documented +4. **Missing resumable agents feature** - Agent continuation with `agentId` +5. **No CLI-based configuration** - `--agents` flag for session-specific agents +6. **Outdated file format** - Uses `system_prompt` instead of YAML frontmatter with markdown body +7. **Missing thoroughness levels** - Quick, Medium, Very thorough for Explore agent +8. **No proactive invocation guidance** - "use PROACTIVELY" description patterns + +## Scope + +### In Scope +- Update `04-subagents/README.md` with all official documentation features +- Update example subagent files to use correct YAML frontmatter format +- Add new example subagents (debugger, data-scientist) from official docs +- Document built-in subagents (General-Purpose, Plan, Explore) +- Add `/agents` command documentation +- Add CLI-based configuration section +- Document resumable agents feature +- Update installation and usage instructions + +### Out of Scope +- Plugin subagents in `07-plugins/` (separate concern) +- Creating new advanced tutorials +- Video or interactive content + +## Key Changes + +### 1. Configuration Format Update + +**Current** (incorrect): +```yaml +--- +name: agent-name +description: Brief description +tools: read, grep, diff +--- +``` + +**Updated** (per official docs): +```yaml +--- +name: agent-name +description: Description of when this subagent should be invoked +tools: tool1, tool2, tool3 # Optional - inherits all tools if omitted +model: sonnet # Optional - specify model alias or 'inherit' +permissionMode: default # Optional - permission mode +skills: skill1, skill2 # Optional - skills to auto-load +--- + +Your subagent's system prompt goes here in markdown. +``` + +### 2. Built-in Subagents Documentation + +Add new section documenting: +- **General-Purpose** - Sonnet model, all tools, complex tasks +- **Plan** - Sonnet model, research tools, plan mode +- **Explore** - Haiku model, read-only, fast codebase searching with thoroughness levels + +### 3. Management Features + +- `/agents` command for interactive management +- CLI `--agents` flag for session-specific configuration +- Resumable agents with `agentId` + +### 4. Example Updates + +Update existing examples and add: +- Debugger subagent (from official docs) +- Data Scientist subagent (from official docs) + +## Success Criteria + +- [ ] README covers all features from official documentation +- [ ] Configuration examples use correct YAML frontmatter format +- [ ] All 5 existing example agents updated to new format +- [ ] 2 new example agents added (debugger, data-scientist) +- [ ] Built-in subagents documented +- [ ] `/agents` command documented +- [ ] Resumable agents feature documented +- [ ] Installation instructions updated diff --git a/openspec/changes/update-subagents-lesson/specs/subagents-lesson/spec.md b/openspec/changes/update-subagents-lesson/specs/subagents-lesson/spec.md new file mode 100644 index 0000000..d1b0e1f --- /dev/null +++ b/openspec/changes/update-subagents-lesson/specs/subagents-lesson/spec.md @@ -0,0 +1,101 @@ +# Spec: Subagents Lesson Content + +## MODIFIED Requirements + +### Requirement: Configuration Format + +The subagent configuration MUST use YAML frontmatter with all supported fields. + +#### Scenario: Complete configuration example +- **Given**: A user wants to create a subagent +- **When**: They view the configuration documentation +- **Then**: The example shows all fields: name, description, tools (optional), model (optional), permissionMode (optional), skills (optional) + +#### Scenario: Tools field omission +- **Given**: A subagent configuration omits the tools field +- **When**: The documentation explains this +- **Then**: It states the subagent inherits all tools from the main agent + +### Requirement: Built-in Subagents Documentation + +The lesson MUST document the three built-in subagents. + +#### Scenario: General-Purpose subagent +- **Given**: A user reads about built-in subagents +- **When**: They view the General-Purpose section +- **Then**: They learn it uses Sonnet model, has all tools, and handles complex multi-step tasks + +#### Scenario: Plan subagent +- **Given**: A user reads about built-in subagents +- **When**: They view the Plan section +- **Then**: They learn it uses Sonnet model, has Read/Glob/Grep/Bash tools, and is used in plan mode + +#### Scenario: Explore subagent +- **Given**: A user reads about built-in subagents +- **When**: They view the Explore section +- **Then**: They learn it uses Haiku model, is read-only, fast, and supports thoroughness levels (quick, medium, very thorough) + +### Requirement: /agents Command + +The lesson MUST document the interactive /agents command. + +#### Scenario: User discovers management interface +- **Given**: A user wants to manage subagents interactively +- **When**: They read the documentation +- **Then**: They learn about `/agents` command to create, edit, delete, and view subagents + +### Requirement: Resumable Agents + +The lesson MUST document agent continuation with agentId. + +#### Scenario: User learns about resuming agents +- **Given**: A user wants to continue a previous agent conversation +- **When**: They read the resumable agents section +- **Then**: They learn agents return an agentId and can be resumed with full context + +### Requirement: CLI Configuration + +The lesson MUST document session-specific agent configuration via CLI. + +#### Scenario: User defines agents via command line +- **Given**: A user wants to define agents for a single session +- **When**: They read the CLI configuration section +- **Then**: They learn to use `--agents` flag with JSON configuration + +## ADDED Requirements + +### Requirement: Example Subagent - Debugger + +The lesson MUST include a debugger subagent example. + +#### Scenario: User needs debugging specialist +- **Given**: A user wants a debugging-focused subagent +- **When**: They view the examples +- **Then**: They find a complete debugger.md example with root cause analysis approach + +### Requirement: Example Subagent - Data Scientist + +The lesson MUST include a data scientist subagent example. + +#### Scenario: User needs data analysis specialist +- **Given**: A user wants a data analysis subagent +- **When**: They view the examples +- **Then**: They find a complete data-scientist.md example with SQL/BigQuery focus + +### Requirement: File Location Documentation + +The lesson MUST document where subagent files can be stored. + +#### Scenario: User learns storage locations +- **Given**: A user wants to know where to put subagent files +- **When**: They read the file locations section +- **Then**: They learn about project (.claude/agents/), user (~/.claude/agents/), plugin, and CLI locations with priority order + +### Requirement: Proactive Invocation Guidance + +The lesson MUST explain how to encourage automatic subagent use. + +#### Scenario: User wants subagent used automatically +- **Given**: A user wants Claude to proactively use their subagent +- **When**: They read the usage section +- **Then**: They learn to include "use PROACTIVELY" or "MUST BE USED" in the description field diff --git a/openspec/changes/update-subagents-lesson/tasks.md b/openspec/changes/update-subagents-lesson/tasks.md new file mode 100644 index 0000000..bb9a8f1 --- /dev/null +++ b/openspec/changes/update-subagents-lesson/tasks.md @@ -0,0 +1,90 @@ +# Tasks: update-subagents-lesson + +## Phase 1: Update README.md Structure + +1. [x] **Update Overview section** + - Add `/agents` command mention + - Add built-in subagents overview + - Update key benefits with official wording + +2. [x] **Add File Locations section** + - Document project subagents (`.claude/agents/`) + - Document user subagents (`~/.claude/agents/`) + - Document plugin agents + - Document CLI-defined agents + +3. [x] **Update Configuration section** + - Update YAML frontmatter format with all fields + - Add configuration fields table (name, description, tools, model, permissionMode, skills) + - Add CLI-based configuration with `--agents` flag + +## Phase 2: Add New Sections + +4. [x] **Add Built-in Subagents section** + - Document General-Purpose subagent (Sonnet, all tools) + - Document Plan subagent (Sonnet, research tools) + - Document Explore subagent (Haiku, read-only, thoroughness levels) + +5. [x] **Add /agents Command section** + - Document interactive menu options + - Create, edit, delete operations + - View available subagents + +6. [x] **Add Resumable Agents section** + - Document agentId concept + - Show resume syntax + - List use cases + +7. [x] **Add Chaining Subagents section** + - Multi-agent workflows + - Sequential delegation + +## Phase 3: Update Example Files + +8. [x] **Update `code-reviewer.md`** + - Add model field + - Update to match official example format + - Add proactive usage hints + +9. [x] **Update `test-engineer.md`** + - Add model field + - Update system prompt format + +10. [x] **Update `documentation-writer.md`** + - Add model field + - Update format + +11. [x] **Update `secure-reviewer.md`** + - Update to minimal permission pattern + +12. [x] **Update `implementation-agent.md`** + - Update tool list format + +## Phase 4: Add New Example Files + +13. [x] **Create `debugger.md`** + - Copy from official docs example + - Adapt to project style + +14. [x] **Create `data-scientist.md`** + - Copy from official docs example + - Adapt to project style + +## Phase 5: Finalize + +15. [x] **Update Installation Instructions** + - Add `/agents` method + - Update verification steps + +16. [x] **Update Related Concepts** + - Link to new sections + - Update comparison table + +17. [x] **Update last modified date** + +## Validation + +- [x] All YAML frontmatter validates correctly +- [x] No broken internal links +- [x] Examples use consistent formatting +- [x] Built-in agents documented accurately diff --git a/openspec/specs/hooks-documentation/spec.md b/openspec/specs/hooks-documentation/spec.md index ba96f58..949c5da 100644 --- a/openspec/specs/hooks-documentation/spec.md +++ b/openspec/specs/hooks-documentation/spec.md @@ -123,3 +123,18 @@ The hooks lesson SHALL provide working example scripts that use JSON stdin input #### Scenario: Intelligent stop hook - **WHEN** a user wants automatic task completion verification - **THEN** they find a working prompt-based stop hook example + +### Requirement: Context Usage Reporting Hook Example +The hooks lesson SHALL include a detailed example showing how to create a hook that reports context/token usage after each user request. + +#### Scenario: User learns to create context monitoring hook +- **WHEN** a user reads the context usage reporter example +- **THEN** they find a complete Python script that reads the transcript file +- **AND** they understand how to estimate token usage from conversation history +- **AND** they see the configuration for UserPromptSubmit or Stop hooks +- **AND** they understand the limitations of token estimation + +#### Scenario: Hook output format is documented +- **WHEN** a user implements the context usage hook +- **THEN** they can generate a one-line report showing used tokens and remaining capacity +- **AND** they understand the report is an estimate based on transcript analysis