@rashidee/co2 1.3.12 → 1.3.13

package/dist/index.js

@@ -6809,7 +6809,7 @@ var {
 // package.json
 var package_default = {
   name: "@rashidee/co2",
-  version: "1.3.12",
+  version: "1.3.13",
   description: "Compound Context Studio \u2014 self-hosted team context authoring for CO2 projects",
   type: "module",
   license: "MIT",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rashidee/co2",
-  "version": "1.3.12",
+  "version": "1.3.13",
   "description": "Compound Context Studio — self-hosted team context authoring for CO2 projects",
   "type": "module",
   "license": "MIT",

package/plugin/.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "co2-skills",
       "source": "./",
       "description": "Compound Context Skills — generates data models, HTML mockups, technical specifications, test specifications, and orchestrates full-stack development from Agile user stories.",
-      "version": "1.6.0",
+      "version": "1.7.0",
       "author": {
         "name": "Rashidee M.Rashid"
       },

package/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "co2-skills",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Compound Context Skills — an opinionated context engineering methodology for AI-driven software development. Generates data models, HTML mockups, technical specifications, test specifications, and orchestrates full-stack development from Agile user stories.",
   "author": {
     "name": "Rashidee M.Rashid"

package/plugin/README.md

@@ -229,6 +229,7 @@ Example skill invocation for technical specification generation:
 /specgen-flutter-riverpod <app_name> ## For generating Flutter 3 mobile application technical specification with Riverpod, Hive, Dio, go_router and Firebase Messaging.
 /specgen-ts-cli <app_name> ## For generating Node.js CLI application technical specification with TypeScript, Commander.js and tsup.
 /specgen-node-cli-web <app_name> ## For generating self-hosted Node.js web application technical specification distributed as a global npm CLI — Hono, embedded React SPA, Drizzle + SQLite, hand-rolled sessions and tsup.
+/specgen-custom <app_name> ## For generating a technical specification for an arbitrary user-defined stack from a custom stack spec markdown (also the automatic fallback when no specgen matches).
 ~~~
 
 - Input:
@@ -556,7 +557,7 @@ We welcome contributions from the community! Here are some ways you can contribu
 
 ## Specification Generator Skills (`specgen-*`)
 
-This is the **highest impact area** for contribution. The CO2 workflow is designed to be technology-agnostic, but each `specgen-*` skill targets a specific technology stack. We currently support:
+This is the **highest impact area** for contribution. The CO2 workflow is designed to be technology-agnostic, but each `specgen-*` skill targets a specific technology stack. Stacks not covered by a dedicated variant are served by `specgen-custom` (driven by a user-authored stack spec markdown), but a contributed stack-specific specgen always produces a deeper specification and remains preferred. We currently support:
 
 | Skill | Technology Stack |
 |-------|-----------------|
@@ -570,6 +571,7 @@ This is the **highest impact area** for contribution. The CO2 workflow is design
 | `specgen-ts-cli` | Node.js CLI + TypeScript + Commander.js + tsup + pkg |
 | `specgen-node-cli-web` | Self-hosted Node.js web app as a global npm CLI — Node 22 + commander 12 + Hono 4 + embedded React 19/Vite 6 SPA + Tailwind CSS v4 + shadcn/ui + Drizzle ORM + SQLite + hand-rolled scrypt sessions + tsup + Biome + Vitest + Playwright |
 | `specgen-sdk-java` | Java SDK library — Maven Multi-Release fat JAR (JDK 8 baseline + JDK 11+ overlay) + OkHttp |
+| `specgen-custom` | Any stack described by a user-authored custom stack spec markdown (authoring template: `skills/specgen-custom/references/stack-doc-template.md`) — an explicit declaration overrides the built-in variants; also the automatic fallback when no variant matches |
 
 We are looking for contributors to create new `specgen-*` skills for other technology stacks, such as:
 

package/plugin/SKILLS.md

@@ -237,7 +237,9 @@ All specgens share the same contract: **Invoke** `/specgen-<variant> <applicatio
 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):
+technology stack** (declared in `CLAUDE.md` / PRD Architecture Principle). A custom stack
+spec declared as ``Stack per custom stack spec at `<path>` `` always wins over the built-in
+variants, and `specgen-custom` is the fallback when nothing matches:
 
 | Skill | Pick when the application is… |
 |-------|-------------------------------|
@@ -250,6 +252,7 @@ technology stack** (declared in `CLAUDE.md` / PRD Architecture Principle):
 | `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-custom` | ANY other stack — driven by a user-authored custom stack spec markdown (declared in PRD.md/CLAUDE.md as ``Stack per custom stack spec at `<path>` ``, authoring template in `references/stack-doc-template.md`). An explicit declaration OVERRIDES the built-in variants; also the automatic fallback (with `[TODO]`-annotated defaults) when no variant matches |
 
 > **`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
@@ -406,7 +409,7 @@ implemented** (empty stub — no SKILL.md). Do not invoke; fall back to `specgen
 | "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) |
+| "write the technical spec" | the ONE `specgen-*` matching the stack (see table); a declared custom stack spec → `specgen-custom`, which is also the fallback when nothing matches |
 | "generate the test plan" | `testgen-functional` |
 | "set up databases/queues in k8s" | `util-preparek8senv` |
 | "plan deployment / plan cicd" | `util-plancicd` |

package/plugin/skills/conductor-feature-develop/SKILL.md

@@ -389,6 +389,11 @@ files to understand what has already been completed.
             version (e.g., `${APP_VERSION:1.0.4}`)
           - **config/app.php** (Laravel): Update the default in `env('APP_VERSION', '1.0.0')`
             to the new version
+          - **Custom / other stacks** (SPECIFICATION.md generated by `specgen-custom`): Update
+            the manifest file/field and environment variable named in SPECIFICATION.md's
+            **Application Version Configuration** subsection. If the spec names none, update
+            the project's primary manifest and add a `[TODO]` in IMPLEMENTATION_MASTER.md
+            noting the gap.
           The version displayed in the application footer (or API info endpoint) MUST reflect
           the new version after this update.
        3. Proceed to Phase 3 (Implementation) for the affected modules.
@@ -496,6 +501,8 @@ subdirectory. Instead:
   then move ALL files (including dotfiles) from that temp directory up to `<source-code-path>/`,
   then remove the empty temp directory. This avoids overwriting the existing `context/` folder.
 - For Spring Boot: Same approach — scaffold into a temp dir, then move files up.
+- For any other stack whose scaffolding tool creates a nested project directory: same
+  temp-dir-then-move approach.
 - NEVER use the project slug/name as the target directory if it would create a nested folder.
 
 **Scaffolding Checklist** (adapt to the technology stack from SPECIFICATION.md):
@@ -511,6 +518,9 @@ subdirectory. Instead:
    - **Laravel**: Set `version` in `composer.json` and `APP_VERSION` in `.env`
    - **React / Node.js**: Set `version` in `package.json` and `VITE_APP_VERSION` in
      `.env.development` (or `APP_VERSION` in `.env` for Node.js backends)
+   - **Custom / other stacks**: Use the manifest file/field and environment variable named in
+     SPECIFICATION.md's **Application Version Configuration** subsection (a spec generated by
+     `specgen-custom` always names them)
    - The version in the manifest MUST match the version in the environment variable
    - For multi-version processing, this version will be updated during each version increment
      in the Phase 0 resume check
@@ -1057,6 +1067,9 @@ Extracted from IMPLEMENTATION_MASTER.md execution order and module details.>
 - For **Spring Boot** apps: use Maven/Gradle commands, `src/main/java` paths, `application.yml` config
 - For **Laravel** apps: use Composer/Artisan commands, `app/` paths, `.env` config
 - For **REST API** apps: omit view/template sections, focus on API endpoints and Swagger/OpenAPI docs
+- For **custom stacks** (SPECIFICATION.md generated by `specgen-custom`): every command, path
+  and config reference comes from SPECIFICATION.md's Build, Run & Packaging and Project
+  Structure sections — never from stack assumptions
 - Include only sections that are relevant to the actual specification — do NOT add sections for
   features that are not part of the spec (e.g., skip messaging section if no messaging is configured)
 

package/plugin/skills/conductor-feature-prepare/SKILL.md

@@ -319,8 +319,10 @@ record the result for use throughout the version loop:
   decisions and resolved-file-path propagation to mockgen-* and specgen-*. No additional action
   needed; Step 1.5 is the canonical handler.
 - **`# Architecture Principle`** — Already consumed by Step 1.3 (Infer Database Type) and
-  Step 1.7 (Infer Technology Stack) as the **primary signal** for routing decisions. Sub-skills
-  (modelgen-*, specgen-*) read it directly from PRD.md.
+  Step 1.7 (Infer Technology Stack) as the **primary signal** for routing decisions. It may
+  also declare a custom stack spec file (``Stack per custom stack spec at `<path>` `` or a
+  markdown link to the stack file), which Step 1.7 treats as the **overriding** signal and
+  routes to `specgen-custom`. Sub-skills (modelgen-*, specgen-*) read it directly from PRD.md.
 - **`# High Level Process Flow`** — **Detect presence here** so all downstream skills are aware:
   1. Check PRD.md for a `# High Level Process Flow` section. If present, record:
      - The list of named flows (e.g., "Country submission flow", "Worker registration flow")
@@ -384,6 +386,10 @@ tracker that this skill — and any resumed Ralph Loop iteration — reads to kn
 | Spec Generator | TBD | - |
 
 > Filled in by the inference steps (1.3, 1.5, 1.7) as the pipeline runs.
+> When a custom stack spec is used, record Technology Stack = "Custom (per `<path>`)" and
+> Spec Generator = "specgen-custom (explicit)" or "specgen-custom (fallback)"; the Source
+> column names the declaration (`PRD.md # Architecture Principle (custom stack spec)`,
+> `CLAUDE.md entry (custom stack spec)`) or `fallback (no specgen matched)`.
 
 ---
 
@@ -514,31 +520,53 @@ applies to all items regardless of version.
 
 #### Step 1.7: Infer Technology Stack
 
-1. **Check PRD.md `# Architecture Principle` section first** (primary signal):
+1. **Check for an explicit custom stack spec declaration first** (overrides all other signals):
+   - In PRD.md `# Architecture Principle`: a statement matching ``Stack per custom stack spec at `<path>` ``
+     or a markdown link to a custom stack spec markdown file (e.g., `[STACK.md](reference/STACK.md)`)
+   - Else in the application's CLAUDE.md entry (under `# Custom Applications`): the same
+     ``Stack per custom stack spec at `<path>` `` convention
+   - If found: resolve the path (relative to PRD.md first, then to the project root) and verify
+     the file exists — if it does NOT exist, **STOP** and report the dangling declaration to the
+     user. If it exists, record **Technology Stack = Custom (per `<path>`)** with the resolved
+     path and **skip items 2–3** — the stack doc is authoritative.
+2. **Check PRD.md `# Architecture Principle` section** (primary signal):
    - If Architecture Principle explicitly mentions a framework (e.g., "Spring Boot", "Laravel"), use it
    - If it mentions a view engine (e.g., "JTE", "Blade"), use it
    - If it mentions frontend tooling (e.g., "HTMX", "Alpine.js", "Vite"), use it
    - If it mentions architectural style (e.g., "monolithic", "REST API"), use it to disambiguate specgen variant
-2. **Fallback to CLAUDE.md** (if Architecture Principle is absent or incomplete):
+3. **Fallback to CLAUDE.md** (if Architecture Principle is absent or incomplete):
    - Read application details from CLAUDE.md (already in context)
    - Identify the technology stack:
      - Framework (Laravel, Spring Boot, etc.)
      - ORM (Eloquent, JPA/Hibernate, etc.)
      - View engine (Blade, JTE, etc.)
      - Frontend enhancement (HTMX, Alpine.js, etc.)
-3. Record the inferred technology stack for the next step
+4. Record the inferred technology stack (or the resolved custom stack doc path) for the next step
 
 #### Step 1.8: Generate Technical Specification
 
 1. **Check if artifacts exist**: List files in `<app_folder>/context/specification/`
    - If `.md` files already exist AND this is NOT a version increment → **SKIP** this step
    - If this IS a version increment, **proceed** to re-invoke the skill with version/module args
-2. Determine the appropriate specification generator:
-   - Check available skills matching `specgen-*` pattern
-   - For Laravel + Eloquent + Blade + HTMX → `Skill(skill: "co2-skills:specgen-laravel-eloquent-bladehtmx", args: "<app_folder> [version:<version>] [module:<module>]")`
-   - For Spring Boot + JPA + JTE + HTMX → `Skill(skill: "co2-skills:specgen-spring-jpa-jtehtmx", args: "<app_folder> [version:<version>] [module:<module>]")`
-   - For a self-hosted Node.js web app distributed as a global npm CLI (Hono + embedded React SPA + SQLite) → `Skill(skill: "co2-skills:specgen-node-cli-web", args: "<app_folder> [version:<version>] [module:<module>]")`
-   - Match the skill name against the inferred technology stack components
+2. Determine the appropriate specification generator, **in this priority order**:
+   - **a. Explicit custom stack spec (from Step 1.7)** — if Step 1.7 resolved a custom stack doc,
+     use `specgen-custom` regardless of whether a built-in specgen would also match the stack:
+     `Skill(skill: "co2-skills:specgen-custom", args: "<app_folder> [version:<version>] [module:<module>] stack:<resolved-stack-doc-path>")`
+   - **b. Built-in specgen match** — otherwise, check available skills matching the `specgen-*`
+     pattern (excluding `specgen-custom`) and match against the inferred technology stack.
+     Only route to a variant that actually exists as an invokable skill (has a SKILL.md):
+     - For Laravel + Eloquent + Blade + HTMX → `Skill(skill: "co2-skills:specgen-laravel-eloquent-bladehtmx", args: "<app_folder> [version:<version>] [module:<module>]")`
+     - For Spring Boot + JPA + JTE + HTMX → `Skill(skill: "co2-skills:specgen-spring-jpa-jtehtmx", args: "<app_folder> [version:<version>] [module:<module>]")`
+     - For a self-hosted Node.js web app distributed as a global npm CLI (Hono + embedded React SPA + SQLite) → `Skill(skill: "co2-skills:specgen-node-cli-web", args: "<app_folder> [version:<version>] [module:<module>]")`
+     - Match the skill name against the inferred technology stack components
+   - **c. No match — fallback to specgen-custom** — if NO built-in specgen matches the inferred
+     stack, do NOT stop and do NOT force-fit the closest variant. Invoke:
+     `Skill(skill: "co2-skills:specgen-custom", args: "<app_folder> [version:<version>] [module:<module>] stack-desc:\"<inferred stack summary from Step 1.7>\"")`
+     specgen-custom will first attempt to auto-discover a stack doc at its well-known paths
+     (`<app_folder>/context/reference/STACK.md`, `<app_folder>/context/STACK.md`,
+     `<root>/shared_context/STACK.md`); if none exists it generates from the inferred stack
+     description, annotating every assumption with `[TODO]`. Surface the applied defaults to
+     the user in the run summary.
 3. Wait for the skill to complete. The output will be specification files in `<app_folder>/context/specification/`
 
 #### Step 1.9: Generate Test Specification

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.

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}}