@rashidee/co2 1.3.11 → 1.3.13

package/package.json

@@ -1,41 +1,41 @@
-{
-  "name": "@rashidee/co2",
-  "version": "1.3.11",
-  "description": "Compound Context Studio — self-hosted team context authoring for CO2 projects",
-  "type": "module",
-  "license": "MIT",
-  "publishConfig": {
-    "access": "public"
-  },
-  "engines": {
-    "node": ">=22"
-  },
-  "bin": {
-    "co2": "dist/index.js"
-  },
-  "files": [
-    "dist",
-    "static",
-    "drizzle",
-    "plugin"
-  ],
-  "scripts": {
-    "build": "tsup && node ../../scripts/copy-migrations.mjs && node ../../scripts/copy-web.mjs && node ../../scripts/copy-plugin.mjs"
-  },
-  "dependencies": {
-    "better-sqlite3": "^12.2.0",
-    "node-pty": "^1.0.0"
-  },
-  "devDependencies": {
-    "@co2-cli/core": "workspace:*",
-    "@co2-cli/server": "workspace:*",
-    "@hono/node-server": "^1.13.0",
-    "@hono/zod-validator": "^0.4.1",
-    "commander": "^12.1.0",
-    "drizzle-orm": "^0.36.0",
-    "hono": "^4.6.0",
-    "picocolors": "^1.1.0",
-    "tsup": "^8.3.0",
-    "zod": "^3.23.8"
-  }
-}
+{
+  "name": "@rashidee/co2",
+  "version": "1.3.13",
+  "description": "Compound Context Studio — self-hosted team context authoring for CO2 projects",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "co2": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "static",
+    "drizzle",
+    "plugin"
+  ],
+  "scripts": {
+    "build": "tsup && node ../../scripts/copy-migrations.mjs && node ../../scripts/copy-web.mjs && node ../../scripts/copy-plugin.mjs"
+  },
+  "dependencies": {
+    "better-sqlite3": "^12.2.0",
+    "node-pty": "^1.0.0"
+  },
+  "devDependencies": {
+    "@co2-cli/core": "workspace:*",
+    "@co2-cli/server": "workspace:*",
+    "@hono/node-server": "^1.13.0",
+    "@hono/zod-validator": "^0.4.1",
+    "commander": "^12.1.0",
+    "drizzle-orm": "^0.36.0",
+    "hono": "^4.6.0",
+    "picocolors": "^1.1.0",
+    "tsup": "^8.3.0",
+    "zod": "^3.23.8"
+  }
+}

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