thoth-agents 0.4.2 → 0.5.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 (115) hide show
  1. package/LICENSE +30 -0
  2. package/README.md +86 -58
  3. package/dist/agents/prompt-sections.d.ts +5 -3
  4. package/dist/agents/prompt-utils.d.ts +1 -1
  5. package/dist/agents/worker.d.ts +2 -0
  6. package/dist/{chunk-STCURXAQ.js → chunk-MRFCA3U2.js} +33 -67
  7. package/dist/{chunk-EFGSGPYM.js → chunk-OW6I7ZUU.js} +391 -416
  8. package/dist/chunk-V7HSGRMB.js +1016 -0
  9. package/dist/{chunk-WCLUZZHI.js → chunk-VUNYH263.js} +1580 -351
  10. package/dist/cli/claude-code-paths.d.ts +2 -2
  11. package/dist/cli/codex-install.d.ts +5 -2
  12. package/dist/cli/codex-paths.d.ts +2 -2
  13. package/dist/cli/index.js +47 -11
  14. package/dist/cli/operations/pi.d.ts +1 -0
  15. package/dist/cli/pi-effort.d.ts +1 -1
  16. package/dist/cli/pi-external-package.d.ts +24 -0
  17. package/dist/cli/pi-git-source.d.ts +1 -0
  18. package/dist/cli/pi-install.d.ts +92 -15
  19. package/dist/cli/pi-managed-write.d.ts +3 -0
  20. package/dist/cli/pi-model-config.d.ts +17 -0
  21. package/dist/cli/pi-native-probe.d.ts +2 -0
  22. package/dist/cli/pi-paths.d.ts +2 -0
  23. package/dist/cli/pi-resources.d.ts +3 -1
  24. package/dist/cli/pi-tool-config.d.ts +32 -0
  25. package/dist/cli/tui/index.js +3 -3
  26. package/dist/cli/types.d.ts +2 -0
  27. package/dist/config/constants.d.ts +4 -8
  28. package/dist/config/schema.d.ts +7 -36
  29. package/dist/harness/adapters/claude-code.d.ts +2 -4
  30. package/dist/harness/core/agent-pack.d.ts +52 -42
  31. package/dist/harness/core/memory-governance.d.ts +2 -2
  32. package/dist/harness/core/sdd.d.ts +159 -319
  33. package/dist/harness/writers/pi-agent.d.ts +3 -1
  34. package/dist/index.js +12 -6
  35. package/dist/pi/tools-panel.d.ts +51 -0
  36. package/dist/pi.d.ts +44 -2
  37. package/dist/pi.js +471 -9
  38. package/dist/utils/subprocess.d.ts +1 -0
  39. package/package.json +23 -6
  40. package/pi/.thoth-agents-assets.json +5 -6
  41. package/pi/agents/thoth-designer.md +23 -8
  42. package/pi/agents/thoth-explorer.md +29 -9
  43. package/pi/agents/thoth-librarian.md +30 -8
  44. package/pi/agents/thoth-oracle.md +18 -10
  45. package/pi/agents/thoth-worker.md +96 -0
  46. package/plugin/.claude-plugin/.thoth-agents-plugin-assets.json +7 -12
  47. package/plugin/.claude-plugin/plugin.json +2 -2
  48. package/plugin/.codex-plugin/plugin.json +2 -2
  49. package/plugin/agents/designer.md +13 -5
  50. package/plugin/agents/explorer.md +16 -5
  51. package/plugin/agents/librarian.md +15 -4
  52. package/plugin/agents/oracle.md +13 -7
  53. package/plugin/agents/orchestrator.md +82 -91
  54. package/plugin/agents/worker.md +76 -0
  55. package/plugin/skills/plan-reviewer/SKILL.md +39 -141
  56. package/plugin/skills/thoth-archive/SKILL.md +50 -47
  57. package/plugin/skills/thoth-archive/scripts/archive.mjs +287 -654
  58. package/plugin/skills/thoth-constitution/SKILL.md +23 -42
  59. package/plugin/skills/thoth-constitution/templates/constitution.md +54 -44
  60. package/plugin/skills/thoth-init/SKILL.md +19 -29
  61. package/plugin/skills/thoth-init/scripts/init.mjs +73 -66
  62. package/plugin/skills/thoth-sdd/SKILL.md +164 -117
  63. package/plugin/skills/thoth-sdd/references/phases/checklist.md +2 -22
  64. package/plugin/skills/thoth-sdd/references/phases/clarify.md +14 -12
  65. package/plugin/skills/thoth-sdd/references/phases/converge.md +2 -13
  66. package/plugin/skills/thoth-sdd/references/phases/explore.md +3 -8
  67. package/plugin/skills/thoth-sdd/references/phases/implement.md +58 -57
  68. package/plugin/skills/thoth-sdd/references/phases/plan.md +2 -18
  69. package/plugin/skills/thoth-sdd/references/phases/specify.md +2 -33
  70. package/plugin/skills/thoth-sdd/references/phases/tasks.md +4 -45
  71. package/plugin/skills/thoth-sdd/references/phases/verify.md +4 -22
  72. package/plugin/skills/thoth-sdd/scripts/validate.mjs +610 -1232
  73. package/plugin/skills/thoth-sdd/templates/change.md +94 -0
  74. package/skills/README.md +11 -13
  75. package/skills/plan-reviewer/SKILL.md +39 -141
  76. package/skills/thoth-archive/SKILL.md +50 -47
  77. package/skills/thoth-archive/scripts/archive.mjs +287 -654
  78. package/skills/thoth-constitution/SKILL.md +23 -42
  79. package/skills/thoth-constitution/templates/constitution.md +54 -44
  80. package/skills/thoth-init/SKILL.md +19 -29
  81. package/skills/thoth-init/scripts/init.mjs +73 -66
  82. package/skills/thoth-sdd/SKILL.md +164 -117
  83. package/skills/thoth-sdd/references/phases/checklist.md +2 -22
  84. package/skills/thoth-sdd/references/phases/clarify.md +14 -12
  85. package/skills/thoth-sdd/references/phases/converge.md +2 -13
  86. package/skills/thoth-sdd/references/phases/explore.md +3 -8
  87. package/skills/thoth-sdd/references/phases/implement.md +58 -57
  88. package/skills/thoth-sdd/references/phases/plan.md +2 -18
  89. package/skills/thoth-sdd/references/phases/specify.md +2 -33
  90. package/skills/thoth-sdd/references/phases/tasks.md +4 -45
  91. package/skills/thoth-sdd/references/phases/verify.md +4 -22
  92. package/skills/thoth-sdd/scripts/validate.mjs +610 -1232
  93. package/skills/thoth-sdd/templates/change.md +94 -0
  94. package/thoth-agents.schema.json +9 -77
  95. package/dist/agents/deep.d.ts +0 -2
  96. package/dist/agents/quick.d.ts +0 -2
  97. package/dist/chunk-2U5MBLLV.js +0 -312
  98. package/pi/agents/thoth-deep.md +0 -81
  99. package/pi/agents/thoth-quick.md +0 -81
  100. package/plugin/agents/deep.md +0 -68
  101. package/plugin/agents/quick.md +0 -68
  102. package/plugin/skills/plan-reviewer/templates/plan-review.md +0 -65
  103. package/plugin/skills/thoth-sdd/templates/archive-report.md +0 -25
  104. package/plugin/skills/thoth-sdd/templates/checklist.md +0 -27
  105. package/plugin/skills/thoth-sdd/templates/plan.md +0 -46
  106. package/plugin/skills/thoth-sdd/templates/spec.md +0 -62
  107. package/plugin/skills/thoth-sdd/templates/tasks.md +0 -58
  108. package/plugin/skills/thoth-sdd/templates/verify-report.md +0 -28
  109. package/skills/plan-reviewer/templates/plan-review.md +0 -65
  110. package/skills/thoth-sdd/templates/archive-report.md +0 -25
  111. package/skills/thoth-sdd/templates/checklist.md +0 -27
  112. package/skills/thoth-sdd/templates/plan.md +0 -46
  113. package/skills/thoth-sdd/templates/spec.md +0 -62
  114. package/skills/thoth-sdd/templates/tasks.md +0 -58
  115. package/skills/thoth-sdd/templates/verify-report.md +0 -28
