pantheon-opencode 1.6.3-beta.9 β†’ 1.7.0-beta.1

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 (69) hide show
  1. package/AGENTS.global.md +1 -1
  2. package/AGENTS.md +1 -1
  3. package/CHANGELOG.md +187 -6
  4. package/README.md +7 -1
  5. package/README.pt-BR.md +1 -1
  6. package/bin/pantheon-init.mjs +46 -28
  7. package/package.json +2 -2
  8. package/plugin.json +2 -2
  9. package/pyproject.toml +1 -1
  10. package/scripts/decision-router-budget.mjs +102 -2
  11. package/scripts/decision-router-v2-budget.mjs +2 -2
  12. package/scripts/decision-router.mjs +82 -25
  13. package/scripts/doctor.mjs +4 -1
  14. package/scripts/install/cli-ui.mjs +2 -1
  15. package/scripts/install/decision-router-config.mjs +12 -4
  16. package/scripts/install/interactive.mjs +45 -28
  17. package/scripts/install/opencode.mjs +151 -30
  18. package/scripts/jev-live-probe.mjs +114 -86
  19. package/scripts/skill-search.mjs +273 -0
  20. package/skills-lock.json +3 -1
  21. package/src/agents/aphrodite.md +34 -1
  22. package/src/agents/apollo.md +227 -0
  23. package/src/agents/athena.md +26 -0
  24. package/src/agents/demeter.md +33 -0
  25. package/src/agents/gaia.md +24 -0
  26. package/src/agents/hephaestus.md +24 -0
  27. package/src/agents/hermes.md +33 -0
  28. package/src/agents/iris.md +24 -0
  29. package/src/agents/mnemosyne.md +25 -3
  30. package/src/agents/nyx.md +50 -22
  31. package/src/agents/prometheus.md +242 -1
  32. package/src/agents/talos.md +24 -0
  33. package/src/agents/themis.md +24 -0
  34. package/src/agents/zeus.md +71 -20
  35. package/src/pantheon/j1-approvals.ts +123 -0
  36. package/src/pantheon/jev-decision-tool.ts +148 -17
  37. package/src/pantheon/jev-decisions.ts +95 -12
  38. package/src/pantheon/jev-escalation.ts +1 -1
  39. package/src/pantheon/jev-quality-score.ts +45 -10
  40. package/src/pantheon/jev-rank-verify.ts +244 -14
  41. package/src/pantheon/jev-risk-gate.ts +82 -12
  42. package/src/pantheon/local-decision-budget.ts +169 -2
  43. package/src/pantheon/local-decision-prompt.ts +2 -0
  44. package/src/pantheon/local-decision-router.ts +16 -0
  45. package/src/pantheon/local-decision-turn.ts +110 -4
  46. package/src/pantheon/local-decision-usage-evidence.internal.ts +2 -2
  47. package/src/pantheon/pantheon-decision-catalog.ts +9 -2
  48. package/src/pantheon/v2-decision-budget.ts +4 -2
  49. package/src/pantheon/v2-tools.ts +42 -0
  50. package/src/plugin-v2.ts +85 -5
  51. package/src/plugins/tui/dist/server-v2.d.ts +14 -6
  52. package/src/plugins/tui/dist/server-v2.d.ts.map +1 -1
  53. package/src/plugins/tui/dist/server-v2.js +16 -9
  54. package/src/plugins/tui/dist/server-v2.js.map +1 -1
  55. package/src/plugins/tui/dist/tui-v2.js +128 -25
  56. package/src/plugins/tui/dist/tui-v2.js.map +1 -1
  57. package/src/plugins/tui/dist/tui.js +1 -1
  58. package/src/plugins/tui/package-lock.json +2 -2
  59. package/src/plugins/tui/package.json +1 -1
  60. package/src/plugins/tui/src/server-v2.ts +14 -7
  61. package/src/plugins/tui/src/whats-new-highlights.ts +59 -5
  62. package/src/plugins/tui/src/whats-new-open.ts +41 -1
  63. package/src/plugins/tui/src/whats-new.tsx +61 -8
  64. package/src/routing.yml +2 -0
  65. package/src/skills/README.md +1 -1
  66. package/src/skills/agent-forge/SKILL.md +76 -0
  67. package/src/skills/auto-continue/SKILL.md +12 -163
  68. package/src/skills/auto-continue/references/auto-continue-details.md +175 -0
  69. package/src/skills/prompt-refinery/SKILL.md +60 -0
