heimdall-agent 1.0.0 → 1.2.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 (250) hide show
  1. package/README.md +57 -26
  2. package/README.pt-BR.md +443 -0
  3. package/agents/cloud-engineer.md +77 -0
  4. package/agents/code-sentinel.md +71 -34
  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 +68 -0
  9. package/agents/orchestrator.md +107 -93
  10. package/agents/reviewer.md +102 -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 +31 -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 +762 -573
  22. package/docs/SKILLS.md +393 -275
  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/2026-11-12-compare-report.json +1028 -0
  29. package/docs/runs/skill-audit/2026-11-12-upstream-audit.json +275 -0
  30. package/docs/runs/skill-audit/add_progressive_disclosure.cjs +30 -0
  31. package/docs/runs/skill-audit/check_heimdall_skills.ps1 +9 -0
  32. package/docs/runs/skill-audit/compare_classics.ps1 +26 -0
  33. package/docs/runs/skill-audit/compare_taste.ps1 +12 -0
  34. package/docs/runs/skill-audit/customization-report.json +380 -0
  35. package/docs/runs/skill-audit/diff_pending_skills.cjs +94 -0
  36. package/docs/runs/skill-audit/fetch_and_apply_skill.cjs +58 -0
  37. package/docs/runs/skill-audit/fetch_and_apply_taste_v2.cjs +65 -0
  38. package/docs/runs/skill-audit/inspect_pending_skills.cjs +71 -0
  39. package/docs/runs/skill-audit/inventory.json +308 -0
  40. package/docs/runs/skill-audit/list_local_taste.ps1 +1 -0
  41. package/docs/runs/skill-audit/phase5-update-plan.json +595 -0
  42. package/docs/runs/skill-audit/phase5-update-plan.md +138 -0
  43. package/docs/runs/skill-audit/probe.ps1 +16 -0
  44. package/docs/runs/skill-audit/probe_classics_branches.ps1 +3 -0
  45. package/docs/runs/skill-audit/probe_commits.ps1 +15 -0
  46. package/docs/runs/skill-audit/probe_repos.ps1 +17 -0
  47. package/docs/runs/skill-audit/probe_sentry_sec.ps1 +3 -0
  48. package/docs/runs/skill-audit/probe_sentry_sweep.ps1 +5 -0
  49. package/docs/runs/skill-audit/probe_snyk.ps1 +3 -0
  50. package/docs/runs/skill-audit/probe_snyk_recipes.ps1 +5 -0
  51. package/docs/runs/skill-audit/probe_taste_branches.ps1 +8 -0
  52. package/docs/runs/skill-audit/probe_taste_v19.ps1 +3 -0
  53. package/docs/runs/skill-audit/probe_user_repos.ps1 +19 -0
  54. package/docs/runs/skill-audit/prune_taste_skills.cjs +22 -0
  55. package/docs/runs/skill-audit/run_phase1_2.cjs +142 -0
  56. package/docs/runs/skill-audit/run_phase6_verification.cjs +107 -0
  57. package/docs/runs/skill-audit/show_16_details.ps1 +25 -0
  58. package/docs/runs/skill-audit/show_20_skills.ps1 +28 -0
  59. package/docs/runs/skill-audit/show_classics_diff.cjs +37 -0
  60. package/docs/runs/skill-audit/sync_agent_markdowns.cjs +30 -0
  61. package/docs/runs/skill-audit/taste-skill-upstream.md +542 -0
  62. package/docs/runs/skill-audit/update-manifest.md +88 -0
  63. package/docs/runs/skill-audit/update_config_skills.cjs +52 -0
  64. package/docs/runs/skill-audit/update_registry_phase7.cjs +83 -0
  65. package/docs/runs/skill-audit/upstream-status.json +563 -0
  66. package/docs/runs/skill-audit/verification-results.json +252 -0
  67. package/doctrine/AGENTS.md +42 -77
  68. package/hooks/git/pre-commit +11 -0
  69. package/hooks/heimdall-hook.cjs +81 -2
  70. package/hooks/herdr-agent-state.ps1 +55 -0
  71. package/hooks/hooks.json +0 -11
  72. package/lib/catalog-sync.cjs +167 -0
  73. package/lib/hermes-context.cjs +57 -0
  74. package/lib/model-context.cjs +123 -0
  75. package/lib/path-discovery.cjs +94 -0
  76. package/package.json +7 -3
  77. package/playbooks/01-interactive-grilling-gate.md +23 -6
  78. package/playbooks/02-fast-code-deep-verification.md +3 -2
  79. package/playbooks/03-adversarial-code-review.md +15 -7
  80. package/playbooks/05-canonical-plan-template.md +35 -19
  81. package/playbooks/06-model-registry-matrix.md +24 -13
  82. package/playbooks/07-legacy-code-modernization.md +74 -0
  83. package/playbooks/08-backlog-and-change-request-flow.md +122 -0
  84. package/setup.mjs +592 -172
  85. package/skills/antislop/SKILL.md +76 -56
  86. package/skills/antislop/VERSION +1 -0
  87. package/skills/antislop-copywriting/SKILL.md +407 -372
  88. package/skills/antislop-human/LICENSE-web-quality-skills +21 -0
  89. package/skills/antislop-human/SKILL.md +204 -147
  90. package/skills/antislop-human/contrast-check.py +168 -165
  91. package/skills/antislop-human/contrast-mcp.py +6 -3
  92. package/skills/antislop-human/references/A11Y-PATTERNS.md +249 -0
  93. package/skills/antislop-human/references/WCAG.md +127 -0
  94. package/skills/antislop-ui/LICENSE-web-quality-skills +21 -0
  95. package/skills/antislop-ui/SKILL.md +344 -304
  96. package/skills/antislop-ui/references/CORE-WEB-VITALS.md +181 -0
  97. package/skills/antislop-ui/references/WEB-BASELINE.md +28 -0
  98. package/skills/brainstorming/SKILL.md +296 -265
  99. package/skills/brainstorming/builder-check-prompt.md +23 -0
  100. package/skills/brainstorming/scripts/frame-template.html +213 -213
  101. package/skills/brainstorming/scripts/server.cjs +723 -723
  102. package/skills/brandkit/SKILL.md +798 -798
  103. package/skills/brutalist-skill/SKILL.md +93 -92
  104. package/skills/caveman/README.md +68 -0
  105. package/skills/caveman/SKILL.md +73 -38
  106. package/skills/claude-collaborator/SKILL.md +24 -44
  107. package/skills/clean-code/SKILL.md +152 -0
  108. package/skills/cloudflare-security-audit/AI-AND-LLM.md +83 -83
  109. package/skills/cloudflare-security-audit/ATTACK-CLASSES.md +130 -130
  110. package/skills/cloudflare-security-audit/CLIENT-SIDE.md +83 -83
  111. package/skills/cloudflare-security-audit/CLOUD-AND-DEPLOYMENT.md +86 -86
  112. package/skills/cloudflare-security-audit/DATA-ISOLATION-AND-LIFECYCLE.md +84 -84
  113. package/skills/cloudflare-security-audit/DESKTOP-MOBILE-AND-LOCAL-IPC.md +89 -89
  114. package/skills/cloudflare-security-audit/HUNTING.md +251 -251
  115. package/skills/cloudflare-security-audit/MEMORY-SAFETY-AND-BINARY.md +101 -101
  116. package/skills/cloudflare-security-audit/PROTOCOLS-RPC-AND-MESSAGING.md +81 -81
  117. package/skills/cloudflare-security-audit/RECONNAISSANCE.md +156 -156
  118. package/skills/cloudflare-security-audit/RESOURCE-EXHAUSTION-AND-AVAILABILITY.md +78 -78
  119. package/skills/cloudflare-security-audit/SKILL.md +192 -192
  120. package/skills/cloudflare-security-audit/SUPPLY-CHAIN-AND-RELEASE.md +73 -73
  121. package/skills/cloudflare-security-audit/VALIDATION-AND-REPORTING.md +186 -186
  122. package/skills/cloudflare-security-audit/WEB-PROTOCOL-AND-AUTH.md +105 -105
  123. package/skills/cloudflare-security-audit/report-schema.json +461 -461
  124. package/skills/cloudflare-security-audit/validate-coverage-ledger.cjs +872 -872
  125. package/skills/cloudflare-security-audit/validate-coverage-ledger.test.cjs +740 -740
  126. package/skills/cloudflare-security-audit/validate-findings.cjs +773 -773
  127. package/skills/cloudflare-security-audit/validate-findings.test.cjs +652 -652
  128. package/skills/codebase-design/DEEPENING.md +37 -0
  129. package/skills/codebase-design/DESIGN-IT-TWICE.md +44 -0
  130. package/skills/codebase-design/SKILL.md +114 -0
  131. package/skills/codex-collaborator/SKILL.md +24 -45
  132. package/skills/communication-doctrine/SKILL.md +89 -0
  133. package/skills/diagnosing-superpowers/SKILL.md +1 -1
  134. package/skills/diagnosing-superpowers/references/github-issues.md +3 -3
  135. package/skills/diagnosing-superpowers/templates/issue.md +23 -4
  136. package/skills/domain-modeling/ADR-FORMAT.md +47 -0
  137. package/skills/domain-modeling/GLOSSARY-FORMAT.md +60 -0
  138. package/skills/domain-modeling/SKILL.md +74 -0
  139. package/skills/executing-plans/SKILL.md +6 -56
  140. package/skills/executing-plans/scripts/task-done +52 -52
  141. package/skills/executing-plans/scripts/task-start +28 -28
  142. package/skills/gemini-collaborator/SKILL.md +24 -56
  143. package/skills/grill-me/SKILL.md +65 -0
  144. package/skills/handoff/SKILL.md +64 -0
  145. package/skills/herdr/SKILL.md +243 -0
  146. package/skills/image-to-code-skill/SKILL.md +1228 -1228
  147. package/skills/imagegen-frontend-mobile/SKILL.md +1465 -1465
  148. package/skills/imagegen-frontend-web/SKILL.md +987 -987
  149. package/skills/improve-codebase-architecture/HTML-REPORT.md +123 -0
  150. package/skills/improve-codebase-architecture/SKILL.md +71 -0
  151. package/skills/karpathy-guidelines/SKILL.md +67 -67
  152. package/skills/mcp-engineering/SKILL.md +74 -0
  153. package/skills/minimalist-skill/SKILL.md +87 -85
  154. package/skills/output-skill/SKILL.md +49 -49
  155. package/skills/owasp-security/reference/config-and-supply-chain.md +346 -344
  156. package/skills/owasp-security/reference/languages.md +378 -372
  157. package/skills/owasp-security/reference/owasp-report.md +1144 -1140
  158. package/skills/owasp-security/reference/review-checklist.md +134 -132
  159. package/skills/ponytail/SKILL.md +36 -52
  160. package/skills/postgres-best-practices/SKILL.md +30 -52
  161. package/skills/postgres-best-practices/references/backup-restore.md +372 -0
  162. package/skills/postgres-best-practices/references/bulk-loading.md +315 -0
  163. package/skills/postgres-best-practices/references/connection-pooling.md +310 -0
  164. package/skills/postgres-best-practices/references/hot-standby.md +221 -0
  165. package/skills/postgres-best-practices/references/indexing.md +318 -0
  166. package/skills/postgres-best-practices/references/logical-replication.md +610 -0
  167. package/skills/postgres-best-practices/references/major-version-upgrades.md +334 -0
  168. package/skills/postgres-best-practices/references/performance-diagnostics.md +553 -0
  169. package/skills/postgres-best-practices/references/query-optimization.md +294 -0
  170. package/skills/postgres-best-practices/references/query-patterns.md +566 -0
  171. package/skills/postgres-best-practices/references/schema-design.md +362 -0
  172. package/skills/postgres-best-practices/references/security-roles.md +489 -0
  173. package/skills/postgres-best-practices/references/transaction-isolation.md +344 -0
  174. package/skills/progressive-disclosure/SKILL.md +68 -0
  175. package/skills/pstack-discipline/SKILL.md +40 -0
  176. package/skills/receiving-code-review/SKILL.md +2 -23
  177. package/skills/requesting-code-review/SKILL.md +7 -36
  178. package/skills/soft-skill/SKILL.md +99 -98
  179. package/skills/stitch-skill/DESIGN.md +121 -121
  180. package/skills/stitch-skill/SKILL.md +185 -184
  181. package/skills/strix-security/SKILL.md +54 -53
  182. package/skills/subagent-driven-development/SKILL.md +35 -264
  183. package/skills/subagent-driven-development/references/batching.md +11 -0
  184. package/skills/subagent-driven-development/references/cannot-verify.md +10 -0
  185. package/skills/subagent-driven-development/references/final-review.md +47 -0
  186. package/skills/subagent-driven-development/references/fix-loop.md +77 -0
  187. package/skills/subagent-driven-development/references/handling-reports.md +15 -0
  188. package/skills/subagent-driven-development/references/preflight.md +26 -0
  189. package/skills/subagent-driven-development/references/resuming.md +12 -0
  190. package/skills/subagent-driven-development/scripts/review-package +53 -53
  191. package/skills/subagent-driven-development/scripts/sdd-workspace +87 -82
  192. package/skills/subagent-driven-development/scripts/task-brief +43 -43
  193. package/skills/systematic-debugging/SKILL.md +283 -306
  194. package/skills/taste-skill/SKILL.md +542 -1206
  195. package/skills/taste-skill/references/app-screens.md +1199 -0
  196. package/skills/taste-skill/references/colour.md +141 -0
  197. package/skills/taste-skill/references/copy.md +177 -0
  198. package/skills/taste-skill/references/critique.md +182 -0
  199. package/skills/taste-skill/references/imagery.md +791 -0
  200. package/skills/taste-skill/references/layout.md +292 -0
  201. package/skills/taste-skill/references/motion.md +980 -0
  202. package/skills/taste-skill/references/research.md +356 -0
  203. package/skills/taste-skill/references/scenes.md +174 -0
  204. package/skills/taste-skill/references/tells.md +115 -0
  205. package/skills/taste-skill/references/type.md +170 -0
  206. package/skills/test-driven-development/SKILL.md +330 -337
  207. package/skills/thermo/SKILL.md +67 -0
  208. package/skills/threat-modeling/SKILL.md +55 -0
  209. package/skills/to-spec/SKILL.md +75 -0
  210. package/skills/to-tickets/SKILL.md +105 -0
  211. package/skills/trailofbits-audit-context/SKILL.md +72 -72
  212. package/skills/trailofbits-insecure-defaults/commands/audit.md +35 -0
  213. package/skills/trailofbits-insecure-defaults/references/debug-features.json +13 -13
  214. package/skills/trailofbits-insecure-defaults/references/debug-features.md +75 -75
  215. package/skills/trailofbits-insecure-defaults/references/default-credentials.json +12 -12
  216. package/skills/trailofbits-insecure-defaults/references/default-credentials.md +76 -76
  217. package/skills/trailofbits-insecure-defaults/references/fail-open-security.json +11 -11
  218. package/skills/trailofbits-insecure-defaults/references/fail-open-security.md +70 -70
  219. package/skills/trailofbits-insecure-defaults/references/fallback-secrets.json +11 -11
  220. package/skills/trailofbits-insecure-defaults/references/fallback-secrets.md +70 -70
  221. package/skills/trailofbits-insecure-defaults/references/permissive-access.json +13 -13
  222. package/skills/trailofbits-insecure-defaults/references/permissive-access.md +62 -62
  223. package/skills/trailofbits-insecure-defaults/references/weak-crypto.json +13 -13
  224. package/skills/trailofbits-insecure-defaults/references/weak-crypto.md +71 -71
  225. package/skills/trailofbits-triage-brocards/SKILL.md +208 -208
  226. package/skills/verification-before-completion/SKILL.md +0 -14
  227. package/skills/wayfinder/SKILL.md +128 -0
  228. package/skills/writing-plans/SKILL.md +11 -15
  229. package/skills/writing-skills/SKILL.md +21 -303
  230. package/skills/writing-skills/references/CLAUDE_MD_TESTING.md +189 -0
  231. package/skills/writing-skills/references/anthropic-best-practices.md +1150 -0
  232. package/skills/writing-skills/references/bulletproofing.md +80 -0
  233. package/skills/writing-skills/references/discovery.md +201 -0
  234. package/skills/writing-skills/references/flowcharts.md +37 -0
  235. package/skills/writing-skills/references/graphviz-conventions.dot +172 -0
  236. package/skills/writing-skills/references/persuasion-principles.md +187 -0
  237. package/skills/writing-skills/references/testing-skills-with-subagents.md +384 -0
  238. package/tools/{claude-bridge.ps1 → archive/claude-bridge.ps1} +10 -7
  239. package/tools/{codex-bridge.ps1 → archive/codex-bridge.ps1} +1 -1
  240. package/tools/{gemini-bridge.ps1 → archive/gemini-bridge.ps1} +12 -19
  241. package/skills/gpt-tasteskill/SKILL.md +0 -74
  242. package/skills/taste-skill-v1/SKILL.md +0 -226
  243. /package/tools/{claude-bridge.cmd → archive/claude-bridge.cmd} +0 -0
  244. /package/tools/{claude-bridge.sh → archive/claude-bridge.sh} +0 -0
  245. /package/tools/{codex-bridge.cmd → archive/codex-bridge.cmd} +0 -0
  246. /package/tools/{codex-bridge.sh → archive/codex-bridge.sh} +0 -0
  247. /package/tools/{codexcli-bridge.cmd → archive/codexcli-bridge.cmd} +0 -0
  248. /package/tools/{codexcli-bridge.ps1 → archive/codexcli-bridge.ps1} +0 -0
  249. /package/tools/{gemini-bridge.cmd → archive/gemini-bridge.cmd} +0 -0
  250. /package/tools/{gemini-bridge.sh → archive/gemini-bridge.sh} +0 -0