package/LICENSE CHANGED
@@ -19,3 +19,33 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
19
  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
20
  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
21
  SOFTWARE.
22
+
23
+ ---
24
+
25
+ Third-party notices
26
+
27
+ src/cli/pi-git-source.ts contains portions ported from
28
+ @earendil-works/pi-coding-agent 1.0.2 (dist/utils/git.js), distributed under
29
+ the following license:
30
+
31
+ MIT License
32
+
33
+ Copyright (c) 2025 Mario Zechner
34
+
35
+ Permission is hereby granted, free of charge, to any person obtaining a copy
36
+ of this software and associated documentation files (the "Software"), to deal
37
+ in the Software without restriction, including without limitation the rights
38
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
39
+ copies of the Software, and to permit persons to whom the Software is
40
+ furnished to do so, subject to the following conditions:
41
+
42
+ The above copyright notice and this permission notice shall be included in all
43
+ copies or substantial portions of the Software.
44
+
45
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
46
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
47
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
48
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
49
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
50
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
51
+ SOFTWARE.
package/README.md CHANGED
@@ -1,5 +1,5 @@
1
1
  <div align="center">
2
- <img src="img/thoth-agents-header.webp" alt="Seven cyber-Egyptian specialists led by Thoth, the Orchestrator" width="100%">
2
+ <img src="img/thoth-agents-header.webp" alt="Five cyber-Egyptian specialists led by Thoth, the Orchestrator" width="100%">
3
3
  <h1>Thoth-Agents</h1>
