@event4u/agent-config 1.21.0 → 1.22.0

package/.agent-src/templates/agent-settings.md

@@ -204,12 +204,12 @@ pipelines:
 
 # --- Roadmap execution ---
 #
-# Controls when /roadmap execute runs the project's quality pipeline.
+# Controls when /roadmap:process-* runs the project's quality pipeline.
 # Step checkboxes and the dashboard are ALWAYS updated in the same
 # response — that cadence is governed by `roadmap-progress-sync` and
 # is non-negotiable. This setting only governs *quality tool runs*.
 roadmap:
-  # When to run quality tools during /roadmap execute.
+  # When to run quality tools during /roadmap:process-step|phase|full.
   #   end_of_roadmap = once, before archiving (default — fastest, fewest tokens)
   #   per_phase      = once after every completed phase
   #   per_step       = after every completed step (legacy; highest token cost)
@@ -293,6 +293,16 @@ commands:
     # Commands to never suggest. Still work when typed explicitly.
     blocklist: []
 
+  # Pre-creation preview of the generated PR description in `/create-pr`.
+  # When `false` (default): skip the title/body preview + adjust loop;
+  # use the generated content directly to create the PR. Saves agent
+  # tokens by avoiding a re-render of the full description in chat.
+  # When `true`: show title and body in copyable code blocks and ask
+  # for adjustments before creating the PR.
+  # `/create-pr:description-only` always previews — that is its sole purpose.
+  create_pr:
+    preview_description: false
+
 # --- Telemetry (artefact engagement, default-off) ---
 #
 # Records — at task / phase-step boundaries — which artefacts (skills,
@@ -361,7 +371,7 @@ lives under `personal:` in YAML.
 | `hooks.chat_history.enabled` | `true`, `false` | `true` | Register the chat-history hooks (`append` on `after_step`, `halt_append` on `on_halt`). Gated by **both** this flag AND `chat_history.enabled`; either off → no chat-history hook registers. Schema v4: every entry self-identifies via a 16-char session fingerprint, no ownership/sidecar layer. |
 | `hooks.chat_history.script` | path | `scripts/chat_history.py` | Override path to the chat-history CLI. Set only when the script lives outside the standard location. |
 | `pipelines.skill_improvement` | `true`, `false` | `true` | When `true`: propose learning capture after meaningful tasks. When `false`: silent. Included in every profile except `custom`. |
-| `roadmap.quality_cadence` | `end_of_roadmap`, `per_phase`, `per_step` | `end_of_roadmap` | When `/roadmap execute` runs the project's quality pipeline. Default skips per-step / per-phase runs and gates only the final archival. `per_phase` runs once after every phase; `per_step` is the legacy verbose mode. Step checkboxes and the dashboard are always updated regardless. `verify-before-complete` still requires fresh output before any "roadmap complete" claim. |
+| `roadmap.quality_cadence` | `end_of_roadmap`, `per_phase`, `per_step` | `end_of_roadmap` | When `/roadmap:process-step|phase|full` runs the project's quality pipeline. Default skips per-step / per-phase runs and gates only the final archival. `per_phase` runs once after every phase; `per_step` is the legacy verbose mode. Step checkboxes and the dashboard are always updated regardless. `verify-before-complete` still requires fresh output before any "roadmap complete" claim. |
 | `subagents.implementer_model` | model alias or empty | _(empty)_ | Model for implementer subagents. Empty = same tier as session model. See [subagent-configuration](../contexts/subagent-configuration.md). |
 | `subagents.judge_model` | model alias or empty | _(empty)_ | Model for judge subagents. Empty = one tier above implementer (opus if sonnet, sonnet if haiku). |
 | `subagents.max_parallel` | integer | `3` | Maximum parallel subagent invocations. `1` serializes. |
@@ -375,6 +385,7 @@ lives under `personal:` in YAML.
 | `commands.suggestion.cooldown_seconds` | integer | `600` | Cooldown between re-suggestions of the same `(command, evidence)` pair. `600` = 10m. |
 | `commands.suggestion.max_options` | integer | `4` | Max number of command suggestions before the always-present "run as-is" option (total rendered = `max_options + 1`). |
 | `commands.suggestion.blocklist` | list of command names | `[]` | Commands that never appear as a suggestion. They still work when typed explicitly. |
