@zelari/core 0.7.9 → 0.7.11

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.
@@ -1,17 +1,17 @@
1
1
  import { registerCodingSkill } from '../../skills.js';
2
- const CLARIFICATION_PROTOCOL = `
3
-
4
- WHEN TO ASK THE USER (clarification):
5
- If a single missing fact would materially change your output (target platform, scope, a binary design choice with significant trade-offs, a constraint you cannot safely assume), pause and ask the user by appending EXACTLY this block at the end of your message:
6
-
7
- ---QUESTION---
8
- { "question": "One focused question", "choices": ["Option A", "Option B", "Option C"], "context": "Why this matters" }
9
- ---END---
10
-
11
- Rules for clarifications:
12
- - Ask AT MOST ONE question per turn, and only when genuinely blocked.
13
- - Prefer a small set of concrete "choices" (2-4). The user can still type a custom answer.
14
- - Do NOT ask for information that could be reasonably assumed or already in shared context.
2
+ const CLARIFICATION_PROTOCOL = `
3
+
4
+ WHEN TO ASK THE USER (clarification):
5
+ If a single missing fact would materially change your output (target platform, scope, a binary design choice with significant trade-offs, a constraint you cannot safely assume), pause and ask the user by appending EXACTLY this block at the end of your message:
6
+
7
+ ---QUESTION---
8
+ { "question": "One focused question", "choices": ["Option A", "Option B", "Option C"], "context": "Why this matters" }
9
+ ---END---
10
+
11
+ Rules for clarifications:
12
+ - Ask AT MOST ONE question per turn, and only when genuinely blocked.
13
+ - Prefer a small set of concrete "choices" (2-4). The user can still type a custom answer.
14
+ - Do NOT ask for information that could be reasonably assumed or already in shared context.
15
15
  - If you can proceed with a sound documented assumption, DO SO instead of asking.`;
16
16
  const commitMessage = {
17
17
  id: 'commit-message',
@@ -42,11 +42,11 @@ const commitMessage = {
42
42
  input: 'Staged diff: 3 files changed, +45/-12. Adds brain event types and EventBus class.',
43
43
  output: {
44
44
  subject: 'feat(events): add BrainEvent types + EventBus (Phase 11)',
45
- body: `Adds the provider-neutral event layer:
46
- - 12 BrainEvent discriminated union types
47
- - EventBus class with typed subscribers + error isolation
48
- - emit/subscribe/subscribeAll API
49
-
45
+ body: `Adds the provider-neutral event layer:
46
+ - 12 BrainEvent discriminated union types
47
+ - EventBus class with typed subscribers + error isolation
48
+ - emit/subscribe/subscribeAll API
49
+
50
50
  Foundation for Phase 12 (AgentHarness extraction).`,
51
51
  footer: 'Refs: docs/plans/2026-06-28-zelari-code.md',
52
52
  type: 'feat',
