opensdd 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,79 @@
+<p align="center">
+  <b>OpenSDD</b>
+</p>
+
+<p align="center">
+  <b>--Open Spec-Driven Development--</b>
+</p>
+
+---
+
+AI agents are great at writing code, but they need to know *what* to build. OpenSDD is a protocol and CLI for writing, sharing, and consuming **behavioral specs** — language-agnostic contracts that tell agents what software should do, without dictating how.
+
+Think of it like a package manager, but for specifications instead of code.
+
+```bash
+npm install -g opensdd
+
+# Initialize OpenSDD in your project
+opensdd init
+
+# Install a spec from the registry
+opensdd install slugify
+```
+
+Then tell your coding agent: "implement the slugify spec" — it reads the spec, writes the code, and generates tests.
+
+## How It Works
+
+1. **Write a spec** — Define what your software does in `opensdd/spec.md` using a simple markdown format with behavioral contracts, edge cases, and invariants.
+2. **Share it** — Publish your spec to a registry with `opensdd publish`. Others can install it with `opensdd install`.
+3. **Implement it** — Your AI agent reads the spec and generates a bespoke implementation in whatever language and framework your project uses.
+
+Specs are the source of truth. Code flows from the spec, not the other way around.
+
+## Features
+
+- **Language-agnostic specs** — One spec, any implementation. The same spec produces TypeScript, Python, Rust, or whatever your project needs.
+- **Registry & versioning** — Publish, install, and update specs with semver. Updates produce changesets so your agent knows exactly what changed.
+- **Multi-agent support** — Skills auto-install for Claude Code, Codex CLI, Cursor, GitHub Copilot, Gemini CLI, and Amp.
+- **Deviations** — Need to diverge from a spec? Document it formally instead of silently drifting.
+- **Spec dependencies** — Specs can reference other specs for shared types and contracts.
+
+## Quick Example
+
+A spec (`spec.md`) looks like this:
+
+```markdown
+# slugify
+
+> Converts a string into a URL-friendly slug.
+
+## Behavioral Contract
+
+### Core Behavior
+
+Accepts a string and returns a lowercase, hyphen-separated slug.
+
+- `slugify("Hello World")` MUST return `"hello-world"`
+- `slugify("Déjà Vu")` MUST return `"deja-vu"`
+
+## Invariants
+
+- For any string `x`: `slugify(slugify(x)) === slugify(x)` (idempotent)
+```
+
+## Documentation
+
+- [Spec Format](opensdd/spec-format.md) — How to write specs
+- [CLI Reference](opensdd/cli.md) — All CLI commands
+- [SDD Manager Skill](opensdd/sdd-manager.md) — How agents implement and verify specs
+- [SDD Generate Skill](opensdd/sdd-generate.md) — How agents generate specs from existing code
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and workflows.
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.

package/opensdd/cli.md

@@ -81,38 +81,38 @@ Initialized OpenSDD:
 
 ### Skill Installation Mapping
 
-`opensdd init` installs both skills (sdd-manager and sdd-generate) into the native configuration format of each supported coding agent. The canonical skill content is authored as markdown source files (`sdd-manager.md`, `sdd-generate.md`, `spec-format.md`). The CLI transforms these into each agent's expected format during installation.
+`opensdd init` installs both skills (sdd-manager and sdd-generate) into the native configuration format of each supported coding agent. The canonical skill content is authored as markdown source files in `opensdd/skills/` (`skills/sdd-manager.md`, `skills/sdd-generate.md`) and `opensdd/` (`spec-format.md`). Source skill files use Agent Skills frontmatter (`name`, `description`) which the CLI parses and transforms per-agent format during installation.
 
 All installed skill files are **spec-owned** — they are overwritten on every `opensdd init` and MUST NOT be edited by the user.
 
 #### Claude Code (Agent Skills standard)
 
-Each skill is a directory with a `SKILL.md` and a `references/` subdirectory. Claude Code auto-discovers skills in `.claude/skills/`.
+Each skill is a directory with a `SKILL.md` and a `references/` subdirectory. Claude Code auto-discovers skills in `.claude/skills/`. The `SKILL.md` files include Agent Skills frontmatter with `name` and `description` fields, copied as-is from the source skill files.
 
 ```
 .claude/skills/
   sdd-manager/
-    SKILL.md                    ← sdd-manager.md
+    SKILL.md                    ← skills/sdd-manager.md
     references/
       spec-format.md            ← spec-format.md
   sdd-generate/
-    SKILL.md                    ← sdd-generate.md
+    SKILL.md                    ← skills/sdd-generate.md
     references/
       spec-format.md            ← spec-format.md
 ```
 
 #### OpenAI Codex CLI (Agent Skills standard)
 
