thoth-agents 0.2.3 → 0.2.5

package/README.md

@@ -1,6 +1,7 @@
 <div align="center">
-  <img src="img/team.png" alt="thoth-agents agents" width="420">
-  <p><i>Seven specialized agents, one delegate-first workflow across supported harnesses.</i></p>
+<img src="img/team.png" alt="thoth-agents agents" width="420">
+
+<p><i>Seven specialized agents, one delegate-first workflow across supported harnesses.</i></p>
   <p><b>thoth-agents</b> - Multi-harness orchestration - Thoth-mem persistence - Bundled SDD pipeline</p>
   <p>
     <a href="https://github.com/EremesNG/thoth-agents/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/EremesNG/thoth-agents/ci.yml?branch=master&label=CI" alt="CI status"></a>
@@ -50,11 +51,12 @@ hooks, MCP, skills, and per-agent tool permissions.
 
 ## Harness Support
 
-| Harness | Status | Setup path | Notes |
-| --- | --- | --- | --- |
-| OpenCode | Stable default | `npx thoth-agents@latest install` or `npx thoth-agents@latest install --agent=opencode` | Native plugin config, native `task` delegation, optional tmux panes, OpenCode provider auth. |
-| Codex | Supported explicit path | `npx thoth-agents@latest install --agent=codex` | Installs ambient/root guidance, six role subagents, and a Personal plugin source. Requires `/plugins` and `/hooks` trust review. Some governance remains instruction-level. |
-| Claude Code | Supported first-class path | `npx thoth-agents@latest install --agent=claude` | Installs one Claude Code plugin: six specialist subagents (`Task(subagent_type: ...)`), an `orchestrator` agent activated as the main thread via `settings.json`, `.mcp.json`, and bundled skills. Role permissions are enforced by subagent `tools`. |
+
+| Harness     | Status                     | Setup path                                                                              | Notes                                                                                                                                                                                                                                                 |
+| ----------- | -------------------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| OpenCode    | Stable default             | `npx thoth-agents@latest install` or `npx thoth-agents@latest install --agent=opencode` | Native plugin config, native`task` delegation, optional tmux panes, OpenCode provider auth.                                                                                                                                                           |
+| Codex       | Supported explicit path    | `npx thoth-agents@latest install --agent=codex`                                         | Installs ambient/root guidance, six role subagents, and a Personal plugin source. Requires`/plugins` and `/hooks` trust review. Some governance remains instruction-level.                                                                            |
+| Claude Code | Supported first-class path | `npx thoth-agents@latest install --agent=claude`                                        | Installs one Claude Code plugin: six specialist subagents (`Task(subagent_type: ...)`), an `orchestrator` agent activated as the main thread via `settings.json`, `.mcp.json`, and bundled skills. Role permissions are enforced by subagent `tools`. |
 
 OpenCode can load the plugin with:
 
@@ -323,14 +325,15 @@ artifacts before task execution.
 
 Artifacts can be persisted in four modes:
 
-| Mode | Writes to | Cost | Use when |
-| --- | --- | --- | --- |
-| `thoth-mem` | Memory only | Low | Fast iteration without repo planning files |
-| `openspec` | `openspec/` files only | Medium | Reviewable planning artifacts in the repo |
-| `hybrid` | Both | High | Maximum durability; default |
-| `none` | Neither | Lowest | Ephemeral iterations, no persistence |
 
