@codewizard-dt/bootstrap 2.11.2 → 2.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (76) hide show
  1. package/README.md +9 -9
  2. package/lib/README.md +1 -1
  3. package/lib/hooks/lib/serena.js +20 -6
  4. package/lib/prompts/migrate-wiki.md +2 -2
  5. package/lib/prompts/setup-strict-typechecks.md +18 -7
  6. package/lib/scripts/README.md +7 -7
  7. package/lib/scripts/bootstrap-serena.sh +8 -6
  8. package/lib/scripts/build-mcp-guide.sh +3 -3
  9. package/lib/scripts/install-mcps.sh +71 -28
  10. package/lib/scripts/lib.sh +34 -7
  11. package/lib/scripts/migrate-project.sh +9 -2
  12. package/lib/scripts/setup-deployment.sh +9 -0
  13. package/lib/scripts/sync-wiki-scaffold.sh +145 -24
  14. package/lib/scripts/templates/CLAUDE-wiki.md +6 -2
  15. package/lib/scripts/templates/guides/stubs/serena.md +7 -7
  16. package/lib/scripts/templates/wiki/conventions.md +2 -0
  17. package/lib/scripts/templates/wiki/index.md +6 -0
  18. package/lib/skills/bug-close/SKILL.md +1 -1
  19. package/lib/skills/bug-file/SKILL.md +2 -2
  20. package/lib/skills/bug-triage/SKILL.md +1 -1
  21. package/lib/skills/debug-logs/SKILL.md +2 -2
  22. package/lib/skills/decision-create/SKILL.md +1 -1
  23. package/lib/skills/decision-finalize/SKILL.md +1 -1
  24. package/lib/skills/decision-next/SKILL.md +1 -1
  25. package/lib/skills/decision-walkthrough/SKILL.md +1 -1
  26. package/lib/skills/demo/SKILL.md +1 -1
  27. package/lib/skills/eval-create/SKILL.md +7 -3
  28. package/lib/skills/eval-gap/SKILL.md +6 -2
  29. package/lib/skills/eval-run/SKILL.md +1 -1
  30. package/lib/skills/extract-feature/SKILL.md +1 -1
  31. package/lib/skills/gap-assess/SKILL.md +1 -1
  32. package/lib/skills/git-commit/SKILL.md +1 -1
  33. package/lib/skills/lint/SKILL.md +1 -1
  34. package/lib/skills/marp-slideshow/SKILL.md +1 -1
  35. package/lib/skills/mermaid-flowchart/SKILL.md +1 -1
  36. package/lib/skills/now/SKILL.md +1 -1
  37. package/lib/skills/port-feature/SKILL.md +1 -1
  38. package/lib/skills/power-mode/SKILL.md +1 -1
  39. package/lib/skills/primer/SKILL.md +2 -2
  40. package/lib/skills/project-readme/SKILL.md +1 -1
  41. package/lib/skills/req-create/SKILL.md +1 -1
  42. package/lib/skills/req-extract-decisions/SKILL.md +1 -1
  43. package/lib/skills/req-finalize/SKILL.md +1 -1
  44. package/lib/skills/req-retire/SKILL.md +2 -2
  45. package/lib/skills/req-update/SKILL.md +1 -1
  46. package/lib/skills/research/SKILL.md +1 -1
  47. package/lib/skills/roadmap-add/SKILL.md +2 -2
  48. package/lib/skills/roadmap-create/SKILL.md +3 -3
  49. package/lib/skills/roadmap-next/SKILL.md +1 -1
  50. package/lib/skills/serena-config/SKILL.md +1 -1
  51. package/lib/skills/simplify/SKILL.md +1 -1
  52. package/lib/skills/tackle/SKILL.md +3 -3
  53. package/lib/skills/task-add/SKILL.md +1 -1
  54. package/lib/skills/task-audit/SKILL.md +2 -2
  55. package/lib/skills/task-trash/SKILL.md +1 -1
  56. package/lib/skills/task-update/SKILL.md +2 -2
  57. package/lib/skills/uat-auto/SKILL.md +1 -1
  58. package/lib/skills/uat-auto-plus/SKILL.md +1 -1
  59. package/lib/skills/uat-generate/SKILL.md +1 -1
  60. package/lib/skills/uat-skip/SKILL.md +1 -1
  61. package/lib/skills/uat-walk/SKILL.md +1 -1
  62. package/lib/skills/uat-walk/UAT-CORE.md +1 -1
  63. package/lib/skills/update-docs/SKILL.md +2 -2
  64. package/lib/skills/wiki-ingest/SKILL.md +1 -1
  65. package/lib/skills/wiki-lint/SKILL.md +1 -1
  66. package/lib/skills/wiki-query/SKILL.md +1 -1
  67. package/package.json +1 -1
  68. package/raw/guides/type-checking-templates/README.md +7 -7
  69. package/raw/guides/type-checking-templates/eslint/eslint.config.ts +1 -1
  70. package/raw/research/mcp-add-scope-writes/index.md +46 -0
  71. package/raw/research/mcp-add-scope-writes/sources.md +38 -0
  72. package/raw/research/mcp-scope-conflict-handling/index.md +61 -0
  73. package/raw/research/mcp-scope-conflict-handling/sources.md +32 -0
  74. package/.github/workflows/build.yml +0 -88
  75. package/raw/guides/mcp-tools.md +0 -335
  76. package/raw/guides/task-spec.md +0 -79