+| `commands.create_pr.preview_description` | `true`, `false` | `false` | When `false`: `/create-pr` skips the title/body preview + adjust loop and uses the generated content directly. Saves agent tokens. When `true`: show title and body before creating and ask for adjustments. `/create-pr:description-only` always previews regardless of this setting. |
 | `telemetry.artifact_engagement.enabled` | `true`, `false` | `false` | Master switch for the artefact engagement log. Default-off; zero file IO and zero token cost when `false`. Maintainer-targeted; consumers leave it off. |
 | `telemetry.artifact_engagement.granularity` | `task`, `phase-step`, `tool-call` | `task` | Boundary at which events are recorded. `tool-call` is expensive — opt-in only. |
 | `telemetry.artifact_engagement.record.consulted` | `true`, `false` | `true` | When `true`: record artefacts loaded into context. |

package/.agent-src/templates/command.md

@@ -20,6 +20,11 @@ name: {command-name}
 description: {Short description of what the command does}
 disable-model-invocation: true
 skills: [{optional-skill-1}, {optional-skill-2}]
+suggestion:
+  eligible: true
+  trigger_description: "natural-language pattern, comma-separated examples"
+  trigger_context: "concrete signal — branch name, file pattern, recent tool output"
+# council_depth: deep   # uncomment for architecture/refactor/bug-diagnose commands
 ---
 
 <!-- FRONTMATTER RULES (delete this comment when done):
@@ -27,6 +32,17 @@ skills: [{optional-skill-1}, {optional-skill-2}]
   - description: short, human-readable — what the command does
   - disable-model-invocation: ALWAYS true for commands (prevents Claude from auto-invoking)
   - skills: optional — list skills this command references or delegates to
+  - suggestion: REQUIRED — drives the in-host command suggester
+    - eligible: true  → set trigger_description + trigger_context
+    - eligible: false → set rationale (why never auto-suggested)
+    See agents/contexts/command-suggestion-eligibility.md for guidance.
+  - council_depth: optional — only `deep` is accepted. **Omit the key
+    for default depth** (`standard` is the implicit default and is
+    rejected by the schema — every frontmatter byte counts). Set `deep`
+    when this command triggers AI Council on architecture, refactoring,
+    or bug-diagnosis artefacts. The host translates `deep` into
+    `--depth deep` on the council CLI, raising the round floor to
+    `ai_council.deep_min_rounds`. See .augment/skills/ai-council/SKILL.md.
 -->
 
 # /{command-name}
@@ -74,7 +90,7 @@ Ask the user:
 
 Before considering a command complete:
 
-- [ ] **Frontmatter**: has `name`, `description`, `disable-model-invocation: true`
+- [ ] **Frontmatter**: has `name`, `description`, `disable-model-invocation: true`, `suggestion` block
 - [ ] **Steps**: numbered sub-headings (`### 1.`, `### 2.`, ...)
 - [ ] **Source of truth**: works on `.agent-src.uncompressed/`, not `.agent-src/` or `.augment/`
 - [ ] **No auto-apply**: presents findings, asks before destructive changes

package/.agent-src/templates/roadmaps.md

