Create Rule

Create a new rule file with _rules suffix and automatically create symlink in .claude/rules/.

SUBMODULE MODE: If a submodule name is provided (e.g., /create-rule foundation), create the rule in that submodule. If no submodule name is provided, create in the main repository's docs/ directory.

Command

create-rule [submodule_name]

Inputs

• submodule_name (optional string): Submodule name to create rule in (e.g., "foundation"). If omitted, creates rule in main repository's docs/ directory.

Workflow Overview

If submodule name provided:

1. Verify submodule exists
2. Determine submodule rule location
3. Prompt user for rule details
4. Create rule file in submodule
5. Run setup script to create symlink (if applicable)
6. Exit after submodule rule creation

If no submodule name provided (default - repo mode):

1. Prompt user for rule details
2. Create rule file in docs/{location}/{name}_rules.md
3. Include standard Agent Instructions template
4. Run setup script to create symlink
5. Verify symlink created

Tasks

Step 1: Determine Scope

If submodule name provided:

1. Verify submodule exists:

   if ! git submodule status <submodule_name> >/dev/null 2>&1; then
     echo "❌ Submodule not found: <submodule_name>"
     exit 1
   fi

2. Determine submodule rule location:
   • For foundation submodule: foundation/agent_instructions/cursor_rules/
   • For other submodules: Check for standard rule directories or prompt user
3. Set context for submodule rule creation

If no submodule name provided:

• Set context for main repository rule creation in docs/ directory

Step 2: Prompt User for Rule Details

Repository mode prompts:

1. Rule file name (without _rules.md suffix)
   • Example: "entity_resolution" will become "entity_resolution_rules.md"
   • Validate: alphanumeric with underscores only
2. Location in docs/ directory
   • Options: conventions, foundation, subsystems, architecture, developer, etc.
   • Validate: directory must exist or ask to create
3. Rule purpose and scope
   • Brief description of what this rule ensures
   • What triggers loading this rule
4. Key constraints/MUST/SHOULD rules
   • List of main rules this document will enforce
   • Use RFC 2119 language (MUST, SHOULD, MUST NOT)

Submodule mode prompts:

1. Rule file name (without _rules.mdc suffix for foundation submodule, or without .mdc for foundation submodule - MUST use .mdc extension for foundation rules)
2. Rule purpose and scope
3. Key constraints/MUST/SHOULD rules

Step 3: Create Rule File

Repository mode:

Create file at docs/{location}/{name}_rules.md with content:

# {Rule Title}

**Reference:** `docs/{reference_doc}.md` — Related documentation (if applicable)

{Brief description of what this rule ensures}

## Purpose

{Expanded purpose from user input}

## Trigger Patterns

When any of the following occur:

- {Trigger pattern 1}
- {Trigger pattern 2}
- {Trigger pattern 3}

## Agent Actions

### Step 1: {Action Title}

{Description of what agent should do}

### Step 2: {Action Title}

{Description of what agent should do}

## Constraints

### MUST

1. {MUST constraint 1}
2. {MUST constraint 2}

### SHOULD

1. {SHOULD constraint 1}
2. {SHOULD constraint 2}

### MUST NOT

1. {MUST NOT constraint 1}
2. {MUST NOT constraint 2}

## Examples

### Example 1: {Example Title}

{Example description and code/steps}

---

## Agent Instructions

### When to Load This Document

Load this document when:

- {Trigger condition 1}
- {Trigger condition 2}

### Required Co-Loaded Documents

- {Required document 1}
- {Required document 2}

### Constraints Agents Must Enforce

1. {Constraint to enforce 1}
2. {Constraint to enforce 2}

### Forbidden Patterns

- {Anti-pattern 1}
- {Anti-pattern 2}

### Validation Checklist

- [ ] {Validation item 1}
- [ ] {Validation item 2}

Submodule mode:

For foundation submodule, create file following foundation cursor-rules pattern (simpler structure without Agent Instructions section since these are loaded automatically).

Step 4: Run Setup Script

Repository mode:

1. Run foundation setup script:

   ./foundation/scripts/setup-cursor-rules.sh

2. Verify symlink created in .claude/rules/:
   • Expected symlink name: {location}_{name}_rules.md
   • Example: docs/conventions/entity_resolution_rules.md → .claude/rules/conventions_entity_resolution_rules.md
3. Output success message:

   ✅ Rule created successfully!
   
   File: docs/{location}/{name}_rules.md
   Symlink: .claude/rules/{location}_{name}_rules.md
   
   The rule is now available to all Cursor agents in this repository.
   
   Next steps:
   1. Review the generated rule file and fill in any remaining details
   2. Test the rule by triggering its conditions
   3. Update related documentation to reference this rule if needed

Submodule mode:

1. If submodule is foundation, run setup script from main repository:

   ./foundation/scripts/setup-cursor-rules.sh

2. Verify symlink created (for foundation rules, they're prefixed with foundation-)
3. Output success message:

   ✅ Rule created in submodule successfully!
   
   File: {submodule}/{rule_path}/{name}{suffix}.mdc (for foundation submodule, use .mdc extension)
   Symlink: .claude/rules/{prefix}{name}.mdc (if applicable)
   
   The rule is now available to all repositories using this submodule.

Error Handling

• If submodule not found: Exit with error message
• If location directory doesn't exist in repo mode: Offer to create it or exit
• If file already exists: Warn and ask to overwrite or exit
• If setup script fails: Report error but keep the created file

Configuration

Optional configuration in foundation-config.yaml:

agent_instructions:
  rules:
    default_location: "docs/conventions"  # Default location for new rules
    template_path: null  # Custom template path (optional)
    auto_run_setup: true  # Automatically run setup script after creation

Examples

Example 1: Create Repository Rule

/create-rule

Prompts:

• Rule file name: entity_resolution
• Location: subsystems
• Purpose: "Ensure consistent entity resolution patterns across codebase"
• Key constraints: "MUST use deterministic merging, MUST NOT introduce randomness"

Creates:

• docs/subsystems/entity_resolution_rules.md
• .claude/rules/subsystems_entity_resolution_rules.md (symlink)

Example 2: Create Foundation Submodule Rule

/create-rule foundation

Prompts:

• Rule file name: testing_patterns
• Purpose: "Enforce consistent testing patterns"
• Key constraints: "MUST include unit tests, SHOULD use fixtures"

Creates:

• foundation/agent_instructions/cursor_rules/testing_patterns.mdc
• .claude/rules/foundation_testing_patterns.mdc (symlink)

Required Documents

Load before starting:

• foundation/scripts/setup-cursor-rules.sh (setup script)
• docs/conventions/documentation_standards_rules.md (if creating repo rule)
• foundation-config.yaml (configuration)