heimdall-agent 1.2.0 → 1.5.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 CHANGED
@@ -4,13 +4,13 @@
4
4
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" alt="License: MIT" /></a>
5
5
  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D18.0.0-339933.svg?style=flat-square&logo=node.js&logoColor=white" alt="Node >= 18" /></a>
6
6
  <a href="#10-predefined-agent-personas"><img src="https://img.shields.io/badge/agents-10%20predefined-orange.svg?style=flat-square" alt="Agents: 10 Predefined" /></a>
7
- <a href="#skill-inventory-64-modules-across-25-toolkits"><img src="https://img.shields.io/badge/skills-25%20toolkits%20%2864%20modules%29-blueviolet.svg?style=flat-square" alt="Skills: 25 Toolkits (64 Modules)" /></a>
7
+ <a href="#skill-inventory-69-modules-across-30-toolkits"><img src="https://img.shields.io/badge/skills-30%20toolkits%20%2869%20modules%29-blueviolet.svg?style=flat-square" alt="Skills: 30 Toolkits (69 Modules)" /></a>
8
8
  <a href="#supported-tools--runtimes"><img src="https://img.shields.io/badge/runtimes-Antigravity%20%7C%20Claude%20%7C%20Codex%20%7C%20Hermes%20%7C%20OpenClaw-black.svg?style=flat-square" alt="Runtimes" /></a>
9
9
  </p>
10
10
 
11
11
  🌐 **Language / Idioma:** **English** | [Português (Brasil)](README.pt-BR.md)
12
12
 
13
- Heimdall is a portable bootstrap toolkit and quality sentinel for multi-agent software engineering. It enforces planning gates before code generation, prevents AI slop, isolates module boundaries, and synchronizes **10 specialized agent personas** and **64 modular skills** across **Google Antigravity**, **Claude Code**, **OpenAI Codex CLI**, **Hermes Agent**, **OpenClaw**, **OpenDesign**, and **Claude Desktop**.
13
+ Heimdall is a portable bootstrap toolkit and quality sentinel for multi-agent software engineering. It enforces planning gates before code generation, prevents AI slop, isolates module boundaries, and synchronizes **10 specialized agent personas** and **69 modular skills** across **Google Antigravity**, **Claude Code**, **OpenAI Codex CLI**, **Hermes Agent**, **OpenClaw**, **OpenDesign**, and **Claude Desktop**.
14
14
 
15
15
  ---
16
16
 
@@ -31,10 +31,10 @@ Heimdall is a portable bootstrap toolkit and quality sentinel for multi-agent so
31
31
  <a id="1-what-is-heimdall"></a>
32
32
  ## 1. What is Heimdall?
33
33
 
34
- **Heimdall** is an environment bootstrapper and multi-agent coordination layer for AI coding tools.
34
+ **Heimdall** is an environment bootstrapper and multi-agent coordination layer for AI coding tools. More than a skill aggregator, it installs a complete, opinionated **way of working and coding**—combining structured communication, empirical verification, surgical code restraint, and runtime safety hooks into a deterministic, verified engineering environment.
35
35
 
36
36
  Instead of manually maintaining scattered custom instructions, system prompts, and configuration files across different AI clients, Heimdall provides a single source of truth:
37
- * **Modular Skills**: 64 task-activated capabilities (such as database design, security audits, design token enforcement, progressive disclosure, and debugging) that load on demand instead of wasting prompt tokens.
37
+ * **Modular Skills**: 69 task-activated capabilities (such as database design, security audits, design token enforcement, progressive disclosure, and debugging) that load on demand instead of wasting prompt tokens.
38
38
  * **Specialized Agent Personas**: 10 predefined roles with isolated context windows (`orchestrator`, `tester`, `frontend-designer`, `mobile-designer`, `reviewer`, `security-auditor`, `database-architect`, `code-sentinel`, `modernizer`, `cloud-engineer`).
39
39
  * **Universal Doctrine**: Central rules (`AGENTS.md`) synchronized across all harnesses, enforcing planning gates, test-driven development (TDD), and minimal surgical code edits.
40
40
 
@@ -56,16 +56,44 @@ Heimdall transforms unconstrained AI coding assistants into disciplined, multi-a
56
56
  5. **Adversarial Peer Review**: Dispatches context-blinded reviewers to inspect git diffs for edge cases, silent regressions, and unhandled failure branches.
57
57
  6. **Intercepts Dangerous Operations**: Evaluates shell commands and file mutations via lifecycle hooks to block destructive root wiping and force-pushes to protected branches.
58
58
 
