Blueprint Development

/blueprint:development

Guide and reference for the Blueprint Development methodology that generates project-specific behavioral rules and workflow commands from PRDs (Product Requirements Documents).

When to Use This Skill

For detailed rule templates, command templates, and generation guidelines, see REFERENCE.md.

Context

• Blueprint initialized: !find docs/blueprint -maxdepth 1 -name 'manifest.json' -type f
• PRDs present: !find docs/prds -name "*.md" -type f
• Rules directory: !find .claude -maxdepth 1 -name 'rules' -type d
• Existing rules: !find .claude/rules -maxdepth 1 -name "*.md"
• Project type: !find . -maxdepth 1 \( -name 'package.json' -o -name 'pyproject.toml' -o -name 'Cargo.toml' -o -name 'go.mod' \) -type f -print -quit

Execution

Execute the complete Blueprint Development setup and rule generation workflow:

Step 1: Verify project readiness

Check context values above:

1. If Blueprint initialized = "NO" → Error: "Blueprint not initialized. Run /blueprint:init first" 2. If PRDs present = "0" → Error: "No PRDs found. Create at least one PRD in docs/prds/ before generating rules" 3. If Rules directory = "NO" → Create: mkdir -p .claude/rules

Step 2: Analyze PRDs and extract patterns

Read all PRD files in docs/prds/ and extract:

1. Architecture Patterns: Project structure, dependency injection, error handling, module boundaries, layering, code organization 2. Testing Strategies: TDD workflow, test types (unit, integration, e2e), mocking patterns, coverage requirements 3. Implementation Guides: Patterns for implementing feature types (APIs, UI, database, external services) 4. Quality Standards: Code review checklist, performance baselines, security requirements, style standards

See REFERENCE.md for specific extraction patterns for each category.

Step 3: Generate four behavioral rules in .claude/rules/

Create project-specific rules that guide Claude's behavior during development:

Three required core rules:

1. `architecture-patterns.md` - Project structure, design patterns, dependency management, error handling, integration patterns 2. `testing-strategies.md` - TDD workflow, test structure, test types, mocking patterns, coverage requirements 3. `quality-standards.md` - Code review checklist, performance baselines, security standards, style, documentation

One optional advanced rule (if applicable):

4. `implementation-guides.md` - Step-by-step patterns for implementing specific feature types from PRDs

For each rule file:

• Use templates from REFERENCE.md
• Extract content directly from PRDs
• Include code examples and specific references
• Document rationale for architectural choices
• Use imperative language ("Use...", "Follow...", "Ensure...")

See REFERENCE.md for detailed guidelines on creating effective rules.

Step 4: Generate workflow commands

Create project-specific workflow commands in .claude/skills/ or docs/blueprint/:

Six core commands:

1. `/blueprint:init` - Initialize Blueprint Development structure 2. `/blueprint:generate-rules` - Generate project rules from PRDs (main entry point) 3. `/blueprint:generate-commands` - Generate workflow commands based on project type 4. `/blueprint:work-order` - Create isolated work-order for subagent execution 5. `/project:continue` - Analyze state and resume development 6. `/project:test-loop` - Run automated TDD cycle

For each command:

• Determine project type and language
• Extract test runners, build commands, development workflows
• Customize command implementations using REFERENCE.md
• Verify with expected allowed-tools permissions

Step 5: Create mapping in manifest

Update docs/blueprint/manifest.json with:

{
  "generated": {
    "rules": [
      "architecture-patterns.md",
      "testing-strategies.md",
      "quality-standards.md",
      "implementation-guides.md"
    ],
    "commands": [
      "blueprint-init.md",
      "blueprint-generate-rules.md",
      "blueprint-generate-commands.md",
      "blueprint-work-order.md",
      "project-continue.md",
      "project-test-loop.md"
    ]
  },
  "source_prds": ["project-overview.md"],
  "last_generated": "ISO-8601-timestamp"
}

This enables regeneration without losing track of what was auto-generated vs. manually created.

Step 6: Test and validate

Verify rules and commands work correctly:

1. Test rules apply: Check that Claude follows architecture-patterns, testing-strategies, and quality-standards during development 2. Test commands execute: Run each command to verify it works as expected 3. Verify output quality: Check that generated rules match PRD requirements and include concrete examples 4. Refine as needed: Update rules and commands based on feedback and actual project development

Step 7: Report results and next steps

Create summary report:

• Rules generated: {count} in .claude/rules/
• Commands created: {count} (use /project:continue to start development)
• Manifest updated with tracking metadata
• Next steps:

1. Review generated rules for accuracy 2. Add project-specific additions or clarifications 3. Run /project:continue to begin Blueprint Development workflow 4. Use /blueprint:work-order to create isolated tasks for team members

Integration with Blueprint Development

This skill enables the core Blueprint Development workflow:

PRDs (requirements) - Rules (behavioral guidelines) - Commands (workflow automation) - Work-orders (isolated tasks)

By generating project-specific rules and commands from PRDs, Blueprint Development creates a self-documenting, AI-native development environment where behavioral guidelines, patterns, and quality standards are first-class citizens.

GitHub Work Order Integration

Work orders can be linked to GitHub issues for transparency and cooperative development. See REFERENCE.md for workflow modes (--no-publish, --from-issue N), label setup, completion workflow, and work order file format.

Agentic Optimizations

Examples

See .claude/docs/blueprint-development/ for complete workflow documentation and examples.

---

For detailed rule templates, command examples, extraction patterns, and project-specific customization, see REFERENCE.md.

blueprint-development REFERENCE

Reference material for rule generation, command creation, and detailed implementation guidance for Blueprint Development.

Extraction Patterns

Architecture Pattern Extraction

Extract from PRD "Technical Considerations" or "Architecture" sections:

• Project structure and module organization
• Dependency injection patterns
• Error handling approaches
• Module boundaries and layering conventions
• Code organization and file naming conventions
• Integration patterns for external services/databases

Testing Strategy Extraction

Extract from PRD "TDD Requirements" or "Success Criteria" sections:

• TDD workflow specification (RED → GREEN → REFACTOR)
• Test types to implement (unit, integration, e2e)
• Test structure and directory organization
• Mocking patterns and isolation strategies
• Coverage requirements and minimum percentages
• Test command and runners

Quality Standard Extraction

Extract from PRD "Success Criteria", "Code Review", or "Quality" sections:

• Code review checklist items
• Performance baselines and targets
• Security requirements (OWASP, validation, authentication)
• Style and formatting standards
• Documentation requirements
• Dependency management policies

Implementation Guide Extraction

Extract from PRD "Functional Requirements" and "Technical" sections:

• API endpoint design patterns
• UI component architecture (if applicable)
• Database operation patterns
• External service integration patterns
• Data flow and state management patterns

Rule Templates

Architecture Patterns Rule Template

# Architecture Patterns

> Architecture patterns and code organization for [project name]. Defines how code is structured, organized, and modularized in this project.

## Project Structure

[Describe directory organization, module boundaries, layering. Include file tree example.]

## Design Patterns

[Document architectural patterns used: MVC, layered, hexagonal, etc. Include code examples.]

## Dependency Management

[How dependencies are injected, managed, and organized. Show injection pattern examples.]

## Error Handling

[Centralized error handling, error types, error propagation. Show error handling pattern examples.]

## Code Organization

[File naming conventions, module boundaries, separation of concerns. Show example directory structure.]

## Integration Patterns

[How external services, databases, APIs are integrated. Include integration examples.]

Testing Strategies Rule Template

# Testing Strategies

> TDD workflow, testing patterns, and coverage requirements for [project name]. Enforces test-first development and defines testing standards.

## TDD Workflow

Follow strict RED → GREEN → REFACTOR:
1. Write failing test describing desired behavior
2. Run test suite to confirm failure
3. Write minimal implementation to pass
4. Run test suite to confirm success
5. Refactor while keeping tests green

## Test Structure

[Directory organization, naming conventions, test types.]

## Test Types

### Unit Tests
[What to unit test, mocking patterns, isolation strategies. Include example test.]

### Integration Tests
[What to integration test, test database setup, external service handling. Include example test.]

### End-to-End Tests
[User flows to test, test environment setup, data seeding. Include example test if applicable.]

## Mocking Patterns

[When to mock, what to mock, mocking libraries and conventions. Include mocking examples.]

## Coverage Requirements

[Minimum coverage percentages, critical path requirements, edge case coverage.]

## Test Commands

[How to run tests, watch mode, coverage reports, debugging tests.]

**Project test commands:**
- Run all tests: [command]
- Watch mode: [command]
- Coverage report: [command]
- Debug specific test: [command]

Quality Standards Rule Template

# Quality Standards

> Code review criteria, performance baselines, security standards, and quality gates for [project name]. Enforces project quality requirements.

## Code Review Checklist

- [ ] All functions have tests (unit and/or integration)
- [ ] Input validation on all external inputs
- [ ] Error handling doesn't leak sensitive information
- [ ] No hardcoded credentials or secrets
- [ ] [Project-specific checklist items]

## Performance Baselines

[Specific performance targets from PRD]
- [Metric 1]: [Target]
- [Metric 2]: [Target]

## Security Standards

[Security requirements from PRD]
- [Security requirement 1]
- [Security requirement 2]

## Code Style

[Formatting, naming conventions, documentation standards. Include examples.]

## Documentation Requirements

[When and what to document.]

## Dependency Management

[Versioning, security updates, license compliance.]

Implementation Guides Rule Template

# Implementation Guides

> Step-by-step guides for implementing specific feature types in [project name]. Provides patterns for APIs, UI, data access, and integrations.

## API Endpoint Implementation

### Step 1: Write Integration Test
[Template for API test - write test first]

### Step 2: Create Route
[Route definition pattern for your framework]

### Step 3: Implement Controller
[Controller pattern with error handling and validation]

### Step 4: Implement Service Logic
[Service layer pattern with business logic]

### Step 5: Add Data Access
[Repository/data access pattern]

## [Feature Type 2] Implementation

[Step-by-step pattern specific to project]

## Database Operations

[Pattern for database queries, transactions, migrations]

## External Service Integration

[Pattern for integrating with third-party APIs/services]

## [Additional Patterns]

[Any other common implementation patterns in the project]

Command Templates

Blueprint Init Command

---
description: "Initialize Blueprint Development in this project"
allowed-tools: Bash, Write
---

Initialize Blueprint Development structure:

1. Create `docs/blueprint/` directory
2. Create `docs/prds/` for requirements
3. Create `docs/adrs/` for architecture decisions
4. Create `docs/prps/` for proposed work
5. Create `docs/blueprint/manifest.json` with initial structure
6. Add `docs/blueprint/work-orders/` directory (for task tracking)
7. Add `docs/blueprint/work-orders/completed/` directory

Report:
- Directories created
- Next steps: Write PRDs, then run `/blueprint:generate-rules`

Generate Rules Command

---
description: "Generate project-specific behavioral rules from PRDs in docs/prds/"
allowed-tools: Read, Write, Glob
---

Generate project-specific rules:

1. Read all PRD files in `docs/prds/`
2. Analyze PRDs to extract:
   - Architecture patterns and decisions
   - Testing strategies and requirements
   - Implementation guides and patterns
   - Quality standards and baselines
3. Generate four behavioral rules in `.claude/rules/`:
   - `architecture-patterns.md`
   - `testing-strategies.md`
   - `implementation-guides.md`
   - `quality-standards.md`
4. Update manifest tracking in `docs/blueprint/manifest.json`

Report:
- Rules generated
- Key patterns extracted
- Next steps: Review rules, run `/project:continue` to start development

Generate Commands Command

---
description: "Generate workflow commands based on project structure and PRDs"
allowed-tools: Read, Write, Bash, Glob
---

Generate workflow commands:

1. Analyze project structure (package.json, Makefile, etc.)
2. Detect test runner and commands
3. Detect build and development commands
4. Generate workflow commands:
   - `/project:continue` - Resume development
   - `/project:test-loop` - Run TDD cycle
   - [Project-specific commands based on stack]

Report:
- Commands generated
- Detected commands and tools
- Next steps: Review rules, then use `/project:continue` to start work

Work Order Command

---
description: "Create work-order with minimal context for isolated subagent execution"
args: "[--no-publish] [--from-issue N]"
allowed-tools: Read, Write, Glob, Bash
---

Generate work-order:

1. Analyze current project state:
   - Read feature-tracker.json if exists
   - Check git status
   - Read relevant PRDs
2. Identify next logical work unit
3. Determine minimal required context:
   - Only files that need modification
   - Only relevant code excerpts
   - Only relevant PRD sections
4. Generate work-order document:
   - Sequential number (find highest + 1)
   - Clear objective
   - Minimal context
   - TDD requirements
   - Implementation steps
   - Success criteria
5. Save to `docs/blueprint/work-orders/NNN-task-name.md`
6. Create GitHub issue (unless --no-publish):
   - Title: "Work-Order NNN: [Task Name]"
   - Label: `work-order`
   - Body: Summary with link to local file
7. Update work-order with issue number

Report:
- Work-order created
- Work-order number and objective
- GitHub issue number (if created)

Continue Development Command

---
description: "Analyze project state and continue development where left off"
allowed-tools: Read, Bash, Grep, Glob, Edit, Write
---

Continue project development:

1. Check current state:
   - Run `git status` (branch, uncommitted changes)
   - Run `git log -5 --oneline` (recent commits)
2. Read context:
   - All PRDs in `docs/prds/`
   - `feature-tracker.json` (current phase, tasks, progress)
   - Recent work-orders (completed and pending)
3. Identify next task:
   - Based on PRD requirements
   - Based on feature tracker progress
   - Based on git status
4. Begin work following TDD:
   - Apply project-specific rules
   - Follow RED → GREEN → REFACTOR workflow
   - Commit incrementally

Report before starting:
- Current project status summary
- Next task identified
- Approach and plan

Test Loop Command

---
description: "Run test → fix → refactor loop with TDD workflow"
allowed-tools: Read, Edit, Bash
---

Run TDD cycle:

1. Run test suite: [project-specific test command]
2. If tests fail:
   - Analyze failure output
   - Identify root cause
   - Make minimal fix to pass test
   - Re-run tests to confirm
3. If tests pass:
   - Check for refactoring opportunities
   - Refactor while keeping tests green
   - Re-run tests to confirm still passing
4. Repeat until:
   - All tests pass
   - No obvious refactoring needed
   - User intervention required

Report:
- Test results summary
- Fixes applied
- Refactorings performed
- Current status (all pass / needs work / blocked)

Rule Generation Guidelines

Be Specific and Actionable

Use precise, actionable guidance with concrete references:

Good: "Use constructor injection for services, following the pattern in services/authService.js:15-20"

Good: "All API endpoints must have integration tests with valid input, invalid input, and authorization test cases"

Include Code Examples

Every pattern should include a code example showing:

• What the pattern looks like in practice
• File location reference
• Line number reference (if applicable)

Document Rationale

For architecture and technical decisions, include:

• Why this pattern was chosen
• What alternatives were considered
• What trade-offs were made
• When to deviate from the pattern

Use Imperative Language

Rules should be behavioral guidelines that Claude follows:

• Use imperative language: "Use...", "Follow...", "Ensure..."
• Be specific about when the rule applies
• Include examples of correct behavior

Keep Rules Focused

Each rule file should have a single concern:

• Architecture patterns: Structure and organization
• Testing strategies: How to test
• Implementation guides: How to implement features
• Quality standards: What defines quality

Command Generation Guidelines

Make Commands Autonomous

Commands should:

• Run without user input (except explicit prompts)
• Read necessary context automatically
• Report clearly what was done
• Suggest next steps

Provide Clear Output

Commands should report: 1. What was analyzed 2. What was done 3. What the results are 4. What to do next

Handle Errors Gracefully

Commands should detect common issues:

• Missing files or directories
• No PRDs found
• Invalid project structure
• Test command not found

Report errors clearly and suggest fixes.

Manifest Structure

{
  "format_version": "3.0.0",
  "updated_at": "ISO-8601-timestamp",
  "structure": {
    "has_prds": true,
    "has_adrs": true,
    "has_prps": true
  },
  "generated": {
    "rules": [
      "architecture-patterns.md",
      "testing-strategies.md",
      "quality-standards.md",
      "implementation-guides.md"
    ],
    "commands": [
      "blueprint-init.md",
      "blueprint-generate-rules.md",
      "blueprint-generate-commands.md",
      "blueprint-work-order.md",
      "project-continue.md",
      "project-test-loop.md"
    ]
  },
  "source_prds": ["project-overview.md"],
  "last_generated": "ISO-8601-timestamp"
}

GitHub Work Order Integration

Work orders can be linked to GitHub issues for transparency and cooperative development.

Why GitHub Integration?

Workflow Modes

Default (GitHub-first):

/blueprint:work-order
# Creates local markdown + GitHub issue
# Issue has `work-order` label
# Work-order links to issue number

Local-only (offline/private):

/blueprint:work-order --no-publish
# Creates local markdown only
# Can publish later manually

From existing issue:

/blueprint:work-order --from-issue 123
# Fetches issue #123
# Creates local work-order with context
# Updates issue with work-order link

Label Setup

Create the work-order label in repositories using this methodology:

gh label create work-order --description "AI-assisted work order" --color "0E8A16"

Completion Workflow

1. Execute work-order following TDD workflow 2. Create PR with Fixes #N in title/body (where N = issue number) 3. Merge PR - Issue auto-closes 4. Move work-order to completed/ directory

Work Order File Format

# Work-Order 003: [Task Name]

**GitHub Issue**: #42
**Status**: pending | in-progress | completed

## Objective
[One sentence]

## Context
[Minimal context for isolated execution]

## TDD Requirements
[Specific tests]