-Codex CLI follows the same Agent Skills standard but discovers skills in `.agents/skills/`.
+Codex CLI follows the same Agent Skills standard but discovers skills in `.agents/skills/`. The `SKILL.md` files include Agent Skills frontmatter with `name` and `description` fields, copied as-is from the source skill files.
 
 ```
 .agents/skills/
   sdd-manager/
-    SKILL.md                    ← sdd-manager.md
+    SKILL.md                    ← skills/sdd-manager.md
     references/
       spec-format.md            ← spec-format.md
   sdd-generate/
-    SKILL.md                    ← sdd-generate.md
+    SKILL.md                    ← skills/sdd-generate.md
     references/
       spec-format.md            ← spec-format.md
 ```
@@ -123,9 +123,9 @@ Cursor discovers rules as `.md` or `.mdc` files in `.cursor/rules/`. Each skill
 
 ```
 .cursor/rules/
-  sdd-manager.md                ← sdd-manager.md with frontmatter
-  sdd-generate.md               ← sdd-generate.md with frontmatter
-  opensdd-spec-format.md        ← spec-format.md with frontmatter
+  sdd-manager.md                ← skills/sdd-manager.md with Cursor frontmatter
+  sdd-generate.md               ← skills/sdd-generate.md with Cursor frontmatter
+  opensdd-spec-format.md        ← spec-format.md with Cursor frontmatter
 ```
 
 Frontmatter for `sdd-manager.md`:
@@ -158,15 +158,32 @@ Copilot discovers instructions as `.instructions.md` files in `.github/instructi
 
 ```
 .github/instructions/
-  sdd-manager.instructions.md   ← sdd-manager.md with frontmatter
-  sdd-generate.instructions.md  ← sdd-generate.md with frontmatter
-  opensdd-spec-format.instructions.md  ← spec-format.md with frontmatter
+  sdd-manager.instructions.md   ← skills/sdd-manager.md with Copilot frontmatter
+  sdd-generate.instructions.md  ← skills/sdd-generate.md with Copilot frontmatter
+  opensdd-spec-format.instructions.md  ← spec-format.md with Copilot frontmatter
 ```
 
-Frontmatter for each file:
+Frontmatter for `sdd-manager.instructions.md`:
 ```yaml
 ---
 applyTo: "**"
