opensdd 0.1.2 → 0.1.4

package/opensdd/cli.md

@@ -24,41 +24,68 @@ Prints usage information including the current version, available commands, and
 
 ### `opensdd init`
 
-Initializes the OpenSDD protocol in the current project.
+Initializes the OpenSDD protocol in the current project. Supports two modes:
 
-#### Behavior
-
-1. Verify the current directory is a project root (contains `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `.git`, `opensdd.json`, or similar project markers). If no project marker is found, warn the user and ask for confirmation to proceed.
-2. Install both skills (sdd-manager and sdd-generate) into all supported agent configuration directories. If already present, overwrite — skills are always spec-owned. The full installation mapping is defined in the **Skill Installation Mapping** section below.
-3. If `opensdd.json` does not exist at the project root, create it with default contents: `{ "opensdd": "0.1.0", "specs_dir": "opensdd", "deps_dir": ".opensdd.deps" }`. The `registry`, `publish`, and `dependencies` fields are intentionally omitted from the default — they are optional. When `registry` is absent, the CLI defaults to `https://github.com/deepagents-ai/opensdd` per the registry source resolution logic. If `opensdd.json` already exists, leave it untouched.
-4. Create the `opensdd/` directory (or the directory specified by `specs_dir` in an existing `opensdd.json`) if it does not exist.
-5. If `<specs_dir>/spec.md` does not exist, create a skeleton `spec.md` with placeholder sections:
-   ```markdown
-   # {project-name}
-
-   > TODO: One-line description of what this software does.
-
-   ## Behavioral Contract
+- **Consumer-only**: Install and implement dependency specs. Minimal footprint — only `sdd-manager` skill installed, no specs directory or skeleton `spec.md`.
+- **OpenSDD-driven**: Full SDD methodology adoption. Both skills installed, specs directory and skeleton `spec.md` created.
 
-   <!-- Define behaviors here. -->
+Mode detection: presence of `specsDir` in `opensdd.json` = OpenSDD-driven. Absence = consumer-only.
 
-   ## NOT Specified (Implementation Freedom)
-
-   <!-- List aspects left to the implementer's discretion. -->
-
-   ## Invariants
-
-   <!-- List properties that must hold true across all inputs and states. -->
-   ```
-   The `{project-name}` placeholder SHOULD be inferred from the nearest project manifest (e.g., `name` in `package.json`) or default to the directory name. If `spec.md` already exists, leave it untouched.
-6. Create the `.opensdd.deps/` directory (or the directory specified by `deps_dir` in an existing `opensdd.json`) if it does not exist.
-7. Print a success message.
+#### Behavior
 
-- `opensdd init` in a fresh project MUST produce the output below
-- `opensdd init` in a project that already has OpenSDD initialized MUST overwrite all skill installation files across all agent formats but MUST NOT overwrite `opensdd.json`
+1. Verify the current directory is a project root (contains `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `.git`, `opensdd.json`, or similar project markers). If no project marker is found, warn the user and ask for confirmation to proceed.
+2. Read existing `opensdd.json` if present.
+3. Determine mode:
+   - **Existing manifest with `specsDir`** (OpenSDD-driven re-init): `mode = 'full'`. No prompt.
+   - **Existing manifest without `specsDir`** (consumer re-init): prompt "Upgrade to OpenSDD-driven? (y/n)". If yes, add `specsDir` to manifest and `mode = 'full'`. If no, `mode = 'consumer'`.
+   - **No manifest** (fresh init): prompt "How will this project use OpenSDD?" with numbered choices:
+     1. Consumer only — install and implement dependency specs
+     2. OpenSDD-driven — full SDD methodology (author specs, both skills)
+   Create manifest accordingly.
+4. Install skills with the determined mode. In consumer mode, only `sdd-manager` is installed. In full mode, both `sdd-manager` and `sdd-generate` are installed. The full installation mapping is defined in the **Skill Installation Mapping** section below. If already present, overwrite — skills are always spec-owned.
+5. Create the `.opensdd.deps/` directory (or the directory specified by `depsDir` in an existing `opensdd.json`) if it does not exist. (Both modes.)
+6. If `mode === 'full'`:
+   a. If `opensdd.json` does not exist at the project root, create it with default contents: `{ "opensdd": "0.1.0", "specsDir": "opensdd", "depsDir": ".opensdd.deps" }`. The `registry`, `publish`, and `dependencies` fields are intentionally omitted from the default — they are optional. When `registry` is absent, the CLI defaults to `https://github.com/deepagents-ai/opensdd` per the registry source resolution logic. If `opensdd.json` already exists, leave it untouched.
+   b. Create the `opensdd/` directory (or the directory specified by `specsDir` in the `opensdd.json`) if it does not exist.
+   c. If `<specsDir>/spec.md` does not exist, create a skeleton `spec.md` with placeholder sections:
+      ```markdown
+      # {project-name}
+
+      > TODO: One-line description of what this software does.
+
+      ## Behavioral Contract
+
+      <!-- Define behaviors here. -->
+
+      ## NOT Specified (Implementation Freedom)
+
+      <!-- List aspects left to the implementer's discretion. -->
+
+      ## Invariants
+
+      <!-- List properties that must hold true across all inputs and states. -->
+      ```
+      The `{project-name}` placeholder SHOULD be inferred from the nearest project manifest (e.g., `name` in `package.json`) or default to the directory name. If `spec.md` already exists, leave it untouched.
+7. If `mode === 'consumer'`: create `opensdd.json` with consumer-only contents: `{ "opensdd": "0.1.0", "depsDir": ".opensdd.deps" }` (no `specsDir`). If `opensdd.json` already exists, leave it untouched.
+8. Print a success message.
+
+- `opensdd init` selecting OpenSDD-driven in a fresh project MUST produce the full output below
+- `opensdd init` selecting consumer-only in a fresh project MUST produce the consumer output below
+- `opensdd init` in a project that already has OpenSDD initialized (with `specsDir`) MUST overwrite all skill installation files across all agent formats but MUST NOT overwrite `opensdd.json`
+- `opensdd init` in a consumer project MUST prompt to upgrade to OpenSDD-driven
 
 #### Output
 
+Consumer-only (fresh):
+```
+Initialized OpenSDD (consumer):
+  Skills installed for: Claude Code, Codex CLI, Cursor, GitHub Copilot, Gemini CLI, Amp
+    sdd-manager              installed (6 agent formats)
+  opensdd.json               created
+  .opensdd.deps/             created
+```
+
+OpenSDD-driven (fresh):
 ```
 Initialized OpenSDD:
   Skills installed for: Claude Code, Codex CLI, Cursor, GitHub Copilot, Gemini CLI, Amp
@@ -70,7 +97,7 @@ Initialized OpenSDD:
   .opensdd.deps/             created
 ```
 
-If already initialized:
+OpenSDD-driven (re-init):
 ```
 Initialized OpenSDD:
   Skills installed for: Claude Code, Codex CLI, Cursor, GitHub Copilot, Gemini CLI, Amp
@@ -89,7 +116,7 @@ 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 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.
+`opensdd init` installs skills into the native configuration format of each supported coding agent. In **consumer mode**, only `sdd-manager` is installed. In **full (OpenSDD-driven) mode**, both `sdd-manager` and `sdd-generate` are installed. 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.
 
@@ -269,13 +296,13 @@ Fetches a spec from the registry and installs it as a dependency.
 
 #### Behavior
 
-1. Verify `opensdd.json` exists at the project root. If not, print a message suggesting `opensdd init` first and exit with code 1.
-2. Check if the spec `<name>` already exists as a key in `opensdd.json`'s `dependencies` object. If it does AND the spec directory exists in `<deps_dir>`, print a message indicating the spec is already installed and suggest `opensdd update` instead. Exit with code 1. If the entry exists BUT the spec directory is missing, treat as a re-install: log a message noting the stale entry, then continue to step 4 using the version from the existing entry (unless `[version]` is explicitly provided, in which case use that).
+1. Verify `opensdd.json` exists at the project root. If not, auto-bootstrap as a consumer project: create a minimal `opensdd.json` (no `specsDir`), install consumer-mode skills, create the `.opensdd.deps/` directory, print "Auto-initialized OpenSDD (consumer).", and continue with the normal install flow.
+2. Check if the spec `<name>` already exists as a key in `opensdd.json`'s `dependencies` object. If it does AND the spec directory exists in `<depsDir>`, print a message indicating the spec is already installed and suggest `opensdd update` instead. Exit with code 1. If the entry exists BUT the spec directory is missing, treat as a re-install: log a message noting the stale entry, then continue to step 4 using the version from the existing entry (unless `[version]` is explicitly provided, in which case use that).
 3. Validate the spec name (lowercase alphanumeric and hyphens only).
 4. Fetch `index.json` from `registry/<name>/` in the configured registry source. If `[version]` is provided, use that version; otherwise use `latest` from `index.json`.
-5. Read `manifest.json` from `registry/<name>/<version>/` to get spec_format and dependencies.
-6. Copy all files from `registry/<name>/<version>/` into `<deps_dir>/<name>/` (including `manifest.json`, `spec.md`, and any supplementary files).
-7. Add an entry to `opensdd.json` under `dependencies.<name>` with fields from `manifest.json` (`version`, `spec_format`), the resolved registry URL as `source`, and consumer-managed fields initialized to defaults: `implementation: null`, `tests: null`, `has_deviations: false`.
+5. Read `manifest.json` from `registry/<name>/<version>/` to get specFormat and dependencies.
+6. Copy all files from `registry/<name>/<version>/` into `<depsDir>/<name>/` (including `manifest.json`, `spec.md`, and any supplementary files).
+7. Add an entry to `opensdd.json` under `dependencies.<name>` with fields from `manifest.json` (`version`, `specFormat`), the resolved registry URL as `source`, and consumer-managed fields initialized to defaults: `implementation: null`, `tests: null`, `hasDeviations: false`.
 8. If the spec has `dependencies`, check whether each dependency name exists as a key in `opensdd.json`'s `dependencies` object. If any are missing, print a warning listing the missing dependencies and suggesting `opensdd install` for each.
 9. Print a success message.
 
@@ -300,7 +327,6 @@ Run "implement the slugify spec" in your agent to generate an implementation.
 - Spec not found in registry: print error listing available specs and exit with code 1.
 - Requested version not found: print error listing available versions and exit with code 1.
 - Spec already installed (entry and directory both exist): print message suggesting `opensdd update` and exit with code 1.
-- OpenSDD not initialized: print message suggesting `opensdd init` and exit with code 1.
 
 ### `opensdd update [name]`
 
@@ -310,15 +336,15 @@ Fetches the latest version of installed dependency specs from the registry, upda
 
 1. If `<name>` is provided, update that single spec. If no name is provided, update all installed dependencies.
 2. For each spec being updated:
-   a. Read the spec's entry in `opensdd.json` `dependencies` to get the installed version and `spec_format` version.
+   a. Read the spec's entry in `opensdd.json` `dependencies` to get the installed version and `specFormat` version.
    b. Fetch `index.json` from the registry to get the latest version. Read `manifest.json` from the latest version directory.
    c. If the registry version matches the installed version, skip with a message "already up to date".
    d. Before overwriting, compute unified diffs of all spec-owned files that will change.
-   e. Overwrite all spec-owned files in `<deps_dir>/<name>/` with the new version from the registry (`manifest.json`, `spec.md`, and any supplementary files).
+   e. Overwrite all spec-owned files in `<depsDir>/<name>/` with the new version from the registry (`manifest.json`, `spec.md`, and any supplementary files).
    f. MUST NOT overwrite or delete `deviations.md`. The CLI MUST NOT create, modify, or delete `deviations.md` under any circumstances.
    g. Create the staging directory `.opensdd.deps/.updates/<name>/` and write two files. If a pending update already exists for this spec, overwrite it and note the replacement in the output.
-      - `changeset.md` — contains previous and new version, `spec_format` version change (if any), and unified diffs from step (d).
-      - `manifest.json` — contains the metadata needed to finalize the update in `opensdd.json`: `name`, `previous_version`, `version`, `source`, `spec_format`.
+      - `changeset.md` — contains previous and new version, `specFormat` version change (if any), and unified diffs from step (d).
+      - `manifest.json` — contains the metadata needed to finalize the update in `opensdd.json`: `name`, `previousVersion`, `version`, `source`, `specFormat`.
 3. Print a summary of what was updated.
 
 #### Input
@@ -376,7 +402,7 @@ Applies a staged update to `opensdd.json`, confirming that the migration is comp
 3. Prompt the user for confirmation (y/n). If declined, exit with code 0.
 4. For each pending update:
    a. Read `.opensdd.deps/.updates/<name>/manifest.json` to get the update metadata.
-   b. Update the `opensdd.json` `dependencies.<name>` entry: set `version`, `source`, and `spec_format` from the manifest. Preserve all consumer-managed fields (`implementation`, `tests`, `has_deviations`).
+   b. Update the `opensdd.json` `dependencies.<name>` entry: set `version`, `source`, and `specFormat` from the manifest. Preserve all consumer-managed fields (`implementation`, `tests`, `hasDeviations`).
    c. Delete the `.opensdd.deps/.updates/<name>/` directory.
 5. If `.opensdd.deps/.updates/` is now empty, delete it.
 6. Print a summary.
@@ -431,14 +457,14 @@ Publishes an authored spec to the registry.
 
 1. Verify `opensdd.json` exists at the project root. If not, print a message suggesting `opensdd init` first and exit with code 1.
 2. Verify `opensdd.json` has a `publish` object. If not, print an error suggesting the user add a `publish` section and exit with code 1.
-3. Read the `publish` object to get `name`, `version`, `description`, `spec_format`, `dependencies`.
-4. Verify `<specs_dir>/spec.md` exists. If not, print error and exit with code 1.
-5. Run validation on the `<specs_dir>/` directory (same logic as `opensdd validate`). If validation fails with errors, print them and exit with code 1.
+3. Read the `publish` object to get `name`, `version`, `description`, `specFormat`, `dependencies`.
+4. Verify `<specsDir>/spec.md` exists. If not, print error and exit with code 1.
+5. Run validation on the `<specsDir>/` directory (same logic as `opensdd validate`). If validation fails with errors, print them and exit with code 1.
 6. Resolve the registry source. The registry MUST be a GitHub repository URL for publishing.
 7. Fetch `index.json` from `registry/<name>/` if it exists. If the version being published already exists in `index.json`, print error suggesting a version bump and exit with code 1.
 8. Construct the registry entry:
-   a. Build `manifest.json` from the `opensdd.json` `publish` fields (`name`, `version`, `description`, `spec_format`, `dependencies`).
-   b. Collect all files from `<specs_dir>/`.
+   a. Build `manifest.json` from the `opensdd.json` `publish` fields (`name`, `version`, `description`, `specFormat`, `dependencies`).
+   b. Collect all files from `<specsDir>/`.
 9. If `--branch <name>` was provided, use that as the branch name. Otherwise, prompt the user for a branch name.
 10. Clone the registry repo (shallow), create a new branch with the chosen name, and:
     a. Create `registry/<name>/<version>/` with `manifest.json` and all spec files.
@@ -472,7 +498,7 @@ Published. Spec will be available after PR is merged.
 
 - OpenSDD not initialized: print message suggesting `opensdd init` and exit with code 1.
 - No `publish` section in `opensdd.json`: print error and exit with code 1.
-- `<specs_dir>/spec.md` missing: print error and exit with code 1.
+- `<specsDir>/spec.md` missing: print error and exit with code 1.
 - Spec validation fails: print validation errors and exit with code 1.
 - Version already exists in registry: print error suggesting version bump and exit with code 1.
 - Registry is not a GitHub URL: print error (publishing requires a GitHub registry) and exit with code 1.
@@ -487,8 +513,8 @@ Shows the status of the authored spec and all installed dependency specs in the
 
 1. Read `opensdd.json`.
 2. If `publish` exists, print authored spec section showing the spec's name, version, and directory.
-3. If `dependencies` exists and has entries, iterate the `dependencies` object. For each entry, read its consumer-managed fields and check for the presence of `deviations.md` in `<deps_dir>/<name>/`. Print a dependency status table.
-4. Check for untracked directories: spec directories in `<deps_dir>` that have no corresponding `opensdd.json` dependency entry. Warn about any found.
+3. If `dependencies` exists and has entries, iterate the `dependencies` object. For each entry, read its consumer-managed fields and check for the presence of `deviations.md` in `<depsDir>/<name>/`. Print a dependency status table.
+4. Check for untracked directories: spec directories in `<depsDir>` that have no corresponding `opensdd.json` dependency entry. Warn about any found.
 
 #### Output
 
@@ -520,7 +546,7 @@ Validates that a spec directory conforms to the OpenSDD spec-format.
 3. Check for required files: `spec.md` MUST exist.
 4. If `manifest.json` exists, validate it:
    a. `name` MUST be present.
-   b. `spec_format` MUST be present and be a recognized version.
+   b. `specFormat` MUST be present and be a recognized version.
    c. `version` MUST be present and be valid semver.
 5. Validate `spec.md`:
    a. MUST start with an H1 header followed by a blockquote summary.
@@ -607,7 +633,7 @@ For local paths, the CLI MUST read directly from the filesystem. This supports d
 During `opensdd update apply`, the CLI MUST preserve these `opensdd.json` fields for each affected dependency entry:
 - `implementation`
 - `tests`
-- `has_deviations`
+- `hasDeviations`
 
 The CLI reads the existing `opensdd.json` dependency entry, applies updated metadata from the staged manifest, then re-applies the consumer-managed field values. Note that `opensdd update` does NOT touch `opensdd.json` at all — it only stages the update. The `opensdd.json` entry continues to reflect the old version until `opensdd update apply` is called.
 
@@ -620,7 +646,9 @@ The CLI reads the existing `opensdd.json` dependency entry, applies updated meta
 - Running `opensdd update` when a pending update already exists for the spec: overwrite the existing staged update with the new one.
 - Running `opensdd update apply` when no pending updates exist: print "No pending updates." and exit with code 0 (not an error).
 - Running `opensdd update apply <name>` when the agent hasn't finished processing the changeset: the CLI has no way to verify this — it's the user's responsibility to confirm the migration is complete before applying.
-- Running `opensdd init` in a project that already has OpenSDD initialized: overwrite all skill installation files across all agent formats, leave `opensdd.json` untouched.
+- Running `opensdd init` in a project that already has OpenSDD initialized (with `specsDir`): overwrite all skill installation files across all agent formats, leave `opensdd.json` untouched.
+- Running `opensdd init` in a consumer-only project: prompt to upgrade to OpenSDD-driven. If declined, re-install consumer skills only.
+- Running `opensdd install` in an uninitialized project: auto-bootstrap as consumer, then continue with install.
 - Running any command outside a project directory (no project markers found): warn but allow with confirmation, except `opensdd list` and `opensdd validate` which work anywhere.
 - Spec name contains characters invalid for directory names: reject with an error listing allowed characters (lowercase alphanumeric and hyphens).
 - Publishing a version that already exists in the registry: reject with an error suggesting a version bump.
@@ -651,7 +679,7 @@ The CLI reads the existing `opensdd.json` dependency entry, applies updated meta
 - The Claude Code skill installation (`.claude/skills/`) MUST always be present since Gemini CLI and Amp reference it
 - `opensdd.json` MUST be created by `opensdd init` if it does not exist, and MUST NOT be overwritten if it already exists
 - Consumer-managed `opensdd.json` fields MUST survive all update operations
-- Every installed dependency MUST have both a directory in `deps_dir` and an entry in `opensdd.json` `dependencies`
+- Every installed dependency MUST have both a directory in `depsDir` and an entry in `opensdd.json` `dependencies`
 - All commands MUST exit with code 0 on success and code 1 on error
 - The CLI MUST NOT invoke an AI model or coding agent
 - `opensdd publish` MUST NOT allow overwriting an existing version in the registry

package/opensdd/skills/sdd-generate.md

@@ -1,10 +1,10 @@
 ---
 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."
+description: "Extract an OpenSDD behavioral spec from an existing codebase. 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.
+> Guides an AI agent through analyzing an existing codebase and extracting a behavioral spec in the OpenSDD format.
 
 ## Overview
 
@@ -17,7 +17,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.
-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.
+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 `specsDir` (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
 
@@ -38,7 +38,7 @@ If `opensdd.json` exists, add or update the `publish` object:
     "name": "{name}",
     "version": "{semver}",
     "description": "{one-line description}",
-    "spec_format": "0.1.0",
+    "specFormat": "0.1.0",
     "dependencies": []
   }
 }
@@ -164,7 +164,7 @@ Always update `_notes/gaps.md` at the end of each pass with what still needs to
   - `## NOT Specified (Implementation Freedom)` — list implementation choices observed in the source that the spec intentionally leaves open (data structures, algorithms, caching, internal architecture)
   - `## Invariants` — universal properties extracted from property tests, type constraints, or behavioral patterns (e.g., idempotency, commutativity, output format guarantees)
   - `## Implementation Hints` (optional) — guidance on performance, concurrency, or common pitfalls observed in the source, only if genuinely useful. If the spec targets a specific platform, hints MAY be platform-specific; otherwise they SHOULD be language-agnostic.
-- If `opensdd.json` exists, add or update the `publish` object with name, version, description, spec_format, and dependencies from `_notes/scope.md`.
+- If `opensdd.json` exists, add or update the `publish` object with name, version, description, specFormat, and dependencies from `_notes/scope.md`.
 
 **Validate the output:**
 - MUST have H1 header with blockquote summary and `## Behavioral Contract`

package/opensdd/skills/sdd-manager.md

@@ -1,20 +1,20 @@
 ---
 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."
+description: "Manage OpenSDD specs — revise authored specs, implement dependency specs, process updates, check conformance, and create deviations. Use when the user asks to revise a spec, 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.
+> Teaches agents how to revise authored specs, and implement, update, and verify dependency specs in an OpenSDD-compliant project.
 
 ## Overview
 
-The sdd-manager skill is installed once per project via `opensdd init` alongside the sdd-generate skill, into each supported coding agent's configuration directory. It teaches agents four workflows: implementing a spec, processing a spec update, checking conformance, and creating deviations. It also defines universal implementation defaults, the project conventions check, and the verification protocol that apply to all spec implementations.
+The sdd-manager skill is installed once per project via `opensdd init` alongside the sdd-generate skill, into each supported coding agent's configuration directory. It teaches agents five workflows: revising an authored spec, implementing a dependency spec, processing a dependency spec update, checking conformance, and creating deviations. It also defines universal implementation defaults, the project conventions check, and the verification protocol that apply to all spec implementations.
 
-This skill is the required entry point whenever an agent reads an installed OpenSDD dependency spec to make changes to the project — whether that is a first implementation, an incremental update, a conformance check, or a deviation. The agent MUST NOT implement or modify code based on an OpenSDD spec outside of the workflows defined here.
+This skill is the required entry point whenever an agent works with OpenSDD specs — whether revising the project's authored spec, implementing a dependency spec, processing a dependency update, checking conformance, or creating a deviation. The agent MUST NOT implement or modify code based on an OpenSDD spec outside of the workflows defined here.
 
 ## Spec as Source of Truth
 
-The dependency spec (`spec.md`) is the authoritative description of what to build. It is already a carefully structured behavioral contract with precise language, edge cases, and constraints. The agent MUST treat it as the primary reference throughout all workflows and MUST NOT replace it with a self-generated substitute.
+The spec (`spec.md`) — whether an authored spec or an installed dependency — is the authoritative description of what to build. It is already a carefully structured behavioral contract with precise language, edge cases, and constraints. The agent MUST treat it as the primary reference throughout all workflows and MUST NOT replace it with a self-generated substitute.
 
 **Do not rewrite the spec into a plan.** The agent MUST NOT translate spec requirements into its own planning format (todo lists, step-by-step plans, internal summaries, etc.) as a substitute for the spec itself. Such translations are inherently lossy — they flatten nuance, drop edge cases, and shift intent. The spec's behavioral contract already defines what to build; duplicating it in another format adds no value and introduces drift.
 
@@ -22,10 +22,61 @@ The dependency spec (`spec.md`) is the authoritative description of what to buil
 
 **Plans are for additive context only.** If the agent uses planning tools (todo lists, scratchpads, plan mode, etc.), those plans MUST be limited to information that is _not_ in the spec: project-specific decisions (file paths, module structure, integration points), target language and framework details, implementation ordering, and deviations. Plans SHOULD reference spec sections by name rather than restating their content.
 
+## Workflow Identification
+
+When entering any sdd-manager workflow, the agent MUST announce the active workflow to the user before proceeding. The announcement MUST include the workflow name, the target spec, and a one-line description of what will happen next.
+
+Format:
+
+> **[sdd-manager: {Workflow}]** {Target spec}
+> {What the user should expect}
+
+Examples:
+
+> **[sdd-manager: Revise]** opensdd/cli.md
+> I'll draft a changeset for your review before modifying the spec.
+
+> **[sdd-manager: Implement]** .opensdd.deps/slugify/spec.md
+> I'll walk you through the spec, then implement and verify.
+
+> **[sdd-manager: Update]** .opensdd.deps/slugify
+> Reading the staged changeset to identify what changed.
+
+If the agent determines the wrong workflow was triggered, it MUST stop and clarify with the user before proceeding.
+
 ## Workflows
 
+### Revise
+
+For incremental changes to the project's authored spec. The agent drafts a changeset for the user to review before modifying the spec or implementation.
+
+1. **Understand the request.** Read the user's description of the desired behavior change. Read the current spec from `<specsDir>/` (`spec.md` and any supplementary files).
+
+2. **Draft changeset.** Write a changeset to `<specsDir>/.changes/changeset.md` containing:
+   - **Rationale:** Why this change is being made — the user's request, the problem it solves, and any design decisions.
+   - **Changed Files:** For each spec file being modified, a unified diff showing the proposed changes. For new sections being added, show the full proposed content as an addition.
+
+   The changeset MUST be persisted to disk (not kept in conversation context) so it survives context window clears. The agent MUST NOT modify spec files or implementation code during this step.
+
+3. **Review.** Present the changeset to the user. Summarize what's changing and why. The user may:
+   - **Approve** — proceed to step 4.
+   - **Request modifications** — the agent updates the changeset and re-presents. The agent MUST re-read the changeset from disk before modifying it.
+   - **Reject** — delete `<specsDir>/.changes/` and stop.
+
+   The agent MUST NOT proceed past this step without explicit user approval.
+
+4. **Apply to spec.** Apply the approved diffs to the spec files. Delete `<specsDir>/.changes/` after successful application.
+
+5. **Implement.** Update the implementation to match the revised spec. Use the changeset to identify which behavioral sections changed — only modify code affected by the changes. The agent MUST re-read the updated spec sections directly (not work from the changeset diffs) when implementing.
+
+6. **Verify.** Execute the verification protocol (see Verification Protocol section below) scoped to the changed sections: regenerate affected tests, run until all pass, dispatch subagent for spec compliance audit scoped to the changed sections, fix any findings, re-run tests.
+
+7. **Report.** Summarize what changed in the spec and implementation. If the project has `publish` configured in `opensdd.json`, remind the user to bump the version before publishing.
+
 ### Implement
 
+For first-time implementation of a dependency spec.
+
 1. **Read:** Read the dependency spec from `.opensdd.deps/<name>/` (`spec.md` and any supplementary files), `deviations.md` (if it exists), and other dependency specs it depends on.
 
 2. **Clarify (pre-implementation Q&A):** Before writing any code, the agent MUST walk the user through the spec's scope and structure and solicit clarifications. The agent MUST:
@@ -40,7 +91,7 @@ The dependency spec (`spec.md`) is the authoritative description of what to buil
 
 5. **Verify:** Execute the full verification protocol (see Verification Protocol section below): generate test suite → run tests until all pass (or SHOULD bail after 50 attempts) → dispatch subagent for spec compliance audit → fix any findings → re-run tests.
 
-6. **Record:** Update `opensdd.json` `dependencies` entry with `implementation` path, `tests` path, and `has_deviations` if applicable.
+6. **Record:** Update `opensdd.json` `dependencies` entry with `implementation` path, `tests` path, and `hasDeviations` if applicable.
 
 7. **Report:** Report results with spec coverage summary.
 
@@ -59,7 +110,7 @@ Run existing test suite → report pass/fail. If test suite is missing or stale,
 
 ### Create Deviation
 
-Determine affected spec section → classify type → create/append to `deviations.md` in `.opensdd.deps/<name>/` → update test suite to skip affected tests → update `has_deviations` in `opensdd.json`.
+Determine affected spec section → classify type → create/append to `deviations.md` in `.opensdd.deps/<name>/` → update test suite to skip affected tests → update `hasDeviations` in `opensdd.json`.
 
 ## Universal Implementation Defaults
 

package/opensdd/spec-format.md

@@ -21,7 +21,7 @@ A project MAY be both an author (has `opensdd/spec.md`) and a consumer (has `.op
 
 In a monorepo, each sub-project that needs its own spec maintains its own `opensdd.json`, `opensdd/`, and `.opensdd.deps/` at its sub-project root — the same way each package in an npm workspace has its own `package.json`. The CLI always operates relative to the nearest `opensdd.json` in the directory hierarchy.
 
-The OpenSDD protocol installs two skills into the project: **sdd-manager** teaches agents how to implement, update, and verify installed dependency specs; **sdd-generate** teaches agents how to generate specs from existing code. Individual specs are not skills — they are data that the skills operate on.
+The OpenSDD protocol installs two skills into the project: **sdd-manager** teaches agents how to revise authored specs and implement, update, and verify dependency specs; **sdd-generate** teaches agents how to extract a spec from an existing codebase. Individual specs are not skills — they are data that the skills operate on.
 
 Skills are installed into the native configuration format of each supported coding agent so they are automatically discovered. The canonical skill content follows the Agent Skills standard (agentskills.io) with `SKILL.md` files; adapter files are generated for agents with different configuration systems. See the CLI spec for the full installation mapping. Supported agents:
 
@@ -48,7 +48,7 @@ A spec is a directory containing spec files. The directory name is the bare spec
 
 In the registry and in installed dependency specs (`.opensdd.deps/`), every spec directory MUST contain:
 
-- `manifest.json` — Metadata about the spec (name, version, spec_format, description, dependencies).
+- `manifest.json` — Metadata about the spec (name, version, specFormat, description, dependencies).
 - `spec.md` — The behavioral contract and acceptance criteria. The spec IS the acceptance criteria — a well-written spec contains everything needed to both implement and verify the software.
 
 For the authored spec (`opensdd/`), the directory contains `spec.md` and any supplementary files. The metadata that would be in `manifest.json` lives in the `opensdd.json` `publish` entry instead; a separate `manifest.json` file is constructed during publishing.
@@ -227,11 +227,12 @@ The CLI resolves `opensdd.json` by searching upward from the current working dir
 
 The development methodology for an OpenSDD-compliant repo:
 
-1. **Edit the spec** — all behavior changes start in `opensdd/spec.md`. The spec is the source of truth.
-2. **Update the code** — the developer or their AI agent updates the implementation to match the spec. The protocol is deliberately not prescriptive about this step — the agent reads the spec, understands what changed, and updates the code accordingly.
-3. **Publish** — when the spec and implementation are in sync, the developer publishes the spec version to the registry via `opensdd publish`.
-
-The protocol does not mandate a specific tooling flow for step 2 (e.g., changesets, diffs). The spec is always readable in full, and any capable agent can compare the spec against the implementation to identify gaps.
+1. **Propose** — behavior changes are drafted as a changeset (rationale + unified diffs) staged in `<specsDir>/.changes/changeset.md`. The sdd-manager skill's Revise workflow guides this process.
+2. **Review** — the user reviews the proposed changeset, iterates if needed, and approves.
+3. **Apply** — the agent applies the approved changeset to the spec files and deletes the staging directory.
+4. **Implement** — the agent updates the implementation to match the revised spec, using the changeset to scope the changes.
+5. **Verify** — the agent runs the verification protocol (tests + spec compliance audit) scoped to the changed sections.
+6. **Publish** — when the spec and implementation are in sync, the developer publishes the spec version to the registry via `opensdd publish`.
 
 #### Publishing
 
@@ -255,23 +256,23 @@ The `opensdd.json` file is the project-level manifest. It lives at the project r
 {
   "opensdd": "0.1.0",
   "registry": "https://github.com/deepagents-ai/opensdd",
-  "specs_dir": "opensdd",
-  "deps_dir": ".opensdd.deps",
+  "specsDir": "opensdd",
+  "depsDir": ".opensdd.deps",
   "publish": {
     "name": "auth",
     "version": "1.0.0",
     "description": "Authentication with multiple provider support",
-    "spec_format": "0.1.0",
+    "specFormat": "0.1.0",
     "dependencies": []
   },
   "dependencies": {
     "slugify": {
       "version": "2.1.0",
       "source": "https://github.com/deepagents-ai/opensdd",
-      "spec_format": "0.1.0",
+      "specFormat": "0.1.0",
       "implementation": null,
       "tests": null,
-      "has_deviations": false
+      "hasDeviations": false
     }
   }
 }
@@ -281,8 +282,8 @@ The `opensdd.json` file is the project-level manifest. It lives at the project r
 
 - `opensdd` (required): Protocol version string. Agents and the CLI MUST use this to determine how to interpret the manifest.
 - `registry` (optional): URL of the default registry. Overridden by the CLI's `--registry` flag. Default: `"https://github.com/deepagents-ai/opensdd"`.
-- `specs_dir` (optional): Relative path from the project root to the directory containing the authored spec. Default: `"opensdd"`.
-- `deps_dir` (optional): Relative path from the project root to the directory containing installed dependency specs. Default: `".opensdd.deps"`.
+- `specsDir` (optional): Relative path from the project root to the directory containing the authored spec. Default: `"opensdd"`.
+- `depsDir` (optional): Relative path from the project root to the directory containing installed dependency specs. Default: `".opensdd.deps"`.
 - `publish` (optional): Object defining the spec this project publishes. Omit if the project only consumes specs.
 - `dependencies` (optional): Object keyed by spec name. Each entry tracks an installed dependency spec. Omit if the project only publishes specs.
 
@@ -291,17 +292,17 @@ The `opensdd.json` file is the project-level manifest. It lives at the project r
 - `name` (required): Bare spec name — lowercase alphanumeric and hyphens only.
 - `version` (required): Semver version of the spec being developed.
 - `description` (required): One-line description for registry display.
-- `spec_format` (required): Which version of the OpenSDD protocol this spec targets.
+- `specFormat` (required): Which version of the OpenSDD protocol this spec targets.
 - `dependencies` (optional): Array of bare spec names that this spec references for shared types or behavioral contracts.
 
 #### Dependency entry fields
 
 - `version` (required): Semver version of the installed spec.
 - `source` (required): URL of the registry this spec was installed from.
-- `spec_format` (required): OpenSDD protocol version of the installed spec.
+- `specFormat` (required): OpenSDD protocol version of the installed spec.
 - `implementation` (consumer-managed): Path to the generated implementation file, `null` until implemented.
 - `tests` (consumer-managed): Path to the generated test file, `null` until implemented.
-- `has_deviations` (consumer-managed): Boolean, `false` until a deviation is created.
+- `hasDeviations` (consumer-managed): Boolean, `false` until a deviation is created.
 
 Consumer-managed fields MUST be present with explicit `null` or `false` values rather than omitted. Fields MUST survive all update operations.
 
@@ -338,8 +339,8 @@ Each spec in the registry MUST have an `index.json` at its root:
   "description": "String to URL-friendly slug",
   "latest": "2.2.0",
   "versions": {
-    "2.1.0": { "spec_format": "0.1.0" },
-    "2.2.0": { "spec_format": "0.1.0" }
+    "2.1.0": { "specFormat": "0.1.0" },
+    "2.2.0": { "specFormat": "0.1.0" }
   }
 }
 ```
@@ -347,7 +348,7 @@ Each spec in the registry MUST have an `index.json` at its root:
 - `name` (required): Bare spec name.
 - `description` (required): One-line description.
 - `latest` (required): The most recent published version.
-- `versions` (required): Object keyed by semver version string. Each entry MAY include summary metadata (e.g., `spec_format`).
+- `versions` (required): Object keyed by semver version string. Each entry MAY include summary metadata (e.g., `specFormat`).
 
 #### manifest.json (per version)
 
@@ -357,7 +358,7 @@ Each version directory MUST contain a `manifest.json`:
 {
   "name": "slugify",
   "version": "2.2.0",
-  "spec_format": "0.1.0",
+  "specFormat": "0.1.0",
   "description": "String to URL-friendly slug",
   "dependencies": []
 }
@@ -365,7 +366,7 @@ Each version directory MUST contain a `manifest.json`:
 
 - `name` (required): Bare spec name.
 - `version` (required): Semver version of this entry.
-- `spec_format` (required): OpenSDD protocol version.
+- `specFormat` (required): OpenSDD protocol version.
 - `description` (required): One-line description.
 - `dependencies` (optional): Array of bare spec names.
 
@@ -405,6 +406,10 @@ Captures everything the agent needs to understand and process the update without
 **Spec-format:** {old version} → {new version} (or "unchanged")
 **Date:** {ISO 8601 date}
 
+## Rationale (optional)
+
+{Context for why this version was published. Omitted if not available from the registry.}
+
 ## Changed Files
 
 ### spec.md
@@ -429,22 +434,57 @@ Contains the metadata needed to finalize the `opensdd.json` dependency entry whe
 ```json
 {
   "name": "slugify",
-  "previous_version": "2.1.0",
+  "previousVersion": "2.1.0",
   "version": "2.2.0",
   "source": "https://github.com/deepagents-ai/opensdd",
-  "spec_format": "0.1.0"
+  "specFormat": "0.1.0"
 }
 ```
 
 This is a transient artifact. `opensdd update apply` reads this file, applies the metadata to `opensdd.json`, and deletes the staging directory.
 
+### Authored Spec Staging
+
+When a behavior change is proposed to the project's authored spec via the sdd-manager Revise workflow, the agent stages the changeset in `<specsDir>/.changes/`:
+
+```
+opensdd/
+  .changes/
+    changeset.md      # Rationale + unified diffs of proposed spec changes
+  spec.md             # Unchanged until the changeset is approved and applied
+```
+
+The staging directory is persisted to disk so it survives context window clears. It is deleted after the changeset is applied (or rejected).
+
+#### changeset.md (authored spec)
+
+```markdown
+# Changeset
+
+**Date:** {ISO 8601 date}
+
+## Rationale
+
+{Why this change is being made — the user's request, the problem it solves, and any design decisions made.}
+
+## Changed Files
+
+### {filename}
+
+\`\`\`diff
+{unified diff of proposed changes}
+\`\`\`
+```
+
+The rationale section distinguishes authored spec changesets from dependency update changesets. For dependency updates, the "why" is implicit in the version change. For authored spec changes, the "why" is the design decision being made and MUST be captured explicitly.
+
 ### 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](skills/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 revise authored specs and implement, update, and verify 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](skills/sdd-generate.md) for the full skill workflow.
+The sdd-generate skill teaches agents how to extract a behavioral spec from an existing codebase. See [sdd-generate.md](skills/sdd-generate.md) for the full skill workflow.
 
 ### Versioning
 
@@ -475,7 +515,7 @@ Specs use semantic versioning:
 - How spec dependencies are resolved when circular (not currently supported)
 - The sdd-generate skill's internal workflow (separate concern)
 - File encoding (assumed UTF-8)
-- How the author syncs implementation with spec changes (the protocol is deliberately not prescriptive about this)
+- The exact wording of the sdd-manager workflow identification announcement
 - The exact mechanism for authenticating with the registry during publish (deferred to local git/gh credentials)
 
 ## Invariants
@@ -484,7 +524,7 @@ Specs use semantic versioning:
 - Spec-owned files in `.opensdd.deps/` MUST NOT be modified by the consumer or their agent
 - `deviations.md` MUST NOT be created, modified, or deleted by the CLI or any automated tooling
 - Consumer-managed fields in `opensdd.json` MUST survive all update operations
-- Every installed dependency spec MUST have both a directory in `deps_dir` and an entry in `opensdd.json` `dependencies`
+- Every installed dependency spec MUST have both a directory in `depsDir` and an entry in `opensdd.json` `dependencies`
 - All behaviors described in the spec MUST be thoroughly tested by the implementing agent
 - A `spec.md` MUST contain an H1 header with blockquote summary and a `## Behavioral Contract` section
 - `deviations.md` MUST only be created when a deviation actually exists

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opensdd",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "The official OpenSDD (Open Spec-Driven Development) CLI, spec, and spec registry",
   "type": "module",
   "bin": {
@@ -15,7 +15,7 @@
     "node": ">=18.0.0"
   },
   "scripts": {
-    "test": "node --test test/**/*.test.js"
+    "test": "echo '\\n========== TESTS BEGIN ==========\\n' && node --test test/**/*.test.js; EXIT=$?; echo '\\n========== TESTS END ==========\\n'; exit $EXIT"
   },
   "keywords": [
     "opensdd",

package/src/commands/init.js

@@ -75,6 +75,18 @@ function promptYN(question) {
   });
 }
 
+function promptChoice(question, choices) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    const lines = choices.map((c, i) => `  ${i + 1}. ${c}`).join('\n');
+    rl.question(`${question}\n${lines}\nChoice: `, (answer) => {
+      rl.close();
+      const idx = parseInt(answer, 10);
+      resolve(idx >= 1 && idx <= choices.length ? idx : null);
+    });
+  });
+}
+
 export async function initCommand() {
   const cwd = process.cwd();
 
@@ -88,23 +100,9 @@ export async function initCommand() {
     }
   }
 
