@rashidee/co2 1.3.11 → 1.3.13

package/plugin/skills/specgen-custom/SKILL.md

@@ -0,0 +1,442 @@
+---
+name: specgen-custom
+model: claude-opus-4-8
+effort: high
+description: >
+  Generate a detailed technical specification for an application whose technology stack
+  is described by a USER-AUTHORED custom stack spec markdown file — instead of one of the
+  built-in stack-specific specgen-* variants. Reads the stack doc (declared in PRD.md
+  `# Architecture Principle` or the application's CLAUDE.md entry as "Stack per custom
+  stack spec at `<path>`", passed via stack:<path>, or found at well-known paths) and
+  produces the SAME artifact shape as every other specgen: context/specification/
+  SPECIFICATION.md plus one self-contained per-module SPEC.md, with complete code samples
+  in the stack doc's declared languages/frameworks and full traceability tables. Also
+  serves as the FALLBACK generator when no built-in specgen-* matches the inferred
+  technology stack (invoked with stack-desc:"<inferred stack>"), synthesizing a stack
+  definition and annotating every assumption with [TODO]. Standardized input: application
+  name (mandatory), version (mandatory), module (optional), stack:<path> (optional),
+  stack-desc:"<text>" (optional).
+  Use this skill whenever the user asks to create a spec for a custom, bespoke,
+  unsupported or "bring your own" technology stack, says "spec from my stack doc",
+  "use my custom stack spec", "no specgen matches my stack", or when a custom stack spec
+  file is declared in PRD.md/CLAUDE.md. Do NOT use this skill when a built-in specgen-*
+  variant matches the application's stack AND no custom stack spec is declared — the
+  stack-specific variant always produces a deeper specification.
+---
+
+# Custom Stack Application Specification Generator
+
+This skill generates a comprehensive specification document (Markdown) for an application
+whose technology stack is **defined by the user**, not by a built-in `specgen-*` variant.
+The spec is intended to be followed by a developer or coding agent (normally
+`conductor-feature-develop`) to produce a fully functional application — without the
+develop phase ever having to re-infer or guess the stack.
+
+The specification does NOT generate code. It produces a detailed technical document
+describing every layer of the application — project layout, build pipeline, data layer,
+service composition, testing — so that implementation becomes a mechanical exercise.
+
+## Operating Modes
+
+The skill runs in one of two modes, resolved during Stack Doc Resolution below:
+
+- **Mode 1 — Stack-doc-driven (primary).** A custom stack spec markdown authored by the
+  user is resolved. That document is the **authoritative stack definition**: where the
+  coding agent's general stack habits or preferences conflict with the stack doc, **the
+  stack doc wins**. Technologies listed in the stack doc's `# Exclusions` section must
+  never appear in the spec.
+- **Mode 2 — Inferred-stack fallback.** No stack doc exists; the invoker (normally
+  `conductor-feature-prepare` Step 1.8, after no built-in `specgen-*` matched) passes the
+  inferred stack as `stack-desc:"<free text>"`. The skill synthesizes a stack definition
+  from that description plus CLAUDE.md, records every assumption in the Determination
+  Summary, and annotates each assumption inline in the generated spec with
+  `[TODO: confirm — defaulted by specgen-custom]`.
+
+## Stack Definition Source
+
+Unlike the stack-specific `specgen-*` variants, this skill has **no fixed technology
+table and no opinionated version pins**. The Technology Stack table in the generated
+`SPECIFICATION.md` is rendered from the stack doc (Mode 1) or the synthesized definition
+(Mode 2) — never from this skill's own preferences.
+
+- A library named in the stack doc without a version gets "latest stable as of the
+  generation date" plus a `[TODO: pin version]` marker in the spec.
+- Never silently substitute a technology the stack doc names or excludes. If a stack doc
+  choice is unworkable (e.g., two mutually incompatible libraries), flag the conflict to
+  the user instead of quietly resolving it.
+
+## When the Skill Triggers
+
+Generate the spec when the user (or the prepare conductor) provides an **application
+name** and **version** that corresponds to one of the custom applications defined in
+`CLAUDE.md`, and the application's stack is custom (declared stack doc) or unmatched by
+any built-in `specgen-*` variant.
+
+Example invocations:
+- `/specgen-custom my_app v1.0.0`
+- `/specgen-custom my_app v1.0.0 stack:shared_context/STACK.md`
+- `/specgen-custom my_app v1.0.0 module:Inventory`
+- `/specgen-custom my_app v1.0.0 stack-desc:"Go 1.23 + Gin + PostgreSQL server-rendered app"`
+
+## Version Gate
+
+Before starting any work, resolve the application folder first (see Input Resolution below), then check `CHANGELOG.md` in the application folder (`<app_folder>/CHANGELOG.md`):
+
+1. If `<app_folder>/CHANGELOG.md` does not exist, skip this check (first-ever execution for this application).
+2. If `<app_folder>/CHANGELOG.md` exists, scan all `## vX.Y.Z` headings and determine the **highest version** using semantic versioning comparison.
+3. Compare the requested version against the highest version:
+   - If requested version **>=** highest version: proceed normally.
+   - If requested version **<** highest version: **STOP immediately**. Print: `"Version {requested} is lower than the current application version {highest} recorded in <app_folder>/CHANGELOG.md. Execution rejected."` Do NOT proceed with any work.
+
+## Input Resolution
+
+This skill uses standardized input resolution. Provide:
+
+| Argument | Required | Example | Description |
+|----------|----------|---------|-------------|
+| `<application>` | Yes | `my_app` | Application name to locate the context folder |
+| `<version>` | Yes | `v1.0.0` | Version to scope processing |
+| `module:<name>` | No | `module:Inventory` | Limit generation to a single module |
+| `stack:<path>` | No | `stack:shared_context/STACK.md` | Explicit path to the custom stack spec doc |
+| `stack-desc:<text>` | No | `stack-desc:"Go + Gin + PostgreSQL"` | Inferred-stack fallback description (Mode 2); used only when no stack doc resolves |
+
+### Application Folder Resolution
+
+The application name is matched against root-level application folders:
+1. Strip any leading `<number>_` prefix from folder names (e.g., `1_my_app` → `my_app`)
+2. Match case-insensitively against the provided application name
+3. Accept snake_case, kebab-case, or title-case input (all match the same folder)
+4. If no match found, list available applications and stop
+
+### Auto-Resolved Paths
+
+| File | Resolved Path |
+|------|---------------|
+| PRD.md | `<app_folder>/context/PRD.md` |
+| Module Models | `<app_folder>/context/model/` |
+| HTML Mockups | `<app_folder>/context/mockup/` |
+| Output (specification) | `<app_folder>/context/specification/` |
+
+### Version Filtering
+
+When a version is provided, only include user stories, NFRs, and constraints from versions
+<= the provided version. For example, if `v1.0.4` is specified:
+- Include items tagged `[v1.0.0]` through `[v1.0.4]`
+- Exclude items tagged `[v1.0.5]` or later
+- Version comparison uses semantic versioning order
+
+### Module Filtering
+
+When `module:<name>` is provided:
+- Only generate the `SPEC.md` for that specific module
+- Other existing module spec files remain untouched
+- `SPECIFICATION.md` (root) gets a partial update — only that module's entry in the TOC
+  is added or updated; all other TOC entries are preserved as-is
+
+## Stack Doc Resolution
+
+Resolve the custom stack spec document in this priority order (first hit wins):
+
+1. **`stack:<path>` argument** — resolve relative to the project root first, then
+   relative to `<app_folder>`. If the argument is given but the file does not exist,
+   **STOP** and report the dangling path.
+2. **PRD.md `# Architecture Principle` section** — a statement matching
+   ``Stack per custom stack spec at `<path>` `` or any markdown link to a stack spec
+   markdown file (e.g., `[STACK.md](reference/STACK.md)`). Resolve the path relative to
+   PRD.md, then relative to the project root.
+3. **CLAUDE.md application entry** — the same ``Stack per custom stack spec at `<path>` ``
+   convention in the application's description under `# Custom Applications` (this
+   mirrors the existing "Stack per the `specgen-<variant>` CO2 specgen variant" comment
+   convention used for built-in variants).
+4. **Well-known paths**, checked in order:
+   - `<app_folder>/context/reference/STACK.md`
+   - `<app_folder>/context/STACK.md`
+   - `<project_root>/shared_context/STACK.md`
+5. **Nothing found**:
+   - If `stack-desc:` was provided → enter **Mode 2** (inferred-stack fallback).
+   - Otherwise → **STOP** and print: `"No custom stack spec found for <application>.
+     Copy the template at co2-skills/skills/specgen-custom/references/stack-doc-template.md
+     into your project (e.g., <app_folder>/context/reference/STACK.md), fill every
+     REQUIRED section, and declare it in PRD.md under '# Architecture Principle' as:
+     Stack per custom stack spec at '<path>'."`
+
+Record the resolved mode and stack doc path — they are printed in the Determination
+Summary and written into the changelog row.
+
+## Stack Doc Validation (Mode 1)
+
+Validate the resolved stack doc against the template sections before generating anything.
+
+**Required sections — STOP if missing (never guess fundamentals):**
+
+| Section | Why it cannot be defaulted |
+|---------|---------------------------|
+| `# Languages & Frameworks` (with the primary framework named) | Defines the languages every code sample is written in |
+| `# Architecture Style` | Defines module boundaries and layering of the whole spec |
+| `# Project Layout` | Defines where every generated blueprint file lives |
+| `# Build, Run & Test Commands` | conductor-feature-develop executes these verbatim |
+
+If any required section is missing or empty, **STOP** and print a checklist of exactly
+which sections must be added to the stack doc. Guessing fundamentals defeats the purpose
+of a user-authored stack definition.
+
+**Recommended sections — apply a sensible default + inline `[TODO]` when missing:**
+
+| Section | Default when absent |
+|---------|--------------------|
+| Versions on individual libraries | Latest stable + `[TODO: pin version]` |
+| `# Testing Stack` | The stack's dominant unit-test framework + Playwright E2E (the CO2 `testgen-functional` / develop-phase convention) |
+| `# Packaging & Deployment` | Run from source + `[TODO: confirm packaging]`; primary manifest carries the app version |
+| `# Coding Conventions` | The language's community standard + `[TODO: confirm conventions]` |
+| `# Key Libraries` | Chosen per capability need, each choice marked `[TODO: confirm library]` |
+| `# Authentication & Security` | Derived from PRD.md auth stories; if PRD has none, no auth layer |
+| `# Data & Persistence` | Derived from the module model files + CLAUDE.md dependency list |
+
+Every applied default MUST appear in **both** places:
+1. The pre-generation **Determination Summary** (so the user can override), and
+2. An inline `[TODO: confirm — defaulted by specgen-custom]` annotation at the point of
+   use in the generated spec.
+
+In **Mode 2** the entire stack definition is synthesized (from `stack-desc:`, CLAUDE.md
+and the model/mockup artifacts), so every table row of the Technology Stack and every
+defaulted section carries the `[TODO]` convention above.
+
+## Gathering Input
+
+The specification is driven by **six input sources** read from the project's context
+files, plus the stack doc:
+
+### Input 1: Application Name (from CLAUDE.md)
+
+From CLAUDE.md (already loaded in context), locate the target application under the
+**Custom Applications** section. Extract:
+
+- **Application name**: The section heading
+- **Application description**: The description paragraph below the heading
+- **Dependencies**: The "Depends on" list — external services become integration points
+  in the spec, wired through the mechanisms the stack doc declares (HTTP client, queue
+  driver, etc.)
+
+### Input 2: User Stories (from PRD.md)
+
+Read `<app_folder>/context/PRD.md`. This file contains all user stories organized by
+module. Extract:
+
+- **System modules**: Modules under `# System Module` (e.g., Authentication, User
+  Management) — each becomes a module blueprint using the stack doc's auth approach.
+- **Business modules**: Modules under `# Business Module`. Each becomes a feature area in
+  the stack doc's project layout and a `<module>/SPEC.md`.
+- **Command/terminal-facing stories** (if the stack doc declares a CLI surface) map to
+  commands.
+
+**Important:** Items with strikethrough (`~~text~~`) are deprecated — do NOT include them
+as active requirements. List them in the "Removed / Replaced" subsection of the
+traceability table. Track the `[v1.0.x]` version tag for each item and carry it through
+to the generated specification's traceability section.
+
+### Input 3: Non-Functional Requirements (from PRD.md)
+
+Each module's `### Non Functional Requirement` section informs:
+
+- Pagination, filtering, and list-size decisions
+- Validation rules (character limits, formats) → the stack doc's validation mechanism
+- Performance constraints (response budgets, concurrency expectations)
+- Security posture layered onto the stack doc's `# Authentication & Security` section
+
+### Input 4: Constraints (from PRD.md)
+
+Each module's `### Constraint` section defines hard boundaries:
+
+- Status enum values → schema-level enums in the stack doc's persistence layer
+- Business rules → service-layer invariants with tests
+- Access control (e.g., "only ADMIN can ...") → guard configuration in the stack doc's
+  auth mechanism
+
+### Input 5: Module Model (from model/ folder)
+
+Read `<app_folder>/context/model/MODEL.md` first as the index, then the individual module
+model files (e.g., `model/inventory/model.md` + `schemas.json`). The module model maps to
+the **persistence layer defined in the stack doc** — ORM entities, schema definitions,
+migration files, or document models, whichever the stack doc names — field-for-field, not
+placeholder. If the model family (relational vs NoSQL) mismatches the stack doc's
+datastore, map the structures across and note every mapping decision in the spec.
+
+### Input 6: HTML Mockup Screens (from mockup/ folder)
+
+Read `<app_folder>/context/mockup/MOCKUP.html` first as the index, then the HTML files
+organized by role in subfolders. The mockups map to the **UI layer defined in the stack
+doc** — pages, templates, components, or views, whichever the stack doc names:
+
+- One UI blueprint per screen, using the stack doc's UI technology
+- Navigation structure and per-role menu items
+- Design tokens (colors, font, radius) extracted from mockup CSS
+
+**Role folders inform access control, NOT URL paths.** `mockup/admin/users.html` means
+the route requires the `admin` role — the URL is `/users`, never `/admin/users`.
+
+If the stack doc declares a **headless stack** (API-only, CLI, batch, library), skip this
+input with an explicit note in the Determination Summary — do not invent a UI layer.
+
+## PRD.md Extended Sections
+
+Before determining capabilities, check PRD.md for the following extended sections:
+
+### Architecture Principle Extraction
+
+If PRD.md contains an `# Architecture Principle` section, its statements are **constraints
+to honor** — unlike the stack-specific variants, this skill has no fixed architecture
+model to defend. Precedence rules:
+
+- **Technology choices**: the stack doc wins. If PRD.md names a technology the stack doc
+  excludes or contradicts, flag the contradiction to the user — do not silently pick one.
+- **Requirements and principles** (offline-first, audit logging, deployment posture):
+  PRD.md wins; the spec must realize them with the stack doc's technologies.
+
+### Design System Extraction
+
+If PRD.md contains a `# Design System` section with a file reference, resolve and read
+it, then map design tokens into the styling mechanism the stack doc declares. If absent,
+derive tokens from the mockup CSS.
+
+### High Level Process Flow Extraction
+
+If PRD.md contains a `# High Level Process Flow` section, flows inform service-method
+sequencing, status enums surfaced in list filters, and the E2E test scenario order.
+If absent, derive flow from user stories only.
+
+## Determination Summary
+
+After resolving the stack and analyzing all inputs, produce a determination summary
+before generating the spec. Present it to the user for confirmation:
+
+```
+Mode:               Stack-doc-driven (Mode 1)
+Stack Doc:          <app_folder>/context/reference/STACK.md
+Technology Stack:
+  <the rendered Layer | Technology | Version table>
+Applied Defaults:
+  - Testing Stack: <framework> + Playwright E2E   [TODO — stack doc section missing]
+  - <library> version: latest stable              [TODO — unpinned in stack doc]
+Capability Determination (from NFRs/stories, mapped to the stack doc's Key Libraries):
+  - DataGrid:    yes → <library from stack doc, or [TODO: choose library]>
+  - Charts:      no
+  - FileUpload:  yes → <mechanism>
+  - Jobs:        no
+Modules:            <list of modules to generate>
+UI Layer:           <UI technology, or "headless — mockup input skipped">
+```
+
+If the user disagrees with any determination, allow them to override before proceeding.
+When invoked non-interactively by `conductor-feature-prepare`, print the summary into the
+run output and proceed — the `[TODO]` markers in the spec remain the review surface.
+
+## Generating the Specification
+
+Once inputs are gathered and the stack is determined, generate the specification as a
+**multi-file output split by module**. Read the generic spec template at
+`references/spec-template.md` for the exact structure and content of each section — it is
+the authoritative guide.
+
+This skill ships **no stack pattern reference files**. Where a stack-specific variant
+would read `auth-patterns.md` or `server-patterns.md`, this skill derives patterns from:
+
+1. The stack doc's `# Coding Conventions`, `# Key Libraries` and
+   `# Authentication & Security` sections, and
+2. The framework's idiomatic community patterns for anything the stack doc leaves open
+   (each such derivation marked `[TODO: confirm — defaulted by specgen-custom]`).
+
+The specification is split into two categories:
+
+1. **Root `SPECIFICATION.md`** — TOC, project overview with the stack-doc-rendered
+   Technology Stack table, project structure & build configuration (including the
+   mandatory **Application Version Configuration** subsection), data & persistence,
+   application composition, authentication (if applicable), UI shell (UI stacks only),
+   testing strategy, and build/run/packaging.
+2. **Per-module `<module-name>/SPEC.md`** — Each module gets its own folder with a
+   self-contained blueprint spanning its data model, schemas/validation, service logic,
+   API/routes/commands, UI feature (if applicable), and tests.
+
+An auth/user-management module SPEC.md is generated **only when** PRD.md defines
+authentication/user stories or the stack doc declares an `# Authentication & Security`
+section — a custom stack may legitimately be a headless API or batch application with no
+auth surface. When generated, PRD story IDs merge into its traceability tables.
+
+**Important:** The generated spec must use **real application data** from the context
+files, not generic placeholders:
+
+- **Modules** use actual module names from PRD.md and MODEL.md
+- **Entities/schemas and types** match the model files field-for-field
+- **Routes/commands and services** map to actual user stories
+- **UI blueprints** map to actual mockup screens; URL paths are module-based, not
+  role-prefixed
+- **Validation** enforces the actual PRD constraints
+- **Version tags** on every user story ID, NFR ID, constraint ID, and mockup screen in
+  traceability tables (e.g., `USMA00003 [v1.0.2]`); **ALL traceability sub-tables MUST
+  include the `| Version |` column**
+- **Removed / Replaced** subsection lists deprecated items with the removing version,
+  replacement ID (if any), and reason
+
+### Output Structure
+
+```
+<app_folder>/context/specification/
+├── SPECIFICATION.md              ← Root: TOC + shared infrastructure per the stack doc
+├── <module-1>/
+│   └── SPEC.md                   ← Module blueprint (data + service + API/UI per the stack doc)
+├── <module-2>/
+│   └── SPEC.md
+└── ...                           ← One folder per module from PRD.md
+```
+
+**Sample code is mandatory.** Every component described in any spec file must include a
+complete, self-explanatory code sample **written in the stack doc's declared languages
+and frameworks**. The code must be continuous (no `// ...` gaps) and usable as a direct
+reference by a coding agent.
+
+## Changelog Append
+
+After all specification files are successfully generated, append an entry to `CHANGELOG.md` in the application folder (`<app_folder>/CHANGELOG.md`):
+
+1. Read `<app_folder>/CHANGELOG.md`. If it does not exist, create it with:
+   ```markdown
+   # Changelog
+
+   - This file tracks all skill executions by version for this application.
+   - The highest version recorded here is the current application version.
+   - Skills MUST NOT execute for a version lower than the highest version in this file.
+
+   ---
+   ```
+2. Search for a `## {version}` heading matching the current version.
+3. If the section **exists**: append a new row to its table.
+4. If the section **does not exist**: insert a new section after the `---` below the context header and before any existing `## vX.Y.Z` section (newest-first ordering), with a new table header and the first row.
+5. Row format: `| {YYYY-MM-DD} | {application_name} | specgen-custom | {module or "All"} | Generated technical specification from custom stack spec ({stack doc path, or "inferred stack (Mode 2)"}) |`
+6. **Never modify or delete existing rows.**
+
+## Constraints (Non-Negotiable)
+
+These constraints apply to the generated spec regardless of the stack. Where the coding
+agent's habits conflict with them, these constraints win.
+
+**The spec must be self-sufficient for `conductor-feature-develop`.** The develop
+conductor extracts exactly these from `SPECIFICATION.md` and must find them without
+consulting the stack doc:
+
+- The **Technology Stack table** with versions (from the stack doc)
+- The **Project Layout tree** with actual module names substituted
+- The **Build, Run & Test Commands** verbatim from the stack doc
+- An **Application Version Configuration** subsection naming the manifest file/field and
+  environment variable that carry the application version (from the stack doc's
+  `# Packaging & Deployment` section; if the stack doc names none, pick the stack's
+  primary manifest and mark it `[TODO: confirm version carrier]`), and how the running
+  application surfaces it (footer, `--version` flag, or info endpoint)
+
+**Stack doc supremacy.** Never substitute a technology the stack doc names, never
+introduce one it excludes. Conflicts are flagged to the user, not silently resolved.
+
+**`[TODO]` greppability.** Every assumption or default must be annotated with a marker
+that literally contains `[TODO` so a single grep surfaces the full review list.
+
+**Traceability completeness.** Every user story, NFR and constraint in scope for the
+requested version appears in exactly one module's traceability tables, with the
+`| Version |` column present in every sub-table.