thoth-agents 0.3.2 → 0.3.4

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "thoth-agents",
       "description": "Adaptive root orchestration, six specialist subagents, and a runtime-autonomous Spec Kit-compatible SDD bundle.",
-      "version": "0.3.2",
+      "version": "0.3.4",
       "author": {
         "name": "thoth-agents maintainers"
       },

package/README.md

@@ -23,7 +23,10 @@ parallelism creates a net gain.
 The plugin ships the seven-role contract and thoth-owned SDD
 contracts that combine Spec Kit-grade traceability with OpenSpec-style durable
 deltas. Accelerated planning fast-forwards without routine pauses; structural
-`ready`/`closeout` gates and independent oracle review retain rigor. During
+`ready`/`closeout` gates and independent oracle review retain rigor. Root
+recommends Direct, Accelerated, or Full and the user selects the route. After
+`ready`, artifact-backed routes offer optional Oracle plan review or proceeding
+without it; every final verification remains mandatory. During
 installation, the CLI obtains four mandatory external skills
 from their canonical repositories with `npx skills add` and invokes the official
 provider-owned thoth-mem setup for the selected harness. During an SDD, agents
@@ -58,32 +61,28 @@ Restart OpenCode and initialize the current repository:
 /thoth-init
 ```
 
-This copies the four thoth-owned workflow skills into `.agents/skills/` and
+This copies the five thoth-owned workflow skills into `.agents/skills/` and
 creates missing `openspec/` governance files. The external skills are already in
-OpenCode's global skill root and thoth-mem has completed its own provider setup
-from the CLI step. Existing project-owned files are preserved.
+one of the OpenCode global discovery roots managed here,
+`~/.config/opencode/skills/` or `~/.agents/skills/`, and thoth-mem has completed
+its own provider setup from the CLI step. Existing project-owned files are
+preserved.
 
 ### Codex
 
-Register the repository marketplace from a terminal:
-
-```bash
-codex plugin marketplace add EremesNG/thoth-agents
-```
-
-Restart Codex, open `/plugins`, and install or enable `thoth-agents`. Then return
-to a terminal and apply the mandatory global layer:
+Preview, then run the combined native-plugin and global-layer installer:
 
 ```bash
 npx thoth-agents@latest install --agent=codex --dry-run
 npx thoth-agents@latest install --agent=codex
 ```
 
-The CLI writes the orchestrator block to `~/.codex/AGENTS.md`, creates six
-custom-agent TOMLs under `~/.codex/agents/`, and merges the managed feature into
-`~/.codex/config.toml`. It also installs the external skills and invokes
-provider-owned thoth-mem setup. Restart Codex again, then initialize each target
-repository's SDD governance:
+The CLI first uses Codex's native manager to register `EremesNG/thoth-agents`
+and install or enable `thoth-agents@thoth-agents`. It then writes the
+orchestrator block to `~/.codex/AGENTS.md`, creates six custom-agent TOMLs under
+`~/.codex/agents/`, merges the managed feature into `~/.codex/config.toml`,
+installs the external skills, and invokes provider-owned thoth-mem setup.
+Restart Codex, then initialize each target repository's SDD governance:
 
 ```text
 $thoth-init
@@ -119,7 +118,7 @@ Restart Claude Code or run `/reload-plugins`, then initialize the repository:
 /thoth-agents:thoth-init
 ```
 
-Claude discovers the packaged orchestrator, six namespaced subagents, and four
+Claude discovers the packaged orchestrator, six namespaced subagents, and five
 thoth-owned skills from the plugin. The CLI installs the external skills into
 Claude's global skill root and requires thoth-mem's own setup result to be
 complete. Init creates only the missing project governance files; it never edits
@@ -147,8 +146,8 @@ correctness-critical work.
       <br>
       <i>Adaptive root and final synthesis.</i>
       <br><br>
-      Keeps task ownership and synthesis, chooses the route, coordinates SDD
-      artifacts, and implements bounded work directly.
+      Keeps task ownership and synthesis, recommends a route for the user's
+      selection, coordinates SDD artifacts, and implements bounded work directly.
       <br><br>
       <b>Mode:</b> <code>adaptive-root</code>
     </td>
@@ -201,7 +200,7 @@ correctness-critical work.
       <br>
       <i>Independent analysis and verification.</i>
       <br><br>
-      Challenges plans, owns Full analysis, and independently verifies every
+      Reviews plans when the user requests it and independently verifies every
       implementation.
       <br><br>
       <b>Mode:</b> <code>read-only</code>
@@ -273,29 +272,33 @@ Accelerated work.
 ```text
 Direct:      implement -> verify
 Accelerated: specify -> plan -> tasks -> implement -> verify -> archive
