@event4u/agent-config 2.6.1 → 2.8.0

package/docs/guidelines/gtm-handoff.md

@@ -0,0 +1,114 @@
+# GTM Handoff
+
+Wing-3-specific prose for the three load-bearing senior-skill chains
+in the GTM + Growth cluster. The mechanical contract — initiator →
+delegated(input) → output-artifact, lint rules, worktree boundary —
+lives in [`docs/contracts/cross-wing-handoff.md`](../contracts/cross-wing-handoff.md).
+The cross-wing routing prose (when to hand off at all, L4 / C8
+boundary, decision tree) lives in
+[`docs/guidelines/cross-role-handoff.md`](cross-role-handoff.md).
+This guideline covers **what crosses each Wing-3 boundary**, **what
+the typed artifact looks like**, and **who owns the failure mode
+when the chain breaks**.
+
+Cycle / dangling / tier-mismatch enforcement is not duplicated here —
+`task lint-handoffs` (per cross-wing-handoff § 4) is the mechanical
+gate.
+
+## Chain 1 — brand → channel
+
+Five-step chain that turns a category point-of-view into a shipped
+funnel of channel artifacts. CMO cluster owns every step.
+
+```
+positioning-strategy (H1)
+  → messaging-architecture (H2)
+    → gtm-launch (H3)
+      → editorial-calendar (H4)
+        → content-funnel-design (H5)
+```
+
+| Step | Hands off when | Typed artifact crossing the boundary | Failure-mode owner |
+|---|---|---|---|
+| H1 → H2 | Category framing + opposable-positioning audit locked. | `positioning-statement.md` — "we are X for Y, not Z" + point-of-view paragraph + opposable-positioning matrix. | H1 owns drift: if H2 cannot derive proofs from the statement, H1's POV is too soft. |
+| H2 → H3 | Primary message + supporting proofs + audience-by-message matrix locked. | `messaging-stack.md` — primary message, three supporting proofs, audience-message matrix, narrative beats. | H2 owns drift: if H3's wave-by-wave narrative drifts, the proofs were the wrong shape. |
+| H3 → H4 | Launch sequencing (alpha → beta → GA) + audience-wave logic locked; engineering-readiness signals attached. | `launch-plan.md` — wave list, narrative beats per wave, dependency map, go / no-go signals. | H3 owns drift: missing engineering-readiness signal = H3 shipped a plan that cannot land. |
+| H4 → H5 | Cadence cognition (evergreen vs campaign vs reactive) + beat-mapping locked. | `editorial-calendar.md` — cadence per audience, beat-to-asset map, content-debt ledger. | H4 owns drift: a calendar that does not map beats to funnel stages cannot be designed against. |
+| H5 self-closes | Funnel-stage-to-content-shape mapping + conversion-pathway design locked. | `content-funnel.md` — per-stage asset shapes, conversion pathways, leading indicators. | H5 owns drift: any stage without a content shape is a broken funnel hand-back to H4. |
+
+H5 also **composes** `funnel-analysis` (H14, Chain 3) — the funnel
+diagnostic feeds the conversion-pathway design without H5 absorbing
+funnel-diagnostic cognition.
+
+## Chain 2 — discovery → pipeline
+
+Five-step chain that turns customer research into a forecast-able
+pipeline. Spans the Discovery → RevOps boundary inside Wing 3 and
+hands the forecast call back to the Wing-4 finance-partner.
+
+```
+customer-research (L1, shipped)
+  → ideal-customer-profile artifact
+    → pipeline-strategy (H8)
+      → deal-qualification-meddic (H9)
+        → forecast-accuracy (H10) → forecasting (Wing-4 O2)
+```
+
+| Step | Hands off when | Typed artifact crossing the boundary | Failure-mode owner |
+|---|---|---|---|
+| `customer-research` → H8 | Switch-event interviews + JTBD framing complete; ICP synthesized from verbatims. | `icp.md` — segment definition, switch events, JTBD frame, anti-ICP. | `customer-research` owns drift: an ICP without anti-ICP boundaries leaks into H8 stage definitions. |
+| H8 → H9 | Stage definitions + conversion-rate targets + coverage reasoning locked. | `pipeline-shape.md` — stage list, per-stage conversion target, coverage ratio, leak map. | H8 owns drift: stages H9 cannot disqualify against = H8 stage definitions were not orthogonal. |
+| H9 → H10 | MEDDIC qualification rubric + disqualification heuristics locked. | `qualification-rubric.md` — MEDDIC fields per stage, disqualification triggers, champion-test. | H9 owns drift: forecasts that ignore disqualification heuristics inflate; H9 owns the rubric. |
+| H10 → Wing-4 O2 | Forecast call constructed (commit / best-case / pipeline) against the `forecast-construction-shape` ADR. | `forecast-band.json` — commit value, best-case value, pipeline value, confidence band, retro signature. | **Interface contract owned by O2** (per cross-wing-handoff § 5 / W4 chain): if the ADR drifts, O2 breaks the contract, not H10. |
+
+H10's parallel-development rule (starts after O2-interface ≥ 100 %,
+runs in parallel with O2 implementation) is recorded in the roadmap
+H10 entry and the contract — not duplicated here.
+
+## Chain 3 — funnel → retention
+
+Six-step chain that turns funnel diagnostics into a retention and
+expansion system. Growth PM cluster owns the first three steps,
+Customer Success cluster owns the last three; the H15 → H12 boundary
+crosses the cluster line inside Wing 3.
+
+```
+funnel-analysis (H14)
+  → activation-design (H16)
+    → onboarding-design (H11)
+      → retention-loops (H15)
+        → churn-prevention (H12)
+          → expansion-playbook (H13)
+```
+
+| Step | Hands off when | Typed artifact crossing the boundary | Failure-mode owner |
+|---|---|---|---|
+| H14 → H16 | Funnel-stage diagnostics + leaky-bucket-vs-growth-loop classification + leading-indicator selection locked. | `funnel-diagnostic.md` — per-stage drop-off, loop classification, leading indicators, cohort behavior. | H14 owns drift: an unselected leading indicator leaves H16 without an aha-moment signal. |
+| H16 → H11 | Aha-moment definition + activation-event selection + activation-funnel construction locked. | `activation-spec.md` — aha-moment, activation event, activation-funnel stages, leading-vs-lagging indicators. | H16 owns drift: an activation event H11 cannot instrument is the wrong event. |
+| H11 → H15 | Time-to-first-value reasoning + milestone design + friction audit locked. | `onboarding-flow.md` — milestone list, time-to-value target, friction-audit findings, drop-off diagnosis. | H11 owns drift: milestones without retention hooks force H15 to re-derive habit cognition. |
+| H15 → H12 | Habit-formation reasoning + trigger-action-reward design + loop classification locked. | `retention-loop.md` — trigger / action / reward triple, loop classification, network-vs-single-user signal. | H15 owns drift: a loop that does not surface a health signal leaves H12 without an early warning. |
+| H12 → H13 | Health-score signal design + churn-cause classification + early-warning loop locked. | `churn-signals.md` — health-score schema, churn-cause buckets, early-warning thresholds. | H12 owns drift: a health signal H13 cannot read against expansion triggers blocks NRR cognition. Also feeds **back to Wing-4 forecasting** per the cross-skill map. |
+| H13 self-closes | Account-expansion patterns + upsell-vs-cross-sell reasoning + NRR cognition locked. | `expansion-playbook.md` — expansion patterns, trigger signals, NRR levers. | H13 owns drift: expansion triggers that ignore churn signals double-count growth. |
+
+## Reading the failure-mode column
+
+The column answers one question: **when a downstream skill cannot
+do its job, which upstream skill rewrites its artifact?** The owner
+is the **upstream** skill, not the consumer — drift is always a
+producer-side fix. This mirrors the W4 / W3 forecasting chain in
+the contract (O2 owns the interface; H10 only consumes it).
+
+## See also
+
+- [`docs/contracts/cross-wing-handoff.md`](../contracts/cross-wing-handoff.md)
+  — typed-handoff mechanical contract; `task lint-handoffs` enforces
+  cycles, dangling references, and tier mismatches over the graph.
+- [`docs/guidelines/cross-role-handoff.md`](cross-role-handoff.md)
+  — when to hand off at all, how to phrase the routing, L4 / C8
+  boundary.
+- [`docs/contracts/context-spine.md`](../contracts/context-spine.md)
+  § Wing-3 slots — `channel-stage`, `funnel-stage`,
+  `customer-segment`; every chain step opts into ≥ 1 slot.
+- `agents/roadmaps/` § Block H (archived after merge) — the
+  sixteen H-skills this guideline maps; pending skills appear here
+  as backtick slugs until shipped.