@@ -2,15 +2,27 @@
2
2
 
3
3
  > **For Desktop & Web AI**: Use this authoritative schema whenever generating implementation plans (`/plan`, plan mode, or architectural prompts). Generic, simplified, or abbreviated templates are strictly forbidden.
4
4
 
5
+ ## Mandatory Plan Storage & Archiving Lifecycle
6
+ 1. **Creation Path & Naming**:
7
+ - All plans MUST be written directly to disk under the `docs/designs/` directory.
8
+ - The file name MUST strictly follow the format: `YYYY-MM-DD <plan name>.md` (e.g. `docs/designs/2026-10-31 user-authentication-flow.md`).
9
+ 2. **Archiving Upon Completion**:
10
+ - Once all phases of the plan have finished, tests have passed, and functionality is confirmed working, the plan file MUST be moved into:
11
+ `docs/designs/old/YYYY-MM-DD <plan name>.md`
12
+ - Active plans remain in `docs/designs/`; only finalized, delivered work is archived to `docs/designs/old/`.
13
+
5
14
  ---
6
15
 
7
16
  ````markdown
8
17
  # Plan: [Feature / Task Name]
9
18
 
10
19
  ## 1. Active Skills & Directives Checklist
11
- - [x] `brainstorming` — Intent discovered, assumptions surfaced, tradeoffs evaluated
20
+ - [x] `grill-me` / `brainstorming` — Intent discovered via Frontier questioning, assumptions surfaced, tradeoffs evaluated
21
+ - [x] `domain-modeling` — [Required for Tier 3] Architectural decisions recorded in `docs/adr/`, domain terms aligned
22
+ - [x] `codebase-design` — Deep module boundaries established, pass-through layers rejected, deletion test applied
12
23
  - [x] `karpathy-guidelines` — Simplicity first, surgical edits, no speculative bloat
