@event4u/agent-config 14.5.0 → 14.7.0

package/dist/agent-src/skills/roadmap-management/references/authoring.md

@@ -0,0 +1,107 @@
+# roadmap-management — authoring a roadmap
+
+> Mode body of the [`roadmap-management`](../SKILL.md) skill (router-head
+> retrofit, 2026-08-20). Content moved VERBATIM from SKILL.md — load this
+> file when the mode table in SKILL.md routes here.
+
+## Roadmap structure
+
+Every roadmap follows this structure:
+
+```markdown
+# Roadmap: {Short descriptive title}
+
+> {One sentence: What is the expected outcome?}
+
+## Prerequisites
+
+- [ ] Read `AGENTS.md` and relevant docs
+- [ ] {specific prerequisites}
+
+## Context
+
+{Why this roadmap exists. Which module/domain. Links to Jira tickets.}
+
+## Phase 1: {Phase name}
+
+- [ ] **Step 1:** {Clear, actionable instruction}
+- [ ] **Step 2:** {Next step — reference files/classes}
+- [ ] ...
+
+## Phase 2: {Phase name}
+
+- [ ] **Step 1:** {description}
+- [ ] ...
+
+## Acceptance Criteria
+
+- [ ] {Observable, testable criterion}
+- [ ] All quality gates pass — the project's type-checker, auto-fixer, linter, and full test suite (see the `quality-tools` skill for stack-specific invocations)
+
+## Notes
+
+{Edge cases, decisions, links}
+```
+
+## Key rules for roadmaps
+
+### Checkboxes — mandatory, not decorative
+
+- **Every active roadmap MUST contain at least one `- [ ]` per non-intro phase.** Decision tables, ICE matrices, and block-sequencing tables are valid rationale, but they do not satisfy this rule on their own — pair them with a `## Phase N` or `## Implementation Checklist` section whose checkboxes execute the decision. A roadmap without checkboxes is invisible to `agents/roadmaps-progress.md` and violates [`roadmap-progress-sync`](../../rules/roadmap-progress-sync.md) Iron Law #2.
+- Every actionable step uses `- [ ]` (unchecked) or `- [x]` (completed).
+- Mark steps as `[x]` immediately after completing them.
+- Never remove completed steps — they serve as history.
+- **Status is binary: `ready` (default, implicit) or `draft`.** New roadmaps are created **ready** unless the user explicitly says otherwise — `ready` is implicit and need not be written. A roadmap that is still being authored, awaiting upstream decisions, or capturing options without a worked plan declares `status: draft` in YAML frontmatter at the top of the file. Drafts are hidden from `agents/roadmaps-progress.md` until the flag is removed or flipped to `ready`. There are no other status values; legacy banners (`**Status: directional**`, `Status: capture-only`, `mode: feedback`) are removed.
+
+### Awaiting evidence — a blocker entry, never a new glyph
+
+- Waiting on **evidence that has not arrived** (soak still running, benchmark unfunded, adopter absent) is neither `[~]` nor `[-]`. Signal it with a structured `## Blockers` entry — five-field shape in [`templates/roadmaps.md` rule 20](../../agent-src/templates/roadmaps.md) — whose `Resolved when:` names the decidable signal ending the wait. The item stays `- [ ]` and points at it: `<!-- blocked-by: <id> -->`.
+- **No new glyph.** `[ ]` + `blocked-by:` = open, awaiting named evidence (stays active) · `[~]` = deferred by decision (bars archival, Iron Law 3) · `[-]` = cancelled with a reason (does not bar it). A fifth state buys nothing the entry above does not already carry.
+
+### Phases
+
+- Group related steps into phases (e.g. "Preparation", "Migration", "Cleanup").
+- Complete one phase before starting the next (unless steps are independent).
+- After completing a phase, summarize what was done.
+
+### Quality gates
+
+Every roadmap implicitly includes the project's quality pipeline
+(static analysis, autofixes, tests). Whether the agent runs it locally
+at all is gated by `quality.local_auto_run`: `false` or missing (the
+default) → the agent never runs the pipeline locally; the user runs it
+manually and remote CI on the PR is the authoritative gate (run-end
+report: *"quality gates delegated to remote CI"*; new-gate carve-out
+steps still run once). When `local_auto_run: true`, **when** the
+pipeline runs during `/roadmap:process-step|phase|full` is controlled
+by `roadmap.quality_cadence` in `.agent-settings.yml`:
+
+| Cadence | Pipeline runs (`local_auto_run: true` only) | Trade-off |
+|---|---|---|
+| `end_of_roadmap` (default) | Once before archiving | Fastest, fewest tokens; errors compound across phases |
+| `per_phase` | After every completed phase + final | Balanced; catches drift at phase boundaries |
+| `per_step` | After every completed step + final | Legacy verbose; highest token cost |
+
+The default is `end_of_roadmap` because most steps are checkbox-only
+content edits and a final pipeline run is the cheapest way to satisfy
+`verify-before-complete`. Switch to `per_phase` for risky migrations or
+unfamiliar codebases.
+
+**Always-on, regardless of cadence:**
+
+- Step checkboxes flip `[ ] → [x]` and the dashboard regenerates **same
+  response** (enforced by `roadmap-progress-sync`).
+- Before any "roadmap complete" claim or archival, the pipeline runs
+  fresh (enforced by `verify-before-complete`).
+
+### Step granularity
+
+- Each step should be completable in one session (< 1 hour of work).
+- If a step is too large, break it down into sub-steps.
+- Steps should reference specific files/classes when possible.
+
+### Language
+
+- Roadmap files are written in **English** (per project convention).
+- Step descriptions should be precise and actionable, not vague.
+

