create-sdd-project 0.4.2 → 0.6.0

package/README.md

@@ -1,6 +1,7 @@
 # SDD DevFlow
 
 [![npm version](https://img.shields.io/npm/v/create-sdd-project)](https://www.npmjs.com/package/create-sdd-project)
+[![npm downloads](https://img.shields.io/npm/dm/create-sdd-project)](https://www.npmjs.com/package/create-sdd-project)
 [![license](https://img.shields.io/npm/l/create-sdd-project)](LICENSE)
 [![node](https://img.shields.io/node/v/create-sdd-project)](package.json)
 
@@ -16,7 +17,34 @@ A complete development methodology for Claude Code and Gemini that combines spec
 npx create-sdd-project my-app
 ```
 
-The interactive wizard asks about your stack, AI tools, and autonomy level. For defaults (fullstack Express+Next.js):
+The interactive wizard asks about your stack, AI tools, and autonomy level:
+
+```
+🚀 Create SDD DevFlow Project
+
+── Step 1: Project Basics ──────────────────────
+  Project name: my-app
+  Brief project description: Task management API
+
+── Step 3: Project Type & Tech Stack ──────────
+  1) Backend + Frontend (monorepo)  ← default
+  2) Backend only
+  3) Frontend only
+
+── Step 4: AI Tools ────────────────────────────
+  1) Claude Code + Gemini  ← default
+  2) Claude Code only
+  3) Gemini only
+
+── Step 5: Workflow Configuration ──────────────
+  Autonomy level:
+  1) L1 Full Control — Human approves every checkpoint
+  2) L2 Trusted — Human reviews plans + merges only  ← default
+  3) L3 Autopilot — Human only approves merges
+  4) L4 Full Auto — No human checkpoints, CI/CD gates only
+```
+
+For defaults (fullstack Express+Next.js, L2 autonomy):
 
 ```bash
 npx create-sdd-project my-app --yes