-Full:        explore -> specify -> plan -> tasks -> analyze -> implement -> verify -> archive
+Full:        explore -> specify -> plan -> tasks -> implement -> verify -> archive
 ```
 
 | Route | Use when | Artifacts |
 | --- | --- | --- |
 | Direct | Clear, bounded, low-risk work, including multi-file documentation/mechanical edits | None; oracle returns its verdict in-session. |
 | Accelerated | Generic SDD request, partial clarity, moderate risk, multi-surface behavior, or architecture | Canonical artifacts with fast-forward specification/planning/tasks. |
-| Full | Material uncertainty, cross-cutting behavior/architecture, high contract risk, or high failure cost | Accelerated artifacts plus exploration and independent pre-implementation analysis. |
+| Full | Material uncertainty, cross-cutting behavior/architecture, high contract risk, or high failure cost | Accelerated artifacts plus exploration and separate planning gates. |
 
 The root loads only the current phase contract from the bundled `thoth-sdd`
 skill. It owns specification, clarification, planning, requirements checklists,
 task decomposition, convergence, report persistence, and archive. `explorer`
-owns Full discovery; `oracle` always owns `analyze` and `verify`.
+owns Full discovery; `oracle` owns user-selected plan review and every `verify`.
 
-An explicitly named route wins. A generic request to use SDD sets Accelerated as
-the minimum. Accelerated writes `spec.md -> plan.md -> tasks.md` in one
-uninterrupted root pass and does not pause for routine approval between phases.
+An explicitly named route is the user's selection and wins. Otherwise root
+recommends one of all three routes and waits for the user's choice. A generic
+request to use SDD sets Accelerated as the minimum recommendation. Accelerated
+writes `spec.md -> plan.md -> tasks.md` in one uninterrupted root pass and does
+not pause for routine approval between those planning phases.
 
 Conditional phases remain deliberately narrow:
 
 - `clarify` runs only for a material ambiguity and updates canonical `spec.md`;
 - `checklist` audits high-risk requirement quality with `CHK###` taxonomy and a
   separate revalidation pass;
+- `plan-review` is offered after `ready` on Accelerated and Full; the user chooses
+  `Review plan with Oracle (Recommended)` or `Proceed without review`;
 - `converge` appends tasks only after failed artifact-backed verification; and
 - `architectural-grilling` runs before specification only when explicitly
   requested or a material human-owned decision remains unresolved.
@@ -320,6 +323,7 @@ Every harness package includes the workflow contracts owned by thoth-agents:
 | `thoth-sdd` | Route rules, phase contracts, templates, and structural validator. |
 | `thoth-constitution` | Explicit governance SemVer lifecycle; routine plans only read principles. |
 | `thoth-archive` | Passing closeout, transactional durable-spec sync, audit report, and dated move. |
+| `plan-reviewer` | Optional read-only Oracle plan review with exact `[OKAY]`/`[REJECT]` results and freshness evidence. |
 
 The installer obtains these mandatory external skills from their single source
 of truth:
@@ -345,7 +349,7 @@ diagnostics, manual actions, and receipt paths remain visible for recovery.
 | Harness | Important limitation |
 | --- | --- |
 | OpenCode | Strongest integrated path. The CLI installs the npm plugin configuration, external skills, and provider-owned thoth-mem setup; `/thoth-init` materializes thoth-owned project skills/governance. Only the OpenAI built-in preset ships. |
