AI-Native Product Engineering Playbook

The complete system — every agent definition, every skill template, the task management system, git strategies, quality gate configuration, and workflow guides.

A systematic approach to building software products in partnership with AI agents.

Philosophy
Core Concepts
The Artifact System
Agents
Skills
- Workflow Skills
- Domain Skills
Task Management
The Implementation Layer
Day-to-Day Workflow
Compound Engineering
Quick Reference
Troubleshooting

Philosophy

Traditional product development artifacts—PRDs, TDDs, sprint plans—were designed for human-to-human collaboration. They optimize for stakeholder alignment, meeting-based communication, and handoffs between specialized roles.

AI-native development requires different artifacts. Agents don't need persuasive narratives or organizational context. They need focused, purpose-driven documentation with clear boundaries. They need to know exactly what to read, when to read it, and what to do with the information.

This playbook is built on five principles:

Separation of Concerns: Each document answers exactly one question (WHAT, WHY, or HOW). No document tries to do everything.
Context Hygiene: Agents perform best with minimal, relevant context. We load only what's needed for the current task, and we keep documents short enough to fit comfortably in context windows.
Compound Engineering: Every debugging session, every failed approach, every discovered pattern gets captured. Agents working in the codebase tomorrow should be smarter than agents working today.
Enforced Quality: Manual checklists get skipped. Automated pipelines don't. The /implement pipeline ensures every feature goes through build, test, review, and verification—enforced by tooling and quality gates, not willpower.
Progressive Complexity: Quality investment should be proportional to risk. A throwaway prototype doesn't need the same rigor as a payment flow. Scaffolding and configuration get lighter review; data mutations and auth logic get heavier scrutiny. The pipeline supports this—test steps can be conditionally skipped, specialist reviewers are opt-in, and discrete workflow commands let you apply exactly the level of process a task warrants.

Core Concepts

Agents vs Skills

This is the key conceptual distinction in the playbook:

Agents are personas that do work. They run in isolated context windows, can't see your conversation history, and return deliverables (code, review docs, test files). Think of them as specialized contractors.
Skills are reference manuals and orchestration playbooks. They inject knowledge or instructions into your current context. They don't spawn separate processes—they expand into your conversation as structured prompts.

	Agents	Skills
Context	Isolated (own context window)	Shared (expands into current context)
Purpose	Do work, produce deliverables	Provide knowledge, orchestrate sequences
Invocation	"Use the builder subagent to..."	`/implement`, `/review`, `/compound`
Output	Files, commits, review docs	Instructions, templates, domain knowledge
Persistence	Results persist (files on disk)	Knowledge persists (patterns in skills)

When to use agents: Task requires independent perspective (reviews), produces large output that would clutter context (test suites), or benefits from fresh context (catching bugs the author is blind to).

When to use skills: Task needs orchestration (multi-step pipeline), requires domain knowledge (API patterns, testing conventions), or needs to augment your current session rather than replace it.

Progressive Disclosure

Context efficiency is central to v5. Here's how it works:

Skills load descriptions at startup (~100 tokens each). Claude sees a menu of available capabilities without loading full content.
Full skill content loads on invocation. Running /implement expands the full orchestration prompt. Running /review security loads the security review protocol.
Domain knowledge appears when relevant. The frontend-design skill only enters context when you're working on UI. The database-patterns skill only loads for data layer work.

This means a project with 10 skills doesn't pay a 10x context cost. It pays ~1000 tokens at startup, then loads what's needed.

The Artifact System

Overview

Document	Purpose	Question Answered	When Created	Lives In
PRODUCT.md	Feature spec, personas, scope	WHAT are we building?	After ideation	`docs/`
BUILD-STRATEGY.md	Tech stack, architecture, decisions	WHY this approach?	Before implementation	`docs/`
CONVENTIONS.md	Global patterns, standards, file structure	HOW do we implement? (global)	Emerges during build	repo root
CLAUDE.md	Agent instructions, protocols	HOW should agents work?	Project init	repo root
README.md	Overview, setup, quick context	What is this + how to run?	Project init	repo root
DECISIONS.md	Decision log, pivots, rationale	WHY did we change course?	As needed	`docs/`
DESIGN.md	Brand, theme, component patterns	HOW should it look/feel?	If frontend-heavy	`docs/` or `docs/design/`
Domain Skills	Domain-specific patterns and conventions	HOW do we implement? (domain)	As domains emerge	`.claude/skills/`

PRODUCT.md

Purpose: Define WHAT we're building. Nothing else.

What belongs here:

Product vision and problem statement
User personas
Feature specifications (MVP vs. post-MVP)
User flows and core interactions
Success criteria

What does NOT belong here:

Go-to-market strategy
Monetization models
Technical implementation details
Timelines or roadmaps

Structure:

# [Product Name]

## Vision
[2-3 sentences: What is this product and why does it matter?]

## Problem Statement
[What pain point does this solve? For whom?]

## Personas
### [Persona 1 Name]
- Background: ...
- Goals: ...
- Pain points: ...

## Features

### MVP Scope
#### [Feature 1]
- Description: ...
- User story: As a [persona], I want to [action] so that [outcome]
- Acceptance criteria:
  - [ ] ...

### Post-MVP
#### [Feature N]
- Description: ...
- Priority: [High/Medium/Low]
- Dependencies: ...

## User Flows
[Describe or diagram key user journeys]

## Success Metrics
[How do we know this product is working?]

Creation Prompt:

I'm going to describe a product idea. Your job is to help me develop it into a complete product specification.

First, I'll share my initial vision. Then, I want you to:
1. Ask probing questions to uncover gaps, edge cases, and assumptions I haven't considered
2. Challenge me on scope—what's truly MVP vs. nice-to-have
3. Help me think through user personas and their specific needs
4. Identify potential user flows I might have missed

After our discussion, you'll draft a PRODUCT.md following this structure:
- Vision (2-3 sentences)
- Problem Statement
- Personas (with backgrounds, goals, pain points)
- Features (split into MVP and Post-MVP, each with descriptions, user stories, and acceptance criteria)
- User Flows
- Success Metrics

Important constraints:
- This document describes WHAT we're building only
- No technical implementation details
- No go-to-market or monetization strategy
- No timelines or roadmaps
- Keep it focused enough to fit comfortably in an LLM context window

Here's my initial vision:

[YOUR BRAIN DUMP HERE]

BUILD-STRATEGY.md

Purpose: Document WHY we're taking this technical approach. Strategic decisions, not implementation details.

What belongs here:

Tech stack selections with rationale
Architecture overview and patterns
Data architecture / schema design
Key trade-offs and their reasoning
Integration decisions
Testing philosophy
Performance and scaling considerations

What does NOT belong here:

Code-level implementation details
Step-by-step setup instructions
Specific file paths or function names

Structure:

# Build Strategy

## Tech Stack

### Frontend
- **Framework**: [Choice] — [1-2 sentence rationale]
- **Styling**: [Choice] — [rationale]
- **State Management**: [Choice] — [rationale]

### Backend
- **Runtime**: [Choice] — [rationale]
- **Framework**: [Choice] — [rationale]
- **Database**: [Choice] — [rationale]

### Infrastructure
- **Hosting**: [Choice] — [rationale]
- **CI/CD**: [Choice] — [rationale]

## Architecture Overview
[High-level description of system architecture. Include a simple diagram if helpful.]

## Data Architecture
[Schema overview, key models, relationships. For complex apps, reference separate SCHEMA.md]

### Core Models
- **[Model 1]**: [Purpose, key fields, relationships]
- **[Model 2]**: ...

## Key Decisions

### [Decision 1 Title]
- **Context**: [What problem were we solving?]
- **Decision**: [What did we choose?]
- **Rationale**: [Why?]
- **Trade-offs**: [What did we give up?]

