pantheon-opencode 1.6.3-beta.26 → 1.6.3-beta.28

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/CHANGELOG.md CHANGED
@@ -10,6 +10,18 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
10
10
  <!-- Add new changes here. Running `node scripts/versioning.mjs apply` will
11
11
  move this section to a versioned entry and reset the template below. -->
12
12
 
13
+ ## [v1.6.3-beta.28] - 2026-11-07
14
+
15
+ ## 🆕 What's New
16
+ - auto-continue split: core 2,656→1,003 tokens, the cooldown/timeout/checkpoint details moved to references/ (read under demand). The checkpoint contract is intact — the test follows the move.
17
+ - prompt-refinery tiers finalized: Tier 1 is an INTERNAL minimal adjust (the user sees the work begin, no approval ceremony; generous scope when the request demands); the six-section contract is EXCLUSIVELY the >> prefix; clarifying questions ride the native question tool.
18
+ - Descriptions trimmed keeping triggers (mnemosyne, agent-forge, prompt-refinery); skill-creator referenced in agent-forge.
19
+
20
+ ## [v1.6.3-beta.27] - 2026-11-07
21
+
22
+ ## 🆕 What's New
23
+ - prompt-refinery em TRÊS níveis com custo controlado por limite de saída (não por tier de modelo): pedido claro passa intacto; o sinal determinístico dispara o AJUSTE MÍNIMO (≤15 linhas — PT corrigido, estrutura leve); o contrato completo de seis seções é EXCLUSIVO do prefixo `>>`. Referências incorporadas: prompt-enhancer (opt-in, cap, fail-open) e prompt-improver (nudges self-cancel-cheap, clarificação com opções). Falha = fail-open; convenções do projeto têm prioridade sobre defaults.
24
+
13
25
  ## [v1.6.3-beta.26] - 2026-11-07
14
26
 
15
27
  ## 🆕 What's New
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pantheon-opencode",
3
- "version": "1.6.3-beta.26",
3
+ "version": "1.6.3-beta.28",
4
4
  "description": "Multi-agent orchestration for OpenCode \u2014 14 specialized agents, TDD, Themis review gates.",
5
5
  "type": "module",
