@fission-ai/openspec 1.6.0-beta.1 → 1.7.0

package/dist/utils/spec-discovery.js

@@ -0,0 +1,102 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+/**
+ * Recursively discover every `spec.md` under a specs root, so both the flat
+ * `specs/<id>/spec.md` layout and nested `specs/<area>/<id>/spec.md` layouts
+ * are found (#1353). A `spec.md` sitting directly in the root is ignored,
+ * matching the historical requirement that specs live in a capability folder.
+ * Dot-directories are skipped and symlinked directories are not followed.
+ * A symlinked `spec.md` IS resolved: `hasAnyFileUnder` and the artifact
+ * graph's globs both count it as content, so dropping it here would silently
+ * lose the delta on archive; a dangling link is skipped. Results are sorted
+ * by id for deterministic output.
+ *
+ * A missing root (ENOENT) yields an empty list, but any other read failure
+ * (EACCES, EIO, ...) is thrown rather than swallowed: since this feeds the
+ * archive/apply merge path, silently dropping an unreadable capability would
+ * recreate the exact data-loss class #1353 is closing.
+ */
+export async function discoverSpecFiles(specsRoot) {
+    const results = [];
+    const walk = async (dir, segments) => {
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch (err) {
+            if (err?.code === 'ENOENT')
+                return;
+            throw err;
+        }
+        for (const entry of entries) {
+            if (entry.name.startsWith('.'))
+                continue;
+            if (entry.isDirectory()) {
+                await walk(path.join(dir, entry.name), [...segments, entry.name]);
+            }
+            else if (entry.name === 'spec.md' && segments.length > 0) {
+                if (entry.isFile()) {
+                    results.push({ id: segments.join('/'), specFile: path.join(dir, entry.name) });
+                }
+                else if (entry.isSymbolicLink()) {
+                    const specFile = path.join(dir, entry.name);
+                    try {
+                        if ((await fs.stat(specFile)).isFile()) {
+                            results.push({ id: segments.join('/'), specFile });
+                        }
+                    }
+                    catch (err) {
+                        // A dangling link is not content; anything else fails loudly.
+                        if (err?.code !== 'ENOENT')
+                            throw err;
+                    }
+                }
+            }
+        }
+    };
+    await walk(specsRoot, []);
+    // Plain code-point comparison, not localeCompare: the latter follows the
+    // process's ICU locale, so ordering could vary by OS/CI. Code-point ordering
+    // guarantees the deterministic output the docstring promises.
+    return results.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}
+/**
+ * True when any regular non-dot file exists anywhere under the given
+ * directory. Used by validate/archive to detect content under a change's
+ * specs/ that contradicts a declared skip_specs marker - including files that
+ * discoverSpecFiles ignores (a root spec.md, stray non-spec.md notes), since
+ * anything there would be silently dropped or misread while the change claims
+ * to have nothing. Dot entries (.DS_Store, .gitkeep, dot-directories) are
+ * skipped to match discoverSpecFiles - they are invisible to every other
+ * code path, so they must not count as spec content. Symlinks DO count
+ * (without being followed): the artifact graph's globs follow them, so a
+ * symlinked spec would read as existing content while the change claims to
+ * have none - it contradicts the marker like any regular file. A missing
+ * directory returns false; other read failures are thrown for the caller to
+ * decide.
+ */
+export async function hasAnyFileUnder(dirPath) {
+    let entries;
+    try {
+        entries = await fs.readdir(dirPath, { withFileTypes: true });
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT') {
+            return false;
+        }
+        throw err;
+    }
+    for (const entry of entries) {
+        if (entry.name.startsWith('.')) {
+            continue;
+        }
+        if (entry.isFile() || entry.isSymbolicLink()) {
+            return true;
+        }
+        if (entry.isDirectory() && (await hasAnyFileUnder(path.join(dirPath, entry.name)))) {
+            return true;
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=spec-discovery.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fission-ai/openspec",
-  "version": "1.6.0-beta.1",
+  "version": "1.7.0",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "openspec",
@@ -17,7 +17,6 @@
   "license": "MIT",
   "author": "OpenSpec Contributors",
   "type": "module",
-  "packageManager": "pnpm@9.15.9",
   "publishConfig": {
     "access": "public"
   },
@@ -39,9 +38,36 @@
     "!dist/**/__tests__",
     "!dist/**/*.map"
   ],
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "devDependencies": {
+    "@changesets/changelog-github": "^0.7.0",
+    "@changesets/cli": "^2.31.1",
+    "@types/node": "^20.19.43",
+    "@vitest/ui": "^3.2.6",
+    "eslint": "^10.5.0",
+    "smol-toml": "^1.7.1",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.65.0",
+    "vitest": "^3.2.6"
+  },
+  "dependencies": {
+    "@inquirer/core": "^10.3.2",
+    "@inquirer/prompts": "^7.10.1",
+    "chalk": "^5.6.2",
+    "commander": "^14.0.0",
+    "cross-spawn": "7.0.6",
+    "fast-glob": "^3.3.3",
+    "ora": "^9.4.1",
+    "yaml": "^2.8.3",
+    "zod": "^4.4.3"
+  },
   "scripts": {
     "lint": "eslint src/",
     "build": "node build.js",
+    "generate:skills": "node scripts/generate-skillssh.mjs",
+    "regen:parity-hashes": "node scripts/regen-parity-hashes.mjs",
     "dev": "tsc --watch",
     "dev:cli": "pnpm build && node bin/openspec.js",
     "test": "vitest run",
@@ -49,37 +75,10 @@
     "test:ui": "vitest --ui",
     "test:coverage": "vitest --coverage",
     "test:postinstall": "node scripts/postinstall.js",
-    "prepare": "pnpm run build",
-    "prepublishOnly": "pnpm run build",
     "postinstall": "node scripts/postinstall.js",
     "check:pack-version": "node scripts/pack-version-check.mjs",
     "release": "pnpm run release:ci",
     "release:ci": "pnpm run check:pack-version && pnpm exec changeset publish",
     "changeset": "changeset"
-  },
-  "engines": {
-    "node": ">=20.19.0"
-  },
-  "devDependencies": {
-    "@changesets/changelog-github": "^0.5.2",
-    "@changesets/cli": "^2.27.7",
-    "@types/node": "^24.2.0",
-    "@vitest/ui": "^3.2.6",
-    "eslint": "^9.39.2",
-    "typescript": "^5.9.3",
-    "typescript-eslint": "^8.62.0",
-    "vitest": "^3.2.6"
-  },
-  "dependencies": {
-    "@inquirer/core": "^10.3.2",
-    "@inquirer/prompts": "^7.10.1",
-    "chalk": "^5.5.0",
-    "commander": "^14.0.0",
-    "cross-spawn": "7.0.6",
-    "fast-glob": "^3.3.3",
-    "ora": "^8.2.0",
-    "posthog-node": "^5.20.0",
-    "yaml": "^2.8.2",
-    "zod": "^4.0.17"
   }
-}
+}