+description: "Implement, update, and verify installed OpenSDD dependency specs. Use when the user asks to implement a spec, process a spec update, check conformance, or create a deviation."
+---
+```
+
+Frontmatter for `sdd-generate.instructions.md`:
+```yaml
+---
+applyTo: "**"
+description: "Generate an OpenSDD behavioral spec from existing code. Use when the user asks to generate, create, or extract a spec from a repository or codebase."
+---
+```
+
+Frontmatter for `opensdd-spec-format.instructions.md`:
+```yaml
+---
+applyTo: "**"
+description: "OpenSDD spec format reference. Defines the structure and rules for behavioral specifications. Referenced by sdd-manager and sdd-generate skills."
 ---
 ```
 

package/opensdd/{sdd-generate.md → skills/sdd-generate.md}

@@ -1,3 +1,7 @@
+---
+name: sdd-generate
+description: "Generate an OpenSDD behavioral spec from existing code. Use when the user asks to generate, create, or extract a spec from a repository or codebase."
+---
 # SDD Generate
 
 > Guides an AI agent through analyzing a repository and generating a behavioral spec in the OpenSDD format.
@@ -12,7 +16,7 @@ Before starting, you need:
 
 1. A **target repository** — a GitHub URL or local path provided by the user.
 2. A **scope** — which capability, module, or function to spec. If the user provides a whole-repo URL without scoping, ask them to narrow it before proceeding. A spec for "the entire lodash library" is not useful. A spec for "lodash's string slugification" is.
-3. The **spec-format reference** — read [spec-format.md](spec-format.md) to understand the required output structure.
+3. The **spec-format reference** — read [spec-format.md](../spec-format.md) to understand the required output structure.
 4. A **working directory** — confirm with the user where the generated spec should be written. If the project has `opensdd.json`, use the directory specified by `specs_dir` (default: `opensdd/`). If the project is not yet initialized, ask the user where to output the spec — a common default is `opensdd/` in the current project root. The agent does not need `opensdd.json` to exist before generating a spec.
 
 ## Output
@@ -153,7 +157,7 @@ Always update `_notes/gaps.md` at the end of each pass with what still needs to
 - The full `spec.md` draft
 - `_notes/inventory.md` — verify every public API item is covered
 - `_notes/gaps.md` — verify no critical gaps remain
-- [spec-format.md](spec-format.md) — verify structural compliance
+- [spec-format.md](../spec-format.md) — verify structural compliance
 
 **Write:**
 - `spec.md` — add or complete:

package/opensdd/{sdd-manager.md → skills/sdd-manager.md}

@@ -1,3 +1,7 @@
+---
+name: sdd-manager
+description: "Implement, update, and verify installed OpenSDD dependency specs. Use when the user asks to implement a spec, process a spec update, check conformance, or create a deviation."
+---
 # SDD Manager
 
 > Teaches agents how to implement, update, and verify installed dependency specs in an OpenSDD-compliant project.

package/opensdd/spec-format.md

@@ -440,11 +440,11 @@ This is a transient artifact. `opensdd update apply` reads this file, applies th
 
 ### SDD-Manager Skill
 
-The sdd-manager skill teaches agents how to implement, update, and verify installed dependency specs. It is installed once per project via `opensdd init` alongside the sdd-generate skill, into each supported agent's configuration directory. See [sdd-manager.md](sdd-manager.md) for the full skill workflow, including implementation defaults, the project conventions check, and the verification protocol.
+The sdd-manager skill teaches agents how to implement, update, and verify installed dependency specs. It is installed once per project via `opensdd init` alongside the sdd-generate skill, into each supported agent's configuration directory. See [sdd-manager.md](skills/sdd-manager.md) for the full skill workflow, including implementation defaults, the project conventions check, and the verification protocol.
 
 ### SDD-Generate Skill
 
-The sdd-generate skill teaches agents how to generate a spec from existing code. See [sdd-generate.md](sdd-generate.md) for the full skill workflow.
+The sdd-generate skill teaches agents how to generate a spec from existing code. See [sdd-generate.md](skills/sdd-generate.md) for the full skill workflow.
 
 ### Versioning
 

package/opensdd/spec.md

@@ -0,0 +1,88 @@
+# OpenSDD
+
+> A protocol, CLI, and agent skills for spec-driven development — write behavioral specs, share them via a registry, and let AI agents generate bespoke implementations.
+
+## Version
+
+0.1.0
+
+## Overview
+
+OpenSDD (Open Spec-Driven Development) treats behavioral specifications as the source of truth for software. A spec defines **what** software does and **what constraints** it must satisfy, while leaving **how** it is implemented to the consuming agent. Specs are language-agnostic by default — the same spec can produce implementations in any language or framework.
+
+The system has four components:
+
+- **[Spec Format](spec-format.md)** — The standard format for behavioral specifications. Defines spec structure, the `opensdd.json` manifest, the registry layout, and the protocol rules that all other components depend on.
+- **[CLI](cli.md)** — A Node.js command-line tool (`opensdd`) that initializes projects, installs and updates specs from a registry, publishes authored specs, and installs agent skills.
+- **[SDD Manager](sdd-manager.md)** — A skill installed into coding agents that teaches them how to implement, update, verify, and deviate from installed dependency specs.
+- **[SDD Generate](sdd-generate.md)** — A skill installed into coding agents that teaches them how to generate a behavioral spec from an existing codebase.
+
+## Behavioral Contract
+
+### Spec Authoring
+
+A project authors a spec by placing a `spec.md` in its `opensdd/` directory (configurable via `opensdd.json`). The spec MUST contain an H1 header with a blockquote summary and a `## Behavioral Contract` section. The author MAY include supplementary files in the same directory; all supplementary files MUST be reachable by following links from `spec.md`.
+
+Development is spec-first: behavior changes start in the spec, then code is updated to match.
+
+See [Spec Format](spec-format.md) for the full format definition, required and recommended sections, and inline example conventions.
+
+### Spec Distribution
+
+Specs are distributed via a registry — a versioned store of published specs. The default registry is the `registry/` directory in the OpenSDD GitHub repository.
+
+- `opensdd publish` packages the authored spec and opens a PR against the registry.
+- `opensdd install <name>` fetches a spec from the registry and places it in `.opensdd.deps/<name>/`.
+- `opensdd update [name]` pulls newer versions and stages changesets for the agent to process.
+
+Installed spec files are spec-owned and MUST NOT be edited by the consumer. The `.opensdd.deps/` directory MUST be committed to the repo.
+
+See [CLI](cli.md) for the full command reference, registry source resolution, and update staging behavior.
+
+### Spec Implementation
+
+When a consumer installs a spec, their AI agent implements it using the sdd-manager skill. The agent reads the spec, checks project conventions (language, framework, test runner), generates an implementation, and runs a verification protocol that includes both a test suite and a spec compliance audit.
+
+The agent MUST NOT implement or modify code based on an OpenSDD spec outside of the workflows defined by the sdd-manager skill.
+
+See [SDD Manager](sdd-manager.md) for the implementation, update, conformance check, and deviation workflows.
+
+### Spec Generation
+
+The sdd-generate skill teaches agents to generate a behavioral spec from an existing codebase via a multi-pass, artifact-driven strategy. The generated spec follows the spec format and is written to `opensdd/spec.md`.
+
+See [SDD Generate](sdd-generate.md) for the multi-pass strategy, prerequisites, and output format.
+
+### Agent Skill Installation
+
+`opensdd init` installs both skills (sdd-manager and sdd-generate) into the native configuration format of each supported coding agent:
+
+- **Claude Code** — `.claude/skills/<name>/SKILL.md` with `references/`
+- **OpenAI Codex CLI** — `.agents/skills/<name>/SKILL.md` with `references/`
+- **Cursor** — `.cursor/rules/<name>.md` with YAML frontmatter
+- **GitHub Copilot** — `.github/instructions/<name>.instructions.md` with YAML frontmatter
+- **Gemini CLI** — `GEMINI.md` with `@` imports to canonical skill files
+- **Amp** — `AGENTS.md` with `@` references to canonical skill files
+
+All skill files are spec-owned and overwritten on every `opensdd init`. The Claude Code installation serves as the canonical source that Gemini CLI and Amp reference.
+
+See [CLI — Skill Installation Mapping](cli.md#skill-installation-mapping) for the full mapping and installation rules.
+
+## NOT Specified (Implementation Freedom)
+
+- The internal prompting strategy of the sdd-manager and sdd-generate skills
+- How agents discover skills (defined by each agent's native mechanism)
+- The specific testing framework or test runner (determined by the consumer's project)
+- How agents generate implementations (model choice, temperature, etc.)
+- The transport mechanism for fetching specs from a registry (defined by the CLI)
+- File encoding (assumed UTF-8)
+
+## Invariants
+
+- A spec MUST always contain an H1 header with blockquote summary and a `## Behavioral Contract` section
+- Spec-owned files in `.opensdd.deps/` MUST NOT be modified by the consumer
+- `deviations.md` MUST NOT be created, modified, or deleted by the CLI or any automated tooling
+- Consumer-managed `opensdd.json` fields MUST survive all update operations
+- The `.opensdd.deps/` directory MUST be committed to the repo
+- Publishing MUST NOT allow overwriting an existing version in the registry
+- All supplementary files in a spec directory MUST be reachable by following links from `spec.md`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opensdd",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "The official OpenSDD (Open Spec-Driven Development) CLI, spec, and spec registry",
   "type": "module",
   "bin": {
@@ -28,4 +28,4 @@
   "dependencies": {
     "diff": "^7.0.0"
   }
-}
+}

package/src/commands/publish.js

@@ -145,14 +145,13 @@ export async function publishCommand(options) {
   }
 
   const { owner, repo } = parseGitHubUrl(registrySource);
-  const repoUrl = `https://github.com/${owner}/${repo}.git`;
 
   // Step 10: Clone, create branch, add files, push, create PR
   const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'opensdd-publish-'));
 
   try {
-    // Clone
-    execSync(`git clone --depth 1 "${repoUrl}" "${tmpDir}"`, { stdio: 'pipe' });
+    // Clone using gh to respect the user's configured git protocol (ssh vs https)
+    execSync(`gh repo clone "${owner}/${repo}" "${tmpDir}" -- --depth 1`, { stdio: 'pipe' });
 
     // Create branch
     execSync(`git checkout -b "${branchName}"`, { cwd: tmpDir, stdio: 'pipe' });

package/src/lib/skills.js

@@ -8,11 +8,30 @@ const __dirname = path.dirname(__filename);
 const OPENSDD_SECTION_START = '<!-- OpenSDD Skills (managed by opensdd init \u2014 do not edit this section) -->';
 const OPENSDD_SECTION_END = '<!-- /OpenSDD Skills -->';
 
+function parseFrontmatter(content) {
+  if (!content.startsWith('---\n')) return { frontmatter: {}, body: content };
+  const endIdx = content.indexOf('\n---\n', 4);
+  if (endIdx === -1) return { frontmatter: {}, body: content };
+
+  const yamlStr = content.substring(4, endIdx);
+  const body = content.substring(endIdx + 5);
+
+  const frontmatter = {};
+  for (const line of yamlStr.split('\n')) {
+    const match = line.match(/^(\w+):\s*"([^"]*)"\s*$/) || line.match(/^(\w+):\s*(.*?)\s*$/);
+    if (match) {
+      frontmatter[match[1]] = match[2];
+    }
+  }
+  return { frontmatter, body };
+}
+
 function getSkillContent() {
   const opensddDir = path.resolve(__dirname, '../../opensdd');
+  const skillsDir = path.join(opensddDir, 'skills');
   return {
-    sddManager: fs.readFileSync(path.join(opensddDir, 'sdd-manager.md'), 'utf-8'),
-    sddGenerate: fs.readFileSync(path.join(opensddDir, 'sdd-generate.md'), 'utf-8'),
+    sddManager: fs.readFileSync(path.join(skillsDir, 'sdd-manager.md'), 'utf-8'),
+    sddGenerate: fs.readFileSync(path.join(skillsDir, 'sdd-generate.md'), 'utf-8'),
     specFormat: fs.readFileSync(path.join(opensddDir, 'spec-format.md'), 'utf-8'),
   };
 }
