heimdall-agent 1.1.0 → 1.4.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 (60) hide show
  1. package/README.md +101 -31
  2. package/README.pt-BR.md +124 -40
  3. package/agents/code-sentinel.md +7 -1
  4. package/agents/frontend-designer.md +6 -1
  5. package/agents/modernizer.md +8 -3
  6. package/agents/orchestrator.md +22 -8
  7. package/agents/reviewer.md +3 -1
  8. package/config/agents.json +177 -5
  9. package/config/mcp.json +1 -1
  10. package/config/mcp.resolved.json +74 -0
  11. package/config/mcp.template.json +85 -0
  12. package/config/models.json +70 -0
  13. package/config/profiles.json +4 -3
  14. package/config/skills.json +321 -93
  15. package/docs/SKILLS.md +158 -75
  16. package/docs/designs/old/2026-11-16 upstream-skill-sync-and-provenance-links.md +60 -0
  17. package/docs/runs/skill-audit/2026-11-12-compare-report.json +1028 -0
  18. package/docs/runs/skill-audit/2026-11-12-upstream-audit.json +275 -0
  19. package/doctrine/AGENTS.md +7 -4
  20. package/hooks/heimdall-hook.cjs +16 -1
  21. package/hooks/hooks.json +11 -0
  22. package/lib/catalog-sync.cjs +8 -3
  23. package/lib/model-context.cjs +50 -1
  24. package/lib/model-router.cjs +294 -0
  25. package/package.json +1 -1
  26. package/playbooks/01-interactive-grilling-gate.md +14 -10
  27. package/playbooks/03-adversarial-code-review.md +12 -4
  28. package/playbooks/05-canonical-plan-template.md +8 -13
  29. package/playbooks/06-model-registry-matrix.md +27 -19
  30. package/readme.html +1006 -0
  31. package/setup.mjs +317 -206
  32. package/skills/antislop-copywriting/SKILL.md +36 -1
  33. package/skills/brainstorming/SKILL.md +60 -38
  34. package/skills/codebase-design/DEEPENING.md +37 -0
  35. package/skills/codebase-design/DESIGN-IT-TWICE.md +44 -0
  36. package/skills/codebase-design/SKILL.md +114 -0
  37. package/skills/communication-doctrine/SKILL.md +2 -2
  38. package/skills/domain-modeling/ADR-FORMAT.md +47 -0
  39. package/skills/domain-modeling/GLOSSARY-FORMAT.md +60 -0
  40. package/skills/domain-modeling/SKILL.md +74 -0
  41. package/skills/executing-plans/SKILL.md +6 -4
  42. package/skills/grill-me/SKILL.md +65 -0
  43. package/skills/handoff/SKILL.md +77 -0
  44. package/skills/improve-codebase-architecture/HTML-REPORT.md +123 -0
  45. package/skills/improve-codebase-architecture/SKILL.md +71 -0
  46. package/skills/mcp-cleanup/SKILL.md +61 -0
  47. package/skills/mcp-sync/SKILL.md +58 -0
  48. package/skills/modern-web-guidance/SKILL.md +90 -0
  49. package/skills/owasp-security/reference/config-and-supply-chain.md +346 -344
  50. package/skills/owasp-security/reference/languages.md +378 -372
  51. package/skills/owasp-security/reference/owasp-report.md +1144 -1140
  52. package/skills/owasp-security/reference/review-checklist.md +134 -132
  53. package/skills/ruminate/SKILL.md +140 -0
  54. package/skills/subagent-driven-development/SKILL.md +7 -4
  55. package/skills/taste-skill/SKILL.md +367 -534
  56. package/skills/to-spec/SKILL.md +75 -0
  57. package/skills/to-tickets/SKILL.md +105 -0
  58. package/skills/upstream-skill-sync/SKILL.md +46 -0
  59. package/skills/wayfinder/SKILL.md +128 -0
  60. package/skills/writing-plans/SKILL.md +1 -1