## Success Criteria
[Checkboxes]

When to Use Each Mode

Testing Generated Rules and Commands

1. Verify Rules Are Applied

Test that Claude applies rules in relevant contexts:

• When discussing architecture, architecture-patterns rule should guide behavior
• When writing tests, testing-strategies rule should guide behavior
• When implementing features, implementation-guides rule should guide behavior
• When reviewing code, quality-standards rule should guide behavior

2. Verify Commands Work

Test each command:

/blueprint:init              # Should create directory structure
/blueprint:generate-rules    # Should create four rules in .claude/rules/
/blueprint:generate-commands # Should create workflow commands
/project:continue            # Should analyze state and resume work
/blueprint:work-order        # Should create work-order document
/project:test-loop           # Should run tests and report

3. Verify Rules Guide Correctly

Manually check that:

• Architecture patterns match PRD technical decisions
• Testing strategies match PRD TDD requirements
• Implementation guides match PRD API/feature designs
• Quality standards match PRD success criteria

4. Refine as Needed

During initial project development:

• Rules may need refinement as patterns emerge
• Commands may need adjustment based on actual workflow
• Update rules and commands iteratively

Architecture Patterns

Project Structure

[PROJECT_ROOT]/
├── [DIRECTORY_1]/           # [Purpose]
├── [DIRECTORY_2]/           # [Purpose]
├── [DIRECTORY_3]/           # [Purpose]
└── [DIRECTORY_4]/           # [Purpose]

Organization Principles:

• [Principle 1]: [Description]
• [Principle 2]: [Description]
• [Principle 3]: [Description]

Architectural Style

Pattern: [Layered / Hexagonal / Clean Architecture / MVC / MVVM / etc.]

Rationale: [Why this architectural style was chosen]

Layers/Components: 1. [Layer/Component 1]: [Responsibility]

• Location: [directory]/
• Purpose: [What this layer does]
• Dependencies: [What it can depend on]

2. [Layer/Component 2]: [Responsibility]

• Location: [directory]/
• Purpose: [What this layer does]
• Dependencies: [What it can depend on]

3. [Layer/Component 3]: [Responsibility]

• Location: [directory]/
• Purpose: [What this layer does]
• Dependencies: [What it can depend on]

Dependency Rules:

• [Rule 1: e.g., "Services can depend on repositories but not on controllers"]
• [Rule 2: e.g., "Domain models have no external dependencies"]
• [Rule 3: e.g., "Cross-cutting concerns (logging, auth) in middleware"]

Design Patterns

[Pattern Name 1]

When to use: [Scenario]

Implementation: ```[language] // Example code showing the pattern [CODE_EXAMPLE]

**Location**: `[file_path]:[line_range]`

### [Pattern Name 2]

**When to use**: [Scenario]

**Implementation**:

// Example code showing the pattern [CODE_EXAMPLE]

**Location**: `[file_path]:[line_range]`

## Dependency Injection

**Approach**: [Constructor Injection / Property Injection / Service Locator / DI Container]

**Pattern**:

// Example showing dependency injection pattern [CODE_EXAMPLE]

**Guidelines**:
- [Guideline 1]
- [Guideline 2]
- [Guideline 3]

## Error Handling

**Strategy**: [Centralized error handling / Error boundaries / Result types / etc.]

**Error Types**:
- **[ErrorType1]**: [When to use, example]
- **[ErrorType2]**: [When to use, example]
- **[ErrorType3]**: [When to use, example]

**Error Handling Pattern**:

// Example showing error handling [CODE_EXAMPLE]

**Guidelines**:
- [Guideline 1: e.g., "Never swallow errors silently"]
- [Guideline 2: e.g., "Log errors with context before throwing"]
- [Guideline 3: e.g., "Don't expose internal errors to clients"]

## Code Organization

### File Naming

**Conventions**:
- [Type 1]: `[naming-pattern]` (e.g., Components: `UserProfile.jsx`)
- [Type 2]: `[naming-pattern]` (e.g., Services: `authService.js`)
- [Type 3]: `[naming-pattern]` (e.g., Tests: `authService.test.js`)

### Module Boundaries

**Guideline**: [How to define module boundaries]

**Example**:

[module_name]/ ├── [file_1].js ├── [file_2].js ├── [file_3].js └── index.js # Public API

**Rules**:
- [Rule 1: e.g., "Modules expose only index.js exports"]
- [Rule 2: e.g., "No cross-module imports except through index"]
- [Rule 3: e.g., "Each module has single responsibility"]

### Separation of Concerns

**Principles**:
- [Principle 1]
- [Principle 2]
- [Principle 3]

## Integration Patterns

### Database Integration

**Pattern**: [ORM / Query Builder / Raw SQL / Repository Pattern / etc.]

**Example**:

// Example showing database integration [CODE_EXAMPLE]

**Guidelines**:
- [Guideline 1]
- [Guideline 2]
- [Guideline 3]

### External API Integration

**Pattern**: [Adapter Pattern / Service Wrapper / etc.]

**Example**:

// Example showing external API integration [CODE_EXAMPLE]

**Guidelines**:
- [Guideline 1: e.g., "Wrap third-party clients in adapters"]
- [Guideline 2: e.g., "Mock external services in tests"]
- [Guideline 3: e.g., "Handle timeouts and retries"]

### Message Queue / Event System

**Pattern**: [Publisher-Subscriber / Event Bus / Message Broker / etc.]

**Example**:

// Example showing event/message handling [CODE_EXAMPLE]

**Guidelines**:
- [Guideline 1]
- [Guideline 2]
- [Guideline 3]

## Configuration Management

**Approach**: [Environment Variables / Config Files / Config Service / etc.]

**Location**: `[config_directory]/` or `[config_file]`

**Pattern**:

// Example showing configuration loading [CODE_EXAMPLE]

**Guidelines**:
- [Guideline 1: e.g., "Never commit secrets"]
- [Guideline 2: e.g., "Validate config on startup"]
- [Guideline 3: e.g., "Use environment-specific configs"]

## State Management

**Approach**: [Redux / Vuex / Context API / etc.]

**Pattern**:

// Example showing state management [CODE_EXAMPLE]

**Guidelines**:
- [Guideline 1]
- [Guideline 2]
- [Guideline 3]

## Concurrency / Async Patterns

**Approach**: [Promises / Async-Await / Callbacks / Observables / etc.]

**Pattern**:

// Example showing async pattern [CODE_EXAMPLE]

**Guidelines**:
- [Guideline 1: e.g., "Always handle promise rejections"]
- [Guideline 2: e.g., "Use async/await for sequential operations"]
- [Guideline 3: e.g., "Use Promise.all for parallel operations"]

## Naming Conventions

**General Rules**:
- [Rule 1: e.g., "Use camelCase for variables and functions"]
- [Rule 2: e.g., "Use PascalCase for classes and components"]
- [Rule 3: e.g., "Use UPPER_SNAKE_CASE for constants"]

**Specific Conventions**:
- **Variables**: [Pattern and examples]
- **Functions**: [Pattern and examples]
- **Classes**: [Pattern and examples]
- **Files**: [Pattern and examples]
- **Directories**: [Pattern and examples]

## Common Pitfalls

### Pitfall 1: [Description]

**Problem**: [What happens]

**Solution**: [How to avoid]

**Example**:

// Bad [BAD_CODE_EXAMPLE]

// Good [GOOD_CODE_EXAMPLE]

### Pitfall 2: [Description]

**Problem**: [What happens]

**Solution**: [How to avoid]

**Example**:

// Bad [BAD_CODE_EXAMPLE]

// Good [GOOD_CODE_EXAMPLE]

## When to Deviate

**Allowed deviations**:
- [Scenario 1]: [When and why it's okay to deviate]
- [Scenario 2]: [When and why it's okay to deviate]

**Process for deviation**:
1. [Step 1: e.g., "Document rationale in code comments"]
2. [Step 2: e.g., "Discuss in code review"]
3. [Step 3: e.g., "Update this skill if pattern becomes common"]

## References

- [Link to PRD technical decisions]
- [Link to external documentation]
- [Link to related skills]

---

**Note**: This skill is generated from PRDs. Update this file as architectural patterns evolve during development.

Implementation Guides

API Endpoint Implementation

Step-by-Step Pattern

Step 1: Write Integration Test (RED)

```[language] describe('[HTTP_METHOD] [endpoint_path]', () => { it('should [expected behavior] when [valid input]', async () => { const response = await request(app) .method .send([request_body]);

expect(response.status).toBe([expected_status]); expect(response.body).toMatchObject([expected_shape]); }); });

