### Installation Summary Example

Source: https://github.com/carlrannaberg/claudekit/blob/main/reports/SETUP_EXPERIENCE_2025-08-10.md

An example of the installation summary presented to the user after making selections.

```text
Installation Summary
────────────────────────────────────────
• Command Groups: 2 selected (Git Workflow, Validation)
• Hook Groups: 2 selected (File Validation, Completion Validation)
• Subagents: 23 selected (all domain experts)

Total components to install: ~40+ items
```

--------------------------------

### claudekit setup examples

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/reference/cli.md

Examples of how to use the claudekit setup command.

```bash
# Interactive setup (recommended)
claudekit setup

# Install everything with defaults
claudekit setup --all --yes

# Install specific components
claudekit setup --commands git:commit,spec:create --hooks typecheck-changed

# Install for user globally
claudekit setup --user
```

--------------------------------

### Confirmation Example

Source: https://github.com/carlrannaberg/claudekit/blob/main/reports/SUBAGENT_GROUPS_PROPOSAL.md

Example output from the confirmation step, listing the selected agents for installation.

```bash
Selected Agents (12):

Core:
  • typescript-expert (detected)
  • react-expert (detected)
  • nodejs-expert

Specialists:
  • react-performance-expert
  • postgres-expert (detected)
  • jest-expert (detected)
  • webpack-expert (detected)

Quality:
  • testing-expert
  • code-quality-expert
  • git-expert

Support:
  • database-expert
  • css-styling-expert

[Install] [Customize] [Back]
```

--------------------------------

### Agent Installation Commands

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/reference/subagents.md

Examples of how to install all agents, specific agents, or agents by category using the claudekit setup command.

```bash
claudekit setup --all
```

```bash
claudekit setup --agents typescript-expert,react-expert
```

```bash
claudekit setup --agents testing-expert,jest-expert,vitest-testing-expert,playwright-expert
```

--------------------------------

### Good Troubleshooting Examples

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/internals/writing-guides.md

Examples of actionable and effective troubleshooting steps.

```markdown
- Check if registered: `/hooks` command
- View execution: `claude --debug`
- Validate JSON: `jq . config.json`
```

--------------------------------

### README Structure - Quick Start and Hook Setup

Source: https://github.com/carlrannaberg/claudekit/blob/main/specs/feat-plugin-marketplace-transformation.md

Example README structure for the claudekit Plugin Marketplace, including quick start commands for adding the marketplace and installing plugins, and a section detailing the hook setup requirements.

```markdown
# claudekit Plugin Marketplace

## Quick Start

```bash
# Add marketplace
/plugin marketplace add claudekit/plugins

# Install plugins
/plugin install ck-git@claudekit
```

## ⚠️ Hook Setup Required

Plugins with hooks (ck-quality) require claudekit-hooks:
```bash
npm install -g claudekit  # provides claudekit-hooks CLI
```

If hooks fail: `npm install -g claudekit`

## Available Plugins

| Plugin | Description | Skills | Model-Invocable | Hooks |
|--------|-------------|--------|-----------------|-------|
| ck-git | Git automation | commit, push, status, checkout, repo-init | commit | No |
| ck-spec | Specifications | create, validate, decompose, execute | create, validate, decompose | No |
| ck-quality | Code quality | code-review, refactor | code-review, refactor | **Yes** |
| ck-agents-md | AI config | init, migration, cli | - | No |
| ck-core | Hook management | hook-disable, hook-enable, hook-status | - | No |

> **Note**: Checkpoints are built-in to Claude Code. Use `/rewind` or Esc+Esc.

## Model-Invocable Skills

Just describe what you want (confirmation required for changes):
- "commit my changes" → commit skill (confirms before staging)
- "review my code" → code-review skill
- "refactor this code" → refactor skill
```

--------------------------------

### Basic Usage Example

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/guides/codebase-map.md

Demonstrates the one-time installation and setup, followed by starting a Claude Code session where the codebase map is automatically provided and updated.

```bash
# Install and setup (one-time)
npm install -g claudekit codebase-map && claudekit setup --yes --force --hooks codebase-map,codebase-map-update

# Start Claude Code session
# → Codebase map automatically provided as context
# → Edit files via Claude Code
# → Context automatically updates
```

--------------------------------

### Project Analysis Example

Source: https://github.com/carlrannaberg/claudekit/blob/main/reports/SUBAGENT_GROUPS_PROPOSAL.md

