@rashidee/co2 1.2.6 → 1.3.2

package/plugin/SKILLS.md

@@ -1,350 +1,417 @@
-# CO2 Skills Catalog — Agent Reference
-
-> **Audience:** AI agents. This document tells you WHICH skill to invoke WHEN in the
-> Compound Context (CO2) workflow. Every skill reads its inputs from the project's context
-> files (`CLAUDE.md`, `<app_folder>/context/PRD.md`, etc.) — invoke with the application
-> name and version; do not ask the user for information the context files already contain.
-
-## Workflow Order
-
-Skills belong to phases and generally must run in this order per application:
-
-```
-0. Bootstrap        util-projectinit → (user fills session) → /brainstorm-loop → util-projectsync
-1. PRD clean-up     util-usanalyzer → util-ustagger          (util-updprd for requirement changes)
-2. Artifacts        modelgen-* → mockgen-* → specgen-* → testgen-functional
-                    (or all four via conductor-feature-prepare)
-3. Infrastructure   util-preparek8senv                        (before development)
-4. Development      conductor-feature-develop → tracegen-matrix (auto) → depgen-k8s (auto)
-5. Bug fixing       conductor-defect → tracegen-matrix (auto)
-```
-
-## Artifact Map — who produces what
-
-```
-<project_root>/
-├── CLAUDE.md                          ← /brainstorm-loop (Phase A), annotated by util-projectsync
-├── DEVTOOL.md                         ← per-developer (manual)
-├── ENVIRONMENT.md                     ← util-preparek8senv
-├── <topic>.brainstorm.md              ← util-projectinit (session doc, iterated by /brainstorm-loop)
-├── brainstorm-protocol.md             ← util-projectinit (copied)
-├── co2-context-generation-guide.md    ← util-projectinit (copied)
-├── environment/                       ← util-preparek8senv (K8s manifests for 3rd party apps; gitignored)
-└── <app_folder>/
-    ├── CHANGELOG.md                   ← appended by every skill (version gate)
-    ├── Dockerfile                     ← depgen-k8s
-    ├── k8s/                           ← depgen-k8s (app manifests; gitignored)
-    ├── (source code)                  ← conductor-feature-develop / conductor-defect
-    └── context/
-        ├── PRD.md                     ← /brainstorm-loop (Phase B), scaffolded by util-projectsync,
-        │                                tagged by util-ustagger, annotated by util-usanalyzer
-        ├── BUG.md                     ← util-projectsync scaffold; user reports; tagged by conductor-defect
-        ├── TRACEABILITY.md            ← tracegen-matrix
-        ├── model/                     ← modelgen-relational / modelgen-nosql
-        ├── mockup/                    ← mockgen-tailwind / mockgen-shadcn (assets + manifest;
-        │                                served by the shared Mockup Hub at <root>/mockup)
-        ├── specification/             ← specgen-* (one variant)
-        ├── test/                      ← testgen-functional
-        ├── prepare/                   ← conductor-feature-prepare (PREPARE_MASTER.md tracking)
-        ├── develop/                   ← conductor-feature-develop (tracking files)
-        └── bug/                       ← conductor-defect (per-bug tracking files)
-```
-
-**Universal conventions (apply to almost every skill):**
-
-- **Invocation shape:** `/skill-name <application> <version> [module:<name>]`. The application
-  name resolves to a root-level app folder (leading `<number>_` prefix stripped,
-  case-insensitive, snake/kebab/title case all match).
-- **Version gate:** skills refuse to run for a version lower than the highest version recorded
-  in `<app_folder>/CHANGELOG.md`, and append a row there on success.
-- **Version filtering:** only PRD items tagged `[vX.Y.Z]` <= the requested version are included;
-  strikethrough (`~~…~~`) items are deprecated and excluded.
-- **Traceability:** PRD item IDs (e.g., `[USHM00003]`, `[NFRHM0012]`) must be carried through
-  into every generated artifact.
-
----
-
-## Phase 0 — Project Bootstrap
-
-### `util-projectinit`
-- **Invoke:** `/util-projectinit "<application idea or topic>"`
-- **What it does:** Sets up a file-based, turn-based **brainstorming session** in the project
-  folder: generates `<topic>.brainstorm.md` from the appdev template (seeded with the idea),
-  copies `brainstorm-protocol.md` and `co2-context-generation-guide.md` to the project root,
-  and ensures the `/brainstorm-loop` command is installed. It does NOT generate project context
-  directly and it NEVER starts the loop itself — it instructs the user to fill in the session
-  document and manually run `/brainstorm-loop`.
-- **Use when:** the user wants to start/init/bootstrap a NEW project, or brainstorm an
-  application idea into CO2 context. First skill of the workflow.
-- **Do NOT use when:** the project already has a `CLAUDE.md` and the user wants to evolve it
-  (use `util-projectsync` or `util-updprd`).
-- **Prerequisites:** an application idea (even one paragraph).
-- **Output:** `<topic>.brainstorm.md` (session document), `brainstorm-protocol.md`,
-  `co2-context-generation-guide.md` at the project root, and
-  `.claude/commands/brainstorm-loop.md` when the plugin command is not available — plus a
-  hand-off instruction block. Non-destructive — never overwrites existing files.
-
-### `/brainstorm-loop` (plugin command, not a skill)
-- **Invoke:** `/brainstorm-loop [scan-root] [max-watch-rounds]` — **run manually by the user**,
-  never auto-started by a skill.
-- **What it does:** In-session watch loop over `*.brainstorm.md` session documents. Each round
-  the agent drafts the CO2 context tree (Phase A: root `CLAUDE.md`; Phase B: one `PRD.md` per
-  application) per `co2-context-generation-guide.md`, appends questions, and waits for the
-  human to answer and flip a status row. Token-efficient: 60-second file polling, acts only on
-  status flips.
-- **Output:** root `CLAUDE.md` + `<app_folder>/context/PRD.md` per application (at the session's
-  destination), plus a `.brainstorm-loop-status.md` dashboard.
-
-### `util-projectsync`
-- **Invoke:** `/util-projectsync` (no arguments — reads everything from `CLAUDE.md`)
-- **What it does:** Synchronizes project folder structure with `CLAUDE.md`: validates
-  dependencies (circular, missing, logical) and orphaned services, creates missing application
-  folders, scaffolds `PRD.md`/`BUG.md` from templates, adds missing module sections, inserts
-  `[TODO]` annotations into `CLAUDE.md` for validation failures.
-- **Use when:** after the brainstorm closes, or any time `CLAUDE.md` applications/modules
-  changed and folders/PRDs must catch up ("sync project", "scaffold project folders",
-  "validate dependencies").
-- **Prerequisites:** `CLAUDE.md`.
-- **Output:** missing `<app_folder>/` folders, scaffolded `<app_folder>/context/PRD.md` and
-  `BUG.md`, missing module sections added to existing files, `[TODO]` annotations in
-  `CLAUDE.md` for validation failures, and a sync/validation summary report.
-
----
-
-## Phase 1 — PRD Clean-Up
-
-### `util-usanalyzer`
-- **Invoke:** `/util-usanalyzer <application>`
-- **What it does:** Analyzes `PRD.md` for quality issues — incomplete sentences, broken
-  references, cross-module inconsistencies, contradictions, duplicate roles, process-flow
-  coverage gaps — and adds inline `[TODO]` annotations for each issue.
-- **Use when:** the user asks to validate/review/audit user stories or requirements quality,
-  or before tagging a freshly edited PRD.
-- **Prerequisites:** `PRD.md`.
-- **Output:** inline `[TODO]` annotations written into `PRD.md` at each issue, plus a summary
-  report of all issues found with improvement suggestions.
-
-### `util-ustagger`
-- **Invoke:** `/util-ustagger <application> <version>`
-- **What it does:** Tags every untagged top-level item in `PRD.md` (User Stories, NFRs,
-  Constraints, References, Tests) with a unique 9-character ID code and validates that no
-  duplicate tags exist.
-- **Use when:** new PRD items need IDs ("tag user stories", "add IDs to requirements",
-  "validate tags"). Run after any manual PRD edit and before artifact generation.
-- **Prerequisites:** `PRD.md`.
-- **Output:** updated `PRD.md` with every item tagged (e.g., `[USHM00003]`, `[NFRHM0012]`,
-  `[CONHM0009]`, `[REFHM0003]`), plus a duplicate-tag validation report.
-
-### `util-updprd` ⚠️ *not yet implemented — folder is an empty stub; do not invoke*
-- **Documented intent:** apply a free-form requirement change across all applications' PRD.md
-  files — decide add/cancel/modify per item, auto-classify major/minor/patch, layer changes
-  under a NEW version tag (prior versions immutable), tag via `util-ustagger`, append
-  CHANGELOG entries.
-
----
-
-## Phase 2 — Context Artifact Generation
-
-> Run the four steps individually below, or all at once via `conductor-feature-prepare`.
-
-### `conductor-feature-prepare` (orchestrator)
-- **Invoke:** `/conductor-feature-prepare <application> [version:<v>] [module:<m>]`
-- **What it does:** Runs `util-ustagger` → `modelgen-*` → `mockgen-*` → `specgen-*` →
-  `testgen-functional` in sequence, auto-selecting the right variant per the application's
-  technology stack, tracking progress in `PREPARE_MASTER.md` (read first on resume to skip
-  already-completed steps/versions). Multiple versions are processed sequentially in ascending
-  semver order. Manages its own Ralph Loop internally for cross-session continuity.
-- **Use when:** "prepare artifacts", "generate context", "prepare for development",
-  "resume preparation".
-- **Prerequisites:** `PRD.md`, `CLAUDE.md`.
-- **Output:** the complete `context/` artifact tree — `model/`, `mockup/`, `specification/`
-  and `test/` (each as described under its sub-skill below) — plus `CHANGELOG.md` entries per
-  step and the `context/prepare/PREPARE_MASTER.md` progress tracker (inferred config, per-version
-  × per-artifact status) for cross-session resumption.
-
-### `modelgen-relational`
-- **Invoke:** `/modelgen-relational <application> <version> [module:<m>]`
-- **What it does:** Extracts relational (SQL) entity models from user stories using DDD —
-  ERD diagrams (Mermaid) + per-module model documentation. Also handles "update/upgrade the
-  model" for incremental evolution.
-- **Use when:** the app's datastore is a relational DB (MySQL, PostgreSQL, SQLite …).
-- **Output:** `context/model/` — `MODEL.md` index + per-module `model.md` / `erd.mermaid`.
-
-### `modelgen-nosql`
-- **Invoke:** `/modelgen-nosql <application> <version> [module:<m>]`
-- **What it does:** Extracts NoSQL document models (embed-vs-reference analysis, Mermaid class
-  diagrams, JSON schema examples per collection). Database-agnostic (MongoDB, Couchbase,
-  DynamoDB, Firestore, CosmosDB).
-- **Use when:** the app's datastore is document-oriented. **Not** for relational schemas —
-  use `modelgen-relational`.
-- **Output:** `context/model/` — `MODEL.md` index + per-module `model.md` (embed/reference
-  decisions), Mermaid class diagram, and `schemas.json` JSON schema examples per collection.
-
-### `mockgen-tailwind`
-- **Invoke:** `/mockgen-tailwind <application> <version> [module:<m>]`
-- **What it does:** Generates HTML mockup screens (Alpine.js + HTMX assets, admin
-  dashboard layout, organized by user role) for human designer review. All mockups are
-  served by the single shared **Mockup Hub** at `<root>/mockup` — a zero-dependency Node
-  server (created/upgraded automatically) with a landing page listing every application
-  and role (unclickable until ready) and a configurable port (`PORT` env /
-  `mockup.config.json`).
-- **Use when:** mockups are needed and the target stack is server-rendered or plain HTML;
-  default mockup generator.
-- **Prerequisites:** `PRD.md`, `modelgen-*` output.
-- **Output:** `context/mockup/` — `MOCKUP.html` index, `mockup-manifest.json`, partials,
-  role folders (assets only; no per-app server) + shared hub at `<root>/mockup/`.
-
-### `mockgen-shadcn`
-- **Invoke:** `/mockgen-shadcn <application> <version> [module:<m>]`
-- **What it does:** Generates React + shadcn/ui mockup screens (Vite + React 19 + TypeScript +
-  React Router v7, admin dashboard layout, organized by user role) with
-  `base`/`basename` = `/{app_slug}/`, builds them (`npm run build`), and serves the `dist/`
-  output through the same shared **Mockup Hub** at `<root>/mockup` (Vite dev server remains
-  for design iteration only).
-- **Use when:** the target application is React/shadcn-based (pairs naturally with
-  `specgen-nextjs-react-tailwind` / `specgen-node-cli-web`).
-- **Prerequisites:** `PRD.md`, `modelgen-*` output.
-- **Output:** `context/mockup/` — `MOCKUP.html` index page, `mockup-manifest.json`, Vite +
-  React project files, layout components, vendored shadcn/ui components, role-specific page
-  components, and built `dist/` + shared hub at `<root>/mockup/`.
-
-### `specgen-*` — Technical Specification Generators
-
-All specgens share the same contract: **Invoke** `/specgen-<variant> <application> <version>
-[module:<m>]`; **Prerequisites** `PRD.md` + `modelgen-*` output (+ `mockgen-*` output for
-UI-bearing stacks); **Output** `context/specification/` — root `SPECIFICATION.md` + one
-self-contained `SPEC.md` per module (or per command for CLI stacks), with complete code
-samples and traceability tables. **Pick exactly ONE variant, matching the application's
-technology stack** (declared in `CLAUDE.md` / PRD Architecture Principle):
-
-| Skill | Pick when the application is… |
-|-------|-------------------------------|
-| `specgen-spring-jpa-jtehtmx` | Spring Boot 3 server-rendered web app (JTE + Tailwind + Alpine.js + htmx, Spring Modulith; optional Keycloak, RabbitMQ, Quartz/Batch, i18n) |
-| `specgen-spring-jpa-restapi` | Spring Boot 3 REST API (Spring Modulith; optional Keycloak resource server / JWT, RabbitMQ, Quartz/Batch) |
-| `specgen-laravel-eloquent-bladehtmx` | Laravel 12 server-rendered web app (Blade + Tailwind + Alpine.js + htmx, nwidart modules; optional Keycloak/Breeze, RabbitMQ, scheduling, i18n) |
-| `specgen-react-mui` | React 19 SPA with Material UI v6 (TypeScript 5, Vite 6, React Router 7, TanStack Query 5, Zustand 5, RHF 7, Zod 3; optional Keycloak/OIDC, WebSocket, i18n, MUI X grids/charts) |
-| `specgen-react-tailwind` | React 19 SPA with Tailwind CSS v3 + Headless UI v2 + Heroicons (same data stack as react-mui, no component framework; optional TanStack Table, Recharts, react-day-picker, Tiptap, reporting) |
-| `specgen-flutter-riverpod` | Flutter 3 mobile app (Dart 3, Riverpod 2, Hive 2, Dio 5, go_router 14, Firebase Messaging, freezed/json_serializable; optional Keycloak PKCE, WebSocket, i18n) |
-| `specgen-ts-cli` | Distributable Node.js CLI **tool** (TypeScript 5, Commander 12, tsup, Zod, chalk/ora; optional prompts, conf/cosmiconfig, SQLite, execa, got, @yao-pkg/pkg binaries) — terminal-only, no web UI |
-| `specgen-node-cli-web` | Self-hosted **web application distributed as a global npm CLI** — installed `npm i -g`, started `<app> start`, opened at `http://IP:PORT`. Single Node 22 process: Hono 4 API + embedded pre-built React 19/Vite 6 SPA (Tailwind v4, shadcn/ui), Drizzle + SQLite, hand-rolled scrypt sessions with first-run admin + forced password change, tsup, Biome, Vitest + Playwright with built-binary smoke test |
-| `specgen-sdk-java` | Java SDK **library** wrapping a remote REST API — Maven Multi-Release fat JAR, JDK 8 baseline + JDK 11+ overlay, OkHttp as sole runtime dependency |
-
-> **`specgen-ts-cli` vs `specgen-node-cli-web`:** if the deliverable is a terminal tool with
-> commands and flags → `specgen-ts-cli`. If the deliverable is a browser-accessed web app that
-> merely *installs and starts* via a CLI → `specgen-node-cli-web`.
-
-⚠️ `specgen-nextjs-react-tailwind` (Next.js 15 App Router) is documented but **not yet
-implemented** (empty stub — no SKILL.md). Do not invoke; fall back to `specgen-react-tailwind`
-+ a REST API specgen, or ask the user.
-
-### `testgen-functional`
-- **Invoke:** `/testgen-functional <application> <version> [module:<m>]`
-- **What it does:** Generates a Playwright E2E test plan and per-module test specifications as
-  Markdown blueprints (scenarios, data seeding, cleanup) — NOT actual test code.
-- **Use when:** "generate test plan/spec", after specgen completes. Last artifact step.
-- **Prerequisites:** `PRD.md`, `modelgen-*`, `mockgen-*`, `specgen-*` outputs.
-- **Output:** `context/test/` — `TEST_PLAN.md`/`TEST_PLAN.mmd` + per-module `TEST_SPEC.md`.
-
----
-
-## Phase 3 — Infrastructure
-
-### `util-preparek8senv`
-- **Invoke:** `/util-preparek8senv [environment]`
-- **What it does:** Generates StatefulSet-based K8s manifests for ALL 3rd party supporting
-  applications (databases, queues, caches, SSO, gateways) for one target environment, and
-  creates/updates `ENVIRONMENT.md` with per-environment configs and credentials. Output goes
-  directly into the gitignored `environment/` folder.
-- **Use when:** "prepare k8s environment", "setup infrastructure" — run BEFORE application
-  development so backing services exist.
-- **Prerequisites:** `CLAUDE.md`, `DEVTOOL.md`.
-- **Output:** `ENVIRONMENT.md` (created/updated with per-environment configs and credentials)
-  and `environment/` — `namespace.yaml` plus one StatefulSet-based manifest per 3rd party
-  application (PVC, ConfigMap, Secret, headless Service, NodePort Service).
-
----
-
-## Phase 4 — Development
-
-### `conductor-feature-develop` (orchestrator)
-- **Invoke:** `/conductor-feature-develop <application> [version:<v>] [module:<m>]`
-- **What it does:** Implements the full application module-by-module (code + Playwright E2E
-  tests) using all generated artifacts, tracking progress in `IMPLEMENTATION_MASTER.md` and
-  per-module `IMPLEMENTATION_MODULE.md`. Auto-starts a Ralph Loop for cross-session
-  continuity; invokes `tracegen-matrix` and `depgen-k8s` at the end.
-- **Use when:** "implement the application", "start development", "develop from specs",
-  "resume implementation".
-- **Prerequisites:** all `conductor-feature-prepare` outputs (model/, mockup/,
-  specification/, test/).
-- **Output:** application source code organized by module; `context/develop/` tracking files
-  (`IMPLEMENTATION_MASTER.md` with overall status/execution order/pre-implementation
-  checklist, and per-module `IMPLEMENTATION_MODULE.md` with resource tables, implementation
-  checklists, user-story/NFR completion checklists and timestamped logs); Playwright E2E test
-  suite per module; then via auto-invoked sub-skills: `context/TRACEABILITY.md`, `Dockerfile`
-  and `k8s/` manifests.
-
-### `tracegen-matrix`
-- **Invoke:** `/tracegen-matrix <application> [version] [module]`
-- **What it does:** Links every PRD requirement ID and bug code to the implementing source
-  code and writes `context/TRACEABILITY.md`. Resolves from in-source CO2 comments
-  (`Implements:` / `NFR:` / `Constraints:` / `Bug fixes:`) with a name-based fallback;
-  optional codebase-memory MCP enrichment (works fully without it).
-- **Use when:** "generate/update traceability", "link requirements to code" — usually invoked
-  automatically as the final step of `conductor-feature-develop` and `conductor-defect`.
-- **Prerequisites:** `PRD.md`, `specification/*/SPEC.md`, application source code.
-- **Output:** `context/TRACEABILITY.md` — per-application matrix mapping every requirement ID
-  and bug code to the implementing source files.
-
-### `depgen-k8s`
-- **Invoke:** `/depgen-k8s <application> [environment]`
-- **What it does:** Generates a production-ready multi-stage Dockerfile (application root) and
-  Kubernetes manifests in the gitignored `<app_folder>/k8s/` for one target environment.
-  Auto-detects the stack (Spring Boot / Laravel / Node.js) from project files. Only CUSTOM
-  applications — never 3rd party services (those are `util-preparek8senv`'s job).
-- **Use when:** "containerize", "create a Dockerfile", "generate k8s manifests", "deploy this
-  app" — auto-invoked by `conductor-feature-develop` after all modules complete.
-- **Prerequisites:** `SPECIFICATION.md`, `CLAUDE.md`, application source code.
-- **Output:** `<app_folder>/Dockerfile` (multi-stage, production-ready) and
-  `<app_folder>/k8s/` — namespace, ConfigMap, Secret, Deployment, Service and Ingress YAML
-  files with env-var mapping and health/readiness probes (gitignored, per-machine).
-
----
-
-## Phase 5 — Bug Fixing
-
-### `conductor-defect` (orchestrator)
-- **Invoke:** `/conductor-defect <application> [version:<v>] [module:<m>]`
-- **What it does:** Fixes bugs from `<app_folder>/context/BUG.md` one at a time: tags untagged
-  bugs, creates `BUG_MASTER.md`, then per bug — reproduce with Playwright, write
-  `BUG_TEST_SPEC.md`, plan (`BUG_FIX_PLAN.md`), fix, verify, and sync affected artifacts
-  (mockups, specs, models, PRD). Manages Ralph Loop internally; runs `tracegen-matrix` at the
-  end.
-- **Use when:** "fix bugs", "bug fix session", "resolve bugs from BUG.md",
-  "resume bug fixing".
-- **Prerequisites:** `BUG.md`, all `conductor-feature-prepare` outputs.
-- **Output:** fixed source code; tagged `BUG.md` (`[BUG-XXX]`); `context/bug/BUG_MASTER.md`
-  tracking file (statuses: NEW, IN_PROGRESS, FIXED, CANNOT_REPRODUCE, HIGH_IMPACT); per-bug
-  folder `context/bug/<module>/<BUG-XXX>/` with `reproduce.spec.ts`,
-  `screenshot_reproduce.png`, `BUG_TEST_SPEC.md`, `BUG_FIX_PLAN.md`, `screenshot_fixed.png`;
-  synced artifacts (mockups, specs, models, PRD) and an updated `context/TRACEABILITY.md`.
-
----
-
-## Quick Decision Table
-
-| User intent sounds like… | Invoke |
-|---|---|
-| "start a new project / I have an app idea" | `util-projectinit` (then user runs `/brainstorm-loop`) |
-| "sync folders / CLAUDE.md changed / scaffold PRDs" | `util-projectsync` |
-| "check my requirements / review user stories" | `util-usanalyzer` |
-| "tag the new PRD items / add requirement IDs" | `util-ustagger` |
-| "prepare everything for development" | `conductor-feature-prepare` |
-| "design the data model / ERD" | `modelgen-relational` or `modelgen-nosql` (by datastore) |
-| "generate mockups / UI screens" | `mockgen-tailwind` or `mockgen-shadcn` (by stack) |
-| "write the technical spec" | the ONE `specgen-*` matching the stack (see table) |
-| "generate the test plan" | `testgen-functional` |
-| "set up databases/queues in k8s" | `util-preparek8senv` |
-| "build/implement the app" | `conductor-feature-develop` |
-| "link requirements to code" | `tracegen-matrix` |
-| "dockerize / deploy the app" | `depgen-k8s` |
-| "fix the reported bugs" | `conductor-defect` |
+# CO2 Skills Catalog — Agent Reference
+
+> **Audience:** AI agents. This document tells you WHICH skill to invoke WHEN in the
+> Compound Context (CO2) workflow. Every skill reads its inputs from the project's context
+> files (`CLAUDE.md`, `<app_folder>/context/PRD.md`, etc.) — invoke with the application
+> name and version; do not ask the user for information the context files already contain.
+
+## Workflow Order
+
+Skills belong to phases and generally must run in this order per application:
+
+```
+0. Bootstrap        util-projectinit → (user fills session) → /brainstorm-loop → util-projectsync
+1. PRD clean-up     util-usanalyzer → util-ustagger          (util-updprd for requirement changes)
+2. Artifacts        modelgen-* → mockgen-* → specgen-* → testgen-functional
+                    (or all four via conductor-feature-prepare)
+3. Infrastructure   util-preparek8senv → util-plancicd → util-gencicdscript  (before development)
+4. Development      conductor-feature-develop → tracegen-matrix (auto) → depgen-k8s (auto)
+5. Bug fixing       conductor-defect → tracegen-matrix (auto)
+```
+
+## Artifact Map — who produces what
+
+```
+<project_root>/
+├── CLAUDE.md                          ← /brainstorm-loop (Phase A), annotated by util-projectsync
+├── DEVTOOL.md                         ← per-developer (manual)
+├── ENVIRONMENT.md                     ← util-preparek8senv
+├── <topic>.brainstorm.md              ← util-projectinit (session doc, iterated by /brainstorm-loop)
+├── brainstorm-protocol.md             ← util-projectinit (copied)
+├── co2-context-generation-guide.md    ← util-projectinit (copied)
+├── environment/                       ← util-preparek8senv (K8s manifests for 3rd party apps; gitignored)
+├── cicd/                              ← util-plancicd (CICD_PLAN.md), util-gencicdscript (app/; gitignored)
+│   ├── CICD_PLAN.md                   ← util-plancicd
+│   ├── CICD_GENERATION.md             ← util-gencicdscript
+│   └── app/                           ← util-gencicdscript (server.js, cicd.config.json; gitignored)
+└── <app_folder>/
+    ├── CHANGELOG.md                   ← appended by every skill (version gate)
+    ├── Dockerfile                     ← depgen-k8s
+    ├── k8s/                           ← depgen-k8s (app manifests; gitignored)
+    ├── (source code)                  ← conductor-feature-develop / conductor-defect
+    └── context/
+        ├── PRD.md                     ← /brainstorm-loop (Phase B), scaffolded by util-projectsync,
+        │                                tagged by util-ustagger, annotated by util-usanalyzer
+        ├── BUG.md                     ← util-projectsync scaffold; user reports; tagged by conductor-defect
+        ├── TRACEABILITY.md            ← tracegen-matrix
+        ├── model/                     ← modelgen-relational / modelgen-nosql
+        ├── mockup/                    ← mockgen-tailwind / mockgen-shadcn (assets + manifest;
+        │                                served by the shared Mockup Hub at <root>/mockup)
+        ├── specification/             ← specgen-* (one variant)
+        ├── test/                      ← testgen-functional
+        ├── prepare/                   ← conductor-feature-prepare (PREPARE_MASTER.md tracking)
+        ├── develop/                   ← conductor-feature-develop (tracking files)
+        └── bug/                       ← conductor-defect (per-bug tracking files)
+```
+
+**Universal conventions (apply to almost every skill):**
+
+- **Invocation shape:** `/skill-name <application> <version> [module:<name>]`. The application
+  name resolves to a root-level app folder (leading `<number>_` prefix stripped,
+  case-insensitive, snake/kebab/title case all match).
+- **Version gate:** skills refuse to run for a version lower than the highest version recorded
+  in `<app_folder>/CHANGELOG.md`, and append a row there on success.
+- **Version filtering:** only PRD items tagged `[vX.Y.Z]` <= the requested version are included;
+  strikethrough (`~~…~~`) items are deprecated and excluded.
+- **Traceability:** PRD item IDs (e.g., `[USHM00003]`, `[NFRHM0012]`) must be carried through
+  into every generated artifact.
+
+---
+
+## Phase 0 — Project Bootstrap
+
+### `util-projectinit`
+- **Invoke:** `/util-projectinit "<application idea or topic>"`
+- **What it does:** Sets up a file-based, turn-based **brainstorming session** in the project
+  folder: generates `<topic>.brainstorm.md` from the appdev template (seeded with the idea),
+  copies `brainstorm-protocol.md` and `co2-context-generation-guide.md` to the project root,
+  and ensures the `/brainstorm-loop` command is installed. It does NOT generate project context
+  directly and it NEVER starts the loop itself — it instructs the user to fill in the session
+  document and manually run `/brainstorm-loop`.
+- **Use when:** the user wants to start/init/bootstrap a NEW project, or brainstorm an
+  application idea into CO2 context. First skill of the workflow.
+- **Do NOT use when:** the project already has a `CLAUDE.md` and the user wants to evolve it
+  (use `util-projectsync` or `util-updprd`).
+- **Prerequisites:** an application idea (even one paragraph).
+- **Output:** `<topic>.brainstorm.md` (session document), `brainstorm-protocol.md`,
+  `co2-context-generation-guide.md` at the project root, and
+  `.claude/commands/brainstorm-loop.md` when the plugin command is not available — plus a
+  hand-off instruction block. Non-destructive — never overwrites existing files.
+
+### `/brainstorm-loop` (plugin command, not a skill)
+- **Invoke:** `/brainstorm-loop [scan-root] [max-watch-rounds]` — **run manually by the user**,
+  never auto-started by a skill.
+- **What it does:** In-session watch loop over `*.brainstorm.md` session documents. Each round
+  the agent drafts the CO2 context tree (Phase A: root `CLAUDE.md`; Phase B: one `PRD.md` per
+  application) per `co2-context-generation-guide.md`, appends questions, and waits for the
+  human to answer and flip a status row. Token-efficient: 60-second file polling, acts only on
+  status flips.
+- **Output:** root `CLAUDE.md` + `<app_folder>/context/PRD.md` per application (at the session's
+  destination), plus a `.brainstorm-loop-status.md` dashboard.
+
+### `util-projectsync`
+- **Invoke:** `/util-projectsync` (no arguments — reads everything from `CLAUDE.md`)
+- **What it does:** Synchronizes project folder structure with `CLAUDE.md`: validates
+  dependencies (circular, missing, logical) and orphaned services, creates missing application
+  folders, scaffolds `PRD.md`/`BUG.md` from templates, adds missing module sections, inserts
+  `[TODO]` annotations into `CLAUDE.md` for validation failures.
+- **Use when:** after the brainstorm closes, or any time `CLAUDE.md` applications/modules
+  changed and folders/PRDs must catch up ("sync project", "scaffold project folders",
+  "validate dependencies").
+- **Prerequisites:** `CLAUDE.md`.
+- **Output:** missing `<app_folder>/` folders, scaffolded `<app_folder>/context/PRD.md` and
+  `BUG.md`, missing module sections added to existing files, `[TODO]` annotations in
+  `CLAUDE.md` for validation failures, and a sync/validation summary report.
+
+---
+
+## Phase 1 — PRD Clean-Up
+
+### `util-usanalyzer`
+- **Invoke:** `/util-usanalyzer <application>`
+- **What it does:** Analyzes `PRD.md` for quality issues — incomplete sentences, broken
+  references, cross-module inconsistencies, contradictions, duplicate roles, process-flow
+  coverage gaps — and adds inline `[TODO]` annotations for each issue.
+- **Use when:** the user asks to validate/review/audit user stories or requirements quality,
+  or before tagging a freshly edited PRD.
+- **Prerequisites:** `PRD.md`.
+- **Output:** inline `[TODO]` annotations written into `PRD.md` at each issue, plus a summary
+  report of all issues found with improvement suggestions.
+
+### `util-ustagger`
+- **Invoke:** `/util-ustagger <application> <version>`
+- **What it does:** Tags every untagged top-level item in `PRD.md` (User Stories, NFRs,
+  Constraints, References, Tests) with a unique 9-character ID code and validates that no
+  duplicate tags exist.
+- **Use when:** new PRD items need IDs ("tag user stories", "add IDs to requirements",
+  "validate tags"). Run after any manual PRD edit and before artifact generation.
+- **Prerequisites:** `PRD.md`.
+- **Output:** updated `PRD.md` with every item tagged (e.g., `[USHM00003]`, `[NFRHM0012]`,
+  `[CONHM0009]`, `[REFHM0003]`), plus a duplicate-tag validation report.
+
+### `util-updprd`
+- **Invoke:** `/util-updprd "<free-form requirement change>" [application:<app>] [module:<module>] [version:<vX.Y.Z>] [--auto-approve]`
+  (or `/util-updprd <path/to/prd_updates.md>` for a PRD-Wizard hand-off).
+- **What it does:** Applies a free-form requirement change across all applications' `PRD.md`
+  files — decomposes the prompt into discrete changes, determines which applications, modules
+  and subsections (User Story, NFR, Constraint, Reference, Test) are impacted, and decides per
+  item whether to ADD, CANCEL or MODIFY it. Auto-classifies the change as major/minor/patch (or
+  accepts an explicit `version:` override, gated to be ≥ each impacted application's current
+  highest version) and layers the new/updated items under a NEW version tag on top of the
+  existing versions (prior versions immutable). Tags new items via `util-ustagger` and appends
+  a `CHANGELOG.md` entry per impacted application. Presents an impact plan for human
+  confirmation before writing (skippable with `--auto-approve`). Always stops after updating
+  the PRDs — never chains into any conductor or generator skill.
+- **Use when:** the user describes a new or changed requirement in plain language ("update
+  PRD", "add requirement", "add user story", "cancel user story", "the client wants…"), or the
+  PRD Wizard hands off a `prd_updates` markdown.
+- **Prerequisites:** `PRD.md`, `CLAUDE.md`.
+- **Output:** updated `PRD.md` per impacted application (new version tag, ADD/CANCEL/MODIFY
+  items), IDs assigned via `util-ustagger`, a `CHANGELOG.md` entry per impacted application,
+  plus an impact-analysis plan and completion summary.
+
+---
+
+## Phase 2 — Context Artifact Generation
+
+> Run the four steps individually below, or all at once via `conductor-feature-prepare`.
+
+### `conductor-feature-prepare` (orchestrator)
+- **Invoke:** `/conductor-feature-prepare <application> [version:<v>] [module:<m>]`
+- **What it does:** Runs `util-ustagger` → `modelgen-*` → `mockgen-*` → `specgen-*` →
+  `testgen-functional` in sequence, auto-selecting the right variant per the application's
+  technology stack, tracking progress in `PREPARE_MASTER.md` (read first on resume to skip
+  already-completed steps/versions). Multiple versions are processed sequentially in ascending
+  semver order. Manages its own Ralph Loop internally for cross-session continuity.
+- **Use when:** "prepare artifacts", "generate context", "prepare for development",
+  "resume preparation".
+- **Prerequisites:** `PRD.md`, `CLAUDE.md`.
+- **Output:** the complete `context/` artifact tree — `model/`, `mockup/`, `specification/`
+  and `test/` (each as described under its sub-skill below) — plus `CHANGELOG.md` entries: each
+  sub-skill appends its own row, and on completion the orchestrator appends an umbrella
+  `conductor-feature-prepare` summary row per version (one on top of the sub-skill rows,
+  matching `conductor-feature-develop` / `conductor-defect`). Also writes the
+  `context/prepare/PREPARE_MASTER.md` progress tracker (inferred config, per-version ×
+  per-artifact status) for cross-session resumption.
+
+### `modelgen-relational`
+- **Invoke:** `/modelgen-relational <application> <version> [module:<m>]`
+- **What it does:** Extracts relational (SQL) entity models from user stories using DDD —
+  ERD diagrams (Mermaid) + per-module model documentation. Also handles "update/upgrade the
+  model" for incremental evolution.
+- **Use when:** the app's datastore is a relational DB (MySQL, PostgreSQL, SQLite …).
+- **Output:** `context/model/` — `MODEL.md` index + per-module `model.md` / `erd.mermaid`.
+
+### `modelgen-nosql`
+- **Invoke:** `/modelgen-nosql <application> <version> [module:<m>]`
+- **What it does:** Extracts NoSQL document models (embed-vs-reference analysis, Mermaid class
+  diagrams, JSON schema examples per collection). Database-agnostic (MongoDB, Couchbase,
+  DynamoDB, Firestore, CosmosDB).
+- **Use when:** the app's datastore is document-oriented. **Not** for relational schemas —
+  use `modelgen-relational`.
+- **Output:** `context/model/` — `MODEL.md` index + per-module `model.md` (embed/reference
+  decisions), Mermaid class diagram, and `schemas.json` JSON schema examples per collection.
+
+### `mockgen-tailwind`
+- **Invoke:** `/mockgen-tailwind <application> <version> [module:<m>]`
+- **What it does:** Generates HTML mockup screens (Alpine.js + HTMX assets, admin
+  dashboard layout, organized by user role) for human designer review. All mockups are
+  served by the single shared **Mockup Hub** at `<root>/mockup` — a zero-dependency Node
+  server (created/upgraded automatically) with a landing page listing every application
+  and role (unclickable until ready) and a configurable port (`PORT` env /
+  `mockup.config.json`).
+- **Use when:** mockups are needed and the target stack is server-rendered or plain HTML;
+  default mockup generator.
+- **Prerequisites:** `PRD.md`, `modelgen-*` output.
+- **Output:** `context/mockup/` — `MOCKUP.html` index, `mockup-manifest.json`, partials,
+  role folders (assets only; no per-app server) + shared hub at `<root>/mockup/`.
+
+### `mockgen-shadcn`
+- **Invoke:** `/mockgen-shadcn <application> <version> [module:<m>]`
+- **What it does:** Generates React + shadcn/ui mockup screens (Vite + React 19 + TypeScript +
+  React Router v7, admin dashboard layout, organized by user role) with
+  `base`/`basename` = `/{app_slug}/`, builds them (`npm run build`), and serves the `dist/`
+  output through the same shared **Mockup Hub** at `<root>/mockup` (Vite dev server remains
+  for design iteration only).
+- **Use when:** the target application is React/shadcn-based (pairs naturally with
+  `specgen-nextjs-react-tailwind` / `specgen-node-cli-web`).
+- **Prerequisites:** `PRD.md`, `modelgen-*` output.
+- **Output:** `context/mockup/` — `MOCKUP.html` index page, `mockup-manifest.json`, Vite +
+  React project files, layout components, vendored shadcn/ui components, role-specific page
+  components, and built `dist/` + shared hub at `<root>/mockup/`.
+
+### `specgen-*` — Technical Specification Generators
+
+All specgens share the same contract: **Invoke** `/specgen-<variant> <application> <version>
+[module:<m>]`; **Prerequisites** `PRD.md` + `modelgen-*` output (+ `mockgen-*` output for
+UI-bearing stacks); **Output** `context/specification/` — root `SPECIFICATION.md` + one
+self-contained `SPEC.md` per module (or per command for CLI stacks), with complete code
+samples and traceability tables. **Pick exactly ONE variant, matching the application's
+technology stack** (declared in `CLAUDE.md` / PRD Architecture Principle):
+
+| Skill | Pick when the application is… |
+|-------|-------------------------------|
+| `specgen-spring-jpa-jtehtmx` | Spring Boot 3 server-rendered web app (JTE + Tailwind + Alpine.js + htmx, Spring Modulith; optional Keycloak, RabbitMQ, Quartz/Batch, i18n) |
+| `specgen-spring-jpa-restapi` | Spring Boot 3 REST API (Spring Modulith; optional Keycloak resource server / JWT, RabbitMQ, Quartz/Batch) |
+| `specgen-laravel-eloquent-bladehtmx` | Laravel 12 server-rendered web app (Blade + Tailwind + Alpine.js + htmx, nwidart modules; optional Keycloak/Breeze, RabbitMQ, scheduling, i18n) |
+| `specgen-react-mui` | React 19 SPA with Material UI v6 (TypeScript 5, Vite 6, React Router 7, TanStack Query 5, Zustand 5, RHF 7, Zod 3; optional Keycloak/OIDC, WebSocket, i18n, MUI X grids/charts) |
+| `specgen-react-tailwind` | React 19 SPA with Tailwind CSS v3 + Headless UI v2 + Heroicons (same data stack as react-mui, no component framework; optional TanStack Table, Recharts, react-day-picker, Tiptap, reporting) |
+| `specgen-flutter-riverpod` | Flutter 3 mobile app (Dart 3, Riverpod 2, Hive 2, Dio 5, go_router 14, Firebase Messaging, freezed/json_serializable; optional Keycloak PKCE, WebSocket, i18n) |
+| `specgen-ts-cli` | Distributable Node.js CLI **tool** (TypeScript 5, Commander 12, tsup, Zod, chalk/ora; optional prompts, conf/cosmiconfig, SQLite, execa, got, @yao-pkg/pkg binaries) — terminal-only, no web UI |
+| `specgen-node-cli-web` | Self-hosted **web application distributed as a global npm CLI** — installed `npm i -g`, started `<app> start`, opened at `http://IP:PORT`. Single Node 22 process: Hono 4 API + embedded pre-built React 19/Vite 6 SPA (Tailwind v4, shadcn/ui), Drizzle + SQLite, hand-rolled scrypt sessions with first-run admin + forced password change, tsup, Biome, Vitest + Playwright with built-binary smoke test |
+| `specgen-sdk-java` | Java SDK **library** wrapping a remote REST API — Maven Multi-Release fat JAR, JDK 8 baseline + JDK 11+ overlay, OkHttp as sole runtime dependency |
+
+> **`specgen-ts-cli` vs `specgen-node-cli-web`:** if the deliverable is a terminal tool with
+> commands and flags → `specgen-ts-cli`. If the deliverable is a browser-accessed web app that
+> merely *installs and starts* via a CLI → `specgen-node-cli-web`.
+
+⚠️ `specgen-nextjs-react-tailwind` (Next.js 15 App Router) is documented but **not yet
+implemented** (empty stub — no SKILL.md). Do not invoke; fall back to `specgen-react-tailwind`
++ a REST API specgen, or ask the user.
+
+### `testgen-functional`
+- **Invoke:** `/testgen-functional <application> <version> [module:<m>]`
+- **What it does:** Generates a Playwright E2E test plan and per-module test specifications as
+  Markdown blueprints (scenarios, data seeding, cleanup) — NOT actual test code.
+- **Use when:** "generate test plan/spec", after specgen completes. Last artifact step.
+- **Prerequisites:** `PRD.md`, `modelgen-*`, `mockgen-*`, `specgen-*` outputs.
+- **Output:** `context/test/` — `TEST_PLAN.md`/`TEST_PLAN.mmd` + per-module `TEST_SPEC.md`.
+
+---
+
+## Phase 3 — Infrastructure
+
+### `util-preparek8senv`
+- **Invoke:** `/util-preparek8senv [environment]`
+- **What it does:** Generates StatefulSet-based K8s manifests for ALL 3rd party supporting
+  applications (databases, queues, caches, SSO, gateways) for one target environment, and
+  creates/updates `ENVIRONMENT.md` with per-environment configs and credentials. Output goes
+  directly into the gitignored `environment/` folder.
+- **Use when:** "prepare k8s environment", "setup infrastructure" — run BEFORE application
+  development so backing services exist.
+- **Prerequisites:** `CLAUDE.md`, `DEVTOOL.md`.
+- **Output:** `ENVIRONMENT.md` (created/updated with per-environment configs and credentials)
+  and `environment/` — `namespace.yaml` plus one StatefulSet-based manifest per 3rd party
+  application (PVC, ConfigMap, Secret, headless Service, NodePort Service).
+
+### `util-plancicd`
+- **Invoke:** `/util-plancicd <path-to-plan-request-md>`
+- **What it does:** Infers a local-deployment plan for every custom application by reading
+  `ENVIRONMENT.md`, `DEVTOOL.md`, `CLAUDE.md` (`# Custom Applications`, `# Port Allocation`)
+  and each application's `SPECIFICATION.md`, then decides per application the deployment
+  method (container vs. bare process), build/start/stop commands (e.g. Spring Boot jar vs
+  Docker image), a deploy method + command (`none` / `web-server` copy / `docker` run /
+  `kubernetes` apply — only when the environment names a target), port and health-check URL,
+  plus a port for the generated CI/CD app itself. Writes `cicd/CICD_PLAN.md` with a top-level
+  `**Status**: IN PROGRESS` header flipped to `COMPLETED` when done, for Compound Context
+  Studio's watcher and human review. Never generates the CI/CD app itself — that is
+  `util-gencicdscript`, gated on the studio stamping an `**Approved**:` line onto the plan.
+- **Use when:** the studio's "Plan deployment" action requests a CI/CD plan ("plan cicd",
+  "plan deployment", "cicd plan", "infer deployment").
+- **Prerequisites:** `ENVIRONMENT.md`, `DEVTOOL.md`, `CLAUDE.md`, each application's
+  `SPECIFICATION.md`, and the studio-generated plan-request markdown.
+- **Output:** `cicd/CICD_PLAN.md` — per-application deployment decisions table plus rationale,
+  `**Status**: IN PROGRESS` → `COMPLETED`. Hands back to the human for review/approval in the
+  studio.
+
+### `util-gencicdscript`
+- **Invoke:** `/util-gencicdscript cicd/CICD_PLAN.md`
+- **What it does:** Generates the self-contained, zero-npm-dependency CI/CD build/run/deploy
+  app (`cicd/app/` — `server.js` + `cicd.config.json`) from an APPROVED `cicd/CICD_PLAN.md`.
+  Refuses to run unless the plan has `**Status**: COMPLETED` AND an `**Approved**:` line
+  (stamped by the studio's Approve button). The generated app is a bare, iframe-embeddable,
+  light-themed page with one nav tab per application: a controls bar (status badge, clickable
+  app URL opening a new tab, Build / Start / Stop / Deploy buttons running the plan's
+  commands) above that application's log streamed live over a built-in zero-dependency
+  WebSocket (bounded tail, backpressure-dropped slow clients, trimmed client buffer). Controls
+  are disabled for an application that never completed a conductor-develop run (checked via
+  the studio's `/api/cicd-guard` endpoint); health/port probing marks already-running apps —
+  even ones started elsewhere. No version selector: only the latest built applications are
+  operated. Writes `cicd/CICD_GENERATION.md` with `**Status**: IN PROGRESS` → `COMPLETED` for
+  the studio watcher. Idempotent — re-running regenerates `cicd/app/` in place.
+- **Use when:** the plan is approved and the studio requests the CI/CD app be generated
+  ("generate cicd", "gen cicd script", "generate ci/cd app", "cicd app").
+- **Prerequisites:** an approved `cicd/CICD_PLAN.md` (`**Status**: COMPLETED` plus an
+  `**Approved**:` line).
+- **Output:** `cicd/app/server.js`, `cicd/app/cicd.config.json`, and the
+  `cicd/CICD_GENERATION.md` tracking file; appends `cicd/logs/` and `cicd/state.json` to
+  `.gitignore`.
+
+---
+
+## Phase 4 — Development
+
+### `conductor-feature-develop` (orchestrator)
+- **Invoke:** `/conductor-feature-develop <application> [version:<v>] [module:<m>]`
+- **What it does:** Implements the full application module-by-module (code + Playwright E2E
+  tests) using all generated artifacts, tracking progress in `IMPLEMENTATION_MASTER.md` and
+  per-module `IMPLEMENTATION_MODULE.md`. Auto-starts a Ralph Loop for cross-session
+  continuity; invokes `tracegen-matrix` and `depgen-k8s` at the end.
+- **Use when:** "implement the application", "start development", "develop from specs",
+  "resume implementation".
+- **Prerequisites:** all `conductor-feature-prepare` outputs (model/, mockup/,
+  specification/, test/).
+- **Output:** application source code organized by module; `context/develop/` tracking files
+  (`IMPLEMENTATION_MASTER.md` with overall status/execution order/pre-implementation
+  checklist, and per-module `IMPLEMENTATION_MODULE.md` with resource tables, implementation
+  checklists, user-story/NFR completion checklists and timestamped logs); Playwright E2E test
+  suite per module; then via auto-invoked sub-skills: `context/TRACEABILITY.md`, `Dockerfile`
+  and `k8s/` manifests.
+
+### `tracegen-matrix`
+- **Invoke:** `/tracegen-matrix <application> [version] [module]`
+- **What it does:** Links every PRD requirement ID and bug code to the implementing source
+  code and writes `context/TRACEABILITY.md`. Resolves from in-source CO2 comments
+  (`Implements:` / `NFR:` / `Constraints:` / `Bug fixes:`) with a name-based fallback;
+  optional codebase-memory MCP enrichment (works fully without it).
+- **Use when:** "generate/update traceability", "link requirements to code" — usually invoked
+  automatically as the final step of `conductor-feature-develop` and `conductor-defect`.
+- **Prerequisites:** `PRD.md`, `specification/*/SPEC.md`, application source code.
+- **Output:** `context/TRACEABILITY.md` — per-application matrix mapping every requirement ID
+  and bug code to the implementing source files.
+
+### `depgen-k8s`
+- **Invoke:** `/depgen-k8s <application> [environment]`
+- **What it does:** Generates a production-ready multi-stage Dockerfile (application root) and
+  Kubernetes manifests in the gitignored `<app_folder>/k8s/` for one target environment.
+  Auto-detects the stack (Spring Boot / Laravel / Node.js) from project files. Only CUSTOM
+  applications — never 3rd party services (those are `util-preparek8senv`'s job).
+- **Use when:** "containerize", "create a Dockerfile", "generate k8s manifests", "deploy this
+  app" — auto-invoked by `conductor-feature-develop` after all modules complete.
+- **Prerequisites:** `SPECIFICATION.md`, `CLAUDE.md`, application source code.
+- **Output:** `<app_folder>/Dockerfile` (multi-stage, production-ready) and
+  `<app_folder>/k8s/` — namespace, ConfigMap, Secret, Deployment, Service and Ingress YAML
+  files with env-var mapping and health/readiness probes (gitignored, per-machine).
+
+---
+
+## Phase 5 — Bug Fixing
+
+### `conductor-defect` (orchestrator)
+- **Invoke:** `/conductor-defect <application> [version:<v>] [module:<m>]`
+- **What it does:** Fixes bugs from `<app_folder>/context/BUG.md` one at a time: tags untagged
+  bugs, creates `BUG_MASTER.md`, then per bug — reproduce with Playwright, write
+  `BUG_TEST_SPEC.md`, plan (`BUG_FIX_PLAN.md`), fix, verify, and sync affected artifacts
+  (mockups, specs, models, PRD). Manages Ralph Loop internally; runs `tracegen-matrix` at the
+  end.
+- **Use when:** "fix bugs", "bug fix session", "resolve bugs from BUG.md",
+  "resume bug fixing".
+- **Prerequisites:** `BUG.md`, all `conductor-feature-prepare` outputs.
+- **Output:** fixed source code; tagged `BUG.md` (`[BUG-XXX]`); `context/bug/BUG_MASTER.md`
+  tracking file (statuses: NEW, IN_PROGRESS, FIXED, CANNOT_REPRODUCE, HIGH_IMPACT); per-bug
+  folder `context/bug/<module>/<BUG-XXX>/` with `reproduce.spec.ts`,
+  `screenshot_reproduce.png`, `BUG_TEST_SPEC.md`, `BUG_FIX_PLAN.md`, `screenshot_fixed.png`;
+  synced artifacts (mockups, specs, models, PRD) and an updated `context/TRACEABILITY.md`.
+
+---
+
+## Quick Decision Table
+
+| User intent sounds like… | Invoke |
+|---|---|
+| "start a new project / I have an app idea" | `util-projectinit` (then user runs `/brainstorm-loop`) |
+| "sync folders / CLAUDE.md changed / scaffold PRDs" | `util-projectsync` |
+| "check my requirements / review user stories" | `util-usanalyzer` |
+| "tag the new PRD items / add requirement IDs" | `util-ustagger` |
+| "prepare everything for development" | `conductor-feature-prepare` |
+| "design the data model / ERD" | `modelgen-relational` or `modelgen-nosql` (by datastore) |
+| "generate mockups / UI screens" | `mockgen-tailwind` or `mockgen-shadcn` (by stack) |
+| "write the technical spec" | the ONE `specgen-*` matching the stack (see table) |
+| "generate the test plan" | `testgen-functional` |
+| "set up databases/queues in k8s" | `util-preparek8senv` |
+| "plan deployment / plan cicd" | `util-plancicd` |
+| "generate ci/cd app / generate ci/cd script" | `util-gencicdscript` |
+| "build/implement the app" | `conductor-feature-develop` |
+| "link requirements to code" | `tracegen-matrix` |
+| "dockerize / deploy the app" | `depgen-k8s` |
+| "fix the reported bugs" | `conductor-defect` |