@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.
Files changed (186) hide show
  1. package/.github/workflows/build.yml +88 -0
  2. package/.github/workflows/security.yml +24 -0
  3. package/.gitleaks.toml +15 -0
  4. package/README.md +472 -0
  5. package/bin/cli.js +47 -0
  6. package/lib/README.md +27 -0
  7. package/lib/hooks/README.md +316 -0
  8. package/lib/hooks/env-file-guard.js +45 -0
  9. package/lib/hooks/git-protected-ops-block.js +77 -0
  10. package/lib/hooks/lib/serena-languages.js +158 -0
  11. package/lib/hooks/lib/serena.js +787 -0
  12. package/lib/hooks/mv-absolute-path-block.js +53 -0
  13. package/lib/hooks/serena-bash-grep-block.js +501 -0
  14. package/lib/hooks/serena-edit-guard.js +74 -0
  15. package/lib/hooks/serena-first-glob-guard.js +94 -0
  16. package/lib/hooks/serena-first-guard.js +74 -0
  17. package/lib/hooks/serena-first-read-guard.js +167 -0
  18. package/lib/hooks/serena-pre-delegation.js +117 -0
  19. package/lib/hooks/serena-session-reset.js +45 -0
  20. package/lib/hooks/serena-usage-tracker.js +186 -0
  21. package/lib/hooks/serena-write-guard.js +58 -0
  22. package/lib/prompts/README.md +16 -0
  23. package/lib/prompts/migrate-wiki.md +111 -0
  24. package/lib/prompts/setup-deployment.md +322 -0
  25. package/lib/prompts/setup-design-system.md +162 -0
  26. package/lib/prompts/setup-strict-typechecks.md +139 -0
  27. package/lib/scripts/README.md +49 -0
  28. package/lib/scripts/bootstrap-serena.sh +145 -0
  29. package/lib/scripts/build-mcp-guide.sh +108 -0
  30. package/lib/scripts/install-global.sh +78 -0
  31. package/lib/scripts/install-mcps.sh +131 -0
  32. package/lib/scripts/lib.sh +154 -0
  33. package/lib/scripts/merge-gitignore.sh +65 -0
  34. package/lib/scripts/migrate-project.sh +273 -0
  35. package/lib/scripts/setup-deployment.sh +104 -0
  36. package/lib/scripts/setup-project.sh +55 -0
  37. package/lib/scripts/setup-runner.sh +99 -0
  38. package/lib/scripts/setup-strict-typechecks.sh +29 -0
  39. package/lib/scripts/startup.sh +42 -0
  40. package/lib/scripts/sync-wiki-scaffold.sh +104 -0
  41. package/lib/scripts/templates/CLAUDE-env-safety.md +3 -0
  42. package/lib/scripts/templates/CLAUDE-wiki.md +60 -0
  43. package/lib/scripts/templates/gitignore +136 -0
  44. package/lib/scripts/templates/guides/stubs/00-header.md +15 -0
  45. package/lib/scripts/templates/guides/stubs/brave-search.md +20 -0
  46. package/lib/scripts/templates/guides/stubs/context7.md +26 -0
  47. package/lib/scripts/templates/guides/stubs/playwright.md +26 -0
  48. package/lib/scripts/templates/guides/stubs/serena.md +219 -0
  49. package/lib/scripts/templates/wiki/conventions.md +100 -0
  50. package/lib/scripts/templates/wiki/dashboard.html +1733 -0
  51. package/lib/scripts/templates/wiki/hot.md +21 -0
  52. package/lib/scripts/templates/wiki/index.md +46 -0
  53. package/lib/scripts/templates/wiki/knowledge/concepts/.gitkeep +0 -0
  54. package/lib/scripts/templates/wiki/knowledge/entities/components/.gitkeep +0 -0
  55. package/lib/scripts/templates/wiki/knowledge/entities/organisations/.gitkeep +0 -0
  56. package/lib/scripts/templates/wiki/knowledge/entities/people/.gitkeep +0 -0
  57. package/lib/scripts/templates/wiki/knowledge/entities/tools/.gitkeep +0 -0
  58. package/lib/scripts/templates/wiki/knowledge/sources/.gitkeep +0 -0
  59. package/lib/scripts/templates/wiki/log.md +14 -0
  60. package/lib/scripts/templates/wiki/work/bugs/.gitkeep +0 -0
  61. package/lib/scripts/templates/wiki/work/bugs/archive/index.md +6 -0
  62. package/lib/scripts/templates/wiki/work/bugs/index.md +12 -0
  63. package/lib/scripts/templates/wiki/work/bugs/lifecycle.md +39 -0
  64. package/lib/scripts/templates/wiki/work/decisions/.gitkeep +0 -0
  65. package/lib/scripts/templates/wiki/work/decisions/archive/index.md +6 -0
  66. package/lib/scripts/templates/wiki/work/decisions/index.md +12 -0
  67. package/lib/scripts/templates/wiki/work/decisions/lifecycle.md +42 -0
  68. package/lib/scripts/templates/wiki/work/requirements/.gitkeep +0 -0
  69. package/lib/scripts/templates/wiki/work/requirements/archive/index.md +6 -0
  70. package/lib/scripts/templates/wiki/work/requirements/index.md +12 -0
  71. package/lib/scripts/templates/wiki/work/requirements/lifecycle.md +34 -0
  72. package/lib/scripts/templates/wiki/work/roadmaps/.gitkeep +0 -0
  73. package/lib/scripts/templates/wiki/work/roadmaps/archive/index.md +6 -0
  74. package/lib/scripts/templates/wiki/work/roadmaps/index.md +12 -0
  75. package/lib/scripts/templates/wiki/work/roadmaps/lifecycle.md +32 -0
  76. package/lib/scripts/templates/wiki/work/tasks/.gitkeep +0 -0
  77. package/lib/scripts/templates/wiki/work/tasks/archive/index.md +6 -0
  78. package/lib/scripts/templates/wiki/work/tasks/index.md +12 -0
  79. package/lib/scripts/templates/wiki/work/tasks/lifecycle.md +39 -0
  80. package/lib/scripts/templates/wiki/work/uat/.gitkeep +0 -0
  81. package/lib/scripts/templates/wiki/work/uat/archive/index.md +6 -0
  82. package/lib/scripts/templates/wiki/work/uat/index.md +12 -0
  83. package/lib/scripts/templates/wiki/work/uat/lifecycle.md +48 -0
  84. package/lib/scripts/templates/wiki/work/uat/screenshots/.gitkeep +0 -0
  85. package/lib/scripts/update-project.sh +75 -0
  86. package/lib/scripts/wiki-dashboard-server.js +146 -0
  87. package/lib/skills/README.md +146 -0
  88. package/lib/skills/anti-slop/SKILL.md +183 -0
  89. package/lib/skills/bug-close/SKILL.md +136 -0
  90. package/lib/skills/bug-file/SKILL.md +114 -0
  91. package/lib/skills/bug-triage/SKILL.md +140 -0
  92. package/lib/skills/company-align/SKILL.md +203 -0
  93. package/lib/skills/debug-logs/SKILL.md +129 -0
  94. package/lib/skills/decision-create/SKILL.md +220 -0
  95. package/lib/skills/decision-finalize/SKILL.md +181 -0
  96. package/lib/skills/decision-next/SKILL.md +129 -0
  97. package/lib/skills/decision-walkthrough/SKILL.md +169 -0
  98. package/lib/skills/demo/SKILL.md +183 -0
  99. package/lib/skills/elevator-pitch/SKILL.md +125 -0
  100. package/lib/skills/eval-create/SKILL.md +344 -0
  101. package/lib/skills/eval-gap/SKILL.md +150 -0
  102. package/lib/skills/eval-run/SKILL.md +214 -0
  103. package/lib/skills/extract-feature/SKILL.md +344 -0
  104. package/lib/skills/flashcard/SKILL.md +513 -0
  105. package/lib/skills/frontend-taste/SKILL.md +184 -0
  106. package/lib/skills/gap-assess/SKILL.md +97 -0
  107. package/lib/skills/git-commit/SKILL.md +164 -0
  108. package/lib/skills/lint/SKILL.md +99 -0
  109. package/lib/skills/marp-slideshow/SKILL.md +212 -0
  110. package/lib/skills/mermaid-flowchart/SKILL.md +194 -0
  111. package/lib/skills/now/SKILL.md +36 -0
  112. package/lib/skills/port-feature/SKILL.md +315 -0
  113. package/lib/skills/power-mode/SKILL.md +184 -0
  114. package/lib/skills/primer/SKILL.md +84 -0
  115. package/lib/skills/project-readme/SKILL.md +166 -0
  116. package/lib/skills/req-compile/SKILL.md +131 -0
  117. package/lib/skills/req-create/SKILL.md +124 -0
  118. package/lib/skills/req-extract-decisions/SKILL.md +241 -0
  119. package/lib/skills/req-finalize/SKILL.md +251 -0
  120. package/lib/skills/req-retire/SKILL.md +185 -0
  121. package/lib/skills/req-update/SKILL.md +265 -0
  122. package/lib/skills/research/SKILL.md +250 -0
  123. package/lib/skills/research-company/SKILL.md +345 -0
  124. package/lib/skills/roadmap-add/SKILL.md +238 -0
  125. package/lib/skills/roadmap-create/SKILL.md +223 -0
  126. package/lib/skills/roadmap-next/SKILL.md +132 -0
  127. package/lib/skills/security-audit/SKILL.md +246 -0
  128. package/lib/skills/serena-config/SKILL.md +92 -0
  129. package/lib/skills/simplify/SKILL.md +227 -0
  130. package/lib/skills/tackle/SKILL.md +156 -0
  131. package/lib/skills/task-add/SKILL.md +208 -0
  132. package/lib/skills/task-audit/SKILL.md +294 -0
  133. package/lib/skills/task-trash/SKILL.md +115 -0
  134. package/lib/skills/task-update/SKILL.md +136 -0
  135. package/lib/skills/uat-auto/SKILL.md +69 -0
  136. package/lib/skills/uat-auto-plus/SKILL.md +115 -0
  137. package/lib/skills/uat-generate/SKILL.md +289 -0
  138. package/lib/skills/uat-skip/SKILL.md +169 -0
  139. package/lib/skills/uat-walk/SKILL.md +164 -0
  140. package/lib/skills/uat-walk/UAT-CORE.md +140 -0
  141. package/lib/skills/update-docs/SKILL.md +75 -0
  142. package/lib/skills/wiki-archive/SKILL.md +96 -0
  143. package/lib/skills/wiki-ingest/SKILL.md +139 -0
  144. package/lib/skills/wiki-lint/SKILL.md +131 -0
  145. package/lib/skills/wiki-query/SKILL.md +71 -0
  146. package/lib/skills/wiki-rotate-log/SKILL.md +90 -0
  147. package/lib/skills/wiki-tidy/SKILL.md +107 -0
  148. package/package.json +32 -0
  149. package/raw/.gitkeep +0 -0
  150. package/raw/design-principles.md +65 -0
  151. package/raw/guides/command-anti-patterns.md +79 -0
  152. package/raw/guides/deployment-strategy.md +448 -0
  153. package/raw/guides/evals-framework.md +452 -0
  154. package/raw/guides/mcp-tools.md +335 -0
  155. package/raw/guides/task-spec.md +79 -0
  156. package/raw/guides/type-checking-templates/README.md +112 -0
  157. package/raw/guides/type-checking-templates/eslint/eslint.config.ts +105 -0
  158. package/raw/guides/type-checking-templates/python/mypy.ini +69 -0
  159. package/raw/guides/type-checking-templates/python/pyproject.toml +164 -0
  160. package/raw/guides/type-checking-templates/python/pyrightconfig.json +67 -0
  161. package/raw/guides/type-checking-templates/tsconfig/tsconfig.app.jsonc +45 -0
  162. package/raw/guides/type-checking-templates/tsconfig/tsconfig.lib.jsonc +44 -0
  163. package/raw/guides/type-checking-templates/tsconfig/tsconfig.node-esm.jsonc +40 -0
  164. package/raw/guides/type-checking-templates/tsconfig/tsconfig.node.jsonc +34 -0
  165. package/raw/guides/type-checking-templates/tsconfig/tsconfig.vite-root.json +8 -0
  166. package/raw/harness-notes.md +20 -0
  167. package/raw/house-style/components/Badge.tsx +16 -0
  168. package/raw/house-style/components/Button.tsx +32 -0
  169. package/raw/house-style/components/Card.tsx +26 -0
  170. package/raw/house-style/components/Chip.tsx +57 -0
  171. package/raw/house-style/components/IconButton.tsx +67 -0
  172. package/raw/house-style/components/Modal.tsx +18 -0
  173. package/raw/house-style/components/Stepper.tsx +141 -0
  174. package/raw/house-style/components/icons.tsx +128 -0
  175. package/raw/house-style/preview/src/index.css +46 -0
  176. package/raw/house-style/tokens/tailwind.preset.ts +49 -0
  177. package/raw/house-style/tokens/tokens.json +62 -0
  178. package/raw/llm-wiki-2.md +162 -0
  179. package/raw/llm-wiki.md +75 -0
  180. package/raw/research/dark-mode-theme/index.md +85 -0
  181. package/raw/research/dark-mode-theme/sources.md +49 -0
  182. package/raw/research/serena-mcp-disconnect/index.md +81 -0
  183. package/raw/research/serena-mcp-disconnect/sources.md +87 -0
  184. package/raw/research/wiki-tooling-improvements/index.md +126 -0
  185. package/raw/research/wiki-tooling-improvements/sources.md +73 -0
  186. 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)