@codewizard-dt/bootstrap 5.1.0 → 6.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (95) hide show
  1. package/README.md +11 -3
  2. package/bin/cli.js +16 -0
  3. package/lib/hooks/README.md +124 -3
  4. package/lib/hooks/claude-settings-guard.js +8 -2
  5. package/lib/prompts/README.md +1 -1
  6. package/lib/prompts/migrate-wiki.md +7 -7
  7. package/lib/scripts/README.md +111 -10
  8. package/lib/scripts/bootstrap-prefs-tui.js +1222 -0
  9. package/lib/scripts/install-global.sh +137 -6
  10. package/lib/scripts/migrate-project.sh +52 -10
  11. package/lib/scripts/rename-wiki-ids.js +232 -0
  12. package/lib/scripts/templates/CLAUDE-wiki.md +6 -6
  13. package/lib/scripts/templates/bootstrap-prefs-schema.json +11 -2
  14. package/lib/scripts/templates/settings-sandbox-unattended.json +36 -0
  15. package/lib/scripts/templates/settings-sandbox.json +7 -0
  16. package/lib/scripts/templates/wiki/conventions.md +12 -10
  17. package/lib/scripts/templates/wiki/dashboard.html +527 -23
  18. package/lib/scripts/templates/wiki/index.md +2 -2
  19. package/lib/scripts/templates/wiki/work/bugs/lifecycle.md +1 -1
  20. package/lib/scripts/templates/wiki/work/decisions/index.md +12 -4
  21. package/lib/scripts/templates/wiki/work/decisions/lifecycle.md +11 -9
  22. package/lib/scripts/templates/wiki/work/requirements/index.md +12 -4
  23. package/lib/scripts/templates/wiki/work/requirements/lifecycle.md +8 -8
  24. package/lib/scripts/templates/wiki/work/roadmaps/index.md +11 -3
  25. package/lib/scripts/templates/wiki/work/roadmaps/lifecycle.md +7 -5
  26. package/lib/scripts/templates/wiki/work/tasks/index.md +1 -1
  27. package/lib/scripts/templates/wiki/work/tasks/lifecycle.md +16 -8
  28. package/lib/scripts/templates/wiki/work/uat/lifecycle.md +3 -3
  29. package/lib/scripts/wiki-dashboard-server.js +98 -0
  30. package/lib/skills/README.md +27 -22
  31. package/lib/skills/_shared/ARCHIVE-WORK-ITEM.md +103 -0
  32. package/lib/skills/_shared/ID-RESOLUTION.md +142 -0
  33. package/lib/skills/_shared/SKILL-BOILERPLATE.md +50 -0
  34. package/lib/skills/adr-assess/SKILL.md +112 -0
  35. package/lib/skills/{decision-create → adr-create}/SKILL.md +27 -26
  36. package/lib/skills/adr-deprecate/SKILL.md +190 -0
  37. package/lib/skills/adr-extract/SKILL.md +255 -0
  38. package/lib/skills/{decision-finalize → adr-finalize}/SKILL.md +38 -38
  39. package/lib/skills/{decision-next → adr-next}/SKILL.md +20 -19
  40. package/lib/skills/{decision-walkthrough → adr-walkthrough}/SKILL.md +23 -29
  41. package/lib/skills/architecture-audit/SKILL.md +24 -3
  42. package/lib/skills/autopilot/SKILL.md +110 -0
  43. package/lib/skills/bootstrap-config/SKILL.md +1 -1
  44. package/lib/skills/bug-assess/SKILL.md +3 -3
  45. package/lib/skills/bug-close/SKILL.md +15 -26
  46. package/lib/skills/{bug-file → bug-create}/SKILL.md +25 -15
  47. package/lib/skills/bug-triage/SKILL.md +5 -19
  48. package/lib/skills/demo/SKILL.md +11 -11
  49. package/lib/skills/elevator-pitch/SKILL.md +1 -1
  50. package/lib/skills/extract-feature/SKILL.md +29 -87
  51. package/lib/skills/git-commit/SKILL.md +4 -4
  52. package/lib/skills/marp-slideshow/SKILL.md +2 -2
  53. package/lib/skills/port-feature/SKILL.md +28 -83
  54. package/lib/skills/power-mode/SKILL.md +42 -49
  55. package/lib/skills/prd-assess/SKILL.md +105 -0
  56. package/lib/skills/{req-compile → prd-compile}/SKILL.md +6 -13
  57. package/lib/skills/{req-create → prd-create}/SKILL.md +19 -19
  58. package/lib/skills/prd-deprecate/SKILL.md +173 -0
  59. package/lib/skills/{req-finalize → prd-finalize}/SKILL.md +20 -29
  60. package/lib/skills/primer/SKILL.md +2 -2
  61. package/lib/skills/research/SKILL.md +3 -3
  62. package/lib/skills/roadmap-assess/SKILL.md +20 -20
  63. package/lib/skills/roadmap-create/SKILL.md +23 -29
  64. package/lib/skills/roadmap-next/SKILL.md +16 -28
  65. package/lib/skills/security-audit/SKILL.md +3 -3
  66. package/lib/skills/tackle/SKILL.md +13 -15
  67. package/lib/skills/{task-audit → task-assess}/SKILL.md +34 -44
  68. package/lib/skills/task-close/SKILL.md +73 -0
  69. package/lib/skills/{task-add → task-create}/SKILL.md +44 -24
  70. package/lib/skills/uat-assess/SKILL.md +124 -0
  71. package/lib/skills/uat-auto/SKILL.md +9 -6
  72. package/lib/skills/uat-auto-plus/SKILL.md +2 -2
  73. package/lib/skills/{uat-generate → uat-create}/SKILL.md +10 -12
  74. package/lib/skills/uat-skip/SKILL.md +5 -9
  75. package/lib/skills/uat-walk/SKILL.md +2 -2
  76. package/lib/skills/uat-walk/UAT-CORE.md +29 -16
  77. package/lib/skills/update-docs/SKILL.md +1 -1
  78. package/lib/skills/usage-report/SKILL.md +52 -0
  79. package/lib/skills/usage-report/scripts/pricing.json +22 -0
  80. package/lib/skills/usage-report/scripts/usage-report.js +518 -0
  81. package/lib/skills/whats-next/SKILL.md +177 -0
  82. package/lib/skills/wiki-archive/SKILL.md +12 -23
  83. package/lib/skills/wiki-lint/SKILL.md +42 -5
  84. package/lib/skills/wiki-query/SKILL.md +1 -1
  85. package/lib/skills/wiki-rotate-log/SKILL.md +1 -1
  86. package/lib/skills/wiki-tidy/SKILL.md +6 -9
  87. package/package.json +1 -1
  88. package/lib/scripts/templates/wiki/work/decisions/archive/index.md +0 -10
  89. package/lib/scripts/templates/wiki/work/requirements/archive/index.md +0 -10
  90. package/lib/scripts/templates/wiki/work/roadmaps/archive/index.md +0 -10
  91. package/lib/skills/req-extract-decisions/SKILL.md +0 -241
  92. package/lib/skills/req-retire/SKILL.md +0 -185
  93. package/lib/skills/req-update/SKILL.md +0 -265
  94. package/lib/skills/task-trash/SKILL.md +0 -115
  95. package/lib/skills/task-update/SKILL.md +0 -136
