relay-kit 0.2.0 → 0.3.1

package/dist/cli.js

@@ -1,75 +1,64 @@
 #!/usr/bin/env node
-
-// src/cli.ts
-import { Command } from "commander";
-
-// src/commands/ask.ts
-import path9 from "path";
-
-// src/core/clipboard.ts
-import { spawn } from "child_process";
-async function copyToClipboard(content) {
-  const command = process.platform === "win32" ? "clip" : process.platform === "darwin" ? "pbcopy" : "xclip";
-  const args = process.platform === "linux" ? ["-selection", "clipboard"] : [];
-  return new Promise((resolve) => {
-    const child = spawn(command, args, { stdio: ["pipe", "ignore", "ignore"], windowsHide: true });
-    child.on("error", () => resolve(false));
-    child.on("close", (code) => resolve(code === 0));
-    child.stdin.end(content);
-  });
-}
-
-// src/core/command-runner.ts
-import { exec } from "child_process";
-import { promisify as promisify2 } from "util";
-
-// src/core/git.ts
-import { execFile } from "child_process";
-import { promisify } from "util";
-
-// src/core/excludes.ts
-import path from "path";
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
 
 // src/core/constants.ts
-var RELAY_DIR = ".relay";
-var RELAYIGNORE_FILE = ".relayignore";
-var CONFIG_FILE = `${RELAY_DIR}/config.json`;
-var STATE_FILE = `${RELAY_DIR}/state.json`;
-var DEFAULT_HANDOFF_DIR = "docs/agent-handoffs";
-var DEFAULT_LANE = "main";
-var DEFAULT_MAX_DIFF_LINES = 500;
-var DEFAULT_MAX_LOG_LINES = 160;
-var AGENTS_START_MARKER = "<!-- relay-kit:start -->";
-var AGENTS_END_MARKER = "<!-- relay-kit:end -->";
-var DEFAULT_SKILLS = [
-  "relay-planner",
-  "relay-delegator",
-  "relay-escalation",
-  "relay-reviewer"
-];
-var EXCLUDED_NAMES = /* @__PURE__ */ new Set([
-  ".env",
-  ".git",
-  "node_modules",
-  "dist",
-  "build",
-  "coverage"
-]);
-var EXCLUDED_GLOBS = [
-  ".env",
-  ".env.*",
-  "node_modules/",
-  "dist/",
-  "build/",
-  "coverage/",
-  ".git/",
-  "*.pem",
-  "*.key",
-  "*.crt",
-  "*.p12",
-  "*.log"
-];
-var DEFAULT_RELAYIGNORE_CONTENT = `# relay-kit context ignore rules
+var RELAY_DIR, RELAYIGNORE_FILE, CONFIG_FILE, STATE_FILE, DEFAULT_HANDOFF_DIR, DEFAULT_LANE, DEFAULT_MAX_DIFF_LINES, DEFAULT_MAX_LOG_LINES, AGENTS_START_MARKER, AGENTS_END_MARKER, OPENSPEC_DIR, OPENSPEC_CHANGES_DIR, OPENSPEC_SPECS_DIR, OPENSPEC_ARCHIVE_DIR, OPENSPEC_CONFIG_FILE, OPENSPEC_DEFAULT_SCHEMA, DEFAULT_SKILLS, EXCLUDED_NAMES, EXCLUDED_GLOBS, DEFAULT_RELAYIGNORE_CONTENT;
+var init_constants = __esm({
+  "src/core/constants.ts"() {
+    "use strict";
+    RELAY_DIR = ".relay";
+    RELAYIGNORE_FILE = ".relayignore";
+    CONFIG_FILE = `${RELAY_DIR}/config.json`;
+    STATE_FILE = `${RELAY_DIR}/state.json`;
+    DEFAULT_HANDOFF_DIR = "docs/agent-handoffs";
+    DEFAULT_LANE = "main";
+    DEFAULT_MAX_DIFF_LINES = 500;
+    DEFAULT_MAX_LOG_LINES = 160;
+    AGENTS_START_MARKER = "<!-- relay-kit:start -->";
+    AGENTS_END_MARKER = "<!-- relay-kit:end -->";
+    OPENSPEC_DIR = "openspec";
+    OPENSPEC_CHANGES_DIR = `${OPENSPEC_DIR}/changes`;
+    OPENSPEC_SPECS_DIR = `${OPENSPEC_DIR}/specs`;
+    OPENSPEC_ARCHIVE_DIR = `${OPENSPEC_DIR}/changes/archive`;
+    OPENSPEC_CONFIG_FILE = ".openspec.yaml";
+    OPENSPEC_DEFAULT_SCHEMA = "spec-driven";
+    DEFAULT_SKILLS = [
+      "relay-planner",
+      "relay-delegator",
+      "relay-escalation",
+      "relay-reviewer"
+    ];
+    EXCLUDED_NAMES = /* @__PURE__ */ new Set([
+      ".env",
+      ".git",
+      "node_modules",
+      "dist",
+      "build",
+      "coverage"
+    ]);
+    EXCLUDED_GLOBS = [
+      ".env",
+      ".env.*",
+      "node_modules/",
+      "dist/",
+      "build/",
+      "coverage/",
+      ".git/",
+      "*.pem",
+      "*.key",
+      "*.crt",
+      "*.p12",
+      "*.log"
+    ];
+    DEFAULT_RELAYIGNORE_CONTENT = `# relay-kit context ignore rules
 .env
 .env.*
 node_modules/
