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.
- package/README.md +101 -31
- package/README.pt-BR.md +124 -40
- package/agents/code-sentinel.md +7 -1
- package/agents/frontend-designer.md +6 -1
- package/agents/modernizer.md +8 -3
- package/agents/orchestrator.md +22 -8
- package/agents/reviewer.md +3 -1
- package/config/agents.json +177 -5
- package/config/mcp.json +1 -1
- package/config/mcp.resolved.json +74 -0
- package/config/mcp.template.json +85 -0
- package/config/models.json +70 -0
- package/config/profiles.json +4 -3
- package/config/skills.json +321 -93
- package/docs/SKILLS.md +158 -75
- package/docs/designs/old/2026-11-16 upstream-skill-sync-and-provenance-links.md +60 -0
- package/docs/runs/skill-audit/2026-11-12-compare-report.json +1028 -0
- package/docs/runs/skill-audit/2026-11-12-upstream-audit.json +275 -0
- package/doctrine/AGENTS.md +7 -4
- package/hooks/heimdall-hook.cjs +16 -1
- package/hooks/hooks.json +11 -0
- package/lib/catalog-sync.cjs +8 -3
- package/lib/model-context.cjs +50 -1
- package/lib/model-router.cjs +294 -0
- package/package.json +1 -1
- package/playbooks/01-interactive-grilling-gate.md +14 -10
- package/playbooks/03-adversarial-code-review.md +12 -4
- package/playbooks/05-canonical-plan-template.md +8 -13
- package/playbooks/06-model-registry-matrix.md +27 -19
- package/readme.html +1006 -0
- package/setup.mjs +317 -206
- package/skills/antislop-copywriting/SKILL.md +36 -1
- package/skills/brainstorming/SKILL.md +60 -38
- package/skills/codebase-design/DEEPENING.md +37 -0
- package/skills/codebase-design/DESIGN-IT-TWICE.md +44 -0
- package/skills/codebase-design/SKILL.md +114 -0
- package/skills/communication-doctrine/SKILL.md +2 -2
- package/skills/domain-modeling/ADR-FORMAT.md +47 -0
- package/skills/domain-modeling/GLOSSARY-FORMAT.md +60 -0
- package/skills/domain-modeling/SKILL.md +74 -0
- package/skills/executing-plans/SKILL.md +6 -4
- package/skills/grill-me/SKILL.md +65 -0
- package/skills/handoff/SKILL.md +77 -0
- package/skills/improve-codebase-architecture/HTML-REPORT.md +123 -0
- package/skills/improve-codebase-architecture/SKILL.md +71 -0
- package/skills/mcp-cleanup/SKILL.md +61 -0
- package/skills/mcp-sync/SKILL.md +58 -0
- package/skills/modern-web-guidance/SKILL.md +90 -0
- package/skills/owasp-security/reference/config-and-supply-chain.md +346 -344
- package/skills/owasp-security/reference/languages.md +378 -372
- package/skills/owasp-security/reference/owasp-report.md +1144 -1140
- package/skills/owasp-security/reference/review-checklist.md +134 -132
- package/skills/ruminate/SKILL.md +140 -0
- package/skills/subagent-driven-development/SKILL.md +7 -4
- package/skills/taste-skill/SKILL.md +367 -534
- package/skills/to-spec/SKILL.md +75 -0
- package/skills/to-tickets/SKILL.md +105 -0
- package/skills/upstream-skill-sync/SKILL.md +46 -0
- package/skills/wayfinder/SKILL.md +128 -0
- 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
|
-
- [ ]
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
- [ ]
|
|
62
|
-
- [ ]
|
|
63
|
-
- [ ]
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
- [ ]
|
|
69
|
-
- [ ]
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
- [ ]
|
|
75
|
-
- [ ]
|
|
76
|
-
|
|
77
|
-
- [ ]
|
|
78
|
-
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
- [ ]
|
|
84
|
-
- [ ]
|
|
85
|
-
- [ ]
|
|
86
|
-
- [ ]
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
- [ ]
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
- [ ]
|
|
98
|
-
- [ ]
|
|
99
|
-
- [ ]
|
|
100
|
-
- [ ]
|
|
101
|
-
- [ ]
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
- [ ]
|
|
107
|
-
- [ ]
|
|
108
|
-
- [ ]
|
|
109
|
-
- [ ]
|
|
110
|
-
- [ ]
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
- [ ]
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
- [ ]
|
|
119
|
-
|
|
120
|
-
- [ ]
|
|
121
|
-
- [ ]
|
|
122
|
-
- [ ]
|
|
123
|
-
- [ ]
|
|
124
|
-
|
|
125
|
-
- [ ]
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
- [ ]
|
|
129
|
-
|
|
130
|
-
- [ ]
|
|
131
|
-
|
|
132
|
-
- [ ]
|
|
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`
|
|
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`
|
|
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
|
|
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`
|
|
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
|