ai-sdlc-kit 0.1.0__py3-none-any.whl

ai_sdlc/__init__.py

@@ -0,0 +1 @@
+"""AI-SDLC — spec-driven SDLC skills for AI coding agents."""

ai_sdlc/cli.py

@@ -0,0 +1,144 @@
+"""AI-SDLC CLI — installs bundled skills into your project or home directory."""
+
+from __future__ import annotations
+
+import argparse
+import importlib.metadata as metadata
+import importlib.resources as resources
+import shutil
+import sys
+from pathlib import Path
+
+AGENT_DIRS = {
+    "claude": ".claude/skills",
+    "cursor": ".cursor/skills",
+    "windsurf": ".windsurf/skills",
+    "gemini": ".gemini/skills",
+}
+
+DIST_NAME = "ai-sdlc-kit"
+
+
+def _skills_root():
+    bundled = resources.files("ai_sdlc") / "skills"
+    if bundled.is_dir():
+        return bundled
+    fallback = Path(__file__).resolve().parents[2] / "skills"
+    if fallback.is_dir():
+        return fallback
+    raise FileNotFoundError(
+        "could not locate the bundled 'skills' directory — "
+        "the ai-sdlc-kit package may be installed incorrectly"
+    )
+
+
+def _copy_tree(src, dst: Path) -> None:
+    dst.mkdir(parents=True, exist_ok=True)
+    for entry in src.iterdir():
+        target = dst / entry.name
+        if entry.is_dir():
+            _copy_tree(entry, target)
+        else:
+            target.write_bytes(entry.read_bytes())
+
+
+def _install_for_agent(agent: str, target: Path, force: bool) -> None:
+    agent_dir = target / AGENT_DIRS[agent]
+    installed = 0
+    skipped = 0
+    for skill in sorted(_skills_root().iterdir(), key=lambda p: p.name):
+        if not skill.is_dir():
+            continue
+        dest = agent_dir / skill.name
+        if dest.exists() and not force:
+            print(f"skip {skill.name} (exists)")
+            skipped += 1
+            continue
+        if dest.exists():
+            shutil.rmtree(dest)
+        _copy_tree(skill, dest)
+        print(f"installed {skill.name}")
+        installed += 1
+    print(f"installed {installed}, skipped {skipped} → {agent_dir}")
+
+
+def _cmd_install(args: argparse.Namespace) -> int:
+    target = Path.home() if args.global_ else Path(args.target)
+    agents = list(AGENT_DIRS) if args.agent == "all" else [args.agent]
+    for agent in agents:
+        _install_for_agent(agent, target, args.force)
+    return 0
+
+
+def _cmd_list(args: argparse.Namespace) -> int:
+    for skill in sorted(_skills_root().iterdir(), key=lambda p: p.name):
+        if skill.is_dir():
+            print(skill.name)
+    return 0
+
+
+def _version() -> str:
+    try:
+        return metadata.version(DIST_NAME)
+    except metadata.PackageNotFoundError:
+        return "0.0.0-dev"
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="ai-sdlc", description="Install AI-SDLC skills for your coding agent."
+    )
+    parser.add_argument("--version", action="store_true", help="print the version and exit")
+
+    subparsers = parser.add_subparsers(dest="command")
+
+    install_parser = subparsers.add_parser(
+        "install", help="install skills into an agent's skills directory"
+    )
+    install_parser.add_argument(
+        "--agent",
+        choices=[*AGENT_DIRS, "all"],
+        default="claude",
+        help="which agent to install skills for (default: claude)",
+    )
+    install_parser.add_argument(
+        "--target", default=".", help="target project directory (default: current directory)"
+    )
+    install_parser.add_argument(
+        "--global",
+        dest="global_",
+        action="store_true",
+        help="install into your home directory instead of --target",
+    )
+    install_parser.add_argument(
+        "--force", action="store_true", help="overwrite existing skill folders"
+    )
+    install_parser.set_defaults(func=_cmd_install)
+
+    list_parser = subparsers.add_parser("list", help="list bundled skills")
+    list_parser.set_defaults(func=_cmd_list)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.version:
+        print(_version())
+        return 0
+
+    if not getattr(args, "command", None):
+        parser.print_help()
+        return 1
+
+    try:
+        return args.func(args)
+    except FileNotFoundError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ai_sdlc/skills/architecture-diagram/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: architecture-diagram
+description: Create professional, dark-themed architecture diagrams as standalone HTML files with SVG graphics. Use when the user asks for system architecture diagrams, infrastructure diagrams, cloud architecture visualizations, security diagrams, network topology diagrams, or any technical diagram showing system components and their relationships.
+license: MIT
+metadata:
+  version: "1.0"
+  author: Cocoon AI (hello@cocoon-ai.com)
+---
+
+# Architecture Diagram Skill
+
+Create professional technical architecture diagrams as self-contained HTML files with inline SVG graphics and CSS styling.
+
+## Design System
+
+### Color Palette
+
+Use these semantic colors for component types:
+
+| Component Type | Fill (rgba) | Stroke |
+|---------------|-------------|--------|
+| Frontend | `rgba(8, 51, 68, 0.4)` | `#22d3ee` (cyan-400) |
+| Backend | `rgba(6, 78, 59, 0.4)` | `#34d399` (emerald-400) |
+| Database | `rgba(76, 29, 149, 0.4)` | `#a78bfa` (violet-400) |
+| AWS/Cloud | `rgba(120, 53, 15, 0.3)` | `#fbbf24` (amber-400) |
+| Security | `rgba(136, 19, 55, 0.4)` | `#fb7185` (rose-400) |
+| Message Bus | `rgba(251, 146, 60, 0.3)` | `#fb923c` (orange-400) |
+| External/Generic | `rgba(30, 41, 59, 0.5)` | `#94a3b8` (slate-400) |
+
+### Typography
+
+Use JetBrains Mono for all text (monospace, technical aesthetic):
+```html
+<link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600;700&display=swap" rel="stylesheet">
+```
+
+Font sizes: 12px for component names, 9px for sublabels, 8px for annotations, 7px for tiny labels.
+
+### Visual Elements
+
+**Background:** `#020617` (slate-950) with subtle grid pattern:
+```svg
+<pattern id="grid" width="40" height="40" patternUnits="userSpaceOnUse">
+  <path d="M 40 0 L 0 0 0 40" fill="none" stroke="#1e293b" stroke-width="0.5"/>
+</pattern>
+```
+
+**Component boxes:** Rounded rectangles (`rx="6"`) with 1.5px stroke, semi-transparent fills.
+
+**Security groups:** Dashed stroke (`stroke-dasharray="4,4"`), transparent fill, rose color.
+
+**Region boundaries:** Larger dashed stroke (`stroke-dasharray="8,4"`), amber color, `rx="12"`.
+
+**Arrows:** Use SVG marker for arrowheads:
+```svg
+<marker id="arrowhead" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
+  <polygon points="0 0, 10 3.5, 0 7" fill="#64748b" />
+</marker>
+```
+
+**Arrow z-order:** Draw connection arrows early in the SVG (after the background grid) so they render behind component boxes. SVG elements are painted in document order, so arrows drawn first will appear behind shapes drawn later.
+
+**Masking arrows behind transparent fills:** Since component boxes use semi-transparent fills (`rgba(..., 0.4)`), arrows behind them will show through. To fully mask arrows, draw an opaque background rect (e.g., `fill="#0f172a"`) at the same position before drawing the semi-transparent styled rect on top:
+```svg
+<!-- Opaque background to mask arrows -->
+<rect x="X" y="Y" width="W" height="H" rx="6" fill="#0f172a"/>
+<!-- Styled component on top -->
+<rect x="X" y="Y" width="W" height="H" rx="6" fill="rgba(76, 29, 149, 0.4)" stroke="#a78bfa" stroke-width="1.5"/>
+```
+
+**Auth/security flows:** Dashed lines in rose color (`#fb7185`).
+
+**Message buses / Event buses:** Small connector elements between services. Use orange color (`#fb923c` stroke, `rgba(251, 146, 60, 0.3)` fill):
+```svg
+<rect x="X" y="Y" width="120" height="20" rx="4" fill="rgba(251, 146, 60, 0.3)" stroke="#fb923c" stroke-width="1"/>
+<text x="CENTER_X" y="Y+14" fill="#fb923c" font-size="7" text-anchor="middle">Kafka / RabbitMQ</text>
+```
+
+### Spacing Rules
+
+**CRITICAL:** When stacking components vertically, ensure proper spacing to avoid overlaps:
+
+- **Standard component height:** 60px for services, 80-120px for larger components
+- **Minimum vertical gap between components:** 40px
+- **Inline connectors (message buses):** Place IN the gap between components, not overlapping
+
+**Example vertical layout:**
+```
+Component A: y=70,  height=60  → ends at y=130
+Gap:         y=130 to y=170   → 40px gap, place bus at y=140 (20px tall)
+Component B: y=170, height=60  → ends at y=230
+```
+
+**Wrong:** Placing a message bus at y=160 when Component B starts at y=170 (causes overlap)
+**Right:** Placing a message bus at y=140, centered in the 40px gap (y=130 to y=170)
+
+### Legend Placement
+
+**CRITICAL:** Place legends OUTSIDE all boundary boxes (region boundaries, cluster boundaries, security groups).
+
+- Calculate where all boundaries end (y position + height)
+- Place legend at least 20px below the lowest boundary
+- Expand SVG viewBox height if needed to accommodate
+
+**Example:**
+```
+Kubernetes Cluster: y=30, height=460 → ends at y=490
+Legend should start at: y=510 or below
+SVG viewBox height: at least 560 to fit legend
+```
+
+**Wrong:** Legend at y=470 inside a cluster boundary that ends at y=490
+**Right:** Legend at y=510, below the cluster boundary, with viewBox height extended
+
+### Layout Structure
+
+1. **Header** - Title with pulsing dot indicator, subtitle
+2. **Main SVG diagram** - Contained in rounded border card
+3. **Summary cards** - Grid of 3 cards below diagram with key details
+4. **Footer** - Minimal metadata line
+
+### Component Box Pattern
+
+```svg
+<rect x="X" y="Y" width="W" height="H" rx="6" fill="FILL_COLOR" stroke="STROKE_COLOR" stroke-width="1.5"/>
+<text x="CENTER_X" y="Y+20" fill="white" font-size="11" font-weight="600" text-anchor="middle">LABEL</text>
+<text x="CENTER_X" y="Y+36" fill="#94a3b8" font-size="9" text-anchor="middle">sublabel</text>
+```
+
+### Info Card Pattern
+
+```html
+<div class="card">
+  <div class="card-header">
+    <div class="card-dot COLOR"></div>
+    <h3>Title</h3>
+  </div>
+  <ul>
+    <li>• Item one</li>
+    <li>• Item two</li>
+  </ul>
+</div>
+```
+
+## Template
+
+Copy and customize the template at `assets/template.html`. Key customization points:
+
+1. Update the `<title>` and header text
+2. Modify SVG viewBox dimensions if needed (default: `1000 x 680`)
+3. Add/remove/reposition component boxes
+4. Draw connection arrows between components
+5. Update the three summary cards
+6. Update footer metadata
+
+## Output
+
+Always produce a single self-contained `.html` file with:
+- Embedded CSS (no external stylesheets except Google Fonts)
+- Inline SVG (no external images)
+- No JavaScript required (pure CSS animations)
+
+The file should render correctly when opened directly in any modern browser.