## Testing Philosophy
[Unit vs integration vs E2E balance. What gets tested, what doesn't, and why.]

## Performance Considerations
[Known bottlenecks, scaling approach, optimization priorities]

Creation Prompt:

I need you to help me create a build strategy for a product.

First, read and internalize the product specification:
[PASTE PRODUCT.md CONTENTS OR REFERENCE FILE]

Now, I want you to:
1. Use Context7 to look up current documentation for frameworks and tools relevant to this application type
2. Recommend a tech stack with clear rationale for each choice
3. Propose a high-level architecture
4. Identify key technical decisions we'll need to make and recommend approaches
5. Consider trade-offs explicitly—what are we optimizing for, and what are we sacrificing?

After research and discussion, draft a BUILD-STRATEGY.md with:
- Tech Stack (with rationale for each choice)
- Architecture Overview
- Data Architecture (core models and relationships)
- Key Decisions (with context, decision, rationale, trade-offs)
- Testing Philosophy
- Performance Considerations

Important:
- This is strategic guidance, not implementation documentation
- Focus on WHY we're making these choices
- No code-level details
- Consider my constraints: [ADD ANY CONSTRAINTS: timeline, team size, budget, existing systems]

My initial thoughts on tech preferences (if any):
[YOUR PREFERENCES OR "No strong preferences, recommend what's best"]

CONVENTIONS.md

Purpose: Document global implementation patterns—file structure, naming, git, error handling. Domain-specific patterns live in domain skills.

What belongs here:

File/folder structure conventions
Naming conventions (files, functions, components, database)
Git conventions (commit messages, branch naming)
Error handling approaches
Global anti-patterns

What does NOT belong here:

Strategic decisions (those go in BUILD-STRATEGY.md)
Domain-specific patterns (those go in domain skills—e.g., testing patterns → testing-patterns/SKILL.md, API patterns → api-design/SKILL.md)
Feature specifications
Setup instructions

Key principle: This document is NOT pre-written. It emerges during implementation. After the first sprint/cycle, patterns will have formed—that's when this document starts to have real content.

Structure:

# Conventions

> This document captures global patterns and conventions for this codebase.
> Domain-specific patterns live in their respective skills under .claude/skills/.
> Updated continuously as patterns emerge or evolve.

## File Structure
```
src/
├── components/     # [Description]
├── hooks/          # [Description]
├── services/       # [Description]
├── utils/          # [Description]
└── ...
```

## Naming Conventions
- Components: [Convention, e.g., PascalCase]
- Files: [Convention]
- Functions: [Convention]
- Database tables: [Convention]

## Git Conventions
- Branch: `{NNN}/{brief-slug}` (e.g., `001/project-setup`)
- Commit: `[NNN] Description` (e.g., `[001] Initialize project structure`)
- One todo = one branch = one PR

## Error Handling
[Global error handling approach — e.g., error boundaries, try/catch patterns, logging]

## Anti-Patterns

### [Anti-pattern Name]
**Don't do this**:
```[language]
// Bad example
```
**Why**: [Explanation of what went wrong or why this is problematic]
**Do this instead**:
```[language]
// Good example
```

---
*Last updated: [Date]*
*Update this document when new global patterns emerge or existing patterns prove problematic.*
*Domain-specific patterns go in `.claude/skills/{domain}/SKILL.md`.*

Initial Setup Prompt (after first implementation cycle):

We've completed initial scaffolding. Analyze the codebase and create a CONVENTIONS.md that captures the global patterns that have emerged.

Review:
1. File and folder structure
2. Naming conventions in use
3. Git conventions
4. Error handling approaches
5. Any global anti-patterns discovered

This document covers GLOBAL conventions only. Domain-specific patterns (testing, API design, frontend, database) will go in dedicated skill files later.

CLAUDE.md

Purpose: Orchestrate agent behavior. Tell agents how to work in this codebase.

Approach: Use /init in Claude Code to generate the foundation, then append the custom instructions below.

Template:

## Custom Instructions

### Think Before Coding
- State assumptions explicitly. If uncertain, ask.
- If multiple valid approaches exist, present them with tradeoffs — don't pick silently.
- If a simpler approach exists, say so. Push back when warranted.
- If something is unclear, stop. Name what's confusing. Ask.

### Goal-Driven Execution
Transform tasks into verifiable goals before implementing:
- "Add validation" → "Write tests for invalid inputs, then make them pass"
- "Fix the bug" → "Write a test that reproduces it, then make it pass"

For multi-step tasks, state a brief plan:
```
1. [Step] → verify: [check]
2. [Step] → verify: [check]
```

### Surgical Changes
When editing existing code:
- Remove imports/variables/functions that YOUR changes made unused
- Don't remove pre-existing dead code unless asked (mention it instead)

### Session Startup Protocol
At the beginning of each session:
1. Read `docs/PRODUCT.md` to understand what we're building
2. Read `docs/BUILD-STRATEGY.md` for tech stack and architecture decisions
3. Read `CONVENTIONS.md` to understand current patterns and standards
4. Check `todos/active/` for in-progress work — if resuming, read the todo's Session Log for context from the previous session
5. Read `README.md` (if it exists) for project overview
6. Signal readiness by saying: "⏱️ So much time and so little to do. Wait. Strike that. Reverse it."

### Completing Work

> When using the `/implement` pipeline, completion is handled automatically by Step 8. Follow these steps only in non-pipeline sessions.

1. Commit all work
2. Update the todo file's Session Log (if working on a todo)
3. Execute the Self-Improving Protocol (below)
4. Move the todo file to the appropriate directory (`todos/done/`, `todos/blocked/`, or leave in `todos/active/`)
5. Signal completion by saying: "🧪 Invention is 93% perspiration, 6% electricity, 4% evaporation, and 2% butterscotch ripple. Do you concur?"

### Git Conventions
- Branch: `{NNN}/{brief-slug}` (e.g., `001/project-setup`)
- Commit: `[NNN] Description` (e.g., `[001] Add login form validation`)
- Keep commits focused and atomic

### Self-Improving Protocol
This protocol ensures the codebase gets smarter over time. It is **not optional**—execute it after every implementation session.

> When using the `/implement` pipeline, this protocol is executed via Step 7 (/compound). Follow it manually in non-pipeline sessions.

**After completing any implementation work:**
1. Review `CONVENTIONS.md`
2. Ask yourself:
   - Did I establish any new global patterns that should be replicated?
   - Did I discover that an existing pattern was problematic?
   - Did I try an approach that failed and should be documented as an anti-pattern?
3. If yes to any: Update `CONVENTIONS.md` (global) or the relevant domain skill (domain-specific)
4. For significant architectural changes: Add entry to `docs/DECISIONS.md`

**After resolving any bug or unexpected behavior:**
1. Identify root cause
2. Determine if it was caused by:
   - Missing pattern → Add the pattern to `CONVENTIONS.md` or domain skill
   - Wrong pattern → Update the pattern
   - One-off issue → Document in todo session log only
3. If a pattern caused the bug, document it as an anti-pattern with:
   - What the bad approach was
   - Why it failed
   - What the correct approach is

### When to Ask for Human Input
- Unclear or ambiguous requirements
- Decisions that significantly deviate from established patterns
- Security-sensitive implementations
- External service integrations not covered in `docs/BUILD-STRATEGY.md`
- When stuck after 2-3 different approaches
- When unsure if a pattern change is warranted

A Note on Signal Phrases (aka "Canaries")

What this is: A trick I picked up from another developer. You add specific phrases to your CLAUDE.md that Claude says at key moments—like a canary in a coal mine, letting you know everything's working as expected.

Why it's useful:

When running multiple Claude Code sessions, you can glance at a terminal and instantly know if Claude is oriented (startup) or done (completion)
If you don't see the phrase, you know something went wrong—Claude may have skipped steps or missed your instructions
Adds a bit of joy to your workflow

Where to put them:

Signal	Placement	What It Confirms
Startup	End of Session Startup Protocol	Claude read the context docs and is ready to begin
Completion	End of todo completion steps	Implementation is done and awaiting your review

How to add one: Add a numbered step with the format Signal [readiness/completion]: "[your phrase]". Example:

5. Signal readiness: "🦖 Hold onto your butts."

Movie quotes work great for this purpose.

README.md

Purpose: Dual-purpose—provide quick context for agents AND serve as traditional project documentation.

Structure:

# [Project Name]

[One paragraph: What is this project?]

## Quick Context for AI Agents
- **Product spec**: See `docs/PRODUCT.md`
- **Tech decisions**: See `docs/BUILD-STRATEGY.md`
- **Patterns & conventions**: See `CONVENTIONS.md`
- **Agent instructions**: See `CLAUDE.md`

## Getting Started

### Prerequisites
- [Runtime/language version]
- [Required tools]

### Installation
```bash
[Installation commands]
```

### Environment Setup
1. Copy `.env.example` to `.env`
2. Fill in required values:
   - `VAR_1`: [Description, where to get it]
   - `VAR_2`: [Description]

### Running Locally
```bash
[Commands to run the project]
```

### Running Tests
```bash
[Test commands]
```

## Project Structure
```
[High-level folder structure with brief descriptions]
```

## Documentation
- [docs/PRODUCT.md](docs/PRODUCT.md) — Product specification
- [docs/BUILD-STRATEGY.md](docs/BUILD-STRATEGY.md) — Technical approach
- [CONVENTIONS.md](CONVENTIONS.md) — Code patterns and standards

DECISIONS.md (Optional)

Purpose: Track significant decisions and pivots over time. Lightweight alternative to full ADRs.

When to use: When you've made a significant change to approach, swapped a major dependency, or reversed a previous decision.

Structure:

# Decision Log

## 2024-01-15: Switched from Redux to Zustand
**Context**: Redux boilerplate was slowing down development; state management needs are simpler than anticipated.
**Decision**: Migrate to Zustand for state management.
**Rationale**: Zustand offers simpler API, less boilerplate, and sufficient functionality for our needs.
**Trade-offs**: Less ecosystem tooling, team needs to learn new patterns.
**Migration notes**: [Any relevant details]

## 2024-01-10: Chose PostgreSQL over MongoDB
**Context**: Initial assumption was document store; data relationships proved more complex.
**Decision**: Use PostgreSQL with Prisma ORM.
**Rationale**: Strong relational needs, better query flexibility, team familiarity.
**Trade-offs**: More schema management overhead.

Design Documentation (Optional)

For simple apps: Single docs/DESIGN.md

For design-heavy apps: docs/design/ folder with:

BRAND.md — Colors, typography, voice/tone
THEME.md — Theme architecture, how to work with themes
COMPONENTS.md — Component patterns, when to use what

Note: Design docs are consumable by both humans and AI agents, including design-focused sub-agents and the frontend-design domain skill.

DESIGN.md Structure:

# Design System

> This document is consumable by both humans and AI agents (including design-focused sub-agents).

## Brand

### Colors
- Primary: `#[hex]` — [Usage]
- Secondary: `#[hex]` — [Usage]
- Accent: `#[hex]` — [Usage]
- Background: `#[hex]`
- Text: `#[hex]`
- Error: `#[hex]`
- Success: `#[hex]`

### Typography
- Headings: [Font family, weights]
- Body: [Font family, weights]
- Mono: [Font family]

### Spacing Scale
[8px base unit, or whatever system]

## Component Patterns

### Buttons
- Primary: [When to use, styling notes]
- Secondary: [When to use]
- Ghost: [When to use]

### Forms
[Form layout patterns, validation display]

### Cards
[Card usage patterns]

## Accessibility
- Minimum contrast ratios
- Focus state requirements
- Screen reader considerations

Agents

Philosophy

Agents extend the primary Claude instance's capabilities by handling specialized tasks in isolated context windows. Rather than asking one agent to do everything, we spawn focused agents with narrow mandates and clear deliverables.

Why context isolation matters:

A reviewer who didn't write the code catches more issues
A doc verifier with no implementation context reads docs like a newcomer would
A test writer that only sees the interface (not the implementation journey) writes more honest tests
Context isolation prevents the "I just wrote this so it must be right" bias

When to use agents:

Task requires specialized expertise (testing, security, documentation)
Task is distinct from main implementation flow
You want independent review/perspective on work
Task can be clearly scoped and isolated
Task produces large outputs that would clutter main context

When NOT to use agents:

Task is tightly coupled with ongoing implementation
Context switching overhead exceeds benefit
Task requires deep understanding of current session's work-in-progress

Key constraints:

Agents cannot spawn other agents (no nesting). The main conversation orchestrates multi-agent workflows.
Each agent runs in its own context window with its own system prompt, tool access, and permissions. It cannot see the main conversation history.

Core Agents

Agents are defined as Markdown files with YAML frontmatter. Store them in .claude/agents/ (project-level) or ~/.claude/agents/ (user-level, available across all projects). Project-level agents take precedence when names conflict.

Claude invokes agents automatically based on the description field, or you can invoke them manually by name.

`builder.md`

---
name: builder
description: Implements features following project conventions. Use proactively when starting work on implementation tasks.
tools: Read, Write, Edit, Bash, Grep, Glob
model: inherit
---

You are the builder agent. Implement the requested feature while maintaining project quality.

## Process

1. Read `CONVENTIONS.md` for current patterns and anti-patterns
2. If a todo file is referenced, read it for context (description, technical approach, session log)
3. Read any relevant domain skills in `.claude/skills/` for domain-specific patterns
4. Implement the feature following established conventions
5. Commit frequently: `[NNN] Brief description` format

## Before Finishing

1. If you established new patterns or found anti-patterns, note them in your summary
2. If you made significant architectural decisions, note them in your summary

## Output

Provide a concise summary:
- **Modified files**: Exact list of every file created, modified, or deleted (full paths)
- What was built (brief description)
- Any new patterns established or anti-patterns discovered
- Any open questions or known limitations

## Constraints
- Follow existing patterns in CONVENTIONS.md and domain skills
- Do NOT over-engineer—implement what's asked for
- Do NOT skip error handling at system boundaries

`test-writer.md`

---
name: test-writer
description: Expert test writing specialist. MUST BE USED after implementing features, before marking todos Done.
tools: Read, Grep, Glob, Bash, Write, Edit
model: inherit
---

You are a test-writing specialist. Your job is to write comprehensive tests for recently implemented code.

## Context Loading
- Read `CONVENTIONS.md` for global conventions
- Read `.claude/skills/testing-patterns/SKILL.md` if it exists, for testing-specific patterns and the **test command** to run
- Read `docs/BUILD-STRATEGY.md` for testing philosophy
- If the orchestrator provided a list of modified files, focus on those files specifically
- Otherwise, focus on the files/features specified in the task

## Your Task
1. Analyze the implementation to understand what needs testing
2. Write tests following established patterns
3. Run the tests to verify they pass (use the test command from testing-patterns skill or BUILD-STRATEGY.md)
4. Prioritize:
   - Happy path coverage
   - Edge cases
   - Error handling
   - Integration points
5. Use existing test utilities and mocking patterns

## Output
- Test files following project naming conventions
- Brief summary of coverage and any gaps you intentionally left

## Constraints
- Do NOT modify implementation code (flag issues instead)
- Do NOT write tests for functionality that doesn't exist
- Do NOT over-mock to the point tests don't verify real behavior

`code-reviewer.md`

---
name: code-reviewer
description: Expert code review specialist. MUST BE USED before merging to main, after implementation complete.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer. Review recent implementation work and provide actionable feedback.

## Process

1. If the orchestrator provided a list of modified files, use that list. Otherwise, run `git diff main --name-only` to identify changed files.
2. Run `git log --oneline -10` to understand recent commits
3. Read `CONVENTIONS.md` for project standards
4. Read any relevant domain skills in `.claude/skills/` for domain-specific patterns
5. Review each changed file

## Review Criteria

- **Correctness** — Does the code do what it should?
- **Convention compliance** — Does it follow CONVENTIONS.md and domain skills?
- **Edge cases** — Are error states handled?
- **Security** — Any injection, auth, or data exposure risks?
- **Performance** — Any obvious N+1 queries, missing indexes, or unnecessary work?
- **Readability** — Is the code clear without excessive comments?
- **Test quality** — Do tests verify real behavior? Any gaps?

## Output

Create a review document at `docs/reviews/YYYY-MM-DD-review.md`:

```markdown
# Code Review — YYYY-MM-DD

## Summary
[One paragraph: what was reviewed, overall quality assessment]

## Files Reviewed
- [file list]

## Critical (Must Fix)
- [ ] Description — `file:line` — Suggested fix

## Warnings (Should Fix)
- [ ] Description — `file:line` — Suggested fix

## Suggestions (Consider)
- [ ] Description — Rationale

## Convention Compliance
[Notes on adherence to CONVENTIONS.md and domain skills]

## Patterns to Document
[New patterns that should be added to CONVENTIONS.md or domain skills]
```

After creating the doc, return a brief summary of findings and the file path.

## Constraints
- Do NOT make changes yourself (main context decides what to act on)
- Do NOT be nitpicky about style if it matches conventions
- Do NOT flag issues that are explicitly accepted in CONVENTIONS.md

`doc-verifier.md`

---
name: doc-verifier
description: Verifies documentation accurately reflects the current implementation. Use after code changes are finalized.
tools: Read, Grep, Glob
model: inherit
---

You are a documentation auditor. Verify that project docs match the actual implementation.

## Process

1. Identify documentation files (CONVENTIONS.md, docs/*.md, README.md)
2. For each documented behavior, pattern, or example, verify it against the code
3. Check for features that exist in code but aren't documented

## Look For

- **Incorrect docs** — Documented behavior that doesn't match code
- **Missing docs** — Implemented features with no documentation
- **Stale examples** — Code samples that don't match current patterns
- **Dead references** — Links or paths to moved/deleted files

## Output

Create `docs/reviews/YYYY-MM-DD-doc-verification.md`:

```markdown
# Documentation Verification — YYYY-MM-DD

## Documents Reviewed
- [list]

## Critical (Docs Are Wrong)
- [ ] `[doc file]` — What's wrong → What it should say

## Missing Documentation
- [ ] [Feature/pattern] needs documentation in [suggested location]

## Stale Content
- [ ] `[doc file]` — [Section] references outdated [thing]

## Status
| Document | Status |
|----------|--------|
| CONVENTIONS.md | Accurate / Needs updates |
| README.md | Accurate / Needs updates |
| docs/*.md | Accurate / Needs updates |
```

Return a brief summary and the file path.

## Constraints
- Do NOT make changes yourself (main context handles fixes)
- Do NOT flag trivial formatting issues
- Focus on factual accuracy—does the documentation match the code?

`documentation-writer.md`

---
name: documentation-writer
description: Documentation specialist for human-readable docs. Use at end of sprint/milestone or when significant features ship.
tools: Read, Grep, Glob, Write, Edit
model: inherit
---

You are a documentation specialist. Your job is to write clear, helpful documentation for humans trying to understand and work with this codebase.

## Context Loading
- Read `README.md` for current documentation state
- Read `docs/PRODUCT.md` to understand what the product does
- Read `CONVENTIONS.md` to understand patterns
- Review recent changes as specified in the task

## Your Task
1. Update README.md if setup/running instructions have changed
2. Document new features for end users (if applicable)
3. Document new patterns or architectural changes for developers
4. Ensure documentation matches current reality

## Writing Guidelines
- Write for humans, not agents
- Assume reader is a competent developer but new to this codebase
- Include examples for complex concepts
- Keep it concise—link to code rather than duplicating it
- Use clear headings and scannable structure

## Output
- Updated documentation files
- Summary of what changed and why

## Constraints
- Do NOT document internal implementation details that will change
- Do NOT write documentation that duplicates CONVENTIONS.md
- Do NOT add fluff or marketing language

`refactor-scout.md`

---
name: refactor-scout
description: Refactoring specialist for identifying tech debt. Use after 3-5 features implemented or when codebase feels messy.
tools: Read, Grep, Glob
model: inherit
---

You are a refactoring specialist. Your job is to analyze the codebase and identify opportunities for improvement.

## Context Loading
- Read `CONVENTIONS.md` for established patterns
- Read `docs/BUILD-STRATEGY.md` for architectural intent
- Analyze the codebase holistically

## Identify
1. **Pattern violations**: Code that doesn't follow CONVENTIONS.md or domain skills
2. **Duplication**: Similar code that could be consolidated
3. **Complexity hotspots**: Files/functions that are too complex
4. **Abstraction opportunities**: Repeated patterns that could be extracted
5. **Dead code**: Unused files, functions, or imports
6. **Naming inconsistencies**: Things that don't match conventions

## Output Format
```markdown
## High Priority
[Refactors that reduce bugs or significantly improve maintainability]

## Medium Priority
[Refactors that improve consistency and readability]

## Low Priority / Tech Debt Backlog
[Nice-to-have improvements]

## Pattern Updates Needed
[Suggestions for CONVENTIONS.md or domain skills based on what you found]
```

For each item, include:
- Location (file/function)
- Current state (what's wrong)
- Suggested improvement
- Estimated effort (small/medium/large)

## Constraints
- Do NOT make changes yourself (output is for human prioritization)
- Do NOT suggest over-engineering or premature abstraction
- Do NOT flag things that are intentionally simple

Specialized Review Agents

These are opt-in supplements to the default code-reviewer. Use them when a task warrants deeper scrutiny in a specific domain. Invoke via /review [specialist-name] or directly.

`security-sentinel.md`

---
name: security-sentinel
description: Security-focused code reviewer. Use for auth flows, payment handling, user data processing, or any security-sensitive implementation.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a security specialist. Review recent implementation work with a security-first lens.

## Process

1. If the orchestrator provided a list of modified files, use that list. Otherwise, run `git diff main --name-only` to identify changed files.
2. Read `CONVENTIONS.md` for project security patterns
3. Review each changed file for security concerns

## Review Focus

- **Injection** — SQL injection, XSS, command injection, template injection
- **Authentication** — Token handling, session management, password storage, MFA
- **Authorization** — Access control checks, privilege escalation, IDOR
- **Data exposure** — Sensitive data in logs, responses, error messages, URLs
- **Secrets** — Hardcoded credentials, API keys, tokens in code or config
- **Dependencies** — Known vulnerable packages, unnecessary dependencies
- **Input validation** — Missing or insufficient validation at system boundaries
- **CSRF/CORS** — Cross-origin protections, same-site cookie settings

## Output

Create `docs/reviews/YYYY-MM-DD-security-review.md`:

```markdown
# Security Review — YYYY-MM-DD

## Summary
[Overall security posture of the changes]

## Critical (Must Fix Before Merge)
- [ ] Description — `file:line` — Risk level — Suggested fix

## Warnings (Should Fix)
- [ ] Description — `file:line` — Risk level — Suggested fix

## Recommendations
- [ ] Description — Rationale

## OWASP Top 10 Check
| Category | Status |
|----------|--------|
| Injection | Clear / Concern |
| Broken Auth | Clear / Concern |
| Sensitive Data Exposure | Clear / Concern |
| ... | ... |
```

Return a brief summary and the file path.

## Constraints
- Do NOT make changes yourself
- Do NOT flag theoretical risks with no practical attack vector
- Focus on real, exploitable vulnerabilities first

`data-integrity-guardian.md`

---
name: data-integrity-guardian
description: Data layer reviewer. Use for database migrations, data model changes, transaction-heavy code, or query-intensive features.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a data integrity specialist. Review recent implementation work focusing on the data layer.

## Process

1. If the orchestrator provided a list of modified files, use that list. Otherwise, run `git diff main --name-only` to identify changed files.
2. Identify migration files, schema changes, and data access code
3. Read `CONVENTIONS.md` and `.claude/skills/database-patterns/SKILL.md` (if it exists) for data patterns

## Review Focus

- **Migrations** — Reversibility, data preservation, zero-downtime compatibility, index creation
- **Data consistency** — Foreign key constraints, cascading deletes, orphaned records
- **Transactions** — Proper boundaries, isolation levels, deadlock potential
- **Query performance** — N+1 queries, missing indexes, full table scans, unnecessary joins
- **Data validation** — Constraint enforcement at DB level vs. app level
- **Race conditions** — Concurrent access patterns, optimistic/pessimistic locking

## Output

Create `docs/reviews/YYYY-MM-DD-data-review.md`:

```markdown
# Data Layer Review — YYYY-MM-DD

## Summary
[Overview of data layer changes and their risk level]

## Critical (Must Fix)
- [ ] Description — `file:line` — Risk — Suggested fix

## Warnings (Should Fix)
- [ ] Description — `file:line` — Risk — Suggested fix

## Migration Safety
| Migration | Reversible | Zero-downtime | Data preserved |
|-----------|-----------|---------------|----------------|
| [name] | Yes/No | Yes/No | Yes/No |

## Query Performance
[Notes on query patterns, missing indexes, optimization opportunities]
```

Return a brief summary and the file path.

## Constraints
- Do NOT make changes yourself
- Do NOT flag minor style issues in queries
- Focus on data safety and performance risks

`architecture-strategist.md`

---
name: architecture-strategist
description: Structural reviewer. Use for features that introduce new patterns, significant refactors, or changes that affect multiple modules.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are an architecture reviewer. Review recent implementation work for structural quality and alignment with the project's architectural intent.

## Process

1. If the orchestrator provided a list of modified files, use that list. Otherwise, run `git diff main --name-only` to identify changed files.
2. Read `docs/BUILD-STRATEGY.md` for architectural intent
3. Read `CONVENTIONS.md` for established patterns
4. Review the structural impact of the changes

## Review Focus

- **Separation of concerns** — Are responsibilities clearly divided? Any god objects/functions?
- **Coupling** — Are modules appropriately decoupled? Hidden dependencies?
- **Cohesion** — Do related things live together? Are unrelated things separated?
- **BUILD-STRATEGY alignment** — Do the changes follow the intended architecture?
- **Dependency direction** — Do dependencies flow in the right direction?
- **API boundaries** — Are internal/external interfaces clean and well-defined?
- **Scalability implications** — Will this approach work at 10x scale?

## Output

Create `docs/reviews/YYYY-MM-DD-architecture-review.md`:

```markdown
# Architecture Review — YYYY-MM-DD

## Summary
[Overall structural quality assessment]

## Critical (Structural Issues)
- [ ] Description — Impact — Suggested refactor

## Warnings (Design Concerns)
- [ ] Description — Impact — Suggested improvement

## Alignment with BUILD-STRATEGY.md
[Notes on how changes align or diverge from intended architecture]

## Pattern Observations
[Emerging patterns that should be documented, or existing patterns being violated]
```

Return a brief summary and the file path.

## Constraints
- Do NOT make changes yourself
- Do NOT over-architect — suggest the simplest structure that works
- Do NOT flag things that are intentionally simple for the current scale

`pattern-recognition-specialist.md`

---
name: pattern-recognition-specialist
description: Pattern consistency reviewer. Use after several features to catch convention drift, inconsistencies across files, and missed abstraction opportunities.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a pattern consistency specialist. Review the codebase for cross-file consistency and convention adherence.

## Process

1. If the orchestrator provided a list of modified files, use that list. Otherwise, run `git diff main --name-only` to identify changed files.
2. Read `CONVENTIONS.md` for established patterns
3. Read domain skills in `.claude/skills/` for domain-specific patterns
4. Compare the changed files against patterns in the rest of the codebase

## Review Focus

- **Cross-file consistency** — Are similar things implemented the same way across the codebase?
- **Convention drift** — Has the codebase drifted from documented conventions?
- **Naming consistency** — Are names consistent across related files?
- **Pattern completeness** — Are established patterns applied everywhere they should be?
- **Abstraction opportunities** — Are there 3+ instances of the same pattern that could be extracted?
- **Convention gaps** — Are there patterns in the code that aren't documented yet?

## Output

Create `docs/reviews/YYYY-MM-DD-pattern-review.md`:

```markdown
# Pattern Review — YYYY-MM-DD

## Summary
[Overall consistency assessment]

## Inconsistencies Found
- [ ] Pattern: [name] — `file:line` deviates from `file:line` — Suggested fix

## Convention Drift
- [ ] `CONVENTIONS.md` says X but code does Y in [locations]

## Undocumented Patterns
- [ ] Pattern observed in [locations] — should be added to [CONVENTIONS.md / domain skill]

## Abstraction Candidates
- [ ] [Pattern] appears in [N] places — could be extracted to [location]
```

Return a brief summary and the file path.

## Constraints
- Do NOT make changes yourself
- Do NOT suggest abstractions for fewer than 3 instances
- Do NOT flag intentional variations documented in conventions

Manual Agent Invocation

Use agents directly when you don't need the full pipeline:

Use the builder subagent to implement the todo 005 search feature

Use the code-reviewer subagent to review the last 3 commits

Use the test-writer subagent to write tests for the auth module

Use the doc-verifier subagent to check if CONVENTIONS.md is still accurate

Use the refactor-scout subagent to analyze the services/ directory for tech debt

Use the security-sentinel subagent to review the payment flow

Automatic invocation: Claude reads each agent's description field and delegates automatically when tasks match. Use trigger phrases like "MUST BE USED" or "use PROACTIVELY" in descriptions to encourage automatic delegation.

Skills

Skill System Overview

Skills are Markdown files with YAML frontmatter stored in .claude/skills/. They inject instructions or knowledge into your current conversation when invoked.

Key mechanics:

Progressive disclosure: Claude sees only the skill's description at startup. Full content loads on invocation.
Frontmatter fields: name, description, argument-hint (placeholder text for arguments)
$ARGUMENTS: Replaced with whatever the user types after the skill name (e.g., /implement Add login flow → $ARGUMENTS = "Add login flow")
Invocation: Type /skill-name followed by optional arguments

Skill types in this playbook:

Workflow skills orchestrate multi-step processes (/implement, /plan, /work, /review, /compound)
Domain skills inject domain-specific knowledge and patterns (frontend, database, testing, API)

Workflow Skills

`/implement` — Full Pipeline

The primary orchestration skill. Chains agents through a complete build → test → review → verify → compound cycle.

Create .claude/skills/implement/SKILL.md:

---
name: implement
description: Run the full build → test → review → verify → compound workflow for a feature or task
argument-hint: <todo NNN or task description>
---

Run the full implementation workflow for: $ARGUMENTS

Follow these steps in order. Do not skip steps.

## Step 0 — Context

If a todo number (NNN) is referenced in "$ARGUMENTS":
1. Read the todo file from `todos/active/` (or `todos/backlog/` and move it to `todos/active/`)
2. Note the description, technical approach, and acceptance criteria
3. Use the todo number for commit messages and branch naming

If no todo is referenced, proceed with the task description as given.

## Step 1 — Build

Use the **builder** subagent to implement the feature: $ARGUMENTS

Provide it with any relevant context from the todo file. Wait for it to complete.

**Capture the builder's file list**: The builder's summary must include an exact list of modified file paths. Extract this list — you will pass it to downstream agents so they know exactly what to review and test.

## Step 2 — Test (conditional)

Review the builder's summary. Invoke the **test-writer** subagent if the implementation includes testable logic—data access, business rules, non-trivial transformations, or error handling paths.

**Pass the modified file list** from Step 1 to the test-writer so it knows exactly which files to write tests for.

**Skip** if the work is primarily scaffolding, configuration, layout, or wiring with no meaningful logic to verify. Note that you skipped and why.

If invoked, wait for it to complete and note its coverage summary.

## Step 3 — Code Review

Use the **code-reviewer** subagent to review the changes made in Steps 1 and 2 (if applicable).

**Pass the modified file list** from Steps 1-2 to the code-reviewer so it reviews exactly the right files without relying on `git diff`.

Wait for it to complete. Read the full review document it created.

## Step 4 — Address Review Feedback

Address the review findings yourself (do not use a subagent):
1. Fix all **Critical** items
2. Fix all **Warning** items
3. Consider **Suggestion** items and fix where appropriate
4. Commit the fixes

## Step 5 — Documentation Verification

Use the **doc-verifier** subagent to verify documentation matches the implementation.

Wait for it to complete. Read the verification report.

## Step 6 — Address Doc Issues

Fix any **Critical** documentation discrepancies yourself. Commit the changes.

## Step 7 — Compound Engineering

Execute the compound engineering protocol yourself (do not use a subagent):
1. Review `CONVENTIONS.md` — add any new global patterns, update any that proved problematic, document anti-patterns
2. Check relevant domain skills in `.claude/skills/` — update domain-specific patterns if applicable
3. Update `docs/DECISIONS.md` if significant architectural decisions were made
4. Commit any convention or skill updates

## Step 8 — Finalize

1. If a todo was referenced:
   - Update the todo file's Session Log with what was built, status, and context
   - Move the todo file from `todos/active/` to `todos/done/`

2. Provide a **final summary** covering:
   - What was built
   - Test coverage (or why tests were skipped)
   - Review findings and how they were resolved
   - Documentation status
   - Convention/skill updates made
   - Files created or modified
   - Any remaining items or known issues

`/plan` — Discrete Planning

Create .claude/skills/plan/SKILL.md:

---
name: plan
description: Analyze a task and produce an implementation plan before building
argument-hint: <todo NNN or task description>
---

Create an implementation plan for: $ARGUMENTS

## Process

1. **Load context:**
   - Read `docs/PRODUCT.md` for product understanding
   - Read `docs/BUILD-STRATEGY.md` for architectural constraints
   - Read `CONVENTIONS.md` for established patterns
   - Check `todos/` for current progress (backlog, active, done)
   - If a todo number (NNN) is referenced, read the todo file for details

2. **Analyze the codebase:**
   - Identify files that will need to be created or modified
   - Understand existing patterns in the affected areas
   - Check for relevant domain skills in `.claude/skills/`

3. **Produce the plan:**
   - List the implementation steps in order
   - For each step: what to do, which files, and how to verify
   - Flag risks, open questions, or decisions that need human input
   - Estimate complexity (small/medium/large)

4. **Output format:**
```markdown
## Implementation Plan: [Task]

### Approach
[1-2 paragraph summary of the approach and key decisions]

### Steps
1. [Step] — `file(s)` — verify: [how to check it worked]
2. [Step] — `file(s)` — verify: [check]
...

### Risks / Open Questions
- [Risk or question]

### Complexity: [Small / Medium / Large]
```

Do NOT implement anything. This is a planning-only step.

`/work` — Discrete Build

Create .claude/skills/work/SKILL.md:

---
name: work
description: Invoke the builder agent to implement a feature or task
argument-hint: <todo NNN or task description>
---

Build: $ARGUMENTS

## Process

1. If a todo number (NNN) is referenced:
   - Read the todo file for context
   - Move it to `todos/active/` if it's still in `todos/backlog/`

2. Use the **builder** subagent to implement: $ARGUMENTS

   Provide it with any relevant context from the todo file.

3. When the builder completes, summarize what was built and any open items.

This skill does NOT run tests, reviews, or compound engineering. Use `/implement` for the full pipeline, or follow up with `/review` and `/compound` as needed.

`/review` — Discrete Review

Create .claude/skills/review/SKILL.md:

---
name: review
description: Run a code review on recent changes, optionally with a specialist reviewer
argument-hint: [specialist-name] (default: code-reviewer)
---

Review recent changes using: $ARGUMENTS

## Determine Reviewer

Parse $ARGUMENTS to determine which reviewer to use:
- If empty or "code-reviewer" → use **code-reviewer** (default)
- If "security" or "security-sentinel" → use **security-sentinel**
- If "data" or "data-integrity-guardian" → use **data-integrity-guardian**
- If "architecture" or "architecture-strategist" → use **architecture-strategist**
- If "patterns" or "pattern-recognition-specialist" → use **pattern-recognition-specialist**

## Process

1. Identify the files to review: run `git diff main --name-only` to get the list of changed files
2. Invoke the selected reviewer subagent, passing the list of changed files so it can focus its review
3. Wait for it to complete
4. Read the full review document it created
5. Summarize findings: Critical count, Warning count, Suggestion count
6. Ask the user how they'd like to proceed:
   - "Fix all" — address all Critical and Warning items
   - "Fix critical only" — address only Critical items
   - "Skip" — note findings for later

`/compound` — Discrete Compound Engineering

Create .claude/skills/compound/SKILL.md:

---
name: compound
description: Review recent changes and update conventions, domain skills, and decisions documentation
argument-hint: (no arguments needed)
---

Execute the compound engineering protocol for recent changes.

## Process

1. **Review what changed:**
   - Run `git diff main --name-only` to see changed files
   - Run `git log --oneline main..HEAD` to see commit history

2. **Update global conventions:**
   - Read `CONVENTIONS.md`
   - Ask: Did any new global patterns emerge? Any existing patterns prove problematic? Any anti-patterns discovered?
   - If yes: Update `CONVENTIONS.md`

3. **Update domain skills:**
   - Check `.claude/skills/` for existing domain skills
   - Ask: Did domain-specific patterns emerge that belong in a skill rather than CONVENTIONS.md?
   - If a relevant skill exists: Update it
   - If a new domain is emerging (3+ related patterns): Consider creating a new domain skill

4. **Update decisions log:**
   - Ask: Were any significant architectural decisions made?
   - If yes: Add entry to `docs/DECISIONS.md`

5. **Commit updates:**
   - Commit any convention, skill, or decision updates with a clear message

6. **Summary:**
   - List what was updated and why
   - Note any domain skills that might be worth creating in the future

Domain Skills

Domain skills inject domain-specific patterns and conventions into context only when relevant. They keep CONVENTIONS.md lean (global patterns only) while ensuring deep domain knowledge is available on demand.

Where they live: .claude/skills/{domain-name}/SKILL.md

When they load: When Claude invokes the skill, when the /implement pipeline builder reads them, or when explicitly referenced.

How they grow: The /compound skill (or /implement Step 7) reviews recent changes and updates the relevant domain skill, just like it updates CONVENTIONS.md for global patterns.

`frontend-design/SKILL.md`

---
name: frontend-design
description: Frontend design patterns and anti-AI-slop aesthetic guidelines. Use when building UI components, pages, or layouts.
---

# Frontend Design Patterns

## The Prime Directive
**NEVER** produce generic, cookie-cutter UI. Avoid "AI slop" aesthetics: standard purple gradients, rounded cards on white backgrounds, generic Bootstrap/Tailwind defaults.

## Design Thinking Process
Before generating any frontend code, commit to a specific aesthetic direction:
- **Brutally Minimal** or **Maximalist Chaos**
- **Retro-Futuristic** or **Organic/Natural**
- **Luxury/Refined** or **Playful/Toy-like**
- **Editorial/Magazine** or **Industrial/Utilitarian**
- **Art Deco/Geometric** or **Soft/Pastel**

State your chosen direction before writing code.

## Aesthetic Guidelines

### Typography
ABANDON generic fonts (Arial, Roboto, Inter, system fonts). Select distinctive, characterful fonts. Pair a unique display font with a refined body font.

### Color
Use dominant colors with sharp accents. Avoid timid, evenly distributed palettes. Every color choice should be intentional.

### Motion
Implement high-impact moments. Use staggered reveals (animation-delay) and scroll triggers. Motion should feel purposeful, not decorative.

### Composition
Use asymmetry, overlap, diagonal flow, and grid-breaking elements. Rigid grids are a starting point, not a destination.

### Texture & Depth
Use noise textures, gradient meshes, geometric patterns, glassmorphism, or grain overlays to create atmosphere.

## Component Patterns
[Add project-specific component patterns as they emerge]

## Anti-Patterns
- Generic card grids with uniform spacing
- Purple/blue gradient headers
- Centered text blocks with no visual hierarchy
- Stock photo hero sections
- Default shadow/radius values everywhere

## Output Format
When building UI:
1. State your design rationale (the "vibe" and why)
2. Provide complete, working code
3. Reference `docs/DESIGN.md` or `docs/design/` for project-specific brand guidelines

`database-patterns/SKILL.md`

---
name: database-patterns
description: Database conventions, migration safety, query patterns, and data integrity rules. Use when working with database schemas, migrations, or data access code.
---

# Database Patterns

## Migration Safety
- All migrations must be reversible (provide both `up` and `down`)
- Never drop columns in production without a deprecation period
- Add new columns as nullable or with defaults — never as required on existing tables
- Create indexes concurrently when possible to avoid table locks
- Test migrations against a copy of production-scale data before deploying

## Naming Conventions
- Tables: `snake_case`, plural (e.g., `user_profiles`)
- Columns: `snake_case` (e.g., `created_at`, `is_active`)
- Foreign keys: `{referenced_table_singular}_id` (e.g., `user_id`)
- Indexes: `idx_{table}_{columns}` (e.g., `idx_users_email`)
- Enums: `snake_case` values (e.g., `pending`, `in_progress`)

## Query Patterns
- Always use parameterized queries — never string concatenation
- Use explicit column lists in SELECT — avoid `SELECT *`
- Include LIMIT on queries that could return unbounded results
- Use database-level constraints (NOT NULL, UNIQUE, CHECK) in addition to app-level validation

## Transactions
- Wrap multi-step mutations in transactions
- Keep transactions short — no external API calls inside a transaction
- Use appropriate isolation levels (default to READ COMMITTED)
- Handle deadlocks with retry logic

## Indexing Strategy
- Index foreign keys
- Index columns used in WHERE, ORDER BY, and JOIN clauses
- Use composite indexes for queries that filter on multiple columns
- Monitor slow query logs and add indexes based on actual usage

## Anti-Patterns
[Add project-specific anti-patterns as they emerge]

`testing-patterns/SKILL.md`

---
name: testing-patterns
description: Testing conventions, structure, mocking patterns, and what to test. Use when writing or reviewing tests.
---

# Testing Patterns

## Test Structure
- One test file per source file: `{filename}.test.{ext}`
- Group related tests with `describe` blocks
- Use descriptive test names: "should [expected behavior] when [condition]"
- Follow Arrange-Act-Assert (AAA) pattern within each test

## What to Test
- **Always test**: Business logic, data transformations, validation rules, error handling paths
- **Usually test**: API endpoints (integration), complex UI interactions, state management
- **Skip**: Trivial getters/setters, framework boilerplate, styling, static content

## Mocking Guidelines
- Mock external services (APIs, databases, file system) — not internal modules
- Use real implementations for pure utility functions
- Reset mocks between tests to avoid state leakage
- Prefer dependency injection over module mocking when possible

## Test Data
- Use factories or builders for test data — not raw object literals repeated everywhere
- Keep test data minimal — only include fields relevant to the test
- Use realistic but deterministic values (avoid `Math.random()` in tests)

## Anti-Patterns
- Testing implementation details instead of behavior
- Asserting on entire objects when only one field matters
- Tests that pass when the feature is broken (false positives)
- Tests that break when unrelated code changes (brittle tests)
- Mocking so heavily that the test verifies nothing real

## Test Command
<!-- REQUIRED: Update this for your project so agents know how to run tests -->
```bash
# Example — replace with your project's actual test command:
npm test -- <filepath>
```

## Project-Specific Patterns
[Add patterns as they emerge — e.g., test utilities, shared fixtures, custom matchers]

`api-design/SKILL.md`

---
name: api-design
description: API design conventions including URL structure, HTTP methods, error format, pagination, and auth patterns. Use when building or reviewing API endpoints.
---

# API Design Patterns

## URL Structure
- Use plural nouns: `/users`, `/orders`, `/products`
- Nest for clear relationships: `/users/{id}/orders`
- Use kebab-case for multi-word resources: `/order-items`
- Keep URLs shallow — max 2 levels of nesting

## HTTP Methods
- `GET` — Read (idempotent, no side effects)
- `POST` — Create (or complex operations that don't fit REST)
- `PUT` — Full replace
- `PATCH` — Partial update
- `DELETE` — Remove

## Response Format
```json
{
  "data": { ... },
  "meta": { "page": 1, "total": 100 }
}
```

## Error Format
```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable description",
    "details": [
      { "field": "email", "message": "Invalid email format" }
    ]
  }
}
```

Use appropriate HTTP status codes:
- `400` — Bad request (validation errors)
- `401` — Not authenticated
- `403` — Authenticated but not authorized
- `404` — Resource not found
- `409` — Conflict (e.g., duplicate)
- `422` — Unprocessable entity (valid syntax, invalid semantics)
- `500` — Server error (never expose internals)

## Pagination
- Use cursor-based pagination for large or frequently-changing datasets
- Use offset/limit for small, stable datasets
- Always include total count when using offset pagination
- Return pagination metadata in `meta` field

## Authentication
- Use Bearer tokens in Authorization header
- Never pass tokens in URLs (they appear in logs)
- Short-lived access tokens + long-lived refresh tokens
- Include rate limiting headers in responses

## Project-Specific Patterns
[Add patterns as they emerge — e.g., specific middleware, versioning strategy, webhook patterns]

Task Management

Filesystem Todo System

Todos live in the repository as Markdown files, organized by status into subdirectories.

Directory Structure

todos/
├── backlog/          # Not yet started
│   ├── 004-search-and-filtering.md
│   ├── 005-settings-page.md
│   └── 006-email-notifications.md
├── active/           # Currently being worked on
│   └── 003-dashboard-layout.md
├── done/             # Completed
│   ├── 001-project-setup.md
│   └── 002-auth-flow.md
└── blocked/          # Waiting on something
    └── 007-payment-integration.md

Why this works:

ls todos/active/ immediately shows what's in progress
ls todos/backlog/ shows what's next
Glob patterns find todos instantly: todos/**/*.md
Git tracks history natively
No external service dependency

File Naming

{NNN}-{slug}.md

NNN: Three-digit sequential number (001, 002, 003...)
slug: Kebab-case description
Examples: 001-project-setup.md, 014-payment-webhook.md

Numbers are sortable, human-readable, and work cleanly in commit messages and branch names.

Todo File Template

---
id: "NNN"
title: "Human-readable title"
status: backlog | active | done | blocked
priority: high | medium | low
complexity: small | medium | large
depends-on: []
blocks: []
parallelizable: false
created: YYYY-MM-DD
started:
completed:
branch: "NNN/slug"
---

## Description
[Clear description of what needs to be implemented]

## Technical Approach
- Approach: [How this should be implemented]
- Files likely affected: [List key files]
- Dependencies: [Other todos this depends on]

## Acceptance Criteria
- [ ] [Criterion 1]
- [ ] [Criterion 2]
- [ ] [Criterion 3]

## Session Log

### YYYY-MM-DD
- What was done: [Summary]
- Status: [Complete / In Progress / Blocked]
- Context for next session: [Important notes]
- Known issues: [Any edge cases or problems]

Status Transitions

Moving a file between directories is the status transition:

# Start work on a todo
mv todos/backlog/003-dashboard-layout.md todos/active/

# Complete a todo
mv todos/active/003-dashboard-layout.md todos/done/

# Block a todo
mv todos/active/007-payment-integration.md todos/blocked/

# Unblock and resume
mv todos/blocked/007-payment-integration.md todos/active/

Generating Todos

Break your project into todos directly from the context docs. For greenfield projects, use PRODUCT.md + BUILD-STRATEGY.md. For brownfield, describe the changes you want. For a single feature, just create one todo manually.

Generation Prompt (greenfield):

Read and internalize:
1. Product specification: docs/PRODUCT.md
2. Build strategy: docs/BUILD-STRATEGY.md

Break the MVP into discrete, implementable tasks. Each task should be completable in a single /implement session.

For each task, create a todo file in todos/backlog/ following the naming convention {NNN}-{slug}.md with:
- YAML frontmatter (id, title, status: backlog, priority, complexity, depends-on, blocks, parallelizable, created, branch)
- Clear description and technical approach
- Acceptance criteria
- Empty Session Log section

Number sequentially (001, 002, 003...). Group foundational/infrastructure tasks first, then features. Flag dependencies and mark what can parallelize.

For brownfield or feature work, adapt the prompt:

I want to add [feature / fix / refactor description] to this codebase.

Review the codebase, then break this work into discrete todos in todos/backlog/. Each should be completable in a single /implement session. Use the {NNN}-{slug}.md naming convention, continuing from the highest existing todo number.

Complete Example

---
id: "004"
title: "User registration and login flow"
status: active
priority: high
complexity: medium
depends-on: ["001", "003"]
blocks: ["007"]
parallelizable: false
created: 2026-03-10
started: 2026-03-11
completed:
branch: "004/auth-flow"
---

## Description
Implement user registration (email/password) and login with JWT tokens. Include email validation, password strength requirements, and secure token storage.

## Technical Approach
- Use bcrypt for password hashing
- JWT access tokens (15min) + refresh tokens (7d)
- Store refresh tokens in httpOnly cookies
- Rate limit login attempts (5/min per IP)
- Files affected: routes/auth.ts, services/auth.ts, middleware/auth.ts, migrations/

## Acceptance Criteria
- [ ] Users can register with email and password
- [ ] Password must be 8+ chars with at least one number
- [ ] Users can log in and receive JWT token
- [ ] Invalid credentials return 401 with generic message
- [ ] Refresh token rotation on use
- [ ] Rate limiting prevents brute force

## Session Log

### 2026-03-11
- What was done: Scaffolded auth routes, implemented registration endpoint, added bcrypt hashing
- Status: In Progress
- Context for next session: Login endpoint and JWT generation still needed. Registration works and passes basic tests.
- Known issues: Need to add email uniqueness constraint migration

The Implementation Layer

Git Integration

Branch Strategy:

main
├── 001/project-setup
├── 002/auth-flow
├── 003/dashboard-ui
└── ...

Conventions:

Branch: {NNN}/{brief-slug} (e.g., 004/auth-flow)
Commit: [NNN] Description (e.g., [004] Add login form validation)
One todo = one branch = one PR
Merge to main after review/approval

Parallel Work with Worktrees

When working on multiple independent todos simultaneously (marked parallelizable: true), use git worktrees to isolate each implementation. Each worktree is a separate checkout with its own branch, allowing multiple Claude instances to work without stepping on each other.

Shell Setup (add to ~/.zshrc):

# Create a worktree for a todo and start Claude
worktree-claude() {
  local todo=$1
  local repo=$(basename "$(git rev-parse --show-toplevel)")
  local dir="../${repo}-${todo}"
  local branch="${todo}"

  if [ ! -d "$dir" ]; then
    git worktree add "$dir" -b "$branch"
  fi

  cd "$dir"
  echo "Starting Claude in worktree. Suggested first message:"
  echo "  Work on todo ${todo}"
  echo ""
  claude
}

# Clean up worktrees whose branches have been merged into main
worktree-cleanup() {
  local main_repo=$(git rev-parse --show-toplevel)

  git worktree list | while read -r line; do
    local wt_path=$(echo "$line" | awk '{print $1}')
    [ "$wt_path" = "$main_repo" ] && continue

    local branch=$(git -C "$wt_path" rev-parse --abbrev-ref HEAD 2>/dev/null)
    if [ -n "$branch" ] && git branch --merged main | grep -qE "^\s*${branch}$"; then
      echo "Removing worktree: $wt_path (branch: $branch)"
      git worktree remove "$wt_path"
      git branch -d "$branch" 2>/dev/null
    fi
  done

  # Clean up orphaned branches that are merged but have no worktree
  git branch --merged main | grep -E "^\s*[0-9]{3}/" | while read -r branch; do
    branch=$(echo "$branch" | xargs)
    echo "Removing orphaned branch: $branch"
    git branch -d "$branch" 2>/dev/null
  done
}

Workflow:

Step	Command	Notes
Start parallel work	`worktree-claude 004/auth-flow`	Run from main repo; opens Claude in new worktree
Work on todo	(normal session)	Same protocols as single-todo workflow
Push & create PR	(from worktree)	Claude pushes branch, creates PR
After PR merges	`worktree-cleanup`	Run from main repo; removes merged worktrees

When to use:

Multiple todos marked parallelizable: true with no dependencies
You want to context-switch between todos without stashing/branching
Running multiple Claude instances on different features

When NOT to use:

Todos that modify the same files (merge conflicts)
Single-todo focused work (unnecessary overhead)

Handling conflicts: Even parallelizable todos can conflict if they touch shared files. When GitHub shows conflicts on one PR:

Merge the clean PR first
In the conflicting worktree:
```
cd ../repo-004
claude
```
Ask Claude: "Rebase onto main, resolve conflicts preserving both changes, and push."

Context7 MCP Setup

Context7 provides deterministic, version-pinned library documentation directly in Claude's context. Instead of searching the web for how a library works, Claude can look up the exact API for the version you're using.

Configuration (add to ~/.claude/mcp.json or project .claude/mcp.json):

{
  "mcpServers": {
    "context7": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@context7/mcp@latest"]
    }
  }
}

What it provides: Library documentation lookup via MCP tools. Claude can query docs for specific libraries and versions.

When to use: When implementing features that depend on specific library APIs. Particularly useful for:

Less common libraries where Claude's training data may be outdated
Version-specific API differences
Exact function signatures and parameters

In the BUILD-STRATEGY.md creation prompt, we reference Context7 instead of generic web search for library research.

settings.json Reference

Create or update .claude/settings.json:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Check if the user invoked the /implement skill in this conversation. If they did NOT use /implement, return {\"decision\": \"allow\"}. If they DID use /implement, verify ALL of these phases completed: (1) builder subagent was invoked, (2) test-writer subagent was either invoked OR explicitly skipped with a stated reason, (3) code-reviewer subagent was invoked, (4) review feedback was addressed, (5) doc-verifier subagent was invoked, (6) compound engineering was executed, (7) a final summary was provided. If any phase is missing, return {\"decision\": \"block\", \"reason\": \"[missing phase] has not been completed yet\"}. If all phases completed, return {\"decision\": \"allow\"}."
          }
        ]
      }
    ]
  }
}

