clawstrap 1.2.0 → 1.3.0

package/README.md

@@ -49,12 +49,15 @@ Scaffold a production-ready AI agent workspace.
 
 ? Enable session handoff checklists? (for multi-session work) Yes
 
+? Enable Spec-Driven Development? (write specs before implementing) Yes
+
 Configuration:
   Workspace:       my-project
   Workload:        Research & Analysis
   Parallel agents: single
   Quality level:   team
   Session handoff: yes
+  Spec-driven dev: yes
 
 Generating your workspace...
 
@@ -103,6 +106,8 @@ my-project/
 │   │   └── SKILL_REGISTRY.md        # Skill index
 │   ├── memory/
 │   │   └── MEMORY.md                # Cross-session memory (session handoff only)
+│   ├── commands/
+│   │   └── spec.md                  # /spec slash command (SDD only)
 │   ├── subagent-bootstrap.md        # Lightweight ad-hoc governance (multi-agent only)
 │   ├── gotcha-log.md                # Incident tracking — why rules exist
 │   └── future-considerations.md     # Deferred ideas parking lot
@@ -110,6 +115,8 @@ my-project/
 │   └── _template/
 │       ├── README.md                # Project metadata template
 │       └── process.md               # Workflow and session checklist template
+├── specs/
+│   └── _template.md                 # Spec template (SDD only)
 ├── tmp/                             # Gitignored session workspace
 ├── research/                        # Reference material
 ├── context/                         # Session checkpoints
