@codewizard-dt/bootstrap 2.11.1 → 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.
- package/README.md +9 -9
- package/lib/README.md +1 -1
- package/lib/hooks/lib/serena.js +20 -6
- package/lib/prompts/migrate-wiki.md +2 -2
- package/lib/prompts/setup-strict-typechecks.md +18 -7
- package/lib/scripts/README.md +7 -7
- package/lib/scripts/bootstrap-serena.sh +30 -9
- package/lib/scripts/build-mcp-guide.sh +3 -3
- package/lib/scripts/install-mcps.sh +71 -28
- package/lib/scripts/lib.sh +34 -7
- package/lib/scripts/migrate-project.sh +9 -2
- package/lib/scripts/setup-deployment.sh +9 -0
- package/lib/scripts/sync-wiki-scaffold.sh +145 -24
- package/lib/scripts/templates/CLAUDE-wiki.md +6 -2
- package/lib/scripts/templates/guides/stubs/serena.md +7 -7
- package/lib/scripts/templates/wiki/conventions.md +2 -0
- package/lib/scripts/templates/wiki/index.md +6 -0
- package/lib/skills/bug-close/SKILL.md +1 -1
- package/lib/skills/bug-file/SKILL.md +2 -2
- package/lib/skills/bug-triage/SKILL.md +1 -1
- package/lib/skills/debug-logs/SKILL.md +2 -2
- package/lib/skills/decision-create/SKILL.md +1 -1
- package/lib/skills/decision-finalize/SKILL.md +1 -1
- package/lib/skills/decision-next/SKILL.md +1 -1
- package/lib/skills/decision-walkthrough/SKILL.md +1 -1
- package/lib/skills/demo/SKILL.md +1 -1
- package/lib/skills/eval-create/SKILL.md +7 -3
- package/lib/skills/eval-gap/SKILL.md +6 -2
- package/lib/skills/eval-run/SKILL.md +1 -1
- package/lib/skills/extract-feature/SKILL.md +1 -1
- package/lib/skills/gap-assess/SKILL.md +1 -1
- package/lib/skills/git-commit/SKILL.md +1 -1
- package/lib/skills/lint/SKILL.md +1 -1
- package/lib/skills/marp-slideshow/SKILL.md +1 -1
- package/lib/skills/mermaid-flowchart/SKILL.md +1 -1
- package/lib/skills/now/SKILL.md +1 -1
- package/lib/skills/port-feature/SKILL.md +1 -1
- package/lib/skills/power-mode/SKILL.md +1 -1
- package/lib/skills/primer/SKILL.md +2 -2
- package/lib/skills/project-readme/SKILL.md +1 -1
- package/lib/skills/req-create/SKILL.md +1 -1
- package/lib/skills/req-extract-decisions/SKILL.md +1 -1
- package/lib/skills/req-finalize/SKILL.md +1 -1
- package/lib/skills/req-retire/SKILL.md +2 -2
- package/lib/skills/req-update/SKILL.md +1 -1
- package/lib/skills/research/SKILL.md +1 -1
- package/lib/skills/roadmap-add/SKILL.md +2 -2
- package/lib/skills/roadmap-create/SKILL.md +3 -3
- package/lib/skills/roadmap-next/SKILL.md +1 -1
- package/lib/skills/serena-config/SKILL.md +1 -1
- package/lib/skills/simplify/SKILL.md +1 -1
- package/lib/skills/tackle/SKILL.md +3 -3
- package/lib/skills/task-add/SKILL.md +1 -1
- package/lib/skills/task-audit/SKILL.md +2 -2
- package/lib/skills/task-trash/SKILL.md +1 -1
- package/lib/skills/task-update/SKILL.md +2 -2
- package/lib/skills/uat-auto/SKILL.md +1 -1
- package/lib/skills/uat-auto-plus/SKILL.md +1 -1
- package/lib/skills/uat-generate/SKILL.md +1 -1
- package/lib/skills/uat-skip/SKILL.md +1 -1
- package/lib/skills/uat-walk/SKILL.md +1 -1
- package/lib/skills/uat-walk/UAT-CORE.md +1 -1
- package/lib/skills/update-docs/SKILL.md +2 -2
- package/lib/skills/wiki-ingest/SKILL.md +1 -1
- package/lib/skills/wiki-lint/SKILL.md +1 -1
- package/lib/skills/wiki-query/SKILL.md +1 -1
- package/package.json +1 -1
- package/raw/guides/type-checking-templates/README.md +7 -7
- package/raw/guides/type-checking-templates/eslint/eslint.config.ts +1 -1
- package/raw/research/mcp-add-scope-writes/index.md +46 -0
- package/raw/research/mcp-add-scope-writes/sources.md +38 -0
- package/raw/research/mcp-scope-conflict-handling/index.md +61 -0
- package/raw/research/mcp-scope-conflict-handling/sources.md +32 -0
- package/.github/workflows/build.yml +0 -88
- package/raw/guides/mcp-tools.md +0 -335
- 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."
|
package/raw/guides/mcp-tools.md
DELETED
|
@@ -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 |
|
package/raw/guides/task-spec.md
DELETED
|
@@ -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
|
-
```
|