@soleri/forge 9.2.0 → 9.3.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 (43) hide show
  1. package/dist/scaffold-filetree.js +1 -1
  2. package/dist/skills/brain-debrief/SKILL.md +12 -12
  3. package/dist/skills/brainstorming/SKILL.md +7 -7
  4. package/dist/skills/code-patrol/SKILL.md +15 -15
  5. package/dist/skills/context-resume/SKILL.md +8 -8
  6. package/dist/skills/deep-review/SKILL.md +22 -11
  7. package/dist/skills/executing-plans/SKILL.md +10 -9
  8. package/dist/skills/fix-and-learn/SKILL.md +8 -8
  9. package/dist/skills/health-check/SKILL.md +11 -11
  10. package/dist/skills/knowledge-harvest/SKILL.md +17 -17
  11. package/dist/skills/onboard-me/SKILL.md +10 -10
  12. package/dist/skills/parallel-execute/SKILL.md +46 -32
  13. package/dist/skills/retrospective/SKILL.md +9 -9
  14. package/dist/skills/second-opinion/SKILL.md +11 -8
  15. package/dist/skills/systematic-debugging/SKILL.md +8 -8
  16. package/dist/skills/test-driven-development/SKILL.md +11 -11
  17. package/dist/skills/vault-capture/SKILL.md +15 -15
  18. package/dist/skills/vault-navigator/SKILL.md +10 -10
  19. package/dist/skills/vault-smells/SKILL.md +24 -16
  20. package/dist/skills/verification-before-completion/SKILL.md +18 -18
  21. package/dist/skills/writing-plans/SKILL.md +9 -9
  22. package/package.json +1 -1
  23. package/src/scaffold-filetree.ts +1 -1
  24. package/src/skills/brain-debrief/SKILL.md +12 -12
  25. package/src/skills/brainstorming/SKILL.md +7 -7
  26. package/src/skills/code-patrol/SKILL.md +15 -15
  27. package/src/skills/context-resume/SKILL.md +8 -8
  28. package/src/skills/deep-review/SKILL.md +22 -11
  29. package/src/skills/executing-plans/SKILL.md +10 -9
  30. package/src/skills/fix-and-learn/SKILL.md +8 -8
  31. package/src/skills/health-check/SKILL.md +11 -11
  32. package/src/skills/knowledge-harvest/SKILL.md +17 -17
  33. package/src/skills/onboard-me/SKILL.md +10 -10
  34. package/src/skills/parallel-execute/SKILL.md +46 -32
  35. package/src/skills/retrospective/SKILL.md +9 -9
  36. package/src/skills/second-opinion/SKILL.md +11 -8
  37. package/src/skills/systematic-debugging/SKILL.md +8 -8
  38. package/src/skills/test-driven-development/SKILL.md +11 -11
  39. package/src/skills/vault-capture/SKILL.md +15 -15
  40. package/src/skills/vault-navigator/SKILL.md +10 -10
  41. package/src/skills/vault-smells/SKILL.md +24 -16
  42. package/src/skills/verification-before-completion/SKILL.md +18 -18
  43. package/src/skills/writing-plans/SKILL.md +9 -9
@@ -30,13 +30,13 @@ Focus extraction on gaps — skip what vault already covers.
30
30
 
31
31
  ### 3. Extract and Classify
32
32
 
33
- | Type | What to Look For |
34
- |------|-----------------|
35
- | **pattern** | Repeatable approaches that work |
36
- | **anti-pattern** | Known mistakes to avoid |
37
- | **decision** | Architectural choices with rationale |
38
- | **principle** | Guiding rules or heuristics |
39
- | **workflow** | Step-by-step procedures |
33
+ | Type | What to Look For |
34
+ | ---------------- | ------------------------------------ |
35
+ | **pattern** | Repeatable approaches that work |
36
+ | **anti-pattern** | Known mistakes to avoid |
37
+ | **decision** | Architectural choices with rationale |
38
+ | **principle** | Guiding rules or heuristics |
39
+ | **workflow** | Step-by-step procedures |
40
40
 
41
41
  For each: determine category, severity, and tags.
42
42
 
@@ -85,13 +85,13 @@ Optionally promote universal patterns: `op:memory_promote_to_global`.
85
85
 
86
86
  ## Quick Reference
87
87
 
