@codewizard-dt/bootstrap 2.10.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.github/workflows/build.yml +88 -0
- package/.github/workflows/security.yml +24 -0
- package/.gitleaks.toml +15 -0
- package/README.md +472 -0
- package/bin/cli.js +47 -0
- package/lib/README.md +27 -0
- package/lib/hooks/README.md +316 -0
- package/lib/hooks/env-file-guard.js +45 -0
- package/lib/hooks/git-protected-ops-block.js +77 -0
- package/lib/hooks/lib/serena-languages.js +158 -0
- package/lib/hooks/lib/serena.js +787 -0
- package/lib/hooks/mv-absolute-path-block.js +53 -0
- package/lib/hooks/serena-bash-grep-block.js +501 -0
- package/lib/hooks/serena-edit-guard.js +74 -0
- package/lib/hooks/serena-first-glob-guard.js +94 -0
- package/lib/hooks/serena-first-guard.js +74 -0
- package/lib/hooks/serena-first-read-guard.js +167 -0
- package/lib/hooks/serena-pre-delegation.js +117 -0
- package/lib/hooks/serena-session-reset.js +45 -0
- package/lib/hooks/serena-usage-tracker.js +186 -0
- package/lib/hooks/serena-write-guard.js +58 -0
- package/lib/prompts/README.md +16 -0
- package/lib/prompts/migrate-wiki.md +111 -0
- package/lib/prompts/setup-deployment.md +322 -0
- package/lib/prompts/setup-design-system.md +162 -0
- package/lib/prompts/setup-strict-typechecks.md +139 -0
- package/lib/scripts/README.md +49 -0
- package/lib/scripts/bootstrap-serena.sh +145 -0
- package/lib/scripts/build-mcp-guide.sh +108 -0
- package/lib/scripts/install-global.sh +78 -0
- package/lib/scripts/install-mcps.sh +131 -0
- package/lib/scripts/lib.sh +154 -0
- package/lib/scripts/merge-gitignore.sh +65 -0
- package/lib/scripts/migrate-project.sh +273 -0
- package/lib/scripts/setup-deployment.sh +104 -0
- package/lib/scripts/setup-project.sh +55 -0
- package/lib/scripts/setup-runner.sh +99 -0
- package/lib/scripts/setup-strict-typechecks.sh +29 -0
- package/lib/scripts/startup.sh +42 -0
- package/lib/scripts/sync-wiki-scaffold.sh +104 -0
- package/lib/scripts/templates/CLAUDE-env-safety.md +3 -0
- package/lib/scripts/templates/CLAUDE-wiki.md +60 -0
- package/lib/scripts/templates/gitignore +136 -0
- package/lib/scripts/templates/guides/stubs/00-header.md +15 -0
- package/lib/scripts/templates/guides/stubs/brave-search.md +20 -0
- package/lib/scripts/templates/guides/stubs/context7.md +26 -0
- package/lib/scripts/templates/guides/stubs/playwright.md +26 -0
- package/lib/scripts/templates/guides/stubs/serena.md +219 -0
- package/lib/scripts/templates/wiki/conventions.md +100 -0
- package/lib/scripts/templates/wiki/dashboard.html +1733 -0
- package/lib/scripts/templates/wiki/hot.md +21 -0
- package/lib/scripts/templates/wiki/index.md +46 -0
- package/lib/scripts/templates/wiki/knowledge/concepts/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/entities/components/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/entities/organisations/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/entities/people/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/entities/tools/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/sources/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/log.md +14 -0
- package/lib/scripts/templates/wiki/work/bugs/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/bugs/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/bugs/index.md +12 -0
- package/lib/scripts/templates/wiki/work/bugs/lifecycle.md +39 -0
- package/lib/scripts/templates/wiki/work/decisions/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/decisions/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/decisions/index.md +12 -0
- package/lib/scripts/templates/wiki/work/decisions/lifecycle.md +42 -0
- package/lib/scripts/templates/wiki/work/requirements/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/requirements/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/requirements/index.md +12 -0
- package/lib/scripts/templates/wiki/work/requirements/lifecycle.md +34 -0
- package/lib/scripts/templates/wiki/work/roadmaps/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/roadmaps/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/roadmaps/index.md +12 -0
- package/lib/scripts/templates/wiki/work/roadmaps/lifecycle.md +32 -0
- package/lib/scripts/templates/wiki/work/tasks/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/tasks/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/tasks/index.md +12 -0
- package/lib/scripts/templates/wiki/work/tasks/lifecycle.md +39 -0
- package/lib/scripts/templates/wiki/work/uat/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/uat/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/uat/index.md +12 -0
- package/lib/scripts/templates/wiki/work/uat/lifecycle.md +48 -0
- package/lib/scripts/templates/wiki/work/uat/screenshots/.gitkeep +0 -0
- package/lib/scripts/update-project.sh +75 -0
- package/lib/scripts/wiki-dashboard-server.js +146 -0
- package/lib/skills/README.md +146 -0
- package/lib/skills/anti-slop/SKILL.md +183 -0
- package/lib/skills/bug-close/SKILL.md +136 -0
- package/lib/skills/bug-file/SKILL.md +114 -0
- package/lib/skills/bug-triage/SKILL.md +140 -0
- package/lib/skills/company-align/SKILL.md +203 -0
- package/lib/skills/debug-logs/SKILL.md +129 -0
- package/lib/skills/decision-create/SKILL.md +220 -0
- package/lib/skills/decision-finalize/SKILL.md +181 -0
- package/lib/skills/decision-next/SKILL.md +129 -0
- package/lib/skills/decision-walkthrough/SKILL.md +169 -0
- package/lib/skills/demo/SKILL.md +183 -0
- package/lib/skills/elevator-pitch/SKILL.md +125 -0
- package/lib/skills/eval-create/SKILL.md +344 -0
- package/lib/skills/eval-gap/SKILL.md +150 -0
- package/lib/skills/eval-run/SKILL.md +214 -0
- package/lib/skills/extract-feature/SKILL.md +344 -0
- package/lib/skills/flashcard/SKILL.md +513 -0
- package/lib/skills/frontend-taste/SKILL.md +184 -0
- package/lib/skills/gap-assess/SKILL.md +97 -0
- package/lib/skills/git-commit/SKILL.md +164 -0
- package/lib/skills/lint/SKILL.md +99 -0
- package/lib/skills/marp-slideshow/SKILL.md +212 -0
- package/lib/skills/mermaid-flowchart/SKILL.md +194 -0
- package/lib/skills/now/SKILL.md +36 -0
- package/lib/skills/port-feature/SKILL.md +315 -0
- package/lib/skills/power-mode/SKILL.md +184 -0
- package/lib/skills/primer/SKILL.md +84 -0
- package/lib/skills/project-readme/SKILL.md +166 -0
- package/lib/skills/req-compile/SKILL.md +131 -0
- package/lib/skills/req-create/SKILL.md +124 -0
- package/lib/skills/req-extract-decisions/SKILL.md +241 -0
- package/lib/skills/req-finalize/SKILL.md +251 -0
- package/lib/skills/req-retire/SKILL.md +185 -0
- package/lib/skills/req-update/SKILL.md +265 -0
- package/lib/skills/research/SKILL.md +250 -0
- package/lib/skills/research-company/SKILL.md +345 -0
- package/lib/skills/roadmap-add/SKILL.md +238 -0
- package/lib/skills/roadmap-create/SKILL.md +223 -0
- package/lib/skills/roadmap-next/SKILL.md +132 -0
- package/lib/skills/security-audit/SKILL.md +246 -0
- package/lib/skills/serena-config/SKILL.md +92 -0
- package/lib/skills/simplify/SKILL.md +227 -0
- package/lib/skills/tackle/SKILL.md +156 -0
- package/lib/skills/task-add/SKILL.md +208 -0
- package/lib/skills/task-audit/SKILL.md +294 -0
- package/lib/skills/task-trash/SKILL.md +115 -0
- package/lib/skills/task-update/SKILL.md +136 -0
- package/lib/skills/uat-auto/SKILL.md +69 -0
- package/lib/skills/uat-auto-plus/SKILL.md +115 -0
- package/lib/skills/uat-generate/SKILL.md +289 -0
- package/lib/skills/uat-skip/SKILL.md +169 -0
- package/lib/skills/uat-walk/SKILL.md +164 -0
- package/lib/skills/uat-walk/UAT-CORE.md +140 -0
- package/lib/skills/update-docs/SKILL.md +75 -0
- package/lib/skills/wiki-archive/SKILL.md +96 -0
- package/lib/skills/wiki-ingest/SKILL.md +139 -0
- package/lib/skills/wiki-lint/SKILL.md +131 -0
- package/lib/skills/wiki-query/SKILL.md +71 -0
- package/lib/skills/wiki-rotate-log/SKILL.md +90 -0
- package/lib/skills/wiki-tidy/SKILL.md +107 -0
- package/package.json +32 -0
- package/raw/.gitkeep +0 -0
- package/raw/design-principles.md +65 -0
- package/raw/guides/command-anti-patterns.md +79 -0
- package/raw/guides/deployment-strategy.md +448 -0
- package/raw/guides/evals-framework.md +452 -0
- package/raw/guides/mcp-tools.md +335 -0
- package/raw/guides/task-spec.md +79 -0
- package/raw/guides/type-checking-templates/README.md +112 -0
- package/raw/guides/type-checking-templates/eslint/eslint.config.ts +105 -0
- package/raw/guides/type-checking-templates/python/mypy.ini +69 -0
- package/raw/guides/type-checking-templates/python/pyproject.toml +164 -0
- package/raw/guides/type-checking-templates/python/pyrightconfig.json +67 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.app.jsonc +45 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.lib.jsonc +44 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.node-esm.jsonc +40 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.node.jsonc +34 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.vite-root.json +8 -0
- package/raw/harness-notes.md +20 -0
- package/raw/house-style/components/Badge.tsx +16 -0
- package/raw/house-style/components/Button.tsx +32 -0
- package/raw/house-style/components/Card.tsx +26 -0
- package/raw/house-style/components/Chip.tsx +57 -0
- package/raw/house-style/components/IconButton.tsx +67 -0
- package/raw/house-style/components/Modal.tsx +18 -0
- package/raw/house-style/components/Stepper.tsx +141 -0
- package/raw/house-style/components/icons.tsx +128 -0
- package/raw/house-style/preview/src/index.css +46 -0
- package/raw/house-style/tokens/tailwind.preset.ts +49 -0
- package/raw/house-style/tokens/tokens.json +62 -0
- package/raw/llm-wiki-2.md +162 -0
- package/raw/llm-wiki.md +75 -0
- package/raw/research/dark-mode-theme/index.md +85 -0
- package/raw/research/dark-mode-theme/sources.md +49 -0
- package/raw/research/serena-mcp-disconnect/index.md +81 -0
- package/raw/research/serena-mcp-disconnect/sources.md +87 -0
- package/raw/research/wiki-tooling-improvements/index.md +126 -0
- package/raw/research/wiki-tooling-improvements/sources.md +73 -0
- package/raw/software-factory-case-study.pdf +0 -0
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
set -euo pipefail
|
|
3
|
+
|
|
4
|
+
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
|
5
|
+
. "$SCRIPT_DIR/lib.sh"
|
|
6
|
+
TEMPLATE_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
|
|
7
|
+
TEMPLATES="$SCRIPT_DIR/templates/wiki"
|
|
8
|
+
|
|
9
|
+
if [ $# -ne 1 ]; then
|
|
10
|
+
echo "Usage: $0 <path-to-project>"
|
|
11
|
+
exit 1
|
|
12
|
+
fi
|
|
13
|
+
|
|
14
|
+
PROJECT_DIR="$(resolve_project_dir "$1")" || exit 1
|
|
15
|
+
|
|
16
|
+
echo "Syncing wiki scaffold into: $PROJECT_DIR"
|
|
17
|
+
|
|
18
|
+
# 1. Create all directories
|
|
19
|
+
mkdir -p \
|
|
20
|
+
"$PROJECT_DIR/raw" \
|
|
21
|
+
"$PROJECT_DIR/wiki" \
|
|
22
|
+
"$PROJECT_DIR/wiki/knowledge/sources" \
|
|
23
|
+
"$PROJECT_DIR/wiki/knowledge/concepts" \
|
|
24
|
+
"$PROJECT_DIR/wiki/knowledge/entities/people" \
|
|
25
|
+
"$PROJECT_DIR/wiki/knowledge/entities/organisations" \
|
|
26
|
+
"$PROJECT_DIR/wiki/knowledge/entities/tools" \
|
|
27
|
+
"$PROJECT_DIR/wiki/knowledge/entities/components" \
|
|
28
|
+
"$PROJECT_DIR/wiki/work/requirements" \
|
|
29
|
+
"$PROJECT_DIR/wiki/work/decisions" \
|
|
30
|
+
"$PROJECT_DIR/wiki/work/roadmaps" \
|
|
31
|
+
"$PROJECT_DIR/wiki/work/tasks" \
|
|
32
|
+
"$PROJECT_DIR/wiki/work/uat" \
|
|
33
|
+
"$PROJECT_DIR/wiki/work/uat/screenshots" \
|
|
34
|
+
"$PROJECT_DIR/wiki/work/bugs" \
|
|
35
|
+
"$PROJECT_DIR/.docs/guides"
|
|
36
|
+
|
|
37
|
+
# 2. COPY-ONCE: index.md, log.md, hot.md, .gitkeep files — project-owned after creation, never overwrite
|
|
38
|
+
# Exclude conventions.md and lifecycle.md (those are always-refresh, handled in step 3).
|
|
39
|
+
rsync -av --ignore-existing \
|
|
40
|
+
--exclude 'conventions.md' \
|
|
41
|
+
--exclude 'lifecycle.md' \
|
|
42
|
+
--exclude 'dashboard.html' \
|
|
43
|
+
"$TEMPLATES/" "$PROJECT_DIR/wiki/"
|
|
44
|
+
|
|
45
|
+
# 3. ALWAYS-REFRESH: spec docs (conventions.md, lifecycle.md) and dashboard.html that remain template-owned; always overwrite
|
|
46
|
+
rsync -av "$TEMPLATES/conventions.md" "$PROJECT_DIR/wiki/conventions.md"
|
|
47
|
+
rsync -av "$TEMPLATES/dashboard.html" "$PROJECT_DIR/wiki/dashboard.html"
|
|
48
|
+
for fam in requirements decisions roadmaps tasks uat bugs; do
|
|
49
|
+
rsync -av "$TEMPLATES/work/$fam/lifecycle.md" "$PROJECT_DIR/wiki/work/$fam/lifecycle.md"
|
|
50
|
+
done
|
|
51
|
+
|
|
52
|
+
# 4. GUIDES: always refresh from raw/guides/ into target .docs/guides/
|
|
53
|
+
rsync -av "$TEMPLATE_DIR/raw/guides/" "$PROJECT_DIR/.docs/guides/"
|
|
54
|
+
|
|
55
|
+
# 5. Ensure raw/ has a .gitkeep so git tracks the empty dir
|
|
56
|
+
touch -a "$PROJECT_DIR/raw/.gitkeep" 2>/dev/null || true
|
|
57
|
+
|
|
58
|
+
# 6. Deliver the wiki schema section to the target's CLAUDE.md (copy-once).
|
|
59
|
+
# Sentinel: a line starting with "## LLM Wiki". Never re-appended once present.
|
|
60
|
+
CLAUDE_TEMPLATE="$SCRIPT_DIR/templates/CLAUDE-wiki.md"
|
|
61
|
+
TARGET_CLAUDE="$PROJECT_DIR/CLAUDE.md"
|
|
62
|
+
if [ -f "$CLAUDE_TEMPLATE" ]; then
|
|
63
|
+
if [ ! -f "$TARGET_CLAUDE" ]; then
|
|
64
|
+
{
|
|
65
|
+
echo "# CLAUDE.md"
|
|
66
|
+
echo ""
|
|
67
|
+
echo "This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository."
|
|
68
|
+
echo ""
|
|
69
|
+
cat "$CLAUDE_TEMPLATE"
|
|
70
|
+
} > "$TARGET_CLAUDE"
|
|
71
|
+
echo "CLAUDE.md created with the LLM Wiki schema section."
|
|
72
|
+
elif ! grep -q '^## LLM Wiki' "$TARGET_CLAUDE"; then
|
|
73
|
+
{
|
|
74
|
+
echo ""
|
|
75
|
+
echo "---"
|
|
76
|
+
echo ""
|
|
77
|
+
cat "$CLAUDE_TEMPLATE"
|
|
78
|
+
} >> "$TARGET_CLAUDE"
|
|
79
|
+
echo "LLM Wiki schema section appended to CLAUDE.md."
|
|
80
|
+
else
|
|
81
|
+
echo "CLAUDE.md already has the LLM Wiki schema section, skipping."
|
|
82
|
+
fi
|
|
83
|
+
fi
|
|
84
|
+
|
|
85
|
+
# 7. Ensure the .env safety policy sits at the TOP of the target's CLAUDE.md (copy-once).
|
|
86
|
+
# Sentinel: the distinctive policy line. Prepended only when absent — never duplicated.
|
|
87
|
+
ENV_TEMPLATE="$SCRIPT_DIR/templates/CLAUDE-env-safety.md"
|
|
88
|
+
ENV_SENTINEL='never allowed to read or write to any'
|
|
89
|
+
if [ -f "$ENV_TEMPLATE" ] && [ -f "$TARGET_CLAUDE" ]; then
|
|
90
|
+
if ! grep -qF "$ENV_SENTINEL" "$TARGET_CLAUDE"; then
|
|
91
|
+
TMP_CLAUDE="$(mktemp)"
|
|
92
|
+
{
|
|
93
|
+
cat "$ENV_TEMPLATE"
|
|
94
|
+
echo ""
|
|
95
|
+
cat "$TARGET_CLAUDE"
|
|
96
|
+
} > "$TMP_CLAUDE"
|
|
97
|
+
mv "$TMP_CLAUDE" "$TARGET_CLAUDE"
|
|
98
|
+
echo ".env safety policy prepended to top of CLAUDE.md."
|
|
99
|
+
else
|
|
100
|
+
echo "CLAUDE.md already has the .env safety policy, skipping."
|
|
101
|
+
fi
|
|
102
|
+
fi
|
|
103
|
+
|
|
104
|
+
echo "Wiki scaffold synced."
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
## LLM Wiki
|
|
2
|
+
|
|
3
|
+
This project maintains a three-layer LLM Wiki. This section is the **schema** — it tells you how the wiki is structured and what rules govern it.
|
|
4
|
+
|
|
5
|
+
```
|
|
6
|
+
raw/ Immutable ground-truth sources. Read them; NEVER modify, move, or delete them.
|
|
7
|
+
wiki/ LLM-maintained knowledge base. You own this layer entirely.
|
|
8
|
+
CLAUDE.md This schema section.
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
### Two domains with opposite organizing laws
|
|
12
|
+
|
|
13
|
+
**`wiki/knowledge/`** — timeless synthesis, organized by links not status. Pages are revised in place as understanding evolves; no `status` field.
|
|
14
|
+
|
|
15
|
+
- `wiki/knowledge/sources/` — one summary page per ingested `raw/` source
|
|
16
|
+
- `wiki/knowledge/concepts/` — patterns, ideas, conventions, recurring themes
|
|
17
|
+
- `wiki/knowledge/entities/{people,organisations,tools,components}/` — one page per entity, filed by sub-type
|
|
18
|
+
|
|
19
|
+
**`wiki/work/`** — stateful lifecycle artifacts, organized by status. Active files are **never moved** after creation; state lives in the `status:` frontmatter field. Each family has a `lifecycle.md` (schema + valid transitions), an `index.md` listing **only active items**, and an `archive/` subdirectory for terminal items. When an item leaves the active set, delete its line from the family index; terminal items may be moved to `archive/` by `/wiki-archive`.
|
|
20
|
+
|
|
21
|
+
- `wiki/work/requirements/` — REQ-NNN
|
|
22
|
+
- `wiki/work/decisions/` — DEC-NNNN (per-decision `#DM`)
|
|
23
|
+
- `wiki/work/roadmaps/` — ROADMAP-NNN
|
|
24
|
+
- `wiki/work/tasks/` — TASK-NNN
|
|
25
|
+
- `wiki/work/uat/` — UAT-NNN (own family, one per task)
|
|
26
|
+
- `wiki/work/bugs/` — BUG-NNNN
|
|
27
|
+
|
|
28
|
+
**Navigation:** `wiki/index.md` is the home Map of Content — read it first on every wiki query. Knowledge pages are listed there individually; work items live only in their family index. `wiki/log.md` is the append-only operation log. `wiki/conventions.md` holds the page rules (atomic pages, stable IDs/aliases, typed links, frontmatter namespace).
|
|
29
|
+
|
|
30
|
+
### Auto Memory vs. this wiki
|
|
31
|
+
|
|
32
|
+
Claude Code has its own native **Auto Memory** feature — typed memory files (`user`, `feedback`, `project`, `reference`) kept under `~/.claude/projects/<hash>/memory/`, indexed by `MEMORY.md`, auto-loaded at session start. It is **cross-project and un-versioned**: it lives outside this git repo and follows the user across every project. This wiki, by contrast, is **per-project and git-versioned**: it lives in `wiki/`, is reviewable in diffs, and is shared with anyone who clones the repo.
|
|
33
|
+
|
|
34
|
+
Rule of thumb for where a new fact belongs:
|
|
35
|
+
|
|
36
|
+
- **Auto Memory** — facts about the *user* and their cross-project working style: how they like to collaborate, standing preferences, feedback that applies regardless of which repo is open. If a fact is true only because "the user told me once" and holds everywhere → Auto Memory.
|
|
37
|
+
- **This wiki** — facts about *this project*: its architecture, decisions, requirements, tasks, and synthesized knowledge that should be versioned, reviewable, and survive in git history. If a fact is true because "this project decided X" → wiki.
|
|
38
|
+
|
|
39
|
+
Keep the two from duplicating or contradicting each other: project-specific state does not go in Auto Memory, and cross-project user preferences do not go in the wiki.
|
|
40
|
+
|
|
41
|
+
### Wiki operations
|
|
42
|
+
|
|
43
|
+
| Command | Purpose |
|
|
44
|
+
|---------|---------|
|
|
45
|
+
| `/wiki-ingest <raw-file>` | Process a source from `raw/` into the wiki — summary page, entity/concept updates, index + log entries |
|
|
46
|
+
| `/wiki-query <question>` | Answer from the wiki with citations; offer to file valuable synthesis back as a new page |
|
|
47
|
+
| `/wiki-lint` | Health-check — contradictions, orphan pages, stale claims, index drift, never-ingested raw sources |
|
|
48
|
+
| `/wiki-archive [family]` | Batch-move terminal work items into `<family>/archive/`; update `archive/index.md` and log the operation |
|
|
49
|
+
| `/wiki-rotate-log` | Rotate `wiki/log.md` to a timestamped archive file when it exceeds ~500 lines; create a fresh `log.md` with an archive pointer |
|
|
50
|
+
| `/wiki-tidy` | One-shot cleanup — lint, archive terminal items across all families, then rotate log if overgrown; phases run in sequence with user confirmation |
|
|
51
|
+
|
|
52
|
+
### CRITICAL wiki rules
|
|
53
|
+
|
|
54
|
+
1. `raw/` is immutable — never create, modify, move, or delete files under `raw/`
|
|
55
|
+
2. Cross-link aggressively — related pages link to each other with relative markdown links; the link network is as valuable as the pages
|
|
56
|
+
3. Index and log updates are mandatory — every ingest and filed answer updates `wiki/index.md` + `wiki/log.md`; every work-item create or status flip updates the family `index.md` + `wiki/log.md`
|
|
57
|
+
4. Flag contradictions explicitly — when a new source conflicts with an existing page, add a `> **Contradiction:**` callout citing both; never silently overwrite
|
|
58
|
+
5. Answer from the wiki, not general knowledge — if the wiki lacks coverage, say so and suggest `/wiki-ingest` for relevant sources
|
|
59
|
+
6. Atomic pages — one concept, entity, or artifact per file; split a page rather than let it cover two things
|
|
60
|
+
7. Typed links — when a link has a meaning, annotate it inline as `rel::[[target]]` (e.g. `implements::[[REQ-012]]`, `supersedes::[[DEC-0003#D2]]`); keep the two domains separate — never file a stateful artifact under `knowledge/` or a timeless synthesis under `work/`
|
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
# ---------------------------------------------------------------------------
|
|
2
|
+
# OS / Editor
|
|
3
|
+
# ---------------------------------------------------------------------------
|
|
4
|
+
.DS_Store
|
|
5
|
+
Thumbs.db
|
|
6
|
+
*~
|
|
7
|
+
.idea/
|
|
8
|
+
.vscode/*
|
|
9
|
+
!.vscode/settings.json
|
|
10
|
+
!.vscode/extensions.json
|
|
11
|
+
*.swp
|
|
12
|
+
.conductor
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
# ---------------------------------------------------------------------------
|
|
16
|
+
# Claude Code — machine-local MCP registration (absolute paths; regenerated by setup)
|
|
17
|
+
# ---------------------------------------------------------------------------
|
|
18
|
+
.mcp.json
|
|
19
|
+
.playwright-mcp/
|
|
20
|
+
|
|
21
|
+
# ---------------------------------------------------------------------------
|
|
22
|
+
# Secrets & local environment (NEVER commit real secrets)
|
|
23
|
+
# ---------------------------------------------------------------------------
|
|
24
|
+
.env
|
|
25
|
+
.env.*
|
|
26
|
+
!.env.example
|
|
27
|
+
*.pem
|
|
28
|
+
*.key
|
|
29
|
+
|
|
30
|
+
# ---------------------------------------------------------------------------
|
|
31
|
+
# Logs & temp
|
|
32
|
+
# ---------------------------------------------------------------------------
|
|
33
|
+
*.log
|
|
34
|
+
logs/
|
|
35
|
+
tmp/
|
|
36
|
+
*.tmp
|
|
37
|
+
|
|
38
|
+
# ---------------------------------------------------------------------------
|
|
39
|
+
# Node / TypeScript / JavaScript
|
|
40
|
+
# ---------------------------------------------------------------------------
|
|
41
|
+
node_modules/
|
|
42
|
+
dist/
|
|
43
|
+
build/
|
|
44
|
+
out/
|
|
45
|
+
.next/
|
|
46
|
+
.nuxt/
|
|
47
|
+
.cache/
|
|
48
|
+
coverage/
|
|
49
|
+
*.tgz
|
|
50
|
+
*.tsbuildinfo
|
|
51
|
+
.npm/
|
|
52
|
+
.eslintcache
|
|
53
|
+
.pnp.*
|
|
54
|
+
.yarn/*
|
|
55
|
+
!.yarn/patches
|
|
56
|
+
!.yarn/releases
|
|
57
|
+
|
|
58
|
+
# ---------------------------------------------------------------------------
|
|
59
|
+
# Python
|
|
60
|
+
# ---------------------------------------------------------------------------
|
|
61
|
+
__pycache__/
|
|
62
|
+
*.py[cod]
|
|
63
|
+
*$py.class
|
|
64
|
+
*.egg
|
|
65
|
+
*.egg-info/
|
|
66
|
+
.eggs/
|
|
67
|
+
.installed.cfg
|
|
68
|
+
develop-eggs/
|
|
69
|
+
sdist/
|
|
70
|
+
wheels/
|
|
71
|
+
share/python-wheels/
|
|
72
|
+
MANIFEST
|
|
73
|
+
|
|
74
|
+
# Virtual environments
|
|
75
|
+
.venv/
|
|
76
|
+
venv/
|
|
77
|
+
env/
|
|
78
|
+
ENV/
|
|
79
|
+
.python-version
|
|
80
|
+
|
|
81
|
+
# Test / type / lint caches
|
|
82
|
+
.pytest_cache/
|
|
83
|
+
.mypy_cache/
|
|
84
|
+
.dmypy.json
|
|
85
|
+
.pyre/
|
|
86
|
+
.ruff_cache/
|
|
87
|
+
.tox/
|
|
88
|
+
.nox/
|
|
89
|
+
.coverage
|
|
90
|
+
.coverage.*
|
|
91
|
+
htmlcov/
|
|
92
|
+
.hypothesis/
|
|
93
|
+
|
|
94
|
+
# ---------------------------------------------------------------------------
|
|
95
|
+
# Jupyter / Notebooks
|
|
96
|
+
# ---------------------------------------------------------------------------
|
|
97
|
+
.ipynb_checkpoints/
|
|
98
|
+
*/.ipynb_checkpoints/*
|
|
99
|
+
profile_default/
|
|
100
|
+
ipython_config.py
|
|
101
|
+
|
|
102
|
+
# ---------------------------------------------------------------------------
|
|
103
|
+
# Machine Learning — models, checkpoints, artifacts
|
|
104
|
+
# ---------------------------------------------------------------------------
|
|
105
|
+
*.ckpt
|
|
106
|
+
*.pt
|
|
107
|
+
*.pth
|
|
108
|
+
*.h5
|
|
109
|
+
*.hdf5
|
|
110
|
+
*.pb
|
|
111
|
+
*.onnx
|
|
112
|
+
*.tflite
|
|
113
|
+
*.pkl
|
|
114
|
+
*.pickle
|
|
115
|
+
*.joblib
|
|
116
|
+
*.safetensors
|
|
117
|
+
*.bin
|
|
118
|
+
|
|
119
|
+
# Experiment tracking & pipelines
|
|
120
|
+
wandb/
|
|
121
|
+
mlruns/
|
|
122
|
+
.mlflow/
|
|
123
|
+
lightning_logs/
|
|
124
|
+
runs/
|
|
125
|
+
outputs/
|
|
126
|
+
checkpoints/
|
|
127
|
+
.dvc/cache
|
|
128
|
+
.dvc/tmp
|
|
129
|
+
|
|
130
|
+
# Datasets — uncomment if large/raw data should NOT be versioned.
|
|
131
|
+
# Prefer DVC / git-lfs / external storage for big data.
|
|
132
|
+
# data/
|
|
133
|
+
# datasets/
|
|
134
|
+
# *.csv
|
|
135
|
+
# *.parquet
|
|
136
|
+
# *.tfrecord
|
|
@@ -0,0 +1,15 @@
|
|
|
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
|
+
---
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
|
|
2
|
+
## Brave Search (Web Research)
|
|
3
|
+
|
|
4
|
+
### Rate Limit: 50 requests per second
|
|
5
|
+
|
|
6
|
+
- Up to 50 requests per second are supported — parallel searches are allowed
|
|
7
|
+
- On 429 errors, back off briefly and retry (max 3 times)
|
|
8
|
+
|
|
9
|
+
### Usage
|
|
10
|
+
|
|
11
|
+
```python
|
|
12
|
+
mcp__brave-search__brave_web_search(
|
|
13
|
+
query="FastAPI dependency injection best practices 2025",
|
|
14
|
+
count=10
|
|
15
|
+
)
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
Use for general research, best practices, troubleshooting, news. Do NOT use for library documentation (use Context7).
|
|
19
|
+
|
|
20
|
+
---
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
|
|
2
|
+
## Context7 (Library Documentation)
|
|
3
|
+
|
|
4
|
+
Two-step workflow — resolve the library ID, then query docs.
|
|
5
|
+
|
|
6
|
+
### Step 1: Resolve Library ID
|
|
7
|
+
|
|
8
|
+
```python
|
|
9
|
+
mcp__context7__resolve-library-id(libraryName="sqlalchemy")
|
|
10
|
+
# Returns: "/sqlalchemy/sqlalchemy"
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
Skip only if user provides an explicit `/org/project` ID.
|
|
14
|
+
|
|
15
|
+
### Step 2: Query Documentation
|
|
16
|
+
|
|
17
|
+
```python
|
|
18
|
+
mcp__context7__query-docs(
|
|
19
|
+
libraryId="/sqlalchemy/sqlalchemy",
|
|
20
|
+
query="async session management"
|
|
21
|
+
)
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
If results are insufficient, refine the query with more specific terms.
|
|
25
|
+
|
|
26
|
+
---
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
|
|
2
|
+
## Playwright (Browser Automation)
|
|
3
|
+
|
|
4
|
+
### Tools
|
|
5
|
+
|
|
6
|
+
| Tool | Purpose |
|
|
7
|
+
|------|---------|
|
|
8
|
+
| `browser_navigate` | Navigate to a URL |
|
|
9
|
+
| `browser_take_screenshot` | Screenshot current page |
|
|
10
|
+
| `browser_snapshot` | Get accessibility tree (use to get element `ref` IDs before clicking/typing) |
|
|
11
|
+
| `browser_click` | Click element by `ref` ID from snapshot |
|
|
12
|
+
| `browser_type` | Type into an input field by `ref` ID |
|
|
13
|
+
| `browser_evaluate` | Execute JavaScript in browser |
|
|
14
|
+
| `browser_select_option` | Select dropdown option by `ref` ID |
|
|
15
|
+
| `browser_hover` | Hover over element by `ref` ID |
|
|
16
|
+
| `browser_close` | Close the browser |
|
|
17
|
+
|
|
18
|
+
### Workflow
|
|
19
|
+
|
|
20
|
+
1. **No explicit launch step** — the browser starts automatically on the first tool call.
|
|
21
|
+
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.
|
|
22
|
+
3. Use `browser_take_screenshot` for visual verification after navigation or interaction.
|
|
23
|
+
|
|
24
|
+
Use for visual verification, form interaction, and browser-rendered content. Do NOT use for static content fetching or library docs.
|
|
25
|
+
|
|
26
|
+
---
|
|
@@ -0,0 +1,219 @@
|
|
|
1
|
+
|
|
2
|
+
### Standard tools (`Read`, `Edit`, `Write`) are permitted for:
|
|
3
|
+
|
|
4
|
+
- **Markdown files** (`.md`) — content edits use standard tools (Serena's symbolic editor doesn't apply to prose)
|
|
5
|
+
- **Config files** — JSON, YAML, TOML, `.env`, `.gitignore`, `package.json`, etc.
|
|
6
|
+
- **Creating brand-new files** of any type
|
|
7
|
+
- **Binary files and images** (read only)
|
|
8
|
+
|
|
9
|
+
### Standard tools are NEVER permitted for:
|
|
10
|
+
|
|
11
|
+
- **Code files** — TypeScript, JavaScript, Python, Go, Rust, etc. Always use Serena's symbolic or file/line tools.
|
|
12
|
+
- **File or directory exploration of any kind**, regardless of file type. This includes:
|
|
13
|
+
- Listing directories → use `mcp__serena__list_dir`, **never** `ls` / `tree` / `find -type d`
|
|
14
|
+
- Finding files by name → use `mcp__serena__find_file`, **never** `find -name` / `ls | grep`
|
|
15
|
+
- Searching file contents → use `mcp__serena__search_for_pattern` or the `Grep` tool, **never** `grep` / `rg` / `ag` invoked through `bash`
|
|
16
|
+
- Reading file contents for inspection → use `mcp__serena__get_symbols_overview` (code) or `Read` (markdown/config), **never** `cat` / `head` / `tail`
|
|
17
|
+
- Editing via shell → **never** `sed` / `awk` / `echo >>`
|
|
18
|
+
|
|
19
|
+
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.
|
|
20
|
+
|
|
21
|
+
### Common anti-patterns and their fixes
|
|
22
|
+
|
|
23
|
+
These are real mistakes AI agents make on this codebase. Do not repeat them.
|
|
24
|
+
|
|
25
|
+
#### ❌ Anti-pattern: `sed` to flip task-file checkboxes
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
# WRONG — never do this
|
|
29
|
+
sed -i '' 's/- \[ \] Launch Puppeteer/- [x] Launch Puppeteer/; s/- \[ \] Navigate and screenshot/- [x] Navigate and screenshot/' .docs/tasks/051-ux-conversion-audit.md
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
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.
|
|
33
|
+
|
|
34
|
+
✅ **Correct**: call the `Edit` tool once per checkbox (or use `replace_all: true` if every `- [ ]` in the file should become `- [x]`):
|
|
35
|
+
|
|
36
|
+
```
|
|
37
|
+
Edit(file_path=".docs/tasks/051-ux-conversion-audit.md",
|
|
38
|
+
old_string="- [ ] Launch Puppeteer",
|
|
39
|
+
new_string="- [x] Launch Puppeteer")
|
|
40
|
+
Edit(file_path=".docs/tasks/051-ux-conversion-audit.md",
|
|
41
|
+
old_string="- [ ] Navigate and screenshot each marketing",
|
|
42
|
+
new_string="- [x] Navigate and screenshot each marketing")
|
|
43
|
+
# ...one Edit call per checkbox
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Yes, even if there are ten checkboxes. Ten `Edit` calls is correct. One `sed` is wrong.
|
|
47
|
+
|
|
48
|
+
#### ❌ Anti-pattern: `cat` to check what's in a file before editing
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
# WRONG
|
|
52
|
+
cat .docs/tasks/051-ux-conversion-audit.md
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
✅ **Correct**: `Read` tool. Always.
|
|
56
|
+
|
|
57
|
+
#### ❌ Anti-pattern: `ls` to see what's in a directory
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
# WRONG
|
|
61
|
+
ls .docs/uat/screenshots/
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
✅ **Correct**: `mcp__serena__list_dir(relative_path=".docs/uat/screenshots/")`
|
|
65
|
+
|
|
66
|
+
#### ❌ Anti-pattern: `grep -r` to find a string across files
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
# WRONG
|
|
70
|
+
grep -r "pending-uat" .
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
✅ **Correct**: the `Grep` tool, or `mcp__serena__search_for_pattern`.
|
|
74
|
+
|
|
75
|
+
#### ❌ Anti-pattern: `echo "new content" >> file.md` to append to a file
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
# WRONG
|
|
79
|
+
echo "## New Section" >> README.md
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
✅ **Correct**: `Read` the file first to see the current end, then `Edit` to append (or `Write` if creating fresh).
|
|
83
|
+
|
|
84
|
+
**See also**: [`command-anti-patterns.md`](./command-anti-patterns.md) — shell hygiene, scratch-dir rules, and the /tackle-vs-UAT verification split.
|
|
85
|
+
|
|
86
|
+
---
|
|
87
|
+
|
|
88
|
+
## Serena (Code Exploration & Editing)
|
|
89
|
+
|
|
90
|
+
Serena provides two editing approaches:
|
|
91
|
+
1. **Symbolic** — LSP-powered, refactoring-safe (entire functions/classes)
|
|
92
|
+
2. **File/line-based** — Precise line-range and regex edits (within functions)
|
|
93
|
+
|
|
94
|
+
### Tools
|
|
95
|
+
|
|
96
|
+
**Exploration:**
|
|
97
|
+
|
|
98
|
+
| Tool | Purpose | Key Params |
|
|
99
|
+
|------|---------|------------|
|
|
100
|
+
| `get_symbols_overview` | File structure overview | `relative_path`, `depth` (0=top-level) |
|
|
101
|
+
| `find_symbol` | Find symbols by name | `name_path_pattern`, `include_body`, `depth`, `substring_matching` |
|
|
102
|
+
| `find_referencing_symbols` | Find all callers/references | `name_path`, `relative_path` (file, not dir) |
|
|
103
|
+
| `search_for_pattern` | Regex search across files | `substring_pattern`, `relative_path`, `paths_include_glob` |
|
|
104
|
+
| `list_dir` | List directory contents | `relative_path`, `recursive` |
|
|
105
|
+
| `find_file` | Find files by name/mask | `file_mask`, `relative_path` |
|
|
106
|
+
|
|
107
|
+
**Symbolic editing** (use when replacing entire symbols):
|
|
108
|
+
|
|
109
|
+
| Tool | Purpose | Key Params |
|
|
110
|
+
|------|---------|------------|
|
|
111
|
+
| `replace_symbol_body` | Replace function/class body | `name_path`, `relative_path`, `body` (includes signature, NOT docstring) |
|
|
112
|
+
| `insert_after_symbol` | Add code after a symbol | `name_path`, `relative_path`, `body` |
|
|
113
|
+
| `insert_before_symbol` | Add code before a symbol | `name_path`, `relative_path`, `body` |
|
|
114
|
+
| `rename_symbol` | Rename across codebase | `name_path`, `relative_path`, `new_name` |
|
|
115
|
+
|
|
116
|
+
**File/line editing** (use for precise edits within symbols):
|
|
117
|
+
|
|
118
|
+
| Tool | Purpose | Key Params |
|
|
119
|
+
|------|---------|------------|
|
|
120
|
+
| `replace_content` | Literal or regex replacement | `relative_path`, `mode` (literal/regex), `needle`, `repl` |
|
|
121
|
+
| `replace_lines` | Replace line range | `relative_path`, `start_line`, `end_line`, `content` (0-based) |
|
|
122
|
+
| `delete_lines` | Delete line range | `relative_path`, `start_line`, `end_line` (0-based) |
|
|
123
|
+
| `insert_at_line` | Insert at line number | `relative_path`, `line`, `content` (0-based) |
|
|
124
|
+
|
|
125
|
+
### Name Path Patterns
|
|
126
|
+
|
|
127
|
+
- `"method"` — matches any symbol named "method"
|
|
128
|
+
- `"MyClass/method"` — matches method in MyClass (relative)
|
|
129
|
+
- `"/MyClass/method"` — exact match (absolute)
|
|
130
|
+
- `"MyClass/method[0]"` — specific overload
|
|
131
|
+
|
|
132
|
+
### Workflow
|
|
133
|
+
|
|
134
|
+
```
|
|
135
|
+
1. get_symbols_overview → 2. find_symbol → 3. Edit → 4. find_referencing_symbols
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
### Choosing Edit Mode
|
|
139
|
+
|
|
140
|
+
| Scenario | Use |
|
|
141
|
+
|----------|-----|
|
|
142
|
+
| Replace entire function/method/class | Symbolic: `replace_symbol_body` |
|
|
143
|
+
| Add new method to class | Symbolic: `insert_after_symbol` |
|
|
144
|
+
| Rename across codebase | Symbolic: `rename_symbol` |
|
|
145
|
+
| Edit few lines within large function | File/line: `replace_content` or `replace_lines` |
|
|
146
|
+
| Regex-based replacement | File/line: `replace_content` with `mode="regex"` |
|
|
147
|
+
| Edit doesn't align with symbol boundaries | File/line: `replace_lines` |
|
|
148
|
+
|
|
149
|
+
---
|
|
150
|
+
|
|
151
|
+
## Onboarding & Memory
|
|
152
|
+
|
|
153
|
+
Always run onboarding check when starting work:
|
|
154
|
+
|
|
155
|
+
```python
|
|
156
|
+
mcp__serena__check_onboarding_performed()
|
|
157
|
+
# If not performed:
|
|
158
|
+
mcp__serena__onboarding()
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
### Memory Tools
|
|
162
|
+
|
|
163
|
+
| Tool | Purpose | Key Params |
|
|
164
|
+
|------|---------|------------|
|
|
165
|
+
| `list_memories` | List available memories | `topic` (optional filter, e.g. `"auth"`) |
|
|
166
|
+
| `read_memory` | Read a memory's contents | `memory_name` |
|
|
167
|
+
| `write_memory` | Create a new memory (markdown) | `memory_name`, `content`, `max_chars` (optional) |
|
|
168
|
+
| `edit_memory` | Update existing memory in-place | `memory_name`, `needle`, `repl`, `mode` (`literal` or `regex`), `allow_multiple_occurrences` |
|
|
169
|
+
| `rename_memory` | Rename or move a memory | `old_name`, `new_name` |
|
|
170
|
+
| `delete_memory` | Delete a memory (user permission required) | `memory_name` |
|
|
171
|
+
|
|
172
|
+
### Memory Naming & Organization
|
|
173
|
+
|
|
174
|
+
Use `/` separators to create topic hierarchies:
|
|
175
|
+
|
|
176
|
+
```
|
|
177
|
+
modules/frontend → .serena/memories/modules/frontend.md
|
|
178
|
+
auth/login/logic → .serena/memories/auth/login/logic.md
|
|
179
|
+
global/java/style_guide → shared across all projects
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
- **Project memories**: Stored in `.serena/memories/` within the project
|
|
183
|
+
- **Global memories**: Use `global/` prefix — shared across all projects (only when explicitly instructed)
|
|
184
|
+
- **Topic filtering**: `list_memories(topic="auth")` returns only memories under that topic
|
|
185
|
+
|
|
186
|
+
### When to Write Memories
|
|
187
|
+
|
|
188
|
+
Write memories to persist **non-obvious project knowledge** useful for future tasks:
|
|
189
|
+
|
|
190
|
+
- Architecture decisions and their rationale
|
|
191
|
+
- Integration patterns between modules
|
|
192
|
+
- Naming conventions and project-specific terminology
|
|
193
|
+
- Known gotchas, workarounds, and edge cases
|
|
194
|
+
- Configuration requirements that aren't self-documenting
|
|
195
|
+
|
|
196
|
+
**Do NOT write memories for**:
|
|
197
|
+
- Information already in code comments or docs
|
|
198
|
+
- Temporary task state or debugging notes
|
|
199
|
+
- Easily re-derivable facts (file paths, import lists)
|
|
200
|
+
|
|
201
|
+
### Memory Workflow
|
|
202
|
+
|
|
203
|
+
```
|
|
204
|
+
1. list_memories → discover what exists (filter by topic if needed)
|
|
205
|
+
2. read_memory → check if relevant memory already covers this
|
|
206
|
+
3. write_memory → create new, OR edit_memory → update existing
|
|
207
|
+
4. After implementation → update memories that reference changed code
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
### Best Practices
|
|
211
|
+
|
|
212
|
+
- **Check before writing**: Always `list_memories` then `read_memory` to avoid duplicates
|
|
213
|
+
- **Edit over rewrite**: Use `edit_memory` (literal or regex mode) for targeted updates instead of rewriting entire memories
|
|
214
|
+
- **Keep memories focused**: One topic per memory — split broad memories into topic-specific ones
|
|
215
|
+
- **Update after changes**: When code changes affect documented patterns, update the relevant memories
|
|
216
|
+
- **Meaningful names**: Use descriptive hierarchical names (`api/auth/jwt-flow` not `memory1`)
|
|
217
|
+
- **Review post-onboarding**: After Serena onboarding, review generated memories and refine them
|
|
218
|
+
|
|
219
|
+
---
|