@@ -83,8 +72,11 @@ coverage/
 *.p12
 *.log
 `;
+  }
+});
 
 // src/core/excludes.ts
+import path from "path";
 function normalizePath(value) {
   return value.replace(/\\/g, "/");
 }
@@ -114,8 +106,647 @@ function assertInsideRoot(root, target) {
   }
   throw new Error(`Refusing to write outside project root: ${target}`);
 }
+var init_excludes = __esm({
+  "src/core/excludes.ts"() {
+    "use strict";
+    init_constants();
+  }
+});
+
+// src/core/fs.ts
+import { constants as fsConstants } from "fs";
+import fs from "fs/promises";
+import path2 from "path";
+async function pathExists(filePath) {
+  try {
+    await fs.access(filePath, fsConstants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function ensureDir(dirPath) {
+  await fs.mkdir(dirPath, { recursive: true });
+}
+async function readTextIfExists(filePath) {
+  if (!await pathExists(filePath)) {
+    return "";
+  }
+  return fs.readFile(filePath, "utf8");
+}
+async function readJsonIfExists(filePath) {
+  if (!await pathExists(filePath)) {
+    return void 0;
+  }
+  return JSON.parse(stripBom(await fs.readFile(filePath, "utf8")));
+}
+async function writeJsonFile(filePath, value) {
+  await ensureDir(path2.dirname(filePath));
+  await fs.writeFile(filePath, `${JSON.stringify(value, null, 2)}
+`, "utf8");
+}
+async function safeWriteFile(root, relativePath, content, options = {}) {
+  const target = assertInsideRoot(root, relativePath);
+  await ensureDir(path2.dirname(target));
+  if (!options.force && await pathExists(target)) {
+    throw new Error(`Refusing to overwrite existing file without --force: ${relativePath}`);
+  }
+  await fs.writeFile(target, content, "utf8");
+  return target;
+}
+async function copyDirectory(source, target, options = {}) {
+  if (!await pathExists(source)) {
+    throw new Error(`Missing source directory: ${source}`);
+  }
+  await ensureDir(target);
+  const entries = await fs.readdir(source, { withFileTypes: true });
+  for (const entry of entries) {
+    const sourcePath = path2.join(source, entry.name);
+    const targetPath = path2.join(target, entry.name);
+    if (entry.isDirectory()) {
+      await copyDirectory(sourcePath, targetPath, options);
+      continue;
+    }
+    if (!entry.isFile()) {
+      continue;
+    }
+    if (!options.force && await pathExists(targetPath)) {
+      continue;
+    }
+    await fs.copyFile(sourcePath, targetPath);
+  }
+}
+function stripBom(value) {
+  return value.charCodeAt(0) === 65279 ? value.slice(1) : value;
+}
+var init_fs = __esm({
+  "src/core/fs.ts"() {
+    "use strict";
+    init_excludes();
+  }
+});
+
+// src/core/schema.ts
+function getSchema(name) {
+  return BUILTIN_SCHEMAS[name];
+}
+function getAvailableSchemas() {
+  return Object.values(BUILTIN_SCHEMAS);
+}
+function getArtifact(schema, artifactId) {
+  return schema.artifacts.find((a) => a.id === artifactId);
+}
+function getArtifactTemplate(templateFile) {
+  return ARTIFACT_TEMPLATES[templateFile] ?? `<!-- Template not found: ${templateFile} -->`;
+}
+function getApplyInstruction(schema) {
+  return schema.apply.instruction;
+}
+function getApplyRequires(schema) {
+  return schema.apply.requires;
+}
+function getDefaultSchema() {
+  return SPEC_DRIVEN_SCHEMA;
+}
+var SPEC_DRIVEN_SCHEMA, ARTIFACT_TEMPLATES, BUILTIN_SCHEMAS;
+var init_schema = __esm({
+  "src/core/schema.ts"() {
+    "use strict";
+    SPEC_DRIVEN_SCHEMA = {
+      name: "spec-driven",
+      version: 1,
+      description: "Default OpenSpec workflow - proposal \u2192 specs \u2192 design \u2192 tasks",
+      artifacts: [
+        {
+          id: "proposal",
+          generates: "proposal.md",
+          description: "Initial proposal document outlining the change",
+          template: "proposal.md",
+          instruction: `Create the proposal document that establishes WHY this change is needed.
+
+Sections:
+- **Why**: 1-2 sentences on the problem or opportunity. What problem does this solve? Why now?
+- **What Changes**: Bullet list of changes. Be specific about new capabilities, modifications, or removals. Mark breaking changes with **BREAKING**.
+- **Capabilities**: Identify which specs will be created or modified:
+  - **New Capabilities**: List capabilities being introduced. Each becomes a new specs/<name>/spec.md. Use kebab-case names (e.g., user-auth, data-export).
+  - **Modified Capabilities**: List existing capabilities whose REQUIREMENTS are changing. Only include if spec-level behavior changes (not just implementation details). Each needs a delta spec file. Check openspec/specs/ for existing spec names. Leave empty if no requirement changes.
+- **Impact**: Affected code, APIs, dependencies, or systems.
+
+IMPORTANT: The Capabilities section is critical. It creates the contract between
+proposal and specs phases. Research existing specs before filling this in.
+Each capability listed here will need a corresponding spec file.
+
+Keep it concise (1-2 pages). Focus on the "why" not the "how" -
+implementation details belong in design.md.
+
+This is the foundation - specs, design, and tasks all build on this.`,
+          requires: []
+        },
+        {
+          id: "specs",
+          generates: "specs/**/*.md",
+          description: "Detailed specifications for the change",
+          template: "spec.md",
+          instruction: `Create specification files that define WHAT the system should do.
+
+Create one spec file per capability listed in the proposal's Capabilities section.
+- New capabilities: use the exact kebab-case name from the proposal (specs/<capability>/spec.md).
+- Modified capabilities: use the existing spec folder name from openspec/specs/<capability>/ when creating the delta spec at specs/<capability>/spec.md.
+
+Delta operations (use ## headers):
+- **ADDED Requirements**: New capabilities
+- **MODIFIED Requirements**: Changed behavior - MUST include full updated content
+- **REMOVED Requirements**: Deprecated features - MUST include **Reason** and **Migration**
+- **RENAMED Requirements**: Name changes only - use FROM:/TO: format
+
+Format requirements:
+- Each requirement: ### Requirement: <name> followed by description
+- Use SHALL/MUST for normative requirements (avoid should/may)
+- Each scenario: #### Scenario: <name> with WHEN/THEN format
+- **CRITICAL**: Scenarios MUST use exactly 4 hashtags (####). Using 3 hashtags or bullets will fail silently.
+- Every requirement MUST have at least one scenario.
+
+MODIFIED requirements workflow:
+1. Locate the existing requirement in openspec/specs/<capability>/spec.md
+2. Copy the ENTIRE requirement block (from ### Requirement: through all scenarios)
+3. Paste under ## MODIFIED Requirements and edit to reflect new behavior
+4. Ensure header text matches exactly (whitespace-insensitive)
+
+Common pitfall: Using MODIFIED with partial content loses detail at archive time.
+If adding new concerns without changing existing behavior, use ADDED instead.`,
+          requires: ["proposal"]
+        },
+        {
+          id: "design",
+          generates: "design.md",
+          description: "Technical design document with implementation details",
+          template: "design.md",
+          instruction: `Create the design document that explains HOW to implement the change.
+
+When to include design.md (create only if any apply):
+- Cross-cutting change (multiple services/modules) or new architectural pattern
+- New external dependency or significant data model changes
+- Security, performance, or migration complexity
+- Ambiguity that benefits from technical decisions before coding
+
+Sections:
+- **Context**: Background, current state, constraints, stakeholders
+- **Goals / Non-Goals**: What this design achieves and explicitly excludes
+- **Decisions**: Key technical choices with rationale (why X over Y?). Include alternatives considered for each decision.
+- **Risks / Trade-offs**: Known limitations, things that could go wrong. Format: [Risk] \u2192 Mitigation
+- **Migration Plan**: Steps to deploy, rollback strategy (if applicable)
+- **Open Questions**: Outstanding decisions or unknowns to resolve
+
+Focus on architecture and approach, not line-by-line implementation.
+Reference the proposal for motivation and specs for requirements.
+
+Good design docs explain the "why" behind technical decisions.`,
+          requires: ["proposal"]
+        },
+        {
+          id: "tasks",
+          generates: "tasks.md",
+          description: "Implementation checklist with trackable tasks",
+          template: "tasks.md",
+          instruction: `Create the task list that breaks down the implementation work.
+
+**IMPORTANT: Follow the template below exactly.** The apply phase parses
+checkbox format to track progress. Tasks not using - [ ] won't be tracked.
+
+Guidelines:
+- Group related tasks under ## numbered headings
+- Each task MUST be a checkbox: - [ ] X.Y Task description
+- Tasks should be small enough to complete in one session
+- Order tasks by dependency (what must be done first?)
+
+Reference specs for what needs to be built, design for how to build it.
+Each task should be verifiable - you know when it's done.`,
+          requires: ["specs", "design"]
+        }
+      ],
+      apply: {
+        requires: ["tasks"],
+        tracks: "tasks.md",
+        instruction: "Read context files, work through pending tasks, mark complete as you go.\nPause if you hit blockers or need clarification."
+      }
+    };
+    ARTIFACT_TEMPLATES = {
+      "proposal.md": `## Why
+
+<!-- Explain the motivation for this change. What problem does this solve? Why now? -->
+
+## What Changes
+
+<!-- Describe what will change. Be specific about new capabilities, modifications, or removals. -->
+
+## Capabilities
+
+### New Capabilities
+<!-- Capabilities being introduced. Replace <name> with kebab-case identifier (e.g., user-auth, data-export, api-rate-limiting). Each creates specs/<name>/spec.md -->
+- \`<name>\`: <brief description of what this capability covers>
+
+### Modified Capabilities
+<!-- Existing capabilities whose REQUIREMENTS are changing (not just implementation).
+     Only list here if spec-level behavior changes. Each needs a delta spec file.
+     Use existing spec names from openspec/specs/. Leave empty if no requirement changes. -->
+- \`<existing-name>\`: <what requirement is changing>
+
+## Impact
+
+<!-- Affected code, APIs, dependencies, systems -->`,
+      "design.md": `## Context
+
+<!-- Background and current state -->
+
+## Goals / Non-Goals
+
+**Goals:**
+<!-- What this design aims to achieve -->
+
+**Non-Goals:**
+<!-- What is explicitly out of scope -->
+
+## Decisions
+
+<!-- Key design decisions and rationale -->
+
+## Risks / Trade-offs
+
+<!-- Known risks and trade-offs -->`,
+      "tasks.md": `## 1. <!-- Task Group Name -->
+
+- [ ] 1.1 <!-- Task description -->
+- [ ] 1.2 <!-- Task description -->
+
+## 2. <!-- Task Group Name -->
+
+- [ ] 2.1 <!-- Task description -->
+- [ ] 2.2 <!-- Task description -->`,
+      "spec.md": `## ADDED Requirements
+
+### Requirement: <!-- requirement name -->
+<!-- requirement text -->
+
+#### Scenario: <!-- scenario name -->
+- **WHEN** <!-- condition -->
+- **THEN** <!-- expected outcome -->`
+    };
+    BUILTIN_SCHEMAS = {
+      "spec-driven": SPEC_DRIVEN_SCHEMA
+    };
+  }
+});
+
+// src/core/openspec.ts
+var openspec_exports = {};
+__export(openspec_exports, {
+  archiveChange: () => archiveChange,
+  formatDate: () => formatDate,
+  formatOpenSpecContext: () => formatOpenSpecContext,
+  getApplyInstructions: () => getApplyInstructions,
+  getChangeStatus: () => getChangeStatus,
+  getInstructions: () => getInstructions,
+  initOpenSpecStructure: () => initOpenSpecStructure,
+  listOpenSpecChanges: () => listOpenSpecChanges,
+  listOpenSpecChangesDetailed: () => listOpenSpecChangesDetailed,
+  newChange: () => newChange,
+  readOpenSpecContext: () => readOpenSpecContext,
+  resolveOpenSpecChange: () => resolveOpenSpecChange
+});
+import fs2 from "fs/promises";
+import path5 from "path";
+function formatDate(date = /* @__PURE__ */ new Date()) {
+  return date.toISOString().slice(0, 10);
+}
+async function initOpenSpecStructure(root) {
+  await ensureDir(path5.join(root, OPENSPEC_DIR));
+  await ensureDir(path5.join(root, OPENSPEC_CHANGES_DIR));
+  await ensureDir(path5.join(root, OPENSPEC_SPECS_DIR));
+  await ensureDir(path5.join(root, OPENSPEC_ARCHIVE_DIR));
+  const gitkeepFiles = [OPENSPEC_CHANGES_DIR, OPENSPEC_SPECS_DIR, OPENSPEC_ARCHIVE_DIR];
+  for (const dir of gitkeepFiles) {
+    const gitkeep = path5.join(root, dir, ".gitkeep");
+    if (!await pathExists(gitkeep)) {
+      await fs2.writeFile(gitkeep, "", "utf8");
+    }
+  }
+}
+async function newChange(root, name, schema = OPENSPEC_DEFAULT_SCHEMA) {
+  if (!/^[a-z]/.test(name)) {
+    throw new Error("Change name must start with a letter.");
+  }
+  if (!/^[a-z0-9][-a-z0-9]*$/.test(name)) {
+    throw new Error("Change name must be kebab-case (lowercase letters, digits, hyphens).");
+  }
+  const changeDir = path5.join(root, OPENSPEC_CHANGES_DIR, name);
+  if (await pathExists(changeDir)) {
+    throw new Error(`Change already exists: ${name}`);
+  }
+  const schemaDef = getSchema(schema);
+  if (!schemaDef) {
+    throw new Error(`Unknown schema: ${schema}. Available: ${["spec-driven"].join(", ")}`);
+  }
+  await ensureDir(changeDir);
+  const config = {
+    schema,
+    created: formatDate()
+  };
+  await fs2.writeFile(
+    path5.join(changeDir, OPENSPEC_CONFIG_FILE),
+    `schema: ${config.schema}
+created: ${config.created}
+`,
+    "utf8"
+  );
+  return changeDir;
+}
+async function listOpenSpecChanges(root) {
+  const changesDir = path5.join(root, OPENSPEC_CHANGES_DIR);
+  if (!await pathExists(changesDir)) {
+    return [];
+  }
+  const entries = await fs2.readdir(changesDir, { withFileTypes: true });
+  return entries.filter((entry) => entry.isDirectory() && entry.name !== "archive").map((entry) => entry.name).sort();
+}
+async function listOpenSpecChangesDetailed(root) {
+  const names = await listOpenSpecChanges(root);
+  const entries = [];
+  for (const name of names) {
+    const config = await readChangeConfig(root, name);
+    entries.push({
+      name,
+      schema: config?.schema ?? OPENSPEC_DEFAULT_SCHEMA,
+      created: config?.created ?? ""
+    });
+  }
+  return entries;
+}
+async function resolveOpenSpecChange(root, requested) {
+  if (requested) {
+    const changeDir = path5.join(root, OPENSPEC_CHANGES_DIR, requested);
+    if (!await pathExists(changeDir)) {
+      throw new Error(`OpenSpec change not found: ${requested}`);
+    }
+    return requested;
+  }
+  const changes = await listOpenSpecChanges(root);
+  if (changes.length === 1) {
+    return changes[0];
+  }
+  if (changes.length === 0) {
+    throw new Error("No OpenSpec changes found.");
+  }
+  throw new Error(`Multiple OpenSpec changes found. Specify one with --change: ${changes.join(", ")}`);
+}
+async function readChangeConfig(root, change) {
+  const configPath = path5.join(root, OPENSPEC_CHANGES_DIR, change, OPENSPEC_CONFIG_FILE);
+  const content = await readTextIfExists(configPath);
+  if (!content) return null;
+  const schemaMatch = content.match(/^schema:\s*(.+)$/m);
+  const createdMatch = content.match(/^created:\s*(.+)$/m);
+  return {
+    schema: schemaMatch?.[1]?.trim() ?? OPENSPEC_DEFAULT_SCHEMA,
+    created: createdMatch?.[1]?.trim() ?? ""
+  };
+}
+async function getChangeStatus(root, change) {
+  const changeDir = path5.join(root, OPENSPEC_CHANGES_DIR, change);
+  if (!await pathExists(changeDir)) {
+    throw new Error(`Change not found: ${change}`);
+  }
+  const config = await readChangeConfig(root, change);
+  const schemaName = config?.schema ?? OPENSPEC_DEFAULT_SCHEMA;
+  const schemaDef = getSchema(schemaName);
+  if (!schemaDef) {
+    throw new Error(`Unknown schema: ${schemaName}`);
+  }
+  const applyRequires = getApplyRequires(schemaDef);
+  const artifacts = [];
+  for (const artifact of schemaDef.artifacts) {
+    const status = await computeArtifactStatus(root, change, artifact);
+    artifacts.push(status);
+  }
+  return {
+    changeName: change,
+    schemaName,
+    applyRequires,
+    artifacts
+  };
+}
+async function computeArtifactStatus(root, change, artifact) {
+  const changeDir = path5.join(root, OPENSPEC_CHANGES_DIR, change);
+  if (artifact.id === "specs") {
+    const specsDir = path5.join(changeDir, "specs");
+    if (!await pathExists(specsDir)) {
+      const depsOk = artifact.requires.length === 0;
+      return { id: artifact.id, status: depsOk ? "ready" : "blocked" };
+    }
+    const entries = await fs2.readdir(specsDir, { withFileTypes: true });
+    const hasFiles = entries.some(
+      (entry) => entry.isFile() && entry.name.endsWith(".md")
+    );
+    return { id: artifact.id, status: hasFiles ? "done" : "ready" };
+  }
+  const filePath = path5.join(changeDir, artifact.generates);
+  const fileExists = await pathExists(filePath);
+  if (fileExists) {
+    return { id: artifact.id, status: "done" };
+  }
+  const allDepsDone = await checkDepsDone(root, change, artifact.requires);
+  return { id: artifact.id, status: allDepsDone ? "ready" : "blocked" };
+}
+async function checkDepsDone(root, change, deps) {
+  if (deps.length === 0) return true;
+  const changeDir = path5.join(root, OPENSPEC_CHANGES_DIR, change);
+  const schemaDef = getDefaultSchema();
+  for (const depId of deps) {
+    const depArtifact = getArtifact(schemaDef, depId);
+    if (!depArtifact) continue;
+    if (depArtifact.id === "specs") {
+      const specsDir = path5.join(changeDir, "specs");
+      if (!await pathExists(specsDir)) return false;
+      const entries = await fs2.readdir(specsDir, { withFileTypes: true });
+      if (!entries.some((e) => e.isFile() && e.name.endsWith(".md"))) return false;
+      continue;
+    }
+    const depPath = path5.join(changeDir, depArtifact.generates);
+    if (!await pathExists(depPath)) return false;
+  }
+  return true;
+}
+async function getInstructions(root, change, artifactId) {
+  const config = await readChangeConfig(root, change);
+  const schemaName = config?.schema ?? OPENSPEC_DEFAULT_SCHEMA;
+  const schemaDef = getSchema(schemaName);
+  if (!schemaDef) {
+    throw new Error(`Unknown schema: ${schemaName}`);
+  }
+  const artifact = getArtifact(schemaDef, artifactId);
+  if (!artifact) {
+    throw new Error(`Unknown artifact: ${artifactId} in schema ${schemaName}`);
+  }
+  const template = getArtifactTemplate(artifact.template);
+  const changeDir = path5.join(root, OPENSPEC_CHANGES_DIR, change);
+  const outputPath = artifactId === "specs" ? path5.join(changeDir, "specs") : path5.join(changeDir, artifact.generates);
+  return {
+    artifactId,
+    context: `Project: ${root}. Change: ${change}. Schema: ${schemaName}.`,
+    rules: "Keep artifacts concise. Follow the template structure.",
+    template,
+    instruction: artifact.instruction,
+    outputPath,
+    dependencies: artifact.requires
+  };
+}
+async function getApplyInstructions(root, change) {
+  const config = await readChangeConfig(root, change);
+  const schemaName = config?.schema ?? OPENSPEC_DEFAULT_SCHEMA;
+  const schemaDef = getSchema(schemaName);
+  if (!schemaDef) {
+    throw new Error(`Unknown schema: ${schemaName}`);
+  }
+  const changeDir = path5.join(root, OPENSPEC_CHANGES_DIR, change);
+  const status = await getChangeStatus(root, change);
+  const applyReq = getApplyRequires(schemaDef);
+  const allRequiredDone = applyReq.every((id) => {
+    const artifact = status.artifacts.find((a) => a.id === id);
+    return artifact?.status === "done";
+  });
+  const contextFiles = {};
+  for (const artifact of schemaDef.artifacts) {
+    if (artifact.id === "specs") {
+      const specsDir = path5.join(changeDir, "specs");
+      if (await pathExists(specsDir)) {
+        const entries = await fs2.readdir(specsDir, { withFileTypes: true });
+        const mdFiles = entries.filter((e) => e.isFile() && e.name.endsWith(".md")).map((e) => path5.join(specsDir, e.name));
+        if (mdFiles.length > 0) {
+          contextFiles[artifact.id] = mdFiles;
+        }
+      }
+      continue;
+    }
+    const filePath = path5.join(changeDir, artifact.generates);
+    if (await pathExists(filePath)) {
+      contextFiles[artifact.id] = [filePath];
+    }
+  }
+  const tasks = await parseTasks(root, change);
+  let state = "ready";
+  if (!allRequiredDone) {
+    state = "blocked";
+  } else if (tasks.length > 0 && tasks.every((t) => t.completed)) {
+    state = "all_done";
+  }
+  return {
+    schemaName,
+    changeName: change,
+    state,
+    contextFiles,
+    total: tasks.length,
+    complete: tasks.filter((t) => t.completed).length,
+    remaining: tasks.filter((t) => !t.completed).length,
+    tasks,
+    instruction: getApplyInstruction(schemaDef)
+  };
+}
+async function parseTasks(root, change) {
+  const tasksPath = path5.join(root, OPENSPEC_CHANGES_DIR, change, "tasks.md");
+  const content = await readTextIfExists(tasksPath);
+  if (!content) return [];
+  const tasks = [];
+  const checkboxRe = /^-\s*\[(x|\s)\]\s+(\S+)\s+(.+)$/;
+  for (const line of content.split("\n")) {
+    const match = line.match(checkboxRe);
+    if (match) {
+      tasks.push({
+        index: match[2],
+        description: match[3].trim(),
+        completed: match[1].toLowerCase() === "x"
+      });
+    }
+  }
+  return tasks;
+}
+async function archiveChange(root, change) {
+  const changeDir = path5.join(root, OPENSPEC_CHANGES_DIR, change);
+  if (!await pathExists(changeDir)) {
+    throw new Error(`Change not found: ${change}`);
+  }
+  const dateStr = formatDate();
+  const archiveName = `${dateStr}-${change}`;
+  const archiveDir = path5.join(root, OPENSPEC_ARCHIVE_DIR, archiveName);
+  if (await pathExists(archiveDir)) {
+    throw new Error(`Archive already exists: ${archiveName}`);
+  }
+  await ensureDir(path5.join(root, OPENSPEC_ARCHIVE_DIR));
+  await fs2.rename(changeDir, archiveDir);
+  return archiveDir;
+}
+async function readOpenSpecContext(root, change) {
+  return {
+    change,
+    proposal: filterExcludedLines(
+      await readTextIfExists(path5.join(root, OPENSPEC_CHANGES_DIR, change, "proposal.md"))
+    ),
+    design: filterExcludedLines(
+      await readTextIfExists(path5.join(root, OPENSPEC_CHANGES_DIR, change, "design.md"))
+    ),
+    tasks: filterExcludedLines(
+      await readTextIfExists(path5.join(root, OPENSPEC_CHANGES_DIR, change, "tasks.md"))
+    )
+  };
+}
+function formatOpenSpecContext(context) {
+  if (!context) {
+    return "";
+  }
+  return [
+    `# OpenSpec Change: ${context.change}`,
+    "## proposal.md",
+    context.proposal || "(missing)",
+    "## design.md",
+    context.design || "(missing)",
+    "## tasks.md",
+    context.tasks || "(missing)"
+  ].join("\n\n");
+}
+var init_openspec = __esm({
+  "src/core/openspec.ts"() {
+    "use strict";
+    init_constants();
+    init_excludes();
+    init_fs();
+    init_schema();
+  }
+});
+
+// src/cli.ts
+import { Command } from "commander";
+
+// src/commands/ask.ts
+import path9 from "path";
+
+// src/core/clipboard.ts
+import { spawn } from "child_process";
+async function copyToClipboard(content) {
+  const command = process.platform === "win32" ? "clip" : process.platform === "darwin" ? "pbcopy" : "xclip";
+  const args = process.platform === "linux" ? ["-selection", "clipboard"] : [];
+  return new Promise((resolve) => {
+    const child = spawn(command, args, { stdio: ["pipe", "ignore", "ignore"], windowsHide: true });
+    child.on("error", () => resolve(false));
+    child.on("close", (code) => resolve(code === 0));
+    child.stdin.end(content);
+  });
+}
+
+// src/core/command-runner.ts
+import { exec } from "child_process";
+import { promisify as promisify2 } from "util";
 
 // src/core/git.ts