@@ -55,48 +55,48 @@ Foundation for Phase 12 (AgentHarness extraction).`,
55
55
  },
56
56
  ],
57
57
  outputSchema: '{ subject: string; body: string; footer: string; type: "feat" | "fix" | "refactor" | "docs" | "test" | "chore" | "perf" | "style"; scope: string }',
58
- systemPromptFragment: `You are writing a Conventional Commits message.
59
-
60
- ## Format
61
- <type>(<scope>): <subject>
62
-
63
- <body — explain WHY, not WHAT>
64
-
65
- <footer — issue refs, breaking changes>
66
-
67
- ## Types
68
- - feat: new feature
69
- - fix: bug fix
70
- - refactor: code change that neither fixes a bug nor adds a feature
71
- - docs: documentation only
72
- - test: adding/correcting tests
73
- - chore: build/tooling changes (deps, CI, config)
74
- - perf: performance improvement
75
- - style: formatting, missing semicolons, etc. (no logic change)
76
-
77
- ## Subject rules
78
- - Imperative mood ("add" not "added")
79
- - Lowercase (except proper nouns)
80
- - Max 72 characters
81
- - No trailing period
82
-
83
- ## Body rules
84
- - Wrap at 72 characters
85
- - Explain WHY the change was made
86
- - Bullet points for multiple distinct changes
87
-
88
- ## Footer rules
89
- - \`Refs: #123\` for related issues
90
- - \`BREAKING CHANGE: <description>\` for breaking changes
91
- - \`Co-authored-by: Name <email>\` for pair work
92
-
93
- ## Output format (JSON-typed)
94
- - subject: string
95
- - body: string
96
- - footer: string
97
- - type: ConventionalCommitType
98
- - scope: string (optional, lowercase module name)
99
-
58
+ systemPromptFragment: `You are writing a Conventional Commits message.
59
+
60
+ ## Format
61
+ <type>(<scope>): <subject>
62
+
63
+ <body — explain WHY, not WHAT>
64
+
65
+ <footer — issue refs, breaking changes>
66
+
67
+ ## Types
68
+ - feat: new feature
69
+ - fix: bug fix
70
+ - refactor: code change that neither fixes a bug nor adds a feature
71
+ - docs: documentation only
72
+ - test: adding/correcting tests
73
+ - chore: build/tooling changes (deps, CI, config)
74
+ - perf: performance improvement
75
+ - style: formatting, missing semicolons, etc. (no logic change)
76
+
77
+ ## Subject rules
78
+ - Imperative mood ("add" not "added")
79
+ - Lowercase (except proper nouns)
80
+ - Max 72 characters
81
+ - No trailing period
82
+
83
+ ## Body rules
84
+ - Wrap at 72 characters
85
+ - Explain WHY the change was made
86
+ - Bullet points for multiple distinct changes
87
+
88
+ ## Footer rules
89
+ - \`Refs: #123\` for related issues
90
+ - \`BREAKING CHANGE: <description>\` for breaking changes
91
+ - \`Co-authored-by: Name <email>\` for pair work
92
+
93
+ ## Output format (JSON-typed)
94
+ - subject: string
95
+ - body: string
96
+ - footer: string
97
+ - type: ConventionalCommitType
98
+ - scope: string (optional, lowercase module name)
99
+
100
100
  Stay under 300 words.${CLARIFICATION_PROTOCOL}`,
101
101
  };
102
102
  const prDescription = {
@@ -147,30 +147,30 @@ const prDescription = {
147
147
  },
148
148
  ],
149
149
  outputSchema: '{ title: string; summary: string; motivation: string; changes: string[]; testing: string; risks: string[] }',
