@codewizard-dt/bootstrap 2.11.2 → 2.14.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 (77) 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 +8 -8
  7. package/lib/scripts/bootstrap-serena.sh +8 -6
  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 +35 -8
  11. package/lib/scripts/merge-gitignore.sh +102 -29
  12. package/lib/scripts/migrate-project.sh +9 -2
  13. package/lib/scripts/setup-deployment.sh +9 -0
  14. package/lib/scripts/sync-wiki-scaffold.sh +145 -24
  15. package/lib/scripts/templates/CLAUDE-wiki.md +6 -2
  16. package/lib/scripts/templates/guides/stubs/serena.md +7 -7
  17. package/lib/scripts/templates/wiki/conventions.md +2 -0
  18. package/lib/scripts/templates/wiki/index.md +6 -0
  19. package/lib/skills/bug-close/SKILL.md +1 -1
  20. package/lib/skills/bug-file/SKILL.md +2 -2
  21. package/lib/skills/bug-triage/SKILL.md +1 -1
  22. package/lib/skills/debug-logs/SKILL.md +2 -2
  23. package/lib/skills/decision-create/SKILL.md +1 -1
  24. package/lib/skills/decision-finalize/SKILL.md +1 -1
  25. package/lib/skills/decision-next/SKILL.md +1 -1
  26. package/lib/skills/decision-walkthrough/SKILL.md +1 -1
  27. package/lib/skills/demo/SKILL.md +1 -1
  28. package/lib/skills/eval-create/SKILL.md +7 -3
  29. package/lib/skills/eval-gap/SKILL.md +6 -2
  30. package/lib/skills/eval-run/SKILL.md +1 -1
  31. package/lib/skills/extract-feature/SKILL.md +1 -1
  32. package/lib/skills/gap-assess/SKILL.md +1 -1
  33. package/lib/skills/git-commit/SKILL.md +1 -1
  34. package/lib/skills/lint/SKILL.md +1 -1
  35. package/lib/skills/marp-slideshow/SKILL.md +1 -1
  36. package/lib/skills/mermaid-flowchart/SKILL.md +1 -1
  37. package/lib/skills/now/SKILL.md +1 -1
  38. package/lib/skills/port-feature/SKILL.md +1 -1
  39. package/lib/skills/power-mode/SKILL.md +1 -1
  40. package/lib/skills/primer/SKILL.md +2 -2
  41. package/lib/skills/project-readme/SKILL.md +1 -1
  42. package/lib/skills/req-create/SKILL.md +1 -1
  43. package/lib/skills/req-extract-decisions/SKILL.md +1 -1
  44. package/lib/skills/req-finalize/SKILL.md +1 -1
  45. package/lib/skills/req-retire/SKILL.md +2 -2
  46. package/lib/skills/req-update/SKILL.md +1 -1
  47. package/lib/skills/research/SKILL.md +1 -1
  48. package/lib/skills/roadmap-add/SKILL.md +2 -2
  49. package/lib/skills/roadmap-create/SKILL.md +3 -3
  50. package/lib/skills/roadmap-next/SKILL.md +1 -1
  51. package/lib/skills/serena-config/SKILL.md +1 -1
  52. package/lib/skills/simplify/SKILL.md +1 -1
  53. package/lib/skills/tackle/SKILL.md +3 -3
  54. package/lib/skills/task-add/SKILL.md +1 -1
  55. package/lib/skills/task-audit/SKILL.md +2 -2
  56. package/lib/skills/task-trash/SKILL.md +1 -1
  57. package/lib/skills/task-update/SKILL.md +2 -2
  58. package/lib/skills/uat-auto/SKILL.md +1 -1
  59. package/lib/skills/uat-auto-plus/SKILL.md +1 -1
  60. package/lib/skills/uat-generate/SKILL.md +1 -1
  61. package/lib/skills/uat-skip/SKILL.md +1 -1
  62. package/lib/skills/uat-walk/SKILL.md +1 -1
  63. package/lib/skills/uat-walk/UAT-CORE.md +1 -1
  64. package/lib/skills/update-docs/SKILL.md +2 -2
  65. package/lib/skills/wiki-ingest/SKILL.md +1 -1
  66. package/lib/skills/wiki-lint/SKILL.md +1 -1
  67. package/lib/skills/wiki-query/SKILL.md +1 -1
  68. package/package.json +1 -1
  69. package/raw/guides/type-checking-templates/README.md +7 -7
  70. package/raw/guides/type-checking-templates/eslint/eslint.config.ts +1 -1
  71. package/raw/research/mcp-add-scope-writes/index.md +46 -0
  72. package/raw/research/mcp-add-scope-writes/sources.md +38 -0
  73. package/raw/research/mcp-scope-conflict-handling/index.md +61 -0
  74. package/raw/research/mcp-scope-conflict-handling/sources.md +32 -0
  75. package/.github/workflows/build.yml +0 -88
  76. package/raw/guides/mcp-tools.md +0 -335
  77. package/raw/guides/task-spec.md +0 -79
