@rashidee/co2 1.3.11 → 1.3.13

package/plugin/skills/specgen-custom/references/spec-template.md

@@ -0,0 +1,271 @@
+# Specification Template — Custom Stack Application
+
+This is the authoritative template for the generated specification. It is
+**stack-agnostic**: every technology-specific value is rendered from the resolved custom
+stack spec doc (Mode 1) or the synthesized stack definition (Mode 2) — see SKILL.md. The
+specification is split into **two types of files**:
+
+1. **`SPECIFICATION.md`** (root) — Table of Contents, project overview, project structure
+   & build configuration, data & persistence, application composition, authentication
+   (if applicable), UI shell (UI stacks only), testing, build/run/packaging. Generated
+   once per application.
+2. **`<module-name>/SPEC.md`** (per-module) — Self-contained module blueprint spanning
+   every layer the stack doc declares. Generated once per module from PRD.md.
+
+```
+specification/
+├── SPECIFICATION.md
+├── <module-1>/
+│   └── SPEC.md
+├── <module-2>/
+│   └── SPEC.md
+└── ...
+```
+
+Placeholders use `{{VARIABLE}}` syntax and must be replaced with actual values. Sections
+marked *[UI stacks only]* are omitted for headless stacks (API/CLI/batch/library);
+sections marked *[if applicable]* are included only when their capability exists.
+
+---
+
+# Part A: Root SPECIFICATION.md
+
+---
+
+## Table of Contents
+
+Generate a TOC with anchor links. Include a **Modules** section linking to each module's
+`SPEC.md`:
+
+```markdown
+## Table of Contents
+
+### Shared Infrastructure
+- [1. Project Overview](#1-project-overview)
+- [2. Project Structure & Build Configuration](#2-project-structure--build-configuration)
+- ...
+
+### Modules
+- [{{Module 1}}]({{module-1}}/SPEC.md)
+- ...
+```
+
+---
+
+## Section 1: Project Overview
+
+```
+# {{APPLICATION_NAME}} — Technical Specification
+
+## 1. Project Overview
+
+**Application Name**:  {{APPLICATION_NAME}}
+**Application Type**:  {{web | api | cli | mobile | batch | library — from the stack doc}}
+**Description**:       {{APP_DESCRIPTION}}
+**Versions Covered**:  v1.0.0 — v{{LATEST_VERSION}}
+**Stack Definition**:  {{path to the custom stack spec doc, or "inferred (Mode 2) — see [TODO] markers"}}
+
+### Architecture Model
+{{The Architecture Style from the stack doc, expanded into 1–2 paragraphs: process
+model, layering, module boundary rules, communication style. Cite compatible PRD.md
+Architecture Principle statements here.}}
+
+### Technology Stack
+{{Render the full Layer | Technology | Version table from the stack doc, plus any
+capability-driven additions from Key Libraries. Unpinned versions carry
+[TODO: pin version]; Mode 2 rows carry [TODO: confirm — defaulted by specgen-custom].}}
+
+### Capability Determination (Auto-Determined from PRD)
+{{The capability list from the Determination Summary — grids, charts, file upload,
+background jobs, integrations — each mapped to the stack doc's Key Libraries entry or
+marked [TODO: choose library].}}
+
+### User Roles   [if applicable]
+| Role | Source (mockup folder) | Capabilities summary |
+|------|------------------------|----------------------|
+| {{role}} | mockup/{{role}}/ | {{...}} |
+
+### Module Index
+| Module | Spec File | {{Persistence Units}} | {{Routes / Commands / Screens}} |
+|--------|-----------|----------------------|--------------------------------|
+| {{Module}} | [{{module}}/SPEC.md]({{module}}/SPEC.md) | {{tables/collections/files}} | {{...}} |
+```
+
+---
+
+## Section 2: Project Structure & Build Configuration
+
+- Render the **Project Layout tree from the stack doc** with actual module names from
+  PRD.md substituted into the module slots.
+- Complete, copy-pasteable **manifest and build configuration files** (whatever the stack
+  uses: `go.mod` + `Makefile`, `pyproject.toml`, `pom.xml`, `package.json`, ...), with
+  every dependency from the Technology Stack table at its pinned version.
+- State the **structural rules** from the stack doc's Coding Conventions (naming,
+  file-size limits, error handling, forbidden patterns). Defaulted conventions carry
+  `[TODO: confirm conventions]`.
+
+### Section 2a: Application Version Configuration (MANDATORY)
+
+This subsection is never omitted — `conductor-feature-develop` reads it on every version
+increment:
+
+- **Version carrier**: the manifest file + field ({{from the stack doc's Packaging &
+  Deployment section, e.g., "`version` in `pyproject.toml`"}}) MUST be set to the version
+  from skill invocation (highest, if multiple).
+- **Environment variable**: {{e.g., APP_VERSION}} mirrors the manifest value.
+- **Surfacing**: how the running application exposes the version — {{UI footer / CLI
+  `--version` flag / info endpoint, per application type}} — with a complete code sample.
+- If the stack doc named no version carrier, name the stack's primary manifest here and
+  mark the choice `[TODO: confirm version carrier]`.
+
+---
+
+## Section 3: Data & Persistence
+
+From the stack doc's Data & Persistence section and the module model files:
+
+- Datastore, access layer (ORM / query builder / driver) and connection management —
+  complete configuration sample
+- Migration tool and workflow (file location, generation command, when migrations run)
+- The **complete schema/entity definitions** for shared/system tables; per-module tables
+  live in each module's SPEC.md
+- If the model family (relational vs NoSQL) mismatches the stack doc's datastore, the
+  mapping decisions are documented here
+
+---
+
+## Section 4: Application Composition
+
+The application's entry point and composition root, in the stack doc's framework:
+
+- Entry point sample (main function / bootstrap / CLI program) — complete
+- Middleware/interceptor order or command wiring (request ID, logging, auth resolution,
+  guards, routes/commands)
+- Configuration loading (env vars / config file per the stack doc), validated at startup —
+  complete sample
+- Logging setup per the stack doc's logging library
+- Health/status surface ({{endpoint / command}}) used by tests and operations
+
+---
+
+## Section 5: Authentication & Security   [if applicable]
+
+Only when PRD.md defines auth stories or the stack doc declares Authentication & Security:
+
+- The auth mechanism from the stack doc (sessions / OIDC / API keys / ...) with complete
+  samples: credential verification, session/token issue + resolve + revoke, guards
+- Password/credential policy as validation schemas shared by UI and API
+- Role model and route/command guard configuration
+- Security invariants as explicit, testable statements (e.g., "cannot delete the last
+  admin"), each mapped to a PRD constraint ID where one exists
+
+---
+
+## Section 6: UI Shell   [UI stacks only]
+
+- The UI technology setup from the stack doc (SPA build config / template engine layout /
+  mobile navigation shell) — complete samples
+- Design tokens from the PRD Design System file or mockup CSS, mapped into the stack
+  doc's styling mechanism
+- Shared layout (navigation, topbar/sidebar, footer rendering `v{{VERSION}}` from the
+  version surface defined in Section 2a)
+- Route/screen registration pattern and role-guarded navigation derived from mockup role
+  folders
+
+---
+
+## Section 7: Testing Strategy
+
+From the stack doc's Testing Stack section (or the CO2 default: dominant unit framework +
+Playwright E2E, marked `[TODO]` when defaulted):
+
+- Unit/integration test setup — real persistence layer in tests where the stack allows
+  (in-memory / testcontainers), never a fully mocked data layer
+- The mandatory coverage list: every PRD constraint invariant, auth invariants (if
+  applicable), and one regression assertion per `### Bug` entry in PRD.md
+- E2E setup and the scenario ordering (from High Level Process Flow when present)
+
+---
+
+## Section 8: Build, Run & Packaging
+
+- The **verbatim command table** from the stack doc (install / build / run-dev /
+  run-prod / test / lint) — `conductor-feature-develop` executes these as-is
+- Packaging: artifact type and production run model from the stack doc's Packaging &
+  Deployment section
+- Configuration reference: every env var / config key, type, and default
+
+---
+
+# Part B: Per-Module `<module-name>/SPEC.md`
+
+Every module file is **self-contained** — a coding agent implements it independently
+after the shared infrastructure exists. Layer sections use the stack doc's layer names;
+the generic names below are placeholders to be renamed accordingly (e.g., "Routes" →
+"Handlers" for Gin, "Commands" for a CLI, "Screens" for mobile).
+
+## Template
+
+```
+# {{MODULE_NAME}} — Module Specification
+
+> Part of [{{APPLICATION_NAME}} Technical Specification](../SPECIFICATION.md).
+> Implement after the shared infrastructure (root spec sections 2–{{N}}) is in place.
+
+## 1. Traceability
+
+### User Stories
+| ID | Version | Summary | Implemented By |
+|----|---------|---------|----------------|
+| {{USXX00001}} | [v1.0.0] | {{summary}} | {{handler / service / screen file}} |
+
+### Non-Functional Requirements
+| ID | Version | Requirement | Technical Decision |
+|----|---------|-------------|--------------------|
+
+### Constraints
+| ID | Version | Constraint | Enforcement Point |
+|----|---------|------------|-------------------|
+
+### Mockup Screens   [UI stacks only]
+| Screen | Role | Route/Screen | Component/Template |
+|--------|------|--------------|--------------------|
+
+### Removed / Replaced
+| Removed ID | Removed In | Replaced By | Reason |
+|-----------|------------|-------------|--------|
+
+## 2. Data Model
+The module's persistence definitions (tables / collections / entities) in the stack
+doc's access layer — field-for-field from the model files, with relations and the
+migration file name. Complete sample.
+
+## 3. Schemas & Validation
+The module's input/output schemas in the stack doc's validation mechanism — entity,
+create/update inputs, query params — with derived types where the language supports it.
+Complete sample.
+
+## 4. Service / Business Logic
+The module's service layer — pure business logic taking the data access handle;
+business rules from PRD constraints as explicit invariants. No transport concerns.
+Complete sample.
+
+## 5. API / Routes / Commands
+The module's transport surface in the stack doc's framework — every route/command with
+validation, guards, and typed responses; wired into the composition root (Section 4 of
+the root spec). Complete sample. Surface table: {{method+path or command}}, guard,
+request schema, response, story IDs.
+
+## 6. UI Feature   [UI stacks only]
+- One UI blueprint per mockup screen in the stack doc's UI technology, matching the
+  mockup layout
+- Forms bound to the Section 3 schemas
+- Data access via the pattern defined in the root spec
+- Route/screen registration + role-guarded navigation entries
+Complete samples for every component.
+
+## 7. Tests
+- Unit/integration: service + transport tests per the root Testing Strategy; every
+  constraint invariant has a test; every `### Bug` entry has a regression assertion
+- E2E: the module's user-visible flows appended to the E2E suite   [UI stacks only]
+```

package/plugin/skills/specgen-custom/references/stack-doc-template.md

@@ -0,0 +1,154 @@
+<!--
+  CUSTOM STACK SPEC TEMPLATE (CO2 / specgen-custom)
+
+  Copy this file into your project — recommended location:
+    <app_folder>/context/reference/STACK.md
+  (also discovered at <app_folder>/context/STACK.md and <root>/shared_context/STACK.md)
+
+  Fill every REQUIRED section, then declare it in the application's PRD.md under
+  `# Architecture Principle` as:
+
+    Stack per custom stack spec at `context/reference/STACK.md`
+
+  (or equivalently in the application's CLAUDE.md entry under # Custom Applications).
+
+  RECOMMENDED sections may be omitted — specgen-custom will apply a sensible default and
+  mark it inline with [TODO: confirm — defaulted by specgen-custom] for your review.
+  Replace every {{placeholder}}. Delete these comment blocks when done.
+-->
+
+# Stack Overview
+
+<!-- REQUIRED context paragraph. State the application type explicitly:
+     web app / REST API / CLI / mobile app / batch job / library. -->
+
+{{One paragraph: what kind of application this stack builds, its runtime model
+(single process? client + server? serverless?), and how end users run or consume it.}}
+
+**Application type**: {{web | api | cli | mobile | batch | library}}
+
+# Languages & Frameworks
+
+<!-- REQUIRED. The primary framework MUST be named. Versions are strongly recommended —
+     unpinned entries get "latest stable" + [TODO: pin version] in the generated spec. -->
+
+| Layer | Technology | Version |
+|-------|------------|---------|
+| Language | {{e.g., Go}} | {{e.g., 1.23}} |
+| Framework | {{e.g., Gin}} | {{e.g., 1.10}} |
+| {{Frontend / Templates}} | {{e.g., templ + HTMX}} | {{...}} |
+| {{...}} | {{...}} | {{...}} |
+
+# Architecture Style
+
+<!-- REQUIRED. Defines the layering and module boundaries of the whole specification. -->
+
+- {{Monolith / modular monolith / microservices / hexagonal / layered MVC ...}}
+- {{Module boundary rule — e.g., "one package per business module, no cross-module
+  imports except through the service interfaces"}}
+- {{Communication style — e.g., "server-rendered pages + HTMX partials", "JSON REST",
+  "gRPC between services"}}
+
+# Project Layout
+
+<!-- REQUIRED. Annotated directory tree. specgen-custom substitutes actual module names
+     from PRD.md into this layout. -->
+
+```
+{{project-root/
+├── cmd/server/main.go          # entry point
+├── internal/
+│   ├── <module>/               # one package per business module
+│   │   ├── handler.go
+│   │   ├── service.go
+│   │   └── repo.go
+│   └── platform/               # shared: db, config, auth, logging
+├── migrations/                 # SQL migrations
+├── web/                        # templates + static assets
+└── Makefile}}
+```
+
+# Build, Run & Test Commands
+
+<!-- REQUIRED. conductor-feature-develop runs these verbatim — they must be exact. -->
+
+| Purpose | Command |
+|---------|---------|
+| Install dependencies | {{e.g., go mod download}} |
+| Build | {{e.g., go build -o bin/app ./cmd/server}} |
+| Run (dev) | {{e.g., go run ./cmd/server}} |
+| Run (prod) | {{e.g., ./bin/app}} |
+| Unit/integration tests | {{e.g., go test ./...}} |
+| E2E tests | {{e.g., npx playwright test}} |
+| Lint/format | {{e.g., golangci-lint run}} |
+
+# Data & Persistence
+
+<!-- RECOMMENDED. Default when absent: derived from the module model files and the
+     CLAUDE.md dependency list, marked [TODO]. -->
+
+- **Datastore**: {{e.g., PostgreSQL 16}}
+- **Access layer**: {{ORM / query builder / driver — e.g., sqlc, GORM, raw pgx}}
+- **Migrations**: {{tool + workflow — e.g., "golang-migrate; files in migrations/,
+  applied on deploy via make migrate"}}
+
+# Authentication & Security
+
+<!-- RECOMMENDED. Default when absent: derived from PRD.md auth stories; omitted
+     entirely for headless stacks with no auth stories. -->
+
+- **Mechanism**: {{e.g., session cookies / OIDC via Keycloak / API keys / none}}
+- **Session/token handling**: {{storage, expiry, revocation}}
+- **Role model**: {{roles and how routes/commands are guarded}}
+
+# Testing Stack
+
+<!-- RECOMMENDED. Default when absent: the stack's dominant unit-test framework +
+     Playwright E2E. NOTE: the CO2 pipeline (testgen-functional and the develop phase)
+     assumes Playwright E2E for UI-bearing applications — if your stack cannot run
+     Playwright (embedded, desktop-native, ...), declare the substitute here explicitly. -->
+
+- **Unit/integration**: {{framework + conventions}}
+- **E2E**: {{Playwright (CO2 default) or declared substitute}}
+- **Test data**: {{fixtures / in-memory DB / testcontainers ...}}
+
+# Key Libraries
+
+<!-- RECOMMENDED. Capabilities not covered here get a [TODO: choose library] in the spec
+     when PRD NFRs demand them (grids, charts, file upload, background jobs, HTTP...). -->
+
+| Purpose | Library | Version |
+|---------|---------|---------|
+| Validation | {{...}} | {{...}} |
+| Logging | {{...}} | {{...}} |
+| HTTP client | {{...}} | {{...}} |
+| {{...}} | {{...}} | {{...}} |
+
+# Coding Conventions
+
+<!-- RECOMMENDED. Default when absent: the language's community standard, marked [TODO]. -->
+
+- {{Naming conventions, file-size limits, error-handling style, typing strictness,
+  lint configuration, forbidden patterns}}
+
+# Packaging & Deployment
+
+<!-- RECOMMENDED but IMPORTANT: name the manifest file/field and environment variable
+     that carry the application version — conductor-feature-develop updates these on
+     every version increment and surfaces the version in the app footer/--version/info
+     endpoint. Default when absent: the stack's primary manifest + [TODO]. -->
+
+- **Artifact**: {{e.g., single static binary / jar / npm package / container image}}
+- **Version carrier**: {{manifest file + field, e.g., "version constant in
+  internal/platform/version.go" or "version field in pyproject.toml"}} and
+  {{env var, e.g., APP_VERSION}}
+- **Configuration**: {{how config is supplied — env vars / config file + naming
+  conventions}}
+
+# Exclusions
+
+<!-- OPTIONAL. Technologies that must NOT appear in the generated spec, even where the
+     coding agent would habitually reach for them. -->
+
+- {{e.g., No ORM — raw SQL via sqlc only}}
+- {{e.g., No Docker}}