pantheon-opencode 1.6.0-beta.13 → 1.6.0-beta.15

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 (41) hide show
  1. package/AGENTS.global.md +8 -10
  2. package/AGENTS.md +1 -1
  3. package/CHANGELOG.md +47 -0
  4. package/README.md +51 -0
  5. package/README.pt-BR.md +1 -1
  6. package/bin/pantheon-init.mjs +29 -36
  7. package/package.json +1 -1
  8. package/plugin.json +1 -1
  9. package/pyproject.toml +1 -1
  10. package/scripts/check-plugin-v2-coverage.mjs +4 -1
  11. package/scripts/install/agents-md.mjs +2 -2
  12. package/scripts/install/cli-ui.mjs +32 -71
  13. package/scripts/install/component-selection.mjs +61 -0
  14. package/scripts/install/health-check.mjs +3 -3
  15. package/scripts/install/interactive.mjs +9 -6
  16. package/scripts/install/migrate.mjs +13 -19
  17. package/scripts/install/model-picker.mjs +155 -228
  18. package/scripts/install/opencode.mjs +52 -27
  19. package/scripts/install/shared.mjs +5 -5
  20. package/scripts/install/strings.mjs +6 -6
  21. package/scripts/install/venv.mjs +5 -5
  22. package/src/agents/aphrodite.md +11 -10
  23. package/src/agents/apollo.md +3 -3
  24. package/src/agents/athena.md +12 -11
  25. package/src/agents/demeter.md +10 -7
  26. package/src/agents/hephaestus.md +4 -3
  27. package/src/agents/hermes.md +9 -8
  28. package/src/agents/nyx.md +4 -4
  29. package/src/agents/prometheus.md +12 -11
  30. package/src/agents/zeus.md +26 -1
  31. package/src/instructions/agent-return-format.instructions.md +7 -9
  32. package/src/instructions/zeus-council-synthesis.instructions.md +2 -2
  33. package/src/instructions/zeus-memory-operations.instructions.md +9 -1
  34. package/src/instructions/zeus-timeout-retry.instructions.md +8 -1
  35. package/src/pantheon/task-result-guard.ts +13 -13
  36. package/src/pantheon/v2-execute-after.ts +27 -13
  37. package/src/plugins/tui/dist/tui-v2.js +2 -2
  38. package/src/plugins/tui/dist/tui.js +1 -1
  39. package/src/plugins/tui/package-lock.json +2 -2
  40. package/src/plugins/tui/package.json +1 -1
  41. package/src/routing.yml +45 -0
