heimdall-agent 1.0.0 → 1.1.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 (231) hide show
  1. package/README.md +57 -26
  2. package/README.pt-BR.md +429 -0
  3. package/agents/cloud-engineer.md +77 -0
  4. package/agents/code-sentinel.md +66 -35
  5. package/agents/database-architect.md +31 -25
  6. package/agents/frontend-designer.md +30 -28
  7. package/agents/mobile-designer.md +25 -24
  8. package/agents/modernizer.md +66 -0
  9. package/agents/orchestrator.md +94 -93
  10. package/agents/reviewer.md +100 -71
  11. package/agents/security-auditor.md +27 -27
  12. package/agents/tester.md +97 -90
  13. package/commands/grill-me.md +20 -4
  14. package/commands/orchestrate.md +16 -0
  15. package/commands/orchestrator.md +16 -0
  16. package/commands/plan.md +17 -1
  17. package/config/agents.json +21 -3
  18. package/config/mcp.json +72 -0
  19. package/config/models.json +26 -16
  20. package/config/profiles.json +2 -4
  21. package/config/skills.json +210 -100
  22. package/docs/SKILLS.md +341 -245
  23. package/docs/designs/old/2026-10-31 plan-lifecycle-backlog-and-clean-code-skill.md +87 -0
  24. package/docs/designs/old/2026-11-02 skill-upstream-audit-and-update.md +105 -0
  25. package/docs/designs/old/2026-11-05 communication-doctrine-bluf-ste.md +94 -0
  26. package/docs/designs/old/2026-11-06-cloud-engineer-and-resilience-synthesis.md +67 -0
  27. package/docs/designs/old/2026-11-06-herdr-native-agent-orchestration.md +45 -0
  28. package/docs/runs/skill-audit/add_progressive_disclosure.cjs +30 -0
  29. package/docs/runs/skill-audit/check_heimdall_skills.ps1 +9 -0
  30. package/docs/runs/skill-audit/compare_classics.ps1 +26 -0
  31. package/docs/runs/skill-audit/compare_taste.ps1 +12 -0
  32. package/docs/runs/skill-audit/customization-report.json +380 -0
  33. package/docs/runs/skill-audit/diff_pending_skills.cjs +94 -0
  34. package/docs/runs/skill-audit/fetch_and_apply_skill.cjs +58 -0
  35. package/docs/runs/skill-audit/fetch_and_apply_taste_v2.cjs +65 -0
  36. package/docs/runs/skill-audit/inspect_pending_skills.cjs +71 -0
  37. package/docs/runs/skill-audit/inventory.json +308 -0
  38. package/docs/runs/skill-audit/list_local_taste.ps1 +1 -0
  39. package/docs/runs/skill-audit/phase5-update-plan.json +595 -0
  40. package/docs/runs/skill-audit/phase5-update-plan.md +138 -0
  41. package/docs/runs/skill-audit/probe.ps1 +16 -0
  42. package/docs/runs/skill-audit/probe_classics_branches.ps1 +3 -0
  43. package/docs/runs/skill-audit/probe_commits.ps1 +15 -0
  44. package/docs/runs/skill-audit/probe_repos.ps1 +17 -0
  45. package/docs/runs/skill-audit/probe_sentry_sec.ps1 +3 -0
  46. package/docs/runs/skill-audit/probe_sentry_sweep.ps1 +5 -0
  47. package/docs/runs/skill-audit/probe_snyk.ps1 +3 -0
  48. package/docs/runs/skill-audit/probe_snyk_recipes.ps1 +5 -0
  49. package/docs/runs/skill-audit/probe_taste_branches.ps1 +8 -0
  50. package/docs/runs/skill-audit/probe_taste_v19.ps1 +3 -0
  51. package/docs/runs/skill-audit/probe_user_repos.ps1 +19 -0
  52. package/docs/runs/skill-audit/prune_taste_skills.cjs +22 -0
  53. package/docs/runs/skill-audit/run_phase1_2.cjs +142 -0
  54. package/docs/runs/skill-audit/run_phase6_verification.cjs +107 -0
  55. package/docs/runs/skill-audit/show_16_details.ps1 +25 -0
  56. package/docs/runs/skill-audit/show_20_skills.ps1 +28 -0
  57. package/docs/runs/skill-audit/show_classics_diff.cjs +37 -0
  58. package/docs/runs/skill-audit/sync_agent_markdowns.cjs +30 -0
  59. package/docs/runs/skill-audit/taste-skill-upstream.md +542 -0
  60. package/docs/runs/skill-audit/update-manifest.md +88 -0
  61. package/docs/runs/skill-audit/update_config_skills.cjs +52 -0
  62. package/docs/runs/skill-audit/update_registry_phase7.cjs +83 -0
  63. package/docs/runs/skill-audit/upstream-status.json +563 -0
  64. package/docs/runs/skill-audit/verification-results.json +252 -0
  65. package/doctrine/AGENTS.md +39 -77
  66. package/hooks/git/pre-commit +11 -0
  67. package/hooks/heimdall-hook.cjs +81 -2
  68. package/hooks/herdr-agent-state.ps1 +55 -0
  69. package/hooks/hooks.json +0 -11
  70. package/lib/catalog-sync.cjs +162 -0
  71. package/lib/hermes-context.cjs +57 -0
  72. package/lib/model-context.cjs +123 -0
  73. package/lib/path-discovery.cjs +94 -0
  74. package/package.json +7 -3
  75. package/playbooks/01-interactive-grilling-gate.md +14 -1
  76. package/playbooks/02-fast-code-deep-verification.md +3 -2
  77. package/playbooks/03-adversarial-code-review.md +3 -3
  78. package/playbooks/05-canonical-plan-template.md +32 -18
  79. package/playbooks/06-model-registry-matrix.md +24 -13
  80. package/playbooks/07-legacy-code-modernization.md +74 -0
  81. package/playbooks/08-backlog-and-change-request-flow.md +122 -0
  82. package/setup.mjs +592 -172
  83. package/skills/antislop/SKILL.md +76 -56
  84. package/skills/antislop/VERSION +1 -0
  85. package/skills/antislop-copywriting/SKILL.md +372 -372
  86. package/skills/antislop-human/LICENSE-web-quality-skills +21 -0
  87. package/skills/antislop-human/SKILL.md +204 -147
  88. package/skills/antislop-human/contrast-check.py +168 -165
  89. package/skills/antislop-human/contrast-mcp.py +6 -3
  90. package/skills/antislop-human/references/A11Y-PATTERNS.md +249 -0
  91. package/skills/antislop-human/references/WCAG.md +127 -0
  92. package/skills/antislop-ui/LICENSE-web-quality-skills +21 -0
  93. package/skills/antislop-ui/SKILL.md +344 -304
  94. package/skills/antislop-ui/references/CORE-WEB-VITALS.md +181 -0
  95. package/skills/antislop-ui/references/WEB-BASELINE.md +28 -0
  96. package/skills/brainstorming/SKILL.md +274 -265
  97. package/skills/brainstorming/builder-check-prompt.md +23 -0
  98. package/skills/brainstorming/scripts/frame-template.html +213 -213
  99. package/skills/brainstorming/scripts/server.cjs +723 -723
  100. package/skills/brandkit/SKILL.md +798 -798
  101. package/skills/brutalist-skill/SKILL.md +93 -92
  102. package/skills/caveman/README.md +68 -0
  103. package/skills/caveman/SKILL.md +73 -38
  104. package/skills/claude-collaborator/SKILL.md +24 -44
  105. package/skills/clean-code/SKILL.md +152 -0
  106. package/skills/cloudflare-security-audit/AI-AND-LLM.md +83 -83
  107. package/skills/cloudflare-security-audit/ATTACK-CLASSES.md +130 -130
  108. package/skills/cloudflare-security-audit/CLIENT-SIDE.md +83 -83
  109. package/skills/cloudflare-security-audit/CLOUD-AND-DEPLOYMENT.md +86 -86
  110. package/skills/cloudflare-security-audit/DATA-ISOLATION-AND-LIFECYCLE.md +84 -84
  111. package/skills/cloudflare-security-audit/DESKTOP-MOBILE-AND-LOCAL-IPC.md +89 -89
  112. package/skills/cloudflare-security-audit/HUNTING.md +251 -251
  113. package/skills/cloudflare-security-audit/MEMORY-SAFETY-AND-BINARY.md +101 -101
  114. package/skills/cloudflare-security-audit/PROTOCOLS-RPC-AND-MESSAGING.md +81 -81
  115. package/skills/cloudflare-security-audit/RECONNAISSANCE.md +156 -156
  116. package/skills/cloudflare-security-audit/RESOURCE-EXHAUSTION-AND-AVAILABILITY.md +78 -78
  117. package/skills/cloudflare-security-audit/SKILL.md +192 -192
  118. package/skills/cloudflare-security-audit/SUPPLY-CHAIN-AND-RELEASE.md +73 -73
  119. package/skills/cloudflare-security-audit/VALIDATION-AND-REPORTING.md +186 -186
  120. package/skills/cloudflare-security-audit/WEB-PROTOCOL-AND-AUTH.md +105 -105
  121. package/skills/cloudflare-security-audit/report-schema.json +461 -461
  122. package/skills/cloudflare-security-audit/validate-coverage-ledger.cjs +872 -872
  123. package/skills/cloudflare-security-audit/validate-coverage-ledger.test.cjs +740 -740
  124. package/skills/cloudflare-security-audit/validate-findings.cjs +773 -773
  125. package/skills/cloudflare-security-audit/validate-findings.test.cjs +652 -652
  126. package/skills/codex-collaborator/SKILL.md +24 -45
  127. package/skills/communication-doctrine/SKILL.md +89 -0
  128. package/skills/diagnosing-superpowers/SKILL.md +1 -1
  129. package/skills/diagnosing-superpowers/references/github-issues.md +3 -3
  130. package/skills/diagnosing-superpowers/templates/issue.md +23 -4
  131. package/skills/executing-plans/SKILL.md +0 -52
  132. package/skills/executing-plans/scripts/task-done +52 -52
  133. package/skills/executing-plans/scripts/task-start +28 -28
  134. package/skills/gemini-collaborator/SKILL.md +24 -56
  135. package/skills/herdr/SKILL.md +243 -0
  136. package/skills/image-to-code-skill/SKILL.md +1228 -1228
  137. package/skills/imagegen-frontend-mobile/SKILL.md +1465 -1465
  138. package/skills/imagegen-frontend-web/SKILL.md +987 -987
  139. package/skills/karpathy-guidelines/SKILL.md +67 -67
  140. package/skills/mcp-engineering/SKILL.md +74 -0
  141. package/skills/minimalist-skill/SKILL.md +87 -85
  142. package/skills/output-skill/SKILL.md +49 -49
  143. package/skills/ponytail/SKILL.md +36 -52
  144. package/skills/postgres-best-practices/SKILL.md +30 -52
  145. package/skills/postgres-best-practices/references/backup-restore.md +372 -0
  146. package/skills/postgres-best-practices/references/bulk-loading.md +315 -0
  147. package/skills/postgres-best-practices/references/connection-pooling.md +310 -0
  148. package/skills/postgres-best-practices/references/hot-standby.md +221 -0
  149. package/skills/postgres-best-practices/references/indexing.md +318 -0
  150. package/skills/postgres-best-practices/references/logical-replication.md +610 -0
  151. package/skills/postgres-best-practices/references/major-version-upgrades.md +334 -0
  152. package/skills/postgres-best-practices/references/performance-diagnostics.md +553 -0
  153. package/skills/postgres-best-practices/references/query-optimization.md +294 -0
  154. package/skills/postgres-best-practices/references/query-patterns.md +566 -0
  155. package/skills/postgres-best-practices/references/schema-design.md +362 -0
  156. package/skills/postgres-best-practices/references/security-roles.md +489 -0
  157. package/skills/postgres-best-practices/references/transaction-isolation.md +344 -0
  158. package/skills/progressive-disclosure/SKILL.md +68 -0
  159. package/skills/pstack-discipline/SKILL.md +40 -0
  160. package/skills/receiving-code-review/SKILL.md +2 -23
  161. package/skills/requesting-code-review/SKILL.md +7 -36
  162. package/skills/soft-skill/SKILL.md +99 -98
  163. package/skills/stitch-skill/DESIGN.md +121 -121
  164. package/skills/stitch-skill/SKILL.md +185 -184
  165. package/skills/strix-security/SKILL.md +54 -53
  166. package/skills/subagent-driven-development/SKILL.md +28 -260
  167. package/skills/subagent-driven-development/references/batching.md +11 -0
  168. package/skills/subagent-driven-development/references/cannot-verify.md +10 -0
  169. package/skills/subagent-driven-development/references/final-review.md +47 -0
  170. package/skills/subagent-driven-development/references/fix-loop.md +77 -0
  171. package/skills/subagent-driven-development/references/handling-reports.md +15 -0
  172. package/skills/subagent-driven-development/references/preflight.md +26 -0
  173. package/skills/subagent-driven-development/references/resuming.md +12 -0
  174. package/skills/subagent-driven-development/scripts/review-package +53 -53
  175. package/skills/subagent-driven-development/scripts/sdd-workspace +87 -82
  176. package/skills/subagent-driven-development/scripts/task-brief +43 -43
  177. package/skills/systematic-debugging/SKILL.md +283 -306
  178. package/skills/taste-skill/SKILL.md +542 -1206
  179. package/skills/taste-skill/references/app-screens.md +1199 -0
  180. package/skills/taste-skill/references/colour.md +141 -0
  181. package/skills/taste-skill/references/copy.md +177 -0
  182. package/skills/taste-skill/references/critique.md +182 -0
  183. package/skills/taste-skill/references/imagery.md +791 -0
  184. package/skills/taste-skill/references/layout.md +292 -0
  185. package/skills/taste-skill/references/motion.md +980 -0
  186. package/skills/taste-skill/references/research.md +356 -0
  187. package/skills/taste-skill/references/scenes.md +174 -0
  188. package/skills/taste-skill/references/tells.md +115 -0
  189. package/skills/taste-skill/references/type.md +170 -0
  190. package/skills/test-driven-development/SKILL.md +330 -337
  191. package/skills/thermo/SKILL.md +67 -0
  192. package/skills/threat-modeling/SKILL.md +55 -0
  193. package/skills/trailofbits-audit-context/SKILL.md +72 -72
  194. package/skills/trailofbits-insecure-defaults/commands/audit.md +35 -0
  195. package/skills/trailofbits-insecure-defaults/references/debug-features.json +13 -13
  196. package/skills/trailofbits-insecure-defaults/references/debug-features.md +75 -75
  197. package/skills/trailofbits-insecure-defaults/references/default-credentials.json +12 -12
  198. package/skills/trailofbits-insecure-defaults/references/default-credentials.md +76 -76
  199. package/skills/trailofbits-insecure-defaults/references/fail-open-security.json +11 -11
  200. package/skills/trailofbits-insecure-defaults/references/fail-open-security.md +70 -70
  201. package/skills/trailofbits-insecure-defaults/references/fallback-secrets.json +11 -11
  202. package/skills/trailofbits-insecure-defaults/references/fallback-secrets.md +70 -70
  203. package/skills/trailofbits-insecure-defaults/references/permissive-access.json +13 -13
  204. package/skills/trailofbits-insecure-defaults/references/permissive-access.md +62 -62
  205. package/skills/trailofbits-insecure-defaults/references/weak-crypto.json +13 -13
  206. package/skills/trailofbits-insecure-defaults/references/weak-crypto.md +71 -71
  207. package/skills/trailofbits-triage-brocards/SKILL.md +208 -208
  208. package/skills/verification-before-completion/SKILL.md +0 -14
  209. package/skills/writing-plans/SKILL.md +11 -15
  210. package/skills/writing-skills/SKILL.md +21 -303
  211. package/skills/writing-skills/references/CLAUDE_MD_TESTING.md +189 -0
  212. package/skills/writing-skills/references/anthropic-best-practices.md +1150 -0
  213. package/skills/writing-skills/references/bulletproofing.md +80 -0
  214. package/skills/writing-skills/references/discovery.md +201 -0
  215. package/skills/writing-skills/references/flowcharts.md +37 -0
  216. package/skills/writing-skills/references/graphviz-conventions.dot +172 -0
  217. package/skills/writing-skills/references/persuasion-principles.md +187 -0
  218. package/skills/writing-skills/references/testing-skills-with-subagents.md +384 -0
  219. package/tools/{claude-bridge.ps1 → archive/claude-bridge.ps1} +10 -7
  220. package/tools/{codex-bridge.ps1 → archive/codex-bridge.ps1} +1 -1
  221. package/tools/{gemini-bridge.ps1 → archive/gemini-bridge.ps1} +12 -19
  222. package/skills/gpt-tasteskill/SKILL.md +0 -74
  223. package/skills/taste-skill-v1/SKILL.md +0 -226
  224. /package/tools/{claude-bridge.cmd → archive/claude-bridge.cmd} +0 -0
  225. /package/tools/{claude-bridge.sh → archive/claude-bridge.sh} +0 -0
  226. /package/tools/{codex-bridge.cmd → archive/codex-bridge.cmd} +0 -0
  227. /package/tools/{codex-bridge.sh → archive/codex-bridge.sh} +0 -0
  228. /package/tools/{codexcli-bridge.cmd → archive/codexcli-bridge.cmd} +0 -0
  229. /package/tools/{codexcli-bridge.ps1 → archive/codexcli-bridge.ps1} +0 -0
  230. /package/tools/{gemini-bridge.cmd → archive/gemini-bridge.cmd} +0 -0
  231. /package/tools/{gemini-bridge.sh → archive/gemini-bridge.sh} +0 -0
