ai-sdlc-kit 0.1.0__tar.gz

ai_sdlc_kit-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+dist/
+__pycache__/
+*.egg-info/
+.venv/
+.sdlc/questions.md

ai_sdlc_kit-0.1.0/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.

ai_sdlc_kit-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,162 @@
+# 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/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ai-sdlc-kit"
+version = "0.1.0"
+description = "Spec-driven SDLC skills for AI coding agents — Claude Code, Cursor, Windsurf, Gemini CLI"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{ name = "xajeel" }]
+keywords = ["ai", "agents", "sdlc", "claude-code", "cursor", "skills", "spec-driven"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+  "Intended Audience :: Developers",
+  "Topic :: Software Development",
+]
+
+[project.scripts]
+ai-sdlc = "ai_sdlc.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/xajeel/AI-SDLC"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ai_sdlc"]
+
+# This line is what bundles the repo-root skills/ folder into the wheel:
+[tool.hatch.build.targets.wheel.force-include]
+"skills" = "ai_sdlc/skills"
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "skills", "README.md", "LICENSE", "pyproject.toml"]

ai_sdlc_kit-0.1.0/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.