heimdall-agent 1.1.0 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (60) hide show
  1. package/README.md +101 -31
  2. package/README.pt-BR.md +124 -40
  3. package/agents/code-sentinel.md +7 -1
  4. package/agents/frontend-designer.md +6 -1
  5. package/agents/modernizer.md +8 -3
  6. package/agents/orchestrator.md +22 -8
  7. package/agents/reviewer.md +3 -1
  8. package/config/agents.json +177 -5
  9. package/config/mcp.json +1 -1
  10. package/config/mcp.resolved.json +74 -0
  11. package/config/mcp.template.json +85 -0
  12. package/config/models.json +70 -0
  13. package/config/profiles.json +4 -3
  14. package/config/skills.json +321 -93
  15. package/docs/SKILLS.md +158 -75
  16. package/docs/designs/old/2026-11-16 upstream-skill-sync-and-provenance-links.md +60 -0
  17. package/docs/runs/skill-audit/2026-11-12-compare-report.json +1028 -0
  18. package/docs/runs/skill-audit/2026-11-12-upstream-audit.json +275 -0
  19. package/doctrine/AGENTS.md +7 -4
  20. package/hooks/heimdall-hook.cjs +16 -1
  21. package/hooks/hooks.json +11 -0
  22. package/lib/catalog-sync.cjs +8 -3
  23. package/lib/model-context.cjs +50 -1
  24. package/lib/model-router.cjs +294 -0
  25. package/package.json +1 -1
  26. package/playbooks/01-interactive-grilling-gate.md +14 -10
  27. package/playbooks/03-adversarial-code-review.md +12 -4
  28. package/playbooks/05-canonical-plan-template.md +8 -13
  29. package/playbooks/06-model-registry-matrix.md +27 -19
  30. package/readme.html +1006 -0
  31. package/setup.mjs +317 -206
  32. package/skills/antislop-copywriting/SKILL.md +36 -1
  33. package/skills/brainstorming/SKILL.md +60 -38
  34. package/skills/codebase-design/DEEPENING.md +37 -0
  35. package/skills/codebase-design/DESIGN-IT-TWICE.md +44 -0
  36. package/skills/codebase-design/SKILL.md +114 -0
  37. package/skills/communication-doctrine/SKILL.md +2 -2
  38. package/skills/domain-modeling/ADR-FORMAT.md +47 -0
  39. package/skills/domain-modeling/GLOSSARY-FORMAT.md +60 -0
  40. package/skills/domain-modeling/SKILL.md +74 -0
  41. package/skills/executing-plans/SKILL.md +6 -4
  42. package/skills/grill-me/SKILL.md +65 -0
  43. package/skills/handoff/SKILL.md +77 -0
  44. package/skills/improve-codebase-architecture/HTML-REPORT.md +123 -0
  45. package/skills/improve-codebase-architecture/SKILL.md +71 -0
  46. package/skills/mcp-cleanup/SKILL.md +61 -0
  47. package/skills/mcp-sync/SKILL.md +58 -0
  48. package/skills/modern-web-guidance/SKILL.md +90 -0
  49. package/skills/owasp-security/reference/config-and-supply-chain.md +346 -344
  50. package/skills/owasp-security/reference/languages.md +378 -372
  51. package/skills/owasp-security/reference/owasp-report.md +1144 -1140
  52. package/skills/owasp-security/reference/review-checklist.md +134 -132
  53. package/skills/ruminate/SKILL.md +140 -0
  54. package/skills/subagent-driven-development/SKILL.md +7 -4
  55. package/skills/taste-skill/SKILL.md +367 -534
  56. package/skills/to-spec/SKILL.md +75 -0
  57. package/skills/to-tickets/SKILL.md +105 -0
  58. package/skills/upstream-skill-sync/SKILL.md +46 -0
  59. package/skills/wayfinder/SKILL.md +128 -0
  60. package/skills/writing-plans/SKILL.md +1 -1
