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,162 @@
1
+ 'use strict';
2
+
3
+ const fs = require('node:fs');
4
+ const path = require('node:path');
5
+
6
+ /**
7
+ * Synchronizes skill and suite count references across all repository files:
8
+ * config/skills.json, config/profiles.json, docs/SKILLS.md, README.md,
9
+ * README.pt-BR.md, and setup.mjs.
10
+ *
11
+ * Single Source of Truth: The actual count of entries in config/skills.json ("skills" and "suites").
12
+ *
13
+ * @param {string} rootDir Repository root directory
14
+ * @param {boolean} dryRun If true, computes changes without writing to disk
15
+ * @returns {{ skillCount: number, suiteCount: number, modified: boolean }}
16
+ */
17
+ function syncCatalogCounts(rootDir, dryRun = false) {
18
+ const skillsConfigPath = path.join(rootDir, 'config', 'skills.json');
19
+ if (!fs.existsSync(skillsConfigPath)) return null;
20
+
21
+ try {
22
+ const rawCatalog = fs.readFileSync(skillsConfigPath, 'utf8');
23
+ const catalog = JSON.parse(rawCatalog);
24
+ const skillCount = Object.keys(catalog.skills || {}).length;
25
+ const suiteCount = Object.keys(catalog.suites || {}).length;
26
+ const standaloneCount = suiteCount - 5; // 5 Core Suites + remainder Standalone
27
+ const agentsDir = path.join(rootDir, 'agents');
28
+ const agentCount = fs.existsSync(agentsDir)
29
+ ? fs.readdirSync(agentsDir).filter(f => f.endsWith('.md')).length
30
+ : 10;
31
+
32
+ let modified = false;
33
+
34
+ // 1. Sync config/skills.json total counts
35
+ if (catalog.totalModules !== skillCount || catalog.totalSuites !== suiteCount) {
36
+ catalog.totalModules = skillCount;
37
+ catalog.totalSuites = suiteCount;
38
+ if (!dryRun) {
39
+ fs.writeFileSync(skillsConfigPath, JSON.stringify(catalog, null, 2) + '\n', 'utf8');
40
+ }
41
+ modified = true;
42
+ }
43
+
44
+ // 2. Sync config/profiles.json
45
+ const profilesPath = path.join(rootDir, 'config', 'profiles.json');
46
+ if (fs.existsSync(profilesPath)) {
47
+ const rawProfiles = fs.readFileSync(profilesPath, 'utf8');
48
+ const profiles = JSON.parse(rawProfiles);
49
+ if (profiles.profiles && profiles.profiles.full) {
50
+ const expectedDesc = `Complete ${skillCount}-skill suite & ${agentCount} predefined agents: Process, Anti-Slop, Design, Security, Hygiene, and Cross-Agent Bridges.`;
51
+ if (profiles.profiles.full.description !== expectedDesc) {
52
+ profiles.profiles.full.description = expectedDesc;
53
+ if (!dryRun) {
54
+ fs.writeFileSync(profilesPath, JSON.stringify(profiles, null, 2) + '\n', 'utf8');
55
+ }
56
+ modified = true;
57
+ }
58
+ }
59
+ }
60
+
61
+ // 3. Sync docs/SKILLS.md
62
+ const docsSkillsPath = path.join(rootDir, 'docs', 'SKILLS.md');
63
+ if (fs.existsSync(docsSkillsPath)) {
64
+ let content = fs.readFileSync(docsSkillsPath, 'utf8');
65
+ const regex = /Heimdall's \*\*\d+ Primary Toolkits & Suites \(\d+ modular capabilities\)\*\*/g;
66
+ const targetStr = `Heimdall's **${suiteCount} Primary Toolkits & Suites (${skillCount} modular capabilities)**`;
67
+ if (regex.test(content) && !content.includes(targetStr)) {
68
+ content = content.replace(regex, targetStr);
69
+ if (!dryRun) fs.writeFileSync(docsSkillsPath, content, 'utf8');
70
+ modified = true;
71
+ }
72
+ }
73
+
74
+ // 4. Sync README.md
75
+ const readmePath = path.join(rootDir, 'README.md');
76
+ if (fs.existsSync(readmePath)) {
77
+ let content = fs.readFileSync(readmePath, 'utf8');
78
+ const orig = content;
79
+
80
+ content = content.replace(/skills-\d+%20toolkits%20%28\d+%20modules%29/g, `skills-${suiteCount}%20toolkits%20%28${skillCount}%20modules%29`);
81
+ content = content.replace(/Skills: \d+ Toolkits \(\d+ Modules\)/g, `Skills: ${suiteCount} Toolkits (${skillCount} Modules)`);
82
+ content = content.replace(/#skill-inventory-\d+-modules-across-\d+-toolkits/g, `#skill-inventory-${skillCount}-modules-across-${suiteCount}-toolkits`);
83
+ content = content.replace(/<a id="skill-inventory-\d+-modules-across-\d+-toolkits"><\/a>/g, `<a id="skill-inventory-${skillCount}-modules-across-${suiteCount}-toolkits"></a>`);
84
+ content = content.replace(/### Skill Inventory \(\d+ Modules Across \d+ Toolkits\)/g, `### Skill Inventory (${skillCount} Modules Across ${suiteCount} Toolkits)`);
85
+ content = content.replace(/\*\*\d+ modular skills\*\*/g, `**${skillCount} modular skills**`);
86
+ content = content.replace(/\* \*\*Modular Skills\*\*:\s*\d+\s*task-activated capabilities/g, `* **Modular Skills**: ${skillCount} task-activated capabilities`);
87
+ content = content.replace(/(\|\s*`skills\/`\s*\|\s*`~\/\.<tool>\/skills\/`\s*\|\s*)\d+(\s*domain toolkits)/g, `$1${skillCount}$2`);
88
+ content = content.replace(/(\|\s*\*\*`full`\*\*\s*\*\(Default\)\*\s*\|\s*)\d+(\s*\|\s*)\d+(\s*\|)/g, `$1${skillCount}$2${agentCount}$3`);
89
+ content = content.replace(/agents-\d+%20predefined/g, `agents-${agentCount}%20predefined`);
90
+ content = content.replace(/alt="Agents: \d+ Predefined"/g, `alt="Agents: ${agentCount} Predefined"`);
91
+ content = content.replace(/#\d+-predefined-agent-personas/g, `#${agentCount}-predefined-agent-personas`);
92
+ content = content.replace(/<a id="\d+-predefined-agent-personas"><\/a>/g, `<a id="${agentCount}-predefined-agent-personas"></a>`);
93
+ content = content.replace(/### \d+ Predefined Agent Personas/g, `### ${agentCount} Predefined Agent Personas`);
94
+ content = content.replace(/synchronizes \*\*\d+ specialized agent personas\*\*/g, `synchronizes **${agentCount} specialized agent personas**`);
95
+ content = content.replace(/\* \*\*Specialized Agent Personas\*\*:\s*\d+\s*predefined roles/g, `* **Specialized Agent Personas**: ${agentCount} predefined roles`);
96
+ content = content.replace(/(\|\s*`agents\/`\s*\|\s*`~\/\.<tool>\/agents\/`\s*\|\s*)\d+(\s*specialized agent persona)/g, `$1${agentCount}$2`);
97
+ content = content.replace(/(Heimdall organizes capabilities into \*\*5 Core Multi-Skill Suites \(37 modules\)\*\* and \*\*)\d+(\s*Standalone Toolkits \()\d+(\s*modules\)\*\*)/g, `$1${standaloneCount}$2${standaloneCount}$3`);
98
+ content = content.replace(/(#### Standalone Toolkits \()\d+(\s*Curated Toolkits \/ \s*)\d+(\s*Modules\))/g, `$1${standaloneCount}$2${standaloneCount}$3`);
99
+
100
+ if (content !== orig) {
101
+ if (!dryRun) fs.writeFileSync(readmePath, content, 'utf8');
102
+ modified = true;
103
+ }
104
+ }
105
+
106
+ // 5. Sync README.pt-BR.md
107
+ const readmePtPath = path.join(rootDir, 'README.pt-BR.md');
108
+ if (fs.existsSync(readmePtPath)) {
109
+ let content = fs.readFileSync(readmePtPath, 'utf8');
110
+ const orig = content;
111
+
112
+ content = content.replace(/skills-\d+%20toolkits%20%28\d+%20m%C3%B3dulos%29/g, `skills-${suiteCount}%20toolkits%20%28${skillCount}%20m%C3%B3dulos%29`);
113
+ content = content.replace(/Skills: \d+ Toolkits \(\d+ Módulos\)/g, `Skills: ${suiteCount} Toolkits (${skillCount} Módulos)`);
114
+ content = content.replace(/#inventario-de-skills-\d+-modulos-em-\d+-toolkits/g, `#inventario-de-skills-${skillCount}-modulos-em-${suiteCount}-toolkits`);
115
+ content = content.replace(/<a id="inventario-de-skills-\d+-modulos-em-\d+-toolkits"><\/a>/g, `<a id="inventario-de-skills-${skillCount}-modulos-em-${suiteCount}-toolkits"></a>`);
116
+ content = content.replace(/### Inventário de Skills \(\d+ Módulos em \d+ Toolkits\)/g, `### Inventário de Skills (${skillCount} Módulos em ${suiteCount} Toolkits)`);
117
+ content = content.replace(/\*\*\d+ skills modulares\*\*/g, `**${skillCount} skills modulares**`);
118
+ content = content.replace(/\* \*\*Skills Modulares\*\*:\s*\d+\s*capacidades/g, `* **Skills Modulares**: ${skillCount} capacidades`);
119
+ content = content.replace(/(\|\s*`skills\/`\s*\|\s*`~\/\.<ferramenta>\/skills\/`\s*\|\s*)\d+(\s*toolkits de domínio)/g, `$1${skillCount}$2`);
120
+ content = content.replace(/(\|\s*\*\*`full`\*\*\s*\*\(Padrão\)\*\s*\|\s*)\d+(\s*\|\s*)\d+(\s*\|)/g, `$1${skillCount}$2${agentCount}$3`);
121
+ content = content.replace(/agents-\d+%20predefinidos/g, `agents-${agentCount}%20predefinidos`);
122
+ content = content.replace(/alt="Agentes: \d+ Predefinidos"/g, `alt="Agentes: ${agentCount} Predefinidos"`);
123
+ content = content.replace(/#\d+-personas-de-agentes-predefinidas/g, `#${agentCount}-personas-de-agentes-predefinidas`);
124
+ content = content.replace(/<a id="\d+-personas-de-agentes-predefinidas"><\/a>/g, `<a id="${agentCount}-personas-de-agentes-predefinidas"></a>`);
125
+ content = content.replace(/### \d+ Personas de Agentes Predefinidas/g, `### ${agentCount} Personas de Agentes Predefinidas`);
126
+ content = content.replace(/sincroniza \*\*\d+ personas de agentes especializados\*\*/g, `sincroniza **${agentCount} personas de agentes especializados**`);
127
+ content = content.replace(/\* \*\*Personas de Agentes Especializados\*\*:\s*\d+\s*papéis predefinidos/g, `* **Personas de Agentes Especializados**: ${agentCount} papéis predefinidos`);
128
+ content = content.replace(/(\|\s*`agents\/`\s*\|\s*`~\/\.<ferramenta>\/agents\/`\s*\|\s*)\d+(\s*definições de personas)/g, `$1${agentCount}$2`);
129
+ content = content.replace(/(O Heimdall organiza as capacidades em \*\*5 Suítes Multi-Skill Principais \(37 módulos\)\*\* e \*\*)\d+(\s*Toolkits Independentes \()\d+(\s*módulos\)\*\*)/g, `$1${standaloneCount}$2${standaloneCount}$3`);
130
+ content = content.replace(/(#### Toolkits Independentes \()\d+(\s*Toolkits Curados \/ \s*)\d+(\s*Módulos\))/g, `$1${standaloneCount}$2${standaloneCount}$3`);
131
+
132
+ if (content !== orig) {
133
+ if (!dryRun) fs.writeFileSync(readmePtPath, content, 'utf8');
134
+ modified = true;
135
+ }
136
+ }
137
+
138
+ // 6. Sync setup.mjs
139
+ const setupMjsPath = path.join(rootDir, 'setup.mjs');
140
+ if (fs.existsSync(setupMjsPath)) {
141
+ let content = fs.readFileSync(setupMjsPath, 'utf8');
142
+ const orig = content;
143
+
144
+ content = content.replace(/Skill profile tier: full \(\d+\)/g, `Skill profile tier: full (${skillCount})`);
145
+ content = content.replace(/All \d+ curated skills/g, `All ${skillCount} curated skills`);
146
+
147
+ if (content !== orig) {
148
+ if (!dryRun) fs.writeFileSync(setupMjsPath, content, 'utf8');
149
+ modified = true;
150
+ }
151
+ }
152
+
153
+ return { skillCount, suiteCount, modified };
154
+ } catch (err) {
155
+ console.error('Error during catalog count synchronization:', err);
156
+ return null;
157
+ }
158
+ }
159
+
160
+ module.exports = {
161
+ syncCatalogCounts
162
+ };
@@ -0,0 +1,57 @@
1
+ 'use strict';
2
+
3
+ const fs = require('node:fs');
4
+ const path = require('node:path');
5
+
6
+ /**
7
+ * Updates Hermes Agent's config.yaml to set model context_length to maximum allowable tokens.
8
+ * Performs surgical in-place replacement preserving all comments, indentation, and structure.
9
+ */
10
+ function updateHermesConfigContext(hermesDir, modelContextMap, dryRun = false) {
11
+ const configPath = path.join(hermesDir, 'config.yaml');
12
+ if (!fs.existsSync(configPath)) return false;
13
+
14
+ try {
15
+ let content = fs.readFileSync(configPath, 'utf8');
16
+ let modified = false;
17
+
18
+ // Fix base_url if it's missing the /v1 suffix (Hermes requires /v1 for model discovery)
19
+ const baseUrlRegex = /(base_url:[ \t]*["']https:\/\/ghostcli\.cloud)(["'])/g;
20
+ if (baseUrlRegex.test(content)) {
21
+ content = content.replace(baseUrlRegex, '$1/v1$2');
22
+ modified = true;
23
+ }
24
+
25
+ for (const [modelId, maxTokens] of Object.entries(modelContextMap)) {
26
+ if (!maxTokens) continue;
27
+
28
+ // Escape dots or special chars in modelId (e.g. claude-fable-5.1)
29
+ const escapedModel = modelId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
30
+
31
+ // Match pattern like:
32
+ // claude-opus-5-5:
33
+ // context_length: 256000
34
+ const regex = new RegExp(`(${escapedModel}:[\\r\\n]+(?:[ \\t]+.*[\\r\\n]+)*?[ \\t]+context_length:[ \\t]*)(\\d+)`, 'm');
35
+ const match = content.match(regex);
36
+ if (match) {
37
+ const currentTokens = parseInt(match[2], 10);
38
+ if (currentTokens < maxTokens) {
39
+ content = content.replace(regex, `$1${maxTokens}`);
40
+ modified = true;
41
+ }
42
+ }
43
+ }
44
+
45
+ if (modified && !dryRun) {
46
+ fs.writeFileSync(configPath, content, 'utf8');
47
+ }
48
+
49
+ return modified;
50
+ } catch {
51
+ return false;
52
+ }
53
+ }
54
+
55
+ module.exports = {
56
+ updateHermesConfigContext
57
+ };
@@ -0,0 +1,123 @@
1
+ 'use strict';
2
+
3
+ /**
4
+ * Authoritative Canonical Context Mappings (Max Capacity)
5
+ * Derived from playbooks/06-model-registry-matrix.md
6
+ */
7
+ const CANONICAL_MODEL_CONTEXTS = {
8
+ // Google Gemini Direct
9
+ 'gemini-4': 2097152,
10
+ 'gemini-4-argon': 2097152,
11
+ 'argon': 2097152,
12
+ 'gemini-3.1-pro': 2097152,
13
+ 'gemini-3.8-flash': 1048576,
14
+
15
+ // GhostCLI / Custom Proxies (Max extended capacity)
16
+ 'claude-opus-5-5': 1000000,
17
+ 'claude-sonnet-5': 1000000,
18
+ 'claude-fable-5.1': 1000000,
19
+ 'z-ai/glm-5.3': 1000000,
20
+ 'glm-5.3': 1000000,
21
+ 'gpt-6-astra': 1000000,
22
+ 'astra': 1000000
23
+ };
24
+
25
+ /**
26
+ * Normalizes token numbers into an integer token count and human-readable label.
27
+ */
28
+ function normalizeContextTokens(raw) {
29
+ let tokens = 0;
30
+ if (typeof raw === 'number') {
31
+ tokens = Math.round(raw);
32
+ } else if (typeof raw === 'string') {
33
+ const trimmed = raw.trim().toUpperCase();
34
+ if (trimmed.endsWith('M')) {
35
+ const num = parseFloat(trimmed.replace('M', ''));
36
+ tokens = Math.round(num * 1000000);
37
+ } else if (trimmed.endsWith('K')) {
38
+ const num = parseFloat(trimmed.replace('K', ''));
39
+ tokens = Math.round(num * 1000);
40
+ } else {
41
+ tokens = parseInt(trimmed, 10) || 0;
42
+ }
43
+ }
44
+
45
+ if (tokens <= 0) {
46
+ tokens = 131072; // 128K baseline default
47
+ }
48
+
49
+ let label = '';
50
+ if (tokens >= 1900000) {
51
+ label = '2M';
52
+ } else if (tokens >= 950000) {
53
+ label = '1M';
54
+ } else if (tokens === 131072 || (tokens >= 125000 && tokens <= 135000)) {
55
+ label = '128K';
56
+ } else if (tokens === 262144 || (tokens >= 250000 && tokens <= 265000)) {
57
+ label = '256K';
58
+ } else {
59
+ label = `${Math.round(tokens / 1000)}K`;
60
+ }
61
+
62
+ return { tokens, label };
63
+ }
64
+
65
+ /**
66
+ * Resolves the maximum context window for a model.
67
+ * Prioritizes maximum allowable context (e.g. 1M extended capacity for Claude 5.5/5),
68
+ * falling back to canonical matrices when remote API does not specify it.
69
+ */
70
+ function resolveModelMaxContext(model, options = {}) {
71
+ const prioritizeMax = options.prioritizeMax !== false;
72
+ const modelId = typeof model === 'string' ? model : (model?.id || model?.slug || '');
73
+ const cleanId = modelId.toLowerCase().trim();
74
+
75
+ const canonicalTokens = CANONICAL_MODEL_CONTEXTS[cleanId] ||
76
+ CANONICAL_MODEL_CONTEXTS[cleanId.split('/').pop()] ||
77
+ null;
78
+
79
+ let rawContext = null;
80
+ if (typeof model === 'object' && model !== null) {
81
+ rawContext = model.context_window || model.max_context_tokens || model.context;
82
+ }
83
+
84
+ // If user requests maximum context and canonical defines an extended limit (e.g. 1M vs 256K)
85
+ if (prioritizeMax && canonicalTokens) {
86
+ return normalizeContextTokens(canonicalTokens);
87
+ }
88
+
89
+ if (rawContext) {
90
+ return normalizeContextTokens(rawContext);
91
+ }
92
+
93
+ if (canonicalTokens) {
94
+ return normalizeContextTokens(canonicalTokens);
95
+ }
96
+
97
+ return normalizeContextTokens(131072); // 128K safe fallback
98
+ }
99
+
100
+ /**
101
+ * Resolves the live /v1/models endpoint URL when a custom proxy/vendor endpoint is configured.
102
+ * Returns null when only official 1P endpoints (Anthropic, OpenAI, Google OAuth) are active.
103
+ */
104
+ function resolveCustomModelsEndpoint(endpoints = {}) {
105
+ const candidates = [endpoints.claude, endpoints.codex];
106
+ for (const raw of candidates) {
107
+ if (!raw || typeof raw !== 'string' || !raw.startsWith('http')) continue;
108
+ if (raw.includes('api.anthropic.com') || raw.includes('api.openai.com')) continue;
109
+ if (raw.includes('ghostcli.cloud')) {
110
+ return 'https://ghostcli.cloud/v1/models';
111
+ }
112
+ const base = raw.replace(/\/+$/, '');
113
+ return base.endsWith('/v1') ? `${base}/models` : (base.endsWith('/models') ? base : `${base}/v1/models`);
114
+ }
115
+ return null;
116
+ }
117
+
118
+ module.exports = {
119
+ CANONICAL_MODEL_CONTEXTS,
120
+ normalizeContextTokens,
121
+ resolveModelMaxContext,
122
+ resolveCustomModelsEndpoint
123
+ };
@@ -0,0 +1,94 @@
1
+ 'use strict';
2
+
3
+ const fs = require('node:fs');
4
+ const path = require('node:path');
5
+ const os = require('node:os');
6
+
7
+ const EXCLUDED_PATTERNS = [
8
+ '\\windows\\',
9
+ '\\program files\\',
10
+ '\\program files (x86)\\',
11
+ '\\programdata\\',
12
+ '/usr/sbin',
13
+ '/sbin',
14
+ '\\powershell',
15
+ 'jdk',
16
+ 'jre',
17
+ 'javapath',
18
+ 'oracle',
19
+ 'antigravity-cli',
20
+ '\\appdata\\local\\programs\\',
21
+ '\\appdata\\local\\microsoft\\windowsapps',
22
+ '\\appdata\\local\\agy\\',
23
+ '\\appdata\\local\\hermes\\',
24
+ '\\.codex\\packages\\',
25
+ '\\git\\cmd',
26
+ '\\git\\bin',
27
+ '\\git\\usr\\bin',
28
+ '\\nodejs',
29
+ '\\dotnet'
30
+ ];
31
+
32
+ function isExcludedPath(lowerPath) {
33
+ const normalized = lowerPath.replace(/\//g, '\\');
34
+ return EXCLUDED_PATTERNS.some(pattern => normalized.includes(pattern) || lowerPath.includes(pattern));
35
+ }
36
+
37
+ function scoreCandidate(resolvedPath) {
38
+ const lower = resolvedPath.toLowerCase().replace(/\//g, '\\');
39
+ let score = 0;
40
+
41
+ try {
42
+ const files = fs.readdirSync(resolvedPath);
43
+ if (files.some(f => f === 'heimdall.ps1' || f === 'heimdall.cmd' || f === 'claude-bridge.ps1' || f === 'gemini-bridge.ps1')) {
44
+ score += 100;
45
+ }
46
+ } catch {}
47
+
48
+ if (lower.endsWith('\\tools') || lower.includes('\\tools\\')) score += 50;
49
+ if (lower.includes('heimdall')) score += 40;
50
+ if (lower.endsWith('\\.local\\bin')) score += 30;
51
+ if (lower.includes('\\apps\\')) score += 20;
52
+
53
+ return score;
54
+ }
55
+
56
+ function detectPathCandidates(pathEnv = process.env.PATH || '', userHome = os.homedir()) {
57
+ const rawDirs = pathEnv.split(path.delimiter).map(d => d.trim()).filter(Boolean);
58
+ const candidates = [];
59
+ const seen = new Set();
60
+
61
+ for (const raw of rawDirs) {
62
+ try {
63
+ const resolved = path.resolve(raw);
64
+ const lower = resolved.toLowerCase();
65
+ if (seen.has(lower)) continue;
66
+ seen.add(lower);
67
+
68
+ if (fs.existsSync(resolved) && !isExcludedPath(lower)) {
69
+ const isToolLike = lower.includes('tool') ||
70
+ lower.includes('bin') ||
71
+ lower.includes('.local') ||
72
+ lower.includes('apps') ||
73
+ lower.includes('npm') ||
74
+ lower.includes('cargo') ||
75
+ lower.includes('heimdall');
76
+ if (isToolLike) {
77
+ candidates.push(resolved);
78
+ }
79
+ }
80
+ } catch {}
81
+ }
82
+
83
+ candidates.sort((a, b) => scoreCandidate(b) - scoreCandidate(a));
84
+
85
+ if (candidates.length === 0) {
86
+ candidates.push(path.join(userHome, '.heimdall', 'bin'));
87
+ }
88
+
89
+ return candidates;
90
+ }
91
+
92
+ module.exports = {
93
+ detectPathCandidates
94
+ };
package/package.json CHANGED
@@ -1,11 +1,11 @@
1
1
  {
2
2
  "name": "heimdall-agent",
3
- "version": "1.0.0",
3
+ "version": "1.1.0",
4
4
  "description": "Autonomous multi-agent engineering sentinel & bootstrapper. Synchronizes specialized agent personas, curated skills, and universal doctrine across Google Antigravity, Claude Code, OpenAI Codex CLI, Hermes Agent, OpenClaw, and Claude Desktop.",
5
5
  "type": "module",
6
6
  "bin": {
7
- "heimdall": "./setup.mjs",
8
- "heimdall-agent": "./setup.mjs"
7
+ "heimdall": "setup.mjs",
8
+ "heimdall-agent": "setup.mjs"
9
9
  },
10
10
  "files": [
11
11
  "setup.mjs",
@@ -16,14 +16,18 @@
16
16
  "commands",
17
17
  "hooks",
18
18
  "tools",
19
+ "lib",
19
20
  "config",
20
21
  "docs",
21
22
  "README.md",
22
23
  "LICENSE"
23
24
  ],
24
25
  "scripts": {
26
+ "test": "node --test test/*.test.mjs",
25
27
  "setup": "node setup.mjs",
26
28
  "audit": "node setup.mjs --audit",
29
+ "sync": "node setup.mjs sync",
30
+ "sync-models": "node setup.mjs sync-models",
27
31
  "uninstall": "node setup.mjs --uninstall",
28
32
  "minimal": "node setup.mjs --profile minimal",
29
33
  "full": "node setup.mjs --profile full"
@@ -35,7 +35,20 @@ Before generating any code, creating plans, or taking action on any user request
35
35
  - Declare your professional recommendation with clear reasoning.
36
36
 
37
37
  4. **Hard Gate**:
38
- - MANDATORY VISIBLE OUTPUT: Output the Scope, Probing Questions, and Alternatives explicitly in user-visible chat markdown. Never swallow them in internal thinking/scratchpads or output a bare "awaiting answers" message.
38
+ - MANDATORY VISIBLE OUTPUT (ANTI-PATTERN BAN): NEVER keep the questions or alternatives inside internal thinking/scratchpads. NEVER output a bare "awaiting answers..." blocker message. You MUST render the Scope, Questions, and Alternatives explicitly in user-visible chat markdown using this exact template:
39
+ ```markdown
40
+ ### 1. Scope Classification
41
+ - **Scope**: [Spike / Bounded / Architectural]
42
+
43
+ ### 2. Probing Questions
44
+ 1. [Question 1: edge cases / failure modes]
45
+ 2. [Question 2: limits / boundary conditions]
46
+ 3. [Question 3: integration / performance constraints]
47
+
48
+ ### 3. Concrete Alternatives
49
+ - **Alternative 1**: [Description + architectural trade-offs]
50
+ - **Alternative 2**: [Description + architectural trade-offs]
51
+ ```
39
52
  - STOP and wait for the user to answer and select an approach ONLY AFTER rendering the questions in full.
40
53
  - Only after receiving explicit alignment may you proceed to planning or implementation.
41
54
  ```
@@ -19,13 +19,14 @@
19
19
  - Implement the minimal fix until the test turns green.
20
20
 
21
21
  ## 3. Deep Verification (Never Accept Shallow Checkboxes)
22
- - Verification is NOT a single unit test or a superficial DOM row count.
22
+ - STRICT ZERO DEV-SERVER RULE: NEVER spin up or run a development server (`npm run dev`, `vite`, `next dev`, `live-server`, `python manage.py runserver`, etc.) to test, verify, or make things work. All verification commands must be terminating, non-interactive CLI executions (`npm test`, `npm run build`, `npm run typecheck`, `pytest`, `oxlint`, etc.).
23
23
  - In UI applications (e.g. Playwright):
24
+ - Run tests strictly against pre-built static artifacts or against a pre-existing server already launched by the user outside the agent session. Never spawn dev servers from an agent session.
24
25
  - Always assert visible non-zero bounding box (`expect(element).toBeVisible()`).
25
26
  - Verify state transitions, loading skeletons, and error toast lifecycles.
26
27
  - Verify layout integrity at standard desktop and mobile viewports.
27
28
  - In API applications:
28
29
  - Test negative payloads (null, malformed, unauthorized).
29
30
  - Verify database transaction rollbacks and audit logs.
30
- - Never claim work is complete without displaying verifiable command output.
31
+ - Never claim work is complete without displaying verifiable command output from terminating runs.
31
32
  ```
@@ -34,9 +34,9 @@ For Tier 2 reviews, all findings must be tracked in an authoritative ledger:
34
34
  4. If round returns `"No findings"` AND all previous items are Resolved/Rebutted -> **Clean Exit**.
35
35
  5. If 5 rounds are reached with open Blockers -> **Halt and Escalate** to the user with the complete ledger. Never commit unverified code.
36
36
 
37
- ## 4. Adaptive Execution Engine (Bridge vs. Same-Model Fallback)
38
- - **Primary Route (Cross-Model Bridge)**: If multi-model bridge scripts (`claude-bridge.ps1`, `gemini-bridge.ps1`, `codex-bridge.ps1`) and active credentials exist in the user's environment, dispatch an independent model as the Goldfish reviewer.
39
- - **Graceful Fallback (Same-Model Stateless Goldfish)**: If bridge tools or credentials are absent, fire a fresh, isolated child subagent on the current harness and model with zero conversational context. The stateless Goldfish discipline is strictly preserved.
37
+ ## 4. Adaptive Execution Engine (Herdr Multiplexing vs. Same-Model Fallback)
38
+ - **Primary Route in Herdr (Native Herdr Agent)**: When running inside Herdr (`$env:HERDR_ENV = "1"`), orchestrate the Goldfish reviewer directly via the `herdr` skill (`herdr agent start reviewer --kind <claude|codex|agy> --pane <id>` and `herdr agent prompt reviewer "..." --wait`). Re-use live idle agents first.
39
+ - **Graceful Fallback (Same-Model Stateless Goldfish)**: If outside Herdr or peer agents are unavailable, fire a fresh, isolated child subagent on the current harness and model with zero conversational context. The stateless Goldfish discipline is strictly preserved.
40
40
 
41
41
  ## 5. Adversarial Scrutiny & Silent Failure Hunter Checklist
42
42
  - [ ] **Empty Catch Blocks**: Does any `catch (e) {}` or `.catch(() => [])` swallow exceptions without logging, tracing, or propagation?
@@ -2,6 +2,15 @@
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
@@ -11,6 +20,7 @@
11
20
  - [x] `brainstorming` — Intent discovered, assumptions surfaced, tradeoffs evaluated
12
21
  - [x] `karpathy-guidelines` — Simplicity first, surgical edits, no speculative bloat
13
22
  - [x] `antislop` — Clean comments, no AI boilerplate, accessible contrast
23
+ - [x] `communication-doctrine` — BLUF macro layout, STE imperative steps (<=20 words), zero vague qualifiers
14
24
  - [x] `taste-skill` — [Required for UI / Features] Design Read declared, design system tokens enforced
15
25
 
16
26
  ## 2. Context & Design Read (Required for UI / Features)
@@ -21,9 +31,9 @@
21
31
  ## 3. Multi-Agent Orchestration & Model Allocation Matrix
22
32
  | Task ID | Phase & Task Description | Assigned Model | Effort Level | Selection Rationale | Cross-Reviewer & Tool Command |
23
33
  | :--- | :--- | :--- | :--- | :--- | :--- |
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`) |
34
+ | T1 | Phase 1: Scaffolding | claude-sonnet-5 | high | Schema & component structure | Gemini 3.8 Flash (`herdr agent prompt gemini-reviewer`) |
35
+ | T2 | Phase 2: Implementation | claude-sonnet-5 | high | Core business logic & UI | Gemini 3.8 Flash (`herdr agent prompt gemini-reviewer`) |
36
+ | T3 | Phase 3: Playwright E2E | claude-sonnet-5 | high | Full user journey verification | Gemini 3.8 Flash (`herdr agent prompt gemini-reviewer`) |
27
37
 
28
38
  ## 4. Multi-Phase Implementation Plan
29
39
  ### Phase 1: Architecture & Scaffolding
@@ -32,21 +42,23 @@
32
42
  ### Phase 4: Review, Purge & Handoff
33
43
 
34
44
  ## 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"`
45
+ - In Herdr (`HERDR_ENV=1`), validate tasks directly via peer agent prompts:
46
+ - Tasks executed by Claude -> Validate with Gemini or Codex:
47
+ `herdr agent prompt gemini-reviewer "Review git diff for security regressions and type errors." --wait --timeout 120000`
48
+ `herdr agent prompt codex-reviewer "Review git diff for security regressions and boundary conditions." --wait --timeout 120000`
49
+ - Tasks executed by Gemini -> Validate with Claude or Codex:
50
+ `herdr agent prompt claude-reviewer "Review git diff for security regressions and type errors." --wait --timeout 120000`
51
+ `herdr agent prompt codex-reviewer "Review git diff for security regressions and boundary conditions." --wait --timeout 120000`
52
+ - Tasks executed by Codex -> Validate with Claude or Gemini:
53
+ `herdr agent prompt claude-reviewer "Review git diff for security regressions and type errors." --wait --timeout 120000`
54
+ `herdr agent prompt gemini-reviewer "Review git diff for security regressions and type errors." --wait --timeout 120000`
44
55
 
45
56
  ## 6. Orchestrator Heartbeat
46
57
  - Orchestrator monitors progress every 3 minutes.
47
58
 
48
59
  ## 7. Verification Harness
49
- - **Playwright E2E Primary Gate**: Real browser execution (DOM state, visibility assertions, non-zero bounding box checks).
60
+ - **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`).
61
+ - **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
62
  - **Backend-with-UI-Impact Rule**: Backend tasks affecting user views must include browser verification.
51
63
  - **Rejection of Pseudo-Verification**: No task sign-off on `tsc`, `curl`, `grep`, or container health alone.
52
64
  - **Environment Detection**: Confirm Playwright presence; if absent, ask user during planning for preferred setup.
@@ -60,7 +72,7 @@
60
72
  ### Section Requirements
61
73
  1. **Section 1: Active Skills & Directives Checklist**:
62
74
  - Must explicitly list all active skills governing execution.
63
- - Baseline minimum: `brainstorming`, `karpathy-guidelines`, `antislop`.
75
+ - Baseline minimum: `brainstorming`, `karpathy-guidelines`, `antislop`, `communication-doctrine`.
64
76
  - Any UI, styling, or frontend surface requires `taste-skill`.
65
77
  2. **Section 2: Context & Design Read**:
66
78
  - Required for any user-facing feature or UI change.
@@ -69,18 +81,20 @@
69
81
  3. **Section 3: Model Allocation Matrix**:
70
82
  - Decomposes plan into discrete tasks with explicit task IDs.
71
83
  - 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.
84
+ - Declares the cross-reviewer harness and Herdr prompt command.
73
85
  4. **Section 4: Multi-Phase Implementation Plan**:
74
86
  - Organized into logical progression (Scaffolding -> Core Implementation -> E2E Verification -> Review/Handoff).
75
87
  - Strict TDD: failing test first, minimal code, passing test, self-review.
88
+ - 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
89
  5. **Section 5: Symmetric & Tri-Directional Cross-Model Validation Loop**:
77
- - Defines validation commands using shared bridge scripts in `C:\Apps\tools\`.
90
+ - Defines validation commands using native Herdr agent commands.
78
91
  - Claude tasks validated by Gemini/Codex; Gemini tasks validated by Claude/Codex; Codex tasks validated by Claude/Gemini.
79
92
  6. **Section 6: Orchestrator Heartbeat**:
80
93
  - Cadence for monitoring task progress, status checks, and liveness during subagent runs.
81
94
  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).
95
+ - Zero Dev-Server policy: No agent may start background or dev servers (`npm run dev`, `vite`, `next dev`).
96
+ - Primary verification standard is full Playwright E2E with real DOM state and non-zero bounding box assertions against pre-existing servers or static builds.
97
+ - Enforces the strict ban on pseudo-verification (`curl`, `grep`, `tsc --noEmit` alone, container status).
84
98
  - Mandates browser verification for backend changes with UI impact.
85
99
 
86
100
  ### Effort Constraint Rules