package/schemas/spec-driven/schema.yaml

@@ -21,6 +21,14 @@ artifacts:
       proposal and specs phases. Research existing specs before filling this in.
       Each capability listed here will need a corresponding spec file.
 
+      Every change must either declare at least one capability (new or
+      modified) or explicitly opt out of specs: `openspec validate` rejects a
+      change with zero deltas unless the change's `.openspec.yaml` sets
+      `skip_specs: true`. Use `skip_specs: true` only when no spec-level
+      behavior changes (pure refactor, tooling, docs) - specs describe
+      behavior, so if behavior does not change, no spec should change either.
+      Do not invent a requirement just to satisfy validation.
+
       Keep it concise (1-2 pages). Focus on the "why" not the "how" -
       implementation details belong in design.md.
 
@@ -34,10 +42,32 @@ artifacts:
     instruction: |
       Create specification files that define WHAT the system should do.
 
+      A spec is a behavior contract, not an implementation plan.
+
+      Good spec content:
+      - Observable behavior users or downstream systems rely on
+      - Inputs, outputs, and error conditions
+      - External constraints (security, privacy, reliability, compatibility)
+      - Scenarios that can be tested or explicitly validated
+
+      Avoid in specs:
+      - Internal class/function names
+      - Library or framework choices
+      - Step-by-step implementation details
+      - Detailed execution plans (those belong in design.md or tasks.md)
+
+      Quick test: if the implementation can change without changing externally
+      visible behavior, it likely does not belong in the spec.
+
       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.
 