This prompt-based hook runs when Claude is about to stop. A fast model (Haiku) evaluates the conversation and blocks completion if any workflow phase was skipped. It only activates when /implement was used, so it won't interfere with normal conversations or discrete workflow commands.

Optional: SubagentStop logging

Track subagent completions without affecting flow control:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "..."
          }
        ]
      }
    ],
    "SubagentStop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo \"[$(date -Iseconds)] Subagent completed\" >> .claude/workflow.log"
          }
        ]
      }
    ]
  }
}

Day-to-Day Workflow

Starting a New Project

1. Create project directory
2. Write PRODUCT.md (using the creation prompt)
3. Write BUILD-STRATEGY.md (using the creation prompt, with Context7 for library research)
4. Run /init → generates CLAUDE.md
5. Append the CLAUDE.md template from this playbook
6. Copy .claude/ agents, skills, and settings.json into the project
7. Create todos/ directory structure (backlog/, active/, done/, blocked/)
8. Generate todo files from PRODUCT.md + BUILD-STRATEGY.md (using the generation prompt)
9. git init, initial commit

Brownfield projects: Skip steps 2-3 if you already have context docs or prefer to describe scope conversationally. Start at step 4, then generate todos by describing what you want to change.

Pipeline Mode (`/implement`)

The full automated pipeline. Use this for standard feature work where you want build → test → review → verify → compound in one shot.

