@codewizard-dt/bootstrap 2.10.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 (186) hide show
  1. package/.github/workflows/build.yml +88 -0
  2. package/.github/workflows/security.yml +24 -0
  3. package/.gitleaks.toml +15 -0
  4. package/README.md +472 -0
  5. package/bin/cli.js +47 -0
  6. package/lib/README.md +27 -0
  7. package/lib/hooks/README.md +316 -0
  8. package/lib/hooks/env-file-guard.js +45 -0
  9. package/lib/hooks/git-protected-ops-block.js +77 -0
  10. package/lib/hooks/lib/serena-languages.js +158 -0
  11. package/lib/hooks/lib/serena.js +787 -0
  12. package/lib/hooks/mv-absolute-path-block.js +53 -0
  13. package/lib/hooks/serena-bash-grep-block.js +501 -0
  14. package/lib/hooks/serena-edit-guard.js +74 -0
  15. package/lib/hooks/serena-first-glob-guard.js +94 -0
  16. package/lib/hooks/serena-first-guard.js +74 -0
  17. package/lib/hooks/serena-first-read-guard.js +167 -0
  18. package/lib/hooks/serena-pre-delegation.js +117 -0
  19. package/lib/hooks/serena-session-reset.js +45 -0
  20. package/lib/hooks/serena-usage-tracker.js +186 -0
  21. package/lib/hooks/serena-write-guard.js +58 -0
  22. package/lib/prompts/README.md +16 -0
  23. package/lib/prompts/migrate-wiki.md +111 -0
  24. package/lib/prompts/setup-deployment.md +322 -0
  25. package/lib/prompts/setup-design-system.md +162 -0
  26. package/lib/prompts/setup-strict-typechecks.md +139 -0
  27. package/lib/scripts/README.md +49 -0
  28. package/lib/scripts/bootstrap-serena.sh +145 -0
  29. package/lib/scripts/build-mcp-guide.sh +108 -0
  30. package/lib/scripts/install-global.sh +78 -0
  31. package/lib/scripts/install-mcps.sh +131 -0
  32. package/lib/scripts/lib.sh +154 -0
  33. package/lib/scripts/merge-gitignore.sh +65 -0
  34. package/lib/scripts/migrate-project.sh +273 -0
  35. package/lib/scripts/setup-deployment.sh +104 -0
  36. package/lib/scripts/setup-project.sh +55 -0
  37. package/lib/scripts/setup-runner.sh +99 -0
  38. package/lib/scripts/setup-strict-typechecks.sh +29 -0
  39. package/lib/scripts/startup.sh +42 -0
  40. package/lib/scripts/sync-wiki-scaffold.sh +104 -0
  41. package/lib/scripts/templates/CLAUDE-env-safety.md +3 -0
  42. package/lib/scripts/templates/CLAUDE-wiki.md +60 -0
  43. package/lib/scripts/templates/gitignore +136 -0
  44. package/lib/scripts/templates/guides/stubs/00-header.md +15 -0
  45. package/lib/scripts/templates/guides/stubs/brave-search.md +20 -0
  46. package/lib/scripts/templates/guides/stubs/context7.md +26 -0
  47. package/lib/scripts/templates/guides/stubs/playwright.md +26 -0
  48. package/lib/scripts/templates/guides/stubs/serena.md +219 -0
  49. package/lib/scripts/templates/wiki/conventions.md +100 -0
  50. package/lib/scripts/templates/wiki/dashboard.html +1733 -0
  51. package/lib/scripts/templates/wiki/hot.md +21 -0
  52. package/lib/scripts/templates/wiki/index.md +46 -0
  53. package/lib/scripts/templates/wiki/knowledge/concepts/.gitkeep +0 -0
  54. package/lib/scripts/templates/wiki/knowledge/entities/components/.gitkeep +0 -0
  55. package/lib/scripts/templates/wiki/knowledge/entities/organisations/.gitkeep +0 -0
  56. package/lib/scripts/templates/wiki/knowledge/entities/people/.gitkeep +0 -0
  57. package/lib/scripts/templates/wiki/knowledge/entities/tools/.gitkeep +0 -0
  58. package/lib/scripts/templates/wiki/knowledge/sources/.gitkeep +0 -0
  59. package/lib/scripts/templates/wiki/log.md +14 -0
  60. package/lib/scripts/templates/wiki/work/bugs/.gitkeep +0 -0
  61. package/lib/scripts/templates/wiki/work/bugs/archive/index.md +6 -0
  62. package/lib/scripts/templates/wiki/work/bugs/index.md +12 -0
  63. package/lib/scripts/templates/wiki/work/bugs/lifecycle.md +39 -0
  64. package/lib/scripts/templates/wiki/work/decisions/.gitkeep +0 -0
  65. package/lib/scripts/templates/wiki/work/decisions/archive/index.md +6 -0
  66. package/lib/scripts/templates/wiki/work/decisions/index.md +12 -0
  67. package/lib/scripts/templates/wiki/work/decisions/lifecycle.md +42 -0
  68. package/lib/scripts/templates/wiki/work/requirements/.gitkeep +0 -0
  69. package/lib/scripts/templates/wiki/work/requirements/archive/index.md +6 -0
  70. package/lib/scripts/templates/wiki/work/requirements/index.md +12 -0
  71. package/lib/scripts/templates/wiki/work/requirements/lifecycle.md +34 -0
  72. package/lib/scripts/templates/wiki/work/roadmaps/.gitkeep +0 -0
  73. package/lib/scripts/templates/wiki/work/roadmaps/archive/index.md +6 -0
  74. package/lib/scripts/templates/wiki/work/roadmaps/index.md +12 -0
  75. package/lib/scripts/templates/wiki/work/roadmaps/lifecycle.md +32 -0
  76. package/lib/scripts/templates/wiki/work/tasks/.gitkeep +0 -0
  77. package/lib/scripts/templates/wiki/work/tasks/archive/index.md +6 -0
  78. package/lib/scripts/templates/wiki/work/tasks/index.md +12 -0
  79. package/lib/scripts/templates/wiki/work/tasks/lifecycle.md +39 -0
  80. package/lib/scripts/templates/wiki/work/uat/.gitkeep +0 -0
  81. package/lib/scripts/templates/wiki/work/uat/archive/index.md +6 -0
  82. package/lib/scripts/templates/wiki/work/uat/index.md +12 -0
  83. package/lib/scripts/templates/wiki/work/uat/lifecycle.md +48 -0
  84. package/lib/scripts/templates/wiki/work/uat/screenshots/.gitkeep +0 -0
  85. package/lib/scripts/update-project.sh +75 -0
  86. package/lib/scripts/wiki-dashboard-server.js +146 -0
  87. package/lib/skills/README.md +146 -0
  88. package/lib/skills/anti-slop/SKILL.md +183 -0
  89. package/lib/skills/bug-close/SKILL.md +136 -0
  90. package/lib/skills/bug-file/SKILL.md +114 -0
  91. package/lib/skills/bug-triage/SKILL.md +140 -0
  92. package/lib/skills/company-align/SKILL.md +203 -0
  93. package/lib/skills/debug-logs/SKILL.md +129 -0
  94. package/lib/skills/decision-create/SKILL.md +220 -0
  95. package/lib/skills/decision-finalize/SKILL.md +181 -0
  96. package/lib/skills/decision-next/SKILL.md +129 -0
  97. package/lib/skills/decision-walkthrough/SKILL.md +169 -0
  98. package/lib/skills/demo/SKILL.md +183 -0
  99. package/lib/skills/elevator-pitch/SKILL.md +125 -0
  100. package/lib/skills/eval-create/SKILL.md +344 -0
  101. package/lib/skills/eval-gap/SKILL.md +150 -0
  102. package/lib/skills/eval-run/SKILL.md +214 -0
  103. package/lib/skills/extract-feature/SKILL.md +344 -0
  104. package/lib/skills/flashcard/SKILL.md +513 -0
  105. package/lib/skills/frontend-taste/SKILL.md +184 -0
  106. package/lib/skills/gap-assess/SKILL.md +97 -0
  107. package/lib/skills/git-commit/SKILL.md +164 -0
  108. package/lib/skills/lint/SKILL.md +99 -0
  109. package/lib/skills/marp-slideshow/SKILL.md +212 -0
  110. package/lib/skills/mermaid-flowchart/SKILL.md +194 -0
  111. package/lib/skills/now/SKILL.md +36 -0
  112. package/lib/skills/port-feature/SKILL.md +315 -0
  113. package/lib/skills/power-mode/SKILL.md +184 -0
  114. package/lib/skills/primer/SKILL.md +84 -0
  115. package/lib/skills/project-readme/SKILL.md +166 -0
  116. package/lib/skills/req-compile/SKILL.md +131 -0
  117. package/lib/skills/req-create/SKILL.md +124 -0
  118. package/lib/skills/req-extract-decisions/SKILL.md +241 -0
  119. package/lib/skills/req-finalize/SKILL.md +251 -0
  120. package/lib/skills/req-retire/SKILL.md +185 -0
  121. package/lib/skills/req-update/SKILL.md +265 -0
  122. package/lib/skills/research/SKILL.md +250 -0
  123. package/lib/skills/research-company/SKILL.md +345 -0
  124. package/lib/skills/roadmap-add/SKILL.md +238 -0
  125. package/lib/skills/roadmap-create/SKILL.md +223 -0
  126. package/lib/skills/roadmap-next/SKILL.md +132 -0
  127. package/lib/skills/security-audit/SKILL.md +246 -0
  128. package/lib/skills/serena-config/SKILL.md +92 -0
  129. package/lib/skills/simplify/SKILL.md +227 -0
  130. package/lib/skills/tackle/SKILL.md +156 -0
  131. package/lib/skills/task-add/SKILL.md +208 -0
  132. package/lib/skills/task-audit/SKILL.md +294 -0
  133. package/lib/skills/task-trash/SKILL.md +115 -0
  134. package/lib/skills/task-update/SKILL.md +136 -0
  135. package/lib/skills/uat-auto/SKILL.md +69 -0
  136. package/lib/skills/uat-auto-plus/SKILL.md +115 -0
  137. package/lib/skills/uat-generate/SKILL.md +289 -0
  138. package/lib/skills/uat-skip/SKILL.md +169 -0
  139. package/lib/skills/uat-walk/SKILL.md +164 -0
  140. package/lib/skills/uat-walk/UAT-CORE.md +140 -0
  141. package/lib/skills/update-docs/SKILL.md +75 -0
  142. package/lib/skills/wiki-archive/SKILL.md +96 -0
  143. package/lib/skills/wiki-ingest/SKILL.md +139 -0
  144. package/lib/skills/wiki-lint/SKILL.md +131 -0
  145. package/lib/skills/wiki-query/SKILL.md +71 -0
  146. package/lib/skills/wiki-rotate-log/SKILL.md +90 -0
  147. package/lib/skills/wiki-tidy/SKILL.md +107 -0
  148. package/package.json +32 -0
  149. package/raw/.gitkeep +0 -0
  150. package/raw/design-principles.md +65 -0
  151. package/raw/guides/command-anti-patterns.md +79 -0
  152. package/raw/guides/deployment-strategy.md +448 -0
  153. package/raw/guides/evals-framework.md +452 -0
  154. package/raw/guides/mcp-tools.md +335 -0
  155. package/raw/guides/task-spec.md +79 -0
  156. package/raw/guides/type-checking-templates/README.md +112 -0
  157. package/raw/guides/type-checking-templates/eslint/eslint.config.ts +105 -0
  158. package/raw/guides/type-checking-templates/python/mypy.ini +69 -0
  159. package/raw/guides/type-checking-templates/python/pyproject.toml +164 -0
  160. package/raw/guides/type-checking-templates/python/pyrightconfig.json +67 -0
  161. package/raw/guides/type-checking-templates/tsconfig/tsconfig.app.jsonc +45 -0
  162. package/raw/guides/type-checking-templates/tsconfig/tsconfig.lib.jsonc +44 -0
  163. package/raw/guides/type-checking-templates/tsconfig/tsconfig.node-esm.jsonc +40 -0
  164. package/raw/guides/type-checking-templates/tsconfig/tsconfig.node.jsonc +34 -0
  165. package/raw/guides/type-checking-templates/tsconfig/tsconfig.vite-root.json +8 -0
  166. package/raw/harness-notes.md +20 -0
  167. package/raw/house-style/components/Badge.tsx +16 -0
  168. package/raw/house-style/components/Button.tsx +32 -0
  169. package/raw/house-style/components/Card.tsx +26 -0
  170. package/raw/house-style/components/Chip.tsx +57 -0
  171. package/raw/house-style/components/IconButton.tsx +67 -0
  172. package/raw/house-style/components/Modal.tsx +18 -0
  173. package/raw/house-style/components/Stepper.tsx +141 -0
  174. package/raw/house-style/components/icons.tsx +128 -0
  175. package/raw/house-style/preview/src/index.css +46 -0
  176. package/raw/house-style/tokens/tailwind.preset.ts +49 -0
  177. package/raw/house-style/tokens/tokens.json +62 -0
  178. package/raw/llm-wiki-2.md +162 -0
  179. package/raw/llm-wiki.md +75 -0
  180. package/raw/research/dark-mode-theme/index.md +85 -0
  181. package/raw/research/dark-mode-theme/sources.md +49 -0
  182. package/raw/research/serena-mcp-disconnect/index.md +81 -0
  183. package/raw/research/serena-mcp-disconnect/sources.md +87 -0
  184. package/raw/research/wiki-tooling-improvements/index.md +126 -0
  185. package/raw/research/wiki-tooling-improvements/sources.md +73 -0
  186. package/raw/software-factory-case-study.pdf +0 -0