**Run**: `[test_command]`
**Expected**: **FAIL** (endpoint doesn't exist yet)

#### Step 2: Create Route (GREEN)

// [routes_file_path] router.[method]('[path]', [controller].[method]);

#### Step 3: Implement Controller (GREEN)

// [controllers_file_path] async [methodName](req, res, next) { try { const [input] = req.[body/params/query]; const [result] = await this.[service].method; res.status([status]).json([result]); } catch (error) { next(error); } }

#### Step 4: Implement Service Logic (GREEN)

// [services_file_path] async methodName { // Business logic implementation [implementation] return [result]; }

**Run**: `[test_command]`
**Expected**: **PASS**

#### Step 5: Refactor
- Extract magic numbers to constants
- Improve error handling
- Add input validation
- Optimize database queries

**Run**: `[test_command]`
**Expected**: **STILL PASS**

### Error Handling in APIs

// Pattern for API error handling [ERROR_HANDLING_EXAMPLE]

### Input Validation

// Pattern for input validation [VALIDATION_EXAMPLE]

## [Feature Type 2: e.g., UI Component Implementation]

### Step-by-Step Pattern

[SIMILAR STRUCTURE FOR OTHER FEATURE TYPES]

## Database Operations

### Creating Records

// Create pattern [CREATE_EXAMPLE]

### Reading Records

// Read pattern [READ_EXAMPLE]

### Updating Records

// Update pattern [UPDATE_EXAMPLE]

### Deleting Records

// Delete pattern [DELETE_EXAMPLE]

### Transactions

// Transaction pattern [TRANSACTION_EXAMPLE]

## External Service Integration

### Adapter Pattern

// Service adapter pattern [ADAPTER_EXAMPLE]

### Error Handling
- Timeout handling
- Retry logic
- Circuit breaker pattern
- Fallback strategies

## Background Jobs

[If applicable to project]

### Job Definition

// Job pattern [JOB_EXAMPLE]

### Scheduling

// Schedule pattern [SCHEDULE_EXAMPLE]

## Common Implementation Patterns

### Pattern 1: [Name]
**When to use**: [Scenario]
**Implementation**: [Code example]

### Pattern 2: [Name]
**When to use**: [Scenario]
**Implementation**: [Code example]

## References

- [Link to PRD implementation sections]
- [Link to architecture patterns skill]
- [Link to testing strategies skill]

Quality Standards

Code Review Checklist

Functionality

• [ ] Implementation matches requirements
• [ ] All edge cases handled
• [ ] Error handling appropriate
• [ ] No regressions introduced

Tests

• [ ] All new code has tests (unit and/or integration)
• [ ] Tests follow TDD workflow (written first)
• [ ] Tests cover happy path and error cases
• [ ] Test coverage meets threshold ([X]%)
• [ ] All tests pass

Code Quality

• [ ] Code is readable and maintainable
• [ ] Functions are small and focused
• [ ] No code duplication
• [ ] Appropriate abstractions used
• [ ] Follows project architecture patterns
• [ ] Naming is clear and consistent

Security

• [ ] No hardcoded credentials or secrets
• [ ] Input validation on all external inputs
• [ ] SQL queries use parameterized statements
• [ ] Error messages don't leak sensitive info
• [ ] Authentication/authorization checked where needed
• [ ] Dependencies up-to-date (no known vulnerabilities)

Performance

• [ ] No obvious performance issues
• [ ] Database queries optimized
• [ ] Appropriate caching where needed
• [ ] [Add project-specific performance criteria]

Documentation

• [ ] Complex logic has comments
• [ ] Public APIs documented
• [ ] README updated if needed
• [ ] [Add project-specific documentation requirements]

Performance Baselines

Response Time

• [Endpoint/Operation 1]: [Target, e.g., "p95 < 200ms"]
• [Endpoint/Operation 2]: [Target]
• [Endpoint/Operation 3]: [Target]

Throughput

• [Operation 1]: [Target, e.g., "1000 req/sec"]
• [Operation 2]: [Target]

Resource Usage

• Memory: [Target, e.g., "< 512MB per process"]
• CPU: [Target, e.g., "< 70% under normal load"]
• Database connections: [Target, e.g., "< 10 per process"]

Measuring Performance

# Performance test command
[performance_test_command]

# Profiling command
[profiling_command]

Security Standards

OWASP Top 10 Compliance

• [X] Injection: [How addressed]
• [X] Broken Authentication: [How addressed]
• [X] Sensitive Data Exposure: [How addressed]
• [X] XML External Entities (XXE): [How addressed]
• [X] Broken Access Control: [How addressed]
• [X] Security Misconfiguration: [How addressed]
• [X] Cross-Site Scripting (XSS): [How addressed]
• [X] Insecure Deserialization: [How addressed]
• [X] Using Components with Known Vulnerabilities: [How addressed]
• [X] Insufficient Logging & Monitoring: [How addressed]

Authentication & Authorization

• [Requirement 1: e.g., "All protected endpoints require valid JWT"]
• [Requirement 2: e.g., "Role-based access control enforced"]
• [Requirement 3: e.g., "Failed auth attempts logged"]

Data Protection

• [Requirement 1: e.g., "Passwords hashed with bcrypt (cost 12)"]
• [Requirement 2: e.g., "Sensitive data encrypted at rest"]
• [Requirement 3: e.g., "PII never logged"]

Input Validation

• [Requirement 1: e.g., "All API inputs validated with schemas"]
• [Requirement 2: e.g., "File uploads restricted by type/size"]
• [Requirement 3: e.g., "SQL queries use parameterized statements"]

Security Scanning

# Dependency vulnerability scan
[dependency_scan_command]

# Static analysis
[static_analysis_command]

# Secret scanning
[secret_scan_command]

Code Style

Formatting

Tool: [Prettier / Black / gofmt / etc.]

# Format code
[format_command]

# Check formatting
[format_check_command]

Linting

Tool: [ESLint / Ruff / Clippy / etc.]

# Lint code
[lint_command]

# Auto-fix
[lint_fix_command]

Naming Conventions

• Variables: [Convention]
• Functions: [Convention]
• Classes: [Convention]
• Files: [Convention]
• Constants: [Convention]

Documentation Requirements

Code Comments

When to add comments:

• [Scenario 1: e.g., "Complex algorithms"]
• [Scenario 2: e.g., "Non-obvious workarounds"]
• [Scenario 3: e.g., "Business logic rationale"]

When NOT to add comments:

• [Scenario 1: e.g., "Self-explanatory code"]
• [Scenario 2: e.g., "Redundant descriptions"]

API Documentation

Requirement: [What needs documentation]

Format: [JSDoc / docstrings / etc.]

Example: ```[language] /**

• [Function description]
• @param {[type]} [param] - [Description]
• @returns {[type]} [Description]
• @throws {[ErrorType]} [When thrown]

*/ [FUNCTION_EXAMPLE]

### README Requirements
**Must include**:
- [ ] Project description
- [ ] Setup instructions
- [ ] Running tests
- [ ] Development workflow
- [ ] Deployment instructions

## Dependency Management

### Versioning
- [Policy: e.g., "Pin exact versions in package.json"]
- [Policy: e.g., "Update dependencies monthly"]

### Security

Check for vulnerabilities

[security_check_command]

Update dependencies

[update_command]

### License Compliance
- [Policy: e.g., "Only MIT/Apache/BSD licenses allowed"]
- [Policy: e.g., "Review copyleft licenses before use"]

## Git Workflow

### Commit Messages
**Format**: [Conventional Commits / Other]

**Pattern**:

type: [subject]

[body]

[footer]

**Examples**:
- `feat(auth): add JWT token refresh`
- `fix(api): handle null user in validation`
- `refactor(db): extract query builder logic`

### Branch Naming
**Pattern**: [Pattern, e.g., "feature/feature-name", "fix/bug-description"]

### Pull Requests
**Requirements**:
- [ ] All tests pass
- [ ] Code review approved
- [ ] No merge conflicts
- [ ] [Add project-specific requirements]

**PR Template**: [Link to template or inline]

## Quality Gates

### Pre-Commit
**Checks**:
- [ ] Linting passes
- [ ] Formatting correct
- [ ] No secrets detected
- [ ] [Project-specific checks]

Run pre-commit hooks

[pre_commit_command]

### Pre-Push
**Checks**:
- [ ] All tests pass
- [ ] Coverage threshold met
- [ ] [Project-specific checks]

### CI/CD
**Checks**:
- [ ] Build succeeds
- [ ] All tests pass
- [ ] Security scan passes
- [ ] Performance tests pass
- [ ] [Project-specific checks]

## Monitoring & Observability

### Logging
**Requirements**:
- [Requirement 1: e.g., "Structured logging (JSON)"]
- [Requirement 2: e.g., "Log levels used appropriately"]
- [Requirement 3: e.g., "No PII in logs"]

### Metrics
**Required metrics**:
- [Metric 1: e.g., "Request rate"]
- [Metric 2: e.g., "Error rate"]
- [Metric 3: e.g., "Response time (p50, p95, p99)"]

### Alerts
**Required alerts**:
- [Alert 1: e.g., "Error rate > 5%"]
- [Alert 2: e.g., "Response time p95 > 500ms"]
- [Alert 3: e.g., "Database connection pool exhausted"]

## Common Quality Issues

### Issue 1: [Description]
**Problem**: [What happens]
**How to detect**: [Linter / Test / Review]
**How to fix**: [Solution]

### Issue 2: [Description]
**Problem**: [What happens]
**How to detect**: [Linter / Test / Review]
**How to fix**: [Solution]

## References

- [Link to PRD success criteria]
- [Link to PRD performance baselines]
- [Link to PRD security requirements]
- [Link to architecture patterns skill]
- [Link to testing strategies skill]

---

**Note**: This skill is generated from PRDs. Update this file as quality standards evolve during development.

Testing Strategies

TDD Workflow

Follow strict RED → GREEN → REFACTOR cycle:

RED - Write Failing Test

1. Write a test describing desired behavior 2. Run test suite: [test_command] 3. Confirm test FAILS (expected failure)

GREEN - Minimal Implementation

1. Write minimal code to pass the test 2. Run test suite: [test_command] 3. Confirm test PASSES

REFACTOR - Improve Code

1. Identify refactoring opportunities 2. Refactor while keeping tests green 3. Run test suite: [test_command] 4. Confirm tests STILL PASS

Never skip RED: If test passes immediately, the test is wrong or unnecessary.

Never skip REFACTOR: Technical debt accumulates if you skip refactoring.

Test Structure

[tests_directory]/
├── unit/               # Unit tests for individual functions/classes
│   ├── [module1]/
│   └── [module2]/
├── integration/        # Integration tests for component interactions
│   ├── [area1]/
│   └── [area2]/
└── e2e/               # End-to-end tests for user flows
    ├── [flow1]/
    └── [flow2]/

Naming Conventions:

• Unit tests: [filename].test.js or [filename].spec.js
• Integration tests: [feature].integration.test.js
• E2E tests: [flow].e2e.test.js

Test Types

Unit Tests

Purpose: Test individual functions, classes, or components in isolation

Location: [unit_test_directory]/

What to unit test:

• [Item 1: e.g., "Business logic in service layer"]
• [Item 2: e.g., "Pure functions and utilities"]
• [Item 3: e.g., "Data transformations"]
• [Item 4: e.g., "Validation logic"]

What NOT to unit test:

• [Item 1: e.g., "Framework code or libraries"]
• [Item 2: e.g., "Trivial getters/setters"]
• [Item 3: e.g., "Configuration files"]

Pattern: ```[language] describe('[Component/Function Name]', () => { describe('[Method/Behavior]', () => { it('should [expected behavior]', () => { // Arrange [setup_code]

// Act [execution_code]

// Assert [assertion_code] });

it('should [handle error case]', () => { // Test error handling }); }); });

**Example**:

[CONCRETE_UNIT_TEST_EXAMPLE]

### Integration Tests

**Purpose**: Test interactions between components, with real dependencies

**Location**: `[integration_test_directory]/`

**What to integration test**:
- [Item 1: e.g., "API endpoints with real database"]
- [Item 2: e.g., "Service interactions"]
- [Item 3: e.g., "Data access layer with database"]
- [Item 4: e.g., "Authentication/authorization flows"]

**Setup**:
- [Setup requirement 1: e.g., "Use test database / test containers"]
- [Setup requirement 2: e.g., "Seed test data before each test"]
- [Setup requirement 3: e.g., "Clean up after each test"]

**Pattern**:

describe('[Feature] Integration', () => { beforeAll(async () => { // Setup (e.g., connect to test database) });

beforeEach(async () => { // Reset state (e.g., clear database) });

afterAll(async () => { // Cleanup (e.g., disconnect from database) });

it('should [test end-to-end scenario]', async () => { // Test with real dependencies }); });

**Example**:

[CONCRETE_INTEGRATION_TEST_EXAMPLE]

### End-to-End Tests

**Purpose**: Test complete user flows from start to finish

**Location**: `[e2e_test_directory]/`

**What to E2E test**:
- [Flow 1: e.g., "User registration → login → access protected resource"]
- [Flow 2: e.g., "Product search → add to cart → checkout"]
- [Flow 3: e.g., "Create account → verify email → complete profile"]

**Setup**:
- [Setup requirement 1: e.g., "Run application in test environment"]
- [Setup requirement 2: e.g., "Use headless browser for UI tests"]
- [Setup requirement 3: e.g., "Reset test database before each test"]

**Pattern**:

describe('[User Flow]', () => { it('should [complete the flow successfully]', async () => { // Step 1: [User action] [step_1_code]

// Step 2: [User action] [step_2_code]

// Step 3: [User action] [step_3_code]

// Assert final state [assertion_code] }); });

**Example**:

[CONCRETE_E2E_TEST_EXAMPLE]

## Mocking Patterns

### When to Mock

**DO mock**:
- [Scenario 1: e.g., "External APIs in unit tests"]
- [Scenario 2: e.g., "Time-dependent functions (Date.now)"]
- [Scenario 3: e.g., "File system operations in unit tests"]
- [Scenario 4: e.g., "Expensive computations in unit tests"]

**DON'T mock**:
- [Scenario 1: e.g., "The system under test"]
- [Scenario 2: e.g., "Simple data structures"]
- [Scenario 3: e.g., "Internal dependencies in integration tests"]

### Mocking Library

**Tool**: [Jest / Sinon / Mock / etc.]

**Patterns**:

#### Mock External Service

// Mock pattern for external service [MOCK_EXAMPLE_1]

#### Mock Database

// Mock pattern for database [MOCK_EXAMPLE_2]

#### Spy on Function

// Spy pattern [SPY_EXAMPLE]

### Test Doubles

**Types**:
- **Stub**: Returns predefined values
- **Mock**: Verifies behavior (method calls, arguments)
- **Spy**: Records calls without changing behavior
- **Fake**: Working implementation for testing (e.g., in-memory database)

**Guidelines**:
- [Guideline 1: e.g., "Use stubs for simple value returns"]
- [Guideline 2: e.g., "Use mocks to verify interactions"]
- [Guideline 3: e.g., "Use fakes for complex dependencies"]

## Coverage Requirements

### Overall Coverage
- **Minimum**: [X]% overall test coverage
- **Target**: [Y]% overall test coverage

### Critical Path Coverage
- **Requirement**: [100]% coverage for [critical areas]
- **Critical areas**:
  - [Area 1: e.g., "Authentication and authorization"]
  - [Area 2: e.g., "Payment processing"]
  - [Area 3: e.g., "Data validation"]

### Edge Case Coverage
- **Requirement**: All error paths and edge cases tested
- **Examples**:
  - [Edge case 1: e.g., "Empty inputs"]
  - [Edge case 2: e.g., "Boundary values"]
  - [Edge case 3: e.g., "Concurrent access"]
  - [Edge case 4: e.g., "Network failures"]

### Measuring Coverage

Run tests with coverage

[coverage_command]

View coverage report

[coverage_report_command]

Coverage thresholds

[coverage_threshold_config]

**Coverage Tools**: [Istanbul / nyc / Coverage.py / etc.]

## Test Organization

### Test File Structure

// Recommended test structure describe('[Component/Module Name]', () => { // Setup beforeEach(() => { // Common setup });

// Happy path tests describe('when [normal condition]', () => { it('should [expected behavior]', () => { // Test implementation }); });

// Edge case tests describe('when [edge case condition]', () => { it('should [expected behavior]', () => { // Test implementation }); });

// Error case tests describe('when [error condition]', () => { it('should [expected error handling]', () => { // Test implementation }); }); });

### Test Data Management

**Approach**: [Fixtures / Factories / Builders / Seeds]

**Location**: `[test_data_directory]/`

**Pattern**:

// Test data pattern [TEST_DATA_EXAMPLE]

**Guidelines**:
- [Guideline 1: e.g., "Use factories for flexible test data"]
- [Guideline 2: e.g., "Use fixtures for complex scenarios"]
- [Guideline 3: e.g., "Keep test data minimal and focused"]

## Test Commands

### Run All Tests

[run_all_tests_command]

### Run Unit Tests Only

[run_unit_tests_command]

### Run Integration Tests Only

[run_integration_tests_command]

### Run E2E Tests Only

[run_e2e_tests_command]

### Run Specific Test File

[run_specific_test_command] [file_path]

### Watch Mode

[watch_mode_command]

### Debug Tests

[debug_tests_command]

## Performance Testing

**When required**: [Scenarios where performance tests are needed]

**Tools**: [Performance testing tools]

**Baselines**:
- [Metric 1]: [Target value]
- [Metric 2]: [Target value]

**Pattern**:

// Performance test pattern [PERFORMANCE_TEST_EXAMPLE]

## Test Maintenance

### When to Update Tests

**Update tests when**:
- [Scenario 1: e.g., "Requirements change"]
- [Scenario 2: e.g., "Refactoring changes behavior"]
- [Scenario 3: e.g., "New edge cases discovered"]

**DON'T update tests when**:
- [Scenario 1: e.g., "Just to make them pass (fix code instead)"]
- [Scenario 2: e.g., "Internal refactoring (behavior unchanged)"]

### Flaky Tests

**Definition**: Tests that intermittently fail without code changes

**Common causes**:
- [Cause 1: e.g., "Race conditions"]
- [Cause 2: e.g., "Time-dependent logic"]
- [Cause 3: e.g., "External dependencies"]
- [Cause 4: e.g., "Test data pollution"]

**Solutions**:
- [Solution 1: e.g., "Use deterministic mocks"]
- [Solution 2: e.g., "Reset state between tests"]
- [Solution 3: e.g., "Add proper test isolation"]

### Test Smells

**Signs of bad tests**:
- [Smell 1: e.g., "Tests that test implementation details"]
- [Smell 2: e.g., "Tests with unclear assertions"]
- [Smell 3: e.g., "Tests that depend on execution order"]
- [Smell 4: e.g., "Tests with no assertions"]

**How to fix**:
- [Fix 1]
- [Fix 2]
- [Fix 3]

## Testing Best Practices

### AAA Pattern
- **Arrange**: Set up test data and context
- **Act**: Execute the behavior being tested
- **Assert**: Verify the outcome

### One Assertion Per Test

**Preference**: [Single assertion vs multiple assertions]

**Rationale**: [Why this approach is chosen]

### Test Naming

**Convention**: [Pattern for test names]

**Examples**:
- `should [action] when [condition]`
- `should return [result] given [input]`
- `should throw [error] when [invalid state]`

### Test Independence

**Requirement**: Each test should be independent

**Guidelines**:
- [Guideline 1: e.g., "No shared mutable state"]
- [Guideline 2: e.g., "Tests can run in any order"]
- [Guideline 3: e.g., "Use beforeEach for setup"]

### Readability

**Priority**: Tests should be easy to understand

**Guidelines**:
- [Guideline 1: e.g., "Use descriptive variable names"]
- [Guideline 2: e.g., "Keep tests focused and short"]
- [Guideline 3: e.g., "Extract helpers for common patterns"]

## Common Pitfalls

### Pitfall 1: [Description]

**Problem**: [What happens]

**Solution**: [How to avoid]

**Example**:

// Bad [BAD_TEST_EXAMPLE]

// Good [GOOD_TEST_EXAMPLE]

### Pitfall 2: [Description]

**Problem**: [What happens]

**Solution**: [How to avoid]

**Example**:

// Bad [BAD_TEST_EXAMPLE]

// Good [GOOD_TEST_EXAMPLE]

## CI/CD Integration

### Running Tests in CI

**Configuration**: [CI config file location]

**Pattern**:

CI configuration excerpt

[CI_CONFIG_EXAMPLE]

**Requirements**:
- [Requirement 1: e.g., "All tests must pass before merge"]
- [Requirement 2: e.g., "Coverage threshold enforced"]
- [Requirement 3: e.g., "E2E tests run on staging"]

## References

- [Link to PRD TDD requirements]
- [Link to testing framework documentation]
- [Link to related skills]

---

**Note**: This skill is generated from PRDs. Update this file as testing patterns evolve during development.