Adopt persist repo practices: release, CI, .agents

.agents/rules/agents-first-convention.md

@@ -16,6 +16,8 @@ When creating **any** new rule or skill, follow this convention:
    ln -s ../../.agents/rules/<name>.md .cursor/rules/<name>.mdc
    ```
 
+**Naming:** Tier-2 priming rules that pair with a skill use `<skill-slug>-priming.md` when the rule name would otherwise differ from the skill folder. When names already match, no suffix.
+
 ## Skills (`SKILL.md` files)
 
 1. Create the directory and file in `.agents/skills/<name>/SKILL.md`
@@ -25,6 +27,8 @@ When creating **any** new rule or skill, follow this convention:
    ln -s ../../.agents/skills/<name> .cursor/skills/<name>
    ```
 
+**Never** name bulk reference files `AGENTS.md` inside skill folders — use `FULL-GUIDE.md` or topic siblings.
+
 ## Why
 
 - `.agents/` is the **source of truth** — it is IDE-agnostic and works across different AI coding tools.
@@ -35,3 +39,5 @@ When creating **any** new rule or skill, follow this convention:
 
 - Never place original rule/skill content directly in `.cursor/rules/` or `.cursor/skills/`.
 - Never create a rule or skill without both the `.agents/` file and the `.cursor/` symlink.
+
+Related: [`agents-tier-system.md`](./agents-tier-system.md) · [`AGENTS.md`](../../AGENTS.md).

.agents/rules/agents-tier-system.md

@@ -8,90 +8,23 @@ globs:
 alwaysApply: false
 ---
 
-# `.agents/` tier system
+# `.agents/` tier system — priming
 
-Cursor rules support three attachment modes. Each new rule must consciously pick one.
+Three attachment modes: **always-on** (`alwaysApply: true`), **auto-attached** (`globs:`), **intent** (`description:` only).
 
-| Mode              | Frontmatter                                           | Cost per turn                               | Use for                                                                       |
-| ----------------- | ----------------------------------------------------- | ------------------------------------------- | ----------------------------------------------------------------------------- |
-| **Always-on**     | `alwaysApply: true`                                   | full rule body always loaded                | cross-cutting **practices** — define how we work, not what we build           |
-| **Auto-attached** | `alwaysApply: false` + `globs:`                       | zero unless a matching file is in scope     | technical **patterns** — what we write under `.agents/**`, `src/cli/**`, etc. |
-| **Discoverable**  | `alwaysApply: false` + `description:` only (no globs) | zero unless description matches user intent | intent-driven **workflows** — the user said "do X"                            |
+**Tier 1 budget:** owner-set; currently ~10 always-on rules + `lessons.md` (≤250 lines total). The frontmatter audit is the source of truth — **no hardcoded Tier 1 name lists** in rule, skill, or README. Audit:
 
-## Tiers in this repo
+```bash
+for f in .agents/rules/*.md .agents/lessons.md; do
+  awk '/^---$/{c++; next} c==1 && /^alwaysApply: true$/{found=1; exit} END{exit !found}' "$f" && echo "$f"
+done
+```
 