@@ -0,0 +1,104 @@
1
+ #!/usr/bin/env bash
2
+ set -euo pipefail
3
+
4
+ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
5
+ . "$SCRIPT_DIR/lib.sh"
6
+ TEMPLATE_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
7
+ TEMPLATES="$SCRIPT_DIR/templates/wiki"
8
+
9
+ if [ $# -ne 1 ]; then
10
+ echo "Usage: $0 <path-to-project>"
11
+ exit 1
12
+ fi
13
+
14
+ PROJECT_DIR="$(resolve_project_dir "$1")" || exit 1
15
+
16
+ echo "Syncing wiki scaffold into: $PROJECT_DIR"
17
+
18
+ # 1. Create all directories
19
+ mkdir -p \
20
+ "$PROJECT_DIR/raw" \
21
+ "$PROJECT_DIR/wiki" \
22
+ "$PROJECT_DIR/wiki/knowledge/sources" \
23
+ "$PROJECT_DIR/wiki/knowledge/concepts" \
24
+ "$PROJECT_DIR/wiki/knowledge/entities/people" \
25
+ "$PROJECT_DIR/wiki/knowledge/entities/organisations" \
26
+ "$PROJECT_DIR/wiki/knowledge/entities/tools" \
27
+ "$PROJECT_DIR/wiki/knowledge/entities/components" \
28
+ "$PROJECT_DIR/wiki/work/requirements" \
29
+ "$PROJECT_DIR/wiki/work/decisions" \
30
+ "$PROJECT_DIR/wiki/work/roadmaps" \
31
+ "$PROJECT_DIR/wiki/work/tasks" \
32
+ "$PROJECT_DIR/wiki/work/uat" \
33
+ "$PROJECT_DIR/wiki/work/uat/screenshots" \
34
+ "$PROJECT_DIR/wiki/work/bugs" \
35
+ "$PROJECT_DIR/.docs/guides"
36
+
37
+ # 2. COPY-ONCE: index.md, log.md, hot.md, .gitkeep files — project-owned after creation, never overwrite
38
+ # Exclude conventions.md and lifecycle.md (those are always-refresh, handled in step 3).
39
+ rsync -av --ignore-existing \
40
+ --exclude 'conventions.md' \
41
+ --exclude 'lifecycle.md' \
42
+ --exclude 'dashboard.html' \
43
+ "$TEMPLATES/" "$PROJECT_DIR/wiki/"
44
+
45
+ # 3. ALWAYS-REFRESH: spec docs (conventions.md, lifecycle.md) and dashboard.html that remain template-owned; always overwrite
46
+ rsync -av "$TEMPLATES/conventions.md" "$PROJECT_DIR/wiki/conventions.md"
47
+ rsync -av "$TEMPLATES/dashboard.html" "$PROJECT_DIR/wiki/dashboard.html"
48
+ for fam in requirements decisions roadmaps tasks uat bugs; do
49
+ rsync -av "$TEMPLATES/work/$fam/lifecycle.md" "$PROJECT_DIR/wiki/work/$fam/lifecycle.md"
50
+ done
51
+
52
+ # 4. GUIDES: always refresh from raw/guides/ into target .docs/guides/
53
+ rsync -av "$TEMPLATE_DIR/raw/guides/" "$PROJECT_DIR/.docs/guides/"
54
+
55
+ # 5. Ensure raw/ has a .gitkeep so git tracks the empty dir
56
+ touch -a "$PROJECT_DIR/raw/.gitkeep" 2>/dev/null || true
57
+
58
+ # 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.
60
+ CLAUDE_TEMPLATE="$SCRIPT_DIR/templates/CLAUDE-wiki.md"
61
+ TARGET_CLAUDE="$PROJECT_DIR/CLAUDE.md"
62
+ if [ -f "$CLAUDE_TEMPLATE" ]; then
63
+ if [ ! -f "$TARGET_CLAUDE" ]; then
64
+ {
65
+ echo "# CLAUDE.md"
66
+ echo ""
67
+ echo "This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository."
68
+ echo ""
69
+ cat "$CLAUDE_TEMPLATE"
70
+ } > "$TARGET_CLAUDE"
71
+ 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
+ else
81
+ echo "CLAUDE.md already has the LLM Wiki schema section, skipping."
82
+ fi
83
+ fi
84
+
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.
87
+ ENV_TEMPLATE="$SCRIPT_DIR/templates/CLAUDE-env-safety.md"
88
+ 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
91
+ TMP_CLAUDE="$(mktemp)"
92
+ {
93
+ cat "$ENV_TEMPLATE"
94
+ echo ""
95
+ cat "$TARGET_CLAUDE"
96
+ } > "$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."
101
+ fi
102
+ fi
103
+
104
+ echo "Wiki scaffold synced."
@@ -0,0 +1,3 @@
1
+ **IMPORTANT**
2
+ - You are never allowed to read or write to any `.env` file. The only exception is `.env.example`.
3
+ - You are, however, allowed to source an `.env` file to use the variables in the command line.
@@ -0,0 +1,60 @@
1
+ ## LLM Wiki
2
+
3
+ This project maintains a three-layer LLM Wiki. This section is the **schema** — it tells you how the wiki is structured and what rules govern it.
4
+
5
+ ```
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.
8
+ CLAUDE.md This schema section.
9
+ ```
10
+
11
+ ### Two domains with opposite organizing laws
12
+
13
+ **`wiki/knowledge/`** — timeless synthesis, organized by links not status. Pages are revised in place as understanding evolves; no `status` field.
14
+
15
+ - `wiki/knowledge/sources/` — one summary page per ingested `raw/` source
16
+ - `wiki/knowledge/concepts/` — patterns, ideas, conventions, recurring themes
17
+ - `wiki/knowledge/entities/{people,organisations,tools,components}/` — one page per entity, filed by sub-type
18
+
19
+ **`wiki/work/`** — stateful lifecycle artifacts, organized by status. Active files are **never moved** after creation; state lives in the `status:` frontmatter field. Each family has a `lifecycle.md` (schema + valid transitions), an `index.md` listing **only active items**, and an `archive/` subdirectory for terminal items. When an item leaves the active set, delete its line from the family index; terminal items may be moved to `archive/` by `/wiki-archive`.
20
+
21
+ - `wiki/work/requirements/` — REQ-NNN
22
+ - `wiki/work/decisions/` — DEC-NNNN (per-decision `#DM`)
23
+ - `wiki/work/roadmaps/` — ROADMAP-NNN
24
+ - `wiki/work/tasks/` — TASK-NNN
25
+ - `wiki/work/uat/` — UAT-NNN (own family, one per task)
26
+ - `wiki/work/bugs/` — BUG-NNNN
27
+
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
+
30
+ ### Auto Memory vs. this wiki
31
+
32
+ Claude Code has its own native **Auto Memory** feature — typed memory files (`user`, `feedback`, `project`, `reference`) kept under `~/.claude/projects/<hash>/memory/`, indexed by `MEMORY.md`, auto-loaded at session start. It is **cross-project and un-versioned**: it lives outside this git repo and follows the user across every project. This wiki, by contrast, is **per-project and git-versioned**: it lives in `wiki/`, is reviewable in diffs, and is shared with anyone who clones the repo.
33
+
34
+ Rule of thumb for where a new fact belongs:
35
+
36
+ - **Auto Memory** — facts about the *user* and their cross-project working style: how they like to collaborate, standing preferences, feedback that applies regardless of which repo is open. If a fact is true only because "the user told me once" and holds everywhere → Auto Memory.
37
+ - **This wiki** — facts about *this project*: its architecture, decisions, requirements, tasks, and synthesized knowledge that should be versioned, reviewable, and survive in git history. If a fact is true because "this project decided X" → wiki.
38
+
39
+ Keep the two from duplicating or contradicting each other: project-specific state does not go in Auto Memory, and cross-project user preferences do not go in the wiki.
40
+
41
+ ### Wiki operations
42
+
43
+ | Command | Purpose |
44
+ |---------|---------|
45
+ | `/wiki-ingest <raw-file>` | Process a source from `raw/` into the wiki — summary page, entity/concept updates, index + log entries |
46
+ | `/wiki-query <question>` | Answer from the wiki with citations; offer to file valuable synthesis back as a new page |
47
+ | `/wiki-lint` | Health-check — contradictions, orphan pages, stale claims, index drift, never-ingested raw sources |
48
+ | `/wiki-archive [family]` | Batch-move terminal work items into `<family>/archive/`; update `archive/index.md` and log the operation |
49
+ | `/wiki-rotate-log` | Rotate `wiki/log.md` to a timestamped archive file when it exceeds ~500 lines; create a fresh `log.md` with an archive pointer |
50
+ | `/wiki-tidy` | One-shot cleanup — lint, archive terminal items across all families, then rotate log if overgrown; phases run in sequence with user confirmation |
51
+
52
+ ### CRITICAL wiki rules
53
+
54
+ 1. `raw/` is immutable — never create, modify, move, or delete files under `raw/`
55
+ 2. Cross-link aggressively — related pages link to each other with relative markdown links; the link network is as valuable as the pages
56
+ 3. Index and log updates are mandatory — every ingest and filed answer updates `wiki/index.md` + `wiki/log.md`; every work-item create or status flip updates the family `index.md` + `wiki/log.md`
57
+ 4. Flag contradictions explicitly — when a new source conflicts with an existing page, add a `> **Contradiction:**` callout citing both; never silently overwrite
58
+ 5. Answer from the wiki, not general knowledge — if the wiki lacks coverage, say so and suggest `/wiki-ingest` for relevant sources
59
+ 6. Atomic pages — one concept, entity, or artifact per file; split a page rather than let it cover two things
60
+ 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/`
@@ -0,0 +1,136 @@
1
+ # ---------------------------------------------------------------------------
2
+ # OS / Editor
3
+ # ---------------------------------------------------------------------------
4
+ .DS_Store
5
+ Thumbs.db
6
+ *~
7
+ .idea/
8
+ .vscode/*
9
+ !.vscode/settings.json
10
+ !.vscode/extensions.json
11
+ *.swp
12
+ .conductor
13
+
14
+
15
+ # ---------------------------------------------------------------------------
16
+ # Claude Code — machine-local MCP registration (absolute paths; regenerated by setup)
17
+ # ---------------------------------------------------------------------------
18
+ .mcp.json
19
+ .playwright-mcp/
20
+
21
+ # ---------------------------------------------------------------------------
22
+ # Secrets & local environment (NEVER commit real secrets)
23
+ # ---------------------------------------------------------------------------
24
+ .env
25
+ .env.*
26
+ !.env.example
27
+ *.pem
28
+ *.key
29
+
30
+ # ---------------------------------------------------------------------------
31
+ # Logs & temp
32
+ # ---------------------------------------------------------------------------
33
+ *.log
34
+ logs/
35
+ tmp/
36
+ *.tmp
37
+
38
+ # ---------------------------------------------------------------------------
39
+ # Node / TypeScript / JavaScript
40
+ # ---------------------------------------------------------------------------
41
+ node_modules/
42
+ dist/
43
+ build/
44
+ out/
45
+ .next/
46
+ .nuxt/
47
+ .cache/
48
+ coverage/
49
+ *.tgz
50
+ *.tsbuildinfo
51
+ .npm/
52
+ .eslintcache
53
+ .pnp.*
54
+ .yarn/*
55
+ !.yarn/patches
56
+ !.yarn/releases
57
+
58
+ # ---------------------------------------------------------------------------
59
+ # Python
60
+ # ---------------------------------------------------------------------------
61
+ __pycache__/
62
+ *.py[cod]
63
+ *$py.class
64
+ *.egg
65
+ *.egg-info/
66
+ .eggs/
67
+ .installed.cfg
68
+ develop-eggs/
69
+ sdist/
70
+ wheels/
71
+ share/python-wheels/
72
+ MANIFEST
73
+
74
+ # Virtual environments
75
+ .venv/
76
+ venv/
77
+ env/
78
+ ENV/
79
+ .python-version
80
+
81
+ # Test / type / lint caches
82
+ .pytest_cache/
83
+ .mypy_cache/
84
+ .dmypy.json
85
+ .pyre/
86
+ .ruff_cache/
87
+ .tox/
88
+ .nox/
89
+ .coverage
90
+ .coverage.*
91
+ htmlcov/
92
+ .hypothesis/
93
+
94
+ # ---------------------------------------------------------------------------
95
+ # Jupyter / Notebooks
96
+ # ---------------------------------------------------------------------------
97
+ .ipynb_checkpoints/
98
+ */.ipynb_checkpoints/*
99
+ profile_default/
100
+ ipython_config.py
101
+
102
+ # ---------------------------------------------------------------------------
103
+ # Machine Learning — models, checkpoints, artifacts
104
+ # ---------------------------------------------------------------------------
105
+ *.ckpt
106
+ *.pt
107
+ *.pth
108
+ *.h5
109
+ *.hdf5
110
+ *.pb
111
+ *.onnx
112
+ *.tflite
113
+ *.pkl
114
+ *.pickle
115
+ *.joblib
116
+ *.safetensors
117
+ *.bin
118
+
119
+ # Experiment tracking & pipelines
120
+ wandb/
121
+ mlruns/
122
+ .mlflow/
123
+ lightning_logs/
124
+ runs/
125
+ outputs/
126
+ checkpoints/
127
+ .dvc/cache
128
+ .dvc/tmp
129
+
130
+ # Datasets — uncomment if large/raw data should NOT be versioned.
131
+ # Prefer DVC / git-lfs / external storage for big data.
132
+ # data/
133
+ # datasets/
134
+ # *.csv
135
+ # *.parquet
136
+ # *.tfrecord
@@ -0,0 +1,15 @@
1
+ # MCP Tools Guide
2
+
3
+ **Purpose**: Mandatory MCP tool usage rules for AI agents
4
+
5
+ ---
6
+
7
+ ## ⚠️ TOP RULE — READ FIRST
8
+
9
+ **NEVER use `sed`, `awk`, `perl -i`, `echo >>`, or any other shell command to edit a file.** This applies to **every** file type — code, markdown, JSON, YAML, `.env`, anything. The fact that markdown is allowed to use standard tools means use the **`Edit`** and **`Write`** tools, **NOT** `sed`.
10
+
11
+ If you find yourself reaching for `sed -i` to flip task checkboxes, update a status line, replace a string in a config file, or do "just a quick fix" to a doc — **stop**. Use the `Edit` tool. If you have many similar replacements in one file, use `Edit` with `replace_all: true` or call `Edit` multiple times. The `Edit` tool is always the right answer.
12
+
13
+ The shell is for running programs (`pnpm test`, `git mv`, `curl`), not for inspecting or modifying files.
14
+
15
+ ---
@@ -0,0 +1,20 @@
1
+
2
+ ## Brave Search (Web Research)
3
+
4
+ ### Rate Limit: 50 requests per second
5
+
6
+ - Up to 50 requests per second are supported — parallel searches are allowed
7
+ - On 429 errors, back off briefly and retry (max 3 times)
8
+
9
+ ### Usage
10
+
11
+ ```python
12
+ mcp__brave-search__brave_web_search(
13
+ query="FastAPI dependency injection best practices 2025",
14
+ count=10
15
+ )
16
+ ```
17
+
18
+ Use for general research, best practices, troubleshooting, news. Do NOT use for library documentation (use Context7).
19
+
20
+ ---
@@ -0,0 +1,26 @@
1
+
2
+ ## Context7 (Library Documentation)
3
+
4
+ Two-step workflow — resolve the library ID, then query docs.
5
+
6
+ ### Step 1: Resolve Library ID
7
+
8
+ ```python
9
+ mcp__context7__resolve-library-id(libraryName="sqlalchemy")
10
+ # Returns: "/sqlalchemy/sqlalchemy"
11
+ ```
12
+
13
+ Skip only if user provides an explicit `/org/project` ID.
14
+
15
+ ### Step 2: Query Documentation
16
+
17
+ ```python
18
+ mcp__context7__query-docs(
19
+ libraryId="/sqlalchemy/sqlalchemy",
20
+ query="async session management"
21
+ )
22
+ ```
23
+
24
+ If results are insufficient, refine the query with more specific terms.
25
+
26
+ ---
@@ -0,0 +1,26 @@
1
+
2
+ ## Playwright (Browser Automation)
3
+
4
+ ### Tools
5
+
6
+ | Tool | Purpose |
7
+ |------|---------|
8
+ | `browser_navigate` | Navigate to a URL |
9
+ | `browser_take_screenshot` | Screenshot current page |
10
+ | `browser_snapshot` | Get accessibility tree (use to get element `ref` IDs before clicking/typing) |
11
+ | `browser_click` | Click element by `ref` ID from snapshot |
12
+ | `browser_type` | Type into an input field by `ref` ID |
13
+ | `browser_evaluate` | Execute JavaScript in browser |
14
+ | `browser_select_option` | Select dropdown option by `ref` ID |
15
+ | `browser_hover` | Hover over element by `ref` ID |
16
+ | `browser_close` | Close the browser |
17
+
18
+ ### Workflow
19
+
20
+ 1. **No explicit launch step** — the browser starts automatically on the first tool call.
21
+ 2. **Accessibility-tree first** — always call `browser_snapshot` to get the current page structure and element `ref` IDs before interacting. Pass the `ref` to `browser_click`, `browser_type`, etc.
22
+ 3. Use `browser_take_screenshot` for visual verification after navigation or interaction.
23
+
24
+ Use for visual verification, form interaction, and browser-rendered content. Do NOT use for static content fetching or library docs.
25
+
26
+ ---
@@ -0,0 +1,219 @@
1
+
2
+ ### Standard tools (`Read`, `Edit`, `Write`) are permitted for:
3
+
4
+ - **Markdown files** (`.md`) — content edits use standard tools (Serena's symbolic editor doesn't apply to prose)
5
+ - **Config files** — JSON, YAML, TOML, `.env`, `.gitignore`, `package.json`, etc.
6
+ - **Creating brand-new files** of any type
7
+ - **Binary files and images** (read only)
8
+
9
+ ### Standard tools are NEVER permitted for:
10
+
11
+ - **Code files** — TypeScript, JavaScript, Python, Go, Rust, etc. Always use Serena's symbolic or file/line tools.
12
+ - **File or directory exploration of any kind**, regardless of file type. This includes:
13
+ - Listing directories → use `mcp__serena__list_dir`, **never** `ls` / `tree` / `find -type d`
14
+ - Finding files by name → use `mcp__serena__find_file`, **never** `find -name` / `ls | grep`
15
+ - Searching file contents → use `mcp__serena__search_for_pattern` or the `Grep` tool, **never** `grep` / `rg` / `ag` invoked through `bash`
16
+ - Reading file contents for inspection → use `mcp__serena__get_symbols_overview` (code) or `Read` (markdown/config), **never** `cat` / `head` / `tail`
17
+ - Editing via shell → **never** `sed` / `awk` / `echo >>`
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.
20
+
21
+ ### Common anti-patterns and their fixes
22
+
23
+ These are real mistakes AI agents make on this codebase. Do not repeat them.
24
+
25
+ #### ❌ Anti-pattern: `sed` to flip task-file checkboxes
26
+
27
+ ```bash
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
30
+ ```
31
+
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.
33
+
34
+ ✅ **Correct**: call the `Edit` tool once per checkbox (or use `replace_all: true` if every `- [ ]` in the file should become `- [x]`):
35
+
36
+ ```
37
+ Edit(file_path=".docs/tasks/051-ux-conversion-audit.md",
38
+ old_string="- [ ] Launch Puppeteer",
39
+ new_string="- [x] Launch Puppeteer")
40
+ Edit(file_path=".docs/tasks/051-ux-conversion-audit.md",
41
+ old_string="- [ ] Navigate and screenshot each marketing",
42
+ new_string="- [x] Navigate and screenshot each marketing")
43
+ # ...one Edit call per checkbox
44
+ ```
45
+
46
+ Yes, even if there are ten checkboxes. Ten `Edit` calls is correct. One `sed` is wrong.
47
+
48
+ #### ❌ Anti-pattern: `cat` to check what's in a file before editing
49
+
50
+ ```bash
51
+ # WRONG
52
+ cat .docs/tasks/051-ux-conversion-audit.md
53
+ ```
54
+
55
+ ✅ **Correct**: `Read` tool. Always.
56
+
57
+ #### ❌ Anti-pattern: `ls` to see what's in a directory
58
+
59
+ ```bash
60
+ # WRONG
61
+ ls .docs/uat/screenshots/
62
+ ```
63
+
64
+ ✅ **Correct**: `mcp__serena__list_dir(relative_path=".docs/uat/screenshots/")`
65
+
66
+ #### ❌ Anti-pattern: `grep -r` to find a string across files
67
+
68
+ ```bash
69
+ # WRONG
70
+ grep -r "pending-uat" .
71
+ ```
72
+
73
+ ✅ **Correct**: the `Grep` tool, or `mcp__serena__search_for_pattern`.
74
+
75
+ #### ❌ Anti-pattern: `echo "new content" >> file.md` to append to a file
76
+
77
+ ```bash
78
+ # WRONG
79
+ echo "## New Section" >> README.md
80
+ ```
81
+
82
+ ✅ **Correct**: `Read` the file first to see the current end, then `Edit` to append (or `Write` if creating fresh).
83
+
84
+ **See also**: [`command-anti-patterns.md`](./command-anti-patterns.md) — shell hygiene, scratch-dir rules, and the /tackle-vs-UAT verification split.
85
+
86
+ ---
87
+
88
+ ## Serena (Code Exploration & Editing)
89
+
90
+ Serena provides two editing approaches:
91
+ 1. **Symbolic** — LSP-powered, refactoring-safe (entire functions/classes)
92
+ 2. **File/line-based** — Precise line-range and regex edits (within functions)
93
+
94
+ ### Tools
95
+
96
+ **Exploration:**
97
+
98
+ | Tool | Purpose | Key Params |
99
+ |------|---------|------------|
100
+ | `get_symbols_overview` | File structure overview | `relative_path`, `depth` (0=top-level) |
101
+ | `find_symbol` | Find symbols by name | `name_path_pattern`, `include_body`, `depth`, `substring_matching` |
102
+ | `find_referencing_symbols` | Find all callers/references | `name_path`, `relative_path` (file, not dir) |
103
+ | `search_for_pattern` | Regex search across files | `substring_pattern`, `relative_path`, `paths_include_glob` |
104
+ | `list_dir` | List directory contents | `relative_path`, `recursive` |
105
+ | `find_file` | Find files by name/mask | `file_mask`, `relative_path` |
106
+
107
+ **Symbolic editing** (use when replacing entire symbols):
108
+
109
+ | Tool | Purpose | Key Params |
110
+ |------|---------|------------|
111
+ | `replace_symbol_body` | Replace function/class body | `name_path`, `relative_path`, `body` (includes signature, NOT docstring) |
112
+ | `insert_after_symbol` | Add code after a symbol | `name_path`, `relative_path`, `body` |
113
+ | `insert_before_symbol` | Add code before a symbol | `name_path`, `relative_path`, `body` |
114
+ | `rename_symbol` | Rename across codebase | `name_path`, `relative_path`, `new_name` |
115
+
116
+ **File/line editing** (use for precise edits within symbols):
117
+
118
+ | Tool | Purpose | Key Params |
119
+ |------|---------|------------|
120
+ | `replace_content` | Literal or regex replacement | `relative_path`, `mode` (literal/regex), `needle`, `repl` |
121
+ | `replace_lines` | Replace line range | `relative_path`, `start_line`, `end_line`, `content` (0-based) |
122
+ | `delete_lines` | Delete line range | `relative_path`, `start_line`, `end_line` (0-based) |
123
+ | `insert_at_line` | Insert at line number | `relative_path`, `line`, `content` (0-based) |
124
+
125
+ ### Name Path Patterns
126
+
127
+ - `"method"` — matches any symbol named "method"
128
+ - `"MyClass/method"` — matches method in MyClass (relative)
129
+ - `"/MyClass/method"` — exact match (absolute)
130
+ - `"MyClass/method[0]"` — specific overload
131
+
132
+ ### Workflow
133
+
134
+ ```
135
+ 1. get_symbols_overview → 2. find_symbol → 3. Edit → 4. find_referencing_symbols
136
+ ```
137
+
138
+ ### Choosing Edit Mode
139
+
140
+ | Scenario | Use |
141
+ |----------|-----|
142
+ | Replace entire function/method/class | Symbolic: `replace_symbol_body` |
143
+ | Add new method to class | Symbolic: `insert_after_symbol` |
144
+ | Rename across codebase | Symbolic: `rename_symbol` |
145
+ | Edit few lines within large function | File/line: `replace_content` or `replace_lines` |
146
+ | Regex-based replacement | File/line: `replace_content` with `mode="regex"` |
147
+ | Edit doesn't align with symbol boundaries | File/line: `replace_lines` |
148
+
149
+ ---
150
+
151
+ ## Onboarding & Memory
152
+
153
+ Always run onboarding check when starting work:
154
+
155
+ ```python
156
+ mcp__serena__check_onboarding_performed()
157
+ # If not performed:
158
+ mcp__serena__onboarding()
159
+ ```
160
+
161
+ ### Memory Tools
162
+
163
+ | Tool | Purpose | Key Params |
164
+ |------|---------|------------|
165
+ | `list_memories` | List available memories | `topic` (optional filter, e.g. `"auth"`) |
166
+ | `read_memory` | Read a memory's contents | `memory_name` |
167
+ | `write_memory` | Create a new memory (markdown) | `memory_name`, `content`, `max_chars` (optional) |
168
+ | `edit_memory` | Update existing memory in-place | `memory_name`, `needle`, `repl`, `mode` (`literal` or `regex`), `allow_multiple_occurrences` |
169
+ | `rename_memory` | Rename or move a memory | `old_name`, `new_name` |
170
+ | `delete_memory` | Delete a memory (user permission required) | `memory_name` |
171
+
172
+ ### Memory Naming & Organization
173
+
174
+ Use `/` separators to create topic hierarchies:
175
+
176
+ ```
177
+ modules/frontend → .serena/memories/modules/frontend.md
178
+ auth/login/logic → .serena/memories/auth/login/logic.md
179
+ global/java/style_guide → shared across all projects
180
+ ```
181
+
182
+ - **Project memories**: Stored in `.serena/memories/` within the project
183
+ - **Global memories**: Use `global/` prefix — shared across all projects (only when explicitly instructed)
184
+ - **Topic filtering**: `list_memories(topic="auth")` returns only memories under that topic
185
+
186
+ ### When to Write Memories
187
+
188
+ Write memories to persist **non-obvious project knowledge** useful for future tasks:
189
+
190
+ - Architecture decisions and their rationale
191
+ - Integration patterns between modules
192
+ - Naming conventions and project-specific terminology
193
+ - Known gotchas, workarounds, and edge cases
194
+ - Configuration requirements that aren't self-documenting
195
+
196
+ **Do NOT write memories for**:
197
+ - Information already in code comments or docs
198
+ - Temporary task state or debugging notes
199
+ - Easily re-derivable facts (file paths, import lists)
200
+
201
+ ### Memory Workflow
202
+
203
+ ```
204
+ 1. list_memories → discover what exists (filter by topic if needed)
205
+ 2. read_memory → check if relevant memory already covers this
206
+ 3. write_memory → create new, OR edit_memory → update existing
207
+ 4. After implementation → update memories that reference changed code
208
+ ```
209
+
210
+ ### Best Practices
211
+
212
+ - **Check before writing**: Always `list_memories` then `read_memory` to avoid duplicates
213
+ - **Edit over rewrite**: Use `edit_memory` (literal or regex mode) for targeted updates instead of rewriting entire memories
214
+ - **Keep memories focused**: One topic per memory — split broad memories into topic-specific ones
215
+ - **Update after changes**: When code changes affect documented patterns, update the relevant memories
216
+ - **Meaningful names**: Use descriptive hierarchical names (`api/auth/jwt-flow` not `memory1`)
217
+ - **Review post-onboarding**: After Serena onboarding, review generated memories and refine them
218
+
219
+ ---