13
24
  - [x] `antislop` — Clean comments, no AI boilerplate, accessible contrast
25
+ - [x] `communication-doctrine` — BLUF macro layout, STE imperative steps (<=20 words), zero vague qualifiers
14
26
  - [x] `taste-skill` — [Required for UI / Features] Design Read declared, design system tokens enforced
15
27
 
16
28
  ## 2. Context & Design Read (Required for UI / Features)
@@ -21,9 +33,9 @@
21
33
  ## 3. Multi-Agent Orchestration & Model Allocation Matrix
22
34
  | Task ID | Phase & Task Description | Assigned Model | Effort Level | Selection Rationale | Cross-Reviewer & Tool Command |
23
35
  | :--- | :--- | :--- | :--- | :--- | :--- |
24
- | T1 | Phase 1: Scaffolding | claude-sonnet-5 | high | Schema & component structure | Gemini 3.8 Flash (`gemini-bridge review`) |
25
- | T2 | Phase 2: Implementation | claude-sonnet-5 | high | Core business logic & UI | Gemini 3.8 Flash (`gemini-bridge review`) |
26
- | T3 | Phase 3: Playwright E2E | claude-sonnet-5 | high | Full user journey verification | Gemini 3.8 Flash (`gemini-bridge review`) |
36
+ | T1 | Phase 1: Scaffolding | claude-sonnet-5 | high | Schema & component structure | Gemini 3.8 Flash (`herdr agent prompt gemini-reviewer`) |
37
+ | T2 | Phase 2: Implementation | claude-sonnet-5 | high | Core business logic & UI | Gemini 3.8 Flash (`herdr agent prompt gemini-reviewer`) |
38
+ | T3 | Phase 3: Playwright E2E | claude-sonnet-5 | high | Full user journey verification | Gemini 3.8 Flash (`herdr agent prompt gemini-reviewer`) |
27
39
 
