Define Principles

# Define Principles

Add, edit, or remove project-specific golden rules that are enforced by `check-code` and
`review-pr`. Principles are stored in `.claude/principles.yaml` and automatically loaded by
other skills.

---

## Usage

```bash
# Interactive prompt — guided add / edit / remove workflow
/define-principles

# Config-file import — non-interactive bulk import from a YAML file
/define-principles --from-file path/to/import.yaml

# Preview what --from-file would add without writing to disk
/define-principles --from-file path/to/import.yaml --dry-run

# Fail loudly if any imported principle has an ID that already exists
/define-principles --from-file path/to/import.yaml --strict-ids

Both workflows write the same .claude/principles.yaml format and auto-generate docs/PRINCIPLES.md. The interactive prompt is a guided editor for the same YAML.

---

Instructions

Step 0 — Parse arguments and choose a mode

Inspect the arguments passed after /define-principles:

if --from-file <path> is present:
    → follow the "Config-file import mode" path (Step 1B)
else:
    → follow the "Interactive prompt mode" path (Step 1A)

---

Mode A — Interactive Prompt

Step 1A: Load existing principles

Check whether .claude/principles.yaml already exists:

cat .claude/principles.yaml 2>/dev/null || echo "__EMPTY__"

If the file is missing or empty, start with an empty principles list.

Step 2A: Show current state

Display the existing principles in a readable table:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Project Principles — .claude/principles.yaml
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ID     Category       Severity    Rule
  ────────────────────────────────────────
  P001   architecture   blocking    All DB queries must go through the repository layer
  P002   testing        blocking    Every public API endpoint must have an integration test
  P003   style          suggestion  Prefer dataclasses over plain dicts for structured data

  (3 principles loaded)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

If no principles exist yet, show:

  (no principles defined — let's add some)

Step 3A: Prompt for action

Ask the engineer what they want to do:

What would you like to do?
  [A] Add a new principle
  [E] Edit an existing principle
  [R] Remove a principle
  [D] Done / save and exit

Repeat this loop until the engineer chooses Done.

---

Action: Add a principle

Ask the following questions one at a time:

1. Category — What area does this rule cover?

   • Suggested: architecture, testing, security, performance, style, naming, error-handling
   • Accept any free-form string

2. Rule — State the golden rule in one sentence (imperative mood preferred).

   • Example: "All secrets must be loaded from environment variables, never hardcoded."

3. Severity — How serious is a violation?

   • blocking — Must be fixed before merge (surfaces in 🔴 BLOCKING section of review-pr)
   • suggestion — Nice to have (surfaces in 🟡 SUGGESTIONS section)

4. Applies to — Which skills should enforce this?

   • review-pr, check-code, or both (default: both)

Auto-assign the next available ID (P001, P002, …). Never reuse a deleted ID.

---

Action: Edit a principle

Ask: "Which principle ID do you want to edit?" Then re-ask only the fields the engineer wants to change.

---

Action: Remove a principle

Ask: "Which principle ID do you want to remove?" Confirm before deleting.

---

Mode B — Config-file Import

When --from-file <path> is provided, skip the interactive prompt entirely and import principles from the specified YAML file.

Step 1B: Validate the source file

python scripts/import_principles.py --from-file <path> [--dry-run] [--strict-ids]

The script validates each entry in the source file against the principle schema (see Config-file format below). Validation rules:

Field	Required	Valid values
category	✅	Any non-empty string
severity	✅	blocking or suggestion
rule	✅	Any non-empty string (imperative mood preferred)
applies_to	❌	List subset of ["review-pr", "check-code"] (default: both)
id	❌	Pattern [A-Z][A-Z0-9]*\d{2,} (e.g. P001, MB014). Omit to auto-assign.

If any entry fails validation, print all errors and exit without writing.

Step 2B: Merge with existing principles

• Entries without an id get the next available P-series ID auto-assigned.
• Entries whose id already exists in .claude/principles.yaml:
  • Default: skip silently (print a ⚠️ warning).
  • --strict-ids: exit 1 without writing anything.
• IDs are stable — removed principles are never renumbered.

Step 3B: Report and write

Print a summary of what was added / skipped / errored, then write the merged result to .claude/principles.yaml. With --dry-run, print the summary but skip the write.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Principle Import Summary
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✅ Added (2):
     P004  [security]  🔴 blocking  — All secrets must come from environment variables
     P005  [style]     🟡 suggestion — Prefer dataclasses over plain dicts

  ⚠️  Skipped (1):
     P001  — Principle 'P001' already exists — skipped.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

---

Step 4 — Save to .claude/principles.yaml

After all edits (interactive or file-import), write the final state to .claude/principles.yaml using this schema:

# .claude/principles.yaml
# Project-specific golden rules enforced by check-code and review-pr.
# Edit this file directly or run /define-principles to use the interactive prompt.
version: "1.0"
principles:
  - id: "P001"
    category: "architecture"
    severity: "blocking"
    applies_to: ["review-pr", "check-code"]
    rule: "All databas