@@ -1,132 +1,134 @@
1
- # Security Review Checklist
2
-
3
- Coverage list for step 3 of the review workflow in `SKILL.md`. Skip sections the change does not
4
- touch. A checked-off gap is a lead to trace, not a finding: run it through the triage rubric in
5
- `SKILL.md` before reporting it.
6
-
7
- ## Contents
8
- - Input Handling (A05)
9
- - Authentication & Sessions (A07)
10
- - Access Control (A01)
11
- - Server-Side Request Forgery (A01)
12
- - File Handling (A01)
13
- - Insecure Design (A06)
14
- - Configuration & Hardening (A02)
15
- - Dependencies & Supply Chain (A03)
16
- - Serialization & Data Integrity (A08)
17
- - Data Protection (A04)
18
- - Error Handling & Logging (A09/A10)
19
- - LLM and Agent Features (LLM Top 10 2026, Agentic 2026)
20
-
21
- ## Input Handling (A05)
22
- - [ ] All user input validated server-side
23
- - [ ] Using parameterized queries (not string concatenation)
24
- - [ ] Input length limits enforced
25
- - [ ] Allowlist validation preferred over denylist
26
- - [ ] Output encoded for its context: HTML body, attribute, URL, JS, CSS are different rules
27
- - [ ] No raw HTML sinks fed by user data (`innerHTML`, `dangerouslySetInnerHTML`, `|safe`, `v-html`)
28
- - [ ] OS commands invoked with an argv array, never a shell string
29
- - [ ] XML parsers configured with external entity resolution disabled (XXE, filed under A02 in 2025)
30
- - [ ] Templates never built from user input (SSTI)
31
-
32
- ## Authentication & Sessions (A07)
33
- - [ ] Passwords hashed with Argon2/bcrypt (not MD5/SHA1)
34
- - [ ] Session tokens have sufficient entropy (128+ bits)
35
- - [ ] New session token issued on login (no session fixation)
36
- - [ ] Sessions invalidated on logout, password change, and account disable
37
- - [ ] Cookies set `HttpOnly`, `Secure`, and `SameSite=Lax` or stricter
38
- - [ ] MFA available for sensitive operations
39
- - [ ] JWTs: algorithm pinned server-side (`alg: none` and algorithm confusion rejected),
40
- signature verified, `exp`/`aud`/`iss` checked
41
-
42
- ## Access Control (A01)
43
- - [ ] Authorization checked on every request
44
- - [ ] Using object references user cannot manipulate
45
- - [ ] Deny by default policy
46
- - [ ] Privilege escalation paths reviewed
47
- - [ ] Object-level checks verify ownership/tenancy, not just "is authenticated" (IDOR/BOLA)
48
- - [ ] State-changing requests protected against CSRF (token or `SameSite` + origin check)
49
- - [ ] Redirect targets validated against an allowlist (no open redirect)
50
- - [ ] CORS: no `Access-Control-Allow-Origin: *` combined with credentials, no origin reflection
51
-
52
- ## Server-Side Request Forgery (A01)
53
- - [ ] User-supplied URLs resolved and validated against an allowlist of hosts/schemes
54
- - [ ] Private, loopback, and link-local ranges blocked, including after DNS resolution
55
- - [ ] Redirects not followed blindly to a new host (re-validate each hop)
56
- - [ ] Cloud metadata endpoints (`169.254.169.254`) unreachable from the app
57
-
58
- ## File Handling (A01)
59
- - [ ] Upload type validated by content, not just extension or `Content-Type`
60
- - [ ] Uploads stored outside the web root, served with a non-executable content type
61
- - [ ] File size limits and quota enforced
62
- - [ ] Paths built from user input canonicalized and confined to a base directory (no `../`)
63
- - [ ] Archive extraction guards against path traversal and zip bombs
64
-
65
- ## Insecure Design (A06)
66
- - [ ] Prices, quantities, roles, and state transitions decided server-side, never taken from the client
67
- - [ ] Rate limits on login, password reset, OTP, signup, and expensive operations
68
- - [ ] Multi-step flows can't be skipped, reordered, or replayed (one-time tokens, idempotency keys)
69
- - [ ] Balance, inventory, and coupon updates are atomic (no check-then-write race)
70
-
71
- ## Configuration & Hardening (A02)
72
- - [ ] Debug mode, verbose errors, and dev tooling disabled in production
73
- - [ ] Default credentials and sample/admin accounts removed
74
- - [ ] Unused features, ports, endpoints, and HTTP methods disabled
75
- - [ ] Security headers set: CSP without `unsafe-inline`/`unsafe-eval`, HSTS,
76
- `X-Content-Type-Options: nosniff`, `Referrer-Policy`
77
- - [ ] Cloud storage and object buckets are not publicly readable/writable
78
- - [ ] Container/infra config reviewed (non-root user, no privileged mode, no secrets in image layers)
79
-
80
- ## Dependencies & Supply Chain (A03)
81
- - [ ] Lockfile committed and versions pinned (no floating ranges in production builds)
82
- - [ ] Dependencies scanned for known vulnerabilities and unmaintained packages
83
- - [ ] Package names checked against typosquats and dependency confusion (internal names claimed publicly)
84
- - [ ] Third-party scripts loaded with Subresource Integrity, or self-hosted
85
- - [ ] Build and CI scripts reviewed: install hooks and pipeline steps run with repo write access
86
- - [ ] Artifacts and releases signed; signatures verified before deploy
87
-
88
- ## Serialization & Data Integrity (A08)
89
- - [ ] No deserialization of untrusted data with a native format (`pickle`, `Marshal`,
90
- `ObjectInputStream`, `BinaryFormatter`, `yaml.load`)
91
- - [ ] JSON/schema-validated formats used instead, with a type allowlist
92
- - [ ] Auto-update and plugin loading verify signatures before execution
93
-
94
- ## Data Protection (A04)
95
- - [ ] Sensitive data encrypted at rest
96
- - [ ] TLS for all data in transit
97
- - [ ] No sensitive data in URLs/logs
98
- - [ ] Secrets in environment/vault (not code), and not in git history or container layers
99
- - [ ] Authenticated encryption (AES-GCM/ChaCha20-Poly1305); no ECB, no unauthenticated CBC
100
- - [ ] IVs/nonces unique per encryption; randomness from a CSPRNG, not `Math.random`/`rand()`
101
- - [ ] Secrets and tokens compared in constant time
102
-
103
- ## Error Handling & Logging (A09/A10)
104
- - [ ] No stack traces exposed to users
105
- - [ ] Fail-closed on errors (deny, not allow)
106
- - [ ] All exceptions logged with context
107
- - [ ] Consistent error responses (no user/account enumeration via message or timing)
108
- - [ ] Auth events, authorization failures, and security-control failures logged
109
- - [ ] Logs exclude credentials, tokens, and PII; user input encoded to prevent log injection
110
- - [ ] Empty `catch` blocks and swallowed errors reviewed: silent failure hides attacks
111
-
112
- ## LLM and Agent Features (LLM Top 10 2026, Agentic 2026)
113
- - [ ] Untrusted text (user input, web pages, email, RAG chunks, tool output) can't steer a model
114
- that holds privileged tools (LLM01, ASI01)
115
- - [ ] Model output validated or escaped before any SQL, shell, HTML, code, or tool argument (LLM10)
116
- - [ ] Tools minimal and scoped; no general shell or HTTP tool unless required; destructive
117
- actions need human approval (LLM03, ASI02)
118
- - [ ] Agent credentials short-lived and scoped to the task, never an admin or the user's full session (ASI03)
119
- - [ ] Retrieval enforces the caller's tenant and permissions at query time (LLM02, LLM09)
120
- - [ ] No secrets or authorization logic in the system prompt, tool schemas, or other hidden context (LLM08)
121
- - [ ] MCP servers, plugins, and models pinned and from trusted sources (LLM04, ASI04)
122
- - [ ] Generated code runs in a sandbox (ASI05)
123
- - [ ] Writes to agent memory or the vector store validated, so untrusted content can't persist
124
- instructions (ASI06)
125
- - [ ] Per-user caps on requests, tokens, tool calls, and cost, plus hard timeouts (LLM06)
126
- - [ ] Messages between agents authenticated and integrity-checked; a receiving agent doesn't
127
- trust the sender's claims about identity or authority (ASI07)
128
- - [ ] One agent's failure or bad output can't cascade: step, retry, and fan-out limits, plus
129
- circuit breakers between components (ASI08)
130
- - [ ] AI-generated content labelled; approval prompts show the real action, so an agent can't
131
- talk a user into approving something else (ASI09)
132
- - [ ] Tool calls logged, with a way to stop a running agent (ASI10)
1
+ # Security Review Checklist
2
+
3
+ Coverage list for step 3 of the review workflow in `SKILL.md`. Skip sections the change does not
4
+ touch. A checked-off gap is a lead to trace, not a finding: run it through the triage rubric in
5
+ `SKILL.md` before reporting it.
6
+
7
+ ## Contents
8
+ - Input Handling (A05)
9
+ - Authentication & Sessions (A07)
10
+ - Access Control (A01)
11
+ - Server-Side Request Forgery (A01)
12
+ - File Handling (A01)
13
+ - Insecure Design (A06)
14
+ - Configuration & Hardening (A02)
15
+ - Dependencies & Supply Chain (A03)
16
+ - Serialization & Data Integrity (A08)
17
+ - Data Protection (A04)
18
+ - Error Handling & Logging (A09/A10)
19
+ - LLM and Agent Features (LLM Top 10 2026, Agentic 2026)
20
+
21
+ ## Input Handling (A05)
22
+ - [ ] All user input validated server-side
23
+ - [ ] Using parameterized queries (not string concatenation)
24
+ - [ ] Input length limits enforced
25
+ - [ ] Allowlist validation preferred over denylist
26
+ - [ ] Output encoded for its context: HTML body, attribute, URL, JS, CSS are different rules
27
+ - [ ] No raw HTML sinks fed by user data (`innerHTML`, `dangerouslySetInnerHTML`, `|safe`, `v-html`)
28
+ - [ ] OS commands invoked with an argv array, never a shell string
29
+ - [ ] XML parsers configured with external entity resolution disabled (XXE, filed under A02 in 2025)
30
+ - [ ] Templates never built from user input (SSTI)
31
+
32
+ ## Authentication & Sessions (A07)
33
+ - [ ] Passwords hashed with Argon2/bcrypt (not MD5/SHA1)
34
+ - [ ] Session tokens have sufficient entropy (128+ bits)
35
+ - [ ] New session token issued on login (no session fixation)
36
+ - [ ] Sessions invalidated on logout, password change, and account disable
37
+ - [ ] Cookies set `HttpOnly`, `Secure`, and `SameSite=Lax` or stricter
38
+ - [ ] MFA available for sensitive operations
39
+ - [ ] JWTs: algorithm pinned server-side (`alg: none` and algorithm confusion rejected),
40
+ signature verified, `exp`/`aud`/`iss` checked
41
+
42
+ ## Access Control (A01)
43
+ - [ ] Authorization checked on every request
44
+ - [ ] Using object references user cannot manipulate
45
+ - [ ] Deny by default policy
46
+ - [ ] Privilege escalation paths reviewed
47
+ - [ ] Object-level checks verify ownership/tenancy, not just "is authenticated" (IDOR/BOLA)
48
+ - [ ] State-changing requests protected against CSRF (token or `SameSite` + origin check)
49
+ - [ ] Redirect targets validated against an allowlist (no open redirect)
50
+ - [ ] CORS: no `Access-Control-Allow-Origin: *` combined with credentials, no origin reflection
51
+
52
+ ## Server-Side Request Forgery (A01)
53
+ - [ ] User-supplied URLs resolved and validated against an allowlist of hosts/schemes
54
+ - [ ] Private, loopback, and link-local ranges blocked, including after DNS resolution
55
+ - [ ] The connection goes to the IP that was validated: pin it, or validate inside a custom dialer
56
+ or agent at connect time. Resolve, check, then fetch by hostname is open to DNS rebinding
57
+ - [ ] Redirects not followed blindly to a new host (re-validate each hop)
58
+ - [ ] Cloud metadata endpoints (`169.254.169.254`) unreachable from the app
59
+
60
+ ## File Handling (A01)
61
+ - [ ] Upload type validated by content, not just extension or `Content-Type`
62
+ - [ ] Uploads stored outside the web root, served with a non-executable content type
63
+ - [ ] File size limits and quota enforced
64
+ - [ ] Paths built from user input canonicalized and confined to a base directory (no `../`)
65
+ - [ ] Archive extraction guards against path traversal and zip bombs
66
+
67
+ ## Insecure Design (A06)
68
+ - [ ] Prices, quantities, roles, and state transitions decided server-side, never taken from the client
69
+ - [ ] Rate limits on login, password reset, OTP, signup, and expensive operations
70
+ - [ ] Multi-step flows can't be skipped, reordered, or replayed (one-time tokens, idempotency keys)
71
+ - [ ] Balance, inventory, and coupon updates are atomic (no check-then-write race)
72
+
73
+ ## Configuration & Hardening (A02)
74
+ - [ ] Debug mode, verbose errors, and dev tooling disabled in production
75
+ - [ ] Default credentials and sample/admin accounts removed
76
+ - [ ] Unused features, ports, endpoints, and HTTP methods disabled
77
+ - [ ] Security headers set: CSP without `unsafe-inline`/`unsafe-eval`, HSTS,
78
+ `X-Content-Type-Options: nosniff`, `Referrer-Policy`
79
+ - [ ] Cloud storage and object buckets are not publicly readable/writable
80
+ - [ ] Container/infra config reviewed (non-root user, no privileged mode, no secrets in image layers)
81
+
82
+ ## Dependencies & Supply Chain (A03)
83
+ - [ ] Lockfile committed and versions pinned (no floating ranges in production builds)
84
+ - [ ] Dependencies scanned for known vulnerabilities and unmaintained packages
85
+ - [ ] Package names checked against typosquats and dependency confusion (internal names claimed publicly)
86
+ - [ ] Third-party scripts loaded with Subresource Integrity, or self-hosted
87
+ - [ ] Build and CI scripts reviewed: install hooks and pipeline steps run with repo write access
88
+ - [ ] Artifacts and releases signed; signatures verified before deploy
89
+
90
+ ## Serialization & Data Integrity (A08)
91
+ - [ ] No deserialization of untrusted data with a native format (`pickle`, `Marshal`,
92
+ `ObjectInputStream`, `BinaryFormatter`, `yaml.load`)
93
+ - [ ] JSON/schema-validated formats used instead, with a type allowlist
94
+ - [ ] Auto-update and plugin loading verify signatures before execution
95
+
96
+ ## Data Protection (A04)
97
+ - [ ] Sensitive data encrypted at rest
98
+ - [ ] TLS for all data in transit
99
+ - [ ] No sensitive data in URLs/logs
100
+ - [ ] Secrets in environment/vault (not code), and not in git history or container layers
101
+ - [ ] Authenticated encryption (AES-GCM/ChaCha20-Poly1305); no ECB, no unauthenticated CBC
102
+ - [ ] IVs/nonces unique per encryption; randomness from a CSPRNG, not `Math.random`/`rand()`
103
+ - [ ] Secrets and tokens compared in constant time
104
+
105
+ ## Error Handling & Logging (A09/A10)
106
+ - [ ] No stack traces exposed to users
107
+ - [ ] Fail-closed on errors (deny, not allow)
108
+ - [ ] All exceptions logged with context
109
+ - [ ] Consistent error responses (no user/account enumeration via message or timing)
110
+ - [ ] Auth events, authorization failures, and security-control failures logged
111
+ - [ ] Logs exclude credentials, tokens, and PII; user input encoded to prevent log injection
112
+ - [ ] Empty `catch` blocks and swallowed errors reviewed: silent failure hides attacks
113
+
114
+ ## LLM and Agent Features (LLM Top 10 2026, Agentic 2026)
115
+ - [ ] Untrusted text (user input, web pages, email, RAG chunks, tool output) can't steer a model
116
+ that holds privileged tools (LLM01, ASI01)
117
+ - [ ] Model output validated or escaped before any SQL, shell, HTML, code, or tool argument (LLM10)
118
+ - [ ] Tools minimal and scoped; no general shell or HTTP tool unless required; destructive
119
+ actions need human approval (LLM03, ASI02)
120
+ - [ ] Agent credentials short-lived and scoped to the task, never an admin or the user's full session (ASI03)
121
+ - [ ] Retrieval enforces the caller's tenant and permissions at query time (LLM02, LLM09)
122
+ - [ ] No secrets or authorization logic in the system prompt, tool schemas, or other hidden context (LLM08)
123
+ - [ ] MCP servers, plugins, and models pinned and from trusted sources (LLM04, ASI04)
124
+ - [ ] Generated code runs in a sandbox (ASI05)
125
+ - [ ] Writes to agent memory or the vector store validated, so untrusted content can't persist
126
+ instructions (ASI06)
127
+ - [ ] Per-user caps on requests, tokens, tool calls, and cost, plus hard timeouts (LLM06)
128
+ - [ ] Messages between agents authenticated and integrity-checked; a receiving agent doesn't
129
+ trust the sender's claims about identity or authority (ASI07)
130
+ - [ ] One agent's failure or bad output can't cascade: step, retry, and fan-out limits, plus
131
+ circuit breakers between components (ASI08)
132
+ - [ ] AI-generated content labelled; approval prompts show the real action, so an agent can't
133
+ talk a user into approving something else (ASI09)
134
+ - [ ] Tool calls logged, with a way to stop a running agent (ASI10)
@@ -0,0 +1,140 @@
1
+ ---
2
+ name: ruminate
3
+ description: Mine historical Claude and Gemini session transcripts for correction patterns, repeated preferences, skill trigger failures, and doctrine violations. Writes findings as memory files or skill amendments. Use when bootstrapping a brain from existing conversation history or running periodic deep audits.
4
+ ---
5
+
6
+ # Ruminate: Session Transcript Mining
7
+
8
+ Extract actionable behavioral signals from historical session JSONLs across Claude Code and Gemini/Antigravity. This is the `/ruminate` equivalent from brainmaxxing — finding what `/reflect` missed by scanning bulk history.
9
+
10
+ ---
11
+
12
+ ## 1. When to Run
13
+
14
+ - Bootstrapping a new project's memory from existing sessions
15
+ - Periodic deep audit (weekly/monthly) after accumulating corrections
16
+ - After noticing repeated friction with a specific agent or skill
17
+ - Before major skill/agent refactors to ground changes in evidence
18
+
19
+ ---
20
+
21
+ ## 2. Data Sources
22
+
23
+ ### Claude Code Sessions
24
+ - **Location**: `C:\Users\Bernardo\.claude\projects\<project-dir>\*.jsonl`
25
+ - **Exclude**: `subagents\` subdirectories (noise; focus on main orchestrator turns)
26
+ - **Schema**: Each line is JSON. User messages have `"type":"user"` with `"message.content"`. Assistant messages have `"type":"assistant"`. Tool calls appear as `"type":"tool_use"`. Timestamps in ISO 8601.
27
+
28
+ ### Gemini/Antigravity Sessions
29
+ - **Location**: `C:\Users\Bernardo\.gemini\antigravity-cli\history.jsonl`
30
+ - **Schema**: Each line is JSON with `"display"` (user prompt text), `"timestamp"` (epoch ms), `"workspace"`, optional `"conversationId"`. Simpler than Claude — user prompts only, no assistant responses inline.
31
+
32
+ ---
33
+
34
+ ## 3. Extraction Dimensions
35
+
36
+ Mine each dimension independently. For every finding, record: source file, timestamp, verbatim excerpt, and recommended action.
37
+
38
+ ### 3.1 Correction Patterns (Highest Priority)
39
+ **Signal**: User message that contradicts, overrides, or corrects a preceding assistant action.
40
+ **Detection heuristics**:
41
+ - User messages containing: "no", "wrong", "don't", "stop", "actually", "I said", "not like that", "fix this", "that's incorrect"
42
+ - User messages immediately following an assistant tool call that revert or undo it
43
+ - Explicit negative feedback: "this is bad", "terrible", "waste of tokens"
44
+
45
+ **Output**: New rule for CLAUDE.md, AGENTS.md, or specific skill frontmatter.
46
+
47
+ ### 3.2 Repeated Instructions
48
+ **Signal**: Same or semantically similar instruction given 3+ times across different sessions.
49
+ **Detection heuristics**:
50
+ - Fuzzy-match user prompts across sessions (normalize whitespace, lowercase)
51
+ - Cluster by semantic intent (e.g., "don't start dev server", "never run npm dev", "no dev servers")
52
+ - Count occurrences per cluster
53
+
54
+ **Output**: Promote to global default in CLAUDE.md or AGENTS.md if not already present. If already present but violated, flag as doctrine enforcement gap.
55
+
56
+ ### 3.3 Skill Trigger Failures
57
+ **Signal**: Task description matches a skill's trigger phrases but no `Skill` tool invocation appears in the session.
58
+ **Detection heuristics**:
59
+ - Parse assistant messages for `"type":"tool_use"` with `"name":"Skill"`
60
+ - Compare user task descriptions against known skill trigger phrases (from skill frontmatter `description` fields)
61
+ - Flag sessions where trigger matched but skill was never invoked
62
+
63
+ **Output**: Amend skill `description` to add missing trigger phrases, or create new skill if gap is systemic.
64
+
65
+ ### 3.4 Agent Selection Accuracy
66
+ **Signal**: Subagent spawned for task that didn't require specialization, or wrong agent type selected.
67
+ **Detection heuristics**:
68
+ - Count `Agent` tool invocations per session
69
+ - Correlate with session outcome (did subagent produce useful output vs. redundant work?)
70
+ - Flag sessions with 5+ subagents that could have been single-agent
71
+
72
+ **Output**: Tighten agent dispatch heuristics in orchestrator or agent descriptions.
73
+
74
+ ### 3.5 Doctrine Compliance
75
+ **Signal**: Session violates explicit AGENTS.md constraints.
76
+ **Key doctrines to check**:
77
+ - ZERO DEV-SERVER: search for `npm run dev`, `vite`, `next dev`, `uvicorn`, `flask run`, etc. in tool calls
78
+ - BLUF/STE: check assistant response structure (does it lead with verdict?)
79
+ - KARPATHY SIMPLICITY: flag sessions with >20 tool calls for single-file edits
80
+ - PROGRESSIVE DISCLOSURE: flag unnecessary subagent spawns
81
+
82
+ **Output**: Strengthen guardrails, add hooks, or document justified exceptions.
83
+
84
+ ### 3.6 Cross-Agent Consistency
85
+ **Signal**: Same task handled differently by Claude vs. Gemini, with divergent quality.
86
+ **Detection heuristics**:
87
+ - Match Gemini `workspace` to Claude project directory
88
+ - Compare prompt similarity across agents for same workspace/timeframe
89
+ - Note which agent produced fewer corrections or more complete output
90
+
91
+ **Output**: Codify winning pattern into shared skills or AGENTS.md.
92
+
93
+ ---
94
+
95
+ ## 4. Execution Protocol
96
+
97
+ 1. **Scope selection**: Ask user which projects/date ranges to mine, or default to all sessions in current project.
98
+ 2. **Stream processing**: Read JSONLs line-by-line. Never load entire file into context. Use `Get-Content -ReadCount 100` or equivalent streaming.
99
+ 3. **Extraction pass**: For each dimension, emit candidate findings with source references.
100
+ 4. **Deduplication**: Merge semantically identical findings. Keep highest-frequency version.
101
+ 5. **Validation**: Present top-N findings to user with excerpts. Do NOT auto-write memory files without confirmation.
102
+ 6. **Write confirmed findings**: Use memory file format (see §5). Update MEMORY.md index.
103
+
104
+ ---
105
+
106
+ ## 5. Output Format
107
+
108
+ Each confirmed finding becomes a memory file at `C:\Users\Bernardo\.claude\projects\<project>\memory\<slug>.md`:
109
+
110
+ ```markdown
111
+ ---
112
+ name: <kebab-case-slug>
113
+ description: <one-line summary for recall relevance>
114
+ metadata:
115
+ type: feedback | project
116
+ source_sessions: [<session-id-1>, <session-id-2>]
117
+ extracted_by: ruminate
118
+ extraction_date: YYYY-MM-DD
119
+ ---
120
+
121
+ <The extracted rule, preference, or lesson. Be concrete and actionable.>
122
+
123
+ **Why:** <What went wrong or what pattern emerged from sessions.>
124
+ **How to apply:** <Specific behavioral change for agents/skills.>
125
+ ```
126
+
127
+ Update `MEMORY.md` index with one line per new file:
128
+ ```
129
+ - [<slug>](<slug>.md) — <hook phrase>
130
+ ```
131
+
132
+ ---
133
+
134
+ ## 6. Guardrails
135
+
136
+ - **Never auto-modify skills or AGENTS.md**. Only propose amendments; user confirms.
137
+ - **Redact secrets**: Strip any API keys, tokens, or credentials found in transcripts before writing findings.
138
+ - **Respect scope**: If user says "podium-app only", do not mine heimdall-agent sessions.
139
+ - **Token hygiene**: Process in batches. Summarize intermediate results. Never dump raw JSONL into context.
140
+ - **Evidence over assertion**: Every finding must include verbatim transcript excerpt and source file path. No speculative patterns without grounding.
@@ -111,7 +111,8 @@ sequences — the single most expensive failure observed. Track progress in
111
111
  a ledger file, not only in todos.
112
112
 
113
113
  - Each plan owns a workspace: at skill start, run this skill's
114
- `bash scripts/sdd-workspace PLAN_FILE` — it prints the plan's git-ignored
114
+ `bash scripts/sdd-workspace PLAN_FILE` by its absolute path, from the
115
+ working tree you're executing in — it prints the plan's git-ignored
115
116
  directory (under `<repo-root>/.superpowers/sdd/`), home to
116
117
  every artifact for THIS plan: ledger, briefs, reports, review packages.
117
118
  Another plan's directory is never yours to read or write.
@@ -200,7 +201,8 @@ Record BASE (`git rev-parse HEAD`) before dispatching — the review package
200
201
  and fix-round diffs need it.
201
202
 
202
203
  - **Task brief:** before dispatching an implementer, run this skill's
203
- `bash scripts/task-brief PLAN_FILE N` — it extracts the task's full text to a
204
+ `bash scripts/task-brief PLAN_FILE N` by its absolute path, from the
205
+ working tree you're executing in — it extracts the task's full text to a
204
206
  uniquely named file and prints the path. Compose the dispatch so the
205
207
  brief stays the single source of
206
208
  requirements. Your dispatch should contain: (1) one line on where this
@@ -238,7 +240,7 @@ Template: [implementer-prompt.md](implementer-prompt.md)
238
240
 
239
241
  Implementer subagents report one of four statuses. Handle each appropriately:
240
242
 
241
- **DONE:** Generate the review package (`bash scripts/review-package PLAN_FILE BASE HEAD`, from this skill's directory — it prints the unique file path it wrote; BASE is the commit you recorded before dispatching the implementer — never `HEAD~1`, which silently drops all but the last commit of a multi-commit task), then dispatch the task reviewer with the printed path.
243
+ **DONE:** Generate the review package (`bash scripts/review-package PLAN_FILE BASE HEAD` by its absolute path, from the working tree you're executing in — it prints the unique file path it wrote; BASE is the commit you recorded before dispatching the implementer — never `HEAD~1`, which silently drops all but the last commit of a multi-commit task), then dispatch the task reviewer with the printed path.
242
244
 
243
245
  **Any other status** (DONE_WITH_CONCERNS, NEEDS_CONTEXT, BLOCKED): read
244
246
  [references/handling-reports.md](references/handling-reports.md) and follow
@@ -257,7 +259,8 @@ required. Implementer self-review never replaces the task review; both are
257
259
  needed.
258
260
 
259
261
  - Hand the reviewer its diff as a file: run this skill's
260
- `bash scripts/review-package PLAN_FILE BASE HEAD` and pass the reviewer the file path
262
+ `bash scripts/review-package PLAN_FILE BASE HEAD` by its absolute path, from
263
+ the working tree you're executing in, and pass the reviewer the file path
261
264
  it prints (or, without bash: `git log --oneline`, `git diff --stat`,
262
265
  and `git diff -U10` for the range, redirected to one uniquely named
263
266
  file). The output never enters your own context, and the reviewer sees