4
4
  <p><b>One conversation. The right specialists. A workflow that fits the task.</b></p>
5
5
  <p>Adaptive agent orchestration for OpenCode, Codex, Claude Code, and Pi.</p>
@@ -19,23 +19,28 @@
19
19
  </p>
20
20
  </div>
21
21
 
22
+ > [!WARNING]
23
+ > Thoth-Agents is under active development. Core concepts, workflows, and
24
+ > specifications are still evolving, and significant breaking changes may occur
25
+ > before a stable release.
26
+
22
27
  ---
23
28
 
24
29
  ## Why thoth-agents
25
30
 
26
31
  Describe what you want to build or fix. Thoth keeps the conversation together,
27
- handles straightforward work directly, and brings in specialists when research,
28
- design, implementation, or an independent review would help.
32
+ directs specialists to discover and implement by default, and retains your goals,
33
+ constraints, decisions, acceptance, and final synthesis in one root thread.
29
34
 
30
35
  Small changes stay small. Larger changes get a specification, a plan, and
31
36
  verification you can follow—without manually coordinating every agent.
32
37
 
33
- - **A team, not seven conversations.** One adaptive Orchestrator coordinates six
38
+ - **A team, not six conversations.** One adaptive Orchestrator coordinates five
34
39
  specialists and brings their results back to you.
35
- - **The right amount of process.** Choose a quick Direct path or a structured
36
- specification-driven development (SDD) workflow for more involved work.
37
- - **Specialists where they add value.** Repository discovery, current documentation,
38
- UI/UX, focused edits, complex implementation, and independent review have distinct roles.
40
+ - **Proportional process.** Small, clear, low-risk work stays artifact-free;
41
+ substantial work uses one ID-named record and proportionate verification.
42
+ - **Specialists execute by default.** Repository discovery, current documentation,
43
+ UI/UX, bounded implementation, and independent review have distinct roles.
39
44
  - **Models you can tune.** Configure models per role to suit your workflow and
40
45
  the providers available in your harness.
41
46
  - **Continuity between sessions.** Published installs include setup of
@@ -44,9 +49,10 @@ verification you can follow—without manually coordinating every agent.
44
49
  memory lifecycle, persistence, and storage; thoth-agents only invokes its setup.
45
50
 
46
51
  > [!NOTE]
47
- > OpenCode is the default and most integrated path. All four harnesses share the
48
- > workflow and role design, but their permissions, delegation, and runtime
49
- > capabilities are not identical. Your harness's trust and approval rules still apply.
52
+ > Pi is the default harness and our recommendation for the best Thoth-Agents
53
+ > experience. All four harnesses share the workflow and role design, but their
54
+ > permissions, delegation, and runtime capabilities are not identical. Your
55
+ > harness's trust and approval rules still apply.
50
56
 
51
57
  ## Install
52
58
 
@@ -56,10 +62,10 @@ The commands below install at **global/user scope**.
56
62
 
57
63
  | Harness | What you get | Install command |
58
64
  | --- | --- | --- |
59
- | <a href="https://github.com/anomalyco/opencode"><picture><source media="(prefers-color-scheme: dark)" srcset="https://svgl.app/library/opencode-dark.svg"><img src="https://svgl.app/library/opencode.svg" alt="OpenCode logo" width="48" height="48"></picture></a><br>**OpenCode** | Native plugin, agent team, workflow skills, and memory setup. **Recommended starting point.** | `npx thoth-agents@latest install --agent=opencode` |
65
+ | <a href="https://github.com/anomalyco/opencode"><picture><source media="(prefers-color-scheme: dark)" srcset="https://svgl.app/library/opencode-dark.svg"><img src="https://svgl.app/library/opencode.svg" alt="OpenCode logo" width="48" height="48"></picture></a><br>**OpenCode** | Native plugin, agent team, workflow skills, and memory setup. | `npx thoth-agents@latest install --agent=opencode` |
60
66
  | <a href="https://github.com/openai/codex"><img src="https://github.com/openai.png?size=120" alt="OpenAI logo — Codex" width="48" height="48"></a><br>**Codex** | Native plugin plus the required global agent and instruction setup. **Close Codex first.** | `npx thoth-agents@latest install --agent=codex` |
61
67
  | <a href="https://claude.com/product/claude-code"><img src="https://github.com/anthropics.png?size=120" alt="Anthropic logo — Claude Code" width="48" height="48"></a><br>**Claude Code** | Marketplace agents and skills, completed by the CLI's external skills and memory setup. **Run the prerequisites below first.** | `npx thoth-agents@latest install --agent=claude` |
