### README Installation Section - Quick Install

Source: https://github.com/citypaul/.dotfiles/blob/main/VERSIONING-DISTRIBUTION-ANALYSIS.md

Provides markdown examples for installing the latest or a specific version of the Claude guidelines using a one-line curl and bash command.

```markdown
## Installation

### Option 1: Quick Install (Recommended)

Install the latest version:

```bash
curl -fsSL https://raw.githubusercontent.com/citypaul/.dotfiles/main/install-claude.sh | bash
```

Install a specific version:

```bash
curl -fsSL https://raw.githubusercontent.com/citypaul/.dotfiles/main/install-claude.sh | bash -s v2.0.0
```
```

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

### Project Setup and Feature Planning

Source: https://github.com/citypaul/.dotfiles/blob/main/_autodocs/README.md

Guides through the initial project setup, planning a new feature, and the TDD workflow including RED, GREEN, MUTATE, KILL MUTANTS, and REFACTOR stages. It also includes a command to continue to the next slice.

```bash
# 1. Setup project
/setup

# 2. Plan feature
/plan "Implement checkout"

# 3. Implement with TDD
# RED: Write failing test
# GREEN: Minimal code to pass
# MUTATE: Run Stryker
# KILL MUTANTS: Fix test gaps
# REFACTOR: Clean if it adds value
# /pr: Create PR when complete

# 4. Continue to next slice
/continue
```

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

### Usage Examples for Shell Installer

Source: https://github.com/citypaul/.dotfiles/blob/main/VERSIONING-DISTRIBUTION-ANALYSIS.md

Demonstrates how to use the install-claude.sh script via curl to install the latest version, a specific version, or to a custom directory.

```bash
# Latest version
curl -fsSL https://raw.githubusercontent.com/citypaul/.dotfiles/main/install-claude.sh | bash

# Specific version
curl -fsSL https://raw.githubusercontent.com/citypaul/.dotfiles/main/install-claude.sh | bash -s v2.0.0

# Custom directory
CLAUDE_INSTALL_DIR=.config/claude curl -fsSL https://raw.githubusercontent.com/.../install-claude.sh | bash
```

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

### Start New Project with Claude

Source: https://github.com/citypaul/.dotfiles/blob/main/_autodocs/00-index.md

Initializes a new project and sets up the necessary CLAUDE.md configuration. This command should be run after cloning a repository or installing the CLI.

```bash
# 2. Start new project
cd my-project
/setup
```

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

### README Installation Section - Manual Installation

Source: https://github.com/citypaul/.dotfiles/blob/main/VERSIONING-DISTRIBUTION-ANALYSIS.md

Details manual installation steps for downloading specific release assets directly from GitHub releases using curl.

```markdown
### Option 2: Manual Installation

Download specific version from [releases](https://github.com/citypaul/.dotfiles/releases):

```bash
VERSION=v2.0.0

# Download CLAUDE.md
curl -o .claude/CLAUDE.md \
  https://github.com/citypaul/.dotfiles/releases/download/$VERSION/CLAUDE.md

```

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

### Download and Run Installer Script for OpenCode

Source: https://github.com/citypaul/.dotfiles/blob/main/README.md

Download the installer script, make it executable, and then run it with the --with-opencode flag for OpenCode integration. This provides more control over the installation process.

```bash
# Or download and run with options
curl -fsSL https://raw.githubusercontent.com/citypaul/.dotfiles/main/install-claude.sh -o install-claude.sh
chmod +x install-claude.sh
./install-claude.sh --with-opencode
```

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

### Initiate Feature Building with UX Planning

Source: https://github.com/citypaul/.dotfiles/blob/main/README.md

Use this command to start a structured 5-step flow for new features that require both UX planning and implementation. It guides through design, reference loading, building, iteration, and presentation.

```bash
/impeccable craft [feature description]
```

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

### Test Install Script Locally

Source: https://github.com/citypaul/.dotfiles/blob/main/CONTRIBUTING.md

Execute the install script with various flags to test its functionality, including help, specific component installation, and version pinning.

```bash
# Test with different options
./install-claude.sh --help
./install-claude.sh --claude-only
./install-claude.sh --no-agents

# Test version pinning
./install-claude.sh --version v1.0.0
```

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

### Install Claude CLI

Source: https://github.com/citypaul/.dotfiles/blob/main/_autodocs/00-index.md

Installs the Claude CLI tool globally on your system. This is the first step for individual users to start a new project.

```bash
# 1. Install globally
curl -fsSL https://raw.githubusercontent.com/citypaul/.dotfiles/main/install-claude.sh | bash
```

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

### Project Setup Workflow

Source: https://github.com/citypaul/.dotfiles/blob/main/_autodocs/06-workflow-integration.md

This diagram illustrates the one-time project setup phase, which detects project technologies and generates essential configuration files.

```text
/setup
  ↓