150
- systemPromptFragment: `You are writing a Pull Request description.
151
-
152
- ## Sections (use all)
153
- 1. **Title** (max 72 chars, imperative mood)
154
- 2. **Summary** (1 paragraph): what does this PR do?
155
- 3. **Motivation** (1-2 paragraphs): WHY? What problem does it solve?
156
- 4. **Changes** (bullet list, 5-15 items): specific files/concepts changed
157
- 5. **Testing** (1 paragraph): how was it verified? Test counts, manual steps
158
- 6. **Risks** (bullet list, 2-5 items): what could go wrong? Migration needed?
159
-
160
- ## Output format (JSON-typed)
161
- - title: string
162
- - summary: string
163
- - motivation: string
164
- - changes: string[]
165
- - testing: string
166
- - risks: string[]
167
-
168
- ## PR description principles
169
- - **Reviewer-first**: optimize for someone who has NEVER seen this code
170
- - **Concrete not abstract**: cite file paths, line numbers, function names
171
- - **Risk-honest**: don't hide breaking changes or migration steps
172
- - **Self-contained**: PR description should make sense without clicking through to issues
173
-
150
+ systemPromptFragment: `You are writing a Pull Request description.
151
+
152
+ ## Sections (use all)
153
+ 1. **Title** (max 72 chars, imperative mood)
154
+ 2. **Summary** (1 paragraph): what does this PR do?
155
+ 3. **Motivation** (1-2 paragraphs): WHY? What problem does it solve?
156
+ 4. **Changes** (bullet list, 5-15 items): specific files/concepts changed
157
+ 5. **Testing** (1 paragraph): how was it verified? Test counts, manual steps
158
+ 6. **Risks** (bullet list, 2-5 items): what could go wrong? Migration needed?
159
+
160
+ ## Output format (JSON-typed)
161
+ - title: string
162
+ - summary: string
163
+ - motivation: string
164
+ - changes: string[]
165
+ - testing: string
166
+ - risks: string[]
167
+
168
+ ## PR description principles
169
+ - **Reviewer-first**: optimize for someone who has NEVER seen this code
170
+ - **Concrete not abstract**: cite file paths, line numbers, function names
171
+ - **Risk-honest**: don't hide breaking changes or migration steps
172
+ - **Self-contained**: PR description should make sense without clicking through to issues
173
+
174
174
  Stay under 500 words.${CLARIFICATION_PROTOCOL}`,
175
175
  };
176
176
  const ciPipeline = {
@@ -203,55 +203,55 @@ const ciPipeline = {
203
203
  input: 'Generate GitHub Actions for AnathemaBrain (Electron + React + TS + Vitest)',
204
204
  output: {
205
205
  workflowFile: '.github/workflows/ci.yml',
206
- content: `name: CI
207
-
208
- on:
209
- push:
210
- branches: [main]
211
- pull_request:
212
- branches: [main]
213
-
214
- jobs:
215
- test:
216
- runs-on: ubuntu-latest
217
- timeout-minutes: 15
218
- strategy:
219
- matrix:
220
- node-version: [20.x]
221
-
222
- steps:
223
- - uses: actions/checkout@v4
224
-
225
- - name: Setup Node.js \${{ matrix.node-version }}
226
- uses: actions/setup-node@v4
227
- with:
228
- node-version: \${{ matrix.node-version }}
229
- cache: 'npm'
230
-
231
- - name: Install dependencies
232
- run: npm ci
233
-
234
- - name: Typecheck (node config)
235
- run: npm run typecheck:node
236
-
237
- - name: Typecheck (web config)
238
- run: npm run typecheck:web
239
-
240
- - name: Lint
241
- run: npm run lint
242
-
243
- - name: Test
244
- run: npm run test
245
-
246
- - name: Build (Electron renderer + main)
247
- run: npm run build
248
-
249
- - name: Upload coverage
250
- if: success()
251
- uses: actions/upload-artifact@v4
252
- with:
253
- name: coverage-\${{ matrix.node-version }}
254
- path: coverage/
206
+ content: `name: CI
207
+
208
+ on:
209
+ push:
210
+ branches: [main]
211
+ pull_request:
212
+ branches: [main]
213
+
214
+ jobs:
215
+ test:
216
+ runs-on: ubuntu-latest
217
+ timeout-minutes: 15
218
+ strategy:
219
+ matrix:
220
+ node-version: [20.x]
221
+
222
+ steps:
223
+ - uses: actions/checkout@v4
224
+
225
+ - name: Setup Node.js \${{ matrix.node-version }}
226
+ uses: actions/setup-node@v4
227
+ with:
228
+ node-version: \${{ matrix.node-version }}
229
+ cache: 'npm'
230
+
231
+ - name: Install dependencies
232
+ run: npm ci
233
+
234
+ - name: Typecheck (node config)
235
+ run: npm run typecheck:node
236
+
237
+ - name: Typecheck (web config)
238
+ run: npm run typecheck:web
239
+
240
+ - name: Lint
241
+ run: npm run lint
242
+
243
+ - name: Test
244
+ run: npm run test
245
+
246
+ - name: Build (Electron renderer + main)
247
+ run: npm run build
248
+
249
+ - name: Upload coverage
250
+ if: success()
251
+ uses: actions/upload-artifact@v4
252
+ with:
253
+ name: coverage-\${{ matrix.node-version }}
254
+ path: coverage/
255
255
  `,
256
256
  jobs: ['test'],
257
257
  triggers: ['push to main', 'pull_request to main'],
@@ -260,39 +260,39 @@ jobs:
260
260
  },
261
261
  ],