Example output from the project analysis step, showing detected technologies.

```bash
🔍 Analyzing your project...

Detected:
  ✓ TypeScript (tsconfig.json)
  ✓ React 18.2.0 (package.json)
  ✓ Jest 29.0.0 (jest.config.js)
  ✓ PostgreSQL (database config)
  ✓ Webpack 5 (webpack.config.js)
```

--------------------------------

### Examples of Oracle Agent Invocation

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/integrations/oracle.md

Examples demonstrating how to invoke the Oracle agent for various tasks.

```bash
"Use the oracle agent to debug this race condition"
```

```bash
"Ask oracle to review this architecture"
```

```bash
"Debug this complex issue" # Oracle will be used automatically
```

--------------------------------

### Smart Recommendations Example

Source: https://github.com/carlrannaberg/claudekit/blob/main/reports/SUBAGENT_GROUPS_PROPOSAL.md

Example output from the smart recommendations step, suggesting agent groups based on project analysis.

```bash
Based on your project, we recommend:

🎯 Smart Match (12 agents) ← RECOMMENDED
   Perfectly tailored to your project

Choose a preset:
  ( ) Essential - Core agents only (5)
  (•) Smart Match - Project-specific (12)
  ( ) Professional - Comprehensive (18)
  ( ) Everything - All agents (23)
  ( ) Custom - Choose individually
  
Or select by role:
  [✓] Frontend Developer (7 agents)
  [ ] QA Engineer (6 agents)
  [ ] DevOps Engineer (5 agents)
```

--------------------------------

### Documentation Examples for All Package Managers

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/internals/package-managers.md

Example of showing installation commands for all supported package managers in documentation.

```markdown
Install globally:
- npm: `npm install -g <package>`
- yarn: `yarn global add <package>`
- pnpm: `pnpm add -g <package>`
```

--------------------------------

### Starting a New Feature

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/README.md

Example command for starting a new feature.

```bash

```

--------------------------------

### Step-by-Step Instruction Real Example

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/internals/prompting-guide.md

A practical example demonstrating the step-by-step instruction pattern for converting PS1 configuration.

```markdown
When asked to convert PS1 configuration, follow these steps:
1. Read shell configuration files in this order:
   - ~/.zshrc
   - ~/.bashrc
   - ~/.bash_profile
2. Extract PS1 value using regex: /(?:^|\n)\s*(?:export\s+)?PS1\s*=\s*["']([^"']+)["']/m
3. Convert escape sequences:
   - \u → $(whoami)
   - \h → $(hostname -s)
   - \w → $(pwd)
```

--------------------------------

### Example: We're looking for how the database connection is setup

Source: https://github.com/carlrannaberg/claudekit/blob/main/src/agents/code-search.md

Illustrates using multiple tools in parallel for a broader search.

```bash
LS('config/') & Grep('database') & Grep('connection')
```

--------------------------------

### Environment Detection Example

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/internals/creating-subagents.md

Example of detecting project setup using internal tools before resorting to shell commands.

```bash
# Detect project setup using Read/Grep before shell commands
test -f {config-file} && echo "{Framework} detected"
# Additional detection patterns
```

--------------------------------

### Hook Description Example

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/internals/component-description-guide.md

Example of how to describe a hook, illustrating the 'create-checkpoint' hook for automatic backup.

```markdown
#### [create-checkpoint](../cli/hooks/create-checkpoint.ts)

Automatic backup system for Claude Code sessions using git stash create/store pattern to preserve work without disrupting workflow.

**Triggers**: `Stop` and `SubagentStop` events with universal matcher

**Implementation**: Git status detection, temporary staging, stash object creation, index reset, and automatic cleanup of aged checkpoints

**Behavior**: Silent execution without workflow interruption, provides backup safety net without modifying working directory
```

--------------------------------

### Bad Troubleshooting Examples

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/internals/writing-guides.md

Examples of ineffective or vague troubleshooting steps.

```markdown
- Test manually: `command-name`  # Doesn't work without proper input
- Check target patterns  # Vague, not actionable
- Ensure transcript path  # What does this mean?
```

--------------------------------

### Installation Structure Example

Source: https://github.com/carlrannaberg/claudekit/blob/main/.replit.md

Details the user-level and project-level installation structures for ClaudeKit, showing where settings and commands are placed.