@@ -1,88 +0,0 @@
1
- name: Build & Push
2
-
3
- on:
4
- # push:
5
- # branches: [main] # uncomment to enable automatic deploys on push
6
- workflow_dispatch:
7
-
8
- env:
9
- REGISTRY: ghcr.io
10
- OWNER: ${{ github.repository_owner }}
11
- IMAGE: ${{ github.event.repository.name }}
12
- FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
13
-
14
- jobs:
15
- build:
16
- # Skips automatically until a root-level Dockerfile exists, so this template
17
- # stays green on repos that don't build a container yet. When the build job
18
- # skips, the dependent deploy job skips too (neither fails).
19
- # NOTE: update the guard path if your Dockerfile lives elsewhere,
20
- # e.g. hashFiles('backend/Dockerfile.prod') for a multi-image repo.
21
- if: ${{ hashFiles('Dockerfile') != '' }}
22
- runs-on: ubuntu-latest
23
- permissions:
24
- contents: read
25
- packages: write
26
-
27
- steps:
28
- - uses: actions/checkout@v4
29
-
30
- - uses: docker/setup-buildx-action@v3
31
-
32
- - name: Get version
33
- id: version
34
- run: |
35
- if [ -f package.json ]; then
36
- echo "VERSION=$(node -p "require('./package.json').version")" >> $GITHUB_OUTPUT
37
- else
38
- echo "VERSION=${GITHUB_SHA::8}" >> $GITHUB_OUTPUT
39
- fi
40
-
41
- - uses: docker/login-action@v3
42
- with:
43
- registry: ${{ env.REGISTRY }}
44
- username: ${{ github.actor }}
45
- password: ${{ secrets.GITHUB_TOKEN }}
46
-
47
- # TODO: Adjust context and dockerfile paths for your project.
48
- # For multi-image repos, convert this to a matrix strategy.
49
- - uses: docker/build-push-action@v6
50
- with:
51
- context: .
52
- file: ./Dockerfile
53
- push: true
54
- tags: |
55
- ${{ env.REGISTRY }}/${{ env.OWNER }}/${{ env.IMAGE }}:latest
56
- ${{ env.REGISTRY }}/${{ env.OWNER }}/${{ env.IMAGE }}:${{ steps.version.outputs.VERSION }}
57
- cache-from: type=gha
58
- cache-to: type=gha,mode=max
59
-
60
- deploy:
61
- needs: build
62
- # TODO: Configure your runner. Choose one:
63
- # Option A — Self-hosted runner on deploy server (see lib/scripts/setup-runner.sh):
64
- # runs-on: [self-hosted, <your-label>]
65
- # Option B — GitHub-hosted runner + SSH (add SSH_HOST, SSH_USER, SSH_KEY,
66
- # DEPLOY_PATH as repository secrets, then replace the deploy step below)
67
- runs-on: ubuntu-latest
68
- steps:
69
- # TODO: Replace with your deploy mechanism.
70
- # Option A (self-hosted runner already on deploy server):
71
- # - name: Pull and restart
72
- # run: |
73
- # cd /opt/your-app
74
- # docker compose pull
75
- # docker compose up -d --wait
76
- #
77
- # Option B (GitHub-hosted runner + SSH):
78
- # - uses: appleboy/ssh-action@v1
79
- # with:
80
- # host: ${{ secrets.SSH_HOST }}
81
- # username: ${{ secrets.SSH_USER }}
82
- # key: ${{ secrets.SSH_KEY }}
83
- # script: |
84
- # cd ${{ secrets.DEPLOY_PATH }}
85
- # docker compose pull
86
- # docker compose up -d --wait
87
- - name: Deploy
88
- run: echo "TODO: Configure deploy step — see comments above."
@@ -1,335 +0,0 @@
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 |
@@ -1,79 +0,0 @@
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
- ```