@@ -121,19 +140,22 @@ export function installSkills(projectRoot) {
     const cursorBase = path.join(projectRoot, '.cursor', 'rules');
     ensureDir(cursorBase);
 
+    const { frontmatter: managerFm, body: managerBody } = parseFrontmatter(skills.sddManager);
+    const { frontmatter: generateFm, body: generateBody } = parseFrontmatter(skills.sddGenerate);
+
     const sddManagerCursor = `---
-description: "Implement, update, and verify installed OpenSDD dependency specs. Use when the user asks to implement a spec, process a spec update, check conformance, or create a deviation."
+description: "${managerFm.description}"
 alwaysApply: false
 ---
 
-${skills.sddManager}`;
+${managerBody}`;
 
     const sddGenerateCursor = `---
-description: "Generate an OpenSDD behavioral spec from existing code. Use when the user asks to generate, create, or extract a spec from a repository or codebase."
+description: "${generateFm.description}"
 alwaysApply: false
 ---
 
-${skills.sddGenerate}`;
+${generateBody}`;
 
     const specFormatCursor = `---
 description: "OpenSDD spec format reference. Defines the structure and rules for behavioral specifications. Referenced by sdd-manager and sdd-generate skills."
@@ -154,23 +176,20 @@ ${skills.specFormat}`;
     const copilotBase = path.join(projectRoot, '.github', 'instructions');
     ensureDir(copilotBase);
 
-    const copilotFrontmatter = `---
-applyTo: "**"
----
-
-`;
+    const { frontmatter: managerFmCp, body: managerBodyCp } = parseFrontmatter(skills.sddManager);
+    const { frontmatter: generateFmCp, body: generateBodyCp } = parseFrontmatter(skills.sddGenerate);
 
     writeFileSync(
       path.join(copilotBase, 'sdd-manager.instructions.md'),
-      copilotFrontmatter + skills.sddManager
+      `---\napplyTo: "**"\ndescription: "${managerFmCp.description}"\n---\n\n${managerBodyCp}`
     );
     writeFileSync(
       path.join(copilotBase, 'sdd-generate.instructions.md'),
-      copilotFrontmatter + skills.sddGenerate
+      `---\napplyTo: "**"\ndescription: "${generateFmCp.description}"\n---\n\n${generateBodyCp}`
     );
     writeFileSync(
       path.join(copilotBase, 'opensdd-spec-format.instructions.md'),
-      copilotFrontmatter + skills.specFormat
+      `---\napplyTo: "**"\ndescription: "OpenSDD spec format reference. Defines the structure and rules for behavioral specifications. Referenced by sdd-manager and sdd-generate skills."\n---\n\n${skills.specFormat}`
     );
   } catch (err) {
     warnings.push(`Could not install GitHub Copilot skills: ${err.message}`);