88
- | Op | When to Use |
89
- |----|-------------|
90
- | `search_intelligent` | Check existing knowledge |
91
- | `vault_tags` / `vault_domains` | See what's covered |
92
- | `capture_knowledge` | Capture each item |
93
- | `curator_detect_duplicates` | Post-harvest dedup |
94
- | `curator_groom_all` | Normalize entries |
95
- | `curator_contradictions` | Find conflicts |
96
- | `memory_promote_to_global` | Share cross-project |
97
- | `admin_vault_analytics` | Knowledge quality |
88
+ | Op | When to Use |
89
+ | ------------------------------ | ------------------------ |
90
+ | `search_intelligent` | Check existing knowledge |
91
+ | `vault_tags` / `vault_domains` | See what's covered |
92
+ | `capture_knowledge` | Capture each item |
93
+ | `curator_detect_duplicates` | Post-harvest dedup |
94
+ | `curator_groom_all` | Normalize entries |
95
+ | `curator_contradictions` | Find conflicts |
96
+ | `memory_promote_to_global` | Share cross-project |
97
+ | `admin_vault_analytics` | Knowledge quality |
@@ -109,13 +109,13 @@ YOUR_AGENT_core op:vault_age_report
109
109
 
110
110
  ## Quick Reference
111
111
 
112
- | Op | When to Use |
113
- |----|-------------|
114
- | `identity` / `project_get` | Project overview |
115
- | `project_list_rules` / `get_behavior_rules` | Conventions |
116
- | `vault_domains` / `vault_tags` | Knowledge landscape |
117
- | `search` (severity/type filters) | Critical rules, anti-patterns |
118
- | `search_intelligent` | Key decisions |
119
- | `brain_strengths` | Proven patterns |
120
- | `brain_global_patterns` | Cross-project patterns |
121
- | `admin_search_insights` | Knowledge gaps |
112
+ | Op | When to Use |
113
+ | ------------------------------------------- | ----------------------------- |
114
+ | `identity` / `project_get` | Project overview |
115
+ | `project_list_rules` / `get_behavior_rules` | Conventions |
116
+ | `vault_domains` / `vault_tags` | Knowledge landscape |
117
+ | `search` (severity/type filters) | Critical rules, anti-patterns |
118
+ | `search_intelligent` | Key decisions |
119
+ | `brain_strengths` | Proven patterns |
120
+ | `brain_global_patterns` | Cross-project patterns |
121
+ | `admin_search_insights` | Knowledge gaps |
@@ -24,6 +24,7 @@ You MUST have an approved, split plan before using this skill. If no plan exists
24
24
  - Tasks touch different files/modules (low merge conflict risk)
25
25
 
26
26
  **Do NOT use when:**
27
+
27
28
  - All tasks are sequential (each depends on the previous)
28
29
  - Tasks modify the same files (high conflict risk)
29
30
  - Plan has fewer than 3 tasks (use executing-plans instead)
@@ -60,17 +61,21 @@ Present the wave plan to the user before starting:
60
61
  For each task in the current wave:
61
62
 
62
63
  1. Check readiness:
64
+
63
65
  ```
64
66
  YOUR_AGENT_core op:plan_dispatch params:{ planId: "<id>", taskId: "<taskId>" }
65
67
  ```
68
+
66
69
  Only dispatch tasks where `ready: true`.
67
70
 
68
71
  2. Mark as in_progress:
72
+
69
73
  ```
70
74
  YOUR_AGENT_core op:update_task params:{ planId: "<id>", taskIndex: <n>, status: "in_progress" }
71
75
  ```
72
76
 
73
77
  3. Gather vault context for the task:
78
+
74
79
  ```
75
80
  YOUR_AGENT_core op:search params:{ query: "<task topic>", mode: "scan" }
76
81
  ```
@@ -114,12 +119,15 @@ Use the Agent tool with `isolation: "worktree"` when tasks touch nearby files to
114
119
  As subagents complete, collect their results. For each completed task:
115
120
 
116
121
  1. **Run spec review** — spawn a reviewer subagent:
122
+
117
123
  ```
118
124
  YOUR_AGENT_core op:plan_review_spec params:{ planId: "<id>", taskId: "<taskId>" }
119
125
  ```