```bash
~/.claude/                    # User-level installation
├── settings.json            # User settings (env vars and global hooks)
└── commands/                # Copied commands from src/commands/

<project>/.claude/            # Project-level
├── settings.json            # Hook configuration for this project
└── hooks/                   # Legacy - hooks now managed by embedded system
```

--------------------------------

### Good Organization Example

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/guides/project-organization.md

An example of a well-organized project structure following claudekit conventions, with reports in 'reports/' and temporary files in 'temp/'.

```tree
my-project/
├── reports/
│   ├── implementation/
│   │   └── FEATURE_AUTH_IMPLEMENTATION.md
│   └── testing/
│       └── TEST_RESULTS_2024-07-18.md
├── temp/
│   ├── debug-auth-flow.js
│   └── analyze-performance.py
├── src/
│   └── auth/
│       └── login.js
└── .gitignore (includes /temp/)

```

--------------------------------

### Proper Fix - Manual repository creation and relationship setup

Source: https://github.com/carlrannaberg/claudekit/blob/main/src/agents/loopback/loopback-expert.md

Example of manual repository creation and relationship setup when the CLI fails.

```typescript
// Manual repository creation when CLI fails
@repository(UserRepository)
export class UserController {
  constructor(@repository(UserRepository) public userRepository: UserRepository) {}

  // Manual relationship setup
  @get('/users/{id}/orders')
  async getOrders(@param.path.number('id') id: number): Promise<Order[]> {
    return this.orderRepository.find({ where: { userId: id } });
  }
}
```

--------------------------------

### Refactoring Duplicated Setup Code

Source: https://github.com/carlrannaberg/claudekit/blob/main/src/agents/testing/testing-expert.md

JavaScript example demonstrating how to refactor repetitive setup code in tests by using shared utility functions.

```javascript
// Bad: Repetitive setup
beforeEach(() => {
  mockDatabase.clear();
  mockAuth.login({ id: 1, role: 'user' });
});

// Good: Shared test utilities
// tests/utils/setup.js
export const setupTestUser = (overrides = {}) => ({
  id: 1,
  role: 'user',
  ...overrides
});

export const cleanDatabase = () => mockDatabase.clear();
```

--------------------------------

### Begin in a specified permission mode

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/official/cli.md

Example of starting Claude Code in a specific permission mode.

```bash
claude --permission-mode plan
```

--------------------------------

### Post-Command Suggestions

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/internals/writing-guides.md

Example of suggested next steps after a command is run, emphasizing user actions.

```shell
✓ Complete! Next steps:
1. Review changes: git status
2. Stage files: git add AGENTS.md
3. Commit: git commit -m "feat: update"
```

--------------------------------

### Template for Feature Installation Instructions

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/internals/writing-guides.md

A consistent template for all feature installation instructions, emphasizing the use of `--yes --force` flags for non-interactive execution and overwriting existing configurations.

```bash
# Template for all feature installation instructions
npm install -g claudekit && claudekit setup --yes --force --hooks FEATURE_NAME

```

--------------------------------

### Install the Context7 MCP server globally

Source: https://context7.com/carlrannaberg/claudekit/llms.txt

Instructions for installing the Context7 MCP server globally using npm, yarn, or pnpm.

```bash
# Step 1: Install the Context7 MCP server globally
# Using your preferred package manager:
# npm:
npm install -g @upstash/context7-mcp

# yarn:
yarn global add @upstash/context7-mcp

# pnpm:
pnpm add -g @upstash/context7-mcp
```

--------------------------------

### Read Tool Requirements Example

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/internals/prompting-guide.md

Example of specifying requirements for the 'Read' tool, including parameter constraints and usage best practices.

```markdown
Read Tool Requirements:
- file_path parameter must be absolute path
- Use offset/limit for large files
- Batch multiple reads when possible
```

--------------------------------

### Example Architecture Diagram

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/internals/writing-guides.md

A simple text-based diagram illustrating a user input processing flow.

```text
┌─────────────────────────────────────────────┐
│              User Input                      │
└─────────────────┬───────────────────────────┘
                  ↓
┌─────────────────────────────────────────────┐
│            Processing Step                   │
│  • Key action 1                             │
│  • Key action 2                             │
└─────────────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────────────┐
│              Output                          │
└─────────────────────────────────────────────┘

```

--------------------------------

### CLI Commands

Source: https://github.com/carlrannaberg/claudekit/blob/main/README.md