@@ -0,0 +1,87 @@
1
+ # Plan: Standardized Plan Lifecycle, Backlog Governance & Clean-Code Skill
2
+
3
+ ## 1. Active Skills & Directives Checklist
4
+ - [x] `brainstorming` — Alternative 1 agreed: native markdown ledger, standardized plan pathing & archive, zero-dependency `clean-code` (`ub-mode`) skill
5
+ - [x] `karpathy-guidelines` — Surgical updates to playbooks, doctrine, and skill registries; no unnecessary bloat
6
+ - [x] `antislop` — Direct, clear technical phrasing with zero conversational fluff
7
+ - [x] `writing-plans` — Adhering to the canonical 7-section planning structure
8
+
9
+ ## 2. Context & Design Read (Governance & Architecture)
10
+ - **Domain**: Engineering governance, plan lifecycle, backlog tracking, and software design quality standard.
11
+ - **Surface**: Markdown playbooks, cross-agent doctrine, central backlog ledger, and skill module.
12
+ - **Invariant Rules**:
13
+ - All future plans must be authored in `docs/designs/YYYY-MM-DD <plan-name>.md`.
14
+ - When verified and completed, plans must be archived into `docs/designs/old/`.
15
+ - Backlog tracking follows 4 explicit flows: Bugfixes (fast-path), New Features (backlog intake), Change Request (CR) Analysis (evaluation & decision gate), and Rejection handling.
16
+ - `clean-code` (`ub-mode`) ingested as a zero-dependency skill distilling Uncle Bob's TDD, laziness protocol, boundary discipline, and behavior-over-implementation rules.
17
+
18
+ ## 3. Multi-Agent Orchestration & Model Allocation Matrix
19
+ | Task ID | Phase & Task Description | Assigned Model | Effort Level | Selection Rationale | Cross-Reviewer & Tool Command |
20
+ | :--- | :--- | :--- | :--- | :--- | :--- |
21
+ | T1 | Phase 1: Plan Lifecycle & Doctrine Update | claude-sonnet-5 | high | Exact phrasing in AGENTS.md, Playbook 05, and writing-plans | Gemini 3.8 Flash (`powershell -File C:/Apps/tools/gemini-bridge.ps1 review -Model "Gemini 3.8 Flash"`) |
22
+ | T2 | Phase 2: Backlog & CR Flow Playbook + Ledger | claude-sonnet-5 | high | Codify 4 lifecycle flows in Playbook 08 & create docs/backlog.md | Gemini 3.8 Flash (`powershell -File C:/Apps/tools/gemini-bridge.ps1 review -Model "Gemini 3.8 Flash"`) |
23
+ | T3 | Phase 3: Clean-Code (`ub-mode`) Skill Authoring | claude-sonnet-5 | high | Author skills/clean-code/SKILL.md (with optional companion tools contract) & register in config/skills.json | Gemini 3.8 Flash (`powershell -File C:/Apps/tools/gemini-bridge.ps1 review -Model "Gemini 3.8 Flash"`) |
24
+ | T4 | Phase 4: Documentation Updates (README & SKILLS.md) | claude-sonnet-5 | medium | Update README.md, README.pt-BR.md, and docs/SKILLS.md with 52 skills, new playbook 08, plan lifecycle, and backlog flows | Gemini 3.8 Flash (`powershell -File C:/Apps/tools/gemini-bridge.ps1 review -Model "Gemini 3.8 Flash"`) |
25
+ | T5 | Phase 5: Sync & Ecosystem Verification | claude-sonnet-5 | medium | Run `node setup.mjs --link` to deploy to all tool harnesses and verify audit | Codex (`powershell -File C:/Apps/tools/codex-bridge.ps1 review -Model "gpt-6-astra"`) |
26
+
27
+ ## 4. Multi-Phase Implementation Plan
28
+
29
+ ### Phase 1: Plan Storage, Naming & Archiving Standards
30
+ - **File updates**:
31
+ - [`playbooks/05-canonical-plan-template.md`](file:///C:/Apps/heimdall-agent/playbooks/05-canonical-plan-template.md): Mandate plan file path format (`docs/designs/YYYY-MM-DD <plan-name>.md`) and completion archive step (move to `docs/designs/old/`).
32
+ - [`skills/writing-plans/SKILL.md`](file:///C:/Apps/heimdall-agent/skills/writing-plans/SKILL.md): Update trigger instructions and target output locations to enforce `docs/designs/` and archiving.
33
+ - [`doctrine/AGENTS.md`](file:///C:/Apps/heimdall-agent/doctrine/AGENTS.md): Update `<planning_protocol>` Turn 2 to explicitly cite the storage and archive requirement.
34
+
35
+ ### Phase 2: Backlog Management & Change Request (CR) Governance
36
+ - **New Playbook**:
37
+ - Create [`playbooks/08-backlog-and-change-request-flow.md`](file:///C:/Apps/heimdall-agent/playbooks/08-backlog-and-change-request-flow.md).
38
+ - Codify the 4 explicit lifecycle paths:
39
+ 1. **Bugfixes (Fast Path)**: Report received -> Assess/Plan fix -> Implement with failing test first -> Test & verify -> Mark complete.
40
+ 2. **New Features (Intake)**: Log directly into backlog with context, motivation, and priority.
41
+ 3. **Change Request (CR) Analysis Gate**: Evaluate selected backlog items against architecture, blast radius, and dependencies. If approved -> generate formal Plan in `docs/designs/` -> implement -> verify -> archive plan.
42
+ 4. **Rejection Route**: If rejected during CR analysis, move back to backlog with explicit rejection rationale or delete.
43
+ - **Initial Ledger**:
44
+ - Create [`docs/backlog.md`](file:///C:/Apps/heimdall-agent/docs/backlog.md) seeded with the standard schema and initial Heimdall roadmap items.
45
+
46
+ ### Phase 3: Clean-Code (`ub-mode`) Skill Ingestion
47
+ - **New Skill**:
48
+ - Create [`skills/clean-code/SKILL.md`](file:///C:/Apps/heimdall-agent/skills/clean-code/SKILL.md) with aliases (`clean-code`, `ub-mode`).
49
+ - Incorporate Uncle Bob's core engineering tenets:
50
+ - *First, Make it Work*: Laziness protocol (smallest edit that solves problem), Redesign from first principles, Subtract before adding, Illegal states unrepresentable, Idempotent operations.
51
+ - *Then, Make it Right*: Root-cause fixes over band-aids, Testing behavior rather than implementation, Mathematical complexity bounds (CRAP < 10, DRY similarity < 0.8, Mutation testing awareness).
52
+ - *Companion Tools Contract*: Explicitly define how companion CLI tools (`unclebob/crapper`, `unclebob/dryer`, `unclebob/mutator`) are leveraged: if installed on `PATH`, the agent runs them as deterministic exit-code gates; if absent, the agent statically enforces the identical thresholds and rules.
53
+ - *Practice*: Guard context window, small atomic commits.
54
+ - **Registry Update**:
55
+ - Register `clean-code` in [`config/skills.json`](file:///C:/Apps/heimdall-agent/config/skills.json) under the `full` profile and tag it with `clean-code`, `ub-mode`, `tdd`, `refactoring`.
56
+
57
+ ### Phase 4: Documentation Updates (README & Docs)
58
+ - **Files to update**:
59
+ - [`README.md`](file:///C:/Apps/heimdall-agent/README.md):
60
+ - Update skill badges and counts (from 51 to 52).
61
+ - Add Playbook 08 (`08-backlog-and-change-request-flow.md`) to the Playbook registry.
62
+ - Document the standardized plan directory conventions (`docs/designs/` -> `docs/designs/old/`).
63
+ - Document the 4-stage Backlog and Change Request flows.
64
+ - Add `clean-code` (`ub-mode`) to the Curated Toolkits section.
65
+ - [`README.pt-BR.md`](file:///C:/Apps/heimdall-agent/README.pt-BR.md):
66
+ - Apply identical updates in Brazilian Portuguese.
67
+ - [`docs/SKILLS.md`](file:///C:/Apps/heimdall-agent/docs/SKILLS.md):
68
+ - Document the new `clean-code` skill, its frontmatter, triggers, and companion tool contracts.
69
+
70
+ ### Phase 5: Sync, Verification & Symlink Deployment
71
+ - Run `node setup.mjs --link` to deploy junctions to `~/.gemini`, `~/.claude`, and `~/.codex`.
72
+ - Run `node setup.mjs audit` to confirm 52 skills and full junction synchronization.
73
+ - Move this completed plan to `docs/designs/old/` upon final confirmation to validate the lifecycle end-to-end.
74
+
75
+ ## 5. Symmetric & Tri-Directional Cross-Model Validation Loop
76
+ - Tasks executed by current runner -> validated with Gemini or Codex review bridges:
77
+ - `powershell -File C:/Apps/tools/gemini-bridge.ps1 review -Model "Gemini 3.8 Flash" -Effort "high"`
78
+ - `powershell -File C:/Apps/tools/codex-bridge.ps1 review -Model "gpt-6-astra" -Effort "high"`
79
+
80
+ ## 6. Orchestrator Heartbeat
81
+ - Cadence: Monitored at phase completions.
82
+ - Task status logged in run summaries.
83
+
84
+ ## 7. Verification Harness
85
+ - **Schema & Link Verification**: Ensure all internal Markdown links in `playbooks/`, `doctrine/`, and `skills/` resolve to valid paths.
86
+ - **Setup & Audit Script**: Run `node setup.mjs audit` and verify that the 52nd skill (`clean-code`) is recognized and linked across all active harnesses without error.
87
+ - **Git Worktree Cleanliness**: Check `git status` to ensure only the intended surgical files are modified or added.
@@ -0,0 +1,105 @@
1
+ # Plan: Skill Upstream Audit & Sequential Update Pipeline
2
+
3
+ ## 1. Active Skills & Directives Checklist
4
+ - [x] `brainstorming` — Intent discovered (full inventory scan + upstream sync), assumptions surfaced (local customizations exist, breaking changes possible)
5
+ - [x] `karpathy-guidelines` — Surgical audit scope, no speculative refactors, minimal update surface per skill
6
+ - [x] `antislop` — Clean diff reports, no boilerplate commentary in update manifests
7
+ - [x] `verification-before-completion` — Post-update behavioral test required before sign-off
8
+ - [x] `clean-code` (`ub-mode`) — Quality gates applied to any locally-patched skill merges
9
+
10
+ ## 2. Context & Design Read
11
+ - **Design Read**: N/A (infrastructure/tooling task, no UI surface)
12
+ - **Design System Tokens**: N/A
13
+ - **Anti-Default Discipline**: No automated blind overwrites; every divergence flagged for human review
14
+
15
+ ## 3. Multi-Agent Orchestration & Model Allocation Matrix
16
+ | Task ID | Phase & Task Description | Assigned Model | Effort Level | Selection Rationale | Cross-Reviewer & Tool Command |
17
+ | :--- | :--- | :--- | :--- | :--- | :--- |
18
+ | T1 | Phase 1: Inventory extraction & upstream URL normalization from `config/skills.json` | claude-sonnet-5 | medium | Structured JSON parsing, deterministic output | Gemini 3.8 Flash (`gemini-bridge.ps1 review -Model "gemini-3.8-flash-medium"`) |
19
+ | T2 | Phase 2: Sequential upstream GitHub API polling (latest commit/tag vs. `sourceRevision`) | claude-sonnet-5 | medium | HTTP API calls, rate-limit aware, serial execution | Gemini 3.8 Flash (`gemini-bridge.ps1 review -Model "gemini-3.8-flash-medium"`) |
20
+ | T3 | Phase 3: Local customization detection (git diff of each skill dir against last known clean revision) | claude-sonnet-5 | high | Diff analysis, semantic patch classification | Claude Opus 5.5 (`claude-bridge.ps1 review -Model "claude-opus-5-5" -Effort "high"`) |
21
+ | T4 | Phase 4: Divergence report generation (categorized: clean-update / local-patch / breaking-change) | claude-sonnet-5 | medium | Structured markdown manifest | Gemini 3.8 Flash (`gemini-bridge.ps1 review -Model "gemini-3.8-flash-medium"`) |
22
+ | T5 | Phase 5a: Apply approved clean updates (one skill at a time, individual commits) | claude-sonnet-5 | high | File writes, frontmatter validation | Gemini 3.8 Flash (`gemini-bridge.ps1 review -Model "gemini-3.8-flash-high"`) |
23
+ | T5b | Phase 5b: Flagged manual-review items — present diff + upstream changelog, await human decision | claude-opus-5-5 | high | Deep context synthesis for merge recommendations | Human gate (no auto-apply) |
24
+ | T6 | Phase 6: Post-update verification harness (invoke each updated skill against canonical test prompt) | claude-sonnet-5 | high | Behavioral regression detection | Codex (`codex-bridge.ps1 review -Model "gpt-6-astra" -Effort "high"`) |
25
+ | T7 | Phase 7: Update `config/skills.json` sourceRevision fields & archive plan | claude-sonnet-5 | medium | Registry consistency | Gemini 3.8 Flash (`gemini-bridge.ps1 review -Model "gemini-3.8-flash-medium"`) |
26
+
27
+ ## 4. Multi-Phase Implementation Plan
28
+
29
+ ### Phase 1: Inventory Extraction & Normalization
30
+ - Parse `config/skills.json` → extract all 52 modules with their `upstream` URLs and current `sourceRevision`.
31
+ - Normalize GitHub URLs to API endpoints (`/repos/{owner}/{repo}/commits?per_page=1` or `/releases/latest`).
32
+ - Output: `docs/runs/skill-audit/inventory.json` (structured manifest).
33
+ - **Gate**: Validate inventory count matches 52 modules before proceeding.
34
+
35
+ ### Phase 2: Sequential Upstream Polling
36
+ - For each skill in inventory, query GitHub API for latest commit SHA or release tag.
37
+ - Respect rate limits: 1-second delay between requests; use conditional requests (`If-None-Match`) where possible.
38
+ - Record: `{ skill, currentRevision, latestRevision, hasUpdate, latestCommitDate, latestCommitMessage }`.
39
+ - Output: `docs/runs/skill-audit/upstream-status.json`.
40
+ - **Gate**: All 52 entries populated; any API failures logged with retry count.
41
+
42
+ ### Phase 3: Local Customization Detection
43
+ - For each skill with `hasUpdate: true`, run `git log --oneline <skill-dir>` since last known clean revision.
44
+ - Classify local changes:
45
+ - **Clean**: No local commits touching skill files since installation.
46
+ - **Patched**: Local commits exist but are additive (new references, tuned triggers).
47
+ - **Divergent**: Local commits modify core instructions or remove upstream content.
48
+ - Output: `docs/runs/skill-audit/customization-report.json`.
49
+ - **Gate**: Every updated skill categorized; divergent items flagged for T5b.
50
+
51
+ ### Phase 4: Divergence Report & Human Approval Manifest
52
+ - Generate `docs/runs/skill-audit/update-manifest.md` with three sections:
53
+ 1. **Auto-Approve Queue**: Clean updates, no breaking changes detected.
54
+ 2. **Manual Review Queue**: Patched or divergent skills, with side-by-side diff summary.
55
+ 3. **Breaking Change Alerts**: Upstream removed aliases, changed trigger phrases, or altered tool dependencies.
56
+ - Present manifest to user for explicit approval of Auto-Approve queue and disposition of Manual Review items.
57
+ - **Gate**: User sign-off on manifest before any file writes.
58
+
59
+ ### Phase 5: Sequential Application (Approved Updates Only)
60
+ - **T5a (Auto-Approve)**: For each approved skill:
61
+ 1. Fetch upstream SKILL.md and reference files at `latestRevision`.
62
+ 2. Write to local skill directory.
63
+ 3. Validate frontmatter (name, triggers, description present).
64
+ 4. Git commit: `chore(skills): update {skill-name} to {latestRevision}`.
65
+ - **T5b (Manual Review)**: For each flagged item:
66
+ 1. Present upstream diff + local patch summary + merge recommendation.
67
+ 2. Await human decision: accept-upstream / keep-local / manual-merge.
68
+ 3. Apply decision, commit with descriptive message referencing human approval.
69
+ - **Gate**: Each skill committed individually; no batch commits.
70
+
71
+ ### Phase 6: Post-Update Verification Harness
72
+ - For each updated skill, invoke against a canonical test prompt that exercises its primary trigger and core behavior.
73
+ - Capture: skill loaded successfully, expected instructions present in context, no parse errors.
74
+ - Record pass/fail per skill in `docs/runs/skill-audit/verification-results.json`.
75
+ - **Failure protocol**: Revert the failing skill's commit, flag for re-review, do NOT proceed until resolved.
76
+ - **Gate**: 100% pass rate on updated skills before registry update.
77
+
78
+ ### Phase 7: Registry Update & Plan Archival
79
+ - Update `config/skills.json` `sourceRevision` fields for all successfully verified skills.
80
+ - Validate JSON schema integrity.
81
+ - Git commit: `chore(config): update skill sourceRevisions after upstream audit`.
82
+ - Move this plan to `docs/designs/old/2026-11-02 skill-upstream-audit-and-update.md`.
83
+ - **Gate**: Plan archived only after all phases complete and verification passes.
84
+
85
+ ## 5. Symmetric & Tri-Directional Cross-Model Validation Loop
86
+ - **T1, T2, T4, T7** (Claude Sonnet 5 execution) → Validate with Gemini 3.8 Flash:
87
+ `powershell -File C:/Apps/tools/gemini-bridge.ps1 review -Model "gemini-3.8-flash-medium"`
88
+ - **T3** (Claude Sonnet 5 diff analysis) → Validate with Claude Opus 5.5:
89
+ `powershell -File C:/Apps/tools/claude-bridge.ps1 review -Model "claude-opus-5-5" -Effort "high"`
90
+ - **T5a, T5b** (Claude Sonnet 5 file writes) → Validate with Gemini 3.8 Flash:
91
+ `powershell -File C:/Apps/tools/gemini-bridge.ps1 review -Model "gemini-3.8-flash-high"`
92
+ - **T6** (Claude Sonnet 5 verification) → Validate with Codex GPT-6 Astra:
93
+ `powershell -File C:/Apps/tools/codex-bridge.ps1 review -Model "gpt-6-astra" -Effort "high"`
94
+
95
+ ## 6. Orchestrator Heartbeat
96
+ - Orchestrator monitors progress every 3 minutes during Phases 2–6.
97
+ - Rate-limit backoff: if GitHub API returns 429, pause 60 seconds and resume.
98
+ - Stuck detection: if any phase exceeds 15 minutes without progress, alert user and pause.
99
+
100
+ ## 7. Verification Harness
101
+ - **Strict Zero Dev-Server Policy**: No dev servers launched. Verification is non-interactive skill invocation against canonical prompts.
102
+ - **Behavioral Test Standard**: Each updated skill must load without error and produce expected instruction markers in agent context when triggered by its canonical alias.
103
+ - **Rejection of Pseudo-Verification**: File existence checks or frontmatter parsing alone are insufficient; actual skill invocation is required.
104
+ - **Rollback Protocol**: Any skill failing verification is reverted via `git revert <commit>` before proceeding.
105
+ - **Registry Consistency Check**: Final `config/skills.json` validated against JSON schema and cross-checked against git log of applied commits.
@@ -0,0 +1,94 @@
1
+ # Plan: Communication Doctrine Integration (BLUF & Simplified Technical English)
2
+
3
+ ## 1. Active Skills & Directives Checklist
4
+ - [x] `brainstorming` — Intent discovered, interactive grilling completed, Approach B selected
5
+ - [x] `karpathy-guidelines` — Minimal, surgical edits to existing doctrine, templates, and agent specs
6
+ - [x] `antislop` — Elimination of AI filler words, performative preambles, and vague qualifiers
7
+ - [ ] `taste-skill` — [N/A] Non-UI architectural and governance task
8
+
9
+ ## 2. Context & Design Read (Required for UI / Features)
10
+ - **Design Read**: Non-UI governance and agent infrastructure feature.
11
+ - **Specification**: Implementation of Approach B (Modular `communication-doctrine` Skill + Canonical Integration) across `heimdall-agent`.
12
+ - **Target Surfaces**:
13
+ - `skills/communication-doctrine/SKILL.md` (New modular skill)
14
+ - `doctrine/AGENTS.md` (Cross-agent doctrine update)
15
+ - `playbooks/05-canonical-plan-template.md` & `skills/writing-plans/SKILL.md` (Planning templates)
16
+ - `agents/reviewer.md` & `agents/code-sentinel.md` (Reviewer specs)
17
+ - `config/skills.json` & `docs/SKILLS.md` (Registry and documentation)
18
+ - `test/communication-doctrine.test.mjs` (Automated regression suite)
19
+
20
+ ## 3. Multi-Agent Orchestration & Model Allocation Matrix
21
+ | Task ID | Phase & Task Description | Assigned Model | Effort Level | Selection Rationale | Cross-Reviewer & Tool Command |
22
+ | :--- | :--- | :--- | :--- | :--- | :--- |
23
+ | T1 | Phase 1: Author Modular Skill (`communication-doctrine/SKILL.md`) | claude-sonnet-5 | high | High-precision technical writing & YAML frontmatter | Gemini 3.8 Flash (`gemini-bridge review`) |
24
+ | T2 | Phase 2: Core Doctrine & Template Integration (`doctrine/AGENTS.md`, `playbooks/05`, `writing-plans`) | claude-sonnet-5 | high | Surgical integration into universal doctrine & templates | Gemini 3.8 Flash (`gemini-bridge review`) |
25
+ | T3 | Phase 3: Agent Personas Integration (`reviewer.md`, `code-sentinel.md`) | claude-sonnet-5 | high | Reviewer verdict schemas and Goldfish reporting contracts | GPT-6 Astra (`codex-bridge review`) |
26
+ | T4 | Phase 4: Registry, Docs & Verification Suite (`config/skills.json`, `docs/SKILLS.md`, `test/*.test.mjs`) | claude-sonnet-5 | medium | JSON registry sync, markdown docs index, Node.js test authoring | Gemini 3.8 Flash (`gemini-bridge review`) |
27
+
28
+ ## 4. Multi-Phase Implementation Plan
29
+
30
+ ### Phase 1: Modular Communication Doctrine Skill
31
+ - [x] **Step 1.1**: Create `skills/communication-doctrine/SKILL.md` with YAML frontmatter:
32
+ - Name: `communication-doctrine`
33
+ - Description: "Bottom Line Up Front (BLUF) and Simplified Technical English (STE) communication doctrine for AI agents, implementation plans, code reviews, and subagent handoffs."
34
+ - [x] **Step 1.2**: Define **Macro Structure (BLUF Standard)**:
35
+ - Subagent Handoff Schema: Top 3 lines must contain Status (`SUCCESS | FAILURE | ESCALATED`), Blast Radius (files touched, tests run), and Artifact Location.
36
+ - Reviewer Verdict Schema: Line 1 must declare Verdict (`APPROVED | BLOCKED | REVISION_NEEDED`), followed by findings breakdown (Blockers, Warnings, Nits).
37
+ - Implementation Plan Header Schema: 1-sentence Goal, Scope, Key Risks, Human Step-up Triggers.
38
+ - [x] **Step 1.3**: Define **Micro Syntax (STE Principles & Banned Qualifiers)**:
39
+ - Rule 1: Imperative verb first for all action steps (`Run`, `Create`, `Modify`, `Assert`, `Verify`, `Delete`).
40
+ - Rule 2: Procedural sentences strictly $\le$ 20 words. Descriptive text $\le$ 25 words.
41
+ - Rule 3: Banned Vague Qualifiers list: `ensure`, `properly`, `appropriately`, `as needed`, `as appropriate`, `gracefully`, `robustly`, `seamlessly`, `etc.` Every instruction must state an observable, testable condition.
42
+ - Rule 4: No vague pronouns (`it`, `this`, `they`) without an explicit antecedent noun.
43
+
44
+ ### Phase 2: Core Doctrine & Planning Templates Integration
45
+ - [x] **Step 2.1**: Update `doctrine/AGENTS.md`:
46
+ - Under `<core_discipline>`, add rule: `COMMUNICATION DISCIPLINE (BLUF & STE)` requiring bottom-line-first handoffs and unambiguous, imperative procedural instructions.
47
+ - Under `<subagent_execution_contract>`, require child subagents to emit BLUF summaries at the start of their scratchpad reports.
48
+ - [x] **Step 2.2**: Update `playbooks/05-canonical-plan-template.md`:
49
+ - Update Section 4 instructions to mandate STE step granularity (imperative verbs, $\le$ 20 words per step, zero banned vague qualifiers).
50
+ - Add explicit plan header BLUF requirement.
51
+ - [x] **Step 2.3**: Update `skills/writing-plans/SKILL.md`:
52
+ - Under "Step Granularity", add the STE imperative rules and the banned qualifier lexicon.
53
+
54
+ ### Phase 3: Agent Personas Integration
55
+ - [x] **Step 3.1**: Update `agents/reviewer.md`:
56
+ - Add `skills: communication-doctrine` to frontmatter.
57
+ - In Tier 1 / Tier 2 Step 6, mandate the BLUF Review Verdict header on all review outputs before the detailed findings ledger.
58
+ - Require suggested fixes to follow STE imperative phrasing.
59
+ - [x] **Step 3.2**: Update `agents/code-sentinel.md`:
60
+ - Add `skills: communication-doctrine` to frontmatter.
61
+ - Mandate BLUF audit summary format on all security and hygiene sweeps.
62
+
63
+ ### Phase 4: Registry, Documentation & Automated Regression Suite
64
+ - [x] **Step 4.1**: Update `config/skills.json`:
65
+ - Register `communication-doctrine` under standalone toolkits.
66
+ - Increment `totalModules` to 51.
67
+ - [x] **Step 4.2**: Update `docs/SKILLS.md`:
68
+ - Add `communication-doctrine` entry under Standalone Power Toolkits with summary and usage instructions.
69
+ - [x] **Step 4.3**: Create `test/communication-doctrine.test.mjs`:
70
+ - Test 1: `skills/communication-doctrine/SKILL.md` exists and contains valid frontmatter with name and description.
71
+ - Test 2: `config/skills.json` lists `communication-doctrine` and has valid syntax.
72
+ - Test 3: `doctrine/AGENTS.md` contains the BLUF and STE communication directives.
73
+ - Test 4: `playbooks/05-canonical-plan-template.md` includes STE step constraints and banned qualifiers.
74
+ - [x] **Step 4.4**: Run `npm test` to verify all 5 test suites pass cleanly.
75
+
76
+ ## 5. Symmetric & Tri-Directional Cross-Model Validation Loop
77
+ - Tasks executed by Claude -> Validate with Gemini or Codex:
78
+ `powershell -File C:/Apps/tools/gemini-bridge.ps1 review -Model "Gemini 3.8 Flash" -Effort "high"`
79
+ `powershell -File C:/Apps/tools/codex-bridge.ps1 review -Model "gpt-6-astra" -Effort "high"`
80
+ - Tasks executed by Gemini -> Validate with Claude or Codex:
81
+ `powershell -File C:/Apps/tools/claude-bridge.ps1 review -Model "claude-sonnet-5" -Effort "high"`
82
+ `powershell -File C:/Apps/tools/codex-bridge.ps1 review -Model "gpt-6-astra" -Effort "high"`
83
+ - Tasks executed by Codex -> Validate with Claude or Gemini:
84
+ `powershell -File C:/Apps/tools/claude-bridge.ps1 review -Model "claude-sonnet-5" -Effort "high"`
85
+ `powershell -File C:/Apps/tools/gemini-bridge.ps1 review -Model "Gemini 3.8 Flash" -Effort "high"`
86
+
87
+ ## 6. Orchestrator Heartbeat
88
+ - Orchestrator monitors progress every 3 minutes.
89
+
90
+ ## 7. Verification Harness
91
+ - **Strict Zero Dev-Server Policy**: NEVER include steps to run or launch dev servers (`npm run dev`, `vite`, `next dev`, etc.). All agent verification must be non-interactive and terminating (`npm test`, `npm run build`, `vitest run`, `lint`, `typecheck`).
92
+ - **Terminating Test Suite**: `npm test` runs Node test runner across `test/*.test.mjs`. All tests must pass with exit code 0.
93
+ - **Syntax & Schema Verification**: Validate `config/skills.json` parses as valid JSON without trailing commas or syntax defects.
94
+ - **Rejection of Pseudo-Verification**: Changes are only marked complete when `npm test` succeeds and modified files are inspected against their git diff.
@@ -0,0 +1,67 @@
1
+ # Plan: Cloud Engineer Persona, Resilience Invariants, and MCP/Threat-Modeling Skills Synthesis
2
+
3
+ ## 1. Active Skills & Directives Checklist
4
+ - [x] `brainstorming` — Synthesized top-tier capabilities from VoltAgent, pruned 170+ redundant/sprawl agents.
5
+ - [x] `karpathy-guidelines` — Surgical additions only: 1 missing persona, 2 high-value skills, and targeted agent infusions.
6
+ - [x] `antislop` — Zero conversational filler, strict Gemini 3-Tier instruction standard across all prompts.
7
+ - [x] `communication-doctrine` — BLUF summaries, STE imperative steps (<=20 words), zero vague qualifiers.
8
+ - [x] `taste-skill` — [N/A] Non-visual backend/prompt architectural specification.
9
+
10
+ ## 2. Context & Design Read
11
+ - **Design Read**: Non-visual system architecture read for AI engineering agents, with strict adherence to the Gemini 3-Tier standard (*Persona*, *Chronological Rules*, *Unmistakable Guardrails*), multi-agent model matrix, and self-contained zero-sprawl repository integrity.
12
+ - **System Boundaries**: All agent personas declare `model: inherit` and canonical tool names. Skills adhere to standard `SKILL.md` frontmatter and register into `config/skills.json`.
13
+ - **Anti-Default Discipline**: Reject dumping 186 uncurated agent files; reject unadapted bash-only scripts; reject hallucinated model flags (`claude-sonnet-5-5`, `sonnet`).
14
+
15
+ ## 3. Multi-Agent Orchestration & Model Allocation Matrix
16
+ | Task ID | Phase & Task Description | Assigned Model | Effort Level | Selection Rationale | Cross-Reviewer & Tool Command |
17
+ | :--- | :--- | :--- | :--- | :--- | :--- |
18
+ | T1 | Phase 1: Create `agents/cloud-engineer.md` persona | claude-sonnet-5 | high | Infrastructure, Docker, K8s, Caddy/Nginx, and IaC domain precision | Gemini 3.8 Flash (`powershell -File C:/Apps/tools/gemini-bridge.ps1 review -Model "Gemini 3.8 Flash" -Effort "high"`) |
19
+ | T2 | Phase 2: Infuse Docs-Drift & Resilience into existing agents | claude-sonnet-5 | high | Surgical updates to `reviewer.md`, `code-sentinel.md`, `tester.md`, `database-architect.md` | Gemini 3.8 Flash (`powershell -File C:/Apps/tools/gemini-bridge.ps1 review -Model "Gemini 3.8 Flash" -Effort "high"`) |
20
+ | T3 | Phase 3: Create `skills/threat-modeling` & `skills/mcp-engineering` | claude-sonnet-5 | high | Modular skill authoring with structured checklists and zero AI slop | GPT-6 Astra (`powershell -File C:/Apps/tools/codex-bridge.ps1 review -Model "gpt-6-astra" -Effort "high"`) |
21
+ | T4 | Phase 4: Register skills in catalog & verify test suite | claude-sonnet-5 | medium | Update `config/skills.json`, profiles, and run terminating test suite | Gemini 3.8 Flash (`powershell -File C:/Apps/tools/gemini-bridge.ps1 review -Model "Gemini 3.8 Flash" -Effort "high"`) |
22
+
23
+ ## 4. Multi-Phase Implementation Plan
24
+
25
+ ### Phase 1: Architecture & Scaffolding
26
+ - Step 1.1: Create `agents/cloud-engineer.md` defining the infrastructure, container, reverse proxy, and IaC persona.
27
+ - Step 1.2: Structure `cloud-engineer.md` strictly into Gemini 3-Tier standard: Persona, Chronological Rules, and Unmistakable Guardrails.
28
+ - Step 1.3: Include cloud architecture checklists: Dockerfile optimization, multi-stage builds, Caddy/Nginx reverse proxying, and Terraform/IaC boundaries.
29
+ - Step 1.4: Set persona frontmatter to `model: inherit` and bind tools to `Read`, `Write`, `Edit`, `Bash`, `Glob`, `Grep`.
30
+
31
+ ### Phase 2: Core Implementation (Agent Infusions)
32
+ - Step 2.1: Update `agents/reviewer.md` to add Docs-Drift Guard enforcing review blockers when exported signatures change without documentation updates.
33
+ - Step 2.2: Update `agents/code-sentinel.md` to add surgical documentation-sync rules with a strict 40% file blast-radius cap.
34
+ - Step 2.3: Update `agents/tester.md` to mandate chaos and fault-injection invariants (timeout, retry backoff, network failure assertions).
35
+ - Step 2.4: Update `agents/database-architect.md` to include pgvector, HNSW indexing, chunking guidelines, and connection-pool exhaustion checks.
36
+
37
+ ### Phase 3: Modular Skills Scaffolding & Registration
38
+ - Step 3.1: Create `skills/threat-modeling/SKILL.md` covering STRIDE attack-surface mapping, boundary trust transitions, and IAM privilege reduction.
39
+ - Step 3.2: Create `skills/mcp-engineering/SKILL.md` covering JSON-RPC 2.0 schema validation, stdio/SSE transports, and tool error handling.
40
+ - Step 3.3: Register both skills into `config/skills.json` under their appropriate toolkits (`security` and `core-engineering`).
41
+ - Step 3.4: Synchronize skill counts across `config/profiles.json`, `docs/SKILLS.md`, `README.md`, and `README.pt-BR.md`.
42
+
43
+ ### Phase 4: Review, Verification & Handoff
44
+ - Step 4.1: Execute `npm test` to verify catalog count integrity and documentation invariants pass with zero failures.
45
+ - Step 4.2: Inspect git diff with context-blinded Goldfish criteria to confirm zero unintentional regressions in existing agents.
46
+ - Step 4.3: Move this design plan from `docs/designs/` to `docs/designs/old/` upon successful verification.
47
+
48
+ ## 5. Symmetric & Tri-Directional Cross-Model Validation Loop
49
+ - Tasks executed by Claude -> Validate with Gemini or Codex:
50
+ `powershell -File C:/Apps/tools/gemini-bridge.ps1 review -Model "Gemini 3.8 Flash" -Effort "high"`
51
+ `powershell -File C:/Apps/tools/codex-bridge.ps1 review -Model "gpt-6-astra" -Effort "high"`
52
+ - Tasks executed by Gemini -> Validate with Claude or Codex:
53
+ `powershell -File C:/Apps/tools/claude-bridge.ps1 review -Model "claude-sonnet-5" -Effort "high"`
54
+ `powershell -File C:/Apps/tools/codex-bridge.ps1 review -Model "gpt-6-astra" -Effort "high"`
55
+ - Tasks executed by Codex -> Validate with Claude or Gemini:
56
+ `powershell -File C:/Apps/tools/claude-bridge.ps1 review -Model "claude-sonnet-5" -Effort "high"`
57
+ `powershell -File C:/Apps/tools/gemini-bridge.ps1 review -Model "Gemini 3.8 Flash" -Effort "high"`
58
+
59
+ ## 6. Orchestrator Heartbeat
60
+ - Orchestrator monitors progress every 3 minutes.
61
+ - Evaluates test suite execution and validates zero dev-server processes are spawned.
62
+
63
+ ## 7. Verification Harness
64
+ - **Strict Zero Dev-Server Policy**: NEVER run development servers (`npm run dev`, `vite`, `next dev`).
65
+ - **Terminating Verification**: Execute `npm test` (`node --test test/*.test.mjs`). All tests must pass cleanly.
66
+ - **Catalog Integrity Sentinel**: `test/catalog.test.mjs` must assert zero drift across `skills.json`, `profiles.json`, `SKILLS.md`, `README.md`, and `README.pt-BR.md`.
67
+ - **Formatting Invariants**: Verify all modified markdown files follow standard YAML frontmatter and proper link references.
@@ -0,0 +1,45 @@
1
+ # Design Record: Native Herdr Multi-Agent Orchestration & Performance Synthesis
2
+
3
+ **Date:** 2026-11-06
4
+ **Status:** IMPLEMENTED & VERIFIED
5
+ **Author:** Antigravity Orchestrator
6
+ **Upstream Integration:** Herdr CLI (`herdr.exe` v0.9.5+)
7
+
8
+ ---
9
+
10
+ ## 1. Executive Summary & BLUF
11
+
12
+ Historically, Heimdall relied on custom PowerShell bridge scripts (`claude-bridge.ps1`, `codex-bridge.ps1`, `gemini-bridge.ps1`) to spawn panes, parse diffs, and invoke secondary models with batch flags (`-p`). While effective outside multiplexers, this approach suffered from:
13
+ 1. **Cold-boot latency**: Each invocation incurred 20–30s of initialization, shell bootstrapping, and authentication checks.
14
+ 2. **Ephemeral loss of context**: Panes auto-closed immediately upon command completion, preventing persistent multi-turn follow-ups.
15
+ 3. **Approval blindness**: Headless scripts could not handle interactive questions or tool approvals (`blocked` states).
16
+
17
+ Herdr natively includes first-class agent orchestration primitives (`herdr agent start`, `prompt`, `read`, `wait`, `send-keys`) and an integrated `herdr` skill. This design standardizes direct Herdr agent multiplexing as the primary multi-model communication protocol across Heimdall, while preserving `*-bridge.ps1` as a secondary fallback for headless CI and non-Herdr environments.
18
+
19
+ ---
20
+
21
+ ## 2. Benchmark Findings & Optimization Rules
22
+
23
+ During live multi-agent verification (`claude` and `codex` invoked from `antigravity`), sequential tool turns resulted in ~60s total latency. Analysis revealed two root causes:
24
+ 1. **Sequential Discovery Overhead**: Splitting panes, checking shell readiness, starting agents, and issuing prompts across separate conversation turns multiplied network and thinking round-trips.
25
+ 2. **Model Tier Latency**: Invoking `claude-opus-5-5` with max effort for sanity checks introduced 3+ minutes of deliberation plus upstream API retries, whereas `gpt-6-astra` responded in 14 seconds.
26
+
27
+ ### The 3 Optimization Rules Embedded in `skills/herdr/SKILL.md`:
28
+ 1. **Hot-Agent Re-use**: Inspect `herdr agent list` before spawning new panes. Re-use existing live idle agents with zero startup penalty.
29
+ 2. **Batched Execution**: Combine layout creation (`herdr pane split`), agent startup (`herdr agent start`), and initial prompt (`herdr agent prompt`) into a single PowerShell / bash command block.
30
+ 3. **Speed-Tier Model Selection**: Pass fast model tiers (e.g. `--model claude-sonnet-5`) after `--` for validation and review turns, reserving Opus 5.5 for deep architectural planning.
31
+
32
+ ---
33
+
34
+ ## 3. Changes Applied
35
+
36
+ 1. **Installed Skill**: [`skills/herdr/SKILL.md`](../../skills/herdr/SKILL.md) exported directly from `herdr --skill` and enriched with batching/speed standards.
37
+ 2. **Catalog Registration**: Added `herdr` to `config/skills.json` under `suites` and `skills` (54 modular skills, 22 toolkits).
38
+ 3. **Collaborator Skills**: Updated `claude-collaborator`, `gemini-collaborator`, and `codex-collaborator` to lead with native `herdr agent` commands.
39
+ 4. **Agent Personas & Playbooks**:
40
+ - `agents/orchestrator.md`: Added `herdr` skill and updated Directive 5.
41
+ - `playbooks/03-adversarial-code-review.md`: Documented Herdr primary route for Goldfish code review.
42
+ - `playbooks/05-canonical-plan-template.md`: Documented native Herdr cross-validation prompts.
43
+ - `playbooks/06-model-registry-matrix.md`: Clarified Herdr multiplexing vs GhostCLI gateway.
44
+ 5. **Ecosystem Sync**: Synchronized across `~/.claude/`, `~/.gemini/`, `~/.codex/`, `~/.agents/`, and `~/.hermes/`.
45
+ 6. **Test Verification**: Terminating test suite executed via `npm test` passing 32/32 tests.
@@ -0,0 +1,30 @@
1
+ const fs = require('fs');
2
+ const path = require('path');
3
+
4
+ const configPath = path.resolve('config/skills.json');
5
+ const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
6
+
7
+ config.description = "Heimdall Canonical Skill Registry & 18-Suite Hierarchy";
8
+ config.totalSuites = 18;
9
+ config.totalModules = 50;
10
+
11
+ config.suites['progressive-disclosure'] = {
12
+ name: "Progressive Disclosure & Skill Architecture",
13
+ type: "Standalone Toolkit",
14
+ upstream: "https://github.com/bepaldes/heimdall-agent",
15
+ modules: [
16
+ "progressive-disclosure"
17
+ ]
18
+ };
19
+
20
+ config.skills['progressive-disclosure'] = {
21
+ name: "progressive-disclosure",
22
+ category: "Architecture & Database",
23
+ description: "Structuring modular agent skills and toolsets with progressive disclosure to eliminate prompt bloat and avoid multi-agent sprawl.",
24
+ upstream: "https://github.com/bepaldes/heimdall-agent",
25
+ sourceRevision: "v1.0.0",
26
+ updateProtocol: "Update the selected skill or plugin through its supported mechanism. Review changed instructions/references and repeat a bounded review after material updates. Record source revision, reviewed range, actual tests and remaining validation in the private report."
27
+ };
28
+
29
+ fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
30
+ console.log('Successfully added progressive-disclosure to config/skills.json');
@@ -0,0 +1,9 @@
1
+ $json = Get-Content config/skills.json -Raw | ConvertFrom-Json
2
+ $heimdallSkills = @()
3
+ foreach ($prop in $json.skills.PSObject.Properties) {
4
+ if ($prop.Value.upstream -like '*bepaldes/heimdall-agent*') {
5
+ $heimdallSkills += $prop.Name
6
+ }
7
+ }
8
+ Write-Host "Count: $($heimdallSkills.Count)"
9
+ $heimdallSkills
@@ -0,0 +1,26 @@
1
+ $headers = @{ 'User-Agent' = 'PowerShell' }
2
+ $classics = @(
3
+ "soft-skill",
4
+ "minimalist-skill",
5
+ "brutalist-skill",
6
+ "gpt-tasteskill",
7
+ "stitch-skill",
8
+ "taste-skill-v1"
9
+ )
10
+
11
+ foreach ($s in $classics) {
12
+ $url = "https://raw.githubusercontent.com/Leonxlnx/taste-skill-classics/main/skills/$s/SKILL.md"
13
+ try {
14
+ $remote = Invoke-RestMethod -Uri $url -Headers $headers
15
+ $localPath = "skills/$s/SKILL.md"
16
+ if (Test-Path $localPath) {
17
+ $local = [System.IO.File]::ReadAllText($localPath)
18
+ $eq = ($remote.Trim() -eq $local.Trim())
19
+ Write-Host "$s : Equal? $eq (Remote len: $($remote.Length), Local len: $($local.Length))"
20
+ } else {
21
+ Write-Host "$s : Local file not found!"
22
+ }
23
+ } catch {
24
+ Write-Host "$s : Error fetching: $($_.Exception.Message)"
25
+ }
26
+ }
@@ -0,0 +1,12 @@
1
+ $headers = @{ 'User-Agent' = 'PowerShell' }
2
+ $url = "https://raw.githubusercontent.com/Leonxlnx/taste-skill/main/skills/taste-skill/SKILL.md"
3
+ $content = Invoke-RestMethod -Uri $url -Headers $headers
4
+ [System.IO.File]::WriteAllText("docs/runs/skill-audit/taste-skill-upstream.md", $content)
5
+ $local = [System.IO.File]::ReadAllText("skills/taste-skill/SKILL.md")
6
+ Write-Host "Upstream length: $($content.Length)"
7
+ Write-Host "Local length: $($local.Length)"
8
+ if ($content -eq $local) {
9
+ Write-Host "EQUAL!"
10
+ } else {
11
+ Write-Host "DIFFERENT!"
12
+ }