@event4u/agent-config 5.10.1 → 6.1.0

package/dist/agent-src/commands/roadmap/ai-council.md

@@ -0,0 +1,190 @@
+---
+model_tier: inherit
+name: roadmap-ai-council
+pack: product-basic
+tier: 2
+visibility: internal
+cluster: roadmap
+sub: ai-council
+skills: [ai-council, agent-docs-writing, roadmap-management]
+description: Challenge a roadmap with the AI council (deep tier) and refactor from convergence findings. Wraps `/council default` pinned to `--input-mode roadmap --depth deep`; patches surface as numbered options.
+council_depth: deep
+suggestion:
+  eligible: true
+  trigger_description: "council on roadmap, challenge this roadmap, stress-test the plan, refactor roadmap from council findings"
+  trigger_context: "existing agents/roadmaps/*.md the user wants reviewed before execution"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /roadmap:ai-council
+
+Council-driven challenge + refactor scope of the
+[`/roadmap`](../roadmap.md) cluster. Pins the input mode to
+`roadmap` and the depth tier to `deep` (architecture / refactor
+artefact), then drives the user through applying convergence
+findings as numbered patches against the roadmap file.
+
+**Source of truth:** `.agent-src.uncondensed/` — never read or edit
+`dist/agent-src/` or `.augment/` directly.
+
+## Instructions
+
+### 1. Resolve the target roadmap
+
+Parse the argument as a roadmap path or filename:
+
+- `/roadmap:ai-council agents/roadmaps/<name>.md` — explicit path.
+- `/roadmap:ai-council <name>` — fuzzy match against
+  `agents/roadmaps/*.md`; if multiple match, list and ask
+  (one question per turn per `ask-when-uncertain`).
+- No argument → list `agents/roadmaps/*.md` and ask.
+
+Capture the **original ask** verbatim — the user's framing sentence
+that triggered this council run (e.g. *"review this roadmap before
+I execute it"*). This flows into `--original-ask`.
+
+### 2. Run the `/council default` flow with these pinned flags
+
+Follow [`/council default`](../council/default.md) Steps 2–4
+**verbatim**, with these arguments fixed:
+
+- `--input-mode roadmap`
+- `--depth deep` (this command declares `council_depth: deep` in
+  frontmatter; the host translates it into `--depth deep`)
+- `--output agents/runtime/council/responses/<roadmap-stem>-roadmap.json`
+  (overwrite if it exists; the previous run is the predecessor for
+  this iteration)
+- `--original-ask "<captured-ask>"`
+
+`--depth deep` floors rounds at
+`max(ai_council.deep_min_rounds, ai_council.min_rounds)` (default
+`3`). Do **not** pass `--rounds` unless the user explicitly asked
+for a different count.
+
+The cost gate from `/council default` Step 3 still applies — billable
+members require user confirmation **even under `personal.autonomy: on`**
+(per the deep tier surcharge — typical cost ~$0.05–0.13 vs. ~$0.02
+for the standard tier).
+
+### 3. Render the report
+
+Run `./agent-config council:render <output.json>` and write the
+**Convergence / Divergence** section per
+[`/council default § Render`](../council/default.md). Do **not** end
+with `/council default`'s generic numbered-options block — the
+refactor flow in Step 4 replaces it.
+
+### 4. Append a Council review block to the roadmap
+
+Open the roadmap file and append (do **not** overwrite existing
+content):
+
+```markdown
+
+## Council review (<UTC date>)
+
+<Convergence section verbatim>
+
+### Convergence findings
+
+1. **<Finding 1 title>** — <one-line summary> · trace: §<member-section>
+2. **<Finding 2 title>** — <one-line summary> · trace: §<member-section>
+…
+
+### Divergences (no consensus)
+
+- **<Topic>** — <Member A says X, Member B says Y; user decides>
+
+### Predecessor council trace
+
+`agents/runtime/council/responses/<roadmap-stem>-roadmap.json` (this run).
+```
+
+Run `./agent-config roadmap:progress` after the append. The block
+adds no `[ ]` checkboxes, so the dashboard counts stay flat.
+
+### 5. Apply the critical-evaluation lens, then surface verdicted patches
+
+Before drafting any patch, run every finding from Step 4 through the
+*Critical evaluation* checklist from the
+[`ai-council` skill](../../skills/ai-council/SKILL.md#critical-evaluation--convener-skeptic-stance):
+
+- **Codebase fit** — does the finding match the actual roadmap content, file paths, scripts, contracts cited in the roadmap? (`view` / `codebase-retrieval`)
+- **Locked-decision conflict** — does it contradict an ADR (`docs/decisions/`), a contract (`docs/contracts/`), a kernel rule, or an earlier locked decision in **this** roadmap?
+- **Already addressed** — is the finding already covered by an existing step, AC, or phase in the roadmap?
+- **Cost / benefit** — does the patch's scope vs. roadmap value clear the bar?
+- **Hallucination** — does the finding cite a file, function, phase, or step that does not exist?
+
+For every finding, attach a verdict — **`accept`**, **`accept-with-modification`**, **`reject`**, or **`needs-input`** — with a one-line reason citing host evidence (file:line, ADR, contract, roadmap step).
+
+Append a **Host verdict** sub-block under the Council review block in the roadmap:
+
+```markdown
+### Host verdict
+
+| # | Finding | Verdict | Reason |
+|---|---|---|---|
+| 1 | <one-line> | `accept` | matches `agents/roadmaps/<this>.md` Phase X step Y |
+| 2 | <one-line> | `accept-with-modification` | narrow scope to phase Z — global change contradicts AC §N |
+| 3 | <one-line> | `reject` | contradicts ADR `docs/decisions/<adr>.md` |
+| 4 | <one-line> | `needs-input` | open question — user picks below |
+```
+
+Then surface a single numbered-options block per [`user-interaction`](../../rules/user-interaction.md), carrying the verdict per option:
+
+> 1. `[accept]` Apply finding 1 — <one-line patch summary>
+> 2. `[accept-with-modification]` Apply finding 2 (modified) — <one-line patch summary + adjustment>
+> 3. `[reject]` Skip finding 3 — <one-line reason> (override available below)
+> 4. `[needs-input]` <open question for finding 4>
+> …
+> N. Apply all `accept` findings (recommended only if non-conflicting)
+> N+1. Override host verdict — apply a finding the host rejected (specify number)
+> N+2. Skip — leave Council review block + Host verdict as advisory only
+
+The user picks one or more numbers (`1,3,5` is allowed). Apply each selected patch via `str-replace-editor` against the roadmap, then re-run `./agent-config roadmap:progress` once at the end so the dashboard reflects the new step / AC count.
+
+**Verdict ≠ filter.** Every finding stays visible in the Host verdict block with its verdict and reason — the user can override at any time. The host filters its **own** recommendation; it does not hide council output.
+
+### 6. Hard floor — text + roadmap edits only
+
+`/roadmap:ai-council` may:
+
+- write `agents/runtime/council/responses/<…>.json`
+- append the Council review block to the named roadmap
+- apply user-picked patches to the same roadmap
+- regenerate `agents/roadmaps-progress.md`
+
+It does **NOT**:
+
+- edit any other roadmap, command, rule, or skill file
+- commit, push, or open a PR
+- run `git` beyond `git diff` (read-only)
+
+## Rules
+
+- **One roadmap per invocation.** Re-run for the next file.
+- **Critical evaluation is mandatory** — every council finding gets
+  a host verdict (`accept` / `accept-with-modification` / `reject` /
+  `needs-input`) with one-line evidence before any patch is drafted.
+  Convergence ≠ correctness; the council never saw the codebase. See
+  [`ai-council § Critical evaluation`](../../skills/ai-council/SKILL.md#critical-evaluation--convener-skeptic-stance).
+- **Decline = silence** ([`scope-control`](../../rules/scope-control.md)) —
+  if the user picks "Skip — advisory only", the Council review block
+  + Host verdict stay in the roadmap, but no patches are applied. Do
+  not re-ask the question on the same task.
+- **Cost gate is non-negotiable** — the deep tier costs more than
+  standard; confirm before every billable run, even with
+  `personal.autonomy: on`.
+- **No commit.** Patches land in the working tree only; commit
+  decisions stay with the user per
+  [`commit-policy`](../../rules/commit-policy.md).
+
+## See also
+
+- [`/roadmap`](../roadmap.md) — cluster orchestrator
+- [`/council default`](../council/default.md) — base flow this command wraps
+- [`ai-council`](../../skills/ai-council/SKILL.md) — neutrality, redaction, deep tier
+- [`scripts/council_cli.py`](../../../scripts/council_cli.py) — CLI entry point

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

@@ -0,0 +1,215 @@
+---
+model_tier: inherit
+name: roadmap-create
+pack: product-basic
+tier: 2
+visibility: internal
+cluster: roadmap
+sub: create
+skills: [agent-docs-writing]
+description: Interactively create a new roadmap file in agents/roadmaps/
+suggestion:
+  eligible: true
+  trigger_description: "create a roadmap for X, plan this work as a roadmap"
+  trigger_context: "multi-phase work without an existing agents/roadmaps/*.md"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /roadmap create
+## Instructions
+
+### 1. Determine location
+
+Ask the user (in their language) where the roadmap should be created:
+
+> 1. Project root (`agents/roadmaps/`)
+> 2. In a module (`{module_root}/{Name}/{agent_folder}/roadmaps/`)
+
+If the user picks a module → resolve module roots via
+`scripts/_lib/agent_settings.py::enumerate_modules()`, list available
+modules from `modules.root_paths`, and ask which one. The target
+directory is `{module_path}/{modules.agent_folder}/roadmaps/`
+(default `agent_folder` = `agents`).
+Create the `roadmaps/` directory if it doesn't exist at the chosen location.
+
+### 2. Read the roadmap template
+
+- Read `.augment/templates/roadmaps.md` for the roadmap structure.
+- Use its structure as the basis for the new roadmap.
+
+### 3. Gather content interactively
+
+Ask the user (in their language) step by step:
+
+1. **Title / goal**: What is the goal of this roadmap? (one sentence)
+2. **Context**: What context is important? (module, affected classes, Jira tickets, etc.)
+3. **Phases**: What phases does the roadmap have? (e.g. "Phase 1: Preparation, Phase 2: Migration, Phase 3: Cleanup")
+4. For each phase → What steps belong in Phase {N}?
+
+After each input, show what you've captured and ask the user (in their language) to confirm or adjust.
+
+**Important:** The user may answer in any language, but the roadmap file must be written in **English**.
+Translate user input to English when writing the file.
+
+### 4. Build the roadmap file
+
+Use the template structure:
+
+```markdown
+# Roadmap: {title}
+
+> {One sentence goal}
+
+## Prerequisites
+
+- [ ] Read `AGENTS.md` and relevant module docs
+- [ ] {any specific prerequisites}
+
+## Context
+
+{Context from user input}
+
+## Phase 1: {name}
+
+- [ ] **Step 1:** {description}
+- [ ] **Step 2:** {description}
+- [ ] ...
+
+## Phase 2: {name}
+
+- [ ] **Step 1:** {description}
+- [ ] ...
+
+## Acceptance Criteria
+
+- [ ] {criteria}
+- [ ] All quality gates pass (PHPStan, Rector, tests)
+
+## Notes
+
+{Optional notes}
+```
+
+### 5. Review loop
+
+Show the complete roadmap to the user and ask (in their language) if anything should be added or changed.
+
+- If yes → apply changes, show again.
+- Repeat until the user says it's done.
+
+### 6. Save the file
+
+- Generate a filename from the title: kebab-case, e.g. `optimize-webhook-jobs.md`.
+
+**Before saving, check for filename collisions across the entire
+roadmap namespace** — active, `archive/`, `skipped/`, and any nested
+subdirs (e.g. `agent-memory/`). A new roadmap that shadows an
+archived or skipped one silently buries history; never overwrite,
+never auto-suffix without the user's pick.
+
+```bash
+NAME="<kebab-case-name>.md"
+# Project-root roadmaps:
+find agents/roadmaps -type f -iname "$NAME" 2>/dev/null
+# Module-scoped roadmaps (only if step 1 picked a module):
+# resolve <ModuleRoot>/<Module>/<AgentFolder>/roadmaps/ via enumerate_modules()
+find <ModuleRoot>/<Module>/<AgentFolder>/roadmaps -type f -iname "$NAME" 2>/dev/null
+```
+
+Use `-iname` (case-insensitive) so case-only differences still count
+as a collision on case-sensitive filesystems.
+
+If the search returns one or more hits → **STOP**. Show the matches
+and ask (in the user's language):
+
+> Found N existing roadmap(s) with this name:
+>   - `agents/roadmaps/archive/<file>.md` (archived)
+>   - `agents/roadmaps/skipped/<file>.md` (skipped)
+>
+> 1. Pick a different name — suggest `<name>-v2`, `<name>-<scope>`, or `<name>-<YYYY-MM>`
+> 2. Open the existing file first — revival or extension may be the right move
+> 3. Abort creation
+
+- **1** → re-prompt for name, re-run the collision check, repeat until clean.
+- **2** → read the existing roadmap, summarize state, hand back to the user.
+- **3** → stop without writing anything.
+
+Only when the search is empty: save to the chosen location and show the final path.
+
+### 7. Update the progress dashboard
+
+Regenerate `agents/roadmaps-progress.md` so the new roadmap shows up:
+
+```bash
+./agent-config roadmap:progress
+```
+
+Mention the new overall count to the user.
+
+### 8. Offer council review (B1 hook, verbosity-gated)
+
+Read `verbosity.offer_council_in_delivery` from `.agent-settings.yml`
+(default `false`):
+
+- `false` (default): skip the prompt silently. When `ai_council.enabled:
+  true` AND at least one member enabled, emit one line: `→ council
+  skipped (set verbosity.offer_council_in_delivery: true to enable, or
+  run /council roadmap:<path> directly)`. Otherwise emit nothing.
+- `true`: when `ai_council.enabled: true` **and** at least one member
+  enabled (`anthropic` or `openai`), ask (in the user's language):
+
+  > 1. Run the council on this roadmap before execution? (billable)
+  > 2. Skip council review
+
+  Also suppress when `personal.autonomy: on` (council is billable; see
+  `road-to-ai-council.md` Decision 3 / Q47).
+
+If the user picks **1**:
+
+- Run `/council roadmap:<path>` with the user's original ask captured
+  in step 1 as `original_ask` (the handoff preamble carries it
+  verbatim, see `scripts/ai_council/prompts.py`).
+- Append the council findings as a `## Council review (<UTC date>)`
+  section at the bottom of the roadmap. Include the trace path to
+  `agents/runtime/council/sessions/<timestamp>/raw-text.md` so future readers
+  can audit.
+- Do **not** rewrite the roadmap based on the findings — surface them,
+  let the user decide what to act on.
+
+If the user picks **2** → continue.
+
+### 9. Offer execution
+
+After saving (and any council review), ask the user (in their language) whether to start executing the roadmap immediately.
+
+If yes → switch to [`/roadmap:process-phase`](process-phase.md) with
+the newly created file (the default execution scope of the `/roadmap`
+cluster). Offer [`process-step`](process-step.md) and
+[`process-full`](process-full.md) as alternatives. The legacy
+`/roadmap execute` command was removed — autonomous execution is the
+only path now.
+
+### Rules
+
+- **Do NOT auto-generate content** — always ask the user for input.
+- **Do NOT commit or push.**
+- **Do NOT include commit steps in the roadmap** unless the user explicitly
+  requested them. See [`commit-policy`](../rules/commit-policy.md#never-write-commit-steps-into-roadmaps-unsolicited).
+  Roadmaps plan **work**; commits are a separate delivery decision.
+- **Every phase MUST contain at least one `- [ ]` checkbox.** A roadmap
+  without checkboxes is invisible to `agents/roadmaps-progress.md` and
+  violates [`roadmap-progress-sync`](../rules/roadmap-progress-sync.md)
+  Iron Law #2.
+- **Status is binary: `ready` (default) or `draft`.** Create new
+  roadmaps as **ready** — no `status:` field needed.
+  Only mark `status: draft` (in YAML frontmatter) when the
+  user explicitly says it should be hidden from the dashboard (still
+  being authored, awaiting upstream decisions, capture-only synthesis
+  without executable phases). If the user wants draft, ask once at
+  step 3 — do not infer it.
+- Follow the roadmap template from `.augment/templates/roadmaps.md`; write in English (project convention).
+- Keep the file focused: 500–1000 lines max. If larger, suggest splitting.
+- **Never overwrite an existing roadmap.** Step 6 scans `active/`, `archive/`, `skipped/` (+ subdirs); on collision → STOP, present rename / open / abort. Auto-suffix requires explicit pick.

package/dist/agent-src/commands/roadmap/process-full.md

@@ -0,0 +1,110 @@
+---
+model_tier: medium
+name: roadmap-process-full
+pack: product-basic
+tier: 2
+visibility: internal
+cluster: roadmap
+sub: process-full
+skills: [agent-docs-writing, ai-council, roadmap-management]
+description: Autonomously process every open step across every phase of a roadmap until the file is fully closed. Largest execution scope of the /roadmap cluster — runs continuously across phase boundaries.
+suggestion:
+  eligible: true
+  trigger_description: "process the whole roadmap, finish the roadmap, komplette roadmap abarbeiten"
+  trigger_context: "existing agents/roadmaps/*.md and user wants the entire file done end-to-end"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /roadmap:process-full
+
+Whole-roadmap execution scope of the [`/roadmap`](../roadmap.md)
+cluster. Same canonical loop as
+[`/roadmap:process-phase`](process-phase.md), but does **not** stop at
+phase boundaries — continues until every step is closed (or a halt
+condition fires).
+
+## Instructions
+
+Run the canonical loop in
+[`contexts/execution/roadmap-process-loop`](../../contexts/execution/roadmap-process-loop.md)
+with the **scope delta below**.
+
+## Scope delta
+
+- **Working set:** every open step across every phase, in document
+  order. Phase-internal annotations like `(deferred)` / `(optional)` /
+  "gated on Phase N" do not narrow the working set.
+- **Stop after:** the entire roadmap reaches `count_open == 0`, or a
+  halt condition fires (Hard-Floor, council-off + ambiguity,
+  security-sensitive, scope-out-of-roadmap, test/quality red).
+- **Phase boundary handling:** at every phase boundary, run the
+  per-phase quality pipeline when `quality_cadence: per_phase` (or
+  `per_step`). On red → stop, surface, do **not** silently roll into
+  the next phase.
+- **Final archival:** when the roadmap is fully closed, run the
+  archival check from
+  [`roadmap-process-loop § 6`](../../contexts/execution/roadmap-process-loop.md#6-final-report-and-archival).
+
+## Iron Law — Full is Full
+
+```
+/roadmap:process-full PROCESSES EVERY OPEN STEP IN THE FILE.
+PHASE-INTERNAL "(DEFERRED)" / "(OPTIONAL)" / "GATED ON PHASE X"
+NOTES DO NOT NARROW THE WORKING SET. ONLY THE FIVE HALT CONDITIONS
+STOP THE RUN.
+```
+
+Phase-internal `(deferred)` / `(optional)` / `gated on Phase N` tags are
+authoring annotations, not execution gates. `/roadmap:process-full`
+ignores them by construction. If the user wants narrower execution they
+invoke `/roadmap:process-phase` (scope = single phase) or
+`/roadmap:process-step` (scope = single step) instead.
+
+Time-boxed plate / horizon framing is opt-in via
+`roadmap.horizon_weeks` in `.agent-settings.yml` (default `0` =
+forbidden, per template rule 16 in `templates/roadmaps.md`). If a
+roadmap carries such phrasing — whether by legacy or by an opt-in
+setting — treat it as ordinary prose during execution, never as a
+gate. Phase ordering and explicit dependency gates govern the loop.
+
+## Iron Law — Real-time dashboard
+
+```
+EVERY DONE STEP FLIPS [ ] → [x] BEFORE THE LOOP MOVES TO THE NEXT STEP.
+DASHBOARD REGENERATES IN THE SAME REPLY THAT FLIPPED THE BOX.
+NO BATCH FLIP AT THE ARCHIVE COMMIT. NO "I'LL DO IT AT THE END."
+```
+
+`/roadmap:process-full` is the worst offender for batching because it
+runs continuously across many steps. Flipping all 13 boxes in the
+single archive commit defeats the dashboard's purpose — the user
+loses progress visibility for the entire run. Per Iron Law 2 of
+[`roadmap-progress-sync`](../../rules/roadmap-progress-sync.md): the
+flip + regen pair is atomic with the step's work, executed inside
+[`roadmap-process-loop § 5`](../../contexts/execution/roadmap-process-loop.md#5-step-loop)
+step 5.
+
+## Rules
+
+- **No silent acceleration past a halt.** Every halt condition stops
+  the run; the user resumes on the next turn.
+- **No silent stop at an authoring annotation.** Encountering
+  "gated on Phase N", "deferred", "optional", or any equivalent
+  phase-internal annotation is **not** a halt condition. Continue.
+- **No silent batch flip.** Each step's checkbox flips in the same
+  reply that lands its work — never deferred to the archive commit.
+- **Phase quality pipeline runs at every phase boundary** when cadence
+  is `per_phase` or `per_step`. `end_of_roadmap` skips per-phase and
+  runs only at the final archival check.
+- All other rules from
+  [`process-phase § Rules`](process-phase.md#rules) apply unchanged.
+
+## See also
+
+- [`/roadmap`](../roadmap.md) — cluster orchestrator
+- [`/roadmap:process-step`](process-step.md) — single-step variant
+- [`/roadmap:process-phase`](process-phase.md) — default scope, single phase
+- [`roadmap-process-loop`](../../contexts/execution/roadmap-process-loop.md) — canonical mechanics

package/dist/agent-src/commands/roadmap/process-phase.md

@@ -0,0 +1,76 @@
+---
+model_tier: medium
+name: roadmap-process-phase
+pack: product-basic
+tier: 2
+visibility: internal
+cluster: roadmap
+sub: process-phase
+skills: [agent-docs-writing, ai-council, roadmap-management]
+description: Autonomously process every open step in the next or current phase of a roadmap, then stop. Default execution scope of the /roadmap cluster.
+suggestion:
+  eligible: true
+  trigger_description: "process the next phase, finish this phase autonomously, eine phase abarbeiten"
+  trigger_context: "existing agents/roadmaps/*.md and user wants the next phase done end-to-end"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /roadmap:process-phase
+
+Default execution scope of the [`/roadmap`](../roadmap.md) cluster.
+Sibling of [`/roadmap:process-step`](process-step.md) and
+[`/roadmap:process-full`](process-full.md). Replaces the legacy
+`/roadmap execute` (which paused for confirmation before every step).
+
+## Instructions
+
+Run the canonical loop in
+[`contexts/execution/roadmap-process-loop`](../../contexts/execution/roadmap-process-loop.md)
+with the **scope delta below**. The loop file owns roadmap discovery,
+pre-run summary, cadence resolution, commit-step pre-scan, the step
+loop with AI-council branching, halt conditions, and the archival
+check.
+
+## Scope delta
+
+- **Working set:** all open steps in the **first phase with
+  `count_open > 0`**. If every phase is closed → report "Roadmap
+  already complete." and run the archival check from
+  [`roadmap-process-loop § 6`](../../contexts/execution/roadmap-process-loop.md#6-final-report-and-archival).
+- **Stop after:** the phase boundary. Do **not** advance into the next
+  phase. Use [`/roadmap:process-full`](process-full.md) for continuous
+  execution across phases.
+- **Quality cadence at the boundary:** run the per-phase pipeline when
+  `quality_cadence: per_phase` (or `per_step`). Skip when
+  `end_of_roadmap`.
+
+## Rules
+
+- **Autonomous within the phase, never beyond.** The user picks
+  `process-step` for one step or `process-full` for the whole roadmap.
+- **No commit, push, branch, PR, tag, or bulk-destructive op** without
+  explicit permission this turn — see
+  [`commit-policy`](../../rules/commit-policy.md) and
+  [`scope-control § git-ops`](../../rules/scope-control.md#git-operations--permission-gated).
+  Roadmap-listed commit steps follow the single-upfront-ask flow in
+  [`roadmap-process-loop § 3`](../../contexts/execution/roadmap-process-loop.md#3-commit-step-pre-scan--one-upfront-ask).
+- **Every checkbox edit syncs the dashboard in the same response** per
+  [`roadmap-progress-sync`](../../rules/roadmap-progress-sync.md).
+- **AI-council consultations run silently when council is on.** No
+  per-call confirmation. The opt-in covers the whole run.
+- **Decline = silence.** Once the user said "skip council", do not
+  re-offer for the rest of this run.
+- **Halt cleanly on Hard-Floor or true ambiguity.** Surface state,
+  wait. Resume on the user's next turn from the same checkbox.
+
+## See also
+
+- [`/roadmap`](../roadmap.md) — cluster orchestrator
+- [`/roadmap:process-step`](process-step.md) — single-step variant
+- [`/roadmap:process-full`](process-full.md) — across-phases variant
+- [`/roadmap:create`](create.md) — sibling, scaffolds roadmaps
+- [`roadmap-process-loop`](../../contexts/execution/roadmap-process-loop.md) — canonical mechanics
+- [`roadmap-management`](../../skills/roadmap-management/SKILL.md) — checkbox + archival mechanics

package/dist/agent-src/commands/roadmap/process-step.md

@@ -0,0 +1,64 @@
+---
+model_tier: medium
+name: roadmap-process-step
+pack: product-basic
+tier: 2
+visibility: internal
+cluster: roadmap
+sub: process-step
+skills: [agent-docs-writing, ai-council, roadmap-management]
+description: Autonomously process the single next open step of a roadmap and stop. Smallest execution scope of the /roadmap cluster — one step in, one step out.
+suggestion:
+  eligible: true
+  trigger_description: "process the next step, do the next roadmap step, einen schritt abarbeiten"
+  trigger_context: "existing agents/roadmaps/*.md and user wants exactly one step done autonomously"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /roadmap:process-step
+
+One-step execution scope of the [`/roadmap`](../roadmap.md) cluster.
+Same canonical loop as [`/roadmap:process-phase`](process-phase.md),
+bounded to a single iteration.
+
+## Instructions
+
+Run the canonical loop in
+[`contexts/execution/roadmap-process-loop`](../../contexts/execution/roadmap-process-loop.md)
+with the **scope delta below**.
+
+## Scope delta
+
+- **Working set:** the **first checkbox `[ ]` in document order**
+  inside the first phase with `count_open > 0`. If every step is
+  closed → report "Roadmap already complete." and run the archival
+  check from
+  [`roadmap-process-loop § 6`](../../contexts/execution/roadmap-process-loop.md#6-final-report-and-archival).
+- **Stop after:** one full iteration of
+  [`roadmap-process-loop § 5`](../../contexts/execution/roadmap-process-loop.md#5-step-loop)
+  (sub-steps 1–7). After the checkbox edit + dashboard regen, **stop**.
+- **Quality cadence:** run the per-step pipeline only when
+  `quality_cadence: per_step`. Skip otherwise.
+- **Phase boundary:** if this single step happens to close the phase,
+  do **not** advance. Report the phase as complete and stop.
+- **Roadmap boundary:** if this single step happens to close the
+  entire roadmap, run the archival check before reporting.
+
+## Rules
+
+- **Stop after one step**, even if the next step is trivial. The user
+  picks `process-phase` or `process-full` when they want more.
+- All other rules from
+  [`process-phase § Rules`](process-phase.md#rules) apply unchanged:
+  Hard-Floor, no auto-commit, dashboard sync, AI-council silent-when-on,
+  decline = silence.
+
+## See also
+
+- [`/roadmap`](../roadmap.md) — cluster orchestrator
+- [`/roadmap:process-phase`](process-phase.md) — default scope, single phase
+- [`/roadmap:process-full`](process-full.md) — across-phases variant
+- [`roadmap-process-loop`](../../contexts/execution/roadmap-process-loop.md) — canonical mechanics