@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.
- package/.github/workflows/build.yml +88 -0
- package/.github/workflows/security.yml +24 -0
- package/.gitleaks.toml +15 -0
- package/README.md +472 -0
- package/bin/cli.js +47 -0
- package/lib/README.md +27 -0
- package/lib/hooks/README.md +316 -0
- package/lib/hooks/env-file-guard.js +45 -0
- package/lib/hooks/git-protected-ops-block.js +77 -0
- package/lib/hooks/lib/serena-languages.js +158 -0
- package/lib/hooks/lib/serena.js +787 -0
- package/lib/hooks/mv-absolute-path-block.js +53 -0
- package/lib/hooks/serena-bash-grep-block.js +501 -0
- package/lib/hooks/serena-edit-guard.js +74 -0
- package/lib/hooks/serena-first-glob-guard.js +94 -0
- package/lib/hooks/serena-first-guard.js +74 -0
- package/lib/hooks/serena-first-read-guard.js +167 -0
- package/lib/hooks/serena-pre-delegation.js +117 -0
- package/lib/hooks/serena-session-reset.js +45 -0
- package/lib/hooks/serena-usage-tracker.js +186 -0
- package/lib/hooks/serena-write-guard.js +58 -0
- package/lib/prompts/README.md +16 -0
- package/lib/prompts/migrate-wiki.md +111 -0
- package/lib/prompts/setup-deployment.md +322 -0
- package/lib/prompts/setup-design-system.md +162 -0
- package/lib/prompts/setup-strict-typechecks.md +139 -0
- package/lib/scripts/README.md +49 -0
- package/lib/scripts/bootstrap-serena.sh +145 -0
- package/lib/scripts/build-mcp-guide.sh +108 -0
- package/lib/scripts/install-global.sh +78 -0
- package/lib/scripts/install-mcps.sh +131 -0
- package/lib/scripts/lib.sh +154 -0
- package/lib/scripts/merge-gitignore.sh +65 -0
- package/lib/scripts/migrate-project.sh +273 -0
- package/lib/scripts/setup-deployment.sh +104 -0
- package/lib/scripts/setup-project.sh +55 -0
- package/lib/scripts/setup-runner.sh +99 -0
- package/lib/scripts/setup-strict-typechecks.sh +29 -0
- package/lib/scripts/startup.sh +42 -0
- package/lib/scripts/sync-wiki-scaffold.sh +104 -0
- package/lib/scripts/templates/CLAUDE-env-safety.md +3 -0
- package/lib/scripts/templates/CLAUDE-wiki.md +60 -0
- package/lib/scripts/templates/gitignore +136 -0
- package/lib/scripts/templates/guides/stubs/00-header.md +15 -0
- package/lib/scripts/templates/guides/stubs/brave-search.md +20 -0
- package/lib/scripts/templates/guides/stubs/context7.md +26 -0
- package/lib/scripts/templates/guides/stubs/playwright.md +26 -0
- package/lib/scripts/templates/guides/stubs/serena.md +219 -0
- package/lib/scripts/templates/wiki/conventions.md +100 -0
- package/lib/scripts/templates/wiki/dashboard.html +1733 -0
- package/lib/scripts/templates/wiki/hot.md +21 -0
- package/lib/scripts/templates/wiki/index.md +46 -0
- package/lib/scripts/templates/wiki/knowledge/concepts/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/entities/components/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/entities/organisations/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/entities/people/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/entities/tools/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/sources/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/log.md +14 -0
- package/lib/scripts/templates/wiki/work/bugs/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/bugs/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/bugs/index.md +12 -0
- package/lib/scripts/templates/wiki/work/bugs/lifecycle.md +39 -0
- package/lib/scripts/templates/wiki/work/decisions/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/decisions/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/decisions/index.md +12 -0
- package/lib/scripts/templates/wiki/work/decisions/lifecycle.md +42 -0
- package/lib/scripts/templates/wiki/work/requirements/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/requirements/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/requirements/index.md +12 -0
- package/lib/scripts/templates/wiki/work/requirements/lifecycle.md +34 -0
- package/lib/scripts/templates/wiki/work/roadmaps/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/roadmaps/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/roadmaps/index.md +12 -0
- package/lib/scripts/templates/wiki/work/roadmaps/lifecycle.md +32 -0
- package/lib/scripts/templates/wiki/work/tasks/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/tasks/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/tasks/index.md +12 -0
- package/lib/scripts/templates/wiki/work/tasks/lifecycle.md +39 -0
- package/lib/scripts/templates/wiki/work/uat/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/uat/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/uat/index.md +12 -0
- package/lib/scripts/templates/wiki/work/uat/lifecycle.md +48 -0
- package/lib/scripts/templates/wiki/work/uat/screenshots/.gitkeep +0 -0
- package/lib/scripts/update-project.sh +75 -0
- package/lib/scripts/wiki-dashboard-server.js +146 -0
- package/lib/skills/README.md +146 -0
- package/lib/skills/anti-slop/SKILL.md +183 -0
- package/lib/skills/bug-close/SKILL.md +136 -0
- package/lib/skills/bug-file/SKILL.md +114 -0
- package/lib/skills/bug-triage/SKILL.md +140 -0
- package/lib/skills/company-align/SKILL.md +203 -0
- package/lib/skills/debug-logs/SKILL.md +129 -0
- package/lib/skills/decision-create/SKILL.md +220 -0
- package/lib/skills/decision-finalize/SKILL.md +181 -0
- package/lib/skills/decision-next/SKILL.md +129 -0
- package/lib/skills/decision-walkthrough/SKILL.md +169 -0
- package/lib/skills/demo/SKILL.md +183 -0
- package/lib/skills/elevator-pitch/SKILL.md +125 -0
- package/lib/skills/eval-create/SKILL.md +344 -0
- package/lib/skills/eval-gap/SKILL.md +150 -0
- package/lib/skills/eval-run/SKILL.md +214 -0
- package/lib/skills/extract-feature/SKILL.md +344 -0
- package/lib/skills/flashcard/SKILL.md +513 -0
- package/lib/skills/frontend-taste/SKILL.md +184 -0
- package/lib/skills/gap-assess/SKILL.md +97 -0
- package/lib/skills/git-commit/SKILL.md +164 -0
- package/lib/skills/lint/SKILL.md +99 -0
- package/lib/skills/marp-slideshow/SKILL.md +212 -0
- package/lib/skills/mermaid-flowchart/SKILL.md +194 -0
- package/lib/skills/now/SKILL.md +36 -0
- package/lib/skills/port-feature/SKILL.md +315 -0
- package/lib/skills/power-mode/SKILL.md +184 -0
- package/lib/skills/primer/SKILL.md +84 -0
- package/lib/skills/project-readme/SKILL.md +166 -0
- package/lib/skills/req-compile/SKILL.md +131 -0
- package/lib/skills/req-create/SKILL.md +124 -0
- package/lib/skills/req-extract-decisions/SKILL.md +241 -0
- package/lib/skills/req-finalize/SKILL.md +251 -0
- package/lib/skills/req-retire/SKILL.md +185 -0
- package/lib/skills/req-update/SKILL.md +265 -0
- package/lib/skills/research/SKILL.md +250 -0
- package/lib/skills/research-company/SKILL.md +345 -0
- package/lib/skills/roadmap-add/SKILL.md +238 -0
- package/lib/skills/roadmap-create/SKILL.md +223 -0
- package/lib/skills/roadmap-next/SKILL.md +132 -0
- package/lib/skills/security-audit/SKILL.md +246 -0
- package/lib/skills/serena-config/SKILL.md +92 -0
- package/lib/skills/simplify/SKILL.md +227 -0
- package/lib/skills/tackle/SKILL.md +156 -0
- package/lib/skills/task-add/SKILL.md +208 -0
- package/lib/skills/task-audit/SKILL.md +294 -0
- package/lib/skills/task-trash/SKILL.md +115 -0
- package/lib/skills/task-update/SKILL.md +136 -0
- package/lib/skills/uat-auto/SKILL.md +69 -0
- package/lib/skills/uat-auto-plus/SKILL.md +115 -0
- package/lib/skills/uat-generate/SKILL.md +289 -0
- package/lib/skills/uat-skip/SKILL.md +169 -0
- package/lib/skills/uat-walk/SKILL.md +164 -0
- package/lib/skills/uat-walk/UAT-CORE.md +140 -0
- package/lib/skills/update-docs/SKILL.md +75 -0
- package/lib/skills/wiki-archive/SKILL.md +96 -0
- package/lib/skills/wiki-ingest/SKILL.md +139 -0
- package/lib/skills/wiki-lint/SKILL.md +131 -0
- package/lib/skills/wiki-query/SKILL.md +71 -0
- package/lib/skills/wiki-rotate-log/SKILL.md +90 -0
- package/lib/skills/wiki-tidy/SKILL.md +107 -0
- package/package.json +32 -0
- package/raw/.gitkeep +0 -0
- package/raw/design-principles.md +65 -0
- package/raw/guides/command-anti-patterns.md +79 -0
- package/raw/guides/deployment-strategy.md +448 -0
- package/raw/guides/evals-framework.md +452 -0
- package/raw/guides/mcp-tools.md +335 -0
- package/raw/guides/task-spec.md +79 -0
- package/raw/guides/type-checking-templates/README.md +112 -0
- package/raw/guides/type-checking-templates/eslint/eslint.config.ts +105 -0
- package/raw/guides/type-checking-templates/python/mypy.ini +69 -0
- package/raw/guides/type-checking-templates/python/pyproject.toml +164 -0
- package/raw/guides/type-checking-templates/python/pyrightconfig.json +67 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.app.jsonc +45 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.lib.jsonc +44 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.node-esm.jsonc +40 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.node.jsonc +34 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.vite-root.json +8 -0
- package/raw/harness-notes.md +20 -0
- package/raw/house-style/components/Badge.tsx +16 -0
- package/raw/house-style/components/Button.tsx +32 -0
- package/raw/house-style/components/Card.tsx +26 -0
- package/raw/house-style/components/Chip.tsx +57 -0
- package/raw/house-style/components/IconButton.tsx +67 -0
- package/raw/house-style/components/Modal.tsx +18 -0
- package/raw/house-style/components/Stepper.tsx +141 -0
- package/raw/house-style/components/icons.tsx +128 -0
- package/raw/house-style/preview/src/index.css +46 -0
- package/raw/house-style/tokens/tailwind.preset.ts +49 -0
- package/raw/house-style/tokens/tokens.json +62 -0
- package/raw/llm-wiki-2.md +162 -0
- package/raw/llm-wiki.md +75 -0
- package/raw/research/dark-mode-theme/index.md +85 -0
- package/raw/research/dark-mode-theme/sources.md +49 -0
- package/raw/research/serena-mcp-disconnect/index.md +81 -0
- package/raw/research/serena-mcp-disconnect/sources.md +87 -0
- package/raw/research/wiki-tooling-improvements/index.md +126 -0
- package/raw/research/wiki-tooling-improvements/sources.md +73 -0
- 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"
|