@@ -6,8 +6,30 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
6
6
  # Packed copy of the repo .gitignore (dotfiles are never included in npm packages)
7
7
  TEMPLATE_GITIGNORE="$SCRIPT_DIR/templates/gitignore"
8
8
 
9
+ # merge-gitignore.sh [--interactive] <path-to-project>
10
+ #
11
+ # The template is split into titled sections (delimited by `# ---` banner
12
+ # comments). Per section:
13
+ # - already represented in the target (any of its entries present, exact
14
+ # line match) => merge the section's missing lines silently (sticky opt-in)
15
+ # - otherwise, --interactive => prompt "Add .gitignore section '<title>'?"
16
+ # (default no); non-interactive => skip silently
17
+ # A missing .gitignore is copied wholesale in non-interactive mode; in
18
+ # interactive mode the same per-section prompts build it from scratch.
19
+
20
+ INTERACTIVE=false
21
+ POSITIONAL=()
22
+ for arg in "$@"; do
23
+ case "$arg" in
24
+ --interactive) INTERACTIVE=true ;;
25
+ *) POSITIONAL+=("$arg") ;;
26
+ esac
27
+ done
28
+ # bash 3.2 + set -u: expanding an empty array is an unbound-variable error
29
+ set -- ${POSITIONAL[@]+"${POSITIONAL[@]}"}
30
+
9
31
  if [ $# -ne 1 ]; then
10
- echo "Usage: $0 <path-to-project>" >&2
32
+ echo "Usage: $0 [--interactive] <path-to-project>" >&2
11
33
  exit 1
12
34
  fi
13
35
 
@@ -15,48 +37,99 @@ PROJECT_DIR="$(resolve_project_dir "$1")" || exit 1
15
37
 
16
38
  TARGET="$PROJECT_DIR/.gitignore"
17
39
 
18
- # No target → copy wholesale
19
- if [ ! -f "$TARGET" ]; then
40
+ # No target + non-interactive (or no tty to prompt on) → copy wholesale, so
41
+ # headless setup keeps full coverage instead of creating an empty file.
42
+ if [ ! -f "$TARGET" ] && { [ "$INTERACTIVE" = false ] || [ ! -t 0 ]; }; then
20
43
  cp "$TEMPLATE_GITIGNORE" "$TARGET"
21
44
  echo ".gitignore: copied to $PROJECT_DIR"
22
45
  exit 0
23
46
  fi
24
47
 
25
- # Snapshot existing lines for exact-match lookups during the merge loop
26
- EXISTING=$(mktemp)
48
+ WORK_DIR=$(mktemp -d)
49
+ trap 'rm -rf "$WORK_DIR"' EXIT
50
+
51
+ # Split the template into per-section files. Banner delimiters come in pairs
52
+ # (open dash line, title comment, close dash line); every odd dash line starts
53
+ # a new section. Titles land in $WORK_DIR/title.N, bodies in $WORK_DIR/sec.N.
54
+ SECTION_COUNT=$(awk -v dir="$WORK_DIR" '
55
+ /^# -----/ {
56
+ dash++
57
+ if (dash % 2 == 1) n++
58
+ print >> (dir "/sec." n)
59
+ next
60
+ }
61
+ n > 0 {
62
+ print >> (dir "/sec." n)
63
+ if (dash % 2 == 1 && $0 ~ /^# / && !(n in ttl)) {
64
+ t = $0; sub(/^# +/, "", t); ttl[n] = t
65
+ print t > (dir "/title." n)
66
+ }
67
+ }
68
+ END { print n }
69
+ ' "$TEMPLATE_GITIGNORE")
70
+
71
+ [ -f "$TARGET" ] || : > "$TARGET"
72
+
73
+ # Snapshot existing lines for exact-match lookups during the merge loops
74
+ EXISTING="$WORK_DIR/existing"
27
75
  cp "$TARGET" "$EXISTING"
28
- trap 'rm -f "$EXISTING"' EXIT
29
76
 
30
- added=0
31
- pending="" # comment/blank lines buffered until we know the next content line is new
77
+ # section_represented <section-file>: any non-comment entry already in target?
78
+ section_represented() {
79
+ local line trimmed
80
+ while IFS= read -r line || [ -n "$line" ]; do
81
+ trimmed="${line#"${line%%[![:space:]]*}"}"
82
+ [ -z "$trimmed" ] && continue
83
+ case "$trimmed" in \#*) continue ;; esac
84
+ if grep -qFx -- "$line" "$EXISTING"; then return 0; fi
85
+ done < "$1"
86
+ return 1
87
+ }
32
88
 
33
- while IFS= read -r line || [ -n "$line" ]; do
34
- trimmed="${line#"${line%%[![:space:]]*}"}" # leading-whitespace stripped
89
+ added=0
35
90
 
36
- if [ -z "$trimmed" ] || [[ "$trimmed" == \#* ]]; then
37
- # Blank or comment line — hold in buffer; only flush if a new content line follows
38
- pending+="${line}"$'\n'
39
- else
40
- # Content line
41
- if grep -qFx -- "$line" "$EXISTING"; then
42
- # Already present — discard buffered headers (their section is already represented)
43
- pending=""
91
+ # merge_section <section-file>: append the section's missing lines, keeping
92
+ # comment/blank lines buffered so headers only land when new entries follow.
93
+ merge_section() {
94
+ local line trimmed pending=""
95
+ while IFS= read -r line || [ -n "$line" ]; do
96
+ trimmed="${line#"${line%%[![:space:]]*}"}"
97
+ if [ -z "$trimmed" ] || [[ "$trimmed" == \#* ]]; then
98
+ pending+="${line}"$'\n'
44
99
  else
45
- # New line — pre-flight the file on first append, then flush buffer + add line
46
- if [ "$added" -eq 0 ] && [ -s "$TARGET" ]; then
47
- # Ensure target ends with a newline before we start appending
48
- [[ $(tail -c1 "$TARGET") ]] && printf '\n' >> "$TARGET"
49
- fi
50
- if [ -n "$pending" ]; then
51
- printf '%s' "$pending" >> "$TARGET"
100
+ if grep -qFx -- "$line" "$EXISTING"; then
52
101
  pending=""
102
+ else
103
+ if [ "$added" -eq 0 ] && [ -s "$TARGET" ]; then
104
+ # Ensure target ends with a newline before we start appending
105
+ [[ $(tail -c1 "$TARGET") ]] && printf '\n' >> "$TARGET"
106
+ fi
107
+ if [ -n "$pending" ]; then
108
+ printf '%s' "$pending" >> "$TARGET"
109
+ pending=""
110
+ fi
111
+ printf '%s\n' "$line" >> "$TARGET"
112
+ echo " + $line"
113
+ added=$((added + 1))
53
114
  fi
54
- printf '%s\n' "$line" >> "$TARGET"
55
- echo " + $line"
56
- added=$((added + 1))
57
115
  fi
116
+ done < "$1"
117
+ }
118
+
119
+ i=1
120
+ while [ "$i" -le "$SECTION_COUNT" ]; do
121
+ SEC="$WORK_DIR/sec.$i"
122
+ TITLE="section $i"
123
+ [ -f "$WORK_DIR/title.$i" ] && TITLE="$(cat "$WORK_DIR/title.$i")"
124
+ if section_represented "$SEC"; then
125
+ merge_section "$SEC"
126
+ elif [ "$INTERACTIVE" = true ] && prompt_yn " Add .gitignore section '$TITLE'? [y/N]: "; then
127
+ merge_section "$SEC"
128
+ else
129
+ echo " .gitignore section '$TITLE': skipped (opt in via 'npx @codewizard-dt/bootstrap update')."
58
130
  fi
59
- done < "$TEMPLATE_GITIGNORE"
131
+ i=$((i + 1))
132
+ done
60
133
 
61
134
  if [ "$added" -eq 0 ]; then
62
135
  echo ".gitignore: already up to date in $PROJECT_DIR"
@@ -119,8 +119,15 @@ else
119
119
  echo ""
120
120
  fi
121
121
 
122
- # --- Scaffold first: wiki tree + CLAUDE.md schema + guides -----------------
123
- "$SCRIPT_DIR/sync-wiki-scaffold.sh" "$PROJECT_DIR"
122
+ # --- Scaffold first: wiki tree + CLAUDE.md schema + tiered guides ----------
123
+ "$SCRIPT_DIR/sync-wiki-scaffold.sh" --interactive "$PROJECT_DIR"
124
+ echo ""
125
+
126
+ # --- Assemble mcp-tools.md for the detected MCPs (sync no longer ships it) --
127
+ echo "Building MCP tools guide..."
128
+ installed_mcps="$(detect_installed_mcps "$PROJECT_DIR")"
129
+ # Unquoted on purpose: word-split the space-separated names into arguments.
130
+ "$SCRIPT_DIR/build-mcp-guide.sh" "$PROJECT_DIR" $installed_mcps
124
131
  echo ""
125
132
 
126
133
  # --- Run the Claude-driven migration ---------------------------------------
@@ -4,6 +4,8 @@ set -euo pipefail
4
4
  # Deployment / CI scaffolding seam — separate from the wiki/skills/MCP sync flow.
5
5
  # Reads raw/guides/deployment-strategy.md as a prompt template and runs Claude
6
6
  # to scaffold .github/ workflows + Makefile + .gitleaks.toml into a target project.
7
+ # Also copies the guide itself into the target's wiki/guides/ (deploy-only tier
8
+ # — the wiki sync deliberately never ships it).
7
9
  #
8
10
  # Deliberately not called by setup-project.sh or update-project.sh: workflows get
9
11
  # hand-customized per project (Dockerfile paths, runner labels, deploy steps) and
@@ -68,6 +70,13 @@ if [ "$DRY_RUN" = true ]; then
68
70
  exit 0
69
71
  fi
70
72
 
73
+ # Deliver the deployment guide into the target (deploy-only tier — the wiki
74
+ # sync never ships it). Always refreshed: template-owned reference documenting
75
+ # the topology the scaffolded CI implements. Landed before the Claude run so
76
+ # it survives a timeout.
77
+ mkdir -p "$PROJECT_DIR/wiki/guides"
78
+ rsync -av "$GUIDE" "$PROJECT_DIR/wiki/guides/deployment-strategy.md"
79
+
71
80
  TASK="$(sed "s|__PROJECT_DIR__|$PROJECT_DIR|g" "$TEMPLATE")"
72
81
 
73
82
  PROMPT="$(cat "$GUIDE")
@@ -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