sdlc-framework 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,321 @@
+<div align="center">
+
+# SDLC
+
+**Structured Development Lifecycle** — Closed-loop AI-assisted development for Claude Code.
+
+[![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE)
+
+<br>
+
+```bash
+npx sdlc-framework
+```
+
+**Works on Mac, Windows, and Linux.**
+
+<br>
+
+*"Every step forces the next. Every law is enforced. Every loop closes."*
+
+<br>
+
+[Why SDLC](#why-sdlc) · [Getting Started](#getting-started) · [The Loop](#the-loop) · [Commands](#commands) · [Engineering Laws](#engineering-laws)
+
+</div>
+
+---
+
+## Why SDLC
+
+AI-assisted development has a quality problem. Research shows:
+
+- **Context rot** — LLM accuracy drops 60% past certain thresholds (Chroma Research, 2025)
+- **Security vulnerabilities 10x** — AI code produces 10x more security findings (Apiiro, 2025)
+- **Rules get ignored** — Cursor, Windsurf, and other tools routinely ignore their own rules
+- **Specs drift from code** — OpenSpec, SpecKit, and others can't keep specs and code aligned
+- **Multi-agent chaos** — 17x compounding error rate when chaining unreliable agents (MAST, 2025)
+- **No code review** — Most frameworks skip review entirely, shipping unchecked AI output
+- **Manual testing** — Frameworks that include testing require humans to click through UIs
+
+SDLC fixes all of this with five principles:
+
+1. **Closed loop** — SPEC → IMPLEMENT → VERIFY → REVIEW → CLOSE. Every step forces the next. No orphan plans. No skipped reviews.
+
+2. **Engineering Laws** — SOLID, DRY, YAGNI, Clean Code, Security, and Testing are enforced as blocking gates at review. Not suggestions. Laws.
+
+3. **Automated verification** — Playwright MCP replaces manual UAT. Acceptance criteria become automated tests.
+
+4. **Sub-agent driven development** — Implementation tasks run in parallel via dependency-ordered waves. Each agent gets the spec, the laws, and the boundaries.
+
+5. **Clarification over assumption** — The spec phase asks questions with recommendations. No guessing. No "I assumed you wanted..."
+
+---
+
+## Who This Is For
+
+**Developers using Claude Code** who want reliable, high-quality AI-assisted development.
+
+- **Junior developers** — The framework explains every step. Follow the prompts.
+- **Senior developers** — Engineering laws enforce the standards you care about. Fast-forward path for simple tasks.
+- **Teams** — Consistent process across developers. Specs, reviews, and summaries create an audit trail.
+
+---
+
+## Getting Started
+
+```bash
+npx sdlc-framework
+```
+
+Choose global (all projects) or local (current project only). Verify with `/sdlc:help` in Claude Code.
+
+### Quick Start
+
+```bash
+# 1. Initialize the framework
+/sdlc:init
+
+# 2. Define what to build (asks clarification questions)
+/sdlc:spec
+
+# 3. Build it (spawns parallel sub-agents)
+/sdlc:impl
+
+# 4. The framework forces verify → review → close automatically
+# Just follow the NEXT ACTION REQUIRED prompts
+```
+
+### Just Tell It What To Do
+
+```bash
+/sdlc:fast add a loading spinner to the submit button
+/sdlc:fast the login form crashes on empty password
+/sdlc:fast refactor auth to use dependency injection
+```
+
+`/sdlc:fast` is the **default entry point**. Describe your work in plain language. The framework classifies it (feature, bug, refactor, etc.), estimates complexity, and either executes inline or routes to the right command. Simple work runs the full loop in one shot. Complex work routes to `/sdlc:spec` with pre-filled context.
+
+### For Bugs
+
+```bash
+/sdlc:debug login form submits twice on slow connections
+```
+
+Follows: reproduce → isolate → root-cause → fix → verify.
+
+---
+
+## The Loop
+
+```
+┌──────────────────────────────────────────────────────────┐
+│  SPEC ──→ IMPLEMENT ──→ VERIFY ──→ REVIEW ──→ CLOSE     │
+│   │                                              │       │
+│   └──────────────── next cycle ←─────────────────┘       │
+│                                                          │
+│  Define    Build (parallel   Auto-test    Engineering    │
+│  work +    sub-agents per    (Playwright  laws check     │
+│  ask Qs    dependency wave)  MCP + tests) (SOLID/DRY/..) │
+└──────────────────────────────────────────────────────────┘
+```
+
+### SPEC — Define the work
+
+- Asks clarification questions (no guessing)
+- Presents options with trade-offs and recommendations
+- Defines BDD acceptance criteria (Given/When/Then)
+- Decomposes tasks with dependency graph for parallel execution
+- **Spec integrity review** — checks completeness, consistency, feasibility
+- **User approval gate** — spec must be explicitly approved before implementation starts
+
+### IMPLEMENT — Build it
+
+- Analyzes task dependencies (DAG)
+- Spawns parallel sub-agents per wave
+- Each agent gets: task spec, engineering laws, boundaries
+- Tracks progress via todo list
+
+### VERIFY — Test it
+
+- Translates acceptance criteria to automated tests
+- UI: Playwright MCP (navigate, click, assert)
+- API: curl requests with assertions
+- Logic: test suite execution
+- Reports pass/fail per AC with evidence
+
+### REVIEW — Check it
+
+- Reviews all modified files against Engineering Laws
+- Checks: SOLID, DRY, YAGNI, Clean Code, Security, Testing, Naming, Error Handling
+- Severity levels: BLOCKER (must fix), WARNING (should fix), INFO (consider)
+- Blockers prevent loop closure — routes to `/sdlc:fix` for systematic fixing
+- `/sdlc:fix` analyzes fix dependencies, applies fixes (parallel where possible), auto re-reviews
+
+### CLOSE — Ship it
+
+- Reconciles spec vs actual implementation
+- Records deviations, decisions, lessons
+- Creates SUMMARY.md for audit trail
+- Advances state to next cycle
+
+---
+
+## Commands
+
+15 commands, grouped by purpose. Run `/sdlc:help` for the full reference.
+
+### Core Loop
+
+| Command | What it does | Forces next |
+|---------|-------------|-------------|
+| `/sdlc:spec` | Define work with acceptance criteria | → `/sdlc:impl` |
+| `/sdlc:impl` | Build via parallel sub-agents | → `/sdlc:verify` |
+| `/sdlc:verify` | Automated testing (Playwright MCP) | → `/sdlc:review` |
+| `/sdlc:review` | Engineering laws compliance check | → `/sdlc:close` |
+| `/sdlc:close` | Reconcile and close the loop | → `/sdlc:spec` |
+
+### Quick Entry
+
+| Command | What it does |
+|---------|-------------|
+| `/sdlc:fast <desc>` | **Default entry point.** Describe work → framework classifies, routes, or executes inline |
+
+### Fix & Debug
+
+| Command | What it does |
+|---------|-------------|
+| `/sdlc:fix` | Fix review blockers systematically, auto re-review |
+| `/sdlc:debug <issue>` | Structured debugging: reproduce → isolate → fix → verify |
+| `/sdlc:hotfix <issue>` | Emergency fix with minimal ceremony |
+
+### Session
+
+| Command | What it does |
+|---------|-------------|
+| `/sdlc:pause` | Save context for break |
+| `/sdlc:resume` | Restore context, ONE next action |
+| `/sdlc:status` | Show position + forced next action |
+
+### Setup
+
+| Command | What it does |
+|---------|-------------|
+| `/sdlc:init` | Initialize framework in project |
+| `/sdlc:milestone` | Create or complete milestones |
+| `/sdlc:research` | Deploy research sub-agents |
+| `/sdlc:help` | Show command reference |
+
+---
+
+## Engineering Laws
+
+Laws are enforced at `/sdlc:review`. Violations at `error` severity block `/sdlc:close`.
+
+| Law | Default | What it enforces |
+|-----|---------|-----------------|
+| **SOLID** | error | Single Responsibility, Open/Closed, Liskov, Interface Segregation, Dependency Inversion |
+| **DRY** | error | Search before create. No duplicate logic (3+ similar lines) |
+| **YAGNI** | error | Only build what's in the spec. No speculative features |
+| **CLEAN_CODE** | error | Max 40 lines/function, max 3 params, max 3 nesting levels |
+| **SECURITY** | error | No hardcoded secrets, input validation, parameterized queries |
+| **TESTING** | error | Every behavior change needs tests with meaningful assertions |
+| **NAMING** | warning | Descriptive names, no abbreviations, self-documenting code |
+| **ERROR_HANDLING** | error | No empty catch blocks, domain-specific exceptions, no swallowed errors |
+
+Severity is configurable per project in `.sdlc/LAWS.md`:
+- `error` — Blocks loop closure. Must fix.
+- `warning` — Reported in review. Should fix.
+- `info` — Noted only. Consider fixing.
+
+---
+
+## Project Structure
+
+```
+.sdlc/
+├── PROJECT.md          # Project context and requirements
+├── STATE.md            # Loop position + forced next action
+├── ROADMAP.md          # Milestones and phases
+├── LAWS.md             # Engineering laws (configurable severity)
+├── phases/
+│   └── 01-phase-name/
+│       ├── 01-01-SPEC.md
+│       ├── 01-01-REVIEW.md
+│       └── 01-01-SUMMARY.md
+└── research/           # Sub-agent research output
+```
+
+---
+
+## How It Differs
+
+### vs. PAUL
+
+| Aspect | PAUL | SDLC |
+|--------|------|------|
+| Commands | 26 (cognitive overload) | 15 (focused) |
+| Testing | Manual UAT | Automated (Playwright MCP) |
+| Code review | None | Engineering Laws enforcement |
+| Implementation | In-session | Sub-agent parallel waves |
+| Next action | Suggested | **Forced** |
+| Engineering standards | None | SOLID/DRY/YAGNI as blocking gates |
+| Fast path | None | `/sdlc:fast` for small tasks |
+| Debugging | None | `/sdlc:debug` structured flow |
+
+### vs. GSD / Speckit / OpenSpec
+
+| Problem | Others | SDLC |
+|---------|--------|------|
+| Context rot | No mitigation | Session budget tracking, forced pause |
+| Rules ignored | Prompt-only | Post-generation validation at review |
+| Spec drift | Manual reconciliation | Automated close-loop reconciliation |
+| Security | Hope-based | Scanning as blocking gate |
+| Multi-agent errors | 17x compounding | Dependency-ordered waves, bounded scope |
+| Brownfield support | Greenfield focus | Incremental adoption, existing codebase first |
+
+---
+
+## Installation Options
+
+```bash
+npx sdlc-framework              # Interactive (choose global/local)
+npx sdlc-framework --global     # Install to ~/.claude/
+npx sdlc-framework --local      # Install to ./.claude/
+npx sdlc-framework --global --config-dir ~/.claude-custom
+```
+
+### Staying Updated
+
+```bash
+npx sdlc-framework@latest
+```
+
+---
+
+## Troubleshooting
+
+**Commands not found?**
+- Restart Claude Code to reload slash commands
+- Verify files exist in `~/.claude/commands/sdlc/`
+
+**Loop position seems wrong?**
+- Run `/sdlc:status` for current state
+- Check `.sdlc/STATE.md` directly
+
+**Resuming after a break?**
+- Run `/sdlc:resume` — it reads state and handoffs automatically
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.
+
+---
+
+<div align="center">
+
+**AI writes code. SDLC makes it reliable.**
+
+</div>

package/bin/install.js

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+
+const fs = require('fs')
+const path = require('path')
+const os = require('os')
+const readline = require('readline')
+
+const cyan = '\x1b[36m'
+const green = '\x1b[32m'
+const yellow = '\x1b[33m'
+const dim = '\x1b[2m'
+const reset = '\x1b[0m'
+
+const pkg = require('../package.json')
+
+const banner = `
+${cyan}  ███████╗██████╗ ██╗      ██████╗
+  ██╔════╝██╔══██╗██║     ██╔════╝
+  ███████╗██║  ██║██║     ██║
+  ╚════██║██║  ██║██║     ██║
+  ███████║██████╔╝███████╗╚██████╗
+  ╚══════╝╚═════╝ ╚══════╝ ╚═════╝${reset}
+
+  SDLC Framework ${dim}v${pkg.version}${reset}
+  Structured Development Lifecycle for Claude Code
+`
+
+const args = process.argv.slice(2)
+const hasGlobal = args.includes('--global') || args.includes('-g')
+const hasLocal = args.includes('--local') || args.includes('-l')
+
+function parseConfigDirArg() {
+  const idx = args.findIndex(a => a === '--config-dir' || a === '-c')
+  if (idx !== -1) {
+    const next = args[idx + 1]
+    if (!next || next.startsWith('-')) {
+      console.error(`  ${yellow}--config-dir requires a path argument${reset}`)
+      process.exit(1)
+    }
+    return next
+  }
+  const eqArg = args.find(a => a.startsWith('--config-dir=') || a.startsWith('-c='))
+  if (eqArg) return eqArg.split('=')[1]
+  return null
+}
+
+const explicitConfigDir = parseConfigDirArg()
+const hasHelp = args.includes('--help') || args.includes('-h')
+
+console.log(banner)
+
+if (hasHelp) {
+  console.log(`  ${yellow}Usage:${reset} npx sdlc-framework [options]
+
+  ${yellow}Options:${reset}
+    ${cyan}-g, --global${reset}              Install globally (to Claude config directory)
+    ${cyan}-l, --local${reset}               Install locally (to ./.claude in current directory)
+    ${cyan}-c, --config-dir <path>${reset}   Specify custom Claude config directory
+    ${cyan}-h, --help${reset}                Show this help message
+
+  ${yellow}Examples:${reset}
+    ${dim}# Install to default ~/.claude directory${reset}
+    npx sdlc-framework --global
+
+    ${dim}# Install to custom config directory${reset}
+    npx sdlc-framework --global --config-dir ~/.claude-custom
+
+    ${dim}# Install to current project only${reset}
+    npx sdlc-framework --local
+
+  ${yellow}What gets installed:${reset}
+    commands/sdlc/        - Slash commands (/sdlc:init, /sdlc:spec, etc.)
+    sdlc-framework/       - Templates, workflows, references, rules
+`)
+  process.exit(0)
+}
+
+function expandTilde(filePath) {
+  if (filePath && filePath.startsWith('~/')) {
+    return path.join(os.homedir(), filePath.slice(2))
+  }
+  return filePath
+}
+
+function copyWithPathReplacement(srcDir, destDir, pathPrefix) {
+  fs.mkdirSync(destDir, { recursive: true })
+  const entries = fs.readdirSync(srcDir, { withFileTypes: true })
+
+  for (const entry of entries) {
+    const srcPath = path.join(srcDir, entry.name)
+    const destPath = path.join(destDir, entry.name)
+
+    if (entry.isDirectory()) {
+      copyWithPathReplacement(srcPath, destPath, pathPrefix)
+    } else if (entry.name.endsWith('.md')) {
+      let content = fs.readFileSync(srcPath, 'utf8')
+      content = content.replace(/~\/\.claude\//g, pathPrefix)
+      fs.writeFileSync(destPath, content)
+    } else {
+      fs.copyFileSync(srcPath, destPath)
+    }
+  }
+}
+
+function install(isGlobal) {
+  const src = path.join(__dirname, '..')
+  const configDir = expandTilde(explicitConfigDir) || expandTilde(process.env.CLAUDE_CONFIG_DIR)
+  const defaultGlobalDir = configDir || path.join(os.homedir(), '.claude')
+  const claudeDir = isGlobal ? defaultGlobalDir : path.join(process.cwd(), '.claude')
+
+  const locationLabel = isGlobal
+    ? claudeDir.replace(os.homedir(), '~')
+    : claudeDir.replace(process.cwd(), '.')
+
+  const pathPrefix = isGlobal
+    ? (configDir ? `${claudeDir}/` : '~/.claude/')
+    : './.claude/'
+
+  console.log(`  Installing to ${cyan}${locationLabel}${reset}\n`)
+
+  const commandsDir = path.join(claudeDir, 'commands')
+  fs.mkdirSync(commandsDir, { recursive: true })
+
+  const commandsSrc = path.join(src, 'src', 'commands')
+  const commandsDest = path.join(commandsDir, 'sdlc')
+  copyWithPathReplacement(commandsSrc, commandsDest, pathPrefix)
+  console.log(`  ${green}✓${reset} Installed commands/sdlc`)
+
+  const skillDest = path.join(claudeDir, 'sdlc-framework')
+  fs.mkdirSync(skillDest, { recursive: true })
+
+  const srcDirs = ['templates', 'workflows', 'references', 'rules']
+  for (const dir of srcDirs) {
+    const dirSrc = path.join(src, 'src', dir)
+    const dirDest = path.join(skillDest, dir)
+    if (fs.existsSync(dirSrc)) {
+      copyWithPathReplacement(dirSrc, dirDest, pathPrefix)
+    }
+  }
+  console.log(`  ${green}✓${reset} Installed sdlc-framework`)
+
+  console.log(`
+  ${green}Done!${reset} Launch Claude Code and run ${cyan}/sdlc:help${reset}.
+
+  ${yellow}Quick start:${reset}
+    ${dim}1.${reset} /sdlc:init          ${dim}— Initialize project${reset}
+    ${dim}2.${reset} /sdlc:spec          ${dim}— Define what to build${reset}
+    ${dim}3.${reset} /sdlc:impl          ${dim}— Build it (sub-agent parallel)${reset}
+    ${dim}4.${reset} /sdlc:verify        ${dim}— Playwright auto-test${reset}
+    ${dim}5.${reset} /sdlc:review        ${dim}— Engineering laws check${reset}
+    ${dim}6.${reset} /sdlc:close         ${dim}— Close the loop${reset}
+
+  ${dim}Or for small tasks:${reset} /sdlc:fast "add logout button"
+`)
+}
+
+function promptLocation() {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  })
+
+  const configDir = expandTilde(explicitConfigDir) || expandTilde(process.env.CLAUDE_CONFIG_DIR)
+  const globalPath = configDir || path.join(os.homedir(), '.claude')
+  const globalLabel = globalPath.replace(os.homedir(), '~')
+
+  console.log(`  ${yellow}Where would you like to install?${reset}
+
+  ${cyan}1${reset}) Global ${dim}(${globalLabel})${reset} — available in all projects
+  ${cyan}2${reset}) Local  ${dim}(./.claude)${reset} — this project only
+`)
+
+  rl.question(`  Choice ${dim}[1]${reset}: `, (answer) => {
+    rl.close()
+    const choice = answer.trim() || '1'
+    const isGlobal = choice !== '2'
+    install(isGlobal)
+  })
+}
+
+if (hasGlobal && hasLocal) {
+  console.error(`  ${yellow}Cannot specify both --global and --local${reset}`)
+  process.exit(1)
+} else if (explicitConfigDir && hasLocal) {
+  console.error(`  ${yellow}Cannot use --config-dir with --local${reset}`)
+  process.exit(1)
+} else if (hasGlobal) {
+  install(true)
+} else if (hasLocal) {
+  install(false)
+} else {
+  promptLocation()
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "sdlc-framework",
+  "version": "1.0.0",
+  "description": "Structured Development Lifecycle - A closed-loop AI-assisted development framework for Claude Code",
+  "bin": {
+    "sdlc-framework": "bin/install.js"
+  },
+  "files": [
+    "bin",
+    "src/commands",
+    "src/templates",
+    "src/references",
+    "src/workflows",
+    "src/rules"
+  ],
+  "keywords": [
+    "claude",
+    "claude-code",
+    "sdlc",
+    "ai",
+    "structured-development",
+    "engineering-laws",
+    "code-review",
+    "playwright",
+    "sub-agent",
+    "solid",
+    "dry",
+    "yagni"
+  ],
+  "author": "nadyshalaby",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "engines": {
+    "node": ">=16.7.0"
+  }
+}