package/docs/setup/enterprise-and-offline.md

@@ -0,0 +1,201 @@
+# Enterprise & offline installation
+
+> **Status:** experimental · contract-shaped output of
+> `agents/roadmaps/road-to-distribution-maturity.md` Phase 2. Four
+> documented happy-paths for environments where the public npm
+> registry is not freely reachable from the developer's machine, plus
+> a "no-internet developer" runbook.
+
+## Why no Composer fallback
+
+Re-introducing a Composer-published distribution was evaluated in the
+Phase 0 council session
+(`agents/council-questions/composer-fallback-feasibility.md`) and
+**rejected** on three grounds:
+
+1. **Lock-shape mismatch.** `installed.lock` is npm-shaped (flat dep
+   model + npm pin in `.agent-settings.yml`). A Composer fallback
+   would need either a parallel manifest (breaks the "lock is
+   canonical" invariant) or a translation layer (defeats the
+   "minimal" claim).
+2. **Dual-distribution attack surface.** Two pipelines means two
+   SBOMs, two CVE response surfaces, two signing roots. Supply-chain
+   risk doubles for a fallback most operators will never use.
+3. **"Minimal fallback" is an oxymoron.** Partial functionality
+   shipped on a parallel pipeline confuses operators more than it
+   helps — the failure mode of a half-working Composer install is
+   worse than a documented npm-only path.
+
+The supported alternative is the **four-path enterprise/offline
+matrix** below, all of which keep npm as the single distribution
+channel.
+
+## Path A — pinned-npx via internal registry
+
+For environments where the public registry is unreachable but an
+internal mirror (Verdaccio, Nexus, JFrog, Sonatype) is configured:
+
+```bash
+# .npmrc at repo root or ~/.npmrc
+registry=https://npm.internal.example.com/
+@event4u:registry=https://npm.internal.example.com/
+always-auth=true
+```
+
+Pin the consumed version in the consumer project's
+`.agent-settings.yml`:
+
+```yaml
+# .agent-settings.yml
+agent_config_version: "2.6.1"  # matches the version your mirror has indexed
+```
+
+`scripts/install.py` reads `agent_config_version` at install time and
+records it in `~/.event4u/agent-config/installed.lock` per ADR-007.
+The registry-mirror caveat: your mirror **must** index the
+`@event4u/agent-config` scope before the first `npx` call — `npx`
+does not transparently fall back from a private mirror to the public
+registry.
+
+> **Consumer npm-pinning ≠ release-shape pinning.** This path pins
+> what the consumer's `npx` resolves to. The package's own release
+> cadence (semver, tags, deprecation windows) is not pinned here per
+> `.augment/rules/scope-control.md` § "no version pinning in
+> roadmaps". The `agent_config_version` field is a consumer choice.
+
+## Path B — offline cache strategy
+
+For environments where the developer's machine has no network egress
+at all but a pre-staged npm cache is delivered out-of-band:
+
+```bash
+# On a machine with internet access:
+npm cache add @event4u/agent-config@2.6.1
+tar -czf agent-config-npm-cache.tgz ~/.npm/_cacache
+
+# On the offline machine:
+tar -xzf agent-config-npm-cache.tgz -C ~/
+npx --prefer-offline @event4u/agent-config init
+```
+
+Corepack-pinning the npm version makes the cache reproducible across
+developers:
+
+```bash
+corepack enable
+corepack prepare npm@10.5.0 --activate  # whatever version your cache was built with
+```
+
+`agent_config_version` in `.agent-settings.yml` must match the cached
+version exactly — otherwise `npx` will try (and fail) to resolve a
+different version from the registry.
+
+## Path C — CI-safe install pattern
+
+CI agents (GitHub Actions runners, GitLab runners, Jenkins agents
+behind a corporate proxy) get a narrower happy-path:
+
+- **Cached tarball** in the runner's artifact store
+  (`actions/cache@v4` or equivalent), keyed on
+  `agent_config_version`.
+- **`npm install --offline`** against the cache so the runner never
+  hits the registry.
+- **`scripts/install.py validate`** instead of `init` — `validate`
+  re-reads `installed.lock` and checks the worktree matches; `init`
+  scaffolds tool directories which a CI agent typically does not
+  need.
+- **No global writes.** CI runners are ephemeral; the
+  `~/.event4u/agent-config/installed.lock` write is harmless but the
+  CI job should not rely on it persisting between runs.
+
+## Path D — verified-offline install (`scripts/hermetic-install.sh`)
+
+> **Naming note.** The file name is `scripts/hermetic-install.sh` for
+> roadmap continuity (Phase 2 Step 5). The **semantic** per the
+> Anthropic council verdict is **verified-offline install** — the
+> checksum manifest is delivered via a separate channel (not bundled
+> in the tarball), so the trust model is not circular. "Hermetic" is
+> used in the colloquial sense (reproducible + verifiable), not the
+> Bazel-strict sense.
+
+For air-gapped or strict-supply-chain environments where (a) network
+egress is fully blocked, (b) tarball integrity must be verifiable
+against an external manifest, and (c) installation must be auditable
+end-to-end:
+
+```bash
+# 1. Out-of-band: operator obtains
+#    - agent-config-2.6.1.tgz                (from a separate channel)
+#    - agent-config-2.6.1.sha256             (separate-channel manifest, GPG-signed)
+#    - public.gpg                            (operator-supplied trust root)
+
+# 2. On the target machine:
+bash scripts/hermetic-install.sh \
+  --tarball ./agent-config-2.6.1.tgz \
+  --manifest ./agent-config-2.6.1.sha256 \
+  --gpg-key ./public.gpg
+```
+
+Outcomes recorded in `~/.event4u/agent-config/installed.lock`:
+
+```yaml
+schema_version: 1
+agent_config_version: "2.6.1"
+installation_mode: "hermetic"             # additive field (schema_v1 + extension)
+package_checksum: "sha256:<hex>"          # sha256 of the verified tarball
+signature_verified: true                  # GPG verification result
+installed_at: "2026-05-13T09:42:00Z"
+tools:
+  - claude
+```
+
+> **Platform support.** Unix-only (macOS + Linux). The script depends
+> on `bash`, `sha256sum`/`shasum`, and `gpg`. Windows support is
+> future scope per the Phase 2 council session (o1 verdict). Windows
+> users go through Path B (offline cache) on WSL.
+
+> **Schema cadence.** The three additional fields are written under
+> `schema_version: 1` as additive keys. The bump to
+> `schema_version: 2` is captured as a deferred ADR candidate in
+> `agents/roadmaps/road-to-distribution-maturity.md` Notes § "Phase 2
+> lock-schema extension — ADR candidate" — not opened this PR.
+
+## No-internet developer runbook
+
+A developer arrives on Monday with no network and finds a broken
+`npx` cache (corrupted, stale, or never staged). Recovery:
+
+1. **Confirm no-network.** `curl -m 5 https://registry.npmjs.org/ ||
+   echo "offline as expected"`.
+2. **Inventory what is local.**
+   - `ls ~/.npm/_cacache/` — is the offline cache present?
+   - `cat ~/.event4u/agent-config/installed.lock` — was a prior
+     install successful?
+3. **Pick a path:**
+   - Cache present + lock present → **Path B**, `npx --prefer-offline`.
+   - Cache present + lock missing → **Path B**, then `validate`.
+   - Cache missing + tarball + manifest present → **Path D**.
+   - Cache missing + nothing else → ask the IT contact to deliver
+     either a fresh tarball (for Path D) or a fresh cache archive
+     (for Path B). Do not attempt to bridge to the registry.
+4. **Verify.** After whichever path, run `npx --prefer-offline
+   @event4u/agent-config validate` and confirm exit code zero. If
+   `validate` fails on a checksum or version mismatch, the cache
+   or tarball is stale — re-acquire, do not edit `installed.lock`
+   by hand.
+
+> No code recovery path goes through editing `installed.lock`
+> manually. The file is atomic (`os.replace`) by design — hand-edits
+> bypass the schema invariant and will be overwritten on the next
+> `init`/`update`.
+
+## See also
+
+- `agents/roadmaps/road-to-distribution-maturity.md` § Phase 2 — the
+  roadmap entry that produced this document.
+- `agents/council-questions/composer-fallback-feasibility.md` — the
+  question that rejected the Composer path.
+- `agents/council-questions/hermetic-install-scaffolding.md` — the
+  question that shaped Path D.
+- `docs/decisions/ADR-007-agent-discovery-scopes.md` — the lock
+  manifest contract that Phase 2 extends additively.