-Thoth-mem is the local memory MCP used for durable observations, architectural
+| Mode        | Writes to              | Cost   | Use when                                   |
+| ----------- | ---------------------- | ------ | ------------------------------------------ |
+| `thoth-mem` | Memory only            | Low    | Fast iteration without repo planning files |
+| `openspec`  | `openspec/` files only | Medium | Reviewable planning artifacts in the repo  |
+| `hybrid`    | Both                   | High   | Maximum durability; default                |
+| `none`      | Neither                | Lowest | Ephemeral iterations, no persistence       |
+
+[Thoth-mem](https://github.com/EremesNG/thoth-mem) is the local memory MCP used for durable observations, architectural
 decisions, SDD artifacts, and session summaries. The core retrieval pattern is:
 
 1. `mem_recall(mode="compact")` for compact candidate records
@@ -355,12 +358,13 @@ planning/execution, verification, and archiving. It also registers MCP servers
 for docs research, public code search, and local memory where the harness
 supports that delivery surface.
 
-| Surface | Shared concept | OpenCode binding | Codex binding | Claude Code binding |
-| --- | --- | --- | --- | --- |
-| Skills | Requirements, SDD, review, execution workflows | Copied into the OpenCode skills directory when `--skills=yes` | Packaged as plugin-bundled skills for the Personal plugin source | Bundled in the plugin `skills/` directory |
-| MCPs | `exa`, `context7`, `grep_app`, `thoth_mem` | Registered by generated OpenCode plugin config | Packaged/configured only on validated Codex surfaces | Bundled in the plugin `.mcp.json` (`type: "http"` for URL servers) |
-| Delegation | Seven-role specialist workflow | Native `task` tool | Custom agents plus prompt/plugin guidance | Native `Task(subagent_type: ...)` over auto-discovered subagents |
-| Blocking choices | Use a structured question surface | OpenCode `question` tool | `request_user_input` when enabled and available | `AskUserQuestion` tool |
+
+| Surface          | Shared concept                                 | OpenCode binding                                             | Codex binding                                                    | Claude Code binding                                               |
+| ---------------- | ---------------------------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------- | ----------------------------------------------------------------- |
+| Skills           | Requirements, SDD, review, execution workflows | Copied into the OpenCode skills directory when`--skills=yes` | Packaged as plugin-bundled skills for the Personal plugin source | Bundled in the plugin`skills/` directory                          |
+| MCPs             | `exa`, `context7`, `grep_app`, `thoth_mem`     | Registered by generated OpenCode plugin config               | Packaged/configured only on validated Codex surfaces             | Bundled in the plugin`.mcp.json` (`type: "http"` for URL servers) |
+| Delegation       | Seven-role specialist workflow                 | Native`task` tool                                            | Custom agents plus prompt/plugin guidance                        | Native`Task(subagent_type: ...)` over auto-discovered subagents   |
+| Blocking choices | Use a structured question surface              | OpenCode`question` tool                                      | `request_user_input` when enabled and available                  | `AskUserQuestion` tool                                            |
 
 See [docs/skills-and-mcps.md](docs/skills-and-mcps.md) for the detailed matrix.
 
@@ -400,16 +404,17 @@ corepack prepare pnpm@11.2.2 --activate
 pnpm install
 ```
 
-| Command | Purpose |
-| --- | --- |
-| `pnpm run build` | Build TypeScript into `dist/` and generate declarations/schema |
-| `pnpm run typecheck` | Run TypeScript type checking without emit |
-| `pnpm test` | Run the Vitest suite |
-| `pnpm run lint` | Run Biome linter |
-| `pnpm run format` | Run Biome formatter |
-| `pnpm run check` | Run Biome check with auto-fix |
-| `pnpm run check:ci` | Run Biome check without writes |
-| `pnpm run dev` | Build and launch the OpenCode plugin in local dev mode |
+
+| Command              | Purpose                                                       |
+| -------------------- | ------------------------------------------------------------- |
+| `pnpm run build`     | Build TypeScript into`dist/` and generate declarations/schema |
+| `pnpm run typecheck` | Run TypeScript type checking without emit                     |
+| `pnpm test`          | Run the Vitest suite                                          |
+| `pnpm run lint`      | Run Biome linter                                              |
+| `pnpm run format`    | Run Biome formatter                                           |
+| `pnpm run check`     | Run Biome check with auto-fix                                 |
+| `pnpm run check:ci`  | Run Biome check without writes                                |
+| `pnpm run dev`       | Build and launch the OpenCode plugin in local dev mode        |
 
 ## License
 

package/dist/{chunk-FHEYA3VV.js → chunk-C3VQMXQL.js}

@@ -35,7 +35,7 @@ import {
   renderRolePrompt,
   writeConfig,
   writeLiteConfig
-} from "./chunk-37QKOSBR.js";
+} from "./chunk-HFZAL6NE.js";
 
 // src/cli/codex-paths.ts
 import { homedir } from "os";
@@ -1480,8 +1480,11 @@ function renderCodexRootInstructions(config) {
     codexInternalHandoffGuidance(),
     "<codex-runtime>",
     "- The ambient Codex root session is the root/main orchestrator; orchestrator-only and root-owned instructions apply to it because Codex does not generate a selectable orchestrator agent TOML.",
-    '- On each new root session, when thoth-mem tools are installed and session/project identity is known, call mem_session(action="start") as step 0 before any other thoth-mem call, then save the real user prompt with mem_save(kind="prompt") before later delegation.',
-    "- If thoth-mem tools or identity values are unavailable, disclose that memory bootstrap could not run and continue without claiming memory was saved.",
+    '- On each new root session, first resolve the stable root session identity from Codex request metadata in this order: `nodeRepl.requestMeta["x-codex-turn-metadata"].session_id`, then `nodeRepl.requestMeta["x-codex-turn-metadata"].thread_id`, then `nodeRepl.requestMeta.threadId`. Do not use `nodeRepl.requestMeta["x-codex-turn-metadata"].turn_id` as the stable session id.',
+    '- `nodeRepl.requestMeta["x-codex-turn-metadata"].turn_id` is per-turn metadata only, not the stable root session id.',
+    "- If `nodeRepl.requestMeta` is not yet visible and `tool_search` is available, load/discover the `node_repl` MCP tool before concluding metadata is unavailable.",
+    '- When thoth-mem tools are installed and stable root session identity is resolved, call mem_session(action="start") as step 0 before any other thoth-mem call, then save the real user prompt with mem_save(kind="prompt") before later delegation.',
+    "- If metadata tooling is unavailable, or the required fields are missing, disclose that memory bootstrap could not run and continue without claiming memory was saved.",
     '- Before delegating after meaningful context changes, save or refresh the handoff body with root-owned mem_session(action="summary") or mem_save(kind="session_summary") when available; if unavailable, disclose that root-owned compaction could not be persisted.',
     "- Use the ambient Codex root session as the delegate-first root coordinator; do not generate or select an orchestrator TOML.",
     "- Delegate by invoking `multi_agent_v1.spawn_agent` for the installed Codex role agents: explorer, librarian, oracle, designer, quick, and deep.",

package/dist/{chunk-37QKOSBR.js → chunk-HFZAL6NE.js}

@@ -1749,6 +1749,14 @@ var BUNDLED_SKILL_REGISTRY = [
     kind: "skill",
     purpose: "sdd"
   },
+  {
+    name: "sdd-clarify",
+    description: "Resolve residual spec ambiguity in place before design, with a bounded taxonomy-driven clarification pass.",
+    allowedRoles: ORCHESTRATOR_ONLY,
+    sourcePath: "src/skills/sdd-clarify",
+    kind: "skill",
+    purpose: "sdd"
+  },
   {
     name: "sdd-design",
     description: "Create technical solution design artifacts for changes",

package/dist/{chunk-7KLRUFZ4.js → chunk-YZNH23HZ.js}

@@ -13,7 +13,7 @@ import {
   getStepBudgetPromptSection,
   loadAgentPrompt,
   renderRolePrompt
-} from "./chunk-37QKOSBR.js";
+} from "./chunk-HFZAL6NE.js";
 
 // src/agents/deep.ts
 var DEEP_PROMPT = renderRolePrompt(

package/dist/cli/index.js

@@ -4,7 +4,7 @@ import {
   getOpenCodeVersion,
   isOpenCodeInstalled,
   opencodeAdapter
-} from "../chunk-7KLRUFZ4.js";
+} from "../chunk-YZNH23HZ.js";
 import {
   CODEX_ROLE_NAMES,
   RECOMMENDED_SKILLS,
@@ -36,7 +36,7 @@ import {
   getOperationHarness,
   installRecommendedSkill,
   listOperationHarnesses
-} from "../chunk-FHEYA3VV.js";
+} from "../chunk-C3VQMXQL.js";
 import {
   ALL_AGENT_NAMES,
   CUSTOM_SKILLS,
@@ -48,7 +48,7 @@ import {
   getExistingLiteConfigPath,
   installCustomSkills,
   writeLiteConfig
-} from "../chunk-37QKOSBR.js";
+} from "../chunk-HFZAL6NE.js";
 
 // src/cli/index.ts
 import { pathToFileURL } from "url";

package/dist/cli/tui/index.js

@@ -25,13 +25,13 @@ import {
   listOperationHarnesses,
   parseRoleTomlModel,
   parseSubagentModel
-} from "../../chunk-FHEYA3VV.js";
+} from "../../chunk-C3VQMXQL.js";
 import {
   ALL_AGENT_NAMES,
   DEFAULT_MODELS,
   getExistingLiteConfigPath,
   parseConfig
-} from "../../chunk-37QKOSBR.js";
+} from "../../chunk-HFZAL6NE.js";
 
 // src/cli/tui/index.tsx
 import { render } from "ink";

package/dist/harness/core/skills.d.ts

@@ -51,6 +51,13 @@ export declare const BUNDLED_SKILL_REGISTRY: readonly [{
     readonly sourcePath: "src/skills/sdd-spec";
     readonly kind: "skill";
     readonly purpose: "sdd";
+}, {
+    readonly name: "sdd-clarify";
+    readonly description: "Resolve residual spec ambiguity in place before design, with a bounded taxonomy-driven clarification pass.";
+    readonly allowedRoles: AgentRoleName[];
+    readonly sourcePath: "src/skills/sdd-clarify";
+    readonly kind: "skill";
+    readonly purpose: "sdd";
 }, {
     readonly name: "sdd-design";
     readonly description: "Create technical solution design artifacts for changes";
@@ -143,6 +150,13 @@ export declare const SKILL_REGISTRY: readonly [{
     readonly sourcePath: "src/skills/sdd-spec";
     readonly kind: "skill";
     readonly purpose: "sdd";
+}, {
+    readonly name: "sdd-clarify";
+    readonly description: "Resolve residual spec ambiguity in place before design, with a bounded taxonomy-driven clarification pass.";
+    readonly allowedRoles: AgentRoleName[];
+    readonly sourcePath: "src/skills/sdd-clarify";
+    readonly kind: "skill";
+    readonly purpose: "sdd";
 }, {
     readonly name: "sdd-design";
     readonly description: "Create technical solution design artifacts for changes";

package/dist/index.js

@@ -3,7 +3,7 @@ import {
   renderOpenCodeAgentConfigs,
   spawn,
   spawnSync
-} from "./chunk-7KLRUFZ4.js";
+} from "./chunk-YZNH23HZ.js";
 import {
   DEFAULT_THOTH_COMMAND,
   POLL_INTERVAL_BACKGROUND_MS,
@@ -14,7 +14,7 @@ import {
   installCustomSkills,
   loadPluginConfig,
   stripJsonComments
-} from "./chunk-37QKOSBR.js";
+} from "./chunk-HFZAL6NE.js";
 
 // src/index.ts
 import path4 from "path";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thoth-agents",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Delegate-first OpenCode plugin with seven agents, thoth-mem persistence, and bundled SDD skills.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/skills/requirements-interview/SKILL.md

@@ -201,6 +201,7 @@ Hand off to:
 - **Explore**: delegate read-only repository discovery to explorer before artifact-producing phases.
 - **Propose**: [../sdd-propose/SKILL.md](../sdd-propose/SKILL.md)
 - **Spec** (full SDD only): [../sdd-spec/SKILL.md](../sdd-spec/SKILL.md)
+- **Clarify** (full SDD only): [../sdd-clarify/SKILL.md](../sdd-clarify/SKILL.md)
 - **Design** (full SDD only): [../sdd-design/SKILL.md](../sdd-design/SKILL.md)
 - **Tasks**: [../sdd-tasks/SKILL.md](../sdd-tasks/SKILL.md)