Examples of various claudekit CLI commands for setup, listing components, showing agent/command details, and status checking.

```bash
claudekit setup              # Interactive setup wizard
claudekit setup --yes        # Quick setup with defaults
claudekit setup --all        # Install everything (all agents)
claudekit setup --user       # Install in user directory (~/.claude) instead of project
claudekit list               # Show all components (hooks, commands, agents, config)
claudekit list agents        # List available agents with token counts
claudekit list commands      # List available commands with token counts
claudekit show agent <id>    # Display agent prompt for external use
claudekit show command <id>  # Display command prompt for external use
claudekit show agent <id> -f json    # Output agent metadata and content as JSON
claudekit show command <id> -f json  # Output command metadata and content as JSON
claudekit doctor             # Check your installation and validate documentation links

# Tool status checking
claudekit status stm         # Check Simple Task Master (STM) installation and initialization status

# Linting and validation
claudekit lint-commands      # Lint slash command markdown files
claudekit lint-agents        # Lint agent markdown files (formerly lint-subagents)

# Hook management and profiling
claudekit-hooks run <hook>   # Execute a specific hook manually
claudekit-hooks profile      # Profile all configured hooks performance
claudekit-hooks profile <hook> --iterations 5  # Profile specific hook with averaging

# Session-based hook control (within Claude Code sessions)
claudekit-hooks disable <hook>  # Disable hook for current session
claudekit-hooks enable <hook>   # Re-enable hook for current session  
claudekit-hooks status <hook>   # Show hook status (enabled/disabled)
```

--------------------------------

### Multiple File References Example

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/internals/creating-commands.md

An example demonstrating how to reference multiple configuration files within a command.

```markdown
Review these files:
- Config: @tsconfig.json
- ESLint: @.eslintrc.js
- Package: @package.json

```

--------------------------------

### Copy Example Configuration

Source: https://github.com/carlrannaberg/claudekit/blob/main/examples/README.md

How to copy an example configuration file to your project.

```bash
cp examples/settings.typescript.json .claude/settings.json
```

--------------------------------

### Feature Guide Structure Template

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/internals/writing-guides.md

A recommended markdown structure for feature guides, including sections for overview, installation, architecture, how it works, usage examples, design decisions, and limitations.

```markdown
# Feature Name

## Overview
Brief description of what it does and why it matters.

## Installation
```bash
# One-liner when possible
claudekit setup --yes --force --commands feature
```

## Architecture
[Visual diagram if it helps understanding]

## How It Works
1. Clear step one
2. Clear step two
3. Clear step three

## Usage Examples
[Concrete, runnable examples]

## Key Design Decisions
[Why it works this way]

## Limitations
[Be honest about constraints]

```

--------------------------------

### Initial Setup Workflow

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/reference/cli.md

Steps for performing an initial setup of claudekit.

```bash
# 1. Install claudekit globally
npm install -g claudekit

# 2. Navigate to your project
cd my-project

# 3. Run interactive setup
claudekit setup

# 4. Validate installation
claudekit doctor
```

--------------------------------

### Setup/Takedown Code Example

Source: https://github.com/carlrannaberg/claudekit/blob/main/specs/feat-plugin-marketplace-transformation.md

Illustrates the difference between bad setup/takedown code and good interface design for processing withdrawals.

```javascript
// Bad: Setup and takedown around the call
withdrawal.setCustomerId(customerId);
withdrawal.setBalance(balance);
processWithdrawal(withdrawal);
customerId = withdrawal.getCustomerId();

// Good: Interface accepts what's needed
processWithdrawal(customerId, balance, amount);
```

--------------------------------

### Quick Start Commands

Source: https://github.com/carlrannaberg/claudekit/blob/main/README.md

Example commands to set up claudekit and common commands to use within Claude Code for various tasks like git status, spec creation, and code review.

```bash
# Initialize in your project
claudekit setup

# In Claude Code, try these commands:
/git:status                      # Groups changes by type & suggests commit strategy
/spec:create "your next feature" # Researches codebase & writes full spec
/code-review                     # 6 specialized agents analyze code in parallel
```

--------------------------------

### Diagnostics for Installation & Setup Issues

Source: https://github.com/carlrannaberg/claudekit/blob/main/reports/agent-research/cli/expert-research.md

A set of bash commands to diagnose common installation and setup problems for CLI tools, including checking the npm global bin location, verifying binary creation, and inspecting the shebang in installed scripts.

