opensdd 0.1.3 → 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", "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.
-4. Create the `opensdd/` directory (or the directory specified by `specsDir` in an existing `opensdd.json`) if it does not exist.
-5. 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
+- **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 `depsDir` 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,7 +296,7 @@ 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.
+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`.
@@ -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]`
 
@@ -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.

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
 

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:

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:
 
@@ -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
 
@@ -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
@@ -438,13 +443,48 @@ Contains the metadata needed to finalize the `opensdd.json` dependency entry whe
 
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opensdd",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "The official OpenSDD (Open Spec-Driven Development) CLI, spec, and spec registry",
   "type": "module",
   "bin": {

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',
-      specsDir: 'opensdd',
-      depsDir: '.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.specsDir || 'opensdd';
   const depsDir = manifest.depsDir || '.opensdd.deps';
-  const specsDirPath = path.join(cwd, specsDir);
   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);

package/src/lib/manifest.js

@@ -29,6 +29,10 @@ 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.specsDir || 'opensdd';
 }

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}`);