When to use: Most feature implementation. This is the default workflow.

Start:

1. Check todos/backlog/ or todos/active/ for what to work on next
2. Start Claude:
   - Standard: Open Claude Code in the project directory
   - Parallel work: Run worktree-claude {NNN}/{slug} from main repo
3. Claude reads context docs automatically (per CLAUDE.md Session Startup Protocol)
4. Run: /implement {NNN} {Todo title or description}
5. Pipeline runs all 9 steps automatically

Finish:

1. Review the pipeline's summary
2. Push branch
3. Create PR / merge
4. If using worktrees: worktree-cleanup from main repo later

Walkthrough example:

You: /implement 004 User registration and login flow

[Skill expands into the 9-step orchestration prompt]

Main: Reading todo 004... Moving to active. Invoking builder subagent...

Builder (isolated context):
  → Reads CONVENTIONS.md, domain skills, and todo 004
  → Implements auth routes, services, middleware
  → Commits work across 4 commits
  → Returns summary with file list:
    routes/auth.ts, services/auth.ts, middleware/auth.ts,
    migrations/001_users.sql, types/auth.ts

Main: Builder complete. Captures file list. Implementation includes auth logic
      — invoking test-writer with file list...

Test-writer (isolated context):
  → Receives file list, reads testing-patterns skill for test command
  → Writes unit and integration tests for auth flow
  → Runs tests, all pass
  → Returns coverage summary