262
262
  outputSchema: '{ workflowFile: string; content: string; jobs: string[]; triggers: string[]; nodeVersion: string }',
263
- systemPromptFragment: `You are writing a GitHub Actions workflow YAML.
264
-
265
- ## Required structure
266
- 1. **name**: workflow display name
267
- 2. **on**: triggers (push to main, pull_request, manual workflow_dispatch)
268
- 3. **jobs**: at least one job with steps
269
- 4. **runs-on**: ubuntu-latest (default)
270
- 5. **timeout-minutes**: 15 (default, increase for slower builds)
271
- 6. **matrix.node-version**: pin to a specific major version (e.g. 20.x)
272
-
273
- ## Standard steps (in order)
274
- 1. actions/checkout@v4
275
- 2. actions/setup-node@v4 with cache: 'npm'
276
- 3. npm ci (NOT npm install — faster in CI)
277
- 4. typecheck (run the project's typecheck script)
278
- 5. lint (run the project's lint script)
279
- 6. test (run the project's test script)
280
- 7. build (run the project's build script, if applicable)
281
-
282
- ## Output format (JSON-typed)
283
- - workflowFile: string (path like .github/workflows/ci.yml)
284
- - content: string (the full YAML)
285
- - jobs: string[] (job names)
286
- - triggers: string[] (trigger events)
287
- - nodeVersion: string (pinned Node version)
288
-
289
- ## CI principles
290
- - **Fail fast**: order steps from fastest → slowest (typecheck before build)
291
- - **Cache dependencies**: cache: 'npm' saves 30s+ on cold builds
292
- - **Pin versions**: use @v4 not @latest for reproducibility
293
- - **Don't cache build artifacts**: cache only deps
294
- - **Separate jobs for parallel**: typecheck, lint, test can be parallel jobs
295
-
263
+ systemPromptFragment: `You are writing a GitHub Actions workflow YAML.
264
+
265
+ ## Required structure
266
+ 1. **name**: workflow display name
267
+ 2. **on**: triggers (push to main, pull_request, manual workflow_dispatch)
268
+ 3. **jobs**: at least one job with steps
269
+ 4. **runs-on**: ubuntu-latest (default)
270
+ 5. **timeout-minutes**: 15 (default, increase for slower builds)
271
+ 6. **matrix.node-version**: pin to a specific major version (e.g. 20.x)
272
+
273
+ ## Standard steps (in order)
274
+ 1. actions/checkout@v4
275
+ 2. actions/setup-node@v4 with cache: 'npm'
276
+ 3. npm ci (NOT npm install — faster in CI)
277
+ 4. typecheck (run the project's typecheck script)
278
+ 5. lint (run the project's lint script)
279
+ 6. test (run the project's test script)
280
+ 7. build (run the project's build script, if applicable)
281
+
282
+ ## Output format (JSON-typed)
283
+ - workflowFile: string (path like .github/workflows/ci.yml)
284
+ - content: string (the full YAML)
285
+ - jobs: string[] (job names)
286
+ - triggers: string[] (trigger events)
287
+ - nodeVersion: string (pinned Node version)
288
+
289
+ ## CI principles
290
+ - **Fail fast**: order steps from fastest → slowest (typecheck before build)
291
+ - **Cache dependencies**: cache: 'npm' saves 30s+ on cold builds
292
+ - **Pin versions**: use @v4 not @latest for reproducibility
293
+ - **Don't cache build artifacts**: cache only deps
294
+ - **Separate jobs for parallel**: typecheck, lint, test can be parallel jobs
295
+
296
296
  Stay under 500 words.${CLARIFICATION_PROTOCOL}`,
297
297
  };
298
298
  registerCodingSkill(commitMessage);
@@ -1,17 +1,17 @@
1
1
  import { registerCodingSkill } from '../../skills.js';
2
- const CLARIFICATION_PROTOCOL = `
3
-
4
- WHEN TO ASK THE USER (clarification):
5
- If a single missing fact would materially change your output (target platform, scope, a binary design choice with significant trade-offs, a constraint you cannot safely assume), pause and ask the user by appending EXACTLY this block at the end of your message:
6
-
7
- ---QUESTION---
8
- { "question": "One focused question", "choices": ["Option A", "Option B", "Option C"], "context": "Why this matters" }
9
- ---END---
10
-
11
- Rules for clarifications:
12
- - Ask AT MOST ONE question per turn, and only when genuinely blocked.
13
- - Prefer a small set of concrete "choices" (2-4). The user can still type a custom answer.
14
- - Do NOT ask for information that could be reasonably assumed or already in shared context.
2
+ const CLARIFICATION_PROTOCOL = `
3
+
4
+ WHEN TO ASK THE USER (clarification):
5
+ If a single missing fact would materially change your output (target platform, scope, a binary design choice with significant trade-offs, a constraint you cannot safely assume), pause and ask the user by appending EXACTLY this block at the end of your message:
6
+
7
+ ---QUESTION---
8
+ { "question": "One focused question", "choices": ["Option A", "Option B", "Option C"], "context": "Why this matters" }
9
+ ---END---
10
+
11
+ Rules for clarifications:
12
+ - Ask AT MOST ONE question per turn, and only when genuinely blocked.
13
+ - Prefer a small set of concrete "choices" (2-4). The user can still type a custom answer.
14
+ - Do NOT ask for information that could be reasonably assumed or already in shared context.
15
15
  - If you can proceed with a sound documented assumption, DO SO instead of asking.`;
16
16
  const architectFeature = {
17
17
  id: 'architect-feature',
@@ -76,27 +76,27 @@ const architectFeature = {
76
76
  },
77
77
  ],
78
78
  outputSchema: '{ goal: string; alternatives: Array<{ approach: string; score: string; rationale: string }>; chosen: { approach: string; rationale: string }; adrPath: string; risks: Array<{ risk: string; mitigation: string }> }',
79
- systemPromptFragment: `You are designing a feature with multi-perspective analysis.
80
-
81
- ## Methodology
82
- 1. Restate the goal in ONE sentence: what user need does this serve?
83
- 2. Search prior decisions with the retrieval tool listed in your AVAILABLE TOOLS (searchDocuments or searchRAG — never call one that is not listed), query: "<feature-keyword>"
84
- 3. Generate 3-5 DISTINCT approaches (vary the axis: library vs custom, sync vs async, desktop vs server, etc.).
85
- 4. Score each approach on three dimensions (1-5 each):
86
- - Feasibility (F): how easy to implement given the current stack
87
- - Risk (R, INVERTED — lower is better): likelihood of bugs, security holes, scope creep
88
- - Maintenance (M): long-term cost (bus factor, doc quality, ecosystem health)
89
- 5. Pick the top approach and justify in 1-2 sentences.
90
- 6. Generate an ADR (link to architect-decision-record skill).
91
- 7. List 2-5 concrete risks + mitigations.
92
-
93
- ## Output format (JSON-typed)
94
- - goal: string
95
- - alternatives: Array<{ approach: string; score: string; rationale: string }>
96
- - chosen: { approach: string; rationale: string }
97
- - adrPath: string
98
- - risks: Array<{ risk: string; mitigation: string }>
99
-
79
+ systemPromptFragment: `You are designing a feature with multi-perspective analysis.
80
+
81
+ ## Methodology
82
+ 1. Restate the goal in ONE sentence: what user need does this serve?
83
+ 2. Search prior decisions with the retrieval tool listed in your AVAILABLE TOOLS (searchDocuments or searchRAG — never call one that is not listed), query: "<feature-keyword>"
84
+ 3. Generate 3-5 DISTINCT approaches (vary the axis: library vs custom, sync vs async, desktop vs server, etc.).
85
+ 4. Score each approach on three dimensions (1-5 each):
86
+ - Feasibility (F): how easy to implement given the current stack
87
+ - Risk (R, INVERTED — lower is better): likelihood of bugs, security holes, scope creep
88
+ - Maintenance (M): long-term cost (bus factor, doc quality, ecosystem health)
89
+ 5. Pick the top approach and justify in 1-2 sentences.
90
+ 6. Generate an ADR (link to architect-decision-record skill).
91
+ 7. List 2-5 concrete risks + mitigations.
92
+
93
+ ## Output format (JSON-typed)
94
+ - goal: string
95
+ - alternatives: Array<{ approach: string; score: string; rationale: string }>
96
+ - chosen: { approach: string; rationale: string }
97
+ - adrPath: string
98
+ - risks: Array<{ risk: string; mitigation: string }>
99
+
100
100
  Stay under 400 words. Be decisive: pick ONE approach, do not list 3 equally good options.${CLARIFICATION_PROTOCOL}`,
101
101
  };
102
102
  const architectDecisionRecord = {
@@ -129,57 +129,57 @@ const architectDecisionRecord = {
129
129
  input: 'Document why we use SQLite over Postgres for local storage',
130
130
  output: {
131
131
  path: 'docs/adr/0007-sqlite-over-postgres.md',
132
- content: `# 7. SQLite over Postgres for local storage
133
-
134
- ## Context
135
- AnathemaBrain is an Electron desktop app that runs entirely on the user's machine. We need persistent storage for vault documents, RAG vectors, settings, and council sessions.
136
-
137
- ## Decision
138
- Use SQLite (via better-sqlite3) for all local storage.
139
-
140
- ## Consequences
141
- - Zero-config: works out of the box, no separate DB server to manage
142
- - Single-file backups: copy ~/.anathemabrain/db.sqlite
143
- - FTS5 + JSON1 support built-in (used by RAG and vault search)
144
- - Cross-platform: tested on macOS, Linux, Windows
145
-
146
- ### Positive
147
- - No network round-trip — sub-millisecond reads
148
- - Embedded = no auth/connection-string management
149
- - Mature ecosystem (better-sqlite3, sqlite-vss)
150
-
151
- ### Negative
152
- - Single-writer: concurrent writes are serialized (acceptable for desktop)
153
- - No horizontal scaling (irrelevant for desktop)
154
- - Migration tooling requires custom scripts (we have db/migrations.ts)
155
-
156
- ## Alternatives Considered
157
- - **Postgres**: rejected — requires a server process, overkill for desktop
158
- - **LevelDB / RocksDB**: rejected — no SQL, harder to query vector data
159
- - **JSON files**: rejected — no concurrent access, no FTS
132
+ content: `# 7. SQLite over Postgres for local storage
133
+
134
+ ## Context
135
+ AnathemaBrain is an Electron desktop app that runs entirely on the user's machine. We need persistent storage for vault documents, RAG vectors, settings, and council sessions.
136
+
137
+ ## Decision
138
+ Use SQLite (via better-sqlite3) for all local storage.
139
+
140
+ ## Consequences
141
+ - Zero-config: works out of the box, no separate DB server to manage
142
+ - Single-file backups: copy ~/.anathemabrain/db.sqlite
143
+ - FTS5 + JSON1 support built-in (used by RAG and vault search)
144
+ - Cross-platform: tested on macOS, Linux, Windows
145
+
146
+ ### Positive
147
+ - No network round-trip — sub-millisecond reads
148
+ - Embedded = no auth/connection-string management
149
+ - Mature ecosystem (better-sqlite3, sqlite-vss)
150
+
151
+ ### Negative
152
+ - Single-writer: concurrent writes are serialized (acceptable for desktop)
153
+ - No horizontal scaling (irrelevant for desktop)
154
+ - Migration tooling requires custom scripts (we have db/migrations.ts)
155
+
156
+ ## Alternatives Considered
157
+ - **Postgres**: rejected — requires a server process, overkill for desktop
158
+ - **LevelDB / RocksDB**: rejected — no SQL, harder to query vector data
159
+ - **JSON files**: rejected — no concurrent access, no FTS
160
160
  `,
161
161
  },
162
162
  },
163
163
  ],
164
164
  outputSchema: '{ path: string; content: string }',
165
- systemPromptFragment: `You are writing an Architecture Decision Record (ADR).
166
-
167
- ## Required sections
168
- 1. **# N. <Title>** — short title in present tense ("Use X for Y")
169
- 2. **## Context** — what is the situation? What forces are at play? (2-3 paragraphs)
170
- 3. **## Decision** — what did we decide? State it clearly in 1-2 sentences.
171
- 4. **## Consequences** — what becomes easier (+) and harder (-) as a result?
172
- 5. **## Alternatives Considered** — 2-4 alternatives with one-line rejection reasons.
173
-
174
- ## Numbering
175
- - Check docs/adr/ for the next available number (NNN-title.md format)
176
- - ADR numbers are permanent — never reuse, even if an ADR is superseded (mark superseded in the body instead)
177
-
178
- ## Tone
179
- - Factual, not promotional
180
- - Acknowledge trade-offs honestly
181
- - Link to relevant code/PRs/files using relative paths
182
-
165
+ systemPromptFragment: `You are writing an Architecture Decision Record (ADR).
166
+
167
+ ## Required sections
168
+ 1. **# N. <Title>** — short title in present tense ("Use X for Y")
169
+ 2. **## Context** — what is the situation? What forces are at play? (2-3 paragraphs)
170
+ 3. **## Decision** — what did we decide? State it clearly in 1-2 sentences.
171
+ 4. **## Consequences** — what becomes easier (+) and harder (-) as a result?
172
+ 5. **## Alternatives Considered** — 2-4 alternatives with one-line rejection reasons.
173
+
174
+ ## Numbering
175
+ - Check docs/adr/ for the next available number (NNN-title.md format)
176
+ - ADR numbers are permanent — never reuse, even if an ADR is superseded (mark superseded in the body instead)
177
+
178
+ ## Tone
179
+ - Factual, not promotional
180
+ - Acknowledge trade-offs honestly
181
+ - Link to relevant code/PRs/files using relative paths
182
+
183
183
  Stay under 800 words.${CLARIFICATION_PROTOCOL}`,
184
184
  };
185
185
  const migrateStack = {
@@ -228,27 +228,27 @@ const migrateStack = {
228
228
  },
229
229
  ],
230
230
  outputSchema: '{ goal: string; phases: Array<{ name: string; exitCriterion: string; durationDays: number }>; rollbackStrategy: string; risks: Array<{ risk: string; mitigation: string }> }',
231
- systemPromptFragment: `You are planning a stack migration.
232
-
233
- ## Methodology
234
- 1. State the GOAL in measurable terms (e.g. "reduce build time from 60s to 10s").
235
- 2. Decompose into 3-6 phases. Each phase has a CLEAR exit criterion (testable condition).
236
- 3. Each phase should be DEPLOYABLE on its own (no big-bang steps).
237
- 4. Plan a ROLLBACK strategy: which single commit reverts to the previous state?
238
- 5. List 3-7 concrete risks + mitigations per phase.
239
-
240
- ## Migration principles
241
- - **Strangler Fig**: new system grows alongside old, traffic migrates incrementally
242
- - **No big-bang rewrites**: every phase must be independently shippable
243
- - **Reversibility first**: every phase has a tested rollback path
244
- - **Data migration last**: schema changes follow code changes (dual-write during transition)
245
-
246
- ## Output format (JSON-typed)
247
- - goal: string (measurable)
248
- - phases: Array<{ name: string; exitCriterion: string; durationDays: number }>
249
- - rollbackStrategy: string (the single command or commit that reverts)
250
- - risks: Array<{ risk: string; mitigation: string }>
251
-
231
+ systemPromptFragment: `You are planning a stack migration.
232
+
233
+ ## Methodology
234
+ 1. State the GOAL in measurable terms (e.g. "reduce build time from 60s to 10s").
235
+ 2. Decompose into 3-6 phases. Each phase has a CLEAR exit criterion (testable condition).
236
+ 3. Each phase should be DEPLOYABLE on its own (no big-bang steps).
237
+ 4. Plan a ROLLBACK strategy: which single commit reverts to the previous state?
238
+ 5. List 3-7 concrete risks + mitigations per phase.
239
+
240
+ ## Migration principles
241
+ - **Strangler Fig**: new system grows alongside old, traffic migrates incrementally
242
+ - **No big-bang rewrites**: every phase must be independently shippable
243
+ - **Reversibility first**: every phase has a tested rollback path
244
+ - **Data migration last**: schema changes follow code changes (dual-write during transition)
245
+
246
+ ## Output format (JSON-typed)
247
+ - goal: string (measurable)
248
+ - phases: Array<{ name: string; exitCriterion: string; durationDays: number }>
249
+ - rollbackStrategy: string (the single command or commit that reverts)
250
+ - risks: Array<{ risk: string; mitigation: string }>
251
+
252
252
  Stay under 500 words.${CLARIFICATION_PROTOCOL}`,
253
253
  };