@@ -22,6 +22,15 @@ import { fileURLToPath } from 'node:url'
22
22
  /** Hard cap on bullets shown in the window (the remainder is counted). */
23
23
  export const WHATS_NEW_MAX_ITEMS = 12
24
24
 
25
+ /**
26
+ * Cap for the curated `πŸ†• What's New` summary block β€” the window shows the
27
+ * summary, never the full Added/Changed/Fixed walls.
28
+ */
29
+ export const WHATS_NEW_SUMMARY_MAX_ITEMS = 6
30
+
31
+ /** Bullets longer than this are truncated with an ellipsis (one-line rule). */
32
+ export const WHATS_NEW_ITEM_MAX_CHARS = 140
33
+
25
34
  /** Prefix of the "+N more" line appended when the bullet budget is exceeded. */
26
35
  export const WHATS_NEW_MORE_PREFIX = '… +'
27
36
 
@@ -112,8 +121,38 @@ function stripHeading(text: string): string {
112
121
  }
113
122
 
114
123
  /**
115
- * Extract the release highlights for `version`: H3 subsection headings as
116
- * group labels and their bullets as sanitized plain text, bounded to
124
+ * Extract the curated summary block (`### πŸ†• What's New` or `## πŸ†• What's New`)
125
+ * from a section body: its bullets only, each truncated to
126
+ * WHATS_NEW_ITEM_MAX_CHARS, capped to WHATS_NEW_SUMMARY_MAX_ITEMS. Null when
127
+ * the section carries no summary block (the full-section fallback applies).
128
+ */
129
+ export function extractWhatsNewSummary(body: string): string[] | null {
130
+ const lines = body.split('\n')
131
+ const start = lines.findIndex((line) => /^#{2,3}[ \t]+.*What'?s New/i.test(line.trim()))
132
+ if (start === -1) return null
133
+ const items: string[] = []
134
+ for (const rawLine of lines.slice(start + 1)) {
135
+ const line = rawLine.trim()
136
+ if (line === '' || line.startsWith('<!--')) continue
137
+ if (/^#{1,6}[ \t]/.test(line)) break // next subsection β€” summary ended
138
+ if (!/^[-*][ \t]/.test(line)) continue
139
+ if (items.length >= WHATS_NEW_SUMMARY_MAX_ITEMS) break
140
+ const content = stripMarkdown(line.replace(/^[-*][ \t]+/, ''))
141
+ if (content === '') continue
142
+ items.push(
143
+ content.length > WHATS_NEW_ITEM_MAX_CHARS
144
+ ? `${content.slice(0, WHATS_NEW_ITEM_MAX_CHARS - 1)}…`
145
+ : content,
146
+ )
147
+ }
148
+ return items.length > 0 ? items : null
149
+ }
150
+
151
+ /**
152
+ * Extract the release highlights for `version`. When the section carries a
153
+ * curated `πŸ†• What's New` summary block, THE WINDOW SHOWS ONLY THAT (the
154
+ * full Added/Changed/Fixed walls are for the CHANGELOG readers, not the
155
+ * dialog); otherwise it falls back to the H3-group extraction bounded to
117
156
  * WHATS_NEW_MAX_ITEMS bullets. A missing section, a bullet-less section or a
118
157
  * blank changelog all return EMPTY_HIGHLIGHTS (no window).
119
158
  */
@@ -121,6 +160,17 @@ export function extractHighlights(changelogText: string, version: string): Whats
121
160
  const { found, body } = extractSection(changelogText ?? '', version ?? '')
122
161
  if (!found || !body) return { ...EMPTY_HIGHLIGHTS }
123
162
 
163
+ const summary = extractWhatsNewSummary(body)
164
+ if (summary !== null) {
165
+ return {
166
+ version: String(version).trim().replace(/^v/i, ''),
167
+ found: true,
168
+ groups: [{ heading: null, items: summary }],
169
+ totalItems: summary.length,
170
+ truncated: false,
171
+ }
172
+ }
173
+
124
174
  const groups: WhatsNewGroup[] = []
125
175
  let totalItems = 0
126
176
  let truncated = false
@@ -149,13 +199,17 @@ export function extractHighlights(changelogText: string, version: string): Whats
149
199
 
150
200
  const content = stripMarkdown(isBullet ? line.replace(/^[-*][ \t]+/, '') : line)
151
201
  if (content === '') continue
202
+ const bounded =
203
+ content.length > WHATS_NEW_ITEM_MAX_CHARS
204
+ ? `${content.slice(0, WHATS_NEW_ITEM_MAX_CHARS - 1)}…`
205
+ : content
152
206
  const group = groups.at(-1)
153
207
  if (group === undefined) {
154
- groups.push({ heading: null, items: [content] })
208
+ groups.push({ heading: null, items: [bounded] })
155
209
  } else if (isBullet || group.items.length === 0) {
156
- group.items.push(content)
210
+ group.items.push(bounded)
157
211
  } else {
158
- group.items[group.items.length - 1] = `${group.items.at(-1)} ${content}`.trim()
212
+ group.items[group.items.length - 1] = `${group.items.at(-1)} ${bounded}`.trim()
159
213
  }
160
214
  if (isBullet) totalItems += 1
161
215
  }
@@ -27,11 +27,49 @@ import { markSeenWhatsNew, shouldShowWhatsNew } from './whats-new-state.ts'
27
27
  /** Muted footer hint teaching the dismiss bind (Portuguese, like the sidebar). */
28
28
  export const WHATS_NEW_CLOSE_HINT = 'esc/q fechar'
29
29
 
30
+ /** Hint variant when the highlights span more than one page. */
31
+ export const WHATS_NEW_PAGES_HINT = 'esc/q fechar Β· n prΓ³xima Β· p volta'
32
+
33
+ /** The CHANGELOG pointer shown under the highlights (the window summarizes; the file is complete). */
34
+ export const WHATS_NEW_MORE_HINT = 'CHANGELOG completo: CHANGELOG.md no pacote'
35
+
36
+ /** Rows per page β€” bounded so no changelog can overflow the terminal. */
37
+ export const WHATS_NEW_PAGE_SIZE = 14
38
+
39
+ /** Hard-wrap one display line into rows of at most `width` columns (>= 10). */
40
+ export function wrapWhatsNewLine(line: string, width: number): string[] {
41
+ const bounded = Number.isInteger(width) && width > 10 ? width : 76
42
+ const text = String(line)
43
+ if (text.length <= bounded) return [text]
44
+ const rows: string[] = []
45
+ let rest = text
46
+ while (rest.length > bounded) {
47
+ rows.push(rest.slice(0, bounded))
48
+ rest = rest.slice(bounded)
49
+ }
50
+ if (rest.length > 0) rows.push(rest)
51
+ return rows
52
+ }
53
+
54
+ /** Slice display lines into fixed-size pages (>= 1 page, empty-safe). */
55
+ export function paginateWhatsNewLines(
56
+ lines: string[],
57
+ pageSize: number = WHATS_NEW_PAGE_SIZE,
58
+ ): string[][] {
59
+ const size = Number.isInteger(pageSize) && pageSize > 0 ? pageSize : WHATS_NEW_PAGE_SIZE
60
+ if (lines.length === 0) return [[]]
61
+ const pages: string[][] = []
62
+ for (let i = 0; i < lines.length; i += size) pages.push(lines.slice(i, i + size))
63
+ return pages
64
+ }
65
+
30
66
  /** Everything the window needs to render β€” no host types, no JSX. */
31
67
  export interface WhatsNewViewData {
32
68
  version: string
33
69
  title: string
34
70
  lines: string[]
71
+ /** Fixed-size pages of `lines` (single page when the highlights are short). */
72
+ pages: string[][]
35
73
  hint: string
36
74
  }
37
75
 
@@ -64,11 +102,13 @@ export async function openWhatsNew(input: WhatsNewOpenInput): Promise<boolean> {
64
102
  const lines = whatsNewLines(highlights)
65
103
  if (lines.length === 0) return false
66
104
 
105
+ const pages = paginateWhatsNewLines(lines)
67
106
  const data: WhatsNewViewData = {
68
107
  version,
69
108
  title: whatsNewTitle(version),
70
109
  lines,
71
- hint: WHATS_NEW_CLOSE_HINT,
110
+ pages,
111
+ hint: pages.length > 1 ? WHATS_NEW_PAGES_HINT : WHATS_NEW_CLOSE_HINT,
72
112
  }
73
113
  show(
74
114
  () => data,
@@ -10,8 +10,13 @@
10
10
  * awaited β€” startup must never block). The decision lives in
11
11
  * whats-new-open.ts; this file is only the host glue + view:
12
12
  * `context.ui.dialog.show` plus a keymap layer gated on the open signal so
13
- * `escape`/`q` dismiss while (and only while) the window is up β€” the same
14
- * gated-layer pattern as the dispatch panel.
13
+ * `escape`/`q` dismiss and `n`/`p` flip pages while (and only while) the
14
+ * window is up β€” the same gated-layer pattern as the dispatch panel.
15
+ *
16
+ * The window shows the curated πŸ†• What's New summary (whats-new-highlights
17
+ * prefers it), hard-wrapped to the window width and sliced into fixed-size
18
+ * pages β€” a big changelog can never overflow the terminal; the footer points
19
+ * at the complete CHANGELOG.md.
15
20
  *
16
21
  * Deliberately V2-only: the two dist entries are self-contained (the V1
17
22
  * sidebar mirrors the preset resolver rather than importing it) because any
@@ -29,22 +34,37 @@
29
34
  import type { Context } from '@opencode/plugin/tui/context'
30
35
  import { createSignal, For } from 'solid-js'
31
36
  import { readChangelogForBundle, resolveRunningVersion } from './whats-new-highlights.ts'
32
- import { openWhatsNew, type WhatsNewViewData } from './whats-new-open.ts'
37
+ import { openWhatsNew, type WhatsNewViewData, wrapWhatsNewLine } from './whats-new-open.ts'
33
38
  import { defaultWhatsNewStatePath } from './whats-new-state.ts'
34
39
 
35
- /** Window body: title, rule, bounded highlight lines, dismiss hint. */
36
- export function WhatsNewContent(props: { data: WhatsNewViewData; fg?: any; muted?: any }) {
40
+ /** Window body: title, rule, the current page (wrapped), footer hint. */
41
+ export function WhatsNewContent(props: {
42
+ data: WhatsNewViewData
43
+ page: () => number
44
+ pageCount: () => number
45
+ fg?: any
46
+ muted?: any
47
+ }) {
48
+ const rows = () => {
49
+ const current = props.data.pages[Math.min(props.page(), props.pageCount() - 1)] ?? []
50
+ const wrapped: string[] = []
51
+ for (const line of current) wrapped.push(...wrapWhatsNewLine(line, 76))
52
+ return wrapped
53
+ }
37
54
  return (
38
55
  <box flexDirection="column" paddingLeft={1} paddingRight={1} paddingTop={1}>
39
56
  <text attributes={1} fg={props.fg}>
40
57
  {props.data.title}
41
58
  </text>
42
59
  <text fg={props.muted}>{'─'.repeat(38)}</text>
43
- <For each={props.data.lines}>
60
+ <For each={rows()}>
44
61
  {(line: string) => <text fg={line.startsWith('β€’ ') ? props.fg : props.muted}>{line}</text>}
45
62
  </For>
46
63
  <box height={1} />
47
- <text fg={props.muted}>{props.data.hint}</text>
64
+ <text fg={props.muted}>
65
+ {props.pageCount() > 1 ? `${props.page() + 1}/${props.pageCount()} Β· ` : ''}
66
+ {props.data.hint}
67
+ </text>
48
68
  </box>
49
69
  )
50
70
  }
@@ -61,6 +81,9 @@ export async function maybeShowWhatsNewV2(context: Context): Promise<void> {
61
81
  const changelogText = await readChangelogForBundle(import.meta.url)
62
82
 
63
83
  const [open, setOpen] = createSignal(false)
84
+ const [page, setPage] = createSignal(0)
85
+ let viewData: WhatsNewViewData | undefined
86
+ const pageCount = () => Math.max(1, Math.ceil(viewData?.pages.length ?? 1))
64
87
  let dismiss: () => void = () => {}
65
88
  try {
66
89
  // Gated layer: inert (all keys fall through) while the window is closed.
@@ -78,6 +101,26 @@ export async function maybeShowWhatsNewV2(context: Context): Promise<void> {
78
101
  return undefined
79
102
  },
80
103
  },
104
+ {
105
+ id: 'pantheon.whats-new.next',
106
+ title: 'PrΓ³xima pΓ‘gina',
107
+ bind: 'n,right',
108
+ run: () => {
109
+ if (!open()) return false
110
+ setPage((current) => Math.min(current + 1, pageCount() - 1))
111
+ return undefined
112
+ },
113
+ },
114
+ {
115
+ id: 'pantheon.whats-new.prev',
116
+ title: 'PΓ‘gina anterior',
117
+ bind: 'p,left',
118
+ run: () => {
119
+ if (!open()) return false
120
+ setPage((current) => Math.max(current - 1, 0))
121
+ return undefined
122
+ },
123
+ },
81
124
  ],
82
125
  }))