Main: Tests written. Invoking code-reviewer with file list...

Code-reviewer (isolated context):
  → Receives file list, reviews exactly those files
  → Creates docs/reviews/2026-03-11-review.md
  → Returns: 1 Critical, 2 Warnings, 1 Suggestion

Main: Review complete. Addressing findings...
  → Fixes Critical (missing rate limiting on login)
  → Fixes Warnings (error message leaking email existence, weak password regex)
  → Notes Suggestion (add account lockout — deferred)
  → Commits fixes

Main: Invoking doc-verifier subagent...

Doc-verifier (isolated context):
  → Compares docs to implementation
  → Returns: CONVENTIONS.md needs auth pattern documented

Main: Fixing doc issues. Running compound engineering...
  → Adds auth middleware pattern to CONVENTIONS.md
  → Updates api-design skill with auth header convention
  → Commits updates

Main: Finalizing...
  → Updates todo 004 session log
  → Moves todo to done/
  → Provides full summary

[Quality gate checks all phases ✓ — allows completion]

Discrete Workflow Commands

For when you want more control than the full pipeline, or only need part of the process.

Available commands:

Command	What It Does	When to Use
`/plan`	Analyze task, produce implementation plan (output in conversation, no file created)	Before complex features; when you want to review the approach first
`/work`	Invoke builder agent only	Quick implementations; when you'll review manually
`/review`	Run code review (default or specialist)	After manual work; when you want a second opinion
`/review security`	Security-focused review	Auth, payment, user data features
`/review data`	Data layer review	Migrations, schema changes, query-heavy features
`/review architecture`	Structural review	Multi-module changes, new patterns
`/review patterns`	Pattern consistency check	After several features, periodic health check
`/compound`	Update conventions and domain skills	After manual work; periodic knowledge capture

