@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.
- package/README.md +9 -9
- package/lib/README.md +1 -1
- package/lib/hooks/lib/serena.js +20 -6
- package/lib/prompts/migrate-wiki.md +2 -2
- package/lib/prompts/setup-strict-typechecks.md +18 -7
- package/lib/scripts/README.md +8 -8
- package/lib/scripts/bootstrap-serena.sh +8 -6
- package/lib/scripts/build-mcp-guide.sh +3 -3
- package/lib/scripts/install-mcps.sh +71 -28
- package/lib/scripts/lib.sh +35 -8
- package/lib/scripts/merge-gitignore.sh +102 -29
- package/lib/scripts/migrate-project.sh +9 -2
- package/lib/scripts/setup-deployment.sh +9 -0
- package/lib/scripts/sync-wiki-scaffold.sh +145 -24
- package/lib/scripts/templates/CLAUDE-wiki.md +6 -2
- package/lib/scripts/templates/guides/stubs/serena.md +7 -7
- package/lib/scripts/templates/wiki/conventions.md +2 -0
- package/lib/scripts/templates/wiki/index.md +6 -0
- package/lib/skills/bug-close/SKILL.md +1 -1
- package/lib/skills/bug-file/SKILL.md +2 -2
- package/lib/skills/bug-triage/SKILL.md +1 -1
- package/lib/skills/debug-logs/SKILL.md +2 -2
- package/lib/skills/decision-create/SKILL.md +1 -1
- package/lib/skills/decision-finalize/SKILL.md +1 -1
- package/lib/skills/decision-next/SKILL.md +1 -1
- package/lib/skills/decision-walkthrough/SKILL.md +1 -1
- package/lib/skills/demo/SKILL.md +1 -1
- package/lib/skills/eval-create/SKILL.md +7 -3
- package/lib/skills/eval-gap/SKILL.md +6 -2
- package/lib/skills/eval-run/SKILL.md +1 -1
- package/lib/skills/extract-feature/SKILL.md +1 -1
- package/lib/skills/gap-assess/SKILL.md +1 -1
- package/lib/skills/git-commit/SKILL.md +1 -1
- package/lib/skills/lint/SKILL.md +1 -1
- package/lib/skills/marp-slideshow/SKILL.md +1 -1
- package/lib/skills/mermaid-flowchart/SKILL.md +1 -1
- package/lib/skills/now/SKILL.md +1 -1
- package/lib/skills/port-feature/SKILL.md +1 -1
- package/lib/skills/power-mode/SKILL.md +1 -1
- package/lib/skills/primer/SKILL.md +2 -2
- package/lib/skills/project-readme/SKILL.md +1 -1
- package/lib/skills/req-create/SKILL.md +1 -1
- package/lib/skills/req-extract-decisions/SKILL.md +1 -1
- package/lib/skills/req-finalize/SKILL.md +1 -1
- package/lib/skills/req-retire/SKILL.md +2 -2
- package/lib/skills/req-update/SKILL.md +1 -1
- package/lib/skills/research/SKILL.md +1 -1
- package/lib/skills/roadmap-add/SKILL.md +2 -2
- package/lib/skills/roadmap-create/SKILL.md +3 -3
- package/lib/skills/roadmap-next/SKILL.md +1 -1
- package/lib/skills/serena-config/SKILL.md +1 -1
- package/lib/skills/simplify/SKILL.md +1 -1
- package/lib/skills/tackle/SKILL.md +3 -3
- package/lib/skills/task-add/SKILL.md +1 -1
- package/lib/skills/task-audit/SKILL.md +2 -2
- package/lib/skills/task-trash/SKILL.md +1 -1
- package/lib/skills/task-update/SKILL.md +2 -2
- package/lib/skills/uat-auto/SKILL.md +1 -1
- package/lib/skills/uat-auto-plus/SKILL.md +1 -1
- package/lib/skills/uat-generate/SKILL.md +1 -1
- package/lib/skills/uat-skip/SKILL.md +1 -1
- package/lib/skills/uat-walk/SKILL.md +1 -1
- package/lib/skills/uat-walk/UAT-CORE.md +1 -1
- package/lib/skills/update-docs/SKILL.md +2 -2
- package/lib/skills/wiki-ingest/SKILL.md +1 -1
- package/lib/skills/wiki-lint/SKILL.md +1 -1
- package/lib/skills/wiki-query/SKILL.md +1 -1
- package/package.json +1 -1
- package/raw/guides/type-checking-templates/README.md +7 -7
- package/raw/guides/type-checking-templates/eslint/eslint.config.ts +1 -1
- package/raw/research/mcp-add-scope-writes/index.md +46 -0
- package/raw/research/mcp-add-scope-writes/sources.md +38 -0
- package/raw/research/mcp-scope-conflict-handling/index.md +61 -0
- package/raw/research/mcp-scope-conflict-handling/sources.md +32 -0
- package/.github/workflows/build.yml +0 -88
- package/raw/guides/mcp-tools.md +0 -335
- 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
|
-
|
|
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
|
-
|
|
26
|
-
|
|
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
|
-
|
|
31
|
-
|
|
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
|
-
|
|
34
|
-
trimmed="${line#"${line%%[![:space:]]*}"}" # leading-whitespace stripped
|
|
89
|
+
added=0
|
|
35
90
|
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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:
|
|
53
|
-
|
|
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
|
|
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 [
|
|
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
|
-
|
|
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
|
|
86
|
-
#
|
|
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 "$
|
|
90
|
-
if
|
|
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 "$
|
|
218
|
+
cat "$SCHEMA_FILE"
|
|
96
219
|
} > "$TMP_CLAUDE"
|
|
97
|
-
mv "$TMP_CLAUDE" "$
|
|
98
|
-
echo ".env safety policy prepended to top of
|
|
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
|
|
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
|
-
|
|
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
|
|
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/'
|
|
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="
|
|
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="
|
|
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
|
|
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
|
|
61
|
+
ls wiki/work/uat/screenshots/
|
|
62
62
|
```
|
|
63
63
|
|
|
64
|
-
✅ **Correct**: `mcp__serena__list_dir(relative_path="
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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 | `
|
|
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
|
|
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
|
|
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
|
|
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
|
|
10
|
+
**Prereqs:** obey `wiki/guides/mcp-tools.md`; run /primer if not done this session.
|
|
11
11
|
|
|
12
12
|
|
|
13
13
|
# Walkthrough Decision
|
package/lib/skills/demo/SKILL.md
CHANGED
|
@@ -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
|
|
10
|
+
**Prereqs:** obey `wiki/guides/mcp-tools.md`; run /primer if not done this session.
|
|
11
11
|
|
|
12
12
|
# Demo
|
|
13
13
|
|