62
- | <a href="https://github.com/earendil-works/pi"><img src="https://raw.githubusercontent.com/EremesNG/thoth-mem/master/img/pi.svg" alt="Pi logo" width="48" height="48"></a><br>**Pi** | Native package, six specialists, delegation and research extensions, workflow skills, and memory setup. | `npx thoth-agents@latest install --agent=pi` |
68
+ | <a href="https://github.com/earendil-works/pi"><img src="https://raw.githubusercontent.com/EremesNG/thoth-mem/master/img/pi.svg" alt="Pi logo" width="48" height="48"></a><br>**Pi** | Native package, five specialists, delegation and research extensions, workflow skills, and memory setup. **Recommended for the best experience.** | `npx thoth-agents@latest install --agent=pi` |
63
69
 
64
70
  ### Claude Code prerequisites
65
71
 
@@ -75,10 +81,25 @@ claude plugin install thoth-agents@thoth-plugins --scope user
75
81
  > without writing changes. After installation, restart your harness; Claude Code
76
82
  > also supports `/reload-plugins`.
77
83
 
84
+ Inside Pi, use `/subagents-model` to edit model and effort profiles for global
85
+ and project subagent definitions. See [subagent profile configuration](docs/installation.md#configure-subagent-model-profiles-inside-pi).
86
+ Use `/subagents-tools` to edit each specialist's explicit tool list, including
87
+ registered active and inactive extension and MCP tools. Globs (including `*`) are
88
+ manual advanced selections over all registered root tools; the panel preserves
89
+ them read-only. Edit `disallowed_tools` manually for injected tools and trimming
90
+ globs; only Oracle denies `ask_orchestrator` by default. See
91
+ [tool selection controls](docs/installation.md#configure-specialist-tools-inside-pi).
92
+
78
93
  Pi setup currently supports the default `~/.pi/agent` root. See the
79
94
  [Pi installation guide](docs/installation.md#pi) for runtime requirements,
80
- existing-package conflicts, and recovery. Pi extensions run with your user's
81
- system permissions; agent tool allowlists are not an OS sandbox.
95
+ existing-package conflicts, and recovery. Thoth manages its separate Pi
96
+ delegation runtime as package `@thoth-agents/pi-subagents` (`0.1.0`) through
97
+ `npm:@thoth-agents/pi-subagents@>=0.1.0`. Existing `pi-subagents` and
98
+ `pi-subagents-j0k3r` installs need manual recovery through Pi's package manager
99
+ before setup. Local checkout development uses `pnpm run setup:pi:local`, which
100
+ points Pi at the fork under `pi-packages/pi-subagents`; publishing the fork is
101
+ not required for that path. Pi extensions run with your user's system
102
+ permissions; agent tool allowlists are not an OS sandbox.
82
103
 
83
104
  For scopes, troubleshooting, or local checkout installation, see the
84
105
  [installation guide](docs/installation.md). Local Pi checkout installs keep
@@ -109,31 +130,30 @@ Open your repository in the harness and invoke the installed `thoth-init` skill:
109
130
  | Claude Code | `/thoth-agents:thoth-init` |
110
131
  | Pi | Ask: `Use the thoth-init skill to initialize this repository.` |
111
132
 
112
- This prepares the repository's `openspec/` governance for structured workflows.
113
- It does not install plugins or dependencies, and it preserves existing
114
- constitutions.
133
+ This creates only missing minimum `.thoth/` governance, including
134
+ `.thoth/constitution.md`, `.thoth/specs/`, and the change archive. It does not
135
+ install plugins or dependencies and preserves existing project-owned governance
136
+ and historical records.
115
137
 
116
138
  ### 3. Give Thoth a task
117
139
 
118
140
  Start with a goal, not a list of agents to manage. For example:
119
141
 
120
142
  ```text
121
- Fix the broken documentation link using the Direct route.
143
+ Fix the broken documentation link with the smallest sufficient workflow.
122
144
  ```
123
145
 
124
146
  ```text
125
- Add CSV export to the reports page using Accelerated SDD.
126
- Keep the existing filters and include tests for empty results.
147
+ Add CSV export to the reports page. Understand the existing filters, specify how empty results behave, and clarify any material decision before a test-first implementation. Keep the work proportional.
127
148
  ```
128
149
 
129
150
  ```text
130
- Use Full SDD to plan a migration from our current authentication system.
131
- Explore the risks before proposing changes.
151
+ Plan a migration from our current authentication system. Explore the risks, specify acceptance, and clarify material decisions before implementation. If classification is substantial, keep the plan and acceptance in one `.thoth/changes/<id>/<id>.md` record.
132
152
  ```
133
153
 
134
- You can name a route explicitly or let Thoth recommend one. Describe your
135
- constraints and expected outcome; the Orchestrator decides whether to handle
136
- work directly or bring in a specialist.
154
+ Describe the desired outcome, constraints, and acceptance. The Orchestrator
155
+ first builds proportional understanding, then classifies by coordination,
156
+ uncertainty, and risk and selects the fitting specialist.
137
157
 
138
158
  ## Meet the team
139
159
 
@@ -142,7 +162,7 @@ work directly or bring in a specialist.
142
162
  <table>
143
163
  <tr>
144
164
  <td width="25%" align="center"><img src="img/agents/orchestrator.webp" width="160" alt="Thoth as the Orchestrator"></td>
145
- <td><b>Orchestrator · Keeps the work moving</b><br><br>Your main point of contact. Understands the goal, recommends a workflow, handles bounded work, and coordinates specialists without handing you the management overhead.</td>
165
+ <td><b>Orchestrator · Keeps the work moving</b><br><br>Your main point of contact. Retains goals, constraints, decisions and acceptance while directing specialists, with a bounded exception for known-source consultation or minimal low-risk edits.</td>
146
166
  </tr>
147
167
  </table>
148
168
 
@@ -155,41 +175,40 @@ work directly or bring in a specialist.
155
175
 
156
176
  ### Design and implementation
157
177
 
158
- | Designer | Quick | Deep |
159
- | :---: | :---: | :---: |
160
- | <img src="img/agents/designer.webp" width="150" alt="Hathor as the Designer"> | <img src="img/agents/quick.webp" width="150" alt="Horus as Quick"> | <img src="img/agents/deep.webp" width="150" alt="Sobek as Deep"> |
161
- | **Makes interfaces work well.** Owns UI/UX, accessibility, implementation, and visual quality. | **Makes focused changes.** Handles clear, narrow, low-risk implementation tasks. | **Handles complex changes.** Works through coupled behavior, edge cases, and correctness-critical implementation. |
178
+ | Designer | Worker |
179
+ | :---: | :---: |
180
+ | **Makes interfaces work well.** Owns material UI/UX, accessibility, interaction, and visual quality. | **Implements changes.** Owns delegated implementation, including coupled behavior, edge cases, migrations, and correctness-critical work. |
162
181
 
163
182
  Research and review specialists are read-only. Implementation work has one
164
183
  writer per area; independent areas can proceed in parallel when the harness
165
184
  supports it. You do not need to summon every role for every task.
166
185
 
167
- ## Choose your workflow
168
-
169
- SDD means **specification-driven development**: agree on the intended result,
170
- plan the work, implement it, and check it against that intent.
171
-
172
- | Route | Best for | What to expect |
173
- | --- | --- | --- |
174
- | **Direct** | Clear, bounded, low-risk fixes and documentation changes. | Implement → verify. No planning artifacts required. |
175
- | **Accelerated** | Features spanning several areas, moderate risk, or a request to use SDD. | Specify → plan → tasks → implement → verify → archive. Planning runs in one pass unless a material decision needs you. |
176
- | **Full** | Uncertain requirements, architectural changes, or high-cost failures. | Explore first, then follow the structured workflow with separate planning checkpoints. |
177
-
178
- For Accelerated and Full, the specification, plan, tasks, and verification
179
- reports live under `openspec/`, so you can inspect what was agreed and what
180
- was checked. You can choose an optional Oracle plan review before implementation;
181
- final verification is required either way. These routes and materially risky
182
- Direct work use an independent Oracle for final verification.
183
-
184
- > [!TIP]
185
- > You stay in control of the route. Say “Use Direct,” “Use Accelerated SDD,” or
186
- > “Use Full SDD” when you already know how much structure you want.
187
-
188
- The installed skills cover project initialization, SDD, project principles,
189
- plan review, and archiving. External skills add test-driven development,
190
- behavior-preserving simplification, focused repository context, and architectural
191
- questioning when needed. See [Skills and MCPs](docs/skills-and-mcps.md) and the
192
- [SDD workflow guide](docs/sdd-pipeline.md) for details.
186
+ ## Proportional SDD
187
+
188
+ Every change completes explore, specify, and clarify in order, proportionally to
189
+ its uncertainty and impact. These steps do not force a document, specialist, or
190
+ interview. The Orchestrator resolves repository facts through evidence and asks
191
+ only when a material human-owned decision cannot safely be inferred; unresolved
192
+ material uncertainty blocks classification.
193
+
194
+ Only after understanding does it classify by meaningful coordination and
195
+ contract impact, uncertainty, and risk. File count alone does not increase scope:
196
+ a clear, low-risk localized mechanical change may touch several files and remain
197
+ small. Small work uses test-first implementation and focused verification with
198
+ no record. Substantial or materially risky work plans in one
199
+ `.thoth/changes/<id>/<id>.md` record after classification; risk may warrant
200
+ planning even for a patch-sized change. No alias, duplicate record, report,
201
+ evidence directory, or process tooling is created.
202
+
203
+ For substantial work, optional fresh Oracle plan review runs only when selected.
204
+ After a selected `[OKAY]`, root separately asks Implement (Recommended) or Stop;
205
+ review alone never authorizes implementation or replaces final verification.
206
+ Substantial and materially risky work receives a fresh read-only Oracle
207
+ verification. Declared durable changes sync transactionally to
208
+ `.thoth/specs/` after PASS. Active governance lives at `.thoth/constitution.md`;
209
+ historical records remain preserved, and provider memory stays separate. Native
210
+ harness execution and liveness remain authoritative. See the [SDD guide](docs/sdd-pipeline.md)
211
+ and [Skills and MCPs](docs/skills-and-mcps.md) for limits.
193
212
 
194
213
  ## Configure and update
195
214
 
@@ -225,6 +244,15 @@ skills and provider setup—not just the plugin. Native marketplace updates alon
225
244
  do not prove those other pieces are current. Use `status` to inspect the last
226
245
  complete CLI-managed installation and follow any reported recovery actions.
227
246
 
247
+ For Pi, the first-party `thoth-agents` package remains exact and receipt-verified.
248
+ The five mandatory external extensions use stable minimum-only `>=` ranges, so
249
+ Pi's native package manager can update them independently without waiting for a
250
+ Thoth release. Status validates each installed manifest's package name and
251
+ SemVer floor; newer stable versions are healthy, while prerelease, malformed,
252
+ missing, or older versions are not. Re-running Install or applying Update
253
+ migrates legacy exact external sources through Pi while preserving package
254
+ resource filters and unrelated settings.
255
+
228
256
  ## Documentation
229
257
 
230
258
  ### User guides
@@ -233,7 +261,7 @@ complete CLI-managed installation and follow any reported recovery actions.
233
261
  | --- | --- |
234
262
  | [Installation](docs/installation.md) | Check prerequisites, preview setup, troubleshoot, and repair an installation. |
235
263
  | [Quick Reference](docs/quick-reference.md) | Find commands, roles, skills, and workflow reminders. |
236
- | [SDD Pipeline](docs/sdd-pipeline.md) | Understand planning, review, verification, and archiving. |
264
+ | [SDD pipeline](docs/sdd-pipeline.md) | Understand routes, planning, review, verification, and archiving. |
237
265
  | [Skills and MCPs](docs/skills-and-mcps.md) | See the included workflows, research tools, and memory boundaries. |
238
266
  | [Provider Configuration](docs/provider-configurations.md) | Configure models and providers. |
239
267
  | [Codex Install](docs/codex-install.md) | Follow Codex-specific setup, activation, and trust requirements. |
@@ -4,11 +4,12 @@ import type { ModelEntry } from './prompt-utils';
4
4
  type ModelFamily = 'openai';
5
5
  export type SemanticMemoryAccess = 'dispatch-scoped';
6
6
  export type ReadOnlyAgentRole = 'explorer' | 'librarian' | 'oracle';
7
- export type WriteCapableAgentRole = 'designer' | 'quick' | 'deep';
7
+ export type WriteCapableAgentRole = 'designer' | 'worker';
8
8
  export interface QuestionProtocolSection {
9
9
  kind: 'question-protocol';
10
10
  toolConcept: 'userQuestion';
11
11
  audience: 'root' | 'child';
12
+ role?: AgentRoleName;
12
13
  }
13
14
  export interface SubagentRulesSection {
14
15
  kind: 'subagent-rules';
@@ -25,6 +26,7 @@ export interface ResponseBudgetSection {
25
26
  export interface StepBudgetSection {
26
27
  kind: 'step-budget';
27
28
  steps: number;
29
+ role?: string;
28
30
  }
29
31
  export interface ModelFamilySection {
30
32
  kind: 'model-family';
@@ -40,11 +42,11 @@ export type RolePromptSection = PromptSection;
40
42
  export interface PromptSectionRenderer<TSection extends PromptSection> {
41
43
  render(section: TSection, dialect: HarnessPromptDialect): string;
42
44
  }
43
- export declare function createQuestionProtocolSection(audience?: 'root' | 'child'): QuestionProtocolSection;
45
+ export declare function createQuestionProtocolSection(audience?: 'root' | 'child', role?: AgentRoleName): QuestionProtocolSection;
44
46
  export declare function createSubagentRulesSection(memoryAccess?: SemanticMemoryAccess): SubagentRulesSection;
45
47
  export declare function createReasoningDisciplineSection(): ReasoningDisciplineSection;
46
48
  export declare function createResponseBudgetSection(): ResponseBudgetSection;
47
- export declare function createStepBudgetSection(steps?: number): StepBudgetSection | undefined;
49
+ export declare function createStepBudgetSection(steps?: number, role?: string): StepBudgetSection | undefined;
48
50
  export declare function detectModelFamilyFromModel(model?: string | ModelEntry[]): ModelFamily | undefined;
49
51
  export declare function createModelFamilySection(role: AgentPromptRole, model?: string | ModelEntry[]): ModelFamilySection | undefined;
50
52
  export declare function createOrchestratorPromptSections(): RolePromptSection[];
@@ -15,7 +15,7 @@ export declare const QUESTION_PROTOCOL: string;
15
15
  export declare const SUBAGENT_RULES: string;
16
16
  export declare const RESPONSE_BUDGET: string;
17
17
  export declare function appendPromptSections(...sections: Array<string | undefined>): string;
18
- export declare function getStepBudgetPromptSection(steps?: number): string | undefined;
18
+ export declare function getStepBudgetPromptSection(steps?: number, role?: string): string | undefined;
19
19
  export declare function getModelFamilyPromptSection(role: AgentPromptRole, model?: string | ModelEntry[]): string | undefined;
20
20
  export declare function replacePromptPlaceholders(template: string, placeholders?: Record<string, string | number | undefined>): string;
21
21
  export declare function composeAgentPrompt({ basePrompt, customPrompt, customAppendPrompt, placeholders, }: ComposeAgentPromptOptions): string;
@@ -0,0 +1,2 @@
1
+ import type { AgentDefinition } from './orchestrator';
2
+ export declare function createWorkerAgent(model: string, customPrompt?: string, customAppendPrompt?: string): AgentDefinition;
@@ -16,34 +16,7 @@ import {
16
16
  loadAgentPrompt,
17
17
  renderAgentRoutingDescription,
18
18
  renderRolePrompt
19
- } from "./chunk-EFGSGPYM.js";
20
-
21
- // src/agents/deep.ts
22
- var DEEP_PROMPT = renderRolePrompt(
23
- createWriteCapableSpecialistPromptSections("deep"),
24
- OPENCODE_PROMPT_DIALECT
25
- );
26
- function createDeepAgent(model, customPrompt, customAppendPrompt) {
27
- const prompt = composeAgentPrompt({
28
- basePrompt: DEEP_PROMPT,
29
- customPrompt,
30
- customAppendPrompt: appendPromptSections(
31
- getModelFamilyPromptSection("deep", model),
32
- customAppendPrompt
33
- )
34
- });
35
- return {
36
- name: "deep",
37
- description: "Synchronous write-capable implementation agent optimized for thorough context analysis, edge cases, and correctness \u2014 not for bulk mechanical changes.",
38
- config: {
39
- model,
40
- temperature: 0.1,
41
- prompt,
42
- color: "secondary"
43
- // steps: 80,
44
- }
45
- };
46
- }
19
+ } from "./chunk-OW6I7ZUU.js";
47
20
 
48
21
  // src/agents/designer.ts
49
22
  var DESIGNER_PROMPT = renderRolePrompt(
@@ -61,7 +34,7 @@ function createDesignerAgent(model, customPrompt, customAppendPrompt) {
61
34
  });
62
35
  return {
63
36
  name: "designer",
64
- description: "Synchronous write-capable UI/UX implementation agent with ownership of approach, execution, and visual verification.",
37
+ description: "Write-capable UI/UX implementation agent with ownership of approach, execution, and visual verification.",
65
38
  config: {
66
39
  model,
67
40
  temperature: 0.4,
@@ -140,7 +113,7 @@ function createOracleAgent(model, customPrompt, customAppendPrompt) {
140
113
  });
141
114
  return {
142
115
  name: "oracle",
143
- description: "Synchronous read-only strategic advisor for debugging, architecture, code review, and SDD plan review.",
116
+ description: "Read-only strategic advisor for debugging, architecture, focused plan review, and independent verification.",
144
117
  config: {
145
118
  model,
146
119
  temperature: 0.1,
@@ -166,7 +139,7 @@ function createOrchestratorAgent(model, customPrompt, customAppendPrompt) {
166
139
  });
167
140
  const definition = {
168
141
  name: "orchestrator",
169
- description: "Adaptive root coordinator that handles bounded work directly and delegates only for net gain.",
142
+ description: "Director root that retains decisions and acceptance while specialists discover and implement by default.",
170
143
  config: {
171
144
  temperature: 0.1,
172
145
  prompt,
@@ -184,29 +157,29 @@ function createOrchestratorAgent(model, customPrompt, customAppendPrompt) {
184
157
  return definition;
185
158
  }
186
159
 
187
- // src/agents/quick.ts
188
- var QUICK_PROMPT = renderRolePrompt(
189
- createWriteCapableSpecialistPromptSections("quick"),
160
+ // src/agents/worker.ts
161
+ var WORKER_PROMPT = renderRolePrompt(
162
+ createWriteCapableSpecialistPromptSections("worker"),
190
163
  OPENCODE_PROMPT_DIALECT
191
164
  );
192
- function createQuickAgent(model, customPrompt, customAppendPrompt) {
165
+ function createWorkerAgent(model, customPrompt, customAppendPrompt) {
193
166
  const prompt = composeAgentPrompt({
194
- basePrompt: QUICK_PROMPT,
167
+ basePrompt: WORKER_PROMPT,
195
168
  customPrompt,
196
169
  customAppendPrompt: appendPromptSections(
197
- getModelFamilyPromptSection("quick", model),
170
+ getModelFamilyPromptSection("worker", model),
198
171
  customAppendPrompt
199
172
  )
200
173
  });
201
174
  return {
202
- name: "quick",
203
- description: "Synchronous write-capable implementation agent optimized for fast, mechanical, well-bounded changes \u2014 including uniform patterns across multiple files.",
175
+ name: "worker",
176
+ description: "Write-capable agent for bounded nonvisual implementation regardless of complexity, with thorough context analysis, edge-case handling, and correctness verification.",
204
177
  config: {
205
178
  model,
206
- temperature: 0.2,
179
+ temperature: 0.1,
207
180
  prompt,
208
- color: "success"
209
- // steps: 30,
181
+ color: "secondary"
182
+ // steps: 80,
210
183
  }
211
184
  };
212
185
  }
@@ -295,24 +268,7 @@ var BUILTIN_PERMISSION_PRESETS = {
295
268
  "~/.config/opencode/skills/**": "allow"
296
269
  }
297
270
  },
298
- quick: {
299
- read: "allow",
300
- edit: "allow",
301
- glob: "allow",
302
- grep: "allow",
303
- list: "allow",
304
- bash: "allow",
305
- question: "allow",
306
- codesearch: "allow",
307
- lsp: "allow",
308
- skill: "allow",
309
- todowrite: "deny",
310
- task: "deny",
311
- external_directory: {
312
- "~/.config/opencode/skills/**": "allow"
313
- }
314
- },
315
- deep: {
271
+ worker: {
316
272
  read: "allow",
317
273
  edit: "allow",
318
274
  glob: "allow",
@@ -357,7 +313,10 @@ function applyOverrides(agent, override) {
357
313
  }
358
314
  }
359
315
  function applyStepBudgetPrompt(agent) {
360
- const stepBudgetPrompt = getStepBudgetPromptSection(agent.config.steps);
316
+ const stepBudgetPrompt = getStepBudgetPromptSection(
317
+ agent.config.steps,
318
+ agent.name
319
+ );
361
320
  if (!stepBudgetPrompt) {
362
321
  return;
363
322
  }
@@ -398,8 +357,7 @@ var SUBAGENT_FACTORIES = {
398
357
  librarian: createLibrarianAgent,
399
358
  oracle: createOracleAgent,
400
359
  designer: createDesignerAgent,
401
- quick: createQuickAgent,
402
- deep: createDeepAgent
360
+ worker: createWorkerAgent
403
361
  };
404
362
  function createAgents(config) {
405
363
  const protoSubAgents = Object.entries(SUBAGENT_FACTORIES).map(([name, factory]) => {
@@ -532,7 +490,8 @@ function spawn(command, options = {}) {
532
490
  options.stdout ?? "pipe",
533
491
  options.stderr ?? "pipe"
534
492
  ],
535
- shell: options.shell
493
+ shell: options.shell,
494
+ windowsHide: options.windowsHide ?? true
536
495
  });
537
496
  const managed = {
538
497
  stdin: child.stdin ?? fallbackStdin(),
@@ -564,7 +523,8 @@ function spawnSync(command, options = {}) {
564
523
  options.stdout ?? "pipe",
565
524
  options.stderr ?? "pipe"
566
525
  ],
567
- shell: options.shell
526
+ shell: options.shell,
527
+ windowsHide: options.windowsHide ?? true
568
528
  });
569
529
  return { exitCode: result.status };
570
530
  }
@@ -659,7 +619,10 @@ async function isOpenCodeInstalled() {
659
619
  for (const opencodePath of paths) {
660
620
  try {
661
621
  const invocation = getOpenCodeVersionInvocation(opencodePath);
662
- const proc = spawn(invocation.command, invocation.options);
622
+ const proc = spawn(invocation.command, {
623
+ ...invocation.options,
624
+ windowsHide: true
625
+ });
663
626
  let timer;
664
627
  const timedOut = /* @__PURE__ */ Symbol("timeout");
665
628
  try {
@@ -694,7 +657,10 @@ async function getOpenCodeVersion() {
694
657
  const opencodePath = resolveOpenCodePath();
695
658
  try {
696
659
  const invocation = getOpenCodeVersionInvocation(opencodePath);
697
- const proc = spawn(invocation.command, invocation.options);
660
+ const proc = spawn(invocation.command, {
661
+ ...invocation.options,
662
+ windowsHide: true
663
+ });
698
664
  const output = await new Response(proc.stdout).text();
699
665
  await proc.exited;
700
666
  if (proc.exitCode === 0) {