Example flows:

Quick feature (low risk):

/work 008 Add settings page
[review the output manually]
/compound

Complex feature (high risk):

/plan 004 User auth flow
[review the plan, adjust if needed]
/implement 004 User auth flow

Security-sensitive feature:

/implement 012 Payment webhook handler
/review security
[fix any security findings]

Periodic health check:

/review patterns
/review architecture
/compound

Manual Mode

For debugging, exploration, spikes, and tasks that don't fit structured workflows.

Session Start:

1. Check todos/active/ for in-progress work (if applicable)
2. Start Claude in the project directory
3. Describe the task directly
4. Agent reads context docs per Session Startup Protocol
5. Work begins

During Session:

- One todo per session (context hygiene)
- Frequent commits with clear messages
- If stuck: Document approaches tried, ask for human input
- If requirements unclear: Clarify before proceeding

Session End:

1. Commit all work
2. Update todo file's Session Log (if working on a todo)
3. Execute Self-Improving Protocol (review + update CONVENTIONS.md / domain skills)
4. Move todo to appropriate directory (done/, blocked/, or leave in active/)
5. Push branch

Between Sessions

Each session starts fresh—the Session Startup Protocol re-orients Claude
CONVENTIONS.md and domain skills carry learned patterns forward
todos/ tracks progress — ls todos/done/ shows what's been completed, ls todos/active/ shows what's in flight
Todo session logs carry context from previous sessions
The /plan skill can help re-orient for complex in-progress work