@@ -858,8 +858,9 @@ export function setupRuntimePhase(
858
858
  const S = strings()
859
859
  const setup = deps.setupVenv ?? setupVenv
860
860
  const check = deps.healthCheck ?? healthCheck
861
+ let stopProgress
861
862
  try {
862
- const venvSpinner = spinner(S.settingUpRuntime)
863
+ stopProgress = spinner(S.settingUpRuntime)
863
864
  setup(target, {
864
865
  dryRun,
865
866
  force: clean,
@@ -867,25 +868,29 @@ export function setupRuntimePhase(
867
868
  reviewedRemovals,
868
869
  reviewedSnapshots,
869
870
  })
870
- venvSpinner(true)
871
+ stopProgress(true)
872
+ stopProgress = null
871
873
  const runtimeTarget = isGlobal ? target : join(target, '.opencode')
872
874
  const health = check(runtimeTarget, { dryRun, pythonTarget: target })
873
875
 
874
- section(`\uD83D\uDD0D ${S.healthSection}`)
875
- const healthStep = step(S.runningHealthChecks)
876
+ section(S.healthSection)
877
+ stopProgress = step(S.runningHealthChecks)
876
878
  for (const p of health.passed) success(`${p.check}: ${p.detail}`)
877
879
  for (const w of health.warnings) warning(`${w.check}: ${w.detail}`)
878
880
  for (const f of health.failed) error(`${f.check}: ${f.detail}`)
879
881
 
880
882
  if (health.failed.length > 0) {
881
- healthStep(false)
883
+ stopProgress(false)
884
+ stopProgress = null
882
885
  warning(`${health.failed.length} check(s) failed — review above`)
883
886
  stats.warnings += health.failed.length
884
887
  return false
885
888
  }
886
- healthStep(true)
889
+ stopProgress(true)
890
+ stopProgress = null
887
891
  return true
888
892
  } catch (err) {
893
+ stopProgress?.(false)
889
894
  error(S.runtimeFailed(err.message))
890
895
  warning(S.runtimeSkippedMcp)
891
896
  stats.warnings += 1
@@ -1059,7 +1064,9 @@ async function installPass(
1059
1064
  target = join(homedir(), '.config', 'opencode')
1060
1065
  }
1061
1066
 
1062
- const componentSet = new Set(components)
1067
+ const componentSet = new Set(
1068
+ opts.noMcp ? components.filter((component) => component !== 'runtime') : components,
1069
+ )
1063
1070
  const stats = summary.opencode
1064
1071
  // Per-call baseline. `stats` is the module-level cumulative summary, so the
1065
1072
  // consistency guard must compare against THIS call's delta, not the total.
@@ -1114,6 +1121,12 @@ async function installPass(
1114
1121
  ...opts,
1115
1122
  skipProbe: dryRun,
1116
1123
  })
1124
+ if (version === 'v2' && opts.preset) {
1125
+ throw new Error(
1126
+ '--preset is not supported for OpenCode V2 because V2 ignores the legacy active-preset marker. ' +
1127
+ 'Configure models using V2-native OpenCode configuration instead.',
1128
+ )
1129
+ }
1117
1130
  const versionAssumed =
1118
1131
  dryRun &&
1119
1132
  (opts.version ?? 'auto') === 'auto' &&
@@ -1150,9 +1163,17 @@ async function installPass(
1150
1163
 
1151
1164
  if (interactive && !dryRun) {
1152
1165
  const { runInteractiveInstall } = await import('./interactive.mjs')
1166
+ const hasRequestedComponents = Array.isArray(opts.requestedComponents)
1167
+ const promptComponents = hasRequestedComponents ? opts.requestedComponents : components
1168
+ const promptDefaults = hasRequestedComponents
1169
+ ? []
1170
+ : opts.noMcp
1171
+ ? COMPONENT_NAMES.filter((component) => component !== 'runtime')
1172
+ : COMPONENT_NAMES
1153
1173
  const result = await runInteractiveInstall({
1154
- components,
1155
- defaultComponents: COMPONENT_NAMES,
1174
+ components: promptComponents,
1175
+ defaultComponents: promptDefaults,
1176
+ noMcp: opts.noMcp === true,
1156
1177
  prompts: opts.deps?.prompts,
1157
1178
  isTTY: opts.deps?.isTTY,
1158
1179
  })
@@ -1162,13 +1183,15 @@ async function installPass(
1162
1183
  return { ...stats, applied: false, reason: 'canceled' }
1163
1184
  }
1164
1185
 
1165
- if (!result.confirmed && !autoYes) {
1186
+ if (!result.confirmed) {
1166
1187
  info('Installation canceled.')
1167
1188
  return { ...stats, applied: false, reason: 'canceled' }
1168
1189
  }
1169
1190
 
1170
1191
  // Map target selection to actual path
1171
- const newComponents = [...result.components]
1192
+ const newComponents = [...result.components].filter(
1193
+ (component) => !opts.noMcp || component !== 'runtime',
1194
+ )
1172
1195
  componentSet.clear()
1173
1196
  for (const c of newComponents) componentSet.add(c)
1174
1197
 
@@ -1385,7 +1408,7 @@ async function installPass(
1385
1408
  // 1. Install agents (--components agents)
1386
1409
  // -----------------------------------------------------------------------
1387
1410
  if (componentSet.has('agents')) {
1388
- section('\uD83D\uDCE6 Agents')
1411
+ section('Agents')
1389
1412
  const srcDir = join(ROOT, 'src', 'agents')
1390
1413
  if (!sourceDirValid(srcDir)) {
1391
1414
  warning(`Agent source directory not found: ${srcDir}`)
@@ -1438,7 +1461,7 @@ async function installPass(
1438
1461
  // 2. Install skills (--components skills)
1439
1462
  // -----------------------------------------------------------------------
1440
1463
  if (componentSet.has('skills')) {
1441
- section('\uD83D\uDCDA Skills')
1464
+ section('Skills')
1442
1465
  const skillNames = collectSkillNames()
1443
1466
  if (skillNames.length > 0) {
1444
1467
  const skillStep = step(`Installing ${skillNames.length} skills`)
@@ -1484,7 +1507,7 @@ async function installPass(
1484
1507
  // writeAgentsMdManaged is conservative: content outside the managed region
1485
1508
  // is never deleted, and a legacy fully-generated file upgrades in place.
1486
1509
  if (componentSet.has('instructions')) {
1487
- section('\uD83D\uDCCB Instructions')
1510
+ section('Instructions')
1488
1511
  const srcAgentsMd = isGlobal ? join(ROOT, 'AGENTS.global.md') : join(ROOT, 'AGENTS.md')
1489
1512
  const dstAgentsMd = join(target, 'AGENTS.md')
1490
1513
  if (existsSync(srcAgentsMd)) {
@@ -1522,7 +1545,7 @@ async function installPass(
1522
1545
  // 2.6 Install prompts (--components prompts)
1523
1546
  // -----------------------------------------------------------------------
1524
1547
  if (componentSet.has('prompts')) {
1525
- section('\uD83D\uDCAC Prompts')
1548
+ section('Prompts')
1526
1549
  const srcPrompts = join(ROOT, 'prompts')
1527
1550
  const dstPrompts = join(target, 'prompts')
1528
1551
  if (existsSync(srcPrompts)) {
@@ -1545,7 +1568,7 @@ async function installPass(
1545
1568
  // 2.7 Install commands (--components commands)
1546
1569
  // -----------------------------------------------------------------------
1547
1570
  if (componentSet.has('commands')) {
1548
- section('\u26A1 Commands')
1571
+ section('Commands')
1549
1572
  const srcCmds = join(ROOT, 'commands')
1550
1573
  // V2 project sandboxes use OPENCODE_CONFIG_DIR=<project root>, so OpenCode
1551
1574
  // discovers custom commands from <target>/commands. V1 project installs
@@ -1580,7 +1603,7 @@ async function installPass(
1580
1603
  // 2.8 Install TUI plugins (--components plugins)
1581
1604
  // -----------------------------------------------------------------------
1582
1605
  if (componentSet.has('plugins')) {
1583
- section('\uD83D\uDD0C Plugins')
1606
+ section('Plugins')
1584
1607
  const srcPluginDir = join(ROOT, 'src', 'plugins', 'tui')
1585
1608
  const dstPluginDir = isGlobal
1586
1609
  ? join(target, 'plugins', 'pantheon-tui')
@@ -1626,7 +1649,7 @@ async function installPass(
1626
1649
  // MCP server scripts, code-mode scripts, tiers.json
1627
1650
  // -----------------------------------------------------------------------
1628
1651
  if (componentSet.has('runtime')) {
1629
- section('\u2699\uFE0F Runtime')
1652
+ section('Runtime')
1630
1653
  const runtimeTarget = isGlobal ? target : join(target, '.opencode')
1631
1654
 
1632
1655
  // ── MCP server scripts ──
@@ -1750,6 +1773,7 @@ async function installPass(
1750
1773
  target,
1751
1774
  { dryRun, clean, isGlobal, recorder, reviewedRemovals, reviewedSnapshots },
1752
1775
  stats,
1776
+ opts.deps,
1753
1777
  )
1754
1778
  }
1755
1779
 
@@ -2351,14 +2375,13 @@ async function installPass(
2351
2375
  process.stdout.write(
2352
2376
  ` ${colors.dim('\u2500'.repeat(Math.min(process.stdout.columns || 60, 60)))}\n`,
2353
2377
  )
2354
- process.stdout.write(` ${colors.green('\u2713')} ${created} component(s) installed\n`)
2378
+ process.stdout.write(` [OK] ${created} component(s) installed\n`)
2355
2379
  if (skipped > 0)
2356
2380
  process.stdout.write(` ${colors.dim('\u2014')} ${skipped} already up-to-date\n`)
2357
- if (errors > 0)
2358
- process.stdout.write(` ${colors.yellow('\u26a0')} ${errors} error(s) encountered\n`)
2381
+ if (errors > 0) process.stdout.write(` [WARN] ${errors} error(s) encountered\n`)
2359
2382
  if (warnings > 0)
2360
2383
  process.stdout.write(
2361
- ` ${colors.yellow('\u26a0')} ${warnings} warning(s) — run 'pantheon-opencode doctor' for details\n`,
2384
+ ` [WARN] ${warnings} warning(s) — run 'pantheon-opencode doctor' for details\n`,
2362
2385
  )
2363
2386
  process.stdout.write('\n')
2364
2387
  process.stdout.write(` ${colors.bold('Next steps:')}\n`)
@@ -2374,14 +2397,15 @@ async function installPass(
2374
2397
  }
2375
2398
 
2376
2399
  // -----------------------------------------------------------------------
2377
- // 5. Model preset selection (--components agents). Interactive wizard runs
2378
- // unless autoYes (use defaults) or an explicit --preset was given.
2400
+ // 5. V1 model preset selection (--components agents). V2 ignores the legacy
2401
+ // active-preset marker, so it has no profile wizard or --preset support.
2402
+ // The V1 interactive wizard runs unless autoYes or an explicit preset was given.
2379
2403
  // Q1 default "herdar do chat" (inherit) writes no active-preset.json —
2380
2404
  // delegates inherit the parent chat model (native inheritance).
2381
2405
  // -----------------------------------------------------------------------
2382
- if (interactive && !dryRun && !autoYes && !opts.preset) {
2406
+ if (interactive && stdinTTY && version === 'v1' && !dryRun && !autoYes && !opts.preset) {
2383
2407
  const { runInitWizard } = await import('./model-picker.mjs')
2384
- await runInitWizard({ presetDir: target, logger: console })
2408
+ await runInitWizard({ presetDir: target, logger: console, prompts: opts.deps?.prompts })
2385
2409
  }
2386
2410
 
2387
2411
  if (opts.preset && !dryRun) {
@@ -2397,7 +2421,8 @@ async function installPass(
2397
2421
  // must never fail the install: vision stays optional.
2398
2422
  // -----------------------------------------------------------------------
2399
2423
  if (interactive && !dryRun && !autoYes) {
2400
- const { runVisionPrompt } = await import('./vision-prompt.mjs')
2424
+ const runVisionPrompt =
2425
+ opts.deps?.runVisionPrompt ?? (await import('./vision-prompt.mjs')).runVisionPrompt
2401
2426
  try {
2402
2427
  await runVisionPrompt({ logger: console })
2403
2428
  } catch (err) {
@@ -140,7 +140,7 @@ export function parseArgs(argv) {
140
140
  args.help = true
141
141
  break
142
142
  default:
143
- console.warn(`⚠️ Unknown option: ${argv[i]}`)
143
+ console.warn(`[WARN] Unknown option: ${argv[i]}`)
144
144
  break
145
145
  }
146
146
  }
@@ -165,12 +165,12 @@ export function resolveTarget(target) {
165
165
  export function detectAndReport(target) {
166
166
  const found = detectPlatforms(target).length > 0
167
167
 
168
- console.log(`\n 🔍 Pantheon Platform Detection`)
168
+ console.log(`\n Pantheon Platform Detection`)
169
169
  console.log(` Target: ${target}\n`)
170
170
 
171
171
  console.log(` ${'Platform'.padEnd(12)} ${'Detected?'.padEnd(12)} Config file`)
172
172
  console.log(` ${'─'.repeat(55)}`)
173
- const status = (found ? '✅ YES' : '❌ no').padEnd(12)
173
+ const status = (found ? '[OK] yes' : '[MISSING]').padEnd(12)
174
174
  console.log(` ${'OpenCode'.padEnd(12)} ${status} ${found ? 'opencode.json' : '(not found)'}`)
175
175
  console.log(`\n 📊 ${found ? 1 : 0} of 1 platforms detected.`)
176
176
  if (found) {
@@ -813,7 +813,7 @@ export function printSummary(target, platforms) {
813
813
  totalSkipped += stats.skipped
814
814
  totalErrors += stats.errors
815
815
 
816
- const status = stats.errors > 0 ? '⚠️' : '✅'
816
+ const status = stats.errors > 0 ? '[WARN]' : '[OK]'
817
817
  console.log(
818
818
  ` ${status} ${label}: ${stats.created} created, ${stats.skipped} skipped${stats.errors > 0 ? `, ${stats.errors} errors` : ''}`,
819
819
  )
@@ -825,7 +825,7 @@ export function printSummary(target, platforms) {
825
825
  )
826
826
 
827
827
  if (totalErrors > 0) {
828
- console.log(' ⚠️ Some platforms had errors — review warnings above.')
828
+ console.log(' [WARN] Some platforms had errors — review warnings above.')
829
829
  }
830
830
 
831
831
  console.log('')
@@ -16,13 +16,13 @@ const TABLE = {
16
16
  dryRun: 'DRY RUN',
17
17
  canceled: 'Installation canceled — nothing was broken; run init again anytime.',
18
18
  canceledShort: 'Installation canceled.',
19
- installFailed: (msg) => `❌ Installation failed: ${msg}`,
19
+ installFailed: (msg) => `Installation failed: ${msg}`,
20
20
  failHintNoMcp:
21
21
  ' Run with --no-mcp to skip Python dependencies:\n npx pantheon-opencode init --no-mcp',
22
22
  failHintForce:
23
23
  ' Or retry with --force to recreate the venv:\n npx pantheon-opencode init --force',
24
24
  runningHealthCheck: 'Running health check...',
25
- installedTitle: (v) => `✅ Pantheon OpenCode v${v} installed!`,
25
+ installedTitle: (v) => `Pantheon OpenCode v${v} installed.`,
26
26
  nextSteps: 'Next steps:',
27
27
  nextVerify: '1. Verify installation:\n npx pantheon-opencode doctor',
28
28
  nextLaunch: '2. Launch OpenCode',
@@ -51,7 +51,7 @@ const TABLE = {
51
51
  planOnlyNoYes: 'Plan only — re-run with --yes to apply.',
52
52
  driftHeader: 'State changed since preview — aborting before any write:',
53
53
  driftAbort: 'No files were written. Re-run to re-review.',
54
- applyFailed: (msg) => `❌ Apply failed: ${msg}`,
54
+ applyFailed: (msg) => `Apply failed: ${msg}`,
55
55
  alreadyApplied: 'Paths already applied — no automatic rollback:',
56
56
  restoreRecoveryHint: (dir) => `Recover with: pantheon-opencode restore (backup at ${dir})`,
57
57
  restoreNoBackup:
@@ -74,13 +74,13 @@ const TABLE = {
74
74
  dryRun: 'SIMULAÇÃO',
75
75
  canceled: 'Instalação cancelada — nada foi quebrado; rode init de novo quando quiser.',
76
76
  canceledShort: 'Instalação cancelada.',
77
- installFailed: (msg) => `❌ Instalação falhou: ${msg}`,
77
+ installFailed: (msg) => `Instalação falhou: ${msg}`,
78
78
  failHintNoMcp:
79
79
  ' Rode com --no-mcp para pular dependências Python:\n npx pantheon-opencode init --no-mcp',
80
80
  failHintForce:
81
81
  ' Ou tente de novo com --force para recriar a venv:\n npx pantheon-opencode init --force',
82
82
  runningHealthCheck: 'Rodando verificação de saúde...',
83
- installedTitle: (v) => `✅ Pantheon OpenCode v${v} instalado!`,
83
+ installedTitle: (v) => `Pantheon OpenCode v${v} instalado.`,
84
84
  nextSteps: 'Próximos passos:',
85
85
  nextVerify: '1. Verifique a instalação:\n npx pantheon-opencode doctor',
86
86
  nextLaunch: '2. Abra o OpenCode',
@@ -109,7 +109,7 @@ const TABLE = {
109
109
  planOnlyNoYes: 'Apenas o plano — rode de novo com --yes para aplicar.',
110
110
  driftHeader: 'O estado mudou desde o preview — abortando antes de qualquer escrita:',
111
111
  driftAbort: 'Nenhum arquivo foi escrito. Rode de novo para revisar.',
112
- applyFailed: (msg) => `❌ Falha ao aplicar: ${msg}`,
112
+ applyFailed: (msg) => `Falha ao aplicar: ${msg}`,
113
113
  alreadyApplied: 'Caminhos já aplicados — sem rollback automático:',
114
114
  restoreRecoveryHint: (dir) => `Recupere com: pantheon-opencode restore (backup em ${dir})`,
115
115
  restoreNoBackup:
@@ -67,7 +67,7 @@ export function setupVenv(
67
67
  console.log(' Removing existing .venv (--force)...')
68
68
  removeReviewedTree(venvPath, reviewedRemovals, reviewedSnapshots)
69
69
  }
70
- console.log(' ✅ .venv removed')
70
+ console.log(' [OK] .venv removed')
71
71
  }
72
72
 
73
73
  // Step 1b: Create venv if not exists
@@ -83,7 +83,7 @@ export function setupVenv(
83
83
  throw new Error('Failed to create virtual environment')
84
84
  }
85
85
  }
86
- console.log(' ✅ .venv created')
86
+ console.log(' [OK] .venv created')
87
87
  // A single synthetic entry for the venv directory — never enumerate its
88
88
  // thousands of files. Unscored: the install summary does not count it.
89
89
  recordChange({ path: venvPath, action: ACTIONS.CREATE, bytes: 0, scored: false }, recorder)
@@ -123,7 +123,7 @@ export function setupVenv(
123
123
 
124
124
  if (r.status !== 0) {
125
125
  // Attempt 2: --break-system-packages (PEP 668 / externally-managed)
126
- console.log(' ⚠️ First attempt failed, retrying with --break-system-packages...')
126
+ console.log(' [WARN] First attempt failed, retrying with --break-system-packages...')
127
127
  const r2 = spawnSync(pip, ['install', '-r', reqFile, '--break-system-packages'], {
128
128
  stdio: 'inherit',
129
129
  timeout: 120_000,
@@ -141,7 +141,7 @@ export function setupVenv(
141
141
  }
142
142
  }
143
143
  }
144
- console.log(' ✅ MCP dependencies installed')
144
+ console.log(' [OK] MCP dependencies installed')
145
145
  } else {
146
146
  console.log(' ⏭️ Dependency install skipped (--skip-install)')
147
147
  }
@@ -164,7 +164,7 @@ function main() {
164
164
  const result = setupVenv(target, { dryRun, skipInstall, force })
165
165
  console.log(` 📍 Python: ${result.python}`)
166
166
  } catch (err) {
167
- console.error(`\n ❌ ${err.message}`)
167
+ console.error(`\n [ERROR] ${err.message}`)
168
168
  process.exit(1)
169
169
  }
170
170
  }
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: aphrodite
3
- description: "Frontend specialist — React 19, TypeScript strict, WCAG accessibility, responsive design, TDD, modern API patterns, deprecated npm detection. Calls apollo for discovery, sends to themis for review."
3
+ description: "Frontend specialist — React 19, TypeScript strict, WCAG accessibility, responsive design, TDD, modern API patterns, deprecated npm detection. Routes discovery and Themis review requests through Zeus."
4
4
  mode: all
5
5
  reasoning_effort: medium
6
6
  permission:
@@ -52,17 +52,18 @@ You are a frontend implementation specialist. You BUILD UI. You do NOT design ar
52
52
  ## Workflow
53
53
 
54
54
  ### Before Implementation
55
- 1. Inspect relevant component/test/API files directly; use @apollo only when broad or unfamiliar discovery materially reduces risk
55
+ 1. Inspect relevant component/test/API files directly; when broad or unfamiliar discovery materially reduces risk, send the discovery need to Zeus for routing
56
56
  2. Read relevant frontend standards; load `skill: visual-review-pipeline` only when visual behavior changed
57
57
  3. Plan component/data flow when scope or risk warrants it; do not require a design phase for a bounded fix
58
58
  4. For a supplied image/screenshot, use the original reference and Zeus's visual notes as acceptance context; call `vision_describe` if the image is addressable but not directly visible. Inspect the current state first and preserve unrelated existing work—do not delete or revert it just to match the reference unless that replacement is explicitly in scope.
59
+ - Investigate beyond the assigned context only when necessary to resolve the task or when broader discovery materially reduces risk; verify changed behavior proportionally to its scope and risk, using focused checks for bounded changes and broader checks only when integration boundaries or risk warrant them.
59
60
 
60
61
  ### Implementation (TDD)
61
62
  See `skill: tdd-with-agents` for the full TDD cycle.
62
63
 
63
64
  ### Post-Implementation
64
65
  1. Verify the changed behavior with focused tests; use Playwright screenshots when the change affects visible layout or interaction
65
- 2. Send auth/security-sensitive or material UI changes to @themis; a trivial isolated edit needs no separate review phase
66
+ 2. For auth/security-sensitive or material UI changes, request Themis review through Zeus; a trivial isolated edit needs no separate review phase
66
67
  3. Report changed components and checks run; report coverage only when measured and relevant
67
68
 
68
69
  ## Anti-Stall Rules
@@ -70,9 +71,9 @@ See `skill: tdd-with-agents` for the full TDD cycle.
70
71
  | Symptom | Detection | Recovery |
71
72
  |---------|-----------|----------|
72
73
  | Test loop | Same test fails 3+ times with same error | Stop. Re-read the error. Ask: "Is this a code bug or a test bug?" Try a different assertion approach. |
73
- | CSS spiral | Tweaking same CSS property repeatedly | Stop. Inspect the full layout. Is the issue in a parent component? Delegate layout question to @apollo. |
74
+ | CSS spiral | Tweaking same CSS property repeatedly | Stop. Inspect the full layout. Is the issue in a parent component? Send the discovery question to Zeus for routing. |
74
75
  | Component bloat | Component exceeds 300 lines | Split into sub-components BEFORE continuing. |
75
- | Stuck on API shape | Unsure of backend response format | Do NOT guess. Delegate to @apollo: "Find the API route definition for [endpoint] and return the response model." |
76
+ | Stuck on API shape | Unsure of backend response format | Do NOT guess. Send the API-shape question to Zeus; root routing can assign discovery if needed. |
76
77
  | 3 turns no progress | No new code or test in 3 turns | Output \`[APHRODITE_STALL]\`. Escalate to @zeus with: "Stuck on [component]. Last progress: [description]." |
77
78
 
78
79
  ## Pre-Implementation Recall
@@ -88,13 +89,13 @@ After implementing UI components:
88
89
 
89
90
  ## Handoff Rules
90
91
 
91
- - **To @apollo:** For broad/unfamiliar discovery only; otherwise inspect the relevant local files.
92
- - **To @themis:** For auth/security-sensitive or material UI changes; include focused accessibility and behavior checks.
93
- - **To @zeus:** Only for escalations (stuck, conflicting requirements, scope change)
92
+ - **Discovery:** Send discovery needs and any findings to Zeus. Zeus may dispatch to targets; only root Athena/Hermes sessions may call @apollo directly. Child sessions must not dispatch another Pantheon agent.
93
+ - **Themis review:** If review is required, report the need, request it, and pass relevant findings to Zeus; Zeus root decides and dispatches Themis. Child sessions must not dispatch Themis.
94
+ - **To @zeus:** For discovery routing and findings, plus escalations (stuck, conflicting requirements, scope change)
94
95
 
95
96
  ## Efficiency Rules
96
97
 
97
- - Search/read relevant files directly; delegate broad discovery to @apollo only when useful
98
+ - Search/read relevant files directly; route broad discovery needs through Zeus when useful
98
99
  - Use Context7 only for React/Next.js/TypeScript library docs
99
100
  - Run focused tests for each changed behavior; run the broader suite when the change crosses integration boundaries or risk warrants it
100
101
  - Read only as much context as the task needs; a fixed file-count limit must not trigger unnecessary delegation
@@ -104,7 +105,7 @@ After implementing UI components:
104
105
  - Auto-continue through relevant component test cycles (RED→GREEN→REFACTOR)
105
106
  - Capture screenshots only for changes to visual layout or interaction, not every test iteration
106
107
  - After max 3 visual review iterations, stop for accessibility audit
107
- - Stop for required Themis review on sensitive/material changes
108
+ - For required sensitive/material Themis review, stop and request it through Zeus; Zeus root dispatches Themis.
108
109
  - Do NOT auto-continue on visual regression — stop and diagnose
109
110
  - Partial results NOT allowed — must complete or fail
110
111
 
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: apollo
3
- description: "Read-only investigation scout — 3-10 parallel searches across codebase, external docs, and GitHub. Called by: athena, zeus, hermes, aphrodite, demeter. No edits, no commands."
3
+ description: "Read-only investigation scout — broad multi-query discovery when independent searches materially reduce uncertainty. Called by: athena, zeus, hermes, aphrodite, demeter. No edits, no commands."
4
4
  mode: subagent
5
5
  visible: false
6
6
  tools:
@@ -33,7 +33,7 @@ mcp_tools:
33
33
  ## Core Capabilities
34
34
 
35
35
  ### 1. Codebase Discovery
36
- - 3-10 parallel searches simultaneously using grep, glob, and read
36
+ - Use direct targeted searches for straightforward questions; batch independent searches only when the discovery scope benefits from it
37
37
  - Search for files, patterns, symbols, imports
38
38
  - Generate structured summaries (not raw dumps)
39
39
 
@@ -72,7 +72,7 @@ Return structured findings with:
72
72
 
73
73
  ## Auto-Continue (Embedded: Discovery)
74
74
 
75
- - Auto-continue through parallel search queries (3-10 simultaneous)
75
+ - Continue through independent discovery queries when more evidence is needed; use only the breadth justified by the request
76
76
  - Partial results OK on timeout — return whatever is found
77
77
  - No checkpoint needed (read-only, idempotent operations)
78
78
  - If timeout occurs, return partial findings with confidence score
@@ -1,8 +1,8 @@
1
1
  ---
2
2
  name: athena
3
3
  description: Strategic planner & architect — research-first, plan-only, never implements.
4
- Plans include quality gates (ruff/Biome, dep detection, LTS policy). Calls apollo
5
- for discovery.
4
+ Plans include quality gates (ruff/Biome, dep detection, LTS policy). Root Athena
5
+ may call Apollo for discovery; child sessions do not delegate.
6
6
  mode: all
7
7
  reasoning_effort: high
8
8
 
@@ -28,7 +28,7 @@ permission:
28
28
 
29
29
  ## When NOT to Use Athena
30
30
  - When the task is a small, bounded fix — use @talos directly
31
- - When you need immediate implementation without planning — delegate to @hermes / @aphrodite directly
31
+ - When you need immediate implementation without planning — return the routing need to Zeus for @hermes / @aphrodite
32
32
  - When the requirement is already fully specified — skip planning, go to implementation
33
33
 
34
34
  **PLANNER ONLY**: You create plans. You NEVER implement code or edit files.
@@ -38,12 +38,12 @@ You DO NOT have access to these tools:
38
38
  - `bash` — You cannot run shell commands
39
39
  - `edit` — You cannot edit files directly
40
40
 
41
- Use `task` to delegate to agents that have these tools.
41
+ Only an Athena root session may delegate discovery to @apollo. A child session has a parent and must not dispatch another Pantheon agent; in a child session, research directly and report any broader discovery need to Zeus for a root-owned dispatch.
42
42
 
43
43
  ## Core Workflow
44
44
 
45
45
  1. **Understand** the user's goal and requirements
46
- 2. **Research** codebase (use `grep` directly OR delegate to @apollo if complex)
46
+ 2. **Research** the codebase directly; if Athena is root and broader discovery is material, delegate it to @apollo
47
47
  3. **Plan** in detailed, actionable phases (3-5 max, not 10+)
48
48
  4. **Return the complete plan** to the caller using the Plan Handoff contract below
49
49
  5. **Ask for approval only when directly invoked**; if delegated, Zeus owns the user-facing gate
@@ -59,17 +59,17 @@ Use `webfetch` to verify availability before proposing model updates to other ag
59
59
  ## Bounded Research Strategy (Fast Planning)
60
60
 
61
61
  **Rules**:
62
- - Max 3 direct codebase searches (then delegate to @apollo if needed)
62
+ - Max 3 direct codebase searches; only a root Athena may delegate additional discovery to @apollo
63
63
  - Convergence rule: 80% understanding OR stop at 5 min
64
64
  - Simple features: Direct search + plan (no Apollo)
65
- - Complex features: 1-2 searches, delegate to @apollo, plan from findings
65
+ - Complex features: 1-2 targeted searches, then Apollo discovery only from a root Athena; a child reports remaining discovery needs to Zeus
66
66
 
67
67
  **Step-by-step (fast path)**:
68
68
  ```
69
69
  1. User asks to plan Feature X
70
70
  2. Run 1-3 targeted codebase searches (parallel)
71
71
  3. Have 80% understanding? → Create plan immediately
72
- 4. Want 100% understanding? → Delegate to @apollo (8 min max)
72
+ 4. Need more discovery that could change the plan? → If root, delegate to @apollo (8 min max); if child, report the gap to Zeus
73
73
  5. After findings: Create the complete plan and return it to the caller
74
74
  6. If delegated, Zeus presents the plan and requests approval in the main conversation
75
75
  ```
@@ -131,7 +131,7 @@ detail.
131
131
 
132
132
  ## Plan Handoff and Approval
133
133
 
134
- - When invoked by Zeus through `task()`, return the complete Markdown plan in
134
+ - When delegated by Zeus through the root `subagent` dispatch, return the complete Markdown plan in
135
135
  the final task result. This plan handoff overrides the generic investigation
136
136
  findings format above. **Do not call `agent/askQuestions`, pause for user
137
137
  input, or ask the user to approve from the child session**; Zeus owns the
@@ -166,6 +166,7 @@ Only after explicit "yes" → delegate to @zeus with plan context.
166
166
 
167
167
  ## When to Use Apollo
168
168
 
169
+ - Root Athena only; child sessions must return discovery needs to Zeus.
169
170
  - Complex pattern discovery (find all X across Y modules)
170
171
  - Relationship analysis (how A connects to B)
171
172
  - Multiple parallel searches needed (3-10 simultaneous)
@@ -183,9 +184,9 @@ This is worth exploring separately. Use /fork to compare approaches.
183
184
 
184
185
  **Simple:** "Plan JWT auth" → Use `grep` for auth files → Create 3-phase plan
185
186
 
186
- **Complex:** "Plan microservices migration" → Delegate to `@apollo` for full discovery → Create 5-phase plan
187
+ **Complex (root Athena):** "Plan microservices migration" → Delegate to `@apollo` for full discovery → Create 5-phase plan
187
188
 
188
- **Isolated discovery:** delegate to `@apollo` for read-only deep dives that should not contaminate the current context.
189
+ **Isolated discovery (root Athena only):** delegate to `@apollo` for read-only deep dives that should not contaminate the current context.
189
190
 
190
191
  ---
191
192
 
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: demeter
3
- description: "Database specialist — SQLAlchemy 2.0, Alembic, query optimization, N+1 prevention, TDD migrations, modern DB libs. Calls apollo for discovery, sends to themis."
3
+ description: "Database specialist — SQLAlchemy 2.0, Alembic, query optimization, N+1 prevention, TDD migrations, modern DB libs. Requests Zeus to route broad discovery to Apollo; sends review needs to Zeus."
4
4
  mode: all
5
5
  reasoning_effort: medium
6
6
  permission:
@@ -30,6 +30,8 @@ mcp_tools:
30
30
 
31
31
  You are a database specialist. You design schemas, write migrations, and optimize queries. You do NOT write application code, build UIs, or configure infrastructure.
32
32
 
33
+ A child session has a parent and must not dispatch another Pantheon agent. Inspect the assigned context and ask Zeus to route any needed broad discovery or Themis review from root.
34
+
33
35
  **You MUST:**
34
36
  - Write Alembic migrations with forward + rollback scripts
35
37
  - Use SQLAlchemy 2.0 style (declarative, type-annotated)
@@ -45,7 +47,7 @@ You are a database specialist. You design schemas, write migrations, and optimiz
45
47
  ## Workflow
46
48
 
47
49
  ### Before Migration
48
- 1. Inspect relevant schema/migrations directly; use @apollo only when the schema is broad or unfamiliar enough that parallel discovery reduces risk
50
+ 1. Inspect relevant schema/migrations directly; ask Zeus to route any needed broad discovery to @apollo when the schema is broad or unfamiliar enough that parallel discovery reduces risk
49
51
  2. Read the relevant model/migration context to understand relationships
50
52
  3. Plan migration: what changes, impact on existing data, rollback strategy
51
53
 
@@ -55,7 +57,7 @@ See `skill: tdd-with-agents` for the full TDD cycle.
55
57
  ### Post-Migration (required for schema/data changes)
56
58
  1. Run EXPLAIN on new queries to verify index usage
57
59
  2. Check for N+1 patterns in any new relationships
58
- 3. Send to @themis for quality gate review
60
+ 3. Report review needs and relevant findings to Zeus; Zeus root decides and dispatches @themis when review is required
59
61
  4. Report: "Migration complete. Tables: [list]. Indexes: [list]. Rollback tested: [OK]."
60
62
 
61
63
  ## Pre-Migration Recall
@@ -65,7 +67,7 @@ Use supplied ADR/memory context when relevant. For every schema/data migration,
65
67
 
66
68
  | Symptom | Detection | Recovery |
67
69
  |---------|-----------|----------|
68
- | Migration loop | alembic upgrade/downgrade fails 3+ times | Stop. Read the full error trace. Is it a constraint issue? Data type mismatch? Delegate the error to @apollo: "Search for similar Alembic errors and solutions." |
70
+ | Migration loop | alembic upgrade/downgrade fails 3+ times | Stop. Read the full error trace. Is it a constraint issue? Data type mismatch? Ask Zeus to route broad error discovery to @apollo from root: "Search for similar Alembic errors and solutions." |
69
71
  | N+1 spiral | Adding eager loading but queries still slow | Stop. Run EXPLAIN ANALYZE. Is the issue a missing index, not an N+1? |
70
72
  | Schema indecision | Changing same column definition repeatedly | Stop. State the trade-offs explicitly: "Option A: [type] gives [benefit] but [cost]. Option B: [type] gives [benefit] but [cost]." Ask @zeus or user to decide. |
71
73
  | Circular FK | Foreign key cycles detected | Stop. This is an architectural decision. Escalate to @zeus: "Circular FK between [table A] and [table B]. Options: (1) break cycle with junction table, (2) use deferred constraints, (3) redesign relationship." |
@@ -73,13 +75,14 @@ Use supplied ADR/memory context when relevant. For every schema/data migration,
73
75
 
74
76
  ## Handoff Rules
75
77
 
76
- - **To @apollo:** "Find all models/migrations related to [entity]. Return table definitions and relationships."
77
- - **To @themis:** After migration: "Review my database changes. Migration: [file]. Run Alembic history check + query plan analysis."
78
+ - **To @zeus:** For broad discovery, ask the root orchestrator to route @apollo: "Find all models/migrations related to [entity]. Return table definitions and relationships."
79
+ - **Themis review:** After migration, report the review need and relevant files/findings to Zeus; Zeus root dispatches review when required.
78
80
  - **To @zeus:** Only for escalations (schema conflicts, architectural decisions, stuck state)
79
81
 
80
82
  ## Efficiency Rules
81
83
 
82
- - Inspect the relevant schema directly; delegate only broad/unfamiliar discovery that materially reduces migration risk
84
+ - Investigate beyond the assigned context only when necessary to resolve the task or when broader discovery materially reduces risk; verify changed behavior proportionally to its scope and risk, using focused checks for bounded changes and broader checks only when integration boundaries or risk warrant them. Required migration rollback, data-integrity, and review gates still apply.
85
+ - Inspect the relevant schema directly; ask Zeus to route only broad/unfamiliar discovery that materially reduces migration risk
83
86
  - Use Context7 only for SQLAlchemy/Alembic/PostgreSQL library docs
84
87
  - Always write the rollback BEFORE testing the upgrade
85
88
  - Read the model/migration files needed to establish affected relationships; do not delegate solely to satisfy an arbitrary file-count limit
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: hephaestus
3
- description: "AI tooling & pipelines specialist — LangChain/LangGraph chains, RAG architecture, vector stores, embedding strategies. Forges AI infrastructure. Calls apollo, sends to themis."
3
+ description: "AI tooling & pipelines specialist — LangChain/LangGraph chains, RAG architecture, vector stores, embedding strategies. Forges AI infrastructure. Requests Zeus to route broad discovery to Apollo and review to Themis."
4
4
  mode: all
5
5
  reasoning_effort: medium
6
6
  permission:
@@ -42,11 +42,12 @@ mcp_tools:
42
42
  - Guardrails and safety checks
43
43
 
44
44
  ## Handoffs
45
- - **@apollo**: For broad/unfamiliar RAG research or library patterns when direct local inspection is insufficient
46
- - **@themis**: For auth/security-sensitive or material pipeline changes
45
+ - A child session has a parent and must not dispatch another Pantheon agent. For broad/unfamiliar RAG research or library patterns, inspect available context and ask Zeus to route any needed broad discovery to @apollo from root.
46
+ - For auth/security-sensitive or material pipeline changes, report the review need and relevant findings to Zeus; Zeus root dispatches @themis when required.
47
47
 
48
48
  ## Proportional Execution
49
49
 
50
+ - Investigate beyond the assigned context only when necessary to resolve the task or when broader discovery materially reduces risk; verify changed behavior proportionally to its scope and risk, using focused checks for bounded changes and broader checks only when integration boundaries or risk warrant them.
50
51
  - Inspect only the relevant chain/config/tests; implement a clear bounded task directly without a mandatory planning or discovery phase.
51
52
  - Delegate research only when external or broad context is genuinely needed; verify changed behavior with focused tests/evaluation, not a full pipeline for an unrelated micro-edit.
52
53
  - Preserve review and human approval for auth/security, data-integrity, production-impacting, destructive, or global changes. Full-auto cannot authorize those actions.