-### Tier 1 — Always-on practices (~10 rules max)
-
-Genuinely cross-cutting. Apply to every turn regardless of file:
-
-- `agents-first-convention` — `.agents/` source-of-truth + `.cursor/` symlinks discipline
-- `codemap` — STOP-before-grep
-- `concise-comments` — sweep your own new comments before reporting
-- `concise-reporting` — extreme concision in agent reports
-- `lessons` — read when relevant; lift durable ones into rules/skills
-- `no-bypass-hooks` — never `--no-verify` on `git commit`
-- `pr-comment-fact-check` — fires the fact-check skill on PR-comment intent triggers
-- `preserve-comments` — never silently delete TODOs / commented-out code
-- `tracer-bullets` — small end-to-end slices, not horizontal layers
-- `consumer-surfaces` — consumer-facing text describes user-visible behavior only
-- `verify-after-each-step` — run the project's checks per milestone, not at commit time
-
-### Tier 2 — Auto-attached technical rules (this rule's tier)
-
-Glob-attached. Each is a thin priming layer (~30–50 lines: top-N principles + `Reference` section pointing at the deep-dive skill).
-
-Skills get a paired Tier-2 rule when they have **always-on principles** that should fire whenever the relevant files are in scope (e.g. when codemap grows a TS-specific style rule, it would attach to `**/*.{ts,tsx}`).
-
-Today's Tier-2 rules:
-
-- `agents-tier-system` (this rule) — auto-attaches when authoring under `.agents/**` or `.cursor/**`.
-- `docs-governance` — primes the docs framework when authoring under `docs/**` or `.agents/**` (paired with [`docs-governance` skill](../skills/docs-governance/SKILL.md)).
-- `plan-pr-inspiration-discipline` — primes plan-PR / recipe authoring with the open-spec inspection list when authoring under `docs/plans/**` or `templates/recipes/**`. The canonical inspection-sources table lives in the rule body itself.
-
-### Tier 3 — Discoverable skills (no rule)
-
-Pure intent-triggered. The skill description is detailed enough that Cursor surfaces it on relevant phrases. No always-on cost.
-
-Skills stay rule-less when the work is **explicitly invoked** by the user, not pattern-triggered. Today: `audit-pr-architecture`, `codemap` (consumer pointer), `diagnose`, `docs-governance`, `docs-lifecycle-sweep`, `grill-me`, `harden-pr`, `improve-codebase-architecture`, `pr-comment-fact-check`, `write-a-skill`. (Skills like `gritql-codemods` and `ubiquitous-language` would also fit this tier if adopted.)
-
-## Authoring guidelines
-
-### Adding a new rule
-
-1. **Decide the tier** before writing.
-2. **Tier 1 needs justification** — does it really apply to every turn? If it only applies in certain files / certain intents, demote to Tier 2 or Tier 3.
-3. **Tier 2 globs** — write the broadest pattern that's still meaningfully scoped. `**/*.ts` is acceptable for TS-wide rules. Filename heuristics (`*recipe*.ts`) are brittle for content-driven concerns and should be a last resort.
-4. **Tier 3 description** — write the description as if Cursor is grepping for trigger phrases. Include the verbs and nouns the user is likely to say ("rename", "delete", "convert", "consolidate") and the symbols / patterns the agent will see in code.
-5. **Pair with a skill** — every Tier-1 / Tier-2 rule should link to a skill in its `Reference` section for the deep dive. The rule is priming; the skill is reference.
-6. **Author the source under `.agents/rules/<name>.md` and symlink from `.cursor/rules/<name>.mdc`** per the [`agents-first-convention`](./agents-first-convention.md) rule.
-
-### Adding a new skill
-
-1. **Decide if it needs a rule.** If the skill has always-on principles (any `NEVER` / `ALWAYS` clauses, any "MUST be used when") — pair it with a Tier-1 or Tier-2 rule.
-2. **If skill-only**, write the description with explicit trigger phrases. Cursor's discovery is description-match-based.
-3. **Author under `.agents/skills/<name>/SKILL.md` and symlink from `.cursor/skills/<name>`** per the [`agents-first-convention`](./agents-first-convention.md) rule.
-
-## Authoring discipline: durability
-
-Rules and skills are **more durable** than the artifacts they describe. They outlive specific files, specific commit hashes, specific code shapes. Authoring them as if they were short-lived is the most common way they go stale.
-
-Three concrete sub-rules:
-
-1. **Don't cite specific audit / plan / research filenames as canonical examples.** Audits and plans are mortal under [`docs-lifecycle-sweep`](../skills/docs-lifecycle-sweep/SKILL.md) (Tier C delete or Tier B slim). The first time the doc janitor retires a file your skill named, the skill's example rots. Use shape placeholders (`<YYYY-MM-DD>-<topic>.md`, `<topic>.md`) and describe the **shape** of what the next reader should look for ("the most recent audit under `docs/audits/`"), not which file does it today. **Reference docs (`README.md`, `architecture.md`, `glossary.md`, `roadmap.md`, `agents.md`) ARE durable** — citing them by name is fine; they live forever per their lifecycle type.
-2. **Don't cite specific commit hashes or PR numbers as the only path to context.** Hashes and PR URLs are stable but opaque. If the context matters, summarise it inline. Hashes are good as **secondary** anchors ("the seed datapoint, commit `<hash>`") not primary ones.
-3. **Don't cite specific source-code line numbers.** Same drift as above; lines move on every edit. Reference symbols by name. (Same hazard as [`docs/README.md` Rule 7](../../docs/README.md) — universal, not codemap-specific.)
-
-When in doubt: if the prose still reads correctly six months from now after every doc you didn't write got rewritten or deleted, the skill is durable. If it reads as a stale snapshot, slim the citations to placeholders.
-
-## Audit prompts
-
-When reviewing an existing rule:
-
-- **Is it Tier 1?** Check: does it apply on every turn? If it only applies to TS files, flip to Tier 2 with a glob.
-- **Is it Tier 2?** Check: are the globs well-scoped? Could broader globs catch content-driven cases? Could narrower globs save context without losing coverage?
-- **Is it skill-only?** Check: does the skill have any "always" / "never" clauses? If yes, it deserves a rule.
+**When authoring:** pick tier before writing; pair fat rules with skills; symlinks per [`agents-first-convention`](./agents-first-convention.md). Default to intent-triggered skills and a thin always-on set.
 
 ## Reference
 