28
40
  ## 4. Multi-Phase Implementation Plan
29
41
  ### Phase 1: Architecture & Scaffolding
@@ -32,21 +44,23 @@
32
44
  ### Phase 4: Review, Purge & Handoff
33
45
 
34
46
  ## 5. Symmetric & Tri-Directional Cross-Model Validation Loop
35
- - Tasks executed by Claude -> Validate with Gemini or Codex:
36
- `powershell -File C:/Apps/tools/gemini-bridge.ps1 review -Model "Gemini 3.8 Flash" -Effort "high"`
37
- `powershell -File C:/Apps/tools/codex-bridge.ps1 review -Model "gpt-6-astra" -Effort "high"`
38
- - Tasks executed by Gemini -> Validate with Claude or Codex:
39
- `powershell -File C:/Apps/tools/claude-bridge.ps1 review -Model "claude-sonnet-5" -Effort "high"`
40
- `powershell -File C:/Apps/tools/codex-bridge.ps1 review -Model "gpt-6-astra" -Effort "high"`
41
- - Tasks executed by Codex -> Validate with Claude or Gemini:
42
- `powershell -File C:/Apps/tools/claude-bridge.ps1 review -Model "claude-sonnet-5" -Effort "high"`
43
- `powershell -File C:/Apps/tools/gemini-bridge.ps1 review -Model "Gemini 3.8 Flash" -Effort "high"`
47
+ - In Herdr (`HERDR_ENV=1`), validate tasks directly via peer agent prompts:
48
+ - Tasks executed by Claude -> Validate with Gemini or Codex:
49
+ `herdr agent prompt gemini-reviewer "Review git diff for security regressions and type errors." --wait --timeout 120000`
50
+ `herdr agent prompt codex-reviewer "Review git diff for security regressions and boundary conditions." --wait --timeout 120000`
51
+ - Tasks executed by Gemini -> Validate with Claude or Codex:
52
+ `herdr agent prompt claude-reviewer "Review git diff for security regressions and type errors." --wait --timeout 120000`
53
+ `herdr agent prompt codex-reviewer "Review git diff for security regressions and boundary conditions." --wait --timeout 120000`
54
+ - Tasks executed by Codex -> Validate with Claude or Gemini:
55
+ `herdr agent prompt claude-reviewer "Review git diff for security regressions and type errors." --wait --timeout 120000`
56
+ `herdr agent prompt gemini-reviewer "Review git diff for security regressions and type errors." --wait --timeout 120000`
44
57
 
45
58
  ## 6. Orchestrator Heartbeat