59
+ ### The Heimdall Way of Working (Beyond a Skill Aggregator)
60
+
61
+ Skills alone do not build reliable software—**engineering discipline does**. Heimdall bakes an end-to-end operating methodology directly into every session:
62
+
63
+ 1. **BLUF Communication Architecture (Bottom Line Up Front)** (`communication-doctrine`):
64
+ - Eliminates AI throat-clearing and buried conclusions. Every status report, implementation plan, code review verdict, and subagent handoff opens with the decision, verdict, and blast radius in the **first 1–2 sentences**.
65
+ - Standardized BLUF headers (`Subagent BLUF`, `Review Verdict`, `Plan BLUF`) let coordinators and human engineers parse outcomes in seconds.
66
+ 2. **ASD-STE100 Simplified Technical English**:
67
+ - Procedural steps use **active imperative verbs first** (`Create`, `Modify`, `Assert`, `Verify`, `Run`), strict sentence limits (**≤ 20 words per step**), and explicit object naming (no ambiguous pronouns like *"it"* or *"this"*).
68
+ - Enforces a **Zero-Vagueness Lexicon** that bans subjective qualifiers (*"ensure"*, *"properly"*, *"appropriately"*, *"gracefully"*, *"as needed"*, *"robustly"*, *"etc."*)—replacing them with exact, testable conditions.
69
+ 3. **Poteto (`pstack` / `brainmaxxing`) & High-Rigor Craftsmanship**:
70
+ - **`pstack-discipline`** (from Lauren Tan / `@poteto`): Enforces *"Prove It Works"* (empirical proof before claiming done), *"Fix Root Causes"* (no symptom-masking guards), *"Test Behavior, Not Implementation"*, *"Subtract Before You Add"*, and *"Sequence Work into Verifiable Units"*.
71
+ - **`ruminate`** (inspired by `poteto/brainmaxxing`): Mines historical Claude and Gemini session transcripts for user corrections, repeated instructions, skill trigger failures, and doctrine drift—turning past friction into permanent memory files and skill amendments.
72
+ - Paired with **`thermo`** ("Code Judo" maintainability audits), **`karpathy-guidelines`** (minimal surgical edits), **`clean-code`** (`ub-mode`), **`ponytail`** (Dietrich Gebert's Decision Ladder), and **`modern-web-guidance`** (`GoogleChrome/modern-web-guidance`).
73
+ 4. **Self-Healing Sessions & Context Continuity (`ruminate` + `handoff` + Context Sentinel)**:
74
+ - Heimdall learns from its own history: rules in `handoff` (auto-handoff on coherence degradation) and `writing-plans` (spec-coverage completeness gate) were extracted directly from **187 historical sessions via `/ruminate`**.
75
+ - During active sessions, the **Context Sentinel** ([`hooks/heimdall-hook.cjs`](hooks/heimdall-hook.cjs)) tracks turns and estimated token usage against the active model's window (warning at 75% or 40 turns) so `handoff` can persist clean state before context rot sets in.
76
+ 5. **Dynamic Cross-Family Model Routing (`lib/model-router.cjs` + `heimdall sync-models`)**:
77
+ - Personas use `model: inherit` with zero vendor lock-in. `heimdall sync-models` and [`lib/model-router.cjs`](lib/model-router.cjs) dynamically classify model capabilities, map personas to capability tiers (`deep_reasoning`, `surgical_restraint`, `adversarial_diff_eval`), and select **cross-family reviewers** (e.g., Gemini audited by Claude, Codex, GLM, Hunyuan, or MiMo).
78
+ 6. **Token, Ceremony & Diff Restraint (`progressive-disclosure` + `caveman` + `ponytail`)**:
79
+ - `progressive-disclosure` loads skills on demand to cut prompt overhead, `caveman` strips conversational ceremony, and `ponytail` (*Lazy Senior Dev Mode*, `lite` / `full` / `ultra`) enforces the smallest complete diff and a concise reply a busy engineer understands in one read.
80
+ 7. **Matt Pocock Real Engineering Pipeline ([`mattpocock/skills`](https://github.com/mattpocock/skills)) & Karpathy 4 Pillars (`karpathy-guidelines`)**:
81
+ - **Pre-code → Architecture → Tickets**: `grill-me` (Design Tree Frontier) → `wayfinder` (settled vs. frontier vs. fog) → `domain-modeling` (`GLOSSARY.md` & ADRs) → `to-spec` (invariants) → `to-tickets` (tracer-bullet tickets) → `codebase-design` / `improve-codebase-architecture` (deep modules) → `handoff`.
82
+ - **Karpathy 4 Pillars**: *Think Before Coding* (surface assumptions), *Simplicity First* (no speculative helpers), *Surgical Changes* (touch only task lines), and *Goal-Driven Execution* (verifiable pass criteria first), backed by the 800-line `PreToolUse (Write)` hook.
83
+ 8. **Controlled Upstream Skill Sync (`upstream-skill-sync`)**:
84
+ - Classifies every skill in `config/skills.json` as `mirror`, `adapted`, or `native` and triages upstream changes into **Tier 1 (Safe 1:1)**, **Tier 2 (Selective Merge)**, or **Tier 3 (Reject)** after `snyk-agent-scan` security checks.
85
+
59
86
  ### Comparison: Vanilla AI Coding vs. Heimdall
60
87
 
61
88
  | Area | Vanilla AI Coding | With Heimdall |
62
89
  | :--- | :--- | :--- |
63
90
  | **Initial Prompt** | AI immediately generates 300 lines of unverified code. | **Interactive Gate**: AI pauses, interrogates edge cases, and presents 2 architectural options. |
64
- | **Code Review** | AI rubber-stamps its own code with conversational praise. | **Context-Blinded Review**: Stateless reviewer inspects diffs without conversational bias. |
65
- | **Code Restraint** | Bloated wrappers, defensive boilerplate, speculative options. | **Karpathy Simplicity**: Minimum code, surgical edits, zero unprompted refactoring. |
66
- | **Verification** | AI claims "done!" without testing or relies on shallow checks. | **TDD & Playwright**: Failing test first; active browser DOM assertions for UI. |
67
- | **Safety** | AI can execute destructive commands or force push to main. | **Lifecycle Hooks**: Blocks `rm -rf /` and force pushes to `main`/`master` at runtime and Git level. |
68
- | **Configuration** | Scattered, drifting prompt files across multiple tools. | **Single Source of Truth**: Linked via native junctions/symlinks in 1 second. |
91
+ | **Communication** | Verbose prose, buried verdicts, and vague *"ensure it works properly"* steps. | **BLUF + ASD-STE100**: Verdict in lines 1–2; imperative, ≤20-word testable steps. |
92
+ | **Code Review** | AI rubber-stamps its own code with conversational praise. | **Context-Blinded Review**: Stateless Goldfish reviewer inspects diffs without conversational bias. |
93
+ | **Code Restraint** | Bloated wrappers, defensive boilerplate, speculative options. | **Karpathy & `pstack` Discipline**: Subtract before adding, fix root causes, surgical edits only. |
94
+ | **Verification** | AI claims "done!" without testing or relies on shallow checks. | **TDD & Playwright**: Failing test first; empirical proof via tests and browser DOM assertions. |
95
+ | **Safety** | AI can launch hanging dev servers, run `rm -rf`, or force push `main`. | **Lifecycle Hooks**: Blocks dev servers, destructive commands, secrets, and force pushes at runtime and Git level. |
96
+ | **Configuration** | Scattered, drifting prompt files across multiple tools. | **Single Source of Truth**: Linked via native junctions/symlinks in 1 second; self-audited via `ruminate`. |
69
97
 
70
98
  [↑ Back to top](#table-of-contents)
71
99
 
@@ -82,7 +110,7 @@ When Heimdall bootstraps, it establishes live junctions (Windows) or symlinks (P
82
110
 
83
111
  | Source in Heimdall | Deployed Location | Purpose |
84
112
  | :--- | :--- | :--- |
85
- | `skills/` | `~/.<tool>/skills/` | 64 domain toolkits loaded progressively on demand. |
113
+ | `skills/` | `~/.<tool>/skills/` | 69 domain toolkits loaded progressively on demand. |
86
114
  | `agents/` | `~/.<tool>/agents/` | 10 specialized agent persona definitions. |
87
115
  | `hooks/` | `~/.claude/hooks/` | Event-driven lifecycle hooks for Claude Code CLI. |
88
116
  | `hooks/git/` | `.git/hooks/` (optional) | Universal native Git pre-push hook for all tools. |
@@ -107,18 +135,20 @@ Heimdall adopts the core division of labor from [`google/elephant-goldfish-model
107
135
 
108
136
  ### 3. Event-Driven Lifecycle Hooks
109
137
 
110
- Heimdall includes zero-dependency runtime hooks ([`hooks/heimdall-hook.cjs`](hooks/heimdall-hook.cjs)) registered in `~/.claude/settings.json`:
138
+ Heimdall includes zero-dependency runtime hooks ([`hooks/heimdall-hook.cjs`](hooks/heimdall-hook.cjs)) declared in [`hooks/hooks.json`](hooks/hooks.json) and registered in `~/.claude/settings.json`:
111
139
 
140
+ * **`UserPromptSubmit`**:
141
+ - **Communication Doctrine Injection**: Reinforces BLUF (conclusion in first 1–2 sentences) and ASD-STE100 rules (imperative verb first, ≤20 words/step, zero banned qualifiers) on every prompt.
112
142
  * **`PreToolUse` (Bash/PowerShell)**:
113
143
  - **Blocks Destructive Commands**: Halts operations like `rm -rf /` or `rmdir /s /q C:\` (exit code 2).
144
+ - **Strict Zero Dev-Server Policy**: Blocks hanging dev server commands (`npm run dev`, `vite`, `next dev`, `uvicorn`, `python manage.py runserver`) and enforces non-interactive terminating checks.
114
145
  - **Branch-Aware Force Push Protection**: Blocks `git push --force` targeting `main`, `master`, `release`, or `production` (explicitly or while checked out on those branches). Force pushes to feature branches (`feature/*`, `bugfix/*`) are permitted with an advisory.
115
146
  - **Blocks Secret Commits**: Halts staging unencrypted `.env`, `id_rsa`, or `*.pem` files.
147
+ - **Context Sentinel**: Tracks session turns and estimated token usage against the active model's context limit, warning at 75% capacity or 40 turns.
116
148
  * **`PreToolUse` (Write)**:
117
- - **Karpathy Restraint Warning**: Emits an advisory if an AI attempts to generate a single file exceeding 800 lines.
118
- * **`PostToolUse` (Edit/Write)**:
119
- - **Verification Reminder**: Emits a reminder to run automated tests or browser verification before concluding.
149
+ - **Karpathy Restraint Warning**: Emits an advisory if an AI attempts to generate a single file exceeding 800 lines (exempting HTML/SVG/OpenDesign canvas artifacts) and updates Context Sentinel tracking.
120
150
  * **`PreCompact`**:
121
- - **Compaction State Reminder**: Reminds the agent to persist unresolved decisions and active task ledgers to disk before context compression.
151
+ - **Compaction State Reset & Reminder**: Clears temporary session tracking state and reminds the agent to persist active tasks, rulings, and pending ledger items to disk before context compression.
122
152
  * **Universal Native Git Pre-Push Hook** ([`hooks/git/pre-push`](hooks/git/pre-push)):
123
153
  - Shell hook installable into any repository (`.git/hooks/pre-push`) that blocks non-fast-forward pushes to `main`/`master` universally across all AI harnesses and terminal users.
124
154
 
@@ -152,10 +182,10 @@ Select a profile tier based on your machine and workflow needs:
152
182
 
153
183
  | Profile | Skills | Predefined Agents | Description | Best For |
154
184
  | :--- | :---: | :---: | :--- | :--- |
155
- | **`full`** *(Default)* | 64 | 10 | Complete engineering suite: planning, design, security, database, hygiene. | Everyday development across all tools |
185
+ | **`full`** *(Default)* | 69 | 10 | Complete engineering suite: planning, design, security, database, hygiene. | Everyday development across all tools |
156
186
  | **`minimal`** | 16 | 4 | Lean core: `orchestrator`, `tester`, `code-sentinel`, `reviewer`. | Lightweight laptops, smaller context windows |
157
187
  | **`security`** | 12 | 4 | AppSec suite: `orchestrator`, `security-auditor`, `tester`, `reviewer`. | Penetration testing & pre-deployment audits |
158
- | **`design`** | 12 | 4 | Frontend & mobile: `orchestrator`, `frontend-designer`, `mobile-designer`, `code-sentinel`. | UI/UX design and design-system work |
188
+ | **`design`** | 13 | 4 | Frontend & mobile: `orchestrator`, `frontend-designer`, `mobile-designer`, `code-sentinel`. | UI/UX design and design-system work |
159
189
 
160
190
  To deploy a specific profile:
161
191
  ```powershell
@@ -177,6 +207,41 @@ Heimdall automatically discovers and configures installed AI tools:
177
207
  | **OpenDesign** | `open-design` on PATH / `.opendesign` | Automatic visual canvas mode: bypasses Turn 1 grilling gate, preserves `data-od-*` attributes & applies `taste-skill` + `antislop-ui` |
178
208
  | **Claude Desktop** | `%APPDATA%\Claude` | Auto-configures Context7 MCP and playbooks in `claude_desktop_config.json` |
179
209
 
210
+ ### MCP Server Architecture
211
+
212
+ Heimdall manages Model Context Protocol (MCP) servers through a **template-based resolver** that eliminates Windows `npx` process multiplication and keeps configuration consistent across all installed harnesses.
213
+
214
+ #### How It Works
215
+
216
+ 1. **Global Package Install**: During setup (`node setup.mjs`), Heimdall automatically installs required MCP packages globally via `npm install -g`:
217
+ - `@upstash/context7-mcp` — up-to-date library documentation queries
218
+ - `chrome-devtools-mcp` — browser automation and performance profiling
219
+
220
+ 2. **Template Resolution**: The portable template at `config/mcp.template.json` declares server definitions with `{{PLACEHOLDER}}` tokens and `resolve` hints. The resolver script (`scripts/resolve-mcp.mjs`) detects local paths at runtime and generates `config/mcp.resolved.json` with direct `node.exe` entrypoints.
221
+
222
+ 3. **Dynamic Harness Detection**: The resolver syncs to **every installed harness** by checking for config file existence — it does not hardcode a fixed set of targets:
223
+ - Gemini → `~/.gemini/config/mcp_config.json` (JSON)
224
+ - Claude Code → `~/.claude/settings.json` (JSON)
225
+ - Codex CLI → `~/.codex/config.toml` (TOML `[mcp_servers.*]`)
226
+ - Hermes → `%LOCALAPPDATA%\hermes\config.yaml` (YAML `mcp_servers:`)
227
+ - Any future harness added to the resolver is auto-detected on next sync
228
+
229
+ 4. **Direct `node.exe` Invocation**: Resolved configs use `C:\Program Files\nodejs\node.exe <entrypoint.js>` instead of `npx`, spawning exactly **1 process per server per session** with zero `cmd.exe` wrappers and zero orphan multiplication on exit.
230
+
231
+ #### Daily MCP Commands
232
+
233
+ ```powershell
234
+ # Re-resolve paths and sync to all installed harnesses (after toggling servers or updating packages)
235
+ /mcp-sync
236
+
237
+ # Kill orphaned MCP processes left behind by crashed sessions
238
+ /mcp-cleanup
239
+ ```
240
+
241
+ #### Disabling Heavy Servers
242
+
243
+ Edit `config/mcp.template.json` and set `"disabled": true` on any server (e.g., `chrome-devtools`) to prevent it from spawning in new sessions. Run `/mcp-sync` after editing.
244
+
180
245
  [↑ Back to top](#table-of-contents)
181
246
 
182
247
  ---
@@ -198,6 +263,11 @@ heimdall audit
198
263
  # Refresh dynamic model catalog from your active provider/proxy
199
264
  heimdall sync-models
200
265
 
266
+ # Enable, disable, or theme the 2-line Heimdall HUD statusline
267
+ heimdall hud
268
+ heimdall hud --on --theme night-blue
269
+ heimdall hud --off
270
+
201
271
  # Browse canonical skills catalog and upstream repositories
202
272
  heimdall skills
203
273
 
@@ -214,7 +284,9 @@ heimdall uninstall
214
284
  | Flag | Default | Description | Example |
215
285
  | :--- | :---: | :--- | :--- |
216
286
  | `--profile <name>` | `full` | Skill profile tier: `full`, `minimal`, `security`, or `design`. | `heimdall --profile minimal` |
217
- | `--agents <targets>` | `all` | Comma-separated list of harnesses: `claude`, `gemini`, `codex`, `desktop`, `all`. | `heimdall --agents claude,gemini` |
287
+ | `--agents <targets>` | `all` | Comma-separated list of harnesses: `claude`, `gemini`, `codex`, `hermes`, `openclaw`, `vscode`, `desktop`, `all`. | `heimdall --agents claude,vscode` |
288
+ | `--theme <name>` | `night-blue` | HUD color theme: `night-blue`, `heimdall`, `claude-warm`, or `titanium`. | `heimdall hud --theme claude-warm` |
289
+ | `--no-hud` | `false` | Skip configuring the Heimdall HUD statusline during install or sync. | `heimdall --no-hud` |
218
290
  | `--link` | `true` (rec.) | Deploy skills using live NTFS junctions (Windows) or POSIX symlinks (macOS/Linux). | `heimdall --link` |
219
291
  | `--clean` | `false` | Wipe legacy skills from target directory before deploying. | `heimdall --clean` |
220
292
  | `--dry-run` | `false` | Simulate execution and display actions without modifying the filesystem. | `heimdall --dry-run` |
@@ -289,28 +361,28 @@ All personas declare `model: inherit` to run on whichever active model or vendor
289
361
 
290
362
  | Persona | Capability Tier | Role & Responsibilities | Bound Skills |
291
363
  | :--- | :--- | :--- | :--- |
292
- | **`orchestrator`** | `deep_reasoning` | Planning gatekeeper (`/grill-me`), requirements interrogation, modular task decomposition, Playwright E2E verification enforcement, and subagent coordination. | `grill-me`, `brainstorming`, `writing-plans`, `to-spec`, `to-tickets`, `wayfinder`, `domain-modeling`, `handoff`, `pstack-discipline`, `subagent-driven-development`, `dispatching-parallel-agents`, `using-git-worktrees`, `writing-skills`, `executing-plans`, `herdr` |
293
- | **`frontend-designer`** | `high_polish_vision` | Enforces design read, typography hierarchy, token mappings, and anti-slop UI aesthetics for web surfaces. | `taste-skill`, `brandkit`, `minimalist-skill`, `brutalist-skill`, `soft-skill`, `antislop-ui`, `antislop-human`, `stitch-skill`, `image-to-code-skill`, `imagegen-frontend-web`, `redesign-skill` |
364
+ | **`orchestrator`** | `deep_reasoning` | Planning gatekeeper (`/grill-me`), requirements interrogation, modular task decomposition, Playwright E2E verification enforcement, and subagent coordination. | `grill-me`, `brainstorming`, `writing-plans`, `to-spec`, `to-tickets`, `wayfinder`, `domain-modeling`, `handoff`, `pstack-discipline`, `subagent-driven-development`, `dispatching-parallel-agents`, `using-git-worktrees`, `writing-skills`, `executing-plans`, `herdr`, `upstream-skill-sync` |
365
+ | **`frontend-designer`** | `high_polish_vision` | Enforces design read, typography hierarchy, token mappings, and anti-slop UI aesthetics for web surfaces. | `taste-skill`, `brandkit`, `minimalist-skill`, `brutalist-skill`, `soft-skill`, `antislop-ui`, `antislop-human`, `stitch-skill`, `image-to-code-skill`, `imagegen-frontend-web`, `redesign-skill`, `modern-web-guidance` |
294
366
  | **`mobile-designer`** | `responsive_flex_safety` | Mobile viewport safety (320px–430px), 48px touch targets, zero-clipping overflow flex containers, and responsive assets. | `antislop-layoutmobile`, `antislop-human`, `antislop-ui`, `imagegen-frontend-mobile`, `taste-skill` |
295
367
  | **`tester`** | `fast_verification` | Enforces strict Test-Driven Development (TDD) and browser verification (Playwright). Rejects pseudo-verification (`curl`, `grep`, `tsc`). | `test-driven-development`, `verification-before-completion`, `systematic-debugging`, `executing-plans` |
296
368
  | **`security-auditor`** | `deep_assurance_audit` | Dynamic differential HTTP probing across auth levels, OWASP Top 10 defenses, and Trail of Bits insecure defaults detection. | `strix-security`, `security-audit-sweep`, `owasp-security`, `cloudflare-security-audit`, `snyk-agent-scan`, `trailofbits-audit-context`, `trailofbits-insecure-defaults`, `trailofbits-triage-brocards` |
297
369
  | **`database-architect`** | `schema_migration_safety` | Governs non-destructive migrations, normalization, query plan audits (`EXPLAIN ANALYZE`), and connection pooling (Postgres/Supabase, SQLite, MySQL). | `postgres-best-practices`, `systematic-debugging`, `karpathy-guidelines` |
298
- | **`code-sentinel`** | `surgical_restraint` | Karpathy simplicity: writes minimal surgical code, strips boilerplate comments, purges defensive dead code, enforces deep modules, and applies anti-slop standards. | `karpathy-guidelines`, `clean-code`, `codebase-design`, `ponytail`, `antislop`, `antislop-code`, `antislop-copywriting`, `antislop-human`, `finishing-a-development-branch` |
370
+ | **`code-sentinel`** | `surgical_restraint` | Karpathy simplicity: writes minimal surgical code, strips boilerplate comments, purges defensive dead code, enforces deep modules, and applies anti-slop standards. | `communication-doctrine`, `karpathy-guidelines`, `clean-code`, `codebase-design`, `ponytail`, `antislop`, `antislop-code`, `antislop-copywriting`, `antislop-human`, `finishing-a-development-branch` |
299
371
  | **`reviewer`** | `adversarial_diff_eval` | Performs adversarial diff analysis, audits module depth and leaky abstractions, catches silent regressions, executes thermo maintainability reviews, and coordinates cross-model validation reviews. | `communication-doctrine`, `thermo`, `codebase-design`, `requesting-code-review`, `receiving-code-review`, `claude-collaborator`, `gemini-collaborator`, `codex-collaborator`, `using-superpowers`, `diagnosing-superpowers`, `output-skill` |
300
- | **`modernizer`** | `legacy_migration_safety` | Executes legacy codebase transformations, runtime upgrades, dependency uncoupling, and Strangler Fig migrations guarded by Golden Master characterization tests. | `test-driven-development`, `verification-before-completion`, `systematic-debugging`, `improve-codebase-architecture`, `codebase-design`, `karpathy-guidelines`, `project-hygiene`, `output-skill` |
372
+ | **`modernizer`** | `legacy_migration_safety` | Executes legacy codebase transformations, runtime upgrades, dependency uncoupling, and Strangler Fig migrations guarded by Golden Master characterization tests. | `test-driven-development`, `verification-before-completion`, `systematic-debugging`, `improve-codebase-architecture`, `codebase-design`, `karpathy-guidelines`, `project-hygiene`, `output-skill`, `modern-web-guidance`, `upstream-skill-sync` |
301
373
  | **`cloud-engineer`** | `infra_container_safety` | Governs containerization (Docker, Compose), Kubernetes manifests, Infrastructure as Code (Terraform), reverse proxies (Caddy, Nginx), CI/CD automation, and terminating verification. | `communication-doctrine`, `karpathy-guidelines`, `clean-code`, `systematic-debugging`, `project-hygiene`, `progressive-disclosure` |
302
374
 
303
375
  ---
304
376
 
305
- <a id="skill-inventory-64-modules-across-25-toolkits"></a>
306
- ### Skill Inventory (64 Modules Across 25 Toolkits)
377
+ <a id="skill-inventory-69-modules-across-30-toolkits"></a>
378
+ ### Skill Inventory (69 Modules Across 30 Toolkits)
307
379
 
308
- Heimdall organizes capabilities into **6 Core Multi-Skill Suites (45 modules)** and **19 Standalone Toolkits (19 modules)**:
380
+ Heimdall organizes capabilities into **6 Core Multi-Skill Suites (45 modules)** and **24 Standalone Toolkits (24 modules)**:
309
381
 
310
382
  #### Core Multi-Skill Suites (6 Suites / 45 Modules)
311
383
 
312
384
  <details open>
313
- <summary><b>1. Superpowers Engineering Suite (15 modules) — Jesse Vincent / obra</b></summary>
385
+ <summary><b>1. Superpowers Engineering Suite (15 modules) — <a href="https://github.com/obra/superpowers">obra/superpowers</a></b></summary>
314
386
 
315
387
  - `brainstorming`: Surfaces implicit assumptions and explores alternatives before design lock.
316
388
  - `writing-plans`: Structures modular, bite-sized tasks with verifiable completion criteria.
@@ -331,7 +403,7 @@ Heimdall organizes capabilities into **6 Core Multi-Skill Suites (45 modules)**
331
403
  </details>
332
404
 
333
405
  <details>
334
- <summary><b>2. Taste Design & Aesthetic Studio (10 modules)</b></summary>
406
+ <summary><b>2. Taste Design & Aesthetic Studio (10 modules) — <a href="https://github.com/Leonxlnx/taste-skill">Leonxlnx/taste-skill</a></b></summary>
335
407
 
336
408
  - `taste-skill`: Enforces cohesive design reads, purpose-driven typography, and brand-first color logic.
337
409
  - `brandkit`: Manages design tokens, invariant brand assets, and multi-palette themes.
@@ -347,7 +419,7 @@ Heimdall organizes capabilities into **6 Core Multi-Skill Suites (45 modules)**
347
419
  </details>
348
420
 
349
421
  <details>
350
- <summary><b>3. Anti-Slop Quality Suite (6 modules) — Jesse Vincent / obra</b></summary>
422
+ <summary><b>3. Anti-Slop Quality Suite (6 modules) — <a href="https://github.com/miqdadbadjuber/anti-slop">miqdadbadjuber/anti-slop</a></b></summary>
351
423
 
352
424
  - `antislop`: Core guardrail prohibiting generic AI filler, fake buzzwords, and decorative bloat.
353
425
  - `antislop-code`: Prohibits redundant comments, defensive dead code, and speculative abstractions.
@@ -368,7 +440,7 @@ Heimdall organizes capabilities into **6 Core Multi-Skill Suites (45 modules)**
368
440
  </details>
369
441
 
370
442
  <details>
371
- <summary><b>5. Trail of Bits High-Assurance AppSec Suite (3 modules) — Trail of Bits</b></summary>
443
+ <summary><b>5. Trail of Bits High-Assurance AppSec Suite (3 modules) — <a href="https://github.com/trailofbits/skills">trailofbits/skills</a></b></summary>
372
444
 
373
445
  - `trailofbits-audit-context`: High-assurance code assumption, guarantee, and architectural dependency mapping.
374
446
  - `trailofbits-insecure-defaults`: Detection of insecure default configurations, fail-open patterns, and permissive access.
@@ -376,7 +448,7 @@ Heimdall organizes capabilities into **6 Core Multi-Skill Suites (45 modules)**
376
448
 
377
449
  </details>
378
450
 
379
- #### Standalone Toolkits (19 Curated Toolkits / 19 Modules)
451
+ #### Standalone Toolkits (24 Curated Toolkits / 24 Modules)
380
452
 
381
453
  <details open>
382
454
  <summary><b>Browse Standalone Toolkits</b></summary>
@@ -400,6 +472,11 @@ Heimdall organizes capabilities into **6 Core Multi-Skill Suites (45 modules)**
400
472
  - **`progressive-disclosure`**: Anthropic & Google-aligned 3-layer progressive disclosure standard cutting prompt overhead by >80% and preventing subagent sprawl.
401
473
  - **`project-hygiene`**: Sweeps workspaces for dead code, unused exports, circular dependencies, and stale build caches.
402
474
  - **`output-skill`**: Guarantees unabridged LLM output without ellipses (`...`), incomplete code blocks, or truncation.
475
+ - **`ruminate`**: Mines historical Claude and Gemini session transcripts for correction patterns, repeated preferences, skill trigger failures, doctrine violations, and cross-agent consistency drift. Writes findings as memory files or skill amendments. Inspired by [poteto/brainmaxxing](https://github.com/poteto/brainmaxxing).
476
+ - **`modern-web-guidance`**: Google Chrome's official modern web platform skill pack (`GoogleChrome/modern-web-guidance`). Steers agents toward Baseline-safe native HTML/CSS/JS APIs, Core Web Vitals (LCP/INP/CLS) best practices, and `legacy-scan` frontend modernization.
477
+ - **`mcp-cleanup`**: Kills orphaned MCP server processes left behind by crashed or closed agent sessions.
478
+ - **`mcp-sync`**: Resolves the Heimdall MCP template to local paths and syncs across installed agent harnesses.
479
+ - **`upstream-skill-sync`**: Audits upstream skill repositories in `config/skills.json` and classifies updates into Safe 1:1, Selective Merge, or Reject.
403
480
 
404
481
  </details>
405
482
 
@@ -417,6 +494,7 @@ For multi-device pair programming, mobile monitoring, and project memory, Heimda
417
494
  * **[Moshi (`getmoshi.app`)](https://getmoshi.app/)**: Mobile client (iOS/Android) pairing with your terminal session. Delivers push notifications when an agent hits an interactive planning gate and enables remote approval.
418
495
  * **[Graphify (`github.com/Graphify-Labs/graphify`)](https://github.com/Graphify-Labs/graphify)**: Local-first code knowledge graph builder. Uses Tree-sitter AST parsing across 40+ programming languages to build deterministic dependency maps with zero LLM API costs, exporting directly to Obsidian vaults.
419
496
  * **[Obsidian (`obsidian.md`)](https://obsidian.md/)**: Local-first Markdown knowledge base. Paired with Graphify-generated vaults (`[[wikilinks]]`), it serves as persistent external memory for AI coding agents, loading immediate architectural context on startup without token-heavy scanning.
497
+ * **Heimdall HUD ([`tools/heimdall-hud.mjs`](tools/heimdall-hud.mjs))**: Built-in 2-line terminal statusline for **Claude Code** and **Google Antigravity (`agy`)** displaying model, color-coded context bar, git branch/dirty count, token usage, session cost, and duration across 4 themes (`night-blue` default, `heimdall`, `claude-warm`, `titanium`). For **Codex CLI** (which does not execute external `statusLine` scripts), `heimdall hud` configures Codex's native `[tui] status_line` items in `~/.codex/config.toml`.
420
498
 
421
499
  [↑ Back to top](#table-of-contents)
422
500