-| Codex | Native plugin installation is incomplete without the CLI. The CLI manages global `AGENTS.md`, six agent TOMLs, config, external skills, and thoth-mem setup; `$thoth-init` only initializes per-repository SDD governance. Runtime role matching and some permissions remain instruction-level. |
+| Codex | The CLI installs the native plugin and manages global `AGENTS.md`, six agent TOMLs, config, external skills, and thoth-mem setup; `$thoth-init` only initializes per-repository SDD governance. Runtime role matching and some permissions remain instruction-level. |
 | Claude Code | Run both native marketplace commands before the CLI installs external skills and requests thoth-mem setup. The native manager owns cache files; fine-grained path restrictions remain instruction-level. |
 
 Codex and Claude marketplace manifests are versioned in
@@ -385,7 +389,8 @@ npx thoth-agents@latest install --agent=claude
 npx thoth-agents@latest model --harness=codex --role=deep --model=gpt-5.6-sol
 ```
 
-It does not replace native marketplace trust or mutate manager-owned caches.
+It does not bypass native marketplace trust or edit manager-owned caches
+directly; Codex and Claude own their native manager mutations.
 
 ## Documentation
 

package/dist/{chunk-YUCGIJPP.js → chunk-6GQYMWWT.js}

@@ -14,7 +14,7 @@ import {
   getStepBudgetPromptSection,
   loadAgentPrompt,
   renderRolePrompt
-} from "./chunk-XO74DXBZ.js";
+} from "./chunk-F2K4CS5J.js";
 
 // src/agents/deep.ts
 var DEEP_PROMPT = renderRolePrompt(

package/dist/{chunk-XO74DXBZ.js → chunk-F2K4CS5J.js}

@@ -797,7 +797,7 @@ var AGENT_ROLES = [
       "keeps requirements, decisions, and final synthesis in the root thread"
     ],
     verification: [
-      "delegates analyze and every verify phase to oracle, including Direct and Accelerated routes",
+      "delegates selected plan-review and every verify phase to oracle; plan review stays optional and final verification stays mandatory",
       "consolidates summarized evidence returned by child agents"
     ]
   },
@@ -832,8 +832,8 @@ var AGENT_ROLES = [
     mode: "read-only",
     dispatch: "synchronous-task-only",
     canMutateWorkspace: false,
-    scope: "diagnosis, architecture, analysis, and independent verification",
-    responsibility: "Independently analyze plans and perform every implementation verification, exposing correctness risks and judging whether results satisfy their contracts.",
+    scope: "diagnosis, architecture, optional plan review, and independent verification",
+    responsibility: "Independently review plans when the user requests it and perform every implementation verification, exposing correctness risks and judging whether results satisfy their contracts.",
     toolGovernance: [
       "performs read-only analysis and independent review and is never the implementer of the work it judges",
       "does not implement, persist artifacts, or delegate further"
@@ -1017,16 +1017,17 @@ var SDD_PHASES = [
     reason: "Produce dependency-ordered implementation slices with verification."
   },
   {
-    id: "analyze",
+    id: "plan-review",
     order: 6,
-    availableFor: ["full"],
-    requiredFor: ["full"],
-    activation: "required",
-    prerequisites: ["specify", "plan", "tasks"],
-    producesArtifact: false,
+    availableFor: ["accelerated", "full"],
+    requiredFor: [],
+    activation: "conditional",
+    prerequisites: ["tasks"],
+    producesArtifact: true,
     defaultAgentRole: "oracle",
     eligibleAgentRoles: ["oracle"],
-    reason: "Independently check cross-artifact consistency before high-risk implementation."
+    reason: "Offer independent blocker-only plan review when the user selects it after planning passes ready.",
+    condition: "Activate only after ready when the user chooses Review plan with Oracle (Recommended)."
   },
   {
     id: "implement",
@@ -1034,7 +1035,7 @@ var SDD_PHASES = [
     availableFor: ["direct", "accelerated", "full"],
     requiredFor: ["direct", "accelerated", "full"],
     activation: "required",
-    prerequisites: ["tasks", "analyze"],
+    prerequisites: ["tasks"],
     producesArtifact: false,
     defaultAgentRole: "orchestrator",
     eligibleAgentRoles: ["orchestrator", "designer", "quick", "deep"],
@@ -1135,6 +1136,13 @@ var SDD_ARTIFACT_GRAPH = [
     consumes: ["spec", "plan"],
     requiredFor: []
   },
+  {
+    id: "plan-review",
+    path: "plan-review.md",
+    producedBy: "plan-review",
+    consumes: ["spec", "plan", "tasks"],
+    requiredFor: []
+  },
   {
     id: "verify-report",
     path: "verify-report.md",
@@ -1164,7 +1172,7 @@ var SDD_ROUTE_EXECUTION_POLICIES = [
     planningMode: "fast-forward",
     validationGates: ["specify", "ready", "closeout"],
     optionalArtifactsByDefault: false,
-    routineUserPauses: false,
+    routineUserPauses: true,
     artifactRevisionPolicy: "revalidate-affected-downstream"
   },
   {
@@ -1172,7 +1180,7 @@ var SDD_ROUTE_EXECUTION_POLICIES = [
     planningMode: "gated",
     validationGates: ["specify", "plan", "tasks", "ready", "closeout"],
     optionalArtifactsByDefault: false,
-    routineUserPauses: false,
+    routineUserPauses: true,
     artifactRevisionPolicy: "revalidate-affected-downstream"
   }
 ];
@@ -1184,25 +1192,25 @@ var SDD_WORKFLOW_CONTRACT = {
     validationGates: [...policy.validationGates]
   })),
   routingRules: [
-    "An explicitly requested direct, accelerated, or full route wins; a generic SDD request sets accelerated as the minimum route.",
+    "The root recommends direct, accelerated, or full from risk evidence, but the user selects the route; an explicitly requested route already counts as selection.",
     "Direct work is the default for clear, bounded, low-risk changes; documentation and mechanical work may remain direct across multiple files.",
     "Accelerated SDD is used for multi-surface behavior, architecture, partial clarity, moderate risk, or broad non-behavioral coordination.",
-    "Accelerated planning fast-forwards specify, plan, and tasks in one uninterrupted root pass without routine user pauses.",
+    "Accelerated planning fast-forwards specify, plan, and tasks without pauses between those artifacts, then offers the user optional oracle plan review after ready.",
     "Full SDD is used for unresolved scope, cross-cutting behavior or architecture, high contract risk, or high failure cost.",
     "Use architectural-grilling before specification only when the user explicitly requests it or material product or architecture decisions remain human-owned and unresolved; never require it merely because the route is Full.",
-    "User input is requested only when a material unresolved decision would change the result."
+    "Route selection and the post-ready plan-review choice are explicit user decisions; other input is requested only when a material unresolved decision changes the result."
   ],
   artifactRules: [
     "Spec Kit artifact semantics are preserved inside the governed openspec store.",
     "Accelerated and full routes require spec.md, plan.md, tasks.md, verify-report.md, and archive-report.md.",
-    "Research, data model, contracts, quickstart, and requirements checklist are created only when useful.",
+    "Research, data model, contracts, quickstart, requirements checklist, and plan-review.md are optional and created only when useful or selected.",
     "The adaptive root writes coordination artifacts after loading the matching bundled phase contract; implementation ownership stays with the root or one writer role.",
     "After oracle PASS, archive transactionally synchronizes only explicitly declared durable ADDED, MODIFIED, REMOVED, and RENAMED requirement deltas into openspec/specs; INTERNAL requirements and undeclared prose never update permanent specifications.",
     "Archive stages and backs up writes so handled failures roll back within the active process; forced process or operating-system termination is not crash-atomic."
   ],
   verificationRules: [
     "Every route delegates focused verification to read-only oracle; the implementation writer never verifies its own work.",
-    "Full SDD delegates independent cross-artifact analysis to oracle before implementation.",
+    "Accelerated and Full offer read-only oracle plan review after ready; it runs only when the user selects it and never replaces final verification.",
     "Accelerated and full verification persists verify-report.md with a pass or fail verdict and requirement compliance matrix.",
     "An artifact-backed fail verdict routes through append-only convergence, implementation, and verification again; direct work returns straight to implementation.",
     "A pass verdict is required before accelerated or full work can archive."
@@ -1383,7 +1391,7 @@ ${renderRoleDirectory()}
 </routing>
 
 <sdd-routing>
-- An explicitly requested route wins; a generic SDD request sets Accelerated as the minimum unless Full risk applies.
+- An explicitly requested route wins: no duplicate route-selection prompt. Otherwise assess and recommend one route, ask with \`{{userQuestionTool}}\`, and wait for the user to select Direct, Accelerated, or Full. The recommendation is not the decision. The user's selected route wins; explain risk without overriding it. A generic SDD request sets Accelerated as the minimum unless Full risk applies.
 - Direct: clear, bounded, low-risk work. ${renderSddRoute("direct")}.
 - Documentation or mechanical work may remain Direct across multiple files when it is clear and low risk.
 - Accelerated SDD: multi-surface behavior, architecture, partial clarity, or moderate risk. ${renderSddRoute("accelerated")}.
@@ -1391,12 +1399,13 @@ ${renderRoleDirectory()}
 - Its thoth-sdd validator gates are ${accelerated.validationGates.join(" -> ")}; optional artifacts are off by default.
 - Full SDD: uncertain scope, cross-cutting behavior or architecture, high contract risk, or high failure cost. ${renderSddRoute("full")}.
 - Full gates are ${full.validationGates.join(" -> ")}; checklist remains conditional.
+- After \`ready\` on Accelerated/Full, ask with \`{{userQuestionTool}}\`: \`Review plan with Oracle (Recommended)\` or \`Proceed without review\`. Skipping plan review means no pre-implementation Oracle review. If selected, load \`plan-reviewer\`, delegate read-only review, and accept only \`[OKAY]\` or \`[REJECT]\` with at most 3 actionable blockers. After \`[OKAY]\`, summarize and ask whether to implement or stop. Plan review never replaces mandatory final Oracle verify.
 - Happy path: verify -> archive. Artifact-backed failure loop: verify fail -> converge -> implement -> verify. Direct failure loop: verify fail -> implement -> verify.
-- Conditional phases: clarify only for material ambiguity; checklist only when requirement risk justifies it; converge only when verification finds actionable defects.
+- Conditional phases: clarify for material ambiguity; checklist for requirement risk; plan-review by user choice; converge for verification defects.
 - When implementation discoveries refine the same intent, update the canonical artifact and revalidate only affected downstream artifacts. Split a new change when the intent changes.
 - Load the bundled \`thoth-sdd\` skill only after selecting Accelerated or Full, then read only the reference for the current phase.
 - Root owns specify, clarify, plan, checklist, tasks, converge, and archive coordination; these phases are not delegated merely to change prompts.
-- Delegate analyze and every verify phase to ${roleTemplate("oracle")}, including Direct and Accelerated work. The implementation writer must never review itself.
+- Delegate each user-selected plan review and every verify phase to ${roleTemplate("oracle")}. The implementation writer must never review itself.
 </sdd-routing>
 
 <external-skills>
@@ -1425,7 +1434,7 @@ ${renderRoleDirectory()}
 
 <execution>
 - Validate contracts and tests first; use test-first work for behavior. Root or one writer implements; do not delegate merely because an agent exists.
-- ${roleTemplate("oracle")} always provides independent verification and also owns Full SDD analysis. Root and implementation writers never self-approve.
+- ${roleTemplate("oracle")} owns selected plan review and every verification; root and writers never self-approve.
 - Preserve unrelated working-tree changes. Never instruct an agent to discard them.
 - Report changed files, evidence, risks, and capability gaps truthfully.
 </execution>
@@ -1452,7 +1461,7 @@ var ROLE_SPECIFIC_RULES = {
   oracle: [
     "Separate observations, risks, and recommendations.",
     "Review against stated requirements and contracts; do not invent implementation scope.",
-    "For analyze or verify, load the matching bundled thoth-sdd reference and remain read-only.",
+    "For plan-review, load the bundled plan-reviewer skill; for verify, load the matching bundled thoth-sdd reference and remain read-only.",
     "Reject self-review: the implementing root or writer cannot substitute for independent oracle judgment."
   ],
   designer: [

package/dist/{chunk-NUSODNWE.js → chunk-W5GCMYA3.js}

@@ -31,7 +31,7 @@ import {
   updateOpenCodeMainConfig,
   writeConfig,
   writeLiteConfig
-} from "./chunk-XO74DXBZ.js";
+} from "./chunk-F2K4CS5J.js";
 
 // src/cli/codex-paths.ts
 import { homedir } from "os";
@@ -1411,11 +1411,11 @@ function buildCodexManagedConfigPatch(content, options) {
   ];
   if (options.pluginId) {
     diffSummary.push(
-      `plugin enablement for "${options.pluginId}" is not textually merged; use /plugins to enable it`
+      `plugin enablement for "${options.pluginId}" is not textually merged; use the native Codex plugin manager`
     );
   } else {
     diffSummary.push(
-      "plugin enablement left to /plugins; no guessed plugin id written"
+      "plugin installation and enablement owned by the native Codex plugin manager; no plugin table written"
     );
   }
   return {
@@ -1843,8 +1843,8 @@ function buildCodexSetupPlan(config) {
     configPath: targets.configPath,
     pluginId: config.pluginId,
     diagnostics: [
-      "Register the published marketplace with `codex plugin marketplace add EremesNG/thoth-agents`, restart Codex, then open /plugins to install and enable thoth-agents.",
-      "The CLI does not copy a plugin into ~/.codex/plugins or merge ~/.agents/plugins/marketplace.json; Codex owns marketplace snapshots and installed plugin cache state.",
+      "The combined install flow runs `codex plugin marketplace add EremesNG/thoth-agents` and `codex plugin add thoth-agents@thoth-agents` through the native manager; restart Codex, then use /plugins to review its state.",
+      "The CLI does not copy a plugin into ~/.codex/plugins or merge ~/.agents/plugins/marketplace.json directly; Codex owns marketplace snapshots and installed plugin cache state.",
       "The /hooks surface may show hooks from independently installed plugins; this thoth-agents setup plan does not install provider hooks.",
       "Codex Default mode user-input requests require features.default_mode_request_user_input = true and use the request_user_input tool; other modes may not expose it.",
       "Higher-precedence Codex config (project, profile, CLI, system, or admin) may override user config feature flags.",
@@ -2496,10 +2496,13 @@ var SKILLS_CLI_AGENT = {
   codex: "codex",
   claude: "claude-code"
 };
-var GLOBAL_SKILL_ROOT = {
-  opencode: [".config", "opencode", "skills"],
-  codex: [".codex", "skills"],
-  claude: [".claude", "skills"]
+var GLOBAL_SKILL_ROOTS = {
+  opencode: [
+    [".config", "opencode", "skills"],
+    [".agents", "skills"]
+  ],
+  codex: [[".agents", "skills"]],
+  claude: [[".claude", "skills"]]
 };
 var REQUIRED_SKILLS = [
   {
@@ -2527,16 +2530,22 @@ var REQUIRED_SKILLS = [
     description: "Conditional product and architecture decision interview"
   }
 ];
-function getRequiredSkillPath(skill, harness, homeDir = homedir2()) {
-  return join3(
-    homeDir,
-    ...GLOBAL_SKILL_ROOT[harness],
-    skill.skillName,
-    "SKILL.md"
+function getRequiredSkillPaths(skill, harness, homeDir = homedir2()) {
+  return GLOBAL_SKILL_ROOTS[harness].map(
+    (root) => join3(homeDir, ...root, skill.skillName, "SKILL.md")
   );
 }
-function isRequiredSkillInstalled(skill, harness, options = {}) {
-  return existsSync6(getRequiredSkillPath(skill, harness, options.homeDir));
+function getRequiredSkillPath(skill, harness, homeDir = homedir2()) {
+  const [primaryPath] = getRequiredSkillPaths(skill, harness, homeDir);
+  if (!primaryPath) {
+    throw new Error(`No global skill root is configured for ${harness}.`);
+  }
+  return primaryPath;
+}
+function getInstalledRequiredSkillPath(skill, harness, homeDir = homedir2()) {
+  return getRequiredSkillPaths(skill, harness, homeDir).find(
+    (path) => existsSync6(path)
+  );
 }
 function getRequiredSkillInstallCommand(skill, harness, options = {}) {
   return getNpxCommand(
@@ -2557,8 +2566,18 @@ function getRequiredSkillInstallCommand(skill, harness, options = {}) {
 }
 function installRequiredSkill(skill, harness, options = {}) {
   const skillPath = getRequiredSkillPath(skill, harness, options.homeDir);
-  if (isRequiredSkillInstalled(skill, harness, options)) {
-    return { skill, harness, status: "already-installed", skillPath };
+  const installedPath = getInstalledRequiredSkillPath(
+    skill,
+    harness,
+    options.homeDir
+  );
+  if (installedPath) {
+    return {
+      skill,
+      harness,
+      status: "already-installed",
+      skillPath: installedPath
+    };
   }
   const { command, args } = getRequiredSkillInstallCommand(
     skill,
@@ -2568,10 +2587,25 @@ function installRequiredSkill(skill, harness, options = {}) {
   try {
     const result = spawnSync2(command, args, { stdio: "inherit" });
     if (result.status === 0) {
-      return { skill, harness, status: "installed", skillPath };
+      return {
+        skill,
+        harness,
+        status: "installed",
+        skillPath: getInstalledRequiredSkillPath(skill, harness, options.homeDir) ?? skillPath
+      };
     }
-    if (isRequiredSkillInstalled(skill, harness, options)) {
-      return { skill, harness, status: "already-installed", skillPath };
+    const recoveredPath = getInstalledRequiredSkillPath(
+      skill,
+      harness,
+      options.homeDir
+    );
+    if (recoveredPath) {
+      return {
+        skill,
+        harness,
+        status: "already-installed",
+        skillPath: recoveredPath
+      };
     }
     return { skill, harness, status: "failed", skillPath, error: result.error };
   } catch (error) {
@@ -4015,8 +4049,13 @@ function homeDirFromContext(context2) {
 function openCodeSkillTargets(context2) {
   const homeDir = homeDirFromContext(context2);
   const requiredTargets = REQUIRED_SKILLS.map((skill) => {
-    const path = getRequiredSkillPath(skill, "opencode", homeDir);
-    const installed = existsSync9(path);
+    const installedPath = getInstalledRequiredSkillPath(
+      skill,
+      "opencode",
+      homeDir
+    );
+    const path = installedPath ?? getRequiredSkillPath(skill, "opencode", homeDir);
+    const installed = installedPath !== void 0;
     return {
       kind: "skill",
       path,

package/dist/cli/codex-plugin-install.d.ts

@@ -0,0 +1,51 @@
+export type CodexPluginSetupAction = 'register-marketplace' | 'install-plugin';
+export interface CodexCommandResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+export interface CodexCommandOptions {
+    cwd: string;
+}
+export interface CodexCommandInvocationOptions {
+    platform?: NodeJS.Platform;
+    commandShell?: string;
+}
+export interface CodexCommandInvocation {
+    command: string;
+    args: string[];
+}
+export type CodexCommandExecutor = (command: string, args: readonly string[], options: CodexCommandOptions) => CodexCommandResult;
+export interface CodexPluginInstallConfig {
+    dryRun?: boolean;
+    projectRoot: string;
+    commandExecutor?: CodexCommandExecutor;
+}
+export interface CodexPluginSetupPlanItem {
+    action: CodexPluginSetupAction;
+    targetPath: string;
+    description: string;
+    command: {
+        executable: 'codex';
+        args: string[];
+        cwd: string;
+    };
+}
+export interface CodexPluginSetupPlan {
+    dryRun: boolean;
+    items: CodexPluginSetupPlanItem[];
+    diagnostics: string[];
+    ready: boolean;
+    projectRoot: string;
+    commandExecutor: CodexCommandExecutor;
+}
+export interface CodexPluginApplyResult {
+    success: boolean;
+    changed: string[];
+    diagnostics: string[];
+    error?: string;
+}
+export declare function getCodexCommand(args: readonly string[], options?: CodexCommandInvocationOptions): CodexCommandInvocation;
+export declare function buildCodexPluginSetupPlan(config: CodexPluginInstallConfig): CodexPluginSetupPlan;
+export declare function applyCodexPluginSetup(plan: CodexPluginSetupPlan): CodexPluginApplyResult;
+export declare function formatCodexPluginSetupPlan(plan: CodexPluginSetupPlan): string;