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
package/docs/SKILLS.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Heimdall Canonical Skills & Suites Directory
2
2
 
3
- This directory serves as the comprehensive reference manual for Heimdall's **24 Primary Toolkits & Suites (56 modular capabilities)**.
3
+ This directory serves as the reference manual for Heimdall's **30 Primary Toolkits & Suites (69 modular capabilities)**.
4
4
 
5
5
  > **Architecture & Execution**: Each skill module is an isolated directory containing a YAML-frontmattered `SKILL.md`. AI agent harnesses (Google Antigravity, Claude Code, OpenAI Codex CLI) parse frontmatter on startup and dynamically activate instructions via progressive disclosure.
6
6
 
@@ -24,6 +24,7 @@ heimdall update-skill all
24
24
  - [📦 Anti-Slop Quality & Token Efficiency Suite (6 modules)](#antislop)
25
25
  - [📦 Tri-Directional Cross-Model Bridges (3 modules)](#cross-model-bridges)
26
26
  - [📦 Trail of Bits High-Assurance AppSec Suite (3 modules)](#trailofbits-appsec)
27
+ - [📦 Matt Pocock Real Engineering Suite (8 modules)](#mattpocock-suite)
27
28
 
28
29
  ### Standalone Power Toolkits
29
30
  - [⚡ Ponytail Code Restraint](#ponytail)
@@ -38,13 +39,17 @@ heimdall update-skill all
38
39
  - [⚡ Project & Workspace Hygiene Sentinel](#project-hygiene)
39
40
  - [⚡ Structured Analysis & Output Formatting](#output-skill)
40
41
  - [⚡ Caveman Chat Token Brevity Protocol](#caveman)
41
- - [⚡ Clean Code & ub-mode Quality Sentinel](#clean-code)
42
- - [⚡ Communication Doctrine (BLUF & STE)](#communication-doctrine)
43
- - [⚡ STRIDE Threat Modeling & Attack Surface Sentinel](#threat-modeling)
44
- - [⚡ MCP Server & Tool Engineering Standards](#mcp-engineering)
45
- - [⚡ Herdr Coding Agent Multiplexer & Orchestrator](#herdr)
46
- - [⚡ Thermo Architectural & Maintainability Audit](#thermo)
42
+ - [⚡ Clean Code & ub-mode Quality Sentinel](#clean-code)
43
+ - [⚡ Communication Doctrine (BLUF & STE)](#communication-doctrine)
44
+ - [⚡ STRIDE Threat Modeling & Attack Surface Sentinel](#threat-modeling)
45
+ - [⚡ MCP Server & Tool Engineering Standards](#mcp-engineering)
46
+ - [⚡ Herdr Coding Agent Multiplexer & Orchestrator](#herdr)
47
+ - [⚡ Thermo Architectural & Maintainability Audit](#thermo)
47
48
  - [⚡ PStack Engineering Discipline](#pstack-discipline)
49
+ - [⚡ Google Chrome Modern Web Guidance](#modern-web-guidance)
50
+ - [⚡ MCP Orphan Process Cleanup](#mcp-cleanup)
51
+ - [⚡ MCP Template Resolver & Sync](#mcp-sync)
52
+ - [⚡ Upstream Skill Sync & Triage](#upstream-skill-sync)
48
53
 
49
54
  ---
50
55
 
@@ -67,7 +72,7 @@ heimdall update-skill all
67
72
  * **`systematic-debugging`**: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes ([Contract File](../skills/systematic-debugging/SKILL.md))
68
73
  * **`verification-before-completion`**: Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always ([Contract File](../skills/verification-before-completion/SKILL.md))
69
74
  * **`finishing-a-development-branch`**: Use when implementation is complete, all tests pass, and you need to decide how to integrate the work ([Contract File](../skills/finishing-a-development-branch/SKILL.md))
70
- * **`using-git-worktrees`**: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback ([Contract File](../skills/using-git-worktrees/SKILL.md))
75
+ * **`using-git-worktrees`**: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - verifies or creates an isolated workspace via native tools or git worktree fallback ([Contract File](../skills/using-git-worktrees/SKILL.md))
71
76
  * **`requesting-code-review`**: Use when completing tasks, implementing major features, or before merging to verify work meets requirements ([Contract File](../skills/requesting-code-review/SKILL.md))
72
77
  * **`receiving-code-review`**: Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation ([Contract File](../skills/receiving-code-review/SKILL.md))
73
78
  * **`using-superpowers`**: Use when starting any conversation - establishes how to find and use skills, requiring skill invocation before ANY response including clarifying questions ([Contract File](../skills/using-superpowers/SKILL.md))
@@ -154,6 +159,27 @@ heimdall update-skill all
154
159
 
155
160
  ## Standalone Power Toolkits
156
161
 
162
+ <a id="mattpocock-suite"></a>
163
+ ### 📦 Matt Pocock Real Engineering Suite (8 modules)
164
+
165
+ - **Upstream Source**: [https://github.com/mattpocock/skills](https://github.com/mattpocock/skills)
166
+ - **Suite Type**: Multi-Skill Suite
167
+
168
+ #### Included Modules:
169
+
170
+ * **`codebase-design`**: Design deep modules (small interfaces hiding large implementations), apply the deletion test, and enforce legitimate seams based on John Ousterhout's *Philosophy of Software Design*. ([Contract File](../skills/codebase-design/SKILL.md))
171
+ * **`domain-modeling`**: Extract ubiquitous language, domain models, and record Architecture Decision Records (ADRs) to eliminate terminology drift and document architectural choices. ([Contract File](../skills/domain-modeling/SKILL.md))
172
+ * **`improve-codebase-architecture`**: Audit codebase structure, detect circular dependencies, evaluate module coupling, and generate dependency matrix reports. ([Contract File](../skills/improve-codebase-architecture/SKILL.md))
173
+ * **`to-spec`**: Formalize requirements and interview outcomes into precise specifications with invariants, error matrices, and user journeys. ([Contract File](../skills/to-spec/SKILL.md))
174
+ * **`to-tickets`**: Decompose formal specifications into atomic, dependency-ordered task tickets formatted for subagent task queues. ([Contract File](../skills/to-tickets/SKILL.md))
175
+ * **`wayfinder`**: Map problem frontiers across large codebases, separating settled decisions from active frontier tickets and unexplored fog. ([Contract File](../skills/wayfinder/SKILL.md))
176
+ * **`grill-me`**: Relentless interview protocol using the Design Tree Frontier, autonomous fact-finding, and Yes-to-Approve recommendation format before implementation begins. ([Contract File](../skills/grill-me/SKILL.md))
177
+ * **`handoff`**: Compact session context into pointer-first handoff documents saved to $env:TEMP with mandatory Suggested Skills contracts to eliminate context drift and skill blindness. ([Contract File](../skills/handoff/SKILL.md))
178
+
179
+ [↑ Back to top](#toc)
180
+
181
+ ---
182
+
157
183
  <a id="ponytail"></a>
158
184
  ### ⚡ Ponytail Code Restraint
159
185
 
@@ -305,74 +331,131 @@ heimdall update-skill all
305
331
  - **Aliases**: `/clean-code`, `/ub-mode`
306
332
  - **Description**: Enforces Uncle Bob's Clean Code discipline, TDD cycles, laziness protocol, and mathematical quality gates (CRAP < 10, DRY similarity < 0.8, mutant-killing test design).
307
333
  - **Upstream Source**: [https://github.com/unclebob/ub-mode](https://github.com/unclebob/ub-mode)
308
- - **Contract File**: [`skills/clean-code/SKILL.md`](../skills/clean-code/SKILL.md)
309
-
310
- [↑ Back to top](#toc)
311
-
312
- ---
313
-
314
- <a id="communication-doctrine"></a>
315
- ### ⚡ Communication Doctrine (BLUF & Simplified Technical English)
316
-
317
- - **Module Name**: `communication-doctrine`
318
- - **Description**: Enforces zero-latency Bottom Line Up Front (BLUF) headers on subagent handoffs, code reviews, and plans, alongside Simplified Technical English (STE) imperative syntax that eliminates ambiguous qualifiers.
334
+ - **Contract File**: [`skills/clean-code/SKILL.md`](../skills/clean-code/SKILL.md)
335
+
336
+ [↑ Back to top](#toc)
337
+
338
+ ---
339
+
340
+ <a id="communication-doctrine"></a>
341
+ ### ⚡ Communication Doctrine (BLUF & Simplified Technical English)
342
+
343
+ - **Module Name**: `communication-doctrine`
344
+ - **Description**: Enforces zero-latency Bottom Line Up Front (BLUF) headers on subagent handoffs, code reviews, and plans, alongside Simplified Technical English (STE) imperative syntax that eliminates ambiguous qualifiers.
319
345
  - **Contract File**: [`skills/communication-doctrine/SKILL.md`](../skills/communication-doctrine/SKILL.md)
320
346
 
321
347
  [↑ Back to top](#toc)
322
348
 
323
- ---
324
-
325
- <a id="threat-modeling"></a>
326
- ### ⚡ STRIDE Threat Modeling & Attack Surface Sentinel
327
-
328
- - **Module Name**: `threat-modeling`
329
- - **Description**: Systematic STRIDE threat modeling, trust boundary mapping, and mitigation verification for architecture, API, and cloud infrastructure changes.
330
- - **Contract File**: [`skills/threat-modeling/SKILL.md`](../skills/threat-modeling/SKILL.md)
331
-
332
- [↑ Back to top](#toc)
333
-
334
- ---
335
-
336
- <a id="mcp-engineering"></a>
337
- ### ⚡ MCP Server & Tool Engineering Standards
338
-
339
- - **Module Name**: `mcp-engineering`
340
- - **Description**: Standards, JSON-RPC 2.0 protocol compliance, schema validation, and stdio/SSE transport discipline for authoring Model Context Protocol (MCP) servers and tools.
341
- - **Contract File**: [`skills/mcp-engineering/SKILL.md`](../skills/mcp-engineering/SKILL.md)
342
-
343
- [↑ Back to top](#toc)
344
-
345
- ---
346
-
347
- <a id="herdr"></a>
348
- ### ⚡ Herdr Coding Agent Multiplexer & Orchestrator
349
-
350
- - **Module Name**: `herdr`
351
- - **Description**: Control Herdr, a terminal workspace manager for coding agents. Inspect or control panes, tabs, workspaces, commands, or coordinate with peer agents (claude, codex, gemini/agy, etc.) in persistent terminal sessions.
352
- - **Contract File**: [`skills/herdr/SKILL.md`](../skills/herdr/SKILL.md)
353
-
354
- [↑ Back to top](#toc)
355
-
356
- ---
357
-
358
- <a id="thermo"></a>
359
- ### ⚡ Thermo Architectural & Maintainability Audit
360
-
361
- - **Module Name**: `thermo`
362
- - **Description**: Unusually strict architectural and maintainability review focusing on "Code Judo" structural simplification, spaghetti conditional elimination, and modularity health.
363
- - **Contract File**: [`skills/thermo/SKILL.md`](../skills/thermo/SKILL.md)
364
-
365
- [↑ Back to top](#toc)
366
-
367
- ---
368
-
369
- <a id="pstack-discipline"></a>
370
- ### ⚡ PStack Engineering Discipline
371
-
372
- - **Module Name**: `pstack-discipline`
373
- - **Description**: High-rigor engineering discipline from the pstack / poteto framework: "Prove It Works", "Fix Root Causes", "Test Behavior, Not Implementation", and "Subtract Before You Add".
374
- - **Contract File**: [`skills/pstack-discipline/SKILL.md`](../skills/pstack-discipline/SKILL.md)
375
-
376
- [↑ Back to top](#toc)
377
-
378
- ---
349
+ ---
350
+
351
+ <a id="threat-modeling"></a>
352
+ ### ⚡ STRIDE Threat Modeling & Attack Surface Sentinel
353
+
354
+ - **Module Name**: `threat-modeling`
355
+ - **Description**: Systematic STRIDE threat modeling, trust boundary mapping, and mitigation verification for architecture, API, and cloud infrastructure changes.
356
+ - **Contract File**: [`skills/threat-modeling/SKILL.md`](../skills/threat-modeling/SKILL.md)
357
+
358
+ [↑ Back to top](#toc)
359
+
360
+ ---
361
+
362
+ <a id="mcp-engineering"></a>
363
+ ### ⚡ MCP Server & Tool Engineering Standards
364
+
365
+ - **Module Name**: `mcp-engineering`
366
+ - **Description**: Standards, JSON-RPC 2.0 protocol compliance, schema validation, and stdio/SSE transport discipline for authoring Model Context Protocol (MCP) servers and tools.
367
+ - **Contract File**: [`skills/mcp-engineering/SKILL.md`](../skills/mcp-engineering/SKILL.md)
368
+
369
+ [↑ Back to top](#toc)
370
+
371
+ ---
372
+
373
+ <a id="herdr"></a>
374
+ ### ⚡ Herdr Coding Agent Multiplexer & Orchestrator
375
+
376
+ - **Module Name**: `herdr`
377
+ - **Description**: Control Herdr, a terminal workspace manager for coding agents. Inspect or control panes, tabs, workspaces, commands, or coordinate with peer agents (claude, codex, gemini/agy, etc.) in persistent terminal sessions.
378
+ - **Contract File**: [`skills/herdr/SKILL.md`](../skills/herdr/SKILL.md)
379
+
380
+ [↑ Back to top](#toc)
381
+
382
+ ---
383
+
384
+ <a id="thermo"></a>
385
+ ### ⚡ Thermo Architectural & Maintainability Audit
386
+
387
+ - **Module Name**: `thermo`
388
+ - **Description**: Unusually strict architectural and maintainability review focusing on "Code Judo" structural simplification, spaghetti conditional elimination, and modularity health.
389
+ - **Contract File**: [`skills/thermo/SKILL.md`](../skills/thermo/SKILL.md)
390
+
391
+ [↑ Back to top](#toc)
392
+
393
+ ---
394
+
395
+ <a id="pstack-discipline"></a>
396
+ ### ⚡ PStack Engineering Discipline
397
+
398
+ - **Module Name**: `pstack-discipline`
399
+ - **Description**: High-rigor engineering discipline from the pstack / poteto framework: "Prove It Works", "Fix Root Causes", "Test Behavior, Not Implementation", and "Subtract Before You Add".
400
+ - **Contract File**: [`skills/pstack-discipline/SKILL.md`](../skills/pstack-discipline/SKILL.md)
401
+
402
+ [↑ Back to top](#toc)
403
+
404
+ ---
405
+
406
+ <a id="ruminate"></a>
407
+ ### ⚡ Ruminate Session Transcript Mining
408
+
409
+ - **Module Name**: `ruminate`
410
+ - **Description**: Mine historical Claude and Gemini session transcripts for correction patterns, repeated preferences, skill trigger failures, agent selection accuracy, doctrine violations, and cross-agent consistency drift. Writes findings as memory files or skill amendments. Use when bootstrapping a brain from existing conversation history or running periodic deep audits.
411
+ - **Upstream Inspiration**: [https://github.com/poteto/brainmaxxing](https://github.com/poteto/brainmaxxing)
412
+ - **Contract File**: [`skills/ruminate/SKILL.md`](../skills/ruminate/SKILL.md)
413
+
414
+ [↑ Back to top](#toc)
415
+
416
+ ---
417
+
418
+ <a id="modern-web-guidance"></a>
419
+ ### ⚡ Google Chrome Modern Web Guidance
420
+
421
+ - **Module Name**: `modern-web-guidance`
422
+ - **Description**: Search and retrieve Google Chrome Modern Web Guidance (Baseline-safe native HTML/CSS/JS APIs, Core Web Vitals, accessibility, and `legacy-scan` frontend modernization).
423
+ - **Upstream Source**: [https://github.com/GoogleChrome/modern-web-guidance](https://github.com/GoogleChrome/modern-web-guidance)
424
+ - **Contract File**: [`skills/modern-web-guidance/SKILL.md`](../skills/modern-web-guidance/SKILL.md)
425
+
426
+ [↑ Back to top](#toc)
427
+
428
+ ---
429
+
430
+ <a id="mcp-cleanup"></a>
431
+ ### ⚡ MCP Orphan Process Cleanup
432
+
433
+ - **Module Name**: `mcp-cleanup`
434
+ - **Description**: Kill orphaned MCP server processes left behind by crashed or closed agent sessions.
435
+ - **Contract File**: [`skills/mcp-cleanup/SKILL.md`](../skills/mcp-cleanup/SKILL.md)
436
+
437
+ [↑ Back to top](#toc)
438
+
439
+ ---
440
+
441
+ <a id="mcp-sync"></a>
442
+ ### ⚡ MCP Template Resolver & Sync
443
+
444
+ - **Module Name**: `mcp-sync`
445
+ - **Description**: Resolve Heimdall MCP template to local paths and sync to agent harness configs.
446
+ - **Contract File**: [`skills/mcp-sync/SKILL.md`](../skills/mcp-sync/SKILL.md)
447
+
448
+ [↑ Back to top](#toc)
449
+
450
+ ---
451
+
452
+ <a id="upstream-skill-sync"></a>
453
+ ### ⚡ Upstream Skill Sync & Triage
454
+
455
+ - **Module Name**: `upstream-skill-sync`
456
+ - **Description**: Audit upstream skill repositories in `config/skills.json` and classify updates via the 3-tier triage rubric (Safe 1:1, Defer/Selective Merge, Reject).
457
+ - **Contract File**: [`skills/upstream-skill-sync/SKILL.md`](../skills/upstream-skill-sync/SKILL.md)
458
+
459
+ [↑ Back to top](#toc)
460
+
461
+ ---
@@ -0,0 +1,60 @@
1
+ # Plan: Upstream Skill Provenance Links & `upstream-skill-sync` Triage Skill
2
+
3
+ ### Plan BLUF
4
+ - **Goal**: Add clickable upstream links to `readme.html` and `README*.md`, classify all 68+ skills by `integrationMode` in `config/skills.json`, and create `skills/upstream-skill-sync/SKILL.md` with a 3-tier update rubric.
5
+ - **Architectural Approach**: Approach A — enrich `config/skills.json` with `integrationMode` (`mirror` | `adapted` | `native`), bind a new `upstream-skill-sync` skill to `orchestrator` and `modernizer`, and surface `upstream` URLs across `readme.html`, `README.md`, and `README.pt-BR.md`.
6
+ - **Risk & Blast Radius**: Low — additive documentation, registry metadata, and one new skill (`68` → `69` modules, `29` → `30` toolkits); verified by `test/catalog-integrity.test.mjs` and `npm test`.
7
+ - **Human Approval Gate**: Required before modifying repository source/config files.
8
+
9
+ ---
10
+
11
+ ## Goal Description
12
+
13
+ Every skill in `config/skills.json` already records an `upstream` repository URL, and `heimdall update-skill <name|all>` prints those URLs. However:
14
+ 1. `readme.html` and `README.md` / `README.pt-BR.md` do not link individual skills or toolkits directly to their original upstream sources.
15
+ 2. Users have no standardized skill or decision rubric to instruct an AI harness to audit upstream repositories and classify changes into **Safe (1:1)**, **Defer / Selective Merge**, or **Not Recommended (Reject)** without overwriting Heimdall-specific customizations (such as `/ruminate` additions in `handoff` and `writing-plans`, BLUF/ASD-STE100 rules, or the Zero Dev-Server Policy).
16
+
17
+ This plan implements **Approach A** (Skill-Driven + Registry Metadata).
18
+
19
+ ---
20
+
21
+ ## Proposed Changes
22
+
23
+ ### 1. Registry Metadata & Triage Rubric (`config/skills.json`)
24
+
25
+ - Add `integrationMode` to every skill entry in `skills`:
26
+ - `"mirror"`: Clean 1:1 upstream skill (safe for direct diffing and 1:1 updates after security scan).
27
+ - `"adapted"`: Upstream skill with Heimdall-specific additions or overrides (e.g., `handoff`, `writing-plans`, `modern-web-guidance`, `ruminate`). Requires selective delta incorporation.
28
+ - `"native"`: Authored inside `heimdall-agent` (e.g., `communication-doctrine`, `mcp-sync`, `mcp-cleanup`, `claude-collaborator`, `gemini-collaborator`, `codex-collaborator`, `upstream-skill-sync`).
29
+ - Register the new `upstream-skill-sync` standalone suite & skill entry (`totalSuites`: `30`, `totalModules`: `69`).
30
+
31
+ ---
32
+
33
+ ### 2. Upstream Sync Skill & Agent Bindings
34
+
35
+ - Create `skills/upstream-skill-sync/SKILL.md` with frontmatter triggers (`"update skills"`, `"sync upstream skills"`, `"check skill updates"`, `"audit upstream"`).
36
+ - Define the 5-step execution workflow in ASD-STE100 syntax:
37
+ 1. **Read Registry**: Load `config/skills.json` and filter by target skill, suite, or `all`.
38
+ 2. **Check Upstream**: Run `git ls-remote <upstream>` or inspect upstream `SKILL.md` / release notes.
39
+ 3. **Security Gate**: Run `snyk-agent-scan` heuristics on fetched upstream diffs to block prompt injection or credential harvesting.
40
+ 4. **Classify via 3-Tier Triage Rubric**:
41
+ - **Tier 1 — Safe (1:1 Replace / Fast-Forward)**: Applies to `"mirror"` skills when upstream adds bugfixes, clearer examples, or new Baseline rules without violating Heimdall doctrine.
42
+ - **Tier 2 — Defer / Selective Merge**: Applies to `"adapted"` skills (or upstream skills overlapping existing Heimdall agents/doctrine). Extract only non-conflicting improvements; preserve `/ruminate` rules, BLUF/STE headers, and Goldfish isolation.
43
+ - **Tier 3 — Not Recommended (Reject / Skip)**: Reject upstream changes that introduce dev-server commands, chatbot closers, vague qualifiers (`ensure`, `properly`), bloated wrappers, or vendor lock-in.
44
+ 5. **Report & Verify**: Output a `Review Verdict` BLUF summary listing each skill's tier, source revision, and `npm test` status.
45
+ - Bind `upstream-skill-sync` in `agents/orchestrator.md` and `agents/modernizer.md`.
46
+
47
+ ---
48
+
49
+ ### 3. Upstream Provenance Links & Documentation Sync
50
+
51
+ - Update `readme.html`: add an `Upstream ↗` link and `mirror` / `adapted` / `native` badge to every skill card, add `upstream-skill-sync`, and update counters (`69` skills, `30` toolkits).
52
+ - Update `README.md` and `README.pt-BR.md`: add clickable upstream links to suite headings and standalone toolkit bullets, add `upstream-skill-sync` to the Standalone Toolkits list and `orchestrator` / `modernizer` rows.
53
+ - Update `docs/SKILLS.md` and run `syncCatalogCounts`.
54
+
55
+ ---
56
+
57
+ ## Verification Plan
58
+
59
+ 1. Run `npm test` (`node --test test/*.test.mjs`) to verify `Catalog and Documentation Count Integrity Sentinel` and `Communication Doctrine (BLUF & STE) Invariants` pass with `69` modules and `30` suites.
60
+ 2. Verify every skill card in `readme.html` has a valid `href="https://..."` upstream link and zero AI-slop buzzwords.