@@ -0,0 +1,294 @@
1
+ 'use strict';
2
+
3
+ const fs = require('node:fs');
4
+ const path = require('node:path');
5
+ const { resolveModelMaxContext } = require('./model-context.cjs');
6
+
7
+ /**
8
+ * Infers the model family/vendor from a model ID.
9
+ * Supports Anthropic, Google, OpenAI, Zhipu (GLM), Tencent (Hunyuan), Xiaomi (MiMo),
10
+ * and any future slash-prefixed or named provider.
11
+ */
12
+ function inferModelFamily(modelId) {
13
+ const id = (modelId || '').toLowerCase().trim();
14
+ if (!id) return 'unknown';
15
+ if (id.startsWith('claude-') || id.includes('anthropic')) return 'anthropic';
16
+ if (id.startsWith('gemini-') || id.includes('google')) return 'google';
17
+ if (id.startsWith('gpt-') || id.startsWith('o1') || id.startsWith('o3') || id.startsWith('o4') || id.includes('codex')) return 'openai';
18
+ if (id.startsWith('z-ai/') || id.includes('glm')) return 'z-ai';
19
+ if (id.startsWith('tencent/') || id.includes('hy4') || id.includes('hunyuan')) return 'tencent';
20
+ if (id.startsWith('xiaomimimo/') || id.includes('mimo')) return 'xiaomi';
21
+ if (id.includes('/')) return id.split('/')[0];
22
+ return id.split('-')[0] || 'unknown';
23
+ }
24
+
25
+ /**
26
+ * Classifies a model's capabilities, speed tier, and context capacity
27
+ * from its ID, displayName, description/specialization, and context window.
28
+ */
29
+ function classifyModelCapabilities(model, channel = 'ghostcli') {
30
+ const id = model?.id || model?.slug || '';
31
+ const displayName = model?.displayName || model?.display_name || id;
32
+ const text = `${id} ${displayName} ${model?.description || ''} ${model?.specialization || ''}`.toLowerCase();
33
+ const family = model?.family || inferModelFamily(id);
34
+ const resolvedCtx = resolveModelMaxContext(model, { prioritizeMax: true });
35
+
36
+ const isFast = /flash|fast|rápid|rapido|mini|lite|haiku|instant/.test(text);
37
+ const isUiCreative = /fable|design|ui|story|creative|visual|frontend/.test(text);
38
+ const isReasoning = /opus|pro|astra|reasoning|racioc[ií]nio|architect|frontier|gemini-4|hy4|mimo/.test(text);
39
+ const isAgentic = /agentic|ag[eê]ntic|c[oó]digo|code|sonnet|glm|astra|mimo|hy4/.test(text);
40
+ const isLongContext = resolvedCtx.tokens >= 950000;
41
+
42
+ const traits = new Set();
43
+ if (isFast) traits.add('fast');
44
+ if (isUiCreative) traits.add('ui_creative');
45
+ if (isReasoning) traits.add('deep_reasoning');
46
+ if (isAgentic) traits.add('agentic_coding');
47
+ if (isLongContext) traits.add('long_context');
48
+ if (traits.size === 0) traits.add('general');
49
+
50
+ return {
51
+ id,
52
+ displayName,
53
+ family,
54
+ channel,
55
+ contextLabel: resolvedCtx.label,
56
+ contextTokens: resolvedCtx.tokens,
57
+ description: model?.description || model?.specialization || '',
58
+ traits: [...traits],
59
+ isFast,
60
+ isUiCreative,
61
+ isReasoning,
62
+ isAgentic,
63
+ isLongContext
64
+ };
65
+ }
66
+
67
+ /**
68
+ * Flattens and deduplicates models from config/models.json into classified entries.
69
+ */
70
+ function collectCatalogModels(catalog = {}) {
71
+ const byId = new Map();
72
+ const sources = [
73
+ ['google', catalog.google || []],
74
+ ['ghostcli', catalog.ghostcli || []],
75
+ ['custom_proxies', catalog.custom_proxies || []]
76
+ ];
77
+
78
+ for (const [channel, list] of sources) {
79
+ for (const raw of list) {
80
+ if (!raw || !raw.id) continue;
81
+ if (!byId.has(raw.id)) {
82
+ byId.set(raw.id, classifyModelCapabilities(raw, channel));
83
+ }
84
+ }
85
+ }
86
+ return [...byId.values()];
87
+ }
88
+
89
+ const TIER_SCORING_RULES = {
90
+ deep_reasoning: (m) =>
91
+ (m.isReasoning ? 40 : 0) +
92
+ (m.isAgentic ? 15 : 0) +
93
+ (m.isLongContext ? 10 : 0) +
94
+ (/opus|gemini-4|astra/.test(m.id.toLowerCase()) ? 25 : 0) +
95
+ (m.isFast ? -15 : 0),
96
+ high_polish_vision: (m) =>
97
+ (m.isUiCreative ? 50 : 0) +
98
+ (m.isAgentic ? 20 : 0) +
99
+ (/sonnet|fable|flash|mimo/.test(m.id.toLowerCase()) ? 15 : 0),
100
+ responsive_flex_safety: (m) =>
101
+ (m.isUiCreative ? 35 : 0) +
102
+ (m.isFast ? 20 : 0) +
103
+ (m.isAgentic ? 20 : 0),
104
+ fast_verification: (m) =>
105
+ (m.isFast ? 45 : 0) +
106
+ (m.isAgentic ? 25 : 0) +
107
+ (/flash|sonnet|mimo|glm/.test(m.id.toLowerCase()) ? 15 : 0),
108
+ deep_assurance_audit: (m) =>
109
+ (m.isReasoning ? 45 : 0) +
110
+ (m.isLongContext ? 15 : 0) +
111
+ (/opus|gemini-4|astra|hy4/.test(m.id.toLowerCase()) ? 20 : 0) +
112
+ (m.isFast ? -15 : 0),
113
+ schema_migration_safety: (m) =>
114
+ (m.isReasoning ? 35 : 0) +
115
+ (m.contextTokens >= 1900000 ? 20 : (m.isLongContext ? 10 : 0)) +
116
+ (m.isAgentic ? 20 : 0),
117
+ surgical_restraint: (m) =>
118
+ (m.isFast ? 30 : 0) +
119
+ (m.isAgentic ? 30 : 0) +
120
+ (/sonnet|flash|glm|mimo/.test(m.id.toLowerCase()) ? 15 : 0),
121
+ adversarial_diff_eval: (m) =>
122
+ (m.isReasoning ? 45 : 0) +
123
+ (m.isAgentic ? 20 : 0) +
124
+ (/opus|gemini-4|astra|hy4|mimo/.test(m.id.toLowerCase()) ? 15 : 0),
125
+ legacy_migration_safety: (m) =>
126
+ (m.isLongContext ? 25 : 0) +
127
+ (m.isAgentic ? 25 : 0) +
128
+ (m.isReasoning ? 20 : 0)
129
+ };
130
+
131
+ /**
132
+ * Ranks all available models for a given agent capabilityTier and selects
133
+ * diverse cross-family models for adversarial review.
134
+ */
135
+ function rankModelsForCapabilityTier(capabilityTier, catalog) {
136
+ const models = Array.isArray(catalog) ? catalog : collectCatalogModels(catalog);
137
+ const scorer = TIER_SCORING_RULES[capabilityTier] || TIER_SCORING_RULES.surgical_restraint;
138
+
139
+ const scored = models
140
+ .map(m => ({ model: m, score: scorer(m) }))
141
+ .sort((a, b) => b.score - a.score || b.model.contextTokens - a.model.contextTokens || a.model.id.localeCompare(b.model.id));
142
+
143
+ // Pick top model per distinct family so non-Claude/Gemini/Codex models are surfaced
144
+ const topByFamily = new Map();
145
+ for (const { model } of scored) {
146
+ if (!topByFamily.has(model.family)) {
147
+ topByFamily.set(model.family, model);
148
+ }
149
+ }
150
+
151
+ const recommendedModels = [...topByFamily.values()].slice(0, 6).map(m => m.id);
152
+ const primary = scored[0]?.model;
153
+ const crossReviewers = [...topByFamily.values()]
154
+ .filter(m => !primary || m.family !== primary.family)
155
+ .slice(0, 4)
156
+ .map(m => m.id);
157
+
158
+ const pickFamily = (fam) => topByFamily.get(fam)?.id;
159
+ const vendorPreferences = {};
160
+ if (pickFamily('google')) vendorPreferences.gemini = pickFamily('google');
161
+ if (pickFamily('anthropic')) vendorPreferences.claude = pickFamily('anthropic');
162
+ if (pickFamily('openai')) vendorPreferences.codex = pickFamily('openai');
163
+
164
+ // Include non-legacy families dynamically (z-ai, tencent, xiaomi, etc.)
165
+ for (const [fam, model] of topByFamily.entries()) {
166
+ if (fam !== 'google' && fam !== 'anthropic' && fam !== 'openai') {
167
+ vendorPreferences[fam] = model.id;
168
+ }
169
+ }
170
+ vendorPreferences.default = 'inherit';
171
+
172
+ return { recommendedModels, crossReviewers, vendorPreferences };
173
+ }
174
+
175
+ /**
176
+ * Synchronizes config/agents.json with live models from config/models.json.
177
+ * Returns { modified: boolean, agentCount: number } or null if files are missing.
178
+ */
179
+ function syncAgentsWithModels(rootDir, dryRun = false) {
180
+ const modelsPath = path.join(rootDir, 'config', 'models.json');
181
+ const agentsPath = path.join(rootDir, 'config', 'agents.json');
182
+ if (!fs.existsSync(modelsPath) || !fs.existsSync(agentsPath)) return null;
183
+
184
+ try {
185
+ const catalog = JSON.parse(fs.readFileSync(modelsPath, 'utf8'));
186
+ const classified = collectCatalogModels(catalog);
187
+ if (classified.length === 0) return { modified: false, agentCount: 0 };
188
+
189
+ const rawAgents = fs.readFileSync(agentsPath, 'utf8');
190
+ const agentsConfig = JSON.parse(rawAgents);
191
+ const agentsMap = agentsConfig.agents || {};
192
+
193
+ let modified = false;
194
+ for (const agentDef of Object.values(agentsMap)) {
195
+ const { recommendedModels, crossReviewers, vendorPreferences } =
196
+ rankModelsForCapabilityTier(agentDef.capabilityTier, classified);
197
+
198
+ const nextVendor = JSON.stringify(vendorPreferences);
199
+ const prevVendor = JSON.stringify(agentDef.vendorPreferences || {});
200
+ const nextRec = JSON.stringify(recommendedModels);
201
+ const prevRec = JSON.stringify(agentDef.recommendedModels || []);
202
+ const nextCross = JSON.stringify(crossReviewers);
203
+ const prevCross = JSON.stringify(agentDef.crossReviewers || []);
204
+
205
+ if (nextVendor !== prevVendor || nextRec !== prevRec || nextCross !== prevCross) {
206
+ agentDef.vendorPreferences = vendorPreferences;
207
+ agentDef.recommendedModels = recommendedModels;
208
+ agentDef.crossReviewers = crossReviewers;
209
+ modified = true;
210
+ }
211
+ }
212
+
213
+ if (modified && !dryRun) {
214
+ fs.writeFileSync(agentsPath, JSON.stringify(agentsConfig, null, 2) + '\n', 'utf8');
215
+ }
216
+
217
+ return { modified, agentCount: Object.keys(agentsMap).length };
218
+ } catch {
219
+ return null;
220
+ }
221
+ }
222
+
223
+ /**
224
+ * Builds the Markdown table for Section 2 (GhostCLI Models) from live catalog entries.
225
+ */
226
+ function buildGhostCliMarkdownSection(ghostcliModels) {
227
+ const rows = ghostcliModels.map(m => {
228
+ const c = classifyModelCapabilities(m, 'ghostcli');
229
+ const spec = c.description || c.traits.join(', ');
230
+ const effort = c.isFast ? '`low`, `medium`, `high`' : '`low`, `medium`, `high`, `xhigh`';
231
+ return `| **${c.displayName}** | \`${c.id}\` | ${c.family} | ${c.contextLabel} | ${effort} | ${spec} |`;
232
+ });
233
+
234
+ return [
235
+ '<!-- heimdall:ghostcli-models:start -->',
236
+ 'All GhostCLI models are discovered dynamically via `heimdall sync` / `heimdall sync-models` and stored in `config/models.json`:',
237
+ '',
238
+ '| Model Name | Canonical Flag | Family | Context Window | Allowed Effort Levels | Specialization / Description |',
239
+ '| :--- | :--- | :--- | :--- | :--- | :--- |',
240
+ ...rows,
241
+ '',
242
+ '> [!NOTE]',
243
+ '> **Dynamic Model Registry**: Always resolve live model IDs from `config/models.json` or this table after `heimdall sync` / `heimdall sync-models`. Route tasks by **capability tier** across all available families (Anthropic, Google, OpenAI, GLM, Hunyuan, MiMo, etc.), not only Claude/Gemini/Codex.',
244
+ '<!-- heimdall:ghostcli-models:end -->'
245
+ ].join('\n');
246
+ }
247
+
248
+ /**
249
+ * Synchronizes playbooks/06-model-registry-matrix.md Section 2 with config/models.json.
250
+ * Returns { modified: boolean } or null if files are missing.
251
+ */
252
+ function syncModelRegistryPlaybook(rootDir, dryRun = false) {
253
+ const modelsPath = path.join(rootDir, 'config', 'models.json');
254
+ const playbookPath = path.join(rootDir, 'playbooks', '06-model-registry-matrix.md');
255
+ if (!fs.existsSync(modelsPath) || !fs.existsSync(playbookPath)) return null;
256
+
257
+ try {
258
+ const catalog = JSON.parse(fs.readFileSync(modelsPath, 'utf8'));
259
+ const ghostcliModels = catalog.ghostcli || catalog.custom_proxies || [];
260
+ if (ghostcliModels.length === 0) return { modified: false };
261
+
262
+ const orig = fs.readFileSync(playbookPath, 'utf8');
263
+ const generatedBlock = buildGhostCliMarkdownSection(ghostcliModels);
264
+
265
+ let updated = orig;
266
+ const markerRegex = /<!-- heimdall:ghostcli-models:start -->[\s\S]*?<!-- heimdall:ghostcli-models:end -->/;
267
+ if (markerRegex.test(updated)) {
268
+ updated = updated.replace(markerRegex, generatedBlock);
269
+ } else {
270
+ const sectionRegex = /(## 2\. GhostCLI Models[^\n]*\n\n)[\s\S]*?(\n---\n)/;
271
+ if (sectionRegex.test(updated)) {
272
+ updated = updated.replace(sectionRegex, `$1${generatedBlock}\n$2`);
273
+ }
274
+ }
275
+
276
+ const modified = updated !== orig;
277
+ if (modified && !dryRun) {
278
+ fs.writeFileSync(playbookPath, updated, 'utf8');
279
+ }
280
+
281
+ return { modified };
282
+ } catch {
283
+ return null;
284
+ }
285
+ }
286
+
287
+ module.exports = {
288
+ inferModelFamily,
289
+ classifyModelCapabilities,
290
+ collectCatalogModels,
291
+ rankModelsForCapabilityTier,
292
+ syncAgentsWithModels,
293
+ syncModelRegistryPlaybook
294
+ };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "heimdall-agent",
3
- "version": "1.1.0",
3
+ "version": "1.4.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": {
@@ -23,27 +23,31 @@ Before generating any code, creating plans, or taking action on any user request
23
23
  - **Tier 3: Architectural**: Subsystem addition, schema migration, auth boundary, or multi-component flow. Full Google EGM Pipeline (Artifact-First design spec in `docs/designs/<feature>.md` + 4-stage Goldfish review: Zoom Out, Comprehension, Critic, Readiness).
24
24
  - Never assume missing requirements. Uncover implicit user assumptions upfront.
25
25
 
26
- 2. **The 3-Point Questioning Rule**:
27
- - Ask at least 2–3 probing questions about:
28
- a) Non-obvious edge cases, error states, and boundary conditions.
29
- b) Data flow, persistence, and concurrency/race concerns.
30
- c) The exact definition of success and acceptance criteria.
26
+ 2. **The Design Tree Frontier & Questioning Protocol**:
27
+ - **Autonomous Fact-Finding First**: Inspect files, configs, and existing helpers before asking. Never ask the human questions the repository already answers.
28
+ - **Frontier Rounds**: Ask only questions whose prerequisites are settled now. If Question B depends on Question A's answer, defer Question B to the next round.
29
+ - **The "Yes-to-Approve" Triage Format**: Formulate each question with an explicit recommendation so the user can accept by replying *"yes"* or providing a 1-line tweak.
31
30
 
