heimdall-agent 1.2.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 +99 -29
- package/README.pt-BR.md +100 -30
- package/agents/frontend-designer.md +6 -1
- package/agents/modernizer.md +4 -1
- package/agents/orchestrator.md +2 -1
- package/agents/reviewer.md +1 -1
- package/config/agents.json +166 -4
- 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 +911 -762
- package/docs/SKILLS.md +82 -21
- package/docs/designs/old/2026-11-16 upstream-skill-sync-and-provenance-links.md +60 -0
- package/doctrine/AGENTS.md +3 -3
- package/hooks/heimdall-hook.cjs +16 -1
- package/hooks/hooks.json +11 -0
- package/lib/model-context.cjs +50 -1
- package/lib/model-router.cjs +294 -0
- package/package.json +1 -1
- package/playbooks/05-canonical-plan-template.md +5 -12
- package/playbooks/06-model-registry-matrix.md +27 -19
- package/readme.html +1006 -0
- package/setup.mjs +317 -206
- package/skills/communication-doctrine/SKILL.md +2 -2
- package/skills/handoff/SKILL.md +13 -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/ruminate/SKILL.md +140 -0
- package/skills/taste-skill/SKILL.md +367 -534
- package/skills/upstream-skill-sync/SKILL.md +46 -0
- package/skills/writing-plans/SKILL.md +1 -1
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: communication-doctrine
|
|
3
3
|
description: >
|
|
4
|
-
|
|
5
|
-
|
|
4
|
+
Mandatory communication standard for ALL responses, status reports, code reviews, and implementation plans.
|
|
5
|
+
Use on every turn to enforce Bottom Line Up Front (BLUF) and ASD-STE100 Simplified Technical English (STE).
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
# Communication Doctrine: BLUF & Simplified Technical English (STE)
|
package/skills/handoff/SKILL.md
CHANGED
|
@@ -9,6 +9,19 @@ When ending a session, switching agent contexts, or spawning a fresh child agent
|
|
|
9
9
|
|
|
10
10
|
---
|
|
11
11
|
|
|
12
|
+
## 0. Auto-Trigger on Coherence Degradation (MANDATORY)
|
|
13
|
+
|
|
14
|
+
Invoke this skill **proactively** — without waiting for an explicit user request — when you detect any of the following signals in your own output:
|
|
15
|
+
- Contradictory statements within the same turn or across recent turns
|
|
16
|
+
- Lost task thread: unable to state the current objective without re-reading prior context
|
|
17
|
+
- Repeated self-corrections (3+ corrections to your own output in a single turn)
|
|
18
|
+
- Hallucinated state that contradicts prior tool results or file contents
|
|
19
|
+
- User has said "loop", "stuck", "drip", "hallucinating", or requested a fresh start
|
|
20
|
+
|
|
21
|
+
When auto-triggered, announce: "Detected coherence degradation. Invoking handoff protocol to preserve context." Then execute the full protocol below. Do NOT continue working after detecting these signals. Extracted from 187 sessions via `/ruminate`.
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
12
25
|
## 1. Zero-Duplication & Pointer-First Principle
|
|
13
26
|
|
|
14
27
|
Do **not** dump raw source code, large file bodies, verbose conversational histories, or full plan duplicates into the handoff artifact.
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: mcp-cleanup
|
|
3
|
+
description: Kill orphaned MCP server processes left behind by crashed or closed agent sessions. Use when node.exe/cmd.exe count is high, MCP servers are unresponsive, or after closing multiple IDE/CLI sessions.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# MCP Cleanup Skill (`mcp-cleanup`)
|
|
7
|
+
|
|
8
|
+
Use this skill when the user reports slow performance, high process counts, unresponsive MCP tools, or after closing multiple agent sessions without clean shutdown.
|
|
9
|
+
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
## When to Invoke
|
|
13
|
+
|
|
14
|
+
- User says `/mcp-cleanup`, "kill mcp orphans", "clean up mcp", "too many node processes"
|
|
15
|
+
- When MCP servers fail to connect and orphan processes are suspected
|
|
16
|
+
- As part of post-crash recovery
|
|
17
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
## Execution Steps
|
|
21
|
+
|
|
22
|
+
1. **Count current MCP-related processes** (diagnostic baseline):
|
|
23
|
+
- On Windows (PowerShell):
|
|
24
|
+
```powershell
|
|
25
|
+
Get-CimInstance Win32_Process -Filter "Name='node.exe' OR Name='cmd.exe'" |
|
|
26
|
+
Where-Object { $_.CommandLine -match 'context7-mcp|chrome-devtools-mcp|rea\.mjs|npx\.cmd|open-design' } |
|
|
27
|
+
Select-Object ProcessId, Name, @{N='CmdLine';E={$_.CommandLine.Substring(0, [Math]::Min(120, $_.CommandLine.Length))}} |
|
|
28
|
+
Format-Table -AutoSize
|
|
29
|
+
```
|
|
30
|
+
- On macOS/Linux:
|
|
31
|
+
```bash
|
|
32
|
+
ps aux | grep -E 'context7-mcp|chrome-devtools-mcp|rea\.mjs|npx' | grep -v grep
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
2. **Warn the user**: Tell them how many orphan processes were found and that killing them will break any active MCP connections. Ask for confirmation unless the user explicitly said "force" or "kill all".
|
|
36
|
+
|
|
37
|
+
3. **Kill orphaned processes**:
|
|
38
|
+
- On Windows (PowerShell):
|
|
39
|
+
```powershell
|
|
40
|
+
Get-CimInstance Win32_Process -Filter "Name='node.exe' OR Name='cmd.exe'" |
|
|
41
|
+
Where-Object { $_.CommandLine -match 'context7-mcp|chrome-devtools-mcp|rea\.mjs|npx\.cmd' } |
|
|
42
|
+
ForEach-Object { Stop-Process -Id $_.ProcessId -Force -ErrorAction SilentlyContinue }
|
|
43
|
+
```
|
|
44
|
+
- On macOS/Linux:
|
|
45
|
+
```bash
|
|
46
|
+
pkill -f 'context7-mcp|chrome-devtools-mcp|rea\.mjs|npx.*mcp'
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
4. **Verify cleanup**: Re-run the diagnostic count from step 1 and report how many processes remain.
|
|
50
|
+
|
|
51
|
+
5. **Recommend prevention**: Remind the user about `/mcp-sync` to ensure configs use direct `node.exe` calls instead of `npx`, which prevents future orphan multiplication.
|
|
52
|
+
|
|
53
|
+
---
|
|
54
|
+
|
|
55
|
+
## Guardrails
|
|
56
|
+
|
|
57
|
+
- NEVER kill node.exe/cmd.exe processes that do NOT match the MCP command-line patterns above.
|
|
58
|
+
- NEVER run cleanup while the user has active agent sessions unless they explicitly confirm.
|
|
59
|
+
- NEVER use `taskkill /F /IM node.exe` — this kills ALL node processes including unrelated apps.
|
|
60
|
+
- Always filter by CommandLine content, not just process name.
|
|
61
|
+
- Report exact counts before and after — never claim cleanup succeeded without verification.
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: mcp-sync
|
|
3
|
+
description: Resolve Heimdall MCP template to local paths and sync to agent harness configs. Use when toggling MCP servers, setting up a new machine, or after installing/updating global npm MCP packages.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# MCP Sync Skill (`mcp-sync`)
|
|
7
|
+
|
|
8
|
+
Use this skill when the user wants to update MCP server configurations, toggle servers on/off, set up MCP on a new machine, or after running `npm install -g` / `npm update -g` for MCP packages.
|
|
9
|
+
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
## When to Invoke
|
|
13
|
+
|
|
14
|
+
- User says `/mcp-sync`, "sync mcp", "update mcp config", "enable/disable <server>"
|
|
15
|
+
- After installing or updating global MCP npm packages
|
|
16
|
+
- When setting up Heimdall on a new workstation
|
|
17
|
+
- When an MCP server fails to connect due to path issues
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
## Execution Steps
|
|
22
|
+
|
|
23
|
+
1. **Check prerequisites**: Verify `config/mcp.template.json` exists. If missing, report error and stop.
|
|
24
|
+
|
|
25
|
+
2. **Toggle servers if requested**: If the user asked to enable or disable a specific server, edit `config/mcp.template.json` and set `"disabled": true/false` on that server entry before resolving.
|
|
26
|
+
|
|
27
|
+
3. **Run the resolver**:
|
|
28
|
+
```bash
|
|
29
|
+
node scripts/resolve-mcp.mjs --sync
|
|
30
|
+
```
|
|
31
|
+
This generates `config/mcp.resolved.json` and writes to `~/.gemini/config/mcp_config.json` and `~/.claude/settings.json`.
|
|
32
|
+
|
|
33
|
+
4. **Report results**: Show which servers are enabled/disabled, any unresolved placeholders, and remind the user to restart agent sessions.
|
|
34
|
+
|
|
35
|
+
5. **If unresolved placeholders exist**: Tell the user which packages to install globally:
|
|
36
|
+
```bash
|
|
37
|
+
npm install -g @upstash/context7-mcp chrome-devtools-mcp rea-agents
|
|
38
|
+
```
|
|
39
|
+
Then re-run the resolver.
|
|
40
|
+
|
|
41
|
+
---
|
|
42
|
+
|
|
43
|
+
## Architecture Notes
|
|
44
|
+
|
|
45
|
+
- `config/mcp.template.json` is the portable source of truth (committed to git).
|
|
46
|
+
- `config/mcp.resolved.json` is machine-specific (gitignored).
|
|
47
|
+
- The resolver replaces `{{PLACEHOLDER}}` tokens with local paths detected at runtime.
|
|
48
|
+
- Disabled servers are excluded from harness configs but preserved in the template.
|
|
49
|
+
- Never use `npx` in resolved configs — always direct `node.exe` calls to avoid Windows process multiplication.
|
|
50
|
+
|
|
51
|
+
---
|
|
52
|
+
|
|
53
|
+
## Guardrails
|
|
54
|
+
|
|
55
|
+
- NEVER edit `config/mcp.resolved.json` directly — it is generated.
|
|
56
|
+
- NEVER add `npx` commands to any MCP config.
|
|
57
|
+
- NEVER start dev servers to test MCP connectivity.
|
|
58
|
+
- Always run `--sync` to propagate changes to harness configs; generating `mcp.resolved.json` alone does not update running agents.
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: modern-web-guidance
|
|
3
|
+
description: |
|
|
4
|
+
Search tool for modern web development best practices. MANDATORY: Execute FIRST for all HTML/CSS and clientside JS tasks. Do NOT skip — web APIs evolve rapidly and training weights contain obsolete patterns.
|
|
5
|
+
Trigger immediately for: modals/dialogs/popovers, tables, dark mode, anchor positioning, container queries, view transitions, scroll-driven animations, parallax/reveals, forms, validation, autofill, accessibility, custom selects, scrollbars, CWV (LCP, INP, CLS), content-visibility, fetch priority, image optimization, security, passkeys, HTML sanitization, web components, dates/timezones, built-in AI, WebAssembly, standard HTML/CSS/DOM in frameworks, etc.
|
|
6
|
+
DO NOT trigger for: backend (SQL, ORMs, API routes), infra/scripts (CI/CD, Docker, Actions, Python/Go, Git), or tooling/trivial (Vite, tsconfig, ESLint, tests, copy/renames, 3P docs), etc.
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# Modern Web Guidance
|
|
10
|
+
|
|
11
|
+
Search and retrieve standardized modern web best practices at the **start** of implementing or updating any web UI, CSS layout/animation, or client-side JS logic (dates/timezones, sanitization, performance, accessibility, UX fixes) before writing ad-hoc solutions or adding dependencies.
|
|
12
|
+
|
|
13
|
+
## Primary Workflow
|
|
14
|
+
|
|
15
|
+
### Step 1. Search Use Cases
|
|
16
|
+
|
|
17
|
+
Run `modern-web-guidance` directly with `npx` using a **2–5 word action-oriented English query** for a **single web platform capability or UI pattern**:
|
|
18
|
+
- **Keep queries focused and generic**: Describe the user-visible capability (`<verb> + <UI/platform object>`, optionally paired with the target HTML/CSS/JS feature name if known). Omit framework/library names (`React`, `Vue`, `Tailwind`, etc.) and app/domain nouns (product, route, or component/file names). Split multi-feature tasks into separate `search` calls.
|
|
19
|
+
- **Name implied UI primitives**: When the user's prompt expresses intent without naming the UI primitive (e.g. "confirm first", "delete with confirmation", "pick a date"), translate the domain intent into the implied UI component or platform mechanism (e.g. search `"confirmation modal dialog"` or `"confirm dialog"` rather than `"confirm destructive action"`, or `"date picker input"` rather than `"pick a date"`).
|
|
20
|
+
- **Example**: Search `"light dismiss dialog"` or `"responsive data table"`, **not** `"dialog"` (too terse), `"responsive table dark mode"` (compound — split into two searches), or `"close React settings modal on outside click"` (framework/app noise).
|
|
21
|
+
|
|
22
|
+
```sh
|
|
23
|
+
npx -y modern-web-guidance@latest search "<query>" --skill-version 2026_11_10-47b4c80e
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
> **Note**: Returns `[{ "id", "description" }, ...]`. Judge results by their `description` fields:
|
|
27
|
+
> - **Match found**: Call `retrieve` directly—do not also run `list`.
|
|
28
|
+
> - **Weak or empty results**: If `search` returns `[]` or unrelated descriptions, **rephrase `search` once** using the concrete HTML/CSS/UI component noun or synonym (e.g., `dialog`, `modal`, `popover`, `table`, `form`) before falling back to `list` (or use `list` once for broad UI audits).
|
|
29
|
+
> - **Topic not covered**: If no `description` matches after rephrasing, proceed without retrieving unrelated guides.
|
|
30
|
+
|
|
31
|
+
### Step 2. Retrieve Best Practices
|
|
32
|
+
|
|
33
|
+
Once you have relevant `id`(s) from the search results, call `retrieve` to get the full guide(s)—including both specific use-case guides that match your task and any broader discipline guide (e.g., `html`, `css`, `forms`, `accessibility`, `color`, `performance`, `security`) that applies. You can pass multiple IDs separated by commas.
|
|
34
|
+
|
|
35
|
+
```sh
|
|
36
|
+
npx -y modern-web-guidance@latest retrieve "<id>"
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
If `retrieve` saves large output (> 9.5 KB) to a temporary file to prevent truncation, read that file path in full using your file-reading tool (reading remaining line ranges if needed)—do not use `cat` or `head`.
|
|
40
|
+
|
|
41
|
+
### Step 3. Verify Guidance Compliance
|
|
42
|
+
|
|
43
|
+
When generating or modifying code, cross-check the implementation against the retrieved guide before concluding:
|
|
44
|
+
- **Applicable Guidance & Fallbacks**: Ensure the relevant modern patterns and necessary fallback strategies from the guide are correctly applied, without forcing unrequested features.
|
|
45
|
+
- **Task Fulfillment**: Confirm that the implementation fully satisfies the user's request.
|
|
46
|
+
- Do not run `legacy-scan`; it's for detecting legacy patterns to modernize, not this.
|
|
47
|
+
|
|
48
|
+
### Step 4. Disclose Skill Usage
|
|
49
|
+
|
|
50
|
+
When you consult `modern-web-guidance` for a task, end the response where you deliver those changes with a `### Modern Web Guidance` section:
|
|
51
|
+
- **When retrieved guides shaped your code**: Write **one** bullet (1–2 sentences, ≤75 words) per newly applied `<id>` in first-person voice explaining the non-obvious implementation choices, CSS/API overrides, or fallbacks `<id>` required and the pitfall it prevented, anchored by a short verbatim quote of that specific rule or gotcha (never the guide's intro overview):
|
|
52
|
+
`- **\`<id>\`**: <Non-obvious APIs, overrides, or fallbacks applied and the pitfall prevented> ("<short verbatim quote of the specific rule or gotcha>").`
|
|
53
|
+
- **Never** guess `<id>`s or quotes from memory after context compaction (re-run `search`/`retrieve` if needed), and credit **only** guide-backed changes from the current turn.
|
|
54
|
+
- **When searched/listed in this turn but zero guides applied**: Write one first-person sentence naming which topics or guides you checked in `modern-web-guidance` and why none applied (omit if any guide applied).
|
|
55
|
+
|
|
56
|
+
## Alternative flow: Modernize an existing codebase
|
|
57
|
+
|
|
58
|
+
**Only** when asked for a broad, open-ended codebase modernization or legacy-pattern scan where no specific target feature or component is named (do **not** run `legacy-scan` when asked to add, update, fix, or audit a specific feature or component), run the 4-step modernization flow:
|
|
59
|
+
|
|
60
|
+
> **Note**: `legacy-scan` scans for a curated subset (~20% of the guidance corpus).
|
|
61
|
+
|
|
62
|
+
```sh
|
|
63
|
+
npx -y modern-web-guidance@latest legacy-scan <path> --json
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
1. Scan: Run `legacy-scan <path> --json` to detect legacy web platform patterns across the project or directory.
|
|
67
|
+
2. Verify: Check each finding against its `keepWhen` / `dropWhen` rubric; drop false positives (fallbacks, cross-file helpers, vendor code, lookalikes).
|
|
68
|
+
3. Report: Summarize verified findings (and the modernization plan, if editing) for the user, noting that `legacy-scan` only checks the subset of guides (~20% of the catalog) that have deterministic legacy rules.
|
|
69
|
+
4. Modernize (when the user asked to modernize rather than only audit/report): Retrieve each finding's guide (`retrieve "<guide-id>"` via Step 2), apply the replacement (keeping existing libraries as fallbacks where the guide requires one), and re-run `legacy-scan <path>` on the modified files to confirm resolution.
|
|
70
|
+
- Dropped findings and kept fallbacks still match static scans; do not edit safe code or inspect `legacy-scan.mjs` to force 0 findings.
|
|
71
|
+
|
|
72
|
+
## Using npx / pnpx
|
|
73
|
+
|
|
74
|
+
- **Runner & Permissions**: Prefer `pnpx` over `npx` if `pnpm` is available (`pnpx` does not use `-y`); on Windows, use `npx.cmd`. When requesting tool permissions, allowlist `npx -y modern-web-guidance@latest *` (or `pnpx modern-web-guidance@latest *`) specifically, never bare `npx *` or `pnpx *`.
|
|
75
|
+
- **Sandboxes & Network**: Fetching `modern-web-guidance` requires outbound network access. In sandboxed or approval-gated environments (e.g., Codex, Claude Code), **proactively request approval/allowlisting with network access BEFORE the first execution** to avoid timeouts, and set `NPM_CONFIG_CACHE=/tmp/npm-cache` if `~/.npm` is read-only.
|
|
76
|
+
- **Offline**: If the command hangs due to being offline, retry with `npx --offline …`.
|
|
77
|
+
|
|
78
|
+
## Guidelines
|
|
79
|
+
|
|
80
|
+
- Always search **first** to find the most relevant guides. Do not hallucinate guides or ignore them; they represent the preferred local standard for the user's project.
|
|
81
|
+
- These guides use vanilla HTML/CSS/JS; adapt them to your framework without dropping the modern feature:
|
|
82
|
+
- **Types**: Spread/cast newly shipped HTML attributes (`{...({ popover: 'hint', interestfor: id, commandfor: id, switch: '' } as any)}`, `[attr.*]`) rather than removing them or merging `@types/react`.
|
|
83
|
+
- **SSR & Bundlers**: Guard `window`/`HTMLElement` in SSR and load polyfills via bare `import('<pkg>')` in client effects (or set Vite `build.target: 'esnext'` for top-level `await`)—never copy files from `node_modules`.
|
|
84
|
+
- **DOM, IDs & CSS**: Call `showModal()`/`moveBefore()` via refs on non-VDOM-managed nodes, generate per-instance IDs/`anchor-name`s (`useId()`), and keep `:root` and `@starting-style` top-level/unscoped.
|
|
85
|
+
|
|
86
|
+
## Interpreting Browser Support & Fallbacks
|
|
87
|
+
|
|
88
|
+
* **Default Behavior**: All guides assume **Baseline Widely available** features are safe to use without fallbacks. For features that are not Baseline widely available, you **MUST** follow the fallback recommendations in the guide, unless the user has specified a custom browser support policy.
|
|
89
|
+
* **Custom Policies**: If the user defines explicit browser support requirements, use the guide's compatibility data to determine if a fallback can be ignored (for `Baseline YYYY` targets, a feature satisfies the target if its "Baseline since" date is `<= YYYY`). Examples: _"Do not implement feature fallbacks"_, _"Safari 17.4+"_, _"Never implement polyfills; use a lightweight custom fallback or redesign"_, or _"Allow Newly Available features if feature-detected with graceful degradation"_.
|
|
90
|
+
* **Reactive Policy Discovery**: Suggest documenting a policy in `AGENTS.md` or `CLAUDE.md` (e.g., `**Browser Support:** Allow Newly Available features, but only adopt custom fallback code that adds <= 20 lines and no external dependencies`) if the developer targets a restricted runtime (Electron/Tauri), excludes specific browsers, hesitates over polyfill size/complexity, or asks if a feature is safe without fallbacks.
|
|
@@ -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.
|