@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,214 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: eval-run
|
|
3
|
+
description: Execute the project's eval suite (golden sets, scenarios, replays), report pass/fail per case, surface regressions, and emit a summary report
|
|
4
|
+
category: executing
|
|
5
|
+
model: claude-sonnet-4-6
|
|
6
|
+
effort: medium
|
|
7
|
+
argument-hint: [optional: stage — golden | scenarios | replay | all]
|
|
8
|
+
disable-model-invocation: false
|
|
9
|
+
user-invocable: true
|
|
10
|
+
---
|
|
11
|
+
**Prereqs:** obey `.docs/guides/mcp-tools.md`.
|
|
12
|
+
|
|
13
|
+
$ARGUMENTS
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
# Eval Run
|
|
18
|
+
|
|
19
|
+
Execute the project's eval suite and produce a structured results report. Supports Stage 1 (golden sets), Stage 2 (labeled scenarios), and Stage 3 (replay fixtures). Stage 4 rubrics and Stage 5 experiments are out of scope for this skill — they require live LLM calls and are gated on human review.
|
|
20
|
+
|
|
21
|
+
**Argument**: optional stage filter (`golden`, `scenarios`, `replay`, or `all`). Defaults to `all` if omitted.
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## Step 1: Locate the eval suite
|
|
26
|
+
|
|
27
|
+
Use Serena to inspect the eval directory:
|
|
28
|
+
|
|
29
|
+
```
|
|
30
|
+
mcp__serena__list_dir("evals", recursive=true)
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Build an inventory:
|
|
34
|
+
|
|
35
|
+
| Directory | Stage | Files | Status |
|
|
36
|
+
|-----------|-------|-------|--------|
|
|
37
|
+
| `evals/golden/` | Stage 1 | N YAML files | found / missing |
|
|
38
|
+
| `evals/scenarios/` | Stage 2 | N YAML files | found / missing |
|
|
39
|
+
| `evals/replays/fixtures/` | Stage 3 | N JSON files | found / missing |
|
|
40
|
+
|
|
41
|
+
If the `evals/` directory does not exist or is empty, stop and tell the user:
|
|
42
|
+
|
|
43
|
+
> No eval suite found. Run `/eval-create` to build the first golden set.
|
|
44
|
+
|
|
45
|
+
---
|
|
46
|
+
|
|
47
|
+
## Step 2: Locate or scaffold the test runner
|
|
48
|
+
|
|
49
|
+
Check whether a test runner script already exists:
|
|
50
|
+
|
|
51
|
+
```
|
|
52
|
+
mcp__serena__find_file("eval_runner*", ".")
|
|
53
|
+
mcp__serena__find_file("run_evals*", ".")
|
|
54
|
+
mcp__serena__find_file("*evals*.sh", ".")
|
|
55
|
+
mcp__serena__find_file("*evals*.py", ".")
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Also check `Makefile` or `package.json` for eval-related targets (`make evals`, `npm run evals`, etc.).
|
|
59
|
+
|
|
60
|
+
**If a runner exists**: execute it using `Bash` and capture stdout/stderr. Parse the output into per-case results (see Step 4).
|
|
61
|
+
|
|
62
|
+
**If no runner exists**: inform the user and offer to scaffold a minimal runner (see Step 3).
|
|
63
|
+
|
|
64
|
+
---
|
|
65
|
+
|
|
66
|
+
## Step 3: Scaffold a minimal runner (only if no runner exists)
|
|
67
|
+
|
|
68
|
+
Ask the user via `AskUserQuestion`:
|
|
69
|
+
|
|
70
|
+
> No eval runner found. Should I scaffold a minimal one?
|
|
71
|
+
> - **Yes — scaffold Python runner** (requires Python 3, PyYAML)
|
|
72
|
+
> - **Yes — scaffold shell runner** (bash, no dependencies)
|
|
73
|
+
> - **No — I will wire up the runner myself**
|
|
74
|
+
|
|
75
|
+
If the user approves scaffolding, create `evals/run_evals.py` (Python) or `evals/run_evals.sh` (shell).
|
|
76
|
+
|
|
77
|
+
The minimal runner must:
|
|
78
|
+
1. Load YAML files from `evals/golden/` (and `evals/scenarios/` if present)
|
|
79
|
+
2. For each case, report:
|
|
80
|
+
- Case ID
|
|
81
|
+
- Which checks passed / failed (tool selection, source citation, must_contain, must_not_contain)
|
|
82
|
+
- Overall PASS / FAIL
|
|
83
|
+
3. Exit with code 0 if all cases pass, non-zero if any fail
|
|
84
|
+
4. Emit a JSON results file to `evals/results/latest.json`
|
|
85
|
+
|
|
86
|
+
**Important**: the scaffolded runner checks YAML structure only (schema validation) — it cannot actually invoke the AI system. Include a prominent comment explaining this:
|
|
87
|
+
|
|
88
|
+
```python
|
|
89
|
+
# NOTE: This runner validates eval case structure (schema + static assertions).
|
|
90
|
+
# To run evals against a live system, integrate your system's invoke() function
|
|
91
|
+
# at the TODO: INTEGRATE comment below.
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Then re-run the scaffolded runner via `Bash` to confirm it executes without errors.
|
|
95
|
+
|
|
96
|
+
---
|
|
97
|
+
|
|
98
|
+
## Step 4: Parse and normalize results
|
|
99
|
+
|
|
100
|
+
Whether from an existing runner or the scaffolded one, normalize results into this structure per case:
|
|
101
|
+
|
|
102
|
+
```
|
|
103
|
+
case_id: "gs-001"
|
|
104
|
+
stage: golden
|
|
105
|
+
status: PASS | FAIL | ERROR | SKIP
|
|
106
|
+
checks:
|
|
107
|
+
tool_selection: pass | fail | n/a
|
|
108
|
+
source_citation: pass | fail | n/a
|
|
109
|
+
must_contain: pass | fail | n/a
|
|
110
|
+
must_not_contain: pass | fail | n/a
|
|
111
|
+
failure_detail: "<which check failed and why, if status=FAIL>"
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
If the runner produced raw output, parse it using `Bash` (grep, awk, jq) as needed.
|
|
115
|
+
|
|
116
|
+
---
|
|
117
|
+
|
|
118
|
+
## Step 5: Diff against baseline
|
|
119
|
+
|
|
120
|
+
Check whether a previous results file exists:
|
|
121
|
+
|
|
122
|
+
```
|
|
123
|
+
mcp__serena__find_file("results.json", "evals/results/")
|
|
124
|
+
mcp__serena__find_file("baseline.json", "evals/results/")
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
If a baseline exists, compute the diff:
|
|
128
|
+
- **Regressions**: cases that were PASS in baseline and are now FAIL
|
|
129
|
+
- **Fixes**: cases that were FAIL in baseline and are now PASS
|
|
130
|
+
- **New cases**: cases with no baseline entry
|
|
131
|
+
- **Removed cases**: cases in baseline no longer present
|
|
132
|
+
|
|
133
|
+
Flag regressions prominently.
|
|
134
|
+
|
|
135
|
+
---
|
|
136
|
+
|
|
137
|
+
## Step 6: Emit results report
|
|
138
|
+
|
|
139
|
+
Print a structured report:
|
|
140
|
+
|
|
141
|
+
### Summary
|
|
142
|
+
|
|
143
|
+
| Metric | Value |
|
|
144
|
+
|--------|-------|
|
|
145
|
+
| Total cases run | N |
|
|
146
|
+
| Passed | N (N%) |
|
|
147
|
+
| Failed | N (N%) |
|
|
148
|
+
| Errors | N |
|
|
149
|
+
| Skipped | N |
|
|
150
|
+
| Regressions vs baseline | N |
|
|
151
|
+
| Fixes vs baseline | N |
|
|
152
|
+
|
|
153
|
+
### Per-stage breakdown
|
|
154
|
+
|
|
155
|
+
| Stage | Cases | Pass | Fail | Pass rate |
|
|
156
|
+
|-------|-------|------|------|-----------|
|
|
157
|
+
| Stage 1 — Golden | N | N | N | N% |
|
|
158
|
+
| Stage 2 — Scenarios | N | N | N | N% |
|
|
159
|
+
| Stage 3 — Replay | N | N | N | N% |
|
|
160
|
+
|
|
161
|
+
### Regressions (if any)
|
|
162
|
+
|
|
163
|
+
List each regression case with:
|
|
164
|
+
- Case ID and query
|
|
165
|
+
- Which check failed
|
|
166
|
+
- Failure detail
|
|
167
|
+
|
|
168
|
+
### Failures (non-regression)
|
|
169
|
+
|
|
170
|
+
List each failing case with failure detail.
|
|
171
|
+
|
|
172
|
+
### Coverage matrix (Stage 2, if scenarios exist)
|
|
173
|
+
|
|
174
|
+
If labeled scenarios are present, emit a `category × difficulty` pass-rate matrix:
|
|
175
|
+
|
|
176
|
+
```
|
|
177
|
+
| straightforward | ambiguous | edge_case |
|
|
178
|
+
------------------|-----------------|-----------|-----------|
|
|
179
|
+
vector_search | 3/3 | 1/2 | 1/1 |
|
|
180
|
+
sql_query | 2/3 | 1/1 | -- |
|
|
181
|
+
multi_tool | 1/1 | 0/1 | -- |
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
Empty cells indicate missing test coverage — flag them.
|
|
185
|
+
|
|
186
|
+
---
|
|
187
|
+
|
|
188
|
+
## Step 7: Save results
|
|
189
|
+
|
|
190
|
+
Write `evals/results/latest.json` with the full per-case results. If a baseline file exists, archive it to `evals/results/YYYY-MM-DD-baseline.json` before overwriting.
|
|
191
|
+
|
|
192
|
+
---
|
|
193
|
+
|
|
194
|
+
## Step 8: Gate and next steps
|
|
195
|
+
|
|
196
|
+
Print a final gate verdict:
|
|
197
|
+
|
|
198
|
+
- **GREEN** — all golden cases pass (regressions = 0): safe to ship
|
|
199
|
+
- **YELLOW** — golden cases pass but scenario pass-rate dropped: review before shipping
|
|
200
|
+
- **RED** — one or more golden cases fail or regressions detected: do not ship
|
|
201
|
+
|
|
202
|
+
Suggest next steps based on results:
|
|
203
|
+
- Failures → "Investigate failing cases. Use `/eval-gap` to see if new coverage is needed or if the system regressed."
|
|
204
|
+
- Empty coverage cells → "Use `/eval-create` to add cases for uncovered categories."
|
|
205
|
+
- No rubric yet → "Consider adding Stage 4 rubrics for quality scoring. Use `/eval-create rubric` to start."
|
|
206
|
+
|
|
207
|
+
---
|
|
208
|
+
|
|
209
|
+
## CRITICAL rules
|
|
210
|
+
|
|
211
|
+
1. **Never invoke the live AI system** unless the project has an existing eval runner that does so explicitly. The scaffolded runner is schema-only.
|
|
212
|
+
2. **Regressions always surface in the report** — never silently omit a case that was passing before.
|
|
213
|
+
3. **Exit code matters**: if running via CI, the runner must exit non-zero on any golden set failure. Note this in the report.
|
|
214
|
+
4. **Never overwrite baseline.json** without archiving the old one first.
|
|
@@ -0,0 +1,344 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: extract-feature
|
|
3
|
+
description: Analyze a feature in the current project and produce a SOLID-compliant standalone module extraction plan with interfaces for all dependencies; output is compatible with /port-feature
|
|
4
|
+
category: planning
|
|
5
|
+
model: claude-opus-4-8
|
|
6
|
+
effort: high
|
|
7
|
+
argument-hint: <feature name or description>
|
|
8
|
+
disable-model-invocation: false
|
|
9
|
+
user-invocable: true
|
|
10
|
+
---
|
|
11
|
+
**Prereqs:** obey `.docs/guides/mcp-tools.md`; run /primer if not done this session.
|
|
12
|
+
|
|
13
|
+
# Extract Feature
|
|
14
|
+
|
|
15
|
+
Analyze a specific feature or area of functionality in the **current project**, design a SOLID-compliant standalone module for it, and produce a concrete extraction plan. Every dependency (database, HTTP client, config, internal services, event bus) is replaced with an interface contract, so the extracted module can be plugged into any host project and its adapters swapped independently.
|
|
16
|
+
|
|
17
|
+
The output document is formatted to be a valid "source project" for `/port-feature` — once the module is extracted, another team can port it into their project using `/port-feature <extracted-module-path> <feature-name>` without any reformatting.
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
**Arguments**: $ARGUMENTS
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## Phase 0: Parse Arguments & Validate
|
|
26
|
+
|
|
27
|
+
1. **Parse `$ARGUMENTS`**:
|
|
28
|
+
- Everything in `$ARGUMENTS` is the `<feature>` description — free-form name or description of the feature to extract
|
|
29
|
+
- Examples: `user authentication`, `email notification service`, `report generation`, `payment processing`
|
|
30
|
+
|
|
31
|
+
2. **Validate**:
|
|
32
|
+
- If `<feature>` is empty or too vague to locate in code: stop and ask the user for a more specific description
|
|
33
|
+
- The description must be specific enough to search for in the codebase (service names, module names, domain concepts)
|
|
34
|
+
|
|
35
|
+
3. **Clarifying questions** — ask before proceeding if any are ambiguous:
|
|
36
|
+
- **Output location**: Should the extracted module live as a subdirectory within this project (e.g., `packages/<module-name>/`) or as a stub for a new standalone repo? (Default: subdirectory)
|
|
37
|
+
- **Constraints**: Any hard constraints — must stay in the same language, no new dependencies, must preserve the current public API for backward compatibility?
|
|
38
|
+
- **Supplementary output**: Should this skill also create a task file in `wiki/work/tasks/` to track the actual extraction work? (Default: yes, suggest it)
|
|
39
|
+
|
|
40
|
+
---
|
|
41
|
+
|
|
42
|
+
## Phase 1: Research
|
|
43
|
+
|
|
44
|
+
Run the `/research` workflow before touching the codebase. The goal is to arrive at Phase 2 armed with the right vocabulary, patterns, and interface design options for this feature type.
|
|
45
|
+
|
|
46
|
+
**Research topics to cover** (combine into one `/research` invocation):
|
|
47
|
+
|
|
48
|
+
1. **Modularization patterns** for this feature type (e.g., "authentication module SOLID design patterns", "notification service hexagonal architecture")
|
|
49
|
+
2. **Interface design** for the dependency categories the feature likely uses:
|
|
50
|
+
- Data access / repository pattern for the detected language/framework
|
|
51
|
+
- External HTTP client abstraction patterns
|
|
52
|
+
- Configuration injection patterns (env-based vs config-object)
|
|
53
|
+
- Event/message bus decoupling if the feature emits or consumes events
|
|
54
|
+
3. **Packaging conventions** for the detected language (e.g., TypeScript `package.json` `exports` field, Python `pyproject.toml` `packages`, Go module layout)
|
|
55
|
+
4. **Library documentation** (via Context7): query docs for any key third-party libraries the feature uses, specifically their interface/adapter extension points
|
|
56
|
+
|
|
57
|
+
Use the research findings as the lens for all architectural decisions in Phase 4. Do not proceed without completing this research phase.
|
|
58
|
+
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
## Phase 2: Discover the Feature in the Codebase
|
|
62
|
+
|
|
63
|
+
**CRITICAL**: Use Serena for ALL current-project code exploration. No `bash ls`, `cat`, `find`, `grep`, or `Read` on code files.
|
|
64
|
+
|
|
65
|
+
### 2a. Recall Context
|
|
66
|
+
|
|
67
|
+
- `mcp__serena__list_memories` → scan for memories related to the feature area (use `topic` filter)
|
|
68
|
+
- `mcp__serena__read_memory` on any relevant memories for architectural constraints, known coupling issues, or prior extraction attempts
|
|
69
|
+
- Check `wiki/work/decisions/` for accepted decisions that constrain how this feature may be restructured
|
|
70
|
+
|
|
71
|
+
### 2b. Locate the Feature
|
|
72
|
+
|
|
73
|
+
Search for all code related to `<feature>`:
|
|
74
|
+
|
|
75
|
+
1. **Symbol search**: `mcp__serena__find_symbol` with name patterns derived from the feature description (e.g., for "auth": `AuthService`, `authenticate`, `AuthMiddleware`, `JwtStrategy`)
|
|
76
|
+
2. **Directory overview**: `mcp__serena__get_symbols_overview` on the most likely directories (e.g., `src/auth/`, `src/services/`, `lib/`)
|
|
77
|
+
3. **Pattern search**: `mcp__serena__search_for_pattern` for import paths, config key names, and env var references
|
|
78
|
+
4. **Reference tracing**: `mcp__serena__find_referencing_symbols` on all discovered entry-point symbols to map every caller
|
|
79
|
+
|
|
80
|
+
### 2c. Trace Data Flow
|
|
81
|
+
|
|
82
|
+
For each discovered entry point, trace:
|
|
83
|
+
|
|
84
|
+
- **Inbound**: Who calls this (controllers, CLI, event consumers, tests)?
|
|
85
|
+
- **Outbound**: What does it call (DB queries, external HTTP, other services, config reads)?
|
|
86
|
+
- **Data models**: What types/schemas/interfaces flow through the feature?
|
|
87
|
+
- **Side effects**: Events emitted, files written, queues published to, metrics recorded?
|
|
88
|
+
|
|
89
|
+
### 2d. Map Coupling Points
|
|
90
|
+
|
|
91
|
+
Classify every dependency the feature touches:
|
|
92
|
+
|
|
93
|
+
| Dependency | File / Symbol | Category | Notes |
|
|
94
|
+
|------------|--------------|----------|-------|
|
|
95
|
+
| `UserRepository` | `src/db/user.repo.ts` | `infra` (DB) | Direct Prisma/Sequelize calls |
|
|
96
|
+
| `MailerService` | `src/mailer/mailer.service.ts` | `internal-coupling` | Feature imports this directly |
|
|
97
|
+
| `process.env.JWT_SECRET` | scattered | `config` | Read inline, not injected |
|
|
98
|
+
| `fetch` / `axios` | `src/auth/oauth.ts` | `direct-external` | Third-party HTTP |
|
|
99
|
+
|
|
100
|
+
Categories:
|
|
101
|
+
- **`infra`** — database, cache, queue, storage (must become a repository/store interface)
|
|
102
|
+
- **`direct-external`** — third-party library calls inlined in feature logic (must become an adapter interface)
|
|
103
|
+
- **`internal-coupling`** — other modules in this project the feature imports (must become interfaces or be absorbed into the module)
|
|
104
|
+
- **`config`** — env vars and config reads (must become an injected config interface)
|
|
105
|
+
- **`framework`** — router decorators, DI container bindings, middleware (must be documented as wiring requirements, not core logic)
|
|
106
|
+
|
|
107
|
+
---
|
|
108
|
+
|
|
109
|
+
## Phase 3: Build Source Feature Inventory
|
|
110
|
+
|
|
111
|
+
Produce the Source Feature Inventory in the exact format `/port-feature` Phase 1c expects, so the extracted module is immediately usable as a port source:
|
|
112
|
+
|
|
113
|
+
```
|
|
114
|
+
SOURCE FEATURE: <feature name>
|
|
115
|
+
Language / Runtime: <language + version>
|
|
116
|
+
Frameworks / Libraries used by this feature:
|
|
117
|
+
- <lib>: <role>
|
|
118
|
+
Entry points:
|
|
119
|
+
- <file:line> — <description>
|
|
120
|
+
Core files:
|
|
121
|
+
- <file> — <responsibility>
|
|
122
|
+
Data models / types:
|
|
123
|
+
- <name> — <shape and purpose>
|
|
124
|
+
External dependencies (infra/services):
|
|
125
|
+
- <infra item> — <how it's used>
|
|
126
|
+
Internal coupling (must become interfaces):
|
|
127
|
+
- <module/file> — <what the feature takes from it>
|
|
128
|
+
Configuration:
|
|
129
|
+
- <env var / config key> — <purpose>
|
|
130
|
+
Test coverage:
|
|
131
|
+
- <test file> — <what it covers>
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
The **Internal coupling** section is the critical addition over the standard `/port-feature` inventory — these are the coupling points that **must** become interface contracts.
|
|
135
|
+
|
|
136
|
+
---
|
|
137
|
+
|
|
138
|
+
## Phase 4: Design Extraction Architecture
|
|
139
|
+
|
|
140
|
+
With the coupling map from Phase 2d and the research from Phase 1, design the standalone module.
|
|
141
|
+
|
|
142
|
+
### 4a. Interface Specification
|
|
143
|
+
|
|
144
|
+
For **every** `infra`, `direct-external`, `internal-coupling`, and `config` dependency, produce an interface contract:
|
|
145
|
+
|
|
146
|
+
| Dependency | Current Form | Interface Name | Required Methods / Fields | Adapter Strategy | Notes |
|
|
147
|
+
|------------|-------------|----------------|--------------------------|-----------------|-------|
|
|
148
|
+
| `UserRepository` | Prisma client | `IUserRepository` | `findById(id)`, `save(user)` | Thin Prisma adapter in `adapters/` | Keep in module |
|
|
149
|
+
| `MailerService` | Injected service | `IMailer` | `send(to, subject, body)` | Adapter in host project | Don't bundle host dep |
|
|
150
|
+
| `process.env.JWT_SECRET` | Inline read | `AuthConfig` | `{ jwtSecret: string, ttl: number }` | Config object injected at construction | — |
|
|
151
|
+
|
|
152
|
+
**SOLID enforcement rules**:
|
|
153
|
+
- **SRP**: One interface per concern — no combining "user repo + mailer" into one interface
|
|
154
|
+
- **OCP**: Core logic must reference only interface types; if adding a new adapter doesn't require touching `core/`, it's open/closed
|
|
155
|
+
- **LSP**: Every interface method must be implementable by any reasonable adapter (no leaky concrete details in the interface signature)
|
|
156
|
+
- **ISP**: If a consumer only needs 2 of 5 repository methods, split into a focused read-interface and write-interface
|
|
157
|
+
- **DIP**: `core/` imports from `interfaces/` only — never from `adapters/` or host project modules
|
|
158
|
+
|
|
159
|
+
### 4b. Proposed Module Structure
|
|
160
|
+
|
|
161
|
+
```
|
|
162
|
+
<kebab-feature-name>/
|
|
163
|
+
src/
|
|
164
|
+
core/ # pure domain logic — imports only from interfaces/ and language stdlib
|
|
165
|
+
interfaces/ # TypeScript interfaces / Python ABCs / Go interfaces — zero implementation
|
|
166
|
+
adapters/ # optional concrete implementations bundled with the module
|
|
167
|
+
index.ts # public API: exports factory function(s) that accept interface implementations
|
|
168
|
+
tests/
|
|
169
|
+
unit/ # tests against core/ with mock adapters
|
|
170
|
+
integration/ # optional — tests against real adapters
|
|
171
|
+
README.md # Source Feature Inventory (this exact document) — port-feature reads this
|
|
172
|
+
package.json # (or pyproject.toml / go.mod / Cargo.toml)
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
`index.ts` example signature:
|
|
176
|
+
```ts
|
|
177
|
+
export function createFeature(deps: {
|
|
178
|
+
userRepo: IUserRepository;
|
|
179
|
+
mailer: IMailer;
|
|
180
|
+
config: FeatureConfig;
|
|
181
|
+
}): FeaturePublicAPI { ... }
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
### 4c. Technology Mapping
|
|
185
|
+
|
|
186
|
+
For each current implementation pattern, state the equivalent in the extracted module:
|
|
187
|
+
|
|
188
|
+
| Current Pattern | Current File | Module Equivalent | Adaptation Required |
|
|
189
|
+
|----------------|-------------|------------------|---------------------|
|
|
190
|
+
| `@Injectable()` class | `auth.service.ts` | Plain class constructor | Remove DI decorator |
|
|
191
|
+
| Prisma `this.prisma.user.findUnique` | `user.repo.ts` | `IUserRepository.findById` | Wrap in thin adapter |
|
|
192
|
+
| `process.env.JWT_SECRET` | inline | `AuthConfig.jwtSecret` | Pass config at construction |
|
|
193
|
+
|
|
194
|
+
---
|
|
195
|
+
|
|
196
|
+
## Phase 5: Gap Analysis
|
|
197
|
+
|
|
198
|
+
Before extraction is safe, identify what must change:
|
|
199
|
+
|
|
200
|
+
### 5a. Current-Project Changes After Extraction
|
|
201
|
+
|
|
202
|
+
- Which files in the current project will need to update their imports to point to the new module path?
|
|
203
|
+
- Which DI container registrations / wiring files need updating?
|
|
204
|
+
- Which config files or env var docs need updating?
|
|
205
|
+
|
|
206
|
+
### 5b. Missing Test Coverage
|
|
207
|
+
|
|
208
|
+
List any behavior that lacks tests and must be covered before the feature can be safely extracted (extraction without tests = no safety net during the refactor):
|
|
209
|
+
|
|
210
|
+
| Behavior | Currently tested? | Risk if untested |
|
|
211
|
+
|----------|-------------------|-----------------|
|
|
212
|
+
| <behavior> | No | High — could break silently during adapter swap |
|
|
213
|
+
|
|
214
|
+
### 5c. Complexity Classification
|
|
215
|
+
|
|
216
|
+
Classify each source file by porting effort:
|
|
217
|
+
|
|
218
|
+
| File | Effort | Reason |
|
|
219
|
+
|------|:------:|--------|
|
|
220
|
+
| `<file>` | **Direct** | Pure logic, no framework coupling — copy as-is |
|
|
221
|
+
| `<file>` | **Adapt** | Framework decorator must be removed; logic preserved |
|
|
222
|
+
| `<file>` | **Rewrite** | Tightly coupled; must be expressed as interface + adapter |
|
|
223
|
+
| `<file>` | **Skip** | Already framework-only wiring — lives in host project |
|
|
224
|
+
|
|
225
|
+
---
|
|
226
|
+
|
|
227
|
+
## Phase 6: Write the Extraction Plan
|
|
228
|
+
|
|
229
|
+
### 6a. Write the Plan File
|
|
230
|
+
|
|
231
|
+
Write to `.docs/extract/<kebab-feature-name>.md`:
|
|
232
|
+
|
|
233
|
+
```markdown
|
|
234
|
+
---
|
|
235
|
+
feature: <feature name>
|
|
236
|
+
extracted-from: <absolute path of current project>
|
|
237
|
+
assessed: <YYYY-MM-DD>
|
|
238
|
+
effort: <Low / Medium / High / Very High>
|
|
239
|
+
status: draft
|
|
240
|
+
solid-compliant: true
|
|
241
|
+
proposed-module-path: <packages/<module-name> OR external repo name>
|
|
242
|
+
---
|
|
243
|
+
|
|
244
|
+
# Extraction Plan: <Feature Name>
|
|
245
|
+
|
|
246
|
+
> **Feature**: <feature description>
|
|
247
|
+
> **Extracted from**: `<absolute project path>`
|
|
248
|
+
> **Proposed module**: `<module path>`
|
|
249
|
+
> **Overall effort**: <Low / Medium / High / Very High>
|
|
250
|
+
> **Summary**: <One sentence on what this extraction involves.>
|
|
251
|
+
|
|
252
|
+
## Source Feature Inventory
|
|
253
|
+
|
|
254
|
+
<Phase 3 inventory — this section is read by /port-feature when this module is the source>
|
|
255
|
+
|
|
256
|
+
## Coupling Analysis
|
|
257
|
+
|
|
258
|
+
<Phase 2d coupling map table>
|
|
259
|
+
|
|
260
|
+
## Interface Specifications
|
|
261
|
+
|
|
262
|
+
<Phase 4a interface table>
|
|
263
|
+
|
|
264
|
+
## Proposed Module Structure
|
|
265
|
+
|
|
266
|
+
<Phase 4b directory tree with annotations>
|
|
267
|
+
|
|
268
|
+
## Technology Mapping
|
|
269
|
+
|
|
270
|
+
<Phase 4c table>
|
|
271
|
+
|
|
272
|
+
## Complexity Breakdown
|
|
273
|
+
|
|
274
|
+
<Phase 5c table>
|
|
275
|
+
|
|
276
|
+
## Gap Analysis
|
|
277
|
+
|
|
278
|
+
<Phase 5a current-project changes + 5b missing test coverage>
|
|
279
|
+
|
|
280
|
+
## Extraction Steps
|
|
281
|
+
|
|
282
|
+
Ordered, dependency-respecting steps. Each step is concrete and actionable.
|
|
283
|
+
|
|
284
|
+
### Step 1: <title>
|
|
285
|
+
|
|
286
|
+
**Effort**: <Direct / Adapt / Rewrite>
|
|
287
|
+
**Files affected**:
|
|
288
|
+
- `<source file>` — extract to `<target file>` (create / move / refactor)
|
|
289
|
+
|
|
290
|
+
**What to do**:
|
|
291
|
+
<Specific instructions: what to move, what to strip, what interface to introduce, what adapter to write>
|
|
292
|
+
|
|
293
|
+
**Definition of done**: <How to know this step is complete — tests pass, imports resolve, no references to old path>
|
|
294
|
+
|
|
295
|
+
---
|
|
296
|
+
|
|
297
|
+
### Step 2: <title>
|
|
298
|
+
|
|
299
|
+
… (repeat for each step)
|
|
300
|
+
|
|
301
|
+
---
|
|
302
|
+
|
|
303
|
+
## Suggested Next Actions
|
|
304
|
+
|
|
305
|
+
- To create a task from this plan: `/task-add "Extract <feature name> into standalone module"`
|
|
306
|
+
- To port this module into another project after extraction: `/port-feature <proposed-module-path> <feature name>`
|
|
307
|
+
- If an interface decision is still open: <frame the specific decision clearly>
|
|
308
|
+
```
|
|
309
|
+
|
|
310
|
+
### 6b. Optionally Create a Task File
|
|
311
|
+
|
|
312
|
+
If the user requested a task file (or the plan is concrete enough to execute immediately):
|
|
313
|
+
|
|
314
|
+
```
|
|
315
|
+
/task-add "Extract <feature name> into standalone module"
|
|
316
|
+
```
|
|
317
|
+
|
|
318
|
+
Include the extraction plan path as context in the task.
|
|
319
|
+
|
|
320
|
+
---
|
|
321
|
+
|
|
322
|
+
## Phase 7: Report to User
|
|
323
|
+
|
|
324
|
+
After writing the plan file:
|
|
325
|
+
|
|
326
|
+
1. State the path written: `.docs/extract/<kebab-feature-name>.md`
|
|
327
|
+
2. Give a one-line effort verdict (e.g., "High effort — 3 interfaces to design, 2 rewrites, 1 missing test suite")
|
|
328
|
+
3. List the top 3 extraction steps in brief
|
|
329
|
+
4. Call out the single biggest coupling risk or blocker
|
|
330
|
+
5. Suggest the most useful next action (task creation, interface decision to make, or `/port-feature` handoff)
|
|
331
|
+
|
|
332
|
+
---
|
|
333
|
+
|
|
334
|
+
## CRITICAL Rules
|
|
335
|
+
|
|
336
|
+
1. **Serena for the current project only** — all current-project code exploration must use Serena tools; no Bash `ls`/`cat`/`find`/`grep` on current project code files
|
|
337
|
+
2. **Research first** — Phase 1 (`/research`) must complete before Phase 4 interface design; never design interfaces from intuition alone
|
|
338
|
+
3. **No speculation** — every coupling point listed must be grounded in what you actually read from the codebase (Serena tool results), not assumed
|
|
339
|
+
4. **Interfaces for everything** — every `infra`, `direct-external`, `internal-coupling`, and `config` dependency must have a corresponding interface in the plan; none may be left as a concrete import in the extracted module's `core/`
|
|
340
|
+
5. **SOLID enforced** — each SOLID principle (SRP, OCP, LSP, ISP, DIP) must be explicitly addressed in Phase 4a; call out any violations with a mitigation
|
|
341
|
+
6. **port-feature compatibility** — Phase 3 inventory must match exactly the format `/port-feature` Phase 1c expects; the `.docs/extract/` document must be usable as a "source project" spec
|
|
342
|
+
7. **Brave Search rate limit** — 50 requests/second, parallel searches allowed (applies during Phase 1 research)
|
|
343
|
+
8. **Maximum 3 concurrent sub-processes** at a time
|
|
344
|
+
9. **Always terminate all processes when done** (dev servers, type checkers, long-running commands)
|