@event4u/agent-config 8.4.1 → 8.6.0

package/dist/agent-src/commands/fix.md

@@ -3,12 +3,12 @@ model_tier: medium
 name: fix
 disable-model-invocation: true
 pack: engineering-base
-intent: "Fix-workflow dispatcher — ci, pr-comments, refs, seeder, portability, comments"
-routes_to: [fix-ci, fix-pr-comments, fix-refs, fix-seeder, fix-portability, fix-comments]
+intent: "Fix-workflow dispatcher — ci, pr-comments, refs, seeder, portability, comments, quality"
+routes_to: [fix-ci, fix-pr-comments, fix-refs, fix-seeder, fix-portability, fix-comments, fix-quality]
 replaces: []
 tier: 1
 visibility: advanced
-description: Fix orchestrator — routes to ci, references, portability, seeder, pr-comments
+description: Fix orchestrator — routes to ci, references, portability, seeder, pr-comments, comments, quality
 cluster: fix
 type: orchestrator
 auto_detect: true
@@ -37,9 +37,10 @@ with a single entry point + sub-command dispatch.
 | `/fix seeder` | `commands/fix/seeder.md` | Scan seeder data files for broken FK references |
 | `/fix pr-comments` | `commands/fix/pr-comments.md` | Fix and reply to all open review comments — **bot + human, classified per comment**; dedupes by comment id + reply marker |
 | `/fix comments` | `commands/fix/comments.md` | Review the **code comments** in the current branch's diff and simplify, shorten, or remove each one (≠ `pr-comments`, which targets GitHub review threads) |
+| `/fix quality` | `commands/fix/quality.md` | Run the quality pipeline (type-checker / linter / formatter, PHP and/or JS/TS) and fix every error — auto-detects language from changed files |
 
 Sub-command names match the locked contract in
