cdspec 0.1.0

package/dist/utils/frontmatter.js

@@ -0,0 +1,40 @@
+export function parseFrontmatter(content) {
+    const normalized = content.replace(/^\uFEFF/, "").replace(/\r\n/g, "\n");
+    if (!normalized.startsWith("---\n")) {
+        return { attributes: {}, body: normalized };
+    }
+    const endIndex = normalized.indexOf("\n---\n", 4);
+    if (endIndex === -1) {
+        return { attributes: {}, body: normalized };
+    }
+    const header = normalized.slice(4, endIndex);
+    const body = normalized.slice(endIndex + 5);
+    const attributes = {};
+    for (const rawLine of header.split("\n")) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const idx = line.indexOf(":");
+        if (idx <= 0)
+            continue;
+        const key = line.slice(0, idx).trim();
+        let value = line.slice(idx + 1).trim();
+        value = stripQuotes(value);
+        attributes[key] = value;
+    }
+    return { attributes, body };
+}
+export function stringifyFrontmatter(attributes, body) {
+    const lines = Object.entries(attributes).map(([key, value]) => {
+        const escaped = value.replace(/"/g, '\\"');
+        return `${key}: "${escaped}"`;
+    });
+    return `---\n${lines.join("\n")}\n---\n\n${body.trimEnd()}\n`;
+}
+function stripQuotes(value) {
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+        return value.slice(1, -1);
+    }
+    return value;
+}

package/dist/utils/fs.js

