@rashidee/co2 1.3.12 → 1.3.14

package/dist/index.js

@@ -6809,7 +6809,7 @@ var {
 // package.json
 var package_default = {
   name: "@rashidee/co2",
-  version: "1.3.12",
+  version: "1.3.14",
   description: "Compound Context Studio \u2014 self-hosted team context authoring for CO2 projects",
   type: "module",
   license: "MIT",
@@ -25398,7 +25398,7 @@ function scanProject(db, workspacePath, folderName) {
 import { join as join22, relative as relative2 } from "path";
 
 // ../server/src/features/workflow/service.ts
-import { existsSync as existsSync20, mkdirSync as mkdirSync9, readFileSync as readFileSync15, writeFileSync as writeFileSync13 } from "fs";
+import { existsSync as existsSync20, mkdirSync as mkdirSync9, readFileSync as readFileSync15, statSync as statSync6, writeFileSync as writeFileSync13 } from "fs";
 import { join as join21, relative, resolve as resolve2, sep } from "path";
 var ACTIVE_RUN_STATUSES = ["pending", "in_progress"];
 function svcError14(code, status) {
@@ -25855,6 +25855,125 @@ function rescanWorkflowRun(db, workspacePath, workflowMarkdownId, watcherInterva
   }
   return getWorkflowRun(db, workflowMarkdownId, workspacePath);
 }
+var DISCOVERABLE_CONDUCTOR_TYPES = ["prepare", "develop", "quality"];
+function rescanProjectWorkflows(db, workspacePath, projectId, user, watcherIntervalMs) {
+  const project = db.select().from(projects).where(eq(projects.id, projectId)).get();
+  if (!project) throw svcError14("PROJECT_NOT_FOUND", 404);
+  const projectDir2 = join21(workspacePath, project.workspaceFolderName);
+  const nonTerminal = db.select({ id: conductorRuns.id, wfmId: conductorRuns.workflowMarkdownId }).from(conductorRuns).where(
+    and(
+      eq(conductorRuns.projectId, projectId),
+      inArray(conductorRuns.status, [...ACTIVE_RUN_STATUSES])
+    )
+  ).all();
+  const rescannedRuns = nonTerminal.length;
+  const wfmIds = new Set(nonTerminal.map((r) => r.wfmId).filter((x) => x !== null));
+  for (const wfmId of wfmIds) rescanWorkflowRun(db, workspacePath, wfmId, watcherIntervalMs);
+  const apps = db.select({ id: applications.id, name: applications.name }).from(applications).where(and(eq(applications.projectId, projectId), eq(applications.isDeleted, 0))).all();
+  const currentVersionId = ensureBaselineVersion(db, projectId, user.id);
+  const semver = db.select({ semver: prdVersions.semver }).from(prdVersions).where(eq(prdVersions.id, currentVersionId)).get()?.semver ?? null;
+  let discoveredRuns = 0;
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  for (const app of apps) {
+    for (const conductorType of DISCOVERABLE_CONDUCTOR_TYPES) {
+      const trackingFilePath = resolveRunTrackingFilePath(projectDir2, app.name, conductorType);
+      const fileStatus = parseTrackingStatus(trackingFilePath);
+      if (fileStatus === "unknown") continue;
+      const aliases = conductorType === "quality" ? ["quality", "defect"] : [conductorType];
+      const known = db.select({
+        status: conductorRuns.status,
+        prdVersionId: conductorRuns.prdVersionId,
+        createdAt: conductorRuns.createdAt,
+        completedAt: conductorRuns.completedAt
+      }).from(conductorRuns).where(
+        and(
+          eq(conductorRuns.applicationId, app.id),
+          inArray(conductorRuns.conductorType, aliases)
+        )
+      ).all();
+      const knownForVersion = known.filter(
+        (r) => r.prdVersionId === null || r.prdVersionId === currentVersionId
+      );
+      if (fileStatus === "COMPLETED" && knownForVersion.some((r) => r.status === "completed"))
+        continue;
+      if (fileStatus === "IN PROGRESS" && known.some((r) => r.status === "pending" || r.status === "in_progress"))
+        continue;
+      if (fileStatus === "FAILED" && knownForVersion.some((r) => r.status === "failed")) continue;
+      let mtimeMs;
+      try {
+        mtimeMs = statSync6(trackingFilePath).mtimeMs;
+      } catch {
+        continue;
+      }
+      const latestKnownMs = known.reduce(
+        (acc, r) => Math.max(
+          acc,
+          Date.parse(r.createdAt) || 0,
+          r.completedAt ? Date.parse(r.completedAt) || 0 : 0
+        ),
+        0
+      );
+      if (latestKnownMs > 0 && mtimeMs <= latestKnownMs) continue;
+      const mtimeIso = new Date(mtimeMs).toISOString();
+      const wfm = db.insert(workflowMarkdowns).values({
+        projectId,
+        conductorType,
+        // The master the discovery was read from — Run History's path link previews it.
+        filePath: relative(projectDir2, trackingFilePath).replace(/\\/g, "/"),
+        versionLabel: semver,
+        createdBy: user.id,
+        createdByName: user.username,
+        createdAt: now,
+        updatedAt: now
+      }).returning({ id: workflowMarkdowns.id }).get();
+      const run = db.insert(conductorRuns).values({
+        projectId,
+        applicationId: app.id,
+        conductorType,
+        prdVersionId: currentVersionId,
+        trackingFilePath,
+        status: fileStatus === "COMPLETED" ? "completed" : fileStatus === "FAILED" ? "failed" : "in_progress",
+        startedBy: user.id,
+        startedAt: mtimeIso,
+        completedAt: fileStatus === "IN PROGRESS" ? null : mtimeIso,
+        workflowMarkdownId: wfm.id,
+        priorPhaseSatisfied: 1,
+        gitOperationStatus: "skipped",
+        // terminal execution — the user owns its git flow
+        createdAt: now
+      }).returning({ id: conductorRuns.id }).get();
+      discoveredRuns++;
+      if (fileStatus === "COMPLETED") {
+        try {
+          registerConductorArtifacts(db, workspacePath, run.id);
+        } catch {
+        }
+        syncDefectRunStatuses(db, run.id);
+      } else if (fileStatus === "IN PROGRESS") {
+        const appName = app.name;
+        startWatcher(
+          db,
+          run.id,
+          () => resolveRunTrackingFilePath(projectDir2, appName, conductorType),
+          user.id,
+          watcherIntervalMs,
+          (id, terminalStatus) => {
+            lastArtifactSweepAt.delete(id);
+            if (terminalStatus === "COMPLETED") {
+              try {
+                registerConductorArtifacts(db, workspacePath, id);
+              } catch {
+              }
+              syncDefectRunStatuses(db, id);
+            }
+          },
+          (id) => sweepRunArtifactsThrottled(db, workspacePath, id)
+        );
+      }
+    }
+  }
+  return { rescannedRuns, discoveredRuns };
+}
 function getWorkflowRun(db, workflowMarkdownId, workspacePath) {
   const wfm = db.select().from(workflowMarkdowns).where(eq(workflowMarkdowns.id, workflowMarkdownId)).get();
   if (!wfm) throw svcError14("RUN_NOT_FOUND", 404);
@@ -25952,7 +26071,9 @@ function toDetail(db, projectFolder, wfm, workspacePath) {
     status: rollupStatus(runs.map((r) => r.status)),
     applications: appBreakdown,
     filePath: wfm.filePath,
-    executeCommand: buildExecuteCommand(projectFolder, wfm.filePath),
+    // Only generated markdowns (workflow/<user>/<ts>.md) carry an Execute prompt — a row
+    // discovered from a tracking master (rescanProjectWorkflows) has nothing to re-run.
+    executeCommand: wfm.filePath.startsWith("workflow/") ? buildExecuteCommand(projectFolder, wfm.filePath) : "",
     versionLabel: wfm.versionLabel,
     gitOperationStatus: git4?.gitOperationStatus ?? "not_started",
     gitBranchCreated: git4?.gitBranchCreated ?? null,
@@ -26469,7 +26590,7 @@ function projectRoutes(db, workspacePath) {
 }
 
 // ../server/src/features/shared-context/service.ts
-import { existsSync as existsSync21, mkdirSync as mkdirSync10, readFileSync as readFileSync16, readdirSync as readdirSync4, statSync as statSync6, writeFileSync as writeFileSync14 } from "fs";
+import { existsSync as existsSync21, mkdirSync as mkdirSync10, readFileSync as readFileSync16, readdirSync as readdirSync4, statSync as statSync7, writeFileSync as writeFileSync14 } from "fs";
 import { join as join23, resolve as resolve3, sep as sep2 } from "path";
 function svcError16(code, status) {
   return Object.assign(new Error(code), { code, status });
@@ -26527,7 +26648,7 @@ function walk(dir, relBase) {
         children: walk(join23(dir, entry.name), rel)
       });
     } else if (entry.isFile()) {
-      const stat = statSync6(join23(dir, entry.name));
+      const stat = statSync7(join23(dir, entry.name));
       nodes.push({
         name: entry.name,
         path: rel,
@@ -26566,7 +26687,7 @@ function uploadFile(db, workspacePath, projectId, folder, file) {
 function getFileContent(db, workspacePath, projectId, relPath) {
   const root = resolveSharedRoot(db, workspacePath, projectId);
   const full = safeResolve(root, relPath);
-  if (!existsSync21(full) || !statSync6(full).isFile()) throw svcError16("NOT_FOUND", 404);
+  if (!existsSync21(full) || !statSync7(full).isFile()) throw svcError16("NOT_FOUND", 404);
   const name = relPath.split("/").pop() ?? relPath;
   return { mimeType: mimeForName(name), bytes: readFileSync16(full), name };
 }
@@ -26574,7 +26695,7 @@ function saveMarkdown(db, workspacePath, projectId, relPath, content) {
   if (mimeForName(relPath) !== "text/markdown") throw svcError16("NOT_MARKDOWN", 400);
   const root = resolveSharedRoot(db, workspacePath, projectId);
   const full = safeResolve(root, relPath);
-  if (!existsSync21(full) || !statSync6(full).isFile()) throw svcError16("NOT_FOUND", 404);
+  if (!existsSync21(full) || !statSync7(full).isFile()) throw svcError16("NOT_FOUND", 404);
   writeFileSync14(full, content, "utf8");
 }
 
@@ -27149,6 +27270,21 @@ function workflowRoutes(db, workspacePath) {
       return errorResponse16(c, e);
     }
   });
+  app.post("/rescan-all", (c) => {
+    const projectId = Number(c.req.query("projectId"));
+    if (Number.isNaN(projectId)) return c.json({ code: "INVALID_ID" }, 400);
+    const user = c.get("user");
+    try {
+      return c.json(
+        rescanProjectWorkflows(db, workspacePath, projectId, {
+          id: user.id,
+          username: user.username
+        })
+      );
+    } catch (e) {
+      return errorResponse16(c, e);
+    }
+  });
   app.post("/runs/:id/rescan", (c) => {
     const id = Number(c.req.param("id"));
     if (Number.isNaN(id)) return c.json({ code: "INVALID_ID" }, 400);
@@ -27663,7 +27799,7 @@ function loggerMiddleware() {
 }
 
 // ../server/src/lib/static.ts
-import { existsSync as existsSync24, readFileSync as readFileSync19, statSync as statSync7 } from "fs";
+import { existsSync as existsSync24, readFileSync as readFileSync19, statSync as statSync8 } from "fs";
 import { extname, join as join26, normalize, resolve as resolve4, sep as sep3 } from "path";
 var MIME = {
   ".html": "text/html; charset=utf-8",
@@ -27701,7 +27837,7 @@ function serveSpa(staticDir) {
     }
     const rel = path === "/" ? "/index.html" : decodeURIComponent(path);
     const filePath = safeResolve2(staticDir, rel);
-    if (filePath && existsSync24(filePath) && statSync7(filePath).isFile()) {
+    if (filePath && existsSync24(filePath) && statSync8(filePath).isFile()) {
       const body = readFileSync19(filePath);
       return c.body(body, 200, {
         "Content-Type": MIME[extname(filePath)] ?? "application/octet-stream"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rashidee/co2",
-  "version": "1.3.12",
+  "version": "1.3.14",
   "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