diff --git a/01-slash-commands/README.md b/01-slash-commands/README.md index aba26b2..717788c 100644 --- a/01-slash-commands/README.md +++ b/01-slash-commands/README.md @@ -4,7 +4,254 @@ ## Overview -Slash commands are user-invoked shortcuts stored as Markdown files that Claude Code can execute. They enable teams to standardize frequently-used prompts and workflows. +Slash commands are tools that control Claude's behavior during an interactive session. They enable teams to standardize frequently-used prompts and workflows, and come in several types with different capabilities. + +## Types of Slash Commands + +| Type | Description | Example | +|------|-------------|---------| +| **Built-in** | Commands provided by Claude Code | `/help`, `/clear`, `/model` | +| **Custom** | User-defined Markdown files | `/optimize`, `/pr` | +| **Plugin** | Commands from installed plugins | `/frontend-design:frontend-design` | +| **MCP** | Commands from MCP servers | `/mcp__github__list_prs` | + +## Built-in Commands Reference + +Claude Code provides these built-in slash commands: + +| Command | Purpose | +|---------|---------| +| `/add-dir` | Add additional working directories | +| `/agents` | Manage custom AI subagents for specialized tasks | +| `/bashes` | List and manage background tasks | +| `/bug` | Report bugs (sends conversation to Anthropic) | +| `/clear` | Clear conversation history | +| `/compact [instructions]` | Compact conversation with optional focus instructions | +| `/config` | Open the Settings interface (Config tab) | +| `/context` | Visualize current context usage as a colored grid | +| `/cost` | Show token usage statistics | +| `/doctor` | Checks the health of your Claude Code installation | +| `/exit` | Exit the REPL | +| `/export [filename]` | Export the current conversation to a file or clipboard | +| `/help` | Get usage help | +| `/hooks` | Manage hook configurations for tool events | +| `/ide` | Manage IDE integrations and show status | +| `/init` | Initialize project with `CLAUDE.md` guide | +| `/install-github-app` | Set up Claude GitHub Actions for a repository | +| `/login` | Switch Anthropic accounts | +| `/logout` | Sign out from your Anthropic account | +| `/mcp` | Manage MCP server connections and OAuth authentication | +| `/memory` | Edit `CLAUDE.md` memory files | +| `/model` | Select or change the AI model | +| `/output-style [style]` | Set the output style directly or from a selection menu | +| `/permissions` | View or update permissions | +| `/plugin` | Manage Claude Code plugins | +| `/pr-comments` | View pull request comments | +| `/privacy-settings` | View and update your privacy settings | +| `/release-notes` | View release notes | +| `/rename ` | Rename the current session | +| `/resume [session]` | Resume a conversation by ID or name | +| `/review` | Request code review | +| `/rewind` | Rewind the conversation and/or code | +| `/sandbox` | Enable sandboxed bash tool with filesystem and network isolation | +| `/security-review` | Complete a security review of pending changes | +| `/stats` | Visualize daily usage, session history, streaks, and model preferences | +| `/status` | Open the Settings interface (Status tab) | +| `/statusline` | Set up Claude Code's status line UI | +| `/terminal-setup` | Install Shift+Enter key binding for newlines | +| `/todos` | List current TODO items | +| `/usage` | Show plan usage limits and rate limit status | +| `/vim` | Enter vim mode for alternating insert and command modes | + +## Custom Slash Commands + +Custom slash commands allow you to define frequently used prompts as Markdown files that Claude Code can execute. + +### File Locations + +| Location | Scope | Label in `/help` | Use Case | +|----------|-------|------------------|----------| +| `.claude/commands/` | Project-specific | `(project)` | Team workflows, shared standards | +| `~/.claude/commands/` | Personal | `(user)` | Personal shortcuts across projects | + +**Priority:** Project commands take precedence over personal commands with the same name. + +### Namespacing with Subdirectories + +Use subdirectories to group related commands: + +``` +.claude/commands/ +├── frontend/ +│ └── component.md → /component (project:frontend) +├── deploy/ +│ ├── production.md → /production (project:deploy) +│ └── staging.md → /staging (project:deploy) +└── optimize.md → /optimize (project) +``` + +### Arguments + +Commands can receive arguments in two ways: + +**All arguments with `$ARGUMENTS`:** + +```markdown +# .claude/commands/fix-issue.md +Fix issue #$ARGUMENTS following our coding standards +``` + +Usage: `/fix-issue 123 high-priority` → `$ARGUMENTS` becomes "123 high-priority" + +**Individual arguments with `$1`, `$2`, etc.:** + +```markdown +# .claude/commands/review-pr.md +Review PR #$1 with priority $2 and assign to $3 +``` + +Usage: `/review-pr 456 high alice` → `$1`="456", `$2`="high", `$3`="alice" + +### Bash Command Execution + +Execute bash commands before the slash command runs using the `!` prefix: + +```markdown +--- +allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*) +description: Create a git commit +--- + +## Context + +- Current git status: !`git status` +- Current git diff: !`git diff HEAD` +- Current branch: !`git branch --show-current` +- Recent commits: !`git log --oneline -10` + +## Your task + +Based on the above changes, create a single git commit. +``` + +### File References + +Include file contents in commands using the `@` prefix: + +```markdown +# Reference a specific file +Review the implementation in @src/utils/helpers.js + +# Reference multiple files +Compare @src/old-version.js with @src/new-version.js +``` + +### Thinking Mode + +Slash commands can trigger extended thinking by including extended thinking keywords in the command content. + +## Frontmatter + +Command files support YAML frontmatter for configuration: + +```markdown +--- +allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*) +argument-hint: [message] +description: Create a git commit +model: claude-3-5-haiku-20241022 +--- + +Create a git commit with message: $ARGUMENTS +``` + +### Frontmatter Fields + +| Field | Purpose | Default | +|-------|---------|---------| +| `allowed-tools` | List of tools the command can use | Inherits from conversation | +| `argument-hint` | Expected arguments for auto-completion | None | +| `description` | Brief description of the command | Uses first line from prompt | +| `model` | Specific model to use | Inherits from conversation | +| `disable-model-invocation` | Prevent SlashCommand tool from calling this | `false` | + +## Plugin Commands + +Plugins can provide custom slash commands that integrate with Claude Code: + +``` +/plugin-name:command-name +``` + +Or simply `/command-name` when there are no naming conflicts. + +**Examples:** +```bash +/frontend-design:frontend-design +/commit-commands:commit +/code-review:code-review +``` + +## MCP Slash Commands + +MCP servers can expose prompts as slash commands: + +``` +/mcp____ [arguments] +``` + +**Examples:** +```bash +/mcp__github__list_prs +/mcp__github__pr_review 456 +/mcp__jira__create_issue "Bug title" high +``` + +## SlashCommand Tool + +Claude can programmatically invoke custom slash commands using the SlashCommand tool. + +### Enabling Programmatic Invocation + +Reference the command in your prompt or `CLAUDE.md`: + +```markdown +> Run /write-unit-test when you are about to start writing tests. +``` + +### Disabling for Specific Commands + +Use the `disable-model-invocation` frontmatter field: + +```markdown +--- +disable-model-invocation: true +--- +``` + +Or disable via permissions: +``` +/permissions +# Add to deny rules: SlashCommand +``` + +### Character Budget + +- **Default limit:** 15,000 characters +- **Custom limit:** Set via `SLASH_COMMAND_TOOL_CHAR_BUDGET` environment variable + +## Skills vs Slash Commands + +| Aspect | Slash Commands | Skills | +|--------|----------------|--------| +| **Best for** | Quick, frequently used prompts | Comprehensive capabilities with structure | +| **Files** | Single `.md` file | Directory with `SKILL.md` + resources | +| **Invocation** | Explicit (`/command`) | Automatic (context-based) | +| **Complexity** | Simple prompts | Complex workflows with multiple steps | + +**Use slash commands** when you invoke the same prompt repeatedly and it fits in a single file. + +**Use skills** when Claude should discover the capability automatically or multiple files/scripts are needed. ## Architecture @@ -17,48 +264,26 @@ graph TD E -->|Returns| F["Result in Context"] ``` -## File Structure +## Command Lifecycle Diagram ```mermaid -graph LR - A["Project Root"] -->|contains| B[".claude/commands/"] - B -->|contains| C["optimize.md"] - B -->|contains| D["test.md"] - B -->|contains| E["docs/"] - E -->|contains| F["generate-api-docs.md"] - E -->|contains| G["generate-readme.md"] +sequenceDiagram + participant User + participant Claude as Claude Code + participant FS as File System + participant CLI as Shell/Bash + + User->>Claude: Types /optimize + Claude->>FS: Searches .claude/commands/ + FS-->>Claude: Returns optimize.md + Claude->>Claude: Loads Markdown content + Claude->>User: Displays prompt context + User->>Claude: Provides code to analyze + Claude->>CLI: (May execute scripts) + CLI-->>Claude: Results + Claude->>User: Returns analysis ``` -### Recommended Structure - -``` -project/ -├── .claude/ -│ └── commands/ -│ ├── optimize.md -│ ├── pr.md -│ └── docs/ -│ └── generate-api-docs.md -``` - -## Command Organization Table - -| Location | Scope | Availability | Use Case | Git Tracked | -|----------|-------|--------------|----------|-------------| -| `.claude/commands/` | Project-specific | Team members | Team workflows, shared standards | ✅ Yes | -| `~/.claude/commands/` | Personal | Individual user | Personal shortcuts across projects | ❌ No | -| Subdirectories | Namespaced | Based on parent | Organize by category | ✅ Yes | - -## Features & Capabilities - -| Feature | Example | Supported | -|---------|---------|-----------| -| Shell script execution | `bash scripts/deploy.sh` | ✅ Yes | -| File references | `@path/to/file.js` | ✅ Yes | -| Bash integration | `$(git log --oneline)` | ✅ Yes | -| Arguments | `/pr --verbose` | ✅ Yes | -| MCP commands | `/mcp__github__list_prs` | ✅ Yes | - ## Available Commands in This Folder ### 1. `/optimize` - Code Optimization @@ -112,25 +337,18 @@ Generates comprehensive API documentation from source code. - Includes request/response schemas - Adds error documentation -## Command Lifecycle Diagram +### 4. `/commit` - Git Commit with Context +Creates a git commit with dynamic context from your repository. -```mermaid -sequenceDiagram - participant User - participant Claude as Claude Code - participant FS as File System - participant CLI as Shell/Bash - - User->>Claude: Types /optimize - Claude->>FS: Searches .claude/commands/ - FS-->>Claude: Returns optimize.md - Claude->>Claude: Loads Markdown content - Claude->>User: Displays prompt context - User->>Claude: Provides code to analyze - Claude->>CLI: (May execute scripts) - CLI-->>Claude: Results - Claude->>User: Returns analysis +**Usage:** ``` +/commit [optional message] +``` + +**Features:** +- Automatically includes git status, diff, and recent commits +- Uses `allowed-tools` for git operations +- Supports optional commit message argument ## Installation @@ -144,9 +362,6 @@ mkdir -p .claude/commands # Copy command files cp 01-slash-commands/*.md .claude/commands/ - -# Copy subdirectory commands -cp -r 01-slash-commands/docs .claude/commands/ ``` ### For Personal Use @@ -169,9 +384,8 @@ Create a file `.claude/commands/my-command.md`: ```markdown --- -name: My Command Name description: What this command does -tags: category, task-type +argument-hint: [optional-args] --- # Command Title @@ -187,184 +401,42 @@ Output format: - What to include ``` -### Command with Frontmatter +### Command with Full Frontmatter ```markdown --- -name: Code Optimization -description: Analyze code for performance issues and suggest optimizations -tags: performance, analysis ---- - -# Code Optimization - -Review the provided code for the following issues in order of priority: - -1. **Performance bottlenecks** - identify O(n²) operations, inefficient loops -2. **Memory leaks** - find unreleased resources, circular references -3. **Algorithm improvements** - suggest better algorithms or data structures - -Format your response with: -- Issue severity (Critical/High/Medium/Low) -- Location in code -- Explanation -- Recommended fix with code example -``` - -## Best Practices - -| ✅ Do | ❌ Don't | -|------|---------| -| Use clear, action-oriented names | Create commands for one-time tasks | -| Document trigger words in description | Build complex logic in commands | -| Keep commands focused on single task | Create redundant commands | -| Version control project commands | Hardcode sensitive information | -| Organize in subdirectories | Create long lists of commands | -| Use simple, readable prompts | Use abbreviated or cryptic wording | - -## Examples - -### Example 1: Simple Task Automation - -**File:** `.claude/commands/test.md` - -```markdown ---- -name: Run Tests -description: Execute test suite with coverage report +allowed-tools: Bash(npm test:*), Bash(npm run lint:*) +argument-hint: [--verbose] [--coverage] +description: Run tests with optional coverage report +model: claude-3-5-haiku-20241022 --- # Test Runner -1. Run the test suite: `npm test` -2. Generate coverage report -3. Summarize results -4. Highlight any failures +Run the project tests with the following options: +- Arguments provided: $ARGUMENTS + +## Context +- Current branch: !`git branch --show-current` +- Package.json scripts: @package.json + +## Steps +1. Run `npm test` +2. If --coverage flag provided, generate coverage report +3. Summarize results and highlight any failures ``` -### Example 2: Multi-step Workflow +## Best Practices -**File:** `.claude/commands/deploy.md` - -```markdown ---- -name: Deploy to Production -description: Complete deployment workflow with checks ---- - -# Production Deployment - -Execute these steps in order: - -1. **Pre-deployment checks** - - Run `npm run lint` - - Run `npm test` - - Check git status is clean - -2. **Build** - - Run `npm run build` - - Verify build artifacts - -3. **Deploy** - - Run `npm run deploy` - - Monitor deployment logs - -4. **Post-deployment** - - Run smoke tests - - Verify deployment - - Notify team -``` - -### Example 3: Code Review Command - -**File:** `.claude/commands/review.md` - -```markdown ---- -name: Code Review -description: Comprehensive code review checklist ---- - -# Code Review - -Review the code for: - -## Security -- [ ] No hardcoded credentials -- [ ] Input validation present -- [ ] SQL injection prevention -- [ ] XSS prevention - -## Performance -- [ ] No N+1 queries -- [ ] Appropriate indexing -- [ ] Efficient algorithms - -## Quality -- [ ] Clear naming -- [ ] Proper error handling -- [ ] Adequate comments -- [ ] No code duplication -``` - -## Advanced Usage - -### Using Arguments - -Commands can accept arguments: - -```bash -/deploy production -/review --verbose -/test --coverage -``` - -Handle arguments in your command file: - -```markdown -# Deployment Command - -Check the provided argument for environment: -- If "production", use strict checks -- If "staging", allow warnings -- If "development", skip certain validations -``` - -### Integrating with MCP - -Commands can use MCP tools: - -```markdown -# GitHub PR Command - -1. Use MCP to list open PRs: `/mcp__github__list_prs` -2. Analyze each PR for: - - Review status - - CI/CD status - - Merge conflicts -3. Provide summary -``` - -### Hierarchical Commands - -Organize related commands in subdirectories: - -``` -.claude/commands/ -├── deploy/ -│ ├── production.md -│ ├── staging.md -│ └── rollback.md -├── test/ -│ ├── unit.md -│ ├── integration.md -│ └── e2e.md -└── docs/ - ├── api.md - └── readme.md -``` - -Access with: `/deploy/production`, `/test/unit`, `/docs/api` +| Do | Don't | +|------|---------| +| Use clear, action-oriented names | Create commands for one-time tasks | +| Include `description` in frontmatter | Build complex logic in commands | +| Keep commands focused on single task | Create redundant commands | +| Version control project commands | Hardcode sensitive information | +| Organize in subdirectories | Create long lists of commands | +| Use `$ARGUMENTS` or `$1`, `$2` for dynamic input | Use abbreviated or cryptic wording | +| Use `!` prefix for dynamic context | Assume Claude knows current state | ## Troubleshooting @@ -387,6 +459,7 @@ Access with: `/deploy/production`, `/test/unit`, `/docs/api` - Add more specific instructions - Include examples in command file - Test with simple inputs first +- Check `allowed-tools` if using bash commands ### Personal vs Project Commands @@ -411,10 +484,9 @@ Access with: `/deploy/production`, `/test/unit`, `/docs/api` ## Resources -- [Discovering Claude Code Slash Commands](https://medium.com/@luongnv89/discovering-claude-code-slash-commands-cdc17f0dfb29) - Comprehensive blog post exploring slash commands -- [Claude Code Commands Documentation](https://docs.claude.com/en/docs/claude-code/custom-commands) +- [Claude Code Slash Commands Documentation](https://code.claude.com/docs/en/slash-commands) - Official documentation +- [Discovering Claude Code Slash Commands](https://medium.com/@luongnv89/discovering-claude-code-slash-commands-cdc17f0dfb29) - Comprehensive blog post - [Markdown Guide](https://www.markdownguide.org/) -- [Command Examples Repository](https://github.com/anthropics/claude-code-examples) --- diff --git a/01-slash-commands/commit.md b/01-slash-commands/commit.md new file mode 100644 index 0000000..eed8ca2 --- /dev/null +++ b/01-slash-commands/commit.md @@ -0,0 +1,26 @@ +--- +allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*), Bash(git diff:*) +argument-hint: [message] +description: Create a git commit with context +--- + +## Context + +- Current git status: !`git status` +- Current git diff: !`git diff HEAD` +- Current branch: !`git branch --show-current` +- Recent commits: !`git log --oneline -10` + +## Your task + +Based on the above changes, create a single git commit. + +If a message was provided via arguments, use it: $ARGUMENTS + +Otherwise, analyze the changes and create an appropriate commit message following conventional commits format: +- `feat:` for new features +- `fix:` for bug fixes +- `docs:` for documentation changes +- `refactor:` for code refactoring +- `test:` for adding tests +- `chore:` for maintenance tasks diff --git a/01-slash-commands/generate-api-docs.md b/01-slash-commands/generate-api-docs.md index d57e1ed..642c3f2 100644 --- a/01-slash-commands/generate-api-docs.md +++ b/01-slash-commands/generate-api-docs.md @@ -1,7 +1,5 @@ --- -name: Generate API Documentation description: Create comprehensive API documentation from source code -tags: documentation, api --- # API Documentation Generator diff --git a/01-slash-commands/optimize.md b/01-slash-commands/optimize.md index 8af0839..ac4f24b 100644 --- a/01-slash-commands/optimize.md +++ b/01-slash-commands/optimize.md @@ -1,7 +1,5 @@ --- -name: Code Optimization description: Analyze code for performance issues and suggest optimizations -tags: performance, analysis --- # Code Optimization diff --git a/01-slash-commands/pr.md b/01-slash-commands/pr.md index e46d8b5..ae27970 100644 --- a/01-slash-commands/pr.md +++ b/01-slash-commands/pr.md @@ -1,7 +1,6 @@ --- -name: Prepare Pull Request description: Clean up code, stage changes, and prepare a pull request -tags: git, workflow +allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git diff:*), Bash(npm test:*), Bash(npm run lint:*) --- # Pull Request Preparation Checklist diff --git a/01-slash-commands/push-all.md b/01-slash-commands/push-all.md index ee681ad..d1840e0 100644 --- a/01-slash-commands/push-all.md +++ b/01-slash-commands/push-all.md @@ -1,7 +1,6 @@ --- -name: Commit and push everything description: Stage all changes, create commit, and push to remote (use with caution) -tags: git, workflow, automation +allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*), Bash(git push:*), Bash(git diff:*), Bash(git log:*), Bash(git pull:*) --- # Commit and Push Everything diff --git a/openspec/AGENTS.md b/openspec/AGENTS.md new file mode 100644 index 0000000..a3b6be2 --- /dev/null +++ b/openspec/AGENTS.md @@ -0,0 +1,456 @@ +# OpenSpec Instructions + +Instructions for AI coding assistants using OpenSpec for spec-driven development. + +## TL;DR Quick Checklist + +- Search existing work: `openspec spec list --long`, `openspec list` (use `rg` only for full-text search) +- Decide scope: new capability vs modify existing capability +- Pick a unique `change-id`: kebab-case, verb-led (`add-`, `update-`, `remove-`, `refactor-`) +- Scaffold: `proposal.md`, `tasks.md`, `design.md` (only if needed), and delta specs per affected capability +- Write deltas: use `## ADDED|MODIFIED|REMOVED|RENAMED Requirements`; include at least one `#### Scenario:` per requirement +- Validate: `openspec validate [change-id] --strict` and fix issues +- Request approval: Do not start implementation until proposal is approved + +## Three-Stage Workflow + +### Stage 1: Creating Changes +Create proposal when you need to: +- Add features or functionality +- Make breaking changes (API, schema) +- Change architecture or patterns +- Optimize performance (changes behavior) +- Update security patterns + +Triggers (examples): +- "Help me create a change proposal" +- "Help me plan a change" +- "Help me create a proposal" +- "I want to create a spec proposal" +- "I want to create a spec" + +Loose matching guidance: +- Contains one of: `proposal`, `change`, `spec` +- With one of: `create`, `plan`, `make`, `start`, `help` + +Skip proposal for: +- Bug fixes (restore intended behavior) +- Typos, formatting, comments +- Dependency updates (non-breaking) +- Configuration changes +- Tests for existing behavior + +**Workflow** +1. Review `openspec/project.md`, `openspec list`, and `openspec list --specs` to understand current context. +2. Choose a unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, optional `design.md`, and spec deltas under `openspec/changes//`. +3. Draft spec deltas using `## ADDED|MODIFIED|REMOVED Requirements` with at least one `#### Scenario:` per requirement. +4. Run `openspec validate --strict` and resolve any issues before sharing the proposal. + +### Stage 2: Implementing Changes +Track these steps as TODOs and complete them one by one. +1. **Read proposal.md** - Understand what's being built +2. **Read design.md** (if exists) - Review technical decisions +3. **Read tasks.md** - Get implementation checklist +4. **Implement tasks sequentially** - Complete in order +5. **Confirm completion** - Ensure every item in `tasks.md` is finished before updating statuses +6. **Update checklist** - After all work is done, set every task to `- [x]` so the list reflects reality +7. **Approval gate** - Do not start implementation until the proposal is reviewed and approved + +### Stage 3: Archiving Changes +After deployment, create separate PR to: +- Move `changes/[name]/` → `changes/archive/YYYY-MM-DD-[name]/` +- Update `specs/` if capabilities changed +- Use `openspec archive --skip-specs --yes` for tooling-only changes (always pass the change ID explicitly) +- Run `openspec validate --strict` to confirm the archived change passes checks + +## Before Any Task + +**Context Checklist:** +- [ ] Read relevant specs in `specs/[capability]/spec.md` +- [ ] Check pending changes in `changes/` for conflicts +- [ ] Read `openspec/project.md` for conventions +- [ ] Run `openspec list` to see active changes +- [ ] Run `openspec list --specs` to see existing capabilities + +**Before Creating Specs:** +- Always check if capability already exists +- Prefer modifying existing specs over creating duplicates +- Use `openspec show [spec]` to review current state +- If request is ambiguous, ask 1–2 clarifying questions before scaffolding + +### Search Guidance +- Enumerate specs: `openspec spec list --long` (or `--json` for scripts) +- Enumerate changes: `openspec list` (or `openspec change list --json` - deprecated but available) +- Show details: + - Spec: `openspec show --type spec` (use `--json` for filters) + - Change: `openspec show --json --deltas-only` +- Full-text search (use ripgrep): `rg -n "Requirement:|Scenario:" openspec/specs` + +## Quick Start + +### CLI Commands + +```bash +# Essential commands +openspec list # List active changes +openspec list --specs # List specifications +openspec show [item] # Display change or spec +openspec validate [item] # Validate changes or specs +openspec archive [--yes|-y] # Archive after deployment (add --yes for non-interactive runs) + +# Project management +openspec init [path] # Initialize OpenSpec +openspec update [path] # Update instruction files + +# Interactive mode +openspec show # Prompts for selection +openspec validate # Bulk validation mode + +# Debugging +openspec show [change] --json --deltas-only +openspec validate [change] --strict +``` + +### Command Flags + +- `--json` - Machine-readable output +- `--type change|spec` - Disambiguate items +- `--strict` - Comprehensive validation +- `--no-interactive` - Disable prompts +- `--skip-specs` - Archive without spec updates +- `--yes`/`-y` - Skip confirmation prompts (non-interactive archive) + +## Directory Structure + +``` +openspec/ +├── project.md # Project conventions +├── specs/ # Current truth - what IS built +│ └── [capability]/ # Single focused capability +│ ├── spec.md # Requirements and scenarios +│ └── design.md # Technical patterns +├── changes/ # Proposals - what SHOULD change +│ ├── [change-name]/ +│ │ ├── proposal.md # Why, what, impact +│ │ ├── tasks.md # Implementation checklist +│ │ ├── design.md # Technical decisions (optional; see criteria) +│ │ └── specs/ # Delta changes +│ │ └── [capability]/ +│ │ └── spec.md # ADDED/MODIFIED/REMOVED +│ └── archive/ # Completed changes +``` + +## Creating Change Proposals + +### Decision Tree + +``` +New request? +├─ Bug fix restoring spec behavior? → Fix directly +├─ Typo/format/comment? → Fix directly +├─ New feature/capability? → Create proposal +├─ Breaking change? → Create proposal +├─ Architecture change? → Create proposal +└─ Unclear? → Create proposal (safer) +``` + +### Proposal Structure + +1. **Create directory:** `changes/[change-id]/` (kebab-case, verb-led, unique) + +2. **Write proposal.md:** +```markdown +# Change: [Brief description of change] + +## Why +[1-2 sentences on problem/opportunity] + +## What Changes +- [Bullet list of changes] +- [Mark breaking changes with **BREAKING**] + +## Impact +- Affected specs: [list capabilities] +- Affected code: [key files/systems] +``` + +3. **Create spec deltas:** `specs/[capability]/spec.md` +```markdown +## ADDED Requirements +### Requirement: New Feature +The system SHALL provide... + +#### Scenario: Success case +- **WHEN** user performs action +- **THEN** expected result + +## MODIFIED Requirements +### Requirement: Existing Feature +[Complete modified requirement] + +## REMOVED Requirements +### Requirement: Old Feature +**Reason**: [Why removing] +**Migration**: [How to handle] +``` +If multiple capabilities are affected, create multiple delta files under `changes/[change-id]/specs//spec.md`—one per capability. + +4. **Create tasks.md:** +```markdown +## 1. Implementation +- [ ] 1.1 Create database schema +- [ ] 1.2 Implement API endpoint +- [ ] 1.3 Add frontend component +- [ ] 1.4 Write tests +``` + +5. **Create design.md when needed:** +Create `design.md` if any of the following apply; otherwise omit it: +- Cross-cutting change (multiple services/modules) or a new architectural pattern +- New external dependency or significant data model changes +- Security, performance, or migration complexity +- Ambiguity that benefits from technical decisions before coding + +Minimal `design.md` skeleton: +```markdown +## Context +[Background, constraints, stakeholders] + +## Goals / Non-Goals +- Goals: [...] +- Non-Goals: [...] + +## Decisions +- Decision: [What and why] +- Alternatives considered: [Options + rationale] + +## Risks / Trade-offs +- [Risk] → Mitigation + +## Migration Plan +[Steps, rollback] + +## Open Questions +- [...] +``` + +## Spec File Format + +### Critical: Scenario Formatting + +**CORRECT** (use #### headers): +```markdown +#### Scenario: User login success +- **WHEN** valid credentials provided +- **THEN** return JWT token +``` + +**WRONG** (don't use bullets or bold): +```markdown +- **Scenario: User login** ❌ +**Scenario**: User login ❌ +### Scenario: User login ❌ +``` + +Every requirement MUST have at least one scenario. + +### Requirement Wording +- Use SHALL/MUST for normative requirements (avoid should/may unless intentionally non-normative) + +### Delta Operations + +- `## ADDED Requirements` - New capabilities +- `## MODIFIED Requirements` - Changed behavior +- `## REMOVED Requirements` - Deprecated features +- `## RENAMED Requirements` - Name changes + +Headers matched with `trim(header)` - whitespace ignored. + +#### When to use ADDED vs MODIFIED +- ADDED: Introduces a new capability or sub-capability that can stand alone as a requirement. Prefer ADDED when the change is orthogonal (e.g., adding "Slash Command Configuration") rather than altering the semantics of an existing requirement. +- MODIFIED: Changes the behavior, scope, or acceptance criteria of an existing requirement. Always paste the full, updated requirement content (header + all scenarios). The archiver will replace the entire requirement with what you provide here; partial deltas will drop previous details. +- RENAMED: Use when only the name changes. If you also change behavior, use RENAMED (name) plus MODIFIED (content) referencing the new name. + +Common pitfall: Using MODIFIED to add a new concern without including the previous text. This causes loss of detail at archive time. If you aren’t explicitly changing the existing requirement, add a new requirement under ADDED instead. + +Authoring a MODIFIED requirement correctly: +1) Locate the existing requirement in `openspec/specs//spec.md`. +2) Copy the entire requirement block (from `### Requirement: ...` through its scenarios). +3) Paste it under `## MODIFIED Requirements` and edit to reflect the new behavior. +4) Ensure the header text matches exactly (whitespace-insensitive) and keep at least one `#### Scenario:`. + +Example for RENAMED: +```markdown +## RENAMED Requirements +- FROM: `### Requirement: Login` +- TO: `### Requirement: User Authentication` +``` + +## Troubleshooting + +### Common Errors + +**"Change must have at least one delta"** +- Check `changes/[name]/specs/` exists with .md files +- Verify files have operation prefixes (## ADDED Requirements) + +**"Requirement must have at least one scenario"** +- Check scenarios use `#### Scenario:` format (4 hashtags) +- Don't use bullet points or bold for scenario headers + +**Silent scenario parsing failures** +- Exact format required: `#### Scenario: Name` +- Debug with: `openspec show [change] --json --deltas-only` + +### Validation Tips + +```bash +# Always use strict mode for comprehensive checks +openspec validate [change] --strict + +# Debug delta parsing +openspec show [change] --json | jq '.deltas' + +# Check specific requirement +openspec show [spec] --json -r 1 +``` + +## Happy Path Script + +```bash +# 1) Explore current state +openspec spec list --long +openspec list +# Optional full-text search: +# rg -n "Requirement:|Scenario:" openspec/specs +# rg -n "^#|Requirement:" openspec/changes + +# 2) Choose change id and scaffold +CHANGE=add-two-factor-auth +mkdir -p openspec/changes/$CHANGE/{specs/auth} +printf "## Why\n...\n\n## What Changes\n- ...\n\n## Impact\n- ...\n" > openspec/changes/$CHANGE/proposal.md +printf "## 1. Implementation\n- [ ] 1.1 ...\n" > openspec/changes/$CHANGE/tasks.md + +# 3) Add deltas (example) +cat > openspec/changes/$CHANGE/specs/auth/spec.md << 'EOF' +## ADDED Requirements +### Requirement: Two-Factor Authentication +Users MUST provide a second factor during login. + +#### Scenario: OTP required +- **WHEN** valid credentials are provided +- **THEN** an OTP challenge is required +EOF + +# 4) Validate +openspec validate $CHANGE --strict +``` + +## Multi-Capability Example + +``` +openspec/changes/add-2fa-notify/ +├── proposal.md +├── tasks.md +└── specs/ + ├── auth/ + │ └── spec.md # ADDED: Two-Factor Authentication + └── notifications/ + └── spec.md # ADDED: OTP email notification +``` + +auth/spec.md +```markdown +## ADDED Requirements +### Requirement: Two-Factor Authentication +... +``` + +notifications/spec.md +```markdown +## ADDED Requirements +### Requirement: OTP Email Notification +... +``` + +## Best Practices + +### Simplicity First +- Default to <100 lines of new code +- Single-file implementations until proven insufficient +- Avoid frameworks without clear justification +- Choose boring, proven patterns + +### Complexity Triggers +Only add complexity with: +- Performance data showing current solution too slow +- Concrete scale requirements (>1000 users, >100MB data) +- Multiple proven use cases requiring abstraction + +### Clear References +- Use `file.ts:42` format for code locations +- Reference specs as `specs/auth/spec.md` +- Link related changes and PRs + +### Capability Naming +- Use verb-noun: `user-auth`, `payment-capture` +- Single purpose per capability +- 10-minute understandability rule +- Split if description needs "AND" + +### Change ID Naming +- Use kebab-case, short and descriptive: `add-two-factor-auth` +- Prefer verb-led prefixes: `add-`, `update-`, `remove-`, `refactor-` +- Ensure uniqueness; if taken, append `-2`, `-3`, etc. + +## Tool Selection Guide + +| Task | Tool | Why | +|------|------|-----| +| Find files by pattern | Glob | Fast pattern matching | +| Search code content | Grep | Optimized regex search | +| Read specific files | Read | Direct file access | +| Explore unknown scope | Task | Multi-step investigation | + +## Error Recovery + +### Change Conflicts +1. Run `openspec list` to see active changes +2. Check for overlapping specs +3. Coordinate with change owners +4. Consider combining proposals + +### Validation Failures +1. Run with `--strict` flag +2. Check JSON output for details +3. Verify spec file format +4. Ensure scenarios properly formatted + +### Missing Context +1. Read project.md first +2. Check related specs +3. Review recent archives +4. Ask for clarification + +## Quick Reference + +### Stage Indicators +- `changes/` - Proposed, not yet built +- `specs/` - Built and deployed +- `archive/` - Completed changes + +### File Purposes +- `proposal.md` - Why and what +- `tasks.md` - Implementation steps +- `design.md` - Technical decisions +- `spec.md` - Requirements and behavior + +### CLI Essentials +```bash +openspec list # What's in progress? +openspec show [item] # View details +openspec validate --strict # Is it correct? +openspec archive [--yes|-y] # Mark complete (add --yes for automation) +``` + +Remember: Specs are truth. Changes are proposals. Keep them in sync. diff --git a/openspec/changes/add-cli-lesson/proposal.md b/openspec/changes/add-cli-lesson/proposal.md new file mode 100644 index 0000000..703fea6 --- /dev/null +++ b/openspec/changes/add-cli-lesson/proposal.md @@ -0,0 +1,41 @@ +# Change: Add CLI Reference Lesson + +## Why + +The Claude How To repository covers nine major Claude Code features (01-09), but lacks a dedicated lesson for the CLI reference - the command-line interface that users interact with directly. Understanding CLI commands, flags, and options is fundamental to using Claude Code effectively. Users need a comprehensive reference to leverage features like model selection, output formats, permission management, and session handling via CLI. + +## What Changes + +- **NEW** `10-cli/` directory with comprehensive CLI reference lesson +- **NEW** `10-cli/README.md` - Main lesson content following established structure +- **UPDATE** Root `README.md` - Add CLI lesson to navigation and learning path +- **UPDATE** Root `README.md` - Add CLI to feature comparison and use case matrix +- **UPDATE** `LEARNING-ROADMAP.md` - Include CLI lesson in learning progression + +## Key Content Areas + +1. **CLI Commands** - Start interactive REPL, query mode, continue/resume sessions, updates +2. **Core Flags** - Print mode, continue, resume, version +3. **Model Configuration** - Model selection, fallback models, agent configuration +4. **System Prompt Customization** - Replace, append, file-based prompts +5. **Tool & Permission Management** - Allowed/disallowed tools, permission modes +6. **Output & Format** - JSON, stream-JSON, text formats +7. **MCP Configuration** - Server loading, strict mode +8. **Session Management** - Session IDs, forking, resumption +9. **Advanced Features** - Chrome integration, IDE connection, debug mode + +## High-Value Use Cases + +1. **CI/CD Integration** - Headless mode with JSON output for automation pipelines +2. **Script Piping** - Process files, logs, and data through Claude +3. **Multi-Session Workflows** - Resume and fork sessions for complex projects +4. **Custom Agent Configurations** - Define specialized subagents via CLI +5. **Batch Processing** - Process multiple queries with consistent settings +6. **Security-Conscious Development** - Permission modes and tool restrictions +7. **API Integration** - Structured JSON output for programmatic consumption + +## Impact + +- Affected specs: None (new capability) +- Affected code: Root README.md, LEARNING-ROADMAP.md +- New files: `10-cli/README.md` diff --git a/openspec/changes/add-cli-lesson/specs/cli-reference/spec.md b/openspec/changes/add-cli-lesson/specs/cli-reference/spec.md new file mode 100644 index 0000000..c1e49b2 --- /dev/null +++ b/openspec/changes/add-cli-lesson/specs/cli-reference/spec.md @@ -0,0 +1,99 @@ +## ADDED Requirements + +### Requirement: CLI Reference Lesson + +The repository SHALL provide a comprehensive CLI reference lesson at `10-cli/` that documents all command-line interface options, flags, and usage patterns for Claude Code. + +#### Scenario: User learns CLI basics +- **WHEN** a user navigates to `10-cli/README.md` +- **THEN** they find an overview of CLI capabilities with architecture diagram +- **AND** a quick reference table of all CLI commands +- **AND** examples demonstrating common usage patterns + +#### Scenario: User looks up specific CLI flag +- **WHEN** a user needs to understand a specific CLI flag (e.g., `--output-format`) +- **THEN** they find the flag documented with description, options, and example usage +- **AND** related flags are cross-referenced + +#### Scenario: User integrates Claude Code in CI/CD +- **WHEN** a user wants to use Claude Code in automation +- **THEN** they find practical examples for CI/CD integration +- **AND** examples show headless mode, JSON output, and error handling + +### Requirement: CLI Commands Documentation + +The CLI lesson SHALL document all primary CLI commands with their syntax and use cases. + +#### Scenario: Interactive mode commands documented +- **WHEN** a user reads the CLI commands section +- **THEN** they find `claude` for starting interactive REPL +- **AND** `claude "query"` for starting with initial prompt +- **AND** `claude -c` for continuing recent conversation +- **AND** `claude -r` for resuming specific session + +#### Scenario: Print mode commands documented +- **WHEN** a user reads the print mode section +- **THEN** they find `claude -p "query"` for non-interactive queries +- **AND** pipe input examples like `cat file | claude -p "query"` +- **AND** output format options (text, json, stream-json) + +### Requirement: CLI Flags Documentation + +The CLI lesson SHALL document all CLI flags organized by category with examples. + +#### Scenario: Core flags documented +- **WHEN** a user reads the core flags section +- **THEN** they find `-p/--print`, `-c/--continue`, `-r/--resume`, `-v/--version` +- **AND** each flag has description and example usage + +#### Scenario: Model configuration flags documented +- **WHEN** a user reads the model configuration section +- **THEN** they find `--model`, `--fallback-model`, `--agent`, `--agents` +- **AND** examples show model selection and custom agent definitions + +#### Scenario: Permission flags documented +- **WHEN** a user reads the permission section +- **THEN** they find `--tools`, `--allowedTools`, `--disallowedTools` +- **AND** `--dangerously-skip-permissions`, `--permission-mode` +- **AND** examples demonstrate security-conscious configurations + +### Requirement: High-Value Use Cases + +The CLI lesson SHALL include practical use case examples that demonstrate real-world CLI value. + +#### Scenario: CI/CD integration example provided +- **WHEN** a user reads the CI/CD use case +- **THEN** they find a complete GitHub Actions or Jenkins example +- **AND** the example demonstrates headless mode with JSON output +- **AND** error handling and exit codes are explained + +#### Scenario: Script piping example provided +- **WHEN** a user reads the script piping use case +- **THEN** they find examples of piping file contents to Claude +- **AND** examples show log analysis, code review via pipe +- **AND** output processing patterns are demonstrated + +#### Scenario: Multi-session workflow example provided +- **WHEN** a user reads the session management use case +- **THEN** they find examples of resuming and forking sessions +- **AND** session naming and organization patterns are shown + +### Requirement: Navigation Integration + +The root documentation SHALL be updated to include the CLI lesson in all navigation elements. + +#### Scenario: CLI appears in Quick Navigation +- **WHEN** a user views the README Quick Navigation table +- **THEN** they see CLI Reference listed with link to `10-cli/` + +#### Scenario: CLI appears in Learning Path +- **WHEN** a user views the Learning Path table +- **THEN** they see CLI Reference at position 10 with appropriate difficulty and timing + +#### Scenario: CLI appears in Feature Comparison +- **WHEN** a user views the Feature Comparison table +- **THEN** CLI Reference is included with invocation, persistence, and use case columns + +#### Scenario: CLI appears in Directory Structure +- **WHEN** a user views the Directory Structure tree +- **THEN** `10-cli/` directory is shown with `README.md` diff --git a/openspec/changes/add-cli-lesson/tasks.md b/openspec/changes/add-cli-lesson/tasks.md new file mode 100644 index 0000000..59dc044 --- /dev/null +++ b/openspec/changes/add-cli-lesson/tasks.md @@ -0,0 +1,50 @@ +# Tasks: Add CLI Reference Lesson + +## 1. Create CLI Lesson Content + +- [ ] 1.1 Create `10-cli/` directory +- [ ] 1.2 Create `10-cli/README.md` with: + - Overview section with architecture diagram + - CLI commands table (claude, claude "query", claude -p, etc.) + - Core flags section with examples + - Model & configuration flags + - System prompt customization section + - Tool & permission management section + - Output & format options + - Workspace & directory flags + - MCP configuration options + - Session management commands + - Advanced features (chrome, ide, debug) + - Agents flag format with JSON examples + - High-value use cases section with practical examples + - Installation/usage quick reference + - Troubleshooting section + - Related concepts links + +## 2. Add Use Case Examples + +- [ ] 2.1 CI/CD integration example (GitHub Actions, Jenkins) +- [ ] 2.2 Script piping example (log analysis, code processing) +- [ ] 2.3 Multi-session workflow example +- [ ] 2.4 Custom agent configuration example +- [ ] 2.5 Batch processing example +- [ ] 2.6 Security-conscious development example +- [ ] 2.7 JSON API integration example + +## 3. Update Root Documentation + +- [ ] 3.1 Add CLI to Quick Navigation table in `README.md` +- [ ] 3.2 Add CLI to Learning Path table in `README.md` +- [ ] 3.3 Add CLI section (section 10) in `README.md` +- [ ] 3.4 Add CLI to Feature Comparison table +- [ ] 3.5 Add CLI to Use Case Matrix +- [ ] 3.6 Add CLI to Directory Structure tree +- [ ] 3.7 Add CLI to Installation Quick Reference +- [ ] 3.8 Update `LEARNING-ROADMAP.md` with CLI lesson + +## 4. Quality Assurance + +- [ ] 4.1 Verify all code examples are valid and tested +- [ ] 4.2 Ensure consistent style with other lessons (mermaid diagrams, tables) +- [ ] 4.3 Check all internal links work correctly +- [ ] 4.4 Review against official documentation for accuracy diff --git a/openspec/changes/update-hooks-lesson/proposal.md b/openspec/changes/update-hooks-lesson/proposal.md new file mode 100644 index 0000000..9872f79 --- /dev/null +++ b/openspec/changes/update-hooks-lesson/proposal.md @@ -0,0 +1,36 @@ +# Change: Update Hooks Lesson Based on Official Documentation + +## Why + +The current hooks lesson (`blog-posts/06-hooks.md`) contains outdated and inaccurate information that doesn't match the official Claude Code hooks documentation. Key issues include: + +1. **Incorrect hook event names**: Uses `PreToolUse:Write`, `PreCommit`, `PostCommit`, `PrePush` which don't exist +2. **Missing hook events**: Doesn't cover `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact`, `SessionStart` (with matchers), `SessionEnd` +3. **Wrong configuration format**: Shows string-based hook commands instead of the array-based matcher/hooks structure +4. **Missing hook input/output**: Doesn't explain JSON stdin input or structured JSON output +5. **Missing exit code semantics**: Exit code 2 for blocking vs other non-zero codes +6. **Missing prompt-based hooks**: No coverage of `type: "prompt"` hooks for LLM-based evaluation +7. **Missing security considerations**: No disclaimer or security best practices from official docs +8. **Incorrect variable references**: Uses `${file_path}`, `${command}` instead of JSON stdin input + +## What Changes + +- **BREAKING**: Complete rewrite of hook event types and configuration format +- Update all code examples to use correct array-based configuration structure +- Add coverage of all 9 hook events: `PreToolUse`, `PermissionRequest`, `PostToolUse`, `Notification`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PreCompact`, `SessionStart`, `SessionEnd` +- Add JSON hook input/output documentation with examples +- Add hook matchers (tool patterns, regex support) +- Add prompt-based hooks for `Stop`/`SubagentStop` +- Add security considerations section with official disclaimer +- Add environment variables section (`CLAUDE_PROJECT_DIR`, `CLAUDE_ENV_FILE`, `CLAUDE_CODE_REMOTE`) +- Add plugin hooks documentation +- Add MCP tool hook patterns (`mcp____`) +- Update debugging section with `claude --debug` and verbose mode +- Remove incorrect/non-existent hook types (`PreCommit`, `PostCommit`, `PrePush`) + +## Impact + +- **Affected specs**: hooks-documentation (new capability) +- **Affected code**: `blog-posts/06-hooks.md` (complete rewrite) +- **Affected examples**: Any example hook scripts in the repo need updating to use JSON stdin +- **User impact**: Users following the current guide will have non-functional hooks; this update provides correct, working examples diff --git a/openspec/changes/update-hooks-lesson/specs/hooks-documentation/spec.md b/openspec/changes/update-hooks-lesson/specs/hooks-documentation/spec.md new file mode 100644 index 0000000..7e30819 --- /dev/null +++ b/openspec/changes/update-hooks-lesson/specs/hooks-documentation/spec.md @@ -0,0 +1,124 @@ +# Hooks Documentation Specification + +## ADDED Requirements + +### Requirement: Hook Event Types Documentation +The hooks lesson SHALL document all 9 official hook events with their correct names, matchers, and behavior. + +#### Scenario: Complete hook event coverage +- **WHEN** a user reads the hooks lesson +- **THEN** they find documentation for PreToolUse, PermissionRequest, PostToolUse, Notification, UserPromptSubmit, Stop, SubagentStop, PreCompact, SessionStart, and SessionEnd events + +#### Scenario: No deprecated hook events +- **WHEN** a user searches for PreCommit, PostCommit, or PrePush hooks +- **THEN** they do not find these as they are not valid Claude Code hook events + +### Requirement: Hook Configuration Format +The hooks lesson SHALL document the correct array-based configuration format with matchers and hooks arrays. + +#### Scenario: Configuration structure +- **WHEN** a user views hook configuration examples +- **THEN** they see the structure: `{ "hooks": { "EventName": [{ "matcher": "Pattern", "hooks": [{ "type": "command", "command": "..." }] }] } }` + +#### Scenario: Matcher patterns +- **WHEN** a user needs to match specific tools +- **THEN** they find documentation for exact string matching, regex patterns, and wildcards + +### Requirement: Hook Input Documentation +The hooks lesson SHALL document the JSON stdin input that hooks receive. + +#### Scenario: JSON input structure +- **WHEN** a user writes a hook script +- **THEN** they understand the input includes session_id, transcript_path, cwd, permission_mode, hook_event_name, tool_name, tool_input, and tool_use_id + +#### Scenario: Event-specific input fields +- **WHEN** a user writes a hook for a specific event +- **THEN** they find documentation for event-specific input fields (e.g., stop_hook_active for Stop event) + +### Requirement: Hook Output Documentation +The hooks lesson SHALL document hook output semantics including exit codes and JSON stdout structure. + +#### Scenario: Exit code semantics +- **WHEN** a user implements a hook +- **THEN** they understand exit code 0 means success, exit code 2 means blocking error (stderr used as error message), and other codes mean non-blocking error + +#### Scenario: JSON output format +- **WHEN** a hook needs to control behavior +- **THEN** the user can output JSON with continue, stopReason, suppressOutput, systemMessage, and hookSpecificOutput fields + +#### Scenario: Event-specific output +- **WHEN** a user writes a PreToolUse hook +- **THEN** they can output permissionDecision (allow/deny/ask), permissionDecisionReason, and updatedInput + +### Requirement: Prompt-Based Hooks Documentation +The hooks lesson SHALL document type="prompt" hooks for LLM-based evaluation on Stop and SubagentStop events. + +#### Scenario: Prompt hook configuration +- **WHEN** a user wants intelligent stop evaluation +- **THEN** they find documentation for configuring type="prompt" hooks with prompt text and timeout + +#### Scenario: LLM response schema +- **WHEN** using prompt-based hooks +- **THEN** the user understands the expected response schema with decision (approve/block), reason, continue, stopReason, and systemMessage + +### Requirement: Environment Variables Documentation +The hooks lesson SHALL document all environment variables available to hooks. + +#### Scenario: Standard environment variables +- **WHEN** a user writes a hook script +- **THEN** they can use CLAUDE_PROJECT_DIR for the absolute project path + +#### Scenario: SessionStart environment persistence +- **WHEN** using SessionStart hooks +- **THEN** the user can persist environment variables via CLAUDE_ENV_FILE + +#### Scenario: Remote environment detection +- **WHEN** running in web environment +- **THEN** hooks can check CLAUDE_CODE_REMOTE to detect this + +### Requirement: Security Documentation +The hooks lesson SHALL include security considerations and best practices from the official documentation. + +#### Scenario: Security disclaimer +- **WHEN** a user reads about hooks +- **THEN** they see a clear disclaimer that hooks execute arbitrary shell commands at their own risk + +#### Scenario: Security best practices +- **WHEN** a user implements hooks +- **THEN** they find guidance on input validation, shell variable quoting, path traversal prevention, and sensitive file handling + +### Requirement: MCP Tool Hook Patterns +The hooks lesson SHALL document how to create hooks for MCP tools. + +#### Scenario: MCP tool matching +- **WHEN** a user wants to hook into MCP tool calls +- **THEN** they find documentation for the pattern `mcp____` and regex matching + +### Requirement: Plugin Hooks Documentation +The hooks lesson SHALL document how plugins can provide hooks. + +#### Scenario: Plugin hook configuration +- **WHEN** a plugin needs to provide hooks +- **THEN** documentation covers hooks/hooks.json structure and ${CLAUDE_PLUGIN_ROOT} variable + +### Requirement: Debugging Documentation +The hooks lesson SHALL document how to debug hook execution. + +#### Scenario: Debug mode +- **WHEN** hooks are not working as expected +- **THEN** users can enable `claude --debug` for detailed hook execution logs + +#### Scenario: Verbose mode +- **WHEN** using Claude Code interactively +- **THEN** users can enable verbose mode (ctrl+o) to see hook execution progress + +### Requirement: Working Example Scripts +The hooks lesson SHALL provide working example scripts that use JSON stdin input. + +#### Scenario: Bash command validator +- **WHEN** a user wants to validate bash commands +- **THEN** they find a working Python script that reads JSON stdin and validates commands + +#### Scenario: Intelligent stop hook +- **WHEN** a user wants automatic task completion verification +- **THEN** they find a working prompt-based stop hook example diff --git a/openspec/changes/update-hooks-lesson/tasks.md b/openspec/changes/update-hooks-lesson/tasks.md new file mode 100644 index 0000000..ec6c72a --- /dev/null +++ b/openspec/changes/update-hooks-lesson/tasks.md @@ -0,0 +1,69 @@ +# Tasks: Update Hooks Lesson + +## 1. Content Structure Update +- [x] 1.1 Update introduction to explain hooks as event-driven automation scripts +- [x] 1.2 Replace hook architecture diagram with correct event flow +- [x] 1.3 Update hook types table with all 9 official hook events + +## 2. Configuration Format +- [x] 2.1 Rewrite configuration section with array-based matcher/hooks structure +- [x] 2.2 Add hook matcher documentation (exact match, regex patterns, wildcards) +- [x] 2.3 Add timeout configuration examples + +## 3. Hook Events Documentation +- [x] 3.1 Document PreToolUse event (matchers, decision control, updatedInput) +- [x] 3.2 Document PermissionRequest event (decision behavior, messages) +- [x] 3.3 Document PostToolUse event (block decision, additionalContext) +- [x] 3.4 Document Notification event (matchers: permission_prompt, idle_prompt, etc.) +- [x] 3.5 Document UserPromptSubmit event (block decision, context addition) +- [x] 3.6 Document Stop event (block continuation, stop_hook_active) +- [x] 3.7 Document SubagentStop event (subagent completion handling) +- [x] 3.8 Document PreCompact event (manual vs auto matchers) +- [x] 3.9 Document SessionStart event (startup/resume/clear/compact matchers, CLAUDE_ENV_FILE) +- [x] 3.10 Document SessionEnd event (reason field) + +## 4. Hook Input/Output +- [x] 4.1 Document JSON stdin input structure (session_id, transcript_path, cwd, etc.) +- [x] 4.2 Document exit code semantics (0=success, 2=blocking error, other=non-blocking) +- [x] 4.3 Document JSON stdout output structure (continue, stopReason, hookSpecificOutput) +- [x] 4.4 Add examples for each hook event's specific output format + +## 5. Prompt-Based Hooks +- [x] 5.1 Add section on type="prompt" hooks for Stop/SubagentStop +- [x] 5.2 Document LLM response schema (decision, reason, continue, stopReason) +- [x] 5.3 Add practical examples of intelligent stop hooks + +## 6. Environment Variables +- [x] 6.1 Document CLAUDE_PROJECT_DIR usage +- [x] 6.2 Document CLAUDE_ENV_FILE for SessionStart env persistence +- [x] 6.3 Document CLAUDE_CODE_REMOTE for web environment detection +- [x] 6.4 Document plugin hook variables (${CLAUDE_PLUGIN_ROOT}) + +## 7. Security Section +- [x] 7.1 Add official security disclaimer (USE AT YOUR OWN RISK) +- [x] 7.2 Document security best practices (input validation, quoting, path traversal) +- [x] 7.3 Add configuration safety notes (snapshot at startup, modification warnings) + +## 8. Advanced Features +- [x] 8.1 Add MCP tool hook patterns (mcp____) +- [x] 8.2 Add plugin hooks documentation +- [x] 8.3 Add project-specific hook script examples + +## 9. Debugging and Troubleshooting +- [x] 9.1 Update debugging section with claude --debug flag +- [x] 9.2 Add verbose mode (ctrl+o) documentation +- [x] 9.3 Update troubleshooting with correct error scenarios + +## 10. Example Scripts +- [x] 10.1 Rewrite format-code hook to use JSON stdin +- [x] 10.2 Rewrite security-scan hook with proper JSON input parsing +- [x] 10.3 Rewrite bash command validator example from official docs +- [x] 10.4 Add intelligent stop hook example with prompt type +- [x] 10.5 Remove non-existent PreCommit/PostCommit/PrePush examples + +## 11. Final Cleanup +- [x] 11.1 Update Mermaid diagrams for accuracy +- [x] 11.2 Update variable reference table to reflect JSON input +- [x] 11.3 Update best practices table +- [x] 11.4 Update directory structure section +- [x] 11.5 Verify all links and references diff --git a/openspec/changes/update-skills-lesson/proposal.md b/openspec/changes/update-skills-lesson/proposal.md new file mode 100644 index 0000000..0b43fe4 --- /dev/null +++ b/openspec/changes/update-skills-lesson/proposal.md @@ -0,0 +1,48 @@ +# Change: Update Agent Skills Lesson with Latest Documentation + +## Why + +The current Agent Skills lesson (03-skills) is missing several key features and best practices from the latest official Claude Code documentation at https://code.claude.com/docs/en/skills#agent-skills. Users need up-to-date information to effectively create, manage, debug, and share skills. + +## What Changes + +### Documentation Updates (README.md and blog-posts/03-skills.md) + +1. **Enhanced Managing Skills Section** - Add comprehensive guidance for: + - Viewing available skills (via Claude and filesystem) + - Testing skills effectively + - Updating skills (with restart requirements) + - Removing skills properly + +2. **Improved Debugging Section** - Add detailed troubleshooting for: + - Skills being skipped or non-functional + - Invalid YAML frontmatter detection + - Script permission issues + - Path format requirements (forward slashes) + - Multiple skills conflicting + +3. **Version History Best Practice** - Add guidance on documenting skill versions in SKILL.md + +4. **Enhanced allowed-tools Documentation** - Expand explanation of tool access control with: + - Use cases for read-only skills + - Security-sensitive workflow examples + - Note about permission prompts when not specified + +5. **Multi-File Skill Example** - Add comprehensive example showing: + - Directory structure for complex skills + - Multiple reference files + - Scripts subdirectory + - Templates organization + +6. **Plugin Skills Clarification** - Better explain how plugin-bundled skills work + +### Example Updates (03-skills/ directory) + +7. **Add Version History Example** - Update code-review SKILL.md to include version history section + +## Impact + +- Affected docs: `03-skills/README.md`, `blog-posts/03-skills.md` +- Affected examples: `03-skills/code-review/SKILL.md` +- No breaking changes - purely additive documentation improvements +- Improves user experience for skill creation and debugging diff --git a/openspec/changes/update-skills-lesson/specs/skills-lesson/spec.md b/openspec/changes/update-skills-lesson/specs/skills-lesson/spec.md new file mode 100644 index 0000000..323833d --- /dev/null +++ b/openspec/changes/update-skills-lesson/specs/skills-lesson/spec.md @@ -0,0 +1,64 @@ +## ADDED 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 diff --git a/openspec/changes/update-skills-lesson/tasks.md b/openspec/changes/update-skills-lesson/tasks.md new file mode 100644 index 0000000..e62de94 --- /dev/null +++ b/openspec/changes/update-skills-lesson/tasks.md @@ -0,0 +1,27 @@ +# Tasks: Update Agent Skills Lesson + +## 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 + +## 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 + +## 3. Update Example Skills + +- [ ] 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 diff --git a/openspec/changes/update-slash-commands-session/proposal.md b/openspec/changes/update-slash-commands-session/proposal.md new file mode 100644 index 0000000..8a1e994 --- /dev/null +++ b/openspec/changes/update-slash-commands-session/proposal.md @@ -0,0 +1,33 @@ +# Change: Update Slash Commands Documentation + +## Why + +The current slash commands documentation in `01-slash-commands/README.md` is outdated compared to the official Claude Code documentation at https://code.claude.com/docs/en/slash-commands. Several new features, built-in commands, and capabilities have been added that users should know about. + +## What Changes + +### Documentation Updates + +- **Add comprehensive built-in commands table** - Document all 40+ built-in slash commands with their purposes +- **Update custom command features** - Document new argument handling (`$ARGUMENTS`, `$1`, `$2`, etc.) +- **Add bash execution syntax** - Document the `!` prefix for executing bash commands within slash commands +- **Update frontmatter fields** - Document `allowed-tools`, `argument-hint`, `description`, `model`, `disable-model-invocation` +- **Add file reference syntax** - Document the `@` prefix for including file contents +- **Add Plugin commands section** - Document `/plugin-name:command-name` pattern +- **Add MCP slash commands section** - Document `/mcp____` pattern +- **Add SlashCommand Tool section** - Document programmatic invocation from Claude +- **Add Skills vs Slash Commands comparison** - Help users choose the right tool + +### Example Updates + +- Add example command with bash execution (`!git status`) +- Add example with file references (`@src/utils/helpers.js`) +- Add example with complete frontmatter +- Update existing examples to use official syntax + +## Impact + +- Affected specs: `slash-commands` (new capability spec to be created) +- Affected code: `01-slash-commands/README.md`, potentially new example files +- No breaking changes - additive documentation improvements +- Benefits all users learning about Claude Code slash commands diff --git a/openspec/changes/update-slash-commands-session/specs/slash-commands/spec.md b/openspec/changes/update-slash-commands-session/specs/slash-commands/spec.md new file mode 100644 index 0000000..101c509 --- /dev/null +++ b/openspec/changes/update-slash-commands-session/specs/slash-commands/spec.md @@ -0,0 +1,147 @@ +## ADDED Requirements + +### Requirement: Slash Command Types Documentation + +The documentation SHALL describe the four types of slash commands: +1. Built-in commands provided by Claude Code +2. Custom user-defined commands (project and personal) +3. Plugin commands +4. MCP (Model Context Protocol) slash commands + +#### Scenario: User learns about command types +- **WHEN** a user reads the slash commands documentation +- **THEN** they understand the different types of slash commands available +- **AND** they know when to use each type + +--- + +### Requirement: Built-in Commands Reference + +The documentation SHALL include a comprehensive reference table of all built-in slash commands with their purposes, including but not limited to: +- `/add-dir` - Add additional working directories +- `/agents` - Manage custom AI subagents +- `/clear` - Clear conversation history +- `/compact` - Compact conversation with optional focus instructions +- `/config` - Open Settings interface +- `/context` - Visualize current context usage +- `/cost` - Show token usage statistics +- `/doctor` - Check installation health +- `/export` - Export conversation to file or clipboard +- `/help` - Get usage help +- `/hooks` - Manage hook configurations +- `/init` - Initialize project with CLAUDE.md +- `/mcp` - Manage MCP server connections +- `/memory` - Edit CLAUDE.md memory files +- `/model` - Select or change AI model +- `/permissions` - View or update permissions +- `/resume` - Resume conversation by ID or name +- `/review` - Request code review +- `/sandbox` - Enable sandboxed bash tool +- `/vim` - Enter vim mode + +#### Scenario: User finds built-in command +- **WHEN** a user needs to perform a common operation +- **THEN** they can find the appropriate built-in command in the reference table +- **AND** they understand what the command does + +--- + +### Requirement: Argument Handling + +The documentation SHALL explain both argument handling methods: +1. `$ARGUMENTS` - Receives all arguments as a single string +2. `$1`, `$2`, `$3`, etc. - Individual positional arguments + +#### Scenario: User uses $ARGUMENTS placeholder +- **WHEN** a user creates a command with `$ARGUMENTS` placeholder +- **AND** invokes it with `/fix-issue 123 high-priority` +- **THEN** `$ARGUMENTS` contains "123 high-priority" + +#### Scenario: User uses positional arguments +- **WHEN** a user creates a command with `$1`, `$2`, `$3` placeholders +- **AND** invokes it with `/review-pr 456 high alice` +- **THEN** `$1` is "456", `$2` is "high", `$3` is "alice" + +--- + +### Requirement: Bash Command Execution + +The documentation SHALL explain the `!` prefix for executing bash commands within slash command files before the command runs. + +#### Scenario: User includes dynamic context +- **WHEN** a user adds `!git status` in their command file +- **THEN** the git status output is included in the command context +- **AND** Claude receives the current repository state + +--- + +### Requirement: File Reference Syntax + +The documentation SHALL explain the `@` prefix for including file contents in slash commands. + +#### Scenario: User references a file +- **WHEN** a user adds `@src/utils/helpers.js` in their command file +- **THEN** the contents of that file are included in the command context + +--- + +### Requirement: Frontmatter Fields + +The documentation SHALL document all supported frontmatter fields: +- `allowed-tools` - List of tools the command can use +- `argument-hint` - Expected arguments for auto-completion +- `description` - Brief description of the command +- `model` - Specific model to use for this command +- `disable-model-invocation` - Prevent SlashCommand tool from calling this command + +#### Scenario: User creates command with frontmatter +- **WHEN** a user creates a command with frontmatter fields +- **THEN** Claude Code respects those configuration options +- **AND** the command behaves according to the specified settings + +--- + +### Requirement: Plugin Commands Documentation + +The documentation SHALL explain the plugin command format: `/plugin-name:command-name` or simply `/command-name` when there are no naming conflicts. + +#### Scenario: User invokes plugin command +- **WHEN** a user types `/frontend-design:frontend-design` +- **THEN** the corresponding plugin command executes + +--- + +### Requirement: MCP Slash Commands Documentation + +The documentation SHALL explain the MCP slash command format: `/mcp____ [arguments]` + +#### Scenario: User invokes MCP command +- **WHEN** a user types `/mcp__github__list_prs` +- **THEN** the MCP server's prompt is executed + +--- + +### Requirement: SlashCommand Tool Documentation + +The documentation SHALL explain how Claude can programmatically invoke slash commands using the SlashCommand tool, including: +- How to enable this via prompt or CLAUDE.md references +- How to disable via permissions +- The character budget limit (default 15,000, configurable via `SLASH_COMMAND_TOOL_CHAR_BUDGET`) + +#### Scenario: User enables programmatic invocation +- **WHEN** a user adds "Run /write-unit-test when writing tests" to CLAUDE.md +- **THEN** Claude can automatically invoke that command when appropriate + +--- + +### Requirement: Skills vs Slash Commands Comparison + +The documentation SHALL include a comparison table helping users choose between Skills and Slash Commands based on: +- Best use cases for each +- File structure differences +- Invocation method (explicit vs automatic) +- Complexity level + +#### Scenario: User decides between skill and command +- **WHEN** a user needs to create a reusable capability +- **THEN** they can use the comparison to decide whether a slash command or skill is more appropriate diff --git a/openspec/changes/update-slash-commands-session/tasks.md b/openspec/changes/update-slash-commands-session/tasks.md new file mode 100644 index 0000000..57d9ebf --- /dev/null +++ b/openspec/changes/update-slash-commands-session/tasks.md @@ -0,0 +1,42 @@ +## 1. Documentation Structure Updates + +- [x] 1.1 Add "Types of Slash Commands" section with overview of built-in, custom, plugin, and MCP commands +- [x] 1.2 Create comprehensive built-in commands reference table (40+ commands) +- [x] 1.3 Update custom commands section with new features + +## 2. Custom Command Features + +- [x] 2.1 Document `$ARGUMENTS` placeholder for all arguments +- [x] 2.2 Document individual argument placeholders (`$1`, `$2`, `$3`, etc.) +- [x] 2.3 Document bash execution with `!` prefix (e.g., `!git status`) +- [x] 2.4 Document file references with `@` prefix (e.g., `@src/file.js`) +- [x] 2.5 Document thinking mode trigger via keywords + +## 3. Frontmatter Updates + +- [x] 3.1 Update frontmatter section with official fields +- [x] 3.2 Document `allowed-tools` field with examples +- [x] 3.3 Document `argument-hint` field for auto-completion +- [x] 3.4 Document `description` field +- [x] 3.5 Document `model` field for specific model selection +- [x] 3.6 Document `disable-model-invocation` field + +## 4. New Sections + +- [x] 4.1 Add "Plugin Commands" section with `/plugin-name:command-name` pattern +- [x] 4.2 Add "MCP Slash Commands" section with `/mcp____` pattern +- [x] 4.3 Add "SlashCommand Tool" section for programmatic invocation +- [x] 4.4 Add "Skills vs Slash Commands" comparison table + +## 5. Example Files + +- [x] 5.1 Create new example showing bash execution feature (commit.md) +- [x] 5.2 Create new example showing file references (commit.md includes @package.json example in README) +- [x] 5.3 Update existing examples to use official frontmatter format (removed name/tags, added allowed-tools) +- [x] 5.4 Add commit command example (from official docs) + +## 6. Validation + +- [x] 6.1 Verify all links work correctly +- [x] 6.2 Test example commands format +- [x] 6.3 Review for consistency with official documentation diff --git a/openspec/project.md b/openspec/project.md new file mode 100644 index 0000000..f5636ce --- /dev/null +++ b/openspec/project.md @@ -0,0 +1,125 @@ +# Project Context + +## Purpose + +**Claude How To** is a comprehensive educational repository providing examples and documentation for Claude Code features and concepts. The project serves as: + +- A learning resource for developers new to Claude Code +- A reference collection of example configurations (slash commands, memory, skills, subagents, MCP, hooks, plugins, checkpoints, advanced features) +- A tool for generating offline documentation (EPUB format) + +**Goals:** +1. Provide clear, numbered learning paths (01-09) for Claude Code features +2. Include ready-to-use example configurations users can copy to their projects +3. Generate an EPUB ebook from the documentation for offline reading +4. Maintain high-quality Python tooling with CI/CD automation + +## Tech Stack + +### Primary Technologies +- **Python 3.10+** - EPUB builder script and tooling +- **Markdown** - Documentation content (all guides and examples) +- **JSON/YAML** - Configuration files (MCP configs, plugin definitions) +- **Shell Scripts** - Hook examples in `06-hooks/` + +### Python Dependencies +- `ebooklib` - EPUB generation +- `markdown` - Markdown to HTML conversion +- `beautifulsoup4` - HTML parsing/manipulation +- `httpx` - HTTP client (for Mermaid diagram rendering) +- `pillow` - Image processing +- `tenacity` - Retry logic for external API calls + +### Development Tools +- `uv` - Python package manager and virtual environment +- `ruff` - Linting and formatting (replaces black, isort, flake8) +- `bandit` - Security scanning +- `pytest` / `pytest-asyncio` - Testing framework +- `pre-commit` - Git hooks for code quality + +### CI/CD +- **GitHub Actions** - Automated linting, security scanning, testing, and EPUB builds +- Workflows in `.github/workflows/ci.yml` and `.github/workflows/release.yml` + +## Project Conventions + +### Code Style +- **Python**: Ruff for linting and formatting + - Line length: 88 characters + - Target: Python 3.10 + - Double quotes, space indentation + - Import sorting: isort rules via Ruff +- **Markdown**: Standard GitHub-Flavored Markdown +- **YAML/JSON**: Validated via pre-commit hooks + +### Architecture Patterns +- **Numbered directories** (01-09) for learning progression +- **Each feature folder** contains: + - Example files demonstrating the feature + - `README.md` with detailed explanations +- **Scripts directory** contains Python tooling: + - `build_epub.py` - Main EPUB builder with async Mermaid rendering + - `tests/` - pytest test suite + +### Testing Strategy +- **Unit tests** in `scripts/tests/` +- **Pytest** with `pytest-asyncio` for async code +- **CI runs tests** on every push/PR to `main` +- **Test coverage** focused on EPUB builder functionality + +### Git Workflow +- **Main branch**: `main` +- **PRs required** for contributions +- **Pre-commit hooks** enforce: + - Ruff lint and format + - Bandit security scan + - YAML/TOML validation + - Trailing whitespace and EOF fixes +- **Commit messages**: Descriptive, no co-author attribution required +- **No time estimates** in commits or PRs + +## Domain Context + +### Claude Code Concepts +This repository covers nine major Claude Code features: + +1. **Slash Commands** - User-invoked shortcuts (`/optimize`, `/pr`) +2. **Memory** - Persistent context via `CLAUDE.md` files +3. **Skills** - Auto-invoked reusable capabilities +4. **Subagents** - Specialized AI assistants with isolated contexts +5. **MCP Protocol** - External tool/API access +6. **Hooks** - Event-driven shell command automation +7. **Plugins** - Bundled feature collections +8. **Checkpoints** - Session snapshots and rewind +9. **Advanced Features** - Planning mode, extended thinking, background tasks + +### Installation Targets +Examples are designed to be copied to: +- `~/.claude/` - Personal/global configurations +- `.claude/` - Project-specific configurations +- Root project directory - For `CLAUDE.md` memory files + +## Important Constraints + +- **Python 3.10+** required for all scripts +- **Virtual environment** must be activated before running Python (configured in `~/.claude/CLAUDE.md`) +- **No Claude co-author** in commit messages (per user preferences) +- **No auto-commits/pushes** without explicit user request +- **Large files** limited to 1MB (pre-commit hook) +- **Security scans** must pass (Bandit) + +## External Dependencies + +### External Services +- **Mermaid.ink API** - Renders Mermaid diagrams to images for EPUB + - Used in `build_epub.py` with retry logic via `tenacity` + - Rate limiting handled with exponential backoff + +### GitHub Integration +- **GitHub Actions** for CI/CD +- **GitHub Releases** for versioned EPUB distribution +- Example MCP configurations reference GitHub API tokens + +### No Runtime External Dependencies +- Documentation is static markdown +- EPUB can be built offline (diagrams cached or skip rendering)