+      There must be at least one spec file unless the change's `.openspec.yaml`
+      sets `skip_specs: true` (no spec-level behavior change) - `openspec validate`
+      rejects a zero-delta change without that marker. If the proposal lists no
+      capabilities and `skip_specs` is not set, revisit the proposal first.
+
       Delta operations (use ## headers):
       - **ADDED Requirements**: New capabilities
       - **MODIFIED Requirements**: Changed behavior - MUST include full updated content
@@ -51,6 +81,16 @@ artifacts:
       - **CRITICAL**: Scenarios MUST use exactly 4 hashtags (`####`). Using 3 hashtags or bullets will fail silently.
       - Every requirement MUST have at least one scenario.
 
+      New capabilities only: start the delta spec with a `## Purpose` section -
+      one or two sentences (50+ characters, or `openspec validate --strict`
+      reports it as too brief) describing what the capability is for. Archive
+      copies it into the main spec it creates; without it the new main spec is
+      left with a `TBD ... Update Purpose after archive` placeholder to fill in
+      by hand. Do NOT add `## Purpose` to a delta for an existing capability -
+      that spec already has one and the delta's is ignored. To change an
+      existing capability's Purpose - including a leftover `TBD` placeholder -
+      edit `openspec/specs/<capability>/spec.md` directly.
+
       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)
@@ -60,8 +100,12 @@ artifacts:
       Common pitfall: Using MODIFIED with partial content loses detail at archive time.
       If adding new concerns without changing existing behavior, use ADDED instead.
 
