dot-prime

name	dot-prime
description	Activate principles before working on a file or task. Supports explicit group and ID overrides. Use when the user runs /dot-prime [target] to load the relevant principles into the active frame before writing or editing.
argument-hint	[@group...] [ID...] | [file|directory|description]
allowed-tools	Read, Glob, Grep, Bash
version	0.12.0
authors	Flemming N. Larsen (https://github.com/flemming-n-larsen)
license	MIT
generated-by	.principles

Prime

⛔ PREREQUISITE — CHECK THIS BEFORE ANYTHING ELSE

Before parsing arguments or doing any work, determine whether an explicit principle spec is present in $ARGUMENTS:

• Explicit spec = $ARGUMENTS contains one or more @-prefixed tokens, or tokens matching [A-Z][A-Z0-9]*(-[A-Z0-9]+)+ (bare principle IDs like CODE-CS-DRY)

If no explicit spec is present, check for principle sources in this order:

1. Read .agents/principles-catalog/active.md; keep if it contains the generated-by marker (<!-- generated by /dot-scout). If found, continue.

2. If none found: glob .github/instructions/*.instructions.md and REVIEW.md (at the git root) — these are Copilot Code Review and Claude Code Review outputs; keep only files containing the generated-by marker. If any are found, continue.

3. If none found: walk up from the target path (or CWD when no path was given) to the git root (.git/), max 10 levels; collect any .principles files. If any are found, continue.

4. If nothing is found → STOP. Do not proceed. Respond only with:

⚠️ /dot-prime found no principle sources. Run /dot-scout to generate instruction files, or create a .principles file listing @group tags, then retry.

You are activating a compact set of principles before working on a file or task. Follow these four phases exactly.

Phase 1 — Parse Arguments and Guard

1.1 — Detect explicit mode

Scan $ARGUMENTS for explicit principle specs:

1. @<group> tokens — one or more words prefixed with @ (e.g. @ddd, @docs-as-code). Extract all such tokens as the spec; the remaining tokens form the target context.
2. Bare principle IDs — tokens that match the pattern [A-Z][A-Z0-9]*(-[A-Z0-9]+)+ (e.g. CODE-CS-DRY, SOLID-SRP). Extract all matching tokens as the spec; remaining tokens form the target context.
3. No spec — treat all of $ARGUMENTS as target context. This is normal mode.

If a spec was detected: set explicit-mode: true. Otherwise: explicit-mode: false.

1.3 — Detect artifact type

Determine the artifact type from the target context (remaining tokens after spec extraction, or the full $ARGUMENTS in normal mode). If the target context is empty or a description rather than a path, scan the current working directory.

Detect by reading .agents/principles-catalog/layers/artifact-types.yaml and matching extensions, filenames, and path patterns.

Record the detected type: code | docs | config | infra | schema | pipeline

For code targets, also note any risk signals present: authentication, payments, PII, public API, concurrency, high-throughput.

Phase 2 — Resolve Active Set

Explicit mode

For each @<group> token: read .agents/principles-catalog/groups/<group>.yaml. Add all IDs from its principles: list. Recursively process any includes: entries (detect cycles and abort). If a group file is not found, report a warning and continue.

For each bare principle ID token: add it directly to the active set.

Active set = union of all expanded IDs.

Normal mode

Read the active principle set from the first source found:

1. .agents/principles-catalog/active.md — written by /dot-scout Phase 6 on every run; present whenever the catalog is vendored. Check for the <!-- generated by /dot-scout marker.
2. Review tool files (backward compat — only checked if active.md is absent): glob .github/instructions/*.instructions.md and REVIEW.md at the git root (Copilot Code Review and Claude Code Review outputs respectively); filter to files containing the generated-by marker.
3. .principles hierarchy (fallback — only if no scout-generated files found at all): handled below.

For sources 1 and 2: parse every - ID: Summary line; the ID is everything before the first colon. Union all IDs → active set.

Fallback — .principles hierarchy: if no scout-generated files were found in steps 1–3:

Walk up from the target path (determined in Phase 1) or CWD if no path was given, to the git root (.git/), max 10 levels. Collect every .principles file encountered. Order them root → target.

For each file (root → target):

1. Skip blank lines and # comment lines.
2. :directive value — parse as a configuration directive; :max_principles N caps the active set to N after all files are processed.
3. @group — read .agents/principles-catalog/groups/<group>.yaml; add all IDs from its principles: list to the active set; recursively expand any includes: entries (detect and abort on cycles).
4. Bare ID matching [A-Z][A-Z0-9]*(-[A-Z0-9]+)+ (case-insensitive) — add to the active set.
5. !ID — add to the exclusion set.

active set = collected IDs MINUS exclusion set (then apply :max_principles cap if set).

Note in the output: (resolved from .principles — no scout-generated files found)

If .agents/principles-catalog/install.cfg contains scout but active.md is absent, add a non-blocking warning alongside the active rules:

⚠️ Scout is recorded as installed but .agents/principles-catalog/active.md not found. Consider re-running /dot-scout.

Phase 3 — Select Top Principles

From the active set, select 5 to 10 principles most relevant to the current task. Hard cap: 10.

Selection priority (fill from top until cap reached):

1. Risk-elevated — any active IDs whose prefix is OWASP-*, CODE-SEC-*, CODE-RL-*, INFRA-SEC-*, or SEC-ARCH-*, AND which match a risk signal detected in Phase 1
2. Universal — SIMPLE-DESIGN-REVEALS-INTENTION, CODE-CS-DRY, CODE-CS-KISS, CODE-CS-YAGNI, CODE-DX-NAMING, ARCH-DECISION-RECORDS
3. Most task-relevant — use the artifact type and risk signals from Phase 1 to judge which remaining active IDs are most directly applicable to the work about to be done; prefer principles the developer is most likely to violate or forget for this specific task

In explicit mode, if the resolved set is ≤ 10: use all of them. If > 10: apply the same priority order to trim.

Phase 4 — Output Active Rules

Output the selected principles as a compact block. For each principle, write a single line:

- ID: one imperative sentence summarising what to do

The imperative sentence must be ≤ 12 words, written in second-person present tense (e.g. "Give every piece of knowledge one authoritative home."). Derive it from the principle title and your knowledge of the principle — do not read any catalog files.

Format:

**Active rules:**
- CODE-CS-DRY: Give every piece of knowledge one authoritative home.
- SOLID-SRP: Give each module exactly one reason to change.
- CODE-CS-FAIL-FAST: Detect errors immediately and report them loudly.
...

End with this line, on its own:

These are your focus principles for this task. Any full rule set from .agents/principles-catalog/active.md, REVIEW.md, or .github/instructions/ remains active. Proceed.