Blueprint Generate Rules

Generate project-specific rules from Product Requirements Documents.

When to Use This Skill

Rules are generated to the directory configured in structure.generated_rules_path (defaults to .claude/rules/ when the field is absent). Rules with paths frontmatter are loaded conditionally when working on matching files.

Steps

Prerequisites:

• docs/prds/ directory exists
• At least one PRD file in docs/prds/

0. Resolve the output path:

Read structure.generated_rules_path from docs/blueprint/manifest.json (default .claude/rules/):

   RULES_DIR=$(jq -r '.structure.generated_rules_path // ".claude/rules/"' docs/blueprint/manifest.json)
   mkdir -p "$RULES_DIR"

Use $RULES_DIR for all subsequent reads/writes. This isolates blueprint-managed rules from any hand-written files in the parent .claude/rules/ directory (issue #1043).

1. Find and read all PRDs:

• Use Glob to find all .md files in docs/prds/
• Read each PRD file
• If no PRDs found, report error and suggest writing PRDs first

2. Check for existing generated rules:

   ls "$RULES_DIR" 2>/dev/null

• Scope conflict checks to files under $RULES_DIR only — never to the parent .claude/rules/. Hand-written files outside $RULES_DIR are invisible to this check.
• If rules exist, check manifest for content hashes
• Compare current content hash vs stored hash
• If modified, offer options: overwrite, skip, or backup

3. Analyze PRDs and extract (aggregated from all PRDs):

Architecture Patterns:

• Project structure and organization
• Architectural style (MVC, layered, hexagonal, etc.)
• Design patterns
• Dependency injection approach
• Error handling strategy
• Code organization conventions
• Integration patterns

Testing Strategies:

• TDD workflow requirements
• Test types (unit, integration, e2e)
• Mocking patterns
• Coverage requirements
• Test structure and organization
• Test commands

Implementation Guides:

• How to implement APIs/endpoints
• How to implement UI components (if applicable)
• Database operation patterns
• External service integration patterns
• Background job patterns (if applicable)

Quality Standards:

• Code review checklist
• Performance baselines
• Security requirements (OWASP, validation, auth)
• Code style and formatting
• Documentation requirements
• Dependency management

4. Generate four aggregated domain rules:

Create in $RULES_DIR (the configured structure.generated_rules_path):

`architecture-patterns.md`:

• Aggregated patterns from all PRDs
• Fill in project-specific patterns extracted from PRDs
• Include code examples where possible
• Reference specific files/directories

`testing-strategies.md`:

• Aggregated testing requirements from all PRDs
• Fill in TDD requirements from PRDs
• Include coverage requirements
• Include test commands for the project
• Add paths frontmatter if tests live in specific directories:

     ---
     paths:
       - "tests/**/*"
       - "**/*.{test,spec}.*"
     ---

`implementation-guides.md`:

• Aggregated implementation patterns from all PRDs
• Fill in step-by-step patterns for feature types
• Include code examples
• Scope to source paths if applicable:

     ---
     paths:
       - "src/**/*"
       - "lib/**/*"
     ---

`quality-standards.md`:

• Aggregated quality requirements from all PRDs
• Fill in performance baselines from PRDs
• Fill in security requirements from PRDs
• Create project-specific checklist

Path-scoping guidance: Add paths frontmatter when a rule only applies to specific file types or directories. This reduces context noise — Claude only loads the rule when working on matching files. Use brace expansion for concise patterns: *.{ts,tsx}, src/{api,routes}/**/*.

5. Update manifest with generation tracking:

Store filenames relative to $RULES_DIR so the registry remains stable when generated_rules_path changes. The path itself lives in structure.generated_rules_path; the keys here are bare filenames (without directory).

   {
     "generated": {
       "rules": {
         "architecture-patterns.md": {
           "source": "docs/prds/*",
           "source_hash": "sha256:...",
           "generated_at": "[ISO timestamp]",
           "plugin_version": "3.0.0",
           "content_hash": "sha256:...",
           "status": "current"
         },
         "testing-strategies.md": { ... },
         "implementation-guides.md": { ... },
         "quality-standards.md": { ... }
       }
     }
   }

6. Update task registry:

Update the task registry entry in docs/blueprint/manifest.json:

   jq --arg now "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
     --argjson processed "${PRDS_READ:-0}" \
     --argjson created "${RULES_GENERATED:-0}" \
     '.task_registry["generate-rules"].last_completed_at = $now |
      .task_registry["generate-rules"].last_result = "success" |
      .task_registry["generate-rules"].context.source_prd_hashes = ($source_prd_hashes // {}) |
      .task_registry["generate-rules"].stats.runs_total = ((.task_registry["generate-rules"].stats.runs_total // 0) + 1) |
      .task_registry["generate-rules"].stats.items_processed = $processed |
      .task_registry["generate-rules"].stats.items_created = $created' \
     docs/blueprint/manifest.json > tmp.json && mv tmp.json docs/blueprint/manifest.json

For source_prd_hashes, compute sha256sum of each PRD file and pass as a JSON object via --argjson.

7. Report:

   Rules generated from PRDs!

   Created in $RULES_DIR (configured via structure.generated_rules_path):
   - architecture-patterns.md
   - testing-strategies.md
   - implementation-guides.md
   - quality-standards.md

   PRDs analyzed:
   - docs/prds/[List PRD files]

   Key patterns extracted:
   - Architecture: [Brief summary]
   - Testing: [Brief summary]
   - Implementation: [Brief summary]
   - Quality: [Brief summary]

   Rules are immediately available - Claude auto-discovers them based on context!

8. Prompt for next action (use AskUserQuestion):

   question: "Rules generated. What would you like to do next?"
   options:
     - label: "Generate workflow commands (Recommended)"
       description: "Create /project:continue and /project:test-loop commands"
     - label: "Update CLAUDE.md"
       description: "Regenerate project overview document with new rules"
     - label: "Review generated rules"
       description: "I'll examine and refine the rules manually"
     - label: "I'm done for now"
       description: "Exit - rules are already available"

Based on selection:

• "Generate workflow commands" -> Run /blueprint:generate-commands
• "Update CLAUDE.md" -> Run /blueprint:claude-md
• "Review generated rules" -> Show rule file locations and exit
• "I'm done for now" -> Exit

Important:

• Rules should be markdown files with clear headings
• Keep rule content specific and focused
• Include code examples to make patterns concrete
• Reference PRD sections for traceability
• Rules should be actionable, not just documentation

Error Handling:

• If no PRDs found -> Guide user to derive plans first (/blueprint:derive-plans)
• If PRDs incomplete -> Generate rules with TODO markers for missing sections
• If rules already exist and modified -> Offer to backup before overwriting