@xzzpig/pi-openspec-x 0.1.0

package/src/skills.ts

@@ -0,0 +1,386 @@
+/**
+ * Official-track skill generation for pi-openspec-x.
+ *
+ * Generates the five openspec-* SKILL.md files from the installed OpenSpec
+ * CLI into `<agentDir>/cache/pi-openspec-x/skills/<cliVersion>/`. The CLI
+ * version is the cache key: when the versioned directory exists and its
+ * stamp matches, no CLI command runs at all (the version itself comes from
+ * the once-per-session probe in cli.ts). On a miss, the artifact list is
+ * taken from `openspec schemas --json` (spec-driven -> proposal, specs,
+ * design, tasks).
+ *
+ * The generated bodies are English skeletons that keep the CLI's own flavor:
+ * they tell the agent when the skill triggers, sketch the workflow steps, and
+ * direct it to fetch the authoritative instructions from the CLI at execution
+ * time (`openspec status/list/instructions <artifact> --change <id> --json`).
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { openspecXSkillsDir, resolveAgentDir } from "./agent-dir.ts";
+import {
+  listOpenspecSchemas,
+  probeOpenspecVersion,
+  type OpenspecCliOptions,
+  type OpenspecSchemaInfo,
+} from "./cli.ts";
+
+/** The five generated skills, matching the official openspec skill set. */
+export const OPENSPEC_SKILL_NAMES = [
+  "openspec-explore",
+  "openspec-propose",
+  "openspec-apply-change",
+  "openspec-archive-change",
+  "openspec-sync-specs",
+] as const;
+
+export type OpenspecSkillName = (typeof OPENSPEC_SKILL_NAMES)[number];
+
+/**
+ * Trigger descriptions, semantically aligned with the official static skills
+ * shipped by `openspec init` (wording may be refined, meaning is preserved).
+ */
+const SKILL_DESCRIPTIONS: Record<OpenspecSkillName, string> = {
+  "openspec-explore":
+    'Enter OpenSpec explore mode - a thinking partner for exploring ideas, investigating problems, and clarifying requirements in a project that uses OpenSpec. Use when the user wants to think through something before or during an OpenSpec change. Also use when the user says "openspec explore" or "opsx explore".',
+  "openspec-propose":
+    'Propose a new OpenSpec change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation. Also use when the user says "openspec propose" or "opsx propose".',
+  "openspec-apply-change":
+    'Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks. Also use when the user says "openspec apply", "opsx apply", or "openspec implement".',
+  "openspec-archive-change":
+    'Archive a completed OpenSpec change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete. Also use when the user says "openspec archive" or "opsx archive".',
+  "openspec-sync-specs":
+    'Sync delta specs from an OpenSpec change to main specs. Use when the user wants to update main specs with changes from a delta spec, without archiving the change. Also use when the user says "openspec sync" or "opsx sync".',
+};
+
+// ── rendering ───────────────────────────────────────────────────────────────
+
+export interface SkillRenderContext {
+  cliVersion: string;
+  /** Schema preferred for generation: `spec-driven` when present, else the first reported schema. */
+  schema: OpenspecSchemaInfo | undefined;
+}
+
+function renderFrontmatter(
+  name: OpenspecSkillName,
+  context: SkillRenderContext,
+): string {
+  return [
+    "---",
+    `name: ${name}`,
+    `description: ${SKILL_DESCRIPTIONS[name]}`,
+    "allowed-tools: Bash(openspec:*)",
+    "license: MIT",
+    "compatibility: Requires openspec CLI.",
+    "metadata:",
+    "  author: openspec",
+    '  version: "1.0"',
+    `  generatedBy: "${context.cliVersion}"`,
+    "---",
+  ].join("\n");
+}
+
+function renderAuthoritativeBlock(changeScoped: boolean): string {
+  const commands = changeScoped
+    ? [
+        "openspec list --json",
+        'openspec status --change "<change-id>" --json',
+        'openspec instructions <artifact> --change "<change-id>" --json',
+      ]
+    : ["openspec list --json", 'openspec status --change "<change-id>" --json'];
+  return [
+    `This SKILL.md is a generated trigger and workflow skeleton (generated by the pi-openspec-x extension from OpenSpec CLI). The OpenSpec CLI is the single source of truth at execution time: run the \`--json\` commands below fresh in every session and follow their output over anything written here.`,
+    "",
+    "```bash",
+    ...commands,
+    "```",
+  ].join("\n");
+}
+
+function renderArtifactLine(context: SkillRenderContext): string {
+  if (!context.schema) {
+    return "Run `openspec schemas --json` at execution time to discover the available workflow schemas and their artifacts; none could be captured at generation time.";
+  }
+  return [
+    `Default artifacts for the \`${context.schema.name}\` schema (${context.schema.description}): ${context.schema.artifacts.join(", ")}.`,
+    'Always confirm the artifact set with `openspec status --change "<change-id>" --json` at execution time.',
+  ].join(" ");
+}
+
+const SKILL_BODIES: Record<
+  OpenspecSkillName,
+  (context: SkillRenderContext) => string
+> = {
+  "openspec-explore": (context) =>
+    [
+      renderAuthoritativeBlock(false),
+      "",
+      "## When to use",
+      "",
+      "- The user wants to think through something before or during an OpenSpec change.",
+      '- The user says "openspec explore" or "opsx explore".',
+      "",
+      "## Workflow skeleton",
+      "",
+      "1. **Ground in the CLI first.** Run `openspec list --json` (add `--specs` to include specifications) and read the current changes and specs before saying anything substantive. If the project has no OpenSpec root, treat this as a normal exploration conversation and do not create anything.",
+      "2. **Clarify the question.** Ask open-ended questions until the problem, constraints, and desired outcome are concrete; summarize them back before proposing anything.",
+      "3. **Investigate.** Read the specs, change artifacts, and code the question touches. Quote what you find; distinguish observed behavior from assumptions.",
+      "4. **Discuss, do not build.** Offer options, trade-offs, and recommendations. If the user wants to proceed to a change, hand off to the openspec-propose workflow.",
+      "",
+      renderArtifactLine(context),
+      "",
+      "## Guardrails",
+      "",
+      "- Explore mode is conversational: no artifact writes, no implementation.",
+      '- Re-run `openspec list --json` / `openspec status --change "<id>" --json` whenever state may have changed; never answer from memory of a previous run.',
+    ].join("\n"),
+  "openspec-propose": (context) =>
+    [
+      renderAuthoritativeBlock(true),
+      "",
+      "## When to use",
+      "",
+      "- The user wants to describe what they want to build and get a complete proposal ready for implementation.",
+      '- The user says "openspec propose" or "opsx propose".',
+      "",
+      "## Workflow skeleton",
+      "",
+      '1. **Understand the request.** Derive a kebab-case change id (e.g. "add user authentication" -> `add-user-auth`). Ask when scope-affecting ambiguity exists; make and record reasonable assumptions for minor details.',
+      "2. **Ground in the CLI.** Run `openspec list --json` to check the project has an OpenSpec root and to see existing changes. If there is no root, stop and ask the user how to proceed; never create the root as a side effect.",
+      '3. **Create the change.** Run `openspec new change "<change-id>"` (pass `--schema <name>` only if the user explicitly requested a schema).',
+      '4. **Read the build order.** Run `openspec status --change "<change-id>" --json` and use `applyRequires` plus each artifact\'s `requires` edges to compute the full required artifact set.',
+      '5. **Create every artifact in dependency order.** For each artifact run `openspec instructions <artifact> --change "<change-id>" --json`, then write the artifact to the returned `resolvedOutputPath` using its `template`; treat its `context`, `rules`, and `instruction` as constraints (never copy them into the file). Re-read completed dependency artifacts from disk before using them.',
+      '6. **Iterate to done.** Re-run `openspec status --change "<change-id>" --json` after each artifact; create newly unblocked artifacts; stop when every artifact in the required set is done or deliberately skipped.',
+      "7. **Hand off.** Summarize what was created and point the user to the apply workflow for implementation.",
+      "",
+      renderArtifactLine(context),
+      "",
+      "## Guardrails",
+      "",
+      "- Planning boundary: this workflow authorizes planning only. Do not implement the change or edit project code; stop after the artifacts are complete.",
+      "- The `openspec instructions` output is authoritative for each artifact, even for familiar artifact names.",
+      '- If the user names a registered store, append `--store "<id>"` to the commands that accept it (discover ids with `openspec store list --json`).',
+    ].join("\n"),
+  "openspec-apply-change": (context) =>
+    [
+      renderAuthoritativeBlock(true),
+      "",
+      "## When to use",
+      "",
+      "- The user wants to start implementing, continue implementation, or work through the tasks of an existing change.",
+      '- The user says "openspec apply", "opsx apply", or "openspec implement".',
+      "",
+      "## Workflow skeleton",
+      "",
+      '1. **Ground in the CLI.** Run `openspec list --json` to see in-progress changes and `openspec status --change "<change-id>" --json` for artifact completion. Confirm with the user which change to apply when it is ambiguous.',
+      '2. **Fetch authoritative apply instructions.** Run `openspec instructions apply --change "<change-id>" --json` and follow its `instruction`, `context`, and `rules`; they override this skeleton.',
+      "3. **Read the artifacts.** Read `tasks.md` (and the other artifacts the instructions name) from disk before starting; never rely on conversation memory.",
+      "4. **Implement task by task.** Work through tasks in order, marking each complete exactly as the apply instructions specify. Keep implementation grounded in the tasks; surface blockers instead of silently skipping.",
+      '5. **Verify.** Run the project checks the artifacts call for, then re-run `openspec status --change "<change-id>" --json` and report remaining work.',
+      "6. **Archive or stop.** When every task is complete, point the user to the archive workflow; archive only when the user asks.",
+      "",
+      renderArtifactLine(context),
+      "",
+      "## Guardrails",
+      "",
+      "- Follow the change's artifacts; if code reality conflicts with them, stop and reconcile with the user instead of improvising.",
+      "- Do not archive as a side effect of implementation.",
+    ].join("\n"),
+  "openspec-archive-change": (context) =>
+    [
+      renderAuthoritativeBlock(true),
+      "",
+      "## When to use",
+      "",
+      "- The user wants to finalize and archive a change after implementation is complete.",
+      '- The user says "openspec archive" or "opsx archive".',
+      "",
+      "## Workflow skeleton",
+      "",
+      '1. **Ground in the CLI.** Run `openspec list --json` and `openspec status --change "<change-id>" --json` to confirm the change exists and its work is complete. If tasks remain, confirm with the user before archiving.',
+      '2. **Fetch authoritative archive instructions.** Run `openspec instructions archive --change "<change-id>" --json` and follow the returned `instruction`, `context`, and `rules`.',
+      '3. **Archive.** Run `openspec archive "<change-id>"`, appending any flags the instructions require (for example skip-specs handling for changes without spec deltas).',
+      "4. **Verify.** Re-run `openspec list --json` (and `--specs`) to confirm the change moved to archive and main specs were updated as the instructions described.",
+      "",
+      renderArtifactLine(context),
+      "",
+      "## Guardrails",
+      "",
+      "- Archiving updates main specs: read the archive instructions' spec-update rules and verify the resulting specs before declaring success.",
+      "- Never hand-edit archived changes; use the CLI.",
+    ].join("\n"),
+  "openspec-sync-specs": (context) =>
+    [
+      renderAuthoritativeBlock(true),
+      "",
+      "## When to use",
+      "",
+      "- The user wants to update main specs with changes from a delta spec, without archiving the change.",
+      '- The user says "openspec sync" or "opsx sync".',
+      "",
+      "## Workflow skeleton",
+      "",
+      '1. **Ground in the CLI.** Run `openspec list --json` and `openspec status --change "<change-id>" --json` to locate the change and confirm its `specs` artifact exists.',
+      '2. **Fetch authoritative instructions.** Run `openspec instructions specs --change "<change-id>" --json` (or the artifact id the status output names) and follow its `instruction`, `context`, and `rules` for how this change\'s deltas apply to main specs.',
+      "3. **Apply the deltas.** Update the main spec files exactly as the instructions and the change's delta spec direct; preserve the main specs' organization and existing capability paths.",
+      "4. **Verify.** Run the validation command the instructions name (e.g. `openspec validate --json`) and show what changed.",
+      "",
+      renderArtifactLine(context),
+      "",
+      "## Guardrails",
+      "",
+      "- Sync does not archive: the change stays open until the user explicitly archives it.",
+      "- The CLI instructions and the change's delta spec are authoritative over this skeleton.",
+    ].join("\n"),
+};
+
+export function renderSkill(
+  name: OpenspecSkillName,
+  context: SkillRenderContext,
+): string {
+  return `${renderFrontmatter(name, context)}\n\n${SKILL_BODIES[name](context)}\n`;
+}
+
+// ── cache & generation ──────────────────────────────────────────────────────
+
+export interface EnsureOpenspecSkillsOptions extends OpenspecCliOptions {
+  /** Override the resolved agent dir (tests). Defaults to `resolveAgentDir(env, homeDir)`. */
+  agentDir?: string;
+  /** Home dir used by agent-dir resolution when `agentDir` is not given. */
+  homeDir?: string;
+}
+
+export interface EnsureOpenspecSkillsResult {
+  /** `<agentDir>/cache/pi-openspec-x/skills/<cliVersion>` — pass as a skill path to pi. */
+  skillsDir: string;
+  /** CLI version the cache is keyed on. */
+  version: string;
+  /** True when the versioned directory was already present and valid. */
+  cacheHit: boolean;
+  /** Absolute SKILL.md paths, one per generated skill. */
+  skillFilePaths: string[];
+}
+
+const STAMP_FILE_NAME = ".pi-openspec-x-stamp.json";
+
+interface SkillsStamp {
+  generatedBy: string;
+  skills: string[];
+}
+
+function isCacheHit(skillsDir: string, version: string): boolean {
+  try {
+    const stamp = JSON.parse(
+      fs.readFileSync(path.join(skillsDir, STAMP_FILE_NAME), "utf-8"),
+    ) as SkillsStamp;
+    if (stamp.generatedBy !== version || !Array.isArray(stamp.skills))
+      return false;
+    return OPENSPEC_SKILL_NAMES.every(
+      (name) =>
+        stamp.skills.includes(name) &&
+        fs.existsSync(path.join(skillsDir, name, "SKILL.md")),
+    );
+  } catch {
+    return false;
+  }
+}
+
+function generateSkills(
+  skillsDir: string,
+  context: SkillRenderContext,
+): string[] {
+  fs.rmSync(skillsDir, { recursive: true, force: true });
+  fs.mkdirSync(skillsDir, { recursive: true });
+  const skillFilePaths: string[] = [];
+  for (const name of OPENSPEC_SKILL_NAMES) {
+    const skillDir = path.join(skillsDir, name);
+    fs.mkdirSync(skillDir, { recursive: true });
+    const filePath = path.join(skillDir, "SKILL.md");
+    fs.writeFileSync(filePath, renderSkill(name, context), "utf-8");
+    skillFilePaths.push(filePath);
+  }
+  const stamp: SkillsStamp = {
+    generatedBy: context.cliVersion,
+    skills: [...OPENSPEC_SKILL_NAMES],
+  };
+  // The stamp is written last: its presence marks a complete generation.
+  fs.writeFileSync(
+    path.join(skillsDir, STAMP_FILE_NAME),
+    `${JSON.stringify(stamp, null, 2)}\n`,
+    "utf-8",
+  );
+  return skillFilePaths;
+}
+
+/**
+ * Session-level freeze of the resolved skills directory.
+ *
+ * Spec: 同一会话内发生 skill 重新发现（如扩展 reload）时，动态 skill 的路径与内容
+ * 保持不变，期间发生的 CLI 升级不在本会话生效。 Pi runs one process per session,
+ * so pinning the first successful resolution for the process lifetime is exactly
+ * that freeze: a re-discovery after an extension reload reuses the pin instead
+ * of re-probing the CLI, and a CLI upgrade mid-session therefore cannot swap the
+ * skills out from under a running flow.
+ */
+const frozenSkills = new Map<string, { skillsDir: string; version: string }>();
+
+/** Test-only: drop the session freeze. */
+export function resetSkillsFreezeForTests(): void {
+  frozenSkills.clear();
+}
+
+function frozenResult(frozen: {
+  skillsDir: string;
+  version: string;
+}): EnsureOpenspecSkillsResult {
+  return {
+    skillsDir: frozen.skillsDir,
+    version: frozen.version,
+    cacheHit: true,
+    skillFilePaths: OPENSPEC_SKILL_NAMES.map((name) =>
+      path.join(frozen.skillsDir, name, "SKILL.md"),
+    ),
+  };
+}
+
+/**
+ * Ensure the versioned skills cache exists and return its path.
+ *
+ * Cache hit: directory present, stamp matches the probed CLI version, and
+ * every SKILL.md exists — returns without running any schemas/templates
+ * command (the version itself comes from the once-per-session probe).
+ * Cache miss: probes the version, reads `openspec schemas --json` for the
+ * artifact list, and (re)generates all five skills.
+ *
+ * Throws the typed cli.ts errors; callers decide how to surface them (the
+ * resources_discover handler never rethrows).
+ */
+export function ensureOpenspecSkills(
+  options: EnsureOpenspecSkillsOptions = {},
+): EnsureOpenspecSkillsResult {
+  const agentDir =
+    options.agentDir ?? resolveAgentDir(options.env, options.homeDir);
+  const cliOptions: OpenspecCliOptions = {
+    env: options.env,
+    cwd: options.cwd,
+    timeoutMs: options.timeoutMs,
+    spawnImpl: options.spawnImpl,
+  };
+  const freezeKey = `${agentDir}::${options.cwd ?? ""}`;
+  const frozen = frozenSkills.get(freezeKey);
+  if (frozen) return frozenResult(frozen);
+
+  const version = probeOpenspecVersion(cliOptions);
+  const skillsDir = openspecXSkillsDir(agentDir, version);
+  frozenSkills.set(freezeKey, { skillsDir, version });
+  if (isCacheHit(skillsDir, version)) {
+    return frozenResult({ skillsDir, version });
+  }
+  const schemas = listOpenspecSchemas(cliOptions);
+  const schema =
+    schemas.find((entry) => entry.name === "spec-driven") ?? schemas[0];
+  const skillFilePaths = generateSkills(skillsDir, {
+    cliVersion: version,
+    schema,
+  });
+  return { skillsDir, version, cacheHit: false, skillFilePaths };
+}

