@codewizard-dt/bootstrap 2.11.1 → 2.13.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 (76) hide show
  1. package/README.md +9 -9
  2. package/lib/README.md +1 -1
  3. package/lib/hooks/lib/serena.js +20 -6
  4. package/lib/prompts/migrate-wiki.md +2 -2
  5. package/lib/prompts/setup-strict-typechecks.md +18 -7
  6. package/lib/scripts/README.md +7 -7
  7. package/lib/scripts/bootstrap-serena.sh +30 -9
  8. package/lib/scripts/build-mcp-guide.sh +3 -3
  9. package/lib/scripts/install-mcps.sh +71 -28
  10. package/lib/scripts/lib.sh +34 -7
  11. package/lib/scripts/migrate-project.sh +9 -2
  12. package/lib/scripts/setup-deployment.sh +9 -0
  13. package/lib/scripts/sync-wiki-scaffold.sh +145 -24
  14. package/lib/scripts/templates/CLAUDE-wiki.md +6 -2
  15. package/lib/scripts/templates/guides/stubs/serena.md +7 -7
  16. package/lib/scripts/templates/wiki/conventions.md +2 -0
  17. package/lib/scripts/templates/wiki/index.md +6 -0
  18. package/lib/skills/bug-close/SKILL.md +1 -1
  19. package/lib/skills/bug-file/SKILL.md +2 -2
  20. package/lib/skills/bug-triage/SKILL.md +1 -1
  21. package/lib/skills/debug-logs/SKILL.md +2 -2
  22. package/lib/skills/decision-create/SKILL.md +1 -1
  23. package/lib/skills/decision-finalize/SKILL.md +1 -1
  24. package/lib/skills/decision-next/SKILL.md +1 -1
  25. package/lib/skills/decision-walkthrough/SKILL.md +1 -1
  26. package/lib/skills/demo/SKILL.md +1 -1
  27. package/lib/skills/eval-create/SKILL.md +7 -3
  28. package/lib/skills/eval-gap/SKILL.md +6 -2
  29. package/lib/skills/eval-run/SKILL.md +1 -1
  30. package/lib/skills/extract-feature/SKILL.md +1 -1
  31. package/lib/skills/gap-assess/SKILL.md +1 -1
  32. package/lib/skills/git-commit/SKILL.md +1 -1
  33. package/lib/skills/lint/SKILL.md +1 -1
  34. package/lib/skills/marp-slideshow/SKILL.md +1 -1
  35. package/lib/skills/mermaid-flowchart/SKILL.md +1 -1
  36. package/lib/skills/now/SKILL.md +1 -1
  37. package/lib/skills/port-feature/SKILL.md +1 -1
  38. package/lib/skills/power-mode/SKILL.md +1 -1
  39. package/lib/skills/primer/SKILL.md +2 -2
  40. package/lib/skills/project-readme/SKILL.md +1 -1
  41. package/lib/skills/req-create/SKILL.md +1 -1
  42. package/lib/skills/req-extract-decisions/SKILL.md +1 -1
  43. package/lib/skills/req-finalize/SKILL.md +1 -1
  44. package/lib/skills/req-retire/SKILL.md +2 -2
  45. package/lib/skills/req-update/SKILL.md +1 -1
  46. package/lib/skills/research/SKILL.md +1 -1
  47. package/lib/skills/roadmap-add/SKILL.md +2 -2
  48. package/lib/skills/roadmap-create/SKILL.md +3 -3
  49. package/lib/skills/roadmap-next/SKILL.md +1 -1
  50. package/lib/skills/serena-config/SKILL.md +1 -1
  51. package/lib/skills/simplify/SKILL.md +1 -1
  52. package/lib/skills/tackle/SKILL.md +3 -3
  53. package/lib/skills/task-add/SKILL.md +1 -1
  54. package/lib/skills/task-audit/SKILL.md +2 -2
  55. package/lib/skills/task-trash/SKILL.md +1 -1
  56. package/lib/skills/task-update/SKILL.md +2 -2
  57. package/lib/skills/uat-auto/SKILL.md +1 -1
  58. package/lib/skills/uat-auto-plus/SKILL.md +1 -1
  59. package/lib/skills/uat-generate/SKILL.md +1 -1
  60. package/lib/skills/uat-skip/SKILL.md +1 -1
  61. package/lib/skills/uat-walk/SKILL.md +1 -1
  62. package/lib/skills/uat-walk/UAT-CORE.md +1 -1
  63. package/lib/skills/update-docs/SKILL.md +2 -2
  64. package/lib/skills/wiki-ingest/SKILL.md +1 -1
  65. package/lib/skills/wiki-lint/SKILL.md +1 -1
  66. package/lib/skills/wiki-query/SKILL.md +1 -1
  67. package/package.json +1 -1
  68. package/raw/guides/type-checking-templates/README.md +7 -7
  69. package/raw/guides/type-checking-templates/eslint/eslint.config.ts +1 -1
  70. package/raw/research/mcp-add-scope-writes/index.md +46 -0
  71. package/raw/research/mcp-add-scope-writes/sources.md +38 -0
  72. package/raw/research/mcp-scope-conflict-handling/index.md +61 -0
  73. package/raw/research/mcp-scope-conflict-handling/sources.md +32 -0
  74. package/.github/workflows/build.yml +0 -88
  75. package/raw/guides/mcp-tools.md +0 -335
  76. package/raw/guides/task-spec.md +0 -79
@@ -6,8 +6,19 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
6
6
  TEMPLATE_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
7
7
  TEMPLATES="$SCRIPT_DIR/templates/wiki"
8
8
 