ai_sdlc/skills/architecture-diagram/assets/template.html

@@ -0,0 +1,319 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>[PROJECT NAME] Architecture Diagram</title>
+  <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600;700&display=swap" rel="stylesheet">
+  <style>
+    * {
+      margin: 0;
+      padding: 0;
+      box-sizing: border-box;
+    }
+    
+    body {
+      font-family: 'JetBrains Mono', monospace;
+      background: #020617;
+      min-height: 100vh;
+      padding: 2rem;
+      color: white;
+    }
+    
+    .container {
+      max-width: 1200px;
+      margin: 0 auto;
+    }
+    
+    .header {
+      margin-bottom: 2rem;
+    }
+    
+    .header-row {
+      display: flex;
+      align-items: center;
+      gap: 1rem;
+      margin-bottom: 0.5rem;
+    }
+    
+    .pulse-dot {
+      width: 12px;
+      height: 12px;
+      background: #22d3ee;
+      border-radius: 50%;
+      animation: pulse 2s infinite;
+    }
+    
+    @keyframes pulse {
+      0%, 100% { opacity: 1; }
+      50% { opacity: 0.5; }
+    }
+    
+    h1 {
+      font-size: 1.5rem;
+      font-weight: 700;
+      letter-spacing: -0.025em;
+    }
+    
+    .subtitle {
+      color: #94a3b8;
+      font-size: 0.875rem;
+      margin-left: 1.75rem;
+    }
+    
+    .diagram-container {
+      background: rgba(15, 23, 42, 0.5);
+      border-radius: 1rem;
+      border: 1px solid #1e293b;
+      padding: 1.5rem;
+      overflow-x: auto;
+    }
+    
+    svg {
+      width: 100%;
+      min-width: 900px;
+      display: block;
+    }
+    
+    .cards {
+      display: grid;
+      grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+      gap: 1rem;
+      margin-top: 2rem;
+    }
+    
+    .card {
+      background: rgba(15, 23, 42, 0.5);
+      border-radius: 0.75rem;
+      border: 1px solid #1e293b;
+      padding: 1.25rem;
+    }
+    
+    .card-header {
+      display: flex;
+      align-items: center;
+      gap: 0.5rem;
+      margin-bottom: 0.75rem;
+    }
+    
+    .card-dot {
+      width: 8px;
+      height: 8px;
+      border-radius: 50%;
+    }
+    
+    .card-dot.cyan { background: #22d3ee; }
+    .card-dot.emerald { background: #34d399; }
+    .card-dot.violet { background: #a78bfa; }
+    .card-dot.amber { background: #fbbf24; }
+    .card-dot.rose { background: #fb7185; }
+    
+    .card h3 {
+      font-size: 0.875rem;
+      font-weight: 600;
+    }
+    
+    .card ul {
+      list-style: none;
+      color: #94a3b8;
+      font-size: 0.75rem;
+    }
+    
+    .card li {
+      margin-bottom: 0.375rem;
+    }
+    
+    .footer {
+      text-align: center;
+      margin-top: 1.5rem;
+      color: #475569;
+      font-size: 0.75rem;
+    }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <!-- Header -->
+    <div class="header">
+      <div class="header-row">
+        <div class="pulse-dot"></div>
+        <h1>[PROJECT NAME] Architecture</h1>
+      </div>
+      <p class="subtitle">[Subtitle description]</p>
+    </div>
+
+    <!-- Main Diagram -->
+    <div class="diagram-container">
+      <svg viewBox="0 0 1000 680">
+        <!-- Definitions -->
+        <defs>
+          <marker id="arrowhead" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
+            <polygon points="0 0, 10 3.5, 0 7" fill="#64748b" />
+          </marker>
+          <pattern id="grid" width="40" height="40" patternUnits="userSpaceOnUse">
+            <path d="M 40 0 L 0 0 0 40" fill="none" stroke="#1e293b" stroke-width="0.5"/>
+          </pattern>
+        </defs>
+
+        <!-- Background Grid -->
+        <rect width="100%" height="100%" fill="url(#grid)" />
+
+        <!-- =================================================================
+             COMPONENT EXAMPLES - Copy and customize these patterns
+             ================================================================= -->
+
+        <!-- External/Generic Component -->
+        <rect x="30" y="280" width="100" height="50" rx="6" fill="rgba(30, 41, 59, 0.5)" stroke="#94a3b8" stroke-width="1.5"/>
+        <text x="80" y="300" fill="white" font-size="11" font-weight="600" text-anchor="middle">Users</text>
+        <text x="80" y="316" fill="#94a3b8" font-size="9" text-anchor="middle">Browser/Mobile</text>
+
+        <!-- Security Component -->
+        <rect x="30" y="80" width="100" height="60" rx="6" fill="rgba(136, 19, 55, 0.4)" stroke="#fb7185" stroke-width="1.5"/>
+        <text x="80" y="105" fill="white" font-size="11" font-weight="600" text-anchor="middle">Auth Provider</text>
+        <text x="80" y="121" fill="#94a3b8" font-size="9" text-anchor="middle">OAuth 2.0</text>
+
+        <!-- Region/Cloud Boundary -->
+        <rect x="160" y="40" width="820" height="620" rx="12" fill="rgba(251, 191, 36, 0.05)" stroke="#fbbf24" stroke-width="1" stroke-dasharray="8,4"/>
+        <text x="172" y="58" fill="#fbbf24" font-size="10" font-weight="600">AWS Region: us-west-2</text>
+
+        <!-- AWS/Cloud Service -->
+        <rect x="200" y="280" width="110" height="50" rx="6" fill="rgba(120, 53, 15, 0.3)" stroke="#fbbf24" stroke-width="1.5"/>
+        <text x="255" y="300" fill="white" font-size="11" font-weight="600" text-anchor="middle">CloudFront</text>
+        <text x="255" y="316" fill="#94a3b8" font-size="9" text-anchor="middle">CDN</text>
+
+        <!-- Multi-line AWS Component (S3 Buckets example) -->
+        <rect x="200" y="380" width="110" height="100" rx="6" fill="rgba(120, 53, 15, 0.3)" stroke="#fbbf24" stroke-width="1.5"/>
+        <text x="255" y="400" fill="white" font-size="11" font-weight="600" text-anchor="middle">S3 Buckets</text>
+        <text x="255" y="420" fill="#94a3b8" font-size="8" text-anchor="middle">• bucket-one</text>
+        <text x="255" y="434" fill="#94a3b8" font-size="8" text-anchor="middle">• bucket-two</text>
+        <text x="255" y="448" fill="#94a3b8" font-size="8" text-anchor="middle">• bucket-three</text>
+        <text x="255" y="466" fill="#fbbf24" font-size="7" text-anchor="middle">OAI Protected</text>
+
+        <!-- Security Group (dashed boundary) -->
+        <rect x="350" y="265" width="120" height="80" rx="8" fill="transparent" stroke="#fb7185" stroke-width="1" stroke-dasharray="4,4"/>
+        <text x="358" y="279" fill="#fb7185" font-size="8">sg-name :port</text>
+        
+        <!-- Component inside security group -->
+        <rect x="360" y="280" width="100" height="50" rx="6" fill="rgba(120, 53, 15, 0.3)" stroke="#fbbf24" stroke-width="1.5"/>
+        <text x="410" y="300" fill="white" font-size="11" font-weight="600" text-anchor="middle">Load Balancer</text>
+        <text x="410" y="316" fill="#94a3b8" font-size="9" text-anchor="middle">HTTPS :443</text>
+
+        <!-- Backend Component -->
+        <rect x="510" y="280" width="110" height="50" rx="6" fill="rgba(6, 78, 59, 0.4)" stroke="#34d399" stroke-width="1.5"/>
+        <text x="565" y="300" fill="white" font-size="11" font-weight="600" text-anchor="middle">API Server</text>
+        <text x="565" y="316" fill="#94a3b8" font-size="9" text-anchor="middle">FastAPI :8000</text>
+
+        <!-- Database Component -->
+        <rect x="700" y="280" width="120" height="50" rx="6" fill="rgba(76, 29, 149, 0.4)" stroke="#a78bfa" stroke-width="1.5"/>
+        <text x="760" y="300" fill="white" font-size="11" font-weight="600" text-anchor="middle">Database</text>
+        <text x="760" y="316" fill="#94a3b8" font-size="9" text-anchor="middle">PostgreSQL</text>
+
+        <!-- Frontend Component -->
+        <rect x="200" y="520" width="200" height="110" rx="8" fill="rgba(8, 51, 68, 0.4)" stroke="#22d3ee" stroke-width="1.5"/>
+        <text x="300" y="545" fill="white" font-size="12" font-weight="600" text-anchor="middle">Frontend</text>
+        <text x="300" y="565" fill="#94a3b8" font-size="9" text-anchor="middle">React + TypeScript</text>
+        <text x="300" y="580" fill="#94a3b8" font-size="9" text-anchor="middle">Additional detail</text>
+        <text x="300" y="595" fill="#94a3b8" font-size="9" text-anchor="middle">More info</text>
+        <text x="300" y="615" fill="#22d3ee" font-size="8" text-anchor="middle">domain.example.com</text>
+
+        <!-- =================================================================
+             ARROW EXAMPLES
+             ================================================================= -->
+
+        <!-- Standard arrow with label -->
+        <line x1="130" y1="305" x2="198" y2="305" stroke="#22d3ee" stroke-width="1.5" marker-end="url(#arrowhead)"/>
+        <text x="164" y="299" fill="#94a3b8" font-size="9" text-anchor="middle">HTTPS</text>
+        
+        <!-- Simple arrow (no label) -->
+        <line x1="310" y1="305" x2="358" y2="305" stroke="#22d3ee" stroke-width="1.5" marker-end="url(#arrowhead)"/>
+        
+        <!-- Vertical arrow -->
+        <line x1="255" y1="330" x2="255" y2="378" stroke="#fbbf24" stroke-width="1.5" marker-end="url(#arrowhead)"/>
+        <text x="270" y="358" fill="#94a3b8" font-size="9">OAI</text>
+        
+        <!-- Dashed arrow (for auth/security flows) -->
+        <line x1="460" y1="305" x2="508" y2="305" stroke="#34d399" stroke-width="1.5" marker-end="url(#arrowhead)"/>
+        <line x1="620" y1="305" x2="698" y2="305" stroke="#a78bfa" stroke-width="1.5" marker-end="url(#arrowhead)"/>
+        <text x="655" y="299" fill="#94a3b8" font-size="9">TLS</text>
+
+        <!-- Curved path for auth flow -->
+        <path d="M 80 140 L 80 200 Q 80 220 100 220 L 200 220 Q 220 220 220 240 L 220 278" fill="none" stroke="#fb7185" stroke-width="1.5" stroke-dasharray="5,5"/>
+        <text x="150" y="210" fill="#fb7185" font-size="8">JWT + PKCE</text>
+
+        <!-- =================================================================
+             LEGEND
+             ================================================================= -->
+        <text x="720" y="70" fill="white" font-size="10" font-weight="600">Legend</text>
+        
+        <rect x="720" y="82" width="16" height="10" rx="2" fill="rgba(8, 51, 68, 0.4)" stroke="#22d3ee" stroke-width="1"/>
+        <text x="742" y="90" fill="#94a3b8" font-size="8">Frontend</text>
+        
+        <rect x="720" y="98" width="16" height="10" rx="2" fill="rgba(6, 78, 59, 0.4)" stroke="#34d399" stroke-width="1"/>
+        <text x="742" y="106" fill="#94a3b8" font-size="8">Backend</text>
+        
+        <rect x="720" y="114" width="16" height="10" rx="2" fill="rgba(120, 53, 15, 0.3)" stroke="#fbbf24" stroke-width="1"/>
+        <text x="742" y="122" fill="#94a3b8" font-size="8">Cloud Service</text>
+        
+        <rect x="720" y="130" width="16" height="10" rx="2" fill="rgba(76, 29, 149, 0.4)" stroke="#a78bfa" stroke-width="1"/>
+        <text x="742" y="138" fill="#94a3b8" font-size="8">Database</text>
+        
+        <rect x="720" y="146" width="16" height="10" rx="2" fill="rgba(136, 19, 55, 0.4)" stroke="#fb7185" stroke-width="1"/>
+        <text x="742" y="154" fill="#94a3b8" font-size="8">Security</text>
+        
+        <line x1="720" y1="168" x2="736" y2="168" stroke="#fb7185" stroke-width="1" stroke-dasharray="3,3"/>
+        <text x="742" y="171" fill="#94a3b8" font-size="8">Auth Flow</text>
+        
+        <rect x="720" y="178" width="16" height="10" rx="2" fill="transparent" stroke="#fb7185" stroke-width="1" stroke-dasharray="3,3"/>
+        <text x="742" y="186" fill="#94a3b8" font-size="8">Security Group</text>
+      </svg>
+    </div>
+
+    <!-- Info Cards -->
+    <div class="cards">
+      <div class="card">
+        <div class="card-header">
+          <div class="card-dot rose"></div>
+          <h3>Card Title 1</h3>
+        </div>
+        <ul>
+          <li>• Item one</li>
+          <li>• Item two</li>
+          <li>• Item three</li>
+          <li>• Item four</li>
+        </ul>
+      </div>
+
+      <div class="card">
+        <div class="card-header">
+          <div class="card-dot amber"></div>
+          <h3>Card Title 2</h3>
+        </div>
+        <ul>
+          <li>• Item one</li>
+          <li>• Item two</li>
+          <li>• Item three</li>
+          <li>• Item four</li>
+        </ul>
+      </div>
+
+      <div class="card">
+        <div class="card-header">
+          <div class="card-dot violet"></div>
+          <h3>Card Title 3</h3>
+        </div>
+        <ul>
+          <li>• Item one</li>
+          <li>• Item two</li>
+          <li>• Item three</li>
+          <li>• Item four</li>
+        </ul>
+      </div>
+    </div>
+
+    <!-- Footer -->
+    <p class="footer">
+      [Project Name] • [Additional metadata]
+    </p>
+  </div>
+</body>
+</html>

ai_sdlc/skills/build/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: build
+description: "Implement a spec task-by-task with a verify gate after every task and a full-suite checkpoint every 2 tasks. USE WHEN: 'build X', 'implement the spec', 'continue building X', or after /spec produced .sdlc/specs/<feature>.md. Executes the spec exactly — it does not redesign. Resumable: always continues from the first unchecked task."
+argument-hint: "The feature to build (must have a spec in .sdlc/specs/)"
+---
+
+# build
+
+Executes `.sdlc/specs/<feature>.md`. The spec is the authority: `Files` lists are a whitelist, `Do` bullets are the instructions, `Verify` commands are the gate. Progress lives in the spec's checkboxes, so a fresh session resumes exactly where the last one stopped.
+
+## Setup
+
+1. Read `.sdlc/PROJECT.md` (conventions, commands, boundaries) and the spec. Spec missing → tell the user to run /spec first. Do not improvise a plan.
+2. If spec Status is `draft`, set it to `building`.
+3. `git branch --show-current` — on main/master/develop/staging/release/* → create and switch to `feat/<feature>` before touching anything.
+
+## Task loop — repeat until no `[ ]` tasks remain
+
+1. **Pick** the first `[ ]` task, top to bottom.
+2. **Read only** the files in its `Files:` and `Pattern:` lines — not the whole codebase.
+3. **Implement** exactly what the Do bullets say:
+   - Mirror the Pattern file's style: naming, error handling, imports, structure.
+   - Obey every PROJECT.md convention and boundary.
+   - Touch ONLY the listed files. If another file needs changing → STOP, report which file and why, propose the spec edit, wait for approval.
+   - No new dependencies unless the task names them. No drive-by refactors. No TODO/FIXME placeholders.
+4. **Verify.** Run the task's Verify command.
+   - Pass → continue.
+   - Fail → fix and rerun, up to 3 attempts. Still failing → mark the task `[!]` in the spec, STOP, report the exact failing output.
+5. **Mark done.** Flip `[ ]` to `[x]` in the spec. Tell the user one line: `T3 done — <name> (verify: pass)`.
+6. **Checkpoint** — after every 2 completed tasks and after the final task: run the full `test:` command from PROJECT.md.
+   - A previously-passing test now failing is a regression → fix it NOW, before the next task. Not fixed in 3 attempts → STOP and report.
+
+## Finish
+
+When every task is `[x]` and the final checkpoint is green:
+1. Set spec Status: `qa`.
+2. Report in ≤ 6 lines: tasks completed, files created/edited, suite result, then: "Run `/qa <feature>`."
+
+## Hard rules
+- Never mark a task `[x]` without its Verify passing. No exceptions, no "fix later".
+- Never weaken a failing test to make it pass — fix the code. If the test itself is wrong, say so and ask.
+- Stop conditions are stops, not suggestions: unlisted file needed · 3 failed verify attempts · unfixable regression · missing spec.
+- Fix-tasks appended by /qa (`F1`, `F2`, …) are ordinary tasks — the same loop executes them.

ai_sdlc/skills/qa/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: qa
+description: "Mechanical QA gate for a built feature — re-runs every task Verify, runs Acceptance checks, full-suite regression, and a convention diff scan, then appends a verdict to the spec. Failures become fix-tasks /build can execute. USE WHEN: 'qa X', 'test the feature', 'verify the implementation', after /build finishes."
+argument-hint: "The feature to QA (must have a spec in .sdlc/specs/)"
+---
+
+# qa
+
+Verifies a feature against its own spec. Mechanical by design: the spec already defines every check — QA executes them, it does not wander the codebase. QA reports; /build fixes.
+
+## Procedure
+
+**1. Load** `.sdlc/PROJECT.md` + the spec. Spec name unclear → list `.sdlc/specs/` and ask.
+
+**2. Task verifies.** Re-run the Verify command of every `[x]` task. Record pass/fail per task.
+
+**3. Acceptance checks.** Run each command under Acceptance checks; compare actual vs expected. If a check needs a live app, start it with PROJECT.md's `run:` command and stop it afterwards.
+
+**4. Regression.** Run the full `test:` suite. Any failure outside this feature's own tests — especially in areas named under `Touches → Risk` — is a regression: always CRITICAL, always blocks PASS.
+
+**5. Coverage gap.** Any acceptance check not covered by a test in the suite → write ONE minimal test for it (following the project's test pattern), run it, keep it.
+
+**6. Diff scan.** `git diff --name-only` (plus `git status --short` for untracked). Exactly two checks:
+- Every changed file appears in some task's `Files:` list — unlisted changes get flagged.
+- Each changed file respects PROJECT.md Conventions and Boundaries — walk the bullets mechanically.
+
+**7. Verdict.**
+- **PASS** — all task verifies, acceptance checks, and the suite are green; no unlisted changes. Convention nits alone don't block — list them as notes.
+- **FAIL** — anything else. For each failure, append a fix-task to the spec's Tasks section — `### [ ] F1 — fix: <what>` with Files / Do / Verify filled in — so `/build <feature>` can execute the fixes directly.
+
+**8. Append to the spec's QA log** (≤ 20 lines per run):
+
+```markdown
+### QA <date> — PASS | FAIL
+Task verifies: 6/6 · Acceptance: 3/3 · Suite: 42 passed, 0 failed · Regressions: 0
+Unlisted changes: none
+Failures: <one line per F-task, or "none">
+Notes: <convention nits, or "none">
+Try it:
+1. <command or click-path with concrete sample data>
+2. <expected result>
+```
+
+The **Try it** block is 2–5 steps any human — technical or not — can follow to see the feature working: concrete sample data, exact expected outcome.
+
+**9. Report in ≤ 8 lines:** verdict, the counts line, failures if any, next step — `/build <feature>` to execute fixes, or `/ship <feature>` on PASS.
+
+## Rules
+- Never PASS with a failing acceptance check or a regression. There is no "pass with warnings" for those.
+- Never fix code here — failures become F-tasks for /build. (Sole exception: the minimal coverage test in step 5.)
+- Scope is this feature's diff plus the test suite — do not re-review the whole codebase.
+- Environment blocks a check (no DB, no network)? Record it as SKIPPED with the reason — never silently count it as passing.

ai_sdlc/skills/roadmap/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: roadmap
+description: "Break a whole project (PRD or description) into an ordered list of shippable features — creates .sdlc/ROADMAP.md. Optional: for greenfield projects or large multi-feature efforts. USE WHEN: 'divide this project', 'break down this PRD', 'create a development plan'. NOT for a single feature — use /spec directly."
+argument-hint: "The PRD, project description, or doc path to break down"
+---
+
+# roadmap
+
+Turns a PRD into an ordered feature list where each feature fits one `/spec → /build → /qa → /ship` cycle. It decides WHAT to build and in what order — never HOW (no file lists, no schemas; that is /spec's job).
+
+## Procedure
+
+**1.** Read `.sdlc/PROJECT.md`. Missing → run the sdlc-init skill first (follow its SKILL.md), then return here.
+
+**2.** Read the PRD/description fully. Extract: purpose, features, constraints, non-functional needs (auth, scale, deploy).
+
+**3. Gaps → MCQ.** Ask only what changes the breakdown: rough scale, auth needs, deploy target, what is out of scope for v1. Max 5 questions; options A–D with one `(Recommended)`. ≤ 3 → ask in chat; > 3 → write `.sdlc/questions.md`, wait for **done**, read answers, delete the file.
+
+**4. Divide.** Rules:
+- Each feature = one meaningful capability, shippable and testable on its own. Target size: one focused /build session.
+- Order by dependency: skeleton → data layer → auth → core features → integrations → polish. Auth before anything protected; schema before anything that uses it.
+- On greenfield, feature 1 is always the project skeleton (installs, runs, lints, health check).
+- Max 10 lines per feature block. If a feature needs more, it is two features.
+
+**5. Write `.sdlc/ROADMAP.md`:**
+
+```markdown
+# Roadmap — <project>
+
+| # | Feature | Needs | Status |
+|---|---------|-------|--------|
+| 1 | skeleton | — | todo |
+| 2 | user-auth | 1 | todo |
+
+## 1. skeleton
+Goal: <one line>
+Scope: <3–6 bullets>
+Done when: <2–3 verifiable criteria — "returns 401 unauthenticated", not "works">
+
+## 2. user-auth
+…
+
+## Out of v1
+- <anything deliberately dropped, one line each>
+```
+
+**6. Report in ≤ 6 lines:** feature count, phase summary, and the next command: `/spec <feature-1>`.
+
+## Rules
+- Cover the ENTIRE PRD scope — anything skipped goes under "Out of v1", never silently dropped.
+- Feature names are kebab-case; they become spec filenames (`.sdlc/specs/<feature>.md`).
+- The Status column is owned by /ship — it flips `todo → done` as features ship. Don't pre-fill anything else.
+- "Done when" criteria flow into the spec's Acceptance checks — write them so a command can prove them.

ai_sdlc/skills/sdlc-init/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: sdlc-init
+description: "Set up AI-SDLC for a project — creates .sdlc/PROJECT.md (stack, layout, commands, conventions) and .sdlc/STATE.md (feature log). Run once per project, before any other SDLC skill. USE WHEN: 'set up sdlc', 'init project context', or any SDLC skill finds no .sdlc/ folder."
+argument-hint: "Optionally: a PRD/description, a doc path, or 'analyze the codebase'"
+---
+
+# sdlc-init
+
+Creates the two files every other SDLC skill reads. Both are loaded on every skill run, so every line must earn its place — facts only, no prose.
+
+## Output contract
+
+| File | Contains | Budget |
+|---|---|---|
+| `.sdlc/PROJECT.md` | Stack, layout, commands, conventions, boundaries | ≤ 80 lines |
+| `.sdlc/STATE.md` | Feature status table + cross-feature notes | grows ~1 line per feature |
+
+## Procedure
+
+**1. Existing setup check.** If `.sdlc/PROJECT.md` exists and is non-empty: show a 3-line summary, ask — update, replace, or cancel. Wait for the answer.
+
+**2. Gather facts — use the first source that applies:**
+- **PRD or description provided** → read it. Extract: purpose, users, features, stack, constraints.
+- **Codebase exists** → detect, don't interrogate:
+  - Read manifests (`package.json` / `pyproject.toml` / `go.mod` / `Cargo.toml` / …), `docker-compose.yml`, `.env.example`, README.
+  - Read the entry point, 2–3 representative source files (one per layer), and 1 test file.
+  - Do NOT scan the whole codebase — ~10 file reads maximum.
+- **Neither (greenfield, no PRD)** → question mode; step 3 collects everything.
+
+**3. Close remaining gaps with MCQs.** Only ask what steps 1–2 didn't answer and PROJECT.md needs: language + version, framework, DB, package manager, test runner, repo layout, auth approach, deploy target.
+- Format: options A–D, one marked `(Recommended)` where a best practice exists. Blank answer = recommended.
+- ≤ 3 questions → ask directly in chat.
+- \> 3 questions → write `.sdlc/questions.md` (same A–D format, each with an `Answer:` line), tell the user to fill it and reply **done**. Wait, read the answers, then delete the file.
+- Hard cap: 7 questions.
+
+**4. Write `.sdlc/PROJECT.md`** from the template below.
+- Conventions: max 12 bullets, each mechanically checkable ("type hints on all functions" — not "write clean code").
+- Commands must be real: run the test command once to confirm it works (skip on greenfield).
+- No placeholders left in the final file.
+
+**5. Write `.sdlc/STATE.md`** from the template below (empty table).
+
+**6. Report in ≤ 6 lines:** files created, detected stack, and the next step — `/roadmap` for a whole project, `/spec <feature>` for one feature.
+
+## PROJECT.md template
+
+```markdown
+# <project name>
+<one line: what it is and who uses it>
+
+## Stack
+- <language + version, package manager>
+- <framework> | <database + ORM> | <frontend or "none">
+- <anything else an implementer must know: queue, cache, auth method>
+
+## Layout
+- <dir>/ → <responsibility + the one rule that matters, e.g. "routes/ → HTTP only, delegate to services">
+- <dir>/ → <…>
+- <test location + naming, e.g. "tests/<area>/test_*.py">
+> Repos: <single | list each path + purpose if multi-repo>
+
+## Commands
+- test: <exact command>
+- lint: <exact command>
+- run: <exact command>
+- migrate: <exact command or "n/a">
+
+## Conventions
+- <max 12 checkable bullets>
+
+## Boundaries
+- Never edit: <e.g. migrations/versions/*, generated files>
+- Never commit: .env*, secrets, build artifacts
+```
+
+## STATE.md template
+
+```markdown
+# State
+
+| Feature | Spec | Status | Shipped |
+|---|---|---|---|
+
+## Notes
+<!-- cross-feature facts an implementer must know; one line each -->
+```
+
+## Edge cases
+- Multiple languages in the workspace → list all in Stack, ask which is primary (1 MCQ).
+- Monorepo / multi-repo → one PROJECT.md at the workspace root; Layout lists each repo path + purpose.
+- User says "skip questions" → use recommended defaults, mark them `(assumed)` in PROJECT.md.

ai_sdlc/skills/ship/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: ship
+description: "Commit a QA-passed feature safely — branch guard, explicit staging, conventional commit built from the spec, STATE.md + roadmap update. Never pushes, never commits on protected branches. USE WHEN: 'ship X', 'commit the feature', 'commit my changes', after /qa passes."
+argument-hint: "The feature to ship (e.g. 'ship user-auth')"
+---
+
+# ship
+
+Commit-only. Reads the spec for the message, guards the branch, stages files by name, updates the feature log. Never pushes.
+
+## Procedure
+
+**1. Gate.** Read the spec. The latest QA log entry must be PASS. Not PASS, or no QA log → say so and offer `/qa <feature>`. Proceed anyway only on an explicit user override ("ship anyway") — note the override in the commit body.
+
+**2. Branch guard** (per repo, if multi-repo). `git branch --show-current`. On main / master / develop / development / staging / integration / release/* or detached HEAD → refuse and offer:
+- A) create `feat/<feature>` and continue
+- B) user switches manually
+- C) cancel
+
+**3. Update records first, so they ride in the same commit:**
+- Spec `Status:` → `done`
+- `.sdlc/STATE.md` → add or update the row: `| <feature> | specs/<feature>.md | done | <YYYY-MM-DD> |`
+- `.sdlc/ROADMAP.md` (if the feature is on it) → flip its Status to `done`
+
+**4. Stage.** `git status --short`. Stage by name — never `git add .` or `-A`:
+- every file from the spec's task `Files:` lists
+- the spec itself, STATE.md, ROADMAP.md if touched
+- never `.env*`, secrets, build artifacts, dependency dirs
+- changed files NOT in the spec → list them, ask include / exclude
+
+**5. Build the message** (Conventional Commits):
+
+```
+<type>(<feature>): <spec Goal, imperative, ≤ 72 chars>
+
+- <one bullet per task — the behavior, not the file names>
+
+Spec: .sdlc/specs/<feature>.md
+```
+
+Type: feat | fix | refactor | test | chore — whichever the spec actually did.
+
+**6. Confirm.** Show branch, staged file list, and the message. Wait for **yes** (or apply requested edits). Then commit — multi-line via `git commit -F .sdlc/commit-msg.txt`, delete the temp file after.
+
+**7. Report in ≤ 5 lines:** short hash, branch, file count, and the push command as reference only. Do not push. Do not open a PR.
+
+## Rules
+- Never push. Never commit on a protected branch. Never stage secrets.
+- Merge-conflict markers anywhere → refuse; user resolves first.
+- Multi-repo: run guard → stage → commit per repo that has changes; each repo gets its own message.
+- Clean working tree → show status, exit cleanly.
+- Branch named `trunk` or `mainline` → treat as protected, ask before proceeding.

ai_sdlc/skills/spec/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: spec
+description: "Plan one feature into a single executable spec — .sdlc/specs/<feature>.md with decisions (why), integration map, and small verifiable tasks (instructions + contracts, NOT code). USE WHEN: 'plan X', 'spec the auth feature', 'plan roadmap feature 3', before building anything non-trivial. Produces the file /build executes."
+argument-hint: "The feature to spec (e.g. 'user auth', 'roadmap feature 3', 'payment webhooks')"
+---
+
+# spec
+
+Produces ONE file containing everything about a feature — what, why, and how — as tasks small enough that a weak model can implement each one without judgment calls. Tasks carry contracts and instructions, never full code. The developer reads the Decisions section and can explain the design to anyone.
+
+## Procedure
+
+**1. Load context — these files and nothing else:**
+- `.sdlc/PROJECT.md` — missing → run the sdlc-init skill first, then return here.
+- `.sdlc/STATE.md` — what already shipped; never re-plan existing work.
+- `.sdlc/ROADMAP.md` — only if the user referenced a roadmap feature; pull its goal, scope, done-when.
+
+**2. Understand.** Restate the feature in ≤ 2 sentences: what the user gets, what changes in the system. This becomes `Goal`. Then draft the **What & why** section — 3–6 plain-English sentences describing what this feature is and how it will work once built (the journey from the user's action to the result). No jargon: a smart 12th-grader with zero coding background must be able to follow it.
+
+**3. Research the unknowns (no code yet).** List the components the feature needs (e.g. "JWT refresh flow", "webhook signature verification", "cursor pagination"). For each one not already solved in this codebase:
+- Find the standard production approach — official docs / web search if tools are available, otherwise known best practice.
+- Write a **Decision** in the template's format, ≤ 5 lines, in plain English:
+  1. what the component IS — one simple line, assume the reader has never heard of it
+  2. what we chose
+  3. why, in everyday words
+  4. what we rejected and why not
+- Define every technical term in brackets at first use — e.g. "JWT (a signed pass the server can verify without a database lookup)".
+- Audience rule: **What & why** and **Decisions** are written for the developer and anyone they must explain the feature to — a boss, a client, a teammate — NOT for the model. If a sentence needs a CS degree, rewrite it.
+
+**4. Integration scan.** Read ONLY the existing files this feature touches or extends. Record in `Touches`:
+- files to be edited, and what changes in each
+- pattern files — existing code the new code must mirror (the style-drift guard)
+- existing behavior this could break (shared utils, routes, schema) → these become QA regression targets
+
+**5. Gaps → MCQ.** Only unknowns that change the design. Max 5; options A–D with one `(Recommended)`. ≤ 3 → ask in chat; > 3 → write `.sdlc/questions.md`, wait for **done**, read answers, delete the file.
+
+**6. Write `.sdlc/specs/<feature>.md`** (kebab-case filename) from the template below. Task rules — /build depends on these:
+- **≤ 8 tasks.** Need more → split the feature; tell the user.
+- Order by dependency. Each task independently verifiable.
+- Each task ≤ 20 lines with exactly these fields:
+  - `Files:` explicit CREATE / EDIT list — /build treats this as a whitelist
+  - `Pattern:` existing file to mirror (omit if none)
+  - `Do:` 3–7 imperative bullets — exact names, signatures, routes, data shapes, edge cases
+  - `Verify:` one runnable command + expected outcome
+- Code appears ONLY as: function/route signatures, request/response/schema shapes, and ≤ 5-line pseudocode for genuinely tricky logic. NEVER full file bodies.
+- Every Do bullet must be decidable without judgment: "hash with bcrypt, cost 12" — not "hash securely".
+- If tests aren't built into each task, the last task is the feature's tests.
+
+**7. Report in ≤ 6 lines:** spec path, task count, key decisions (1 line each), then: "Review Decisions and Tasks — edit anything — then run `/build <feature>`."
+
+## Spec template
+
+```markdown
+# <feature>
+Status: draft            <!-- draft → building → qa → done · owned by build/qa/ship -->
+Goal: <one line>
+Done when:
+- <verifiable criterion>
+- <verifiable criterion>
+
+## What & why — plain English
+<3–6 sentences anyone can understand: what this feature is, how it works once
+built — the flow from the user's action to the result — and where it fits in
+the app. Optional: a ≤ 8-line ASCII flow of that journey.>
+
+## Decisions
+<!-- One block per choice · ≤ 5 lines each · plain English · define jargon in
+     brackets at first use. A non-programmer must be able to read these. -->
+- **<Component>** — <what this thing is, one simple line>.
+  Chose: <choice>. Why: <reason in everyday words>.
+  Rejected: <alternative> — <why not>.
+
+## Touches
+- Edits: <existing files + what changes in each>
+- Mirrors: <pattern file(s) new code must match>
+- Risk: <existing behavior that could break — QA checks these>
+
+## Tasks
+
+### [ ] T1 — <name>
+Files: CREATE src/…, EDIT src/…
+Pattern: src/…
+Do:
+- <exact imperative instruction>
+- <signature / shape where needed>
+Verify: `<command>` → <expected>
+
+### [ ] T2 — <name>
+…
+
+## Acceptance checks
+- [ ] `<command>` → <expected observable result>
+- [ ] `<command>` → <expected>
+
+## QA log
+<!-- appended by /qa -->
+```
+
+## Quality bar — check before saving
+- [ ] A model with ONLY this spec + PROJECT.md could implement every task
+- [ ] Every task has a runnable Verify; every "Done when" maps to an Acceptance check
+- [ ] No full code bodies; no vague bullets ("handle errors properly")
+- [ ] Touches lists every existing file that will change
+- [ ] **What & why** + **Decisions** pass the 12th-grader test: a reader with no coding
+      background can say what is being built, how it will work, and why each choice
+      was made — every technical term is defined at first use

ai_sdlc_kit-0.1.0.dist-info/METADATA

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: ai-sdlc-kit
+Version: 0.1.0
+Summary: Spec-driven SDLC skills for AI coding agents — Claude Code, Cursor, Windsurf, Gemini CLI
+Project-URL: Homepage, https://github.com/xajeel/AI-SDLC
+Author: xajeel
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,claude-code,cursor,sdlc,skills,spec-driven
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# AI-SDLC v2 — Spec-Driven Skills for AI Coding Agents
+
+A lean, token-efficient Software Development Life Cycle for AI coding agents (Claude Code, Cursor, Windsurf, Gemini CLI). Six skills that make an agent work the way a senior engineer does: **understand → decide → plan in verifiable steps → build with checks after every step → gate → ship**.
+
+Designed so that **even a small model can execute reliably**: the planning skill (run once, ideally with a strong model) removes every judgment call up front, and the execution skills are mechanical loops with hard stop conditions.
+
+---
+
+## Design principles (what changed from v1)
+
+| v1 problem | v2 fix |
+|---|---|
+| Huge token use | Skills are 4–10× smaller; artifacts have hard size budgets; every skill reads only the files it names — never "scan the codebase" |
+| Implementation files full of code, impossible to review | Specs contain **instructions + contracts** (signatures, shapes, exact steps) — never code bodies. You review decisions and contracts, not walls of code |
+| QA didn't catch bugs | Checks are **defined at plan time** (every task has a `Verify` command, every goal an acceptance check). QA just executes them — nothing left to a model's mood |
+| Too many files per feature | **One spec file per feature.** Plan, decisions, tasks, and QA log all live in `.sdlc/specs/<feature>.md` |
+| Features silently broke each other | `/build` runs the full test suite every 2 tasks (not only at the end); `/qa` treats any regression as an automatic FAIL |
+| Style drift, copied bugs | Every task names a `Pattern:` file the new code must mirror; PROJECT.md carries ≤ 12 checkable convention rules |
+| Black-box output | Every spec opens with **What & why** (plain-English story of the feature) and a **Decisions** section: what each component is, what was chosen, why, and what was rejected — written to pass the "12th-grader test", so you can explain the design to anyone |
+
+---
+
+## Install
+
+Copy the folders inside `skills/` into your agent's skills directory at the project root:
+
+| Agent / IDE | Path |
+|---|---|
+| Claude Code | `.claude/skills/` |
+| Cursor | `.cursor/skills/` |
+| Windsurf | `.windsurf/skills/` |
+| Gemini CLI | `.gemini/skills/` |
+
+The skills appear as slash commands: `/sdlc-init`, `/roadmap`, `/spec`, `/build`, `/qa`, `/ship`.
+
+---
+
+## The flow
+
+```
+/sdlc-init                     one-time setup            → .sdlc/PROJECT.md + STATE.md
+    │
+/roadmap   (optional)          whole project → features  → .sdlc/ROADMAP.md
+    │
+/spec <feature>                plan one feature          → .sdlc/specs/<feature>.md
+    │                          (research, decisions, tasks with contracts + verify commands)
+/build <feature>               implement task-by-task    → code; verify gate after EVERY task,
+    │                                                      full-suite checkpoint every 2 tasks
+/qa <feature>                  mechanical gate           → verdict appended to the spec;
+    │                                                      failures become fix-tasks for /build
+/ship <feature>                safe commit               → feature branch only, STATE.md updated
+```
+
+The `/build → /qa → /build` loop is the self-healing part: QA never fixes code, it appends `F1, F2…` fix-tasks to the spec, and `/build` executes them like any other task.
+
+## The six skills
+
+| Skill | Does | Reads | Writes |
+|---|---|---|---|
+| `sdlc-init` | One-time project setup: stack, layout, commands, conventions, boundaries | manifests + a few source files, or PRD, or your answers | `PROJECT.md`, `STATE.md` |
+| `roadmap` | Splits a PRD into ordered, shippable features (what + order, never how) | PROJECT.md, the PRD | `ROADMAP.md` |
+| `spec` | Plans one feature: researches unknowns, records decisions, writes ≤ 8 tasks with `Files / Pattern / Do / Verify` | PROJECT.md, STATE.md, only the files the feature touches | `specs/<feature>.md` |
+| `build` | Executes the spec exactly: whitelist files, mirror patterns, verify after every task, checkpoint every 2 | PROJECT.md, the spec, only listed files | code + spec checkboxes |
+| `qa` | Re-runs all verifies + acceptance checks + full suite + diff scan; PASS/FAIL verdict; failures → fix-tasks | PROJECT.md, the spec, the diff | QA log in the spec |
+| `ship` | Branch guard, explicit staging, conventional commit from the spec, records update. Never pushes | the spec | git commit, STATE.md, ROADMAP.md |
+
+Bonus: `architecture-diagram` — renders a self-contained HTML/SVG architecture diagram (unchanged from v1).
+
+---
+
+## The `.sdlc/` folder — 4 file types, that's all
+
+```
+.sdlc/
+├── PROJECT.md          # ≤ 80 lines: stack, layout, commands, conventions, boundaries
+├── STATE.md            # one table: feature | spec | status | shipped date (+ cross-feature notes)
+├── ROADMAP.md          # optional: ordered feature list for a whole project
+└── specs/
+    └── <feature>.md    # everything about one feature: goal, decisions, touches,
+                        # tasks (with checkboxes = live progress), acceptance checks, QA log
+```
+
+A spec file looks like this (abridged):
+
+```markdown
+# user-auth
+Status: building
+Goal: Email+password auth issuing JWT access/refresh tokens
+Done when:
+- POST /v1/auth/login returns tokens for valid credentials
+- Protected routes return 401 without a valid token
+
+## What & why — plain English
+When someone signs up, we store their account with a scrambled (hashed) password —
+we never keep the real one. When they log in, we check the password and hand back
+two digital passes: a short-lived access token shown on every request, and a
+longer-lived refresh token used to get a new pass when the old one expires.
+Any protected page simply refuses visitors without a valid pass.
+
+## Decisions
+- **JWT tokens** — a JWT is a signed digital pass the server can verify without a
+  database lookup. Chose: 15-min access token + rotating 7-day refresh token.
+  Why: servers don't have to remember who is logged in, so the app scales by just
+  adding more servers. Rejected: cookie sessions — they need shared session
+  storage, which complicates scaling.
+- **bcrypt (cost 12)** — a slow-by-design password scrambler, so stolen data is
+  useless to attackers. Why: the battle-tested standard. Rejected: argon2 —
+  slightly stronger but adds a native dependency our stack doesn't need.
+
+## Touches
+- Edits: src/main.py (register router)
+- Mirrors: src/routes/items.py, src/services/items.py
+- Risk: shared error handler in src/exceptions.py
+
+## Tasks
+### [x] T1 — User model + migration
+Files: CREATE src/models/user.py, CREATE migrations/…
+Pattern: src/models/item.py
+Do:
+- Table users: id UUID pk, email unique not-null, password_hash str, created_at
+- Migration with upgrade + downgrade
+Verify: `uv run alembic upgrade head` → applies cleanly
+
+### [ ] T2 — Auth service
+Files: CREATE src/services/auth.py
+Pattern: src/services/items.py
+Do:
+- register(email, password) -> User — reject duplicate email with ConflictError
+- login(email, password) -> TokenPair(access: str, refresh: str)
+- Hash with bcrypt cost 12; never log passwords
+Verify: `uv run pytest tests/auth -q` → pass
+
+## Acceptance checks
+- [ ] `curl -s -X POST :8000/v1/auth/login -d '{…}'` → 200 with access + refresh tokens
+- [ ] `curl -s :8000/v1/items` (no token) → 401
+
+## QA log
+### QA 2026-07-12 — PASS
+Task verifies: 5/5 · Acceptance: 3/3 · Suite: 42 passed · Regressions: 0
+Try it:
+1. Run `uv run uvicorn src.main:app`, POST /v1/auth/register with {"email":"test@example.com","password":"Pass123!"}
+2. Expect 201 and a user id; then login with the same credentials → 200 with two tokens
+```
+
+Notice: an implementer needs **no other document**, a reviewer reads Decisions + contracts in minutes, the checkboxes are resumable progress state, and QA's checklist was fixed the moment the spec was written.
+
+---
+
+## Why this works with small models
+
+1. **Judgment happens once, at spec time.** Use your best model for `/spec`. After that, `/build` and `/qa` are deterministic loops — pick task, read 2–3 listed files, follow exact bullets, run a command, check a box.
+2. **Whitelists instead of freedom.** A task's `Files:` list is a hard boundary; needing another file is a stop-and-report, not an improvisation.
+3. **Patterns instead of taste.** "Mirror `src/services/items.py`" keeps style consistent without describing style.
+4. **Verification is a command, not an opinion.** Every task and every acceptance criterion is proven by running something and comparing output.
+5. **Tiny context.** PROJECT.md ≤ 80 lines, one spec per feature, skills that forbid whole-codebase scans — the model's window stays small and focused.
+
+## Roadmap for this kit
+
+- pip / npm installer that copies skills into the right folder per agent and scaffolds `.sdlc/`
+- Optional CI hook: run `/qa` checks headlessly on pull requests
+
+Related prior art: [github/spec-kit](https://github.com/github/spec-kit).

ai_sdlc_kit-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+ai_sdlc/__init__.py,sha256=gbdBYQ8g-h1ARESgDVQbfngnSYJl6bTvd_bgMpquR_0,64
+ai_sdlc/cli.py,sha256=yYe1UMIfxvLOGDA0hxZiP4-1KLXMSD0ZV07B2VYY6P0,4135
+ai_sdlc/skills/architecture-diagram/SKILL.md,sha256=j9B03K8VqoiHnQcj2pkxpS-5do58_SnkHBB3-lFRAPM,6386
+ai_sdlc/skills/architecture-diagram/assets/template.html,sha256=-OGPVK7gDUbmtFCc2QM6iBbAs-bDvamd9kRhEkezzpw,12482
+ai_sdlc/skills/build/SKILL.md,sha256=HB2E_k0S0zP43oEvgQpPOkCEyHiWqD32QJt-XK-swKU,2941
+ai_sdlc/skills/qa/SKILL.md,sha256=RNPwT-Q-4yrAphd_FET0BWy_sJ2bNFXe8EHB7mHlF1E,3214
+ai_sdlc/skills/roadmap/SKILL.md,sha256=lQHR_7cKchcNkqafbhaVEuuzA8rGxHncbS7L234JMW4,2647
+ai_sdlc/skills/sdlc-init/SKILL.md,sha256=1jqZRp4rjzNp6kJ2Q_cfCqTuAuy09emLEmpTkNpQ-bQ,3985
+ai_sdlc/skills/ship/SKILL.md,sha256=qZygTsGaWiBn0VlMLMLWKlgkL2BnOMyV_HZhfu3K6QI,2626
+ai_sdlc/skills/spec/SKILL.md,sha256=klaOGevmnWU-XIFn3zrrGJEtj3TpfUvmqtKvy4ExQlA,6028
+ai_sdlc_kit-0.1.0.dist-info/METADATA,sha256=b_Sly7FOLU5XzwdLzlpgftl8593liNOofB05swaIy7s,9634
+ai_sdlc_kit-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+ai_sdlc_kit-0.1.0.dist-info/entry_points.txt,sha256=fGUpqBfCpkoZP2GkwmZpbEMll5AvDoatao928B5QRXs,45
+ai_sdlc_kit-0.1.0.dist-info/licenses/LICENSE,sha256=l7UBWQC4JuYyqyEBmDyhoiQJ3mB_TX24wpFkCfimRJM,1063
+ai_sdlc_kit-0.1.0.dist-info/RECORD,,

ai_sdlc_kit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

ai_sdlc_kit-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ai-sdlc = ai_sdlc.cli:main

ai_sdlc_kit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xajeel
+
+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.