126
+
120
127
  Use the returned prompt to launch a spec-review Agent that reads the ACTUAL code changes (not the implementer's self-report).
121
128
 
122
129
  2. **Record spec review outcome:**
130
+
123
131
  ```
124
132
  YOUR_AGENT_core op:plan_review_outcome params:{
125
133
  planId: "<id>", taskId: "<taskId>",
@@ -130,12 +138,15 @@ As subagents complete, collect their results. For each completed task:
130
138
  ```
131
139
 
132
140
  3. **If spec passes, run quality review:**
141
+
133
142
  ```
134
143
  YOUR_AGENT_core op:plan_review_quality params:{ planId: "<id>", taskId: "<taskId>" }
135
144
  ```
145
+
136
146
  Launch a quality-review Agent with the returned prompt.
137
147
 
138
148
  4. **Record quality review outcome:**
149
+
139
150
  ```
140
151
  YOUR_AGENT_core op:plan_review_outcome params:{
141
152
  planId: "<id>", taskId: "<taskId>",
@@ -147,12 +158,12 @@ As subagents complete, collect their results. For each completed task:
147
158
 
148
159
  5. **Handle outcomes:**
149
160
 
150
- | Spec | Quality | Action |
151
- |------|---------|--------|
152
- | Pass | Pass | Mark task completed |
153
- | Fail | — | Dispatch fix subagent with failure feedback (max 2 retries) |
154
- | Pass | Critical issues | Dispatch targeted fix subagent (max 2 retries) |
155
- | Pass | Minor issues only | Mark completed, note issues for later |
161
+ | Spec | Quality | Action |
162
+ | ---- | ----------------- | ----------------------------------------------------------- |
163
+ | Pass | Pass | Mark task completed |
164
+ | Fail | — | Dispatch fix subagent with failure feedback (max 2 retries) |
165
+ | Pass | Critical issues | Dispatch targeted fix subagent (max 2 retries) |
166
+ | Pass | Minor issues only | Mark completed, note issues for later |
156
167
 
157
168
  6. **Mark completed:**
158
169
  ```
@@ -164,6 +175,7 @@ As subagents complete, collect their results. For each completed task:
164
175
  After all tasks in a wave are complete (or failed after retries):
165
176
 
166
177
  1. Report wave results to the user:
178
+
167
179
  ```
168
180
  ## Wave N Complete
169
181
 
@@ -216,23 +228,23 @@ YOUR_AGENT_core op:session_capture params:{
216
228
 
217
229
  ## Subagent Isolation Rules
218
230
 
219
- | Situation | Isolation |
220
- |-----------|-----------|
221
- | Tasks touch completely different directories | No isolation needed |
222
- | Tasks touch files in the same package | Use `isolation: "worktree"` |
223
- | Tasks modify the same file | **Do NOT parallelize** — run sequentially |
231
+ | Situation | Isolation |
232
+ | -------------------------------------------- | ----------------------------------------- |
233
+ | Tasks touch completely different directories | No isolation needed |
234
+ | Tasks touch files in the same package | Use `isolation: "worktree"` |
235
+ | Tasks modify the same file | **Do NOT parallelize** — run sequentially |
224
236
 
225
237
  When using worktree isolation, the controller must merge worktree changes back after review passes.
226
238
 
227
239
  ## Failure Handling
228
240
 
229
- | Failure | Response |
230
- |---------|----------|
231
- | Subagent reports blocker | Pause that task, continue others in the wave |
232
- | Spec review fails | Dispatch fix subagent with feedback (retry 1/2) |
233
- | Second retry fails | Mark task as `failed`, escalate to user |
234
- | Merge conflict from worktree | Resolve manually, then re-run quality review |
235
- | All tasks in wave fail | Stop execution, report to user |
241
+ | Failure | Response |
242
+ | ---------------------------- | ----------------------------------------------- |
243
+ | Subagent reports blocker | Pause that task, continue others in the wave |
244
+ | Spec review fails | Dispatch fix subagent with feedback (retry 1/2) |
245
+ | Second retry fails | Mark task as `failed`, escalate to user |
246
+ | Merge conflict from worktree | Resolve manually, then re-run quality review |
247
+ | All tasks in wave fail | Stop execution, report to user |
236
248
 
237
249
  ## Capture Learnings
238
250
 
@@ -248,30 +260,32 @@ YOUR_AGENT_core op:capture_quick params:{
248
260
  ## When to Fall Back to Sequential
249
261
 
250
262
  **Switch to executing-plans skill mid-execution when:**
263
+
251
264
  - Subagents keep conflicting on shared files
252
265
  - Merge resolution is taking longer than the parallelization saves
253
266
  - User requests sequential execution
254
267
 
255
268
  ## Agent Tools Reference
256
269
 
257
- | Op | When to Use |
258
- |----|-------------|
259
- | `get_plan` | Load tracked plan |
260
- | `plan_list_tasks` | List all tasks with dependencies |
261
- | `plan_dispatch` | Check task readiness (dependencies met?) |
262
- | `update_task` | Mark tasks in_progress / completed / failed |
263
- | `plan_review_spec` | Generate spec compliance review prompt |
264
- | `plan_review_quality` | Generate code quality review prompt |
265
- | `plan_review_outcome` | Record review pass/fail result |
266
- | `plan_reconcile` | Post-execution drift analysis |
267
- | `plan_complete_lifecycle` | Extract knowledge, archive |
268
- | `session_capture` | Save session context |
269
- | `capture_quick` | Capture mid-execution learnings |
270
- | `search` | Vault lookup for task context |
270
+ | Op | When to Use |
271
+ | ------------------------- | ------------------------------------------- |
272
+ | `get_plan` | Load tracked plan |
273
+ | `plan_list_tasks` | List all tasks with dependencies |
274
+ | `plan_dispatch` | Check task readiness (dependencies met?) |
275
+ | `update_task` | Mark tasks in_progress / completed / failed |
276
+ | `plan_review_spec` | Generate spec compliance review prompt |
277
+ | `plan_review_quality` | Generate code quality review prompt |
278
+ | `plan_review_outcome` | Record review pass/fail result |
279
+ | `plan_reconcile` | Post-execution drift analysis |
280
+ | `plan_complete_lifecycle` | Extract knowledge, archive |
281
+ | `session_capture` | Save session context |
282
+ | `capture_quick` | Capture mid-execution learnings |
283
+ | `search` | Vault lookup for task context |
271
284
 
272
285
  ## Integration
273
286
 
274
287
  **Required skills:**
288
+
275
289
  - writing-plans — Creates the plan this skill executes
276
290
  - verification-before-completion — Verify work before claiming completion
277
291
  - executing-plans — Fallback for sequential execution
@@ -87,12 +87,12 @@ If quality issues found: `op:curator_consolidate` then `op:brain_build_intellige
87
87
 
88
88
  ## Quick Reference
89
89
 
90
- | Op | When to Use |
91
- |----|-------------|
92
- | `brain_stats` / `brain_strengths` | Metrics and patterns |
93
- | `vault_recent` | Recent captures |
94
- | `memory_topics` / `memory_stats` | Knowledge clusters |
95
- | `plan_stats` | Plan completion |
96
- | `admin_search_insights` | Search misses |
97
- | `curator_health_audit` | Vault quality |
98
- | `capture_knowledge` | Persist retrospective |
90
+ | Op | When to Use |
91
+ | --------------------------------- | --------------------- |
92
+ | `brain_stats` / `brain_strengths` | Metrics and patterns |
93
+ | `vault_recent` | Recent captures |
94
+ | `memory_topics` / `memory_stats` | Knowledge clusters |
95
+ | `plan_stats` | Plan completion |
96
+ | `admin_search_insights` | Search misses |
97
+ | `curator_health_audit` | Vault quality |
98
+ | `capture_knowledge` | Persist retrospective |
@@ -19,12 +19,14 @@ YOUR_AGENT_core op:route_intent
19
19
  ### 2. Search All Knowledge Sources
20
20
 
21
21
  **Vault** — previous decisions, patterns, anti-patterns:
22
+
22
23
  ```
23
24
  YOUR_AGENT_core op:search_intelligent
24
25
  params: { query: "<the decision or options>" }
25
26
  ```
26
27
 
27
28
  **Brain** — proven approaches:
29
+
28
30
  ```
29
31
  YOUR_AGENT_core op:brain_strengths
30
32
  YOUR_AGENT_core op:brain_recommend
@@ -32,6 +34,7 @@ YOUR_AGENT_core op:brain_recommend
32
34
  ```
33
35
 
34
36
  **Cross-project** — what other projects chose:
37
+
35
38
  ```
36
39
  YOUR_AGENT_core op:memory_cross_project_search
37
40
  params: { query: "<topic>", crossProject: true }
@@ -87,11 +90,11 @@ YOUR_AGENT_core op:capture_knowledge
87
90
 
88
91
  ## Quick Reference
89
92
 
90
- | Op | When to Use |
91
- |----|-------------|
92
- | `route_intent` | Classify decision type |
93
- | `search_intelligent` | Find previous decisions |
94
- | `brain_strengths` / `brain_recommend` | Proven approaches |
95
- | `memory_cross_project_search` | Other projects' choices |
96
- | `memory_search` | Session context |
97
- | `capture_knowledge` | Persist the decision |
93
+ | Op | When to Use |
94
+ | ------------------------------------- | ----------------------- |
95
+ | `route_intent` | Classify decision type |
96
+ | `search_intelligent` | Find previous decisions |
97
+ | `brain_strengths` / `brain_recommend` | Proven approaches |
98
+ | `memory_cross_project_search` | Other projects' choices |
99
+ | `memory_search` | Session context |
100
+ | `capture_knowledge` | Persist the decision |
@@ -91,13 +91,13 @@ YOUR_AGENT_core op:session_capture
91
91
 
92
92
  ## Quick Reference
93
93
 
94
- | Phase | Key Activities | Tools |
95
- |-------|---------------|-------|
96
- | 0. Search | Vault, web, memory | `search_intelligent`, `brain_strengths`, `memory_search` |
97
- | 1. Root Cause | Read errors, reproduce, trace | `loop_iterate` |
98
- | 2. Pattern | Find working examples, compare | `search_intelligent` |
99
- | 3. Hypothesis | Form theory, test minimally | `loop_iterate` |
100
- | 4. Implementation | Test, fix, verify | `loop_iterate` |
101
- | 5. Capture | Persist root cause | `capture_knowledge`, `loop_complete` |
94
+ | Phase | Key Activities | Tools |
95
+ | ----------------- | ------------------------------ | -------------------------------------------------------- |
96
+ | 0. Search | Vault, web, memory | `search_intelligent`, `brain_strengths`, `memory_search` |
97
+ | 1. Root Cause | Read errors, reproduce, trace | `loop_iterate` |
98
+ | 2. Pattern | Find working examples, compare | `search_intelligent` |
99
+ | 3. Hypothesis | Form theory, test minimally | `loop_iterate` |
100
+ | 4. Implementation | Test, fix, verify | `loop_iterate` |
101
+ | 5. Capture | Persist root cause | `capture_knowledge`, `loop_complete` |
102
102
 
103
103
  **Related skills:** test-driven-development, verification-before-completion, fix-and-learn
@@ -75,17 +75,17 @@ YOUR_AGENT_core op:capture_quick
75
75
  - Test passes immediately (testing existing behavior, not new)
76
76
  - Multiple behaviors in one test ("and" in name means split it)
77
77
 
78
- | Problem | Solution |
79
- |---------|----------|
80
- | Don't know how to test | Write wished-for API first |
81
- | Must mock everything | Code too coupled — use DI |
82
- | Test setup huge | Extract helpers or simplify design |
78
+ | Problem | Solution |
79
+ | ---------------------- | ---------------------------------- |
80
+ | Don't know how to test | Write wished-for API first |
81
+ | Must mock everything | Code too coupled — use DI |
82
+ | Test setup huge | Extract helpers or simplify design |
83
83
 
84
84
  ## Quick Reference
85
85
 
86
- | Op | When to Use |
87
- |----|-------------|
88
- | `search_intelligent` | Find testing patterns |
89
- | `brain_strengths` | Proven testing approaches |
90
- | `loop_start` / `loop_iterate` / `loop_complete` | TDD cycle tracking |
91
- | `capture_quick` | Capture new testing patterns |
86
+ | Op | When to Use |
87
+ | ----------------------------------------------- | ---------------------------- |
88
+ | `search_intelligent` | Find testing patterns |
89
+ | `brain_strengths` | Proven testing approaches |
90
+ | `loop_start` / `loop_iterate` / `loop_complete` | TDD cycle tracking |
91
+ | `capture_quick` | Capture new testing patterns |
@@ -25,13 +25,13 @@ If similar entry exists, update it instead of creating a duplicate.
25
25
 
26
26
  ### 2. Classify the Knowledge
27
27
 
28
- | Type | Description |
29
- |------|-------------|
30
- | **pattern** | Works and should be repeated |
31
- | **anti-pattern** | Fails and should be avoided |
32
- | **workflow** | Steps for a specific task |
33
- | **principle** | Guiding rule or heuristic |
34
- | **decision** | Architectural choice with rationale |
28
+ | Type | Description |
29
+ | ---------------- | ----------------------------------- |
30
+ | **pattern** | Works and should be repeated |
31
+ | **anti-pattern** | Fails and should be avoided |
32
+ | **workflow** | Steps for a specific task |
33
+ | **principle** | Guiding rule or heuristic |
34
+ | **decision** | Architectural choice with rationale |
35
35
 
36
36
  ### 3. Capture
37
37
 
@@ -76,11 +76,11 @@ For cross-project knowledge: `op:memory_promote_to_global params: { entryId: "<i
76
76
 
77
77
  ## Quick Reference
78
78
 
79
- | Op | When to Use |
80
- |----|-------------|
81
- | `search_intelligent` | Check for duplicates |
82
- | `capture_knowledge` / `capture_quick` | Persist to vault |
83
- | `curator_groom` / `curator_enrich` | Post-capture quality |
84
- | `curator_contradictions` | Find conflicts |
85
- | `memory_promote_to_global` | Share cross-project |
86
- | `admin_health` | Verify health |
79
+ | Op | When to Use |
80
+ | ------------------------------------- | -------------------- |
81
+ | `search_intelligent` | Check for duplicates |
82
+ | `capture_knowledge` / `capture_quick` | Persist to vault |
83
+ | `curator_groom` / `curator_enrich` | Post-capture quality |
84
+ | `curator_contradictions` | Find conflicts |
85
+ | `memory_promote_to_global` | Share cross-project |
86
+ | `admin_health` | Verify health |
@@ -72,13 +72,13 @@ If all vault strategies return nothing, search the web. If web finds something u
72
72
 
73
73
  ## Quick Reference
74
74
 
75
- | Op | When to Use |
76
- |----|-------------|
77
- | `search_intelligent` | Default semantic search |
78
- | `search` | Structured search with filters |
79
- | `vault_tags` / `vault_domains` | Browse knowledge landscape |
80
- | `vault_recent` | Recently modified entries |
81
- | `vault_age_report` | Stale entries |
82
- | `memory_cross_project_search` | Cross-project search |
83
- | `brain_strengths` / `brain_global_patterns` | Proven patterns |
84
- | `capture_quick` | Capture web findings |
75
+ | Op | When to Use |
76
+ | ------------------------------------------- | ------------------------------ |
77
+ | `search_intelligent` | Default semantic search |
78
+ | `search` | Structured search with filters |
79
+ | `vault_tags` / `vault_domains` | Browse knowledge landscape |
80
+ | `vault_recent` | Recently modified entries |
81
+ | `vault_age_report` | Stale entries |
82
+ | `memory_cross_project_search` | Cross-project search |
83
+ | `brain_strengths` / `brain_global_patterns` | Proven patterns |
84
+ | `capture_quick` | Capture web findings |
@@ -23,6 +23,7 @@ YOUR_AGENT_core op:curator_contradictions
23
23
  ```
24
24
 
25
25
  **What to look for:**
26
+
26
27
  - Two patterns that recommend opposite approaches for the same situation
27
28
  - An anti-pattern that contradicts an active pattern
28
29
  - Entries from different time periods with conflicting advice (the older one may be stale)
@@ -38,6 +39,7 @@ YOUR_AGENT_core op:vault_age_report
38
39
  ```
39
40
 
40
41
  **Indicators:**
42
+
41
43
  - Entries >60 days without access or update
42
44
  - Patterns referencing APIs, libraries, or versions that have changed
43
45
  - Entries tagged with technologies the project no longer uses
@@ -55,6 +57,7 @@ YOUR_AGENT_core op:curator_detect_duplicates
55
57
  ```
56
58
 
57
59
  **Indicators:**
60
+
58
61
  - Entries with zero inbound or outbound links
59
62
  - Entries never returned in search results (check search insights)
60
63
  - Entries with no tags or only generic tags
@@ -73,6 +76,7 @@ YOUR_AGENT_core op:curator_detect_duplicates
73
76
  ```
74
77
 
75
78
  **Indicators:**
79
+
76
80
  - High similarity scores between entries
77
81
  - Same tags and category but different titles
78
82
  - Entries captured in different sessions about the same topic
@@ -89,6 +93,7 @@ YOUR_AGENT_core op:curator_health_audit
89
93
  ```
90
94
 
91
95
  **Indicators:**
96
+
92
97
  - Description under 50 characters
93
98
  - No examples or context
94
99
  - Missing "why" — only states "what" without rationale
@@ -107,6 +112,7 @@ YOUR_AGENT_core op:vault_tags
107
112
  ```
108
113
 
109
114
  **Indicators:**
115
+
110
116
  - Near-duplicate categories (e.g., "error-handling" and "errors" and "exception-handling")
111
117
  - Categories with only 1-2 entries (too granular)
112
118
  - Tags used inconsistently (same concept, different tag names)
@@ -123,6 +129,7 @@ YOUR_AGENT_core op:brain_strengths
123
129
  ```
124
130
 
125
131
  **Indicators:**
132
+
126
133
  - Patterns with high initial strength that have decayed below 0.3
127
134
  - Patterns that were strong but haven't received positive feedback in >30 days
128
135
  - Patterns with mixed feedback (both positive and negative) — unresolved
@@ -131,13 +138,14 @@ YOUR_AGENT_core op:brain_strengths
131
138
 
132
139
  ### 8. Knowledge Gap Smells
133
140
 
134
- Areas where the vault *should* have knowledge but doesn't.
141
+ Areas where the vault _should_ have knowledge but doesn't.
135
142
 
136
143
  ```
137
144
  YOUR_AGENT_core op:admin_search_insights
138
145
  ```
139
146
 
140
147
  **Indicators:**
148
+
141
149
  - Repeated search queries that return no results
142
150
  - Domains the project uses but vault has no entries for
143
151
  - Anti-patterns captured without corresponding patterns (what to do instead?)
@@ -166,11 +174,11 @@ YOUR_AGENT_core op:admin_search_insights
166
174
 
167
175
  For each smell category, assess severity:
168
176
 
169
- | Severity | Meaning |
170
- |----------|---------|
171
- | 🟢 Clean | No issues in this category |
172
- | 🟡 Minor | 1-3 instances, low impact |
173
- | 🟠 Moderate | Multiple instances, degrading quality |
177
+ | Severity | Meaning |
178
+ | ----------- | ------------------------------------------ |
179
+ | 🟢 Clean | No issues in this category |
180
+ | 🟡 Minor | 1-3 instances, low impact |
181
+ | 🟠 Moderate | Multiple instances, degrading quality |
174
182
  | 🔴 Critical | Widespread, actively causing bad decisions |
175
183
 
176
184
  ### Step 3: Present the Report
@@ -237,15 +245,15 @@ After fixes: `op:brain_build_intelligence` to rebuild with clean data.
237
245
 
238
246
  ## Quick Reference
239
247
 
240
- | Smell | Detection Op | Fix Op |
241
- |-------|-------------|--------|
242
- | Contradictions | `curator_contradictions` | `curator_resolve_contradiction` |
243
- | Staleness | `vault_age_report` | Review + archive/update |
244
- | Orphans | `admin_vault_analytics` | Link or archive |
245
- | Duplicates | `curator_detect_duplicates` | `curator_groom` (merge) |
246
- | Shallow entries | `curator_health_audit` | Enrich or archive |
247
- | Category drift | `vault_domains` + `vault_tags` | `curator_groom_all` |
248
- | Confidence decay | `brain_strengths` | Reinforce or retire |
249
- | Knowledge gaps | `admin_search_insights` | `capture_knowledge` |
248
+ | Smell | Detection Op | Fix Op |
249
+ | ---------------- | ------------------------------ | ------------------------------- |
250
+ | Contradictions | `curator_contradictions` | `curator_resolve_contradiction` |
251
+ | Staleness | `vault_age_report` | Review + archive/update |
252
+ | Orphans | `admin_vault_analytics` | Link or archive |
253
+ | Duplicates | `curator_detect_duplicates` | `curator_groom` (merge) |
254
+ | Shallow entries | `curator_health_audit` | Enrich or archive |
255
+ | Category drift | `vault_domains` + `vault_tags` | `curator_groom_all` |
256
+ | Confidence decay | `brain_strengths` | Reinforce or retire |
257
+ | Knowledge gaps | `admin_search_insights` | `capture_knowledge` |
250
258
 
251
259
  **Related skills:** health-check (operational status), vault-curate (active cleanup), knowledge-harvest (fill gaps)
@@ -43,12 +43,12 @@ If any check reports problems, address before claiming completion.
43
43
 
44
44
  ## Common Failures
45
45
 
46
- | Claim | Requires | Not Sufficient |
47
- |-------|----------|----------------|
48
- | Tests pass | Test output: 0 failures | Previous run, "should pass" |
49
- | Build succeeds | Build command: exit 0 | Linter passing |
50
- | Bug fixed | Original symptom passes | "Code changed, assumed fixed" |
51
- | Requirements met | Line-by-line checklist | Tests passing alone |
46
+ | Claim | Requires | Not Sufficient |
47
+ | ---------------- | ----------------------- | ----------------------------- |
48
+ | Tests pass | Test output: 0 failures | Previous run, "should pass" |
49
+ | Build succeeds | Build command: exit 0 | Linter passing |
50
+ | Bug fixed | Original symptom passes | "Code changed, assumed fixed" |
51
+ | Requirements met | Line-by-line checklist | Tests passing alone |
52
52
 
53
53
  ## Red Flags — STOP
54
54
 
@@ -57,12 +57,12 @@ If any check reports problems, address before claiming completion.
57
57
  - About to commit/push/PR without verification
58
58
  - Relying on partial verification
59
59
 
60
- | Excuse | Reality |
61
- |--------|---------|
62
- | "Should work now" | RUN the verification |
63
- | "I'm confident" | Confidence is not evidence |
64
- | "Just this once" | No exceptions |
65
- | "Partial check is enough" | Partial proves nothing |
60
+ | Excuse | Reality |
61
+ | ------------------------- | -------------------------- |
62
+ | "Should work now" | RUN the verification |
63
+ | "I'm confident" | Confidence is not evidence |
64
+ | "Just this once" | No exceptions |
65
+ | "Partial check is enough" | Partial proves nothing |
66
66
 
67
67
  ## After Verification
68
68
 
@@ -77,9 +77,9 @@ Capture session summary: `YOUR_AGENT_core op:session_capture params: { summary:
77
77
 
78
78
  ## Quick Reference
79
79
 
80
- | Op | When to Use |
81
- |----|-------------|
82
- | `admin_health` | Quick system health check |
83
- | `admin_diagnostic` | Comprehensive diagnostic |
84
- | `admin_vault_analytics` | Knowledge quality metrics |
85
- | `session_capture` | Persist verified completion context |
80
+ | Op | When to Use |
81
+ | ----------------------- | ----------------------------------- |
82
+ | `admin_health` | Quick system health check |
83
+ | `admin_diagnostic` | Comprehensive diagnostic |
84
+ | `admin_vault_analytics` | Knowledge quality metrics |
85
+ | `session_capture` | Persist verified completion context |
@@ -97,12 +97,12 @@ Offer execution choice: subagent-driven (this session) or parallel session with
97
97
 
98
98
  ## Quick Reference
99
99
 
100
- | Op | When to Use |
101
- |----|-------------|
102
- | `search_intelligent` | Find patterns before planning |
103
- | `brain_strengths` | Proven approaches |
104
- | `create_plan` | Create tracked plan |
105
- | `plan_grade` / `plan_auto_improve` | Grade and improve |
106
- | `plan_iterate` | Iterate with feedback |
107
- | `plan_split` | Split into tasks |
108
- | `approve_plan` | Lock in approved plan |
100
+ | Op | When to Use |
101
+ | ---------------------------------- | ----------------------------- |
102
+ | `search_intelligent` | Find patterns before planning |
103
+ | `brain_strengths` | Proven approaches |
104
+ | `create_plan` | Create tracked plan |
105
+ | `plan_grade` / `plan_auto_improve` | Grade and improve |
106
+ | `plan_iterate` | Iterate with feedback |
107
+ | `plan_split` | Split into tasks |
108
+ | `approve_plan` | Lock in approved plan |