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
@@ -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
+ ```