thoth-agents 0.1.13 → 0.1.16

package/README.md

@@ -2,6 +2,13 @@
   <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>
+    <a href="https://www.npmjs.com/package/thoth-agents"><img src="https://img.shields.io/npm/v/thoth-agents?label=npm" alt="npm version"></a>
+    <a href="https://github.com/EremesNG/thoth-agents/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/thoth-agents" alt="MIT license"></a>
+    <img src="https://img.shields.io/node/v/thoth-agents" alt="Node.js version">
+    <img src="https://img.shields.io/badge/pnpm-11.2.2-F69220?logo=pnpm&logoColor=white" alt="pnpm 11.2.2">
+  </p>
 </div>
 
 ---

package/dist/{chunk-SCM2O4TP.js → chunk-HFKZF2ZB.js}

@@ -31,7 +31,7 @@ import {
   renderRolePrompt,
   writeConfig,
   writeLiteConfig
-} from "./chunk-WGFDTUZI.js";
+} from "./chunk-XTLXC2CM.js";
 
 // src/harness/adapters/codex.ts
 import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
@@ -94,7 +94,7 @@ var AGENT_ROLES = [
     responsibility: "Provide strategic technical guidance anchored to evidence and review SDD plans.",
     toolGovernance: [
       "read-only analysis and review",
-      "no implementation or artifact-producing SDD phases",
+      "no implementation; may perform read-only SDD plan review and verification review, but does not persist artifacts",
       "no task delegation"
     ],
     verification: ["separates observations, risks, and recommendations"]

package/dist/{chunk-WGFDTUZI.js → chunk-XTLXC2CM.js}

@@ -746,6 +746,186 @@ var CODEX_PROMPT_DIALECT = {
   }
 };
 
