@codewizard-dt/bootstrap 2.11.2 → 2.14.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 +8 -8
- package/lib/scripts/bootstrap-serena.sh +8 -6
- package/lib/scripts/build-mcp-guide.sh +3 -3
- package/lib/scripts/install-mcps.sh +71 -28
- package/lib/scripts/lib.sh +35 -8
- package/lib/scripts/merge-gitignore.sh +102 -29
- 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
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
---
|
|
2
|
+
topic: Research the specific 'claude mcp add' lines in this repo (history + present) and the 'mcp add' scope API to determine why steno ended up with conflicting playwright scopes and why serena landed in the project's .mcp.json.
|
|
3
|
+
slug: mcp-add-scope-writes
|
|
4
|
+
researched: 2026-07-29
|
|
5
|
+
sources: [./sources.md]
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Research: This repo's `mcp add` lines vs the `mcp add` scope API — why steno broke
|
|
9
|
+
|
|
10
|
+
> Builds on [mcp-scope-conflict-handling](../mcp-scope-conflict-handling/index.md). Two distinct defects, neither caused by any change to the `claude mcp add` API (every script version passes `--scope` explicitly, so the CLI's `local` default never applied). **(1) Playwright:** steno's project-scoped stdio entry was pre-existing repository config (user attestation [S6]); the 2.11.0 upgrade path only knows how to replace user-scoped entries (`claude mcp remove -s user`), so it added the shared HTTP server on top → `[Conflicting scopes]`. **(2) Serena:** bootstrap registers serena with `--scope project`, which writes a machine-specific absolute path (`--project /Users/<user>/…`) into the repo's shared `.mcp.json` — the wrong scope. It belongs at **local scope** (`--scope local`), stored in `~/.claude.json` under the project's entry: still per-project (no serena language-config bleed, oraios/serena#895) but machine-local, and local-scope servers load headlessly without the `.mcp.json` approval gate.
|
|
11
|
+
|
|
12
|
+
## Research Questions
|
|
13
|
+
- Did a `claude mcp add` API change cause either problem?
|
|
14
|
+
- Where did steno's project-scoped playwright entry come from?
|
|
15
|
+
- Why did serena land in `.mcp.json`, and what scope should it use?
|
|
16
|
+
- Which current `mcp add` call sites can still write to a project's `.mcp.json`?
|
|
17
|
+
|
|
18
|
+
## Current State (Codebase)
|
|
19
|
+
`claude mcp add` call sites in `lib/scripts/install-mcps.sh` (working tree):
|
|
20
|
+
- **serena** — `claude mcp add --scope project serena -- uvx …` run in `$PROJECT_DIR` → writes `.mcp.json` with a machine-specific absolute path. **Defect: should be `--scope local`** [S1][S6].
|
|
21
|
+
- **brave-search** — `mcp_add_scoped user …` (hardcoded user; shared Docker container) [S1].
|
|
22
|
+
- **context7** — `mcp_add_scoped "$1" …` where `$1` comes from `prompt_scope` → a "p" answer writes `.mcp.json` (legitimate: URL-based, no machine-specific paths) [S1].
|
|
23
|
+
- **playwright** — Darwin: hardcoded user (shared HTTP); non-Darwin: scope-prompt honored (stdio) [S1].
|
|
24
|
+
- UX inconsistency: `register_optional_mcp` asks `prompt_scope` for every optional MCP, then brave (and playwright-on-macOS) silently ignore the answer [S1].
|
|
25
|
+
|
|
26
|
+
## Key Findings
|
|
27
|
+
- **No `mcp add` API change involved**: `-s/--scope` (local | user | project, default `local`) — all script versions pass it explicitly [S2][S3] *(that the default never changed is an inference — no primary source; irrelevant given explicit flags)*.
|
|
28
|
+
- **Scope storage semantics**: `project` scope → `.mcp.json` in the repo (shareable, requires per-user approval, wins over user scope); `local` scope → `~/.claude.json` under the project's entry (machine-local, per-project, no approval gate); precedence local > project > user, no field merging [S3][S5].
|
|
29
|
+
- **Playwright**: steno's `.mcp.json` entry (`npx @playwright/mcp@latest`) was pre-existing repo config [S6]. (Historical note: bootstrap 2.7.0–2.10.0 *could* produce identical entries via its scope prompt [S2], but that is not what happened here.) The 2.11.0-2.11.2 upgrade path removes only `-s user` before re-adding → duplicate registration [S4].
|
|
30
|
+
- **Serena**: the entry in steno's `.mcp.json` was written by bootstrap's own setup script (it was not pre-existing) [S6]. `--scope project` bakes `--project /Users/david/Repositories/steno` into a file that may be committed/team-shared — broken for every other machine that clones the repo, and it forces the `.mcp.json` approval gate that broke headless `bootstrap-serena.sh` yesterday. Local scope fixes all three: machine-local storage, valid absolute path, no approval prompt [S3][S5][S6].
|
|
31
|
+
|
|
32
|
+
## Constraints
|
|
33
|
+
- `.mcp.json` is repository-owned config; the script may only *remove* entries from it with explicit interactive consent (Option C decision, prior report).
|
|
34
|
+
- bash 3.2; no `--json` on `claude mcp get` — scope detection greps the `Scope:` line and must fail safe (unknown → touch nothing).
|
|
35
|
+
- Existing installs have serena in `.mcp.json` (this repo included) — need a consented migration path, not just a new default.
|
|
36
|
+
|
|
37
|
+
## Recommendation
|
|
38
|
+
1. **Serena → `--scope local`** in `install-mcps.sh` (and every doc/error message that teaches the `--scope project` form); detection switches from grepping `.mcp.json` to `claude mcp get serena` run in the project dir (covers all scopes). Offer an interactive migration when serena is found in `.mcp.json`.
|
|
39
|
+
2. **Option C for the shared-server upgrade path**: `mcp_scope_of()` helper (user | project | local | unknown); user-scoped stale entry → silent upgrade as today; project/local-scoped → interactive y/N "migrate to the shared server (removes the <scope>-scope entry)?"; non-interactive or unknown → skip + print the manual command.
|
|
40
|
+
3. **Stop asking scope questions that are ignored**: `fixed_scope` argument so brave (always) and playwright (macOS) skip `prompt_scope`.
|
|
41
|
+
4. `bootstrap-serena.sh`: use `--mcp-config .mcp.json --strict-mcp-config` only when `.mcp.json` actually contains serena (legacy layout); plain `claude --print` otherwise — local-scope serena loads headlessly without the approval gate.
|
|
42
|
+
|
|
43
|
+
## Next Steps
|
|
44
|
+
- Implement the four changes; ship as 2.11.3.
|
|
45
|
+
- Steno: on next `bootstrap update`, answer "y" to migrate playwright; serena entry in its `.mcp.json` gets the same consented migration.
|
|
46
|
+
- `/wiki-ingest raw/research/mcp-add-scope-writes/index.md` (pairs with `mcp-scope-conflict-handling`).
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
---
|
|
2
|
+
topic: Research the specific 'claude mcp add' lines in this repo's history and any changes to the 'mcp add' API to determine why steno's .mcp.json was modified (playwright project-scope entry).
|
|
3
|
+
slug: mcp-add-scope-writes
|
|
4
|
+
researched: 2026-07-29
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Primary Sources — `mcp add` scope writes
|
|
8
|
+
|
|
9
|
+
| ID | Type | Locator | Accessed | What it contributed |
|
|
10
|
+
|----|------|---------|----------|---------------------|
|
|
11
|
+
| S1 | codebase | `lib/scripts/install-mcps.sh` (working tree): serena block, `_add_brave`, `_add_context7`, `_add_playwright`, `register_optional_mcp` | 2026-07-29 | All current `claude mcp add` call sites; serena always `--scope project`; context7 + non-mac playwright still honor a "p" scope answer; brave/playwright-mac ignore the prompt |
|
|
12
|
+
| S2 | git | `git show bca82bc:lib/scripts/install-mcps.sh` (bootstrap 2.7.0, "Add interactive MCP setup"); history via `git log -S playwright` (bca82bc → 6bc3d16 → 47b4e0a) | 2026-07-29 | Historical capability only: 2.7.0–2.10.0 could write project-scope playwright entries on a "p" prompt answer (identical command shape) — NOT the confirmed origin for steno (see S6); rewritten 2026-07-28 in 2.11.0 (`47b4e0a`) |
|
|
13
|
+
| S3 | cli | `claude mcp add --help` output on this machine | 2026-07-29 | `-s, --scope <scope>` … `(default: "local")` — default never applies because every script version passes `--scope` explicitly |
|
|
14
|
+
| S4 | codebase | `lib/scripts/install-mcps.sh::register_optional_mcp` upgrade branch as shipped in 2.11.0–2.11.2 | 2026-07-29 | `claude mcp remove "$name" -s user` is the only removal attempted before re-adding — no-op for project-scope entries |
|
|
15
|
+
| S5 | web | https://code.claude.com/docs/en/mcp (scope sections + hierarchy) | 2026-07-29 | Scope storage semantics (project → `.mcp.json`, local → `~/.claude.json` per-project; approval gate applies to `.mcp.json` servers) and precedence local > project > user |
|
|
16
|
+
| S6 | user | David Taylor, this session (2026-07-29) | 2026-07-29 | Attestation: steno's playwright `.mcp.json` entry was pre-existing repository config, not written by bootstrap; the serena entry was NOT pre-existing — bootstrap's setup script added it to `.mcp.json`, and it should instead live in `~/.claude.json` under the project's entry (local scope) |
|
|
17
|
+
| S7 | screenshot | `/Users/davidtaylor/Downloads/Screenshot 2026-07-29 at 9.35.45 AM.png` | 2026-07-29 | Steno's project entry is exactly `npx @playwright/mcp@latest` under `/Users/david/Repositories/steno/.mcp.json`; serena also listed there |
|
|
18
|
+
|
|
19
|
+
## Excerpts
|
|
20
|
+
|
|
21
|
+
### S2 — bootstrap 2.7.0 `install-mcps.sh` (git show bca82bc)
|
|
22
|
+
> ```bash
|
|
23
|
+
> scope=$(prompt_scope "playwright")
|
|
24
|
+
> if [ "$scope" = "project" ] && [ -n "$PROJECT_DIR" ]; then
|
|
25
|
+
> ( cd "$PROJECT_DIR" && \
|
|
26
|
+
> claude mcp add --scope project playwright -- npx @playwright/mcp@latest )
|
|
27
|
+
> ```
|
|
28
|
+
|
|
29
|
+
### S3 — `claude mcp add --help`
|
|
30
|
+
> `-s, --scope <scope> Configuration scope (local, user, or project) (default: "local")`
|
|
31
|
+
|
|
32
|
+
### S5 — Claude Code docs: Connect Claude Code to tools via MCP
|
|
33
|
+
https://code.claude.com/docs/en/mcp
|
|
34
|
+
> When the same server is defined in more than one place, Claude Code connects to it once, using the definition from the highest-precedence source. … 1. Local scope 2. Project scope 3. User scope
|
|
35
|
+
|
|
36
|
+
### S7 — user screenshot (steno /mcp screen)
|
|
37
|
+
> `Project MCPs (/Users/david/Repositories/steno/.mcp.json)` … `playwright · ✔ connected · 24 tools`
|
|
38
|
+
> `Server "playwright" is defined in multiple scopes with different endpoints: user (http://localhost:8931/mcp), project (npx @playwright/mcp@latest).`
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
---
|
|
2
|
+
topic: How should install-mcps.sh handle an MCP server that is already registered at project/local scope when it wants to install the shared user-scope server? What solutions exist and which fits this repo?
|
|
3
|
+
slug: mcp-scope-conflict-handling
|
|
4
|
+
researched: 2026-07-29
|
|
5
|
+
sources: [./sources.md]
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Research: Handling MCP scope conflicts in `install-mcps.sh`
|
|
9
|
+
|
|
10
|
+
> When `bootstrap setup` ran on a machine whose project (`steno`) already had a project-scoped stdio `playwright` entry in `.mcp.json`, the shared-HTTP "upgrade path" removed nothing (it only removes user scope) and installed a second, user-scoped registration — producing Claude Code's `[Conflicting scopes]` warning. Because scope precedence is local > project > user, the project stdio entry keeps winning and the shared server is never used. Four remedies were compared; the recommendation is **detect the scope and skip with a migration hint** (Option A), which is implemented in the working tree but intentionally left uncommitted pending review.
|
|
11
|
+
|
|
12
|
+
## Research Questions
|
|
13
|
+
- Why exactly did the conflict occur, and which registration actually wins?
|
|
14
|
+
- What are the viable behaviors when setup finds a non-user-scope registration of a server it manages?
|
|
15
|
+
- How can scope be detected reliably from a bash 3.2 script (is there structured output)?
|
|
16
|
+
- Which behavior fits this repo's existing conventions (never edit project `.mcp.json`, non-interactive safety, additive-only merges)?
|
|
17
|
+
|
|
18
|
+
## Current State (Codebase)
|
|
19
|
+
- `lib/scripts/install-mcps.sh::register_optional_mcp` upgrade path (pre-fix): on "installed but not matching expected", it ran `claude mcp remove <name> -s user` then re-added at user scope — a no-op removal when the existing entry is project-scoped, creating the duplicate [S1].
|
|
20
|
+
- The script already declares the constraint "Hint only — never edit a project's `.mcp.json`" in its Darwin-only end-of-run warning block [S2].
|
|
21
|
+
- `lib/scripts/lib.sh` house conventions: bash 3.2 only, `grep`-based probes (`mcp_installed`, `mcp_matches`, `serena_installed`), non-interactive runs must degrade safely [S1].
|
|
22
|
+
- Working-tree (uncommitted) fix: new `mcp_user_scoped()` helper in `lib.sh` (greps `claude mcp get` for `Scope: User`) + a guard in the upgrade path that skips and prints the migration command when the entry is not user-scoped.
|
|
23
|
+
|
|
24
|
+
## Key Findings
|
|
25
|
+
- Scope precedence is **1. Local, 2. Project, 3. User**; Claude Code connects once using the highest-precedence definition and does not merge fields — so after the buggy run, the project stdio entry still wins and the shared HTTP server is unused [S4].
|
|
26
|
+
- The `[Conflicting scopes]` warning is real UX damage: OAuth tokens are stored per endpoint, and `/mcp` tells the user to remove one entry manually [S5].
|
|
27
|
+
- `claude mcp get <name>` prints a stable-looking `Scope: User config (…)` / project line but has **no `--json` flag** (`claude mcp get --help` shows only `-h`), so text-grep is the only scriptable detection; it must fail safe [S3].
|
|
28
|
+
- Grep for the project's `.mcp.json` (the `serena_installed` technique) detects project scope but misses local scope and requires `PROJECT_DIR`; `claude mcp get` run from the project cwd covers local + project + user uniformly [S1][S3].
|
|
29
|
+
|
|
30
|
+
## Constraints
|
|
31
|
+
- Never modify a project's `.mcp.json` without explicit user action — it is often team-shared/committed config (steno's carries clickup, figma, guru, playwright as deliberate project choices; the serena entry there was added by bootstrap's own setup script, wrongly — see [mcp-add-scope-writes](../mcp-add-scope-writes/index.md)) [S2][S5].
|
|
32
|
+
- Non-interactive invocations (`bootstrap install`, headless update) must not prompt and must not take destructive action.
|
|
33
|
+
- bash 3.2; no jq dependency; detection must degrade safely if `claude mcp get` output format changes.
|
|
34
|
+
|
|
35
|
+
## Solution Comparison
|
|
36
|
+
|
|
37
|
+
| Criteria | A. Detect scope → skip + hint | B. Auto-remove project entry | C. Interactive migrate prompt | D. Silent skip |
|
|
38
|
+
|----------|------------------------------|------------------------------|-------------------------------|----------------|
|
|
39
|
+
| **Approach** | If entry isn't user-scoped, don't install; print exact `claude mcp remove <name> -s project` migration command | Remove the project `.mcp.json` entry, then install user-scope shared server | In `--interactive` mode ask y/N before removing project entry; skip in non-interactive | Treat project entry as authoritative; say nothing |
|
|
40
|
+
| **Pros** | No conflict ever created; respects team config; works identically in both modes; user stays in control | Converges every machine to the shared server automatically | User consent makes removal legitimate | Simplest |
|
|
41
|
+
| **Cons** | Requires one manual command to migrate | Edits team-shared, possibly git-committed config; violates stated house rule; destructive in non-interactive runs | Two code paths; still edits shared config; surprising in team repos | User never learns the shared server is being shadowed |
|
|
42
|
+
| **Complexity** | Low | Low | Medium | Trivial |
|
|
43
|
+
| **Codebase fit** | Matches existing "hint only" rule and non-interactive safety convention | Contradicts explicit in-file rule [S2] | Partially contradicts it | Loses the existing warning behavior |
|
|
44
|
+
| **Failure mode if scope-grep breaks** | Skips install (safe — no conflict, hint still printed) | Could remove the wrong entry | Same risk as B on yes | n/a |
|
|
45
|
+
|
|
46
|
+
## Recommendation
|
|
47
|
+
**Option A — detect and skip with a migration hint** (already applied in working tree, uncommitted):
|
|
48
|
+
1. `lib.sh`: `mcp_user_scoped()` — `claude mcp get <name> | grep -q "Scope: User"`.
|
|
49
|
+
2. `register_optional_mcp` upgrade path: if the existing registration is not user-scoped, print "already registered at project/local scope — skipping user-scope install to avoid conflicting scopes" plus the exact migration command, and return without touching anything.
|
|
50
|
+
3. Fail-safe direction: if the `Scope:` line format ever changes, the grep returns false → the script *skips* (never creates a conflict); worst case is a printed hint instead of an automatic upgrade.
|
|
51
|
+
|
|
52
|
+
Risks & mitigations:
|
|
53
|
+
- *Text-format drift in `claude mcp get`* → failure mode is conservative (skip), and `mcp_user_scoped` is a single central helper to update.
|
|
54
|
+
- *Users who actually want the project-scoped stdio entry* → Option A leaves it untouched; the hint is advisory.
|
|
55
|
+
|
|
56
|
+
Alternative if constraints change: if `.mcp.json` were machine-local (never committed) in all target projects, Option C (interactive migrate) would become attractive; Option B remains inappropriate for a tool that runs unattended.
|
|
57
|
+
|
|
58
|
+
## Next Steps
|
|
59
|
+
- Review + commit the working-tree implementation as 2.11.3 and publish.
|
|
60
|
+
- Immediate remediation for the affected machine: `cd ~/Repositories/steno && claude mcp remove playwright -s project` **or** `claude mcp remove playwright -s user` (keep whichever playwright the team intends; removing the project entry adopts the shared HTTP server).
|
|
61
|
+
- Optional: `/wiki-ingest raw/research/mcp-scope-conflict-handling/index.md` to fold this into the knowledge base alongside ROADMAP-003's single-process MCP work.
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
---
|
|
2
|
+
topic: How should install-mcps.sh handle an MCP server that is already registered at project/local scope when it wants to install the shared user-scope server? What solutions exist and which fits this repo?
|
|
3
|
+
slug: mcp-scope-conflict-handling
|
|
4
|
+
researched: 2026-07-29
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Primary Sources — MCP scope-conflict handling
|
|
8
|
+
|
|
9
|
+
| ID | Type | Locator | Accessed | What it contributed |
|
|
10
|
+
|----|------|---------|----------|---------------------|
|
|
11
|
+
| S1 | codebase | `lib/scripts/install-mcps.sh::register_optional_mcp` (upgrade branch) + `lib/scripts/lib.sh::mcp_installed/mcp_matches` | 2026-07-29 | The bug: upgrade path removes only `-s user` before re-adding, so a project-scoped stale entry survives and gets duplicated; house grep-probe conventions |
|
|
12
|
+
| S2 | codebase | `lib/scripts/install-mcps.sh` Darwin end-of-run warning block (comment "Hint only — never edit a project's .mcp.json") | 2026-07-29 | Existing house rule that project `.mcp.json` is user-owned; setup only hints |
|
|
13
|
+
| S3 | cli | `claude mcp get playwright` and `claude mcp get --help` output on this machine | 2026-07-29 | Detection surface: `Scope: User config (available in all your projects)` line exists; no `--json` flag on `mcp get`/`mcp list` |
|
|
14
|
+
| S4 | web | https://code.claude.com/docs/en/mcp (Scope hierarchy and precedence) | 2026-07-29 | Precedence order and no-merge behavior |
|
|
15
|
+
| S5 | screenshot | `/Users/davidtaylor/Downloads/Screenshot 2026-07-29 at 9.35.45 AM.png` (user-supplied, steno machine) | 2026-07-29 | Observed failure: `[Conflicting scopes]` warning, playwright at user (http://localhost:8931/mcp) + project (npx @playwright/mcp@latest); steno `.mcp.json` also carries clickup/figma/guru/serena |
|
|
16
|
+
|
|
17
|
+
## Excerpts
|
|
18
|
+
|
|
19
|
+
### S3 — `claude mcp get playwright` (local CLI output)
|
|
20
|
+
> `Scope: User config (available in all your projects)`
|
|
21
|
+
> `claude mcp get --help` → Options: `-h, --help` only (no JSON output mode)
|
|
22
|
+
|
|
23
|
+
### S4 — Claude Code docs: Connect Claude Code to tools via MCP
|
|
24
|
+
https://code.claude.com/docs/en/mcp
|
|
25
|
+
> When the same server is defined in more than one place, Claude Code connects to it once, using the definition from the highest-precedence source. The entire server entry from that source is used; fields are not merged across scopes.
|
|
26
|
+
> 1. Local scope
|
|
27
|
+
> 2. Project scope
|
|
28
|
+
> 3. User scope
|
|
29
|
+
|
|
30
|
+
### S5 — user screenshot (steno machine, /mcp screen)
|
|
31
|
+
> Server "playwright" is defined in multiple scopes with different endpoints: user (http://localhost:8931/mcp), project (npx @playwright/mcp@latest). OAuth tokens are stored per endpoint, so authenticating in one context will not carry over.
|
|
32
|
+
> Keep the correct endpoint and remove the others: `claude mcp remove playwright -s user` or `claude mcp remove playwright -s project`
|
|
@@ -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 |
|