@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,162 @@
1
+ You are integrating a design system into a frontend application.
2
+
3
+ **Design system path**: `<DESIGN_SYSTEM_PATH>`
4
+ **App source path**: `<APP_SRC_PATH>`
5
+ **Routes/pages path**: `<APP_ROUTES_PATH>` (the directory Claude should watch for edits)
6
+ **Skill name**: `<SKILL_NAME>` (kebab-case, e.g. `my-brand-route-design`)
7
+
8
+ IMPORTANT: if any of these paths are not obvious, ask the user for clarification
9
+
10
+ ---
11
+
12
+ ## Phase 1 — Migrate assets and tokens
13
+
14
+ 1. Read the design system directory at `<DESIGN_SYSTEM_PATH>` to understand its structure
15
+ before doing anything else.
16
+ 2. Create `<APP_SRC_PATH>/design-system/` with subdirectories `assets/` and `components/`.
17
+ 3. Copy the CSS/token file (colors, typography, spacing, shadows, animation vars) into
18
+ `<APP_SRC_PATH>/design-system/design-system.css`. Preserve content exactly.
19
+ 4. Copy all static assets (icons, logos, fonts, videos) into
20
+ `<APP_SRC_PATH>/design-system/assets/`.
21
+ 5. Copy the original prototype/reference component files into
22
+ `<APP_SRC_PATH>/design-system/components/` **unmodified** — these are read-only reference.
23
+
24
+ ## Phase 2 — Wire tokens into the app entry point
25
+
26
+ 6. Read the app entry file (e.g. `main.tsx`, `main.ts`, `index.js`, `_app.tsx`).
27
+ 7. Add the design-system CSS import as the **first** import, before any other styles or app
28
+ imports.
29
+
30
+ ## Phase 3 — Convert prototype components to production TypeScript
31
+
32
+ For each prototype component in `<APP_SRC_PATH>/design-system/components/`:
33
+
34
+ 8. Read the prototype file before writing any production code.
35
+ 9. Produce a typed production equivalent in `<APP_SRC_PATH>/components/`. Rules:
36
+ - Use the target framework's idiomatic component model (typed props, no `any`).
37
+ - Drive all visual properties exclusively through CSS custom properties from
38
+ `design-system.css` — never hardcode color, spacing, or typography values.
39
+ - Keep components stateless/pure where possible; lift state to callers.
40
+ - Export each component as a named export from an `index` barrel file.
41
+
42
+ ## Phase 4 — Wire components into routes/pages
43
+
44
+ 10. For each route or page file in the app, read it before editing.
45
+ 11. Import and render the corresponding production component.
46
+ 12. Pass only the props the component declares; use mock/static data for any data that requires
47
+ a live backend (label it clearly as mock).
48
+
49
+ ## Phase 5 — Create the brand enforcement skill
50
+
51
+ 13. Read `<DESIGN_SYSTEM_PATH>/README.md` in full before writing the skill.
52
+ 14. Create `~/.claude/skills/<SKILL_NAME>/SKILL.md` with the following structure:
53
+
54
+ ```markdown
55
+ ---
56
+ name: <SKILL_NAME>
57
+ description: Enforce <brand> design guidelines when implementing or modifying frontend
58
+ routes. Reads design tokens, component patterns, and brand rules. Auto-triggered by PostToolUse
59
+ hook when route files are edited.
60
+ user-invocable: true
61
+ ---
62
+
63
+ You are implementing a <brand> frontend route. Before writing any UI code, read:
64
+
65
+ 1. `<APP_SRC_PATH>/design-system/design-system.css` — all CSS custom properties
66
+ 2. `<APP_SRC_PATH>/design-system/components/` — original prototype implementations for
67
+ reference
68
+ 3. `<DESIGN_SYSTEM_PATH>/README.md` — full brand rules, voice, iconography, animation spec
69
+
70
+ Key non-negotiables:
71
+ <EXTRACT THESE VERBATIM FROM THE DESIGN SYSTEM README — theme, color usage, typography
72
+ rules,
73
+ spacing rules, component patterns, interaction rules, copy voice, icon library, animation
74
+ easing,
75
+ confirmation requirements for destructive actions, anything explicitly prohibited>
76
+ ```
77
+
78
+ The "Key non-negotiables" section must be populated from the actual design system README,
79
+ not left as a placeholder.
80
+
81
+ ## Phase 6 — Create the PostToolUse hook and register it
82
+
83
+ 15. Create `~/.claude/hooks/` if it does not exist.
84
+ 16. Create `~/.claude/hooks/on-route-edit.sh` with this content:
85
+
86
+ ```bash
87
+ #!/bin/bash
88
+ # PostToolUse hook: fires after Edit or Write tool use.
89
+ # If the modified file is under <APP_ROUTES_PATH>, injects the brand skill
90
+ # into Claude's active context so design rules are always in scope.
91
+ set -euo pipefail
92
+
93
+ INPUT=$(cat)
94
+ FILE_PATH=$(echo "$INPUT" | python3 -c "
95
+ import sys, json
96
+ try:
97
+ d = json.load(sys.stdin)
98
+ print(d.get('file_path', d.get('path', '')))
99
+ except Exception:
100
+ print('')
101
+ " 2>/dev/null || echo "")
102
+
103
+ if echo "$FILE_PATH" | grep -q "<APP_ROUTES_PATH>"; then
104
+ ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
105
+ SKILL="$HOME/.claude/skills/<SKILL_NAME>/SKILL.md"
106
+ if [ -f "$SKILL" ]; then
107
+ echo ""
108
+ echo "=== <BRAND> DESIGN SYSTEM ==="
109
+ cat "$SKILL"
110
+ echo "=============================="
111
+ fi
112
+ fi
113
+ ```
114
+
115
+ 17. Make it executable: `chmod +x ~/.claude/hooks/on-route-edit.sh`
116
+ 18. Read `~/.claude/settings.json` if it exists; otherwise create it. Add the hook entry — do not
117
+ overwrite any existing hooks:
118
+
119
+ ```json
120
+ {
121
+ "hooks": {
122
+ "PostToolUse": [
123
+ {
124
+ "matcher": "Edit|Write",
125
+ "hooks": [
126
+ {
127
+ "type": "command",
128
+ "command": "bash ~/.claude/hooks/on-route-edit.sh"
129
+ }
130
+ ]
131
+ }
132
+ ]
133
+ }
134
+ }
135
+ ```
136
+
137
+ ## Phase 7 — Verify
138
+
139
+ 19. Run the framework's type checker (`tsc --noEmit`, `vue-tsc`, etc.) — must exit 0 with no
140
+ errors.
141
+ 20. Confirm `<APP_SRC_PATH>/design-system/design-system.css` exists and contains the expected
142
+ `:root` custom property blocks.
143
+ 21. Confirm `.claude/hooks/on-route-edit.sh` is executable (`ls -la` shows `-rwxr-xr-x`).
144
+ 22. Confirm `.claude/settings.json` contains the `PostToolUse` hook entry.
145
+ 23. Start the dev server and visually confirm each converted component renders without console
146
+ errors.
147
+
148
+ ---
149
+
150
+ ## Standing rules (always apply, no exceptions)
151
+
152
+ - Use CSS vars everywhere. No hardcoded hex, px, or font-family strings in component styles.
153
+ - Preserve the design system's theme — do not introduce a mode the prototype does not define.
154
+ - Every destructive or irreversible user action must show a confirmation step before the action
155
+ fires.
156
+ - Follow the icon library, stroke width, and size scale in the design system exactly — no
157
+ substitutions.
158
+ - Copy tone and casing follow the design system's voice guidelines exactly.
159
+
160
+ The key addition: Phase 5 requires reading the design system README before writing the skill,
161
+ and explicitly filling in the non-negotiables from it rather than leaving them as a
162
+ placeholder. That makes the skill self-documenting and accurate to the actual brand.
@@ -0,0 +1,139 @@
1
+ # Set up strict type checking for this project.
2
+
3
+ ## Phase 1 — Assess languages
4
+
5
+ Scan the repo and identify every language that has a type-checking or linting tool (e.g. TypeScript, Python, Go, Rust, Java). For each
6
+ one, note:
7
+ - Which files / directories contain that language
8
+ - What config files already exist (tsconfig, pyproject.toml, mypy.ini, .eslintrc, etc.)
9
+ - What package manager / toolchain is in use
10
+
11
+ ## Phase 2 — Research best practices (per language)
12
+
13
+ For each language found, use Context7 (for library docs) or Brave Search (for general practices, up to 50 req/sec, parallel OK) to look up the
14
+ current strict-mode recommendations:
15
+ - TypeScript: tsconfig strict, tseslint strictTypeChecked, stylisticTypeChecked, parserOptions.project
16
+ - Python: mypy --strict, pyproject.toml [tool.mypy]
17
+ - Go: staticcheck, go vet
18
+ - Rust: #![deny(warnings)], Clippy --deny warnings
19
+ - …and so on for any other language present
20
+
21
+ Research what the strict flags actually enable, what the known gotchas are (e.g. type-aware ESLint rules requiring parserOptions.project;
22
+ mypy needing ignore_missing_imports for third-party stubs), and what companion tools are idiomatic (e.g. ESLint for TypeScript,
23
+ mypy/pyright for Python).
24
+
25
+ ## Phase 3 — Install toolchain packages
26
+
27
+ Before touching any config file, ensure every required tool is actually installed in the project root. Do not just add entries to a
28
+ dependency file and stop — run the install command so the binaries are present and `make typecheck` can execute.
29
+
30
+ **TypeScript projects**
31
+ - Detect package manager: look for `pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, otherwise npm.
32
+ - Install (example for pnpm; adjust for the detected manager):
33
+ ```
34
+ pnpm add -D typescript eslint @eslint/js typescript-eslint
35
+ ```
36
+ If the project uses a framework-specific ESLint plugin (e.g. `eslint-plugin-react`, `@next/eslint-plugin-next`,
37
+ `eslint-plugin-vue`) install that too.
38
+ - Create `eslint.config.mjs` (flat config) at the project root if it does not exist. Use `typescript-eslint`'s
39
+ `strictTypeChecked` + `stylisticTypeChecked` presets and set `parserOptions.projectService: true` so type-aware rules work.
40
+ - Create or update `tsconfig.json` at the project root with `"strict": true` and a `"include"` that covers all source directories.
41
+ If a framework tsconfig already exists, extend it and layer strict on top rather than replacing it.
42
+
43
+ **Python projects**
44
+ - Detect toolchain: look for `pyproject.toml` → use `uv` (preferred) or `pip`; look for `requirements*.txt` → use pip.
45
+ - Install:
46
+ ```
47
+ uv add --dev ruff mypy # or: pip install ruff mypy
48
+ ```
49
+ - Create `ruff.toml` (or `[tool.ruff]` in `pyproject.toml`) at the project root with `line-length`, `select = ["ALL"]`, and a
50
+ reasonable `ignore` list (at minimum: `D`, `ANN`, `S101` unless tests are excluded by path).
51
+ - Create `[tool.mypy]` in `pyproject.toml` (or `mypy.ini`) with `strict = true` and `ignore_missing_imports = true` for any
52
+ third-party packages that lack stubs.
53
+
54
+ **Go projects**
55
+ - Install staticcheck: `go install honnef.co/go/tools/cmd/staticcheck@latest`
56
+ - No config file needed; use `go vet ./...` + `staticcheck ./...` in the Makefile target.
57
+
58
+ **Rust projects**
59
+ - No install needed; Clippy ships with rustup.
60
+ - Add a `clippy.toml` at the project root only if project-wide lint levels need tuning.
61
+
62
+ **Other languages**: follow the same pattern — install first, then write config.
63
+
64
+ After installing, verify the binaries resolve from the project root before proceeding:
65
+ - TypeScript: `npx tsc --version` and `npx eslint --version`
66
+ - Python: `ruff --version` and `mypy --version`
67
+ - Go: `staticcheck --version`
68
+
69
+ ## Phase 4 — Configure
70
+
71
+ For each language, finalize the config files written in Phase 3 to enable strict mode (flags, rules, paths). Do **not** run the type
72
+ checker and do **not** attempt to fix any errors — this phase is setup only.
73
+
74
+ ## Phase 5 — Makefile
75
+
76
+ Create (or update) a root-level Makefile with:
77
+ make typecheck # runs all language checks in sequence
78
+ make typecheck-<lang> # per-language target
79
+
80
+ Each per-language target must:
81
+ - Run any required code-generation step first (e.g. tsr generate for TanStack Router before tsc -b)
82
+ - Run the type checker
83
+ - Run the linter if one exists for that language
84
+ - Exit non-zero on any error
85
+
86
+ If a language directory is empty (no source files yet), the target must skip gracefully rather than fail.
87
+
88
+ ## Phase 6 — Skill
89
+
90
+ Write ~/.claude/skills/typecheck/SKILL.md with this exact content (do not alter the structure):
91
+
92
+ ```
93
+ ---
94
+ name: typecheck
95
+ description: Run typecheck, fix the first error, repeat until clean
96
+ model: claude-sonnet-4-6
97
+ disable-model-invocation: false
98
+ user-invocable: true
99
+ ---
100
+
101
+ # Run typecheck and fix issues
102
+
103
+ IMPORTANT: Adhere to all rules in `.docs/guides/mcp-tools.md` if it exists.
104
+
105
+ ## Step 1: find the problem
106
+
107
+ Run `make typecheck 2>&1 | head -20`
108
+
109
+ If there are no errors, this task is done.
110
+
111
+ ## Step 2: assess the problem
112
+
113
+ - Analyze the output for only the **first** error reported
114
+ - Use Serena to read the relevant code symbols where the error occurs
115
+ - Understand the root cause: type annotation issue, import problem, or genuine type mismatch?
116
+ - Use Context7 or Brave Search if you need more detail on the error
117
+
118
+ ## Step 3: fix the root cause
119
+
120
+ - Fix the root cause of the first error using Serena's symbolic editing tools
121
+ - Re-run `make typecheck 2>&1 | head -20` to verify the fix
122
+
123
+ ## Step 4: repeat, one error at a time
124
+
125
+ - Repeat steps 1–3 until the output is empty
126
+ - Do not keep a to-do list of separate errors — just run the command again to get the next one
127
+ ```
128
+
129
+ ## Phase 7 — Report
130
+
131
+ Do **not** run `make typecheck`. Report to the user:
132
+
133
+ - Which languages were configured and what strict flags were enabled for each
134
+ - Which config files were created or updated
135
+ - Which packages were installed
136
+ - How to run type checking: `make typecheck` (all languages) or `make typecheck-<lang>` (per language)
137
+ - How to start fixing errors interactively: run `/typecheck`
138
+
139
+ **Type-checking is now set up and ready to use.**
@@ -0,0 +1,49 @@
1
+ # scripts/
2
+
3
+ Bash orchestration layer. These are the only scripts `bin/cli.js` ever executes directly; everything else in `lib/` (hooks, prompts, skills, templates) gets copied, synced, or read by one of these.
4
+
5
+ All scripts use `set -euo pipefail`. Every script that touches a target project sources `lib.sh` for shared helpers and takes the project path as `$1`.
6
+
7
+ ## CLI-facing scripts (one per `bootstrap` command)
8
+
9
+ | Script | `bootstrap` command | What it does |
10
+ |--------|---------------------|---------------|
11
+ | `setup-project.sh` | `setup` | Preflight-checks `claude` and `uv` are installed, then runs the full new-project sequence: MCP install (interactive), global skills/hooks install, wiki scaffold sync, `.gitignore` merge, and Serena `project.yml` bootstrap. Does **not** scaffold deployment — that's explicit via `deploy`. |
12
+ | `update-project.sh` | `update` | Re-installs global skills/hooks and re-syncs the wiki scaffold + `.docs/guides/` into an existing project. Detects legacy `.docs/`-layout families (`tasks`, `uat`, `adr`, `prd`, `bugs`, `roadmaps`) and warns without touching them — migration is a separate, explicit step (`migrate`). Never touches `.github/`. |
13
+ | `install-global.sh` | `install` | Installs/updates MCPs, hooks, and skills globally with **no project path** — the shared step both `setup` and `update` delegate to. Also prunes stale skill folders left over from the wiki rename (`adr-*` → `decision-*`, `prd-*` → `req-*`). Accepts `--skip-mcps` when the caller already handled MCP install interactively. |
14
+ | `setup-deployment.sh` | `deploy` / `deployment` | Reads `raw/guides/deployment-strategy.md` as a prompt template and runs `claude` to scaffold `.github/workflows/`, `Makefile` Docker targets, and `.gitleaks.toml` into the target project. Deliberately **not** called by `setup`/`update` — CI files get hand-customized per project (Dockerfile paths, runner labels, deploy steps) and must never be created or clobbered implicitly. `security.yml` is always overwritten (generic); `build.yml`/`.gitleaks.toml` are copy-once; `Makefile` targets are merged. |
15
+ | `migrate-project.sh` | `migrate` | Claude-driven migration of a legacy `.docs/`-layout project to the LLM Wiki structure (`wiki/knowledge/` + `wiki/work/`). Preflight requires a clean git tree; runs on a fresh `wiki-migration` branch so the whole migration is one reviewable diff. Scaffolds first via `sync-wiki-scaffold.sh`, then drives the semantic conversion (frontmatter synthesis, ID renames, link rewrites, family indexes) with the prompt at `lib/prompts/migrate-wiki.md`. `git mv` before edit, so history is preserved. `--dry-run` prints the file inventory only and does not touch anything. |
16
+ | `setup-strict-typechecks.sh` | `typechecks` | Loads `lib/prompts/setup-strict-typechecks.md`, appends an optional language list (space- or comma-separated), and runs `claude` to detect languages, research current strict-mode conventions, install toolchains, and wire `make typecheck`. |
17
+ | `wiki-dashboard-server.js` | `dashboard` | Zero-dependency Node static file server (Node builtins only) that serves the live wiki dashboard client (`templates/wiki/dashboard.html`) at `/` and the project's `wiki/` tree read-only under `/wiki/*`, all with `no-store` cache headers so the polling client always sees current content. Runs in the foreground until Ctrl-C. Binds `http://localhost:4317` by default; pass a port to override (`bootstrap dashboard 4400`), and falls back to the next port (up to 10 tries) if the chosen one is in use. Unlike the other CLI scripts, this is Node, not Bash, and is long-running rather than one-shot. |
18
+
19
+ ## Shared helpers and internal scripts
20
+
21
+ | Script | Used by | Purpose |
22
+ |--------|---------|---------|
23
+ | `lib.sh` | Every script above | Shared bash library: `resolve_project_dir` (path resolution + validation), `mcp_installed`/`serena_installed`/`detect_installed_mcps` (MCP state checks), `run_project_sync` (the common setup/update sequence: MCPs → skills/hooks → wiki scaffold → gitignore → Serena), and `prompt_yn`/`prompt_scope` (interactive prompt helpers). |
24
+ | `install-mcps.sh` | `install-global.sh`, `setup-project.sh`, `update-project.sh` | Installs Brave Search, Context7, Playwright, and (when a project dir is given) Serena. Two modes: non-interactive (`install-global.sh`'s default — installs everything missing at user scope) and `--interactive --project-dir <dir>` (prompts per-MCP and asks for scope, used by `setup`/`update`). |
25
+ | `sync-wiki-scaffold.sh` | `setup-project.sh`, `update-project.sh`, `migrate-project.sh` | Scaffolds an **empty** wiki into the target project from `templates/wiki/`: creates `raw/` + all `wiki/` family directories, lifecycle docs, per-family `index.md`, and stub `index.md`/`log.md`. Copy-once for project-owned files; always-refreshes `conventions.md` and `lifecycle.md`. Also delivers the `## LLM Wiki` section and `.env` safety policy into the target's `CLAUDE.md` (copy-once, sentinel-guarded, from `templates/CLAUDE-wiki.md` / `templates/CLAUDE-env-safety.md`). |
26
+ | `build-mcp-guide.sh` | `setup-project.sh`, `update-project.sh` | Assembles `.docs/guides/mcp-tools.md` in the target project from the per-server stub files in `templates/guides/stubs/`, including only the sections for MCPs actually installed. |
27
+ | `bootstrap-serena.sh` | `setup-project.sh`, `update-project.sh` | Headlessly triggers `.serena/project.yml` creation via `claude --print` and enables the optional Serena tools needed by this template's workflow. Preflights `claude` and `python3`. |
28
+ | `merge-gitignore.sh` | `setup-project.sh`, `update-project.sh` | Copies the packaged `.gitignore` template into the target project if none exists; otherwise merges in only the missing lines, leaving the project's existing `.gitignore` content untouched. |
29
+
30
+ ## Standalone infra scripts (not wired to the CLI)
31
+
32
+ These are **not** referenced by `bin/cli.js` or by any other script — they're invoked manually when standing up self-hosted CI infrastructure for a project that used `deploy`.
33
+
34
+ | Script | Purpose |
35
+ |--------|---------|
36
+ | `setup-runner.sh` | Generalized GitHub Actions self-hosted runner installer. Run as root on a target droplet: `RUNNER_TOKEN=<token> REPO_URL=<url> bash setup-runner.sh`. Registers the runner, installs it as a service, and configures GHCR login. |
37
+ | `startup.sh` | One-shot droplet bootstrap: updates apt, installs zsh/curl/make, and installs Docker + the Compose plugin from Docker's official apt repo. Typically run once before `setup-runner.sh` on a fresh VM. |
38
+
39
+ ## `templates/`
40
+
41
+ Static and semi-static assets copied or read by the scripts above — never executed themselves.
42
+
43
+ | Path | Read/copied by | Contents |
44
+ |------|-----------------|----------|
45
+ | `templates/wiki/` | `sync-wiki-scaffold.sh` | The empty wiki scaffold: `index.md`, `log.md`, `conventions.md`, and per-family `knowledge/`/`work/{tasks,uat,bugs,requirements,decisions,roadmaps}/` directories with `lifecycle.md`, `index.md`, `archive/index.md`, and `.gitkeep` placeholders. |
46
+ | `templates/guides/stubs/` | `build-mcp-guide.sh` | Per-MCP-server markdown fragments (`serena.md`, `context7.md`, `brave-search.md`, `playwright.md`) plus `00-header.md` (the shared top-of-file rules), assembled into `.docs/guides/mcp-tools.md`. |
47
+ | `templates/CLAUDE-wiki.md` | `sync-wiki-scaffold.sh` | The `## LLM Wiki` schema section delivered into a target project's `CLAUDE.md` (copy-once, sentinel-guarded). |
48
+ | `templates/CLAUDE-env-safety.md` | `sync-wiki-scaffold.sh` | The `.env` read/write safety policy prepended to a target project's `CLAUDE.md` (copy-once, never duplicated). |
49
+ | `templates/gitignore` | `merge-gitignore.sh` | Packed copy of this repo's own `.gitignore` (dotfiles aren't included in npm packages, so it's shipped under a non-dot name and renamed on copy). |
@@ -0,0 +1,145 @@
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
+
7
+ if [ $# -ne 1 ]; then
8
+ echo "Usage: $0 <path-to-project>"
9
+ exit 1
10
+ fi
11
+
12
+ PROJECT_DIR="$(resolve_project_dir "$1")" || exit 1
13
+
14
+ # Preflight checks
15
+ if ! command -v claude &>/dev/null; then
16
+ echo "Error: 'claude' (Claude Code) is not installed."
17
+ echo "Install it with: npm install -g @anthropic-ai/claude-code"
18
+ exit 1
19
+ fi
20
+
21
+ if ! command -v python3 &>/dev/null; then
22
+ echo "Error: 'python3' is not installed."
23
+ exit 1
24
+ fi
25
+
26
+ echo "Bootstrapping Serena for: $PROJECT_DIR"
27
+
28
+ cd "$PROJECT_DIR"
29
+
30
+ if [ ! -f ".serena/project.yml" ]; then
31
+ echo "Triggering Claude Code to initialize Serena (.serena/ will be created)..."
32
+ claude --print "exit" >/dev/null 2>&1 || true
33
+ if [ ! -f ".serena/project.yml" ]; then
34
+ echo "Error: .serena/project.yml was not created by 'claude --print'. Ensure Serena MCP is registered for this project (run setup-project.sh first)."
35
+ exit 1
36
+ fi
37
+ else
38
+ echo ".serena/project.yml already exists, skipping claude --print step."
39
+ fi
40
+
41
+ PROJECT_YML="$PROJECT_DIR/.serena/project.yml"
42
+ REPLACED=$(python3 - "$PROJECT_YML" <<'PY'
43
+ import sys, pathlib
44
+ p = pathlib.Path(sys.argv[1])
45
+ text = p.read_text()
46
+ needle = "included_optional_tools: []"
47
+ repl = (
48
+ "included_optional_tools:\n"
49
+ " - list_dir\n"
50
+ " - find_file\n"
51
+ " - find_symbol\n"
52
+ " - find_referencing_symbols\n"
53
+ " - search_for_pattern\n"
54
+ " - replace_content\n"
55
+ " - replace_lines\n"
56
+ " - insert_at_line\n"
57
+ " - insert_after_symbol\n"
58
+ " - insert_before_symbol\n"
59
+ " - delete_lines"
60
+ )
61
+ count = text.count(needle)
62
+ if count:
63
+ p.write_text(text.replace(needle, repl, 1))
64
+ print(count)
65
+ PY
66
+ )
67
+
68
+ if [ "$REPLACED" = "0" ]; then
69
+ echo "Serena optional tools already configured, skipping."
70
+ elif [ "$REPLACED" = "1" ]; then
71
+ echo "Added 11 optional tools."
72
+ else
73
+ echo "Warning: replaced $REPLACED occurrences of the marker (expected 1)"
74
+ fi
75
+
76
+ # Ensure required languages are listed (markdown, python, typescript, yaml)
77
+ LANG_RESULT=$(python3 - "$PROJECT_YML" <<'PY'
78
+ import sys, re, pathlib
79
+
80
+ REQUIRED = ['markdown', 'python', 'typescript', 'yaml']
81
+
82
+ p = pathlib.Path(sys.argv[1])
83
+ text = p.read_text()
84
+
85
+ # Match the languages: block including list items at ANY indentation (0-indent is valid YAML).
86
+ # The trailing alternative allows a final item with no trailing newline.
87
+ LANG_BLOCK = re.compile(
88
+ r'^(languages:[ \t]*\n)'
89
+ r'((?:[ \t]*-[ \t]+[^\n]+\n)*(?:[ \t]*-[ \t]+[^\n]+)?)',
90
+ re.MULTILINE
91
+ )
92
+
93
+ bm = LANG_BLOCK.search(text)
94
+ if bm:
95
+ existing = re.findall(r'^[ \t]*-[ \t]+(\S+)', bm.group(2), re.MULTILINE)
96
+ missing = [lang for lang in REQUIRED if lang not in existing]
97
+ # Detect items without leading whitespace (Serena occasionally generates these)
98
+ bad_indent = bool(re.search(r'^-', bm.group(2), re.MULTILINE))
99
+
100
+ if not missing and not bad_indent:
101
+ print('present')
102
+ sys.exit(0)
103
+
104
+ # Rewrite entire block: deduplicate, sort, enforce 2-space indent
105
+ all_langs = sorted(set(existing + missing))
106
+ new_block = bm.group(1) + ''.join(f' - {lang}\n' for lang in all_langs)
107
+ p.write_text(text[:bm.start()] + new_block + text[bm.end():])
108
+ print('added:' + ','.join(missing) if missing else 'present')
109
+ sys.exit(0)
110
+
111
+ # languages: [] inline form
112
+ m = re.search(r'^languages:[ \t]*\[\][ \t]*\n?', text, re.MULTILINE)
113
+ if m:
114
+ block = 'languages:\n' + ''.join(f' - {lang}\n' for lang in REQUIRED)
115
+ p.write_text(text[:m.start()] + block + text[m.end():])
116
+ print('added:' + ','.join(REQUIRED))
117
+ sys.exit(0)
118
+
119
+ # singular language: <value> — convert to list form and add required
120
+ m = re.search(r'^language:[ \t]*(\S+)[ \t]*\n?', text, re.MULTILINE)
121
+ if m:
122
+ all_langs = sorted(set([m.group(1)] + REQUIRED))
123
+ block = 'languages:\n' + ''.join(f' - {lang}\n' for lang in all_langs)
124
+ p.write_text(text[:m.start()] + block + text[m.end():])
125
+ added = [lang for lang in REQUIRED if lang != m.group(1)]
126
+ print('added:' + ','.join(added) if added else 'present')
127
+ sys.exit(0)
128
+
129
+ print('no_key')
130
+ PY
131
+ )
132
+
133
+ if [ "$LANG_RESULT" = "present" ]; then
134
+ echo "Serena required languages already configured (markdown, python, typescript, yaml), skipping."
135
+ elif [[ "$LANG_RESULT" == added:* ]]; then
136
+ echo "Added languages to Serena config: ${LANG_RESULT#added:}"
137
+ # Restart any running Serena process so it picks up the change
138
+ if pkill -f "serena start-mcp-server" 2>/dev/null; then
139
+ echo "Restarted Serena (language config changed)."
140
+ else
141
+ echo "Serena not running — updated config will apply on next start."
142
+ fi
143
+ else
144
+ echo "Warning: could not find 'languages:' key in .serena/project.yml — add markdown, python, typescript, yaml manually."
145
+ fi
@@ -0,0 +1,108 @@
1
+ #!/usr/bin/env bash
2
+ set -euo pipefail
3
+
4
+ # build-mcp-guide.sh <project-dir> [mcp-name...]
5
+ #
6
+ # Assembles .docs/guides/mcp-tools.md in the target project from per-server stubs.
7
+ # Only sections for the listed MCP names are included.
8
+ #
9
+ # Valid MCP names: serena context7 brave-search playwright
10
+ #
11
+ # Example:
12
+ # build-mcp-guide.sh /path/to/project serena context7
13
+
14
+ SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
15
+ STUBS_DIR="$SCRIPT_DIR/templates/guides/stubs"
16
+
17
+ if [ $# -lt 1 ]; then
18
+ echo "Usage: $0 <project-dir> [mcp-name...]" >&2
19
+ exit 1
20
+ fi
21
+
22
+ PROJECT_DIR="$1"; shift
23
+ INSTALLED_MCPS=("$@")
24
+
25
+ OUT="$PROJECT_DIR/.docs/guides/mcp-tools.md"
26
+
27
+ has_mcp() {
28
+ local name="$1"
29
+ for m in "${INSTALLED_MCPS[@]+"${INSTALLED_MCPS[@]}"}"; do
30
+ [ "$m" = "$name" ] && return 0
31
+ done
32
+ return 1
33
+ }
34
+
35
+ mkdir -p "$PROJECT_DIR/.docs/guides"
36
+
37
+ {
38
+ # 1. Always: title + TOP RULE
39
+ cat "$STUBS_DIR/00-header.md"
40
+ echo ""
41
+
42
+ # 2. MANDATORY table (only for installed MCPs)
43
+ if [ ${#INSTALLED_MCPS[@]} -gt 0 ]; then
44
+ cat <<'EOF'
45
+ ## MANDATORY: MCP Tool Requirements
46
+
47
+ These MCP servers are **REQUIRED** for all applicable operations. Using standard tools when an MCP tool exists is a violation of project rules.
48
+
49
+ | MCP Server | Mandatory For | Replaces |
50
+ |------------|--------------|----------|
51
+ EOF
52
+ if has_mcp "serena"; then
53
+ echo "| **Serena** | All **code** exploration and editing; **all** file/directory exploration and search (code, markdown, config, anything) | \`Read\`, \`Edit\`, \`Write\`, \`Grep\`, \`Glob\` (for code files); \`bash\` exploration commands (\`ls\`, \`cat\`, \`find\`, \`grep\`, \`sed\`, \`awk\`, \`head\`, \`tail\`, \`tree\`) for **any** file type |"
54
+ fi
55
+ if has_mcp "context7"; then
56
+ echo "| **Context7** | All library/framework documentation lookups | WebSearch, WebFetch (for library docs) |"
57
+ fi
58
+ if has_mcp "brave-search"; then
59
+ echo "| **Brave Search** | All general web research | WebSearch (for non-library topics) |"
60
+ fi
61
+ if has_mcp "playwright"; then
62
+ echo "| **Playwright** | Browser automation, screenshots, UI interaction | WebFetch (for rendered pages) |"
63
+ fi
64
+ echo ""
65
+ echo "---"
66
+ echo ""
67
+ fi
68
+
69
+ # 3. Per-server stubs (in canonical order)
70
+ if has_mcp "serena"; then cat "$STUBS_DIR/serena.md"; echo ""; fi
71
+ if has_mcp "context7"; then cat "$STUBS_DIR/context7.md"; echo ""; fi
72
+ if has_mcp "brave-search"; then cat "$STUBS_DIR/brave-search.md"; echo ""; fi
73
+ if has_mcp "playwright"; then cat "$STUBS_DIR/playwright.md"; echo ""; fi
74
+
75
+ # 4. Quick Reference table (always present; rows per installed MCP)
76
+ cat <<'EOF'
77
+ ## Quick Reference: Which Tool for What
78
+
79
+ | Task | MUST Use | NEVER Use |
80
+ |------|----------|-----------|
81
+ | Read markdown content | Standard `Read` | `cat`, `head`, `tail` |
82
+ | Edit markdown content | Standard `Edit` / `Write` | `sed`, `awk`, `echo >>` |
83
+ | Edit config files (JSON, YAML, .env) | Standard `Read`/`Edit`/`Write` | `sed` |
84
+ EOF
85
+ if has_mcp "serena"; then
86
+ cat <<'EOF'
87
+ | Explore code structure | Serena `get_symbols_overview` | `Read` on code files, `cat` |
88
+ | Find function/class | Serena `find_symbol` | `Grep` on code files, `bash grep` |
89
+ | Edit code | Serena symbolic or file/line tools | Standard `Edit` on code files, `sed` |
90
+ | Rename symbol | Serena `rename_symbol` | Manual find-and-replace |
91
+ | Search file contents | Serena `search_for_pattern` or `Grep` tool | `bash grep` / `rg` / `ag` |
92
+ | List a directory | Serena `list_dir` | `ls`, `tree`, `find -type d` |
93
+ | Find files by name | Serena `find_file` or `Glob` tool | `find -name`, `ls \| grep` |
94
+ EOF
95
+ fi
96
+ if has_mcp "context7"; then
97
+ echo "| Library docs | Context7 | \`WebSearch\` / \`WebFetch\` |"
98
+ fi
99
+ if has_mcp "brave-search"; then
100
+ echo "| General research | Brave Search (sequential, 1/sec) | Parallel searches |"
101
+ fi
102
+ if has_mcp "playwright"; then
103
+ echo "| Browser interaction | Playwright | \`WebFetch\` for rendered content |"
104
+ fi
105
+
106
+ } > "$OUT"
107
+
108
+ echo " mcp-tools.md assembled for: ${INSTALLED_MCPS[*]+"${INSTALLED_MCPS[*]}"} → $OUT"