package/src/static-conflict.ts

@@ -0,0 +1,89 @@
+/**
+ * Static same-name skill detection for pi-openspec-x.
+ *
+ * The official static skills that `openspec init` writes under the project's
+ * `.pi/skills/openspec-` skill directories collide with the dynamically
+ * generated skills this extension provides. When both exist, the static
+ * copies are redundant. This module only detects and reports — it never
+ * deletes or modifies project files.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { OPENSPEC_SKILL_NAMES } from "./skills.ts";
+
+/** customType of the static-conflict notice sent to the session. */
+export const STATIC_CONFLICT_CUSTOM_TYPE =
+  "pi-openspec-x/static-skill-conflict";
+
+/**
+ * Return the absolute paths of `<cwd>/.pi/skills/<name>` directories that
+ * exist for the generated skill names, in skill order.
+ */
+export function findStaticSkillConflicts(
+  cwd: string,
+  skillNames: readonly string[] = OPENSPEC_SKILL_NAMES,
+): string[] {
+  const hits: string[] = [];
+  for (const name of skillNames) {
+    const candidate = path.join(cwd, ".pi", "skills", name);
+    try {
+      if (fs.statSync(candidate).isDirectory()) hits.push(candidate);
+    } catch {}
+  }
+  return hits;
+}
+
+/** Build the notice text listing the conflicting paths and the recommendation. */
+export function staticConflictMessage(
+  conflictPaths: readonly string[],
+): string {
+  return [
+    "pi-openspec-x provides generated OpenSpec skills with the same names as static skill directories found in this project:",
+    "",
+    ...conflictPaths.map((conflictPath) => `- ${conflictPath}`),
+    "",
+    "The extension's skills are generated from the installed OpenSpec CLI and provided automatically; these static copies are redundant and may shadow or duplicate them. Consider removing the directories listed above (pi-openspec-x never deletes or modifies project files itself).",
+  ].join("\n");
+}
+
+export interface WarnStaticSkillConflictsOptions {
+  /**
+   * Send at most one notice per cwd for the lifetime of the passed memo set.
+   * Defaults to true; pass false to always re-check-and-send.
+   */
+  oncePerCwd?: boolean;
+  /** Memo set of cwds already warned about; owned by the caller. */
+  warned?: Set<string>;
+}
+
+/**
+ * Detect static same-name skills under `cwd` and, when found, send one
+ * custom-message notice through `pi.sendMessage`. Returns true when a notice
+ * was sent. Best-effort: sendMessage failures are swallowed.
+ */
+export function warnStaticSkillConflicts(
+  pi: Pick<ExtensionAPI, "sendMessage">,
+  cwd: string,
+  options: WarnStaticSkillConflictsOptions = {},
+): boolean {
+  const conflictPaths = findStaticSkillConflicts(cwd);
+  if (conflictPaths.length === 0) return false;
+  if (options.oncePerCwd !== false) {
+    if (options.warned?.has(cwd)) return false;
+    options.warned?.add(cwd);
+  }
+  try {
+    pi.sendMessage(
+      {
+        customType: STATIC_CONFLICT_CUSTOM_TYPE,
+        content: staticConflictMessage(conflictPaths),
+        display: true,
+      },
+      { deliverAs: "followUp" },
+    );
+  } catch {
+    // Notification is best-effort; never break discovery.
+  }
+  return true;
+}