46
59
  - Orchestrator monitors progress every 3 minutes.
47
60
 
48
61
  ## 7. Verification Harness
49
- - **Playwright E2E Primary Gate**: Real browser execution (DOM state, visibility assertions, non-zero bounding box checks).
62
+ - **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`).
63
+ - **Playwright E2E Primary Gate**: Real browser execution (DOM state, visibility assertions, non-zero bounding box checks) strictly against pre-existing human-managed servers or static build artifacts. Agents do NOT spin up servers.
50
64
  - **Backend-with-UI-Impact Rule**: Backend tasks affecting user views must include browser verification.
51
65
  - **Rejection of Pseudo-Verification**: No task sign-off on `tsc`, `curl`, `grep`, or container health alone.
52
66
  - **Environment Detection**: Confirm Playwright presence; if absent, ask user during planning for preferred setup.
@@ -60,7 +74,7 @@
60
74
  ### Section Requirements
61
75
  1. **Section 1: Active Skills & Directives Checklist**:
62
76
  - Must explicitly list all active skills governing execution.
63
- - Baseline minimum: `brainstorming`, `karpathy-guidelines`, `antislop`.
77
+ - Baseline minimum: `brainstorming`, `karpathy-guidelines`, `antislop`, `communication-doctrine`.
64
78
  - Any UI, styling, or frontend surface requires `taste-skill`.
65
79
  2. **Section 2: Context & Design Read**:
66
80
  - Required for any user-facing feature or UI change.
@@ -69,18 +83,20 @@
69
83
  3. **Section 3: Model Allocation Matrix**:
70
84
  - Decomposes plan into discrete tasks with explicit task IDs.
71
85
  - Each task assigns a canonical model and effort level from [`playbooks/06-model-registry-matrix.md`](file:///C:/Apps/heimdall-agent/playbooks/06-model-registry-matrix.md).
72
- - Declares the cross-reviewer harness and bridge execution command.
86
+ - Declares the cross-reviewer harness and Herdr prompt command.
73
87
  4. **Section 4: Multi-Phase Implementation Plan**:
74
88
  - Organized into logical progression (Scaffolding -> Core Implementation -> E2E Verification -> Review/Handoff).
75
89
  - Strict TDD: failing test first, minimal code, passing test, self-review.
90
+ - Strict STE Step Granularity: Every step begins with an approved imperative verb (`Create`, `Modify`, `Assert`, `Verify`, `Delete`, `Run`), contains <= 20 words, and contains zero banned vague qualifiers (`ensure`, `properly`, `appropriately`, `as needed`).
76
91
  5. **Section 5: Symmetric & Tri-Directional Cross-Model Validation Loop**:
77
- - Defines validation commands using shared bridge scripts in `C:\Apps\tools\`.
92
+ - Defines validation commands using native Herdr agent commands.
78
93
  - Claude tasks validated by Gemini/Codex; Gemini tasks validated by Claude/Codex; Codex tasks validated by Claude/Gemini.
79
94
  6. **Section 6: Orchestrator Heartbeat**:
80
95
  - Cadence for monitoring task progress, status checks, and liveness during subagent runs.
81
96
  7. **Section 7: Verification Harness**:
82
- - Primary verification standard is full Playwright E2E with real DOM state and non-zero bounding box assertions.
83
- - Enforces the strict ban on pseudo-verification (`curl`, `grep`, `tsc --noEmit`, container status).
97
+ - Zero Dev-Server policy: No agent may start background or dev servers (`npm run dev`, `vite`, `next dev`).
98
+ - Primary verification standard is full Playwright E2E with real DOM state and non-zero bounding box assertions against pre-existing servers or static builds.
99
+ - Enforces the strict ban on pseudo-verification (`curl`, `grep`, `tsc --noEmit` alone, container status).
84
100
  - Mandates browser verification for backend changes with UI impact.
85
101
 
86
102
  ### Effort Constraint Rules
@@ -4,12 +4,19 @@
4
4
 
5
5
  ---
6
6
 
7
- ## 1. Access Channels
7
+ ## 1. Access Channels & Multi-Agent Multiplexing
8
8
 
9
- Models are accessed through three primary channels:
10
- - **GhostCLI** (`https://ghostcli.cloud`): Unified API proxy for Claude Code and OpenAI Codex CLI sessions.
11
- - **Gemini Bridge** (`gemini-bridge.ps1`): Direct connection to Google's API for Gemini sessions and reviews (not through GhostCLI).
12
- - **Bridge Scripts** (`C:\Apps\tools\`): Canonical shared scripts (`claude-bridge.ps1`, `gemini-bridge.ps1`, `codex-bridge.ps1`) hitting native APIs for cross-model validation.
9
+ Models are partitioned into two architectural access channels:
10
+
11
+ - **Channel 1: GhostCLI Unified Gateway (`https://ghostcli.cloud`)**
12
+ - Powers **Claude Code CLI**, **OpenAI Codex CLI**, and **Hermes Agent**.
13
+ - Serves all Anthropic models (`claude-*`), OpenAI models (`gpt-6-astra`), and Zhipu AI models (`z-ai/glm-5.3`, `z-ai/glm-5.3-flash`).
14
+ - Because GhostCLI exposes multi-protocol translation (`/v1/messages`, `/v1/responses`, `/v1/chat/completions`), Claude Code can run GPT-6 Astra or GLM directly (`claude --model gpt-6-astra`), and Codex can run Claude Sonnet directly (`codex --model claude-sonnet-5`).
15
+ - When coordinating between harnesses in Herdr (`HERDR_ENV=1`), use native Herdr multiplexing (`herdr agent start/prompt`) directly.
16
+
17
+ - **Channel 2: Google Gemini Direct API (`gemini.googleapis.com`)**
18
+ - Powers **Google Antigravity** natively (via direct Google OAuth).
19
+ - Coordinated across harnesses via native Herdr (`herdr agent start <name> --kind agy`).
13
20
 
14
21
  ---
15
22
 
@@ -22,20 +29,23 @@ All GhostCLI models support text and image input:
22
29
  | **Claude Opus 5.5** | `claude-opus-5-5` | 256K / 1M extended | 128K | ✅ | ✅ | `low`, `medium`, `high`, `xhigh` | Deepest architectural reasoning, complex multi-system debugging, critical security audits, knotty algorithms. |
23
30
  | **Claude Sonnet 5** | `claude-sonnet-5` | 256K / 1M extended | 128K | ✅ | ✅ | `low`, `medium`, `high`, `xhigh` | Primary full-stack coding driver, type-safe API schemas, database mutation logic, Playwright E2E test authoring. |
24
31
  | **Claude Fable 5.1** | `claude-fable-5.1` | 256K / 1M extended | 128K | ✅ | ✅ | `low`, `medium`, `high`, `xhigh` | Visual storytelling, high-polish frontend design, copycrafting, UI aesthetic alignment, interaction flows. |
25
- | **GLM 5.3** | `z-ai/glm-5.3` | 1M | 128K | ❌ | ❌ | `low`, `medium`, `high`, `xhigh` | Massive context analysis, long-document processing, Zhipu AI reasoning. |
32
+ | **GLM 5.3** | `z-ai/glm-5.3` | 1M | 128K | ❌ | ❌ | `low`, `medium`, `high`, `xhigh` | Massive context analysis, long-document processing, Zhipu AI reasoning (upstream may experience upstream queue delays). |
33
+ | **GLM 5.3 Flash** | `z-ai/glm-5.3-flash` | 1M | 128K | ❌ | ❌ | `low`, `medium`, `high` | Fast responses for code tasks, rapid reasoning, lightweight context queries. |
26
34
  | **GPT-6 Astra** | `gpt-6-astra` | 1M | 128K | ✅ | ✅ | `low`, `medium`, `high`, `xhigh` | OpenAI reasoning, broad general-purpose tasks, alternative perspective for cross-validation. |
27
35
 
36
+ > [!WARNING]
37
+ > **Naming Asymmetry Guardrail**: Opus is version **5.5** (`claude-opus-5-5`), while Sonnet is strictly version **5** (`claude-sonnet-5`). Do NOT hallucinate `claude-sonnet-5-5` or `sonnet-5-5`. There is no 5.5 release for Sonnet.
38
+
28
39
  ---
29
40
 
30
- ## 3. Gemini Bridge Models (Google API Direct)
41
+ ## 3. Google Antigravity Models (Google API Direct)
31
42
 
32
- Accessed via `gemini-bridge.ps1` hitting Google's API directly (never through GhostCLI):
43
+ Accessed natively via Google Antigravity / `agy` CLI (never through GhostCLI):
33
44
 
34
45
  | Model Name | Canonical Flag | Allowed Effort Levels | Optimal Specialization |
35
46
  | :--- | :--- | :--- | :--- |
36
- | **Gemini 4 (Argon)** | `gemini-4` (`gemini-4-argon`, `argon`) | `low`, `medium`, `high`, `xhigh` | Next-generation flagship Gemini reasoning, complex multi-file architecture, deep cross-workspace synthesis, high-velocity full-stack implementation. |
37
- | **Gemini 3.8 Flash** | `gemini-3.8-flash` | `low`, `medium`, `high` | Fast scans, workspace audits, boilerplate generation, unit test scaffolding, rapid prototyping, responsive styling. |
38
- | **Gemini 3.1 Pro** | `gemini-3.1-pro` | `medium`, `high`, `xhigh` | Massive context analysis, repository-wide multi-file refactoring, deep documentation synthesis, architectural audits. |
47
+ | **Gemini 4 Argon** | `gemini-4-argon-{effort}` (e.g. `gemini-4-argon-high`) | `low`, `medium`, `high`, `xhigh` | Next-generation flagship Gemini reasoning, complex multi-file architecture, deep cross-workspace synthesis, high-velocity full-stack implementation. |
48
+ | **Gemini 3.8 Flash** | `gemini-3.8-flash-{effort}` (e.g. `gemini-3.8-flash-high`) | `low`, `medium`, `high` | Fast scans, workspace audits, boilerplate generation, unit test scaffolding, rapid prototyping, responsive styling. |
39
49
 
40
50
  ---
41
51
 
@@ -62,11 +72,12 @@ The `/model` picker in Claude Code shows a hardcoded list that may include model
62
72
 
63
73
  To dispatch any GhostCLI model — including those invisible in the picker — pass its canonical flag via the Agent tool's `model` parameter when spawning subagents (e.g. `model: "gpt-6-astra"`, `model: "z-ai/glm-5.3"`). The API call routes through GhostCLI regardless of what `/model` displays.
64
74
 
65
- Gemini models (`gemini-4`, `gemini-3.8-flash`, `gemini-3.1-pro`) are never reachable through GhostCLI; they require `gemini-bridge.ps1` hitting Google's API directly.
75
+ Gemini models (`gemini-4`, `gemini-3.8-flash`, `gemini-3.1-pro`) are never reachable through GhostCLI; they are accessed natively via Google Antigravity (`agy` CLI in Herdr).
66
76
 
67
77
  ---
68
78
 
69
79
  ## 6. Effort Constraint & Fallback Rules
70
80
 
71
81
  - **Effort Constraint Rule**: Each task in a plan must explicitly declare one of the registered models and an allowed effort level matching the tables above.
72
- - **Quota Fallback Rule**: When Gemini 4 Argon reaches quota cooldown, immediately fallback to Gemini 3.8 Flash (for fast scans/reviews) or Gemini 3.1 Pro (for massive context), or Claude Sonnet 5 / GPT-6 Astra via GhostCLI.
82
+ - **Quota Fallback Rule**: When Gemini 4 Argon reaches quota cooldown, immediately fallback to Gemini 3.8 Flash (for fast scans/reviews) or Claude Sonnet 5 / GPT-6 Astra via GhostCLI.
83
+ - **Headless Execution Limitation**: The `agy` CLI requires a TTY for all execution modes including `--print`. Non-interactive/headless invocations from scripts, CI, or piped environments will hang indefinitely. Use Herdr split/tab/window modes instead, or run `agy` interactively.
@@ -0,0 +1,74 @@
1
+ # Playbook 07: Legacy Code Modernization & Transformation
2
+
3
+ > **For Desktop & Web AI**: Use this playbook whenever undertaking legacy codebase upgrades, runtime migrations, dependency modernizations, or monolithic subsystem refactoring.
4
+
5
+ ---
6
+
7
+ ## 1. Overview & Core Philosophy
8
+ Modernizing legacy software using AI coding agents carries a significant risk: models frequently discard critical, undocumented business logic because it looks messy or idiomatic to older language versions.
9
+
10
+ This playbook enforces Anthropic's **Code Modernization Playbook** framework: transformations must proceed through disciplined **Characterization Testing (Golden Master)** and **Vertical Slice Migrations**, guaranteeing zero behavioral regressions.
11
+
12
+ ---
13
+
14
+ ## 2. The 4-Phase Modernization Workflow
15
+
16
+ ```mermaid
17
+ flowchart LR
18
+ P1["Phase 1: Discovery & Boundary Mapping"] --> P2["Phase 2: Golden Master Characterization"]
19
+ P2 --> P3["Phase 3: Vertical Slice Migration"]
20
+ P3 --> P4["Phase 4: Dual-Run Parity & Cutover"]
21
+ ```
22
+
23
+ ### Phase 1: Discovery & Boundary Mapping
24
+ 1. **Identify the Seam**: Locate where the legacy subsystem interacts with the rest of the application (API contracts, DB tables, file I/O, exported functions).
25
+ 2. **Blast-Radius Assessment**:
26
+ - Classify downstream consumers into Tier 1 (internal non-critical), Tier 2 (user-facing views), or Tier 3 (database mutations, auth, financial transactions).
27
+ 3. **Document Invariants**: Record all expected input formats, edge cases, and known quirks in `docs/modernization/<subsystem>-invariants.md`.
28
+
29
+ ### Phase 2: Golden Master (Characterization) Test Baseline
30
+ > [!CRITICAL]
31
+ > **Zero-Mutation Rule**: Do NOT touch, clean up, or refactor legacy code during this phase.
32
+
33
+ 1. **Write Characterization Tests**:
34
+ - Capture real-world inputs and record outputs from the *existing* legacy implementation.
35
+ - Include: valid payloads, malformed inputs, boundary values (null, empty, negative, maximum length), and error conditions.
36
+ 2. **Lock the Baseline**:
37
+ - Run the tests against the untouched legacy code.
38
+ - Every characterization test must pass (100% baseline).
39
+ 3. **Commit Baseline**:
40
+ - Commit the characterization suite to git before proceeding to Phase 3.
41
+
42
+ ### Phase 3: Incremental Vertical Slice Migration (Strangler Fig)
43
+ 1. **Define the Modern Interface**: Author clean TypeScript/Node.js or target language interfaces representing the modernized seam.
44
+ 2. **Implement Behind an Adapter**:
45
+ - Create a routing adapter that can switch between the legacy implementation and the modernized implementation via an environment variable or feature flag:
46
+ ```typescript
47
+ export async function processTransaction(data: TransactionInput): Promise<TransactionResult> {
48
+ if (process.env.USE_MODERN_TRANSACTIONS === "true") {
49
+ return modernProcessor.execute(data);
50
+ }
51
+ return legacyProcessor.execute(data);
52
+ }
53
+ ```
54
+ 3. **Surgical Implementation**: Write the modernized implementation adhering strictly to Karpathy simplicity and native platform features.
55
+
56
+ ### Phase 4: Dual-Run Parity & Cutover
57
+ 1. **Dual-Run Verification**:
58
+ - Run the Golden Master test suite with the feature toggle enabled.
59
+ - Verify that all outputs match the legacy outputs bit-for-bit (or within explicitly documented architectural updates).
60
+ 2. **Peer Adversarial Review**:
61
+ - Dispatch the diff to the Reviewer (via `herdr agent prompt <reviewer-agent> "Review diff..." --wait` or child subagent review).
62
+ 3. **Decommissioning**:
63
+ - Remove the feature toggle and safely delete the legacy code branch.
64
+
65
+ ---
66
+
67
+ ## 3. Mandatory Modernization Guardrails
68
+
69
+ 1. **Ban Big-Bang Rewrites**:
70
+ - Any refactoring plan proposing to replace more than 500 lines of legacy code in a single pull request without incremental seams must be rejected.
71
+ 2. **Preserve Business Quirks**:
72
+ - Never "fix" undocumented behavioral quirks during a modernization pass unless the user explicitly commands the behavioral change.
73
+ 3. **Automated Rollback Readiness**:
74
+ - Every modernized vertical slice must have an immediate, zero-downtime rollback mechanism (feature toggle or reversible commit) until production stability is established.
@@ -0,0 +1,122 @@
1
+ # Playbook 08: Backlog Governance, Change Request (CR) Analysis & Execution Flows
2
+
3
+ > **For Desktop & Web AI**: Use this operational protocol to govern issue intake, feature backlogs, Change Request (CR) reviews, and implementation lifecycles.
4
+
5
+ ---
6
+
7
+ ## 1. Governance Overview
8
+
9
+ Heimdall distinguishes between **fast-path bugfixes** and **evaluated feature requests** to maintain stability while preventing architectural drift:
10
+
11
+ ```mermaid
12
+ flowchart TD
13
+ A["Incoming Engineering Request"] --> B{"Classify Intake"}
14
+
15
+ %% Flow 1: Bugfixes
16
+ B -->|Bug / Defect| C["Flow 1: Bugfix Fast-Path"]
17
+ C --> C1["1. Receive Report & Triage"]
18
+ C1 --> C2["2. Assess Root Cause & Plan Fix"]
19
+ C2 --> C3["3. Implement with Failing Test First (TDD)"]
20
+ C3 --> C4["4. Run Verification (Automated + Playwright if UI)"]
21
+ C4 --> C5["5. Completed & Merged"]
22
+
23
+ %% Flow 2 & 3: Features & Backlog
24
+ B -->|New Feature / Idea| D["Flow 2: Backlog Intake"]
25
+ D --> D1["Log into docs/backlog.md with context & priority"]
26
+ D1 --> E["Flow 3: Change Request (CR) Analysis"]
27
+ E --> E1["CR Assessment (Blast Radius, Architecture, Scope)"]
28
+ E1 --> E2{"Human Decision Gate"}
29
+
30
+ %% Approved Path
31
+ E2 -->|Approved| F["Flow 3a: Execution Cycle"]
32
+ F --> F1["Author Plan: docs/designs/YYYY-MM-DD <name>.md"]
33
+ F1 --> F2["Implementation & Testing"]
34
+ F2 --> F3["Archive Plan to docs/designs/old/"]
35
+ F3 --> F4["Mark Backlog Item as [Completed]"]
36
+
37
+ %% Rejection Path
38
+ E2 -->|Not Approved| G["Flow 4: Rejection Handling"]
39
+ G --> G1["Return to Backlog with Rebuttal/Notes OR Delete if Discarded"]
40
+ ```
41
+
42
+ ---
43
+
44
+ ## 2. The Four Distinct Lifecycle Flows
45
+
46
+ ### Flow 1: Bugfixes (Fast-Path Loop)
47
+ * **Trigger**: Bug report, runtime error, broken assertion, or security defect.
48
+ * **Protocol**:
49
+ 1. **Receive Report**: Extract steps to reproduce, affected files, error logs, and expected behavior.
50
+ 2. **Assess & Plan Fix**: Identify root cause; for <50 LOC (Tier 1), plan surgically in-chat; for complex defects, author a brief plan.
51
+ 3. **Implement via TDD**: Write a failing regression test proving the bug exists; implement minimal surgical code until the test passes.
52
+ 4. **Verify**: Run full test suite (`pnpm test` / `pytest`) and Playwright E2E if user interface is touched.
53
+ 5. **Complete**: Mark resolved, record fix in commit message.
54
+
55
+ ### Flow 2: New Features (Backlog Intake)
56
+ * **Trigger**: New requirement, enhancement proposal, or architectural improvement.
57
+ * **Protocol**:
58
+ 1. **Do not immediately implement.**
59
+ 2. Log the item into [`docs/backlog.md`](file:///C:/Apps/heimdall-agent/docs/backlog.md) under `## Active Backlog`.
60
+ 3. Capture:
61
+ - **ID**: `FEAT-XXX` or `CR-XXX`
62
+ - **Title**: Descriptive name
63
+ - **Motivation & Details**: Context, target users, business justification
64
+ - **Impact & Estimated Scope**: Tier 1, 2, or 3
65
+ - **Status**: `Backlog` (or `Under Analysis`)
66
+
67
+ ### Flow 3: Change Request (CR) Analysis & Implementation
68
+ * **Trigger**: User requests evaluation of a specific backlog item (or a batch sweep of the backlog).
69
+ * **Protocol**:
70
+ 1. **CR Analysis Phase**:
71
+ - Evaluate technical feasibility, architectural fit, dependency footprint, and blast radius.
72
+ - Review backward compatibility and potential regressions.
73
+ - Present findings clearly:
74
+ - Scope classification (Tier 1, 2, or 3)
75
+ - Architectural impact & trade-offs
76
+ - Effort estimation & model allocation recommendation
77
+ 2. **Human Approval Gate**:
78
+ - STOP and wait for explicit user sign-off to proceed.
79
+ 3. **Implementation Cycle (Upon Approval)**:
80
+ - **Step A**: Author a formal 7-section plan in:
81
+ `docs/designs/YYYY-MM-DD <feature-name>.md`
82
+ - **Step B**: Execute plan task-by-task following TDD and anti-slop guidelines.
83
+ - **Step C**: Verify thoroughly with automated tests and Playwright E2E.
84
+ - **Step D**: Archive the plan:
85
+ Move `docs/designs/YYYY-MM-DD <feature-name>.md` to `docs/designs/old/YYYY-MM-DD <feature-name>.md`.
86
+ - **Step E**: Update [`docs/backlog.md`](file:///C:/Apps/heimdall-agent/docs/backlog.md), moving item to `## Completed`.
87
+
88
+ ### Flow 4: Rejection & Postponement
89
+ * **Trigger**: CR Analysis concludes the feature is out of scope, premature, high risk, or user rejects proposal.
90
+ * **Protocol**:
91
+ - **Option 4A (Postpone / Defer)**: Move the item back to `## Active Backlog` or `## Icebox`, appending the rejection rationale, unanswered questions, or blockers.
92
+ - **Option 4B (Delete / Discard)**: If permanently discarded, record in `## Discarded / Rejected` with reason (or delete from the document if instructed by user).
93
+
94
+ ---
95
+
96
+ ## 3. Backlog Document Schema (`docs/backlog.md`)
97
+
98
+ All projects governed by Heimdall must maintain [`docs/backlog.md`](file:///C:/Apps/heimdall-agent/docs/backlog.md) adhering to this authoritative structure:
99
+
100
+ ```markdown
101
+ # Product & Engineering Backlog
102
+
103
+ ## 1. Under Analysis / Change Requests (In-Flight Evaluation)
104
+ | ID | Title | Priority | Scope Tier | CR Status | Analysis Notes / Design Link |
105
+ | :--- | :--- | :--- | :--- | :--- | :--- |
106
+
107
+ ## 2. Active Backlog (Prioritized Features)
108
+ | ID | Title | Priority (P0-P3) | Type (Feature/Enchancement) | Description & Value | Target Milestone |
109
+ | :--- | :--- | :--- | :--- | :--- | :--- |
110
+
111
+ ## 3. Icebox / Deferred
112
+ | ID | Title | Date Added | Deferral Reason / Unresolved Questions |
113
+ | :--- | :--- | :--- | :--- |
114
+
115
+ ## 4. Completed
116
+ | ID | Title | Completed Date | Plan Reference (docs/designs/old/) | Verified By |
117
+ | :--- | :--- | :--- | :--- | :--- |
118
+
119
+ ## 5. Discarded / Rejected
120
+ | ID | Title | Decision Date | Rejection Rationale |
121
+ | :--- | :--- | :--- | :--- |
122
+ ```