32
31
  3. **Present 2 Concrete Architectural Alternatives**:
33
32
  - Offer Approach A (minimal, lighter, faster) vs. Approach B (robust, extensible).
34
33
  - Detail the explicit tradeoffs of each.
35
34
  - Declare your professional recommendation with clear reasoning.
35
+ - **ADR Synchronization**: For Tier 3 architectural decisions, record settled choices in `docs/adr/YYYY-MM-DD-<title>.md`.
36
36
 
37
37
  4. **Hard Gate**:
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:
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, Frontier Questions, and Alternatives explicitly in user-visible chat markdown using this exact template:
39
39
  ```markdown
40
40
  ### 1. Scope Classification
41
41
  - **Scope**: [Spike / Bounded / Architectural]
42
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]
43
+ ### 2. Frontier Questions (Yes-to-Approve Format)
44
+ ❓ **Q1 - [Decision Title]**: [Context, edge cases, and options]
45
+ ➡️ **Recommended**: [Explicit recommendation + rationale]
46
+
47
+ ---
48
+
49
+ ❓ **Q2 - [Decision Title]**: [Context, limits, boundary conditions]
50
+ ➡️ **Recommended**: [Explicit recommendation + rationale]
47
51
 
48
52
  ### 3. Concrete Alternatives
49
53
  - **Alternative 1**: [Description + architectural trade-offs]
@@ -16,11 +16,19 @@ When reviewing code, pull requests, or git diffs, assume that edge cases and def
16
16
  - **"No Glazing" Rule**: Eliminate sycophancy. Never use validating adjectives like "brilliant," "great," "smart," "perfect," or "spot-on." Ban apologies ("I apologize"). Lead with what is wrong, missing, or risky.
17
17
  - **Plain-English Standard**: Plain, direct, jargon-free technical English. No ungrounded promotional adjectives or buzzwords.
18
18
 
19
- ## 2. Two-Tier Review Trigger
20
- - **Tier 1 (Bounded & Routine Tasks)**: Single-pass adversarial critique targeting edge cases, security, and anti-slop code hygiene.
21
- - **Tier 2 (Architectural & High-Stakes Tasks)**: Mandatory **5-round convergence loop** with a structured findings ledger.
19
+ ## 2. 3-Tier Review & Handoff Policy
20
+ - **Tier 1 (Spikes & Local Fixes < 50 LOC)**:
21
+ - **Zero Review Ceremony**. Author verifies empirically via terminating automated tests (`npm test`, `pytest`).
22
+ - No peer model review or handoff document required.
23
+ - **Tier 2 (Bounded Features & Subsystems)**:
24
+ - **Single Peer Reviewer Gate**. One peer model (e.g. Claude implements -> Gemini reviews; or vice-versa) to prevent self-review blindness. Multiple reviewers are NOT needed.
25
+ - **Lean Handoff**: Feed the reviewer using the `handoff` skill (pointer to spec, target branch, and diff) to strictly maintain Goldfish blinding without leaking conversational bias.
26
+ - Single-pass adversarial critique targeting edge cases, security, and anti-slop code hygiene.
27
+ - **Tier 3 (Architectural, Auth, Schema Migrations & High-Stakes)**:
28
+ - **Multi-Model Consensus & Full Handoff**. Seeded with a formal `handoff` document referencing ADRs (`docs/adr/`) and specifications (`docs/designs/`).
29
+ - Mandatory **5-round convergence loop** with a structured findings ledger across multiple peer models.
22
30
 
23
- ## 3. The 5-Round Convergence Ledger Protocol
31
+ ## 3. The 5-Round Convergence Ledger Protocol (Tier 3)
24
32
  For Tier 2 reviews, all findings must be tracked in an authoritative ledger:
25
33
 
26
34
  ```markdown
