### Example Project Configuration

Source: https://github.com/christopherkahler/paul/blob/main/src/templates/config.md

A concrete example of a populated .paul/config.md file for the 'expense-tracker' project, with SonarQube integration enabled.

```markdown
# Project Config

**Project:** expense-tracker
**Created:** 2026-01-28

## Project Settings

```yaml
project:
  name: expense-tracker
  version: 0.2.0
```

## Integrations

### SonarQube

```yaml
sonarqube:
  enabled: true
  project_key: expense-tracker
  server_url: http://localhost:9000
```

### Enterprise Plan Audit

```yaml
enterprise_plan_audit:
  enabled: false
```

### Future Integrations

```yaml
# linting:
#   enabled: false
```

## Preferences

```yaml
preferences:
  auto_commit: false
  verbose_output: false
  parallel_agents: false
```

---

*Config created: 2026-01-28*

```

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

### Config Line Detail Example

Source: https://github.com/christopherkahler/paul/blob/main/src/workflows/init-project.md

Example of how to detail enabled integrations within the config.md line.

```text
.paul/config.md ✓ (SonarQube, Enterprise Plan Audit enabled)
```

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

### Teach by Contrast Example

Source: https://github.com/christopherkahler/paul/blob/main/src/rules/references.md

Demonstrates the 'teach by contrast' pattern, showing a vague example versus a specific, well-defined example to illustrate a concept clearly. This is useful for highlighting best practices.

```markdown
## Vague vs Specific

<!-- BAD -->
<task>
  <action>Set up authentication</action>
</task>

<!-- GOOD -->
<task>
  <action>
    Create POST /api/auth/login endpoint:
    - Accept { email, password }
    - Validate with bcrypt compare
    - Return JWT token (15min expiry)
  </action>
</task>
```

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

### Install PAUL Framework

Source: https://github.com/christopherkahler/paul/blob/main/README.md

Install the PAUL framework globally or locally using npm. This command installs the latest version.

```bash
npx paul-framework
```

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

### Example Workflow Structure

Source: https://github.com/christopherkahler/paul/blob/main/src/rules/workflows.md

A comprehensive example demonstrating the full structure of a workflow file, including purpose, when_to_use, required_reading, loop_context, and process with detailed steps.

```markdown
<purpose>
Execute an approved PLAN by running tasks in order, verifying each, and recording results.
</purpose>

<when_to_use>
- User has approved a PLAN.md
- STATE.md shows loop position at PLAN (ready for APPLY)
- No blocking checkpoints remain unresolved
</when_to_use>

<required_reading>
@.paul/STATE.md
@.paul/phases/{phase}/{plan}-PLAN.md
</required_reading>

<loop_context>
Expected phase: APPLY
Prior phase: PLAN (approval just received)
Next phase: UNIFY (after execution completes)
</loop_context>

<process>

<step name="validate_preconditions" priority="first">
  1. Read STATE.md, confirm loop position
  2. Read PLAN.md, confirm autonomous flag
  3. If autonomous=false and checkpoints exist, warn user
</step>

<step name="execute_tasks">
  For each <task> in PLAN.md <tasks> section:
  1. Log task start
  2. Execute <action> content
  3. Run <verify> command
  4. If verify passes, record in APPLY-LOG
  5. If verify fails, stop and report
</step>

<step name="finalize">
  1. Update STATE.md loop position to UNIFY
  2. Report completion status
</step>

</process>
```

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

### Example Command Structure: paul:plan

Source: https://github.com/christopherkahler/paul/blob/main/src/rules/commands.md

A complete example of a command rule file, demonstrating the structure including objective, execution context, context, process, and success criteria.

```markdown
---
name: paul:plan
description: Enter PLAN phase for current or new plan
argument-hint: "[phase-plan]"
allowed-tools: [Read, Write, Glob, AskUserQuestion]
---

<objective>
Create or continue a PLAN for the specified phase.

**When to use:** Starting new work or resuming incomplete plan.
</objective>

<execution_context>
@src/workflows/plan-phase.md
@src/templates/PLAN.md
@src/references/plan-format.md
</execution_context>

<context>
$ARGUMENTS

@.paul/PROJECT.md
@.paul/STATE.md
@.paul/ROADMAP.md
</context>

<process>
Follow workflow: @src/workflows/plan-phase.md
</process>

<success_criteria>
- [ ] PLAN.md created in correct phase directory
- [ ] All acceptance criteria defined
- [ ] STATE.md updated with loop position
</success_criteria>
```

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

### Example External Integrations Documentation

Source: https://github.com/christopherkahler/paul/blob/main/src/templates/codebase/integrations.md

A concrete example of how to fill out the external integrations markdown template. It details specific services like Stripe, SendGrid, and OpenAI, including their SDKs, authentication methods, and usage.

