@event4u/agent-config 5.10.1 → 6.1.0

package/dist/agent-src/skills/repomix-packer/SKILL.md

@@ -0,0 +1,141 @@
+---
+model_tier: high
+context: large
+name: repomix-packer
+description: "Use when packaging a codebase to a single AI-friendly file for LLM analysis — local or remote, XML/Markdown/JSON, token counting, gitignore filtering, peer-side `repomix` CLI."
+domain: process
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+> **Pinned upstream:** `repomix` CLI (npm: `repomix`, brew: `repomix`). Re-verify per minor bump. Repomix is an **optional dependency** — this skill never installs it silently.
+
+# repomix-packer
+
+Wraps the upstream [`yamadashy/repomix`](https://github.com/yamadashy/repomix) CLI for codebase-snapshot workflows: pack a local or remote repo into a single XML / Markdown / JSON file with token counts and secret detection, then feed it to an LLM for review, audit, or migration scoping.
+
+## When to use
+
+- Producing an LLM-ingestible snapshot of a repo (or a sub-tree) for review or audit.
+- Comparing two branches by packaging each and diffing the snapshots.
+- Pulling a remote third-party library into context without cloning.
+- Pre-flighting a token budget before sending a codebase to an LLM.
+
+Do NOT use when:
+
+- You only need a few specific files — read them directly with `view`.
+- The snapshot will only feed a non-text format (PDF, image, audio) — route to [`markitdown`](../markitdown/SKILL.md).
+- The repo is sensitive and `--no-security-check` would be needed — STOP, route to a human.
+
+## Procedure: Snapshot a repo for LLM review
+
+### 1. Inspect: verify `repomix` is installed (peer-side)
+
+```bash
+repomix --version
+```
+
+If the binary is missing, surface one of the install recipes and STOP — do not install silently:
+
+```bash
+# npm (preferred for project-local installs)
+npm install -g repomix
+
+# Homebrew (macOS / Linux)
+brew install repomix
+```
+
+### 2. Decide local vs remote
+
+```bash
+# Local: pack the current directory.
+repomix
+
+# Remote shorthand: owner/repo
+npx repomix --remote owner/repo
+
+# Remote URL with a pinned commit
+npx repomix --remote https://github.com/owner/repo/commit/<sha>
+```
+
+### 3. Filter the snapshot to the smallest useful slice
+
+```bash
+# Include patterns
+repomix --include "src/**/*.php,*.md"
+
+# Add ignore patterns on top of .gitignore
+repomix -i "tests/**,*.test.js"
+
+# Strip comments to save tokens
+repomix --remove-comments
+```
+
+### 4. Pick the output format and destination
+
+```bash
+repomix --style markdown -o snapshot.md   # human-readable
+repomix --style xml -o snapshot.xml       # default; clearest separators for LLMs
+repomix --style json -o snapshot.json     # programmatic post-processing
+repomix --copy                            # also copy to clipboard
+```
+
+### 5. Verify token budget and secrets
+
+Repomix prints per-file and total token counts and runs Secretlint on the output. Check the totals against the target LLM context window:
+
+| Model              | Approx context |
+|--------------------|----------------|
+| Claude Sonnet 4.5  | ~200K tokens   |
+| GPT-4 family       | ~128K tokens   |
+| GPT-3.5            | ~16K tokens    |
+
+If Secretlint flags anything, STOP — sanitize the input or add the offending paths to `.repomixignore` before re-packing. Never use `--no-security-check` on an unfamiliar codebase.
+
+### 6. Hand the snapshot to the consumer skill
+
+Most workflows that call this skill pass the snapshot to:
+
+- A code-review pass — pair with [`judge-bug-hunter`](../judge-bug-hunter/SKILL.md) or [`judge-security-auditor`](../judge-security-auditor/SKILL.md).
+- Reference-repo analysis — route to [`analyze-reference-repo`](../../commands/analyze-reference-repo.md).
+- Migration scoping — route to [`blast-radius-analyzer`](../blast-radius-analyzer/SKILL.md).
+
+Cite the snapshot path so the consumer skill can read it.
+
+## Output format
+
+1. The repomix invocation (one shell line, with all filters and the output path).
+2. The output file path + format + total token count.
+3. Any Secretlint findings, verbatim. Empty section if none.
+
+## Gotcha
+
+- `--copy` puts the entire snapshot on the clipboard — surprising on large repos. Prefer `-o <path>` for anything > a few KB.
+- `--no-gitignore` plus a wildcard include can pull in `.env`, `vendor/`, `node_modules/` — never combine without a tight `--include` first.
+- Remote `npx repomix --remote owner/repo` defaults to the latest commit on the default branch — pin a commit SHA when reproducing a previous snapshot.
+- Token counts are LLM-tokenizer estimates, not exact — leave a 10–15% headroom under the model's documented context window.
+
+## Do NOT
+
+- Do NOT run `repomix --no-security-check` on an unfamiliar codebase.
+- Do NOT install repomix silently — surface the recipe and let the consumer install it.
+- Do NOT commit `repomix-output.*` artifacts — add the pattern to `.gitignore`.
+- Do NOT package `.env`, key material, or `.git/` — adjust `.repomixignore` first.
+- Do NOT vendor repomix into the repo — it is a peer-side CLI.
+
+## Auto-trigger keywords
+
+- repomix
+- pack codebase
+- repository snapshot
+- llm context bundle
+- codebase to single file
+
+## Provenance
+
+- Upstream tool: https://github.com/yamadashy/repomix (MIT).
+- Adopted from: an external reference (MIT, © 2025 an external reference) — wrapper-style adoption, no upstream code vendored.
+- Provenance registry: `agents/settings/contexts/skills-provenance.yml` (entry: `repomix`).
+- Iron-Law floor: `non-destructive-by-default`, `missing-tool-handling`, `tool-safety`.

package/dist/agent-src/skills/roadmap-management/SKILL.md

@@ -0,0 +1,461 @@
+---
+model_tier: inherit
+name: roadmap-management
+description: "Use when the user says \"create roadmap\", \"show roadmap\", or \"execute roadmap\". Creates, reads, and manages roadmap files with phase tracking."
+domain: process
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# roadmap-manager
+
+## When to use
+
+Use this skill when:
+- Creating a new roadmap (`/roadmap:create` command)
+- Executing a roadmap (`/roadmap:process-step|phase|full` commands)
+- Checking roadmap progress
+- Updating roadmap status after completing work
+
+
+Do NOT use when:
+- Small tasks that don't span multiple steps
+- One-off questions or fixes
+
+## ⚠ Dashboard sync — non-negotiable
+
+`agents/roadmaps-progress.md` is auto-generated and must reflect the
+live state in real time. After **any** checkbox edit (`[x]`, `[~]`,
+`[-]`, `[ ]`) or phase add/rename/remove in a roadmap file, regenerate
+the dashboard **in the same response**.
+
+**Completion = archival.** If an edit takes a roadmap to
+`count_open == 0` (pure `[x]`, or `[x]` + `[~]`/`[-]`), `git mv`
+it into `agents/roadmaps/archive/` **before** regenerating — see
+the auto-archive decision table under "Check completion status"
+below. A 100%-complete roadmap left in `agents/roadmaps/` makes the
+next reader think work is still open.
+
+This is enforced by the [`roadmap-progress-sync`](../../rules/roadmap-progress-sync.md)
+rule. Batching multiple edits in one response is fine — one final
+regeneration before replying is enough. But the response must not end
+without it.
+
+## Procedure: Manage a roadmap
+
+1. **Identify need** — Is this a multi-step change that spans sessions or agents?
+2. **Create or locate** — Create new roadmap in `agents/roadmaps/` or find existing one.
+3. **Update progress** — Mark completed steps with `[x]`, add notes for blockers, then regenerate the dashboard in the same response (enforced by `roadmap-progress-sync`).
+4. **Verify** — Confirm all steps reflect current state, no stale information.
+
+A roadmap is a structured `.md` file in `agents/roadmaps/` that describes a multi-step change
+(refactoring, feature, migration). It ensures work can be picked up across sessions and by
+different agents.
+
+## Roadmap locations
+
+| Location | Scope |
+|---|---|
+| `agents/roadmaps/` | Project-wide roadmaps |
+| `{module_root}/{Module}/{agent_folder}/roadmaps/` | Module-specific roadmaps (see note) |
+| `{package-root}/agents/roadmaps/` | Package-specific roadmaps |
+
+**Module path resolution.** `{module_root}` and `{agent_folder}` come from
+`modules.root_paths` and `modules.agent_folder` in
+`.agent-project-settings.yml` — see [`layered-settings`](../../../../../docs/guidelines/agent-infra/layered-settings.md).
+Common shapes:
+
+- Laravel — `app/Modules/{Module}/agents/roadmaps/`
+- Symfony bundles — `src/Bundle/{Bundle}/agents/roadmaps/`
+- Node / Python / Go monorepo packages — `packages/{Pkg}/agents/roadmaps/`
+
+Use `scripts/_lib/agent_settings.py::enumerate_modules()` to discover the
+actual paths in the current project; never assume `app/Modules/`.
+
+The file `.augment/templates/roadmaps.md` defines the canonical structure.
+**Always read it first** before creating or modifying roadmaps.
+
+## 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.
+
+### 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). What's configurable is **when**
+the pipeline runs during `/roadmap:process-step|phase|full`,
+controlled by `roadmap.quality_cadence` in `.agent-settings.yml`:
+
+| Cadence | Pipeline runs | 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.
+
+## 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
+
+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.
+
+### Completing, archiving & skipping a roadmap
+
+Every roadmap ends in exactly one of three states:
+
+| State | Folder | Trigger |
+|---|---|---|
+| **Active** | `agents/roadmaps/` | Work in progress or planned |
+| **Archived** | `agents/roadmaps/archive/` | Work was done (fully or partially) and no more work is planned |
+| **Skipped** | `agents/roadmaps/skipped/` | Decision against pursuit — superseded, scope rejected, wrong direction. Typically **0 items `[x]`** |
+
+After the last step of a roadmap is done, check completion status:
+
+1. **Scan the file** for all checkbox markers: `- [x]`, `- [ ]`, `- [~]`, `- [-]`.
+2. **Classify:**
+   - `[x]` = completed
+   - `[ ]` = open (not done)
+   - `[~]` = deferred (intentionally pushed out, may come back)
+   - `[-]` = cancelled (individual item dropped)
+
+3. **Decision rule — `count_open == 0` means the roadmap has no active
+   work left. `[x]`, `[-]` are final states. `[~]` deferred items
+   block silent closure — they carry plans user has not consented to drop
+   (enforced by [`roadmap-progress-sync`](../../rules/roadmap-progress-sync.md)
+   Iron Law 3).**
+
+   | count_x | count_open | count_deferred | count_cancelled | Action |
+   |---|---|---|---|---|
+   | ≥ 1 | 0 | 0 | 0 | **Auto-archive** (silent) — pure completion |
+   | ≥ 1 | 0 | 0 | ≥ 1 | **Auto-archive** (silent) — done with explicit drops |
+   | ≥ 1 | 0 | ≥ 1 | ≥ 0 | **STOP — Iron Law 3 flow.** Surface deferred items, present follow-up options, wait. Step 4b. |
+   | 0 | 0 | ≥ 1 | ≥ 0 | **STOP — Iron Law 3 flow.** Scope-drop or deferred-to-later? Same options as 4b. |
+   | 0 | 0 | 0 | ≥ 1 | **Auto-skip** (silent) — no work, all cancelled |
+   | ≥ 0 | ≥ 1 | ≥ 0 | ≥ 0 | **Ask the user** — open work remains (step 4a) |
+
+   Show on auto-move:
+
+   - Archive: `✅  Roadmap archived → agents/roadmaps/archive/{filename}`
+   - Skip:    `⏭️  Roadmap skipped → agents/roadmaps/skipped/{filename}`
+
+   `[-]` cancelled items remain searchable in archived file — they were
+   explicit drops. `[~]` deferred items, by contrast, may not silently
+   follow file into archive: they represent work user planned and would
+   lose track of. Step 4b is the gate.
+
+4a. **Open items remain (`count_open ≥ 1`)** → **Ask the user.** Show what's incomplete:
+
+   ```
+   📋 Roadmap completion check:
+
+     ✅  Completed: {count_x}
+     ⬜  Open:      {count_open}  — {list of open items, 1 line each}
+     ⏭️  Deferred:  {count_deferred}  — {list of deferred items, 1 line each}
+     ❌  Cancelled: {count_cancelled} — {list of cancelled items, 1 line each}
+
+   > 1. Archive — mark open items as cancelled [-] and archive now
+   > 2. Keep active — I want to finish the open items
+   > 3. Mark open items as deferred [~] and archive (triggers Iron Law 3 flow)
+   > 4. Skip — move to skipped/ (no meaningful work done, not pursuing)
+   ```
+
+   Option 4 only appropriate when `count_x == 0` or completed items were
+   trivial (e.g. prerequisites). If user picks 4 despite meaningful work
+   done, confirm once — archive usually right. Picking option 3 does
+   NOT archive immediately — converts open → deferred, re-enters the
+   `count_deferred > 0` branch, which runs step 4b.
+
+4b. **Deferred items present (`count_deferred ≥ 1`, `count_open == 0`)** — Iron Law 3 flow.
+   Archive **blocked** until user resolves deferrals. Surface plan and ask:
+
+   ```
+   📋 Roadmap closure check — deferred items must resolve before archive:
+
+     ✅  Completed: {count_x}
+     ⏭️  Deferred:  {count_deferred}
+     {for each deferred item:}
+       - Phase {N}: {step text}  {<!-- deferred: <annotation> --> if present}
+
+   These items carry plans you would lose to a silent archive.
+
+   > 1. Spawn follow-up roadmap as DRAFT
+   >    → agents/roadmaps/road-to-{auto-slug}.md, status: draft,
+   >      parent_roadmap: {this-slug}. Hidden from dashboard until you
+   >      flip status to "ready".
+   > 2. Spawn follow-up roadmap as READY (with blocked-until note)
+   >    → status: ready (default), parent_roadmap: {this-slug}, plus
+   >      `> Blocked until <condition>` line in body. Visible in
+   >      dashboard; execution waits on condition.
+   > 3. Keep deferred items in this archive — confirm "no follow-up"
+   >    intentional drop. Items stay searchable in archive/.
+   > 4. Restore selected items to [ ] — finish them here before archive.
+   > 5. Convert selected items to [-] cancelled — drop with rationale.
+   ```
+
+   Picks 1 or 2 → see "Spawn follow-up from deferred items" below.
+   Picks 3, 4, or 5 → apply the change in this roadmap; re-evaluate
+   the decision table; archive when gate clears.
+
+### Spawn follow-up from deferred items (procedure)
+
+When user picks option 1 or 2 in step 4b:
+
+1. **Derive slug.** Default `<parent-slug>-followup` (e.g. `road-to-x.md`
+   → `road-to-x-followup.md`). User-supplied slug in picker → use that.
+   Avoid collisions with `agents/roadmaps/` (active + `archive/` + `skipped/`).
+
+2. **Write new file** at `agents/roadmaps/<slug>.md`:
+
+   ```markdown
+   ---
+   complexity: lightweight            # bump if parent was structural
+   status: draft                      # option 1; omit for option 2 (= ready)
+   parent_roadmap: <parent-slug>      # back-link to source
+   ---
+
+   # Roadmap: Follow-up to <parent-title>
+
+   > <One sentence stating carried-over outcome.>
+
+   ## Context
+
+   This roadmap collects items deferred from
+   [`agents/roadmaps/archive/<parent-slug>.md`](archive/<parent-slug>.md).
+   See parent's archive entry for original rationale.
+
+   ## Prerequisites
+
+   - [ ] Read `AGENTS.md` and parent archive entry.
+   {parent prerequisites still relevant, copied verbatim}
+
+   <!-- Option 2 only — body note, NOT a frontmatter key: -->
+   > Blocked until <condition>. Execution starts when condition clears.
+
+   ## Phase 1: <name carried from parent>
+
+   - [ ] {deferred step text, copied verbatim with parent-phase pointer}
+   {repeat per deferred item, regrouped by parent phase}
+
+   ## Acceptance Criteria
+
+   - [ ] {restate or adjust per deferred scope}
+   - [ ] All quality gates pass — see `quality-tools`.
+   ```
+
+3. **In parent roadmap** (still in working tree), append a line at
+   bottom (above any final `---`):
+
+   ```
+   <!-- Deferred items migrated to agents/roadmaps/<followup-slug>.md on YYYY-MM-DD -->
+   ```
+
+   Do **not** delete `[~]` lines — keep visible in archived parent so
+   trail stays grep-able. Follow-up carries forward executable copy.
+
+4. **Regenerate dashboard.** Follow-up appears (draft hidden, ready
+   visible) and parent — once moved — drops off.
+
+5. **Archive parent** (`git mv` → `archive/`) and regen one more time
+   per [`roadmap-progress-sync`](../../rules/roadmap-progress-sync.md)
+   Iron Laws 1 + 3.
+
+5. **Move the file** with `git mv` so history is preserved:
+
+   ```bash
+   # Archive (work was done)
+   git mv agents/roadmaps/{file} agents/roadmaps/archive/{file}
+
+   # Skipped (not pursuing)
+   git mv agents/roadmaps/{file} agents/roadmaps/skipped/{file}
+   ```
+
+6. **Regenerate the dashboard** (see "Command" below). The moved roadmap is
+   excluded from the active set once it sits in `archive/` or `skipped/`.
+
+### When to use `skipped/` vs `archive/`
+
+| Situation | Destination |
+|---|---|
+| Finished all phases | `archive/` |
+| Finished some phases, rest deferred/cancelled on purpose | `archive/` |
+| Whole roadmap deferred or cancelled (no `[x]` at all) | `skipped/` |
+| Never started, scope decision reversed | `skipped/` |
+| Superseded by another roadmap | `skipped/` — add a pointer line at the top: `> Superseded by agents/roadmaps/{other}.md` |
+| Research proved the direction wrong | `skipped/` — add a 1-line reason at the top |
+
+If in doubt: archive beats skipped. `skipped/` is reserved for roadmaps where
+no meaningful work was invested and the scope itself was rejected.
+
+## 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.py`.
+
+**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.
+
+## Output format
+
+1. Roadmap file in agents/roadmaps/ with ordered phases and tasks
+2. Progress tracking with checkbox status
+3. `agents/roadmaps-progress.md` regenerated on every change
+
+## Auto-trigger keywords
+
+- roadmap
+- roadmap creation
+- phase tracking
+- step completion
+
+## Gotcha
+
+- Roadmap files go in `agents/roadmaps/` — don't create them in other directories.
+- Don't mark phases complete without running verification (tests, quality checks) — the verify-before-complete rule applies.
+- The model tends to skip phases it deems "simple" — every phase must be explicitly completed.
+- Auto-archive is allowed when `count_open == 0` AND `count_deferred == 0`. `[-]` cancelled items archive silently (explicit drops). `[~]` deferred items **block** silent archive — they trigger the Iron Law 3 flow (see step 4b).
+- `archive/` and `skipped/` are distinct — `archive/` = work happened, `skipped/` = no meaningful work, not pursuing. Create either directory if it doesn't exist.
+- Use `git mv` (not `mv`) so history follows the file.
+
+## Do NOT
+
+- Do NOT skip quality gates between steps.
+- Do NOT mark steps as done without actually completing them.
+- Do NOT modify completed steps (only add notes if needed).
+- Do NOT create roadmaps for trivial changes (single-file fixes don't need a roadmap).
+- Do NOT commit or push — only local changes.
+- Do NOT archive roadmaps with open `[ ]` items without asking the user.
+- Do NOT delete roadmaps — always move to `archive/` or `skipped/`.
+- Do NOT use `skipped/` as a dumping ground for partially-finished work — that is what `archive/` with deferred items is for.
+- Do NOT assign version numbers, git tags, deprecation dates, or release identifiers to phases. Roadmaps plan work; releases and tags are decided by the user separately. Hard rule — see [`scope-control`](../../rules/scope-control.md#git-operations--permission-gated).
+- Do NOT propose a branch switch while executing a roadmap. The branch question is settled at creation time; if the user already declined (or you never asked because it wasn't sensible), stay silent. See [`scope-control`](../../rules/scope-control.md#decline--silence--no-re-asking-on-the-same-task).