@@ -321,6 +328,7 @@ Every rule in a Clawstrap workspace exists because something went wrong without
 ```
 clawstrap init [directory]                    Scaffold a new workspace (interactive)
 clawstrap init [directory] --yes              Use defaults, skip prompts
+clawstrap init [directory] --sdd              Enable Spec-Driven Development mode
 clawstrap add agent <name>                    Add a new agent definition
 clawstrap add skill <name>                    Add a new skill with SKILL.md
 clawstrap add project <name>                  Add a new project with README + process.md
@@ -346,11 +354,60 @@ Generates a directory with `paperclip.manifest.json`, agent definitions with fro
 | `--mission`, `-m` | Company mission statement |
 | `--adapter`, `-a` | Agent adapter type (default: `claude_local`) |
 
+## Spec-Driven Development
+
+Enable SDD mode to enforce a spec-first workflow. Before Claude implements anything, it writes a structured spec, saves it to `specs/{name}.md`, and gets your explicit approval.
+
+```bash
+npx clawstrap init --sdd
+```
+
+What you get:
+
+- **`specs/_template.md`** — reusable spec format with problem statement, acceptance criteria, technical constraints, out-of-scope, and implementation notes
+- **`.claude/rules/sdd.md`** — governance rule Claude loads every session: "Never implement from a vague prompt"
+- **`.claude/commands/spec.md`** — `/spec` slash command that walks Claude through writing, saving, and presenting a spec for approval
+
+In practice:
+
+```
+You: Build a CSV export for the orders table.
+
+Claude: Writing spec to specs/csv-export-orders.md...
+
+        # Spec: CSV Export — Orders Table
+        Status: draft | Created: 2026-04-04
+
+        ## Problem Statement
+        Users need to export order data for reporting in external tools.
+
+        ## Acceptance Criteria
+        - [ ] Export all orders or filter by date range
+        - [ ] CSV includes: order_id, customer, total, status, created_at
+        - [ ] Empty state handled gracefully
+        - [ ] File named orders-export-{date}.csv
+
+        ## Technical Constraints
+        - Must use existing DB connection pool
+        - Must stream for large datasets (>10k rows)
+
+        ## Out of Scope
+        - PDF export
+        - Scheduled exports
+
+        Does this spec look right? Any changes before I start?
+
+You: Looks good, go ahead.
+
+Claude: Implementing from spec...
+```
+
 ## Flags
 
 | Flag | Description |
 |------|-------------|
 | `--yes`, `-y` | Skip prompts, use sensible defaults (init only) |
+| `--sdd` | Enable Spec-Driven Development mode (init only) |
 | `--version` | Show version |
 | `--help` | Show help |
 
@@ -360,7 +417,8 @@ Generates a directory with `paperclip.manifest.json`, agent definitions with fro
 |---------|--------|------|
 | **v1.0** | Done | `init` command, 4 workspace profiles, full governance templates, `--yes` mode |
 | **v1.1** | Done | `add agent`, `add skill`, `add project`, `status` commands |
-| **v1.2** | **Now** | `export --format paperclip` — Paperclip company template export |
+| **v1.2** | Done | `export --format paperclip` — Paperclip company template export |
+| **v1.3** | **Now** | `--sdd` flag — Spec-Driven Development mode with `/spec` slash command |
 | **v2.0** | Planned | Multi-model support, `upgrade` command, ClipMart publishing |
 
 ## Contributing

package/dist/index.cjs

@@ -57,6 +57,7 @@ var ClawstrapConfigSchema = import_zod.z.object({
   parallelAgents: import_zod.z.enum(PARALLEL_AGENTS),
   qualityLevel: import_zod.z.enum(QUALITY_LEVELS),
   sessionHandoff: import_zod.z.boolean(),
+  sdd: import_zod.z.boolean().default(false),
   lastExport: LastExportSchema
 });
 
@@ -104,7 +105,9 @@ function deriveTemplateVars(config) {
     hasQualityGates: config.qualityLevel !== "solo",
     isProductionQuality: config.qualityLevel === "production",
     // Session handoff
-    sessionHandoff: config.sessionHandoff
+    sessionHandoff: config.sessionHandoff,
+    // Spec-Driven Development
+    sddEnabled: config.sdd
   };
 }
 
@@ -210,15 +213,30 @@ var OUTPUT_MANIFEST = [
     templateKey: "memoryIndex",
     outputPath: "{%systemDir%}/memory/MEMORY.md",
     condition: "sessionHandoff"
+  },
+  {
+    templateKey: "sddRule",
+    outputPath: "{%systemDir%}/rules/sdd.md",
+    condition: "sddEnabled"
+  },
+  {
+    templateKey: "sddSpecTemplate",
+    outputPath: "specs/_template.md",
+    condition: "sddEnabled"
+  },
+  {
+    templateKey: "sddSpecCommand",
+    outputPath: "{%systemDir%}/commands/spec.md",
+    condition: "sddEnabled"
   }
 ];
 var EMPTY_DIRS = ["tmp", "research", "context", "artifacts"];
 
 // src/templates/governance-file.md.tmpl
-var governance_file_md_default = "# {%governanceFile%} \u2014 Master Governance Rules\n> **Workspace**: {%workspaceName%} | **Generated**: {%generatedDate%} | **Status**: active\n> Loaded every session. Keep lean. Move details to skills or rules files.\n\n---\n\n## Workflow Rules\n\n**Approval-first, always.**\nPlan work and get explicit approval before executing. No speculative actions.\nIf scope changes mid-task, pause and re-confirm.\n\n**If it's not on disk, it didn't happen.**\nSave findings immediately, not at session end. Flush {%flushCadence%}.\nWrite corrections to durable locations before applying them.\n{%#if hasSubagents%}Subagents return file paths, not raw data.{%/if%}\n\n**Quality > context cleanliness > speed > token cost.**\nQuality failures require full rework (100% waste). Never trade quality for tokens.\n{%#if isResearch%}\n**Research-specific:**\n- Cite sources for every claim \u2014 no unsourced assertions\n- Write findings to file immediately, not at session end\n- Separate facts from interpretation in all output\n{%/if%}\n{%#if isContent%}\n**Content-specific:**\n- Every piece of content follows the draft \u2192 review \u2192 approve cycle\n- Never publish or finalize without explicit approval\n- Track all revision feedback in a dedicated file\n{%/if%}\n{%#if isDataProcessing%}\n**Data processing-specific:**\n- Define batch size before starting \u2014 never process unbounded sets\n- Validate schema on every write\n- Log every transformation step for auditability\n{%/if%}\n\n---\n\n## Persistence Hierarchy\n\nFrom most ephemeral to most durable:\n\n| Layer | Location | Loaded When |\n|-------|----------|-------------|\n| Conversation | (in-context) | Always \u2014 volatile |\n| Temp files | `tmp/` | Per-task, gitignored |\n{%#if sessionHandoff%}| Memory | `{%systemDir%}/memory/` | On demand |\n{%/if%}| Skills | `{%systemDir%}/skills/*/SKILL.md` | When triggered |\n| Rules | `{%systemDir%}/rules/*.md` | Every session |\n| **{%governanceFile%}** | `./{%governanceFile%}` | **Every session** |\n\n---\n\n## Context Discipline\n\n- Flush working state to file {%flushCadence%}\n{%#if hasSubagents%}- Subagents write output to `tmp/{task}/{name}.json`; return one-line receipt\n- Main session reads subagent files ONLY if needed for the next step\n- Never hold raw batch results in conversation \u2014 write to disk first\n{%/if%}- Before batch work: write execution plan to file (survives context loss)\n\n---\n{%#if sessionHandoff%}\n## Session Handoff Checklist\n\nRun this at every session end (mandatory, not optional):\n\n1. Save all work to SSOT files\n2. Sync derived files (rebuild from SSOTs)\n3. SSOT integrity check (no duplicates, no stale data)\n4. Update progress tracker\n5. Write next-session plan (with pre-execution hooks listed)\n6. Launch QC on work done this session\n\n---\n{%/if%}\n\n## Security Rules\n\n- Never read `.env` files or echo credentials\n- Never install third-party MCP servers/plugins without explicit approval\n- Never write outside this workspace root \u2014 use project-local `tmp/`, not system `/tmp/`\n- Approved tools only \u2014 ask before using new tools/APIs\n\n---\n\n## Quality Rules\n{%#if isProductionQuality%}\n- QC is a structural gate, not an optional post-step\n- Run spot-checks after every 5 items in batch work (Ralph Loop)\n- Combined agents (extract + classify) beat split agents on quality\n- Disagreements between agents reveal ambiguity \u2014 escalate, don't suppress\n{%/if%}\n{%#if hasQualityGates%}\n{%#unless isProductionQuality%}- QC is a structural gate, not an optional post-step\n- Run QC checkpoints at regular intervals during batch work\n- All results must be reviewed before being marked complete\n{%/unless%}\n{%/if%}\n{%#unless hasQualityGates%}- Run a quick check before finishing any task\n- Review outputs before marking work complete\n{%/unless%}\n\n---\n\n## Pointers to Other Layers\n\n- Rules: `{%systemDir%}/rules/` \u2014 domain-specific rules loaded every session\n- Skills: `{%systemDir%}/skills/SKILL_REGISTRY.md` \u2014 index of all skills\n{%#if hasSubagents%}- Agents: `{%systemDir%}/agents/` \u2014 subagent definitions with governance baked in\n{%/if%}- Gotchas: `{%systemDir%}/gotcha-log.md` \u2014 incident log (why rules exist)\n- Future: `{%systemDir%}/future-considerations.md` \u2014 deferred ideas\n";
+var governance_file_md_default = "# {%governanceFile%} \u2014 Master Governance Rules\n> **Workspace**: {%workspaceName%} | **Generated**: {%generatedDate%} | **Status**: active\n> Loaded every session. Keep lean. Move details to skills or rules files.\n\n---\n\n## Workflow Rules\n\n**Approval-first, always.**\nPlan work and get explicit approval before executing. No speculative actions.\nIf scope changes mid-task, pause and re-confirm.\n\n**If it's not on disk, it didn't happen.**\nSave findings immediately, not at session end. Flush {%flushCadence%}.\nWrite corrections to durable locations before applying them.\n{%#if hasSubagents%}Subagents return file paths, not raw data.{%/if%}\n\n**Quality > context cleanliness > speed > token cost.**\nQuality failures require full rework (100% waste). Never trade quality for tokens.\n{%#if isResearch%}\n**Research-specific:**\n- Cite sources for every claim \u2014 no unsourced assertions\n- Write findings to file immediately, not at session end\n- Separate facts from interpretation in all output\n{%/if%}\n{%#if isContent%}\n**Content-specific:**\n- Every piece of content follows the draft \u2192 review \u2192 approve cycle\n- Never publish or finalize without explicit approval\n- Track all revision feedback in a dedicated file\n{%/if%}\n{%#if isDataProcessing%}\n**Data processing-specific:**\n- Define batch size before starting \u2014 never process unbounded sets\n- Validate schema on every write\n- Log every transformation step for auditability\n{%/if%}\n\n---\n\n## Persistence Hierarchy\n\nFrom most ephemeral to most durable:\n\n| Layer | Location | Loaded When |\n|-------|----------|-------------|\n| Conversation | (in-context) | Always \u2014 volatile |\n| Temp files | `tmp/` | Per-task, gitignored |\n{%#if sessionHandoff%}| Memory | `{%systemDir%}/memory/` | On demand |\n{%/if%}| Skills | `{%systemDir%}/skills/*/SKILL.md` | When triggered |\n| Rules | `{%systemDir%}/rules/*.md` | Every session |\n| **{%governanceFile%}** | `./{%governanceFile%}` | **Every session** |\n\n---\n\n## Context Discipline\n\n- Flush working state to file {%flushCadence%}\n{%#if hasSubagents%}- Subagents write output to `tmp/{task}/{name}.json`; return one-line receipt\n- Main session reads subagent files ONLY if needed for the next step\n- Never hold raw batch results in conversation \u2014 write to disk first\n{%/if%}- Before batch work: write execution plan to file (survives context loss)\n\n---\n{%#if sessionHandoff%}\n## Session Handoff Checklist\n\nRun this at every session end (mandatory, not optional):\n\n1. Save all work to SSOT files\n2. Sync derived files (rebuild from SSOTs)\n3. SSOT integrity check (no duplicates, no stale data)\n4. Update progress tracker\n5. Write next-session plan (with pre-execution hooks listed)\n6. Launch QC on work done this session\n\n---\n{%/if%}\n\n## Security Rules\n\n- Never read `.env` files or echo credentials\n- Never install third-party MCP servers/plugins without explicit approval\n- Never write outside this workspace root \u2014 use project-local `tmp/`, not system `/tmp/`\n- Approved tools only \u2014 ask before using new tools/APIs\n\n---\n\n## Quality Rules\n{%#if isProductionQuality%}\n- QC is a structural gate, not an optional post-step\n- Run spot-checks after every 5 items in batch work (Ralph Loop)\n- Combined agents (extract + classify) beat split agents on quality\n- Disagreements between agents reveal ambiguity \u2014 escalate, don't suppress\n{%/if%}\n{%#if hasQualityGates%}\n{%#unless isProductionQuality%}- QC is a structural gate, not an optional post-step\n- Run QC checkpoints at regular intervals during batch work\n- All results must be reviewed before being marked complete\n{%/unless%}\n{%/if%}\n{%#unless hasQualityGates%}- Run a quick check before finishing any task\n- Review outputs before marking work complete\n{%/unless%}\n\n---\n\n## Pointers to Other Layers\n\n- Rules: `{%systemDir%}/rules/` \u2014 domain-specific rules loaded every session\n- Skills: `{%systemDir%}/skills/SKILL_REGISTRY.md` \u2014 index of all skills\n{%#if hasSubagents%}- Agents: `{%systemDir%}/agents/` \u2014 subagent definitions with governance baked in\n{%/if%}- Gotchas: `{%systemDir%}/gotcha-log.md` \u2014 incident log (why rules exist)\n- Future: `{%systemDir%}/future-considerations.md` \u2014 deferred ideas\n{%#if sddEnabled%}\n---\n\n## Spec-Driven Development\n\nThis workspace uses SDD. Before implementing any feature:\n\n1. Write a spec \u2192 `specs/{name}.md` (use `/spec` or copy `specs/_template.md`)\n2. Get explicit user approval\n3. Implement from the approved spec \u2014 not from the conversation\n\nRule details: `{%systemDir%}/rules/sdd.md`\n{%/if%}\n";
 
 // src/templates/getting-started.md.tmpl
-var getting_started_md_default = "# Getting Started \u2014 {%workspaceName%}\n> Generated by Clawstrap v{%clawstrapVersion%} on {%generatedDate%}\n\nWelcome to your AI agent workspace. This workspace is configured for\n**{%workloadLabel%}** workflows.\n\n---\n\n## Quick Start\n\n1. **Read `{%governanceFile%}`** \u2014 this is your master governance file. It loads\n   automatically every session and defines the rules your AI assistant follows.\n\n2. **Check `{%systemDir%}/rules/`** \u2014 these rule files also load every session.\n   They contain detailed procedures for context discipline, approval workflows,\n   and quality gates.\n\n3. **Start working** \u2014 open a Claude Code session in this directory. The\n   governance files will load automatically.\n\n---\n\n## What's in This Workspace\n\n```\n{%governanceFile%}                    \u2190 Master governance (always loaded)\nGETTING_STARTED.md               \u2190 You are here\n.clawstrap.json                  \u2190 Your workspace configuration\n\n{%systemDir%}/\n  rules/                         \u2190 Auto-loaded rules (every session)\n  skills/                        \u2190 Skill definitions (loaded when triggered)\n{%#if hasSubagents%}  agents/                        \u2190 Agent definitions\n{%/if%}  gotcha-log.md                  \u2190 Incident log\n  future-considerations.md       \u2190 Deferred ideas\n{%#if sessionHandoff%}  memory/                        \u2190 Persistent memory across sessions\n{%/if%}\nprojects/\n  _template/                     \u2190 Template for new projects\n\ntmp/                             \u2190 Temporary files (gitignored)\nresearch/                        \u2190 Reference material\ncontext/                         \u2190 Session checkpoints\nartifacts/                       \u2190 Durable output\n```\n\n---\n\n## Key Principles\n\nThis workspace enforces five principles:\n\n1. **If it's not on disk, it didn't happen.** Context windows compress. Sessions\n   end. The only thing that persists is files. Flush work {%flushCadence%}.\n\n2. **Approval-first, always.** Plan work, get approval, then execute. No\n   speculative actions.\n\n3. **Quality is a structural gate.** Quality checks happen during work, not after.\n{%#if hasQualityGates%}   See `{%systemDir%}/rules/quality-gates.md` for the full procedure.{%/if%}\n\n4. **Disagreements reveal ambiguity.** When agents disagree, the rules are\n   ambiguous. Escalate and clarify \u2014 don't suppress.\n\n5. **One decision at a time.** Binary decisions made sequentially compound into\n   reliable outcomes.\n{%#if hasSubagents%}\n\n---\n\n## Working with Multiple Agents\n\nYour workspace is configured for multi-agent workflows. Key rules:\n\n- **Subagents write to `tmp/`** \u2014 they return file paths and one-line summaries,\n  never raw data in conversation.\n- **The main session is an orchestrator** \u2014 it tracks progress, launches agents,\n  and checks output files. It does not hold subagent data in memory.\n- **Agent definitions live in `{%systemDir%}/agents/`** \u2014 each file becomes the\n  system prompt for a subagent. Governance is baked into the definition.\n{%/if%}\n{%#if sessionHandoff%}\n\n---\n\n## Session Handoff\n\nThis workspace uses session handoff checklists. At the end of every session:\n\n1. Save all work to SSOT files\n2. Sync derived files\n3. Check SSOT integrity\n4. Update progress tracker\n5. Write next-session plan\n6. Run QC on session work\n\nThis ensures no context is lost between sessions.\n{%/if%}\n{%#if isResearch%}\n\n---\n\n## Research Tips\n\n- Write findings to disk immediately \u2014 don't accumulate in conversation\n- Cite sources for every claim\n- Separate facts from interpretation\n- Use `research/` for reference material, `artifacts/` for synthesis output\n{%/if%}\n{%#if isContent%}\n\n---\n\n## Content Workflow Tips\n\n- Every piece follows: draft \u2192 review \u2192 approve\n- Track revision feedback in dedicated files\n- Never finalize without explicit approval\n- Use `artifacts/` for final deliverables\n{%/if%}\n{%#if isDataProcessing%}\n\n---\n\n## Data Processing Tips\n\n- Define batch size before starting any processing run\n- Validate schema on every write\n- Checkpoint every 5 batch items\n- Log all transformations for auditability\n{%/if%}\n\n---\n\n*This workspace was generated by [Clawstrap](https://github.com/clawstrap/clawstrap).\nEdit any file to fit your needs \u2014 there's no lock-in.*\n";
+var getting_started_md_default = "# Getting Started \u2014 {%workspaceName%}\n> Generated by Clawstrap v{%clawstrapVersion%} on {%generatedDate%}\n\nWelcome to your AI agent workspace. This workspace is configured for\n**{%workloadLabel%}** workflows.\n\n---\n\n## Quick Start\n\n1. **Read `{%governanceFile%}`** \u2014 this is your master governance file. It loads\n   automatically every session and defines the rules your AI assistant follows.\n\n2. **Check `{%systemDir%}/rules/`** \u2014 these rule files also load every session.\n   They contain detailed procedures for context discipline, approval workflows,\n   and quality gates.\n\n3. **Start working** \u2014 open a Claude Code session in this directory. The\n   governance files will load automatically.\n\n---\n\n## What's in This Workspace\n\n```\n{%governanceFile%}                    \u2190 Master governance (always loaded)\nGETTING_STARTED.md               \u2190 You are here\n.clawstrap.json                  \u2190 Your workspace configuration\n\n{%systemDir%}/\n  rules/                         \u2190 Auto-loaded rules (every session)\n  skills/                        \u2190 Skill definitions (loaded when triggered)\n{%#if hasSubagents%}  agents/                        \u2190 Agent definitions\n{%/if%}  gotcha-log.md                  \u2190 Incident log\n  future-considerations.md       \u2190 Deferred ideas\n{%#if sessionHandoff%}  memory/                        \u2190 Persistent memory across sessions\n{%/if%}\nprojects/\n  _template/                     \u2190 Template for new projects\n\ntmp/                             \u2190 Temporary files (gitignored)\nresearch/                        \u2190 Reference material\ncontext/                         \u2190 Session checkpoints\nartifacts/                       \u2190 Durable output\n{%#if sddEnabled%}specs/\n  _template.md                   \u2190 Spec template (copy for each feature)\n{%/if%}```\n\n---\n\n## Key Principles\n\nThis workspace enforces five principles:\n\n1. **If it's not on disk, it didn't happen.** Context windows compress. Sessions\n   end. The only thing that persists is files. Flush work {%flushCadence%}.\n\n2. **Approval-first, always.** Plan work, get approval, then execute. No\n   speculative actions.\n\n3. **Quality is a structural gate.** Quality checks happen during work, not after.\n{%#if hasQualityGates%}   See `{%systemDir%}/rules/quality-gates.md` for the full procedure.{%/if%}\n\n4. **Disagreements reveal ambiguity.** When agents disagree, the rules are\n   ambiguous. Escalate and clarify \u2014 don't suppress.\n\n5. **One decision at a time.** Binary decisions made sequentially compound into\n   reliable outcomes.\n{%#if hasSubagents%}\n\n---\n\n## Working with Multiple Agents\n\nYour workspace is configured for multi-agent workflows. Key rules:\n\n- **Subagents write to `tmp/`** \u2014 they return file paths and one-line summaries,\n  never raw data in conversation.\n- **The main session is an orchestrator** \u2014 it tracks progress, launches agents,\n  and checks output files. It does not hold subagent data in memory.\n- **Agent definitions live in `{%systemDir%}/agents/`** \u2014 each file becomes the\n  system prompt for a subagent. Governance is baked into the definition.\n{%/if%}\n{%#if sessionHandoff%}\n\n---\n\n## Session Handoff\n\nThis workspace uses session handoff checklists. At the end of every session:\n\n1. Save all work to SSOT files\n2. Sync derived files\n3. Check SSOT integrity\n4. Update progress tracker\n5. Write next-session plan\n6. Run QC on session work\n\nThis ensures no context is lost between sessions.\n{%/if%}\n{%#if isResearch%}\n\n---\n\n## Research Tips\n\n- Write findings to disk immediately \u2014 don't accumulate in conversation\n- Cite sources for every claim\n- Separate facts from interpretation\n- Use `research/` for reference material, `artifacts/` for synthesis output\n{%/if%}\n{%#if isContent%}\n\n---\n\n## Content Workflow Tips\n\n- Every piece follows: draft \u2192 review \u2192 approve\n- Track revision feedback in dedicated files\n- Never finalize without explicit approval\n- Use `artifacts/` for final deliverables\n{%/if%}\n{%#if isDataProcessing%}\n\n---\n\n## Data Processing Tips\n\n- Define batch size before starting any processing run\n- Validate schema on every write\n- Checkpoint every 5 batch items\n- Log all transformations for auditability\n{%/if%}\n\n---\n\n{%#if sddEnabled%}\n\n---\n\n## Spec-Driven Development\n\nThis workspace enforces a spec-first workflow. Before any implementation:\n\n1. **Type `/spec`** to start a new spec interactively \u2014 Claude will guide you\n2. Or copy `specs/_template.md` manually, fill it in, and get approval\n3. Only implement after the spec is approved\n\nYour specs live in `specs/`. Each approved spec is the contract between you and\nClaude \u2014 implementation follows the spec, not the conversation.\n\nSee `{%systemDir%}/rules/sdd.md` for the full rules and exemptions.\n{%/if%}\n\n---\n\n*This workspace was generated by [Clawstrap](https://github.com/clawstrap/clawstrap).\nEdit any file to fit your needs \u2014 there's no lock-in.*\n";
 
 // src/templates/gitignore.tmpl
 var gitignore_default = "# Dependencies\nnode_modules/\n\n# Temporary files (subagent output, session data)\ntmp/\n\n# Secrets\n.env\n.env.*\ncredentials.json\n*.pem\n*.key\n\n# OS\n.DS_Store\nThumbs.db\n\n# Editor\n*.swp\n*.swo\n*~\n";
@@ -327,6 +345,15 @@ var add_project_readme_md_default = "# Project: {%projectName%}\n> **Status**: a
 // src/templates/projects/add-project-process.md.tmpl
 var add_project_process_md_default = '# Process: {%projectName%}\n> Workflow, hooks, and session checklist for this project.\n> Update this file as the workflow evolves.\n\n---\n{%#if sessionHandoff%}\n## Session Start Checklist (Pre-Hooks)\n\nRun these at the start of every session on this project:\n\n1. [ ] Read `README.md` \u2014 confirm current status and next step\n2. [ ] Read `{%governanceFile%}` (auto-loaded, but confirm it\'s current)\n3. [ ] Check `tmp/{task}/plan.md` if a batch is in progress\n4. [ ] Confirm SSOT files are in expected state (no stale data)\n\n---\n\n## Session End Checklist (Post-Hooks)\n\nRun these at the end of every session (mandatory \u2014 not optional):\n\n1. [ ] Save all work to SSOT files\n2. [ ] Sync derived files (regenerate from SSOTs)\n3. [ ] SSOT integrity check (no duplicates, no stale data)\n4. [ ] Update `README.md` \u2192 "Last done" and "Next" fields\n5. [ ] Write next-session plan to `tmp/{task}/plan.md`\n6. [ ] Run QC on work done this session\n\n---\n{%/if%}\n\n## Execution Workflow\n\n*(Describe the main execution loop for this project\'s primary task)*\n{%#if isResearch%}\n```\n1. Define research question \u2192 get approval\n2. Gather sources \u2192 write findings to file immediately\n3. Synthesize \u2192 cite all sources\n4. QC gate: {%flushCadence%}\n5. Output: artifacts/{topic}/synthesis.md\n```\n{%/if%}\n{%#if isContent%}\n```\n1. Brief \u2192 get approval on scope and outline\n2. Draft \u2192 write to artifacts/\n3. Review \u2192 collect feedback in dedicated file\n4. Revise \u2192 approval required before finalizing\n5. QC gate: {%flushCadence%}\n```\n{%/if%}\n{%#if isDataProcessing%}\n```\n1. Plan \u2192 get approval \u2192 define batch size\n2. Process batch \u2192 validate schema on every write\n3. QC gate: {%flushCadence%} (Ralph Loop)\n4. Output: tmp/{task}/{name}.json\n5. Human review \u2192 finalize\n```\n{%/if%}\n{%#if isCustom%}\n```\n1. Plan \u2192 get approval \u2192 execute\n2. Batch size: [N items per batch]\n3. QC gate: {%flushCadence%}\n4. Output: tmp/{task}/{name}.json\n```\n{%/if%}\n\n---\n{%#if hasQualityGates%}\n## Active Batch Tracking\n\n| Batch | Status | QC Grade | Notes |\n|-------|--------|----------|-------|\n| *(none yet)* | \u2014 | \u2014 | \u2014 |\n\n---\n{%/if%}\n\n## Known Gotchas (Project-Specific)\n\n*(1-2 line summaries of project-specific failure modes)*\n\n*(None yet \u2014 add entries as issues arise)*\n';
 
+// src/templates/rules/sdd.md.tmpl
+var sdd_md_default = '# Rule: Spec-Driven Development\n> **Scope**: All sessions | **Version**: 1.0 | **Generated**: {%generatedDate%}\n\n## The Rule\n\nNever implement from a vague prompt. Before writing any code or making structural\nchanges, write a spec. Get explicit approval. Then implement from the spec.\n\nThis rule exists because "just do it" prompts produce work that satisfies the\nsurface request while violating unstated constraints. Specs surface those\nconstraints before the work starts.\n\n---\n\n## When to Write a Spec\n\nA spec is required for:\n\n- Any new feature or component\n- Any refactor that touches more than 3 files\n- Any change to a public API or data schema\n- Any work whose scope is not fully clear from the request\n\nA spec is **not** required for:\n\n- Bug fixes under 5 lines\n- Documentation-only changes\n- Adding tests for existing, already-specified behavior\n- Changes explicitly described as "no spec needed" by the user\n\n---\n\n## The Workflow\n\n1. **Receive request** \u2014 user describes what they want\n2. **Write spec** \u2014 create `specs/{kebab-name}.md` using `specs/_template.md`\n3. **Present for approval** \u2014 show the spec to the user before doing any implementation\n4. **Incorporate feedback** \u2014 update the spec until approved; do not start work until then\n5. **Implement from spec** \u2014 treat the approved spec as the contract; flag deviations\n6. **Mark complete** \u2014 update spec status to `complete` after implementation\n\n---\n\n## Spec Naming\n\nUse kebab-case, descriptive, scoped to the feature:\n\n```\nspecs/user-authentication.md\nspecs/csv-export-pipeline.md\nspecs/agent-retry-logic.md\n```\n\n---\n\n## On Pushback\n\nIf the user says "just do it, skip the spec":\n\n- Acknowledge the preference\n- Offer a 5-minute lightweight spec (problem + criteria only) as a compromise\n- If they explicitly confirm "no spec", proceed \u2014 but note the deviation\n\nThe rule exists to protect the user\'s time, not to create friction for its own sake.\n';
+
+// src/templates/sdd-spec-template.md.tmpl
+var sdd_spec_template_md_default = "# Spec: {title}\n> **Status**: draft | **Created**: {%generatedDate%} | **Workspace**: {%workspaceName%}\n\n---\n\n## Problem Statement\n\n_What problem does this solve? What is the user need or pain point?_\n\n---\n\n## Acceptance Criteria\n\n_What must be true for this to be considered done? Be specific and testable._\n\n- [ ] ...\n- [ ] ...\n- [ ] ...\n\n---\n\n## Technical Constraints\n\n_What must this solution comply with?_\n\n- Must use: ...\n- Must not: ...\n- Performance: ...\n- Compatibility: ...\n\n---\n\n## Out of Scope\n\n_What are we explicitly NOT doing in this spec?_\n\n- ...\n\n---\n\n## Open Questions\n\n_What needs to be decided before or during implementation?_\n\n- [ ] ...\n\n---\n\n## Implementation Notes\n\n_Claude fills this in after implementation is complete._\n\n- Approach taken: ...\n- Key decisions made: ...\n- Deviations from spec (if any): ...\n\n---\n\n> Copy this file to `specs/{kebab-feature-name}.md`, fill it in, and get approval\n> before starting work. See `.claude/rules/sdd.md` for the full workflow.\n";
+
+// src/templates/commands/spec.md.tmpl
+var spec_md_default = 'Write a spec for the feature or change the user just described. Follow these steps exactly:\n\n1. Ask the user for the feature name if they haven\'t provided one. Use it to create the spec filename in kebab-case: `specs/{name}.md`.\n\n2. Copy the structure from `specs/_template.md` and fill in each section based on what you know from the conversation:\n   - **Problem Statement**: why this feature is needed\n   - **Acceptance Criteria**: specific, testable conditions for done\n   - **Technical Constraints**: things the solution must or must not do\n   - **Out of Scope**: what you are explicitly not building\n   - **Open Questions**: anything that needs a decision before or during work\n\n3. Save the completed spec to `specs/{name}.md`.\n\n4. Present the spec to the user and ask: "Does this spec look right? Any changes before I start?"\n\n5. Do NOT begin implementation until the user explicitly approves the spec. If they request changes, update the spec and re-present it.\n\n6. Once approved, implement from the spec. If you need to deviate from it during implementation, flag the deviation and get confirmation before proceeding.\n\nThe spec is the contract. Build what the spec says, not what you think was meant.\n';
+
 // src/templates/index.ts
 var templates = {
   governanceFile: governance_file_md_default,
@@ -347,7 +374,10 @@ var templates = {
   newAgent: new_agent_md_default,
   newSkill: new_skill_md_default,
   addProjectReadme: add_project_readme_md_default,
-  addProjectProcess: add_project_process_md_default
+  addProjectProcess: add_project_process_md_default,
+  sddRule: sdd_md_default,
+  sddSpecTemplate: sdd_spec_template_md_default,
+  sddSpecCommand: spec_md_default
 };
 
 // src/writer.ts
@@ -476,12 +506,17 @@ async function runPrompts() {
     message: "Enable session handoff checklists? (for multi-session work)",
     default: true
   });
+  const sdd = await (0, import_prompts.confirm)({
+    message: "Enable Spec-Driven Development? (write specs before implementing)",
+    default: false
+  });
   return {
     workspaceName,
     workloadType,
     parallelAgents,
     qualityLevel,
-    sessionHandoff
+    sessionHandoff,
+    sdd
   };
 }
 function getDefaults(targetDir) {
@@ -491,7 +526,8 @@ function getDefaults(targetDir) {
     workloadType: "custom",
     parallelAgents: "single",
     qualityLevel: "solo",
-    sessionHandoff: true
+    sessionHandoff: true,
+    sdd: false
   };
 }
 
@@ -537,7 +573,8 @@ async function init(directory, options) {
     workloadType: answers.workloadType,
     parallelAgents: answers.parallelAgents,
     qualityLevel: answers.qualityLevel,
-    sessionHandoff: answers.sessionHandoff
+    sessionHandoff: answers.sessionHandoff,
+    sdd: options.sdd ?? answers.sdd
   });
   console.log("\nConfiguration:");
   console.log(`  Workspace:      ${config.workspaceName}`);
@@ -547,6 +584,7 @@ async function init(directory, options) {
   console.log(
     `  Session handoff: ${config.sessionHandoff ? "yes" : "no"}`
   );
+  console.log(`  Spec-driven dev: ${config.sdd ? "yes" : "no"}`);
   const vars = deriveTemplateVars(config);
   console.log("\nGenerating your workspace...\n");
   const result = writeWorkspace(targetDir, vars, config);
@@ -776,6 +814,7 @@ Configuration:`);
   console.log(
     `  Session handoff: ${config.sessionHandoff ? "yes" : "no"}`
   );
+  console.log(`  Spec-driven dev: ${config.sdd ? "yes" : "no"}`);
   console.log(`
 Structure:`);
   console.log(`  Agents:   ${agentCount} (${systemDir}/agents/)`);
@@ -1191,8 +1230,8 @@ Exported to ${import_node_path13.default.relative(process.cwd(), outDir) || outD
 
 // src/index.ts
 var program = new import_commander.Command();
-program.name("clawstrap").description("Scaffold a production-ready AI agent workspace").version("1.2.0");
-program.command("init").description("Create a new AI workspace in the current directory").argument("[directory]", "Target directory", ".").option("-y, --yes", "Use defaults, skip prompts").action(async (directory, options) => {
+program.name("clawstrap").description("Scaffold a production-ready AI agent workspace").version("1.3.0");
+program.command("init").description("Create a new AI workspace in the current directory").argument("[directory]", "Target directory", ".").option("-y, --yes", "Use defaults, skip prompts").option("--sdd", "Enable Spec-Driven Development mode").action(async (directory, options) => {
   await init(directory, options);
 });
 var add = program.command("add").description("Add components to the workspace");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawstrap",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Scaffold a production-ready AI agent workspace in under 2 minutes",
   "type": "module",
   "bin": {