Detects: TypeScript, Vitest, ESLint, Prettier
  ↓
Generates: .claude/CLAUDE.md, settings.json, pr.md, pr-reviewer.md
  ↓
Ready for work
```

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

### Install All Dotfiles

Source: https://github.com/citypaul/.dotfiles/blob/main/README.md

Installs all personal dotfiles, including git, shell, vim, tmux, npm, and Claude Code settings, using a provided installation script after cloning the repository.

```bash
# Install GNU Stow first (if not already installed)
# macOS: brew install stow
# Ubuntu/Debian: sudo apt-get install stow
# Fedora: sudo dnf install stow

# Clone the repository
git clone https://github.com/citypaul/.dotfiles.git ~/.dotfiles
cd ~/.dotfiles

# Run the installation script
./install.sh
```

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

### Workflow Integration Example

Source: https://github.com/citypaul/.dotfiles/blob/main/_autodocs/03-commands-reference.md

This diagram outlines the typical workflow integration for the /continue command, showing the sequence of actions from merging a pull request to starting a new slice and preparing for the next PR.

```text
Merge to main ← PR approved
    ↓
/continue
    ↓
New feature branch created
    ↓
RED (write failing test for Slice 2)
    ↓
GREEN-MUTATE-KILL MUTANTS-REFACTOR
    ↓
/pr (Slice 2 PR)
    ↓
/continue (repeat)
```

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

### Run Setup Command

Source: https://github.com/citypaul/.dotfiles/blob/main/_autodocs/05-installation-configuration.md

Execute the /setup command to detect the tech stack and generate project configuration files.

```bash
/setup
```

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

### Install with OpenCode Support

Source: https://github.com/citypaul/.dotfiles/blob/main/_autodocs/05-installation-configuration.md

Install Claude with OpenCode support by downloading and executing the installation script.

```bash
curl -fsSL https://raw.githubusercontent.com/citypaul/.dotfiles/main/install-claude.sh | bash -s -- --with-opencode
```

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

### Verify Installation Files

Source: https://github.com/citypaul/.dotfiles/blob/main/_autodocs/05-installation-configuration.md

List and view the generated .claude configuration files to verify the installation.

```bash
ls -la .claude/
cat .claude/CLAUDE.md
cat .claude/settings.json
```

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

### Claude Code Import Syntax Examples

Source: https://github.com/citypaul/.dotfiles/blob/main/SPLIT-CLAUDE-MD-PLAN.md

Demonstrates the syntax for importing files in Claude Code. Absolute paths starting with '~' are required when referencing files from the user's home directory, especially for dotfiles.

```markdown
# In project CLAUDE.md (can use relative paths)
See @README for project overview.
For testing guidelines, see @docs/testing.md

# In ~/.claude/CLAUDE.md (must use absolute paths)
For testing guidelines, see @~/.claude/docs/testing.md

# Individual Preferences (always use absolute paths)
@~/.claude/my-project-instructions.md
```

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

### Shell Script Installer

Source: https://github.com/citypaul/.dotfiles/blob/main/VERSIONING-DISTRIBUTION-ANALYSIS.md

Bash script for installing guidelines and agents via curl. Supports version pinning and selective installation.

```bash
#!/bin/bash
# install-claude.sh

VERSION="${1:-latest}"
PACKAGES="${2:-guidelines,agents}"
INSTALL_DIR="${3:-.claude}"

