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.
- package/README.md +101 -31
- package/README.pt-BR.md +124 -40
- package/agents/code-sentinel.md +7 -1
- package/agents/frontend-designer.md +6 -1
- package/agents/modernizer.md +8 -3
- package/agents/orchestrator.md +22 -8
- package/agents/reviewer.md +3 -1
- package/config/agents.json +177 -5
- package/config/mcp.json +1 -1
- package/config/mcp.resolved.json +74 -0
- package/config/mcp.template.json +85 -0
- package/config/models.json +70 -0
- package/config/profiles.json +4 -3
- package/config/skills.json +321 -93
- package/docs/SKILLS.md +158 -75
- package/docs/designs/old/2026-11-16 upstream-skill-sync-and-provenance-links.md +60 -0
- package/docs/runs/skill-audit/2026-11-12-compare-report.json +1028 -0
- package/docs/runs/skill-audit/2026-11-12-upstream-audit.json +275 -0
- package/doctrine/AGENTS.md +7 -4
- package/hooks/heimdall-hook.cjs +16 -1
- package/hooks/hooks.json +11 -0
- package/lib/catalog-sync.cjs +8 -3
- package/lib/model-context.cjs +50 -1
- package/lib/model-router.cjs +294 -0
- package/package.json +1 -1
- package/playbooks/01-interactive-grilling-gate.md +14 -10
- package/playbooks/03-adversarial-code-review.md +12 -4
- package/playbooks/05-canonical-plan-template.md +8 -13
- package/playbooks/06-model-registry-matrix.md +27 -19
- package/readme.html +1006 -0
- package/setup.mjs +317 -206
- package/skills/antislop-copywriting/SKILL.md +36 -1
- package/skills/brainstorming/SKILL.md +60 -38
- package/skills/codebase-design/DEEPENING.md +37 -0
- package/skills/codebase-design/DESIGN-IT-TWICE.md +44 -0
- package/skills/codebase-design/SKILL.md +114 -0
- package/skills/communication-doctrine/SKILL.md +2 -2
- package/skills/domain-modeling/ADR-FORMAT.md +47 -0
- package/skills/domain-modeling/GLOSSARY-FORMAT.md +60 -0
- package/skills/domain-modeling/SKILL.md +74 -0
- package/skills/executing-plans/SKILL.md +6 -4
- package/skills/grill-me/SKILL.md +65 -0
- package/skills/handoff/SKILL.md +77 -0
- package/skills/improve-codebase-architecture/HTML-REPORT.md +123 -0
- package/skills/improve-codebase-architecture/SKILL.md +71 -0
- package/skills/mcp-cleanup/SKILL.md +61 -0
- package/skills/mcp-sync/SKILL.md +58 -0
- package/skills/modern-web-guidance/SKILL.md +90 -0
- package/skills/owasp-security/reference/config-and-supply-chain.md +346 -344
- package/skills/owasp-security/reference/languages.md +378 -372
- package/skills/owasp-security/reference/owasp-report.md +1144 -1140
- package/skills/owasp-security/reference/review-checklist.md +134 -132
- package/skills/ruminate/SKILL.md +140 -0
- package/skills/subagent-driven-development/SKILL.md +7 -4
- package/skills/taste-skill/SKILL.md +367 -534
- package/skills/to-spec/SKILL.md +75 -0
- package/skills/to-tickets/SKILL.md +105 -0
- package/skills/upstream-skill-sync/SKILL.md +46 -0
- package/skills/wayfinder/SKILL.md +128 -0
- 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.
|
|
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
|
|
27
|
-
-
|
|
28
|
-
|
|
29
|
-
|
|
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.
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
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.
|
|
20
|
-
- **Tier 1 (
|
|
21
|
-
- **
|
|
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
|
|
45
|
-
- In Herdr (`HERDR_ENV=1`), validate tasks
|
|
46
|
-
-
|
|
47
|
-
|
|
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,
|
|
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
|
|
14
|
-
- Because GhostCLI exposes multi-protocol translation (`/v1/messages`, `/v1/responses`, `/v1/chat/completions`),
|
|
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
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
|
29
|
-
|
|
|
30
|
-
| **Claude
|
|
31
|
-
| **Claude
|
|
32
|
-
| **
|
|
33
|
-
| **
|
|
34
|
-
| **
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
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
|
|
48
|
-
| **Gemini
|
|
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-
|
|
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,
|
|
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.
|