```bash
# Check npm global bin location
npm config get prefix
echo $PATH | grep -q "$(npm config get prefix)/bin" && echo "PATH configured" || echo "PATH missing npm bin"

# Verify binary creation
ls -la node_modules/.bin/

# Check shebang in installed script
head -n1 $(which your-cli)
```

--------------------------------

### Manual Steps for Publishing

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/integrations/npm-publishing.md

Provides a step-by-step guide for manually publishing to NPM, including git operations, testing, building, version bumping, and publishing.

```bash
# 1. Ensure you're on main and up to date
git checkout main
git pull origin main

# 2. Run tests
npm run test:ci
npm run lint
npm run typecheck

# 3. Build
npm run build

# 4. Bump version
npm version patch  # or minor, major

# 5. Publish
npm publish --access public

# 6. Push git changes
git push origin main --tags
```

--------------------------------

### Full Validation Setup

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/reference/hooks.md

Example configuration for comprehensive validation setup with additional hooks.

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {"type": "command", "command": "claudekit-hooks run typecheck-changed"},
          {"type": "command", "command": "claudekit-hooks run check-any-changed"}
        ]
      },
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {"type": "command", "command": "claudekit-hooks run lint-changed"}
        ]
      },
      {
        "matcher": "Write,Edit,MultiEdit",
        "hooks": [
          {"type": "command", "command": "claudekit-hooks run test-changed"}
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "*",
        "hooks": [
          {"type": "command", "command": "claudekit-hooks run create-checkpoint"},
          {"type": "command", "command": "claudekit-hooks run check-todos"},
          {"type": "command", "command": "claudekit-hooks run typecheck-project"},
          {"type": "command", "command": "claudekit-hooks run lint-project"},
          {"type": "command", "command": "claudekit-hooks run test-project"}
        ]
      }
    ]
  }
}
```

--------------------------------

### First Release with Script

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/integrations/npm-publishing.md

Instructions for performing the initial publication using the local release script.

```bash
# From project root
./scripts/release.sh --dry-run  # Review what will happen
./scripts/release.sh            # Execute the release
```

--------------------------------

### Installation and Setup

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/guides/typescript-hooks.md

Command to install claudekit globally and set up the typecheck-changed and typecheck-project hooks.

```bash
npm install -g claudekit && claudekit setup --yes --force --hooks typecheck-changed,typecheck-project
```

--------------------------------

### Verify package manager installation

Source: https://context7.com/carlrannaberg/claudekit/llms.txt

Commands to verify the installation and version of npm, yarn, and pnpm.

```bash
# For npm:
npm --version
npx --version

# For yarn:
yarn --version

# For pnpm:
pnpm --version
```

--------------------------------

### claudekit setup command and options

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/reference/cli.md

Initializes claudekit in your project with interactive configuration.

```bash
claudekit setup [options]

Options:
  -f, --force               Overwrite existing .claude directory
  -y, --yes                 Automatic yes to prompts (use defaults)
  --all                     Install all features including all 24+ agents
  --skip-agents             Skip subagent installation
  --commands <list>         Comma-separated list of command IDs to install
  --hooks <list>            Comma-separated list of hook IDs to install  
  --agents <list>           Comma-separated list of agent IDs to install
  --user                    Install in user directory (~/.claude) instead of project
  --project <path>          Target directory for project installation
  --select-individual       Use legacy individual component selection
```

--------------------------------

### Install External CLI Tools

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/integrations/oracle.md

Commands to install preferred external CLI tools for the Oracle subagent.

```bash
curl https://cursor.com/install -fsS | bash
```

```bash
npm install -g @openai/codex
```

```bash
npm i -g opencode-ai@latest
```

--------------------------------

### Starting a new feature workflow

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/getting-started/installation.md

Workflow for starting a new feature, including creating a checkpoint and generating a specification.

```bash
# Create a checkpoint before starting
/checkpoint:create Starting feature X

# Generate a specification
/spec:create feature X

# Work on the feature...
# Hooks will automatically validate your code
```

--------------------------------

### Migration Guide: Create Directories

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/guides/project-organization.md

Commands to create the necessary directory structure for reports and temporary files during project migration.

```bash
mkdir -p reports/{implementation,testing,performance,validation}
mkdir -p temp/{debug,test-artifacts,experiments,logs}