-      Example:
+      Example (a new capability, so it opens with `## Purpose`):
       ```
+      ## Purpose
+
+      Lets users take their data out of the product in a portable format.
+
       ## ADDED Requirements
 
       ### Requirement: User can export data
@@ -96,15 +140,22 @@ artifacts:
       - 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
+      - **Context**: Only the current state and constraints needed to explain the approach. Reference the proposal for motivation instead of restating it (e.g., "See proposal.md - Why").
+      - **Goals / Non-Goals**: What this design achieves and explicitly excludes. Don't restate the proposal's scope - add only design-level boundaries.
       - **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] → Mitigation
       - **Migration Plan**: Steps to deploy, rollback strategy (if applicable)
-      - **Open Questions**: Outstanding decisions or unknowns to resolve
+      - **Open Questions**: Unknowns that can safely be answered later without
+        changing the specs, the approach, or the task breakdown. Omit if none.
+
+      Open questions are for genuinely deferrable unknowns, not decisions you
+      skipped. If a question would change the specs, the chosen approach, or
+      the task breakdown, resolve it now - ask the user instead of guessing.
 
       Focus on architecture and approach, not line-by-line implementation.
-      Reference the proposal for motivation and specs for requirements.
+      The proposal covers why and what; design covers how. Reference the
+      proposal for motivation and, once written, the specs for requirements -
+      if a section would only restate them, point to them instead.
 
       Good design docs explain the "why" behind technical decisions.
     requires:
@@ -117,6 +168,10 @@ artifacts:
     instruction: |
       Create the task list that breaks down the implementation work.
 
+      Before writing tasks, check design.md for Open Questions. If any of them
+      would change what gets built, resolve them with the user first - do not
+      bake an unstated assumption into the task list.
+
       **IMPORTANT: Follow the template below exactly.** The apply phase parses
       checkbox format to track progress. Tasks not using `- [ ]` won't be tracked.
 

package/schemas/spec-driven/templates/design.md

@@ -1,6 +1,6 @@
 ## Context
 
-<!-- Background and current state -->
+<!-- Current state and constraints that shape the approach. See proposal.md for motivation - don't restate it -->
 
 ## Goals / Non-Goals
 
@@ -12,7 +12,7 @@
 
 ## Decisions
 
-<!-- Key design decisions and rationale -->
+<!-- Key design decisions with rationale and alternatives considered -->
 
 ## Risks / Trade-offs
 

package/schemas/spec-driven/templates/proposal.md

@@ -15,7 +15,11 @@
 ### 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. -->
+     Use existing spec names from openspec/specs/. Leave empty if no requirement
+     changes. A change with no capabilities at all (pure refactor, tooling, docs)
+     must set `skip_specs: true` in its .openspec.yaml - openspec validate rejects
+     a zero-delta change without that marker. Do not invent a requirement just to
+     satisfy validation. -->
 - `<existing-name>`: <what requirement is changing>
 
 ## Impact

package/schemas/spec-driven/templates/spec.md

@@ -1,3 +1,6 @@
+## Purpose
+<!-- New capabilities only: one or two sentences (50+ characters) on what this capability is for. Delete this section for an existing capability. -->
+
 ## ADDED Requirements
 
 ### Requirement: <!-- requirement name -->

package/dist/core/command-generation/adapters/codex.d.ts

@@ -1,16 +0,0 @@
-/**
- * Codex Command Adapter
- *
- * Formats commands for Codex following its frontmatter specification.
- * Codex custom prompts live in the global home directory (~/.codex/prompts/)
- * and are not shared through the repository. The CODEX_HOME env var can
- * override the default ~/.codex location.
- */
-import type { ToolCommandAdapter } from '../types.js';
-/**
- * Codex adapter for command generation.
- * File path: <CODEX_HOME>/prompts/opsx-<id>.md (absolute, global)
- * Frontmatter: description, argument-hint
- */
-export declare const codexAdapter: ToolCommandAdapter;
-//# sourceMappingURL=codex.d.ts.map

package/dist/core/command-generation/adapters/codex.js

@@ -1,39 +0,0 @@
-/**
- * Codex Command Adapter
- *
- * Formats commands for Codex following its frontmatter specification.
- * Codex custom prompts live in the global home directory (~/.codex/prompts/)
- * and are not shared through the repository. The CODEX_HOME env var can
- * override the default ~/.codex location.
- */
-import os from 'os';
-import path from 'path';
-/**
- * Returns the Codex home directory.
- * Respects the CODEX_HOME env var, defaulting to ~/.codex.
- */
-function getCodexHome() {
-    const envHome = process.env.CODEX_HOME?.trim();
-    return path.resolve(envHome ? envHome : path.join(os.homedir(), '.codex'));
-}
-/**
- * Codex adapter for command generation.
- * File path: <CODEX_HOME>/prompts/opsx-<id>.md (absolute, global)
- * Frontmatter: description, argument-hint
- */
-export const codexAdapter = {
-    toolId: 'codex',
-    getFilePath(commandId) {
-        return path.join(getCodexHome(), 'prompts', `opsx-${commandId}.md`);
-    },
-    formatFile(content) {
-        return `---
-description: ${content.description}
-argument-hint: command arguments
----
-
-${content.body}
-`;
-    },
-};
-//# sourceMappingURL=codex.js.map

package/dist/core/command-generation/adapters/windsurf.d.ts

@@ -1,14 +0,0 @@
-/**
- * Windsurf Command Adapter
- *
- * Formats commands for Windsurf following its frontmatter specification.
- * Windsurf uses a similar format to Claude but may have different conventions.
- */
-import type { ToolCommandAdapter } from '../types.js';
-/**
- * Windsurf adapter for command generation.
- * File path: .windsurf/workflows/opsx-<id>.md
- * Frontmatter: name, description, category, tags
- */
-export declare const windsurfAdapter: ToolCommandAdapter;
-//# sourceMappingURL=windsurf.d.ts.map

package/dist/core/command-generation/adapters/windsurf.js

@@ -1,38 +0,0 @@
-/**
- * Windsurf Command Adapter
- *
- * Formats commands for Windsurf following its frontmatter specification.
- * Windsurf uses a similar format to Claude but may have different conventions.
- */
-import path from 'path';
-import { escapeYamlValue } from '../yaml.js';
-/**
- * Formats a tags array as a YAML array with proper escaping.
- */
-function formatTagsArray(tags) {
-    const escapedTags = tags.map((tag) => escapeYamlValue(tag));
-    return `[${escapedTags.join(', ')}]`;
-}
-/**
- * Windsurf adapter for command generation.
- * File path: .windsurf/workflows/opsx-<id>.md
- * Frontmatter: name, description, category, tags
- */
-export const windsurfAdapter = {
-    toolId: 'windsurf',
-    getFilePath(commandId) {
-        return path.join('.windsurf', 'workflows', `opsx-${commandId}.md`);
-    },
-    formatFile(content) {
-        return `---
-name: ${escapeYamlValue(content.name)}
-description: ${escapeYamlValue(content.description)}
-category: ${escapeYamlValue(content.category)}
-tags: ${formatTagsArray(content.tags)}
----
-
-${content.body}
-`;
-    },
-};
-//# sourceMappingURL=windsurf.js.map