@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,184 @@
1
+ ---
2
+ name: power-mode
3
+ description: Orchestrator for parallel agent teams. When invoked with a roadmap file path, drives every item through the full tackle → uat-generate → uat-auto pipeline until complete. When invoked with a task file path, runs that pipeline once and stops.
4
+ category: executing
5
+ model: claude-sonnet-4-6
6
+ argument-hint: "[roadmap-file-path | task-file-path]"
7
+ disable-model-invocation: false
8
+ user-invocable: true
9
+ ---
10
+
11
+ # Power Mode — Agent Team Orchestrator
12
+
13
+ Use this skill to drive tasks or roadmaps to completion using a parallel agent team. The primary goal is efficiency: collision-safe tasks must always run in parallel. You are the primary orchestrator. Use agent teams for parallel work.
14
+
15
+ ---
16
+
17
+ ## Dispatch — Roadmap vs Task
18
+
19
+ **Trigger:** `/power-mode <path>` with no additional instructions.
20
+
21
+ Inspect the path argument:
22
+ - Path contains `roadmap` or matches `ROADMAP-NNN` → **Roadmap-to-Completion Orchestrator** (see below)
23
+ - Path contains `task` or matches `TASK-NNN` → **Single-Task Executor** (see below)
24
+
25
+ ---
26
+
27
+ ## Parallelization Mandate
28
+
29
+ **Spawning a parallel agent team is MANDATORY whenever tasks are collision-safe.** Collision-safe means the tasks do not write to the same files or shared state. When in doubt, read the task steps — if file paths do not overlap, they are collision-safe.
30
+
31
+ - **Minimum team size: 5 agents** when 5 or more collision-safe tasks are available in the current wave.
32
+ - If the wave has fewer than 5 tasks, spawn one agent per task — still parallel, never sequential.
33
+ - Running collision-safe tasks one at a time is a **performance failure**. It is forbidden.
34
+ - The mandate applies equally to UAT generation (Phase 2) and UAT execution (Phase 3).
35
+
36
+ **Collision check protocol before each wave:**
37
+ 1. List the files each task is expected to touch (read each task file's Steps section).
38
+ 2. Group tasks that share no file paths — each group is safe to run in parallel.
39
+ 3. Spawn all agents in the safe group simultaneously in a single message with multiple Agent tool calls.
40
+ 4. Only serialize tasks within a group if a direct dependency is declared in the task file.
41
+
42
+ ---
43
+
44
+ ## Team Member Requirements
45
+
46
+ Every agent spawned in power-mode MUST include `mode: "bypassPermissions"` and the following footer appended to its prompt:
47
+
48
+ ```
49
+ IMPORTANT: Follow .docs/guides/mcp-tools.md for all file and code operations. Use Serena (mcp__serena__*) for ALL file/directory exploration and ALL code editing. Never use ls, cat, find, grep, sed, awk, or any shell command to inspect or modify files. Use Read/Edit/Write only for markdown and config files.
50
+
51
+ IMPORTANT: If at any point you are not 100% sure how to fix an issue or which implementation strategy to use, invoke /research first and act on its recommendation before proceeding.
52
+ ```
53
+
54
+ All agent call examples below omit this footer for brevity — it is always required.
55
+
56
+ ---
57
+
58
+ ## Single-Task Executor
59
+
60
+ **Trigger:** `/power-mode <path/to/TASK-NNN.md>` with no additional instructions.
61
+
62
+ **Goal:** Drive one task through the full tackle → UAT-generate → UAT-auto pipeline exactly once, then stop.
63
+
64
+ **AUTONOMOUS EXECUTION MANDATE:** Execute all three phases without pausing, asking questions, or awaiting approval. The only valid stopping point is after `/uat-auto` completes and the file-move housekeeping is done.
65
+
66
+ **Phase 1 — Tackle**
67
+
68
+ ```
69
+ Agent({
70
+ description: "Tackle <TASK-NNN>",
71
+ prompt: "Run /tackle <task-path>. [append team member footer]",
72
+ mode: "bypassPermissions"
73
+ })
74
+ ```
75
+
76
+ Wait for the agent to complete.
77
+
78
+ **Phase 2 — Generate UAT tests**
79
+
80
+ ```
81
+ Agent({
82
+ description: "UAT generate <TASK-NNN>",
83
+ prompt: "Run /uat-generate <task-path>. [append team member footer]",
84
+ mode: "bypassPermissions"
85
+ })
86
+ ```
87
+
88
+ Wait for the agent to complete.
89
+
90
+ **Phase 3 — Run UATs**
91
+
92
+ ```
93
+ Agent({
94
+ description: "UAT auto <TASK-NNN>",
95
+ prompt: "Run /uat-auto <uat-path> (infer the UAT file path from the task path — same NNN slug, under wiki/work/uat/).
96
+
97
+ Note: on all-pass, /uat-auto's own UAT-CORE Closure procedure already flips the task to done, archives both files, removes index rows, and auto-checks the matching roadmap checkbox (if any) — you do not need to instruct any of that here; it happens natively. Just wait for it to complete and report its summary.
98
+
99
+ UAT tests recorded as [FAIL: auto-judge: UI test requires human verification] do NOT block task completion — /uat-auto does not run UI tests. Treat these as an acceptable resting state, not a blocker.
100
+
101
+ If any tests remain as - [ ] Pass because stub indicators were detected, that's expected — /uat-auto leaves the task in place rather than closing it. Report the stub-detected tests in your summary. [append team member footer]",
102
+ mode: "bypassPermissions"
103
+ })
104
+ ```
105
+
106
+ Done. No further iteration.
107
+
108
+ ---
109
+
110
+ ## Roadmap-to-Completion Orchestrator
111
+
112
+ **Trigger:** `/power-mode <path/to/ROADMAP-NNN.md>` with no additional instructions.
113
+
114
+ **Goal:** Drive the roadmap to completion — every item through the full tackle → UAT-generate → UAT-auto pipeline — looping through waves of parallelizable work until no implementation work remains.
115
+
116
+ **AUTONOMOUS EXECUTION MANDATE:** Once triggered, drive the roadmap to completion without stopping. Do NOT pause between waves to report progress or ask for permission to continue. The only valid stopping point is when `/roadmap-next` reports no items remaining. A roadmap item is complete once it has been through the full pipeline — UAT tests requiring human verification do NOT block loop progression.
117
+
118
+ ### Forbidden actions in orchestrator mode
119
+
120
+ - ❌ Stopping after a wave or phase to ask "shall I continue?"
121
+ - ❌ Asking clarifying questions about scope, naming, or strategy mid-run
122
+ - ❌ Treating a roadmap "Phase" boundary as a stopping point
123
+ - ❌ Blocking loop progression because some UAT tests require human verification
124
+
125
+ ### Orchestrator loop
126
+
127
+ Run until `/roadmap-next <file>` reports no items remaining:
128
+
129
+ **Step 1 — Get the next wave**
130
+
131
+ Invoke `/roadmap-next <file>` to identify the next group of parallelizable unchecked items.
132
+
133
+ **Step 2 — Materialize inline placeholders**
134
+
135
+ For any item that is an inline placeholder (no existing task file link), spawn a task-creation agent:
136
+
137
+ ```
138
+ Agent({
139
+ description: "Create task for <item>",
140
+ prompt: "Run /task-add for this roadmap item: '<item description>'. Link the resulting task back into the roadmap file at wiki/work/roadmaps/<file>. Run /research before writing the task. Make all scope, naming, and structuring decisions autonomously — infer reasonable defaults from the roadmap context and existing task files in wiki/work/tasks/. [append team member footer]",
141
+ mode: "bypassPermissions"
142
+ })
143
+ ```
144
+
145
+ Wait for all task-creation agents to complete.
146
+
147
+ **Step 3 — Three-phase pipeline for the wave**
148
+
149
+ Run tackle → UAT-generate → UAT-auto for all tasks in the current wave. Apply the Parallelization Mandate at every phase.
150
+
151
+ Phase 1 — Tackle (parallel, minimum 5 agents when 5+ collision-safe tasks available):
152
+ ```
153
+ Agent({ description: "Tackle TASK-NNN", prompt: "Run /tackle <path>. [append team member footer]", mode: "bypassPermissions" })
154
+ Agent({ description: "Tackle TASK-MMM", prompt: "Run /tackle <path>. [append team member footer]", mode: "bypassPermissions" })
155
+ // ... one per task, all in the same message
156
+ ```
157
+
158
+ Wait for all to complete.
159
+
160
+ Phase 2 — Generate UAT tests (parallel, read-only):
161
+ ```
162
+ Agent({ description: "UAT generate TASK-NNN", prompt: "Run /uat-generate <task-path>. [append team member footer]", mode: "bypassPermissions" })
163
+ // ... one per task, all in the same message
164
+ ```
165
+
166
+ Wait for all to complete.
167
+
168
+ Phase 3 — Run UATs (parallel when UAT files don't collide):
169
+ ```
170
+ Agent({
171
+ description: "UAT auto TASK-NNN",
172
+ prompt: "Run /uat-auto <uat-path>.
173
+
174
+ Note: on all-pass, /uat-auto's own UAT-CORE Closure procedure already flips the task to done, archives both files, removes index rows, and auto-checks the matching roadmap checkbox — no need to instruct any of that here.
175
+
176
+ UAT tests recorded as [FAIL: auto-judge: UI test requires human verification] do NOT block this step. If stub-detected tests remain, that's /uat-auto's own expected behavior — it leaves the file in place; report the stubs. [append team member footer]",
177
+ mode: "bypassPermissions"
178
+ })
179
+ ```
180
+
181
+ **Step 4 — Repeat**
182
+
183
+ Immediately return to Step 1. No pausing, no reporting, no confirmation. Loop until `/roadmap-next` reports no items remaining.
184
+
@@ -0,0 +1,84 @@
1
+ ---
2
+ name: primer
3
+ description: Refresh codebase context via Serena memories
4
+ category: researching
5
+ model: claude-haiku-4-5-20251001
6
+ disable-model-invocation: false
7
+ user-invocable: true
8
+ ---
9
+ **Prereqs:** obey `.docs/guides/mcp-tools.md`.
10
+
11
+ # MANDATORY REQUIREMENTS
12
+
13
+ ## YOU MUST USE MCP TOOLS. THIS IS NON-NEGOTIABLE.
14
+
15
+ | Operation | REQUIRED Tool | FORBIDDEN Alternative |
16
+ |-----------|---------------|----------------------|
17
+ | List memories | `mcp__serena__list_memories` | N/A |
18
+ | Read memories | `mcp__serena__read_memory` | N/A |
19
+ | Write memories | `mcp__serena__write_memory` | N/A |
20
+ | Edit memories | `mcp__serena__edit_memory` | N/A |
21
+ | Rename memories | `mcp__serena__rename_memory` | N/A |
22
+ | Explore code | `mcp__serena__find_symbol`, `mcp__serena__get_symbols_overview` | ~~Read~~ |
23
+ | Find files | `mcp__serena__find_file`, `mcp__serena__list_dir` | ~~Glob~~ |
24
+ | Search code | `mcp__serena__search_for_pattern` | ~~Grep~~ |
25
+
26
+ **PROHIBITED**: Using Read, Glob, or Grep for code exploration.
27
+
28
+ ---
29
+
30
+ # Codebase Context Update
31
+
32
+ Quick workflow to refresh understanding of the codebase via Serena memories.
33
+
34
+ ## Step 0: Read the Hot Cache
35
+
36
+ Before diving into Serena memories, read the wiki's hot cache — the cheapest, most targeted "what happened last session" signal.
37
+
38
+ 1. `mcp__serena__find_file` for `hot.md` under `wiki/`. If not found, **skip this step silently** — the hot cache is optional session continuity (a project may not have adopted it yet), not a hard requirement. No warning.
39
+ 2. If present, `Read` `wiki/hot.md` and treat its **Key Recent Facts** and **Active Threads** sections as a first-pass context primer. This does not replace Serena memory reading below — it's a cheap first pass that orients the deeper memory discovery.
40
+
41
+ ## Step 1: Discover & Read Memories
42
+
43
+ 1. `mcp__serena__list_memories` → list all available memories (use `topic` parameter to filter by area, e.g. `topic="api"`)
44
+ 2. `mcp__serena__read_memory` → read each relevant memory to rebuild context
45
+ 3. Note any memories that appear stale or reference code that may have changed
46
+
47
+ **Memory organization uses `/` separators** for topic hierarchies (e.g. `modules/frontend`, `auth/login/logic`). Use topic filtering to efficiently navigate large memory sets.
48
+
49
+ ## Step 2: Explore Codebase as Needed
50
+
51
+ Use MCP Serena to verify and extend your understanding:
52
+ - `mcp__serena__get_symbols_overview` → file/module structure
53
+ - `mcp__serena__find_symbol` → locate specific functions, classes, components
54
+ - `mcp__serena__search_for_pattern` → find patterns, usages, integrations
55
+
56
+ Cross-reference what you find against existing memories — if reality has drifted from what's documented, note it for Step 3.
57
+
58
+ ## Step 3: Update Memories
59
+
60
+ Keep memories current and useful for future conversations:
61
+
62
+ 1. **Edit stale memories**: Use `mcp__serena__edit_memory` with `mode="literal"` for precise text swaps or `mode="regex"` for pattern-based updates. Prefer editing over full rewrites.
63
+ 2. **Write new memories**: Use `mcp__serena__write_memory` for genuinely new knowledge:
64
+ - Architecture decisions and their rationale
65
+ - Integration patterns between modules
66
+ - Known gotchas, workarounds, and edge cases
67
+ - Naming conventions and project-specific terminology
68
+ - Use `/` in names for topic hierarchy (e.g. `api/auth/jwt-flow`)
69
+ 3. **Rename disorganized memories**: Use `mcp__serena__rename_memory` to move memories into proper topic hierarchies
70
+ 4. **Do NOT write memories for**: information already in code comments or docs, temporary state, easily re-derivable facts
71
+
72
+ See `.docs/guides/mcp-tools.md` for the complete Serena memory reference.
73
+
74
+ ---
75
+
76
+ ## Step 4: Check the Task Index
77
+
78
+ `/tackle` no-args mode surveys active tasks by reading `wiki/work/tasks/index.md` — a flat bullet list of active items (`- [TASK-NNN — Title](TASK-NNN-slug.md) — one-line summary · status`), one line per `todo`/`in-progress` task. There is no table to "bootstrap"; do a lightweight consistency check so that survey stays trustworthy.
79
+
80
+ 1. Use `mcp__serena__list_dir` on `wiki/work/tasks/` to list task files (top-level only, not `archive/`). If the directory is empty or has no task files, skip this step.
81
+ 2. Read `wiki/work/tasks/index.md` (use `Read` — markdown).
82
+ 3. Consistency check: every active task file (frontmatter `status: todo` or `in-progress`) should have exactly one bullet line in `index.md`, and every bullet in `index.md` should point to a real active task file. If you spot drift (an active task file with no line, a line pointing at a moved/trashed/archived file, or a `done`/`trashed` task still listed), report a one-line warning to the user listing what's off, but do NOT auto-fix — the skill that mutated state without updating the index is the bug.
83
+
84
+ See `wiki/work/tasks/lifecycle.md` for the active status set and frontmatter schema.
@@ -0,0 +1,166 @@
1
+ ---
2
+ name: project-readme
3
+ description: Generate or update a portfolio-ready project README
4
+ category: executing
5
+ model: claude-sonnet-4-6
6
+ argument-hint: "[path to project directory (defaults to cwd)] [custom instructions to alter the output]"
7
+ disable-model-invocation: false
8
+ user-invocable: true
9
+ ---
10
+ **Prereqs:** obey `.docs/guides/mcp-tools.md`.
11
+
12
+ Generate (or update) a **project README** structured for optimal AI parsing and portfolio presentation. The strict section format is machine-readable by AI tools that extract project metadata (name, description, architecture, technologies, use cases, skills).
13
+
14
+ ## Arguments: $ARGUMENTS
15
+
16
+ `$ARGUMENTS` may hold **two kinds of input** in either order, either absent:
17
+ 1. **A target path** — an existing directory (absolute/relative) = project root; absent → cwd.
18
+ 2. **Custom instructions** — free-form guidance that modifies/overrides/extends the defaults (e.g. "skip Deployment, this is a library"; "emphasize the React Native side"; "casual tone in Description"; "add a Benchmarks section after Architecture").
19
+
20
+ **Parsing:** if the first whitespace token resolves to an existing directory (Serena `list_dir` / fs check), it's the target and the rest is instructions; otherwise the whole string is instructions and target = cwd. Empty → target = cwd, no instructions.
21
+
22
+ **Applying instructions:** they take precedence over skill defaults where they conflict, **except** three non-negotiables — (1) the top-level headings and their order (`# {Project Name}` → `## Description` → `## Architecture` → `## Technologies` → `## Use Cases` → `## Skills Demonstrated` → `## Deployment`); a user may *omit* a section but not rename or reorder them; (2) the Skills Terminology rules (ATS keywords, Dreyfus-implied depth) unless the user explicitly opts out; (3) accuracy — never invent technologies, components, or procedures. Ambiguous/conflicting instruction → follow defaults and note it in the end-of-run summary.
23
+
24
+ ---
25
+
26
+ ## 1. Discover project details
27
+
28
+ Explore thoroughly with Serena. Gather:
29
+ - **Project name** — `package.json` name, repo name, or top-level dir.
30
+ - **Short description** — one-sentence pitch (`package.json` description, existing README, or inferred).
31
+ - **Repository URL** — `package.json` repository, `.git/config`, or a URL argument.
32
+ - **Architecture** — directory structure, key files, patterns (MVC, event-driven, serverless, monorepo…). For each **major component** (services, packages, layers, workers, datastores, integrations) capture responsibility, tech, inputs/outputs, and what it talks to. Then the **overall interaction model** — request/response paths, async/event flows, scheduled jobs, and where data is persisted vs cached vs streamed. Feeds the prose + mermaid diagrams.
33
+ - **Technologies** — every language, framework, runtime, database, major library, infra tool (`package.json`, `requirements.txt`, `go.mod`, `Cargo.toml`, Dockerfiles, CI configs). Be exhaustive — each becomes a badge.
34
+ - **Use cases** — problems solved, target user (2-4 sentences).
35
+ - **Skills demonstrated** — inferred from the codebase (see Skills Terminology).
36
+ - **Deployment surface** — evidence of how/where it runs: Dockerfiles, `docker-compose.yml`, k8s manifests, Terraform/Pulumi/CDK, CI/CD workflows, platform configs (`vercel.json`, `netlify.toml`, `fly.toml`, `app.yaml`, `Procfile`, `render.yaml`, `railway.toml`, `.do/app.yaml`), serverless configs (`serverless.yml`, `sam.yaml`), `.env.example`, and any `DEPLOY.md`/`OPERATIONS.md`/`RUNBOOK.md`. Note required env vars, secrets, build/start commands, health checks, ports, external services.
37
+
38
+ ## 2. Generate the README
39
+
40
+ Produce markdown with **exactly** these sections, in order, using these exact headings (parsed by downstream AI tools):
41
+
42
+ ```markdown
43
+ # {Project Name}
44
+
45
+ {One-sentence description.}
46
+
47
+ **Repository:** {repo URL or "N/A"}
48
+
49
+ ## Description
50
+ {2-3 paragraphs: what it does, why it exists, who it's for.}
51
+
52
+ ## Architecture
53
+ {See required subsections below.}
54
+
55
+ ## Technologies
56
+ {Bulleted list of every technology/framework/library/runtime/database/infra tool; group by category if many.}
57
+
58
+ ## Use Cases
59
+ {Bulleted list or short paragraphs: problems solved, target users.}
60
+
61
+ ## Skills Demonstrated
62
+ {Bulleted list of professional skills; see Skills Terminology.}
63
+
64
+ ## Deployment
65
+ {Runbook; see required subsections below.}
66
+ ```
67
+
68
+ ### `## Architecture` subsections (in order)
69
+ Diagrams required when 2+ components; a trivial single-component project may use a one-paragraph Overview and omit diagrams.
70
+
71
+ - **### Overview** — 2-4 sentences: architectural style ("modular monolith", "event-driven microservices", "serverless JAMstack", "CLI + library"), primary runtime boundary, headline decisions (sync/async, mono/polyrepo, stateful/stateless), and one sentence on how the pieces fit.
72
+ - **### Components** — one `####` per major component (order user-facing → backend → data → external; aim 4-10, collapse trivial ones), each with:
73
+ - **Responsibility:** {one sentence} · **Tech:** {language, framework, runtime} · **Inputs:** {routes, topics, watches, CLI args} · **Outputs:** {responses, events, files, DB tables} · **Depends on:** {other components + external services}
74
+ - **### Component Interaction** — a Mermaid `flowchart` with every component as a node and every dependency as a labelled directed edge (protocol/contract); group with `subgraph` (Client/Backend/Data/External):
75
+ ```mermaid
76
+ flowchart LR
77
+ subgraph Client
78
+ UI[Web UI<br/>Next.js]
79
+ end
80
+ subgraph Backend
81
+ API[REST API<br/>FastAPI]
82
+ Worker[Background Worker<br/>Celery]
83
+ end
84
+ subgraph Data
85
+ DB[(PostgreSQL)]
86
+ Cache[(Redis)]
87
+ end
88
+ UI -->|HTTP/JSON| API
89
+ API -->|SQL| DB
90
+ API -->|cache read/write| Cache
91
+ API -->|enqueue| Worker
92
+ Worker -->|SQL| DB
93
+ ```
94
+ - **### Data Flow** — a Mermaid `sequenceDiagram` for the 1-3 most important end-to-end flows; participants in chronological message order; annotate async with `Note over X: async` or dashed arrows:
95
+ ```mermaid
96
+ sequenceDiagram
97
+ participant U as User
98
+ participant UI as Web UI
99
+ participant API as REST API
100
+ participant Q as Queue
101
+ participant W as Worker
102
+ participant DB as PostgreSQL
103
+ U->>UI: submit form
104
+ UI->>API: POST /things
105
+ API->>DB: INSERT thing (status=pending)
106
+ API->>Q: enqueue process(thing_id)
107
+ API-->>UI: 202 Accepted
108
+ W->>Q: dequeue
109
+ W->>DB: UPDATE thing (status=done)
110
+ ```
111
+ - **### Design Decisions** — 3-6 one-sentence bullets, each a non-obvious choice + reason ("SQLite over Postgres for single-tenant simplicity"; "Workers are idempotent so the queue can retry safely"). If formal ADRs exist in `wiki/work/decisions/`, link them instead of restating.
112
+
113
+ ### `## Deployment` subsections (in order; omit one only if genuinely N/A)
114
+ - **### Overview** — 1-2 sentences: target platform(s), deploy model (containerized/serverless/static/VM), manual vs CI-triggered vs GitOps.
115
+ - **### Prerequisites** — required CLIs + versions (`node >=20`, `docker`, `flyctl`, `gcloud`), account/access, DNS/domain, one-time bootstrap ("create the Postgres instance", "provision the S3 bucket").
116
+ - **### Environment Variables** — table of every required/optional var: name, required?, example/format, what it controls; call out secrets vs config. Pull from `.env.example`, config loaders, `process.env.*` / `os.environ[*]`.
117
+ ```
118
+ | Variable | Required | Example | Description |
119
+ |---|---|---|---|
120
+ | `DATABASE_URL` | yes | `postgres://user:pass@host:5432/db` | Primary DB connection string |
121
+ ```
122
+ - **### Build** — exact ordered commands to produce a deployable artifact (build command, output location, asset steps); fenced bash.
123
+ - **### Run Locally** — exact commands to run the full stack for pre-deploy verification (`docker compose up`, seed/migration steps, URL to hit).
124
+ - **### Deploy** — numbered step-by-step per environment (staging/production); if CI/CD, name the workflow file + triggering branch/tag/event; if manual, the platform CLI command.
125
+ - **### Data & Migrations** — migration tool (Prisma migrate, Alembic, Flyway), apply command, auto-on-deploy vs manual, rollback approach, seed commands.
126
+ - **### Health Checks & Smoke Tests** — health URL + expected response, key post-deploy smoke tests.
127
+ - **### Rollback** — exact revert procedure (platform rollback, git revert + redeploy, blue/green switch); how to roll back a migration if applicable.
128
+ - **### Observability** — where logs/metrics live, alerting destinations, first dashboard/log-query URLs the on-call opens; if none, say so explicitly.
129
+ - **### Troubleshooting** — 3-6 failure modes: symptom, likely cause, first command/check ("502 on first request after deploy → cold start, check `/health` after 30s").
130
+
131
+ ## 3. Skills Terminology
132
+
133
+ "Skills Demonstrated" feeds downstream tools that propose individual portfolio skills:
134
+ - **Dreyfus depth (implied, not labelled)** — write descriptions implying the right level: "Designed and optimized PostgreSQL schemas" implies Proficient+; "Used Redis for basic caching" implies Advanced Beginner. (Levels: Novice → Advanced Beginner → Competent → Proficient → Expert.)
135
+ - **ATS-friendly keywords** — job-posting phrasing: "CI/CD Pipeline Configuration" not "automated deploys"; "RESTful API Design" not "built endpoints"; "Infrastructure as Code (Terraform)" not "server setup scripts".
136
+ - **Be specific** — include the tech: "Database Schema Design (Prisma ORM + PostgreSQL)" over "database skills".
137
+
138
+ ## 4. Quality checks (before writing)
139
+ - **Completeness** — every section filled; no placeholders.
140
+ - **Accuracy** — only technologies/skills evidenced in the codebase; never hallucinate.
141
+ - **Specificity** — "Next.js 15 App Router" over "React framework".
142
+ - **Length** — aim 150-350 lines (Deployment adds substantial content); enough for extraction + operation, not overwhelming.
143
+ - **Runbook honesty** — document only what's actually wired up. No CI/CD or health check → say so plainly ("No CI/CD configured; deploys are manual via `flyctl deploy`"). A skipped subsection is a one-sentence why, not silence.
144
+
145
+ ## 5. Write the file
146
+ `Write` to `README.md` in the target root. If one exists, read it first, overwrite, and show a brief change summary; else create it. After writing, confirm the path and print the full content for review.
147
+
148
+ ---
149
+
150
+ ## Why this structure matters
151
+
152
+ Both human-readable and machine-parseable — AI portfolio tools extract structured metadata per section:
153
+
154
+ | Section | Extracted as | Purpose |
155
+ |---------|--------------|---------|
156
+ | `# {Project Name}` | Project name | Primary identifier |
157
+ | First paragraph | Short description | Elevator pitch / summary card |
158
+ | `**Repository:**` | Repo URL | Link to source |
159
+ | `## Description` | Full description | Detailed portfolio context |
160
+ | `## Architecture` | Summary + component graph + sequence flows | System-design ability; mermaid graphs render as diagrams |
161
+ | `## Technologies` | Technology list | Badges and tags |
162
+ | `## Use Cases` | Use-case summary | Real-world impact |
163
+ | `## Skills Demonstrated` | Individual skill proposals | Each bullet → a skill entry with proficiency |
164
+ | `## Deployment` | Operational runbook | On-call docs + evidence of DevOps/SRE skill |
165
+
166
+ "Skills Demonstrated" matters most — each bullet is proposed as an individual ATS-named skill, making the portfolio directly useful for job applications.
@@ -0,0 +1,131 @@
1
+ ---
2
+ name: req-compile
3
+ description: >-
4
+ Compile a requirement into a running, production-grade, delightful system with minimal human time —
5
+ by routing every claim to its cheapest re-runnable check and building the dominant oracle
6
+ first. Use this whenever a project has a wiki/work/requirements/ REQ file to build or execute
7
+ ("build this per the requirement", "execute the spec", "turn these requirements into a working
8
+ system"), when scaffolding or resuming a greenfield build from a requirements document, or in
9
+ a build's closing phase to harvest corrections back into the method. Pairs with
10
+ frontend-design, run/verify, and claude-api.
11
+ category: executing
12
+ model: claude-opus-4-8
13
+ effort: high
14
+ ---
15
+
16
+ # req-compile
17
+
18
+ Turn a requirement into a working system that **self-verifies**, surfacing the human only where no
19
+ machine can decide. The aim is not zero human corrections — some are irreducible taste, or
20
+ intent discovered mid-build — but zero *preventable* ones. This skill encodes the preventable.
21
+
22
+ It inherits the global manifesto (least code, simplest architecture, maximal correctness,
23
+ no docs unless asked). This is the *how-to-build*; the manifesto is *what good looks like*.
24
+
25
+ **Input:** a project dir with a `wiki/work/requirements/REQ-NNN-slug.md` (REQ) file + a project `CLAUDE.md`
26
+ (stack, hosting, boundaries).
27
+ **Output:** code — a typed boundary contract, *failing* oracle stubs, and the answered batched
28
+ forks. Not documentation.
29
+
30
+ ## The one routing question
31
+
32
+ For every **claim** the system makes, ask:
33
+
34
+ > What is the cheapest re-runnable check that this claim is correct? If none exists, it's a
35
+ > human call.
36
+
37
+ This is a question, not a fixed oracle list — so it absorbs oracle flavors you haven't met.
38
+ Common ones, cheapest first: **deterministic** (a unit test) · **eval** (a labeled/grounded
39
+ check over a small golden set) · **human-judgment** (taste or trust no machine can settle) ·
40
+ **trust** (reversible glue not worth a check). Route the *claim*, not the feature; a single
41
+ feature usually splits across several oracles. Build the **dominant** oracle first.
42
+
43
+ ## Locating the requirement
44
+
45
+ Parse `$ARGUMENTS` to find the requirement file:
46
+
47
+ | Input form | Resolution |
48
+ |------------|------------|
49
+ | `<path>` (e.g. `wiki/work/requirements/REQ-003-onboarding.md`) | Use as-is |
50
+ | `<NNN-slug>` (e.g. `003-onboarding`) | `mcp__serena__find_file` with mask `003-onboarding.md` under `wiki/work/requirements/` |
51
+ | `<NNN>` (e.g. `3` or `003`) | Pad to 3 digits; `mcp__serena__find_file` with mask `NNN-*.md` under `wiki/work/requirements/` |
52
+ | Empty / missing | Look for any `wiki/work/requirements/REQ-NNN-slug.md` with `status: approved`; if ambiguous, ask via `AskUserQuestion` |
53
+
54
+ **Verify the requirement has `status: approved`** before proceeding. If `draft`, tell the user to run `/req-finalize <path>` first. If `retired` or `superseded`, refuse — no system should be built against a cancelled requirement.
55
+
56
+ ## The loop
57
+
58
+ 1. **Compile the requirement into claims.** Turn every must-have — and every graded bonus — into an
59
+ explicit claim, each tagged with the oracle that proves it. This list *is* the done-criterion;
60
+ you return to it in step 8. The requirement's User Stories and Acceptance Criteria are the
61
+ primary source; Success Metrics generate the eval claims.
62
+ 2. **Batched forks — ask once, up front** (see below). Default everything else.
63
+ 3. **Define the boundary contract.** One typed contract at the cross-process / cross-language
64
+ seam, the single source of truth, mirrored on both sides. It is the spine everything else
65
+ hangs on and the thing most likely to survive a rewrite underneath it.
66
+ 4. **Write *failing* oracle stubs** for the dominant oracle, cheapest first. Red before green.
67
+ 5. **Manual proof-of-life, then automate.** Get one real input → one real output on screen and
68
+ eyeball it *before* you codify the oracle. Automating an unproven path encodes its bugs.
69
+ 6. **Build to green.** The human appears only at the non-codifiable residue and the step-2 forks.
70
+ 7. **Run the real system as the joint oracle.** Integration and infra correctness only show up
71
+ in the running system, never in unit checks — exercise it for real, including the non-happy
72
+ states (loading, empty, error, out-of-scope), not just the golden path.
73
+ 8. **Audit against the requirement, then bind the gate.** Re-grade the running system against the claim
74
+ list from step 1 — *you* run this false-green checkpoint, the human shouldn't have to ask.
75
+ Once green, bind `verify` to a project `Stop` hook so it can never silently rot. Ratchet.
76
+
77
+ ## Preventions baked into the loop
78
+
79
+ These are defaults, not extra steps — each one is a correction a prior build paid for once.
80
+
81
+ - **Boundary discipline (step 3, 6).** Validate every external / LLM output against the typed
82
+ contract *at the seam*: parse-or-fallback, guard truncation / refusal / shape-drift, and
83
+ re-check any derived claim before serving it. An unvalidated external payload flowing inward
84
+ is the classic production crash. (This is the manifesto's "validate at the edge," applied to
85
+ the model and the network as adversaries.)
86
+ - **Keep the Stop gate deterministic and fast (step 8).** The `verify` bound to the `Stop` hook
87
+ runs *only* offline, deterministic checks — typecheck, lint, types, unit, and a recorded /
88
+ offline eval-smoke. Live, networked, LLM, or deploy oracles run **on demand**, never on every
89
+ Stop. A gate that is flaky or takes minutes is worse than no gate: it trains you to ignore it.
90
+ - **Select taste, don't correct it (step 2, 7).** Before building any human-facing or taste
91
+ surface, gather references and have the human *pick* a direction up front. The only real lever
92
+ on irreducible taste is a tighter reference loop — let them select rather than correct.
93
+ - **Right-size to stakes; no CI.** Build the smallest correct slice for the stated stakes; note
94
+ the rest as scale-path, don't build it. Local `verify` + the `Stop` hook is the safety net —
95
+ don't add CI/CD unless the requirement demands it.
96
+
97
+ ## The batched forks
98
+
99
+ Only these genuinely need a human and can't be safely defaulted. Ask them **once, together,
100
+ up front** — then proceed. Everything else, take the simpler default and move.
101
+
102
+ 1. **Stakes & scope** — POC or production-grade? What's the smallest correct slice, and what is
103
+ explicitly scale-path (noted, not built)?
104
+ 2. **Ground truth** — for each non-deterministic claim, what is the labeled / golden oracle:
105
+ does it already exist, or do we build a small one now — and which examples go in it?
106
+ 3. **Taste references** — for each human-facing surface, what reference(s) define "good"?
107
+ 4. **Deploy** — is a live deployment in scope (a hard oracle), or is a productionization
108
+ description sufficient? (Often answerable from the requirement — confirm, don't assume.)
109
+
110
+ ## Composes with
111
+
112
+ - **frontend-design** — the taste surface; pairs with the taste-references fork.
113
+ - **run / verify** — driving the running system as the final human oracle (step 7).
114
+ - **claude-api** — any LLM work: prompt caching, model choice, and the boundary guard above.
115
+
116
+ ## Closing harvest (self-improvement)
117
+
118
+ At the end of every build, review the human's corrections and **cluster them by root cause** —
119
+ several corrections usually trace to one missing step; fix the 2–3 roots, not the ten symptoms.
120
+ Classify each root:
121
+
122
+ - **Project-specific** → stays in that project's code / `CLAUDE.md`. It must **never** enter this
123
+ skill — that is the overfitting death.
124
+ - **Method / process gap** → fold into this skill, as the *earliest* of: a better default that
125
+ removes the need to ask · a tighter batched fork · a done-check · a right-sizing rule.
126
+ - **Universal quality standard** → the global manifesto, not here.
127
+
128
+ Fold conservatively and reversibly — a bad fold regresses the method. Prefer fewer root-cause
129
+ fixes over many patches, and keep this skill almost embarrassingly thin: the invariant is small,
130
+ and each new project should have to *earn* any addition by proving a third, unlike project would
131
+ need it too.