254
254
  const scopeCheck = {
@@ -302,28 +302,28 @@ const scopeCheck = {
302
302
  },
303
303
  ],
304
304
  outputSchema: '{ feasibility: "yes" | "partial" | "no"; estimatedEffortDays: number; hiddenCosts: Array<{ cost: string; mitigation: string }>; reducedScope: { phase1: string; phase2: string; phase3: string }; risks: string[] }',
305
- systemPromptFragment: `You are validating the scope of a proposed feature or change.
306
-
307
- ## Methodology
308
- 1. Restate the proposal in ONE sentence.
309
- 2. Search the knowledge base with the retrieval tool listed in your AVAILABLE TOOLS (searchDocuments or searchRAG — never call one that is not listed), query: "<proposed-keyword>"
310
- 3. Estimate effort realistically (in person-days, with calibration from prior projects).
311
- 4. List HIDDEN costs: auth flows, data migration, third-party APIs, deployment, monitoring.
312
- 5. Propose a REDUCED SCOPE that delivers 80% of the value in 20% of the time.
313
- 6. Flag risks that could block the project.
314
-
315
- ## Output format (JSON-typed)
316
- - feasibility: 'yes' | 'partial' | 'no'
317
- - estimatedEffortDays: number
318
- - hiddenCosts: Array<{ cost: string; mitigation: string }>
319
- - reducedScope: { phase1: string; phase2: string; phase3: string } (3 phases, each independently shippable)
320
- - risks: string[] (3-5 risks)
321
-
322
- ## When to be skeptical
323
- - "Just add X" usually hides auth + persistence + UI work (3x multiplier)
324
- - "Use the existing system" usually means new integration code
325
- - Estimates from optimistic people — multiply by 2-3x for calendar time
326
-
305
+ systemPromptFragment: `You are validating the scope of a proposed feature or change.
306
+
307
+ ## Methodology
308
+ 1. Restate the proposal in ONE sentence.
309
+ 2. Search the knowledge base with the retrieval tool listed in your AVAILABLE TOOLS (searchDocuments or searchRAG — never call one that is not listed), query: "<proposed-keyword>"
310
+ 3. Estimate effort realistically (in person-days, with calibration from prior projects).
311
+ 4. List HIDDEN costs: auth flows, data migration, third-party APIs, deployment, monitoring.
312
+ 5. Propose a REDUCED SCOPE that delivers 80% of the value in 20% of the time.
313
+ 6. Flag risks that could block the project.
314
+
315
+ ## Output format (JSON-typed)
316
+ - feasibility: 'yes' | 'partial' | 'no'
317
+ - estimatedEffortDays: number
318
+ - hiddenCosts: Array<{ cost: string; mitigation: string }>
319
+ - reducedScope: { phase1: string; phase2: string; phase3: string } (3 phases, each independently shippable)
320
+ - risks: string[] (3-5 risks)
321
+
322
+ ## When to be skeptical
323
+ - "Just add X" usually hides auth + persistence + UI work (3x multiplier)
324
+ - "Use the existing system" usually means new integration code
325
+ - Estimates from optimistic people — multiply by 2-3x for calendar time
326
+
327
327
  Stay under 400 words. Be honest about feasibility — say NO when the answer is NO.${CLARIFICATION_PROTOCOL}`,
328
328
  };
329
329
  // Register all 4 skills at module load time in topological dependency order.