package/docs/setup/per-ide/augment.md

@@ -1,10 +1,18 @@
 # Augment Code Setup
 
-Augment Code is the **substrate** for this package — every other tool
-mirrors content from the canonical `.augment/` tree. The Augment
-extension (VS Code, JetBrains) reads `.augment/rules/`,
-`.augment/skills/`, `.augment/commands/`, `.augment/personas/`, and
-`.augment/contexts/` directly.
+Augment Code is **global-only** in this package — content ships from a
+single user-scope tree at `~/.augment/` and the Augment extension
+(VS Code, JetBrains) reads it on every workspace. Per-project
+`.augment/` content is not installed; project `init` writes only the
+`.augment/settings.json` marker that authorizes the plugin for the
+workspace.
+
+> **Why global-only?** Augment counts the full body of every file in
+> `.augment/rules/` against its 49,512-char workspace-guidelines limit.
+> The package-wide rule set exceeds that limit on every workspace, so
+> a single user-scope install is the canonical surface and the
+> overflow is a known, accepted trade-off. See
+> [`ADR-007 § Amendment 2026-05-13 — global-only`](../../decisions/ADR-007-agent-discovery-scopes.md#amendment-2026-05-13--augment-global-only).
 
 ## Prerequisites
 
@@ -13,28 +21,31 @@ extension (VS Code, JetBrains) reads `.augment/rules/`,
 
 ## Install
 
-Project scope (default):
+Global scope (the only supported path — deploys the full bundle to
+`~/.augment/`):
 
 ```bash
-npx @event4u/agent-config init --tools=augment
+npx @event4u/agent-config init --tools=augment --global
 ```
 
-Global scope (cross-project, deploys the full bundle to `~/.augment/`):
+`--tools=augment` without `--global` is rejected with a directive
+error; `--tools=all` (project scope) silently filters `augment` out.
 
-```bash
-npx @event4u/agent-config init --tools=augment --global
-```
+Populates (`~/.augment/`):
+
+- `~/.augment/rules/`     — kernel (9 Iron-Law rules) + tier-1/2 routed rules
+- `~/.augment/skills/`    — domain skills
+- `~/.augment/commands/`  — slash commands
+- `~/.augment/personas/`  — review-lens personas
+- `~/.augment/contexts/`  — knowledge-layer contexts
+- `~/.augment/templates/` — scaffolds for AGENTS.md, copilot-instructions, etc.
 
-Populates (project):
+A project-scope `init` (any `--tools=…` selection except `augment`)
+still writes:
 
-- `.augment/rules/`     — kernel (9 Iron-Law rules) + tier-1/2 routed rules
-- `.augment/skills/`    — domain skills
-- `.augment/commands/`  — slash commands
-- `.augment/personas/`  — review-lens personas
-- `.augment/contexts/`  — knowledge-layer contexts
-- `.augment/templates/` — scaffolds for AGENTS.md, copilot-instructions, etc.
-- `AGENTS.md`           — canonical agent self-orientation
-- `.agent-settings.yml` — per-project knobs
+- `.augment/settings.json` — plugin activation marker for the workspace
+- `AGENTS.md`              — canonical agent self-orientation
+- `.agent-settings.yml`    — per-project knobs
 
 ## How to use
 
@@ -53,9 +64,9 @@ Populates (project):
 ## Verification
 
 ```bash
-test -d .augment/rules
-test -d .augment/skills
-test -d .augment/commands
+test -d ~/.augment/rules
+test -d ~/.augment/skills
+test -d ~/.augment/commands
 test -f AGENTS.md
 ```
 
@@ -67,8 +78,9 @@ should cite the AGENTS.md emergency triage block.
 | Symptom | Fix |
 |---|---|
 | Skills not surfaced | Reload the Augment workspace; skills are indexed on session start. |
-| Symlinked sub-dirs missing | `.augment/skills` is a symlink to `.agent-src/skills`; run `task sync` to rebuild. |
-| Iron Laws not firing | Confirm `.augment/rules/` contains 9 kernel files (`task ci` validates the kernel count). |
+| `~/.augment/rules/` missing | Re-run `npx @event4u/agent-config init --tools=augment --global`. |
+| Workspace-guidelines overflow warning | Expected — the package rule set exceeds Augment's 49,512-char budget. See [`ADR-007 § Amendment 2026-05-13`](../../decisions/ADR-007-agent-discovery-scopes.md#amendment-2026-05-13--augment-global-only). |
+| Iron Laws not firing | Confirm `~/.augment/rules/` contains 9 kernel files. |
 
 ## Cross-references
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "2.6.1",
+    "version": "2.8.0",
     "description": "Shared agent configuration \u2014 skills, rules, commands, guidelines, and templates for AI coding tools",
     "license": "MIT",
     "private": false,

package/scripts/_bootstrap_tier_frontmatter.py

@@ -0,0 +1,151 @@
+#!/usr/bin/env python3
+"""One-shot bootstrap — inject `tier: N` frontmatter into every slash command.
+
+Per Phase 4 Step 3 of `agents/roadmaps/road-to-distribution-maturity.md`.
+
+Walks `.agent-src.uncompressed/commands/**.md`. For each file:
+
+- Tier-0 promotions match TIER_0 below — typed by hand.
+- Tier-1 promotions match TIER_1 below — typed by hand.
+- Everything else defaults to **Tier-2** (per the contract).
+
+Idempotent — re-running is a no-op once tiers are tagged. The lint
+script `scripts/lint_command_tiers.py` enforces drift from here on.
+
+Run from repo root: `python3 scripts/_bootstrap_tier_frontmatter.py`.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+COMMANDS_DIRS = (
+    REPO_ROOT / ".agent-src.uncompressed" / "commands",
+    REPO_ROOT / ".agent-src" / "commands",
+)
+
+# Tier-0 — daily-driver slash commands (per docs/contracts/command-surface-tiers.md).
+# Paths are relative to COMMANDS_DIR.
+TIER_0 = {
+    "onboard.md",
+    "commit.md",
+    "work.md",
+    "implement-ticket.md",
+    "agent-status.md",
+    "agent-handoff.md",
+}
+
+# Tier-1 — power-user / maintainer / orchestrator slash commands.
+TIER_1 = {
+    "create-pr.md",
+    "review-changes.md",
+    "optimize.md",
+    "roadmap.md",
+    "feature.md",
+    "fix.md",
+    "judge.md",
+    "memory.md",
+    "council.md",
+    "agents.md",
+    "commit/in-chunks.md",
+    "create-pr/description-only.md",
+    "quality-fix.md",
+    "prepare-for-review.md",
+    "estimate-ticket.md",
+    "refine-ticket.md",
+    "bug-fix.md",
+    "bug-investigate.md",
+    "jira-ticket.md",
+    "compress.md",
+    "mode.md",
+    "project-analyze.md",
+    "project-health.md",
+    "rule-compliance-audit.md",
+    "threat-model.md",
+    "set-cost-profile.md",
+    "sync-agent-settings.md",
+    "sync-gitignore.md",
+    "upstream-contribute.md",
+}
+
+FRONTMATTER_RE = re.compile(r"^---\n(.*?)\n---\n", re.DOTALL)
+
+
+def classify(rel_path: str) -> int:
+    if rel_path in TIER_0:
+        return 0
+    if rel_path in TIER_1:
+        return 1
+    return 2
+
+
+def inject_tier(text: str, tier: int) -> tuple[str, bool]:
+    """Inject `tier: N` into the frontmatter block. Returns (new_text, changed).
+
+    If frontmatter already contains `tier:`, the existing value wins
+    (idempotent — bootstrap never overrides a manual tag).
+    """
+    m = FRONTMATTER_RE.match(text)
+    if not m:
+        return text, False
+    block = m.group(1)
+    if re.search(r"^tier:\s*[012]\s*$", block, re.MULTILINE):
+        return text, False
+    # Insert `tier: N` right after the `name:` line if present, else at
+    # the top of the block.
+    name_match = re.search(r"^(name:\s*\S+)$", block, re.MULTILINE)
+    if name_match:
+        new_block = (
+            block[: name_match.end()]
+            + f"\ntier: {tier}"
+            + block[name_match.end() :]
+        )
+    else:
+        new_block = f"tier: {tier}\n{block}"
+    new_fm = f"---\n{new_block}\n---\n"
+    return new_fm + text[m.end() :], True
+
+
+def main() -> int:
+    overall_tagged = 0
+    overall_skipped = 0
+    for commands_dir in COMMANDS_DIRS:
+        if not commands_dir.is_dir():
+            print(f"[bootstrap-tier] no commands dir: {commands_dir}")
+            continue
+        files = sorted(commands_dir.rglob("*.md"))
+        tagged = 0
+        skipped = 0
+        by_tier = {0: 0, 1: 0, 2: 0}
+        for path in files:
+            rel = path.relative_to(commands_dir).as_posix()
+            # Sub-AGENTS.md files are not slash commands.
+            if rel.endswith("AGENTS.md"):
+                continue
+            tier = classify(rel)
+            by_tier[tier] += 1
+            text = path.read_text(encoding="utf-8")
+            new_text, changed = inject_tier(text, tier)
+            if changed:
+                path.write_text(new_text, encoding="utf-8")
+                tagged += 1
+            else:
+                skipped += 1
+        overall_tagged += tagged
+        overall_skipped += skipped
+        rel_label = commands_dir.relative_to(REPO_ROOT)
+        print(
+            f"[bootstrap-tier] dir={rel_label} tagged={tagged} "
+            f"skipped={skipped} tier-0={by_tier[0]} "
+            f"tier-1={by_tier[1]} tier-2={by_tier[2]}"
+        )
+    print(
+        f"[bootstrap-tier] total: tagged={overall_tagged} "
+        f"skipped={overall_skipped}"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())