-[`docs/contracts/command-clusters.md`](../docs/contracts/command-clusters.md).
+[`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
 
 ## Non-interactive & auto-detection
 
@@ -55,6 +56,7 @@ the `auto_detect` kill-switch, rollback). Detection table:
 | PR review comments are the target (any "address review", PR # in context) | `fix/pr-comments` (it then resolves bot/human/both) | HIGH |
 | Source-code comments are the target ("simplify/clean up the comments in my branch", "trim comment noise") | `fix/comments` | HIGH |
 | Seeder / FK breakage named | `fix/seeder` | HIGH |
+| Type-checker / linter / formatter errors in context ("fix the quality errors", PHPStan/tsc/eslint output) | `fix/quality` | HIGH |
 | Project-specific leakage in shared package named | `fix/portability` | MEDIUM |
 | No clear signal, or ≥ 2 conflict | — | LOW → menu (interactive) / `ambiguous_routing` (CI) |
 
@@ -80,6 +82,7 @@ into it and removed.
    > 4. seeder — scan seeders for broken FK references
    > 5. pr-comments — address open review comments (bot / human / both)
    > 6. comments — simplify / shorten / remove code comments in the branch diff
+   > 7. quality — run the quality pipeline and fix every error
 
 ## Rules
 

package/dist/agent-src/commands/optimize/project.md

@@ -0,0 +1,250 @@
+---
+model_tier: high
+name: optimize-project
+pack: meta
+tier: 2
+visibility: internal
+sub: project
+cluster: optimize
+skills: [project-analyzer, decision-review, roadmap-writing]
+description: "Project-wide optimization sweep — inventory roadmaps, ADRs, agent folders (incl. modules), challenge stale decisions with the user in the loop, emit new roadmap(s). E.g. 'optimize this project'."
+suggestion:
+  eligible: true
+  trigger_description: "optimize this project, optimize the project, what should we improve based on current state, challenge our old decisions, are our roadmaps and ADRs still right, optimiere das Projekt, hinterfrag unsere alten Entscheidungen"
+  trigger_context: "user wants a project-wide review that questions existing state (roadmaps, ADRs, decisions, structures) and ends in new roadmap(s) — NOT a bug fix, NOT a single-decision audit (/analyze:decision), NOT agent-layer tooling (/optimize)"
+workspaces:
+  - engineering
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /optimize-project
+
+Project-wide optimization loop: **inventory → challenge → interview →
+roadmap(s)**. Analyzes the project it runs in (package or consumer),
+questions the existing state — roadmaps, ADRs, decisions, structures,
+and in this package e.g. token consumption, memory, learnings — asks
+the user when flipping an old decision would be a real improvement, and
+ends by emitting one or more NEW roadmaps via `/roadmap:create`.
+
+This is a **coordinator** over existing primitives — it composes, never
+reimplements: `/project-health`-style inventory, `/challenge-me`
+interview mechanics, `/analyze:decision`-style decision challenge,
+`/roadmap:create` output.
+
+> Looking for agent-layer tooling (skills, agents-dir, augmentignore,
+> rtk filters)? That is the [`/optimize`](optimize.md)
+> cluster — a different surface. This command optimizes the **project**,
+> not the agent layer.
+
+## When to invoke
+
+- "Optimize this project" / "optimiere das Projekt".
+- "What should we improve based on the current state?"
+- "Challenge our old decisions" / "are our roadmaps and ADRs still right?"
+- Periodic hygiene: many roadmaps have accumulated, decisions feel
+  stale, structures grew organically and nobody has questioned them.
+
+Do NOT invoke for: a single named bug ("fix this"), a single decision
+audit (route to `/analyze:decision`), a code-only analysis
+(`/project-analyze`), or AGENTS.md / agent-layer work (`/agents`,
+`/optimize`).
+
+## Steps
+
+### Step 0 — Scope detection (read-only)
+
+1. Detect the target type:
+   - **Package mode** — this repo IS `event4u/agent-config` (marker:
+     `src/config/budgets.yml` + `dist/agent-src/` present). Optimization
+     surface additionally includes token budget, memory index,
+     learnings/knowledge corpus, lint debt.
+   - **Consumer mode** — any other project with an `agents/` tree
+     and/or installed agent layer. Optimization surface = workflows,
+     structures, docs, roadmaps, decisions.
+2. Resolve module roots via
+   `scripts/_lib/agent_settings.ts::enumerate_modules()` (Laravel shape:
+   `app/Modules/*/agents/`); fall back to `modules.root_paths` in
+   `.agent-settings.yml`.
+3. Exclusions are hard: never analyze `vendor/`, `node_modules/`,
+   `dist/`, or any generated projection (`.augment/`, `.claude/`,
+   `.cursor/`).
+
+### Step 1 — Inventory (read-only, parallel)
+
+Gather without creating or modifying anything:
+
+- **Roadmaps** — `agents/roadmaps/` (+ per-module roadmap dirs): counts
+  per disposition (active / `later/` / `skipped/` / `archive/`),
+  per-roadmap open/done/deferred checkbox counts, staleness
+  (mtime > 60 days with open items), complete-but-unarchived.
+- **Decisions** — ADR dirs (`docs/adr/`, `docs/decisions/`,
+  `agents/decisions/`): count, age distribution, `status:` fields,
+  superseded chains.
+- **Agent folders** — `agents/` root + every module `agents/` folder:
+  docs, features, contexts; orphaned or stale files (referencing
+  deleted code).
+- **Memory / learnings** (if present) — memory index size, knowledge
+  cards, low-impact decisions corpus; entries whose subject no longer
+  exists in the repo.
+- **Package mode only** — current budget usage vs cap
+  (`src/config/budgets.yml`), kernel share, corpus size trends, known
+  lint debt, honest-null / don't-relitigate lock inventory (from memory
+  index + `agents/settings/contexts/`).
+
+Emit a compact inventory report (counts + flagged items), in the
+user's language. Present findings incrementally, not as one dump.
+
+### Step 2 — Findings & challenge candidates
+
+Classify everything flagged in Step 1 into three buckets:
+
+1. **Mechanical optimizations** — no decision needed, just work: stale
+   roadmap cleanup, complete-but-unarchived roadmaps, dead references,
+   missing module docs, memory entries pointing at deleted code.
+2. **Decision-challenge candidates** — an existing decision (ADR, lock,
+   council verdict, structural convention) whose original assumptions
+   may no longer hold. For each candidate record: *the decision · the
+   original assumption · what changed since · the expected gain from
+   flipping · the flip cost/blast radius*. A candidate without a
+   concrete "what changed" is not a candidate — drop it.
+3. **Structural / process improvements** — recurring friction visible
+   in the inventory (e.g. roadmap sprawl, duplicate contexts, token
+   hot-spots in package mode).
+
+Rank candidates by expected impact vs. effort. **Cap the
+decision-challenge list at the top 5** (override: `--max-questions=N`).
+Everything below the cap is carried into Step 4 as "further candidates"
+— never silently dropped.
+
+Before a candidate built on a claim about the current state enters the
+interview, verify the claim against the real source (grep, file read,
+live git/CI state) per
+[`source-discovery-gate`](../../rules/source-discovery-gate.md) —
+never challenge a decision based on a remembered or assumed fact.
+
+### Step 3 — Challenge interview (user-gated, budgeted)
+
+One question per turn, numbered options with a recommendation —
+the `/challenge-me` mechanics, per
+[`ask-when-uncertain`](../../rules/ask-when-uncertain.md) and
+[`user-interaction`](../../rules/user-interaction.md).
+
+Per candidate, present:
+
+```
+> **Decision:** <what was decided, where it is recorded>
+> **Then:** <original assumption>
+> **Now:** <what changed — with evidence source>
+> **Gain if flipped:** <expected improvement> · **Cost:** <blast radius>
+>
+> 1. Keep — assumptions still hold
+> 2. Flip — schedule the change in the output roadmap
+> 3. Re-evaluate via council — genuinely contested, worth a multi-model pass
+> 4. Defer — park as "further candidate"
+```
+
+Hard rules for this step:
+
+- **Locked decisions are never silently flipped.** An honest-null
+  verdict, a "don't relitigate" note, a budget-canon line, or a locked
+  council convergence follows
+  [`decision-revisit-gate`](../../rules/decision-revisit-gate.md):
+  check the lock's mechanism/scope actually matches the proposed change
+  and its recorded revisit-conditions first; if it truly blocks, the
+  only flip path offered is option 3 (council re-eval) — "Flip" is not
+  offered for locks.
+- **Session budget:** at most 5 interview questions by default
+  (`--max-questions=N` to override). Budget exhausted → remaining
+  candidates go to Step 4 as "further candidates".
+- Interview answers are adopted immediately; never re-argue a settled
+  answer.
+
+### Step 4 — Synthesize → roadmap(s)
+
+1. Group the accepted work — mechanical optimizations + flipped
+   decisions + structural improvements — into **one or more roadmaps by
+   concern** (keep k small; one roadmap per coherent theme, not one per
+   finding).
+2. For each group, route to [`/roadmap:create`](roadmap/create.md)
+   with a structured seed: goal, findings (with evidence), accepted
+   decisions from the interview, "further candidates" section for the
+   uninterviewed remainder.
+3. Council re-evals chosen in the interview (option 3) land as an
+   explicit first step in the matching roadmap — do NOT auto-run the
+   council from here.
+4. Regenerate the roadmap dashboard in the same reply
+   (`./agent-config roadmap:progress`) per
+   [`roadmap-progress-sync`](../../rules/roadmap-progress-sync.md).
+5. **Hand back and stop.** Per
+   [`scope-control § Authoring vs. implementation`](../../rules/scope-control.md)
+   the roadmap is the deliverable — never auto-offer
+   `/roadmap:process-*` or start executing.
+
+## Output
+
+1. **Inventory report** (Step 1) — compact counts + flagged items.
+2. **Findings report** (Step 2) — three buckets, ranked, with the
+   challenge-candidate cards.
+3. **Interview** (Step 3) — one question per turn, ≤ budget.
+4. **Roadmap file(s)** (Step 4) — the only files this command creates,
+   via `/roadmap:create`, plus the dashboard regen.
+
+## Rules
+
+- **Read-only until Step 4.** The only writes are the new roadmap
+  file(s) and the dashboard regen. No code edits, no doc rewrites, no
+  deletion — cleanup work becomes roadmap steps, not inline actions.
+- **Never edit or delete existing roadmaps / ADRs / decisions** — a
+  flipped decision becomes a roadmap step ("supersede ADR-NNN with …"),
+  never an in-place edit from this command.
+- **No commits, no push, no PR** — [`commit-policy`](../../rules/commit-policy.md).
+- **Never silently flip a lock** — [`decision-revisit-gate`](../../rules/decision-revisit-gate.md).
+- **One question per turn**, recommendation line under every options
+  block.
+- Mirror the user's language in all reports and questions.
+
+## Gotchas
+
+- **Unbounded interview** — without the question budget the
+  decision-flip loop can eat the session. The cap is load-bearing;
+  don't lift it silently.
+- **Re-litigating without new evidence** — a challenge candidate needs
+  a concrete "what changed". "I would decide differently today" is not
+  evidence; check the lock's recorded revisit-conditions first.
+- **Scope bleed into `/optimize`** — token/skill/agents-dir tooling
+  findings in package mode are reported, but their execution routes to
+  the `/optimize` cluster sub-commands inside the output roadmap.
+- **Roadmap sprawl as output** — emitting five roadmaps for one theme
+  recreates the problem this command exists to fix. Group by concern.
+- **Vendor noise** — module enumeration must come from
+  `enumerate_modules()`, never from a bare glob that catches `vendor/`.
+
+## Do NOT
+
+- Do NOT execute any of the found optimizations in this command's turn
+  — the roadmap is the deliverable.
+- Do NOT auto-run a council session; record it as a roadmap step.
+- Do NOT offer "Flip" on locked decisions — council re-eval only.
+- Do NOT create analysis files (that is `/project-analyze`); this
+  command creates roadmaps only.
+- Do NOT re-ask a settled interview answer.
+
+## See also
+
+- [`/optimize`](optimize.md) — agent-layer tooling
+  cluster (skills, agents-dir, augmentignore, rtk); cross-linked on
+  purpose — closest name, different surface.
+- [`/project-analyze`](project-analyze.md) — deep code/stack
+  analysis with analysis-file output.
+- [`/project-health`](project-health.md) — quick read-only
+  counts, no challenge loop.
+- [`/analyze:decision`](analyze/decision.md)
+  — single-decision audit; this command sweeps and hands hot ones to
+  the interview.
+- [`/challenge-me with-docs`](challenge-me/with-docs.md)
+  — the interview mechanics this command borrows, applied to a seed
+  instead of the project state.
+- [`decision-revisit-gate`](../../rules/decision-revisit-gate.md) —
+  the lock-flip discipline Step 3 enforces.

package/dist/agent-src/commands/{optimize-prompt.md → optimize/prompt.md}

@@ -4,6 +4,7 @@ name: optimize-prompt
 pack: meta
 tier: 2
 visibility: internal
+sub: prompt
 cluster: optimize
 description: "Optimize a raw prompt for ChatGPT, Claude, Gemini, or another AI via the 4-D methodology — BASIC vs DETAIL auto-detect, one clarifying question per turn, returns the polished prompt."
 skills: [prompt-optimizer]
@@ -19,7 +20,7 @@ packs:
 
 # /optimize-prompt
 
-Entry point for the [`prompt-optimizer`](../skills/prompt-optimizer/SKILL.md) skill (persona: **Lyra**). Use when the user wants a polished prompt to paste into an external AI — not when they want the answer that prompt would produce.
+Entry point for the [`prompt-optimizer`](../../skills/prompt-optimizer/SKILL.md) skill (persona: **Lyra**). Use when the user wants a polished prompt to paste into an external AI — not when they want the answer that prompt would produce.
 
 ## Welcome
 
@@ -53,7 +54,7 @@ Three input shapes:
 
 ### 2. Delegate to the skill
 
-Load [`prompt-optimizer`](../skills/prompt-optimizer/SKILL.md) and follow its `## Procedure` verbatim. The skill owns mode detection, the 4-D methodology, the output format, and gotchas.
+Load [`prompt-optimizer`](../../skills/prompt-optimizer/SKILL.md) and follow its `## Procedure` verbatim. The skill owns mode detection, the 4-D methodology, the output format, and gotchas.
 
 ### 3. Hand back
 

package/dist/agent-src/commands/optimize.md

@@ -3,18 +3,18 @@ model_tier: medium
 name: optimize
 disable-model-invocation: true
 pack: meta
-intent: "Optimization dispatcher — skills, rtk, augmentignore, agents-dir"
-routes_to: [optimize-skills, optimize-rtk, optimize-augmentignore, optimize-agents-dir]
+intent: "Optimization dispatcher — skills, rtk, augmentignore, agents-dir, project sweep, prompt"
+routes_to: [optimize-skills, optimize-rtk, optimize-augmentignore, optimize-agents-dir, optimize-project, optimize-prompt]
 replaces: []
 tier: 1
 visibility: advanced
-description: Optimize orchestrator — routes to skills, agents-dir, augmentignore, rtk-filters
+description: Optimize orchestrator — routes to skills, agents-dir, augmentignore, rtk-filters, project (project-wide sweep), prompt (AI-prompt polish)
 cluster: optimize
 type: orchestrator
 suggestion:
   eligible: true
-  trigger_description: "optimize my skills, manage agents directory, tune augmentignore, optimize rtk filters"
-  trigger_context: "maintainer auditing or trimming the agent layer (NOT AGENTS.md — that's /agents)"
+  trigger_description: "optimize my skills, manage agents directory, tune augmentignore, optimize rtk filters, optimize this project, optimize this prompt"
+  trigger_context: "maintainer auditing/trimming the agent layer, running a project-wide optimization sweep, or polishing an AI prompt (NOT AGENTS.md — that's /agents)"
 workspaces:
   - agent-config-maintainer
 packs:
@@ -23,15 +23,13 @@ packs:
 
 # /optimize
 
-Top-level orchestrator for the `/optimize` family.
+Top-level orchestrator for the `/optimize` family — spanning three scopes:
+the **agent layer** (skills, agents-dir, augmentignore, rtk), the **project**
+(`project` — challenge-and-roadmap sweep over roadmaps/ADRs/decisions), and a
+**single prompt** (`prompt`).
 
 > Looking for `AGENTS.md` operations (init, refactor, audit)? Those
 > live under [`/agents`](agents.md) (`init / optimize / audit`).
->
-> Looking for **project-wide** optimization (roadmaps, ADRs, decisions,
-> structures — challenge-and-roadmap loop)? That is the standalone
-> [`/optimize-project`](optimize-project.md) — this cluster only covers
-> the agent layer.
 
 ## Sub-commands
 
@@ -41,9 +39,11 @@ Top-level orchestrator for the `/optimize` family.
 | `/optimize agents-dir` | `commands/optimize/agents-dir.md` | Manage the `agents/` directory — `--scaffold` / `--audit` / `--fix` (interactive wizard if no flag) |
 | `/optimize augmentignore` | `commands/optimize/augmentignore.md` | Create or refine `.augmentignore` based on actual stack |
 | `/optimize rtk` | `commands/optimize/rtk.md` | Create or refine project-local rtk filters |
+| `/optimize project` | `commands/optimize/project.md` | Project-wide optimization sweep — inventory roadmaps/ADRs/agent folders, challenge stale decisions, emit new roadmap(s) |
+| `/optimize prompt` | `commands/optimize/prompt.md` | Optimize a raw prompt for ChatGPT/Claude/Gemini via the 4-D methodology |
 
 Sub-command names match the locked contract in
-[`docs/contracts/command-clusters.md`](../docs/contracts/command-clusters.md).
+[`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
 
 ## Dispatch
 
@@ -57,11 +57,16 @@ Sub-command names match the locked contract in
    > 2. agents-dir — scaffold / audit / fix the `agents/` tree
    > 3. augmentignore — create or refine `.augmentignore`
    > 4. rtk — create or refine project-local rtk filters
+   > 5. project — project-wide sweep (roadmaps, ADRs, decisions → new roadmaps)
+   > 6. prompt — polish a raw AI prompt (4-D methodology)
 
 ## Rules
 
 - **Suggest only — never auto-apply.** All `/optimize` sub-commands are
   audit-grade: they report and propose, but the user approves every change.
+- **Scope check before routing.** Agent-layer subs (1–4) never touch project
+  code or roadmaps; `project` never rewrites the agent layer; `prompt` only
+  returns a rewritten prompt.
 - **Do NOT chain sub-commands.** One `/optimize <sub>` per turn.
 - If the user invokes `/optimize` with no argument, **show the menu** — do
   not guess which sub-command they meant.

package/dist/agent-src/commands/{package-reset.md → package/reset.md}

@@ -4,6 +4,8 @@ name: package-reset
 pack: meta
 tier: 2
 visibility: internal
+sub: reset
+cluster: package
 skills: [composer, npm]
 description: /package-reset
 suggestion:

package/dist/agent-src/commands/{package-test.md → package/test.md}

@@ -1,9 +1,11 @@
 ---
 model_tier: medium
 name: package-test
-pack: engineering-base
+pack: meta
 tier: 2
 visibility: internal
+sub: test
+cluster: package
 skills: [composer, npm, python-packages, go-modules, cargo-packages]
 description: /package-test
 suggestion:

package/dist/agent-src/commands/package.md

@@ -0,0 +1,56 @@
+---
+model_tier: medium
+name: package
+disable-model-invocation: true
+pack: meta
+intent: "Package dispatcher — test the package install or reset the installed state"
+routes_to: [package-test, package-reset]
+replaces: []
+tier: 2
+visibility: internal
+description: Package orchestrator — routes to test (verify the package install) and reset (restore installed state)
+cluster: package
+type: orchestrator
+suggestion:
+  eligible: false
+  rationale: "Package-internal maintenance surface — only deliberate invocation."
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /package
+
+Top-level orchestrator for the `/package` family — maintenance of the
+agent-config package installation itself.
+
+## Sub-commands
+
+| Sub-command | Routes to | Purpose |
+|---|---|---|
+| `/package test` | `commands/package/test.md` | Test the package — verify the install/projection pipeline end-to-end |
+| `/package reset` | `commands/package/reset.md` | Reset the installed package state (destructive — confirmation-gated) |
+
+Sub-command names match the locked contract in
+[`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
+
+## Dispatch
+
+1. Parse the user's argument: `/package <sub-command> [args]`.
+2. Look up the sub-command in the table above.
+3. Load the body of the corresponding `commands/package/<sub>.md` file and
+   follow its `## Instructions` (or `## Steps`) section verbatim.
+4. If the sub-command is unknown or missing, print the menu and ask — do not
+   guess:
+
+   > 1. test — verify the package install pipeline
+   > 2. reset — reset installed package state (destructive, confirmation-gated)
+
+## Rules
+
+- **`reset` is destructive.** It never runs without the explicit confirmation
+  gate its sub-command defines.
+- **Do NOT chain sub-commands.** One `/package <sub>` per turn.
+- If the user invokes `/package` with no argument, **show the menu** — do not
+  guess which sub-command they meant.

package/dist/agent-src/commands/{project-analyze.md → project/analyze.md}

@@ -4,6 +4,8 @@ name: project-analyze
 pack: engineering-base
 tier: 2
 visibility: internal
+sub: analyze
+cluster: project
 skills: [project-analyzer]
 description: Full project analysis — detect stack, inventory modules, audit docs, create missing contexts
 suggestion:
@@ -23,7 +25,7 @@ packs:
 This is a **multi-phase, interactive analysis**. Walk through each phase, show findings,
 and ask before creating any documents.
 
-### Phase 1: Project detection
+### 1. Project detection
 
 Gather in parallel:
 - `composer.json` → PHP version, framework, key packages
@@ -92,7 +94,7 @@ Per `verbosity.routine_confirmations` (default `false`):
   > 2. Stop here — keep the overview only
   ```
 
-### Phase 2: Architecture mapping
+### 2. Architecture mapping
 
 Analyze the directory structure:
 
@@ -130,7 +132,7 @@ CODE INVENTORY:
 ═══════════════════════════════════════════════
 ```
 
-### Phase 3: Module inventory (if modules exist)
+### 3. Module inventory (if modules exist)
 
 If `enumerate_modules()` returns any modules (Laravel shape: `app/Modules/` exists), analyze each module:
 
@@ -150,7 +152,7 @@ MODULES:
 ═══════════════════════════════════════════════
 ```
 
-### Phase 4: Agent docs audit
+### 4. Agent docs audit
 
 Scan all existing agent docs:
 
@@ -177,7 +179,7 @@ AGENT DOCS AUDIT:
 ═══════════════════════════════════════════════
 ```
 
-### Phase 5: Business domains
+### 5. Business domains
 
 Identify domains from models, services, routes, and directory structure.
 For each domain: map models → services → controllers → jobs → events.
@@ -215,7 +217,7 @@ Per `verbosity.routine_confirmations` (default `false`):
 For each confirmed domain, create `agents/evidence/analysis/domains/{domain}.md` using the template
 from the `project-analyzer` skill.
 
-### Phase 6: API surface & service map
+### 6. API surface & service map
 
 List all endpoints per version. Map all services with dependencies.
 
@@ -254,7 +256,7 @@ Create:
 - `agents/evidence/analysis/api/contracts.md`
 - `agents/evidence/analysis/services/service-map.md`
 
-### Phase 7: Write analysis files
+### 7. Write analysis files
 
 Write all remaining analysis files that haven't been created yet:
 
@@ -278,7 +280,7 @@ Per `verbosity.routine_confirmations` (default `false`):
   > 2. Skip
   ```
 
-### Phase 8: Gap analysis & action plan
+### 8. Gap analysis & action plan
 
 ```
 ───────────────────────────────────────────────

package/dist/agent-src/commands/{project-health.md → project/health.md}

@@ -4,6 +4,8 @@ name: project-health
 pack: engineering-base
 tier: 2
 visibility: internal
+sub: health
+cluster: project
 skills: [quality-tools]
 description: Quick project health check — show status of docs, modules, contexts, and roadmaps without creating anything
 suggestion:

package/dist/agent-src/commands/project.md

@@ -0,0 +1,60 @@
+---
+model_tier: medium
+name: project
+disable-model-invocation: true
+pack: engineering-base
+intent: "Project dispatcher — full analysis or quick health check"
+routes_to: [project-analyze, project-health]
+replaces: []
+tier: 2
+visibility: internal
+description: Project orchestrator — routes to analyze (full audit) and health (read-only status check)
+cluster: project
+type: orchestrator
+suggestion:
+  eligible: true
+  trigger_description: "analyze this project, check the project state, how healthy is this repo"
+  trigger_context: "user asks about the project as a whole without picking full-audit vs quick-check"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /project
+
+Top-level orchestrator for the `/project` family — project-wide inspection.
+
+> Looking for a **project-wide optimization sweep** (challenge roadmaps,
+> ADRs, decisions, emit new roadmaps)? That is
+> [`/optimize project`](optimize/project.md).
+
+## Sub-commands
+
+| Sub-command | Routes to | Purpose |
+|---|---|---|
+| `/project analyze` | `commands/project/analyze.md` | Full project analysis — detect stack, inventory modules, audit docs, create missing contexts |
+| `/project health` | `commands/project/health.md` | Quick health check — status of docs, modules, contexts, roadmaps; creates nothing |
+
+Sub-command names match the locked contract in
+[`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
+
+## Dispatch
+
+1. Parse the user's argument: `/project <sub-command> [args]`.
+2. Look up the sub-command in the table above.
+3. Load the body of the corresponding `commands/project/<sub>.md` file and
+   follow its `## Instructions` (or `## Steps`) section verbatim.
+4. If the sub-command is unknown or missing, print the menu and ask — do not
+   guess:
+
+   > 1. analyze — full project audit (writes missing contexts)
+   > 2. health — read-only status check (creates nothing)
+
+## Rules
+
+- **`health` is read-only.** It never creates or modifies files; `analyze`
+  may create missing context docs and says so before writing.
+- **Do NOT chain sub-commands.** One `/project <sub>` per turn.
+- If the user invokes `/project` with no argument, **show the menu** — do not
+  guess which sub-command they meant.