@@ -36,14 +36,22 @@ Templates for roadmap files stored in `agents/roadmaps/` or `app/Modules/{Module
     creating the roadmap — not during execution. Default: stay on the
     current branch. If the user declines, the topic is closed for this
     roadmap. See [`scope-control`](../rules/scope-control.md#decline--silence--no-re-asking-on-the-same-task).
+15. **Declare complexity tier.** Every roadmap declares
+    `complexity: lightweight` or `complexity: structural` in frontmatter.
+    Lightweight (default): ≤ 6 phases, ≤ 600 lines, no nested council
+    debates inside the roadmap. Structural (rare, opt-in): contract-layer
+    or budget-invariant changes; multi-round council, file-ownership
+    matrices, > 600 lines. Enforced by `task lint-roadmap-complexity`.
+    Standard: [`docs/contracts/roadmap-complexity-standard.md`](../docs/contracts/roadmap-complexity-standard.md).
 
 ---
 
 ## Quality Gates (always apply at completion)
 
 Every roadmap must pass the project's quality pipeline before it is
-considered done. **When** the pipeline runs during `/roadmap execute` is
-governed by `roadmap.quality_cadence` in `.agent-settings.yml`
+considered done. **When** the pipeline runs during
+`/roadmap:process-step|phase|full` is governed by
+`roadmap.quality_cadence` in `.agent-settings.yml`
 (`end_of_roadmap` default → once before archival; `per_phase` → after
 every phase; `per_step` → after every step). Either way, a final fresh
 run is mandatory before "complete" per `verify-before-complete`.

package/.agent-src/templates/rule.md

@@ -73,6 +73,7 @@ type: "always"
 tier: "kernel"
 description: "{One-line trigger sentence — what fires this rule}"
 source: package
+# council_depth: deep   # uncomment for rules that gate architecture/refactor/bug-diagnose flows
 load_context:
   - contexts/{area}/{file}.md
 triggers:
@@ -119,6 +120,7 @@ for full detail; rules are pointers, not playbooks.}
 | `triggers` | no | Required on non-kernel rules per `rule-router.md`. |
 | `routes_to` | no | `skill:`, `guideline:`, `command:`, `contract:` targets. Forbidden on kernel rules. |
 | `alwaysApply` | no | Cursor/Cline sidecar — by convention `true` for `type: always`. |
+| `council_depth` | no | Only `deep` is accepted; **omit the key for default depth** (`standard` is the implicit default and is rejected by the schema — every frontmatter byte counts). Set `deep` when this rule gates AI Council on architecture, refactoring, or bug-diagnosis flows. Host translates to `--depth deep` on the council CLI. See `.augment/skills/ai-council/SKILL.md`. |
 
 ## Size budget
 

package/.agent-src/templates/skill.md

@@ -41,6 +41,23 @@ status: active
   See guidelines/agent-infra/runtime-layer.md for details.
 -->
 
+<!-- COUNCIL DEPTH (optional — delete this comment when done):
+  Add `council_depth: deep` to the frontmatter when this skill triggers
+  AI Council on architecture, refactoring, or bug-diagnosis artefacts.
+  The host translates `deep` into `--depth deep` on the council CLI,
+  raising the round floor to `max(ai_council.deep_min_rounds,
+  ai_council.min_rounds)`.
+
+  Only `deep` is accepted. **Omit the key for default depth** —
+  `standard` is the implicit default and is rejected by the schema
+  (every frontmatter byte counts against the context window).
+
+  Example:
+    council_depth: deep
+
+  See .augment/skills/ai-council/SKILL.md.
+-->
+
 <!-- DESCRIPTION RULES (delete this comment when done):
   - Start with "Use when..." — this is a TRIGGER, not a summary
   - Include 2-3 phrases users actually say: "create a DTO", "add column", "fix tests"

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Shared agent configuration \u2014 skills for AI coding tools (Claude Code, Augment, Cursor, Cline, Windsurf, Gemini CLI).",
-    "version": "1.21.0"
+    "version": "1.22.0"
   },
   "plugins": [
     {
@@ -42,6 +42,9 @@
         "./.claude/skills/chat-history-import",
         "./.claude/skills/chat-history-learn",
         "./.claude/skills/chat-history-show",
+        "./.claude/skills/challenge-me",
+        "./.claude/skills/challenge-me-vision",
+        "./.claude/skills/challenge-me-with-docs",
         "./.claude/skills/check-current-md",
         "./.claude/skills/check-refs",
         "./.claude/skills/code-refactoring",
@@ -109,6 +112,7 @@
         "./.claude/skills/git-workflow",
         "./.claude/skills/github-ci",
         "./.claude/skills/grafana",
+        "./.claude/skills/grill-me",
         "./.claude/skills/guideline-writing",
         "./.claude/skills/implement-ticket",
         "./.claude/skills/jira-integration",
@@ -201,9 +205,12 @@
         "./.claude/skills/review-routing",
         "./.claude/skills/rice-prioritization",
         "./.claude/skills/roadmap",
+        "./.claude/skills/roadmap-ai-council",
         "./.claude/skills/roadmap-create",
-        "./.claude/skills/roadmap-execute",
         "./.claude/skills/roadmap-management",
+        "./.claude/skills/roadmap-process-full",
+        "./.claude/skills/roadmap-process-phase",
+        "./.claude/skills/roadmap-process-step",
         "./.claude/skills/rtk-output-filtering",
         "./.claude/skills/rule-compliance-audit",
         "./.claude/skills/rule-writing",

package/AGENTS.md

@@ -168,8 +168,8 @@ appends to `agents/.rule-budget-history.jsonl`.
 ```
 .agent-src.uncompressed/      ← edit here
   skills/       (136 skills)
-  rules/        (58 rules)
-  commands/     (95 commands)
+  rules/        (59 rules)
+  commands/     (102 commands)
   personas/     (7 personas)
   templates/    (AGENTS.md, copilot-instructions.md, skill.md, …)
   contexts/

package/CHANGELOG.md

@@ -318,6 +318,44 @@ our recommendation order, not its support status.
   users" tension without removing any path that an existing user
   might rely on.
 