@@ -17,7 +17,9 @@
17
17
  # Plan: [Feature / Task Name]
18
18
 
19
19
  ## 1. Active Skills & Directives Checklist
20
- - [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
21
23
  - [x] `karpathy-guidelines` — Simplicity first, surgical edits, no speculative bloat
22
24
  - [x] `antislop` — Clean comments, no AI boilerplate, accessible contrast
23
25
  - [x] `communication-doctrine` — BLUF macro layout, STE imperative steps (<=20 words), zero vague qualifiers
@@ -41,17 +43,10 @@
41
43
  ### Phase 3: Integration & Playwright E2E Verification
42
44
  ### Phase 4: Review, Purge & Handoff
43
45
 
44
- ## 5. Symmetric & Tri-Directional Cross-Model Validation Loop
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`
46
+ ## 5. Symmetric Cross-Family Validation Loop
47
+ - In Herdr (`HERDR_ENV=1`), validate tasks using a **different model family** from the authoring model (e.g., Anthropic ↔ Google ↔ OpenAI/Codex ↔ Zhipu/GLM ↔ Tencent/Hunyuan ↔ Xiaomi/MiMo) selected from `config/models.json` / `playbooks/06-model-registry-matrix.md`:
48
+ - `herdr agent prompt <cross-family-reviewer> "Review git diff for security regressions, boundary conditions, and type errors." --wait --timeout 120000`
49
+ - Select any live reviewer agent/model from a distinct family rather than restricting validation to Claude/Gemini/Codex alone.
55
50
 
56
51
  ## 6. Orchestrator Heartbeat
57
52
  - Orchestrator monitors progress every 3 minutes.
@@ -101,4 +96,4 @@
101
96
  - Every task must explicitly declare one of the registered models and an allowed effort level (`low`, `medium`, `high`, `xhigh`) defined in `playbooks/06-model-registry-matrix.md`.
102
97
  - Tasks requiring deep architectural reasoning, type safety, or complex algorithms must use `high` or `xhigh`.
103
98
  - Fast scans, boilerplate scaffolding, or rapid audits may use `low` or `medium`.
104
- - When Gemini 4 Argon reaches quota cooldown, immediately fallback to Gemini 3.8 Flash, Gemini 3.1 Pro, or GhostCLI (Claude Sonnet 5 / GPT-6 Astra).
99
+ - When Gemini 4 Argon reaches quota cooldown, fallback in order: Gemini 4 Hydrogen → Gemini 3.8 Flash → GhostCLI models (Claude/GPT).
@@ -10,8 +10,8 @@ Models are partitioned into two architectural access channels:
10
10
 
11
11
  - **Channel 1: GhostCLI Unified Gateway (`https://ghostcli.cloud`)**
12
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`).
13
+ - Serves all GhostCLI-proxied model families (Anthropic `claude-*`, OpenAI `gpt-*`, Zhipu `z-ai/glm-*`, Tencent `tencent/Hy4-*`, Xiaomi `XiaomiMiMo/*`, and any newly discovered models in `config/models.json`).
14
+ - Because GhostCLI exposes multi-protocol translation (`/v1/messages`, `/v1/responses`, `/v1/chat/completions`), any CLI harness can run any GhostCLI model directly (e.g. `claude --model z-ai/glm-5.3`, `claude --model tencent/Hy4-preview`, `codex --model claude-sonnet-5-5`).
15
15
  - When coordinating between harnesses in Herdr (`HERDR_ENV=1`), use native Herdr multiplexing (`herdr agent start/prompt`) directly.
16
16
 
17
17
  - **Channel 2: Google Gemini Direct API (`gemini.googleapis.com`)**
@@ -22,19 +22,25 @@ Models are partitioned into two architectural access channels:
22
22
 
23
23
  ## 2. GhostCLI Models (via `https://ghostcli.cloud`)
24
24
 
25
- All GhostCLI models support text and image input:
26
-
27
- | Model Name | Canonical Flag | Context Window | Max Output | Parallel Tools | Search | Allowed Effort Levels | Optimal Specialization |
28
- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
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. |
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. |
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. |
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. |
34
- | **GPT-6 Astra** | `gpt-6-astra` | 1M | 128K | ✅ | ✅ | `low`, `medium`, `high`, `xhigh` | OpenAI reasoning, broad general-purpose tasks, alternative perspective for cross-validation. |
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.
25
+ <!-- heimdall:ghostcli-models:start -->
26
+ All GhostCLI models are discovered dynamically via `heimdall sync` / `heimdall sync-models` and stored in `config/models.json`:
27
+
28
+ | Model Name | Canonical Flag | Family | Context Window | Allowed Effort Levels | Specialization / Description |
29
+ | :--- | :--- | :--- | :--- | :--- | :--- |
30
+ | **Claude Opus 5.5** | `claude-opus-5-5` | anthropic | 1M | `low`, `medium`, `high`, `xhigh` | Melhor equilíbrio entre capacidade e custo |
31
+ | **Claude Sonnet 5** | `claude-sonnet-5` | anthropic | 1M | `low`, `medium`, `high` | O mais rápido sem abrir mão de qualidade |
32
+ | **Claude Sonnet 5.5** | `claude-sonnet-5-5` | anthropic | 1M | `low`, `medium`, `high` | Rápido e mais capaz que o Sonnet 5 |
33
+ | **Claude Fable 5.2** | `claude-fable-5.2` | anthropic | 1M | `low`, `medium`, `high`, `xhigh` | Máxima capacidade disponível |
34
+ | **GLM 5.3** | `z-ai/glm-5.3` | z-ai | 1M | `low`, `medium`, `high`, `xhigh` | Código agêntico com contexto de 1M |
35
+ | **GLM 5.3 Flash** | `z-ai/glm-5.3-flash` | z-ai | 1M | `low`, `medium`, `high` | Respostas rápidas para código |
36
+ | **Hunyuan Hy4 Preview** | `tencent/Hy4-preview` | tencent | 1M | `low`, `medium`, `high`, `xhigh` | Raciocínio e código |
37
+ | **DeepSeek V4.1 Flash** | `deepseek-ai/DeepSeek-V4.1-Flash-1017` | deepseek-ai | 1M | `low`, `medium`, `high` | Respostas rápidas para código |
38
+ | **MiMo V2.6 Pro** | `XiaomiMiMo/MiMo-V2.6-Pro` | xiaomi | 1M | `low`, `medium`, `high`, `xhigh` | Código e raciocínio |
39
+ | **GPT-6 Astra** | `gpt-6-astra` | openai | 1M | `low`, `medium`, `high`, `xhigh` | Trabalho agêntico longo com janela de 1M |
40
+
41
+ > [!NOTE]
42
+ > **Dynamic Model Registry**: Always resolve live model IDs from `config/models.json` or this table after `heimdall sync` / `heimdall sync-models`. Route tasks by **capability tier** across all available families (Anthropic, Google, OpenAI, GLM, Hunyuan, MiMo, etc.), not only Claude/Gemini/Codex.
43
+ <!-- heimdall:ghostcli-models:end -->
38
44
 
39
45
  ---
40
46
 
@@ -44,8 +50,10 @@ Accessed natively via Google Antigravity / `agy` CLI (never through GhostCLI):
44
50
 
45
51
  | Model Name | Canonical Flag | Allowed Effort Levels | Optimal Specialization |
46
52
  | :--- | :--- | :--- | :--- |
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. |
53
+ | **Gemini 4 Hydrogen** | `gemini-4-hydrogen-{effort}` (e.g. `gemini-4-hydrogen-xhigh`) | `low`, `medium`, `high`, `xhigh` | Efficient frontier reasoning with speed and long decodes up to 1M tokens. Supports xhigh effort tier. Replaces Flash branding. |
54
+ | **Gemini 4 Argon** | `gemini-4-argon-{effort}` (e.g. `gemini-4-argon-high`) | `low`, `medium`, `high` | Efficient Gemini 4 frontier reasoning, faster responses and lower token spend. Subject to quota cooldowns. |
55
+ | **Orchestrator (Argon)** | N/A (model dropdown option in Antigravity) | Auto-managed | Dynamic mode that splits tasks between Carbon (planning/review) and Hydrogen (implementation) within one session. Uses ~24% less quota and finishes ~19% faster than Carbon alone. Requires Google AI Ultra subscription; not a standalone model. |
56
+ | **Gemini 3.8 Flash** | `gemini-3.8-flash-{effort}` (e.g. `gemini-3.8-flash-high`) | `low`, `medium`, `high` | Stable previous-generation Flash for software engineering, autonomous agents, and complex enterprise workflows. Current default workhorse. |
49
57
 
50
58
  ---
51
59
 
@@ -72,12 +80,12 @@ The `/model` picker in Claude Code shows a hardcoded list that may include model
72
80
 
73
81
  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.
74
82
 
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).
83
+ Gemini models (`gemini-4-hydrogen`, `gemini-4-argon`, `gemini-3.8-flash`) are never reachable through GhostCLI; they are accessed natively via Google Antigravity (`agy` CLI in Herdr). `Orchestrator (Argon)` is a dynamic mode that splits tasks between planning and implementation within one session — it is not a standalone model. Gemini 4 Carbon exists but is unavailable on current plan tier.
76
84
 
77
85
  ---
78
86
 
79
87
  ## 6. Effort Constraint & Fallback Rules
80
88
 
81
89
  - **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.
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.
90
+ - **Quota Fallback Rule**: When Gemini 4 Argon reaches quota cooldown, fallback in order: Gemini 4 Hydrogen → Gemini 3.8 Flash → GhostCLI models (Claude/GPT).
83
91
  - **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.