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:

   Register the rules through the shared helper rather than hand-writing the jq — /blueprint:init Step 8a calls the same script, so the two producers of $RULES_DIR cannot drift apart on the record shape or on how the hash is computed (issue #2331):

   bash "${CLAUDE_SKILL_DIR}/../../scripts/register-generated-rules.sh" \
     --source "docs/prds/*" \
     --source-hash "$PRD_AGGREGATE_SHA256" \
     --plugin-version "3.4.0" \
     architecture-patterns.md testing-strategies.md implementation-guides.md quality-standards.md
   

   --source-hash is the bare hex sha256 over the aggregated PRD content; it is what Step 2 (and /blueprint:sync Step 2d) compares against to decide whether a rule has gone stale.

   Key form — keys are filenames relative to $RULES_DIR, including the .md extension, so the registry stays stable when generated_rules_path changes (the path itself lives in structure.generated_rules_path, exactly once). Consumers resolve a rule as "$RULES_DIR/$key" and must not append .md.

   The resulting generated.rules object map (per blueprint-plugin/schemas/manifest.schema.json):

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

   Hash form — content_hash and source_hash are bare lowercase hex sha256 digests with no sha256: prefix. Both readers (/blueprint:sync Step 2b and blueprint-plugin/hooks/blueprint-drift-probe.sh) compare the raw output of sha256sum / shasum -a 256 against these fields, so a prefixed value can never match and every rule would read as perpetually modified.

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