```

--------------------------------

### User Configuration Example

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/reference/cli.md

Example of user-level environment variables in ~/.claude/settings.json.

```json
{
  "env": {
    "BASH_DEFAULT_TIMEOUT_MS": "600000",
    "CUSTOM_VAR": "value"
  }
}
```

--------------------------------

### Package Installation Test

Source: https://github.com/carlrannaberg/claudekit/blob/main/reports/testing/AGENT-MANUAL-TESTING-2025-08-09.md

Tests building, packing, and installing the claudekit package, followed by setup.

```bash
cd /path/to/claudekit
npm run build
npm pack
cd /tmp/test-package
npm install /path/to/claudekit-*.tgz
npx claudekit setup --all
```

--------------------------------

### Project Configuration Example

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/reference/cli.md

Example of project-specific hook configuration in .claude/settings.json.

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [{"type": "command", "command": "claudekit-hooks run typecheck-changed"}]
      }
    ]
  }
}
```

--------------------------------

### Install Claudekit and Setup Agents

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/guides/using-prompts-with-external-llms.md

Installs claudekit globally and sets up specified expert agents.

```bash
# Install claudekit (if not already installed)
npm install -g claudekit && claudekit setup --yes --force --agents typescript-expert,react-expert,postgres-expert
```

--------------------------------

### Edit Tool Requirements Example

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/internals/prompting-guide.md

Example of specifying requirements for the 'Edit' tool, including prerequisites and constraints.

```markdown
Edit Tool Requirements:
- Must use Read tool first in conversation
- old_string must be unique in file
- All edits must result in valid code
```

--------------------------------

### List available hooks

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/getting-started/installation.md

List all available hooks in claudekit.

```bash
claudekit-hooks list
```

--------------------------------

### File References Example

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/internals/creating-commands.md

Example of including file contents using the '@' prefix.

```markdown
# Include package.json
Package info: @package.json

# Include source file
Current implementation: @src/main.ts
```

--------------------------------

### Initialize claudekit in your project

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/getting-started/installation.md

Initialize claudekit in your project directory. This will create a .claude directory, analyze your project, generate a recommended settings.json configuration, and set up directories for hooks and commands.

```bash
cd your-project
claudekit setup
```

--------------------------------

### Example: Which files handle the user authentication flow?

Source: https://github.com/carlrannaberg/claudekit/blob/main/src/agents/code-search.md

Demonstrates using parallel Grep commands for multiple related terms.

```bash
Grep('login') & Grep('authenticate') & Grep('auth') & Grep('authorization')
```

--------------------------------

### Quick Docker Setup

Source: https://github.com/carlrannaberg/claudekit/blob/main/src/agents/loopback/loopback-expert.md

A basic Dockerfile for setting up a Node.js application with LoopBack.

```dockerfile
# Quick Docker setup
FROM node:16-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY dist ./
dist
EXPOSE 3000
CMD ["node", "."]
```

--------------------------------

### Fresh Installation Test Command

Source: https://github.com/carlrannaberg/claudekit/blob/main/reports/testing/AGENT-MANUAL-TESTING-2025-08-09.md

Command to perform a fresh interactive installation of claudekit, focusing on subagent setup.

```bash
mkdir /tmp/test-claudekit-fresh
cd /tmp/test-claudekit-fresh
claudekit setup
```

--------------------------------

### Example .agentignore configuration

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/guides/file-guard.md

Demonstrates how to block all .env files while allowing specific example files.

```gitignore
# Block all .env files
.env*

# But allow example files  
!.env.example
!.env.template
```

--------------------------------

### Subagent Description Example - Non-Domain Expert

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/internals/component-description-guide.md

Example of how to describe a non-domain expert subagent, focusing on its specialized approach to code review.

```markdown
#### [code-review-expert](../src/agents/code-review-expert.md)

Single-focus code review subagent that gets launched multiple times concurrently by `/code-review` command, with each instance specializing in one review aspect rather than handling all aspects simultaneously.

**Tools**: `Read, Grep, Glob, Bash`
**Specialization**: Cross-file intelligence analysis, evolutionary pattern tracking, solution-oriented feedback with working code examples, dynamic integration with domain experts, and context-aware pattern detection with impact-based prioritization within assigned focus area
```

--------------------------------

### Subagent Description Example - Domain Expert

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/internals/component-description-guide.md

Example of how to describe a domain expert subagent, highlighting its specialization in TypeScript type systems.