+init_excludes();
+import { execFile } from "child_process";
+import { promisify } from "util";
 var execFileAsync = promisify(execFile);
 async function git(root, args) {
   try {
@@ -244,76 +875,9 @@ function sanitizeCommandOutput(output2, options) {
 }
 
 // src/core/config.ts
+init_constants();
+init_fs();
 import path3 from "path";
-
-// src/core/fs.ts
-import { constants as fsConstants } from "fs";
-import fs from "fs/promises";
-import path2 from "path";
-async function pathExists(filePath) {
-  try {
-    await fs.access(filePath, fsConstants.F_OK);
-    return true;
-  } catch {
-    return false;
-  }
-}
-async function ensureDir(dirPath) {
-  await fs.mkdir(dirPath, { recursive: true });
-}
-async function readTextIfExists(filePath) {
-  if (!await pathExists(filePath)) {
-    return "";
-  }
-  return fs.readFile(filePath, "utf8");
-}
-async function readJsonIfExists(filePath) {
-  if (!await pathExists(filePath)) {
-    return void 0;
-  }
-  return JSON.parse(stripBom(await fs.readFile(filePath, "utf8")));
-}
-async function writeJsonFile(filePath, value) {
-  await ensureDir(path2.dirname(filePath));
-  await fs.writeFile(filePath, `${JSON.stringify(value, null, 2)}
-`, "utf8");
-}
-async function safeWriteFile(root, relativePath, content, options = {}) {
-  const target = assertInsideRoot(root, relativePath);
-  await ensureDir(path2.dirname(target));
-  if (!options.force && await pathExists(target)) {
-    throw new Error(`Refusing to overwrite existing file without --force: ${relativePath}`);
-  }
-  await fs.writeFile(target, content, "utf8");
-  return target;
-}
-async function copyDirectory(source, target, options = {}) {
-  if (!await pathExists(source)) {
-    throw new Error(`Missing source directory: ${source}`);
-  }
-  await ensureDir(target);
-  const entries = await fs.readdir(source, { withFileTypes: true });
-  for (const entry of entries) {
-    const sourcePath = path2.join(source, entry.name);
-    const targetPath = path2.join(target, entry.name);
-    if (entry.isDirectory()) {
-      await copyDirectory(sourcePath, targetPath, options);
-      continue;
-    }
-    if (!entry.isFile()) {
-      continue;
-    }
-    if (!options.force && await pathExists(targetPath)) {
-      continue;
-    }
-    await fs.copyFile(sourcePath, targetPath);
-  }
-}
-function stripBom(value) {
-  return value.charCodeAt(0) === 65279 ? value.slice(1) : value;
-}
-
-// src/core/config.ts
 function createDefaultConfig(project, mode) {
   return {
     projectName: project.name,
@@ -373,6 +937,8 @@ function normalizeConfig(config) {
 }
 
 // src/core/relayignore.ts
+init_constants();
+init_fs();
 import path4 from "path";
 async function loadRelayIgnoreMatcher(root, extraPatterns = []) {
   const relayIgnorePath = path4.join(root, RELAYIGNORE_FILE);
@@ -488,59 +1054,13 @@ async function createContextSafety(root, config) {
   };
 }
 
-// src/core/openspec.ts
-import fs2 from "fs/promises";
-import path5 from "path";
-async function listOpenSpecChanges(root) {
-  const changesDir = path5.join(root, "openspec", "changes");
-  if (!await pathExists(changesDir)) {
-    return [];
-  }
-  const entries = await fs2.readdir(changesDir, { withFileTypes: true });
-  return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
-}
-async function resolveOpenSpecChange(root, requested) {
-  if (requested) {
-    const changeDir = path5.join(root, "openspec", "changes", requested);
-    if (!await pathExists(changeDir)) {
-      throw new Error(`OpenSpec change not found: ${requested}`);
-    }
-    return requested;
-  }
-  const changes = await listOpenSpecChanges(root);
-  if (changes.length === 1) {
-    return changes[0];
-  }
-  if (changes.length === 0) {
-    throw new Error("No OpenSpec changes found.");
-  }
-  throw new Error(`Multiple OpenSpec changes found. Specify one with --change: ${changes.join(", ")}`);
-}
-async function readOpenSpecContext(root, change) {
-  const changeDir = path5.join(root, "openspec", "changes", change);
-  return {
-    change,
-    proposal: filterExcludedLines(await readTextIfExists(path5.join(changeDir, "proposal.md"))),
-    design: filterExcludedLines(await readTextIfExists(path5.join(changeDir, "design.md"))),
-    tasks: filterExcludedLines(await readTextIfExists(path5.join(changeDir, "tasks.md")))
-  };
-}
-function formatOpenSpecContext(context) {
-  if (!context) {
-    return "";
-  }
-  return [
-    `# OpenSpec Change: ${context.change}`,
-    "## proposal.md",
-    context.proposal || "(missing)",
-    "## design.md",
-    context.design || "(missing)",
-    "## tasks.md",
-    context.tasks || "(missing)"
-  ].join("\n\n");
-}
+// src/commands/ask.ts
+init_fs();
+init_openspec();
 
 // src/core/runs.ts
+init_constants();
+init_fs();
 import path7 from "path";
 
 // src/core/templates.ts
@@ -612,6 +1132,8 @@ async function createRunStructure(root, config, runId, lane = DEFAULT_LANE, opti
 }
 
 // src/core/state.ts
+init_constants();
+init_fs();
 import path8 from "path";
 function createDefaultState(mode) {
   return {
@@ -712,9 +1234,13 @@ async function maybeRunCommand(root, config, target) {
 }
 
 // src/commands/doctor.ts
+init_constants();
 import path11 from "path";
+init_fs();
+init_openspec();
 
 // src/core/project.ts
+init_fs();
 import fs4 from "fs/promises";
 import path10 from "path";
 async function readPackageScripts(root) {
@@ -800,10 +1326,15 @@ function formatPending(clear, fileName, fix) {
 }
 
 // src/commands/init.ts
+init_constants();
 import fs5 from "fs/promises";
 import path13 from "path";
+init_fs();
+init_openspec();
 
 // src/core/skills.ts
+init_constants();
+init_fs();
 import path12 from "path";
 async function installProjectSkills(root, config, options = {}) {
   const sourceRoot = path12.join(getPackageRoot(), "skills");
@@ -819,33 +1350,58 @@ async function installProjectSkills(root, config, options = {}) {
   }
   return targets;
 }
+async function installOpenspecFiles(root, options = {}) {
+  const pkgRoot = getPackageRoot();
+  const installed = [];
+  const specs = [
+    { source: path12.join(pkgRoot, ".opencode"), target: path12.join(root, ".opencode") },
+    { source: path12.join(pkgRoot, ".claude"), target: path12.join(root, ".claude") },
+    { source: path12.join(pkgRoot, ".codex"), target: path12.join(root, ".codex") }
+  ];
+  for (const spec of specs) {
+    if (!await pathExists(spec.source)) continue;
+    await copyDirectory(spec.source, spec.target, options);
+    installed.push(spec.target);
+  }
+  return installed;
+}
 
 // src/commands/init.ts
 function registerInitCommand(program2) {
-  program2.command("init").description("Initialize relay-kit in the current project.").option("--mode <mode>", "Initialization mode: simple or openspec.").option("--with-openspec", "Show OpenSpec setup guidance without silently creating openspec/.").option("--yes", "Accept non-destructive defaults.").option("--force", "Overwrite relay-kit managed files.").action(async (options) => {
+  program2.command("init").description("Initialize relay-kit in the current project.").option("--mode <mode>", "Initialization mode: simple or openspec.").option("--with-openspec", "Show OpenSpec setup guidance.").option("--openspec-sync <mode>", "How to handle existing openspec CLI: use_relay, use_external, skip.").option("--yes", "Accept non-destructive defaults.").option("--force", "Overwrite relay-kit managed files.").action(async (options) => {
     const result = await runInit(process.cwd(), options);
     console.log(result.summary);
   });
 }
 async function runInit(root, options = {}) {
   const project = await detectProject(root);
-  const mode = resolveMode(project.hasOpenSpec, options.mode);
-  if (options.mode === "openspec" && !project.hasOpenSpec) {
-    throw new Error("Cannot use --mode openspec because openspec/ was not detected.");
-  }
+  const mode = await resolveModeInteractive(project.hasOpenSpec, options);
   const config = createDefaultConfig(project, mode);
   const state = createDefaultState(mode);
   await ensureDir(path13.join(root, ".relay"));
   if (!options.force && (await pathExists(path13.join(root, CONFIG_FILE)) || await pathExists(path13.join(root, STATE_FILE)))) {
     throw new Error("relay-kit is already initialized. Use --force to rewrite managed config/state files.");
   }
+  const openspecInitNotes = [];
+  if (mode === "openspec") {
+    const isExisting = project.hasOpenSpec;
+    if (!isExisting) {
+      await initOpenSpecStructure(root);
+      openspecInitNotes.push(`Created ${OPENSPEC_DIR}/ structure (changes/, specs/, archive/).`);
+    } else {
+      openspecInitNotes.push(`Detected existing ${OPENSPEC_DIR}/ structure. Updating OpenSpec files.`);
+    }
+    await detectAndHandleExternalOpenspec(root, options, openspecInitNotes);
+    const openspecTargets = await installOpenspecFiles(root, { force: isExisting || options.force });
+    openspecInitNotes.push(`OpenSpec files installed to: ${openspecTargets.map((t) => path13.relative(root, t)).join(", ")}`);
+  }
   await writeConfig(root, config);
   await writeState(root, state);
   await ensureDir(path13.join(root, DEFAULT_HANDOFF_DIR, "runs"));
   const relayIgnoreStatus = await ensureRelayIgnore(root);
   await injectAgentsRules(root, options.force);
   const skillTargets = await installProjectSkills(root, config, { force: options.force });
-  const guidance = options.withOpenspec && !project.hasOpenSpec ? "\nOpenSpec was requested, but relay-kit did not create openspec/. Install/init OpenSpec explicitly, then rerun relay init --mode openspec --force." : "";
+  const guidance = options.withOpenspec && mode !== "openspec" ? "\nOpenSpec was requested but not selected. Run relay init --mode openspec to enable OpenSpec mode." : "";
   return {
     summary: [
       `relay init complete (${mode}).`,
@@ -853,10 +1409,113 @@ async function runInit(root, options = {}) {
       `State: ${STATE_FILE}`,
       `Relay ignore: ${relayIgnoreStatus}`,
       `Skills: ${skillTargets.map((target) => path13.relative(root, target)).join(", ")}`,
+      ...openspecInitNotes,
       guidance
     ].filter(Boolean).join("\n")
   };
 }
+async function resolveModeInteractive(hasOpenSpec, options) {
+  if (options.mode === "simple") return "simple";
+  if (options.mode === "openspec") return "openspec";
+  if (hasOpenSpec) return "openspec";
+  if (options.withOpenspec) return "simple";
+  if (options.yes) return "simple";
+  return promptModeSelection();
+}
+async function promptModeSelection() {
+  const readline = await import("readline");
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    return "openspec";
+  }
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  const question = (q) => new Promise((resolve) => rl.question(q, resolve));
+  console.log();
+  console.log("\u9009\u62E9\u521D\u59CB\u5316\u6A21\u5F0F\uFF1A");
+  console.log("  1. \u7B80\u5355\u6A21\u5F0F  \u2014 relay-kit \u72EC\u7ACB\u4F7F\u7528\uFF08\u4E0D\u542B OpenSpec\uFF09");
+  console.log("  2. OpenSpec \u6A21\u5F0F \u2014 \u96C6\u6210 OpenSpec\uFF0C\u89C4\u8303\u9A71\u52A8\u5F00\u53D1\uFF08\u63A8\u8350\uFF09");
+  let answer;
+  try {
+    answer = await question("\u8BF7\u9009\u62E9 (1/2, \u9ED8\u8BA4 2): ");
+  } finally {
+    rl.close();
+  }
+  const trimmed = answer.trim();
+  if (trimmed === "1" || trimmed.toLowerCase() === "simple") {
+    return "simple";
+  }
+  return "openspec";
+}
+async function detectAndHandleExternalOpenspec(root, options, notes) {
+  const externalCliPath = await findExternalOpenspecCli();
+  if (!externalCliPath) {
+    notes.push("\u672A\u68C0\u6D4B\u5230\u5916\u90E8 openspec CLI\u3002\u4F7F\u7528 relay-kit \u5185\u7F6E\u5B9E\u73B0\u3002");
+    return;
+  }
+  const syncMode = options.openspecSync ?? (options.yes ? "use_relay" : void 0);
+  if (syncMode) {
+    if (syncMode === "use_relay") {
+      notes.push("\u53D1\u73B0\u5916\u90E8 openspec CLI\uFF0C\u5DF2\u9009\u62E9\u4F7F\u7528 relay-kit \u5185\u7F6E\u5B9E\u73B0\u3002");
+    } else if (syncMode === "use_external") {
+      notes.push("\u4F7F\u7528\u5916\u90E8 openspec CLI\u3002\u53EF\u901A\u8FC7 relay init --openspec-sync use_relay \u5207\u6362\u3002");
+    }
+    return;
+  }
+  const readline = await import("readline");
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    notes.push("External openspec CLI detected. Using relay-kit built-in (non-TTY default).");
+    return;
+  }
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  const question = (q) => new Promise((resolve) => rl.question(q, resolve));
+  console.log();
+  console.log(`\u68C0\u6D4B\u5230\u5916\u90E8 openspec CLI: ${externalCliPath}`);
+  console.log("relay-kit \u73B0\u5DF2\u5185\u7F6E OpenSpec \u5B9E\u73B0\u3002");
+  console.log("  1. \u4F7F\u7528 relay-kit \u5185\u7F6E\uFF08\u63A8\u8350\uFF09\u2014 \u65E0\u9700\u5916\u90E8\u4F9D\u8D56");
+  console.log("  2. \u4F7F\u7528\u5916\u90E8 openspec CLI \u2014 \u4FDD\u6301\u73B0\u6709\u8BBE\u7F6E");
+  console.log("  3. \u8DF3\u8FC7 \u2014 \u4E0D\u8BBE\u7F6E OpenSpec");
+  let answer;
+  try {
+    answer = await question("\u8BF7\u9009\u62E9 (1/2/3, \u9ED8\u8BA4 1): ");
+  } finally {
+    rl.close();
+  }
+  const trimmed = answer.trim();
+  if (trimmed === "2" || trimmed.toLowerCase() === "external") {
+    notes.push("Using external openspec CLI. Run relay init --openspec-sync use_relay to switch.");
+    return;
+  }
+  if (trimmed === "3" || trimmed.toLowerCase() === "skip") {
+    notes.push("OpenSpec CLI handling skipped.");
+    return;
+  }
+  notes.push("Using relay-kit built-in OpenSpec implementation.");
+}
+async function findExternalOpenspecCli() {
+  const whichCmd = process.platform === "win32" ? "where.exe" : "which";
+  try {
+    const { execFile: execFile2 } = await import("child_process");
+    const { stdout } = await new Promise((resolve, reject) => {
+      execFile2(whichCmd, ["openspec"], { timeout: 5e3 }, (error, stdout2) => {
+        if (error) reject(error);
+        else resolve({ stdout: stdout2 });
+      });
+    });
+    const first = stdout.split("\n")[0]?.trim();
+    if (!first) return null;
+    if (first.includes("node_modules\\relay-kit") || first.includes("node_modules/relay-kit")) {
+      return null;
+    }
+    return first;
+  } catch {
+    return null;
+  }
+}
 async function ensureRelayIgnore(root) {
   if (await pathExists(path13.join(root, RELAYIGNORE_FILE))) {
     return `${RELAYIGNORE_FILE} (kept existing)`;
@@ -864,12 +1523,6 @@ async function ensureRelayIgnore(root) {
   await safeWriteFile(root, RELAYIGNORE_FILE, DEFAULT_RELAYIGNORE_CONTENT);
   return RELAYIGNORE_FILE;
 }
-function resolveMode(hasOpenSpec, requested) {
-  if (requested && requested !== "simple" && requested !== "openspec") {
-    throw new Error("--mode must be simple or openspec.");
-  }
-  return requested ?? (hasOpenSpec ? "openspec" : "simple");
-}
 async function injectAgentsRules(root, force = false) {
   const agentsPath = path13.join(root, "AGENTS.md");
   const existing = await readTextIfExists(agentsPath);
@@ -894,8 +1547,116 @@ function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
+// src/commands/openspec.ts
+init_openspec();
+init_schema();
+function registerOpenspecCommand(program2) {
+  const openspecCmd = program2.command("openspec").description("Manage OpenSpec changes (built-in).").action(() => {
+    console.log("Usage: relay openspec <action> [options]\n");
+    console.log("Actions:");
+    console.log("  new-change <name>   Create a new OpenSpec change");
+    console.log("  status              Show artifact completion status");
+    console.log("  list                List active changes");
+    console.log("  instructions <id>   Get artifact creation instructions");
+    console.log("  apply-instructions  Get apply instructions for a change");
+    console.log("  archive <name>      Archive a completed change");
+    console.log("  schemas             List available schemas");
+  });
+  openspecCmd.command("new-change <name>").description("Create a new OpenSpec change.").option("--schema <schema>", "Schema name (default: spec-driven).").action(async (name, options) => {
+    const result = await newChange(process.cwd(), name, options.schema);
+    console.log(`Created change: ${name}
+Schema: ${options.schema ?? "spec-driven"}
+Path: ${result}`);
+  });
+  openspecCmd.command("status").description("Display artifact completion status for a change.").option("--change <change>", "Change name.").option("--json", "Output as JSON.").action(async (options) => {
+    const change = options.change ?? await resolveCurrentChange();
+    const status = await getChangeStatus(process.cwd(), change);
+    if (options.json) {
+      console.log(JSON.stringify(status, null, 2));
+      return;
+    }
+    console.log(`Change: ${change}`);
+    console.log(`Schema: ${status.schemaName}`);
+    console.log(`Apply Requires: ${status.applyRequires.join(", ")}`);
+    console.log();
+    for (const artifact of status.artifacts) {
+      console.log(`  ${artifact.id}: ${artifact.status}`);
+    }
+  });
+  openspecCmd.command("list").description("List active OpenSpec changes.").option("--json", "Output as JSON.").action(async (options) => {
+    const entries = await listOpenSpecChangesDetailed(process.cwd());
+    if (options.json) {
+      console.log(JSON.stringify(entries, null, 2));
+      return;
+    }
+    if (entries.length === 0) {
+      console.log("No active changes.");
+      return;
+    }
+    for (const entry of entries) {
+      console.log(`  ${entry.name}  (schema: ${entry.schema}, created: ${entry.created})`);
+    }
+  });
+  openspecCmd.command("instructions <artifactId>").description("Output enriched instructions for creating an artifact.").option("--change <change>", "Change name.").option("--json", "Output as JSON.").action(async (artifactId, options) => {
+    const change = options.change ?? await resolveCurrentChange();
+    const instructions = await getInstructions(process.cwd(), change, artifactId);
+    if (options.json) {
+      console.log(JSON.stringify(instructions, null, 2));
+      return;
+    }
+    console.log(`Artifact: ${instructions.artifactId}`);
+    console.log(`Output: ${instructions.outputPath}`);
+    console.log(`Dependencies: ${instructions.dependencies.join(", ") || "(none)"}`);
+    console.log();
+    console.log("## Instruction");
+    console.log(instructions.instruction);
+    console.log();
+    console.log("## Template");
+    console.log(instructions.template);
+  });
+  openspecCmd.command("apply-instructions").description("Output apply instructions for a change.").option("--change <change>", "Change name.").option("--json", "Output as JSON.").action(async (options) => {
+    const change = options.change ?? await resolveCurrentChange();
+    const instructions = await getApplyInstructions(process.cwd(), change);
+    if (options.json) {
+      console.log(JSON.stringify(instructions, null, 2));
+      return;
+    }
+    console.log(`Change: ${instructions.changeName}`);
+    console.log(`Schema: ${instructions.schemaName}`);
+    console.log(`State: ${instructions.state}`);
+    console.log(`Progress: ${instructions.complete}/${instructions.total} tasks complete`);
+    console.log();
+    console.log("## Instruction");
+    console.log(instructions.instruction);
+    if (instructions.tasks.length > 0) {
+      console.log();
+      console.log("## Tasks");
+      for (const task of instructions.tasks) {
+        console.log(`  - [${task.completed ? "x" : " "}] ${task.index} ${task.description}`);
+      }
+    }
+  });
+  openspecCmd.command("archive <name>").description("Archive a completed change.").action(async (name, _options) => {
+    const archiveDir = await archiveChange(process.cwd(), name);
+    console.log(`Archived change "${name}" to ${archiveDir}`);
+  });
+  openspecCmd.command("schemas").description("List available workflow schemas.").action(() => {
+    const schemas = getAvailableSchemas();
+    for (const schema of schemas) {
+      console.log(`${schema.name}: ${schema.description}`);
+      console.log(`  Artifacts: ${schema.artifacts.map((a) => a.id).join(", ")}`);
+      console.log();
+    }
+  });
+}
+async function resolveCurrentChange() {
+  const { resolveOpenSpecChange: resolveOpenSpecChange2 } = await Promise.resolve().then(() => (init_openspec(), openspec_exports));
+  return resolveOpenSpecChange2(process.cwd());
+}
+
 // src/commands/resume.ts
 import path14 from "path";
+init_fs();
 function registerResumeCommand(program2) {
   program2.command("resume").description("Create a resume prompt from a relay decision.").option("--from <path>", "Read Advisor decision from a specific file.").option("--copy", "Copy generated content to clipboard.").option("--force", "Overwrite RESUME_PROMPT.md.").action(async (options) => {
     const result = await runResume(process.cwd(), options);
@@ -942,6 +1703,8 @@ function extractPromptForExecutor(decision) {
 
 // src/commands/review.ts
 import path15 from "path";
+init_fs();
+init_openspec();
 function registerReviewCommand(program2) {
   program2.command("review").description("Create a relay review request for the current implementation.").option("--copy", "Copy generated content to clipboard.").option("--force", "Overwrite REVIEW_REQUEST.md.").action(async (options) => {
     const result = await runReview(process.cwd(), options);
@@ -986,9 +1749,12 @@ ${task}` : "", openSpecText].filter(Boolean).join("\n")
 }
 
 // src/commands/start.ts
+init_constants();
 import path16 from "path";
 import { createInterface } from "readline/promises";
 import { stdin as input, stdout as output } from "process";
+init_fs();
+init_openspec();
 function registerStartCommand(program2) {
   program2.command("start").description("Start a relay handoff run and create an executor task.").option("--title <title>", "Simple mode task title.").option("--scope <scope>", "Allowed implementation scope.").option("--blocked-scope <scope>", "Scope that must not be changed.").option("--change <change>", "OpenSpec change name.").option("--copy", "Copy generated handoff content to clipboard.").option("--force", "Overwrite generated run files.").action(async (options) => {
     const result = await runStart(process.cwd(), options);
@@ -1048,7 +1814,12 @@ async function collectSimpleInputs(options) {
   }
 }
 
+// src/commands/sync.ts
+import path18 from "path";
+
 // src/core/skills-sync.ts
+init_constants();
+init_fs();
 import crypto from "crypto";
 import fs6 from "fs/promises";
 import os from "os";
@@ -1290,28 +2061,41 @@ function pathLabel(value) {
 
 // src/commands/sync.ts
 function registerSyncCommand(program2) {
-  program2.command("sync").description("Synchronize relay-kit managed resources.").option("--skills", "Synchronize relay Skills from .relay/skills.").option("--target <target>", "Skill target: claude, codex, or all.").option("--scope <scope>", "Skill sync scope: project or user.", "project").option("--dry-run", "Preview the sync plan without writing files.").option("--force", "Overwrite conflicted skill files.").action(async (options) => {
+  program2.command("sync").description("Synchronize relay-kit managed resources.").option("--skills", "Synchronize relay Skills from .relay/skills.").option("--openspec", "Synchronize OpenSpec command/skill files.").option("--all", "Synchronize everything (skills + OpenSpec files).").option("--target <target>", "Skill target: claude, codex, or all.").option("--scope <scope>", "Skill sync scope: project or user.", "project").option("--dry-run", "Preview the sync plan without writing files.").option("--force", "Overwrite conflicted skill files.").action(async (options) => {
     const result = await runSync(process.cwd(), options);
     console.log(result.summary);
   });
 }
 async function runSync(root, options = {}) {
-  if (!options.skills) {
-    throw new Error("relay sync currently supports only --skills.");
-  }
-  validateTarget(options.target);
-  validateScope(options.scope);
-  const config = await loadConfig(root);
-  try {
-    const report = await syncSkills(root, config, options);
-    return { summary: formatSkillSyncReport(report) };
-  } catch (error) {
-    if (error instanceof SkillSyncConflictError) {
-      throw new Error(`${formatSkillSyncReport(error.report)}
+  const runSkills = options.all || options.skills;
+  const runOpenspec = options.all || options.openspec;
+  if (!runSkills && !runOpenspec) {
+    throw new Error("Specify --skills, --openspec, or --all.");
+  }
+  const lines = [];
+  if (runSkills) {
+    validateTarget(options.target);
+    validateScope(options.scope);
+    const config = await loadConfig(root);
+    try {
+      const report = await syncSkills(root, config, options);
+      lines.push(formatSkillSyncReport(report));
+    } catch (error) {
+      if (error instanceof SkillSyncConflictError) {
+        throw new Error(`${formatSkillSyncReport(error.report)}
 ${error.message}`);
+      }
+      throw error;
+    }
+  }
+  if (runOpenspec) {
+    const installed = await installOpenspecFiles(root, { force: options.force });
+    lines.push(`relay sync --openspec: installed ${installed.length} directories.`);
+    for (const dir of installed) {
+      lines.push(`  ${path18.relative(root, dir)}`);
     }
-    throw error;
   }
+  return { summary: lines.join("\n") };
 }
 function validateTarget(target) {
   if (target === void 0 || target === "claude" || target === "codex" || target === "all") {
@@ -1330,6 +2114,7 @@ function validateScope(scope) {
 var program = new Command();
 program.name("relay").description("Skills-first, CLI-assisted AI programming relay workflow toolkit.").version("0.2.0");
 registerInitCommand(program);
+registerOpenspecCommand(program);
 registerStartCommand(program);
 registerAskCommand(program);
 registerResumeCommand(program);