thoth-agents 0.3.5 → 0.3.6

package/dist/cli/index.js

@@ -42,8 +42,9 @@ import {
   getRequiredSkillInstallCommand,
   installRequiredSkill,
   listOperationHarnesses,
-  normalizeEffortSelection
-} from "../chunk-W5GCMYA3.js";
+  normalizeEffortSelection,
+  syncOpenCodeOwnedSkills
+} from "../chunk-HIXSRHEG.js";
 import {
   ALL_AGENT_NAMES,
   detectCurrentConfig,
@@ -551,9 +552,30 @@ function formatConfigSummary(dryRun) {
   lines.push(
     `  ${DIM}\u25CB thoth-mem remains the owner of hooks, MCP, skill, lifecycle, persistence, receipts, and recovery.${RESET}`
   );
+  lines.push(`  ${SYMBOLS.check} Global thoth-owned OpenCode skills`);
   lines.push(`  ${SYMBOLS.check} Required external skills for this harness`);
   return lines.join("\n");
 }
+function installOwnedSkillsForOpenCode(dryRun, dependencies) {
+  const result = syncOpenCodeOwnedSkills({
+    dryRun,
+    homeDir: dependencies.homeDir ?? homedir(),
+    packageRoot: dependencies.opencodeOwnedSkillPackageRoot
+  });
+  for (const skill of result.skills) {
+    printInfo(`  - ${skill.name}: ${skill.destinationPath}`);
+  }
+  if (!result.success) {
+    printError(
+      `Failed to synchronize global thoth-owned OpenCode skills: ${result.error ?? "unknown error"}`
+    );
+    return false;
+  }
+  printSuccess(
+    dryRun ? "Global thoth-owned OpenCode skills planned" : "Global thoth-owned OpenCode skills synchronized"
+  );
+  return true;
+}
 function installRequiredSkillsForHarness(harness, dryRun, homeDir = homedir()) {
   if (dryRun) {
     printInfo(`Dry run mode - required ${harness} skills:`);
@@ -617,7 +639,7 @@ async function runInstall(config, dependencies) {
   const detected = detectCurrentConfig();
   const isUpdate = detected.isInstalled;
   printHeader(isUpdate);
-  const totalSteps = 5;
+  const totalSteps = 6;
   let step = 1;
   printStep(step++, totalSteps, "Checking OpenCode installation...");
   if (config.dryRun) {
@@ -666,8 +688,19 @@ ${JSON.stringify(liteConfig, null, 2)}
         return 1;
     }
   }
+  printStep(
+    step++,
+    totalSteps,
+    "Synchronizing global thoth-owned OpenCode skills..."
+  );
+  if (!installOwnedSkillsForOpenCode(config.dryRun, dependencies)) return 1;
   printStep(step++, totalSteps, "Installing required external skills...");
-  if (!installRequiredSkillsForHarness("opencode", config.dryRun)) return 1;
+  if (!installRequiredSkillsForHarness(
+    "opencode",
+    config.dryRun,
+    dependencies.homeDir ?? homedir()
+  ))
+    return 1;
   printStep(step++, totalSteps, "Configuring provider-owned thoth-mem...");
   if (!installThothMemForHarness("opencode", config.dryRun, dependencies)) {
     return 1;

package/dist/cli/install.d.ts

@@ -1,6 +1,8 @@
 import { type ThothMemSetupOptions, type ThothMemSetupResult } from './thoth-mem-install';
 import type { InstallArgs, InstallConfig } from './types';
 export interface InstallDependencies {
+    homeDir?: string;
+    opencodeOwnedSkillPackageRoot?: string;
     runThothMemSetup?: (options: ThothMemSetupOptions) => ThothMemSetupResult;
 }
 export declare function createInstallConfig(args: InstallArgs): InstallConfig;

package/dist/cli/operations/opencode.d.ts

@@ -9,7 +9,7 @@ export declare const opencodeOperationAdapter: {
 };
 export declare function getOpenCodeStatus(context?: OperationContext, evidence?: ProviderEvidenceInput): HarnessStatusReport;
 export declare function buildOpenCodeUpdatePlan(_context?: OperationContext): OperationPlan;
-export declare function buildOpenCodeSyncPlan(_context?: OperationContext): OperationPlan;
-export declare function buildOpenCodeInstallPlan(_context?: OperationContext): OperationPlan;
+export declare function buildOpenCodeSyncPlan(context?: OperationContext): OperationPlan;
+export declare function buildOpenCodeInstallPlan(context?: OperationContext): OperationPlan;
 export declare function buildOpenCodeModelPlan(input: ModelConfigInput, _context?: OperationContext): OperationPlan;
 export declare function applyOpenCodePlan(plan: OperationPlan): OperationApplyResult;

package/dist/cli/owned-skills.d.ts

@@ -0,0 +1,20 @@
+import { type ThothOwnedSkillName } from '../harness/core/owned-skills';
+export interface OpenCodeOwnedSkillSyncOptions {
+    dryRun?: boolean;
+    homeDir?: string;
+    packageRoot?: string;
+}
+export interface OpenCodeOwnedSkillSyncEntry {
+    name: ThothOwnedSkillName;
+    sourcePath: string;
+    destinationPath: string;
+}
+export interface OpenCodeOwnedSkillSyncResult {
+    success: boolean;
+    status: 'planned' | 'installed' | 'failed';
+    skills: OpenCodeOwnedSkillSyncEntry[];
+    error?: string;
+}
+export declare function resolveOwnedSkillPackageRoot(moduleUrl: string): string;
+export declare function getOpenCodeOwnedSkillEntries(options?: Pick<OpenCodeOwnedSkillSyncOptions, 'homeDir' | 'packageRoot'>): OpenCodeOwnedSkillSyncEntry[];
+export declare function syncOpenCodeOwnedSkills(options?: OpenCodeOwnedSkillSyncOptions): OpenCodeOwnedSkillSyncResult;

package/dist/cli/tui/index.js

@@ -2,7 +2,7 @@ import {
   defaultTuiOperations,
   effortChoicesForModel,
   listOperationHarnesses
-} from "../../chunk-W5GCMYA3.js";
+} from "../../chunk-HIXSRHEG.js";
 import "../../chunk-F2K4CS5J.js";
 
 // src/cli/tui/index.tsx

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

@@ -0,0 +1,2 @@
+export declare const THOTH_OWNED_SKILL_NAMES: readonly ["thoth-init", "thoth-sdd", "thoth-constitution", "thoth-archive", "plan-reviewer"];
+export type ThothOwnedSkillName = (typeof THOTH_OWNED_SKILL_NAMES)[number];

package/dist/index.js

@@ -42,12 +42,13 @@ function createOpenCodeInitCommand({
     subtask: false,
     template: `Initialize this project now using the bundled thoth-init skill.
 
-The operation must stay project-scoped, idempotent, and offline. Run:
+The operation must stay scoped to openspec/, idempotent, and offline. Run:
 
-node "${scriptPath}" --project "${projectRoot}" --harness opencode --json
+node "${scriptPath}" --project "${projectRoot}" --json
 
-Inspect the JSON result, report created and preserved files, and do not download
-skills or invoke the thoth-agents CLI.
+Inspect the JSON result and report created, managed, and preserved OpenSpec
+assets. Do not install skills or agents, download dependencies, modify harness
+configuration, or invoke the thoth-agents CLI.
 
 Bundled skill contract:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thoth-agents",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "description": "Adaptive multi-harness orchestration with seven roles, runtime-autonomous Spec Kit-compatible SDD routes, and external provider boundaries.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "thoth-agents",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "description": "Adaptive multi-harness agent pack with seven roles and a runtime-autonomous Spec Kit-compatible SDD bundle for Claude Code.",
   "author": {
     "name": "thoth-agents"

package/plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "thoth-agents",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "description": "Bundled Spec Kit-compatible SDD skills and MCP configuration; the seven-role global Codex layer requires thoth-agents CLI setup.",
   "skills": "./skills/",
   "mcpServers": "./codex.mcp.json"

package/plugin/skills/thoth-init/SKILL.md

@@ -1,30 +1,33 @@
 ---
 name: thoth-init
-description: Initialize project SDD governance and OpenCode local skills from the installed bundle; Codex global agents and instructions remain CLI-owned.
+description: Initialize or synchronize the minimum project OpenSpec governance structure required by thoth-agents SDD flows.
 ---
 
 # Thoth Init
 
-Initialize the current project from this installed skill bundle. Resolve
-`<skill-dir>` as the directory containing this `SKILL.md`, then run the bundled
-script by absolute path:
+Initialize or synchronize the current project's OpenSpec governance from this
+installed skill bundle. Resolve `<skill-dir>` as the directory containing this
+`SKILL.md`, then run the bundled script by absolute path:
 
 ```text
-node "<skill-dir>/scripts/init.mjs" --project <project-root> --harness <opencode|codex|claude> --json
+node "<skill-dir>/scripts/init.mjs" --project <project-root> --json
 ```
 
-- OpenCode materializes the five thoth-owned workflow skills under
-  `.agents/skills/`.
-- Codex init creates project governance only. Codex plugin manifests cannot
-  install custom agents or global instructions; first run the mandatory
-  thoth-agents CLI setup that manages `~/.codex/agents/`,
-  `~/.codex/AGENTS.md`, and `~/.codex/config.toml`.
-- Claude uses auto-discovered plugin agents and owned skills; init creates only
-  project governance assets.
+The project root must already exist. The initializer preflights the complete
+target structure before changing it, then ensures these minimum paths exist:
 
-For every harness, installation must already have used the thoth-agents CLI to
-install mandatory external skills from their canonical repositories. This init
-skill never invokes the CLI or downloads a skill.
+- `openspec/changes/archive/`
+- `openspec/specs/`
+- `openspec/memory/`
+- `openspec/templates/`
+- `openspec/.thoth-agents.json`
 
-The operation is offline and idempotent. It never overwrites the project
-constitution, templates, or unrelated instruction content.
+Missing constitution and SDD template files are copied from the installed
+bundle. Existing constitution and template files remain byte-for-byte intact;
+the thoth-managed manifest may be normalized to the current contract. Inspect
+the JSON `created`, `managed`, and `preserved` arrays when reporting the result.
+
+This operation is offline, idempotent, and harness-neutral. Every write stays
+inside `openspec/`. It never installs or synchronizes skills, agents, plugins,
+harness configuration, external dependencies, or global instruction files;
+those are responsibilities of `npx thoth-agents install`.

package/plugin/skills/thoth-init/scripts/init.mjs

@@ -3,10 +3,10 @@
 import {
   cpSync,
   existsSync,
+  lstatSync,
   mkdirSync,
   readdirSync,
   readFileSync,
-  statSync,
   writeFileSync,
 } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
@@ -15,12 +15,13 @@ import { fileURLToPath } from 'node:url';
 const SCRIPT_PATH = fileURLToPath(import.meta.url);
 const SKILL_ROOT = dirname(dirname(SCRIPT_PATH));
 const BUNDLE_ROOT = dirname(SKILL_ROOT);
-const OWNED_SKILL_NAMES = [
-  'thoth-init',
-  'thoth-sdd',
-  'thoth-constitution',
-  'thoth-archive',
-  'plan-reviewer',
+const OPEN_SPEC_DIRECTORIES = [
+  'openspec',
+  join('openspec', 'changes'),
+  join('openspec', 'changes', 'archive'),
+  join('openspec', 'specs'),
+  join('openspec', 'memory'),
+  join('openspec', 'templates'),
 ];
 
 function parseArgs(argv) {
@@ -29,110 +30,193 @@ function parseArgs(argv) {
     const argument = argv[index];
     if (argument === '--json') options.json = true;
     else if (argument === '--project') options.project = argv[++index];
-    else if (argument === '--harness') options.harness = argv[++index];
     else throw new Error(`Unknown argument: ${argument}`);
   }
   if (!options.project) throw new Error('--project is required');
-  if (!['opencode', 'codex', 'claude'].includes(options.harness)) {
-    throw new Error('--harness must be opencode, codex, or claude');
-  }
   return options;
 }
 
-function copyMissing(source, target, report) {
-  if (!existsSync(source)) return;
-  const sourceStat = statSync(source);
-  if (sourceStat.isDirectory()) {
-    mkdirSync(target, { recursive: true });
-    for (const entry of readdirSync(source)) {
-      copyMissing(join(source, entry), join(target, entry), report);
+function assertDirectory(path, label) {
+  if (!existsSync(path)) return;
+  const stat = lstatSync(path);
+  if (stat.isSymbolicLink() || !stat.isDirectory()) {
+    throw new Error(`${label} must be a directory: ${path}`);
+  }
+}
+
+function assertRegularFile(path, label) {
+  if (!existsSync(path)) return;
+  const stat = lstatSync(path);
+  if (stat.isSymbolicLink() || !stat.isFile()) {
+    throw new Error(`${label} must be a regular file: ${path}`);
+  }
+}
+
+function collectFiles(sourceRoot, targetRoot) {
+  if (!existsSync(sourceRoot)) {
+    throw new Error(`Bundled SDD template directory is missing: ${sourceRoot}`);
+  }
+  assertDirectory(sourceRoot, 'Bundled template directory');
+  const entries = [];
+
+  function visit(source, target) {
+    for (const entry of readdirSync(source, { withFileTypes: true })) {
+      const sourcePath = join(source, entry.name);
+      const targetPath = join(target, entry.name);
+      if (entry.isSymbolicLink()) {
+        throw new Error(
+          `Bundled templates cannot contain symlinks: ${sourcePath}`,
+        );
+      }
+      if (entry.isDirectory()) {
+        entries.push({ kind: 'directory', target: targetPath });
+        visit(sourcePath, targetPath);
+      } else if (entry.isFile()) {
+        entries.push({ kind: 'file', source: sourcePath, target: targetPath });
+      } else {
+        throw new Error(`Unsupported bundled template entry: ${sourcePath}`);
+      }
     }
-    return;
   }
+
+  visit(sourceRoot, targetRoot);
+  return entries;
+}
+
+function preflight(project) {
+  assertDirectory(project, 'Project root');
+  if (!existsSync(project)) {
+    throw new Error(
+      `--project must reference an existing project directory: ${project}`,
+    );
+  }
+
+  const constitutionSource = join(
+    BUNDLE_ROOT,
+    'thoth-constitution',
+    'templates',
+    'constitution.md',
+  );
+  assertRegularFile(constitutionSource, 'Bundled constitution template');
+  if (!existsSync(constitutionSource)) {
+    throw new Error(
+      `Bundled constitution template is missing: ${constitutionSource}`,
+    );
+  }
+
+  const templates = collectFiles(
+    join(BUNDLE_ROOT, 'thoth-sdd', 'templates'),
+    join(project, 'openspec', 'templates'),
+  );
+  for (const directory of OPEN_SPEC_DIRECTORIES) {
+    assertDirectory(join(project, directory), 'OpenSpec path');
+  }
+  for (const entry of templates) {
+    if (entry.kind === 'directory') {
+      assertDirectory(entry.target, 'OpenSpec template path');
+    } else {
+      assertRegularFile(entry.target, 'OpenSpec template path');
+    }
+  }
+
+  const constitutionTarget = join(
+    project,
+    'openspec',
+    'memory',
+    'constitution.md',
+  );
+  const manifestTarget = join(project, 'openspec', '.thoth-agents.json');
+  assertRegularFile(constitutionTarget, 'OpenSpec constitution path');
+  assertRegularFile(manifestTarget, 'OpenSpec manifest path');
+
+  return {
+    constitutionSource,
+    constitutionTarget,
+    manifestTarget,
+    templates,
+  };
+}
+
+function createDirectory(target, report) {
+  if (existsSync(target)) return;
+  mkdirSync(target);
+  report.created.push(target);
+}
+
+function copyPreservingExisting(source, target, report) {
   if (existsSync(target)) {
-    report.skipped.push(target);
+    report.preserved.push(target);
     return;
   }
-  mkdirSync(dirname(target), { recursive: true });
   cpSync(source, target, { errorOnExist: true });
   report.created.push(target);
 }
 
-function writeMissing(target, content, report) {
+function writePreservingExisting(target, content, report) {
   if (existsSync(target)) {
-    report.skipped.push(target);
+    report.preserved.push(target);
     return;
   }
-  mkdirSync(dirname(target), { recursive: true });
   writeFileSync(target, content);
   report.created.push(target);
 }
 
-function installConstitution(project, report) {
-  const target = join(project, 'openspec', 'memory', 'constitution.md');
-  const template = join(
-    BUNDLE_ROOT,
-    'thoth-constitution',
-    'templates',
-    'constitution.md',
-  );
-  if (!existsSync(template)) return;
-  const today = new Date().toISOString().slice(0, 10);
-  writeMissing(
-    target,
-    readFileSync(template, 'utf8').replaceAll('YYYY-MM-DD', today),
-    report,
-  );
+function synchronizeManagedFile(target, content, report) {
+  if (!existsSync(target)) {
+    writeFileSync(target, content);
+    report.created.push(target);
+    return;
+  }
+  if (readFileSync(target, 'utf8') === content) {
+    report.preserved.push(target);
+    return;
+  }
+  writeFileSync(target, content);
+  report.managed.push(target);
 }
 
-function installGovernance(project, report) {
-  installConstitution(project, report);
-  const templatesRoot = join(BUNDLE_ROOT, 'thoth-sdd', 'templates');
-  if (existsSync(templatesRoot)) {
-    for (const entry of readdirSync(templatesRoot)) {
-      copyMissing(
-        join(templatesRoot, entry),
-        join(project, 'openspec', 'templates', entry),
-        report,
-      );
-    }
+function synchronizeOpenSpec(project, assets, report) {
+  for (const directory of OPEN_SPEC_DIRECTORIES) {
+    createDirectory(join(project, directory), report);
   }
-  writeMissing(
-    join(project, 'openspec', '.thoth-agents.json'),
+  for (const entry of assets.templates) {
+    if (entry.kind === 'directory') createDirectory(entry.target, report);
+    else copyPreservingExisting(entry.source, entry.target, report);
+  }
+
+  const today = new Date().toISOString().slice(0, 10);
+  writePreservingExisting(
+    assets.constitutionTarget,
+    readFileSync(assets.constitutionSource, 'utf8').replaceAll(
+      'YYYY-MM-DD',
+      today,
+    ),
+    report,
+  );
+  synchronizeManagedFile(
+    assets.manifestTarget,
     `${JSON.stringify({ version: 1, initializedBy: 'thoth-agents' }, null, 2)}\n`,
     report,
   );
 }
 
-function installOpenCode(project, report) {
-  for (const skillName of OWNED_SKILL_NAMES) {
-    copyMissing(
-      join(BUNDLE_ROOT, skillName),
-      join(project, '.agents', 'skills', skillName),
-      report,
-    );
-  }
-}
-
 try {
   const options = parseArgs(process.argv.slice(2));
   const project = resolve(options.project);
-  mkdirSync(project, { recursive: true });
+  const assets = preflight(project);
   const report = {
     status: 'ready',
-    harness: options.harness,
     project,
     created: [],
     managed: [],
-    skipped: [],
+    preserved: [],
   };
 
-  installGovernance(project, report);
-  if (options.harness === 'opencode') installOpenCode(project, report);
+  synchronizeOpenSpec(project, assets, report);
 
   const output = options.json
     ? JSON.stringify(report)
-    : `thoth-agents initialized ${project} for ${options.harness}`;
+    : `thoth-agents synchronized OpenSpec governance in ${project}`;
   process.stdout.write(`${output}\n`);
 } catch (error) {
   process.stderr.write(

package/skills/README.md

@@ -2,8 +2,8 @@
 
 This directory is the canonical, versioned source for skills owned by
 thoth-agents. `pnpm run integration:sync` copies those skills into the Codex and
-Claude Code plugins; OpenCode exposes `/thoth-init`, which materializes them
-project-locally.
+Claude Code plugins; `npx thoth-agents install --agent=opencode` materializes
+the same packaged skill trees globally under `~/.config/opencode/skills/`.
 
 Owned workflow skills are `thoth-init`, `thoth-sdd`, `thoth-constitution`,
 `thoth-archive`, and `plan-reviewer`. The last one implements the optional,
@@ -11,4 +11,6 @@ user-selected, read-only Oracle review before implementation. Mandatory external
 skills (`simplify`, `tdd`,
 `progressive-context-router`, and `architectural-grilling`) are not copied here:
 the thoth-agents installer invokes `npx skills add` against their canonical
-repositories so they retain a single source of truth.
+repositories so they retain a single source of truth. `thoth-init` only
+initializes or synchronizes minimum project `openspec/` governance and never
+installs skills.

package/skills/thoth-init/SKILL.md

@@ -1,30 +1,33 @@
 ---
 name: thoth-init
-description: Initialize project SDD governance and OpenCode local skills from the installed bundle; Codex global agents and instructions remain CLI-owned.
+description: Initialize or synchronize the minimum project OpenSpec governance structure required by thoth-agents SDD flows.
 ---
 
 # Thoth Init
 
-Initialize the current project from this installed skill bundle. Resolve
-`<skill-dir>` as the directory containing this `SKILL.md`, then run the bundled
-script by absolute path:
+Initialize or synchronize the current project's OpenSpec governance from this
+installed skill bundle. Resolve `<skill-dir>` as the directory containing this
+`SKILL.md`, then run the bundled script by absolute path:
 
 ```text
-node "<skill-dir>/scripts/init.mjs" --project <project-root> --harness <opencode|codex|claude> --json
+node "<skill-dir>/scripts/init.mjs" --project <project-root> --json
 ```
 
-- OpenCode materializes the five thoth-owned workflow skills under
-  `.agents/skills/`.
-- Codex init creates project governance only. Codex plugin manifests cannot
-  install custom agents or global instructions; first run the mandatory
-  thoth-agents CLI setup that manages `~/.codex/agents/`,
-  `~/.codex/AGENTS.md`, and `~/.codex/config.toml`.
-- Claude uses auto-discovered plugin agents and owned skills; init creates only
-  project governance assets.
+The project root must already exist. The initializer preflights the complete
+target structure before changing it, then ensures these minimum paths exist:
 
-For every harness, installation must already have used the thoth-agents CLI to
-install mandatory external skills from their canonical repositories. This init
-skill never invokes the CLI or downloads a skill.
+- `openspec/changes/archive/`
+- `openspec/specs/`
+- `openspec/memory/`
+- `openspec/templates/`
+- `openspec/.thoth-agents.json`
 
-The operation is offline and idempotent. It never overwrites the project
-constitution, templates, or unrelated instruction content.
+Missing constitution and SDD template files are copied from the installed
+bundle. Existing constitution and template files remain byte-for-byte intact;
+the thoth-managed manifest may be normalized to the current contract. Inspect
+the JSON `created`, `managed`, and `preserved` arrays when reporting the result.
+
+This operation is offline, idempotent, and harness-neutral. Every write stays
+inside `openspec/`. It never installs or synchronizes skills, agents, plugins,
+harness configuration, external dependencies, or global instruction files;
+those are responsibilities of `npx thoth-agents install`.