@codewizard-dt/bootstrap 2.11.2 → 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.
- 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 +7 -7
- 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 +34 -7
- 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,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
|
|
|
@@ -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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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: <feature name or description>
|
|
|
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
|
|
|
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
|
|
11
|
+
**Prereqs:** obey `wiki/guides/mcp-tools.md`; run /primer if not done this session.
|
|
12
12
|
|
|
13
13
|
# Gap Assess
|
|
14
14
|
|
package/lib/skills/lint/SKILL.md
CHANGED
|
@@ -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
|
|
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
|
|
10
|
+
**Prereqs:** obey `wiki/guides/mcp-tools.md`; run /primer if not done this session.
|
|
11
11
|
|
|
12
12
|
# Mermaid Flowchart
|
|
13
13
|
|
package/lib/skills/now/SKILL.md
CHANGED
|
@@ -8,7 +8,7 @@ argument-hint: <task description>
|
|
|
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
|
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
11
|
+
**Prereqs:** obey `wiki/guides/mcp-tools.md`; run /primer if not done this session.
|
|
12
12
|
|
|
13
13
|
|
|
14
14
|
# Requirement to Decisions
|