6
6
  "workspaces": [
package/plugin.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "pantheon",
3
3
  "publisher": "ils15",
4
- "version": "1.6.3-beta.26",
4
+ "version": "1.6.3-beta.28",
5
5
  "displayName": "Pantheon",
6
6
  "description": "Conductor-Delegate orchestration platform with 14 specialized agents, 22 skills, and OpenCode support.",
7
7
  "agents": "./src/agents",
package/pyproject.toml CHANGED
@@ -4,7 +4,7 @@ build-backend = "setuptools.backends._legacy:_Backend"
4
4
 
5
5
  [project]
6
6
  name = "pantheon"
7
- version = "1.6.3-beta.26"
7
+ version = "1.6.3-beta.28"
8
8
  description = "Multi-agent orchestration framework"
9
9
  requires-python = ">=3.11"
10
10
  # Python sources under src/mcp/ import fastmcp/pydantic at runtime, but those
@@ -2647,6 +2647,28 @@ async function installPass(
2647
2647
  return config
2648
2648
  }
2649
2649
 
2650
+ // Provenance prefix per install shape (D3-scoped: project installs write it;
2651
+ // global installs NEVER do — the cwd-relative path vanishes agents there).
2652
+ const agentPrefixForSource = isGlobalConfigDir(target)
2653
+ ? null
2654
+ : version === 'v2'
2655
+ ? 'agents'
2656
+ : '.opencode/agents'
2657
+ const agentSources = {}
2658
+ if (agentPrefixForSource !== null) {
2659
+ const agentsDir = join(ROOT, 'src', 'agents')
2660
+ if (existsSync(agentsDir)) {
2661
+ const files = readdirSync(agentsDir).filter(
2662
+ (f) => (f.endsWith('.agent.md') || f.endsWith('.md')) && f.toLowerCase() !== 'readme.md',
2663
+ )
2664
+ for (const f of files) {
2665
+ const name = f.replace(/\.(agent\.)?md$/, '')
2666
+ agentSources[name] = `${agentPrefixForSource}/${name}.md`
2667
+ }
2668
+ }
2669
+ }
2670
+ const isGlobalTarget = isGlobalConfigDir(target)
2671
+
2650
2672
  const configuredMcpServersForPolicies =
2651
2673
  version === 'v2' ? configuredMcpServerNames(config.mcp) : []
2652
2674
  const canonicalAgentConfig = readAgentConfigFromCanonical()
@@ -2662,12 +2684,15 @@ async function installPass(
2662
2684
  // Preserve user-customized fields (model, provider, mcp, etc.)
2663
2685
  const existing = config.agent[agentName]
2664
2686
  if (!existing || typeof existing !== 'object' || Array.isArray(existing)) continue
2665
- // HEAL: older installs wrote `source: "agents/<name>.md"` (cwd-relative
2666
- // provenance). Host 2.2.5 resolves that path against the SESSION cwd,
2667
- // so every agent vanished outside the config dir (field report
2668
- // beta.14: "Agent not found: zeus"). The host loads agents from the
2669
- // agents directory without this field — remove it wherever found.
2670
- delete existing.source
2687
+ // HEAL + provenance (field beta.14→26): `source` is cwd-relative and
2688
+ // host 2.2.5 resolves it against the SESSION cwd — so it is written
2689
+ // ONLY for project installs (the session cwd IS the project) and
2690
+ // NEVER for global installs, where the relative path pointed outside
2691
+ // the config dir and made every agent vanish ("Agent not found:
2692
+ // zeus"). Global entries also get a stale GLOBAL source healed away.
2693
+ if (isGlobalTarget) delete existing.source
2694
+ else if (agentSources[agentName] && !isGlobalTarget)
2695
+ existing.source = agentSources[agentName]
2671
2696
 
2672
2697
  // The sibling opencode.jsonc merges with PRIORITY on this host and is
2673
2698
  // user-managed (the installer never rewrites it wholesale) — but OUR
@@ -2678,7 +2703,9 @@ async function installPass(
2678
2703
  const jsoncPath = join(target, 'opencode.jsonc')
2679
2704
  if (existsSync(jsoncPath)) {
2680
2705
  const raw = readFileSync(jsoncPath, 'utf8')
2681
- const healed = raw.replace(/,?\s*"source":\s*"agents\/[A-Za-z0-9_-]+\.md"/g, '')
2706
+ let healed = raw.replace(/,?\s*"source":\s*"agents\/[A-Za-z0-9_-]+\.md"/g, '')
2707
+ // A source-first entry leaves `"name": {,` — repair the orphan.
2708
+ healed = healed.replace(/("[A-Za-z0-9_-]+": \{),/g, '$1')
2682
2709
  if (healed !== raw) {
2683
2710
  writeFileSync(jsoncPath, healed)
2684
2711
  warning(
@@ -2700,6 +2727,7 @@ async function installPass(
2700
2727
  } else {
2701
2728
  // ── New agent ──
2702
2729
  const newAgent = {}
2730
+ if (!isGlobalTarget && agentSources[agentName]) newAgent.source = agentSources[agentName]
2703
2731
  if (agentCfg.description) newAgent.description = agentCfg.description
2704
2732
 
2705
2733
  // Copy all framework-managed fields from canonical config
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: mnemosyne
3
- description: "Memory curation specialist — owns the durable pantheon-memory stores (memory_store/recall/search) with namespace hygiene and the durable-facts-only policy; curates .pantheon/memory-bank/ and writes ADRs/task records on explicit request. Called by zeus. Never invoked automatically after phases."
3
+ description: "Memory curation specialist — owns the durable pantheon-memory stores (memory_store/recall/search) and curates .pantheon/memory-bank/ + ADRs on request. Use when memory needs saving, curating or recovering."
4
4
  mode: all
5
5
  reasoning_effort: low
6
6
 
@@ -107,8 +107,10 @@ the field refusal (beta.16) was the frontmatter working as designed.
107
107
 
108
108
  When the user's request spans multiple concerns without explicit acceptance
109
109
  criteria (refactor + fix + redesign in one paragraph), the FIRST turn is the
110
- refinement itself: NO reads, NO glob/grep, NO dispatches — load
111
- `skill: prompt-refinery` and produce the structured contract from the request
110
+ MINIMAL adjustment (≤15 lines): PT corrigido, estrutura leve, expansão do
111
+ implícito — o mesmo pedido, legível. NÃO produza o contrato gigante: ele é
112
+ SOMENTE do prefixo `>>` (opt-in explícito do usuário). O modelo ativo da
113
+ sessão faz os dois níveis; o limite de saída é o controle de custo.
112
114
  text alone (objective, numbered scope slices, acceptance criteria per slice,
113
115
  deliverables, and open questions with your recommended defaults). A request
114
116
  QUOTED as a test fixture — numbered battery payloads, "ESPERADO:" markers,
@@ -123,8 +125,8 @@ evidence (beta.22): discovering first burned a delegation and still ended in
123
125
  the same questions — the contract does not need file access, the CONFIRMED
124
126
  slices do. Show the contract once for confirm-or-adjust — silence proceeds
125
127
  with the stated defaults — then route the confirmed slices through the normal
126
- ladder. One refinement turn on the session model; never a dialogue, never a
127
- Jev call (decision models answer scalars, they do not write prose).
128
+ ladder. One refinement turn; never a dialogue, never a Jev call (decision
129
+ models answer scalars, they do not write prose).
128
130
 
129
131
  ## Missing capability? Find a skill before inventing one
130
132
 
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "name": "pantheon-tui",
3
- "version": "1.6.3-beta.26",
3
+ "version": "1.6.3-beta.28",
4
4
  "lockfileVersion": 3,
5
5
  "requires": true,
6
6
  "packages": {
7
7
  "": {
8
8
  "name": "pantheon-tui",
9
- "version": "1.6.3-beta.26",
9
+ "version": "1.6.3-beta.28",
10
10
  "license": "MIT",
11
11
  "dependencies": {
12
12
  "@opencode-ai/plugin": "1.18.33",
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "pantheon-tui",
3
3
  "type": "module",
4
- "version": "1.6.3-beta.26",
4
+ "version": "1.6.3-beta.28",
5
5
  "description": "Pantheon TUI plugin — V1 rich sidebar and usage gauges; native V2 status, session and delegation sidebar",
6
6
  "license": "MIT",
7
7
  "engines": {
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: agent-forge
3
- description: "Forge a new OpenCode agent on demand — interview the user, draft a canonical agent .md (frontmatter, permissions, MCP grants, governance ladder), write it project- or user-scoped, and validate it against the existing roster. Use when the user asks for 'um agente que faça X', 'create an agent for X', or wants a specialist that the roster lacks."
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
4
  ---
5
5
 
6
6
  # Agent Forge
@@ -67,6 +67,7 @@ Rules that are NOT optional:
67
67
  - **Governance identical** — the ladder block is byte-copied from a canonical agent; a forged agent never invents its own escalation rules.
68
68
  - **Never overwrite** — if the target file exists, show it and ask before replacing.
69
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.
70
71
 
71
72
  ---
72
73
 
@@ -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.
@@ -0,0 +1,175 @@
1
+ # Auto-Continue — details under demand
2
+
3
+ Moved out of SKILL.md (cost inventory beta.27: the body was 2,656 tokens and
4
+ most of it only matters mid-task). Read on demand.
5
+
6
+ ---
7
+
8
+ ## Cooldown Pattern
9
+
10
+ Between phases, execute a brief synthesis handoff to prevent context drift and prepare the next phase:
11
+
12
+ ### Phase Summary Template
13
+ ```
14
+ Phase N complete. Summary:
15
+ - What was done: <2 bullet points>
16
+ - What changed: <files modified>
17
+ - What's next: <Gate 2 review OR next phase>
18
+ - Will continue: <YES / after gate approval>
19
+ ```
20
+
21
+ ### Cooldown Rules
22
+ 1. **Between parallel waves (no dependency):** No cooldown needed — wave results are independent
23
+ 2. **Between sequential phases:** Summarize when dependencies or risk changed; skip ceremony for one-step work
24
+ 3. **After required Themis review:** Reassess findings before continuing
25
+ 4. **Session reuse check:** Reuse a prior specialist session only when it reduces real context duplication
26
+
27
+ ### Abbreviated Cooldown
28
+ When auto-continuing between sequential non-gated phases, the cooldown is abbreviated to one line:
29
+ ```
30
+ → Phase N done. Next: Phase N+1. [auto-continuing]
31
+ ```
32
+ Only expand to full cooldown when hitting a mandatory gate.
33
+
34
+ ---
35
+
36
+ ## Timeout & Retry Enforcement
37
+
38
+ Delegate through the root `subagent` tool observed in the Beta 10 runtime. `task()` is
39
+ host/API terminology, not an assumed root tool; call shape and background support are
40
+ runtime-dependent. Prefer synchronous dispatch unless the active schema exposes background
41
+ and the host provides an observable completion notification. Do not assume `task_status`,
42
+ `cancel_task`, or board-based tracking/recovery tools are available. When no completion
43
+ mechanism is observable, use synchronous dispatch or state the limitation; do not claim
44
+ that jobs are being tracked or recovered.
45
+
46
+ When a delegated agent does not respond in time, enforce the timeout policy defined in
47
+ `src/instructions/zeus-timeout-retry.instructions.md`.
48
+
49
+ **That file is the single authority** for per-role timeouts, retry counts, fallback chains, and
50
+ whether partial results are acceptable. It is force-fed into every session via `AGENTS.md`; this
51
+ skill is opt-in. Do not restate those values here — a copy in this skill is precisely what drifted
52
+ out of sync with them. If a dispatch times out, read the role's row from the instruction file.
53
+
54
+ ### Timeout Parcial (Partial Results)
55
+
56
+ Whether an agent may return partial results is the **Partial Results OK?** column in that table.
57
+ Only agents marked ✅ there may return partial — never implementers, never reviewers.
58
+
59
+ **How to signal timeout parcial:**
60
+ When dispatching, set the expectation explicitly:
61
+ ```
62
+ @apollo Search for all auth-related files. If you hit timeout, return whatever you have found so far — partial results are acceptable.
63
+ ```
64
+
65
+ ### Timeout Tracking Table
66
+
67
+ Maintain an in-context (not persistent/native) checklist of delegations when needed:
68
+
69
+ | Agent | Started | Timeout | Status | Partial OK? |
70
+ |-------|---------|---------|--------|-------------|
71
+ | apollo | T+0s | T+60s | ✅ complete | ✅ |
72
+ | hermes | T+0s | T+180s | ⏳ in progress | ❌ |
73
+
74
+ ---
75
+
76
+ ## Examples
77
+
78
+ **Good (auto-continues):**
79
+ ```
80
+ ✅ Wrote migration file.
81
+ → Running migration tests...
82
+ ✅ Tests pass (3/3).
83
+ → Next: write UserRepository query methods.
84
+ ```
85
+
86
+ **Good (stops at Gate 2):**
87
+ ```
88
+ ✅ Phase 1 complete: migration + repository layer.
89
+ ⏸️ GATE 2 — Themis review summary:
90
+ - Coverage: 87% ✅ | No OWASP issues ✅
91
+ Ready for Phase 2? Waiting for go-ahead.
92
+ ```
93
+
94
+ **Bad (stops unnecessarily):**
95
+ ```
96
+ ✅ Wrote the migration file.
97
+ Should I now run the migration tests? [waiting]
98
+ ```
99
+
100
+ ## Session Heartbeat & Checkpoints
101
+
102
+ Session state is **not** file-based. It lives in **pantheon-persistence** under the
103
+ `checkpoint:<slug>` namespace and is cleaned up automatically by a 4h TTL.
104
+
105
+ Use checkpoints only when `context_save` and `context_get` are explicitly
106
+ present in the active session's tool list. If unavailable, do not attempt a
107
+ checkpoint or guess a session ID; carry the handoff in the normal response.
108
+
109
+ When available, call `context_save` with `content=JSON.stringify(state)` and an
110
+ explicit `session_id`. A successful save needs no immediate `context_get`; read
111
+ only when resuming or when the save result is uncertain. Reuse the same session
112
+ ID so the `latest` pointer survives compaction. `state` must be an object — never pass a bare string as `content`: its
113
+ `goal`/`phase`/`delegations`/`heartbeat` values are objects and `tail` is an array.
114
+ `goal` is optional; when unset, omit the key rather than passing a string placeholder.
115
+
116
+ ### Heartbeat Check
117
+ - Check heartbeat only when checkpoint tools are available and the workflow needs a durable resume.
118
+ - Write a heartbeat after anti-stall recovery only when the current session exposes checkpoint tools.
119
+
120
+ ### Checkpoint Rules
121
+ 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
122
+ 2. Include current phase and remaining tasks when a checkpoint is warranted
123
+ 3. On resume, read the latest checkpoint only with a known session ID; otherwise request the missing handoff context.
124
+
125
+ > Do not create `heartbeat.json`, `checkpoint-<N>.json`, or `session.json` under
126
+ > `.pantheon/deepwork/`. That file-based mechanism is retired — TTL handles cleanup, and reading
127
+ > a file that nothing writes back returns stale state.
128
+
129
+ ---
130
+
131
+ ## Safety Policy Configuration
132
+
133
+ Configurable gates for different platforms and risk levels:
134
+
135
+ | Gate | Default | Auto-Approval Condition |
136
+ |------|---------|------------------------|
137
+ | Council | Only when explicitly invoked | Never auto-start a council for ordinary implementation |
138
+ | Plan approval | Only for requested or risk-required plans | Skip for bounded, clear work |
139
+ | Themis review | Required for sensitive/material changes | May omit for trivial isolated edits; never auto-bypass required findings |
140
+ | Git / external actions | Never Auto | Commit, push, merge, deploy, destructive/global changes require explicit approval |
141
+ | Deploy | Always Ask | N/A — always requires human |
142
+ | Destructive DB Ops | Always Ask | N/A — always requires human |
143
+
144
+ ### Configuration Format (for agents/PLAN.md)
145
+
146
+ ```yaml
147
+ auto-continue:
148
+ checkpoint_interval: 5 # turns between checkpoints
149
+ idle_warning: 60 # seconds before warning
150
+ idle_stall: 120 # seconds before stall detection
151
+ idle_pause: 300 # seconds before auto-pause
152
+ gates:
153
+ plan_approval: when_required_by_scope_or_risk
154
+ themis_review: required_for_sensitive_or_material_changes
155
+ git_commit: never_auto
156
+ deploy: always_ask
157
+ destructive_ops: always_ask
158
+ ```
159
+
160
+ ### Idle Detection
161
+
162
+ | Condition | Action |
163
+ |-----------|--------|
164
+ | No tool call for 60s | Log warning heartbeat (status: warning) |
165
+ | No tool call for 120s | Trigger anti-stall protocol |
166
+ | No tool call for 300s | Auto-save checkpoint and pause session |
167
+ | Resume | User must acknowledge and restart |
168
+
169
+ ---
170
+
171
+ ## Scope
172
+
173
+ **Applies to:** Zeus (multi-phase), Hermes/Aphrodite/Demeter (TDD cycles), Apollo (parallel searches), Talos (bug fixes).
174
+
175
+ **Does NOT apply to:** Athena planning (always presents plan = Gate 1), Iris (confirms before push), destructive operations (always ask).
@@ -1,25 +1,38 @@
1
1
  ---
2
2
  name: prompt-refinery
3
- description: "Turn a rough, vague, or one-line request into a structured execution contract (objective, scope slices, acceptance criteria, deliverables, open questions) shown to the user BEFORE executing. Use when a request spans multiple concerns or lacks explicit acceptance criteria."
3
+ description: "Turn a vague multi-concern request into a usable brief — internally and silently by default; the full contract is shown only via >>. Use when the request mixes refactor/fix/redesign without acceptance criteria, or starts with >>."
4
4
  ---
5
5
 
6
6
  # Prompt Refinery
7
7
 
8
- > **A vague request executes expensively and wrong. Refine it into a contract, show the contract, then execute what was confirmed.**
8
+ > **A vague request executes expensively and wrong. Tier 1 refines it INTERNALLY (the user sees the work begin); Tier 2 — only via `>>` — shows the full contract for confirmation.**
9
9
 
10
10
  ---
11
11
 
12
- ## When this fires
12
+ ## When this fires — TRÊS NÍVEIS
13
13
 
14
- - The request spans multiple concerns ("refatora o dashboard, corrige os cálculos, melhora a UI") with no explicit acceptance criteria.
15
- - The request names a desired OUTCOME but not the slices, nomenclature, data sources, or quality bar.
16
- - The user pastes a long context dump and asks for "melhorar/refatorar/revisar" without structure.
14
+ | Nível | Gatilho | O que acontece |
15
+ |---|---|---|
16
+ | **0 — Passa intacto** | Pedido claro e delimitado ("corrija o typo do README"), cumprimentos e conversa fiada (o `__SKIP__` do prompt-enhancer) | Executa direto, zero token de refinamento |
17
+ | **1 — Ajuste mínimo INTERNO (automático)** | O sinal determinístico dispara | Reescreve o prompt **silenciosamente, para uso próprio**: PT corrigido, estrutura leve, expansão do implícito, lacunas viram escolhas com default declarado. SEM apresentar contrato, SEM pedir aprovação — o usuário vê o trabalho começar. Limite: o essencial (~10-15 linhas internas); escopo pode ser generoso quando o pedido pede |
18
+ | **2 — Contrato completo** | **SOMENTE prefixo `>>`** | As seis seções inteiras apresentadas ao usuário para confirmar-ou-ajustar (a ÚNICA via com aprovação explícita) |
17
19
 
18
- A one-line bounded fix ("troque essa cor", "corrija esse typo") does NOT fire this skill — execute directly.
20
+ O modelo ativo da sessão faz os dois níveis sem problema — o custo é controlado pelo LIMITE de saída de cada nível, não por trocar de modelo. Nível 1 nunca vira nível 2 sem o prefixo.
19
21
 
20
22
  ---
21
23
 
22
- ## The contract shape (the rewrite target)
24
+ ## The contract shape — tiers and caps
25
+
26
+ **NÍVEL 1 — Ajuste mínimo INTERNO (o default do sinal determinístico):** reescrita para uso próprio, SEM apresentar ao usuário. O essencial + o que o pedido pedir (o escopo mínimo não é um aperto: expanda o implícito, estime o que falta com default declarado). Exemplo de saída aceitável:
27
+
28
+ ```
29
+ Objetivo: publicar deploys pendentes e liberar espaço nos VPS sem perder dados.
30
+ Fatias: 1) identificar pendências vs produção 2) deploy por serviço 3) limpeza segura de disco.
31
+ Aceite: lista de SHAs por serviço; espaço antes/depois; nada persistente apagado.
32
+ Perguntas: quais VPS? (default: os que rodam estes serviços) | limpeza destrutiva? (default: não).
33
+ ```
34
+
35
+ **NÍVEL 2 — Contrato completo (SOMENTE com o prefixo `>>`):** as seis seções abaixo, inteiras, apresentadas ao usuário para confirmar-ou-ajustar.
23
36
 
24
37
  Produce ALL of the following sections, filling from the request and marking real gaps as open questions — never invent requirements silently:
25
38
 
@@ -34,8 +47,14 @@ Produce ALL of the following sections, filling from the request and marking real
34
47
 
35
48
  ## Operating rules
36
49
 
37
- - **Show, then execute.** The refined contract is presented to the user for confirm-or-adjust BEFORE implementation — one confirmation, not a dialogue. Silence or "ok" proceeds with the defaults stated in Perguntas abertas.
50
+ - **Tier 1 é INTERNO**: o ajuste mínimo acontece na cabeça do agente — o usuário vê o trabalho começar, não o reescrito. Aprovação explícita só existe no Tier 2 (`>>`).
38
51
  - **Domain mapping stays the ladder's**: after confirmation, slices route through the normal discovery ladder (local selector → Jev → specialist dispatch). The contract is the SPEC, not the dispatcher.
39
52
  - **Preserve the user's language** (a PT-BR request refines into PT-BR).
53
+ - **Falha = fail-open**: qualquer erro no rewrite e o prompt ORIGINAL segue — nunca bloqueia.
54
+ - **Nudge self-cancel cheap** (do claude-code-prompt-improver): perguntas abertas com "se isso não se aplicar ao seu caso, ignore" — o nudge barato se anula sozinho quando o palpite erra.
55
+ - **Perguntas pela tool `question` nativa** (NUNCA Jev — decisão de paid/free; não prosa solta): uma lacuna que BLOQUEIA a execução vira uma pergunta com opções e o default recomendado. Lacuna não-bloqueante vira escolha com default declarado e segue.
56
+ - **`extra_instructions` do projeto**: convenções do projeto (stack, hosts de deploy, domínios como cupons ML/AliExpress) têm PRIORIDADE sobre os defaults recomendados — leia o AGENTS.md do projeto antes de propor defaults.
57
+ - **Referências**: `omkarxpatel/prompt-enhancer` (prefixo opt-in, cap de saída, fail-open) e `severity1/claude-code-prompt-improver` (nudges self-cancel, clarificação com opções) — os dois designs que este skill incorpora.
58
+ - **Modelo**: o rewrite roda no modelo ativo da sessão; o controle de custo é o CAP de cada nível (interno ~10-15 linhas; completo = as seis seções) — quando houver modelo free/rápido no preset ativo (ex.: mimo-v2.5-free, deepseek-v4-flash-free), prefira-o via routing para o turno de rewrite.
40
59
  - **One refinement turn.** The rewrite is a single planning pass on the session model — no extra provider call, no Jev needed for the rewrite itself (decision models answer typed scalars, they do not write prose).
41
60
  - **Cost honesty**: the refinement costs roughly one planning turn (~1–4K tokens each way). The expensive thing is executing a mis-specified request; this skill buys that back.