@@ -29,18 +57,138 @@ cd your-existing-project
 npx create-sdd-project --init
 ```
 
-Scans your project, detects your stack and architecture, and installs SDD files adapted to your project. Never modifies existing code or overwrites existing files.
+The scanner detects your stack and installs adapted SDD files:
+
+```
+🔍 Scanning project...
+
+    Project:       my-api
+    Language:      TypeScript
+    Backend:       Express + Mongoose + MongoDB
+    Frontend:      Not detected
+    Architecture:  Layered (controllers + handlers + managers)
+    Tests:         Jest (3 test files)
+    Monorepo:      No
+
+Adding SDD DevFlow to my-api...
+
+  ✓ Installing Claude Code config (agents, skills, commands, hooks)
+  ✓ Installing Gemini config (agents, skills, commands)
+  ✓ Creating ai-specs/specs/ (4 standards files)
+  ✓ Creating docs/project_notes/ (product tracker, memory)
+  ✓ Creating AGENTS.md
+  ✓ Setting autonomy level: L2 (Trusted)
+
+Done! Next steps:
+  git add -A && git commit -m "chore: add SDD DevFlow to existing project"
+  # Open in your AI coding tool and run: add feature "your first feature"
+```
+
+Never modifies existing code or overwrites existing files.
+
+### Upgrade
+
+When a new version of SDD DevFlow is released, upgrade your project's template files:
+
+```bash
+cd your-existing-project
+npx create-sdd-project@latest --upgrade
+```
+
+```
+🔄 SDD DevFlow Upgrade
+
+  Current version:  0.4.2
+  New version:      0.5.0
+  AI tools:         Claude Code + Gemini
+  Project type:     backend
+
+  Will replace:
+    ✓ .claude/ (agents, skills, hooks)
+    ✓ .gemini/ (agents, skills, commands)
+    ✓ AGENTS.md, CLAUDE.md / GEMINI.md
+    ✓ .env.example
+
+  Will preserve:
+    ⊘ .claude/settings.local.json (personal settings)
+    ⊘ docs/project_notes/* (project memory)
+    ⊘ docs/specs/* (your specs)
+    ⊘ docs/tickets/* (your tickets)
+    ⊘ .gitignore
+
+  Standards:
+    ✓ ai-specs/specs/base-standards.mdc — unchanged, will update
+    ⚠ ai-specs/specs/backend-standards.mdc — modified by you, preserved
+
+  Proceed? (y/N)
+```
+
+**What gets upgraded:**
+- Agent definitions, skills, hooks, and commands
+- `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.env.example`
+- Standards files (`.mdc`) — only if you haven't customized them
+
+**What is always preserved:**
+- Your project documentation (`docs/project_notes/`, `docs/specs/`, `docs/tickets/`)
+- Custom agents you added to `.claude/agents/` or `.gemini/agents/`
+- Custom commands in `.claude/commands/`
+- Personal settings (`.claude/settings.local.json`)
+- Your `.gitignore`
+- Autonomy level setting
+
+For non-interactive upgrades (CI/scripts): `npx create-sdd-project@latest --upgrade --yes`
+
+### Doctor (Diagnose Installation)
+
+Check that your SDD installation is healthy:
+
+```bash
+cd your-project
+npx create-sdd-project --doctor
+```
+
+```
+🩺 SDD DevFlow Doctor
+
+  ✓ SDD installed (v0.5.0)
+  ✓ Version up to date (0.5.0)
+  ✓ AI tools: Claude Code + Gemini
+  ✓ Top-level configs present (AGENTS.md, CLAUDE.md, GEMINI.md)
+  ✓ Agents: 8/8 present
+  ✓ Project type coherence: OK (fullstack)
+  ✓ Cross-tool consistency: Claude and Gemini in sync
+  ✓ Standards: 4/4 present
+  ✓ Hooks: quick-scan.sh executable, jq installed, settings.json valid
+  ✓ Project memory: 4/4 files present
+
+  Overall: HEALTHY
+```
+
+**What it checks:** SDD files present, version, agents for your project type, no stray frontend agents in backend projects (and vice versa), Claude and Gemini agents in sync, standards files, hooks and dependencies (`jq`), settings.json integrity, project memory files.
+
+Exit code 1 if errors found — useful for CI pipelines.
 
 ### After Setup
 
-Open in your AI coding tool and run:
+Open your project in Claude Code or Gemini and start building:
 
+**Claude Code:**
 ```
-add feature "your first feature"
-start task F001
+/add-feature "user authentication with JWT"
+/start-task F001
+/show-progress
+/next-task
 ```
 
-The workflow skill guides you through each step with checkpoints based on your autonomy level.
+**Gemini:**
+```
+/add-feature "user authentication with JWT"
+/start-task F001
+/show-progress
+/next-task
+```
+
+The workflow skill guides you through each step — from spec writing to implementation to code review — with checkpoints based on your autonomy level.
 
 ---
 
@@ -149,7 +297,7 @@ When running `--init` on an existing project, the scanner automatically detects:
 | **Component libraries** | Radix UI, Headless UI, Material UI, Chakra UI, Ant Design |
 | **State management** | Zustand, Redux, Jotai, TanStack Query, Recoil, Pinia, MobX |
 | **Testing** | Jest, Vitest, Mocha (unit) + Playwright, Cypress (e2e) |
-| **Architecture** | MVC, DDD, feature-based, handler-based, flat |
+| **Architecture** | MVC, DDD, feature-based, handler-based, layered, flat |
 | **Project type** | Monorepo (workspaces, Lerna, Turbo, pnpm) or single-package |
 
 Standards files are adapted to match your actual architecture — not generic defaults.
@@ -203,7 +351,7 @@ Configurable via the wizard or `<!-- CONFIG -->` comments in template files:
 
 - **Backend**: Node.js + Express + Prisma + PostgreSQL
 - **Frontend**: Next.js (App Router) + Tailwind CSS + Radix UI + Zustand
-- **Shared Types**: Zod schemas with `z.infer<>` for TypeScript types
+- **Shared Types**: Validation schemas with TypeScript type inference
 - **Testing**: Jest (unit) + Playwright (e2e)
 - **Methodology**: TDD + DDD + Spec-Driven Development
 
@@ -214,7 +362,7 @@ These 6 principles apply to ALL tasks, ALL agents, ALL complexity levels:
 1. **Spec First** — No implementation without an approved specification
 2. **Small Tasks** — Work in baby steps, one at a time
 3. **Test-Driven Development** — Write tests before implementation
-4. **Type Safety** — Strict TypeScript, no `any`, runtime validation with Zod
+4. **Type Safety** — Strict TypeScript, no `any`, runtime validation at boundaries
 5. **English Only** — All code, comments, docs, commits, and tickets in English
 6. **Reuse Over Recreate** — Always check existing code before proposing new files
 
@@ -224,21 +372,25 @@ These 6 principles apply to ALL tasks, ALL agents, ALL complexity levels:
 - Node.js 18+
 - `jq` (for quick-scan hook): `brew install jq` (macOS) or `apt install jq` (Linux)
 
-## Manual Setup (Alternative)
+## Manual Setup
 
-If you prefer manual configuration over the CLI wizard:
+If you prefer manual configuration over the CLI wizard, copy the template directory and look for `<!-- CONFIG: ... -->` comments in the files to customize:
 
 ```bash
-cp -r template/ /path/to/your-project/
+cp -r node_modules/create-sdd-project/template/ /path/to/your-project/
 ```
 
-Then look for `<!-- CONFIG: ... -->` comments in the files to customize.
-
 ## Roadmap
 
-- **Agent Teams**: Parallel execution of independent tasks (waiting for Claude Code Agent Teams to stabilize)
-- **PM Agent + L5 Autonomous**: AI-driven feature orchestration with human review at milestone boundaries
+- **Monorepo improvements**: Better support for pnpm workspaces and Turbo
+- **SDD Upgrade/Migration**: Version bumps for projects already using SDD
 - **Retrofit Testing**: Automated test generation for existing projects with low coverage
+- **Agent Teams**: Parallel execution of independent tasks
+- **PM Agent + L5 Autonomous**: AI-driven feature orchestration with human review at milestone boundaries
+
+## Contributing
+
+Found a bug or have a suggestion? [Open an issue on GitHub](https://github.com/pbojeda/sdd-devflow/issues).
 
 ## License
 

package/bin/cli.js

@@ -8,14 +8,40 @@ const args = process.argv.slice(2);
 const projectName = args.find((a) => !a.startsWith('-'));
 const useDefaults = args.includes('--yes') || args.includes('-y');
 const isInit = args.includes('--init');
+const isUpgrade = args.includes('--upgrade');
+const isDoctor = args.includes('--doctor');
+const isForce = args.includes('--force');
 
 async function main() {
+  if (isDoctor) {
+    return runDoctorCmd();
+  }
+  if (isUpgrade) {
+    return runUpgrade();
+  }
   if (isInit) {
     return runInit();
   }
   return runCreate();
 }
 
+function runDoctorCmd() {
+  const { runDoctor, printResults } = require('../lib/doctor');
+
+  const cwd = process.cwd();
+
+  // Validate: must be in an existing project
+  if (!fs.existsSync(path.join(cwd, 'package.json'))) {
+    console.error('Error: No package.json found in current directory.');
+    console.error('The --doctor flag must be run from inside an existing project.');
+    process.exit(1);
+  }
+
+  const results = runDoctor(cwd);
+  const exitCode = printResults(results);
+  process.exit(exitCode);
+}
+
 async function runCreate() {
   const { runWizard, buildDefaultConfig } = require('../lib/wizard');
   const { generate } = require('../lib/generator');
@@ -90,6 +116,106 @@ async function runInit() {
   generateInit(config);
 }
 
+async function runUpgrade() {
+  const { scan } = require('../lib/scanner');
+  const { buildInitDefaultConfig } = require('../lib/init-wizard');
+  const readline = require('readline');
+  const {
+    generateUpgrade,
+    readInstalledVersion,
+    getPackageVersion,
+    detectAiTools,
+    detectProjectType,
+    readAutonomyLevel,
+    collectCustomAgents,
+    collectCustomCommands,
+    buildSummary,
+  } = require('../lib/upgrade-generator');
+
+  const cwd = process.cwd();
+
+  // Validate: must be in an existing project
+  if (!fs.existsSync(path.join(cwd, 'package.json'))) {
+    console.error('Error: No package.json found in current directory.');
+    console.error('The --upgrade flag must be run from inside an existing project.');
+    process.exit(1);
+  }
+
+  // Validate: SDD must be installed
+  if (!fs.existsSync(path.join(cwd, 'ai-specs'))) {
+    console.error('Error: ai-specs/ directory not found.');
+    console.error('SDD DevFlow does not appear to be installed. Use --init first.');
+    process.exit(1);
+  }
+
+  // Validate: no project name with --upgrade
+  if (projectName) {
+    console.error('Error: Cannot specify a project name with --upgrade.');
+    console.error('Usage: create-sdd-project --upgrade');
+    process.exit(1);
+  }
+
+  // Read current state
+  const installedVersion = readInstalledVersion(cwd);
+  const packageVersion = getPackageVersion();
+
+  // Same version check
+  if (installedVersion === packageVersion && !isForce) {
+    console.log(`\nSDD DevFlow is already at version ${packageVersion}.`);
+    console.log('Use --force to re-install the same version.\n');
+    return;
+  }
+
+  // Scan project
+  const scanResult = scan(cwd);
+
+  // Detect current config from installed files
+  const aiTools = detectAiTools(cwd);
+  const projectType = detectProjectType(cwd);
+  const autonomy = readAutonomyLevel(cwd);
+  const customAgents = collectCustomAgents(cwd);
+  const customCommands = collectCustomCommands(cwd);
+  const settingsLocal = fs.existsSync(path.join(cwd, '.claude', 'settings.local.json'));
+
+  // Build config (reuse init defaults as base)
+  const config = buildInitDefaultConfig(scanResult);
+  config.aiTools = aiTools;
+  config.projectType = projectType;
+  config.autonomyLevel = autonomy.level;
+  config.autonomyName = autonomy.name;
+  config.installedVersion = installedVersion;
+
+  // Build and show summary
+  const state = {
+    installedVersion,
+    packageVersion,
+    aiTools,
+    projectType,
+    customAgents,
+    customCommands,
+    settingsLocal,
+    standardsStatus: [], // computed during generation
+  };
+
+  if (!useDefaults) {
+    console.log('\n' + buildSummary(state));
+    console.log('');
+
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise((resolve) => {
+      rl.question('  Proceed? (y/N) ', resolve);
+    });
+    rl.close();
+
+    if (answer.toLowerCase() !== 'y' && answer.toLowerCase() !== 'yes') {
+      console.log('\nUpgrade cancelled.\n');
+      return;
+    }
+  }
+
+  generateUpgrade(config);
+}
+
 main().catch((err) => {
   console.error('\nError:', err.message);
   process.exit(1);

package/lib/config.js

@@ -93,6 +93,16 @@ const BRANCHING_STRATEGIES = [
 const FRONTEND_AGENTS = ['frontend-developer.md', 'frontend-planner.md'];
 const BACKEND_AGENTS = ['backend-developer.md', 'backend-planner.md', 'database-architect.md'];
 
+// All template-provided agent files (for upgrade: detect custom agents)
+const TEMPLATE_AGENTS = [
+  ...FRONTEND_AGENTS,
+  ...BACKEND_AGENTS,
+  'spec-creator.md',
+  'code-review-specialist.md',
+  'production-code-validator.md',
+  'qa-engineer.md',
+];
+
 module.exports = {
   DEFAULTS,
   PROJECT_TYPES,
@@ -103,4 +113,5 @@ module.exports = {
   BRANCHING_STRATEGIES,
   FRONTEND_AGENTS,
   BACKEND_AGENTS,
+  TEMPLATE_AGENTS,
 };