@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,335 @@
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
+ ---
16
+
17
+ ## MANDATORY: MCP Tool Requirements
18
+
19
+ These MCP servers are **REQUIRED** for all applicable operations. Using standard tools when an MCP tool exists is a violation of project rules.
20
+
21
+ | MCP Server | Mandatory For | Replaces |
22
+ |------------|--------------|----------|
23
+ | **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 |
24
+ | **Context7** | All library/framework documentation lookups | WebSearch, WebFetch (for library docs) |
25
+ | **Brave Search** | All general web research | WebSearch (for non-library topics) |
26
+ | **Playwright** | Browser automation, screenshots, UI interaction | WebFetch (for rendered pages) |
27
+
28
+ ### Standard tools (`Read`, `Edit`, `Write`) are permitted for:
29
+
30
+ - **Markdown files** (`.md`) — content edits use standard tools (Serena's symbolic editor doesn't apply to prose)
31
+ - **Config files** — JSON, YAML, TOML, `.env`, `.gitignore`, `package.json`, etc.
32
+ - **Creating brand-new files** of any type
33
+ - **Binary files and images** (read only)
34
+
35
+ ### Standard tools are NEVER permitted for:
36
+
37
+ - **Code files** — TypeScript, JavaScript, Python, Go, Rust, etc. Always use Serena's symbolic or file/line tools.
38
+ - **File or directory exploration of any kind**, regardless of file type. This includes:
39
+ - Listing directories → use `mcp__serena__list_dir`, **never** `ls` / `tree` / `find -type d`
40
+ - Finding files by name → use `mcp__serena__find_file`, **never** `find -name` / `ls | grep`
41
+ - Searching file contents → use `mcp__serena__search_for_pattern` or the `Grep` tool, **never** `grep` / `rg` / `ag` invoked through `bash`
42
+ - Reading file contents for inspection → use `mcp__serena__get_symbols_overview` (code) or `Read` (markdown/config), **never** `cat` / `head` / `tail`
43
+ - Editing via shell → **never** `sed` / `awk` / `echo >>`
44
+
45
+ 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.
46
+
47
+ ### Common anti-patterns and their fixes
48
+
49
+ These are real mistakes AI agents make on this codebase. Do not repeat them.
50
+
51
+ #### ❌ Anti-pattern: `sed` to flip task-file checkboxes
52
+
53
+ ```bash
54
+ # WRONG — never do this
55
+ sed -i '' 's/- \[ \] Launch Puppeteer/- [x] Launch Puppeteer/; s/- \[ \] Navigate and screenshot/- [x] Navigate and screenshot/' .docs/tasks/051-ux-conversion-audit.md
56
+ ```
57
+
58
+ 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.
59
+
60
+ ✅ **Correct**: call the `Edit` tool once per checkbox (or use `replace_all: true` if every `- [ ]` in the file should become `- [x]`):
61
+
62
+ ```
63
+ Edit(file_path=".docs/tasks/051-ux-conversion-audit.md",
64
+ old_string="- [ ] Launch Puppeteer",
65
+ new_string="- [x] Launch Puppeteer")
66
+ Edit(file_path=".docs/tasks/051-ux-conversion-audit.md",
67
+ old_string="- [ ] Navigate and screenshot each marketing",
68
+ new_string="- [x] Navigate and screenshot each marketing")
69
+ # ...one Edit call per checkbox
70
+ ```
71
+
72
+ Yes, even if there are ten checkboxes. Ten `Edit` calls is correct. One `sed` is wrong.
73
+
74
+ #### ❌ Anti-pattern: `cat` to check what's in a file before editing
75
+
76
+ ```bash
77
+ # WRONG
78
+ cat .docs/tasks/051-ux-conversion-audit.md
79
+ ```
80
+
81
+ ✅ **Correct**: `Read` tool. Always.
82
+
83
+ #### ❌ Anti-pattern: `ls` to see what's in a directory
84
+
85
+ ```bash
86
+ # WRONG
87
+ ls .docs/uat/screenshots/
88
+ ```
89
+
90
+ ✅ **Correct**: `mcp__serena__list_dir(relative_path=".docs/uat/screenshots/")`
91
+
92
+ #### ❌ Anti-pattern: `grep -r` to find a string across files
93
+
94
+ ```bash
95
+ # WRONG
96
+ grep -r "pending-uat" .
97
+ ```
98
+
99
+ ✅ **Correct**: the `Grep` tool, or `mcp__serena__search_for_pattern`.
100
+
101
+ #### ❌ Anti-pattern: `echo "new content" >> file.md` to append to a file
102
+
103
+ ```bash
104
+ # WRONG
105
+ echo "## New Section" >> README.md
106
+ ```
107
+
108
+ ✅ **Correct**: `Read` the file first to see the current end, then `Edit` to append (or `Write` if creating fresh).
109
+
110
+ **See also**: [`command-anti-patterns.md`](./command-anti-patterns.md) — shell hygiene, scratch-dir rules, and the /tackle-vs-UAT verification split.
111
+
112
+ ---
113
+
114
+ ## Serena (Code Exploration & Editing)
115
+
116
+ Serena provides two editing approaches:
117
+ 1. **Symbolic** — LSP-powered, refactoring-safe (entire functions/classes)
118
+ 2. **File/line-based** — Precise line-range and regex edits (within functions)
119
+
120
+ ### Tools
121
+
122
+ **Exploration:**
123
+
124
+ | Tool | Purpose | Key Params |
125
+ |------|---------|------------|
126
+ | `get_symbols_overview` | File structure overview | `relative_path`, `depth` (0=top-level) |
127
+ | `find_symbol` | Find symbols by name | `name_path_pattern`, `include_body`, `depth`, `substring_matching` |
128
+ | `find_referencing_symbols` | Find all callers/references | `name_path`, `relative_path` (file, not dir) |
129
+ | `search_for_pattern` | Regex search across files | `substring_pattern`, `relative_path`, `paths_include_glob` |
130
+ | `list_dir` | List directory contents | `relative_path`, `recursive` |
131
+ | `find_file` | Find files by name/mask | `file_mask`, `relative_path` |
132
+
133
+ **Symbolic editing** (use when replacing entire symbols):
134
+
135
+ | Tool | Purpose | Key Params |
136
+ |------|---------|------------|
137
+ | `replace_symbol_body` | Replace function/class body | `name_path`, `relative_path`, `body` (includes signature, NOT docstring) |
138
+ | `insert_after_symbol` | Add code after a symbol | `name_path`, `relative_path`, `body` |
139
+ | `insert_before_symbol` | Add code before a symbol | `name_path`, `relative_path`, `body` |
140
+ | `rename_symbol` | Rename across codebase | `name_path`, `relative_path`, `new_name` |
141
+
142
+ **File/line editing** (use for precise edits within symbols):
143
+
144
+ | Tool | Purpose | Key Params |
145
+ |------|---------|------------|
146
+ | `replace_content` | Literal or regex replacement | `relative_path`, `mode` (literal/regex), `needle`, `repl` |
147
+ | `replace_lines` | Replace line range | `relative_path`, `start_line`, `end_line`, `content` (0-based) |
148
+ | `delete_lines` | Delete line range | `relative_path`, `start_line`, `end_line` (0-based) |
149
+ | `insert_at_line` | Insert at line number | `relative_path`, `line`, `content` (0-based) |
150
+
151
+ ### Name Path Patterns
152
+
153
+ - `"method"` — matches any symbol named "method"
154
+ - `"MyClass/method"` — matches method in MyClass (relative)
155
+ - `"/MyClass/method"` — exact match (absolute)
156
+ - `"MyClass/method[0]"` — specific overload
157
+
158
+ ### Workflow
159
+
160
+ ```
161
+ 1. get_symbols_overview → 2. find_symbol → 3. Edit → 4. find_referencing_symbols
162
+ ```
163
+
164
+ ### Choosing Edit Mode
165
+
166
+ | Scenario | Use |
167
+ |----------|-----|
168
+ | Replace entire function/method/class | Symbolic: `replace_symbol_body` |
169
+ | Add new method to class | Symbolic: `insert_after_symbol` |
170
+ | Rename across codebase | Symbolic: `rename_symbol` |
171
+ | Edit few lines within large function | File/line: `replace_content` or `replace_lines` |
172
+ | Regex-based replacement | File/line: `replace_content` with `mode="regex"` |
173
+ | Edit doesn't align with symbol boundaries | File/line: `replace_lines` |
174
+
175
+ ---
176
+
177
+ ## Context7 (Library Documentation)
178
+
179
+ Two-step workflow — resolve the library ID, then query docs.
180
+
181
+ ### Step 1: Resolve Library ID
182
+
183
+ ```python
184
+ mcp__context7__resolve-library-id(libraryName="sqlalchemy")
185
+ # Returns: "/sqlalchemy/sqlalchemy"
186
+ ```
187
+
188
+ Skip only if user provides an explicit `/org/project` ID.
189
+
190
+ ### Step 2: Query Documentation
191
+
192
+ ```python
193
+ mcp__context7__query-docs(
194
+ libraryId="/sqlalchemy/sqlalchemy",
195
+ query="async session management"
196
+ )
197
+ ```
198
+
199
+ If results are insufficient, refine the query with more specific terms.
200
+
201
+ ---
202
+
203
+ ## Brave Search (Web Research)
204
+
205
+ ### Rate Limit: 50 requests per second
206
+
207
+ - Up to 50 requests per second are supported — parallel searches are allowed
208
+ - On 429 errors, back off briefly and retry (max 3 times)
209
+
210
+ ### Usage
211
+
212
+ ```python
213
+ mcp__brave-search__brave_web_search(
214
+ query="FastAPI dependency injection best practices 2025",
215
+ count=10
216
+ )
217
+ ```
218
+
219
+ Use for general research, best practices, troubleshooting, news. Do NOT use for library documentation (use Context7).
220
+
221
+ ---
222
+
223
+ ## Playwright (Browser Automation)
224
+
225
+ ### Tools
226
+
227
+ | Tool | Purpose |
228
+ |------|---------|
229
+ | `browser_navigate` | Navigate to a URL |
230
+ | `browser_take_screenshot` | Screenshot current page |
231
+ | `browser_snapshot` | Get accessibility tree (use to get element `ref` IDs before clicking/typing) |
232
+ | `browser_click` | Click element by `ref` ID from snapshot |
233
+ | `browser_type` | Type into an input field by `ref` ID |
234
+ | `browser_evaluate` | Execute JavaScript in browser |
235
+ | `browser_select_option` | Select dropdown option by `ref` ID |
236
+ | `browser_hover` | Hover over element by `ref` ID |
237
+ | `browser_close` | Close the browser |
238
+
239
+ ### Workflow
240
+
241
+ 1. **No explicit launch step** — the browser starts automatically on the first tool call.
242
+ 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.
243
+ 3. Use `browser_take_screenshot` for visual verification after navigation or interaction.
244
+
245
+ Use for visual verification, form interaction, and browser-rendered content. Do NOT use for static content fetching or library docs.
246
+
247
+ ---
248
+
249
+ ## Onboarding & Memory
250
+
251
+ Always run onboarding check when starting work:
252
+
253
+ ```python
254
+ mcp__serena__check_onboarding_performed()
255
+ # If not performed:
256
+ mcp__serena__onboarding()
257
+ ```
258
+
259
+ ### Memory Tools
260
+
261
+ | Tool | Purpose | Key Params |
262
+ |------|---------|------------|
263
+ | `list_memories` | List available memories | `topic` (optional filter, e.g. `"auth"`) |
264
+ | `read_memory` | Read a memory's contents | `memory_name` |
265
+ | `write_memory` | Create a new memory (markdown) | `memory_name`, `content`, `max_chars` (optional) |
266
+ | `edit_memory` | Update existing memory in-place | `memory_name`, `needle`, `repl`, `mode` (`literal` or `regex`), `allow_multiple_occurrences` |
267
+ | `rename_memory` | Rename or move a memory | `old_name`, `new_name` |
268
+ | `delete_memory` | Delete a memory (user permission required) | `memory_name` |
269
+
270
+ ### Memory Naming & Organization
271
+
272
+ Use `/` separators to create topic hierarchies:
273
+
274
+ ```
275
+ modules/frontend → .serena/memories/modules/frontend.md
276
+ auth/login/logic → .serena/memories/auth/login/logic.md
277
+ global/java/style_guide → shared across all projects
278
+ ```
279
+
280
+ - **Project memories**: Stored in `.serena/memories/` within the project
281
+ - **Global memories**: Use `global/` prefix — shared across all projects (only when explicitly instructed)
282
+ - **Topic filtering**: `list_memories(topic="auth")` returns only memories under that topic
283
+
284
+ ### When to Write Memories
285
+
286
+ Write memories to persist **non-obvious project knowledge** useful for future tasks:
287
+
288
+ - Architecture decisions and their rationale
289
+ - Integration patterns between modules
290
+ - Naming conventions and project-specific terminology
291
+ - Known gotchas, workarounds, and edge cases
292
+ - Configuration requirements that aren't self-documenting
293
+
294
+ **Do NOT write memories for**:
295
+ - Information already in code comments or docs
296
+ - Temporary task state or debugging notes
297
+ - Easily re-derivable facts (file paths, import lists)
298
+
299
+ ### Memory Workflow
300
+
301
+ ```
302
+ 1. list_memories → discover what exists (filter by topic if needed)
303
+ 2. read_memory → check if relevant memory already covers this
304
+ 3. write_memory → create new, OR edit_memory → update existing
305
+ 4. After implementation → update memories that reference changed code
306
+ ```
307
+
308
+ ### Best Practices
309
+
310
+ - **Check before writing**: Always `list_memories` then `read_memory` to avoid duplicates
311
+ - **Edit over rewrite**: Use `edit_memory` (literal or regex mode) for targeted updates instead of rewriting entire memories
312
+ - **Keep memories focused**: One topic per memory — split broad memories into topic-specific ones
313
+ - **Update after changes**: When code changes affect documented patterns, update the relevant memories
314
+ - **Meaningful names**: Use descriptive hierarchical names (`api/auth/jwt-flow` not `memory1`)
315
+ - **Review post-onboarding**: After Serena onboarding, review generated memories and refine them
316
+
317
+ ---
318
+
319
+ ## Quick Reference: Which Tool for What
320
+
321
+ | Task | MUST Use | NEVER Use |
322
+ |------|----------|-----------|
323
+ | Explore code structure | Serena `get_symbols_overview` | `Read` on code files, `cat` |
324
+ | Find function/class | Serena `find_symbol` | `Grep` on code files, `bash grep` |
325
+ | Edit code | Serena symbolic or file/line tools | Standard `Edit` on code files, `sed` |
326
+ | Rename symbol | Serena `rename_symbol` | Manual find-and-replace |
327
+ | Search file contents | Serena `search_for_pattern` or `Grep` tool | `bash grep` / `rg` / `ag` |
328
+ | List a directory | Serena `list_dir` | `ls`, `tree`, `find -type d` |
329
+ | Find files by name | Serena `find_file` or `Glob` tool | `find -name`, `ls \| grep` |
330
+ | Read markdown content | Standard `Read` | `cat`, `head`, `tail` |
331
+ | Edit markdown content | Standard `Edit` / `Write` | `sed`, `awk`, `echo >>` |
332
+ | Edit config files (JSON, YAML, .env) | Standard `Read`/`Edit`/`Write` | `sed`, Serena symbolic tools |
333
+ | Library docs | Context7 | `WebSearch` / `WebFetch` |
334
+ | General research | Brave Search (up to 50 req/sec, parallel OK) | WebSearch |
335
+ | Browser interaction | Playwright | `WebFetch` for rendered content |
@@ -0,0 +1,79 @@
1
+ # Task File Specification
2
+
3
+ Task files in `.docs/tasks/` are structured outlines designed for execution by `/tackle`.
4
+
5
+ ## Naming Convention
6
+
7
+ ```
8
+ <NNN>-<short-description>.md
9
+ ```
10
+
11
+ - **NNN**: Zero-padded sequential integer (check `.docs/tasks/` and `completed/` to find the next number)
12
+ - **short-description**: Lowercase, hyphen-separated slug (2-4 words)
13
+
14
+ Examples: `001-basic-infrastructure.md`, `004-application-tracker.md`, `008-find-jobs.md`
15
+
16
+ ## Required Structure
17
+
18
+ ```markdown
19
+ # NNN — Task Title
20
+
21
+ ## Objective
22
+
23
+ One-sentence description of what this task accomplishes.
24
+
25
+ ## Approach
26
+
27
+ Brief summary of the technical approach or key decisions (1-3 sentences).
28
+
29
+ ## Prerequisites
30
+
31
+ - [ ] Any setup or dependencies that must exist before starting
32
+ - [ ] Reference other tasks by number: "Task 001 (Infrastructure) completed"
33
+
34
+ ---
35
+
36
+ ## Steps
37
+
38
+ ### 1. Section Name <!-- agent: general-purpose -->
39
+
40
+ - [ ] Step description with enough detail for an agent to implement
41
+ - [ ] Another step — include file paths, component names, or API routes when known
42
+ - Sub-detail or acceptance criteria (plain text indent, not a checkbox)
43
+
44
+ ### 2. Another Section <!-- agent: general-purpose -->
45
+
46
+ - [ ] More steps grouped by logical area
47
+
48
+ ### N. Verification <!-- agent: general-purpose -->
49
+
50
+ - [ ] Verify TypeScript compiles / tests pass / app runs
51
+ - [ ] Verify key user flows work end-to-end
52
+ ```
53
+
54
+ ## Rules
55
+
56
+ - Every actionable item uses `- [ ]` checkbox syntax
57
+ - Number step sections sequentially: `### 1.`, `### 2.`, etc.
58
+ - **Every step section MUST have an agent type annotation**: `<!-- agent: TYPE -->` on the `###` header line
59
+ - Valid types: `general-purpose`, `Explore`, `Plan`
60
+ - Group steps by logical area (e.g., "Schema Update", "API Routes", "UI Components")
61
+ - Steps should be specific enough for `/tackle` to execute without ambiguity — the task file IS the plan
62
+ - Include file paths, function names, or route patterns when known
63
+ - End with a verification section to confirm the work is complete
64
+ - Use `---` separator between Prerequisites and Steps
65
+ - Keep the objective to one sentence
66
+ - Keep the approach to 1-3 sentences
67
+
68
+ ## Lifecycle
69
+
70
+ ```
71
+ .docs/tasks/ → .docs/tasks/completed/
72
+ (/tackle + /uat-walk all pass)
73
+ ```
74
+
75
+ When a task reaches `completed/`, a UAT link is appended:
76
+ ```markdown
77
+ ---
78
+ **UAT**: [`.docs/uat/completed/NNN-slug.uat.md`](../uat/completed/NNN-slug.uat.md)
79
+ ```
@@ -0,0 +1,112 @@
1
+ # Type-Checking & Linting Config Templates
2
+
3
+ Best-practice templates synthesized from analysis of all configs across ~/Repositories. Each template includes inline annotations explaining every non-obvious decision.
4
+
5
+ ---
6
+
7
+ ## Templates
8
+
9
+ | File | When to use |
10
+ |------|-------------|
11
+ | `tsconfig/tsconfig.node-esm.jsonc` | Node.js service, CLI, or MCP server using native ESM |
12
+ | `tsconfig/tsconfig.vite-root.json` | Vite project root (solution coordinator — no compilation) |
13
+ | `tsconfig/tsconfig.app.jsonc` | Vite + React app (browser code) |
14
+ | `tsconfig/tsconfig.node.jsonc` | Vite config file compilation (`vite.config.ts`) |
15
+ | `tsconfig/tsconfig.lib.jsonc` | React/TS library that emits `.d.ts` for npm |
16
+ | `python/pyproject.toml` | Python project: mypy + basedpyright + ruff + pytest + coverage |
17
+ | `python/mypy.ini` | Standalone mypy config (use when `pyproject.toml` is owned by another tool) |
18
+ | `python/pyrightconfig.json` | Pyright / basedpyright standalone config |
19
+ | `eslint/eslint.config.ts` | ESLint flat config for React + TypeScript |
20
+
21
+ ---
22
+
23
+ ## Key Best Practices by Config Type
24
+
25
+ ### TypeScript (`tsconfig.json`)
26
+
27
+ **Module system — pick the right pair:**
28
+ | Project type | `module` | `moduleResolution` |
29
+ |---|---|---|
30
+ | Node.js native ESM | `NodeNext` | `NodeNext` |
31
+ | Vite / bundled app | `ESNext` | `bundler` |
32
+ | Next.js | `ESNext` | `bundler` |
33
+
34
+ Never mix `module: ESNext` with `moduleResolution: node` — they are semantically incompatible.
35
+
36
+ **Strictness — go beyond `strict: true`:**
37
+ ```jsonc
38
+ "strict": true, // enables 8 base flags
39
+ "noUncheckedIndexedAccess": true, // highest-value add-on; catches array/dict access bugs
40
+ "noImplicitReturns": true,
41
+ "noFallthroughCasesInSwitch": true,
42
+ "noImplicitOverride": true,
43
+ "noUnusedLocals": true,
44
+ "noUnusedParameters": true,
45
+ "verbatimModuleSyntax": true // TS 5.0+; prevents silent import bugs
46
+ ```
47
+
48
+ **Vite projects — always use the three-file split:**
49
+ - Root `tsconfig.json` — `"files": []` + `"references"` only (no compilation of its own)
50
+ - `tsconfig.app.json` — browser libs, `noEmit: true`, `moduleResolution: bundler`
51
+ - `tsconfig.node.json` — Node libs, `noEmit: true`, covers only `vite.config.ts`
52
+
53
+ **Anti-patterns observed in the wild:**
54
+ - `module: ESNext` + `moduleResolution: node` — broken module resolution
55
+ - `target: es5` in 2024+ projects — unnecessary transpilation overhead
56
+ - `jsx: "react"` in modern code — use `"react-jsx"` (React 17+ automatic transform)
57
+ - `allowJs: true` without `checkJs: true` — JS files silently bypass type checking
58
+ - Keeping the tsc-generated comment template — adds noise, hides real config
59
+
60
+ ---
61
+
62
+ ### Python type checking (`pyproject.toml` / `mypy.ini`)
63
+
64
+ **mypy:**
65
+ - Always use `strict = true` — never approximate it with manual flag enumeration
66
+ - Use `[[tool.mypy.overrides]]` per-module instead of global `ignore_missing_imports = true`
67
+ - Never use `ignore_errors = true` on a whole module — it silences real bugs; use `ignore_missing_imports = true` only
68
+ - Always set `files` or `exclude` to prevent crawling `.venv`, `dist`, etc.
69
+ - Enable `pydantic.mypy` plugin in any Pydantic project
70
+ - Enable `sqlalchemy.ext.mypy.plugin` if using SQLAlchemy ORM
71
+
72
+ **ruff (replaces flake8 / isort / black):**
73
+ Minimum rule set: `E, W, F, I, B, UP`
74
+ Recommended rule set: `E, W, F, I, N, UP, B, C4, SIM, RUF`
75
+ Add `C90` (mccabe) for complex control-flow codebases (agent loops, etc.)
76
+
77
+ **basedpyright companion pattern:**
78
+ Run basedpyright alongside mypy with `typeCheckingMode = "off"` — opt in only to rules mypy currently lacks (notably `reportTypedDictNotRequiredAccess` for mypy gap #9408). Prevents double-reporting.
79
+
80
+ **Anti-patterns observed in the wild:**
81
+ - `ignore_errors = true` on internal modules — silences real type errors, not just stub gaps
82
+ - `cryptwiz_py`: manually approximating strict mode without `strict = true`, leaving gaps
83
+ - Missing `[tool.ruff.lint.isort]` `known-first-party` — isort can't distinguish first-party vs third-party without it
84
+ - `sales-agent`: no pydantic.mypy plugin despite heavy Pydantic usage
85
+
86
+ ---
87
+
88
+ ### ESLint (flat config)
89
+
90
+ - Use `tseslint.configs.strictTypeChecked` + `parserOptions.projectService: true` for full type-aware linting
91
+ - Never downgrade errors to `"warn"` — either fix or disable with a comment
92
+ - Scope globals tightly: `globals.browser` only in browser files, `globals.node` only in Node/config files
93
+ - Use a separate config block for test files
94
+ - Eliminate `FlatCompat` — all major plugins now ship native flat config support
95
+ - Let the TypeScript parser handle `ecmaVersion`; do not hard-code it
96
+
97
+ **Anti-patterns observed in the wild:**
98
+ - `portfolio_v2`: missing `parserOptions.projectService` — all type-aware lint rules silently disabled
99
+ - `openemr`: `FlatCompat` bridge for jest — use `jest.configs['flat/recommended']` instead
100
+ - `openemr`: `no-undef`, `no-unused-vars`, `no-redeclare` set to `"warn"` — silent tech debt
101
+
102
+ ---
103
+
104
+ ### pyrightconfig.json
105
+
106
+ - Always set `typeCheckingMode` explicitly — the default is `"off"`, meaning no type checking
107
+ - `reportMissingImports` should always be `"error"`
108
+ - `"standard"` is a safe project-wide floor; use per-file suppressions for legacy code
109
+
110
+ **Anti-patterns observed in the wild:**
111
+ - Neither `openemr` nor `cryptwiz_py` set `typeCheckingMode` — Pyright defaulted to `"off"` and did nothing
112
+ - `reportMissingImports: "warning"` — broken imports should always be errors
@@ -0,0 +1,105 @@
1
+ // eslint.config.ts
2
+ // Use for: React + TypeScript projects using ESLint flat config (v9+)
3
+ // Key: uses `strictTypeChecked` + `parserOptions.projectService` for full type-aware linting.
4
+ // Replace plugin imports to match your actual installed packages.
5
+
6
+ import js from '@eslint/js'
7
+ import globals from 'globals'
8
+ import reactHooks from 'eslint-plugin-react-hooks'
9
+ import reactRefresh from 'eslint-plugin-react-refresh'
10
+ import tseslint from 'typescript-eslint'
11
+ import { defineConfig, globalIgnores } from 'eslint/config'
12
+ // If using vitest (native flat config, no FlatCompat needed):
13
+ // import vitest from 'eslint-plugin-vitest'
14
+ // If using jest (v29+ ships native flat config, no FlatCompat needed):
15
+ // import jest from 'eslint-plugin-jest'
16
+
17
+ export default defineConfig([
18
+ // --- Global ignores (replaces .eslintignore) ---
19
+ globalIgnores([
20
+ 'dist',
21
+ 'build',
22
+ 'coverage',
23
+ '.vite',
24
+ '**/*.gen.ts', // generated files
25
+ '**/*.d.ts', // declaration files
26
+ ]),
27
+
28
+ // --- Source files: TypeScript + React ---
29
+ {
30
+ files: ['src/**/*.{ts,tsx}'],
31
+ extends: [
32
+ js.configs.recommended,
33
+ // strictTypeChecked = recommended + strict + ALL type-aware lint rules.
34
+ // Requires parserOptions.projectService below — without it, type-aware
35
+ // rules are silently disabled. This was the primary gap in portfolio_v2.
36
+ tseslint.configs.strictTypeChecked,
37
+ // stylisticTypeChecked adds formatting-adjacent TS rules (optional)
38
+ tseslint.configs.stylisticTypeChecked,
39
+ reactHooks.configs['recommended-latest'],
40
+ reactRefresh.configs.vite,
41
+ ],
42
+ languageOptions: {
43
+ globals: globals.browser,
44
+ parserOptions: {
45
+ // projectService: true → auto-discovers tsconfig.json per file.
46
+ // More efficient than `project: ['./tsconfig.app.json']`.
47
+ // CRITICAL: without this, all type-aware rules are disabled.
48
+ projectService: true,
49
+ tsconfigRootDir: import.meta.dirname,
50
+ },
51
+ },
52
+ rules: {
53
+ // RULE: Never downgrade to "warn" — fix or disable with a comment.
54
+ // Warnings are silent tech debt that accumulate and never get fixed.
55
+
56
+ // Prefer type imports for better tree-shaking / circular dep safety
57
+ '@typescript-eslint/consistent-type-imports': [
58
+ 'error',
59
+ { prefer: 'type-imports', fixStyle: 'inline-type-imports' },
60
+ ],
61
+
62
+ // void-returning arrow callbacks are fine in event handlers
63
+ '@typescript-eslint/no-misused-promises': [
64
+ 'error',
65
+ { checksVoidReturn: { attributes: false } },
66
+ ],
67
+
68
+ // Allow `_` prefix to suppress unused variable lint
69
+ '@typescript-eslint/no-unused-vars': [
70
+ 'error',
71
+ { argsIgnorePattern: '^_', varsIgnorePattern: '^_' },
72
+ ],
73
+ },
74
+ },
75
+
76
+ // --- Test files (relaxed rules) ---
77
+ {
78
+ files: ['**/*.{spec,test}.{ts,tsx}', '**/__tests__/**/*.{ts,tsx}'],
79
+ // Uncomment whichever test framework you use:
80
+ // extends: [vitest.configs.recommended],
81
+ // extends: [jest.configs['flat/recommended']], // no FlatCompat needed in jest v29+
82
+ languageOptions: {
83
+ globals: {
84
+ ...globals.node, // process, __dirname, etc.
85
+ },
86
+ },
87
+ rules: {
88
+ // Test files legitimately use `any` for mocks and non-null assertions
89
+ '@typescript-eslint/no-explicit-any': 'off',
90
+ '@typescript-eslint/no-non-null-assertion': 'off',
91
+ },
92
+ },
93
+
94
+ // --- Node / config scripts ---
95
+ {
96
+ files: ['*.config.{js,ts,mjs,mts}', 'scripts/**/*.{js,ts}'],
97
+ languageOptions: {
98
+ globals: globals.node,
99
+ },
100
+ rules: {
101
+ // Config files often use require() or dynamic imports
102
+ '@typescript-eslint/no-require-imports': 'off',
103
+ },
104
+ },
105
+ ])