+## [1.22.0](https://github.com/event4u-app/agent-config/compare/1.21.0...1.22.0) (2026-05-07)
+
+### Features
+
+* **commands:** add /grill-me alias for /challenge-me + expand triggers ([d2be4ee](https://github.com/event4u-app/agent-config/commit/d2be4ee1a97d2ca2374c6543e0fd908eca0a0f1a))
+* **challenge-me:** add !roadmap and !ai triggers ([7bfbd69](https://github.com/event4u-app/agent-config/commit/7bfbd6943852d781ca7ad29e51750de24d3ef413))
+* **create-pr:** default to skipping description preview to save tokens ([80e77ae](https://github.com/event4u-app/agent-config/commit/80e77aed76a13c26fac8316bc5d58a3533dbbe44))
+* **council:** add critical-evaluation stance for council findings ([7e2524b](https://github.com/event4u-app/agent-config/commit/7e2524b75fd84ca4b6afb6deae0b8777e8b81ac7))
+* **council:** add /roadmap:ai-council deep-tier sub-command ([c5933e4](https://github.com/event4u-app/agent-config/commit/c5933e4b2301a0f9d1c116d2843ed4953bd92163))
+* replace /roadmap-execute with autonomous /roadmap:process-* cluster ([9d4ffd0](https://github.com/event4u-app/agent-config/commit/9d4ffd0815fb7923b337bfd0b3847d9bc5a01e54))
+* **council:** mark architecture/refactor/bug-diagnose artefacts as deep ([6f903c1](https://github.com/event4u-app/agent-config/commit/6f903c194e4bc54512e93a32e1876e84d0292401))
+* **council:** add deep reasoning depth tier with schema enforcement ([f4efd7a](https://github.com/event4u-app/agent-config/commit/f4efd7a11b9d57e93153e6e4605c968565c8924d))
+* **linter:** require suggestion block on commands ([231df91](https://github.com/event4u-app/agent-config/commit/231df918b2d15ea9cc2fa8fe12bae4c2482990df))
+* add --siblings council mode and refine convener wording ([9075647](https://github.com/event4u-app/agent-config/commit/9075647ba520efb5f10ab7612970111e9f9d16e9))
+* add PRD template to technical-specification ([f9ee749](https://github.com/event4u-app/agent-config/commit/f9ee7496434f9342d6b46b95dce14c4703d07d96))
+* add 6-phase loop checklist to systematic-debugging ([29c9e94](https://github.com/event4u-app/agent-config/commit/29c9e9419c9d08dd93c4fc7364e51b93bc771131))
+* add invite-challenge rule for pre-execution goal restatement ([e96da5f](https://github.com/event4u-app/agent-config/commit/e96da5fdf124da3582e454fc625fe32a27ada634))
+* add /challenge-me cluster with vision and with-docs sub-commands ([74481ef](https://github.com/event4u-app/agent-config/commit/74481ef7e7850d3e015ff0f9853be6ea618ac1d9))
+
+### Documentation
+
+* **roadmap:** drop council-response file links per no-council-references ([d792100](https://github.com/event4u-app/agent-config/commit/d792100ef6b2727cca1338c89fefc4c591513265))
+* **readme:** bump hero command count from 100 to 102 ([3212db4](https://github.com/event4u-app/agent-config/commit/3212db48fb1d62a70f9e87cf9307ee73059b7e4e))
+* **roadmap:** integrate R5 council verdict for caveman-insurance ([38b26e2](https://github.com/event4u-app/agent-config/commit/38b26e2f00504a7c6c821c356964cb0cabefd905))
+* **roadmap:** incorporate R4 verdict + structural findings into caveman integration ([c50f39b](https://github.com/event4u-app/agent-config/commit/c50f39bc9b08c8d59c4cf547aeec7fffbff38bc0))
+* **roadmap:** convert caveman integration Phase 2 to hard cutover ([fb459be](https://github.com/event4u-app/agent-config/commit/fb459be70a093eea1814a38a3b1fec9cf9261363))
+* **harvest:** add Superpowers harvest roadmap, hardened by council R2 ([e559259](https://github.com/event4u-app/agent-config/commit/e559259f789014603067e87141d9feb815b480ab))
+* **harvest:** analyze obra/superpowers v5.1.0 for adoption candidates ([e89e0ee](https://github.com/event4u-app/agent-config/commit/e89e0eeadc4b76517b181c559422e88df5c8122a))
+* **council:** document council_depth frontmatter convention in templates ([ba56412](https://github.com/event4u-app/agent-config/commit/ba56412c76204bbe49366bbceb62e4d31c994fc2))
+
+### Chores
+
+* **sync:** re-sync compressed mirror with create-pr preview-gate + agent-settings preview_description ([ceab79e](https://github.com/event4u-app/agent-config/commit/ceab79e23be2c1d4ba504b80426d1b91ffdaadd1))
+* bump artefact counts and refresh compression hashes ([2801342](https://github.com/event4u-app/agent-config/commit/28013424668177fc23df45cc56390faba6fd010e))
+* regenerate tool-dir symlinks for challenge-me and invite-challenge ([b3b0ada](https://github.com/event4u-app/agent-config/commit/b3b0ada9ce108b220289c9f044b3f3d0209f0a12))
+* bump artefact counts and refresh compression hashes ([4147de3](https://github.com/event4u-app/agent-config/commit/4147de3b4da24494128a847be194ac901e506df9))
+* sync compressed projection for challenge-me cluster ([9165762](https://github.com/event4u-app/agent-config/commit/91657620e6d822fbe28923e3b008e218f13e5cea))
+
 ## [1.21.0](https://github.com/event4u-app/agent-config/compare/1.20.0...1.21.0) (2026-05-06)
 
 ### Features

package/README.md

@@ -7,7 +7,7 @@ Give your AI agents an audit-disciplined orchestration contract — testing, Git
 > Your agent picks up the project's stack, runs tests, prepares PRs, fixes CI — and follows your team's coding standards while doing it. Stack-aware skill sets ship for PHP (Laravel · Symfony · Zend/Laminas), JavaScript (Next.js · React · Node), and cross-stack concerns (API · testing · security · observability).
 
 <p align="center">
-  <strong>136 Skills</strong> · <strong>58 Rules</strong> · <strong>95 Commands</strong> · <strong>56 Guidelines</strong> · <strong>8 AI Tools</strong>
+  <strong>136 Skills</strong> · <strong>59 Rules</strong> · <strong>102 Commands</strong> · <strong>56 Guidelines</strong> · <strong>8 AI Tools</strong>
 </p>
 
 ---

package/config/agent-settings.template.yml

@@ -238,6 +238,16 @@ ai_council:
   # invocation (or `--rounds N` to the CLI) to override.
   min_rounds: 2
 
+  # Higher floor for deep-reasoning artefacts (architecture review,
+  # refactoring proposals, bug-diagnosis runs). Activated when the
+  # consuming rule, skill, or command declares `council_depth: deep`
+  # in its frontmatter, or the user passes `--depth deep` to the CLI.
+  # Effective rounds = max(deep_min_rounds, min_rounds), so this floor
+  # is monotonic — lowering it below `min_rounds` has no effect.
+  # Standard tasks keep `min_rounds`; cost rises only when an artefact
+  # opts in. Set to `min_rounds` to disable the deep tier.
+  deep_min_rounds: 3
+
   # Hard cost ceiling per /council invocation. The orchestrator pauses
   # before any member whose projected spend would breach a cap and asks
   # the user to continue. `max_total_usd: 0` disables the USD ceiling
@@ -298,3 +308,15 @@ commands:
     # Commands to never suggest. Still work when typed explicitly.
     # Example: ["/refine-ticket", "/work"]
     blocklist: []
+
+  # --- /create-pr behavior ---
+  #
+  # Pre-creation preview of the generated PR description.
+  # false (default): skip the title/body preview + adjust loop in
+  # /create-pr; use the generated content directly. Saves agent tokens
+  # by avoiding a re-render of the full description in chat.
+  # true: show title and body in copyable code blocks and ask for
+  # adjustments before creating the PR.
+  # /create-pr:description-only always previews — that is its sole purpose.
+  create_pr:
+    preview_description: false

package/docs/architecture.md

@@ -97,8 +97,8 @@ fails on any source-side violation, without producing artifacts.
 | Layer | Count | Purpose |
 |---|---|---|
 | **Skills** | 136 | On-demand expertise — stack analysis (Laravel · Symfony · Zend / Laminas · Next.js · React · Node), testing, Docker, API design, security, observability, … |
-| **Rules** | 58 | Always-active constraints — coding standards, scope control, verification, language-and-tone, agent-authority |
-| **Commands** | 95 | Slash-command workflows — `/commit`, `/create-pr`, `/fix ci`, `/optimize skills`, `/feature plan`, `/work`, `/implement-ticket`, `/compress`, … |
+| **Rules** | 59 | Always-active constraints — coding standards, scope control, verification, language-and-tone, agent-authority |
+| **Commands** | 102 | Slash-command workflows — `/commit`, `/create-pr`, `/fix ci`, `/optimize skills`, `/feature plan`, `/work`, `/implement-ticket`, `/compress`, … |
 | **Guidelines** | 56 | Reference material cited by skills — PHP patterns, Eloquent, Playwright, agent-infra, … |
 | **Templates** | 7 | Scaffolds for features, roadmaps, contexts, skills, overrides |
 | **Contexts** | 5 | Shared knowledge about the system itself |

package/docs/contracts/command-clusters.md

@@ -33,7 +33,7 @@ column 1 of this table.
 | `chat-history` | 2 | `show` · `import` · `learn` | `chat-history` (legacy status) — `resume` / `clear` / `checkpoint` removed in `road-to-chat-history-hook-only` (auto-adopt + structural hooks); `import` (verbatim cross-session render) and `learn` (project-improving learning extraction) added in the v4 stateless schema |
 | `agents` | 2 | `audit` · `cleanup` · `prepare` | `agents-audit` · `agents-cleanup` · `agents-prepare` |
 | `memory` | 2 | `add` · `load` · `promote` · `propose` | `memory-add` · `memory-full` · `memory-promote` · `propose-memory` |
-| `roadmap` | 2 | `create` · `execute` | `roadmap-create` · `roadmap-execute` |
+| `roadmap` | 2 | `create` · `ai-council` · `process-step` · `process-phase` · `process-full` | `roadmap-create` · `roadmap-execute` (replaced — autonomous, no per-step gate; `process-phase` is the default execution scope); `ai-council` added 2026-05-07 — wraps `/council default` with `--input-mode roadmap --depth deep` |
 | `module` | 2 | `create` · `explore` | `module-create` · `module-explore` |
 | `tests` | 2 | `create` · `execute` | `tests-create` · `tests-execute` |
 | `context` | 2 | `create` · `refactor` | `context-create` · `context-refactor` |
@@ -43,6 +43,7 @@ column 1 of this table.
 | `commit` | 2 | `in-chunks` | `commit-in-chunks` |
 | `create-pr` | 2 | `description-only` | `create-pr-description` |
 | `council` | 3 | `default` · `pr` · `design` · `optimize` | `council` (legacy default lens) · `council-pr` · `council-design` · `council-optimize` |
+| `challenge-me` | — | `vision` · `with-docs` | new — Pocock-inspired one-question-at-a-time interview; `vision` is the standard 95%-confidence variant, `with-docs` adds doc/glossary awareness with a session-scoped glossary and load-bearing claim-vs-code verification |
 
 **Net change:** Phase 1 collapsed 15 atomics → 3 clusters; Phase 2
 collapses 26 atomics → 11 sub-command clusters. Sub-commands use
@@ -51,6 +52,49 @@ autocomplete them. The standalone `/review` surface that mirrors
 `judge solo` lives at
 [`commands/review-changes.md`](../../.agent-src.uncompressed/commands/review-changes.md).
 
+## Cluster depth and sub-command naming
+
+Locked by [ADR-003](../decisions/ADR-003-flat-cluster-subs-and-colon-syntax.md)
+(2026-05-07). The shape is the default for **every** new cluster and
+every new sub-command added to an existing cluster.
+
+1. **Flat only.** A cluster has exactly one level of sub-commands.
+   No sub-sub-commands. A dispatcher routes `/cluster <sub>` to a
+   single sub-file; sub-files do not dispatch further. Two-level
+   dispatch is a deliberate contract change requiring a new ADR
+   superseding ADR-003.
+
+2. **Composite sub-names for verb+scope.** When a cluster carries
+   multiple verbs (e.g. authoring + execution), encode the verb in
+   the sub-name, joined with `-`:
+
+   - ✅ `/roadmap:create` · `/roadmap:process-step` ·
+     `/roadmap:process-phase` · `/roadmap:process-full`
+   - ❌ `/roadmap:process:phase` (sub-sub — forbidden)
+   - ❌ `/roadmap:step` · `/roadmap:phase` · `/roadmap:full`
+     (verb hidden — breaks symmetry with `create`)
+   - ❌ separate `/roadmap-process` cluster (domain split — forbidden
+     when one cluster can carry both verbs flat)
+
+   Sibling sub-names stay in the same shape: either all bare verbs,
+   all bare nouns/scopes, or all composite. Mixing bare and composite
+   in the same cluster is allowed only when the bare sibling is the
+   cluster's primary verb (e.g. `/roadmap:create` + `process-*`
+   composites).
+
+3. **Sub-name format.** kebab-case (`pr-bots`, `process-phase`),
+   ≤ 24 chars, no leading verb that duplicates the cluster name
+   (use `/fix:ci`, not `/fix:fix-ci`).
+
+4. **Colon-canonical invocation.**
+   `/<cluster>:<sub>` is the canonical form everywhere — catalog,
+   docs, examples, deprecation warnings. The space-separated form
+   `/<cluster> <sub>` is a first-class equivalent and routes to the
+   same dispatcher; it must keep working. Autocompletion-aware UIs
+   surface the colon form because it stays a single token. Full
+   semantics: [`slash-command-routing-policy-mechanics.md`](../../.agent-src.uncompressed/contexts/communication/rules-auto/slash-command-routing-policy-mechanics.md)
+   § Routing semantics.
+
 ## Frontmatter contract
 
 A new command file under `.agent-src.uncompressed/commands/` MUST

package/docs/decisions/ADR-003-flat-cluster-subs-and-colon-syntax.md

@@ -0,0 +1,126 @@
+# ADR-003 — Flat Cluster Sub-Commands and Colon-Canonical Invocation
+
+- **Status:** Accepted (2026-05-07)
+- **Phase:** Command-cluster contract (Phase 2 follow-up)
+- **Supersedes:** none — extends the locked cluster set in
+  `docs/contracts/command-clusters.md`.
+- **Related:** `roadmap-process` migration (2026-05-07) — the trigger
+  that forced the decision; `contexts/execution/roadmap-process-loop.md`
+  (the shared mechanics extracted alongside).
+
+## Context
+
+`roadmap-execute` was being replaced by an autonomous-execution surface
+with three scopes: single step, single phase, full roadmap. The
+question was where those three commands live in the cluster catalog.
+Four shapes were on the table:
+
+- **A — separate `/roadmap-process` cluster.** Two top-level clusters
+  (`/roadmap` for authoring, `/roadmap-process` for execution).
+- **B — sub-sub-commands** (`/roadmap:process:phase`). One cluster,
+  two-level dispatch.
+- **C — flat under `/roadmap`, no verb** (`/roadmap:step` ·
+  `/roadmap:phase` · `/roadmap:full`). Verb hidden in cluster
+  description.
+- **D — flat under `/roadmap`, verb fused with scope**
+  (`/roadmap:process-step` · `/roadmap:process-phase` ·
+  `/roadmap:process-full`). One cluster, one dispatch level, composite
+  sub-name carries the verb.
+
+Existing infrastructure assumed a single dispatch level: the contract
+table at `docs/contracts/command-clusters.md`, the linter
+`scripts/lint_no_new_atomic_commands.py`, and the dispatcher-shape
+checker `scripts/check_cluster_patterns.py` all parse one column of
+sub-names per cluster.
+
+## Decision
+
+1. **Cluster depth stays flat.** A cluster has exactly one level of
+   sub-commands. No sub-sub-commands. Option B is rejected.
+
+2. **Verb-and-scope sub-commands use a composite name** joined by `-`
+   (`process-step`, `process-phase`, `process-full`). The verb stays
+   visible in the autocomplete list; symmetry with sibling
+   sub-commands (`/roadmap:create`) is preserved as
+   verb-or-noun-per-sub. Option D wins over C.
+
+3. **Colon is the canonical invocation form** (`/<cluster>:<sub>`).
+   The space-separated form (`/<cluster> <sub>`) remains a
+   first-class equivalent — both forms route to the same dispatcher.
+   Autocompletion-aware UIs (Claude Code picker, IDE slash-menus,
+   shell completers) MUST surface the colon form because it stays a
+   single token.
+
+4. **Future verb+scope clusters follow the same shape.** Any future
+   cluster with multiple verbs (e.g. an authoring verb and an
+   execution verb) uses composite sub-names rather than introducing a
+   second cluster or a second dispatch level.
+
+## Rationale
+
+- **Option A (separate cluster)** scatters one domain across two
+  top-level surfaces. Users have to remember which cluster owns
+  which verb; the catalog grows without adding capability.
+- **Option B (sub-sub)** would be the first two-level dispatcher in
+  the repo. Cost: contract change in `command-clusters.md`,
+  linter change in `lint_no_new_atomic_commands.py` (parse a second
+  column), pattern-checker change in `check_cluster_patterns.py`
+  (allow nested dispatch sections), plus an ADR to set the precedent
+  — for a cohesion benefit that Option D delivers at zero
+  architectural cost.
+- **Option C (no verb)** breaks symmetry: `/roadmap:create` is a
+  verb, `/roadmap:phase` is a scope. The mental model becomes
+  inconsistent in the same cluster.
+- **Option D (composite verb-scope)** keeps the cluster flat, keeps
+  the verb visible, costs nothing in the linter or contract
+  parser (one row, four sub-names, kebab-case as before), and
+  scales to any future verb+scope cluster.
+
+The colon form was already canonical for flag-clusters
+(`/commit:in-chunks`, `/create-pr:description-only`). Promoting it
+to the canonical form for dispatcher-clusters too unifies the
+catalog: every sub-command is a single token.
+
+## Consequences
+
+- **Pro:** Zero architectural cost. The locked contract, both
+  linters, the dispatcher pattern checker, and the routing rule all
+  keep working unchanged. The cluster row in
+  `docs/contracts/command-clusters.md` extends with three new
+  sub-names.
+- **Pro:** Single-token autocompletion across the entire command
+  surface. Greppable in chat history and logs.
+- **Pro:** Domain cohesion — `/roadmap:*` covers the full
+  authoring + execution lifecycle.
+- **Con:** Sub-names get longer when the verb is non-obvious from the
+  cluster. `/roadmap:process-phase` is 24 chars vs.
+  `/roadmap-process:phase` (Option A, 23 chars) or
+  `/roadmap:phase` (Option C, 16 chars). Acceptable trade for
+  symmetry and zero contract churn.
+- **Con:** A cluster cannot grow into a true two-level surface
+  without revisiting this ADR. Rolling back to Option B is the
+  escape hatch if a future cluster genuinely needs nested verbs.
+
+## Rollback
+
+If a future cluster grows past ~8 sibling sub-commands and the
+composite-name pattern produces ambiguous or unreadable
+sub-commands, revisit by:
+
+1. Splitting the cluster into two flat clusters (Option A on a
+   case-by-case basis), or
+2. Introducing sub-sub-commands as a deliberate contract change —
+   updating `command-clusters.md`, `lint_no_new_atomic_commands.py`,
+   `check_cluster_patterns.py`, and superseding this ADR.
+
+Both moves are reversible. This ADR locks the default, not the
+ceiling.
+
+## See also
+
+- [`docs/contracts/command-clusters.md`](../contracts/command-clusters.md)
+  — locked cluster set + sub-command naming contract.
+- [`.agent-src.uncompressed/contexts/communication/rules-auto/slash-command-routing-policy-mechanics.md`](../../.agent-src.uncompressed/contexts/communication/rules-auto/slash-command-routing-policy-mechanics.md)
+  — runtime routing semantics and the colon-canonical rule.
+- [`.agent-src.uncompressed/contexts/execution/roadmap-process-loop.md`](../../.agent-src.uncompressed/contexts/execution/roadmap-process-loop.md)
+  — the shared mechanics that motivated the cluster shape.

package/docs/getting-started.md

@@ -115,7 +115,7 @@ Your agent is now:
 - **Respecting your codebase** — no conflicting patterns
 - **Following standards** — consistent code quality
 
-This is enforced automatically by 58 rules. No configuration needed.
+This is enforced automatically by 59 rules. No configuration needed.
 
 ---
 

package/docs/guidelines/agent-infra/naming.md

@@ -41,7 +41,7 @@ source: package
 | Pattern | When | Examples |
 |---|---|---|
 | `{verb}-{target}` | Action commands | `create-pr`, `fix-ci`, `commit` |
-| `{target}-{verb}` | Target-first grouping | `roadmap-create`, `roadmap-execute` |
+| `{target}-{verb}` | Target-first grouping | `roadmap-create` (legacy atomic; current cluster form is `/roadmap:create` and `/roadmap:process-step|phase|full`) |
 | `{scope}-{action}` | Scoped actions | `optimize-agents`, `review-changes` |
 
 ### Guidelines

package/package.json

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

package/scripts/_phase2_shim_helper.py

@@ -25,7 +25,7 @@ PHASE2_SHIMS: list[tuple[str, str]] = [
     ("propose-memory", "memory propose"),
     # roadmap cluster
     ("roadmap-create",  "roadmap create"),
-    ("roadmap-execute", "roadmap execute"),
+    ("roadmap-execute", "roadmap process-phase"),
     # module cluster
     ("module-create",  "module create"),
     ("module-explore", "module explore"),