@@ -0,0 +1,103 @@
1
+ # ARCHIVE-WORK-ITEM — shared procedure for archiving a work item
2
+
3
+ The mechanic for archiving one terminal work item in the `tasks`, `uat`, or `bugs` families — set the terminal status, `git mv` the file into `<family>/archive/`, drop its active-index row, append its `archive/index.md` row, append a `wiki/log.md` entry — lives here once. Each `SKILL.md` that archives an item supplies only its parameters (see **Inputs**) and any deltas (see **Caller deltas**); it does not restate the steps. Run the Procedure once per item. Roadmaps, decisions, and requirements are **not** archived: finished items stay in place and move from `## Active` to `## Closed` in their family index — see **In-place close (roadmaps, decisions, requirements)** below.
4
+
5
+ ## Inputs
6
+
7
+ | Input | Meaning |
8
+ |-------|---------|
9
+ | `family` | One of `tasks`, `uat`, `bugs` — the directory under `wiki/work/`. Roadmaps, decisions, and requirements use the in-place close section below, not this procedure. |
10
+ | `file` | The item's current path, e.g. `wiki/work/<family>/<file>.md`. |
11
+ | `terminal_status` | The status the item ends in. Must be a terminal value for `family` per `wiki/work/<family>/lifecycle.md`. |
12
+ | `log` | The `wiki/log.md` entry text to append, or `skip` when the caller writes its own entry. Omitted means the default entry (see **Row and log formats**). |
13
+
14
+ ## Procedure
15
+
16
+ 1. **Verify and set the status.** `Read` `wiki/work/<family>/lifecycle.md` and confirm `terminal_status` is a terminal value for the family — do not hardcode the per-family sets. `Read` `file`. If its `status:` is already terminal, do not touch the file's content and go to step 2. Otherwise `Edit` once: set `status: <terminal_status>` and bump `updated:` to today's date.
17
+ 2. **Move the file.** `Bash`, `git mv` only: `git mv wiki/work/<family>/<file>.md wiki/work/<family>/archive/<file>.md`. `git mv` (not plain `mv`) preserves history. `archive/` already exists — do not create it.
18
+ 3. **Remove the active-index row.** `Read` `wiki/work/<family>/index.md`, then `Edit` to remove the item's row. If the row is already absent, note it and continue.
19
+ 4. **Append the archive-index row.** `Read` `wiki/work/<family>/archive/index.md`, then `Edit` to append one row in the four-column format below, using the item's `id` and `title` from its frontmatter and today's date.
20
+ 5. **Append the log entry.** Unless `log` is `skip`, `Read` `wiki/log.md`, then `Edit` to append the caller's `log` text, or the default entry.
21
+
22
+ ## Row and log formats
23
+
24
+ Archive-index row (identical shape in every family's `archive/index.md`, including `decisions/`; the table header is `| ID | Title | Final Status | Archived |`):
25
+
26
+ ```
27
+ | [[ID]] | <title> | <terminal_status> | YYYY-MM-DD |
28
+ ```
29
+
30
+ `YYYY-MM-DD` is today's date. Some archive indexes are column-padded by a formatter (e.g. `uat/archive/index.md`); an unpadded row is still valid — do not reformat existing rows.
31
+
32
+ Default log entry (used when the caller passes no `log`):
33
+
34
+ ```
35
+ ## [YYYY-MM-DD] archive | <ID> — <terminal_status>, moved to archive
36
+ <One sentence: moved to wiki/work/<family>/archive/<file>.md, and why if the caller knows.>
37
+ ```
38
+
39
+ ## Caller deltas
40
+
41
+ What each consumer passes. Anything not listed here is the caller's own logic and stays in its `SKILL.md`.
42
+
43
+ | Consumer | `family` | `terminal_status` | `log` / other deltas |
44
+ |----------|----------|-------------------|----------------------|
45
+ | `wiki-archive` | `tasks`, `uat` or `bugs` | the file's existing terminal `status:` (step 1 is a no-op) | `log: skip` per item; writes one batch entry itself (`archive | <family> — N items archived`) |
46
+ | `task-assess` | `tasks` | `done` | default entry |
47
+ | `task-close` | `tasks`, then `uat` | `trashed` | run once for the task, then once per related UAT file; task uses log op `task-trashed`, UAT runs pass `log: skip` |
48
+ | `bug-triage` | `bugs` | `wontfix` \| `duplicate` \| `cannot-reproduce` | `log: skip` — its own Step 9 writes the single entry |
49
+ | `bug-close` | `bugs` | `closed` \| `wontfix` \| `cannot-reproduce` | default entry |
50
+
51
+ ## CRITICAL rules
52
+
53
+ - **Never delete.** Archiving is moving, not deleting.
54
+ - **`archive/index.md` is append-only** — add rows, never edit or remove existing ones.
55
+ - **No body edits.** The only content change to the item is the `status:` / `updated:` flip in step 1. Never reformat or edit anything else in the moved file.
56
+ - **`Bash` only for `git mv`.** Every other edit is `Read` then `Edit`; never `sed`, `awk`, or `echo >>`.
57
+ - **`archive/` already exists** in `tasks`, `uat`, and `bugs` — do not create it. It is never created or used in `requirements`, `decisions`, or `roadmaps`.
58
+
59
+ ## Other consumers (not yet wired)
60
+
61
+ These implement the same mechanic inline and have not been pointed at this doc yet: `uat-skip` (Step 3a/4) and `UAT-CORE.md` Closure (`~/.claude/skills/uat-walk/UAT-CORE.md`). Their task/UAT archiving is unchanged; their roadmap-completion step uses the in-place close below. A follow-up can rewire the task/UAT part to this procedure.
62
+
63
+ ## In-place close (roadmaps, decisions, requirements)
64
+
65
+ For `roadmaps`, `decisions`, and `requirements`, a finished item **stays where it is**. Closing it flips its status (when it has one to flip) and moves its row in the family `index.md` from `## Active` to `## Closed`. There is no `git mv` and no `archive/index.md`. The Inputs `file`, `terminal_status`, and `log` have the same meaning as above.
66
+
67
+ | Family | Active while | Closed when |
68
+ |--------|--------------|-------------|
69
+ | `requirements` | `draft`, `approved` | `retired` |
70
+ | `roadmaps` | `active` | `done` |
71
+ | `decisions` | a group is Active while any block is `proposed` | every block is `accepted`, `deprecated`, or `superseded` |
72
+
73
+ ### Procedure
74
+
75
+ 1. **Verify and set the status.** `Read` `wiki/work/<family>/lifecycle.md` and confirm `terminal_status` is a terminal value for the family. `Read` `file`. If its `status:` is already terminal, do not touch the file's content and go to step 2. Otherwise `Edit` once: set `status: <terminal_status>` and bump `updated:` to today's date. Decisions carry a per-block `Status:` instead of a file `status:`; the decision skills set it themselves before calling this step.
76
+ 2. **Move the index row.** `Read` `wiki/work/<family>/index.md`, then `Edit` to remove the item's row from `## Active` and add it under `## Closed`, in numeric-ID order. If `## Closed` is missing, create it at the end of the file. If the row is already in `## Closed`, only update its trailing segment; if it is absent from `## Active`, note it and continue.
77
+ 3. **Append the log entry.** `Read` `wiki/log.md`, then `Edit` to append `## [YYYY-MM-DD] close | <ID> — <terminal_status>, closed in place`, unless the caller writes its own entry (`log: skip`).
78
+
79
+ ### Row format
80
+
81
+ A Closed row is the Active bullet with the terminal status as a trailing ` · ` segment:
82
+
83
+ ```
84
+ - [ROADMAP-NNNN — Title](ROADMAP-NNNN-slug.md) — one-line summary · done
85
+ ```
86
+
87
+ For a decision group the trailing segment is the per-block summary instead (`D1 accepted, D2 superseded`).
88
+
89
+ ### Caller deltas
90
+
91
+ | Consumer | `family` | `terminal_status` / other deltas |
92
+ |----------|----------|----------------------------------|
93
+ | `roadmap-next`, `roadmap-assess` | `roadmaps` | `done` |
94
+ | `prd-deprecate` | `requirements` | `retired` |
95
+ | `adr-deprecate`, `adr-finalize` (only when the group is fully terminal) | `decisions` | the group's per-block summary as the trailing segment; the skill sets the block `Status:` itself |
96
+ | `uat-skip`, `UAT-CORE.md` roadmap-completion step | `roadmaps` | `done` |
97
+
98
+ ### CRITICAL rules
99
+
100
+ - **Never `git mv`** an item in these families.
101
+ - **Never create `archive/`** in these families.
102
+ - **No body edits.** The only content change to the item is the `status:` / `updated:` flip in step 1.
103
+ - **Every edit is `Read` then `Edit`**; never `sed`, `awk`, or `echo >>`.
@@ -0,0 +1,142 @@
1
+ # ID-RESOLUTION — shared procedure for resolving a work-item reference to a file
2
+
3
+ How a skill turns a user-supplied reference (`<path>`, `TASK-0086`, `0086-some-slug`, bare `86`) into exactly one file under `wiki/work/<family>/` lives here once. **Each consuming skill states only: family, search scope, ambiguity mode (interactive|headless), empty-input behavior, and any post-resolution gate. Everything else is defined here.** Run the Procedure once per reference.
4
+
5
+ Use Serena `find_file` / `list_dir` for every lookup — never `ls`, `find`, or `grep` (see `wiki/guides/mcp-tools.md`).
6
+
7
+ ## Wiring block
8
+
9
+ Consumers replace their inline resolution table with one line in this form:
10
+
11
+ `Resolve the file per ~/.claude/skills/_shared/ID-RESOLUTION.md — family: tasks · scope: active · ambiguous: interactive · empty: <behavior>`
12
+
13
+ Any post-resolution gate (a status check, a "found in `archive/`" message) follows the line in the consumer's own prose. Behavior for empty input and for the gate is the caller's; the resolution mechanics are not.
14
+
15
+ ## Inputs
16
+
17
+ | Input | Meaning |
18
+ |-------|---------|
19
+ | `family` | One of the rows in **Family table** — selects the directory and ID prefix. |
20
+ | `scope` | `active`, `active+archive`, or `active-then-archive-gate` — see **Search scope**. Default `active`. |
21
+ | `ambiguous` | `interactive` or `headless` — see **Match outcomes**. |
22
+ | `empty` | What the caller does when the input is empty or free text. Not resolved here. |
23
+
24
+ ## Family table
25
+
26
+ The only place a family's facts live. Renaming a family or its prefix is a one-table edit here.
27
+
28
+ | Family | Directory | ID prefix | Notes |
29
+ |--------|-----------|-----------|-------|
30
+ | requirements | `wiki/work/requirements/` | `PRD` | new items; legacy prefix `REQ` (files not yet migrated) is also tried, after `PRD` — see Procedure step 4 |
31
+ | decisions | `wiki/work/decisions/` | `ADR` | new items; legacy prefix `DEC` (files not yet migrated) is also tried, after `ADR` — see Procedure step 4; reference may carry a `#DM` suffix (see **`#DM` suffix**) |
32
+ | roadmaps | `wiki/work/roadmaps/` | `ROADMAP` | |
33
+ | tasks | `wiki/work/tasks/` | `TASK` | |
34
+ | uat | `wiki/work/uat/` | `UAT` | one per task; the number mirrors the task's number |
35
+ | bugs | `wiki/work/bugs/` | `BUG` | |
36
+
37
+ Terminal items live in the `archive/` subdirectory for `tasks`, `uat`, and `bugs` only; `requirements`, `decisions`, and `roadmaps` keep finished items in place (closed in the family `index.md`). `index.md` and `lifecycle.md` in the family directory are never resolution targets.
38
+
39
+ ## Accepted forms
40
+
41
+ The input is one token; any trailing free text is the caller's concern.
42
+
43
+ | # | Form | Recognized by | Examples |
44
+ |---|------|---------------|----------|
45
+ | 1 | **Path** | contains `/` or ends in `.md` | `wiki/work/tasks/TASK-0086-uat-fail-offers-bug-file.md` |
46
+ | 2 | **Full ID or ID-slug** | `PREFIX-` then digits, optionally `-slug`; a family's declared legacy prefix (Family table Notes) is accepted as input too | `TASK-0086`, `TASK-0086-uat-fail-offers-bug-file`, legacy `TASK-074`, legacy-prefix `REQ-0003`, legacy-prefix `DEC-0001` |
47
+ | 3 | **`NNN-slug` / `NNNN-slug`** | digits, then `-slug` | `0086-uat-fail-offers-bug-file`, `074-serena-project-from-cwd` |
48
+ | 4 | **Bare number** | digits only | `86`, `086`, `0086` |
49
+ | 5 | **Empty / free-text description** | nothing, or words that are not forms 1-4 | not resolved here — the caller states its own behavior (pick-list, auto-pick, survey, or STOP) |
50
+
51
+ ## Procedure
52
+
53
+ 1. **Split off a `#DM` suffix** if the family is `decisions` and the input contains `#D<n>` (see **`#DM` suffix**). Resolve the rest.
54
+ 2. **Path (form 1).** Confirm the file exists with `find_file`. Missing: STOP `File not found: <path>`. Never create the file. A path outside the family's directory (or its `archive/`, when scope allows) is a resolution error: STOP and report.
55
+ 3. **Otherwise extract the number.** Parse the digits of the input to an **integer**, so `3`, `003`, and `0003` are equal. Never derive a mask by string-concatenating the raw input.
56
+ 4. **Build the masks** from the family's `PREFIX` and the integer, zero-padded:
57
+ 1. `PREFIX-<pad4>-*.md` (current 4-digit IDs), then
58
+ 2. `PREFIX-<pad3>-*.md` (legacy 3-digit IDs), then
59
+ 3. for a family whose Notes declare a **legacy prefix** (`requirements`: `REQ`; `decisions`: `DEC`), the same two masks with `LEGACY-` in place of `PREFIX-` (`REQ-<pad4>-*.md`, `REQ-<pad3>-*.md`; `DEC-<pad4>-*.md`, `DEC-<pad3>-*.md`) — same integer, both widths, always after every `PREFIX` mask.
60
+
61
+ Try them in that order with `find_file` over the search scope; stop at the first mask that matches. When the input carried a slug (forms 2-3 with `-slug`), try `PREFIX-<padN>-<slug>.md` first for each width (then the legacy-prefix equivalents), then fall back to the prefix-only masks above. A legacy-prefix input (for example `REQ-0003`, `DEC-0001`) is reduced to its integer like any other, so it resolves to a migrated `PRD-0003-*.md` / `ADR-0001-*.md` file as well as to an unmigrated `REQ-0003-*.md` / `DEC-0001-*.md`; the number, not the input's prefix, selects the file.
62
+ 5. **Apply the match outcome** (below).
63
+
64
+ ## Match outcomes
65
+
66
+ | Matches | Result |
67
+ |---------|--------|
68
+ | 0 | STOP `No <family> matching '<input>' found.` Never invent a file or guess a nearby number. |
69
+ | 1 | Resolved. Hand the path back to the caller, plus which directory matched when scope is not `active`. |
70
+ | more than 1 | **Ambiguous** — handled per the caller's declared mode (below). |
71
+
72
+ - **interactive** — list the matches and ask which one via `AskUserQuestion`. Never pick silently.
73
+ - **headless** (`uat-auto`, `uat-auto-plus`) — never prompt. STOP and report the ambiguity in the completion summary.
74
+
75
+ ## Search scope
76
+
77
+ The caller declares exactly one:
78
+
79
+ | Scope | Behavior |
80
+ |-------|----------|
81
+ | `active` | Search the family directory only. The default. |
82
+ | `active+archive` | Search the family directory, then its `archive/`. Report which one matched. |
83
+ | `active-then-archive-gate` | Search the family directory first. A hit only in `archive/` means the item is **already terminal** — hand that back to the caller as a gate result rather than as a normal resolution (used by `bug-close`). |
84
+
85
+ `active+archive` and `active-then-archive-gate` are valid only for `tasks`, `uat`, and `bugs` — the families that still archive.
86
+
87
+ **Legacy fallback (permanent) for `requirements`, `decisions`, `roadmaps`.** These families no longer archive, so `scope: active` searches the family directory and, on zero matches, falls back to `<family>/archive/` if that directory exists, reporting the hit as a legacy location. Projects that archived items under the older layout keep resolving. New code never writes to that `archive/`.
88
+
89
+ ## `#DM` suffix (decisions)
90
+
91
+ A decisions reference may end in `#D<n>` (for example `ADR-0001#D2`, legacy `DEC-0001#D2`, or `0001-wiki-cross-family-linking-schema#D2`). Strip the suffix **before** resolving the file, resolve the file by the usual masks, and hand the suffix back separately so the caller can select the decision block. Choosing among several decision blocks (one proposed vs. many) is the caller's logic, not resolution.
92
+
93
+ ## Worked examples
94
+
95
+ Every filename below was verified to exist in this repo.
96
+
97
+ | Form | Family | Input | Resolves to |
98
+ |------|--------|-------|-------------|
99
+ | 1 Path | tasks | `wiki/work/tasks/TASK-0086-uat-fail-offers-bug-file.md` | that file, after `find_file` confirms it |
100
+ | 2 Full ID | tasks | `TASK-0086` | `wiki/work/tasks/TASK-0086-uat-fail-offers-bug-file.md` via mask `TASK-0086-*.md` |
101
+ | 2 ID-slug | tasks | `TASK-0086-uat-fail-offers-bug-file` | same file via `TASK-0086-uat-fail-offers-bug-file.md` |
102
+ | 2 Legacy ID | tasks | `TASK-074` | `wiki/work/tasks/TASK-074-serena-project-from-cwd.md` — `TASK-0074-*.md` matches nothing, so the legacy mask `TASK-074-*.md` matches |
103
+ | 3 NNNN-slug | tasks | `0086-uat-fail-offers-bug-file` | `wiki/work/tasks/TASK-0086-uat-fail-offers-bug-file.md` |
104
+ | 3 NNN-slug | tasks | `074-serena-project-from-cwd` | `wiki/work/tasks/TASK-074-serena-project-from-cwd.md` |
105
+ | 4 Bare number | roadmaps | `11` | `wiki/work/roadmaps/ROADMAP-011-build-bootstrap-prefs-tui.md` — legacy 3-digit fallback after `ROADMAP-0011-*.md` misses |
106
+ | 4 Bare number | bugs | `6` | `wiki/work/bugs/BUG-0006-mv-guard-segment-split-omits-pipe.md` |
107
+ | 4 Bare number | uat | `87` | `wiki/work/uat/UAT-0087-bug-close-clustering-offers-regression-task.md` |
108
+ | 2 Full ID + `#DM` | decisions | `DEC-0001#D2` | legacy-prefix input; suffix `#D2` split off; the `ADR` masks (`ADR-0001-*.md`, `ADR-001-*.md`) match nothing, then the legacy mask `DEC-0001-*.md` matches `wiki/work/decisions/archive/DEC-0001-wiki-cross-family-linking-schema.md` (scope `active+archive` — this decision is archived); caller gets `D2` back separately |
109
+ | 2 Full ID + `#DM` | decisions | `ADR-0001#D2` | same integer, so it resolves to that same `DEC-0001-wiki-cross-family-linking-schema.md` file before migration, and to `ADR-0001-*.md` after it (the migration keeps the number); caller gets `D2` back separately |
110
+ | 2 Full ID + `#DM` | decisions | `ADR-0002#D1` | a new-item input: mask `ADR-0002-*.md` matches the file `adr-create` writes as `ADR-0002-<group-slug>.md` (no such file exists in this repo yet); caller gets `D1` back separately |
111
+ | 4 Bare number | requirements | `3` | no requirement files exist in this repo yet; would try `PRD-0003-*.md`, `PRD-003-*.md`, `REQ-0003-*.md`, then `REQ-003-*.md` |
112
+ | 2 Legacy prefix | requirements | `REQ-0003` | legacy input; same integer, so it resolves to `PRD-0003-*` after migration, or to `REQ-0003-*` before it (no such files exist in this repo yet) |
113
+ | 5 Empty | any | *(nothing)* | not resolved here — the caller's `empty:` behavior applies |
114
+ | any | tasks | `9999` | 0 matches — STOP `No tasks matching '9999' found.` |
115
+
116
+ ## CRITICAL rules
117
+
118
+ - **Integer, not string.** Compare and pad numbers as integers; never build a mask from raw input.
119
+ - **Both widths.** Always try the 4-digit mask, then the 3-digit legacy mask. Files with either width coexist. A declared legacy prefix (Family table Notes) is accepted as input and is tried after the current prefix, at both widths.
120
+ - **Never create or guess.** A missing path or zero matches is a STOP, never a fabricated file.
121
+ - **Headless never prompts.** Ambiguity in `headless` mode STOPs and is reported, never asked.
122
+ - **Tools.** `find_file` / `list_dir` only for lookups — no `ls`, `find`, or `grep`.
123
+ - **Number allocation is elsewhere.** Picking the next free number (`max+1`) is a different algorithm and is not defined here.
124
+
125
+ ## Caller deltas
126
+
127
+ What each consumer supplies. Anything not listed is the caller's own logic and stays in its `SKILL.md`.
128
+
129
+ | Consumer | `family` | `scope` | `ambiguous` | Empty input / gate |
130
+ |----------|----------|---------|-------------|--------------------|
131
+ | `prd-deprecate`, `prd-finalize` | requirements | `active` | interactive | per skill; legacy `archive/` fallback applies (see Search scope) |
132
+ | `adr-extract` | requirements | `active` | interactive | PRD mode only: empty → pick-list of `approved` PRDs; gate `status: approved`. A path outside `wiki/work/requirements/` is document mode and skips resolution entirely. Legacy `archive/` fallback applies |
133
+ | `prd-compile` | requirements | `active` | interactive | empty: auto-look for `status: approved`; gate: `status: approved`. Legacy `archive/` fallback applies |
134
+ | `adr-finalize`, `adr-deprecate`, `adr-walkthrough`, `adr-next` | decisions | `active` | interactive | per skill; `#DM` handled per this doc; legacy `archive/` fallback applies |
135
+ | `roadmap-next` | roadmaps | `active` | interactive | empty: STOP; legacy `archive/` fallback applies |
136
+ | `bug-triage` | bugs | `active` | interactive | not found: STOP |
137
+ | `bug-close` | bugs | `active-then-archive-gate` | interactive | gates: found in root, "must be triaged and worked first"; found in `archive/`, "already terminal" |
138
+ | `tackle`, `uat-skip`, `uat-create` | tasks | `active` | interactive | per skill |
139
+ | `task-close` | tasks | `active+archive` | interactive | per skill |
140
+ | `uat-walk` (via `UAT-CORE.md`) | uat | `active` | interactive | empty: STOP and report |
141
+ | `uat-auto`, `uat-auto-plus` (via `UAT-CORE.md`) | uat | `active` | headless | empty: auto-pick lowest pending `<NNN>` |
142
+ | `uat-assess` | tasks | `active+archive` | headless | n/a — follows a UAT's `task:` back-link; not found: report as an orphan, never STOP |
@@ -0,0 +1,50 @@
1
+ # SKILL-BOILERPLATE — shared boilerplate for wiki-family skills
2
+
3
+ The **Prereqs** grammar, **Edit hygiene** rules, and **Number allocation** algorithm that recur across the wiki-family skills live here once. Consumers: the `task-*`, `bug-*`, `uat-*`, `prd-*`, `req-*`, `adr-*`, `roadmap-*`, `wiki-*`, `tackle`, and `power-mode` skills. **Each consuming skill references a section by name and never restates it.** Only the Prereqs line stays inline (see below); `test/skill-boilerplate.test.js` enforces it.
4
+
5
+ Pointer forms, from a consumer's `SKILL.md`: `Edit only — see ~/.claude/skills/_shared/SKILL-BOILERPLATE.md § Edit hygiene.` and `Allocate the next ID per ~/.claude/skills/_shared/SKILL-BOILERPLATE.md § Number allocation (family: <dir>, prefix: <PREFIX>).`
6
+
7
+ ## Prereqs
8
+
9
+ Every consuming skill opens with exactly one of these verbatim forms:
10
+
11
+ 1. `**Prereqs:** obey \`wiki/guides/mcp-tools.md\`.`
12
+ 2. `**Prereqs:** obey \`wiki/guides/mcp-tools.md\`; run /primer if not done this session.`
13
+ 3. Either form with ` + \`wiki/work/<family>/lifecycle.md\`` after the `mcp-tools.md` reference, where `<family>` is one of `tasks`, `bugs`, `uat`.
14
+
15
+ Choosing:
16
+
17
+ - Add the `/primer` clause when the skill does codebase or wiki exploration.
18
+ - Add the lifecycle reference when the skill reads or writes that family's files.
19
+
20
+ The line stays inline because it is the instruction to read `mcp-tools.md`: hiding it behind a pointer costs an extra Read on every invocation with no drift benefit. Single-sourcing the grammar here plus test enforcement gives drift protection without that Read.
21
+
22
+ ## Edit hygiene
23
+
24
+ - Never use `sed`, `awk`, `perl -i`, `echo >>`, `cat <<EOF`, or any shell redirection to modify a markdown or config file.
25
+ - Use `Read` then `Edit`: one `Edit` per change, even when there are many. Never `Write` to rewrite an existing file in full.
26
+ - Appending to `wiki/log.md` or an index file is a `Read` then `Edit`, not `echo >>`.
27
+ - Bash is reserved for commands with no dedicated tool (for example `git mv`).
28
+
29
+ See `wiki/guides/mcp-tools.md` "Common anti-patterns". Each violation triggers a permission prompt.
30
+
31
+ ## Number allocation
32
+
33
+ Parameterized by (family directory, ID prefix); values in the table below.
34
+
35
+ 1. `list_dir` both `wiki/work/<family>/` and `wiki/work/<family>/archive/`; skip either that does not exist.
36
+ 2. Collect the numeric value of every `<PREFIX><digits>-` filename prefix across both, regardless of digit count (legacy files are 3-digit, new ones 4-digit). Compare as integers, ignoring leading zeros.
37
+ 3. Families flagged **Index scan: yes** also scan the family `index.md` for reserved IDs and include them in the max. Match both widths (for roadmaps, `ROADMAP-\d+`, never a 3-digit-only pattern).
38
+ 4. New number = `max + 1`, zero-padded to 4 digits. In a brand-new project the first ID is `<PREFIX>0001`; in an existing project continue from the current max, never restart at 1.
39
+ 5. Never re-use a number. Terminal items keep their ID forever, in `archive/`.
40
+ 6. **Re-verify immediately before `Write`:** repeat steps 1-4. If the planned number is now taken, silently bump to the next free number. Never call `Write` before completing the re-scan.
41
+
42
+ | Family | Directory | Prefix | Index scan | Notes |
43
+ |--------|-----------|--------|------------|-------|
44
+ | tasks | `wiki/work/tasks/` | `TASK-` | yes | e.g. `TASK-NNNN-slug.md` |
45
+ | roadmaps | `wiki/work/roadmaps/` | `ROADMAP-` | yes | index scan must match 3- and 4-digit IDs |
46
+ | bugs | `wiki/work/bugs/` | `BUG-` | yes | real filenames are `BUG-NNNN-slug.md`; `bug-create` previously said a bare `NNNN-` prefix, and the lifecycle prefix wins |
47
+ | requirements | `wiki/work/requirements/` | `PRD-` | no | also count legacy `REQ-` filenames until migrated, so a number is never reused (the migration keeps numbers) |
48
+ | decisions | `wiki/work/decisions/` | `ADR-` | no | also count legacy `DEC-` filenames until migrated — one number sequence across both prefixes, so a new ADR never collides with an existing `DEC-` item (the migration keeps numbers); new filenames are `ADR-NNNN-slug.md`, blocks are `ADR-NNNN#DM`; `adr-create` previously said a bare `NNNN-` prefix, and the lifecycle prefix wins |
49
+
50
+ `uat` is excluded: its number mirrors its task's number, so it is never allocated.
@@ -0,0 +1,112 @@
1
+ ---
2
+ name: adr-assess
3
+ description: Survey all active ADRs together — surface proposed decisions and accepted decisions with no task, follow supersession chains, and rank decision blocks into one prioritized list with a status update for each
4
+ category: researching
5
+ model: claude-sonnet-5
6
+ disable-model-invocation: false
7
+ user-invocable: true
8
+ ---
9
+ **Prereqs:** obey `wiki/guides/mcp-tools.md`; run /primer if not done this session.
10
+
11
+ # ADR Assessment
12
+
13
+ Assess every active decision in `wiki/work/decisions/` together — this is the multi-ADR counterpart to `/adr-finalize` (one proposed block) and `/adr-walkthrough` (one group), which each operate on exactly one item you've already picked. Status lives on each decision block, so the ranked unit is the block (`ADR-NNNN#DM`), listed under its group. This skill folds in the `/adr-next` check (accepted with no task) and leaves `/adr-next` in place as the fast single-gap form.
14
+
15
+ This skill is strictly read-only: it never flips a status, never creates a file, and never asks questions. Acting on a decision is the job of the commands named in each `Next` line.
16
+
17
+ ---
18
+
19
+ ## Step 1: Discover active ADR groups
20
+
21
+ Read the Family table in `lib/skills/_shared/ID-RESOLUTION.md` for the decisions directory and prefixes — do not hardcode them. Legacy `DEC-` files coexist with `ADR-` files until migrated, so match both prefixes.
22
+
23
+ `list_dir` the decisions directory for `.md` files **directly** in it (ignore every subdirectory); skip `lifecycle.md`, `index.md`, `README.md`. None found → STOP: `No active ADRs found in wiki/work/decisions/. Use /adr-create <topic> to create one.`
24
+
25
+ Read the block statuses and which are terminal from `wiki/work/decisions/lifecycle.md` (currently `proposed | accepted | deprecated | superseded`). Status is read per block, never from the file's location or its group frontmatter.
26
+
27
+ ## Step 2: Parse every group
28
+
29
+ `Read` each file in full and extract:
30
+
31
+ - **Group frontmatter**: `id`, `aliases`, `title`, `created`, `updated`, `tags`.
32
+ - **Per block** (each `## D1.`-style H2): title, `Status`, `Date`, `Supersedes`, `Tags`, and the `### Links` section's `Source task(s):` line.
33
+
34
+ A block `Status` outside the lifecycle's enum is reported in Step 6c, and the block is ranked as an other-proposed block.
35
+
36
+ ## Step 3: Task-reference and gating analysis
37
+
38
+ For each `accepted` block, decide whether it has a task. It has one when `Source task(s):` lists at least one task path or `[[TASK-NNNN]]` link. It also has one when `search_for_pattern` over `wiki/work/tasks/` finds `implements::[[ADR-NNNN#DM]]` (under both prefixes, and by the group's aliases) — a task that exists but was never written into `### Links` still counts. Otherwise the block is **accepted with no task**. A listed task path that no longer exists is a broken reference — note it and treat the block as having no task.
39
+
40
+ Build the gating set for each `proposed` block. For every active roadmap in `wiki/work/roadmaps/` (by `status:`, not location), run the **Parse a roadmap** procedure defined in `lib/skills/roadmap-next/SKILL.md` — do not restate it here, follow it as written — and take its decision-reference set (`linked_decisions` plus inline `rel::[[ADR-…]]` / legacy `DEC-` links). A reference to a bare group counts for every proposed block in it. Also `search_for_pattern` the block's `ADR-NNNN#DM` (and group ID and aliases, both prefixes) across `wiki/work/requirements/` and `wiki/work/tasks/`. Record per proposed block the roadmaps, PRDs, and tasks that reference it; the count is its **gated count**. A block with a gated count above zero is a **proposed block that gates live work**; one with zero is a proposed block with no task or other dependent.
41
+
42
+ ## Step 4: Supersession chains
43
+
44
+ Follow every `Supersedes:` field and every `superseded by` pointer between blocks and render each chain as `ADR-0001#D2 → ADR-0004#D1` (oldest to newest, using each file's own `id:`). Flag as chain problems:
45
+
46
+ - a **cycle** in the chain;
47
+ - **asymmetry** — `Supersedes:` set on the new block but the old block not marked `superseded by`, or the reverse;
48
+ - a `superseded` block whose successor is not `accepted`;
49
+ - a pointer to a block or file that does not exist.
50
+
51
+ Annotate any `proposed` block that would supersede an `accepted` one in its report row. The supersession rules themselves live in `wiki/work/decisions/lifecycle.md`; do not re-derive them here.
52
+
53
+ ## Step 5: Rank decision blocks
54
+
55
+ **Long-idle threshold: 60 days** — a proposed block is long-idle when today − `Date` is more than 60 days.
56
+
57
+ Blocks that are `superseded` or `deprecated`, and `accepted` blocks that have a task, are closed: excluded from ranking and counted once in the report footer. Order the remaining blocks, highest priority first, using this precedence:
58
+
59
+ 1. **Proposed blocks that gate live work** (Step 3) — more gated first; oldest `Date` breaks ties.
60
+ 2. **Accepted blocks with no task** — decided but never scheduled; oldest `Date` first.
61
+ 3. **Other proposed blocks** — oldest `Date` first (age = today − `Date`).
62
+
63
+ Tie-break within a tier: oldest `Date`, then `ADR-NNNN#DM` ascending. Record a one-sentence rationale per block — a judgment call the user can override, not a fact. If nothing is left to rank, STOP with the empty-family text from Step 1.
64
+
65
+ ## Step 6: Report
66
+
67
+ Print, in this order:
68
+
69
+ ### 6a. Prioritized decisions
70
+
71
+ ```
72
+ ## Prioritized Decisions
73
+
74
+ | Rank | Decision | Status | Date | Rationale | Gates / Chain |
75
+ |------|----------|--------|------|-----------|---------------|
76
+ | 1 | ADR-NNNN#DM — <title> | proposed | YYYY-MM-DD | <one sentence> | gates ROADMAP-NNNN, TASK-NNNN |
77
+ | 2 | ADR-MMMM#DM — <title> | accepted | YYYY-MM-DD | <one sentence> | no task |
78
+ ```
79
+
80
+ `Gates / Chain` lists what a proposed block gates (Step 3), any supersession chain it sits in (Step 4), and `no task` for an accepted block with none; `—` if none.
81
+
82
+ ### 6b. Status update per decision
83
+
84
+ One block per ranked decision, in ranked order:
85
+
86
+ ```
87
+ ### ADR-NNNN#DM — <title>
88
+ - Group: <ADR-NNNN — group title>
89
+ - Status: <proposed | accepted> — <gating | no task | idle | long-idle>
90
+ - Summary: <one line>
91
+ - Next: <see below>
92
+ ```
93
+
94
+ `Next` by state:
95
+
96
+ - Proposed → `/adr-finalize <file>#DM`; a group with several proposed blocks: `/adr-walkthrough <file>`; a long-idle proposed block: or `/adr-deprecate <file>#DM`
97
+ - Accepted with no task → `/task-create <description> --decision ADR-NNNN#DM`
98
+
99
+ ### 6c. Warnings (omit if none found)
100
+
101
+ Flag, each as its own short block: chain problems from Step 4, broken references from Step 3, and blocks with an unrecognized `Status`.
102
+
103
+ Footer, when Step 5 excluded any block: `Closed: N (not assessed)`.
104
+
105
+ ---
106
+
107
+ ## Constraints
108
+
109
+ - Read-only — no exception. No file edits, no shell, no prompts, no log or index changes, no status flips. `/adr-finalize`, `/adr-walkthrough`, `/task-create`, and `/adr-deprecate` are the follow-up actions the user runs once they act on this report.
110
+ - Permitted tools: `list_dir`, `find_file`, `search_for_pattern`, `Read`.
111
+ - Never bash reads (`cat`/`find`/`grep`/`sed`/`ls`).
112
+ - Keep the report terse — no preamble, no closing summary beyond the tables above.
@@ -1,5 +1,5 @@
1
1
  ---
2
- name: decision-create
2
+ name: adr-create
3
3
  description: Create a Decision Group file in wiki/work/decisions/ with one or more proposed decisions, table-only comparisons, and mermaid flowcharts
4
4
  category: planning
5
5
  model: claude-opus-5
@@ -31,11 +31,12 @@ See the lifecycle doc's "When to Write" / "When NOT to Write" tables. In short:
31
31
  2. Decide single vs group (Step 1.5).
32
32
  3. Recall Serena memories that may inform any decision: `list_memories` (filter by topic), `read_memory` for architecture/gotcha/integration memories touching the topic.
33
33
  4. Read `CLAUDE.md`, `PROJECT_STATUS.md` (if present), `wiki/work/decisions/lifecycle.md`, and a sample of recent decisions for local conventions.
34
+ 5. **Prior-art scan (optional, cheap — skip silently if nothing plausible turns up):** read `wiki/index.md`'s `### Concepts` and `### Sources` sections for titles/summaries matching the topic, then run `mcp__serena__search_for_pattern` for the topic's key terms across `wiki/knowledge/concepts/` and `wiki/knowledge/sources/`. This is a scan-and-surface check, not a `/research` substitute — don't widen it into a full research pass. Any candidate hit gets confirmed with the user in Step 4, never cited unconfirmed.
34
35
 
35
36
  ## Step 1.5: Single vs Decision Group triage
36
37
  Use the lifecycle doc's "When to Group vs Split":
37
38
 
38
- | Signal | Group | Split (write one now, `/decision-create` again later) |
39
+ | Signal | Group | Split (write one now, `/adr-create` again later) |
39
40
  |--------|-------|-------|
40
41
  | Shared context, drivers, deciders | ✅ | — |
41
42
  | Tightly coupled (one constrains the next) | ✅ | — |
@@ -43,13 +44,13 @@ Use the lifecycle doc's "When to Group vs Split":
43
44
  | Different audiences / timelines | — | ✅ |
44
45
  | One much larger than the others | — | ✅ |
45
46
 
46
- Default to **single-decision** unless `$ARGUMENTS` starts with `group:` or the user lists multiple. When in doubt, ask with the table visible. If grouping, request a list (one short title each, 2-6).
47
+ Default to **single-decision** unless `$ARGUMENTS` starts with `group:` or the user lists multiple. When in doubt, ask with the table visible. If grouping, request a list (one short title each, 2-6). To derive candidate groups from a source, `/adr-extract <PRD or document>` prints ready-made `/adr-create group: <slug> (from <source>)` invocations.
47
48
 
48
49
  ## Step 2: Locate directory, assign number
49
50
  1. Find/create `wiki/work/decisions/`. If creating, add a `lifecycle.md` index and confirm via `AskUserQuestion` first.
50
51
  2. Read `lifecycle.md` for the current chain, area conventions, graph.
51
- 3. Next file number: `list_dir` on `wiki/work/decisions/` **and** `wiki/work/decisions/archive/` (skip either that doesn't exist) — highest 4-digit prefix across both + 1 (first is `0001`). Never re-use a number; archived/superseded decisions keep theirs forever.
52
- 4. Derive the file slug — names the **group**, lowercase dash-separated ≤60 chars (single: `DEC-0007-session-storage-strategy.md`; group: `DEC-0007-session-management.md`).
52
+ 3. Allocate the next ID per `~/.claude/skills/_shared/SKILL-BOILERPLATE.md` § Number allocation (family: `wiki/work/decisions/`, prefix: `ADR-`, also count legacy `DEC-`, no index scan) — one number sequence across both prefixes: the new number is `max(N)+1` over every `ADR-NNNN-*` **and** legacy `DEC-NNNN-*` filename (3- or 4-digit) in `wiki/work/decisions/` and any legacy `archive/` subfolder, so a new ADR can never collide with an existing `DEC-` item.
53
+ 4. Derive the file slug — names the **group**, lowercase dash-separated ≤60 chars (single: `ADR-0007-session-storage-strategy.md`; group: `ADR-0007-session-management.md`).
53
54
 
54
55
  ## Step 2.5: Detect existing decision area (per-decision supersession check, mandatory)
55
56
  Prevents two parallel `accepted` decisions in one area (breaks the chain). Per planned decision:
@@ -73,24 +74,24 @@ Prevents two parallel `accepted` decisions in one area (breaks the chain). Per p
73
74
  Group members may share evidence sources (Shared Context), but each block needs its own drivers/options/consequences. If a block lacks evidence for an option/driver, **drop it** rather than fabricate; note the gap in Step 9.
74
75
 
75
76
  ## Step 4: Clarify with the user (mandatory)
76
- `AskUserQuestion`, **per decision**, at minimum: (1) **Status** — strongly prefer `proposed` (default); may differ per block. (2) **Recommended option** — present research-backed rec with the comparison table; user confirms/overrides. (3) **Deciders** — owner of *this* decision (may differ per block; default git user). (4) **Tags (mandatory, non-empty)** — 1-3 short tags identifying this block's area (required for supersession detection). (5) **Supersedes** — if Step 2.5 surfaced candidates, ask which (if any): `DEC-NNNN#DM`, `none`, or "decide at finalize time".
77
+ `AskUserQuestion`, **per decision**, at minimum: (1) **Status** — strongly prefer `proposed` (default); may differ per block. (2) **Recommended option** — present research-backed rec with the comparison table; user confirms/overrides. (3) **Deciders** — owner of *this* decision (may differ per block; default git user). (4) **Tags (mandatory, non-empty)** — 1-3 short tags identifying this block's area (required for supersession detection). (5) **Supersedes** — if Step 2.5 surfaced candidates, ask which (if any): `ADR-NNNN#DM` (legacy `DEC-NNNN#DM` accepted), `none`, or "decide at finalize time". (6) **Prior art** — if Step 1's scan surfaced a candidate page, ask e.g. "Found `wiki/knowledge/concepts/<slug>.md` — relevant?"; on confirmation, add `derived_from::[[<slug>]]` to that decision's Shared Context or `### Context (decision-specific)`. Skip this question entirely when the scan found nothing plausible.
77
78
 
78
79
  **Refuse to write the file if any block has empty `Tags`.** For groups, batch all decisions' questions in one `AskUserQuestion` when feasible, but keep questions per-decision.
79
80
 
80
81
  ## Step 4.5: Re-verify next decision number — IMMEDIATELY before writing
81
82
 
82
- Re-run the scan from Step 2 (`list_dir` on `wiki/work/decisions/` and `archive/`, highest 4-digit prefix + 1). If the number planned earlier is now taken, silently bump to the new next-available number. **Never call `Write` before completing this re-scan.**
83
+ Repeat § Number allocation step 6 (same family and prefix as Step 2, with the same both-prefix rule — `max(N)+1` over `ADR-` and legacy `DEC-` filenames); never call `Write` before completing it. If the planned number is now taken, silently bump to the next free number.
83
84
 
84
85
  ## Step 5: Generate the file
85
- Write to `wiki/work/decisions/DEC-NNNN-<group-slug>.md` using this template. **Tables only, mermaid for flows** — mandatory in every block.
86
+ Write to `wiki/work/decisions/ADR-NNNN-<group-slug>.md` using this template. **Tables only, mermaid for flows** — mandatory in every block.
86
87
 
87
88
  ````markdown
88
89
  ---
89
- id: DEC-NNNN
90
- aliases: [DEC-NNNN]
90
+ id: ADR-NNNN
91
+ aliases: [ADR-NNNN]
91
92
  ---
92
93
 
93
- # DEC-NNNN: <Decision-Group Title>
94
+ # ADR-NNNN: <Decision-Group Title>
94
95
 
95
96
  > Decision Group covering <area-1>, <area-2>, <area-3>.
96
97
 
@@ -100,18 +101,18 @@ aliases: [DEC-NNNN]
100
101
 
101
102
  ## Shared Context
102
103
 
103
- <Context applying to every decision in the group; don't restate per block. Link code areas (repo-relative), prior decisions ([[DEC-NNNN-slug|DEC-NNNN#DM: title]]), external constraints.>
104
+ <Context applying to every decision in the group; don't restate per block. Link code areas (repo-relative), prior decisions ([[ADR-NNNN-slug|ADR-NNNN#DM: title]]), external constraints.>
104
105
 
105
106
  ---
106
107
 
107
108
  ## D1. <Short Title — Verb Phrase>
108
109
 
109
- - **Status**: <proposed | accepted | deprecated | superseded by DEC-XX#DY>
110
+ - **Status**: <proposed | accepted | deprecated | superseded by ADR-XX#DY>
110
111
  - **Date**: YYYY-MM-DD
111
112
  - **Deciders**: <names or roles>
112
113
  - **Consulted**: <optional>
113
114
  - **Informed**: <optional>
114
- - **Supersedes**: <DEC-MMMM#DK | none>
115
+ - **Supersedes**: <ADR-MMMM#DK | none>
115
116
  - **Tags**: <area-1>, <area-2>
116
117
 
117
118
  ### Context (decision-specific)
@@ -170,8 +171,8 @@ flowchart LR
170
171
  | <e.g. p99 latency> | < 200ms | 30 days post-deploy |
171
172
 
172
173
  ### Links
173
- - Related decisions: [[DEC-NNNN-slug|DEC-NNNN#DM: title]]
174
- - Supersedes: [[DEC-MMMM-slug|DEC-MMMM#DK: title]] (if applicable)
174
+ - Related decisions: [[ADR-NNNN-slug|ADR-NNNN#DM: title]]
175
+ - Supersedes: [[ADR-MMMM-slug|ADR-MMMM#DK: title]] (if applicable)
175
176
  - Source task(s): `wiki/work/tasks/TASK-NNNN-slug.md`
176
177
 
177
178
  ---
@@ -187,28 +188,28 @@ flowchart LR
187
188
  **Single-decision files** have one `D1` block and no `D2`/`D3`; `Shared Context` may merge into D1's `### Context` or be omitted.
188
189
 
189
190
  ## Step 6: Maintain the Decision Index
190
- 1. Append to `wiki/work/decisions/index.md`: `- [DEC-NNNN — Title](DEC-NNNN-slug.md) — one-line summary · D1 proposed`.
191
+ 1. Append under `## Active` in `wiki/work/decisions/index.md` (a group with a `proposed` block is Active; groups that finish move to `## Closed` via `/adr-finalize`): `- [ADR-NNNN — Title](ADR-NNNN-slug.md) — one-line summary · D1 proposed`.
191
192
  2. Add **one row per decision** to the Index in `wiki/work/decisions/lifecycle.md` (a 3-decision file adds 3 rows). Columns: `File`, `Decision`, `Title`, `Decision Area`, `Status`, `Date`, `Deciders`, `Supersedes`, `Superseded By` (see lifecycle doc spec).
192
193
  3. **If any decision was drafted `accepted` AND supersedes an existing one** (rare), apply the two-block cross-reference rule per pair, atomically:
193
- - **Superseded block:** `Status: accepted` → `superseded by DEC-N#DX`; callout `> **Superseded by [[DEC-NNNN-slug\|DEC-N#DX: title]]** on YYYY-MM-DD` directly under that decision's H2.
194
+ - **Superseded block:** `Status: accepted` → `superseded by ADR-N#DX`; callout `> **Superseded by [[ADR-NNNN-slug\|ADR-N#DX: title]]** on YYYY-MM-DD` directly under that decision's H2.
194
195
  - **Superseded block's siblings:** untouched.
195
- - **New block:** `Supersedes` metadata; `### Links` references `[[DEC-MMMM-slug\|DEC-MMMM#DK: title]]`.
196
+ - **New block:** `Supersedes` metadata; `### Links` references `[[ADR-MMMM-slug\|ADR-MMMM#DK: title]]` (the superseded target may be a legacy `DEC-` item — write its own ID as it appears in its file).
196
197
  - **Index:** two rows updated (superseder gets `Supersedes`; superseded gets `Status` + `Superseded By`).
197
198
  - **Graph:** new node; supersession edge; superseded node's class flipped.
198
- **Default to `proposed`** — create-time supersession is rare; `/decision-finalize` enforces it atomically.
199
+ **Default to `proposed`** — create-time supersession is rare; `/adr-finalize` enforces it atomically.
199
200
  4. Don't delete/mutate existing index rows beyond what supersession requires (append-mostly).
200
201
 
201
- ## Step 7: Append to `wiki/log.md` (`Edit`, never `echo >>`)
202
- `## [YYYY-MM-DD] decision-create | DEC-NNNN <Decision-Group Title>`
202
+ ## Step 7: Append to `wiki/log.md` (`Edit` only)
203
+ `## [YYYY-MM-DD] adr-create | ADR-NNNN <Decision-Group Title>`
203
204
 
204
205
  ## Step 8: Cross-link from related artifacts
205
- For any decision prompted by an active task/feature, link both ways (`Read` then `Edit`, never `echo >>`/`sed`): in the source task file append `**Decision**: [[DEC-NNNN-slug|DEC-NNNN#DM: title]]`; in the decision's `### Links` list the source task path.
206
+ For any decision prompted by an active task/feature, link both ways (Edit only — see `~/.claude/skills/_shared/SKILL-BOILERPLATE.md` § Edit hygiene): in the source task file append `**Decision**: [[ADR-NNNN-slug|ADR-NNNN#DM: title]]`; in the decision's `### Links` list the source task path.
206
207
 
207
208
  ## Step 9: Update memories
208
- If a decision establishes a non-obvious pattern, integration constraint, or gotcha: `mcp__serena__write_memory` (topic-hierarchical name, e.g. `architecture/data-layer/cache-strategy`), referencing `DEC-NNNN#DM` not just the file. Skip self-documenting decisions.
209
+ If a decision establishes a non-obvious pattern, integration constraint, or gotcha: `mcp__serena__write_memory` (topic-hierarchical name, e.g. `architecture/data-layer/cache-strategy`), referencing `ADR-NNNN#DM` not just the file. Skip self-documenting decisions.
209
210
 
210
211
  ## Step 10: Report
211
- Tabular summary: File path, Decisions in file (`D1: <title>`, …), Status per decision, Supersession queued for finalize? (per decision), Index updated (N rows), Graph updated (only if any drafted `accepted`), Log appended, Suggested next steps (`/decision-finalize <file>#D1`, …). Note any decision dropped for lack of evidence under a "Gaps" section.
212
+ Tabular summary: File path, Decisions in file (`D1: <title>`, …), Status per decision, Supersession queued for finalize? (per decision), Index updated (N rows), Graph updated (only if any drafted `accepted`), Log appended, Suggested next steps (`/adr-finalize <file>#D1`, …). Note any decision dropped for lack of evidence under a "Gaps" section.
212
213
 
213
214
  ---
214
215
 
@@ -218,7 +219,7 @@ Tabular summary: File path, Decisions in file (`D1: <title>`, …), Status per d
218
219
  3. **One decision per `D*` block** — never cover two; split into `D1`/`D2`.
219
220
  4. **Stable decision IDs** — `D2` stays `D2` forever, even if `D1` is later deprecated; never renumber siblings.
220
221
  5. **Present tense, full sentences** — "We will use Redis as the session cache", not "Redis chosen".
221
- 6. **Immutable per decision once accepted** — never edit an accepted block's content; write a superseding decision instead. Only allowed in-place edits: status change (accepted → superseded) + the supersession callout.
222
+ 6. **Immutable per decision once accepted** — never edit an accepted block's content; write a superseding decision instead. Only allowed in-place edits: status change (accepted → superseded, or accepted → deprecated via `/adr-deprecate`) + the supersession or deprecation callout.
222
223
 
223
224
  ## CRITICAL rules
224
225
  1. **Max 3 sub-processes at a time** if delegating research; **always terminate processes when done**.