9
+ INTERACTIVE=false
10
+ POSITIONAL=()
11
+ for arg in "$@"; do
12
+ case "$arg" in
13
+ --interactive) INTERACTIVE=true ;;
14
+ *) POSITIONAL+=("$arg") ;;
15
+ esac
16
+ done
17
+ # bash 3.2 + set -u: expanding an empty array is an unbound-variable error
18
+ set -- ${POSITIONAL[@]+"${POSITIONAL[@]}"}
19
+
9
20
  if [ $# -ne 1 ]; then
10
- echo "Usage: $0 <path-to-project>"
21
+ echo "Usage: $0 [--interactive] <path-to-project>"
11
22
  exit 1
12
23
  fi
13
24
 
@@ -32,7 +43,7 @@ mkdir -p \
32
43
  "$PROJECT_DIR/wiki/work/uat" \
33
44
  "$PROJECT_DIR/wiki/work/uat/screenshots" \
34
45
  "$PROJECT_DIR/wiki/work/bugs" \
35
- "$PROJECT_DIR/.docs/guides"
46
+ "$PROJECT_DIR/wiki/guides"
36
47
 
37
48
  # 2. COPY-ONCE: index.md, log.md, hot.md, .gitkeep files — project-owned after creation, never overwrite
38
49
  # Exclude conventions.md and lifecycle.md (those are always-refresh, handled in step 3).
@@ -49,18 +60,105 @@ for fam in requirements decisions roadmaps tasks uat bugs; do
49
60
  rsync -av "$TEMPLATES/work/$fam/lifecycle.md" "$PROJECT_DIR/wiki/work/$fam/lifecycle.md"
50
61
  done
51
62
 
52
- # 4. GUIDES: always refresh from raw/guides/ into target .docs/guides/
53
- rsync -av "$TEMPLATE_DIR/raw/guides/" "$PROJECT_DIR/.docs/guides/"
63
+ # 4. GUIDES: tiered delivery into target wiki/guides/ (template-owned
64
+ # infrastructure inside the wiki, same class as conventions.md/lifecycle.md).
65
+ # REQUIRED — always refreshed (template-owned).
66
+ # OPTIONAL — exists in target (new location OR legacy .docs/guides/) =>
67
+ # refresh into wiki/guides/ (user opted in previously);
68
+ # missing => prompt in interactive mode (default no), skip silently
69
+ # otherwise. Opt out by deleting the file/dir (costs one default-no
70
+ # prompt per interactive update).
71
+ # mcp-tools.md is assembled per-project by build-mcp-guide.sh, and
72
+ # deployment-strategy.md is delivered only by setup-deployment.sh
73
+ # (`bootstrap deploy`) — neither is synced here.
74
+ GUIDES_SRC="$TEMPLATE_DIR/raw/guides"
75
+ GUIDES_DST="$PROJECT_DIR/wiki/guides"
76
+ LEGACY_GUIDES="$PROJECT_DIR/.docs/guides"
77
+
78
+ # Tier lists — plain space-separated words (bash 3.2: no associative arrays).
79
+ # Entries may be files or directories; names must not contain spaces.
80
+ REQUIRED_GUIDES="command-anti-patterns.md"
81
+ OPTIONAL_GUIDES="evals-framework.md type-checking-templates"
82
+
83
+ deliver_guide() {
84
+ # $1 = guide name (file or dir under GUIDES_SRC)
85
+ if [ -d "$GUIDES_SRC/$1" ]; then
86
+ rsync -av "$GUIDES_SRC/$1/" "$GUIDES_DST/$1/"
87
+ else
88
+ rsync -av "$GUIDES_SRC/$1" "$GUIDES_DST/"
89
+ fi
90
+ }
91
+
92
+ for guide in $REQUIRED_GUIDES; do
93
+ deliver_guide "$guide"
94
+ done
95
+
96
+ for guide in $OPTIONAL_GUIDES; do
97
+ if [ -e "$GUIDES_DST/$guide" ] || [ -e "$LEGACY_GUIDES/$guide" ]; then
98
+ deliver_guide "$guide"
99
+ echo " $guide: refreshed (already present — previously opted in)."
100
+ elif [ "$INTERACTIVE" = true ] && prompt_yn " Install optional guide '$guide'? [y/N]: "; then
101
+ deliver_guide "$guide"
102
+ else
103
+ echo " $guide: skipped. Opt in any time: re-run 'npx @codewizard-dt/bootstrap update' and answer yes."
104
+ fi
105
+ done
106
+
107
+ # 4b. LEGACY MIGRATION: guides used to live in .docs/guides/. Every
108
+ # template-owned guide found there is removed (fresh copies now land in
109
+ # wiki/guides/ above); deployment-strategy.md is MOVED to wiki/guides/
110
+ # when `bootstrap deploy` has run (its build.yml marker exists) and
111
+ # deleted otherwise. User-authored files in .docs/guides/ are untouched.
112
+ # Also removes deprecated task-spec.md from either location (superseded by
113
+ # wiki/work/tasks/lifecycle.md, which it actively contradicts).
114
+ if [ -d "$LEGACY_GUIDES" ]; then
115
+ for legacy in command-anti-patterns.md evals-framework.md type-checking-templates mcp-tools.md task-spec.md; do
116
+ if [ -e "$LEGACY_GUIDES/$legacy" ]; then
117
+ rm -rf "${LEGACY_GUIDES:?}/$legacy"
118
+ echo " Migrated: removed .docs/guides/$legacy (guides now live in wiki/guides/)."
119
+ fi
120
+ done
121
+ if [ -f "$LEGACY_GUIDES/deployment-strategy.md" ]; then
122
+ if [ -f "$PROJECT_DIR/.github/workflows/build.yml" ]; then
123
+ mv "$LEGACY_GUIDES/deployment-strategy.md" "$GUIDES_DST/deployment-strategy.md"
124
+ echo " Migrated: moved deployment-strategy.md to wiki/guides/ (deploy artifacts present)."
125
+ else
126
+ rm -f "$LEGACY_GUIDES/deployment-strategy.md"
127
+ echo " Removed deployment-strategy.md (deploy-only guide; delivered by 'npx @codewizard-dt/bootstrap deploy')."
128
+ fi
129
+ fi
130
+ # Drop the legacy dirs when empty; scratch content (.docs/demo etc.) is kept.
131
+ rmdir "$LEGACY_GUIDES" 2>/dev/null && echo " Removed empty .docs/guides/." || true
132
+ rmdir "$PROJECT_DIR/.docs" 2>/dev/null || true
133
+ fi
134
+ if [ -f "$GUIDES_DST/task-spec.md" ]; then
135
+ rm -f "$GUIDES_DST/task-spec.md"
136
+ echo " Removed deprecated guide task-spec.md (superseded by wiki/work/tasks/lifecycle.md)."
137
+ fi
54
138
 
55
139
  # 5. Ensure raw/ has a .gitkeep so git tracks the empty dir
56
140
  touch -a "$PROJECT_DIR/raw/.gitkeep" 2>/dev/null || true
57
141
 
58
142
  # 6. Deliver the wiki schema section to the target's CLAUDE.md (copy-once).
59
- # Sentinel: a line starting with "## LLM Wiki". Never re-appended once present.
143
+ # Sentinel: a line starting with "## LLM Wiki". Never re-appended once
144
+ # present (in either CLAUDE.md or CLAUDE.local.md).
145
+ # When a CLAUDE.md already exists WITHOUT the schema, the user chooses
146
+ # interactively whether to modify it or write CLAUDE.local.md instead;
147
+ # non-interactive runs default to CLAUDE.local.md (never touch a file we
148
+ # didn't create without consent).
60
149
  CLAUDE_TEMPLATE="$SCRIPT_DIR/templates/CLAUDE-wiki.md"
61
150
  TARGET_CLAUDE="$PROJECT_DIR/CLAUDE.md"
151
+ TARGET_LOCAL="$PROJECT_DIR/CLAUDE.local.md"
152
+ # SCHEMA_FILE: where the wiki schema lives after this section — used by the
153
+ # .env-safety step below so both sections land in the same file.
154
+ SCHEMA_FILE="$TARGET_CLAUDE"
62
155
  if [ -f "$CLAUDE_TEMPLATE" ]; then
63
- if [ ! -f "$TARGET_CLAUDE" ]; then
156
+ if [ -f "$TARGET_CLAUDE" ] && grep -q '^## LLM Wiki' "$TARGET_CLAUDE"; then
157
+ echo "CLAUDE.md already has the LLM Wiki schema section, skipping."
158
+ elif [ -f "$TARGET_LOCAL" ] && grep -q '^## LLM Wiki' "$TARGET_LOCAL"; then
159
+ SCHEMA_FILE="$TARGET_LOCAL"
160
+ echo "CLAUDE.local.md already has the LLM Wiki schema section, skipping."
161
+ elif [ ! -f "$TARGET_CLAUDE" ]; then
64
162
  {
65
163
  echo "# CLAUDE.md"
66
164
  echo ""
@@ -69,35 +167,58 @@ if [ -f "$CLAUDE_TEMPLATE" ]; then
69
167
  cat "$CLAUDE_TEMPLATE"
70
168
  } > "$TARGET_CLAUDE"
71
169
  echo "CLAUDE.md created with the LLM Wiki schema section."
72
- elif ! grep -q '^## LLM Wiki' "$TARGET_CLAUDE"; then
73
- {
74
- echo ""
75
- echo "---"
76
- echo ""
77
- cat "$CLAUDE_TEMPLATE"
78
- } >> "$TARGET_CLAUDE"
79
- echo "LLM Wiki schema section appended to CLAUDE.md."
80
170
  else
81
- echo "CLAUDE.md already has the LLM Wiki schema section, skipping."
171
+ if [ "$INTERACTIVE" = true ] && prompt_yn " Existing CLAUDE.md found. Append the LLM Wiki schema to it? [y/N] (no = write CLAUDE.local.md instead): "; then
172
+ {
173
+ echo ""
174
+ echo "---"
175
+ echo ""
176
+ cat "$CLAUDE_TEMPLATE"
177
+ } >> "$TARGET_CLAUDE"
178
+ echo "LLM Wiki schema section appended to CLAUDE.md."
179
+ else
180
+ SCHEMA_FILE="$TARGET_LOCAL"
181
+ if [ ! -f "$TARGET_LOCAL" ]; then
182
+ {
183
+ echo "# CLAUDE.local.md"
184
+ echo ""
185
+ echo "Machine-local guidance for Claude Code (claude.ai/code) in this repository — companion to CLAUDE.md."
186
+ echo ""
187
+ cat "$CLAUDE_TEMPLATE"
188
+ } > "$TARGET_LOCAL"
189
+ else
190
+ {
191
+ echo ""
192
+ echo "---"
193
+ echo ""
194
+ cat "$CLAUDE_TEMPLATE"
195
+ } >> "$TARGET_LOCAL"
196
+ fi
197
+ echo "LLM Wiki schema section written to CLAUDE.local.md (CLAUDE.md left untouched)."
198
+ fi
82
199
  fi
83
200
  fi
84
201
 
85
- # 7. Ensure the .env safety policy sits at the TOP of the target's CLAUDE.md (copy-once).
86
- # Sentinel: the distinctive policy line. Prepended only when absent — never duplicated.
202
+ # 7. Ensure the .env safety policy sits at the TOP of the same file that holds
203
+ # the wiki schema (copy-once) — CLAUDE.md, or CLAUDE.local.md when the user
204
+ # declined to modify an existing CLAUDE.md above.
205
+ # Sentinel: the distinctive policy line, checked in BOTH files so the policy
206
+ # is never duplicated across them.
87
207
  ENV_TEMPLATE="$SCRIPT_DIR/templates/CLAUDE-env-safety.md"
88
208
  ENV_SENTINEL='never allowed to read or write to any'
89
- if [ -f "$ENV_TEMPLATE" ] && [ -f "$TARGET_CLAUDE" ]; then
90
- if ! grep -qF "$ENV_SENTINEL" "$TARGET_CLAUDE"; then
209
+ if [ -f "$ENV_TEMPLATE" ] && [ -f "$SCHEMA_FILE" ]; then
210
+ if { [ -f "$TARGET_CLAUDE" ] && grep -qF "$ENV_SENTINEL" "$TARGET_CLAUDE"; } \
211
+ || { [ -f "$TARGET_LOCAL" ] && grep -qF "$ENV_SENTINEL" "$TARGET_LOCAL"; }; then
212
+ echo "$(basename "$SCHEMA_FILE") already has the .env safety policy, skipping."
213
+ else
91
214
  TMP_CLAUDE="$(mktemp)"
92
215
  {
93
216
  cat "$ENV_TEMPLATE"
94
217
  echo ""
95
- cat "$TARGET_CLAUDE"
218
+ cat "$SCHEMA_FILE"
96
219
  } > "$TMP_CLAUDE"
97
- mv "$TMP_CLAUDE" "$TARGET_CLAUDE"
98
- echo ".env safety policy prepended to top of CLAUDE.md."
99
- else
100
- echo "CLAUDE.md already has the .env safety policy, skipping."
220
+ mv "$TMP_CLAUDE" "$SCHEMA_FILE"
221
+ echo ".env safety policy prepended to top of $(basename "$SCHEMA_FILE")."
101
222
  fi
102
223
  fi
103
224
 
@@ -4,7 +4,8 @@ This project maintains a three-layer LLM Wiki. This section is the **schema**
4
4
 
5
5
  ```
6
6
  raw/ Immutable ground-truth sources. Read them; NEVER modify, move, or delete them.
7
- wiki/ LLM-maintained knowledge base. You own this layer entirely.
7
+ wiki/ LLM-maintained knowledge base. You own this layer — except wiki/guides/ and the
8
+ other template-owned files (conventions.md, work/*/lifecycle.md, dashboard.html).
8
9
  CLAUDE.md This schema section.
9
10
  ```
10
11
 
@@ -25,7 +26,9 @@ CLAUDE.md This schema section.
25
26
  - `wiki/work/uat/` — UAT-NNN (own family, one per task)
26
27
  - `wiki/work/bugs/` — BUG-NNNN
27
28
 
28
- **Navigation:** `wiki/index.md` is the home Map of Content — read it first on every wiki query. Knowledge pages are listed there individually; work items live only in their family index. `wiki/log.md` is the append-only operation log. `wiki/conventions.md` holds the page rules (atomic pages, stable IDs/aliases, typed links, frontmatter namespace).
29
+ **`wiki/guides/`** — template-owned reference guides delivered by the bootstrap tooling (MCP tool rules in `mcp-tools.md`, shell anti-patterns, opted-in frameworks like evals or type-checking templates). Read them and obey them; **never edit them** — they are refreshed by `npx @codewizard-dt/bootstrap update` and any local edit will be overwritten. They are infrastructure, not wiki content: no frontmatter, no index entries, exempt from the atomic-page rule.
30
+
31
+ **Navigation:** `wiki/index.md` is the home Map of Content — read it first on every wiki query. Knowledge pages are listed there individually; work items live only in their family index. `wiki/log.md` is the append-only operation log. `wiki/conventions.md` holds the page rules (atomic pages, stable IDs/aliases, typed links, frontmatter namespace). Tool-usage rules live in `wiki/guides/mcp-tools.md`.
29
32
 
30
33
  ### Auto Memory vs. this wiki
31
34
 
@@ -58,3 +61,4 @@ Keep the two from duplicating or contradicting each other: project-specific stat
58
61
  5. Answer from the wiki, not general knowledge — if the wiki lacks coverage, say so and suggest `/wiki-ingest` for relevant sources
59
62
  6. Atomic pages — one concept, entity, or artifact per file; split a page rather than let it cover two things
60
63
  7. Typed links — when a link has a meaning, annotate it inline as `rel::[[target]]` (e.g. `implements::[[REQ-012]]`, `supersedes::[[DEC-0003#D2]]`); keep the two domains separate — never file a stateful artifact under `knowledge/` or a timeless synthesis under `work/`
64
+ 8. Template-owned files are read-only — never edit `wiki/guides/*`, `wiki/conventions.md`, `wiki/work/*/lifecycle.md`, or `wiki/dashboard.html`; they are refreshed from the bootstrap templates and local edits will be lost
@@ -16,7 +16,7 @@
16
16
  - Reading file contents for inspection → use `mcp__serena__get_symbols_overview` (code) or `Read` (markdown/config), **never** `cat` / `head` / `tail`
17
17
  - Editing via shell → **never** `sed` / `awk` / `echo >>`
18
18
 
19
- The rule of thumb: **the shell is for running programs, not for inspecting or modifying files.** Even on a markdown file, do not `cat README.md` — use `Read`. Do not `grep -r foo .docs/` — use `mcp__serena__search_for_pattern` or the `Grep` tool.
19
+ The rule of thumb: **the shell is for running programs, not for inspecting or modifying files.** Even on a markdown file, do not `cat README.md` — use `Read`. Do not `grep -r foo wiki/` — use `mcp__serena__search_for_pattern` or the `Grep` tool.
20
20
 
21
21
  ### Common anti-patterns and their fixes
22
22
 
@@ -26,7 +26,7 @@ These are real mistakes AI agents make on this codebase. Do not repeat them.
26
26
 
27
27
  ```bash
28
28
  # WRONG — never do this
29
- sed -i '' 's/- \[ \] Launch Puppeteer/- [x] Launch Puppeteer/; s/- \[ \] Navigate and screenshot/- [x] Navigate and screenshot/' .docs/tasks/051-ux-conversion-audit.md
29
+ sed -i '' 's/- \[ \] Launch Puppeteer/- [x] Launch Puppeteer/; s/- \[ \] Navigate and screenshot/- [x] Navigate and screenshot/' wiki/work/tasks/TASK-051-ux-conversion-audit.md
30
30
  ```
31
31
 
32
32
  This pattern shows up most often when marking multiple steps complete in a task file. It triggers an approval prompt every time, is fragile against whitespace or escaping, and silently corrupts files when a regex backfires.
@@ -34,10 +34,10 @@ This pattern shows up most often when marking multiple steps complete in a task
34
34
  ✅ **Correct**: call the `Edit` tool once per checkbox (or use `replace_all: true` if every `- [ ]` in the file should become `- [x]`):
35
35
 
36
36
  ```
37
- Edit(file_path=".docs/tasks/051-ux-conversion-audit.md",
37
+ Edit(file_path="wiki/work/tasks/TASK-051-ux-conversion-audit.md",
38
38
  old_string="- [ ] Launch Puppeteer",
39
39
  new_string="- [x] Launch Puppeteer")
40
- Edit(file_path=".docs/tasks/051-ux-conversion-audit.md",
40
+ Edit(file_path="wiki/work/tasks/TASK-051-ux-conversion-audit.md",
41
41
  old_string="- [ ] Navigate and screenshot each marketing",
42
42
  new_string="- [x] Navigate and screenshot each marketing")
43
43
  # ...one Edit call per checkbox
@@ -49,7 +49,7 @@ Yes, even if there are ten checkboxes. Ten `Edit` calls is correct. One `sed` is
49
49
 
50
50
  ```bash
51
51
  # WRONG
52
- cat .docs/tasks/051-ux-conversion-audit.md
52
+ cat wiki/work/tasks/TASK-051-ux-conversion-audit.md
53
53
  ```
54
54
 
55
55
  ✅ **Correct**: `Read` tool. Always.
@@ -58,10 +58,10 @@ cat .docs/tasks/051-ux-conversion-audit.md
58
58
 
59
59
  ```bash
60
60
  # WRONG
61
- ls .docs/uat/screenshots/
61
+ ls wiki/work/uat/screenshots/
62
62
  ```
63
63
 
64
- ✅ **Correct**: `mcp__serena__list_dir(relative_path=".docs/uat/screenshots/")`
64
+ ✅ **Correct**: `mcp__serena__list_dir(relative_path="wiki/work/uat/screenshots/")`
65
65
 
66
66
  #### ❌ Anti-pattern: `grep -r` to find a string across files
67
67
 
@@ -75,6 +75,8 @@ Keep the two organizing laws separate — do not file a stateful artifact under
75
75
 
76
76
  Cross-domain links are encouraged and carry meaning — e.g. a decision `derived_from::` a source, a task `implements::` a requirement.
77
77
 
78
+ **Template-owned infrastructure (exempt from both laws).** A small set of files inside `wiki/` is owned by the bootstrap templates, not by this wiki: `conventions.md` (this file), every `work/<family>/lifecycle.md`, `dashboard.html`, and everything under `guides/` (delivered reference guides — MCP tool rules, anti-patterns, opted-in frameworks). They carry no frontmatter, are never listed as knowledge pages, are exempt from the atomic-page rule, and must **never be edited in place** — they are refreshed by `npx @codewizard-dt/bootstrap update`, which overwrites local changes.
79
+
78
80
  ---
79
81
 
80
82
  ## 5. Archiving terminal items
@@ -44,3 +44,9 @@ Each family's `index.md` lists its **active items only** (completed/terminal ite
44
44
  - **Tasks** — TASK-NNN. [Active index](work/tasks/index.md) · [lifecycle](work/tasks/lifecycle.md)
45
45
  - **UAT** — UAT-NNN, one per task. [Active index](work/uat/index.md) · [lifecycle](work/uat/lifecycle.md)
46
46
  - **Bugs** — BUG-NNNN. [Active index](work/bugs/index.md) · [lifecycle](work/bugs/lifecycle.md)
47
+
48
+ ---
49
+
50
+ ## Guides
51
+
52
+ Template-owned reference guides delivered by the bootstrap tooling — read, never edit (refreshed by `bootstrap update`). See [guides/](guides/): tool rules in `mcp-tools.md`, shell hygiene in `command-anti-patterns.md`, plus any opted-in guides.
@@ -7,7 +7,7 @@ argument-hint: <BUG-NNNN, path, or number-slug>
7
7
  disable-model-invocation: false
8
8
  user-invocable: true
9
9
  ---
10
- **Prereqs:** obey `.docs/guides/mcp-tools.md` + `wiki/work/bugs/lifecycle.md`; run /primer if not done this session.
10
+ **Prereqs:** obey `wiki/guides/mcp-tools.md` + `wiki/work/bugs/lifecycle.md`; run /primer if not done this session.
11
11
 
12
12
  # Close Bug
13
13
 
@@ -7,7 +7,7 @@ argument-hint: <short bug description>
7
7
  disable-model-invocation: false
8
8
  user-invocable: true
9
9
  ---
10
- **Prereqs:** obey `.docs/guides/mcp-tools.md` + `wiki/work/bugs/lifecycle.md`; run /primer if not done this session.
10
+ **Prereqs:** obey `wiki/guides/mcp-tools.md` + `wiki/work/bugs/lifecycle.md`; run /primer if not done this session.
11
11
 
12
12
  # File Bug
13
13
 
@@ -99,7 +99,7 @@ Append a bullet line to `wiki/work/bugs/index.md` (active items only — a flat
99
99
 
100
100
  `<status>` is the status you set in Step 6; `<priority>` is `—` until triage. If the index still shows the placeholder line (`_(none yet)_`), replace it with the new line.
101
101
 
102
- Use **`Edit`** — one targeted call. Never `sed`, `awk`, `perl -i`, or `echo >>`. See `.docs/guides/mcp-tools.md`.
102
+ Use **`Edit`** — one targeted call. Never `sed`, `awk`, `perl -i`, or `echo >>`. See `wiki/guides/mcp-tools.md`.
103
103
 
104
104
  ### Step 8: Report Completion
105
105
 
@@ -7,7 +7,7 @@ argument-hint: <BUG-NNNN, path, or number-slug>
7
7
  disable-model-invocation: false
8
8
  user-invocable: true
9
9
  ---
10
- **Prereqs:** obey `.docs/guides/mcp-tools.md`; run /primer if not done this session.
10
+ **Prereqs:** obey `wiki/guides/mcp-tools.md`; run /primer if not done this session.
11
11
 
12
12
  # Triage Bug
13
13
 
@@ -7,7 +7,7 @@ argument-hint: "[optional symptom or error message]"
7
7
  disable-model-invocation: false
8
8
  user-invocable: true
9
9
  ---
10
- **Prereqs:** obey `.docs/guides/mcp-tools.md`; run /primer if not done this session.
10
+ **Prereqs:** obey `wiki/guides/mcp-tools.md`; run /primer if not done this session.
11
11
 
12
12
  # Debug
13
13
 
@@ -42,7 +42,7 @@ Pick the smallest set of sources that could contain the failure signal. Do not d
42
42
  | Background server crashed / 500s | `TaskOutput` on the dev server task | `TaskOutput` |
43
43
  | Test failure / assertion error | `TaskOutput` on the test task, or rerun with `--reporter=verbose` | `TaskOutput`, `Bash` |
44
44
  | Build / compile error | Build task output, `tsc` / `next build` cache, `.next/trace` | `TaskOutput`, `Read` |
45
- | Browser-side failure (UI bug, console error) | Playwright snapshot + screenshot | `mcp__playwright__browser_snapshot`, `mcp__playwright__browser_take_screenshot` |
45
+ | Browser-side failure (UI bug, console error) | Playwright snapshot + screenshot | `mcp__playwright-shared__browser_snapshot`, `mcp__playwright-shared__browser_take_screenshot` (or `mcp__playwright__*` when the project registers its own server) |
46
46
  | Type / lint regression | IDE diagnostics | `mcp__ide__getDiagnostics` |
47
47
  | CI failure on a PR/branch | GitHub Actions logs | `gh run list`, `gh run view --log-failed` |
48
48
  | Deployed app failure (DigitalOcean) | App platform logs | `mcp__digitalocean__apps-get-logs` |
@@ -8,7 +8,7 @@ argument-hint: <decision topic, group title, or "group: <title>" for an explicit
8
8
  disable-model-invocation: false
9
9
  user-invocable: true
10
10
  ---
11
- **Prereqs:** obey `.docs/guides/mcp-tools.md`; run /primer if not done this session.
11
+ **Prereqs:** obey `wiki/guides/mcp-tools.md`; run /primer if not done this session.
12
12
  **Run `/research <topic>` on the decision topic BEFORE drafting any decision block. Do not skip.**
13
13
  **Read `wiki/work/decisions/lifecycle.md` first** — it defines the Decision Group model, supersession rule, relationship graph, and index format this command must respect.
14
14
 
@@ -8,7 +8,7 @@ argument-hint: <path/to/decision.md#DM, NNNN-slug#DM, or NNNN#DM>
8
8
  disable-model-invocation: false
9
9
  user-invocable: true
10
10
  ---
11
- **Prereqs:** obey `.docs/guides/mcp-tools.md`; run /primer if not done this session.
11
+ **Prereqs:** obey `wiki/guides/mcp-tools.md`; run /primer if not done this session.
12
12
  **Read `wiki/work/decisions/lifecycle.md` first** — it defines the Decision Group model, the per-decision supersession rule, the two-block cross-reference rule, and the relationship graph that finalization must keep in sync.
13
13
 
14
14
  # Finalize Decision
@@ -7,7 +7,7 @@ argument-hint: "[optional: path to a specific decision file or NNNN prefix to sc
7
7
  disable-model-invocation: false
8
8
  user-invocable: true
9
9
  ---
10
- **Prereqs:** obey `.docs/guides/mcp-tools.md`.
10
+ **Prereqs:** obey `wiki/guides/mcp-tools.md`.
11
11
 
12
12
  # Decision Next Task
13
13
 
@@ -7,7 +7,7 @@ argument-hint: <path/to/decision.md, NNNN-slug, or NNNN>
7
7
  disable-model-invocation: false
8
8
  user-invocable: true
9
9
  ---
10
- **Prereqs:** obey `.docs/guides/mcp-tools.md`; run /primer if not done this session.
10
+ **Prereqs:** obey `wiki/guides/mcp-tools.md`; run /primer if not done this session.
11
11
 
12
12
 
13
13
  # Walkthrough Decision
@@ -7,7 +7,7 @@ argument-hint: "[path to project directory (defaults to cwd)] [custom instructio
7
7
  disable-model-invocation: false
8
8
  user-invocable: true
9
9
  ---
10
- **Prereqs:** obey `.docs/guides/mcp-tools.md`; run /primer if not done this session.
10
+ **Prereqs:** obey `wiki/guides/mcp-tools.md`; run /primer if not done this session.
11
11
 
12
12
  # Demo
13
13
 
@@ -8,7 +8,7 @@ argument-hint: "[stage: golden|scenarios|replay|rubric] [description of the eval
8
8
  disable-model-invocation: false
9
9
  user-invocable: true
10
10
  ---
11
- **Prereqs:** obey `.docs/guides/mcp-tools.md`.
11
+ **Prereqs:** obey `wiki/guides/mcp-tools.md`.
12
12
 
13
13
  $ARGUMENTS
14
14
 
@@ -36,7 +36,7 @@ Parse `$ARGUMENTS` immediately. The argument string can take several forms:
36
36
  **Direct mode** (any non-empty argument that is not a bare stage keyword):
37
37
 
38
38
  1. Acknowledge the request: "Creating a golden set eval for: `<extracted description>`"
39
- 2. Read `.docs/guides/evals-framework.md` (always required)
39
+ 2. Read `wiki/guides/evals-framework.md` (always required — if missing, stop and tell the user to re-run `npx @codewizard-dt/bootstrap update` and opt in to `evals-framework.md`, as in Step 1)
40
40
  3. Survey `evals/golden/` to find the next ID and check bootstrap vs gap-fill state
41
41
  4. Go directly to **Step 4-Direct** — skip Steps 1–3
42
42
 
@@ -48,7 +48,11 @@ Parse `$ARGUMENTS` immediately. The argument string can take several forms:
48
48
 
49
49
  ## Step 1: Read the framework
50
50
 
51
- Read `.docs/guides/evals-framework.md` in full. This is authoritative for stage definitions, schemas, check types, and anti-patterns. Do not proceed until you have read it.
51
+ Read `wiki/guides/evals-framework.md` in full. This is authoritative for stage definitions, schemas, check types, and anti-patterns. Do not proceed until you have read it.
52
+
53
+ If the file does not exist, STOP — do not proceed from memory. Tell the user:
54
+
55
+ > This project doesn't have the evals framework guide installed. Run `npx @codewizard-dt/bootstrap update` and answer **yes** when prompted to install the optional guide `evals-framework.md`, then re-run this skill.
52
56
 
53
57
  ---
54
58
 
@@ -8,7 +8,7 @@ argument-hint: [optional: stage — golden | scenarios | replay | rubric | all]
8
8
  disable-model-invocation: false
9
9
  user-invocable: true
10
10
  ---
11
- **Prereqs:** obey `.docs/guides/mcp-tools.md`.
11
+ **Prereqs:** obey `wiki/guides/mcp-tools.md`.
12
12
 
13
13
  $ARGUMENTS
14
14
 
@@ -24,7 +24,11 @@ Read-only audit of the project's eval suite. Produces a prioritised gap report a
24
24
 
25
25
  ## Step 1: Read the framework
26
26
 
27
- Read `.docs/guides/evals-framework.md`. This defines the expected shape of each stage and is required context for meaningful gap analysis.
27
+ Read `wiki/guides/evals-framework.md`. This defines the expected shape of each stage and is required context for meaningful gap analysis.
28
+
29
+ If the file does not exist, STOP — do not proceed from memory. Tell the user:
30
+
31
+ > This project doesn't have the evals framework guide installed. Run `npx @codewizard-dt/bootstrap update` and answer **yes** when prompted to install the optional guide `evals-framework.md`, then re-run this skill.
28
32
 
29
33
  ---
30
34
 
@@ -8,7 +8,7 @@ argument-hint: [optional: stage — golden | scenarios | replay | all]
8
8
  disable-model-invocation: false
9
9
  user-invocable: true
10
10
  ---
11
- **Prereqs:** obey `.docs/guides/mcp-tools.md`.
11
+ **Prereqs:** obey `wiki/guides/mcp-tools.md`.
12
12
 
13
13
  $ARGUMENTS
14
14
 
@@ -8,7 +8,7 @@ argument-hint: <feature name or description>
8
8
  disable-model-invocation: false
9
9
  user-invocable: true
10
10
  ---
11
- **Prereqs:** obey `.docs/guides/mcp-tools.md`; run /primer if not done this session.
11
+ **Prereqs:** obey `wiki/guides/mcp-tools.md`; run /primer if not done this session.
12
12
 
13
13
  # Extract Feature
14
14
 
@@ -8,7 +8,7 @@ argument-hint: <expected functionality — inline description or path to a requi
8
8
  disable-model-invocation: false
9
9
  user-invocable: true
10
10
  ---
11
- **Prereqs:** obey `.docs/guides/mcp-tools.md`; run /primer if not done this session.
11
+ **Prereqs:** obey `wiki/guides/mcp-tools.md`; run /primer if not done this session.
12
12
 
13
13
  # Gap Assess
14
14
 
@@ -6,7 +6,7 @@ model: claude-haiku-4-5-20251001
6
6
  disable-model-invocation: true
7
7
  user-invocable: true
8
8
  ---
9
- **Prereqs:** obey `.docs/guides/mcp-tools.md`.
9
+ **Prereqs:** obey `wiki/guides/mcp-tools.md`.
10
10
 
11
11
  # git-commit
12
12
 
@@ -6,7 +6,7 @@ model: claude-sonnet-5
6
6
  disable-model-invocation: false
7
7
  user-invocable: true
8
8
  ---
9
- **Prereqs:** obey `.docs/guides/mcp-tools.md`.
9
+ **Prereqs:** obey `wiki/guides/mcp-tools.md`.
10
10
 
11
11
  # Lint Fix Cycles
12
12
 
@@ -7,7 +7,7 @@ argument-hint: <path to source file> [optional output path]
7
7
  disable-model-invocation: false
8
8
  user-invocable: true
9
9
  ---
10
- **Prereqs:** obey `.docs/guides/mcp-tools.md`; run /primer if not done this session.
10
+ **Prereqs:** obey `wiki/guides/mcp-tools.md`; run /primer if not done this session.
11
11
 
12
12
  # Marp Slideshow
13
13
 
@@ -7,7 +7,7 @@ argument-hint: <path to source file> [optional output path]
7
7
  disable-model-invocation: false
8
8
  user-invocable: true
9
9
  ---
10
- **Prereqs:** obey `.docs/guides/mcp-tools.md`; run /primer if not done this session.
10
+ **Prereqs:** obey `wiki/guides/mcp-tools.md`; run /primer if not done this session.
11
11
 
12
12
  # Mermaid Flowchart
13
13
 
@@ -8,7 +8,7 @@ argument-hint: <task description>
8
8
  disable-model-invocation: false
9
9
  user-invocable: true
10
10
  ---
11
- **Prereqs:** obey `.docs/guides/mcp-tools.md`; run /primer if not done this session.
11
+ **Prereqs:** obey `wiki/guides/mcp-tools.md`; run /primer if not done this session.
12
12
 
13
13
  $ARGUMENTS
14
14
 
@@ -8,7 +8,7 @@ argument-hint: <absolute-path-to-source-project> <functionality description>
8
8
  disable-model-invocation: false
9
9
  user-invocable: true
10
10
  ---
11
- **Prereqs:** obey `.docs/guides/mcp-tools.md`; run /primer if not done this session.
11
+ **Prereqs:** obey `wiki/guides/mcp-tools.md`; run /primer if not done this session.
12
12
 
13
13
  # Port Feature
14
14
 
@@ -46,7 +46,7 @@ Inspect the path argument:
46
46
  Every agent spawned in power-mode MUST include `mode: "bypassPermissions"` and the following footer appended to its prompt:
47
47
 
48
48
  ```
49
- IMPORTANT: Follow .docs/guides/mcp-tools.md for all file and code operations. Use Serena (mcp__serena__*) for ALL file/directory exploration and ALL code editing. Never use ls, cat, find, grep, sed, awk, or any shell command to inspect or modify files. Use Read/Edit/Write only for markdown and config files.
49
+ IMPORTANT: Follow wiki/guides/mcp-tools.md for all file and code operations. Use Serena (mcp__serena__*) for ALL file/directory exploration and ALL code editing. Never use ls, cat, find, grep, sed, awk, or any shell command to inspect or modify files. Use Read/Edit/Write only for markdown and config files.
50
50
 
51
51
  IMPORTANT: If at any point you are not 100% sure how to fix an issue or which implementation strategy to use, invoke /research first and act on its recommendation before proceeding.
52
52
  ```
@@ -6,7 +6,7 @@ model: claude-haiku-4-5-20251001
6
6
  disable-model-invocation: false
7
7
  user-invocable: true
8
8
  ---
9
- **Prereqs:** obey `.docs/guides/mcp-tools.md`.
9
+ **Prereqs:** obey `wiki/guides/mcp-tools.md`.
10
10
 
11
11
  # MANDATORY REQUIREMENTS
12
12
 
@@ -69,7 +69,7 @@ Keep memories current and useful for future conversations:
69
69
  3. **Rename disorganized memories**: Use `mcp__serena__rename_memory` to move memories into proper topic hierarchies
70
70
  4. **Do NOT write memories for**: information already in code comments or docs, temporary state, easily re-derivable facts
71
71
 
72
- See `.docs/guides/mcp-tools.md` for the complete Serena memory reference.
72
+ See `wiki/guides/mcp-tools.md` for the complete Serena memory reference.
73
73
 
74
74
  ---
75
75
 
@@ -7,7 +7,7 @@ argument-hint: "[path to project directory (defaults to cwd)] [custom instructio
7
7
  disable-model-invocation: false
8
8
  user-invocable: true
9
9
  ---
10
- **Prereqs:** obey `.docs/guides/mcp-tools.md`.
10
+ **Prereqs:** obey `wiki/guides/mcp-tools.md`.
11
11
 
12
12
  Generate (or update) a **project README** structured for optimal AI parsing and portfolio presentation. The strict section format is machine-readable by AI tools that extract project metadata (name, description, architecture, technologies, use cases, skills).
13
13
 
@@ -8,7 +8,7 @@ argument-hint: <feature description, problem statement, or product initiative ti
8
8
  disable-model-invocation: false
9
9
  user-invocable: true
10
10
  ---
11
- **Prereqs:** obey `.docs/guides/mcp-tools.md`; run /primer if not done this session.
11
+ **Prereqs:** obey `wiki/guides/mcp-tools.md`; run /primer if not done this session.
12
12
  **Check `wiki/work/requirements/lifecycle.md`** for the REQ template, status lifecycle, required-non-empty fields, and anti-patterns this skill enforces; **`wiki/work/requirements/index.md`** for the index row format.
13
13
 
14
14
  # Create Requirement
@@ -8,7 +8,7 @@ argument-hint: <path/to/req.md, NNN-slug, or NNN>
8
8
  disable-model-invocation: false
9
9
  user-invocable: true
10
10
  ---
11
- **Prereqs:** obey `.docs/guides/mcp-tools.md`; run /primer if not done this session.
11
+ **Prereqs:** obey `wiki/guides/mcp-tools.md`; run /primer if not done this session.
12
12
 
13
13
 
14
14
  # Requirement to Decisions