+// src/harness/core/sdd.ts
+var SDD_PHASES = [
+  {
+    id: "requirements-interview",
+    order: 0,
+    requiredFor: ["direct", "accelerated", "full"],
+    prerequisites: [],
+    producesArtifact: false,
+    owner: "orchestrator",
+    delegationReason: "Root-owned requirements discovery, scope calibration, and route approval."
+  },
+  {
+    id: "init",
+    order: 1,
+    requiredFor: [],
+    prerequisites: ["requirements-interview"],
+    producesArtifact: true,
+    owner: "write-capable-agent",
+    artifactSkill: "sdd-init",
+    condition: "Only when OpenSpec persistence is selected and openspec/ is missing.",
+    defaultAgentRole: "quick",
+    supportingAgentRoles: ["explorer"],
+    delegationReason: "Fast mechanical bootstrap, with explorer supplying repository facts when needed."
+  },
+  {
+    id: "explore",
+    order: 2,
+    requiredFor: ["accelerated", "full"],
+    prerequisites: ["requirements-interview"],
+    producesArtifact: false,
+    owner: "read-only-agent",
+    defaultAgentRole: "explorer",
+    supportingAgentRoles: ["librarian"],
+    delegationReason: "Read-only repository discovery before artifact-producing SDD phases."
+  },
+  {
+    id: "proposal",
+    order: 3,
+    requiredFor: ["accelerated", "full"],
+    prerequisites: ["requirements-interview", "explore"],
+    producesArtifact: true,
+    owner: "write-capable-agent",
+    artifactSkill: "sdd-propose",
+    defaultAgentRole: "deep",
+    supportingAgentRoles: ["oracle"],
+    delegationReason: "Structured technical reasoning and trade-off synthesis before implementation."
+  },
+  {
+    id: "spec",
+    order: 4,
+    requiredFor: ["full"],
+    prerequisites: ["proposal"],
+    producesArtifact: true,
+    owner: "write-capable-agent",
+    artifactSkill: "sdd-spec",
+    defaultAgentRole: "deep",
+    supportingAgentRoles: ["oracle"],
+    delegationReason: "High-quality requirement contract work where ambiguity propagates downstream."
+  },
+  {
+    id: "design",
+    order: 5,
+    requiredFor: ["full"],
+    prerequisites: ["proposal", "spec"],
+    producesArtifact: true,
+    owner: "write-capable-agent",
+    artifactSkill: "sdd-design",
+    artifactMeaning: "technical-solution-design",
+    defaultAgentRole: "deep",
+    supportingAgentRoles: ["designer"],
+    delegationReason: "Technical architecture and file-change design; designer only supports UI/UX concerns."
+  },
+  {
+    id: "tasks",
+    order: 6,
+    requiredFor: ["accelerated", "full"],
+    prerequisites: ["proposal", "spec", "design"],
+    producesArtifact: true,
+    owner: "write-capable-agent",
+    artifactSkill: "sdd-tasks",
+    defaultAgentRole: "quick",
+    alternateAgentRoles: ["deep"],
+    delegationReason: "Mechanical conversion of settled design into dependency-ordered execution tasks."
+  },
+  {
+    id: "plan-review",
+    order: 7,
+    requiredFor: ["accelerated", "full"],
+    prerequisites: ["tasks"],
+    producesArtifact: false,
+    gate: "oracle-review",
+    owner: "oracle",
+    defaultAgentRole: "oracle",
+    delegationReason: "Independent read-only executability review of tasks before implementation."
+  },
+  {
+    id: "implementation-confirmation",
+    order: 8,
+    requiredFor: ["accelerated", "full"],
+    prerequisites: ["plan-review"],
+    producesArtifact: false,
+    gate: "user-confirmation",
+    owner: "user",
+    delegationReason: "Human approval gate after reviewed tasks and before workspace implementation."
+  },
+  {
+    id: "apply",
+    order: 9,
+    requiredFor: ["direct", "accelerated", "full"],
+    prerequisites: ["implementation-confirmation"],
+    producesArtifact: false,
+    owner: "write-capable-agent",
+    defaultAgentRole: "deep",
+    alternateAgentRoles: ["quick", "designer"],
+    delegationReason: "Correctness-heavy implementation by default; quick handles mechanical batches and designer owns UI/visual work."
+  },
+  {
+    id: "verify",
+    order: 10,
+    requiredFor: ["accelerated", "full"],
+    prerequisites: ["apply"],
+    producesArtifact: true,
+    owner: "oracle",
+    artifactSkill: "sdd-verify",
+    defaultAgentRole: "oracle",
+    persistenceAgentRole: "quick",
+    delegationReason: "Independent verification review; quick persists the report when the selected store requires writes."
+  },
+  {
+    id: "archive",
+    order: 11,
+    requiredFor: ["accelerated", "full"],
+    prerequisites: ["verify"],
+    producesArtifact: true,
+    owner: "write-capable-agent",
+    artifactSkill: "sdd-archive",
+    defaultAgentRole: "quick",
+    delegationReason: "Mechanical closeout, summary, and archive movement after verification passes."
+  }
+];
+var SDD_WORKFLOW_CONTRACT = {
+  phases: [...SDD_PHASES],
+  routingRules: [
+    "Requirements interview is step zero for all non-trivial work.",
+    "Scope-faithful invariant: accepted user intent/scope is preserved; unresolved affected areas remain explicit as deferred/discovery follow-up.",
+    "Direct implementation is reserved for low-complexity work.",
+    "Accelerated SDD follows explore -> proposal -> tasks before execution.",
+    "Full SDD follows explore -> proposal -> spec -> design -> tasks before execution."
+  ],
+  artifactRules: [
+    "SDD delegation defaults are phase-specific: sdd-propose, sdd-spec, and sdd-design default to deep.",
+    "sdd-tasks defaults to quick with deep as fallback when the task plan is complex.",
+    "sdd-verify defaults to oracle for independent review; quick persists the report when repository or memory writes are required.",
+    "sdd-archive defaults to quick for mechanical closeout.",
+    "OpenSpec design.md is technical solution design, not UI/UX design; sdd-design itself never routes to designer.",
+    "Designer participates during apply only for user-facing UI, visual work, screenshots, or visual QA.",
+    "Full-pipeline tasks require proposal, spec, and design artifacts.",
+    "Oracle is read-only and performs plan review plus independent verification review; it does not persist artifacts."
+  ],
+  verificationRules: [
+    "Plan review must complete before implementation confirmation.",
+    "User confirmation is required after plan-review approval and before apply.",
+    "Apply is followed by verify and archive for SDD pipelines."
+  ]
+};
+function getSddWorkflowContract() {
+  return {
+    phases: SDD_WORKFLOW_CONTRACT.phases.map((phase) => ({
+      ...phase,
+      requiredFor: [...phase.requiredFor],
+      prerequisites: [...phase.prerequisites],
+      alternateAgentRoles: phase.alternateAgentRoles ? [...phase.alternateAgentRoles] : void 0,
+      supportingAgentRoles: phase.supportingAgentRoles ? [...phase.supportingAgentRoles] : void 0
+    })),
+    routingRules: [...SDD_WORKFLOW_CONTRACT.routingRules],
+    artifactRules: [...SDD_WORKFLOW_CONTRACT.artifactRules],
+    verificationRules: [...SDD_WORKFLOW_CONTRACT.verificationRules]
+  };
+}
+
 // src/agents/prompt-sections.ts
 function createQuestionProtocolSection() {
   return {
@@ -802,6 +982,43 @@ function createModelFamilySection(role, model) {
 function roleText(template) {
   return { kind: "role-text", template };
 }
+function roleTemplate(role) {
+  return `{{role.${role}}}`;
+}
+function renderRoleList(roles) {
+  return roles.map(roleTemplate).join(", ");
+}
+function getDelegatedSddPhase(id) {
+  const phase = getSddWorkflowContract().phases.find(
+    (candidate) => candidate.id === id
+  );
+  if (!phase?.defaultAgentRole) {
+    throw new Error(`Missing SDD delegation role for ${id}`);
+  }
+  return phase;
+}
+function primarySddRole(id) {
+  return roleTemplate(getDelegatedSddPhase(id).defaultAgentRole);
+}
+function alternateSddRoles(id) {
+  const phase = getDelegatedSddPhase(id);
+  return phase.alternateAgentRoles?.length ? renderRoleList(phase.alternateAgentRoles) : "";
+}
+function supportSddRoles(id) {
+  const phase = getDelegatedSddPhase(id);
+  return phase.supportingAgentRoles?.length ? renderRoleList(phase.supportingAgentRoles) : "";
+}
+function persistenceSddRole(id) {
+  const phase = getDelegatedSddPhase(id);
+  return phase.persistenceAgentRole ? roleTemplate(phase.persistenceAgentRole) : "";
+}
+function renderSddDelegationMatrix() {
+  return `<sdd-delegation-matrix>
+- sdd-init -> ${primarySddRole("init")} (+${supportSddRoles("init")}, if openspec/ missing); sdd-explore -> ${primarySddRole("explore")} (+${supportSddRoles("explore")})
+- sdd-propose/sdd-spec/sdd-design -> ${primarySddRole("proposal")}; sdd-tasks -> ${primarySddRole("tasks")} (fallback: ${alternateSddRoles("tasks")})
+- plan-reviewer -> ${primarySddRole("plan-review")}; sdd-apply -> ${primarySddRole("apply")} (fallback: ${alternateSddRoles("apply")}); sdd-verify -> ${primarySddRole("verify")} (persistence: ${persistenceSddRole("verify")}); sdd-archive -> ${primarySddRole("archive")}
+</sdd-delegation-matrix>`;
+}
 function specialistSections({
   role,
   mode,
@@ -942,15 +1159,19 @@ For {{role.explorer}}/{{role.librarian}}, ask narrow fact-finding questions for
 
 <sdd>
 All work always starts with requirements-interview skill.
+Scope-faithful invariant: accepted user intent and scope must not be silently narrowed; unresolved affected areas stay visible as deferred/discovery follow-up, not hidden as out-of-scope.
 
 Routes:
 - Direct implementation for low-complexity work.
-- Accelerated SDD: propose -> tasks.
-- Full SDD: propose -> spec -> design -> tasks.
+- Accelerated SDD: explore -> propose -> tasks.
+- Full SDD: explore -> propose -> spec -> design -> tasks.
+
+${renderSddDelegationMatrix()}
 
 Hard gates:
-- Artifact-producing SDD phases are dispatched to {{role.deep}} or {{role.quick}} with the matching skill loaded.
-- {{role.oracle}} is read-only and only handles plan-reviewer.
+- Use the SDD delegation matrix as canonical phase routing.
+- Load the matching skill when a phase has one.
+- {{role.oracle}} is read-only for plan-reviewer and sdd-verify review; {{role.quick}} persists verify reports when writes are required.
 - Never skip artifacts or jump from requirements-interview to implementation when SDD is selected.
 - Before SDD execution, load \`executing-plans\`; then track progress in {{progressTool}} plus the persistent artifact.
 - If openspec persistence is selected and openspec/ is missing, dispatch sdd-init first.

package/dist/cli/index.js

@@ -25,7 +25,7 @@ import {
   getOperationHarness,
   installRecommendedSkill,
   listOperationHarnesses
-} from "../chunk-SCM2O4TP.js";
+} from "../chunk-HFKZF2ZB.js";
 import {
   ALL_AGENT_NAMES,
   CUSTOM_SKILLS,
@@ -37,7 +37,7 @@ import {
   getExistingLiteConfigPath,
   installCustomSkills,
   writeLiteConfig
-} from "../chunk-WGFDTUZI.js";
+} from "../chunk-XTLXC2CM.js";
 
 // src/cli/index.ts
 import { pathToFileURL } from "url";

package/dist/cli/tui/index.js

@@ -15,13 +15,13 @@ import {
   getOpenCodeStatus,
   listOperationHarnesses,
   parseRoleTomlModel
-} from "../../chunk-SCM2O4TP.js";
+} from "../../chunk-HFKZF2ZB.js";
 import {
   ALL_AGENT_NAMES,
   DEFAULT_MODELS,
   getExistingLiteConfigPath,
   parseConfig
-} from "../../chunk-WGFDTUZI.js";
+} from "../../chunk-XTLXC2CM.js";
 
 // src/cli/tui/index.tsx
 import { render } from "ink";

package/dist/harness/core/agent-pack.d.ts

@@ -51,7 +51,7 @@ export declare const AGENT_ROLES: readonly [{
     readonly canMutateWorkspace: false;
     readonly scope: "advice, diagnosis, architecture, code review, and plan review";
     readonly responsibility: "Provide strategic technical guidance anchored to evidence and review SDD plans.";
-    readonly toolGovernance: ["read-only analysis and review", "no implementation or artifact-producing SDD phases", "no task delegation"];
+    readonly toolGovernance: ["read-only analysis and review", "no implementation; may perform read-only SDD plan review and verification review, but does not persist artifacts", "no task delegation"];
     readonly verification: ["separates observations, risks, and recommendations"];
 }, {
     readonly name: "designer";

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

@@ -1,6 +1,6 @@
 import type { AgentRoleName } from './agent-pack';
 export type SddPipelineType = 'direct' | 'accelerated' | 'full';
-export type SddPhaseId = 'requirements-interview' | 'proposal' | 'spec' | 'design' | 'tasks' | 'plan-review' | 'implementation-confirmation' | 'apply' | 'verify' | 'archive';
+export type SddPhaseId = 'requirements-interview' | 'init' | 'explore' | 'proposal' | 'spec' | 'design' | 'tasks' | 'plan-review' | 'implementation-confirmation' | 'apply' | 'verify' | 'archive';
 export interface SddPhaseContract {
     id: SddPhaseId;
     order: number;
@@ -8,11 +8,15 @@ export interface SddPhaseContract {
     prerequisites: SddPhaseId[];
     producesArtifact: boolean;
     gate?: 'oracle-review' | 'user-confirmation';
-    owner: 'orchestrator' | 'write-capable-agent' | 'oracle' | 'user';
+    owner: 'orchestrator' | 'read-only-agent' | 'write-capable-agent' | 'oracle' | 'user';
     artifactSkill?: string;
     artifactMeaning?: string;
+    condition?: string;
     defaultAgentRole?: AgentRoleName;
     alternateAgentRoles?: AgentRoleName[];
+    supportingAgentRoles?: AgentRoleName[];
+    persistenceAgentRole?: AgentRoleName;
+    delegationReason?: string;
 }
 export interface SddWorkflowContract {
     phases: SddPhaseContract[];
@@ -20,7 +24,7 @@ export interface SddWorkflowContract {
     artifactRules: string[];
     verificationRules: string[];
 }
-export declare const FULL_SDD_PHASE_ORDER: readonly ["requirements-interview", "proposal", "spec", "design", "tasks", "plan-review", "implementation-confirmation", "apply", "verify", "archive"];
+export declare const FULL_SDD_PHASE_ORDER: readonly ["requirements-interview", "explore", "proposal", "spec", "design", "tasks", "plan-review", "implementation-confirmation", "apply", "verify", "archive"];
 export declare const SDD_PHASES: readonly [{
     readonly id: "requirements-interview";
     readonly order: 0;
@@ -28,27 +32,54 @@ export declare const SDD_PHASES: readonly [{
     readonly prerequisites: [];
     readonly producesArtifact: false;
     readonly owner: "orchestrator";
+    readonly delegationReason: "Root-owned requirements discovery, scope calibration, and route approval.";
 }, {
-    readonly id: "proposal";
+    readonly id: "init";
     readonly order: 1;
+    readonly requiredFor: [];
+    readonly prerequisites: ["requirements-interview"];
+    readonly producesArtifact: true;
+    readonly owner: "write-capable-agent";
+    readonly artifactSkill: "sdd-init";
+    readonly condition: "Only when OpenSpec persistence is selected and openspec/ is missing.";
+    readonly defaultAgentRole: "quick";
+    readonly supportingAgentRoles: ["explorer"];
+    readonly delegationReason: "Fast mechanical bootstrap, with explorer supplying repository facts when needed.";
+}, {
+    readonly id: "explore";
+    readonly order: 2;
     readonly requiredFor: ["accelerated", "full"];
     readonly prerequisites: ["requirements-interview"];
+    readonly producesArtifact: false;
+    readonly owner: "read-only-agent";
+    readonly defaultAgentRole: "explorer";
+    readonly supportingAgentRoles: ["librarian"];
+    readonly delegationReason: "Read-only repository discovery before artifact-producing SDD phases.";
+}, {
+    readonly id: "proposal";
+    readonly order: 3;
+    readonly requiredFor: ["accelerated", "full"];
+    readonly prerequisites: ["requirements-interview", "explore"];
     readonly producesArtifact: true;
     readonly owner: "write-capable-agent";
     readonly artifactSkill: "sdd-propose";
     readonly defaultAgentRole: "deep";
+    readonly supportingAgentRoles: ["oracle"];
+    readonly delegationReason: "Structured technical reasoning and trade-off synthesis before implementation.";
 }, {
     readonly id: "spec";
-    readonly order: 2;
+    readonly order: 4;
     readonly requiredFor: ["full"];
     readonly prerequisites: ["proposal"];
     readonly producesArtifact: true;
     readonly owner: "write-capable-agent";
     readonly artifactSkill: "sdd-spec";
     readonly defaultAgentRole: "deep";
+    readonly supportingAgentRoles: ["oracle"];
+    readonly delegationReason: "High-quality requirement contract work where ambiguity propagates downstream.";
 }, {
     readonly id: "design";
-    readonly order: 3;
+    readonly order: 5;
     readonly requiredFor: ["full"];
     readonly prerequisites: ["proposal", "spec"];
     readonly producesArtifact: true;
@@ -56,58 +87,69 @@ export declare const SDD_PHASES: readonly [{
     readonly artifactSkill: "sdd-design";
     readonly artifactMeaning: "technical-solution-design";
     readonly defaultAgentRole: "deep";
+    readonly supportingAgentRoles: ["designer"];
+    readonly delegationReason: "Technical architecture and file-change design; designer only supports UI/UX concerns.";
 }, {
     readonly id: "tasks";
-    readonly order: 4;
+    readonly order: 6;
     readonly requiredFor: ["accelerated", "full"];
     readonly prerequisites: ["proposal", "spec", "design"];
     readonly producesArtifact: true;
     readonly owner: "write-capable-agent";
     readonly artifactSkill: "sdd-tasks";
-    readonly defaultAgentRole: "deep";
+    readonly defaultAgentRole: "quick";
+    readonly alternateAgentRoles: ["deep"];
+    readonly delegationReason: "Mechanical conversion of settled design into dependency-ordered execution tasks.";
 }, {
     readonly id: "plan-review";
-    readonly order: 5;
+    readonly order: 7;
     readonly requiredFor: ["accelerated", "full"];
     readonly prerequisites: ["tasks"];
     readonly producesArtifact: false;
     readonly gate: "oracle-review";
     readonly owner: "oracle";
+    readonly defaultAgentRole: "oracle";
+    readonly delegationReason: "Independent read-only executability review of tasks before implementation.";
 }, {
     readonly id: "implementation-confirmation";
-    readonly order: 6;
+    readonly order: 8;
     readonly requiredFor: ["accelerated", "full"];
     readonly prerequisites: ["plan-review"];
     readonly producesArtifact: false;
     readonly gate: "user-confirmation";
     readonly owner: "user";
+    readonly delegationReason: "Human approval gate after reviewed tasks and before workspace implementation.";
 }, {
     readonly id: "apply";
-    readonly order: 7;
+    readonly order: 9;
     readonly requiredFor: ["direct", "accelerated", "full"];
     readonly prerequisites: ["implementation-confirmation"];
     readonly producesArtifact: false;
     readonly owner: "write-capable-agent";
     readonly defaultAgentRole: "deep";
     readonly alternateAgentRoles: ["quick", "designer"];
+    readonly delegationReason: "Correctness-heavy implementation by default; quick handles mechanical batches and designer owns UI/visual work.";
 }, {
     readonly id: "verify";
-    readonly order: 8;
+    readonly order: 10;
     readonly requiredFor: ["accelerated", "full"];
     readonly prerequisites: ["apply"];
     readonly producesArtifact: true;
-    readonly owner: "write-capable-agent";
+    readonly owner: "oracle";
     readonly artifactSkill: "sdd-verify";
-    readonly defaultAgentRole: "deep";
+    readonly defaultAgentRole: "oracle";
+    readonly persistenceAgentRole: "quick";
+    readonly delegationReason: "Independent verification review; quick persists the report when the selected store requires writes.";
 }, {
     readonly id: "archive";
-    readonly order: 9;
+    readonly order: 11;
     readonly requiredFor: ["accelerated", "full"];
     readonly prerequisites: ["verify"];
     readonly producesArtifact: true;
     readonly owner: "write-capable-agent";
     readonly artifactSkill: "sdd-archive";
-    readonly defaultAgentRole: "deep";
+    readonly defaultAgentRole: "quick";
+    readonly delegationReason: "Mechanical closeout, summary, and archive movement after verification passes.";
 }];
 export declare const SDD_WORKFLOW_CONTRACT: SddWorkflowContract;
 export declare function getSddWorkflowContract(): SddWorkflowContract;

package/dist/index.js

@@ -26,7 +26,7 @@ import {
   loadPluginConfig,
   renderRolePrompt,
   stripJsonComments
-} from "./chunk-WGFDTUZI.js";
+} from "./chunk-XTLXC2CM.js";
 
 // src/index.ts
 import path4 from "path";

package/package.json

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