# Fetch latest release if not specified
if [ "$VERSION" = "latest" ]; then
  VERSION=$(curl -s https://api.github.com/repos/citypaul/.dotfiles/releases/latest | jq -r .tag_name)
fi

# Download files from release
BASE_URL="https://github.com/citypaul/.dotfiles/releases/download/$VERSION"

if [[ $PACKAGES == *"guidelines"* ]]; then
  mkdir -p "$INSTALL_DIR/docs"
  curl -fsSL "$BASE_URL/CLAUDE.md" -o "$INSTALL_DIR/CLAUDE.md"
  # Download docs/ directory
  for doc in testing typescript code-style workflow examples working-with-claude; do
    curl -fsSL "$BASE_URL/docs/${doc}.md" -o "$INSTALL_DIR/docs/${doc}.md"
  done
fi

if [[ $PACKAGES == *"agents"* ]]; then
  mkdir -p "$INSTALL_DIR/agents"
  for agent in tdd-guardian ts-enforcer refactor-scan learn; do
    curl -fsSL "$BASE_URL/agents/${agent}.md" -o "$INSTALL_DIR/agents/${agent}.md"
  done
fi

echo "✅ Claude guidelines $VERSION installed to $INSTALL_DIR/"

```

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

### Claude Install Script Options

Source: https://github.com/citypaul/.dotfiles/blob/main/README.md

Provides a list of available command-line options for the install-claude.sh script. Use these to customize the installation, such as installing only specific components or targeting particular agents.

```bash
./install-claude.sh                                      # Install everything (CLAUDE.md + skills + commands + agents)
./install-claude.sh --claude-only                        # Install only CLAUDE.md
./install-claude.sh --skills-only                        # Install only skills (via skills.sh)
./install-claude.sh --no-agents                          # Install without agents
./install-claude.sh --no-external                        # Skip all external community skills (web-quality-skills + next-skills + impeccable + grill-me + seo-audit)
./install-claude.sh --no-impeccable                      # Skip impeccable design skills only
./install-claude.sh --with-opencode                      # Also target OpenCode for skills + install OpenCode config
./install-claude.sh --agent codex --agent cursor         # Also install skills for Codex and Cursor (repeatable)
./install-claude.sh --skills-only --no-claude-code \     # Install skills ONLY for a non-Claude agent
                    --agent codex
./install-claude.sh --version v2.0.0                     # Version for CLAUDE.md/commands/agents (skills always latest)
```

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

### Example Invocation of Progress Guardian

Source: https://github.com/citypaul/.dotfiles/blob/main/_autodocs/02-agents-reference.md

Illustrates how to initiate the progress-guardian agent for a new feature and how to update it upon completion of a step. The agent creates a plan file and guides the implementation process.

```shell
"I need to implement OAuth with JWT tokens and refresh logic"

Output:
- Creates plans/oauth.md with approved slices
- Each slice specifies failing test to write first
- Tracks completion through MUTATE phase

"Tests are passing now"
- Updates plan progress
- Asks for commit approval
- Guides next slice
```

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

### Install Only OpenCode Configuration

Source: https://github.com/citypaul/.dotfiles/blob/main/README.md

If Claude Code is already installed, use this command to install only the OpenCode configuration. This is useful if you only need to add OpenCode support to an existing setup.

```bash
# Install OpenCode config only (if you already have CLAUDE.md installed)
curl -fsSL https://raw.githubusercontent.com/citypaul/.dotfiles/main/install-claude.sh | bash -s -- --opencode-only
```

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

### Project Setup with /setup

Source: https://github.com/citypaul/.dotfiles/blob/main/README.md

Run /setup once per project to detect the tech stack, create configuration files, hooks, commands, and a PR reviewer. It analyzes project specifics like TypeScript config, CI pipelines, DDD patterns, and test runners to establish project-level context.

```bash
/setup  →  Detects tech stack, creates .claude/CLAUDE.md, hooks, commands, PR reviewer
```

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

### Publish and Install npm Package

Source: https://github.com/citypaul/.dotfiles/blob/main/VERSIONING-DISTRIBUTION-ANALYSIS.md

Commands for publishing an npm package and for users to install it using npx.

```bash
# Publish to npm
npm publish

# Users install
npx @paulhammond/claude-guidelines init
# → Downloads CLAUDE.md + agents to .claude/
```

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

### Install Dependencies and Create Changeset

Source: https://github.com/citypaul/.dotfiles/blob/main/CONTRIBUTING.md

Install project dependencies using pnpm and then create a changeset to document your changes. This is a crucial step for versioning.

```bash
# Install dependencies first (if not already done)
pnpm install

# Create a changeset
pnpm changeset
```

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

### Create Custom Instructions File

Source: https://github.com/citypaul/.dotfiles/blob/main/MIGRATION.md

Example of creating a new file for custom instructions and importing it into the project's CLAUDE.md.

```bash
# Create custom instructions file
cat > ~/.claude/my-custom-instructions.md << 'EOF'
# My Custom Development Rules

## My Team's Specific Patterns
- Use React Query for all data fetching
- Prefer Tailwind CSS for styling
- etc.
EOF
```

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

### Install Git Configuration

Source: https://github.com/citypaul/.dotfiles/blob/main/README.md

Installs the git configuration, including aliases, by navigating to the dotfiles directory and using stow.

```bash
# Install just the git config
cd ~/.dotfiles
stow git

# Or manually copy specific aliases you want
cat git/.gitconfig >> ~/.gitconfig
```

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

### Install Claude Script (Download and Run)

Source: https://github.com/citypaul/.dotfiles/blob/main/README.md

Installs the Claude development environment by downloading the script, making it executable, and then running it. This method offers more control over the execution.

```bash
curl -fsSL https://raw.githubusercontent.com/citypaul/.dotfiles/main/install-claude.sh -o install-claude.sh
chmod +x install-claude.sh
./install-claude.sh
```

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

### Manual OpenCode Configuration Setup

Source: https://github.com/citypaul/.dotfiles/blob/main/README.md

Manually set up the OpenCode configuration directory and the opencode.json file. This method allows for fine-grained control over the integration process.

```bash
mkdir -p ~/.config/opencode/command ~/.config/opencode/agent

# OpenCode configuration
cat > ~/.config/opencode/opencode.json << 'EOF'
{
  "$schema": "https://opencode.ai/config.json",
  "lsp": true,
  "instructions": [
    "~/.claude/CLAUDE.md",
    "~/.claude/skills/*/SKILL.md",
    "~/.claude/agents/*.md"
  ]
}
EOF
```

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

### Clone Project and Setup Local Hooks

Source: https://github.com/citypaul/.dotfiles/blob/main/_autodocs/00-index.md

For teams, this clones the shared project repository and then runs the setup command to generate local hooks and configurations. Ensures all team members have a consistent development environment.

```bash
# 1. Clone repo with .claude/ in git
git clone https://github.com/yourteam/project.git
cd project

# 2. Generate project config
/setup

# 3. Add to git (share with team)
git add .claude/ && git commit -m "chore: Add project CLAUDE.md"

# 4. Team members pull and start working
git pull
/setup  # Generates their local hooks
/plan [feature]
```

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

### Plan Document Example

Source: https://github.com/citypaul/.dotfiles/blob/main/_autodocs/06-workflow-integration.md

An example of a detailed implementation plan document for a 'Checkout Flow' feature, including overview, acceptance criteria, and slice breakdowns.

```markdown
# Checkout Flow Implementation Plan

## Overview
Users need to enter payment details and complete checkout

## Acceptance Criteria
- Accept payment amount (required)
- Validate card number (required)
- Validate expiration (required)
- Handle declined cards (error case)
- Show success confirmation (happy path)

## Slice 1: Accept Payment Amount
### Failing Test
"Should reject payments under $1"

### Acceptance Criteria
- Accept positive amounts
- Reject zero amount
- Reject negative amounts
- Reject amounts over $10,000

### Implementation Notes
- Validate in domain (pure function)
- Use Money value object
- Return PaymentResult with success/reason

### Dependencies
None (first slice)

---

## Slice 2: Validate Card
### Failing Test
"Should reject invalid card number"

### Acceptance Criteria
- Validate card format (16 digits)
- Reject invalid formats
- Use Luhn algorithm

### Implementation Notes
- Abstract card validation to domain service
- Implement via port (ICardValidator)
- Test through use case

### Dependencies
Must complete Slice 1 first
```

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

### Full Development Lifecycle Workflow

Source: https://github.com/citypaul/.dotfiles/blob/main/_autodocs/01-project-overview.md

Illustrates the sequence of commands and actions for the complete development lifecycle, from setup to knowledge capture and cleanup.

```bash
/setup                    → Detect tech stack, generate project config
  ↓
/plan                     → Create plan in plans/ on branch with PR
  ↓
RED                       → Write failing behavior test
  ↓
GREEN                     → Write minimum code to pass
  ↓
MUTATE                    → Run mutation testing (Stryker)
  ↓
KILL MUTANTS             → Address surviving mutants or justify
  ↓
REFACTOR                 → Assess improvement opportunities
  ↓
/pr                       → Create PR with quality gates
  ↓
/continue                 → Pull merged, create branch, update plan
  ↓
learn + adr + docs       → Capture knowledge
  ↓
DELETE plans/<file>.md   → Clean up after completion
```

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

### Install Claude CLI

Source: https://github.com/citypaul/.dotfiles/blob/main/_autodocs/README.md

Installs the Claude CLI globally using a curl script. Alternatively, you can copy the project locally or install only the skills.

```bash
# Global install (recommended)
curl -fsSL https://raw.githubusercontent.com/citypaul/.dotfiles/main/install-claude.sh | bash

# Or project-specific
cp -r ~/.claude .

# Or skills only
npx skills install @paulhammond/dotfiles
```

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

### Global Install Dotfiles

Source: https://github.com/citypaul/.dotfiles/blob/main/_autodocs/01-project-overview.md

Installs the dotfiles globally to ~/.claude/ for system-wide configuration. Recommended for individual users.

```bash
curl -fsSL https://raw.githubusercontent.com/citypaul/.dotfiles/main/install-claude.sh | bash
```

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

### One-Time Setup: Generate PR Review Automation

Source: https://github.com/citypaul/.dotfiles/blob/main/README.md

Run /generate-pr-review for optional, one-time setup to create project-specific PR review automation. Use this if /setup provides insufficient control or needs regeneration.

```bash
/generate-pr-review  →  Creates project-specific PR review automation
```

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

### Plan Progress Example

Source: https://github.com/citypaul/.dotfiles/blob/main/_autodocs/03-commands-reference.md

This markdown example illustrates how the project plan document is updated to show slice completion and the status of the next slice, including acceptance criteria and the first failing test to write.

```markdown
# Checkout Flow Implementation Plan

## Progress: Slice 1 of 5 Complete ✅

### Slice 1: Accept payment amount
- Status: ✅ COMPLETED (merged in #456)

### Slice 2: Validate card (NEXT)
- Status: 🔄 IN_PROGRESS
- Failing test to write first: "Should reject invalid card number"
- ...
```

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

### Command Output Example

Source: https://github.com/citypaul/.dotfiles/blob/main/_autodocs/03-commands-reference.md

This output indicates the successful creation of a plan document and branch, along with a PR for review. It also summarizes the content of the plan and outlines the subsequent steps for development.

```bash
✅ Created plans/checkout-flow.md
✅ Created branch plan/checkout-flow
✅ Created PR for plan review

Plan document contains:
- Overview of checkout feature
- 5 PR-sized slices with acceptance criteria
- Implementation notes for each slice
- Dependency graph between slices

Next steps:
1. Review plan in PR
2. Request changes if needed
3. Approve plan when ready
4. Create feature branch: git checkout -b feature/checkout-flow
5. Start implementing Slice 1
```

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

### Example Invocation for Use Case Data Patterns

Source: https://github.com/citypaul/.dotfiles/blob/main/_autodocs/02-agents-reference.md

This example demonstrates how to invoke the use-case-data-patterns agent and outlines the expected analytical report content.

```text
"How does the checkout flow work from user click to database?"

Output:
- Comprehensive analytical report
- Use case to data pattern mapping
- Database interactions traced
- Architectural decisions explained
- Missing pieces for feature implementation identified
```

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

### Install Claude Script with Options (One-liner)

Source: https://github.com/citypaul/.dotfiles/blob/main/README.md

Installs the Claude development environment with specific options passed via bash arguments. Use this to enable features like OpenCode support or install a specific version.

```bash
# Install with OpenCode support
curl -fsSL https://raw.githubusercontent.com/citypaul/.dotfiles/main/install-claude.sh | bash -s -- --with-opencode

# Install specific version
curl -fsSL https://raw.githubusercontent.com/citypaul/.dotfiles/main/install-claude.sh | bash -s -- --version v2.0.0
```

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

### Example Invocation for 12-Factor Audit

Source: https://github.com/citypaul/.dotfiles/blob/main/_autodocs/02-agents-reference.md

This example shows how to invoke the twelve-factor-audit agent and the expected output format.

```text
"Audit this service for 12-factor compliance"

Output:
- Factor summary table with compliance status
- Detailed findings with file paths and line numbers
- Code suggestions for each gap
- Prioritized action plan
- Full report saved to twelve-factor-audit.md
```

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

### Shell Script Installation Commands

Source: https://github.com/citypaul/.dotfiles/blob/main/VERSIONING-DISTRIBUTION-ANALYSIS.md

One-liner commands for installing the shell script, with options for specifying version and packages.

```bash
# One-liner installation
curl -fsSL https://install.claude.guide | bash

# Or with options
curl -fsSL https://install.claude.guide | bash -s -- --version=v2.0.0 --full
```

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

### Install Skills via NPM

Source: https://github.com/citypaul/.dotfiles/blob/main/_autodocs/01-project-overview.md

Installs agent skills using the npx command, leveraging the skills.sh ecosystem for agent support.

```bash
npx skills install
```

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

### Implementation Slice Example (TypeScript)

Source: https://github.com/citypaul/.dotfiles/blob/main/_autodocs/06-workflow-integration.md

A TypeScript example demonstrating the RED-GREEN-MUTATE-KILL-REFACTOR cycle for implementing a payment amount validation.

```typescript
// SLICE 1: Accept Payment Amount

// RED PHASE: Write failing test
it('should reject payment amounts under $1', () => {
  const result = processPayment({
    amount: 0.50,
    currency: 'USD',
  });
  expect(result.success).toBe(false);
  expect(result.error).toBe('amount-too-low');
});
// ❌ Test fails (amount validation not implemented)

// GREEN PHASE: Write minimum code
const processPayment = (payment: Payment): PaymentResult => {
  if (payment.amount < 1) {
    return { success: false, error: 'amount-too-low' };
  }
  return { success: true, paymentId: 'temp-123' };
};
// ✅ Test passes

// MUTATE PHASE: Run mutation testing
// Stryker report:
// - Mutant: < becomes <=
//   Test: ✅ Would catch (0.99 < 1 → 0.99 <= 1)
// - Mutant: amount removed
//   Test: ✅ Would catch (uses amount)
// Mutation score: 100%

// KILL MUTANTS PHASE: All mutants killed ✅

// REFACTOR PHASE: Should we refactor?
// - Function is 1 line (too short to refactor)
// - Variable names clear (amount, currency)
// - No duplication
// → No refactoring needed

// COMMIT
git add test/payment.test.ts src/payment.ts
git commit -m "feat: Validate minimum payment amount

- Reject payments under $1
- Return PaymentResult with error code
- 100% mutation score
"
```

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

### Manage Installed Skills with skills.sh CLI

Source: https://github.com/citypaul/.dotfiles/blob/main/README.md

Commands to list, update, find, and remove skills installed globally using the skills.sh CLI. Ensure Node.js is installed to use npx.

```bash
npx skills list -g              # List installed skills
npx skills update -g            # Update all skills to latest
npx skills find <query>         # Discover more skills on skills.sh
npx skills remove -g <name>     # Uninstall a skill
```

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

### Install Specific Dotfiles Individually

Source: https://github.com/citypaul/.dotfiles/blob/main/README.md

Installs specific dotfile configurations like git, bash, or vim individually by navigating to the dotfiles directory and using stow.

```bash
cd ~/.dotfiles

# Install just git config
stow git

# Install just bash config
stow bash

# Install vim config
stow vim

# Install multiple at once
stow git bash vim
```

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

### Install Shell Configuration

Source: https://github.com/citypaul/.dotfiles/blob/main/README.md

Installs shell configurations for bash or zsh by navigating to the dotfiles directory and using stow.

```bash
cd ~/.dotfiles
stow bash  # or stow zsh
```

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

### Initialize Changesets CLI

Source: https://github.com/citypaul/.dotfiles/blob/main/VERSIONING-DISTRIBUTION-ANALYSIS.md

Commands to install the Changesets CLI as a dev dependency and initialize its configuration.

```bash
npm install -D @changesets/cli
npx changeset init
```

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

### Sequential Agent Execution Example

Source: https://github.com/citypaul/.dotfiles/blob/main/_autodocs/02-agents-reference.md

Demonstrates a sequence of agents that must execute in a specific order. This is used for tasks where the output of one agent is a prerequisite for the next.

```text
tdd-guardian (RED-GREEN-MUTATE)
    ↓
ts-enforcer (before commit)
    ↓
refactor-scan (after MUTATE phase)
    ↓
pr-reviewer (before PR)
```

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

### Domain-Driven Design: Domain Modeling Example

Source: https://github.com/citypaul/.dotfiles/blob/main/_autodocs/04-skills-reference.md

Demonstrates building blocks for domain modeling in DDD. Includes examples of Value Objects, Entities, Aggregates, and Domain Services.

```typescript
// VALUE OBJECT: Immutable, compared by value
type Money = readonly { amount: number; currency: string };
const createMoney = (amount: number, currency: string): Money => ({
  amount,
  currency,
});

// ENTITY: Compared by ID
type Order = {
  readonly id: string;
  readonly customerId: string;
  readonly items: readonly OrderItem[];
  readonly total: Money;
  readonly status: 'pending' | 'confirmed' | 'shipped' | 'delivered';
};

// AGGREGATE: Order is aggregate root, OrderItems belong to Order
const createOrder = (
  customerId: string,
  items: OrderItem[],
): Order => {
  if (items.length === 0) throw new Error('Order must have items');
  return {
    id: generateId(),
    customerId,
    items,
    total: calculateTotal(items),
    status: 'pending',
  };
};

// DOMAIN SERVICE: No natural home in entity
const calculateTax = (order: Order, taxRate: number): Money => ({
  amount: order.total.amount * taxRate,
  currency: order.total.currency,
});

```

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

### Docs-Guardian Agent Invocation Example

Source: https://github.com/citypaul/.dotfiles/blob/main/_autodocs/02-agents-reference.md

Examples of how to invoke the docs-guardian agent for documentation tasks. The agent provides assessments, recommendations, and templates.

```shell
"I need to write a README for this feature."
"Can you review the documentation I just wrote?"
```

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

### Install Claude Code with OpenCode Support

Source: https://github.com/citypaul/.dotfiles/blob/main/README.md

Use this one-liner command to install Claude Code with OpenCode support. It automatically handles the necessary configurations.

```bash
# One-liner with OpenCode support
curl -fsSL https://raw.githubusercontent.com/citypaul/.dotfiles/main/install-claude.sh | bash -s -- --with-opencode
```

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

### Example pr-reviewer Invocation

Source: https://github.com/citypaul/.dotfiles/blob/main/_autodocs/02-agents-reference.md

Demonstrates how to invoke the pr-reviewer agent for a specific Pull Request and the expected output format.

```shell
"Review PR #123 and post feedback"
```

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

### Bash Script for Shell Installer

Source: https://github.com/citypaul/.dotfiles/blob/main/VERSIONING-DISTRIBUTION-ANALYSIS.md

This script provides a way to install the Claude guidelines from a GitHub release. It can fetch the latest version or a specific tagged version and download CLAUDE.md, documentation files, and agent files into a specified directory. It requires 'curl'.

```bash
#!/usr/bin/env bash
set -euo pipefail

# Configuration
REPO="citypaul/.dotfiles"
VERSION="${1:-latest}"
INSTALL_DIR="${CLAUDE_INSTALL_DIR:-.claude}"

# Colors
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color

# Functions
log_info() { echo -e "${GREEN}ℹ${NC} $1"; }
log_warn() { echo -e "${YELLOW}⚠${NC} $1"; }
log_error() { echo -e "${RED}✗${NC} $1"; }
log_success() { echo -e "${GREEN}✓${NC} $1"; }

# Check dependencies
command -v curl >/dev/null 2>&1 || { log_error "curl is required but not installed. Aborting."; exit 1; }

# Determine version
if [ "$VERSION" = "latest" ]; then
  log_info "Fetching latest release..."
  VERSION=$(curl -s "https://api.github.com/repos/$REPO/releases/latest" | grep '"tag_name":' | sed -E 's/.*"([^"]+)".*/\1/')
fi

log_info "Installing Claude guidelines $VERSION..."

# Create directory
mkdir -p "$INSTALL_DIR"
mkdir -p "$INSTALL_DIR/docs"
mkdir -p "$INSTALL_DIR/agents"

# Base URL for release
BASE_URL="https://github.com/$REPO/releases/download/$VERSION"

# Download CLAUDE.md
log_info "Downloading CLAUDE.md..."
curl -fsSL "$BASE_URL/CLAUDE.md" -o "$INSTALL_DIR/CLAUDE.md" || {
  log_error "Failed to download CLAUDE.md"
  exit 1
}

# Download docs
log_info "Downloading documentation files..."
for doc in testing typescript code-style workflow examples working-with-claude; do
  curl -fsSL "$BASE_URL/docs/${doc}.md" -o "$INSTALL_DIR/docs/${doc}.md" 2>/dev/null || {
    log_warn "Could not download docs/${doc}.md (may not exist in this version)"
  }
done

# Download agents
log_info "Downloading agents..."
for agent in tdd-guardian ts-enforcer refactor-scan learn; do
  curl -fsSL "$BASE_URL/agents/${agent}.md" -o "$INSTALL_DIR/agents/${agent}.md" || {
    log_warn "Could not download agents/${agent}.md"
  }
done

log_success "Claude guidelines $VERSION installed to $INSTALL_DIR/"
log_info "Files installed:"
log_info "  - CLAUDE.md"
log_info "  - docs/*.md (6 files)"
log_info "  - agents/*.md (4 files)"
```

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

### Monorepo Package JSON Example

Source: https://github.com/citypaul/.dotfiles/blob/main/VERSIONING-DISTRIBUTION-ANALYSIS.md

Example package.json files for different packages within a monorepo structure. Used for independent versioning and dependency management.

```json
// packages/claude-guidelines/package.json
{
  "name": "@paulhammond/claude-guidelines",
  "version": "2.0.0"
}
```

```json
// packages/claude-agents/package.json
{
  "name": "@paulhammond/claude-agents",
  "version": "1.5.0"
}
```

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

### Explicitly Load Skills

Source: https://github.com/citypaul/.dotfiles/blob/main/_autodocs/04-skills-reference.md

Use this command to load multiple skills before starting implementation. Ensure all skill names are comma-separated.

```text
Load tdd, testing, mutation-testing, and refactoring before I start implementing.
```

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

### Good vs. Bad Code Example Style

Source: https://github.com/citypaul/.dotfiles/blob/main/CONTRIBUTING.md

Illustrates the recommended style for code examples in documentation, showing both incorrect ('❌ BAD') and correct ('✅ GOOD') implementations.

```typescript
// ❌ BAD - Show what NOT to do
const badExample = () => { ... };

// ✅ GOOD - Show the correct way
const goodExample = () => { ... };
```

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

### Example Invocation and Output of Refactor Scan

Source: https://github.com/citypaul/.dotfiles/blob/main/_autodocs/02-agents-reference.md

Demonstrates how to invoke the refactor-scan agent and the expected output format, which includes priority classifications and specific refactoring recommendations.

```text
"My tests are passing. Should I refactor anything?"

Output:
- 🔴 Critical refactoring needed (must fix)
- ⚠️ High value opportunities (should fix)
- 💡 Nice to have improvements (consider)
- ✅ Correctly separated code (keep as-is)
- Specific refactoring recommendations with code examples
```

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

### Clone and Stow Dotfiles

Source: https://github.com/citypaul/.dotfiles/blob/main/VERSIONING-DISTRIBUTION-ANALYSIS.md

This method clones the repository and uses an install script to manage dotfiles. It is suitable for users who want to manage their configuration files.

```bash
git clone https://github.com/citypaul/.dotfiles.git ~/.dotfiles
cd ~/.dotfiles
./install.sh
```

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

### Parallel Agent Execution Example

Source: https://github.com/citypaul/.dotfiles/blob/main/_autodocs/02-agents-reference.md

Illustrates how multiple agents can run concurrently to form a quality gate. This pattern is useful when agent tasks are independent and can be processed simultaneously.

```text
tdd-guardian (verify test-first)  ───┐
ts-enforcer (verify types)         ├─→ Pre-commit quality gate
refactor-scan (assess improvements)──┘
```

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

### Example Changeset File

Source: https://github.com/citypaul/.dotfiles/blob/main/CONTRIBUTING.md

A generated changeset file details the type of version bump (major, minor, patch) and provides a summary of the changes made.

```markdown
---
"@paulhammond/dotfiles": minor
---

Add new refactoring assessment agent

Added refactor-scan agent that helps developers assess whether refactoring
would add value and provides guidance on semantic vs structural similarity.
```

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

### Output of /setup Command

Source: https://github.com/citypaul/.dotfiles/blob/main/_autodocs/03-commands-reference.md

This output confirms the successful generation of configuration files and lists the detected technology stack along with the project's build, test, lint, and typecheck commands.

```bash
✅ Generated .claude/CLAUDE.md
✅ Generated .claude/settings.json
✅ Generated .claude/commands/pr.md
✅ Generated .claude/agents/pr-reviewer.md

Tech stack detected:
  - TypeScript (strict mode)
  - Vitest (testing)
  - ESLint (linting)
  - Prettier (formatting)

Build command: npm run build
Test command: npm run test
Lint command: npm run lint
Typecheck command: npx tsc --noEmit
```

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

### Schema Decision Framework Example

Source: https://github.com/citypaul/.dotfiles/blob/main/README.md

Illustrates when to use a schema (e.g., for API responses with validation rules) versus a simple type alias (for pure internal types).

```typescript
// ✅ Schema REQUIRED - Trust boundary (API response)
const UserSchema = z.object({ id: z.string().uuid(), email: z.string().email() });
const user = UserSchema.parse(apiResponse);

// ❌ Schema OPTIONAL - Pure internal type
type Point = { readonly x: number; readonly y: number };
```

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

### Progress Guardian Agent Invocation

Source: https://github.com/citypaul/.dotfiles/blob/main/README.md

Illustrates how to interact with the progress-guardian agent for managing vertical slices of work. It shows example user prompts and the agent's expected actions.

```bash
You: "I need to implement OAuth with JWT tokens and refresh logic"
Claude Code: [Launches progress-guardian to create plans/oauth.md]

You: "Tests are passing now"
Claude Code: [Launches progress-guardian to update plan and ask for commit approval]
```

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

### Install Claude Code Skills Only

Source: https://github.com/citypaul/.dotfiles/blob/main/_autodocs/05-installation-configuration.md

Installs only the pattern skills for Claude Code using npx. This method is minimal and does not install agents or commands.

```bash
npx skills install @paulhammond/dotfiles
```