@@ -0,0 +1,37 @@
+import { mkdir, readdir, rm, stat, copyFile } from "node:fs/promises";
+import path from "node:path";
+export async function ensureDir(dirPath) {
+    await mkdir(dirPath, { recursive: true });
+}
+export async function pathExists(target) {
+    try {
+        await stat(target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function emptyDir(dirPath) {
+    await rm(dirPath, { recursive: true, force: true });
+    await mkdir(dirPath, { recursive: true });
+}
+export async function copyDir(srcDir, dstDir) {
+    await ensureDir(dstDir);
+    const entries = await readdir(srcDir, { withFileTypes: true });
+    for (const entry of entries) {
+        const srcPath = path.join(srcDir, entry.name);
+        const dstPath = path.join(dstDir, entry.name);
+        if (entry.isDirectory()) {
+            await copyDir(srcPath, dstPath);
+            continue;
+        }
+        await copyFile(srcPath, dstPath);
+    }
+}
+export async function listDirs(dirPath) {
+    if (!(await pathExists(dirPath)))
+        return [];
+    const entries = await readdir(dirPath, { withFileTypes: true });
+    return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "cdspec",
+  "version": "0.1.0",
+  "description": "CDSpec CLI for skill sync and task split/archive workflow",
+  "type": "module",
+  "bin": {
+    "cdspec": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/cli.ts",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "@inquirer/checkbox": "^4.3.2",
+    "commander": "^14.0.1",
+    "yaml": "^2.8.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "tsx": "^4.20.3",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+import checkbox from '@inquirer/checkbox'
+import { Command } from 'commander'
+import path from 'node:path'
+import process from 'node:process'
+import { addSkill, initSkills, listSkills, syncSkills } from './skill-core/service.js'
+import { archiveTaskById, splitTasks, updateTask } from './task-core/service.js'
+
+const program = new Command()
+
+program.name('cdspec').description('Skill sync + task split/archive workflow CLI').version('0.1.0')
+
+program
+  .command('init')
+  .description('Initialize skills for selected coding agents')
+  .option('--agents <agents>', 'codex|claudecode|iflow|all or comma-separated')
+  .action(async (options: { agents?: string }) => {
+    const selected = options.agents ?? (await askAgentsSelection())
+    const files = await initSkills(process.cwd(), selected, true)
+    console.log(`Initialized OpenSpec-style setup for "${selected}".`)
+    console.log(`Generated files: ${files.map(x => path.relative(process.cwd(), x)).join(', ')}`)
+  })
+
+program
+  .command('skill')
+  .description('Skill operations')
+  .addCommand(
+    new Command('list').action(async () => {
+      const names = await listSkills(process.cwd())
+      if (names.length === 0) {
+        console.log('No skill found under .codex/.')
+        return
+      }
+      names.forEach(name => console.log(name))
+    })
+  )
+  .addCommand(
+    new Command('add')
+      .argument('<name>', 'skill folder name under .codex')
+      .option('--target <target>', 'codex|claudecode|iflow|all or comma-separated', 'all')
+      .option('--force', 'overwrite existing output', false)
+      .action(async (name: string, options: { target: string; force: boolean }) => {
+        await addSkill(process.cwd(), name, options.target, options.force)
+        console.log(`Skill "${name}" exported to tool folders for target "${options.target}".`)
+      })
+  )
+  .addCommand(
+    new Command('sync')
+      .option('--target <target>', 'codex|claudecode|iflow|all or comma-separated', 'all')
+      .option('--force', 'overwrite existing output', false)
+      .action(async (options: { target: string; force: boolean }) => {
+        await syncSkills(process.cwd(), options.target, options.force)
+        console.log(`All skills synced to tool folders for target "${options.target}".`)
+      })
+  )
+
+program
+  .command('task')
+  .description('Task split/archive operations')
+  .addCommand(
+    new Command('split')
+      .requiredOption('--from <file>', 'source markdown file')
+      .requiredOption('--title <title>', 'task group title')
+      .action(async (options: { from: string; title: string }) => {
+        const count = await splitTasks(process.cwd(), options.from, options.title)
+        console.log(`Generated ${count} tasks from "${options.from}".`)
+      })
+  )
+  .addCommand(
+    new Command('status')
+      .requiredOption('--id <id>', 'task id')
+      .requiredOption('--to <status>', 'todo|in_progress|done')
+      .action(async (options: { id: string; to: 'todo' | 'in_progress' | 'done' }) => {
+        await updateTask(process.cwd(), options.id, options.to)
+        console.log(`Task "${options.id}" updated to "${options.to}".`)
+      })
+  )
+  .addCommand(
+    new Command('archive').requiredOption('--id <id>', 'task id').action(async (options: { id: string }) => {
+      await archiveTaskById(process.cwd(), options.id)
+      console.log(`Task "${options.id}" archived.`)
+    })
+  )
+
+program.parseAsync(process.argv).catch((error: unknown) => {
+  const message = error instanceof Error ? error.message : String(error)
+  console.error(message)
+  process.exitCode = 1
+})
+
+async function askAgentsSelection(): Promise<string> {
+  if (!process.stdin.isTTY) return 'all'
+  const values = await checkbox({
+    message: 'Select coding agents',
+    choices: [
+      { name: 'codex', value: 'codex', checked: true },
+      { name: 'claudecode', value: 'claudecode' },
+      { name: 'iflow', value: 'iflow' },
+      { name: 'all', value: 'all' }
+    ]
+  })
+  if (values.length === 0) return 'all'
+  if (values.includes('all')) return 'all'
+  return values.join(',')
+}

package/src/config/default.ts

@@ -0,0 +1,51 @@
+import { CDSpecConfig } from "./types.js";
+
+export const defaultConfig: CDSpecConfig = {
+  commandBindings: [
+    {
+      id: "propose",
+      skill: "openspec-core",
+      description: "Create a change proposal with scope and impacted specs."
+    },
+    {
+      id: "explore",
+      skill: "openspec-core",
+      description: "Analyze existing specs and produce planned deltas."
+    },
+    {
+      id: "apply",
+      skill: "openspec-core",
+      description: "Implement approved tasks and keep spec updates in sync."
+    },
+    {
+      id: "archive",
+      skill: "openspec-core",
+      description: "Archive completed changes and update baseline specs."
+    }
+  ],
+  agents: {
+    codex: {
+      rootDir: ".codex",
+      commandsDir: "prompts",
+      commandFilePattern: "opsx-{id}.md",
+      slashPattern: "/opsx-{id}",
+      guideFile: "AGENTS.md"
+    },
+    claudecode: {
+      rootDir: ".claude",
+      commandsDir: "commands/opsx",
+      commandFilePattern: "{id}.md",
+      slashPattern: "/opsx:{id}",
+      guideFile: "CLAUDE.md",
+      guideAtProjectRoot: true
+    },
+    iflow: {
+      rootDir: ".iflow",
+      commandsDir: "commands",
+      commandFilePattern: "opsx-{id}.md",
+      slashPattern: "/opsx-{id}",
+      guideFile: "IFLOW.md"
+    }
+  }
+};
+

package/src/config/loader.ts

@@ -0,0 +1,37 @@
+import path from "node:path";
+import { readFile } from "node:fs/promises";
+import { parse } from "yaml";
+import { pathExists } from "../utils/fs.js";
+import { defaultConfig } from "./default.js";
+import { CDSpecConfig } from "./types.js";
+
+const CONFIG_FILE = "cdspec.config.yaml";
+
+export async function loadConfig(cwd: string): Promise<CDSpecConfig> {
+  const configPath = path.join(cwd, CONFIG_FILE);
+  if (!(await pathExists(configPath))) {
+    return defaultConfig;
+  }
+
+  const raw = await readFile(configPath, "utf8");
+  const parsed = parse(raw) as Partial<CDSpecConfig> | null;
+  if (!parsed) return defaultConfig;
+
+  const merged: CDSpecConfig = {
+    commandBindings:
+      parsed.commandBindings && parsed.commandBindings.length > 0
+        ? parsed.commandBindings
+        : defaultConfig.commandBindings,
+    agents: {
+      codex: { ...defaultConfig.agents.codex, ...(parsed.agents?.codex || {}) },
+      claudecode: {
+        ...defaultConfig.agents.claudecode,
+        ...(parsed.agents?.claudecode || {})
+      },
+      iflow: { ...defaultConfig.agents.iflow, ...(parsed.agents?.iflow || {}) }
+    }
+  };
+
+  return merged;
+}
+

package/src/config/path.ts

@@ -0,0 +1,13 @@
+import os from "node:os";
+import path from "node:path";
+
+export function resolveAgentRoot(cwd: string, rootDir: string): string {
+  if (rootDir.startsWith("~/") || rootDir.startsWith("~\\")) {
+    return path.join(os.homedir(), rootDir.slice(2));
+  }
+  if (path.win32.isAbsolute(rootDir) || path.posix.isAbsolute(rootDir)) {
+    return path.normalize(rootDir);
+  }
+  return path.join(cwd, rootDir);
+}
+

package/src/config/types.ts

@@ -0,0 +1,22 @@
+import { Target } from "../skill-core/types.js";
+
+export interface CommandBinding {
+  id: string;
+  skill: string;
+  description: string;
+}
+
+export interface AgentConfig {
+  rootDir: string;
+  commandsDir: string;
+  commandFilePattern: string;
+  slashPattern: string;
+  guideFile: string;
+  guideAtProjectRoot?: boolean;
+}
+
+export interface CDSpecConfig {
+  commandBindings: CommandBinding[];
+  agents: Record<Target, AgentConfig>;
+}
+

package/src/skill-core/adapters/claudecode-adapter.ts

@@ -0,0 +1,45 @@
+import path from "node:path";
+import { emptyDir, pathExists } from "../../utils/fs.js";
+import { Diagnostic, SkillManifest, TargetAdapter } from "../types.js";
+import { emitWithLayout } from "./shared.js";
+
+export class ClaudeCodeAdapter implements TargetAdapter {
+  target = "claudecode" as const;
+
+  validate(manifest: SkillManifest): Diagnostic[] {
+    const diagnostics: Diagnostic[] = [];
+    if (!manifest.name) {
+      diagnostics.push({ level: "error", message: "[claudecode] name is required." });
+    }
+    return diagnostics;
+  }
+
+  async emit(manifest: SkillManifest, outDir: string, force: boolean): Promise<void> {
+    if ((await pathExists(outDir)) && !force) {
+      throw new Error(
+        `Target already exists for skill "${manifest.name}" at ${outDir}. Use --force to overwrite.`
+      );
+    }
+    if (force) {
+      await emptyDir(outDir);
+    }
+
+    const meta = {
+      name: manifest.name,
+      description: manifest.description,
+      entry: "SKILL.md"
+    };
+
+    await emitWithLayout(manifest, outDir, true, [
+      {
+        relativePath: "claudecode.skill.json",
+        content: `${JSON.stringify(meta, null, 2)}\n`
+      }
+    ]);
+  }
+}
+
+export function claudecodeSkillPath(baseOutDir: string, skillName: string): string {
+  return path.join(baseOutDir, "claudecode", skillName);
+}
+

package/src/skill-core/adapters/codex-adapter.ts

@@ -0,0 +1,36 @@
+import path from "node:path";
+import { emptyDir, pathExists } from "../../utils/fs.js";
+import { Diagnostic, SkillManifest, TargetAdapter } from "../types.js";
+import { emitWithLayout } from "./shared.js";
+
+export class CodexAdapter implements TargetAdapter {
+  target = "codex" as const;
+
+  validate(manifest: SkillManifest): Diagnostic[] {
+    const diagnostics: Diagnostic[] = [];
+    if (!manifest.description) {
+      diagnostics.push({
+        level: "error",
+        message: `[codex] ${manifest.name}: description is required.`
+      });
+    }
+    return diagnostics;
+  }
+
+  async emit(manifest: SkillManifest, outDir: string, force: boolean): Promise<void> {
+    if ((await pathExists(outDir)) && !force) {
+      throw new Error(
+        `Target already exists for skill "${manifest.name}" at ${outDir}. Use --force to overwrite.`
+      );
+    }
+    if (force) {
+      await emptyDir(outDir);
+    }
+    await emitWithLayout(manifest, outDir, true, []);
+  }
+}
+
+export function codexSkillPath(baseOutDir: string, skillName: string): string {
+  return path.join(baseOutDir, "codex", skillName);
+}
+

package/src/skill-core/adapters/iflow-adapter.ts

@@ -0,0 +1,49 @@
+import path from "node:path";
+import { emptyDir, pathExists } from "../../utils/fs.js";
+import { Diagnostic, SkillManifest, TargetAdapter } from "../types.js";
+import { emitWithLayout } from "./shared.js";
+
+export class IFlowAdapter implements TargetAdapter {
+  target = "iflow" as const;
+
+  validate(manifest: SkillManifest): Diagnostic[] {
+    const diagnostics: Diagnostic[] = [];
+    if (!manifest.description) {
+      diagnostics.push({
+        level: "warning",
+        message: `[iflow] ${manifest.name}: description is empty.`
+      });
+    }
+    return diagnostics;
+  }
+
+  async emit(manifest: SkillManifest, outDir: string, force: boolean): Promise<void> {
+    if ((await pathExists(outDir)) && !force) {
+      throw new Error(
+        `Target already exists for skill "${manifest.name}" at ${outDir}. Use --force to overwrite.`
+      );
+    }
+    if (force) {
+      await emptyDir(outDir);
+    }
+
+    const skillYaml = [
+      `name: "${manifest.name}"`,
+      `description: "${manifest.description.replace(/"/g, '\\"')}"`,
+      'entry: "prompt.md"'
+    ].join("\n");
+
+    await emitWithLayout(manifest, outDir, false, [
+      {
+        relativePath: "prompt.md",
+        content: `# ${manifest.name}\n\n${manifest.body}\n`
+      },
+      { relativePath: "iflow.skill.yaml", content: `${skillYaml}\n` }
+    ]);
+  }
+}
+
+export function iflowSkillPath(baseOutDir: string, skillName: string): string {
+  return path.join(baseOutDir, "iflow", skillName);
+}
+

package/src/skill-core/adapters/index.ts

@@ -0,0 +1,39 @@
+import { Target, TargetAdapter } from "../types.js";
+import { ClaudeCodeAdapter } from "./claudecode-adapter.js";
+import { CodexAdapter } from "./codex-adapter.js";
+import { IFlowAdapter } from "./iflow-adapter.js";
+
+const adapters: Record<Target, TargetAdapter> = {
+  codex: new CodexAdapter(),
+  claudecode: new ClaudeCodeAdapter(),
+  iflow: new IFlowAdapter()
+};
+
+export function getAdapter(target: Target): TargetAdapter {
+  return adapters[target];
+}
+
+export function expandTargets(raw: string): Target[] {
+  const value = raw.trim().toLowerCase();
+  if (value === "all") return ["codex", "claudecode", "iflow"];
+  const parts = value
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean)
+    .map(normalizeTargetAlias);
+  if (parts.length === 0) {
+    throw new Error(`Unknown target "${raw}". Use codex|claudecode|iflow|all.`);
+  }
+  const invalid = parts.filter(
+    (item) => item !== "codex" && item !== "claudecode" && item !== "iflow"
+  );
+  if (invalid.length > 0) {
+    throw new Error(`Unknown target "${invalid[0]}". Use codex|claudecode|iflow|all.`);
+  }
+  return Array.from(new Set(parts)) as Target[];
+}
+
+function normalizeTargetAlias(value: string): string {
+  if (value === "ifow") return "iflow";
+  return value;
+}

package/src/skill-core/adapters/shared.ts

@@ -0,0 +1,45 @@
+import { copyFile, readFile, readdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { ensureDir, pathExists } from "../../utils/fs.js";
+import { SkillManifest } from "../types.js";
+
+export async function emitWithLayout(
+  manifest: SkillManifest,
+  outDir: string,
+  includeOriginalSkillMd: boolean,
+  generatedFiles: Array<{ relativePath: string; content: string }>
+): Promise<void> {
+  await ensureDir(outDir);
+  if (includeOriginalSkillMd) {
+    const srcSkillMd = path.join(manifest.sourcePath, "SKILL.md");
+    await copyFile(srcSkillMd, path.join(outDir, "SKILL.md"));
+  }
+
+  for (const file of generatedFiles) {
+    const targetFile = path.join(outDir, file.relativePath);
+    await ensureDir(path.dirname(targetFile));
+    await writeFile(targetFile, file.content, "utf8");
+  }
+
+  const folders = ["agents", "references", "scripts", "assets"];
+  for (const folder of folders) {
+    const sourceFolder = path.join(manifest.sourcePath, folder);
+    if (!(await pathExists(sourceFolder))) continue;
+    await copyFolder(sourceFolder, path.join(outDir, folder));
+  }
+}
+
+async function copyFolder(srcDir: string, dstDir: string): Promise<void> {
+  await ensureDir(dstDir);
+  const entries = await readdir(srcDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const src = path.join(srcDir, entry.name);
+    const dst = path.join(dstDir, entry.name);
+    if (entry.isDirectory()) {
+      await copyFolder(src, dst);
+      continue;
+    }
+    const data = await readFile(src);
+    await writeFile(dst, data);
+  }
+}

package/src/skill-core/manifest-loader.ts

@@ -0,0 +1,79 @@
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { parseFrontmatter } from "../utils/frontmatter.js";
+import { listDirs, pathExists } from "../utils/fs.js";
+import { SkillManifest } from "./types.js";
+
+const CODEX_DIR = ".codex";
+
+export async function loadAllSkillManifests(cwd: string): Promise<SkillManifest[]> {
+  const sourceRoot = path.join(cwd, CODEX_DIR);
+  const skillDirs = await listDirs(sourceRoot);
+  const manifests: SkillManifest[] = [];
+  for (const dirName of skillDirs) {
+    const fullPath = path.join(sourceRoot, dirName);
+    const manifest = await loadSkillManifest(fullPath);
+    if (manifest) manifests.push(manifest);
+  }
+  return manifests;
+}
+
+export async function loadSkillManifestByName(
+  cwd: string,
+  name: string
+): Promise<SkillManifest | null> {
+  return loadSkillManifest(path.join(cwd, CODEX_DIR, name));
+}
+
+async function loadSkillManifest(skillDir: string): Promise<SkillManifest | null> {
+  const skillMdPath = path.join(skillDir, "SKILL.md");
+  if (!(await pathExists(skillMdPath))) return null;
+
+  const content = await readFile(skillMdPath, "utf8");
+  const parsed = parseFrontmatter(content);
+  const frontName = parsed.attributes.name?.trim();
+  const frontDescription = parsed.attributes.description?.trim();
+  const displayName = frontName || path.basename(skillDir);
+
+  const agents = await collectRelativeFiles(path.join(skillDir, "agents"), "agents");
+  const resources = await collectRelativeFiles(path.join(skillDir, "references"), "references");
+  const scripts = await collectRelativeFiles(path.join(skillDir, "scripts"), "scripts");
+  const assets = await collectRelativeFiles(path.join(skillDir, "assets"), "assets");
+
+  return {
+    name: displayName,
+    description: frontDescription || "",
+    body: parsed.body.trim(),
+    agents,
+    resources: [...resources, ...scripts, ...assets],
+    sourcePath: skillDir
+  };
+}
+
+async function collectRelativeFiles(
+  dirPath: string,
+  prefix: string
+): Promise<string[]> {
+  if (!(await pathExists(dirPath))) return [];
+  const result: string[] = [];
+  await walk(dirPath, (absolutePath) => {
+    const relative = path.relative(path.dirname(dirPath), absolutePath);
+    result.push(relative.replaceAll("\\", "/").replace(`${prefix}/./`, `${prefix}/`));
+  });
+  return result;
+}
+
+async function walk(
+  dirPath: string,
+  onFile: (absolutePath: string) => void
+): Promise<void> {
+  const entries = await readdir(dirPath, { withFileTypes: true });
+  for (const entry of entries) {
+    const absolute = path.join(dirPath, entry.name);
+    if (entry.isDirectory()) {
+      await walk(absolute, onFile);
+      continue;
+    }
+    onFile(absolute);
+  }
+}