```markdown
#### [typescript-type-expert](../src/agents/typescript/typescript-type-expert.md)

Advanced TypeScript type system specialist for complex generics, conditional types, and type-level programming challenges.

**Tools**: `Read, Edit, MultiEdit, Bash, Grep, Glob`
**Specialization**: Recursive types, brand types, utility type authoring, template literal types, and type performance optimization with comprehensive coverage of 18 advanced type system error patterns
```

--------------------------------

### First Release with GitHub Workflow

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/integrations/npm-publishing.md

Instructions for performing the initial publication using the automated GitHub workflow.

```bash
# Push your changes to main
git push origin main

# Go to GitHub Actions → Version workflow → Run workflow
# Select "patch" (for v0.1.0 → v0.1.1 or similar)
# The release will automatically follow
```

--------------------------------

### Installation and Setup

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/guides/codebase-map.md

Installs claudekit and the codebase-map tool, then adds the necessary hooks for session context and live updates.

```bash
# Install claudekit and codebase-map tool (if not already installed)
npm install -g claudekit codebase-map

# Add both codebase map hooks to your project  
claudekit setup --yes --force --hooks codebase-map,codebase-map-update
```

--------------------------------

### Monitoring Trends Example

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/guides/hook-profiling.md

Shows how to save a baseline profile and compare it with the current profile after making changes to track performance trends.

```bash
# Save baseline
claudekit-hooks profile > baseline.txt

# Compare after changes
claudekit-hooks profile > current.txt
diff baseline.txt current.txt
```

--------------------------------

### Security Constraints Example

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/internals/prompting-guide.md

Example of defining specific security constraints for tool and path access, forbidden operations, and required validations.

```markdown
Security Constraints:
- Tool access limited to: [specific tools]
- Path access restricted to: [specific directories]
- Operations forbidden: [specific actions]
- Required validations: [automatic checks]
```

--------------------------------

### Frontmatter Example

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/official/commands.md

Provides an example of command file frontmatter, including allowed tools, argument hint, description, and model.

```markdown
---
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
argument-hint: [message]
description: Create a git commit
model: haiku
---

An example command
```

--------------------------------

### Example .gitignore patterns

Source: https://github.com/carlrannaberg/claudekit/blob/main/src/commands/agents-md/init.md

Illustrates common patterns for ignoring temporary files, debugging scripts, and Claude-specific settings while ensuring the reports directory is not ignored.

```gitignore
# Temporary files and debugging
/temp/
temp/
**/temp/
debug-*.js
test-*.py
analyze-*.sh
*-debug.*
*.debug

# Claude settings
.claude/settings.local.json

# Don't ignore reports directory
!reports/
!reports/**
```

--------------------------------

### Simple Command Example

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/internals/component-description-guide.md

Example of a well-structured description for a simple command, including its purpose, tools, context collection, processing flow, and output.

```markdown
#### [/checkpoint:create](../src/commands/checkpoint/create.md)

Uses git stash create/store pattern to preserve working directory state without disrupting current files.

**Tools**: `Bash(git stash:*), Bash(git add:*), Bash(git status:*)

**Context collection**: Current working directory status and file changes

**Processing flow**:
1. Temporarily stages all files
2. Creates stash object without affecting working directory
3. Stores stash with descriptive message
4. Resets index to restore original state
5. Verifies checkpoint creation

**Output**: Confirmation message with checkpoint details and preserved state summary
```

--------------------------------

### .gitignore Configuration Example

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/internals/claude-code-config.md

An example of how to configure `.gitignore` to exclude local Claude Code settings while including team settings and commands.

```gitignore
# Claude Code local settings
.claude/settings.local.json
*.local.json

# Don't ignore team settings
!.claude/settings.json
!.claude/commands/
# Hooks are managed via embedded system
```

--------------------------------

### Distinguishing Command Output from User Instructions (Good Example)

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/internals/writing-guides.md

Illustrates how to clearly differentiate between automatic command actions, provided guidance, and manual user steps when documenting commands.

```markdown
## After Running the Command

This command automatically stages and commits your changes.

**Next Steps:**

1. Review the changes:
   ```bash
   git diff --staged
   ```
2. If satisfied, push the changes:
   ```bash
   git push
   ```

```

--------------------------------

### Complex Command Example

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/internals/component-description-guide.md

Example of a well-structured description for a complex command, detailing its advanced features like parallel execution, subagents, and phased fixing.

```markdown
#### [/validate-and-fix](../src/commands/validate-and-fix.md)

