docs: Add blog post and new slash commands for development workflow

- Add blog post: 4 Essential Slash Commands I Use in Every Project - Add new slash commands: /doc-refactor, /setup-ci-cd, /unit-test-expand - Update slash-commands README with comprehensive documentation - Simplify /push-all command structure - Archive add-blog-post-slash-commands change - Add blog-post spec and pending openspec changes
2026-07-07 11:17:48 +02:00 · 2025-12-26 11:02:19 +01:00
parent 8ef1e4a0c0
commit 0fcac18357
21 changed files with 1557 additions and 397 deletions
@@ -0,0 +1,163 @@
+# Design: Context Usage Tracking via Hook Pairs
+
+## Context
+
+Users need visibility into token consumption during Claude Code sessions. While Claude Code provides internal context management, users lack tools to:
+- Track token usage per request
+- Monitor cumulative context growth
+- Understand when they're approaching context limits
+
+The existing `Stop` hook example provides cumulative usage but not per-request deltas.
+
+## Goals / Non-Goals
+
+### Goals
+- Document a reliable method to track per-request token consumption
+- Provide a working example users can copy and modify
+- Explain the methodology and its limitations clearly
+- Use existing hook events (`UserPromptSubmit`, `Stop`) without requiring new capabilities
+
+### Non-Goals
+- Implement actual token counting (we use character-based estimation)
+- Access internal Claude Code context metrics
+- Modify Claude Code's behavior or internal state
+- Track system prompt tokens (not in transcript)
+
+## Decisions
+
+### Decision 1: Use UserPromptSubmit + Stop Hook Pair
+**What**: Use `UserPromptSubmit` as the "pre-message" hook and `Stop` as the "post-response" hook.
+
+**Why**: These are the natural lifecycle points:
+- `UserPromptSubmit` fires before the prompt is sent to the model
+- `Stop` fires after Claude completes its response
+
+**Alternatives Considered**:
+| Option | Pros | Cons |
+|--------|------|------|
+| SessionStart + Stop | Captures full session | No per-request granularity |
+| PreToolUse + PostToolUse | Captures tool overhead | Missing prompt/response tokens |
+| UserPromptSubmit + Stop | Natural request boundaries | Requires temp file for state |
+
+### Decision 2: Use Temp File for State Persistence
+**What**: Store pre-message token count in a temp file keyed by session ID.
+
+**Why**: Hooks are stateless processes; we need persistence between the two hook invocations.
+
+**Implementation**:
+```python
+import tempfile
+import os
+
+def get_state_file(session_id: str) -> str:
+    return os.path.join(tempfile.gettempdir(), f"claude-tokens-{session_id}.json")
+```
+
+### Decision 3: Single Script with Mode Detection
+**What**: One Python script handles both hooks, detecting mode via `hook_event_name`.
+
+**Why**:
+- Reduces file count and complexity
+- Ensures consistent token calculation logic
+- Easier for users to understand and modify
+
+**Structure**:
+```python
+def main():
+    data = json.load(sys.stdin)
+    event = data.get("hook_event_name")
+
+    if event == "UserPromptSubmit":
+        record_pre_message_count(data)
+    elif event == "Stop":
+        report_delta(data)
+```
+
+### Decision 4: Two Offline Token Counting Methods (No API Key)
+**What**: Provide two offline methods - tiktoken-based and simple character estimation.
+
+**Why**:
+- No API key should be required for context tracking hooks
+- Anthropic hasn't released an official offline tokenizer
+- Users have different dependency tolerance levels
+
+#### Method A: tiktoken with p50k_base (Recommended)
+
+```python
+import tiktoken
+
+def count_tokens_tiktoken(text: str) -> int:
+    enc = tiktoken.get_encoding("p50k_base")
+    return len(enc.encode(text))
+```
+
+**Characteristics**:
+- ~90-95% accuracy compared to Claude's actual tokenizer
+- Works completely offline
+- Requires `tiktoken` dependency
+- Fast execution (<10ms)
+
+#### Method B: Character-Based Estimation (Zero Dependencies)
+
+```python
+def count_tokens_estimate(text: str) -> int:
+    return len(text) // 4
+```
+
+**Characteristics**:
+- ~80-90% accuracy for English text
+- No dependencies at all
+- Sub-millisecond latency
+- Less accurate for code and non-English text
+
+**Trade-off Matrix**:
+
+| Factor | tiktoken | Estimation |
+|--------|----------|------------|
+| Accuracy | ~90-95% | ~80-90% |
+| Speed | <10ms | <1ms |
+| Dependencies | tiktoken | None |
+| Offline | Yes | Yes |
+
+**Note**: Anthropic hasn't released their official tokenizer publicly. The `tiktoken` approach uses OpenAI's tokenizer with `p50k_base` encoding as a reasonable approximation since both use BPE (byte-pair encoding).
+
+## Token Delta Calculation Flow
+
+```
+UserPromptSubmit                    Stop
+     |                               |
+     v                               v
+Read transcript               Read transcript
+     |                               |
+     v                               v
+Count characters             Count characters
+     |                               |
+     v                               v
+Estimate tokens (T1)         Estimate tokens (T2)
+     |                               |
+     v                               v
+Save T1 to temp file         Calculate delta = T2 - T1
+                                     |
+                                     v
+                             Report: "Request used ~X tokens"
+```
+
+## Risks / Trade-offs
+
+| Risk | Mitigation |
+|------|------------|
+| Temp file not found (hook failures) | Graceful fallback to cumulative-only reporting |
+| Inaccurate token estimates | Clear documentation of limitations |
+| Race conditions (concurrent sessions) | Session ID in filename for isolation |
+| Temp file cleanup | Use system temp directory (auto-cleaned) |
+
+## Example Output Format
+
+```
+Context Usage: ~12,500 tokens used (~125,000 remaining)
+This request: ~850 tokens (+6.8% of total)
+```
+
+## Open Questions
+
+None - design is straightforward given existing hook capabilities.
@@ -0,0 +1,100 @@
+# Change: Add Context Usage Tracking Documentation via Pre-Message and Post-Response Hooks
+
+## Why
+
+Users want to monitor token consumption per request and overall context usage throughout a Claude Code session. Currently, the hooks documentation shows a basic context-usage example using the Stop hook, but it doesn't demonstrate how to track **per-request** token consumption by comparing measurements at two points in time.
+
+By documenting how to use `UserPromptSubmit` as a "pre-message" hook and `Stop` as a "post-response" hook, users can calculate the delta in token usage for each request, enabling accurate per-request consumption metrics.
+
+## What Changes
+
+- **ADDED**: Documentation for using `UserPromptSubmit` and `Stop` hooks together for context tracking
+- **ADDED**: A new example demonstrating token delta calculation between pre-message and post-response
+- **MODIFIED**: Enhance the existing context usage reporting requirement with delta-based tracking approach
+- **ADDED**: Detailed explanation of token estimation methodology and its limitations
+
+## Impact
+
+- Affected specs: `hooks-documentation`
+- Affected code: `06-hooks/README.md` (documentation updates)
+- No breaking changes - purely additive documentation
+
+## Technical Analysis
+
+### Current Hook Events Mapping
+
+| Desired Hook | Claude Code Event | Trigger Point |
+|--------------|-------------------|---------------|
+| Pre-Message Hook | `UserPromptSubmit` | Before user prompt is processed by the model |
+| Post-Response Hook | `Stop` | After model completes its full response |
+
+### Token Counting Methods (Offline, No API Key)
+
+Since we need offline token counting without an API key, we offer **two local approaches**:
+
+#### Method 1: tiktoken with p50k_base (More Accurate)
+
+Use OpenAI's `tiktoken` library with the `p50k_base` encoding as an approximation for Claude's tokenizer:
+
+```python
+import tiktoken
+
+enc = tiktoken.get_encoding("p50k_base")
+tokens = enc.encode(text)
+token_count = len(tokens)
+```
+
+**Pros:**
+- More accurate than character estimation (~90-95% accuracy)
+- Works completely offline
+- No API key required
+- Fast execution
+
+**Cons:**
+- Requires `tiktoken` dependency (`pip install tiktoken`)
+- Not Claude's exact tokenizer (approximation)
+
+#### Method 2: Character-Based Estimation (Simplest)
+
+For zero-dependency estimation:
+
+```python
+estimated_tokens = len(text) // 4
+```
+
+**Pros:**
+- No dependencies at all
+- Works offline
+- Extremely fast
+
+**Cons:**
+- Less accurate (~80-90% for English text)
+- Varies more with code and non-English text
+
+### Token Delta Calculation Approach
+
+1. **Pre-Message (UserPromptSubmit)**: Read transcript, count tokens (via tiktoken or estimation)
+2. **Post-Response (Stop)**: Read transcript again, calculate new total, compute delta
+
+**Accuracy Evaluation:**
+
+| Factor | tiktoken Method | Character Estimation |
+|--------|-----------------|---------------------|
+| Token accuracy | ~90-95% | ~80-90% |
+| Dependencies | tiktoken | None |
+| Speed | Fast (<10ms) | Very fast (<1ms) |
+| Offline | Yes | Yes |
+
+### Limitations
+
+- **No official offline Claude tokenizer exists** - Anthropic hasn't released their tokenizer publicly
+- System prompts and internal Claude Code context are NOT in the transcript
+- The delta includes: user prompt + Claude's response + any tool outputs
+- Both methods are approximations; actual API token counts may differ slightly
+
+## Open Questions
+
+1. Should we persist the pre-message count to a file, or can we rely on the hook's transient state?
+   - **Recommendation**: Use a simple temp file in the session directory for reliability
+2. Should the example be a single Python script handling both hooks, or two separate scripts?
+   - **Recommendation**: Single script with mode detection based on `hook_event_name`
@@ -0,0 +1,106 @@
+# hooks-documentation Spec Delta
+
+## ADDED Requirements
+
+### Requirement: Pre-Message and Post-Response Hook Pairs Documentation
+The hooks lesson SHALL document how to use `UserPromptSubmit` and `Stop` hooks together for context/token usage tracking.
+
+#### Scenario: Understanding hook event timing for context tracking
+- **WHEN** a user wants to track per-request token consumption
+- **THEN** they find documentation explaining that `UserPromptSubmit` fires before the prompt is processed (pre-message)
+- **AND** they find documentation explaining that `Stop` fires after Claude completes its response (post-response)
+- **AND** they understand how to calculate the delta between these two points
+
+#### Scenario: Token delta calculation methodology
+- **WHEN** a user implements a context tracking hook pair
+- **THEN** they find documentation explaining how to:
+  - Record token count at `UserPromptSubmit` time
+  - Calculate new token count at `Stop` time
+  - Compute the delta representing per-request consumption
+
+### Requirement: Context Tracking Hook Pair Example
+The hooks lesson SHALL provide a working example script that tracks context usage using pre-message and post-response hooks.
+
+#### Scenario: Single script handles both hook events
+- **WHEN** a user copies the context-tracker.py example
+- **THEN** the script detects the hook event type via `hook_event_name`
+- **AND** handles `UserPromptSubmit` by saving current token estimate to a temp file
+- **AND** handles `Stop` by loading the saved count, calculating delta, and reporting usage
+
+#### Scenario: Complete configuration for hook pair
+- **WHEN** a user wants to configure both hooks
+- **THEN** they find a complete settings.json example showing:
+  - `UserPromptSubmit` hook configuration pointing to the context tracker script
+  - `Stop` hook configuration pointing to the same script
+  - Both hooks using the same script for consistent token calculation
+
+#### Scenario: Per-request usage reporting
+- **WHEN** the context tracking hooks execute
+- **THEN** the Stop hook outputs a report showing:
+  - Total estimated tokens used in session
+  - Tokens consumed by the current request (delta)
+  - Remaining capacity estimate
+
+### Requirement: Token Counting Methods Documentation
+The hooks lesson SHALL document two offline token counting methods that require no API key.
+
+#### Scenario: tiktoken-based token counting documented
+- **WHEN** a user wants more accurate offline token counts
+- **THEN** they find documentation for using `tiktoken` with `p50k_base` encoding
+- **AND** they see a Python example using `tiktoken.get_encoding("p50k_base")`
+- **AND** they understand it provides ~90-95% accuracy compared to Claude's tokenizer
+- **AND** they learn it requires the `tiktoken` dependency
+
+#### Scenario: Character estimation token counting documented
+- **WHEN** a user wants zero-dependency token estimation
+- **THEN** they find documentation for the ~4 characters per token estimation ratio
+- **AND** they understand this provides ~80-90% accuracy for English text
+- **AND** they learn it works with no external dependencies
+
+#### Scenario: Method comparison provided
+- **WHEN** a user needs to choose between token counting methods
+- **THEN** they find a comparison showing:
+  - tiktoken method: ~90-95% accuracy, requires tiktoken, <10ms latency
+  - Estimation method: ~80-90% accuracy, no dependencies, <1ms latency
+- **AND** both methods work completely offline without API keys
+
+#### Scenario: Transcript contents explained
+- **WHEN** a user wants to understand what's included in token counts
+- **THEN** they find documentation explaining that the transcript includes:
+  - User prompts
+  - Claude's responses
+  - Tool inputs and outputs
+- **AND** they understand that system prompts and internal context are NOT included
+
+#### Scenario: No official Claude tokenizer caveat
+- **WHEN** a user reads about token counting accuracy
+- **THEN** they understand that Anthropic hasn't released an official offline tokenizer
+- **AND** they understand both methods are approximations based on similar BPE tokenizers
+
+## 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
+
+#### Scenario: Delta-based tracking is documented
+- **WHEN** a user wants per-request token consumption
+- **THEN** they find documentation pointing to the pre-message/post-response hook pair approach
+- **AND** they understand how to use `UserPromptSubmit` + `Stop` for delta calculation
@@ -0,0 +1,36 @@
+# Tasks: Add Context Usage Tracking Documentation
+
+## 1. Documentation Updates
+
+- [x] 1.1 Add "Context Tracking Hook Pairs" section to README explaining pre-message/post-response concept
+- [x] 1.2 Document how UserPromptSubmit serves as pre-message hook
+- [x] 1.3 Document how Stop serves as post-response hook
+- [x] 1.4 Explain token delta calculation methodology
+
+## 2. Example Scripts
+
+- [x] 2.1 Create `context-tracker.py` example script with character estimation (zero dependencies)
+- [x] 2.2 Create `context-tracker-tiktoken.py` example script with tiktoken method (more accurate)
+- [x] 2.3 Implement UserPromptSubmit handler (save pre-message count)
+- [x] 2.4 Implement Stop handler (calculate and report delta)
+- [x] 2.5 Add clear inline comments explaining both approaches
+
+## 3. Configuration Examples
+
+- [x] 3.1 Add hook configuration example for UserPromptSubmit event
+- [x] 3.2 Add hook configuration example for Stop event
+- [x] 3.3 Provide combined configuration showing both hooks together
+
+## 4. Token Counting Methods Documentation
+
+- [x] 4.1 Document tiktoken with p50k_base method (more accurate, ~90-95%)
+- [x] 4.2 Document character-based estimation method (simple, ~80-90%)
+- [x] 4.3 Create comparison table of both offline methods
+- [x] 4.4 Explain what's included/excluded from transcript
+- [x] 4.5 Add caveat that no official Claude offline tokenizer exists
+
+## 5. Validation
+
+- [x] 5.1 Test example script with sample JSON input
+- [x] 5.2 Verify configuration examples have valid JSON syntax
+- [x] 5.3 Run openspec validate to confirm proposal is complete
@@ -0,0 +1,23 @@
+# Change: Add Blog Post - 4 Essential Slash Commands for Development Workflow
+
+## Why
+
+The claude-howto project provides excellent reference documentation but lacks blog-style content that showcases real-world usage patterns. Users have found 4 slash commands particularly valuable across their development workflow, and a blog post explaining when/where/how to use each would help others adopt these productivity tools.
+
+## What Changes
+
+- Create new `blog-post/` directory for blog content
+- Add blog post: "4 Essential Slash Commands I Use in Every Project"
+- Cover 4 commands with practical guidance:
+  - `/push-all` - Quick deployment of coherent changes
+  - `/setup-ci-cd` - Post-POC quality infrastructure
+  - `/doc-refactor` - Post-MVP documentation polish
+  - `/unit-test-expand` - Milestone-driven test expansion
+- Reference the first slash commands blog: [Discovering Claude Code Slash Commands](https://medium.com/@luongnv89/discovering-claude-code-slash-commands-cdc17f0dfb29)
+- Link to full command files when content exceeds 30 lines
+
+## Impact
+
+- Affected specs: None (new capability)
+- Affected code: New `blog-post/` directory and content
+- No breaking changes
@@ -0,0 +1,41 @@
+## ADDED Requirements
+
+### Requirement: Blog Post Directory Structure
+
+The project SHALL provide a `blog-post/` directory for hosting blog-style content that complements the reference documentation.
+
+#### Scenario: Blog post directory exists
+- **WHEN** a user navigates to the project root
+- **THEN** a `blog-post/` directory is present containing blog content
+
+### Requirement: Slash Commands Usage Blog Post
+
+The blog SHALL document 4 essential slash commands with practical usage guidance covering when, where, and how to use each command in a development workflow.
+
+#### Scenario: Complete command coverage
+- **WHEN** a user reads the blog post
+- **THEN** they find documentation for `/push-all`, `/setup-ci-cd`, `/doc-refactor`, and `/unit-test-expand`
+
+#### Scenario: Command file linking for long content
+- **WHEN** a command file exceeds 30 lines
+- **THEN** the blog SHALL provide a link to the full command file in the claude-howto project
+
+#### Scenario: Inline content for short commands
+- **WHEN** a command file is 30 lines or fewer
+- **THEN** the blog MAY include the command content inline
+
+### Requirement: Development Workflow Context
+
+Each command section SHALL explain when to use the command in the development lifecycle (POC, MVP, milestone phases).
+
+#### Scenario: Workflow phase guidance
+- **WHEN** a user reads a command section
+- **THEN** they understand which development phase the command is most appropriate for
+
+### Requirement: Reference to First Blog
+
+The blog post SHALL reference the introductory slash commands blog: "Discovering Claude Code Slash Commands" for foundational context.
+
+#### Scenario: Blog reference present
+- **WHEN** a user reads the introduction
+- **THEN** they find a link to the original slash commands blog post on Medium
@@ -0,0 +1,25 @@
+## 1. Setup
+
+- [x] 1.1 Create `blog-post/` directory at project root
+
+## 2. Blog Post Creation
+
+- [x] 2.1 Create blog post markdown file with proper structure
+- [x] 2.2 Write introduction referencing first slash commands blog
+- [x] 2.3 Document `/push-all` with link to full command (152 lines)
+- [x] 2.4 Document `/setup-ci-cd` with inline content (25 lines)
+- [x] 2.5 Document `/doc-refactor` with inline content (23 lines)
+- [x] 2.6 Document `/unit-test-expand` with inline content (24 lines)
+- [x] 2.7 Add workflow diagram showing when to use each command
+- [x] 2.8 Write conclusion with development lifecycle integration
+
+## 3. Integration
+
+- [x] 3.1 Add blog-post to main README navigation
+- [x] 3.2 Cross-reference from slash-commands README
+
+## 4. Verification
+
+- [x] 4.1 Verify all internal links work
+- [x] 4.2 Verify external links are valid
+- [x] 4.3 Review content for clarity and accuracy
@@ -0,0 +1,20 @@
+# Change: Update Slash Commands README with New Commands
+
+## Why
+
+The `01-slash-commands/README.md` is outdated and needs to reflect:
+1. Updated `push-all.md` command with enhanced safety checks (API key validation, confirmation workflow)
+2. Three new slash commands added to the folder: `doc-refactor.md`, `setup-ci-cd.md`, `unit-test-expand.md`
+
+## What Changes
+
+- **Update push-all documentation**: Reflect the enhanced workflow including safety checks, API key validation, and confirmation prompts
+- **Add doc-refactor command**: Document the new documentation restructuring command
+- **Add setup-ci-cd command**: Document the new CI/CD pipeline setup command
+- **Add unit-test-expand command**: Document the new test coverage expansion command
+- Update "Available Commands" section count from 4 to 7 commands
+
+## Impact
+
+- Affected specs: `slash-commands`
+- Affected code: `01-slash-commands/README.md`
@@ -0,0 +1,66 @@
+## ADDED Requirements
+
+### Requirement: Push-All Command with Safety Checks
+
+The documentation SHALL describe the `/push-all` command with its comprehensive safety workflow including:
+1. Change analysis (git status, diff, log)
+2. Safety checks for secrets, API keys, large files, build artifacts
+3. API key validation distinguishing real keys from placeholders
+4. Confirmation prompt before proceeding
+5. Conventional commit message generation
+6. Error handling guidance
+
+#### Scenario: User learns push-all safety workflow
+- **WHEN** a user reads the push-all command documentation
+- **THEN** they understand the multi-step safety workflow
+- **AND** they know what types of files trigger warnings
+- **AND** they understand they must confirm before execution
+
+---
+
+### Requirement: Doc-Refactor Command Documentation
+
+The documentation SHALL describe the `/doc-refactor` command for restructuring project documentation including:
+1. Project type analysis (library, API, web app, CLI, microservices)
+2. Documentation centralization in `docs/` folder
+3. Root README streamlining
+4. Component-level documentation
+5. Guide creation based on project type
+
+#### Scenario: User uses doc-refactor command
+- **WHEN** a user reads the doc-refactor documentation
+- **THEN** they understand how to invoke the command
+- **AND** they know what documentation structure changes to expect
+- **AND** they understand the command adapts to project type
+
+---
+
+### Requirement: Setup-CI-CD Command Documentation
+
+The documentation SHALL describe the `/setup-ci-cd` command for implementing quality gates including:
+1. Project analysis for language and tooling detection
+2. Pre-commit hook configuration with language-specific tools
+3. GitHub Actions workflow creation
+4. Pipeline verification steps
+
+#### Scenario: User uses setup-ci-cd command
+- **WHEN** a user reads the setup-ci-cd documentation
+- **THEN** they understand the command creates pre-commit hooks
+- **AND** they know GitHub Actions workflows will be generated
+- **AND** they understand tools are selected based on project language
+
+---
+
+### Requirement: Unit-Test-Expand Command Documentation
+
+The documentation SHALL describe the `/unit-test-expand` command for increasing test coverage including:
+1. Coverage analysis to identify gaps
+2. Gap identification (branches, error paths, boundaries)
+3. Framework-specific test generation
+4. Coverage verification
+
+#### Scenario: User uses unit-test-expand command
+- **WHEN** a user reads the unit-test-expand documentation
+- **THEN** they understand the command analyzes existing coverage
+- **AND** they know it targets untested branches and edge cases
+- **AND** they understand it works with their project's testing framework
@@ -0,0 +1,7 @@
+## 1. Implementation
+
+- [x] 1.1 Update `/push-all` section in README to reflect enhanced safety checks (API key validation, confirmation workflow, detailed error handling)
+- [x] 1.2 Add `/doc-refactor` section documenting the documentation restructuring command
+- [x] 1.3 Add `/setup-ci-cd` section documenting the CI/CD pipeline setup command
+- [x] 1.4 Add `/unit-test-expand` section documenting the test coverage expansion command
+- [x] 1.5 Update section heading to reflect 8 available commands (was 4, added 4 new)