sdd-workflow 1.1.0

package/README.md

@@ -0,0 +1,226 @@
+# SDD Workflow
+
+Specification-Driven Development toolkit for [Claude Code](https://claude.ai/claude-code). Install skills, templates, and tooling into any project to bring structured, AI-assisted development to your workflow.
+
+## What is SDD?
+
+SDD (Specification-Driven Development) is a development workflow that writes specifications before code. It combines the discipline of TDD with AI-assisted implementation, enforced through Claude Code skills.
+
+The pipeline:
+
+```
+Specify --> Test Cases --> Plan --> Tasks --> Implement --> Review
+  (What)     (Verify)    (How)   (When)    (Code)    (Quality)
+```
+
+Every phase produces a document. Documents become contracts. AI implements against those contracts. An independent review verifies compliance.
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npx sdd-workflow
+```
+
+This copies skills, templates, and team configurations into your project:
+
+```
+your-project/
+├── .claude/
+│   ├── skills/sdd-*/       10 SDD skills
+│   └── teams/               Team configurations
+└── .specify/
+    ├── memory/              Project constitution (generated later)
+    ├── specs/               Feature specifications
+    ├── templates/           Document templates
+    └── scripts/             Utility scripts
+```
+
+### 2. Initialize
+
+Open Claude Code in your project and run:
+
+```
+/sdd-init
+```
+
+This analyzes your project structure, detects your tech stack, and generates a project-specific constitution at `.specify/memory/constitution.md`.
+
+### 3. Develop
+
+Start a feature using the full auto pipeline:
+
+```
+/sdd-run 001 Add user authentication
+```
+
+Or step through manually:
+
+```
+/sdd-specify User authentication
+/sdd-testcases
+/sdd-plan
+/sdd-tasks
+/sdd-implement
+/sdd-review
+```
+
+## Installation Options
+
+```bash
+npx sdd-workflow              # Standard install (skip existing files)
+npx sdd-workflow --update     # Incremental update (only changed files)
+npx sdd-workflow --force      # Overwrite all existing files
+npx sdd-workflow --dry-run    # Preview what would be installed/updated
+npx sdd-workflow --update --dry-run  # Preview updates
+```
+
+### Update Modes
+
+| Mode | Behavior | When to use |
+|------|----------|-------------|
+| (default) | Skip existing files | First install |
+| `--update` | Only update source-changed files, skip user-customized | After upgrading sdd-workflow |
+| `--force` | Overwrite everything | Reset to defaults |
+
+**How `--update` works**: On first install, a manifest (`.specify/.sdd-manifest.json`) records file hashes. When you run `--update`, it compares source files against the manifest:
+- Source changed, target is original → auto-update
+- Source changed, target also modified by you → **skip** (protect your customizations)
+- New files in source → auto-add
+- Unchanged → skip
+
+## Available Commands
+
+### Core Pipeline
+
+| Command | Description | Input | Output |
+|---------|-------------|-------|--------|
+| `/sdd-specify` | Create feature specification | Feature name or KB link | `spec.md` |
+| `/sdd-testcases` | Design test cases | spec.md | `testcases.md` |
+| `/sdd-plan` | Plan technical implementation | testcases.md + spec.md | `plan.md` |
+| `/sdd-tasks` | Break down into development tasks | plan.md | `tasks.md` |
+| `/sdd-implement` | Execute development tasks | tasks.md | Code changes |
+| `/sdd-review` | Independent quality review | spec + plan + code | Review report |
+
+### Automation
+
+| Command | Description |
+|---------|-------------|
+| `/sdd-run <id> <description>` | Full auto pipeline: specify through review |
+| `/sdd-init` | Initialize SDD for the project (first time only) |
+| `/sdd-constitution` | Create or update project constitution |
+
+### Utilities
+
+| Command | Description |
+|---------|-------------|
+| `/sdd-split` | Split large SDD documents into modular structure |
+
+## Project Constitution
+
+The constitution (`.specify/memory/constitution.md`) is the foundation of SDD in your project. It defines:
+
+- **Tech stack** -- languages, frameworks, libraries detected from your project
+- **Absolute rules** -- data integrity, query performance, security baselines
+- **Development principles** -- simplicity, code quality, testing standards
+- **Architecture constraints** -- based on your project's architecture pattern
+- **Review criteria** -- scoring dimensions, weights, and pass thresholds
+- **Lessons learned** -- accumulated project-specific knowledge
+
+The constitution is generated by `/sdd-init` and can be updated with `/sdd-constitution`. All subsequent SDD commands read it as context.
+
+## Document Structure
+
+Each feature is organized under `.specify/specs/`:
+
+```
+.specify/
+├── memory/
+│   └── constitution.md          Project constitution
+└── specs/
+    └── 001-feature-name/
+        ├── spec.md              What to build
+        ├── testcases.md         How to verify
+        ├── plan.md              How to implement
+        └── tasks.md             When to implement (task breakdown)
+```
+
+### Document Responsibilities
+
+| Document | Answers | Does NOT contain |
+|----------|---------|-----------------|
+| `spec.md` | What to build and why | Technical implementation details |
+| `testcases.md` | How to verify correctness | Implementation code |
+| `plan.md` | How to implement technically | Specific code |
+| `tasks.md` | When to implement (task order) | Implementation details |
+
+## How It Works with Claude Code
+
+SDD Workflow installs as a set of Claude Code skills. Skills are markdown files that Claude Code reads as instructions when you invoke them with `/command-name`.
+
+### Skill Lifecycle
+
+1. `npx sdd-workflow` copies skill files into `.claude/skills/`
+2. Claude Code discovers skills automatically from that directory
+3. You invoke a skill with `/sdd-<name>` in the Claude Code CLI
+4. Claude Code reads the skill instructions and follows them
+5. Skills reference templates from `.specify/templates/` and the constitution from `.specify/memory/`
+
+### Agent Teams
+
+The package also includes team configurations for multi-agent collaboration. Teams are useful for complex tasks that benefit from multiple perspectives:
+
+- **Feature Development Team** (5 roles) -- full-stack feature implementation
+- **Code Review Team** (3 roles) -- security, performance, quality review
+- **Debug Team** (4 roles) -- complex bug investigation with adversarial reasoning
+- **Research Team** (3 roles) -- technical evaluation and architecture assessment
+- **SDD Planning Team** (4 roles) -- collaborative specification and planning
+
+Enable teams by setting `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in your environment.
+
+## Configuration Guide
+
+### CLAUDE.md Integration
+
+After installation, add a section to your project's `CLAUDE.md` (if it exists) so Claude Code always knows SDD is active:
+
+```markdown
+## SDD Workflow
+
+This project uses SDD (Specification-Driven Development).
+
+### Quick Start
+1. `/sdd-init` -- Initialize SDD for this project (first time only)
+2. `/sdd-run <id> <description>` -- Full auto pipeline (recommended)
+3. Or use individual commands: /sdd-specify, /sdd-testcases, /sdd-plan, /sdd-tasks, /sdd-implement, /sdd-review
+
+### Document Structure
+- `.specify/memory/constitution.md` -- Project constitution
+- `.specify/specs/<id>-<name>/` -- Feature specifications
+```
+
+### .gitignore
+
+Consider adding:
+
+```
+.specify/specs/     # Feature specs (project-specific, regenerable)
+.specify/memory/    # Project memory (local context)
+```
+
+### Customization
+
+- **Templates**: Edit files in `.specify/templates/` to match your team's documentation style
+- **Constitution**: Edit `.specify/memory/constitution.md` to add project-specific rules
+- **Skills**: Modify any skill in `.claude/skills/sdd-*/SKILL.md` to adjust behavior
+
+## Requirements
+
+- [Claude Code](https://claude.ai/claude-code) CLI
+- Node.js >= 14.0.0 (for installation only)
+- Git (recommended)
+
+## License
+
+MIT

package/bin/sdd-init.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+
+/**
+ * SDD Workflow - Installation CLI
+ *
+ * Usage:
+ *   npx sdd-workflow              # Install SDD workflow to current project
+ *   npx sdd-workflow --force      # Overwrite existing files
+ *   npx sdd-workflow --dry-run    # Preview what would be installed
+ *   npx sdd-workflow --update     # Incremental update (only changed files)
+ *   npx sdd-workflow --update --dry-run  # Preview updates
+ */
+
+const path = require('path');
+const fs = require('fs');
+const { install } = require('../src/installer');
+
+const args = process.argv.slice(2);
+const options = {
+  force: args.includes('--force'),
+  dryRun: args.includes('--dry-run'),
+  update: args.includes('--update'),
+  help: args.includes('--help') || args.includes('-h'),
+};
+
+if (options.help) {
+  console.log(`
+SDD Workflow Installer
+
+Usage:
+  npx sdd-workflow              Install SDD workflow to current project
+  npx sdd-workflow --force      Overwrite all existing files
+  npx sdd-workflow --dry-run    Preview what would be installed
+  npx sdd-workflow --update     Incremental update (only changed files)
+  npx sdd-workflow --update --dry-run  Preview what would be updated
+
+What gets installed:
+  .claude/skills/sdd-*/     10 SDD skills for Claude Code
+  .specify/                 Templates, scripts, and specs directory
+  .claude/teams/            Team configuration templates
+
+Update modes:
+  (default)     Skip existing files (safe, non-destructive)
+  --update      Smart update: auto-update source-changed files, skip user-customized files
+  --force       Overwrite everything (resets to default, loses customizations)
+
+After installation:
+  1. Open Claude Code in your project
+  2. Run /sdd-init to generate project constitution
+  3. Start using SDD workflow with /sdd-specify, /sdd-plan, etc.
+`);
+  process.exit(0);
+}
+
+const targetDir = process.cwd();
+install(targetDir, options).catch((err) => {
+  console.error('Installation failed:', err.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "sdd-workflow",
+  "version": "1.1.0",
+  "description": "SDD (Specification-Driven Development) workflow toolkit for Claude Code - install skills, templates and tooling to any project",
+  "bin": {
+    "sdd-init": "./bin/sdd-init.js",
+    "sdd-workflow": "./bin/sdd-init.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "templates/"
+  ],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "sdd",
+    "claude-code",
+    "ai-workflow",
+    "specification-driven",
+    "tdd",
+    "code-review"
+  ],
+  "author": "",
+  "license": "MIT",
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}