-  // Step 2: Install skills to all agent formats
-  let warnings;
-  try {
-    warnings = installSkills(cwd);
-  } catch (err) {
-    console.error(`Error: Could not install skills: ${err.message}`);
-    process.exit(1);
-  }
-
-  for (const w of warnings) {
-    console.warn(`Warning: ${w}`);
-  }
-
-  // Step 3: Read or create opensdd.json
+  // Step 2: Read existing opensdd.json if present
   const manifestPath = path.join(cwd, 'opensdd.json');
   let manifest = null;
-  let manifestCreated = false;
 
   if (fs.existsSync(manifestPath)) {
     try {
@@ -115,31 +113,84 @@ export async function initCommand() {
     }
   }
 
+  // Step 3: Determine mode
+  let mode;
+  let manifestCreated = false;
+
+  if (manifest && manifest.specsDir) {
+    // OpenSDD-driven re-init — no prompt needed
+    mode = 'full';
+  } else if (manifest && !manifest.specsDir) {
+    // Consumer re-init — offer upgrade
+    const upgrade = await promptYN('Upgrade to OpenSDD-driven? (y/n) ');
+    if (upgrade) {
+      mode = 'full';
+      manifest.specsDir = manifest.specsDir || 'opensdd';
+      fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
+    } else {
+      mode = 'consumer';
+    }
+  } else {
+    // Fresh init — prompt for mode
+    const choice = await promptChoice('How will this project use OpenSDD?', [
+      'Consumer only \u2014 install and implement dependency specs',
+      'OpenSDD-driven \u2014 full SDD methodology (author specs, both skills)',
+    ]);
+    mode = choice === 2 ? 'full' : 'consumer';
+  }
+
+  // Step 4: Install skills
+  let warnings;
+  try {
+    warnings = installSkills(cwd, { mode });
+  } catch (err) {
+    console.error(`Error: Could not install skills: ${err.message}`);
+    process.exit(1);
+  }
+
+  for (const w of warnings) {
+    console.warn(`Warning: ${w}`);
+  }
+
+  // Step 5: Create or preserve opensdd.json
   if (!manifest) {
-    manifest = {
-      opensdd: '0.1.0',
-      specs_dir: 'opensdd',
-      deps_dir: '.opensdd.deps',
-    };
+    if (mode === 'full') {
+      manifest = {
+        opensdd: '0.1.0',
+        specsDir: 'opensdd',
+        depsDir: '.opensdd.deps',
+      };
+    } else {
+      manifest = {
+        opensdd: '0.1.0',
+        depsDir: '.opensdd.deps',
+      };
+    }
     fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
     manifestCreated = true;
   }
 
-  const specsDir = manifest.specs_dir || 'opensdd';
-  const depsDir = manifest.deps_dir || '.opensdd.deps';
-  const specsDirPath = path.join(cwd, specsDir);
+  const depsDir = manifest.depsDir || '.opensdd.deps';
   const depsDirPath = path.join(cwd, depsDir);
 
-  // Step 4: Create specs directory
-  const specsDirCreated = !fs.existsSync(specsDirPath);
-  fs.mkdirSync(specsDirPath, { recursive: true });
+  // Step 6: Create deps directory (both modes)
+  const depsDirCreated = !fs.existsSync(depsDirPath);
+  fs.mkdirSync(depsDirPath, { recursive: true });
 
-  // Step 5: Create skeleton spec.md
-  const specMdPath = path.join(specsDirPath, 'spec.md');
+  // Step 7: Full mode — create specs directory and skeleton spec.md
+  let specsDirCreated = false;
   let specMdCreated = false;
-  if (!fs.existsSync(specMdPath)) {
-    const projectName = getProjectName(cwd);
-    const skeleton = `# ${projectName}
+  if (mode === 'full') {
+    const specsDir = manifest.specsDir || 'opensdd';
+    const specsDirPath = path.join(cwd, specsDir);
+
+    specsDirCreated = !fs.existsSync(specsDirPath);
+    fs.mkdirSync(specsDirPath, { recursive: true });
+
+    const specMdPath = path.join(specsDirPath, 'spec.md');
+    if (!fs.existsSync(specMdPath)) {
+      const projectName = getProjectName(cwd);
+      const skeleton = `# ${projectName}
 
 > TODO: One-line description of what this software does.
 
@@ -155,30 +206,40 @@ export async function initCommand() {
 
 <!-- List properties that must hold true across all inputs and states. -->
 `;
-    fs.writeFileSync(specMdPath, skeleton);
-    specMdCreated = true;
+      fs.writeFileSync(specMdPath, skeleton);
+      specMdCreated = true;
+    }
   }
 
-  // Step 6: Create deps directory
-  const depsDirCreated = !fs.existsSync(depsDirPath);
-  fs.mkdirSync(depsDirPath, { recursive: true });
-
-  // Step 7: Print output
+  // Step 8: Print output
   const isReInit = !manifestCreated;
   const skillVerb = isReInit ? 'updated' : 'installed';
 
-  console.log('Initialized OpenSDD:');
-  console.log(
-    '  Skills installed for: Claude Code, Codex CLI, Cursor, GitHub Copilot, Gemini CLI, Amp'
-  );
-  console.log(`    sdd-manager              ${skillVerb} (6 agent formats)`);
-  console.log(`    sdd-generate             ${skillVerb} (6 agent formats)`);
-  console.log(
-    `  opensdd.json               ${manifestCreated ? 'created' : 'already exists (preserved)'}`
-  );
-  console.log(`  ${specsDir}/                   ${specsDirCreated ? 'created' : 'already exists'}`);
-  console.log(
-    `  ${specsDir}/spec.md            ${specMdCreated ? 'created (skeleton)' : 'already exists (preserved)'}`
-  );
-  console.log(`  ${depsDir}/             ${depsDirCreated ? 'created' : 'already exists'}`);
+  if (mode === 'consumer') {
+    console.log('Initialized OpenSDD (consumer):');
+    console.log(
+      '  Skills installed for: Claude Code, Codex CLI, Cursor, GitHub Copilot, Gemini CLI, Amp'
+    );
+    console.log(`    sdd-manager              ${skillVerb} (6 agent formats)`);
+    console.log(
+      `  opensdd.json               ${manifestCreated ? 'created' : 'already exists (preserved)'}`
+    );
+    console.log(`  ${depsDir}/             ${depsDirCreated ? 'created' : 'already exists'}`);
+  } else {
+    const specsDir = manifest.specsDir || 'opensdd';
+    console.log('Initialized OpenSDD:');
+    console.log(
+      '  Skills installed for: Claude Code, Codex CLI, Cursor, GitHub Copilot, Gemini CLI, Amp'
+    );
+    console.log(`    sdd-manager              ${skillVerb} (6 agent formats)`);
+    console.log(`    sdd-generate             ${skillVerb} (6 agent formats)`);
+    console.log(
+      `  opensdd.json               ${manifestCreated ? 'created' : 'already exists (preserved)'}`
+    );
+    console.log(`  ${specsDir}/                   ${specsDirCreated ? 'created' : 'already exists'}`);
+    console.log(
+      `  ${specsDir}/spec.md            ${specMdCreated ? 'created (skeleton)' : 'already exists (preserved)'}`
+    );
+    console.log(`  ${depsDir}/             ${depsDirCreated ? 'created' : 'already exists'}`);
+  }
 }

package/src/commands/install.js

@@ -13,17 +13,26 @@ import {
   fetchSpecFiles,
   listRegistrySpecs,
 } from '../lib/registry.js';
+import { installSkills } from '../lib/skills.js';
 
 function isValidSpecName(name) {
   return /^[a-z0-9]+(-[a-z0-9]+)*$/.test(name);
 }
 
 export async function installCommand(name, version, options) {
-  // Step 1: Verify opensdd.json exists
-  const manifestPath = findManifestPath(process.cwd());
+  // Step 1: Verify opensdd.json exists, auto-bootstrap if not
+  let manifestPath = findManifestPath(process.cwd());
   if (!manifestPath) {
-    console.error('Error: OpenSDD not initialized. Run `opensdd init` to get started.');
-    process.exit(1);
+    const cwd = process.cwd();
+    manifestPath = path.join(cwd, 'opensdd.json');
+    const consumerManifest = {
+      opensdd: '0.1.0',
+      depsDir: '.opensdd.deps',
+    };
+    fs.writeFileSync(manifestPath, JSON.stringify(consumerManifest, null, 2) + '\n');
+    installSkills(cwd, { mode: 'consumer' });
+    fs.mkdirSync(path.join(cwd, '.opensdd.deps'), { recursive: true });
+    console.log('Auto-initialized OpenSDD (consumer).');
   }
 
   const manifest = readManifest(manifestPath);
@@ -132,10 +141,10 @@ export async function installCommand(name, version, options) {
   manifest.dependencies[name] = {
     version: resolvedVersion,
     source: registrySource,
-    spec_format: specManifest.spec_format || '0.1.0',
+    specFormat: specManifest.specFormat || '0.1.0',
     implementation: existingEntry?.implementation ?? null,
     tests: existingEntry?.tests ?? null,
-    has_deviations: existingEntry?.has_deviations ?? false,
+    hasDeviations: existingEntry?.hasDeviations ?? false,
   };
 
   writeManifest(manifestPath, manifest);

package/src/commands/publish.js

@@ -65,16 +65,16 @@ export async function publishCommand(options) {
   if (!manifest.publish) {
     console.error('Error: No `publish` section in opensdd.json.');
     console.error(
-      'Add a `publish` object with name, version, description, and spec_format to publish your spec.'
+      'Add a `publish` object with name, version, description, and specFormat to publish your spec.'
     );
     process.exit(1);
   }
 
-  const { name, version, description, spec_format, dependencies } = manifest.publish;
+  const { name, version, description, specFormat, dependencies } = manifest.publish;
 
-  if (!name || !version || !description || !spec_format) {
+  if (!name || !version || !description || !specFormat) {
     console.error(
-      'Error: `publish` section must include name, version, description, and spec_format.'
+      'Error: `publish` section must include name, version, description, and specFormat.'
     );
     process.exit(1);
   }
@@ -169,7 +169,7 @@ export async function publishCommand(options) {
     const publishManifest = {
       name,
       version,
-      spec_format,
+      specFormat,
       description,
       dependencies: dependencies || [],
     };
@@ -192,7 +192,7 @@ export async function publishCommand(options) {
       indexData = { name, description, latest: version, versions: {} };
     }
     indexData.latest = version;
-    indexData.versions[version] = { spec_format };
+    indexData.versions[version] = { specFormat };
     fs.writeFileSync(indexPath, JSON.stringify(indexData, null, 2) + '\n');
     console.log(`  Updated index.json        latest: ${version}`);
 

package/src/commands/status.js

@@ -53,7 +53,7 @@ export async function statusCommand() {
       // Check for deviations
       let deviationInfo = '';
       const deviationsPath = path.join(projectRoot, depsDir, depName, 'deviations.md');
-      if (entry.has_deviations || fs.existsSync(deviationsPath)) {
+      if (entry.hasDeviations || fs.existsSync(deviationsPath)) {
         if (fs.existsSync(deviationsPath)) {
           const content = fs.readFileSync(deviationsPath, 'utf-8');
           const deviationCount = (content.match(/^## /gm) || []).length;

package/src/commands/update.js

@@ -115,8 +115,8 @@ export async function updateCommand(name, options) {
     fs.mkdirSync(updatesDir, { recursive: true });
 
     // Write changeset.md
-    const specFormatOld = entry.spec_format || '0.1.0';
-    const specFormatNew = newManifest.spec_format || '0.1.0';
+    const specFormatOld = entry.specFormat || '0.1.0';
+    const specFormatNew = newManifest.specFormat || '0.1.0';
     const specFormatChange =
       specFormatOld === specFormatNew
         ? 'unchanged'
@@ -142,10 +142,10 @@ export async function updateCommand(name, options) {
     // Write manifest.json for staging
     const stageManifest = {
       name: specName,
-      previous_version: entry.version,
+      previousVersion: entry.version,
       version: latestVersion,
       source: registrySource,
-      spec_format: newManifest.spec_format || '0.1.0',
+      specFormat: newManifest.specFormat || '0.1.0',
     };
 
     fs.writeFileSync(

package/src/commands/updateApply.js

@@ -64,7 +64,7 @@ export async function updateApplyCommand(name) {
   if (pendingNames.length === 1) {
     const updateManifestPath = path.join(updatesDir, pendingNames[0], 'manifest.json');
     const updateManifest = JSON.parse(fs.readFileSync(updateManifestPath, 'utf-8'));
-    confirmMsg = `Apply update for ${pendingNames[0]} v${updateManifest.previous_version} -> v${updateManifest.version}? (y/n) `;
+    confirmMsg = `Apply update for ${pendingNames[0]} v${updateManifest.previousVersion} -> v${updateManifest.version}? (y/n) `;
   } else {
     confirmMsg = `Apply ${pendingNames.length} pending updates? (y/n) `;
   }
@@ -103,13 +103,13 @@ export async function updateApplyCommand(name) {
       ...existing,
       version: updateManifest.version,
       source: updateManifest.source,
-      spec_format: updateManifest.spec_format,
+      specFormat: updateManifest.specFormat,
       // Preserve consumer-managed fields
       implementation:
         existing.implementation !== undefined ? existing.implementation : null,
       tests: existing.tests !== undefined ? existing.tests : null,
-      has_deviations:
-        existing.has_deviations !== undefined ? existing.has_deviations : false,
+      hasDeviations:
+        existing.hasDeviations !== undefined ? existing.hasDeviations : false,
     };
 
     // Delete staging directory
@@ -117,7 +117,7 @@ export async function updateApplyCommand(name) {
 
     applied.push({
       name: specName,
-      oldVersion: updateManifest.previous_version,
+      oldVersion: updateManifest.previousVersion,
       newVersion: updateManifest.version,
     });
   }

package/src/lib/manifest.js

@@ -29,10 +29,14 @@ export function writeManifest(manifestPath, data) {
   fs.writeFileSync(manifestPath, JSON.stringify(data, null, 2) + '\n');
 }
 
+export function isConsumerOnly(manifest) {
+  return !manifest.specsDir;
+}
+
 export function getSpecsDir(manifest) {
-  return manifest.specs_dir || 'opensdd';
+  return manifest.specsDir || 'opensdd';
 }
 
 export function getDepsDir(manifest) {
-  return manifest.deps_dir || '.opensdd.deps';
+  return manifest.depsDir || '.opensdd.deps';
 }

package/src/lib/skills.js

@@ -89,9 +89,10 @@ function updateManagedSection(filePath, sectionBody) {
  * Returns an array of warnings for non-critical failures.
  * Throws on critical failures (e.g., Claude Code installation fails).
  */
-export function installSkills(projectRoot) {
+export function installSkills(projectRoot, { mode = 'full' } = {}) {
   const skills = getSkillContent();
   const warnings = [];
+  const isFull = mode === 'full';
 
   // 1. Claude Code (critical — Gemini and Amp depend on this)
   const claudeBase = path.join(projectRoot, '.claude', 'skills');
@@ -103,14 +104,16 @@ export function installSkills(projectRoot) {
     path.join(claudeBase, 'sdd-manager', 'references', 'spec-format.md'),
     skills.specFormat
   );
-  writeFileSync(
-    path.join(claudeBase, 'sdd-generate', 'SKILL.md'),
-    skills.sddGenerate
-  );
-  writeFileSync(
-    path.join(claudeBase, 'sdd-generate', 'references', 'spec-format.md'),
-    skills.specFormat
-  );
+  if (isFull) {
+    writeFileSync(
+      path.join(claudeBase, 'sdd-generate', 'SKILL.md'),
+      skills.sddGenerate
+    );
+    writeFileSync(
+      path.join(claudeBase, 'sdd-generate', 'references', 'spec-format.md'),
+      skills.specFormat
+    );
+  }
 
   // 2. Codex CLI
   try {
@@ -123,14 +126,16 @@ export function installSkills(projectRoot) {
       path.join(codexBase, 'sdd-manager', 'references', 'spec-format.md'),
       skills.specFormat
     );
-    writeFileSync(
-      path.join(codexBase, 'sdd-generate', 'SKILL.md'),
-      skills.sddGenerate
-    );
-    writeFileSync(
-      path.join(codexBase, 'sdd-generate', 'references', 'spec-format.md'),
-      skills.specFormat
-    );
+    if (isFull) {
+      writeFileSync(
+        path.join(codexBase, 'sdd-generate', 'SKILL.md'),
+        skills.sddGenerate
+      );
+      writeFileSync(
+        path.join(codexBase, 'sdd-generate', 'references', 'spec-format.md'),
+        skills.specFormat
+      );
+    }
   } catch (err) {
     warnings.push(`Could not install Codex CLI skills: ${err.message}`);
   }
@@ -141,7 +146,6 @@ export function installSkills(projectRoot) {
     ensureDir(cursorBase);
 
     const { frontmatter: managerFm, body: managerBody } = parseFrontmatter(skills.sddManager);
-    const { frontmatter: generateFm, body: generateBody } = parseFrontmatter(skills.sddGenerate);
 
     const sddManagerCursor = `---
 description: "${managerFm.description}"
@@ -150,13 +154,6 @@ alwaysApply: false
 
 ${managerBody}`;
 
-    const sddGenerateCursor = `---
-description: "${generateFm.description}"
-alwaysApply: false
----
-
-${generateBody}`;
-
     const specFormatCursor = `---
 description: "OpenSDD spec format reference. Defines the structure and rules for behavioral specifications. Referenced by sdd-manager and sdd-generate skills."
 alwaysApply: false
@@ -165,8 +162,20 @@ alwaysApply: false
 ${skills.specFormat}`;
 
     writeFileSync(path.join(cursorBase, 'sdd-manager.md'), sddManagerCursor);
-    writeFileSync(path.join(cursorBase, 'sdd-generate.md'), sddGenerateCursor);
     writeFileSync(path.join(cursorBase, 'opensdd-spec-format.md'), specFormatCursor);
+
+    if (isFull) {
+      const { frontmatter: generateFm, body: generateBody } = parseFrontmatter(skills.sddGenerate);
+
+      const sddGenerateCursor = `---
+description: "${generateFm.description}"
+alwaysApply: false
+---
+
+${generateBody}`;
+
+      writeFileSync(path.join(cursorBase, 'sdd-generate.md'), sddGenerateCursor);
+    }
   } catch (err) {
     warnings.push(`Could not install Cursor skills: ${err.message}`);
   }
@@ -177,20 +186,24 @@ ${skills.specFormat}`;
     ensureDir(copilotBase);
 
     const { frontmatter: managerFmCp, body: managerBodyCp } = parseFrontmatter(skills.sddManager);
-    const { frontmatter: generateFmCp, body: generateBodyCp } = parseFrontmatter(skills.sddGenerate);
 
     writeFileSync(
       path.join(copilotBase, 'sdd-manager.instructions.md'),
       `---\napplyTo: "**"\ndescription: "${managerFmCp.description}"\n---\n\n${managerBodyCp}`
     );
-    writeFileSync(
-      path.join(copilotBase, 'sdd-generate.instructions.md'),
-      `---\napplyTo: "**"\ndescription: "${generateFmCp.description}"\n---\n\n${generateBodyCp}`
-    );
     writeFileSync(
       path.join(copilotBase, 'opensdd-spec-format.instructions.md'),
       `---\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}`
     );
+
+    if (isFull) {
+      const { frontmatter: generateFmCp, body: generateBodyCp } = parseFrontmatter(skills.sddGenerate);
+
+      writeFileSync(
+        path.join(copilotBase, 'sdd-generate.instructions.md'),
+        `---\napplyTo: "**"\ndescription: "${generateFmCp.description}"\n---\n\n${generateBodyCp}`
+      );
+    }
   } catch (err) {
     warnings.push(`Could not install GitHub Copilot skills: ${err.message}`);
   }
@@ -198,10 +211,12 @@ ${skills.specFormat}`;
   // 5. Gemini CLI
   try {
     const geminiPath = path.join(projectRoot, 'GEMINI.md');
-    const geminiBody = `@.claude/skills/sdd-manager/SKILL.md
-@.claude/skills/sdd-manager/references/spec-format.md
-@.claude/skills/sdd-generate/SKILL.md
+    let geminiBody = `@.claude/skills/sdd-manager/SKILL.md
+@.claude/skills/sdd-manager/references/spec-format.md`;
+    if (isFull) {
+      geminiBody += `\n@.claude/skills/sdd-generate/SKILL.md
 @.claude/skills/sdd-generate/references/spec-format.md`;
+    }
     updateManagedSection(geminiPath, geminiBody);
   } catch (err) {
     warnings.push(`Could not install Gemini CLI skills: ${err.message}`);
@@ -210,10 +225,12 @@ ${skills.specFormat}`;
   // 6. Amp
   try {
     const ampPath = path.join(projectRoot, 'AGENTS.md');
-    const ampBody = `@.claude/skills/sdd-manager/SKILL.md
-@.claude/skills/sdd-manager/references/spec-format.md
-@.claude/skills/sdd-generate/SKILL.md
+    let ampBody = `@.claude/skills/sdd-manager/SKILL.md
+@.claude/skills/sdd-manager/references/spec-format.md`;
+    if (isFull) {
+      ampBody += `\n@.claude/skills/sdd-generate/SKILL.md
 @.claude/skills/sdd-generate/references/spec-format.md`;
+    }
     updateManagedSection(ampPath, ampBody);
   } catch (err) {
     warnings.push(`Could not install Amp skills: ${err.message}`);

package/src/lib/validation.js

@@ -105,9 +105,9 @@ function validateManifest(manifest, result) {
     result.errors.push('manifest.json: Missing name');
   }
 
-  if (!manifest.spec_format) {
-    result.manifestErrors.push('Missing required field: spec_format');
-    result.errors.push('manifest.json: Missing spec_format');
+  if (!manifest.specFormat) {
+    result.manifestErrors.push('Missing required field: specFormat');
+    result.errors.push('manifest.json: Missing specFormat');
   }
 
   if (!manifest.version) {