```markdown
# External Integrations

**Analysis Date:** 2025-01-20

## APIs & External Services

**Payment Processing:**
- Stripe - Subscription billing and one-time course payments
  - SDK/Client: stripe npm package v14.8
  - Auth: API key in STRIPE_SECRET_KEY env var
  - Endpoints used: checkout sessions, customer portal, webhooks

**Email/SMS:**
- SendGrid - Transactional emails (receipts, password resets)
  - SDK/Client: @sendgrid/mail v8.1
  - Auth: API key in SENDGRID_API_KEY env var
  - Templates: Managed in SendGrid dashboard (template IDs in code)

**External APIs:**
- OpenAI API - Course content generation
  - Integration method: REST API via openai npm package v4.x
  - Auth: Bearer token in OPENAI_API_KEY env var
  - Rate limits: 3500 requests/min (tier 3)

```

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

### Starting a New Project Workflow

Source: https://github.com/christopherkahler/paul/blob/main/src/commands/help.md

Demonstrates the sequence of commands to initiate and begin a new project using the PAUL framework.

```bash
/paul:init
/paul:plan
# Approve plan
/paul:apply
/paul:unify
```

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

### Example CLI Application Architecture

Source: https://github.com/christopherkahler/paul/blob/main/src/templates/codebase/architecture.md

An example of documenting a CLI application with a plugin system, detailing its characteristics, layers, data flow, and key abstractions.

