cdspec 0.1.0

package/src/skill-core/scaffold.ts

@@ -0,0 +1,192 @@
+import { mkdtemp, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseFrontmatter } from "../utils/frontmatter.js";
+import { ensureDir, listDirs, pathExists } from "../utils/fs.js";
+import { SkillManifest } from "./types.js";
+
+const DEFAULT_SKILL_NAME = "openspec-core";
+const BUILTIN_TEMPLATE_DIR = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "../../templates/default-skill"
+);
+
+export async function cleanupLegacyDefaultSkillDir(cwd: string): Promise<void> {
+  await rm(path.join(cwd, ".codex", DEFAULT_SKILL_NAME), { recursive: true, force: true });
+  await rm(path.join(cwd, ".cdspec", "seed-skills"), { recursive: true, force: true });
+}
+
+export async function loadDefaultSkillManifest(cwd: string): Promise<SkillManifest> {
+  const projectTemplateManifests = await loadProjectTemplateManifests(cwd);
+  if (projectTemplateManifests.length > 0) return projectTemplateManifests[0];
+
+  if (await pathExists(path.join(BUILTIN_TEMPLATE_DIR, "SKILL.md"))) {
+    return buildManifestFromDir(BUILTIN_TEMPLATE_DIR);
+  }
+  const tempDir = await buildFallbackTemplateInTemp();
+  return buildManifestFromDir(tempDir);
+}
+
+export async function loadProjectTemplateManifests(cwd: string): Promise<SkillManifest[]> {
+  return loadFromProjectTemplates(path.join(cwd, "templates"));
+}
+
+async function buildManifestFromDir(skillDir: string): Promise<SkillManifest> {
+  const raw = await readFile(path.join(skillDir, "SKILL.md"), "utf8");
+  const parsed = parseFrontmatter(raw);
+  const name = parsed.attributes.name?.trim() || DEFAULT_SKILL_NAME;
+  const description = parsed.attributes.description?.trim() || "OpenSpec default skill";
+  const agents = await collectRelativeFiles(path.join(skillDir, "agents"));
+  const references = await collectRelativeFiles(path.join(skillDir, "references"));
+  const scripts = await collectRelativeFiles(path.join(skillDir, "scripts"));
+  const assets = await collectRelativeFiles(path.join(skillDir, "assets"));
+  return {
+    name,
+    description,
+    body: parsed.body.trim(),
+    agents,
+    resources: [...references, ...scripts, ...assets],
+    sourcePath: skillDir
+  };
+}
+
+async function collectRelativeFiles(dirPath: string): Promise<string[]> {
+  if (!(await pathExists(dirPath))) return [];
+  const base = path.dirname(dirPath);
+  const result: string[] = [];
+  const dirs = [dirPath];
+  while (dirs.length > 0) {
+    const current = dirs.pop()!;
+    const children = await listDirs(current);
+    for (const child of children) {
+      dirs.push(path.join(current, child));
+    }
+    const entries = await readdir(current, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isFile()) continue;
+      const fullPath = path.join(current, entry.name);
+      result.push(path.relative(base, fullPath).replaceAll("\\", "/"));
+    }
+  }
+  return result;
+}
+
+async function buildFallbackTemplateInTemp(): Promise<string> {
+  const root = await mkdtemp(path.join(os.tmpdir(), "cdspec-skill-"));
+  await ensureDir(path.join(root, "agents"));
+  await ensureDir(path.join(root, "references"));
+  const skillMd = [
+    "---",
+    "name: openspec-core",
+    "description: OpenSpec-style change workflow skill. Use for proposing, exploring, applying, and archiving spec-driven changes.",
+    "---",
+    "",
+    "# OpenSpec Core Skill",
+    "",
+    "1. /opsx-propose",
+    "2. /opsx-explore",
+    "3. /opsx-apply",
+    "4. /opsx-archive"
+  ].join("\n");
+  const openaiYaml = [
+    "interface:",
+    '  display_name: "OpenSpec Core"',
+    '  short_description: "Spec-driven change workflow with propose/explore/apply/archive"',
+    '  default_prompt: "Use $openspec-core to run OpenSpec-style workflows in this repository."'
+  ].join("\n");
+  await writeFile(path.join(root, "SKILL.md"), `${skillMd}\n`, "utf8");
+  await writeFile(path.join(root, "agents", "openai.yaml"), `${openaiYaml}\n`, "utf8");
+  await writeFile(path.join(root, "references", "project_notes.md"), "# OpenSpec Workflow Notes\n");
+  return root;
+}
+
+async function loadFromProjectTemplates(templateRoot: string): Promise<SkillManifest[]> {
+  if (!(await pathExists(templateRoot))) return [];
+  const manifests: SkillManifest[] = [];
+
+  const childDirs = await listDirs(templateRoot);
+  for (const child of childDirs) {
+    const full = path.join(templateRoot, child);
+    if (await pathExists(path.join(full, "SKILL.md"))) {
+      manifests.push(await buildManifestFromDir(full));
+    }
+  }
+
+  if (manifests.length > 0) return manifests;
+
+  const markdownFiles = await collectMarkdownFiles(templateRoot);
+  for (const selected of markdownFiles.sort()) {
+    manifests.push(await buildManifestFromMarkdown(templateRoot, selected));
+  }
+  return manifests;
+}
+
+async function buildManifestFromMarkdown(
+  templateRoot: string,
+  selected: string
+): Promise<SkillManifest> {
+  const raw = await readFile(selected, "utf8");
+  const parsed = parseFrontmatter(raw);
+  const baseName = path.basename(selected, path.extname(selected));
+  const skillName = normalizeSkillName(parsed.attributes.name || baseName);
+  const description =
+    parsed.attributes.description ||
+    `Generated from templates/${path.relative(templateRoot, selected).replaceAll("\\", "/")}`;
+  const body = parsed.body.trim() || raw.trim();
+
+  const tmp = await mkdtemp(path.join(os.tmpdir(), "cdspec-template-"));
+  await ensureDir(path.join(tmp, "agents"));
+  await ensureDir(path.join(tmp, "references"));
+  const skillMd = ["---", `name: ${skillName}`, `description: ${description}`, "---", "", body].join(
+    "\n"
+  );
+  const openaiYaml = [
+    "interface:",
+    `  display_name: "${humanizeName(skillName)}"`,
+    `  short_description: "${escapeYaml(description)}"`,
+    `  default_prompt: "Use $${skillName} to follow this template skill."`
+  ].join("\n");
+  await writeFile(path.join(tmp, "SKILL.md"), `${skillMd}\n`, "utf8");
+  await writeFile(path.join(tmp, "agents", "openai.yaml"), `${openaiYaml}\n`, "utf8");
+  await writeFile(path.join(tmp, "references", path.basename(selected)), raw, "utf8");
+  return buildManifestFromDir(tmp);
+}
+
+async function collectMarkdownFiles(root: string): Promise<string[]> {
+  const files: string[] = [];
+  const queue = [root];
+  while (queue.length > 0) {
+    const current = queue.pop()!;
+    const dirs = await listDirs(current);
+    for (const dir of dirs) {
+      queue.push(path.join(current, dir));
+    }
+    const entries = await readdir(current, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isFile() && entry.name.toLowerCase().endsWith(".md")) {
+        files.push(path.join(current, entry.name));
+      }
+    }
+  }
+  return files;
+}
+
+function normalizeSkillName(input: string): string {
+  return input
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "") || DEFAULT_SKILL_NAME;
+}
+
+function humanizeName(input: string): string {
+  return input
+    .split("-")
+    .filter(Boolean)
+    .map((part) => part[0].toUpperCase() + part.slice(1))
+    .join(" ");
+}
+
+function escapeYaml(value: string): string {
+  return value.replace(/"/g, '\\"');
+}

package/src/skill-core/service.ts

@@ -0,0 +1,199 @@
+import path from "node:path";
+import { rm } from "node:fs/promises";
+import { loadConfig } from "../config/loader.js";
+import { resolveAgentRoot } from "../config/path.js";
+import { CDSpecConfig } from "../config/types.js";
+import { loadAllSkillManifests, loadSkillManifestByName } from "./manifest-loader.js";
+import { expandTargets, getAdapter } from "./adapters/index.js";
+import {
+  installToolInteractionTemplates,
+  writeSharedAgentsStub
+} from "./tool-interactions.js";
+import {
+  cleanupLegacyDefaultSkillDir,
+  loadDefaultSkillManifest,
+  loadProjectTemplateManifests
+} from "./scaffold.js";
+import { SkillManifest } from "./types.js";
+import { validateManifest } from "./validator.js";
+
+export async function listSkills(cwd: string): Promise<string[]> {
+  const manifests = await loadAllSkillManifests(cwd);
+  return manifests.map((manifest) => manifest.name).sort();
+}
+
+export async function addSkill(
+  cwd: string,
+  name: string,
+  targetRaw: string,
+  force: boolean
+): Promise<void> {
+  const config = await loadConfig(cwd);
+  let manifest = await loadSkillManifestByName(cwd, name);
+  if (!manifest) {
+    const all = await loadAllSkillManifests(cwd);
+    manifest = all.find((item) => item.name === name) ?? null;
+  }
+  if (!manifest) {
+    throw new Error(`Skill "${name}" not found under .codex/.`);
+  }
+  const diagnostics = [...validateManifest(manifest)];
+  const targets = expandTargets(targetRaw);
+  for (const target of targets) {
+    diagnostics.push(...getAdapter(target).validate(manifest));
+  }
+  failIfErrors(diagnostics);
+
+  for (const target of targets) {
+    const adapter = getAdapter(target);
+    const outDir = path.join(resolveAgentRoot(cwd, config.agents[target].rootDir), "skills", manifest.name);
+    await adapter.emit(manifest, outDir, force);
+  }
+}
+
+export async function syncSkills(
+  cwd: string,
+  targetRaw: string,
+  force: boolean
+): Promise<void> {
+  const config = await loadConfig(cwd);
+  const manifests = await loadAllSkillManifests(cwd);
+  if (manifests.length === 0) {
+    throw new Error("No skills found under .codex/.");
+  }
+  const targets = expandTargets(targetRaw);
+
+  for (const manifest of manifests) {
+    const diagnostics = [...validateManifest(manifest)];
+    for (const target of targets) {
+      diagnostics.push(...getAdapter(target).validate(manifest));
+    }
+    failIfErrors(diagnostics);
+  }
+
+  for (const manifest of manifests) {
+    for (const target of targets) {
+      const outDir = path.join(resolveAgentRoot(cwd, config.agents[target].rootDir), "skills", manifest.name);
+      await getAdapter(target).emit(manifest, outDir, force);
+    }
+  }
+}
+
+export async function initSkills(
+  cwd: string,
+  agentsRaw: string,
+  force: boolean
+): Promise<string[]> {
+  await cleanupLegacyDefaultSkillDir(cwd);
+  const baseConfig = await loadConfig(cwd);
+  const projectTemplateManifests = await loadProjectTemplateManifests(cwd);
+  let manifests = projectTemplateManifests.length > 0
+    ? projectTemplateManifests
+    : await loadAllSkillManifests(cwd);
+  if (manifests.length === 0) manifests = [await loadDefaultSkillManifest(cwd)];
+  const config = buildInitConfig(baseConfig, manifests);
+  const targets = expandTargets(agentsRaw);
+  if (force) {
+    for (const target of targets) {
+      const root = resolveAgentRoot(cwd, config.agents[target].rootDir);
+      await rm(path.join(root, "skills"), {
+        recursive: true,
+        force: true
+      });
+      await rm(path.join(root, config.agents[target].commandsDir), {
+        recursive: true,
+        force: true
+      });
+      const guide = config.agents[target].guideAtProjectRoot
+        ? path.join(cwd, config.agents[target].guideFile)
+        : path.join(root, config.agents[target].guideFile);
+      await rm(guide, { force: true });
+    }
+  }
+  for (const manifest of manifests) {
+    const diagnostics = [...validateManifest(manifest)];
+    for (const target of targets) {
+      diagnostics.push(...getAdapter(target).validate(manifest));
+    }
+    failIfErrors(diagnostics);
+  }
+
+  for (const manifest of manifests) {
+    for (const target of targets) {
+      const outDir = path.join(resolveAgentRoot(cwd, config.agents[target].rootDir), "skills", manifest.name);
+      await getAdapter(target).emit(manifest, outDir, force);
+    }
+  }
+
+  const files: string[] = [];
+  for (const target of targets) {
+    files.push(...(await installToolInteractionTemplates(cwd, target, manifests, config)));
+  }
+  files.push(await writeSharedAgentsStub(cwd, targets, manifests, config));
+  return files;
+}
+
+function buildInitConfig(
+  config: CDSpecConfig,
+  manifests: SkillManifest[]
+): CDSpecConfig {
+  const available = new Set(manifests.map((item) => item.name));
+  const skillDrivenBindings = buildSkillDrivenBindings(manifests);
+  return {
+    ...config,
+    commandBindings:
+      skillDrivenBindings.length > 0
+        ? skillDrivenBindings
+        : config.commandBindings.map((item) =>
+            available.has(item.skill) ? item : { ...item, skill: manifests[0]?.name || item.skill }
+          ),
+    agents: {
+      codex: { ...config.agents.codex, commandFilePattern: "{id}.md", slashPattern: "/{id}" },
+      claudecode: {
+        ...config.agents.claudecode,
+        commandFilePattern: "{id}.md",
+        slashPattern: "/{id}"
+      },
+      iflow: { ...config.agents.iflow, commandFilePattern: "{id}.md", slashPattern: "/{id}" }
+    }
+  };
+}
+
+function buildSkillDrivenBindings(manifests: SkillManifest[]) {
+  const used = new Set<string>();
+  return manifests.map((manifest) => {
+    const base = commandIdForSkillName(manifest.name);
+    let id = base;
+    let i = 2;
+    while (used.has(id)) {
+      id = `${base}${i}`;
+      i += 1;
+    }
+    used.add(id);
+    return {
+      id,
+      skill: manifest.name,
+      description: `Run skill ${manifest.name}`
+    };
+  });
+}
+
+function commandIdForSkillName(skillName: string): string {
+  const normalizedName = skillName
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return `cd-${normalizedName || "skill"}`;
+}
+
+function failIfErrors(
+  diagnostics: Array<{ level: "error" | "warning"; message: string }>
+): void {
+  const warnings = diagnostics.filter((item) => item.level === "warning");
+  warnings.forEach((warning) => console.warn(`[warn] ${warning.message}`));
+
+  const errors = diagnostics.filter((item) => item.level === "error");
+  if (errors.length > 0) {
+    throw new Error(errors.map((error) => error.message).join("\n"));
+  }
+}

package/src/skill-core/tool-interactions.ts

@@ -0,0 +1,95 @@
+import { writeFile } from "node:fs/promises";
+import path from "node:path";
+import { resolveAgentRoot } from "../config/path.js";
+import { CDSpecConfig } from "../config/types.js";
+import { ensureDir } from "../utils/fs.js";
+import { SkillManifest, Target } from "./types.js";
+
+export async function installToolInteractionTemplates(
+  cwd: string,
+  target: Target,
+  skills: SkillManifest[],
+  config: CDSpecConfig
+): Promise<string[]> {
+  const agent = config.agents[target];
+  const root = resolveAgentRoot(cwd, agent.rootDir);
+  const commandsDir = path.join(root, agent.commandsDir);
+  await ensureDir(commandsDir);
+  const created: string[] = [];
+
+  for (const binding of config.commandBindings) {
+    const fileName = agent.commandFilePattern.replace("{id}", binding.id);
+    const file = path.join(commandsDir, fileName);
+    await writeFile(file, renderCommandTemplate(target, binding.id, binding.skill, binding.description), "utf8");
+    created.push(file);
+  }
+
+  const guidePath = agent.guideAtProjectRoot
+    ? path.join(cwd, agent.guideFile)
+    : path.join(root, agent.guideFile);
+  await writeFile(guidePath, renderGuide(target, skills, config), "utf8");
+  created.push(guidePath);
+  return created;
+}
+
+export async function writeSharedAgentsStub(
+  cwd: string,
+  targets: Target[],
+  skills: SkillManifest[],
+  config: CDSpecConfig
+): Promise<string> {
+  const file = path.join(cwd, "AGENTS.md");
+  const lines = [
+    "# AGENTS instructions",
+    "",
+    "<INSTRUCTIONS>",
+    "## OpenSpec Setup",
+    `Enabled targets: ${targets.join(", ")}`,
+    "### Skills",
+    ...skills.map((skill) => `- ${skill.name}: ${skill.description || "No description"}`),
+    "### Command Bindings",
+    ...config.commandBindings.map((binding) => `- ${binding.id} -> ${binding.skill}`),
+    "</INSTRUCTIONS>",
+    ""
+  ];
+  await writeFile(file, lines.join("\n"), "utf8");
+  return file;
+}
+
+function renderCommandTemplate(
+  target: Target,
+  commandId: string,
+  skillName: string,
+  description: string
+): string {
+  return [
+    `# ${commandId} (${target})`,
+    "",
+    description,
+    "",
+    "## Skill binding",
+    `- skill: ${skillName}`,
+    "",
+    "## Required output",
+    "- Change ID",
+    "- Updated files",
+    "- Validation summary"
+  ].join("\n");
+}
+
+function renderGuide(target: Target, skills: SkillManifest[], config: CDSpecConfig): string {
+  const agent = config.agents[target];
+  const commandList = config.commandBindings.map((binding) =>
+    `- ${agent.slashPattern.replace("{id}", binding.id)} -> ${binding.skill}`
+  );
+  return [
+    `# ${target} OpenSpec-style setup`,
+    "",
+    "## Installed skills",
+    ...skills.map((skill) => `- ${skill.name}: ${skill.description || "No description"}`),
+    "",
+    "## Commands",
+    ...commandList,
+    ""
+  ].join("\n");
+}

package/src/skill-core/types.ts

@@ -0,0 +1,22 @@
+export type Target = "codex" | "claudecode" | "iflow";
+
+export interface SkillManifest {
+  name: string;
+  description: string;
+  body: string;
+  agents: string[];
+  resources: string[];
+  sourcePath: string;
+}
+
+export interface Diagnostic {
+  level: "error" | "warning";
+  message: string;
+}
+
+export interface TargetAdapter {
+  target: Target;
+  validate(manifest: SkillManifest): Diagnostic[];
+  emit(manifest: SkillManifest, outDir: string, force: boolean): Promise<void>;
+}
+

package/src/skill-core/validator.ts

@@ -0,0 +1,28 @@
+import { Diagnostic, SkillManifest } from "./types.js";
+
+export function validateManifest(manifest: SkillManifest): Diagnostic[] {
+  const diagnostics: Diagnostic[] = [];
+  if (!manifest.name) {
+    diagnostics.push({ level: "error", message: "Skill name is required." });
+  }
+  if (!manifest.description) {
+    diagnostics.push({
+      level: "error",
+      message: `Skill "${manifest.name}" is missing frontmatter description.`
+    });
+  }
+  if (!manifest.body) {
+    diagnostics.push({
+      level: "warning",
+      message: `Skill "${manifest.name}" has empty SKILL.md body.`
+    });
+  }
+  if (!/^[a-z0-9-]+$/.test(manifest.name)) {
+    diagnostics.push({
+      level: "warning",
+      message: `Skill "${manifest.name}" should use lowercase letters, numbers, and hyphens.`
+    });
+  }
+  return diagnostics;
+}
+

package/src/task-core/parser.ts

@@ -0,0 +1,89 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { TaskItem } from "./types.js";
+
+export function splitMarkdownToTasks(
+  markdown: string,
+  sourcePath: string,
+  rootTitle: string
+): TaskItem[] {
+  const normalized = markdown.replace(/\r\n/g, "\n");
+  const lines = normalized.split("\n");
+  const headingStack: string[] = [];
+  const extracted: string[] = [];
+
+  for (const line of lines) {
+    const headingMatch = line.match(/^(#{1,6})\s+(.+?)\s*$/);
+    if (headingMatch) {
+      const level = headingMatch[1].length;
+      const title = headingMatch[2].trim();
+      headingStack.splice(level - 1);
+      headingStack[level - 1] = title;
+      continue;
+    }
+
+    const listMatch = line.match(/^\s*(?:[-*+]|\d+\.)\s+(.+?)\s*$/);
+    if (!listMatch) continue;
+    const item = listMatch[1].trim();
+    const prefix = headingStack.filter(Boolean).join(" / ");
+    extracted.push(prefix ? `${prefix} - ${item}` : item);
+  }
+
+  if (extracted.length === 0) {
+    for (const line of lines) {
+      const headingMatch = line.match(/^#{2,6}\s+(.+?)\s*$/);
+      if (headingMatch) extracted.push(headingMatch[1].trim());
+    }
+  }
+
+  if (extracted.length === 0) {
+    extracted.push(rootTitle);
+  }
+
+  return dedupe(extracted).map((title, idx) =>
+    createTaskItem({
+      sourcePath,
+      title,
+      order: idx + 1
+    })
+  );
+}
+
+function createTaskItem(input: {
+  sourcePath: string;
+  title: string;
+  order: number;
+}): TaskItem {
+  const now = new Date().toISOString();
+  return {
+    id: buildStableId(input.sourcePath, input.title, input.order),
+    title: input.title,
+    status: "todo",
+    source: normalizePath(input.sourcePath),
+    createdAt: now,
+    updatedAt: now
+  };
+}
+
+function buildStableId(sourcePath: string, title: string, order: number): string {
+  const digest = createHash("sha1")
+    .update(`${normalizePath(sourcePath)}::${title}::${order}`)
+    .digest("hex");
+  return digest.slice(0, 10);
+}
+
+function normalizePath(input: string): string {
+  return input.replaceAll("\\", "/").replaceAll(path.sep, "/");
+}
+
+function dedupe(items: string[]): string[] {
+  const seen = new Set<string>();
+  const result: string[] = [];
+  for (const item of items) {
+    if (seen.has(item)) continue;
+    seen.add(item);
+    result.push(item);
+  }
+  return result;
+}
+

package/src/task-core/service.ts

@@ -0,0 +1,49 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { pathExists } from "../utils/fs.js";
+import { splitMarkdownToTasks } from "./parser.js";
+import {
+  archiveTask,
+  initTaskWorkspace,
+  refreshArchiveIndex,
+  refreshTaskIndex,
+  saveTask,
+  updateTaskStatus
+} from "./storage.js";
+import { TaskStatus } from "./types.js";
+
+export async function splitTasks(
+  cwd: string,
+  fromFile: string,
+  title: string
+): Promise<number> {
+  const absoluteInput = path.resolve(cwd, fromFile);
+  if (!(await pathExists(absoluteInput))) {
+    throw new Error(`Input file not found: ${fromFile}`);
+  }
+
+  const markdown = await readFile(absoluteInput, "utf8");
+  const tasks = splitMarkdownToTasks(markdown, fromFile, title);
+  await initTaskWorkspace(cwd);
+  for (const task of tasks) {
+    await saveTask(cwd, task);
+  }
+  await refreshTaskIndex(cwd);
+  return tasks.length;
+}
+
+export async function archiveTaskById(cwd: string, id: string): Promise<void> {
+  await archiveTask(cwd, id);
+  await refreshTaskIndex(cwd);
+  await refreshArchiveIndex(cwd);
+}
+
+export async function updateTask(
+  cwd: string,
+  id: string,
+  status: TaskStatus
+): Promise<void> {
+  await updateTaskStatus(cwd, id, status);
+  await refreshTaskIndex(cwd);
+}
+