Runs quality checks and automatically fixes discovered issues using parallel execution with specialized subagents, organized into risk-based phases.

**Tools**: `Bash, Task, TodoWrite, Read, Edit, MultiEdit`

**Context collection**: Available validation commands from AGENTS.md, package.json scripts, README.md, and common project patterns (lint, typecheck, test, build commands)

**Processing flow**:
1. Discovers and categorizes available quality checks by priority (Critical → High → Medium → Low)
2. Executes parallel validation using Bash to capture full output with file paths and error details
3. Assesses risks and maps issue dependencies before fixing
4. Applies fixes in phases: safe quick wins → functionality fixes → critical issues with confirmation
5. Creates git stash checkpoints between phases and verifies each fix immediately
6. Routes specialized tasks to domain expert subagents
7. Re-runs all checks for final verification and provides fix/remaining issue summary

**Output**: Real-time progress updates, confirmation of each successful fix, summary report of resolved issues vs. remaining manual tasks, and rollback instructions if fixes cause problems
```

--------------------------------

### Poor Organization Example (cleaned by /dev:cleanup)

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/guides/project-organization.md

An example of a poorly organized project structure that would be identified and cleaned by the `/dev:cleanup` command.

```tree
my-project/
├── debug-auth.js              # Should be in temp/
├── TEST_SUMMARY.md            # Should be in reports/testing/
├── analyze-performance.js     # Should be in temp/
├── test-integration/          # Should be in temp/
├── MIGRATION_COMPLETE.md      # Should be in reports/
└── quick-test.js              # Should be in temp/

```

--------------------------------

### Combined Installation Command

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/internals/writing-guides.md

A single command that installs claudekit globally and sets up a specific feature, ensuring proper execution order and preventing missed steps.

```bash
# Single command that handles both requirements
npm install -g claudekit && claudekit setup --yes --force --hooks feature

```

--------------------------------

### Install Claudekit and setup checkpoint system

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/guides/checkpoint.md

Install claudekit globally and then add the checkpoint system to your project, enabling automatic saves and specific commands.

```bash
# Install claudekit (if not already installed)
npm install -g claudekit

# Add checkpoint system to your project
claudekit setup --yes --force --hooks create-checkpoint --commands checkpoint:create,checkpoint:restore,checkpoint:list
```

--------------------------------

### Best Practice - Complete testing setup with package.json scripts

Source: https://github.com/carlrannaberg/claudekit/blob/main/src/agents/loopback/loopback-expert.md

Shows a best practice for comprehensive testing automation, including scripts for watch mode in package.json.

```json
// package.json
{
  "scripts": {
    "start:watch": "tsc-watch --target es2017 --outDir ./dist --onSuccess \"node .\"",
    "test:watch": "mocha --recursive dist/__tests__/**/*.js --watch"
  },
  "nodemonConfig": {
    "watch": ["src"],
    "ext": "ts",
    "exec": "npm start"
  }
}
```

--------------------------------

### Phase 1 Task Execution Example

Source: https://github.com/carlrannaberg/claudekit/blob/main/reports/TASK_DECOMPOSITION_HOOK_REFACTOR_2025-08-01.md

Example commands to view and start Phase 1 tasks, focusing on parallel implementation of new hooks.

```bash
# View all Phase 1 tasks
stm list --tags phase1 --status pending

# Start implementing new hooks in parallel
stm update 51 --status in_progress
stm update 52 --status in_progress
stm update 53 --status in_progress
```

--------------------------------

### Command with File Analysis Example

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/internals/creating-commands.md

A command to analyze project dependencies and suggest updates.

```markdown
---
description: Analyze dependencies
allowed-tools: Read, Bash(npm:*, pnpm:*, yarn:*)
category: validation
---

Current dependencies:
@package.json

Outdated packages:
!`$(command -v pnpm >/dev/null 2>&1 && echo "pnpm outdated" || command -v yarn >/dev/null 2>&1 && echo "yarn outdated" || echo "npm outdated")`

Suggest which packages to update based on the above information.
```

--------------------------------

### Test a hook manually

Source: https://github.com/carlrannaberg/claudekit/blob/main/docs/getting-started/installation.md

Manually test a specific hook, for example, the typecheck-changed hook.

```bash
claudekit-hooks test typecheck-changed --file src/index.ts
```