package/dist/agent-src/skills/roadmap-management/references/dashboard.md

@@ -0,0 +1,47 @@
+# roadmap-management — progress dashboard
+
+> Mode body of the [`roadmap-management`](../SKILL.md) skill (router-head
+> retrofit, 2026-08-20). Content moved VERBATIM from SKILL.md — load this
+> file when the mode table in SKILL.md routes here.
+
+## Progress dashboard — `agents/roadmaps-progress.md`
+
+A generated dashboard aggregates progress across every open roadmap. It sits at
+`agents/roadmaps-progress.md` (outside `roadmaps/` to keep the folder clean) and
+is rewritten by `.augment/scripts/update_roadmap_progress.ts`.
+
+**Always regenerate in the SAME response** after any of the following
+(enforced by [`roadmap-progress-sync`](../../rules/roadmap-progress-sync.md)):
+
+- Creating a new roadmap (`/roadmap:create`)
+- Marking a step `[x]`, `[~]`, or `[-]` during `/roadmap:process-*`
+- Archiving or moving a roadmap to `skipped/`
+- Adding, renaming, or removing a phase
+
+Command:
+
+```bash
+./agent-config roadmap:progress           # rewrite the dashboard
+./agent-config roadmap:progress-check     # CI: fail if stale
+```
+
+The `./agent-config` wrapper lives in the project root (written by the
+package installer, gitignored) and delegates to the master CLI inside
+`node_modules/@event4u/agent-config/` or `vendor/event4u/agent-config/`.
+No global tooling required.
+
+The dashboard is a **read-only snapshot**. Do not edit it by hand — regenerate it.
+
+### Blockers on the dashboard
+
+The overview table's `Blocker` column counts each roadmap's open
+`## Blockers` entries (or the legacy `> Blocked until` note) and links
+to the per-roadmap breakdown, which lists every open blocker with
+owner, blocked scope, and full instructions. Authoring shape:
+[`templates/roadmaps.md` rule 20](../../agent-src/templates/roadmaps.md);
+authoring guidance: [`roadmap-writing § 5b`](../roadmap-writing/SKILL.md).
+Clearing a blocker flips its `Status: resolved` and regenerates the
+dashboard in the same reply, same cadence as a checkbox flip. The
+blocker entry is also the canonical **awaiting-evidence** signal —
+see [§ Awaiting evidence](authoring.md#awaiting-evidence--a-blocker-entry-never-a-new-glyph).
+

package/dist/agent-src/skills/roadmap-management/references/lifecycle.md

@@ -0,0 +1,58 @@
+# roadmap-management — creating, executing, resuming
+
+> Mode body of the [`roadmap-management`](../SKILL.md) skill (router-head
+> retrofit, 2026-08-20). Content moved VERBATIM from SKILL.md — load this
+> file when the mode table in SKILL.md routes here.
+
+## Working with roadmaps
+
+### Creating a roadmap
+
+1. Ask the user for goal, context-create, and phases.
+2. Use the template structure from `.augment/templates/roadmaps.md`.
+3. Review with the user iteratively until approved.
+4. **Branch & release questions — at most once, only if genuinely useful.**
+   Default: stay on the current branch, no version numbers in the
+   roadmap. Only propose a separate branch when there is concrete,
+   evidence-based reason (e.g. risky migration benefits from a spike).
+   Never include release versions, deprecation dates, or git tags in
+   the roadmap text. If the user declines, do **not** re-propose during
+   `/roadmap:process-*`. Decline = silence. See [`scope-control`](../../rules/scope-control.md#decline--silence--no-re-asking-on-the-same-task).
+5. Save with a kebab-case filename (e.g. `optimize-webhook-jobs.md`).
+   **Before writing**, scan the entire roadmap namespace for a
+   collision — active, `archive/`, `skipped/`, and nested subdirs —
+   with `find agents/roadmaps -type f -iname "<name>.md"`. If any
+   hit comes back, stop and ask the user to rename, open the
+   existing file, or abort. Never silently overwrite an archived
+   or skipped roadmap. Detailed prompt in
+   [`commands/roadmap/create.md`](../../commands/roadmap/create.md)
+   step 6.
+6. Regenerate the dashboard so the new roadmap is included.
+
+### Executing a roadmap
+
+0. Resolve the mode per `roadmap-process-loop` § 3a: suffix, frontmatter
+   `execution.mode`, invocation form (absent = derived, not
+   `interactive`). Under `/roadmap:process-*` the mode selects the
+   interaction pattern via the run-start execution contract — see
+   [`roadmap-execution-contract`](../../contexts/execution/roadmap-execution-contract.md).
+   The manual flow below describes `interactive`; under `autonomous`
+   / `phase-checkpoints` step 4's per-step ask is replaced by the
+   accepted contract. **Mode never changes archival semantics** —
+   glyph counting, the closure decision table, and the Iron Law 3
+   deferred-resolution gate below apply identically in every mode.
+1. Read the full roadmap.
+2. Find the next unchecked step (`- [ ]`).
+3. Summarize what needs to be done.
+4. Ask the user before implementing (numbered options: implement / adjust / skip).
+5. After implementation: mark `[x]`, run quality gates, then regenerate the dashboard.
+6. Move to the next step.
+
+### Resuming a roadmap
+
+When picking up a roadmap in a new session:
+1. Read the roadmap to understand the full context.
+2. Check which steps are already completed (`[x]`).
+3. Summarize progress to the user.
+4. Continue from the next open step.
+