pantheon-opencode 1.6.3-beta.1 → 1.6.3-beta.11
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/AGENTS.global.md +1 -1
- package/AGENTS.md +1 -1
- package/CHANGELOG.md +81 -0
- package/README.md +20 -2
- package/bin/pantheon-init.mjs +15 -27
- package/package.json +1 -1
- package/plugin.json +1 -1
- package/pyproject.toml +1 -1
- package/scripts/decision-router-budget.mjs +103 -4
- package/scripts/decision-router-v2-budget.mjs +2 -2
- package/scripts/decision-router-v2-egress.mjs +0 -2
- package/scripts/decision-router.mjs +88 -6
- package/scripts/install/decision-router-config.mjs +53 -2
- package/scripts/install/interactive.mjs +96 -11
- package/scripts/install/opencode.mjs +26 -0
- package/scripts/install/plugin.mjs +17 -0
- package/scripts/jev-live-probe.mjs +210 -0
- package/scripts/skill-search.mjs +242 -0
- package/scripts/sync-tui.mjs +11 -0
- package/src/agents/aphrodite.md +34 -1
- package/src/agents/apollo.md +227 -0
- package/src/agents/athena.md +24 -0
- package/src/agents/demeter.md +33 -0
- package/src/agents/gaia.md +24 -0
- package/src/agents/hephaestus.md +24 -0
- package/src/agents/hermes.md +33 -0
- package/src/agents/iris.md +24 -0
- package/src/agents/mnemosyne.md +25 -3
- package/src/agents/nyx.md +53 -22
- package/src/agents/prometheus.md +242 -1
- package/src/agents/talos.md +24 -0
- package/src/agents/themis.md +24 -0
- package/src/agents/zeus.md +46 -6
- package/src/pantheon/j-telemetry-file.ts +96 -0
- package/src/pantheon/jev-decision-tool.ts +160 -24
- package/src/pantheon/jev-decisions.ts +18 -3
- package/src/pantheon/jev-rank-verify.ts +435 -0
- package/src/pantheon/jev-risk-gate.ts +1 -0
- package/src/pantheon/local-decision-budget.ts +170 -5
- package/src/pantheon/local-decision-provider-matrix.ts +0 -1
- package/src/pantheon/local-decision-usage-evidence.internal.ts +2 -2
- package/src/pantheon/v2-decision-budget.ts +4 -2
- package/src/plugin-v2.ts +9 -2
- package/src/plugins/tui/dist/tui-v2.d.ts.map +1 -1
- package/src/plugins/tui/dist/tui-v2.js +457 -4
- package/src/plugins/tui/dist/tui-v2.js.map +1 -1
- package/src/plugins/tui/dist/tui.js +1 -1
- package/src/plugins/tui/package-lock.json +2 -2
- package/src/plugins/tui/package.json +1 -1
- package/src/plugins/tui/src/index-v2.tsx +6 -0
- package/src/plugins/tui/src/whats-new-highlights.ts +263 -0
- package/src/plugins/tui/src/whats-new-open.ts +80 -0
- package/src/plugins/tui/src/whats-new-state.ts +128 -0
- package/src/plugins/tui/src/whats-new.tsx +119 -0
|
@@ -0,0 +1,242 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* skill-search.mjs — read-only search over the open skills ecosystem
|
|
4
|
+
* (skills.sh via the `skills` CLI) for the discovery pipeline documented in
|
|
5
|
+
* `docs/reference/native-decisions.md` and `src/agents/zeus.md`.
|
|
6
|
+
*
|
|
7
|
+
* The ladder this tool serves: installed skills first (one Jev
|
|
8
|
+
* `mode: "skills"` call answers over the local pool); only when nothing fits
|
|
9
|
+
* does the agent search the ecosystem, rank what came back with one typed
|
|
10
|
+
* Jev choice question, and PROPOSE the project-scoped install to the user —
|
|
11
|
+
* Pantheon never installs, and third-party skills are untrusted instructions.
|
|
12
|
+
*
|
|
13
|
+
* The `skills find` CLI prints ANSI-colored human text; this wrapper strips
|
|
14
|
+
* the escapes and emits the parseable contract (`owner/repo@skill`,
|
|
15
|
+
* install count, skills.sh URL) as JSON — the same contract the agent-side
|
|
16
|
+
* inline parse follows. Read-only: it never adds, updates, or removes
|
|
17
|
+
* skills, and no credentials cross it.
|
|
18
|
+
*
|
|
19
|
+
* Usage:
|
|
20
|
+
* node scripts/skill-search.mjs "<query>" [--limit 5] [--owner <owner>] [--raw]
|
|
21
|
+
*/
|
|
22
|
+
|
|
23
|
+
import { spawnSync } from 'node:child_process'
|
|
24
|
+
import { pathToFileURL } from 'node:url'
|
|
25
|
+
|
|
26
|
+
const FIND_TIMEOUT_MS = 60_000
|
|
27
|
+
const DEFAULT_LIMIT = 5
|
|
28
|
+
/** SGR escape sequences are matched via the ESC codepoint (lint-clean, same semantics). */
|
|
29
|
+
const ANSI_SGR = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, 'g')
|
|
30
|
+
const SKILL_LINE = /^([A-Za-z0-9._-]+\/[A-Za-z0-9._-]+@[A-Za-z0-9._-]+)\s+(\d+)\s+installs$/
|
|
31
|
+
const URL_LINE = /^└?\s*(https:\/\/skills\.sh\/\S+)$/
|
|
32
|
+
|
|
33
|
+
/** Remove SGR escape sequences so the text lines become parseable. */
|
|
34
|
+
export function stripAnsi(text) {
|
|
35
|
+
return String(text).replace(ANSI_SGR, '')
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* Parse `skills find` output into ordered entries {skill, installs, url?}.
|
|
40
|
+
* `limit` (default 5) caps the result; entries keep the CLI's printed order
|
|
41
|
+
* (the ecosystem's own ranking), never re-sorted here.
|
|
42
|
+
*/
|
|
43
|
+
export function parseSkillSearchOutput(raw, { limit = DEFAULT_LIMIT } = {}) {
|
|
44
|
+
const lines = stripAnsi(raw)
|
|
45
|
+
.split('\n')
|
|
46
|
+
.map((line) => line.trim())
|
|
47
|
+
.filter((line) => line.length > 0)
|
|
48
|
+
const found = []
|
|
49
|
+
for (const line of lines) {
|
|
50
|
+
const skillMatch = line.match(SKILL_LINE)
|
|
51
|
+
if (skillMatch !== null) {
|
|
52
|
+
if (found.length >= limit) continue
|
|
53
|
+
found.push({ skill: skillMatch[1], installs: Number(skillMatch[2]), url: undefined })
|
|
54
|
+
continue
|
|
55
|
+
}
|
|
56
|
+
const urlMatch = line.match(URL_LINE)
|
|
57
|
+
if (urlMatch !== null && found.length > 0) {
|
|
58
|
+
const last = found[found.length - 1]
|
|
59
|
+
if (last.url === undefined) last.url = urlMatch[1]
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
return found
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
/** Run the ecosystem search once and return parsed entries. */
|
|
66
|
+
export function searchSkills(query, { limit = DEFAULT_LIMIT, owner, spawn = spawnSync } = {}) {
|
|
67
|
+
const args = ['skills', 'find', String(query)]
|
|
68
|
+
if (owner !== undefined) args.push('--owner', String(owner))
|
|
69
|
+
const result = spawn('npx', args, {
|
|
70
|
+
encoding: 'utf8',
|
|
71
|
+
timeout: FIND_TIMEOUT_MS,
|
|
72
|
+
stdio: ['ignore', 'pipe', 'pipe'],
|
|
73
|
+
})
|
|
74
|
+
if (result.error !== undefined) {
|
|
75
|
+
return { ok: false, error: `skills search failed to start: ${result.error.message}` }
|
|
76
|
+
}
|
|
77
|
+
const raw = `${result.stdout ?? ''}`
|
|
78
|
+
if (result.status !== 0 && raw.trim() === '') {
|
|
79
|
+
return { ok: false, error: `skills search exited ${result.status}` }
|
|
80
|
+
}
|
|
81
|
+
return { ok: true, entries: parseSkillSearchOutput(raw, { limit }), raw }
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
const GITHUB_TIMEOUT_MS = 30_000
|
|
85
|
+
const ANTHROPIC_SKILLS_REPO = 'anthropics/skills'
|
|
86
|
+
|
|
87
|
+
/**
|
|
88
|
+
* Tier 1: the canonical Anthropic catalog. Highest trust (curated upstream),
|
|
89
|
+
* checked first so the canonical `pdf`/`docx`/`xlsx`/`mcp-builder` skills
|
|
90
|
+
* outrank the third-party clones that skills.sh's ranking can surface.
|
|
91
|
+
* Matches query tokens against catalog entry names; returns one entry per
|
|
92
|
+
* matched name.
|
|
93
|
+
*/
|
|
94
|
+
export function searchAnthropicCatalog(query, { limit = DEFAULT_LIMIT, spawn = spawnSync } = {}) {
|
|
95
|
+
const result = spawn(
|
|
96
|
+
'gh',
|
|
97
|
+
['api', `repos/${ANTHROPIC_SKILLS_REPO}/contents/skills`, '--jq', '.[].name'],
|
|
98
|
+
{ encoding: 'utf8', timeout: GITHUB_TIMEOUT_MS, stdio: ['ignore', 'pipe', 'pipe'] },
|
|
99
|
+
)
|
|
100
|
+
if (result.error !== undefined || result.status !== 0) {
|
|
101
|
+
return { ok: false, error: 'anthropic catalog lookup failed (gh api)' }
|
|
102
|
+
}
|
|
103
|
+
const tokens = String(query)
|
|
104
|
+
.toLowerCase()
|
|
105
|
+
.split(/[^a-z0-9]+/)
|
|
106
|
+
.filter((token) => token.length > 2)
|
|
107
|
+
const names = String(result.stdout ?? '')
|
|
108
|
+
.split('\n')
|
|
109
|
+
.map((name) => name.trim())
|
|
110
|
+
.filter((name) => name.length > 0)
|
|
111
|
+
const matched = names.filter((name) => {
|
|
112
|
+
const lower = name.toLowerCase()
|
|
113
|
+
return tokens.some((token) => lower.includes(token))
|
|
114
|
+
})
|
|
115
|
+
return {
|
|
116
|
+
ok: true,
|
|
117
|
+
entries: matched.slice(0, limit).map((name) => ({
|
|
118
|
+
skill: `${ANTHROPIC_SKILLS_REPO}@${name}`,
|
|
119
|
+
installs: null,
|
|
120
|
+
url: `https://github.com/${ANTHROPIC_SKILLS_REPO}/tree/main/skills/${name}`,
|
|
121
|
+
source: 'anthropic',
|
|
122
|
+
})),
|
|
123
|
+
}
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
/**
|
|
127
|
+
* Tier 3: raw GitHub code search over every `SKILL.md` (the widest net —
|
|
128
|
+
* orders of magnitude beyond the skills.sh index, and the weakest trust:
|
|
129
|
+
* every hit is unreviewed third-party instructions).
|
|
130
|
+
*/
|
|
131
|
+
export function searchGithubSkills(query, { limit = DEFAULT_LIMIT, spawn = spawnSync } = {}) {
|
|
132
|
+
const terms = String(query)
|
|
133
|
+
.split(/\s+/)
|
|
134
|
+
.filter((term) => term.length > 1)
|
|
135
|
+
.slice(0, 3)
|
|
136
|
+
.map((term) => encodeURIComponent(term))
|
|
137
|
+
.join('+')
|
|
138
|
+
if (terms === '') return { ok: true, entries: [] }
|
|
139
|
+
const result = spawn(
|
|
140
|
+
'gh',
|
|
141
|
+
['api', `search/code?q=filename:SKILL.md+${terms}&per_page=${Math.min(limit, 10)}`],
|
|
142
|
+
{ encoding: 'utf8', timeout: GITHUB_TIMEOUT_MS, stdio: ['ignore', 'pipe', 'pipe'] },
|
|
143
|
+
)
|
|
144
|
+
if (result.error !== undefined || result.status !== 0) {
|
|
145
|
+
return { ok: false, error: 'github code search failed (gh api)' }
|
|
146
|
+
}
|
|
147
|
+
let parsed
|
|
148
|
+
try {
|
|
149
|
+
parsed = JSON.parse(String(result.stdout ?? '{}'))
|
|
150
|
+
} catch {
|
|
151
|
+
return { ok: false, error: 'github code search returned non-JSON output' }
|
|
152
|
+
}
|
|
153
|
+
const items = Array.isArray(parsed.items) ? parsed.items : []
|
|
154
|
+
return {
|
|
155
|
+
ok: true,
|
|
156
|
+
entries: items.slice(0, limit).map((item) => {
|
|
157
|
+
const repo = String(item?.repository?.full_name ?? 'unknown/repo')
|
|
158
|
+
const path = String(item?.path ?? 'SKILL.md')
|
|
159
|
+
const name = path.split('/')[Math.max(0, path.split('/').length - 2)] ?? 'skill'
|
|
160
|
+
return {
|
|
161
|
+
skill: `${repo}@${name}`,
|
|
162
|
+
installs: null,
|
|
163
|
+
url: `https://github.com/${repo}/blob/main/${path}`,
|
|
164
|
+
source: 'github',
|
|
165
|
+
}
|
|
166
|
+
}),
|
|
167
|
+
}
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
/**
|
|
171
|
+
* The trust cascade: anthropic (canonical) → skills-sh (install-count
|
|
172
|
+
* signal, unreviewed) → github (widest, least trusted). Tier order is the
|
|
173
|
+
* recommendation order; callers may narrow with `sources`.
|
|
174
|
+
*/
|
|
175
|
+
export const SKILL_SEARCH_SOURCES = Object.freeze(['anthropic', 'skills-sh', 'github'])
|
|
176
|
+
|
|
177
|
+
export function searchSkillSources(
|
|
178
|
+
query,
|
|
179
|
+
{ limit = DEFAULT_LIMIT, owner, sources = SKILL_SEARCH_SOURCES, spawn = spawnSync } = {},
|
|
180
|
+
) {
|
|
181
|
+
const perTier = Math.max(1, Math.ceil(limit / sources.length))
|
|
182
|
+
const out = []
|
|
183
|
+
const failures = []
|
|
184
|
+
for (const source of sources) {
|
|
185
|
+
const result =
|
|
186
|
+
source === 'anthropic'
|
|
187
|
+
? searchAnthropicCatalog(query, { limit: perTier, spawn })
|
|
188
|
+
: source === 'skills-sh'
|
|
189
|
+
? searchSkills(query, { limit: perTier, owner, spawn })
|
|
190
|
+
: source === 'github'
|
|
191
|
+
? searchGithubSkills(query, { limit: perTier, spawn })
|
|
192
|
+
: { ok: false, error: `unknown source: ${source}` }
|
|
193
|
+
if (result.ok) out.push(...result.entries.map((entry) => ({ ...entry, source })))
|
|
194
|
+
else failures.push(`${source}: ${result.error}`)
|
|
195
|
+
}
|
|
196
|
+
return { ok: failures.length < sources.length, entries: out.slice(0, limit), failures }
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
function main(args = process.argv.slice(2)) {
|
|
200
|
+
const get = (flag) => {
|
|
201
|
+
const i = args.indexOf(flag)
|
|
202
|
+
return i >= 0 ? args[i + 1] : undefined
|
|
203
|
+
}
|
|
204
|
+
const query = args.find((a) => !a.startsWith('--'))
|
|
205
|
+
if (query === undefined) {
|
|
206
|
+
console.error(
|
|
207
|
+
'usage: node scripts/skill-search.mjs "<query>" [--limit 5] [--sources anthropic,skills-sh,github] [--owner <owner>] [--raw]',
|
|
208
|
+
)
|
|
209
|
+
process.exit(1)
|
|
210
|
+
}
|
|
211
|
+
const sourcesArg = get('--sources')
|
|
212
|
+
const sources =
|
|
213
|
+
sourcesArg === undefined
|
|
214
|
+
? SKILL_SEARCH_SOURCES
|
|
215
|
+
: sourcesArg
|
|
216
|
+
.split(',')
|
|
217
|
+
.map((s) => s.trim())
|
|
218
|
+
.filter((s) => s.length > 0)
|
|
219
|
+
const result = searchSkillSources(query, {
|
|
220
|
+
limit: Number(get('--limit') ?? DEFAULT_LIMIT),
|
|
221
|
+
owner: get('--owner'),
|
|
222
|
+
sources,
|
|
223
|
+
})
|
|
224
|
+
if (args.includes('--raw')) {
|
|
225
|
+
const skillsSh = result.entries.filter((e) => e.source === 'skills-sh')
|
|
226
|
+
console.log(JSON.stringify(skillsSh, null, 1))
|
|
227
|
+
return
|
|
228
|
+
}
|
|
229
|
+
if (result.failures.length > 0) {
|
|
230
|
+
for (const failure of result.failures) console.error(`warning: ${failure}`)
|
|
231
|
+
}
|
|
232
|
+
if (result.entries.length === 0 && result.failures.length === sources.length) {
|
|
233
|
+
console.error('all sources failed')
|
|
234
|
+
process.exit(1)
|
|
235
|
+
}
|
|
236
|
+
console.log(JSON.stringify(result.entries, null, 1))
|
|
237
|
+
}
|
|
238
|
+
|
|
239
|
+
const invokedDirectly =
|
|
240
|
+
process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href
|
|
241
|
+
|
|
242
|
+
if (invokedDirectly) main()
|
package/scripts/sync-tui.mjs
CHANGED
|
@@ -106,6 +106,17 @@ export function copyPluginFiles(srcDir, dstDir, version) {
|
|
|
106
106
|
else result.skipped++
|
|
107
107
|
}
|
|
108
108
|
|
|
109
|
+
// CHANGELOG.md — the copy's one-time "What's new" window reads the release
|
|
110
|
+
// highlights for the running version from its own installed root. Best
|
|
111
|
+
// effort: a missing source simply means no window (the TUI fails open).
|
|
112
|
+
// src/plugins/tui → src/plugins → src → package root.
|
|
113
|
+
const changelogSrc = join(srcDir, '..', '..', '..', 'CHANGELOG.md')
|
|
114
|
+
if (existsSync(changelogSrc)) {
|
|
115
|
+
if (writeIfChanged(join(dstDir, 'CHANGELOG.md'), readFileSync(changelogSrc, 'utf8'))) {
|
|
116
|
+
result.created++
|
|
117
|
+
} else result.skipped++
|
|
118
|
+
}
|
|
119
|
+
|
|
109
120
|
const tuiEntry = join(srcDir, version === 'v2' ? 'tui-v2.ts' : 'tui.ts')
|
|
110
121
|
if (existsSync(tuiEntry)) {
|
|
111
122
|
if (writeIfChanged(join(dstDir, 'tui.ts'), readFileSync(tuiEntry, 'utf8'))) result.created++
|
package/src/agents/aphrodite.md
CHANGED
|
@@ -30,6 +30,30 @@ mcp_tools:
|
|
|
30
30
|
pantheon-vision: [vision_describe, vision_ocr, vision_analyze]
|
|
31
31
|
---
|
|
32
32
|
|
|
33
|
+
## MCP governance (identical ladder, grant-aware)
|
|
34
|
+
|
|
35
|
+
- Escalation order: session context first; the local selector answers free;
|
|
36
|
+
one typed `pantheon_jev_decide` question when genuinely ambiguous (Zeus
|
|
37
|
+
dispatches; a returned label is an advisory, never authorization); a
|
|
38
|
+
native MCP call is the LAST resort for state the session cannot
|
|
39
|
+
reconstruct.
|
|
40
|
+
- **Memory recall/search** — at most one selective query per turn, only when
|
|
41
|
+
prior project history could change the decision; never for context you
|
|
42
|
+
already hold. Every result rides in your context for the rest of the
|
|
43
|
+
session.
|
|
44
|
+
- **Memory store** (only where granted) — durable, reusable facts ONLY:
|
|
45
|
+
decisions with reasons, root causes, conventions, user preferences.
|
|
46
|
+
Session narration never stores: subtask summaries, delegation status and
|
|
47
|
+
debugging play-by-play go to a checkpoint or nowhere. Namespace per
|
|
48
|
+
project; update an existing key instead of duplicating.
|
|
49
|
+
- **Persistence checkpoints** (only where granted) — milestones only: would
|
|
50
|
+
losing this be expensive to redo? Never per turn; never re-save an
|
|
51
|
+
unchanged key.
|
|
52
|
+
- **Vision** (only where granted) — only when the turn carries an
|
|
53
|
+
addressable image; one pass per image; each call is real gateway spend.
|
|
54
|
+
- **Code-mode / infrastructure reads** — cheap and on demand; never for
|
|
55
|
+
decisions the ladder already answers.
|
|
56
|
+
|
|
33
57
|
## Verification Tiers
|
|
34
58
|
|
|
35
59
|
Small bounded fix → change + one targeted proof, no ceremony. Material change → full test discipline. Match the tier to the change.
|
|
@@ -63,7 +87,7 @@ You are a frontend implementation specialist. You BUILD UI. You do NOT design ar
|
|
|
63
87
|
1. Inspect relevant component/test/API files directly; when broad or unfamiliar discovery materially reduces risk, send the discovery need to Zeus for routing
|
|
64
88
|
2. Read relevant frontend standards; load `skill: visual-review-pipeline` only when visual behavior changed
|
|
65
89
|
3. Plan component/data flow when scope or risk warrants it; do not require a design phase for a bounded fix
|
|
66
|
-
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.
|
|
90
|
+
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. One pass per image: `vision_describe` for visual review, `vision_ocr` only when text extraction is the goal — never two vision calls on the same screenshot (each call is real gateway spend). 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.
|
|
67
91
|
- 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.
|
|
68
92
|
|
|
69
93
|
### Implementation (TDD)
|
|
@@ -119,3 +143,12 @@ After implementing UI components:
|
|
|
119
143
|
|
|
120
144
|
## Skills
|
|
121
145
|
Frontend: `tdd-with-agents`, `visual-review-pipeline`, `incremental-implementation`
|
|
146
|
+
|
|
147
|
+
## Domain conventions doc
|
|
148
|
+
|
|
149
|
+
If this project has a real UI/frontend surface, keep `docs/ui/conventions.md` current as you
|
|
150
|
+
work: stack versions, decided patterns, the conventions this project actually
|
|
151
|
+
follows. Read it first when it exists; propose creating it when the surface
|
|
152
|
+
exists and the file does not. Update only what you changed — a stale
|
|
153
|
+
convention line is worse than a missing one. The next session starts from
|
|
154
|
+
this file, not from your memory.
|
package/src/agents/apollo.md
CHANGED
|
@@ -35,6 +35,233 @@ mcp_tools:
|
|
|
35
35
|
- When you need to modify files — Apollo is read-only
|
|
36
36
|
- When the search can be done with a simple grep/glob — use direct tools instead
|
|
37
37
|
|
|
38
|
+
## MCP governance (identical ladder, grant-aware)
|
|
39
|
+
|
|
40
|
+
- Escalation order: session context first; the local selector answers free;
|
|
41
|
+
one typed `pantheon_jev_decide` question when genuinely ambiguous (Zeus
|
|
42
|
+
dispatches; a returned label is an advisory, never authorization); a
|
|
43
|
+
native MCP call is the LAST resort for state the session cannot
|
|
44
|
+
reconstruct.
|
|
45
|
+
- **Memory recall/search** — at most one selective query per turn, only when
|
|
46
|
+
prior project history could change the decision; never for context you
|
|
47
|
+
already hold. Every result rides in your context for the rest of the
|
|
48
|
+
session.
|
|
49
|
+
- **Memory store** (only where granted) — durable, reusable facts ONLY:
|
|
50
|
+
decisions with reasons, root causes, conventions, user preferences.
|
|
51
|
+
Session narration never stores: subtask summaries, delegation status and
|
|
52
|
+
debugging play-by-play go to a checkpoint or nowhere. Namespace per
|
|
53
|
+
project; update an existing key instead of duplicating.
|
|
54
|
+
- **Persistence checkpoints** (only where granted) — milestones only: would
|
|
55
|
+
losing this be expensive to redo? Never per turn; never re-save an
|
|
56
|
+
unchanged key.
|
|
57
|
+
- **Vision** (only where granted) — only when the turn carries an
|
|
58
|
+
addressable image; one pass per image; each call is real gateway spend.
|
|
59
|
+
- **Code-mode / infrastructure reads** — cheap and on demand; never for
|
|
60
|
+
decisions the ladder already answers.
|
|
61
|
+
|
|
62
|
+
## Core Capabilities
|
|
63
|
+
|
|
64
|
+
### 1. **Test-Driven Development**
|
|
65
|
+
See `skill: tdd-with-agents` for the full TDD cycle.
|
|
66
|
+
|
|
67
|
+
### 2. **Context Conservation**
|
|
68
|
+
- Focus ONLY on files you're modifying
|
|
69
|
+
- Don't re-read entire project architecture
|
|
70
|
+
- Return summaries of your changes
|
|
71
|
+
- Ask the Orchestrator only when missing context or a material choice blocks safe progress
|
|
72
|
+
|
|
73
|
+
### 3. **Proper Handoffs**
|
|
74
|
+
- Use a supplied plan when one exists; do not require one for bounded work
|
|
75
|
+
- Ask a clarifying question only when ambiguity blocks a safe implementation
|
|
76
|
+
- Return clear, structured results
|
|
77
|
+
- Report readiness for next phase
|
|
78
|
+
|
|
79
|
+
### 4. **Parallel Execution Mode**
|
|
80
|
+
- Zeus may dispatch @aphrodite and @demeter in parallel on independent scopes; a Hermes child session works only its assigned scope and reports coordination needs to Zeus
|
|
81
|
+
- Your scope: backend files only (routers, services, tests)
|
|
82
|
+
- Signal clearly when done; preserve Themis review for security/auth, data/schema, and material changes
|
|
83
|
+
- Do NOT wait for other workers to finish before starting your work
|
|
84
|
+
|
|
85
|
+
## Search Policy
|
|
86
|
+
- 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.
|
|
87
|
+
- You do NOT perform web searches directly
|
|
88
|
+
- Inspect relevant files directly; only a root Hermes session may delegate discovery to @apollo when broad/unfamiliar discovery materially reduces risk. A child session has a parent and must not dispatch another Pantheon agent; report wider discovery needs to Zeus.
|
|
89
|
+
- For library documentation → Context7 is allowed for library documentation (FastAPI, SQLAlchemy, Pydantic)
|
|
90
|
+
- For web research → a root Hermes may delegate to @apollo; a child session asks Zeus to route it
|
|
91
|
+
- Only use `webfetch` for specific URLs you already know (not for general search)
|
|
92
|
+
|
|
93
|
+
## MCP Security: PostgreSQL
|
|
94
|
+
|
|
95
|
+
> **Risk level: HIGH** — Read-only query capability, but injection still possible.
|
|
96
|
+
|
|
97
|
+
### Parameterized Query Mandate
|
|
98
|
+
- **NEVER** use f-strings, `format()`, or `+` concatenation for SQL query construction
|
|
99
|
+
- **ALWAYS** use parameterized queries:
|
|
100
|
+
```python
|
|
101
|
+
# [OK] SAFE — parameterized
|
|
102
|
+
psql_query("SELECT * FROM products WHERE id = $1", [product_id])
|
|
103
|
+
|
|
104
|
+
# [FAIL] UNSAFE — string interpolation
|
|
105
|
+
psql_query(f"SELECT * FROM products WHERE id = {product_id}")
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
### Read-Only Constraint
|
|
109
|
+
- `postgresql_query` for SELECT only — NEVER for DDL, INSERT, UPDATE, DELETE, or EXECUTE
|
|
110
|
+
- If write access is needed, ask Zeus to route the database work to **@demeter** (they have `postgresql_execute` with stricter controls); a child session does not dispatch it directly.
|
|
111
|
+
|
|
112
|
+
### Verify Query Before Execution
|
|
113
|
+
- Check the SQL string for string interpolation patterns (`f"`, `.format(`, `+`)
|
|
114
|
+
- If any found, rewrite with parameterized syntax before executing
|
|
115
|
+
|
|
116
|
+
## Core Responsibilities
|
|
117
|
+
|
|
118
|
+
### 1. FastAPI Endpoints & Routers
|
|
119
|
+
- Create async endpoints with proper HTTP methods (GET, POST, PUT, PATCH, DELETE)
|
|
120
|
+
- Implement routers for domain logic (auth, media, products, offers, etc.)
|
|
121
|
+
- Use Pydantic schemas for request/response validation
|
|
122
|
+
- Apply dependency injection for database sessions, authentication
|
|
123
|
+
- Implement pagination, filtering, sorting in list endpoints
|
|
124
|
+
|
|
125
|
+
### 2. Service Layer Architecture
|
|
126
|
+
- Build service classes with business logic isolated from routers
|
|
127
|
+
- Implement service methods: `create`, `read`, `update`, `delete`, `list`, `search`
|
|
128
|
+
- Use async/await for I/O operations (database, external APIs)
|
|
129
|
+
- Handle errors gracefully with FastAPI HTTPException
|
|
130
|
+
- Integrate with external services (Gemini AI, R2 storage, Telegram)
|
|
131
|
+
|
|
132
|
+
### 3. Integration Points
|
|
133
|
+
- **Database**: SQLAlchemy async sessions via dependency injection
|
|
134
|
+
- **Cache**: Caching layer (e.g., Redis) for session management and API caching
|
|
135
|
+
- **Storage**: Object storage for media uploads (e.g., S3, R2, GCS)
|
|
136
|
+
- **External APIs**: REST/gRPC integrations (AI services, payment, messaging, etc.)
|
|
137
|
+
|
|
138
|
+
### 4. Security & Performance
|
|
139
|
+
- JWT authentication with httpOnly cookies
|
|
140
|
+
- CSRF protection via middleware
|
|
141
|
+
- Rate limiting for public endpoints
|
|
142
|
+
- Input validation and sanitization
|
|
143
|
+
- Query optimization (avoid N+1 problems)
|
|
144
|
+
- Async operations for concurrent requests
|
|
145
|
+
|
|
146
|
+
## Project Context
|
|
147
|
+
|
|
148
|
+
> **Adopt this agent for your product:** Replace this section with your project's specific routers, services, and models. Store durable reusable facts through `pantheon-memory` when warranted and when the tool is granted, or reference project documentation under `.pantheon/memory-bank/`, which is read on demand rather than auto-loaded.
|
|
149
|
+
|
|
150
|
+
## Implementation Process
|
|
151
|
+
|
|
152
|
+
When creating a new feature:
|
|
153
|
+
|
|
154
|
+
1. **Router First**: Create endpoint in appropriate router file
|
|
155
|
+
```python
|
|
156
|
+
@router.post("", response_model=ResponseSchema)
|
|
157
|
+
async def create_item(
|
|
158
|
+
data: CreateSchema,
|
|
159
|
+
db: AsyncSession = Depends(get_db),
|
|
160
|
+
current_user: User = Depends(get_current_user)
|
|
161
|
+
):
|
|
162
|
+
service = ItemService(db)
|
|
163
|
+
return await service.create(data)
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
2. **Service Layer**: Implement business logic
|
|
167
|
+
```python
|
|
168
|
+
class ItemService:
|
|
169
|
+
def __init__(self, db: AsyncSession):
|
|
170
|
+
self.db = db
|
|
171
|
+
|
|
172
|
+
async def create(self, data: CreateSchema) -> Item:
|
|
173
|
+
# Validation, business logic, persistence
|
|
174
|
+
pass
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
3. **Error Handling**: Use FastAPI exceptions
|
|
178
|
+
```python
|
|
179
|
+
if not item:
|
|
180
|
+
raise HTTPException(status_code=404, detail="Item not found")
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
4. **Testing**: Write unit tests in `backend/tests/`
|
|
184
|
+
|
|
185
|
+
## Code Quality Standards
|
|
186
|
+
|
|
187
|
+
> See instructions/backend-standards.instructions.md for the complete backend standards.
|
|
188
|
+
|
|
189
|
+
## Modern Python & Dependency Hygiene
|
|
190
|
+
|
|
191
|
+
### Obsolete Library Detection
|
|
192
|
+
When adding or changing dependencies, check for obsolete/deprecated libraries and audit the affected dependency set. Do not run dependency-audit tools for an unrelated one-line or documentation fix:
|
|
193
|
+
|
|
194
|
+
```bash
|
|
195
|
+
# Detect stdlib backports, zombie shims, deprecated packages
|
|
196
|
+
pip install dep-audit && dep-audit . --exit-code
|
|
197
|
+
|
|
198
|
+
# Scan for known CVEs in dependencies
|
|
199
|
+
pip-audit -r requirements.txt
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
**Common Python stdlib replacements (use these instead of third-party):**
|
|
203
|
+
| Obsolete | Modern stdlib | Since |
|
|
204
|
+
|----------|--------------|-------|
|
|
205
|
+
| `pytz` | `zoneinfo.ZoneInfo` | Python 3.9 |
|
|
206
|
+
| `tomli` | `tomllib` | Python 3.11 |
|
|
207
|
+
| `six`, `future` | native Python 3 syntax | Python 3.0+ |
|
|
208
|
+
| `dataclasses` backport | `dataclasses` stdlib | Python 3.7+ |
|
|
209
|
+
| `typing_extensions` (most) | `typing` stdlib | Python 3.9-3.11+ |
|
|
210
|
+
| `importlib_metadata` | `importlib.metadata` | Python 3.8+ |
|
|
211
|
+
| `contextlib2` | `contextlib` stdlib | Python 3.7+ |
|
|
212
|
+
| `mock` (PyPI) | `unittest.mock` | Python 3.3+ |
|
|
213
|
+
|
|
214
|
+
### LTS & Modern Version Policy
|
|
215
|
+
- Always pin dependencies to **LTS-compatible versions**
|
|
216
|
+
- Prefer latest **stable major version**: FastAPI ≥0.110, Pydantic ≥2.7, SQLAlchemy ≥2.0
|
|
217
|
+
- Never use EOL Python versions (3.8 and below are unsupported)
|
|
218
|
+
- Check `pip-audit` output to ensure no vulnerable deps
|
|
219
|
+
- Use `ruff check --select UP` to auto-migrate to modern Python syntax
|
|
220
|
+
- Prefer `pyproject.toml` over `setup.py` for project metadata
|
|
221
|
+
|
|
222
|
+
## Documentation Policy
|
|
223
|
+
|
|
224
|
+
Use artifact-management only for planned multi-phase or materially risky work. A bounded fix needs no IMPL artifact; return the structured summary instead. Never create permanent ADRs directly.
|
|
225
|
+
|
|
226
|
+
**Artifact Protocol Reference:** `skill: artifact-management`
|
|
227
|
+
|
|
228
|
+
## Pre-Implementation Recall
|
|
229
|
+
Use supplied memory/ADR context when relevant. Do not block a bounded fix on a separate memory-bank recall or repeat searches that do not change the implementation.
|
|
230
|
+
|
|
231
|
+
## When to Delegate
|
|
232
|
+
|
|
233
|
+
- **@apollo**: Only a root Hermes session may dispatch Apollo for broad/unfamiliar discovery that materially reduces risk; a child session reports that need to Zeus and inspects assigned context directly otherwise
|
|
234
|
+
- **@mnemosyne**: For permanent ADRs or substantial memory-bank artifacts, not routine summaries
|
|
235
|
+
- **@themis**: Required for auth/security, data/schema, and material changes; request required review through Zeus, who dispatches Themis from root. Do not create a separate review phase for a trivial isolated fix
|
|
236
|
+
- **@aphrodite / @demeter / **: Route through **Zeus** — Hermes cannot directly invoke these agents
|
|
237
|
+
|
|
238
|
+
## Output Format
|
|
239
|
+
|
|
240
|
+
When completing a task, provide:
|
|
241
|
+
- [OK] Complete router code with all endpoints
|
|
242
|
+
- [OK] Service implementation with business logic
|
|
243
|
+
- [OK] Pydantic schemas (request/response)
|
|
244
|
+
- [OK] Error handling and validation
|
|
245
|
+
- [OK] Docstrings explaining functionality
|
|
246
|
+
- [OK] Example curl commands for testing
|
|
247
|
+
- [OK] Unit test skeleton (optional)
|
|
248
|
+
|
|
249
|
+
---
|
|
250
|
+
|
|
251
|
+
**Philosophy**: Clean code, clear error messages, proper async patterns, thorough testing.
|
|
252
|
+
|
|
253
|
+
## Verification Tiers (match the change, not a ritual)
|
|
254
|
+
|
|
255
|
+
- **Small bounded fix** (typo, config, copy, single-function tweak): make the change, run the one targeted test or command that proves it, report. No RED→GREEN→REFACTOR ceremony, no extra discovery passes.
|
|
256
|
+
- **Material change** (new endpoint, schema, service, auth, public behavior): full TDD cycle via `skill: tdd-with-agents`, then the Themis handoff.
|
|
257
|
+
- Auto-continue through the chosen tier for authorized work; stop for required Themis review; stop and diagnose when tests fail unexpectedly; no partial results.
|
|
258
|
+
|
|
259
|
+
## Skills
|
|
260
|
+
Implementação: `tdd-with-agents`, `incremental-implementation`, `code-review-checklist`, `git-workflow-and-versioning`
|
|
261
|
+
|
|
262
|
+
|
|
263
|
+
- **Code-mode / infrastructure reads** — cheap and on demand; never for decisions the ladder already answers.
|
|
264
|
+
|
|
38
265
|
## Core Capabilities
|
|
39
266
|
|
|
40
267
|
### 1. Codebase Discovery
|
package/src/agents/athena.md
CHANGED
|
@@ -31,6 +31,30 @@ permission:
|
|
|
31
31
|
apollo: allow
|
|
32
32
|
---
|
|
33
33
|
|
|
34
|
+
## MCP governance (identical ladder, grant-aware)
|
|
35
|
+
|
|
36
|
+
- Escalation order: session context first; the local selector answers free;
|
|
37
|
+
one typed `pantheon_jev_decide` question when genuinely ambiguous (Zeus
|
|
38
|
+
dispatches; a returned label is an advisory, never authorization); a
|
|
39
|
+
native MCP call is the LAST resort for state the session cannot
|
|
40
|
+
reconstruct.
|
|
41
|
+
- **Memory recall/search** — at most one selective query per turn, only when
|
|
42
|
+
prior project history could change the decision; never for context you
|
|
43
|
+
already hold. Every result rides in your context for the rest of the
|
|
44
|
+
session.
|
|
45
|
+
- **Memory store** (only where granted) — durable, reusable facts ONLY:
|
|
46
|
+
decisions with reasons, root causes, conventions, user preferences.
|
|
47
|
+
Session narration never stores: subtask summaries, delegation status and
|
|
48
|
+
debugging play-by-play go to a checkpoint or nowhere. Namespace per
|
|
49
|
+
project; update an existing key instead of duplicating.
|
|
50
|
+
- **Persistence checkpoints** (only where granted) — milestones only: would
|
|
51
|
+
losing this be expensive to redo? Never per turn; never re-save an
|
|
52
|
+
unchanged key.
|
|
53
|
+
- **Vision** (only where granted) — only when the turn carries an
|
|
54
|
+
addressable image; one pass per image; each call is real gateway spend.
|
|
55
|
+
- **Code-mode / infrastructure reads** — cheap and on demand; never for
|
|
56
|
+
decisions the ladder already answers.
|
|
57
|
+
|
|
34
58
|
## When NOT to Use Athena
|
|
35
59
|
- When the task is a small, bounded fix — use @talos directly
|
|
36
60
|
- When you need immediate implementation without planning — return the routing need to Zeus for @hermes / @aphrodite
|
package/src/agents/demeter.md
CHANGED
|
@@ -25,6 +25,30 @@ mcp_tools:
|
|
|
25
25
|
pantheon-code-mode: [execute_code_script]
|
|
26
26
|
---
|
|
27
27
|
|
|
28
|
+
## MCP governance (identical ladder, grant-aware)
|
|
29
|
+
|
|
30
|
+
- Escalation order: session context first; the local selector answers free;
|
|
31
|
+
one typed `pantheon_jev_decide` question when genuinely ambiguous (Zeus
|
|
32
|
+
dispatches; a returned label is an advisory, never authorization); a
|
|
33
|
+
native MCP call is the LAST resort for state the session cannot
|
|
34
|
+
reconstruct.
|
|
35
|
+
- **Memory recall/search** — at most one selective query per turn, only when
|
|
36
|
+
prior project history could change the decision; never for context you
|
|
37
|
+
already hold. Every result rides in your context for the rest of the
|
|
38
|
+
session.
|
|
39
|
+
- **Memory store** (only where granted) — durable, reusable facts ONLY:
|
|
40
|
+
decisions with reasons, root causes, conventions, user preferences.
|
|
41
|
+
Session narration never stores: subtask summaries, delegation status and
|
|
42
|
+
debugging play-by-play go to a checkpoint or nowhere. Namespace per
|
|
43
|
+
project; update an existing key instead of duplicating.
|
|
44
|
+
- **Persistence checkpoints** (only where granted) — milestones only: would
|
|
45
|
+
losing this be expensive to redo? Never per turn; never re-save an
|
|
46
|
+
unchanged key.
|
|
47
|
+
- **Vision** (only where granted) — only when the turn carries an
|
|
48
|
+
addressable image; one pass per image; each call is real gateway spend.
|
|
49
|
+
- **Code-mode / infrastructure reads** — cheap and on demand; never for
|
|
50
|
+
decisions the ladder already answers.
|
|
51
|
+
|
|
28
52
|
## When NOT to Use Demeter
|
|
29
53
|
- For backend business logic — that's @hermes
|
|
30
54
|
- For frontend data display — that's @aphrodite
|
|
@@ -103,3 +127,12 @@ Use supplied ADR/memory context when relevant. For every schema/data migration,
|
|
|
103
127
|
|
|
104
128
|
## Skills
|
|
105
129
|
`tdd-with-agents`, `incremental-implementation`
|
|
130
|
+
|
|
131
|
+
## Domain conventions doc
|
|
132
|
+
|
|
133
|
+
If this project has a real database/data surface, keep `docs/data/conventions.md` current as you
|
|
134
|
+
work: stack versions, decided patterns, the conventions this project actually
|
|
135
|
+
follows. Read it first when it exists; propose creating it when the surface
|
|
136
|
+
exists and the file does not. Update only what you changed — a stale
|
|
137
|
+
convention line is worse than a missing one. The next session starts from
|
|
138
|
+
this file, not from your memory.
|
package/src/agents/gaia.md
CHANGED
|
@@ -29,6 +29,30 @@ mcp_tools:
|
|
|
29
29
|
pantheon-vision: [vision_describe, vision_ocr, vision_analyze]
|
|
30
30
|
---
|
|
31
31
|
|
|
32
|
+
## MCP governance (identical ladder, grant-aware)
|
|
33
|
+
|
|
34
|
+
- Escalation order: session context first; the local selector answers free;
|
|
35
|
+
one typed `pantheon_jev_decide` question when genuinely ambiguous (Zeus
|
|
36
|
+
dispatches; a returned label is an advisory, never authorization); a
|
|
37
|
+
native MCP call is the LAST resort for state the session cannot
|
|
38
|
+
reconstruct.
|
|
39
|
+
- **Memory recall/search** — at most one selective query per turn, only when
|
|
40
|
+
prior project history could change the decision; never for context you
|
|
41
|
+
already hold. Every result rides in your context for the rest of the
|
|
42
|
+
session.
|
|
43
|
+
- **Memory store** (only where granted) — durable, reusable facts ONLY:
|
|
44
|
+
decisions with reasons, root causes, conventions, user preferences.
|
|
45
|
+
Session narration never stores: subtask summaries, delegation status and
|
|
46
|
+
debugging play-by-play go to a checkpoint or nowhere. Namespace per
|
|
47
|
+
project; update an existing key instead of duplicating.
|
|
48
|
+
- **Persistence checkpoints** (only where granted) — milestones only: would
|
|
49
|
+
losing this be expensive to redo? Never per turn; never re-save an
|
|
50
|
+
unchanged key.
|
|
51
|
+
- **Vision** (only where granted) — only when the turn carries an
|
|
52
|
+
addressable image; one pass per image; each call is real gateway spend.
|
|
53
|
+
- **Code-mode / infrastructure reads** — cheap and on demand; never for
|
|
54
|
+
decisions the ladder already answers.
|
|
55
|
+
|
|
32
56
|
## Core Capabilities
|
|
33
57
|
|
|
34
58
|
### 1. Satellite Imagery Analysis
|