```markdown
# Architecture

**Analysis Date:** 2025-01-20

## Pattern Overview

**Overall:** CLI Application with Plugin System

**Key Characteristics:**
- Single executable with subcommands
- Plugin-based extensibility
- File-based state (no database)
- Synchronous execution model

## Layers

**Command Layer:**
- Purpose: Parse user input and route to appropriate handler
- Contains: Command definitions, argument parsing, help text
- Location: `src/commands/*.ts`
- Depends on: Service layer for business logic
- Used by: CLI entry point (`src/index.ts`)

**Service Layer:**
- Purpose: Core business logic
- Contains: FileService, TemplateService, InstallService
- Location: `src/services/*.ts`
- Depends on: File system utilities, external tools
- Used by: Command handlers

**Utility Layer:**
- Purpose: Shared helpers and abstractions
- Contains: File I/O wrappers, path resolution, string formatting
- Location: `src/utils/*.ts`
- Depends on: Node.js built-ins only
- Used by: Service layer

## Data Flow

**CLI Command Execution:**

1. User runs: `gsd new-project`
2. Commander parses args and flags
3. Command handler invoked (`src/commands/new-project.ts`)
4. Handler calls service methods (`src/services/project.ts` → `create()`)
5. Service reads templates, processes files, writes output
6. Results logged to console
7. Process exits with status code

**State Management:**
- File-based: All state lives in `.paul/` directory
- No persistent in-memory state
- Each command execution is independent

## Key Abstractions

**Service:**
- Purpose: Encapsulate business logic for a domain
- Examples: `src/services/file.ts`, `src/services/template.ts`, `src/services/project.ts`
- Pattern: Singleton-like (imported as modules, not instantiated)

**Command:**
- Purpose: CLI command definition
- Examples: `src/commands/new-project.ts`, `src/commands/plan-phase.ts`
- Pattern: Commander.js command registration

**Template:**
- Purpose: Reusable document structures
- Examples: PROJECT.md, PLAN.md templates
- Pattern: Markdown files with substitution variables

```

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

### Getting Help with PAUL

Source: https://github.com/christopherkahler/paul/blob/main/src/commands/help.md

Provides guidance on how to get help within the PAUL framework, including checking progress, and reading project and state files.

```markdown
- Run `/paul:progress` to see where you are and what to do next
- Read `.paul/PROJECT.md` for project context
- Read `.paul/STATE.md` for current position
- Check `.paul/ROADMAP.md` for phase overview
```

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

### Example Milestone Context Content

Source: https://github.com/christopherkahler/paul/blob/main/src/templates/milestone-context.md

An example of a populated MILESTONE-CONTEXT.md file, demonstrating the expected content for features, scope, and other sections.

```markdown
# Milestone Context

**Generated:** 2026-01-29
**Status:** Ready for /paul:create-milestone

## Features to Build

- **Milestone lifecycle commands**: Create, complete, and discuss milestones
- **Roadmap modification commands**: Add and remove phases dynamically
- **Milestone templates**: Entry format, archive format, context handoff

## Scope

**Suggested name:** v0.3 Roadmap & Milestone Management
**Estimated phases:** 3
**Focus:** Complete milestone management tooling for PAUL framework


```

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

### Example Plan File Path

Source: https://github.com/christopherkahler/paul/blob/main/src/workflows/plan-phase.md

Illustrates the expected file path structure for a plan file within the project's phase directory.

```text
.paul/phases/04-workflows-layer/04-01-PLAN.md
```

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

### Example Technology Stack Documentation

Source: https://github.com/christopherkahler/paul/blob/main/src/templates/codebase/stack.md

This is a concrete example of a completed technology stack document for a CLI tool. It specifies TypeScript, Node.js, npm, and key dependencies like commander and chalk, detailing their versions and usage.

```markdown
# Technology Stack

**Analysis Date:** 2025-01-20

## Languages

**Primary:**
- TypeScript 5.3 - All application code

**Secondary:**
- JavaScript - Build scripts, config files

## Runtime

**Environment:**
- Node.js 20.x (LTS)
- No browser runtime (CLI tool only)

**Package Manager:**
- npm 10.x
- Lockfile: `package-lock.json` present

## Frameworks

**Core:**
- None (vanilla Node.js CLI)

**Testing:**
- Vitest 1.0 - Unit tests
- tsx - TypeScript execution without build step

**Build/Dev:**
- TypeScript 5.3 - Compilation to JavaScript
- esbuild - Used by Vitest for fast transforms

## Key Dependencies

**Critical:**
- commander 11.x - CLI argument parsing and command structure
- chalk 5.x - Terminal output styling
- fs-extra 11.x - Extended file system operations

**Infrastructure:**
- Node.js built-ins - fs, path, child_process for file operations

## Configuration

**Environment:**
- No environment variables required
- Configuration via CLI flags only

**Build:**
- `tsconfig.json` - TypeScript compiler options
- `vitest.config.ts` - Test runner configuration

## Platform Requirements

**Development:**
- macOS/Linux/Windows (any platform with Node.js)
- No external dependencies

**Production:**
- Distributed as npm package
- Installed globally via npm install -g
- Runs on user's Node.js installation

--- 

*Stack analysis: 2025-01-20*
*Update after major dependency changes*

```

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

### Standard Task Completion Example

Source: https://github.com/christopherkahler/paul/blob/main/src/references/git-strategy.md

Example of a 'feat' commit for a standard task, including staging relevant files and a descriptive commit message.

```bash
# Standard task
git add src/api/auth.ts src/types/user.ts
git commit -m "feat(08-02): create user registration endpoint

- POST /auth/register validates email and password
- Checks for duplicate users
- Returns JWT token on success
"
```

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

### Test File Organization Example

Source: https://github.com/christopherkahler/paul/blob/main/src/templates/codebase/testing.md

Illustrates a common pattern for organizing test files alongside their corresponding source files.

```tree
src/
  lib/
    utils.ts
    utils.test.ts
  services/
    user-service.ts
    user-service.test.ts
```

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

### Example: Client Website Project Skill Declaration

Source: https://github.com/christopherkahler/paul/blob/main/src/references/specialized-workflow-integration.md

A comprehensive example of SPECIAL-FLOWS declaration for a client website project, including project-level dependencies, phase overrides, and asset usage.

```markdown
# Specialized Flows

## Project-Level Dependencies

| Work Type | Skill/Command | Priority | When Required |
|-----------|---------------|----------|---------------|
| Persuasion copy | /revops-expert | required | Headlines, CTAs, offers |
| UI components | /frontend-design | required | All HTML generation |
| Pricing sections | /revops-expert:hormozi | optional | Offer stacking phases |

## Phase Overrides

| Phase | Additional Skills | Notes |
|-------|-------------------|-------|
| 3 (Pricing) | /revops-expert:hormozi | Value stacking for offers |

## Templates & Assets

| Asset Type | Location | When Used |
|------------|----------|-----------|
| Hero template | templates/hero-section.html | Homepage hero |
| Testimonial | templates/testimonial-card.html | Social proof sections |
```

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

### Example Codebase Structure Documentation

Source: https://github.com/christopherkahler/paul/blob/main/src/templates/codebase/structure.md

An example of a completed STRUCTURE.md file, illustrating the application of the template. It details directory layouts, purposes, key file locations, and provides a clear overview of the project's organization.

```markdown
# Codebase Structure

**Analysis Date:** 2025-01-20

## Directory Layout

```
paul-framework/
├── bin/                # Executable entry points
├── src/                # Source code
│   ├── commands/       # Slash command definitions
│   ├── references/     # Principle documents
│   ├── templates/      # File templates
│   └── workflows/      # Multi-step procedures
├── tests/              # Test files
├── package.json        # Project manifest
└── README.md           # User documentation
```

## Directory Purposes

**bin/**
- Purpose: CLI entry points
- Contains: install.js (installer script)
- Key files: install.js - handles npx installation
- Subdirectories: None

**src/commands/**
- Purpose: Slash command definitions for Claude Code
- Contains: *.md files (one per command)
- Key files: init.md, plan.md, apply.md, unify.md
- Subdirectories: None (flat structure)

**src/references/**
- Purpose: Core philosophy and guidance documents
- Contains: principles.md, context-management.md, loop-phases.md
- Key files: principles.md - system philosophy
- Subdirectories: None

**src/templates/**
- Purpose: Document templates for .paul/ files
- Contains: Template definitions with frontmatter
- Key files: project.md, roadmap.md, plan.md, summary.md
- Subdirectories: codebase/ (stack/architecture/structure templates)

**src/workflows/**
- Purpose: Reusable multi-step procedures
- Contains: Workflow definitions called by commands
- Key files: init-project.md, apply-phase.md, unify-phase.md
- Subdirectories: None

## Key File Locations

**Entry Points:**
- `bin/install.js` - Installation script (npx entry)

**Configuration:**
- `package.json` - Project metadata, dependencies, bin entry
- `.gitignore` - Excluded files

**Core Logic:**
- `bin/install.js` - All installation logic (file copying, path replacement)

**Testing:**
- `tests/` - Test files (if present)

**Documentation:**
- `README.md` - User-facing installation and usage guide
- `CLAUDE.md` - Instructions for Claude Code when working in this repo

```

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

### Task Specificity: Just Right Example

Source: https://github.com/christopherkahler/paul/blob/main/src/references/plan-format.md

A well-defined task example, providing sufficient detail in files, action, verify, and done fields for immediate implementation by Claude.

```xml
<task type="auto">
  <name>Create login endpoint with JWT</name>
  <files>src/app/api/auth/login/route.ts</files>
  <action>
    POST endpoint accepting {email, password}.
    Query User by email, compare password with bcrypt.
    On match, create JWT with jose (15-min expiry).
    Return 200. On mismatch, return 401.
  </action>
  <verify>curl -X POST returns 200 with Set-Cookie header</verify>
  <done>AC-1 satisfied: Valid credentials → 200 + cookie</done>
</task>
```

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

### Example: Newly Initialized Project

Source: https://github.com/christopherkahler/paul/blob/main/src/templates/paul-json.md

This JSON object represents a paul.json file for a project that has just been initialized. All fields are set to their default or initial values.

```json
{
  "name": "my-app",
  "version": "0.0.0",
  "milestone": {
    "name": "None",
    "version": "0.0.0",
    "status": "not_started"
  },
  "phase": {
    "number": 0,
    "name": "None",
    "status": "not_started"
  },
  "loop": {
    "plan": null,
    "position": "IDLE"
  },
  "timestamps": {
    "created_at": "2026-03-17T14:00:00-05:00",
    "updated_at": "2026-03-17T14:00:00-05:00"
  },
  "satellite": {
    "groom": true
  }
}
```

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

### Example Milestone Archive Content

Source: https://github.com/christopherkahler/paul/blob/main/src/templates/milestone-archive.md

A concrete example of a populated milestone archive file, illustrating how the template is filled with specific project details.

```markdown
# Milestone v0.2: Session Continuity

**Status:** ✅ SHIPPED 2026-01-28
**Phases:** 7-8.7
**Total Plans:** 5

## Overview

Pause/resume workflow with handoff files and enhanced STATE.md session tracking.

## Phases

### Phase 7: Session Handoff

**Goal:** Create pause/resume workflow for session breaks
**Depends on:** Phase 6
**Plans:** 1 completed

Plans:
- [x] 07-01: Handoff file generation and resume workflow

**Details:**
- HANDOFF-*.md template for context capture
- Resume command for context restoration
- Session continuity section in STATE.md

### Phase 8.5: Quality Extensions [INSERTED]

**Goal:** Code quality tooling integration
**Depends on:** Phase 8
**Reason:** Discovered need during Phase 8 review

Plans:
- [x] 08.5-01: SonarQube integration (optional)

### Phase 8.6: Codebase CLAUDE.md [INSERTED]

**Goal:** Project-level Claude Code configuration
**Depends on:** Phase 8.5
**Reason:** Improve agent context for PAUL projects

Plans:
- [x] 08.6-01: CLAUDE.md template for codebase guidance

```

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

### Example UAT Issues File

Source: https://github.com/christopherkahler/paul/blob/main/src/templates/UAT-ISSUES.md

A concrete example of a filled-out UAT Issues file, demonstrating how to document specific issues found during testing, including severity and reproduction steps.

```markdown
# UAT Issues: Phase 5 Plan 2

**Tested:** 2026-01-15
**Source:** .paul/phases/05-auth/05-02-SUMMARY.md
**Tester:** User via verify-work workflow

## Open Issues

### UAT-001: Login form doesn't show validation errors

**Discovered:** 2026-01-15
**Phase/Plan:** 05-02
**Severity:** Major
**Feature:** User login form
**Description:** When I enter an invalid email, nothing happens. No error message appears.
**Expected:** Red error message below email field saying "Invalid email format"
**Actual:** Field border turns red but no text explanation
**Repro:**
1. Go to /login
2. Enter "notanemail" in email field
3. Click Login button

### UAT-002: Password field allows paste

**Discovered:** 2026-01-15
**Phase/Plan:** 05-02
**Severity:** Cosmetic
**Feature:** User login form
**Description:** Can paste into password field. Minor UX inconsistency.
**Expected:** Paste disabled (matches signup form)
**Actual:** Paste works in login but not signup
**Repro:** Ctrl+V in password field

## Resolved Issues

[None yet]

---

*Phase: 05-auth*
*Plan: 02*
*Tested: 2026-01-15*

```

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

### Example MILESTONES.md Content

Source: https://github.com/christopherkahler/paul/blob/main/src/templates/MILESTONES.md

This is a concrete example of a MILESTONES.md file, demonstrating how to fill out the template for two distinct milestones: 'Session Continuity' and 'Core Loop'. It shows specific details for delivered features, phases, accomplishments, stats, and git ranges.

```markdown
# Project Milestones: PAUL Framework

## v0.2 Session Continuity (Shipped: 2026-01-28)

**Delivered:** Pause/resume workflow with handoff files and enhanced STATE.md session tracking

**Phases completed:** 7-8.7 (5 plans total)

**Key accomplishments:**
- Handoff file generation for session breaks
- STATE.md Session Continuity section
- SonarQube integration (optional)
- Codebase CLAUDE.md improvements

**Stats:**
| Metric | Value |
|--------|-------|
| Files modified | 12 |
| Lines of code | 850 |
| Phases | 4 (7, 8.5, 8.6, 8.7) |
| Plans completed | 5 |
| Duration | 2 days |

**Git range:** `feat(07-01)` → `feat(08.7-01)`

**What's next:** v0.3 Roadmap & Milestone Management — milestone lifecycle commands

---


## v0.1 Core Loop (Shipped: 2026-01-27)

**Delivered:** PAUL framework foundation with Plan-Apply-Unify loop

**Phases completed:** 1-6 (4 plans total)

**Key accomplishments:**
- PLAN.md, STATE.md, PROJECT.md, SUMMARY.md templates
- ROADMAP.md with phase structure
- CARL PAUL domain with 11 rules

**Stats:**
| Metric | Value |
|--------|-------|
| Files modified | 18 |
| Lines of code | 1,200 |
| Phases | 6 |
| Plans completed | 4 |
| Duration | 1 day |

**Git range:** `feat(01-01)` → `feat(06-01)`

**What's next:** v0.2 Session Continuity — pause/resume workflow

```

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

### Example Task Structure

Source: https://github.com/christopherkahler/paul/blob/main/README.md

Illustrates the expected structure for tasks within the PAUL project, including files, action, verification, and completion status.

```xml
<task type="auto">
  <name>Create login endpoint</name>
  <files>src/api/auth/login.ts</files>
  <action>Implementation details...</action>
  <verify>curl command returns 200</verify>
  <done>AC-1 satisfied</done>
</task>
```

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

### Run SonarQube Server with Docker

Source: https://github.com/christopherkahler/paul/blob/main/src/references/sonarqube-integration.md

Recommended for local development. Starts a SonarQube community edition instance accessible on port 9000.

```bash
docker run -d --name sonarqube -p 9000:9000 sonarqube:community
```

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

### STATE.md Session Continuity Example

Source: https://github.com/christopherkahler/paul/blob/main/src/references/context-management.md

Shows the structure and content of the 'Session Continuity' section within STATE.md for quick session resumes.

```markdown
## Session Continuity

Last session: 2026-01-28 11:15
Stopped at: Phase 3, Plan 01, Task 2 complete
Next action: Create context-management.md reference
Resume file: .paul/phases/03-references-layer/03-01-PLAN.md
Resume context:
- Task 1 complete (checkpoints.md, plan-format.md created)
- Task 2 in progress
- 55% context remaining
```

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

### Loop Context Example

Source: https://github.com/christopherkahler/paul/blob/main/src/rules/workflows.md

Illustrates how to define the loop context within a workflow to track the current, prior, and next phases of the PAUL loop.

```xml
<loop_context>
Expected phase: PLAN
Prior phase: UNIFY (previous plan) or none (first plan)
Next phase: APPLY (after plan approval)
</loop_context>
```

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

### Example of a Comprehensive Plan (Anti-Pattern)

Source: https://github.com/christopherkahler/paul/blob/main/src/references/work-units.md

Illustrates a common anti-pattern where a single plan encompasses too much work, leading to quality degradation. This should be avoided.

```text
Plan: "Complete Authentication System"
Tasks: 8
Result: Task 1-3 good, Task 4-5 degrading, Task 6-8 rushed
```

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

### Task Specificity: Too Vague Example

Source: https://github.com/christopherkahler/paul/blob/main/src/references/plan-format.md

An example of a task that is too vague, lacking specific details for Claude to implement effectively.

```xml
<task type="auto">
  <name>Add authentication</name>
  <files>???</files>
  <action>Implement auth</action>
  <verify>???</verify>
  <done>Users can authenticate</done>
</task>
```

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

### Boundaries Section Example

Source: https://github.com/christopherkahler/paul/blob/main/src/references/plan-format.md

An example of the 'boundaries' section in PLAN.md, explicitly defining areas that should not be changed and scope limitations.

```markdown
<boundaries>
## DO NOT CHANGE
- database/migrations/* (schema locked for this phase)
- src/lib/auth.ts (auth system stable)

## SCOPE LIMITS
- This plan creates API only - no UI
- Do not add new dependencies
</boundaries>
```

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

### Example YAML Frontmatter in Template Content

Source: https://github.com/christopherkahler/paul/blob/main/src/rules/templates.md

This YAML frontmatter is an example of content to be generated by the template, not for the template file itself.

```yaml
---
phase: XX-name
plan: NN
type: execute
wave: 1
depends_on: []
files_modified: []
autonomous: true
---
```

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

### Non-interactive Install PAUL

Source: https://github.com/christopherkahler/paul/blob/main/README.md

Install the PAUL framework non-interactively, either globally to your user directory or locally to the current project.

```bash
npx paul-framework --global   # Install to ~/.claude/
npx paul-framework --local    # Install to ./.claude/
```

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

### PLAN.md Structure Example

Source: https://github.com/christopherkahler/paul/blob/main/src/commands/help.md

Illustrates the expected structure of a PLAN.md file, including metadata, objectives, context, skills, acceptance criteria, tasks, boundaries, and verification steps.

```markdown
---
phase: 01-foundation
plan: 01
type: execute
autonomous: true
---

<objective>
Goal, Purpose, Output
</objective>

<context>
@-references to relevant files
</context>

<skills>
Required skills from SPECIAL-FLOWS.md
</skills>

<acceptance_criteria>
Given/When/Then format
</acceptance_criteria>

<tasks>
<task type="auto">...</task>
</tasks>

<boundaries>
DO NOT CHANGE, SCOPE LIMITS
</boundaries>

<verification>
Completion checks
</verification>

```

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

### Shared Fixture Example

Source: https://github.com/christopherkahler/paul/blob/main/src/templates/codebase/testing.md

Example of a shared fixture file located in tests/fixtures/. This fixture contains markdown content with frontmatter.

```typescript
// Shared fixtures in tests/fixtures/
// tests/fixtures/sample-command.md
export const sampleCommand = `---
description: Test command
---
Content here`;
```

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

### Targeted vs. Kitchen Sink Context Loading

Source: https://github.com/christopherkahler/paul/blob/main/src/references/context-management.md

Demonstrates the difference between loading only necessary files and loading an excessive amount of files into the context.

```markdown
<!-- GOOD: Targeted loading -->
<context>
@.paul/STATE.md
@src/models/user.ts  (the specific file being modified)
</context>

<!-- BAD: Kitchen sink -->
<context>
@.paul/PROJECT.md
@.paul/ROADMAP.md
@.paul/STATE.md
@.paul/phases/01-foundation/01-01-SUMMARY.md
@.paul/phases/01-foundation/01-02-SUMMARY.md
@src/models/user.ts
@src/models/product.ts
@src/api/routes.ts
</context>
```

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

### Example Coding Conventions

Source: https://github.com/christopherkahler/paul/blob/main/src/templates/codebase/conventions.md

This is an example of a filled-out coding conventions document. It specifies naming patterns, code style, and linting rules.

```markdown
# Coding Conventions

**Analysis Date:** 2025-01-20

## Naming Patterns

**Files:**
- kebab-case for all files (command-handler.ts, user-service.ts)
- *.test.ts alongside source files
- index.ts for barrel exports

**Functions:**
- camelCase for all functions
- No special prefix for async functions
- handleEventName for event handlers (handleClick, handleSubmit)

**Variables:**
- camelCase for variables
- UPPER_SNAKE_CASE for constants (MAX_RETRIES, API_BASE_URL)
- No underscore prefix (no private marker in TS)

**Types:**
- PascalCase for interfaces, no I prefix (User, not IUser)
- PascalCase for type aliases (UserConfig, ResponseData)
- PascalCase for enum names, UPPER_CASE for values (Status.PENDING)

## Code Style

**Formatting:**
- Prettier with .prettierrc
- 100 character line length
- Single quotes for strings
- Semicolons required
- 2 space indentation

**Linting:**
- ESLint with eslint.config.js
- Extends @typescript-eslint/recommended
- No console.log in production code (use logger)
- Run: npm run lint

```

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

### One-liner Requirements Examples

Source: https://github.com/christopherkahler/paul/blob/main/src/templates/SUMMARY.md

Provides examples of good and bad one-liners for summarizing phase outcomes, emphasizing the need for substantive detail.

```markdown
| Good |
|------|-----|
| "JWT auth with refresh rotation using jose library" |
| "Prisma schema with User, Session, Product models" |
| "Dashboard with real-time metrics via SSE" |

| Bad |
|------|
| "Phase complete" |
| "Authentication implemented" |
| "All tasks done" |
```

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

### Example of Atomic Plans (Good Practice)

Source: https://github.com/christopherkahler/paul/blob/main/src/references/work-units.md

Demonstrates the recommended approach of breaking down work into small, atomic plans. Each plan focuses on a specific aspect and maintains high quality.

```text
Plan 1: "Auth Database Models" (2 tasks)
Plan 2: "Auth API Core" (2 tasks)
Plan 3: "Auth UI Components" (2 tasks)
Each: 30-40% context, peak quality
```

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

### Initialize PAUL

Source: https://github.com/christopherkahler/paul/blob/main/src/commands/help.md

Initializes PAUL in a project, creating necessary directories and files, and prompting for initial project context and phases. Optionally configures integrations.

```bash
/paul:init
```

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

### Milestone Archive Filename Convention Examples

Source: https://github.com/christopherkahler/paul/blob/main/src/templates/milestone-archive.md

Examples demonstrating the required filename convention for milestone archives, including version and kebab-case naming.

```text
v0.1-core-loop.md
v0.2-session-continuity.md
v1.0-mvp.md
v2.0-redesign.md
```

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

### Create .paul/PROJECT.md

Source: https://github.com/christopherkahler/paul/blob/main/src/workflows/init-project.md

This snippet shows the command to create the `.paul/PROJECT.md` file. This file is populated from walkthrough data, leading to more accurate project plans.

```shell
touch .paul/PROJECT.md
```

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

### Create .paul/codebase/ directory

Source: https://github.com/christopherkahler/paul/blob/main/src/workflows/map-codebase.md

Creates the .paul/codebase/ directory if it does not already exist. This directory will store the generated documentation files.

```bash
mkdir -p .paul/codebase
```

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

### Task Anatomy: Done Field Example

Source: https://github.com/christopherkahler/paul/blob/main/src/references/plan-format.md

Provides examples of the 'done' field, linking task completion to specific acceptance criteria (AC) for traceability.

```xml
<!-- GOOD -->
<done>AC-1 satisfied: Valid credentials return 200 + JWT cookie</done>

<!-- BAD -->
<done>Authentication is complete</done>
```

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

### Example: Technical Project Skill Declaration

Source: https://github.com/christopherkahler/paul/blob/main/src/references/specialized-workflow-integration.md

An example of SPECIAL-FLOWS declaration for a technical project, focusing on skills related to API documentation and database changes.

```markdown
# Specialized Flows

## Project-Level Dependencies

| Work Type | Skill/Command | Priority | When Required |
|-----------|---------------|----------|---------------|
| API documentation | /docs-generator | optional | After API changes |
| Database changes | /migration-helper | required | Schema modifications |
```

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

### TDD Task Completion Example (RED Phase)

Source: https://github.com/christopherkahler/paul/blob/main/src/references/git-strategy.md

Example of a 'test' commit for the RED phase of TDD, focusing on adding a failing test case.

```bash
# TDD task - RED phase
git add src/__tests__/jwt.test.ts
git commit -m "test(07-02): add failing test for JWT generation

- Tests token contains user ID claim
- Tests token expires in 1 hour
- Tests signature verification
"
```

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

### Show Help Reference

Source: https://github.com/christopherkahler/paul/blob/main/src/commands/help.md

Displays the complete PAUL command reference, providing usage details for all available commands.

```bash
/paul:help
```

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

### Create HANDOFF, update STATE, prepare for break

Source: https://github.com/christopherkahler/paul/blob/main/src/references/context-management.md

Use the `/paul:pause` command to create a HANDOFF and update the current STATE, preparing the system for a break.

```markdown
/paul:pause
```

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

### Human Verification Checkpoint Example

Source: https://github.com/christopherkahler/paul/blob/main/src/references/checkpoints.md

An example of a 'checkpoint:human-verify' task for confirming a responsive dashboard. It details the automated work and the specific steps for human verification.

```xml
<task type="checkpoint:human-verify" gate="blocking">
  <what-built>Responsive dashboard with sidebar navigation</what-built>
  <how-to-verify>
    1. Run: npm run dev
    2. Visit: http://localhost:3000/dashboard
    3. Desktop (>1024px): Sidebar visible on left
    4. Mobile (375px): Sidebar collapses to hamburger menu
    5. Check: No layout shift, smooth transitions
  </how-to-verify>
  <resume-signal>Type "approved" or describe issues</resume-signal>
</task>
```

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

### Decision Checkpoint Example

Source: https://github.com/christopherkahler/paul/blob/main/src/references/checkpoints.md

An example of a 'checkpoint:decision' task for selecting a state management approach for a dashboard. It presents two options with their pros and cons for human evaluation.

```xml
<task type="checkpoint:decision" gate="blocking">
  <decision>Select state management approach</decision>
  <context>Dashboard needs client-side state. Two viable approaches:</context>
  <options>
    <option id="zustand">
      <name>Zustand</name>
      <pros>Lightweight, simple API, no boilerplate</pros>
      <cons>Less structure for large apps</cons>
    </option>
    <option id="context">
      <name>React Context + useReducer</name>
      <pros>No dependencies, built-in</pros>
      <cons>More boilerplate, potential re-render issues</cons>
    </option>
  </options>
  <resume-signal>Select: zustand or context</resume-signal>
</task>
```

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

### Create PAUL Directory Structure

Source: https://github.com/christopherkahler/paul/blob/main/src/workflows/init-project.md

Initializes the necessary directory structure for PAUL, including the .paul/ directory and its phases/ subdirectory.

```bash
mkdir -p .paul/phases
```

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

### Offer Next Steps

Source: https://github.com/christopherkahler/paul/blob/main/src/workflows/phase-assumptions.md

Presents the user with options for proceeding after assumptions have been discussed and validated.

```markdown
What's next?
1. Plan this phase - Create detailed execution plans with corrected assumptions
2. Re-examine assumptions - I'll analyze again with your corrections
3. Done for now
```

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

### PLAN.md Frontmatter Example

Source: https://github.com/christopherkahler/paul/blob/main/src/references/plan-format.md

Standard YAML frontmatter for a PLAN.md file, defining phase, plan number, type, wave, dependencies, modified files, and autonomy.

```yaml
---
phase: XX-name
plan: NN
type: execute
wave: N
depends_on: []
files_modified: []
autonomous: true
---
```

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

### Project Initialization Git Add Command

Source: https://github.com/christopherkahler/paul/blob/main/src/references/git-strategy.md

Command to stage all files within the .paul/ directory before committing project initialization.

```bash
git add .paul/
git commit
```

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

### Presenting Phase Context to User

Source: https://github.com/christopherkahler/paul/blob/main/src/workflows/discuss-phase.md

This snippet shows the formatted output used to present the current phase's context, including its number, name, status, description, and prior phase details if applicable.

```bash
════════════════════════════════════════
PHASE DISCUSSION
════════════════════════════════════════

Phase: {phase_number} — {phase_name}
Status: {from ROADMAP.md}

Roadmap description:
{phase description from ROADMAP.md}

{If prior phase completed:}
Prior phase: {prior_phase_name}
What was built: {summary}

────────────────────────────────────────
```

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

### Error Handling Test (Async)

Source: https://github.com/christopherkahler/paul/blob/main/src/templates/codebase/testing.md

Example of testing asynchronous functions that are expected to reject. Uses expect.rejects.toThrow.

```typescript
// Async error
it('should reject on file not found', async () => {
  await expect(readConfig('invalid.txt')).rejects.toThrow('ENOENT');
});
```

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

### Get SonarQube Project Issues

Source: https://github.com/christopherkahler/paul/blob/main/src/references/sonarqube-integration.md

Retrieves specific issues from a SonarQube project, with an optional filter for severity.

```shell
mcp__sonarqube__sonar_get_issues
  project: "my-project"
  severity: "CRITICAL"  # Optional filter
```

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

### Renumber Subsequent Phase Directories

Source: https://github.com/christopherkahler/paul/blob/main/src/workflows/roadmap-management.md

Example of renaming phase directories to maintain sequential numbering after a phase is removed.

```bash
mv .paul/phases/08-name .paul/phases/07-name
mv .paul/phases/09-name .paul/phases/08-name
```

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

### Pre-Planning Exploration Commands

Source: https://github.com/christopherkahler/paul/blob/main/src/commands/help.md

Commands used for initial project exploration, including articulating vision, understanding assumptions, and gathering external research before planning.

```bash
/paul:discuss 3       # Articulate vision
/paul:assumptions 3   # See Claude's assumptions
/paul:research "topic"  # Gather external info
/paul:plan 3          # Now create the plan
```

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

### Project Initialization Commit Format

Source: https://github.com/christopherkahler/paul/blob/main/src/references/git-strategy.md

Use this format for the initial commit when setting up a new project. It includes the project name and a list of phases with their goals.

```git commit
docs: initialize [project-name] ([N] phases)

[One-liner from PROJECT.md]

Phases:
1. [phase-name]: [goal]
2. [phase-name]: [goal]
3. [phase-name]: [goal]
```

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

### Error Handling Test (Sync)

Source: https://github.com/christopherkahler/paul/blob/main/src/templates/codebase/testing.md

Example of testing synchronous functions that are expected to throw an error. Uses expect.toThrow.

```typescript
it('should throw on invalid input', () => {
  expect(() => parse(null)).toThrow('Cannot parse null');
});
```

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

### Create a Plan

Source: https://github.com/christopherkahler/paul/blob/main/src/commands/help.md

Enters the PLAN phase to create an executable plan. Reads current state, generates PLAN.md with tasks and acceptance criteria, and updates the loop position. Can auto-detect the next phase or accept a specific phase number.

```bash
/paul:plan
```

```bash
/paul:plan 3
```

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

### Task Anatomy: Verify Field Example

Source: https://github.com/christopherkahler/paul/blob/main/src/references/plan-format.md

Shows how to define clear verification steps for a task, specifying how to prove completion.

```xml
<!-- GOOD -->
<verify>curl -X POST localhost:3000/api/auth/login returns 200 with Set-Cookie header</verify>

<!-- BAD -->
<verify>It works</verify>
```

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

### Create Project Configuration with SonarQube

Source: https://github.com/christopherkahler/paul/blob/main/src/workflows/init-project.md

Generates the .paul/config.md file when SonarQube is enabled, including project settings, SonarQube integration details, and user preferences.

```markdown
# Project Config

**Project:** [project_name]
**Created:** [timestamp]

## Project Settings

```yaml
project:
  name: [project_name]
  version: 0.0.0
```

## Integrations

### SonarQube

```yaml
sonarqube:
  enabled: true
  project_key: [project_key]
```

## Preferences

```yaml
preferences:
  auto_commit: false
  verbose_output: false
```

---
*Config created: [timestamp]*
```