83
126
  } catch {
@@ -101,11 +144,21 @@ export async function maybeShowWhatsNewV2(context: Context): Promise<void> {
101
144
  }
102
145
  close()
103
146
  }
147
+ viewData = render()
148
+ setPage(0)
104
149
  setOpen(true)
105
150
  try {
106
151
  const theme = context.theme?.text ?? {}
107
152
  context.ui.dialog.show(
108
- () => <WhatsNewContent data={render()} fg={theme.base} muted={theme.muted} />,
153
+ () => (
154
+ <WhatsNewContent
155
+ data={viewData as WhatsNewViewData}
156
+ page={page}
157
+ pageCount={pageCount}
158
+ fg={theme.base}
159
+ muted={theme.muted}
160
+ />
161
+ ),
109
162
  close,
110
163
  )
111
164
  } catch {
package/src/routing.yml CHANGED
@@ -174,9 +174,11 @@ agents:
174
174
  - talos
175
175
  skills:
176
176
  - agent-coordination
177
+ - agent-forge
177
178
  - artifact-management
178
179
  - auto-continue
179
180
  - codemap
181
+ - prompt-refinery
180
182
  - context-compression
181
183
  - incremental-implementation
182
184
  - loop-engineering
@@ -4,7 +4,7 @@
4
4
 
5
5
  Skills are reference modules loaded on demand by agents. Each skill provides domain-specific knowledge β€” architecture patterns, security checklists, optimization strategies, and implementation guides. Agents load skills when their task matches the skill's description, keeping context focused and token-efficient.
6
6
 
7
- There are **20 skills** divided into **5 domains**.
7
+ There are **22 skills** divided into **5 domains**.
8
8
 
9
9
  ## Skills by Domain
10
10
 
@@ -0,0 +1,76 @@
1
+ ---
2
+ name: agent-forge
3
+ description: "Forge a new OpenCode agent on demand. Use when the user asks for 'um agente que faΓ§a X', 'create an agent for X', or wants a specialist the roster lacks."
4
+ ---
5
+
6
+ # Agent Forge
7
+
8
+ > **A new agent is a contract, not a vibe. Interview, draft against the canonical shape, confirm, forge β€” and never shadow an existing specialist.**
9
+
10
+ ---
11
+
12
+ ## When this fires
13
+
14
+ - The user asks for a dedicated agent ("cria um agente de reviews de PR", "I want an agent that watches deploys").
15
+ - A recurring task keeps being delegated with ad-hoc Briefs and would benefit from a standing definition.
16
+
17
+ Do NOT fire when an existing specialist covers the domain β€” route there instead (the 14 canonical agents + any agents already forged in this project).
18
+
19
+ ---
20
+
21
+ ## The interview (before any writing)
22
+
23
+ Ask AT MOST four questions, with your recommended default on each so silence proceeds:
24
+
25
+ 1. **Gap** β€” what recurring task/domain should this agent own? (default: infer from the request)
26
+ 2. **Surface** β€” which tools does it need? read-only, edit, shell, webfetch, MCP grants? (default: least privilege that can do the job)
27
+ 3. **Scope** β€” project (`.opencode/agents/`) or user-global (`~/.config/opencode/agents/`)? (default: project)
28
+ 4. **Model posture** β€” reasoning effort low/medium/high (default: medium; low for narrow mechanical agents).
29
+
30
+ Then present the draft definition for confirm-or-adjust BEFORE writing (the same contract discipline as prompt-refinery).
31
+
32
+ ---
33
+
34
+ ## The forged file (canonical shape)
35
+
36
+ ```markdown
37
+ ---
38
+ name: <kebab-id> # must NOT collide with the 14 canonical ids
39
+ description: "<what it owns> β€” <domain keywords for routing>. Use when <trigger>."
40
+ mode: subagent # or 'all' when it may also be invoked directly
41
+ reasoning_effort: low|medium|high
42
+ permission:
43
+ read: allow
44
+ grep: allow
45
+ glob: allow
46
+ edit: allow|deny # least privilege from the interview
47
+ shell: allow|deny
48
+ webfetch: allow|deny
49
+ task: { "*": deny } # forged agents do not dispatch by default
50
+ mcp_tools: # ONLY registered servers/tools; 'all' or exact lists
51
+ pantheon-resources: all
52
+ skills: [] # add only installed, reviewed skills
53
+ ---
54
+
55
+ ## MCP governance (identical ladder, grant-aware)
56
+ <copy the governance ladder block verbatim from any canonical agent β€” the
57
+ escalation order and cost rules are identical for every agent.>
58
+
59
+ ## Role
60
+ <2-4 sentences: what it owns, what it NEVER does, and where it escalates.>
61
+ ```
62
+
63
+ Rules that are NOT optional:
64
+
65
+ - **No collision** β€” the id must differ from every canonical agent and every already-forged agent in scope; on collision, propose a distinguishable name.
66
+ - **Grants must exist** β€” every `mcp_tools` entry names a server/tool that is actually registered; an exact list beats `all` whenever the role is narrow.
67
+ - **Governance identical** β€” the ladder block is byte-copied from a canonical agent; a forged agent never invents its own escalation rules.
68
+ - **Never overwrite** β€” if the target file exists, show it and ask before replacing.
69
+ - **Routing honesty** β€” project agents are picked up by the host automatically; do not claim they are in `routing.yml` or the decision catalogs (those are package-level and validated by tests).
70
+ - **ReferΓͺncia de fluxo**: o `skill-creator` da Anthropic (entender objetivo β†’ quando ativa β†’ formato β†’ como testar β†’ rascunho β†’ iterar) Γ© o precedentes do nosso interview β†’ draft β†’ confirm.
71
+
72
+ ---
73
+
74
+ ## After forging
75
+
76
+ Tell the user: restart OpenCode (or start a new session) for the host to load the new agent; invoke it with `@<name>`. If the agent should also appear in the local decision routing later, that is a package-level change β€” note it as a follow-up, never silently.
@@ -74,171 +74,20 @@ Full-auto may continue only within a task and scope the user explicitly authoriz
74
74
 
75
75
  ---
76
76
 
77
- ## Cooldown Pattern
77
+ ## Checkpoint content contract (format safety β€” keep in core)
78
78
 
79
- Between phases, execute a brief synthesis handoff to prevent context drift and prepare the next phase:
80
-
81
- ### Phase Summary Template
82
- ```
83
- Phase N complete. Summary:
84
- - What was done: <2 bullet points>
85
- - What changed: <files modified>
86
- - What's next: <Gate 2 review OR next phase>
87
- - Will continue: <YES / after gate approval>
88
- ```
89
-
90
- ### Cooldown Rules
91
- 1. **Between parallel waves (no dependency):** No cooldown needed β€” wave results are independent
92
- 2. **Between sequential phases:** Summarize when dependencies or risk changed; skip ceremony for one-step work
93
- 3. **After required Themis review:** Reassess findings before continuing
94
- 4. **Session reuse check:** Reuse a prior specialist session only when it reduces real context duplication
95
-
96
- ### Abbreviated Cooldown
97
- When auto-continuing between sequential non-gated phases, the cooldown is abbreviated to one line:
98
- ```
99
- β†’ Phase N done. Next: Phase N+1. [auto-continuing]
100
- ```
101
- Only expand to full cooldown when hitting a mandatory gate.
102
-
103
- ---
104
-
105
- ## Timeout & Retry Enforcement
106
-
107
- Delegate through the root `subagent` tool observed in the Beta 10 runtime. `task()` is
108
- host/API terminology, not an assumed root tool; call shape and background support are
109
- runtime-dependent. Prefer synchronous dispatch unless the active schema exposes background
110
- and the host provides an observable completion notification. Do not assume `task_status`,
111
- `cancel_task`, or board-based tracking/recovery tools are available. When no completion
112
- mechanism is observable, use synchronous dispatch or state the limitation; do not claim
113
- that jobs are being tracked or recovered.
114
-
115
- When a delegated agent does not respond in time, enforce the timeout policy defined in
116
- `src/instructions/zeus-timeout-retry.instructions.md`.
117
-
118
- **That file is the single authority** for per-role timeouts, retry counts, fallback chains, and
119
- whether partial results are acceptable. It is force-fed into every session via `AGENTS.md`; this
120
- skill is opt-in. Do not restate those values here β€” a copy in this skill is precisely what drifted
121
- out of sync with them. If a dispatch times out, read the role's row from the instruction file.
122
-
123
- ### Timeout Parcial (Partial Results)
124
-
125
- Whether an agent may return partial results is the **Partial Results OK?** column in that table.
126
- Only agents marked βœ… there may return partial β€” never implementers, never reviewers.
127
-
128
- **How to signal timeout parcial:**
129
- When dispatching, set the expectation explicitly:
130
- ```
131
- @apollo Search for all auth-related files. If you hit timeout, return whatever you have found so far β€” partial results are acceptable.
132
- ```
133
-
134
- ### Timeout Tracking Table
135
-
136
- Maintain an in-context (not persistent/native) checklist of delegations when needed:
137
-
138
- | Agent | Started | Timeout | Status | Partial OK? |
139
- |-------|---------|---------|--------|-------------|
140
- | apollo | T+0s | T+60s | βœ… complete | βœ… |
141
- | hermes | T+0s | T+180s | ⏳ in progress | ❌ |
79
+ When checkpointing via `context_save`: `content=JSON.stringify(state)` and an
80
+ explicit `session_id`; `state` must be an OBJECT (its `goal`/`phase`/
81
+ `delegations`/`heartbeat` values are objects, `tail` is an array); if the
82
+ optional `goal` is unset, omit the key rather than passing a string
83
+ placeholder.
142
84
 
143
85
  ---
144
86
 
145
- ## Examples
146
-
147
- **Good (auto-continues):**
148
- ```
149
- βœ… Wrote migration file.
150
- β†’ Running migration tests...
151
- βœ… Tests pass (3/3).
152
- β†’ Next: write UserRepository query methods.
153
- ```
154
-
155
- **Good (stops at Gate 2):**
156
- ```
157
- βœ… Phase 1 complete: migration + repository layer.
158
- ⏸️ GATE 2 β€” Themis review summary:
159
- - Coverage: 87% βœ… | No OWASP issues βœ…
160
- Ready for Phase 2? Waiting for go-ahead.
161
- ```
162
-
163
- **Bad (stops unnecessarily):**
164
- ```
165
- βœ… Wrote the migration file.
166
- Should I now run the migration tests? [waiting]
167
- ```
168
-
169
- ## Session Heartbeat & Checkpoints
170
-
171
- Session state is **not** file-based. It lives in **pantheon-persistence** under the
172
- `checkpoint:<slug>` namespace and is cleaned up automatically by a 4h TTL.
173
-
174
- Use checkpoints only when `context_save` and `context_get` are explicitly
175
- present in the active session's tool list. If unavailable, do not attempt a
176
- checkpoint or guess a session ID; carry the handoff in the normal response.
177
-
178
- When available, call `context_save` with `content=JSON.stringify(state)` and an
179
- explicit `session_id`. A successful save needs no immediate `context_get`; read
180
- only when resuming or when the save result is uncertain. Reuse the same session
181
- ID so the `latest` pointer survives compaction. `state` must be an object β€” never pass a bare string as `content`: its
182
- `goal`/`phase`/`delegations`/`heartbeat` values are objects and `tail` is an array.
183
- `goal` is optional; when unset, omit the key rather than passing a string placeholder.
184
-
185
- ### Heartbeat Check
186
- - Check heartbeat only when checkpoint tools are available and the workflow needs a durable resume.
187
- - Write a heartbeat after anti-stall recovery only when the current session exposes checkpoint tools.
188
-
189
- ### Checkpoint Rules
190
- 1. Save checkpoints only for long-running/multi-phase work, context-loss risk, or substantive parallel work β€” not a one-off command or bounded fix
191
- 2. Include current phase and remaining tasks when a checkpoint is warranted
192
- 3. On resume, read the latest checkpoint only with a known session ID; otherwise request the missing handoff context.
193
-
194
- > Do not create `heartbeat.json`, `checkpoint-<N>.json`, or `session.json` under
195
- > `.pantheon/deepwork/`. That file-based mechanism is retired β€” TTL handles cleanup, and reading
196
- > a file that nothing writes back returns stale state.
197
-
198
- ---
199
-
200
- ## Safety Policy Configuration
201
-
202
- Configurable gates for different platforms and risk levels:
203
-
204
- | Gate | Default | Auto-Approval Condition |
205
- |------|---------|------------------------|
206
- | Council | Only when explicitly invoked | Never auto-start a council for ordinary implementation |
207
- | Plan approval | Only for requested or risk-required plans | Skip for bounded, clear work |
208
- | Themis review | Required for sensitive/material changes | May omit for trivial isolated edits; never auto-bypass required findings |
209
- | Git / external actions | Never Auto | Commit, push, merge, deploy, destructive/global changes require explicit approval |
210
- | Deploy | Always Ask | N/A β€” always requires human |
211
- | Destructive DB Ops | Always Ask | N/A β€” always requires human |
212
-
213
- ### Configuration Format (for agents/PLAN.md)
214
-
215
- ```yaml
216
- auto-continue:
217
- checkpoint_interval: 5 # turns between checkpoints
218
- idle_warning: 60 # seconds before warning
219
- idle_stall: 120 # seconds before stall detection
220
- idle_pause: 300 # seconds before auto-pause
221
- gates:
222
- plan_approval: when_required_by_scope_or_risk
223
- themis_review: required_for_sensitive_or_material_changes
224
- git_commit: never_auto
225
- deploy: always_ask
226
- destructive_ops: always_ask
227
- ```
228
-
229
- ### Idle Detection
230
-
231
- | Condition | Action |
232
- |-----------|--------|
233
- | No tool call for 60s | Log warning heartbeat (status: warning) |
234
- | No tool call for 120s | Trigger anti-stall protocol |
235
- | No tool call for 300s | Auto-save checkpoint and pause session |
236
- | Resume | User must acknowledge and restart |
237
-
238
- ---
239
-
240
- ## Scope
241
-
242
- **Applies to:** Zeus (multi-phase), Hermes/Aphrodite/Demeter (TDD cycles), Apollo (parallel searches), Talos (bug fixes).
87
+ ## Details under demand
243
88
 
244
- **Does NOT apply to:** Athena planning (always presents plan = Gate 1), Iris (confirms before push), destructive operations (always ask).
89
+ The cooldown templates, timeout/retry enforcement (the single authority is
90
+ `src/instructions/zeus-timeout-retry.instructions.md` β€” force-fed via AGENTS.md),
91
+ tracking-table format, worked examples and the checkpoint rules live in
92
+ `references/auto-continue-details.md` β€” read it ONLY when a delegation times out,
93
+ you need a cooldown template, or you are about to checkpoint.