Compound Engineering

The term and core concept of "compound engineering" come from Kieran Klaassen at Every Inc. My implementation is my own, but it builds on their thinking.

Philosophy

Every debugging session is a learning opportunity. The goal is to make the codebase—and its documentation—smarter over time. When an agent (or human) solves a problem, that solution should benefit all future work.

This is not optional. The Self-Improving Protocol in CLAUDE.md ensures agents automatically execute this after every session. The /implement pipeline enforces it as Step 7. The /compound skill provides a discrete invocation point.

How It Works

Through the /compound skill or /implement Step 7, the system reviews recent changes and routes learnings to the right place:

Learning Type	Where It Goes	Example
Global pattern	`CONVENTIONS.md`	File naming convention, git commit format, error handling approach
Domain pattern	Relevant domain skill	API pagination pattern → `api-design/SKILL.md`
Architectural decision	`docs/DECISIONS.md`	"Switched from REST to tRPC for internal APIs"

Example: Capturing a Learning

Scenario: Agent discovers that directly calling the payment API without idempotency keys causes duplicate charges on retry.

Action: The /compound step identifies this as a domain-specific pattern and updates api-design/SKILL.md:

## Idempotency

### External API Calls
Always include an idempotency key when calling external payment or mutation APIs.

**Don't do this:**
```typescript
await paymentApi.charge({ amount, currency });
```