-- File-layout convention: [`agents-first-convention.md`](./agents-first-convention.md).
-- The docs-governance pair this tier system was first applied to in this repo: [`docs-governance.md` rule](./docs-governance.md) (Tier-2 priming) + [`docs-governance` skill](../skills/docs-governance/SKILL.md) (deep reference).
+- Full assignments, checklist, pairing examples: [`agents-tier-system` skill](../skills/agents-tier-system/SKILL.md)
+- Codemap deltas + size tiers: [`writing-agents-config`](../skills/writing-agents-config/SKILL.md)
+- Router index: [`AGENTS.md`](../../AGENTS.md)
+- Architecture priming: [`architecture-priming.md`](./architecture-priming.md)

.agents/rules/architecture-priming.md

@@ -0,0 +1,26 @@
+---
+description: STOP and run architecture skills before structurally significant changes (module moves, schema/boundary, new exports, agent template layering)
+alwaysApply: true
+---
+
+# Architecture priming
+
+Most code changes are line-level — a parser fix, a CLI flag, a query recipe. They don't need architectural review. **A small minority of changes are structurally significant** and pay back compound interest if reviewed before they land. This rule fires the architecture skills on those signals only, not on every edit.
+
+## STOP if any of these apply
+
+- **≥5 files moved** between top-level `src/` modules (e.g. `src/cli/` → sibling folder)
+- **New `src/<X>/` module** — a new top-level source subtree
+- **Schema or boundary change** in `src/db.ts` (`SCHEMA_VERSION`, new tables/columns with cross-module impact)
+- **New subpath export** in `package.json` `exports`
+- **`templates/agent-content` vs `templates/agents` layering breach** — consumer-served content mixed with init-copied templates (see [`consumer-surfaces`](./consumer-surfaces.md))
+
+For each signal: STOP and run [`improve-codebase-architecture`](../skills/improve-codebase-architecture/SKILL.md) before proceeding; on open PRs or post-merge, also [`audit-pr-architecture`](../skills/audit-pr-architecture/SKILL.md).
+
+## Otherwise, proceed normally
+
+Line-level changes **do not trigger this rule**. Use intent-triggered skills (`harden-pr`, `diagnose`, etc.).
+
+## Reference
+
+[`improve-codebase-architecture`](../skills/improve-codebase-architecture/SKILL.md) · [`audit-pr-architecture`](../skills/audit-pr-architecture/SKILL.md) · [`tracer-bullets`](./tracer-bullets.md) · [`docs/architecture.md`](../../docs/architecture.md)

.agents/rules/authoring-discipline.md

@@ -0,0 +1,25 @@
+---
+description: Authoring discipline for code comments, docs, and committed prose — preserve existing comments, keep new prose concise.
+alwaysApply: true
+---
+
+# Authoring discipline (STOP)
+
+**Prose depth:** [`authoring-discipline/PROSE.md`](../skills/authoring-discipline/PROSE.md). **Doc lifecycle:** [`docs-governance`](../skills/docs-governance/SKILL.md).
+
+## Preserve existing source comments (non-negotiable)
+
+1. **Never remove comments** — preserve when editing; update if outdated, don't delete.
+2. **Never remove TODO / FIXME / HACK** — ask user before removing completed TODOs.
+3. **Never remove commented-out code** — ask before removal.
+4. **StrReplace** — copy comments into `new_string`; move comments when restructuring.
+
+User-requested **doc audits** may slim redundant markdown; preservation above applies to **source** comments only.
+
+## New prose (defaults)
+
+- **Decision test:** could a teammate re-derive this in 30s? → cut it (details in [`PROSE.md`](../skills/authoring-discipline/PROSE.md)).
+- **JSDoc as types (`.mjs`, `@ts-check`):** `@typedef`, `@param`, `@returns`, inline `@type` are the type system — keep them; apply the decision test only to prose in those blocks.
+- **End-of-turn:** cut duplicate tables/narration; after doc slim → [`docs-governance`](../skills/docs-governance/SKILL.md) slimming audit.
+
+Related: [`concise-reporting`](./concise-reporting.md) · [`docs-lifecycle-sweep`](../skills/docs-lifecycle-sweep/SKILL.md).