sddx-workflow 0.6.0

package/README.md

@@ -0,0 +1,134 @@
+# sddx-workflow
+
+Spec-Driven Development CLI for AI-assisted projects. Installs a structured workflow system that guides AI agents (Claude, Cursor, Copilot) through planning, execution, and review — without letting them run loose.
+
+Works with any project: Next.js, Python, React, Django, Go, Rails — the workflow is universal.
+
+```bash
+npx sddx-workflow init
+```
+
+---
+
+## The problem
+
+AI agents tend to implement without validating assumptions, refactor more than asked, and don't have a mental model of when to stop and ask for approval. This system enforces explicit ceremony levels and stop points.
+
+---
+
+## Installation
+
+```bash
+# Initialize in any project
+npx sddx-workflow init
+
+# Overwrite existing files
+npx sddx-workflow init --force
+
+# Add a domain file to an existing installation
+npx sddx-workflow add domain auth
+npx sddx-workflow add domain payments
+npx sddx-workflow add domain storage
+npx sddx-workflow add domain email
+```
+
+Files are **copied locally** — your project owns them. No runtime dependency. Edit them freely.
+
+---
+
+## What it generates
+
+```
+.sdd/
+  workflow.md          # Commands, ceremony levels, stop points
+  project-overview.md  # What this app is (populated by /bootstrap)
+  conventions.md       # Stack and patterns (populated by /bootstrap)
+  domains/             # Domain-specific rules (auth, payments, etc.)
+specs/
+  _template/
+    1-requirements.md  # Problem, goals, acceptance criteria (BDD)
+    2-plan.md          # Technical plan — requires approval before coding
+    3-tasks.md         # Atomic task checklist with TDD gate
+CLAUDE.md              # Entry point — points the agent to .sdd/
+```
+
+---
+
+## First thing to do after init
+
+Run `/bootstrap` with your AI agent to populate the project context:
+
+- **New project** — the agent interviews you with 6 targeted questions (problem, stack, non-goals, architecture decisions, domains, definition of done) and writes `.sdd/project-overview.md` and `.sdd/conventions.md`
+- **Existing project** — run `/bootstrap --scan` and the agent reads your codebase first, infers what it can, then asks only about what the code can't answer
+
+The agent presents a full draft for your approval before writing anything.
+
+---
+
+## Workflow commands
+
+| Command | Purpose |
+|---|---|
+| `/bootstrap` | Populate project context — interview or codebase scan |
+| `/ask` | Research and exploration — no code changes |
+| `/assume` | Surface all assumptions before acting — stops for confirmation |
+| `/bugfix` | Reproduce → diagnose → fix → validate |
+| `/refactor` | Restructure without behavior change — green baseline required |
+| `/spec-new` | Scaffold a spec folder for a feature |
+| `/spec-plan` | Generate technical plan — **stops for approval before any code** |
+| `/spec-tasks` | Execute plan one atomic task at a time, TDD-first |
+| `/review` | Final audit — verifies goals, scenarios, no scope creep |
+| `/finish` | Stage files and generate a conventional commit message for approval |
+
+### Ceremony levels
+
+| Change | Flow |
+|---|---|
+| Typo / comment | Direct |
+| Bug | `/bugfix` → `/finish` |
+| Refactor | `/refactor` → `/finish` |
+| Feature | `/spec-new` → `/spec-plan` → `/spec-tasks` → `/review` → `/finish` |
+| Architecture | `/spec-new` → `/spec-plan` (mandatory human review) → `/spec-tasks` → `/review` → `/finish` |
+
+---
+
+## Execution principles
+
+Built into the workflow — every command enforces these:
+
+1. **Surface assumptions** — list them before acting, not mid-execution
+2. **Minimum code** — only what was asked; no "while I'm here" changes
+3. **Surgical changes** — touch only what the task requires
+4. **Verify before moving on** — define "done" before starting, not after
+
+---
+
+## Spec structure
+
+Each feature gets a folder under `specs/<name>/` with three files:
+
+**`1-requirements.md`** — Problem, measurable goals (G1, G2…), BDD acceptance criteria, constraints, open questions (blocking vs. non-blocking).
+
+**`2-plan.md`** — Goals coverage, assumptions (confirmed via `/assume`), approach + tradeoffs, components affected, abort criteria, verification per task. Requires explicit approval before execution starts.
+
+**`3-tasks.md`** — One task at a time. Each task has: test to write first (red→green), files to change, goal ID, acceptance scenario, and optional tradeoff. Completed specs move to `specs/_done/`.
+
+---
+
+## Updating
+
+```bash
+npm version patch   # bug fix:     0.1.0 → 0.1.1
+npm version minor   # new feature: 0.1.0 → 0.2.0
+npm publish
+```
+
+Users running `npx sddx-workflow init` always get the latest version automatically.
+
+Since files are copied to your project, existing `.sdd/` files are never overwritten on update — use `--force` to explicitly replace them.
+
+---
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,311 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/cli.ts
+var import_commander = require("commander");
+
+// src/commands/init.ts
+var import_path2 = __toESM(require("path"));
+var import_fs2 = __toESM(require("fs"));
+var import_prompts = require("@inquirer/prompts");
+
+// src/utils.ts
+var import_fs = __toESM(require("fs"));
+var import_path = __toESM(require("path"));
+var TEMPLATES_DIR = import_path.default.join(__dirname, "../templates");
+function ensureDir(dir) {
+  if (!import_fs.default.existsSync(dir)) {
+    import_fs.default.mkdirSync(dir, { recursive: true });
+  }
+}
+function copyTemplate(src, dest, force) {
+  const exists = import_fs.default.existsSync(dest);
+  if (exists && !force) {
+    console.log(`  skip     ${dest}`);
+    return;
+  }
+  import_fs.default.copyFileSync(import_path.default.join(TEMPLATES_DIR, src), dest);
+  console.log(`  ${exists ? "overwrite" : "create  "}  ${dest}`);
+}
+
+// src/commands/init.ts
+var CORE_FILES = [
+  { src: "workflow.md", dest: ".sdd/workflow.md" },
+  { src: "project-overview.md", dest: ".sdd/project-overview.md" },
+  { src: "conventions/base.md", dest: ".sdd/conventions.md" },
+  { src: "CLAUDE.md", dest: "CLAUDE.md" },
+  { src: "specs/_template/1-requirements.md", dest: "specs/_template/1-requirements.md" },
+  { src: "specs/_template/2-plan.md", dest: "specs/_template/2-plan.md" },
+  { src: "specs/_template/3-tasks.md", dest: "specs/_template/3-tasks.md" }
+];
+var PROVIDERS = {
+  "claude-code": {
+    name: "Claude Code",
+    dirs: [".claude/commands"],
+    files: [
+      { src: "claude-commands/bootstrap.md", dest: ".claude/commands/bootstrap.md" },
+      { src: "claude-commands/ask.md", dest: ".claude/commands/ask.md" },
+      { src: "claude-commands/assume.md", dest: ".claude/commands/assume.md" },
+      { src: "claude-commands/bugfix.md", dest: ".claude/commands/bugfix.md" },
+      { src: "claude-commands/refactor.md", dest: ".claude/commands/refactor.md" },
+      { src: "claude-commands/spec-new.md", dest: ".claude/commands/spec-new.md" },
+      { src: "claude-commands/spec-plan.md", dest: ".claude/commands/spec-plan.md" },
+      { src: "claude-commands/spec-tasks.md", dest: ".claude/commands/spec-tasks.md" },
+      { src: "claude-commands/review.md", dest: ".claude/commands/review.md" },
+      { src: "claude-commands/finish.md", dest: ".claude/commands/finish.md" }
+    ]
+  },
+  cursor: {
+    name: "Cursor",
+    dirs: [".cursor/rules"],
+    files: [
+      { src: "cursor-rules/sddx-workflow.mdc", dest: ".cursor/rules/sddx-workflow.mdc" }
+    ]
+  },
+  windsurf: {
+    name: "Windsurf",
+    dirs: [".windsurf/rules"],
+    files: [
+      { src: "windsurf-rules/sddx-workflow.md", dest: ".windsurf/rules/sddx-workflow.md" }
+    ]
+  },
+  copilot: {
+    name: "GitHub Copilot",
+    dirs: [".github/prompts"],
+    files: [
+      { src: "copilot-prompts/bootstrap.prompt.md", dest: ".github/prompts/bootstrap.prompt.md" },
+      { src: "copilot-prompts/ask.prompt.md", dest: ".github/prompts/ask.prompt.md" },
+      { src: "copilot-prompts/assume.prompt.md", dest: ".github/prompts/assume.prompt.md" },
+      { src: "copilot-prompts/bugfix.prompt.md", dest: ".github/prompts/bugfix.prompt.md" },
+      { src: "copilot-prompts/refactor.prompt.md", dest: ".github/prompts/refactor.prompt.md" },
+      { src: "copilot-prompts/spec-new.prompt.md", dest: ".github/prompts/spec-new.prompt.md" },
+      { src: "copilot-prompts/spec-plan.prompt.md", dest: ".github/prompts/spec-plan.prompt.md" },
+      { src: "copilot-prompts/spec-tasks.prompt.md", dest: ".github/prompts/spec-tasks.prompt.md" },
+      { src: "copilot-prompts/review.prompt.md", dest: ".github/prompts/review.prompt.md" },
+      { src: "copilot-prompts/finish.prompt.md", dest: ".github/prompts/finish.prompt.md" },
+      { src: "copilot-instructions.md", dest: ".github/copilot-instructions.md" }
+    ]
+  }
+};
+var ALL_PROVIDER_IDS = Object.keys(PROVIDERS);
+async function selectProviders() {
+  if (!process.stdout.isTTY) {
+    return ALL_PROVIDER_IDS;
+  }
+  const selected = await (0, import_prompts.checkbox)({
+    message: "Select the AI providers to install:",
+    choices: ALL_PROVIDER_IDS.map((id) => ({
+      name: PROVIDERS[id].name,
+      value: id,
+      checked: true
+    })),
+    required: true
+  });
+  return selected;
+}
+async function initCommand(options) {
+  const cwd = process.cwd();
+  const { force } = options;
+  console.log("");
+  console.log("  SDD Workflow \u2014 initializing");
+  console.log("");
+  const selectedProviders = await selectProviders();
+  console.log("");
+  ensureDir(import_path2.default.join(cwd, ".sdd/domains"));
+  ensureDir(import_path2.default.join(cwd, "specs/_template"));
+  for (const id of selectedProviders) {
+    for (const dir of PROVIDERS[id].dirs) {
+      ensureDir(import_path2.default.join(cwd, dir));
+    }
+  }
+  const claudeExisted = import_fs2.default.existsSync(import_path2.default.join(cwd, "CLAUDE.md"));
+  for (const file of CORE_FILES) {
+    copyTemplate(file.src, import_path2.default.join(cwd, file.dest), force);
+  }
+  for (const id of selectedProviders) {
+    for (const file of PROVIDERS[id].files) {
+      copyTemplate(file.src, import_path2.default.join(cwd, file.dest), force);
+    }
+  }
+  const providerNames = selectedProviders.map((id) => PROVIDERS[id].name).join(", ");
+  console.log("");
+  console.log("  Done. Next steps:");
+  console.log("");
+  console.log("  1. Run /bootstrap to populate project context (new project)");
+  console.log("     or /bootstrap --scan to let the agent analyze the codebase (existing project)");
+  if (!claudeExisted) {
+    console.log("  2. CLAUDE.md was created \u2014 share it with your AI agent as context");
+  } else {
+    console.log("  2. CLAUDE.md already exists \u2014 add a reference to .sdd/ files manually");
+  }
+  console.log(`  3. Slash commands are ready in: ${providerNames}. Type / to see them.
+`);
+}
+
+// src/commands/add.ts
+var import_path3 = __toESM(require("path"));
+var import_fs3 = __toESM(require("fs"));
+var DOMAIN_MAP = {
+  auth: "domains/auth.md",
+  payments: "domains/payments.md",
+  storage: "domains/storage.md",
+  email: "domains/email.md"
+};
+function addCommand(type, name) {
+  const cwd = process.cwd();
+  if (type !== "domain") {
+    console.error(`  error    Unknown type "${type}". Available: domain`);
+    process.exit(1);
+  }
+  const templateSrc = DOMAIN_MAP[name];
+  if (!templateSrc) {
+    const available = Object.keys(DOMAIN_MAP).join(", ");
+    console.error(`  error    Unknown domain "${name}". Available: ${available}`);
+    process.exit(1);
+  }
+  if (!import_fs3.default.existsSync(import_path3.default.join(cwd, ".sdd"))) {
+    console.error("  error    .sdd/ not found. Run `npx sddx-workflow init` first.");
+    process.exit(1);
+  }
+  console.log("");
+  copyTemplate(templateSrc, import_path3.default.join(cwd, `.sdd/domains/${name}.md`));
+  console.log("");
+}
+
+// src/commands/update.ts
+var import_fs4 = __toESM(require("fs"));
+var import_path4 = __toESM(require("path"));
+var WORKFLOW_FILES = [
+  { src: "workflow.md", dest: ".sdd/workflow.md" },
+  { src: "claude-commands/bootstrap.md", dest: ".claude/commands/bootstrap.md" },
+  { src: "claude-commands/ask.md", dest: ".claude/commands/ask.md" },
+  { src: "claude-commands/assume.md", dest: ".claude/commands/assume.md" },
+  { src: "claude-commands/bugfix.md", dest: ".claude/commands/bugfix.md" },
+  { src: "claude-commands/refactor.md", dest: ".claude/commands/refactor.md" },
+  { src: "claude-commands/spec-new.md", dest: ".claude/commands/spec-new.md" },
+  { src: "claude-commands/spec-plan.md", dest: ".claude/commands/spec-plan.md" },
+  { src: "claude-commands/spec-tasks.md", dest: ".claude/commands/spec-tasks.md" },
+  { src: "claude-commands/review.md", dest: ".claude/commands/review.md" },
+  { src: "claude-commands/finish.md", dest: ".claude/commands/finish.md" },
+  { src: "cursor-rules/sddx-workflow.mdc", dest: ".cursor/rules/sddx-workflow.mdc" },
+  { src: "windsurf-rules/sddx-workflow.md", dest: ".windsurf/rules/sddx-workflow.md" },
+  { src: "copilot-prompts/bootstrap.prompt.md", dest: ".github/prompts/bootstrap.prompt.md" },
+  { src: "copilot-prompts/ask.prompt.md", dest: ".github/prompts/ask.prompt.md" },
+  { src: "copilot-prompts/assume.prompt.md", dest: ".github/prompts/assume.prompt.md" },
+  { src: "copilot-prompts/bugfix.prompt.md", dest: ".github/prompts/bugfix.prompt.md" },
+  { src: "copilot-prompts/refactor.prompt.md", dest: ".github/prompts/refactor.prompt.md" },
+  { src: "copilot-prompts/spec-new.prompt.md", dest: ".github/prompts/spec-new.prompt.md" },
+  { src: "copilot-prompts/spec-plan.prompt.md", dest: ".github/prompts/spec-plan.prompt.md" },
+  { src: "copilot-prompts/spec-tasks.prompt.md", dest: ".github/prompts/spec-tasks.prompt.md" },
+  { src: "copilot-prompts/review.prompt.md", dest: ".github/prompts/review.prompt.md" },
+  { src: "copilot-prompts/finish.prompt.md", dest: ".github/prompts/finish.prompt.md" },
+  { src: "copilot-instructions.md", dest: ".github/copilot-instructions.md" }
+];
+function updateCommand() {
+  const cwd = process.cwd();
+  if (!import_fs4.default.existsSync(import_path4.default.join(cwd, ".sdd"))) {
+    console.error("\n  error    .sdd/ not found. Run `npx sddx-workflow init` first.\n");
+    process.exit(1);
+  }
+  console.log("");
+  console.log("  SDD Workflow \u2014 updating workflow files");
+  console.log("  (project-overview.md, conventions.md, CLAUDE.md, and domains are yours \u2014 untouched)");
+  console.log("");
+  let updated = 0;
+  for (const file of WORKFLOW_FILES) {
+    const dest = import_path4.default.join(cwd, file.dest);
+    if (!import_fs4.default.existsSync(dest)) continue;
+    copyTemplate(file.src, dest, true);
+    updated++;
+  }
+  console.log("");
+  console.log(`  Done. ${updated} file${updated !== 1 ? "s" : ""} updated.
+`);
+}
+
+// src/commands/status.ts
+var import_fs5 = __toESM(require("fs"));
+var import_path5 = __toESM(require("path"));
+function isBootstrapped(cwd) {
+  const file = import_path5.default.join(cwd, ".sdd/project-overview.md");
+  if (!import_fs5.default.existsSync(file)) return false;
+  const lines = import_fs5.default.readFileSync(file, "utf8").split("\n");
+  return lines.some((line) => {
+    const t = line.trim();
+    return t.length > 0 && !t.startsWith("#") && !t.startsWith("<!--") && !t.startsWith("-->");
+  });
+}
+function readSpec(specDir) {
+  const name = import_path5.default.basename(specDir);
+  const tasksFile = import_path5.default.join(specDir, "3-tasks.md");
+  if (!import_fs5.default.existsSync(tasksFile)) {
+    return { name, planApproved: false, tasksDone: 0, tasksTotal: 0 };
+  }
+  const content = import_fs5.default.readFileSync(tasksFile, "utf8");
+  const planApproved = !content.includes("<!-- date -->");
+  const tasksDone = (content.match(/^- \[x\]/gim) ?? []).length;
+  const tasksPending = (content.match(/^- \[ \]/gim) ?? []).length;
+  return { name, planApproved, tasksDone, tasksTotal: tasksDone + tasksPending };
+}
+function statusCommand() {
+  const cwd = process.cwd();
+  if (!import_fs5.default.existsSync(import_path5.default.join(cwd, ".sdd"))) {
+    console.error("\n  error    .sdd/ not found. Run `npx sddx-workflow init` first.\n");
+    process.exit(1);
+  }
+  console.log("");
+  const bootstrapped = isBootstrapped(cwd);
+  console.log(`  bootstrap    ${bootstrapped ? "done" : "pending \u2014 run /bootstrap"}`);
+  const specsDir = import_path5.default.join(cwd, "specs");
+  if (!import_fs5.default.existsSync(specsDir)) {
+    console.log("  open specs   0");
+    console.log("");
+    return;
+  }
+  const specs = import_fs5.default.readdirSync(specsDir).filter((name) => name !== "_template" && name !== "_done").filter((name) => import_fs5.default.statSync(import_path5.default.join(specsDir, name)).isDirectory()).map((name) => readSpec(import_path5.default.join(specsDir, name)));
+  console.log(`  open specs   ${specs.length}`);
+  for (const spec of specs) {
+    const label = spec.name.padEnd(14);
+    if (!spec.planApproved) {
+      console.log(`    ${label} awaiting approval`);
+    } else if (spec.tasksDone === spec.tasksTotal && spec.tasksTotal > 0) {
+      console.log(`    ${label} ${spec.tasksDone}/${spec.tasksTotal} tasks \xB7 done`);
+    } else {
+      console.log(`    ${label} ${spec.tasksDone}/${spec.tasksTotal} tasks \xB7 in progress`);
+    }
+  }
+  console.log("");
+}
+
+// src/cli.ts
+var import_module = require("module");
+var pkg = (0, import_module.createRequire)(__filename)("../package.json");
+var program = new import_commander.Command();
+program.name("sddx-workflow").description("Spec-Driven Development CLI").version(pkg.version);
+program.command("init").description("Initialize SDD protocol in the current project").option("--force", "Overwrite files that already exist").action(initCommand);
+program.command("add <type> <name>").description("Add an SDD component to an existing installation").addHelpText("after", "\nExamples:\n  $ sddx-workflow add domain auth\n  $ sddx-workflow add domain payments").action(addCommand);
+program.command("update").description("Update protocol files to the latest version (leaves your config files untouched)").action(updateCommand);
+program.command("status").description("Show bootstrap status and open specs progress").action(statusCommand);
+program.parseAsync();

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "sddx-workflow",
+  "version": "0.6.0",
+  "description": "Spec-Driven Development CLI — installs an SDD system in any project",
+  "keywords": [
+    "sdd",
+    "spec-driven",
+    "ai",
+    "claude",
+    "cursor",
+    "cli"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MarcosCamara01/sddx-workflow.git"
+  },
+  "homepage": "https://github.com/MarcosCamara01/sddx-workflow#readme",
+  "bugs": {
+    "url": "https://github.com/MarcosCamara01/sddx-workflow/issues"
+  },
+  "bin": {
+    "sddx-workflow": "dist/cli.js"
+  },
+  "files": [
+    "dist/",
+    "templates/"
+  ],
+  "scripts": {
+    "build": "tsup && chmod +x dist/cli.js",
+    "dev": "tsup --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^8.4.2",
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/templates/CLAUDE.md

@@ -0,0 +1,35 @@
+# Claude — Project Context
+
+This project uses the SDD Protocol. Read these files before starting any task:
+
+1. **[.sdd/workflow.md](.sdd/workflow.md)** — commands, ceremony levels, and stop points
+2. **[.sdd/project-overview.md](.sdd/project-overview.md)** — what this app is, its non-goals, domains, and definition of done
+3. **[.sdd/conventions.md](.sdd/conventions.md)** — project-specific conventions and patterns
+
+## Quick Reference
+
+| Intent | Command |
+|---|---|
+| Initialize project context | `/bootstrap` (new) · `/bootstrap --scan` (existing) |
+| Explore / research | `/ask` |
+| Surface and validate assumptions | `/assume` |
+| Fix a confirmed bug | `/bugfix` → `/finish` |
+| Restructure without behavior change | `/refactor` → `/finish` |
+| New feature | `/spec-new` → `/spec-plan` → `/spec-tasks` → `/review` → `/finish` |
+| Stage + commit after any work | `/finish` |
+
+## Active Specs
+
+<!-- List specs currently in progress — completed specs live in specs/_done/ and are not active context.
+- specs/auth-refresh/ — in /spec-tasks (task 3 of 5)
+- specs/payments-v2/ — plan pending approval
+-->
+
+## Domain Files
+
+Relevant domain context lives in `.sdd/domains/`. Read the relevant domain file before working in that area.
+
+<!-- List domains present in this project, e.g.:
+- [.sdd/domains/auth.md](.sdd/domains/auth.md)
+- [.sdd/domains/payments.md](.sdd/domains/payments.md)
+-->

package/templates/claude-commands/ask.md

@@ -0,0 +1,5 @@
+Execute the /ask command defined in .sdd/workflow.md.
+
+Research and exploration only — no code changes. Read files, analyze, and summarize findings with explicit options or recommendations.
+
+Topic: $ARGUMENTS

package/templates/claude-commands/assume.md

@@ -0,0 +1,7 @@
+Execute the /assume command defined in .sdd/workflow.md.
+
+List every assumption being made about the task, codebase state, and technical decisions.
+For each: what you're assuming, why, and what changes if it's wrong.
+Stop and wait for confirmation before proceeding.
+
+Context: $ARGUMENTS

package/templates/claude-commands/bootstrap.md

@@ -0,0 +1,5 @@
+Execute the /bootstrap command defined in .sdd/workflow.md.
+
+Populate .sdd/project-overview.md and .sdd/conventions.md with real project context.
+If $ARGUMENTS contains --scan, analyze the existing codebase first before asking questions.
+Present the full draft for approval before writing any file.

package/templates/claude-commands/bugfix.md

@@ -0,0 +1,6 @@
+Execute the /bugfix command defined in .sdd/workflow.md.
+
+Follow the stages in order: Reproduce → Diagnose → Fix → Validate.
+Do not skip stages. Stop after Reproduce if the bug cannot be confirmed.
+
+Bug or error: $ARGUMENTS

package/templates/claude-commands/finish.md

@@ -0,0 +1,5 @@
+Execute the /finish command defined in .sdd/workflow.md.
+
+Run git status and git diff. Stage all relevant files. Determine the commit type.
+Draft a conventional commit message following the format in workflow.md.
+Stop and present the staged files and commit message for approval before committing.

package/templates/claude-commands/refactor.md

@@ -0,0 +1,6 @@
+Execute the /refactor command defined in .sdd/workflow.md.
+
+Restructure code without changing external behavior. Establish a green test baseline first.
+Every observable behavior before the refactor must be identical after it.
+
+Target: $ARGUMENTS

package/templates/claude-commands/review.md

@@ -0,0 +1,5 @@
+Execute the /review command defined in .sdd/workflow.md.
+
+Audit the spec before closing. Verify all goals (G1, G2…) are satisfied, every acceptance scenario has a passing test, no out-of-scope changes were introduced, and the implementation is the simplest that meets requirements.
+
+Spec: $ARGUMENTS

package/templates/claude-commands/spec-new.md

@@ -0,0 +1,4 @@
+Execute the /spec-new command defined in .sdd/workflow.md.
+
+Create a specs/$ARGUMENTS/ folder by copying the three template files from specs/_template/.
+Replace <Feature Name> in each file title with the actual feature name.

package/templates/claude-commands/spec-plan.md

@@ -0,0 +1,4 @@
+Execute the /spec-plan command defined in .sdd/workflow.md.
+
+Read specs/$ARGUMENTS/1-requirements.md, run /assume, then draft the technical plan in specs/$ARGUMENTS/2-plan.md.
+Stop for explicit approval before writing any implementation code.

package/templates/claude-commands/spec-tasks.md

@@ -0,0 +1,5 @@
+Execute the /spec-tasks command defined in .sdd/workflow.md.
+
+Read the approved specs/$ARGUMENTS/2-plan.md and execute tasks one at a time.
+Write the test first (red), implement until green, run the full suite, then move to the next task.
+Stop if tests fail or if a task reveals new scope.

package/templates/conventions/base.md

@@ -0,0 +1,32 @@
+# Project Conventions
+
+> Fill this out before starting any non-trivial work.
+> The AI agent reads this file before implementing anything.
+
+## Tech Stack
+
+<!-- Primary technologies, frameworks, libraries, and their versions -->
+
+## File & Folder Structure
+
+<!-- How the project is organized. Point out anything non-obvious. -->
+
+## Naming Conventions
+
+<!-- Files, functions, variables, types — rules and examples -->
+
+## Code Style
+
+<!-- Patterns to follow, abstractions in use, preferred approaches -->
+
+## Patterns to Avoid
+
+<!-- Anti-patterns, deprecated approaches, things that have caused bugs before -->
+
+## Testing
+
+<!-- How tests are structured, what needs to be tested, coverage expectations -->
+
+## Domain Glossary
+
+<!-- Key terms in this project and what they mean precisely -->

package/templates/copilot-instructions.md

@@ -0,0 +1,33 @@
+# GitHub Copilot Instructions
+
+This project uses the SDD Protocol. Before starting any task, read:
+
+1. `.sdd/workflow.md` — all commands, ceremony levels, and stop points
+2. `.sdd/project-overview.md` — what this app is, its non-goals, and domains
+3. `.sdd/conventions.md` — project-specific conventions and patterns
+
+## Available commands
+
+Use these slash commands in Copilot Chat (type `/` to see them):
+
+| Command | Purpose |
+|---|---|
+| `/bootstrap` | Populate project context — interview or codebase scan |
+| `/ask` | Research only — no code changes |
+| `/assume` | List assumptions and stop for confirmation |
+| `/bugfix` | Reproduce → diagnose → fix → validate |
+| `/refactor` | Restructure without behavior change |
+| `/spec-new` | Scaffold a spec folder |
+| `/spec-plan` | Generate technical plan — stop for approval |
+| `/spec-tasks` | Execute plan one task at a time, TDD-first |
+| `/review` | Final audit before closing |
+| `/finish` | Stage files and generate commit message |
+
+## Execution principles
+
+1. Surface assumptions before acting — never pick an interpretation silently; if a simpler approach exists, say so and push back
+2. Minimum code — only what was asked; no speculative flexibility, no error handling for impossible scenarios; ask "would a senior engineer say this is overcomplicated?"
+3. Surgical changes — touch only what the task requires; match existing style; remove only orphans *your* changes created, not pre-existing dead code; every changed line must trace to the request
+4. Verify before moving on — transform vague tasks into verifiable goals ("Fix bug" → "Write failing test, then make it pass"); define "done" before starting
+
+Full definitions for each command are in `.sdd/workflow.md`.