**Do this instead:**
```typescript
const idempotencyKey = `charge-${orderId}-${Date.now()}`;
await paymentApi.charge({ amount, currency }, { idempotencyKey });
```

**Why**: Network retries without idempotency keys can cause duplicate charges. The key ensures the API treats retries as the same request.

Previously (v4), this would have gone into CONVENTIONS.md alongside file naming and git conventions. Now it lives in the domain skill where it's most useful—loaded only when working on API code.

Quick Reference

Document Purposes

When you need to know...	Read this
What are we building?	PRODUCT.md
Why this tech stack?	BUILD-STRATEGY.md
What's left to build?	`ls todos/backlog/`
How do I implement? (global)	CONVENTIONS.md
How do I implement? (domain)	`.claude/skills/{domain}/SKILL.md`
How should agents work here?	CLAUDE.md
How do I run this project?	README.md
Why did we change approach?	DECISIONS.md
What should this look like?	DESIGN.md

Agent Quick Reference

Agent	Role	Pipeline	Opt-in
builder	Implements features	/implement Step 1
test-writer	Writes tests	/implement Step 2
code-reviewer	Reviews code (general)	/implement Step 3
doc-verifier	Audits docs vs. code	/implement Step 5
documentation-writer	Writes human docs	—	Manual
refactor-scout	Identifies tech debt	—	Manual
security-sentinel	Security review	—	`/review security`
data-integrity-guardian	Data layer review	—	`/review data`
architecture-strategist	Structural review	—	`/review architecture`
pattern-recognition-specialist	Pattern consistency	—	`/review patterns`

Skill Quick Reference

Skill	Purpose	When to Use
`/implement`	Full pipeline (build → test → review → verify → compound)	Standard feature work
`/plan`	Produce implementation plan (in conversation, no file)	Before complex features
`/work`	Build only (invoke builder agent)	Quick implementations
`/review [name]`	Code review (default or specialist)	After work, before merge
`/compound`	Update conventions and domain skills	After manual work

Workflow Loops

Full pipeline: /implement handles everything in one command.

Discrete workflow: /plan → /work → /review → /compound

Quick iteration: /work → manual review → /compound

Session Checklists

Pipeline Mode (/implement):

Identify todo to work on
Start Claude (standard or worktree)
Run /implement {NNN} {description}
Review the pipeline summary when complete
Push branch and create PR
Merge after approval

Manual Mode:

Starting:

Check todos/active/ for in-progress work
Start Claude in project dir (or worktree)
Have agent read context (per Session Startup Protocol)
Clarify any ambiguities before coding

Ending:

All changes committed with proper messages
Todo session log updated
Self-Improving Protocol executed
CONVENTIONS.md / domain skills updated if patterns emerged
Todo moved to appropriate directory
Branch pushed

Before merging:

Consider: /review for significant changes?
All tests passing
Merge and delete branch

After merging (if using worktrees):

Run worktree-cleanup from main repo

File Structure Summary

project-root/
├── .claude/
│   ├── agents/
│   │   ├── builder.md
│   │   ├── test-writer.md
│   │   ├── code-reviewer.md
│   │   ├── doc-verifier.md
│   │   ├── documentation-writer.md
│   │   ├── refactor-scout.md
│   │   ├── security-sentinel.md           # opt-in specialist
│   │   ├── data-integrity-guardian.md      # opt-in specialist
│   │   ├── architecture-strategist.md      # opt-in specialist
│   │   └── pattern-recognition-specialist.md  # opt-in specialist
│   ├── skills/
│   │   ├── implement/
│   │   │   └── SKILL.md                   # Full pipeline orchestrator
│   │   ├── plan/
│   │   │   └── SKILL.md                   # Discrete planning
│   │   ├── work/
│   │   │   └── SKILL.md                   # Discrete build
│   │   ├── review/
│   │   │   └── SKILL.md                   # Discrete review
│   │   ├── compound/
│   │   │   └── SKILL.md                   # Discrete compound engineering
│   │   ├── frontend-design/
│   │   │   └── SKILL.md                   # Domain skill
│   │   ├── database-patterns/
│   │   │   └── SKILL.md                   # Domain skill
│   │   ├── testing-patterns/
│   │   │   └── SKILL.md                   # Domain skill
│   │   └── api-design/
│   │       └── SKILL.md                   # Domain skill
│   └── settings.json                      # Quality gate hook
├── todos/
│   ├── backlog/                           # Not yet started
│   ├── active/                            # In progress
│   ├── done/                              # Completed
│   └── blocked/                           # Waiting on something
├── CLAUDE.md                              # Agent instructions
├── CONVENTIONS.md                         # Global patterns (living document)
├── README.md                              # Overview + setup
├── docs/
│   ├── PRODUCT.md                         # Product specification
│   ├── BUILD-STRATEGY.md                  # Technical approach
│   ├── DECISIONS.md                       # Decision log (optional)
│   ├── reviews/                           # Created by agents during pipeline
│   └── design/                            # Design documentation (optional)
└── src/
    └── ...

Troubleshooting

Agent not being invoked

Verify the file is in .claude/agents/ (project) or ~/.claude/agents/ (user-level)
Check that name uses only lowercase letters and hyphens
Check that description clearly describes when to use the agent
Try explicit invocation: "Use the builder subagent to..."
Run claude --debug to see if the agent is being matched

Quality gate blocking incorrectly

The Stop hook only checks for /implement usage—normal conversations and discrete commands are unaffected
If it blocks when all steps are complete, the prompt may need tuning for your workflow
Temporarily disable by removing the Stop hook from settings.json

Agent can't find files

Verify tools includes the necessary tools (Read, Grep, Glob, etc.)
Agents start in the project root—use paths relative to that

Infinite loop from Stop hook

Prompt-based hooks evaluate with an LLM, which should return allow once all phases are complete
If stuck, the stop_hook_active field in the hook input is true when Claude is already continuing from a previous Stop hook—the evaluating model should account for this
As a safety valve, Claude Code has built-in limits on consecutive hook-triggered continuations

Review docs piling up

docs/reviews/ accumulates review and verification reports over time
Periodically clean out old reviews, or add them to .gitignore if you don't want them in version control
These are operational artifacts, not permanent documentation

Skill not loading or matching

Verify the skill file is at .claude/skills/{name}/SKILL.md (exact path matters)
Check that name in the frontmatter matches the directory name
Try invoking explicitly: /skill-name
Check that the YAML frontmatter is valid (no tabs, proper --- delimiters)

Context7 not connecting

Verify MCP configuration in ~/.claude/mcp.json or .claude/mcp.json
Ensure npx is available in your PATH
Try running npx -y @context7/mcp@latest manually to check for errors
Context7 is optional—Claude falls back to its training data if unavailable

Todo file conflicts

If two sessions modify the same todo file, resolve like any git conflict
The Session Log section is append-only, so conflicts are usually easy to resolve
Avoid having two sessions work on the same todo simultaneously

Domain skill vs CONVENTIONS.md confusion

CONVENTIONS.md = global rules that apply everywhere (file structure, naming, git, error handling)
Domain skills = patterns specific to a domain (testing, API, database, frontend)
Rule of thumb: If the pattern applies regardless of what you're working on, it's a convention. If it only matters when working in a specific area, it's a domain skill.
When in doubt, start in CONVENTIONS.md. If the section grows large, extract it into a domain skill.

This playbook is itself a living document. Update it as your AI-native workflow evolves.

Table of Contents

Philosophy

Core Concepts

Agents vs Skills

Progressive Disclosure

The Artifact System

Overview

PRODUCT.md

BUILD-STRATEGY.md

CONVENTIONS.md

CLAUDE.md

A Note on Signal Phrases (aka "Canaries")

README.md

DECISIONS.md (Optional)

Design Documentation (Optional)

Agents

Philosophy

Core Agents

builder.md

test-writer.md

code-reviewer.md

doc-verifier.md

documentation-writer.md

refactor-scout.md

Specialized Review Agents

security-sentinel.md

data-integrity-guardian.md

architecture-strategist.md

pattern-recognition-specialist.md

Manual Agent Invocation

Skills

Skill System Overview

Workflow Skills

/implement — Full Pipeline

/plan — Discrete Planning

/work — Discrete Build

/review — Discrete Review

/compound — Discrete Compound Engineering

Domain Skills

frontend-design/SKILL.md

database-patterns/SKILL.md

testing-patterns/SKILL.md

api-design/SKILL.md

Task Management

Filesystem Todo System

Directory Structure

File Naming

Todo File Template

Status Transitions

Generating Todos

Complete Example

The Implementation Layer

Git Integration

Parallel Work with Worktrees

Context7 MCP Setup

settings.json Reference

Day-to-Day Workflow

Starting a New Project

Pipeline Mode (/implement)

Discrete Workflow Commands

Manual Mode

Between Sessions

Compound Engineering

Philosophy

How It Works

Example: Capturing a Learning

Quick Reference

Document Purposes

Agent Quick Reference

Skill Quick Reference

Workflow Loops

Session Checklists

File Structure Summary

Troubleshooting

Agent not being invoked

Quality gate blocking incorrectly

Agent can't find files

Infinite loop from Stop hook

Review docs piling up

Skill not loading or matching

`builder.md`

`test-writer.md`

`code-reviewer.md`

`doc-verifier.md`

`documentation-writer.md`

`refactor-scout.md`

`security-sentinel.md`

`data-integrity-guardian.md`

`architecture-strategist.md`

`pattern-recognition-specialist.md`

`/implement` — Full Pipeline

`/plan` — Discrete Planning

`/work` — Discrete Build

`/review` — Discrete Review

`/compound` — Discrete Compound Engineering

`frontend-design/SKILL.md`

`database-patterns/SKILL.md`

`testing-patterns/SKILL.md`

`api-design/SKILL.md`

Pipeline Mode (`/implement`)