chore: Archive add-context-usage-hook-example change

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

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

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

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

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