diff --git a/openspec/changes/update-skills-lesson/proposal.md b/openspec/changes/archive/2025-12-24-update-skills-lesson/proposal.md similarity index 100% rename from openspec/changes/update-skills-lesson/proposal.md rename to openspec/changes/archive/2025-12-24-update-skills-lesson/proposal.md diff --git a/openspec/changes/update-skills-lesson/specs/skills-lesson/spec.md b/openspec/changes/archive/2025-12-24-update-skills-lesson/specs/skills-lesson/spec.md similarity index 100% rename from openspec/changes/update-skills-lesson/specs/skills-lesson/spec.md rename to openspec/changes/archive/2025-12-24-update-skills-lesson/specs/skills-lesson/spec.md diff --git a/openspec/changes/update-skills-lesson/tasks.md b/openspec/changes/archive/2025-12-24-update-skills-lesson/tasks.md similarity index 100% rename from openspec/changes/update-skills-lesson/tasks.md rename to openspec/changes/archive/2025-12-24-update-skills-lesson/tasks.md diff --git a/openspec/changes/fix-context-usage-hook/proposal.md b/openspec/changes/fix-context-usage-hook/proposal.md new file mode 100644 index 0000000..617a07a --- /dev/null +++ b/openspec/changes/fix-context-usage-hook/proposal.md @@ -0,0 +1,44 @@ +# Change: Fix Context Usage Hook Token Calculation + +## Why + +The context-usage hook (Stop event) always reports 0 tokens because of a bug in line 68 of `context-usage.py`: + +```python +estimated_tokens = estimate_tokens(str(total_chars)) +``` + +This converts the integer `total_chars` (e.g., `156789`) to a string `"156789"` and then calculates tokens from that 6-character string, resulting in `6 // 4 = 1` token instead of `156789 // 4 = ~39,197` tokens. + +**Current behavior:** +``` +Stop says: Context: ~0/200,000 tokens (100.0% remaining) +``` + +**Expected behavior:** +``` +Stop says: Context: ~39,197/200,000 tokens (80.4% remaining) +``` + +## What + +Fix the token calculation bug in the context-usage.py example hook: +1. Remove the erroneous `str()` conversion +2. Calculate estimated tokens directly from character count + +## Scope + +- **Files affected:** + - `06-hooks/README.md` - Update the example code + - User's `~/.claude/hooks/context-usage.py` - Not managed by this repo, but fix will be documented + +## Out of Scope + +- Improving transcript parsing logic +- Adding more sophisticated token estimation +- Adding new hook features + +## Risks + +- **Low:** Simple bug fix with clear expected behavior +- Users who copied the broken example will need to update their hook manually diff --git a/openspec/changes/fix-context-usage-hook/specs/hooks-documentation/spec.md b/openspec/changes/fix-context-usage-hook/specs/hooks-documentation/spec.md new file mode 100644 index 0000000..da084b0 --- /dev/null +++ b/openspec/changes/fix-context-usage-hook/specs/hooks-documentation/spec.md @@ -0,0 +1,24 @@ +# hooks-documentation Specification Delta + +## MODIFIED Requirements + +### Requirement: Context Usage Reporting Hook Example +The hooks lesson SHALL include a correct, working example showing how to create a hook that reports context/token usage after each Claude response. + +#### Scenario: Token calculation is correct +- **WHEN** a user copies the context-usage.py example +- **AND** runs it as a Stop hook +- **THEN** the hook correctly calculates estimated tokens from total character count +- **AND** displays a non-zero token count proportional to conversation length + +#### 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 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** the output shows realistic token counts based on conversation size diff --git a/openspec/changes/fix-context-usage-hook/tasks.md b/openspec/changes/fix-context-usage-hook/tasks.md new file mode 100644 index 0000000..6b1cf18 --- /dev/null +++ b/openspec/changes/fix-context-usage-hook/tasks.md @@ -0,0 +1,20 @@ +# Tasks: Fix Context Usage Hook Token Calculation + +## Implementation Tasks + +### 1. Fix the bug in 06-hooks/README.md example +- [ ] Update line 564 in the context-usage.py example: change `estimate_tokens(str(total_chars))` to `total_chars // 4` +- [ ] Remove the now-unused `estimate_tokens()` function from the example + +### 2. Update user's local hook file +- [ ] Fix `~/.claude/hooks/context-usage.py` with the same correction + +### 3. Verification +- [ ] Test the hook by running Claude Code and confirming non-zero token count is displayed +- [ ] Verify the percentage calculation is reasonable (should show usage increasing during conversation) + +## Acceptance Criteria + +- [ ] After Claude responds, the Stop hook displays a non-zero token estimate +- [ ] The displayed percentage decreases as conversation grows +- [ ] Example in README.md matches the corrected implementation diff --git a/openspec/changes/update-memory-lesson/proposal.md b/openspec/changes/update-memory-lesson/proposal.md new file mode 100644 index 0000000..2730607 --- /dev/null +++ b/openspec/changes/update-memory-lesson/proposal.md @@ -0,0 +1,32 @@ +# Change: Update Memory Lesson with Latest Documentation + +## Why + +The current memory lesson (`blog-posts/02-memory.md`) is based on older Claude Code documentation. The official documentation at `https://code.claude.com/docs/en/memory` includes several new features and updates that the lesson doesn't cover, making it incomplete for readers who want to learn about Claude Code's full memory capabilities. + +## What Changes + +### New Features to Add +- **Project Rules** (`.claude/rules/*.md`) - Modular, topic-specific markdown files for organizing instructions +- **Path-Specific Rules** - YAML frontmatter with `paths:` to scope rules to specific file patterns +- **Glob Pattern Support** - Examples of glob patterns for path-specific rules +- **Project Local Memory** (`CLAUDE.local.md`) - Personal project preferences that are auto-gitignored +- **Symlink Support** - Sharing rules across projects using symbolic links + +### Updates to Existing Content +- **Memory Hierarchy Table** - Update to include Project Rules and Project Local as additional memory types +- **Enterprise Policy Windows Path** - Correct to `C:\Program Files\ClaudeCode\CLAUDE.md` (currently shows `C:\ProgramData\ClaudeCode\CLAUDE.md`) +- **Memory Lookup Algorithm** - Add detailed explanation of recursive upward search behavior +- **Best Practices Section** - Add guidelines for `.claude/rules/` organization + +### Structure Improvements +- Add new section: "Modular Rules with `.claude/rules/`" +- Add new section: "Path-Specific Rules" +- Update directory structure example to show `.claude/rules/` organization +- Improve organization of content to match official documentation structure + +## Impact + +- **Affected files**: `blog-posts/02-memory.md` +- **User benefit**: Readers will learn about complete memory capabilities including modular rules and path-specific scoping +- **No breaking changes**: All existing content remains valid; this adds new sections and updates outdated information diff --git a/openspec/changes/update-memory-lesson/specs/memory-lesson/spec.md b/openspec/changes/update-memory-lesson/specs/memory-lesson/spec.md new file mode 100644 index 0000000..efd0882 --- /dev/null +++ b/openspec/changes/update-memory-lesson/specs/memory-lesson/spec.md @@ -0,0 +1,69 @@ +## MODIFIED Requirements + +### Requirement: Memory Hierarchy Documentation +The memory lesson SHALL document the complete 5-level memory hierarchy including Enterprise Policy, Project Memory, Project Rules, User Memory, and Project Local memory types. + +#### Scenario: Complete hierarchy explanation +- **WHEN** a reader views the memory hierarchy section +- **THEN** they SHALL see all 5 memory levels with their locations, scopes, and sharing capabilities + +#### Scenario: Enterprise Policy Windows path +- **WHEN** a reader views the Enterprise Policy location for Windows +- **THEN** the path SHALL be `C:\Program Files\ClaudeCode\CLAUDE.md` + +#### Scenario: Memory type comparison table +- **WHEN** a reader views the memory type comparison table +- **THEN** it SHALL include Project Rules (`.claude/rules/*.md`) and Project Local (`CLAUDE.local.md`) as distinct types + +## ADDED Requirements + +### Requirement: Modular Rules Documentation +The memory lesson SHALL document the `.claude/rules/` directory for organizing instructions into topic-specific markdown files. + +#### Scenario: Rules directory structure +- **WHEN** a reader views the modular rules section +- **THEN** they SHALL see an example directory structure showing `.claude/rules/` with subdirectories + +#### Scenario: Benefits explanation +- **WHEN** a reader views the modular rules section +- **THEN** they SHALL understand the benefits of topic-specific rule files for organization + +### Requirement: Path-Specific Rules Documentation +The memory lesson SHALL document how to use YAML frontmatter with `paths:` directive to scope rules to specific file patterns. + +#### Scenario: YAML frontmatter example +- **WHEN** a reader views the path-specific rules section +- **THEN** they SHALL see an example of YAML frontmatter with `paths:` directive + +#### Scenario: Glob pattern table +- **WHEN** a reader views the path-specific rules section +- **THEN** they SHALL see a table of glob pattern examples with explanations + +### Requirement: Project Local Memory Documentation +The memory lesson SHALL document `CLAUDE.local.md` files for personal project preferences that are auto-gitignored. + +#### Scenario: Local memory explanation +- **WHEN** a reader views the project local memory section +- **THEN** they SHALL understand that `CLAUDE.local.md` is for personal preferences on shared projects + +#### Scenario: Auto-gitignore behavior +- **WHEN** a reader views the project local memory section +- **THEN** they SHALL understand that these files are automatically excluded from git + +### Requirement: Symlink Support Documentation +The memory lesson SHALL document how to share rules across projects using symbolic links. + +#### Scenario: Symlink examples +- **WHEN** a reader views the symlink support section +- **THEN** they SHALL see bash examples for creating symlinks to shared rule files and directories + +### Requirement: Memory Lookup Algorithm Documentation +The memory lesson SHALL document how Claude Code discovers and loads memory files recursively. + +#### Scenario: Recursive search explanation +- **WHEN** a reader views the memory lookup section +- **THEN** they SHALL understand the recursive upward search from current directory to root + +#### Scenario: Subtree discovery +- **WHEN** a reader views the memory lookup section +- **THEN** they SHALL understand that subtree files are discovered when those files are accessed diff --git a/openspec/changes/update-memory-lesson/tasks.md b/openspec/changes/update-memory-lesson/tasks.md new file mode 100644 index 0000000..84c2d66 --- /dev/null +++ b/openspec/changes/update-memory-lesson/tasks.md @@ -0,0 +1,46 @@ +## 1. Update Memory Hierarchy Section +- [ ] 1.1 Update the memory hierarchy table to include 5 levels (Enterprise, Project, Project Rules, User, Project Local) +- [ ] 1.2 Update the mermaid diagram to show the complete hierarchy +- [ ] 1.3 Fix Windows Enterprise Policy path from `C:\ProgramData\ClaudeCode\CLAUDE.md` to `C:\Program Files\ClaudeCode\CLAUDE.md` +- [ ] 1.4 Add explanation of precedence and loading order + +## 2. Add Modular Rules Section +- [ ] 2.1 Create new section "Modular Rules with `.claude/rules/`" +- [ ] 2.2 Add directory structure example showing `.claude/rules/` organization +- [ ] 2.3 Explain benefits of topic-specific rule files +- [ ] 2.4 Add examples of modular rule filenames (code-style.md, testing.md, security.md) + +## 3. Add Path-Specific Rules Section +- [ ] 3.1 Create new section "Path-Specific Rules with Glob Patterns" +- [ ] 3.2 Explain YAML frontmatter with `paths:` directive +- [ ] 3.3 Add table of glob pattern examples (`**/*.ts`, `src/**/*`, etc.) +- [ ] 3.4 Include practical example of path-scoped API rules + +## 4. Add Project Local Memory Section +- [ ] 4.1 Add explanation of `CLAUDE.local.md` file +- [ ] 4.2 Explain auto-gitignore behavior +- [ ] 4.3 Add use case examples (personal preferences on shared projects) + +## 5. Add Symlink Support Section +- [ ] 5.1 Add section on sharing rules across projects using symlinks +- [ ] 5.2 Include bash examples for creating symlinks to shared rules + +## 6. Update Memory Lookup Algorithm +- [ ] 6.1 Add detailed explanation of recursive upward search +- [ ] 6.2 Explain subtree discovery behavior +- [ ] 6.3 Add example of which files are loaded from different directories + +## 7. Update Best Practices +- [ ] 7.1 Add best practices for `.claude/rules/` organization +- [ ] 7.2 Add guidelines for using path-specific rules sparingly +- [ ] 7.3 Add tips for symlink-based rule sharing + +## 8. Update Directory Structure Example +- [ ] 8.1 Update the directory structure to show `.claude/rules/` hierarchy +- [ ] 8.2 Include subdirectory examples (frontend/, backend/) + +## 9. Review and Polish +- [ ] 9.1 Ensure all mermaid diagrams are updated +- [ ] 9.2 Review table formatting consistency +- [ ] 9.3 Update "Official Documentation" links if needed +- [ ] 9.4 Verify all code examples are accurate diff --git a/openspec/specs/skills-lesson/spec.md b/openspec/specs/skills-lesson/spec.md new file mode 100644 index 0000000..6e12f5a --- /dev/null +++ b/openspec/specs/skills-lesson/spec.md @@ -0,0 +1,67 @@ +# skills-lesson Specification + +## Purpose +TBD - created by archiving change update-skills-lesson. Update Purpose after archive. +## Requirements +### Requirement: Managing Skills Documentation +The skills lesson SHALL provide comprehensive guidance for managing skills including viewing available skills, testing skills, updating skills with restart requirements, and removing skills. + +#### Scenario: User wants to view available skills +- **WHEN** a user wants to see what skills are available +- **THEN** the documentation provides both CLI method (asking Claude "What Skills are available?") and filesystem method (ls ~/.claude/skills/ and ls .claude/skills/) + +#### Scenario: User wants to test a skill +- **WHEN** a user wants to test if their skill works +- **THEN** the documentation explains that skills activate automatically based on matching descriptions, with example test queries + +#### Scenario: User wants to update a skill +- **WHEN** a user modifies a SKILL.md file +- **THEN** the documentation explains that changes take effect on next Claude Code startup and restart is required if already running + +#### Scenario: User wants to remove a skill +- **WHEN** a user wants to remove a skill +- **THEN** the documentation provides rm -rf commands for both personal and project skills, with git commit for project skills + +### Requirement: Enhanced Debugging Guidance +The skills lesson SHALL provide detailed debugging guidance for common skill issues including skipped skills, YAML errors, script permissions, and path formats. + +#### Scenario: Skill not being discovered +- **WHEN** Claude doesn't use a user's skill +- **THEN** the documentation explains to check: description specificity, YAML syntax validity (opening/closing ---, no tabs), and correct file path location + +#### Scenario: Skill has errors +- **WHEN** a skill has runtime errors +- **THEN** the documentation explains to check: dependency installation, script execute permissions (chmod +x), and forward slash usage in paths + +#### Scenario: Multiple skills conflict +- **WHEN** multiple skills are activated unexpectedly +- **THEN** the documentation explains using distinct trigger terms in descriptions to help Claude choose the right skill + +### Requirement: Version History Documentation +The skills lesson SHALL include a best practice example for documenting skill version history in SKILL.md files. + +#### Scenario: User wants to track skill versions +- **WHEN** a user maintains a skill over time +- **THEN** the documentation provides a version history markdown template with date and description format + +### Requirement: Enhanced Tool Access Control Documentation +The skills lesson SHALL provide expanded documentation for the allowed-tools feature including use cases, security examples, and behavior when not specified. + +#### Scenario: User wants a read-only skill +- **WHEN** a user wants to create a skill that cannot modify files +- **THEN** the documentation provides an example with allowed-tools: Read, Grep, Glob + +#### Scenario: User wants security-sensitive workflow +- **WHEN** a user has a security-sensitive skill +- **THEN** the documentation explains how allowed-tools restricts Claude's capabilities within that skill context + +#### Scenario: allowed-tools not specified +- **WHEN** a user doesn't specify allowed-tools +- **THEN** the documentation explains that Claude will ask for permission as normal + +### Requirement: Multi-File Skill Example +The skills lesson SHALL include a comprehensive example of a multi-file skill showing directory structure with multiple reference files, scripts, and templates. + +#### Scenario: User wants to create complex skill +- **WHEN** a user needs a skill with supporting files +- **THEN** the documentation provides a complete directory structure example showing SKILL.md, reference files (FORMS.md, REFERENCE.md), scripts subdirectory, and progressive disclosure explanation