@codepassion/skills 1.1.1 → 1.4.0

package/README.md

@@ -8,8 +8,13 @@ Agent skills (SKILL.md) based on the CodePassion (C9N) conventions.
     npx @codepassion/skills install codex      # ~/.codex/skills
     npx @codepassion/skills install project    # ./.agents/skills
     npx @codepassion/skills install combined   # one combined skill
+    npx @codepassion/skills install cowork     # zip skills for claude.ai/Cowork upload (UI, no API)
 
-Or: ./install.sh {claude|codex|project|combined}
+Or: ./install.sh {claude|codex|project|combined|cowork}
+
+claude.ai and Claude Cowork share a personal skill library with no upload API, so `cowork`
+packages upload-ready zips into dist/cowork/ — upload them at
+claude.ai → Settings → Capabilities → Upload skill.
 
 ## Edit
 

package/SKILLS.md

@@ -8,8 +8,13 @@ Agent skills (SKILL.md) based on the CodePassion (C9N) conventions.
     npx @codepassion/skills install codex      # ~/.codex/skills
     npx @codepassion/skills install project    # ./.agents/skills
     npx @codepassion/skills install combined   # one combined skill
+    npx @codepassion/skills install cowork     # zip skills for claude.ai/Cowork upload (UI, no API)
 
-Or: ./install.sh {claude|codex|project|combined}
+Or: ./install.sh {claude|codex|project|combined|cowork}
+
+claude.ai and Claude Cowork share a personal skill library with no upload API, so `cowork`
+packages upload-ready zips into dist/cowork/ — upload them at
+claude.ai → Settings → Capabilities → Upload skill.
 
 ## Edit
 

package/bin/c9n-skills.js

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
-import { cp, mkdir, readdir, stat } from 'node:fs/promises'
+import { cp, mkdir, readdir, rm, stat } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { execFile } from 'node:child_process'
 const SRC = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'skills')
 const [,, cmd='install', target='claude', ...rest] = process.argv
 if (cmd==='help'||cmd==='--help'||cmd==='-h'){ help(); process.exit(0) }
@@ -12,7 +13,12 @@ const flags={dest:null,force:false,dryRun:false}
 for (let i=0;i<rest.length;i++){ const a=rest[i]
   if (a==='--force') flags.force=true
   else if (a==='--dry-run') flags.dryRun=true
-  else if (a==='--dest') flags.dest=resolve(rest[++i]??'') }
+  else if (a==='--dest'){ const v=rest[++i]
+    if (!v){ console.error('--dest requires a value'); process.exit(1) }
+    flags.dest=resolve(v) } }
+// cowork: claude.ai / Cowork share a personal skill library with NO upload API —
+// this packages upload-ready zips for manual drag-drop in Settings → Capabilities.
+if (target==='cowork'){ await packageForCowork(flags); process.exit(0) }
 const dest = flags.dest ?? defaultDest(target)
 if (!dest){ help(); process.exit(1) }
 const sources = await resolveSources(target)
@@ -33,4 +39,23 @@ function defaultDest(t){ const h=homedir()
   if (t==='codex') return join(h,'.codex','skills')
   if (t==='project') return join(process.cwd(),'.agents','skills')
   return null }
-function help(){ console.log('c9n-skills install [claude|codex|project|combined] [--dest <dir>] [--force] [--dry-run]') }
+async function packageForCowork(flags){
+  const ROOT=resolve(SRC,'..')
+  // only auto-clean the default output dir — never delete a user-supplied --dest
+  const isDefaultOut=!flags.dest
+  const out=flags.dest ?? join(ROOT,'dist','cowork')
+  const sources=[...await resolveSources('combined'), ...await resolveSources('cowork')]
+  if (!sources.length){ console.error('No skills found'); process.exit(1) }
+  console.log(`Packaging ${sources.length} skill zip(s) into ${out}${flags.dryRun?' (dry-run)':''}`)
+  if (!flags.dryRun){ if (isDefaultOut) await rm(out,{recursive:true,force:true}); await mkdir(out,{recursive:true}) }
+  for (const src of sources){ const n=src.split(/[\\/]/).pop()
+    console.log(`  zip   ${n}.zip`)
+    if (!flags.dryRun) await zipDir(SRC,n,join(out,`${n}.zip`)) }
+  console.log('Done. Upload at claude.ai → Settings → Capabilities → Upload skill (shared with Cowork).')
+  console.log('Action skills (c9n-spec, c9n-deliverables) bundle their templates/scripts in the zip.')
+}
+function zipDir(cwd,name,outFile){
+  return new Promise((res,rej)=>{ execFile('zip',['-qr',outFile,name],{cwd},(e)=>{
+    if (e && e.code==='ENOENT') rej(new Error("'zip' command not found — install zip and retry"))
+    else if (e) rej(e); else res() }) }) }
+function help(){ console.log('c9n-skills install [claude|codex|project|combined|cowork] [--dest <dir>] [--force] [--dry-run]') }

package/install.sh

@@ -1,13 +1,36 @@
 #!/usr/bin/env bash
 set -euo pipefail
-SRC="$(cd "$(dirname "$0")" && pwd)/skills"
+ROOT="$(cd "$(dirname "$0")" && pwd)"
+SRC="$ROOT/skills"
 MODE="${1:-claude}"
+
+# cowork: claude.ai / Cowork share a personal skill library with NO upload API —
+# package upload-ready zips for manual drag-drop in Settings → Capabilities.
+if [ "$MODE" = "cowork" ]; then
+  command -v zip >/dev/null || { echo "error: 'zip' not found — install zip and retry"; exit 1; }
+  DEST="${TARGET_DIR:-$ROOT/dist/cowork}"
+  # only auto-clean the default output dir — never delete a user-supplied TARGET_DIR
+  if [ -z "${TARGET_DIR:-}" ]; then rm -rf "$DEST"; fi
+  mkdir -p "$DEST"
+  count=0
+  for d in "$SRC"/c9n "$SRC"/c9n-*; do
+    [ -d "$d" ] || continue
+    name="$(basename "$d")"
+    (cd "$SRC" && zip -qr "$DEST/$name.zip" "$name")
+    count=$((count + 1))
+  done
+  echo "Packaged $count skill zip(s) into $DEST"
+  echo "Upload at claude.ai → Settings → Capabilities → Upload skill (shared with Cowork)."
+  command -v open >/dev/null && open "$DEST" 2>/dev/null || true
+  exit 0
+fi
+
 case "$MODE" in
   claude)   DEST="${TARGET_DIR:-$HOME/.claude/skills}" ;;
   codex)    DEST="${TARGET_DIR:-$HOME/.codex/skills}" ;;
   project)  DEST="${TARGET_DIR:-$PWD/.agents/skills}" ;;
   combined) DEST="${TARGET_DIR:-$HOME/.claude/skills}" ;;
-  *) echo "Use: claude | codex | project | combined"; exit 1 ;;
+  *) echo "Use: claude | codex | project | combined | cowork"; exit 1 ;;
 esac
 mkdir -p "$DEST"
 if [ "$MODE" = "combined" ]; then cp -R "$SRC/c9n" "$DEST/"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codepassion/skills",
-  "version": "1.1.1",
+  "version": "1.4.0",
   "description": "Agent skills (SKILL.md) for CodePassion (C9N) engineering conventions.",
   "license": "MIT",
   "type": "module",

package/skills/c9n/SKILL.md

@@ -172,3 +172,347 @@ Alpha: tag from develop, `git tag -a vX.Y.Z -m "Release vX.Y.Z" && git push orig
 Production: confirm Go → pull release branch → create release → CI deploys → monitor.
 Reference: https://semver.org/spec/v2.0.0.html
 
+
+
+---
+
+## Deliverables
+
+Repeatable customer project delivery for the Code Passion team. Turns a codebase into a
+clean, customer-ready documentation package. Fully generic — adapt to whatever stack the
+project uses. Bundled `scripts/` are proven references; read and adapt them per project.
+
+## Four mandatory gates
+
+These ALWAYS run, in order — never skip them:
+
+1. **Clarify-first** — interview before generating anything (see Workflow step 1).
+2. **Security/sanitize** — never ship secrets. Before packaging: scan for and exclude
+   `.env`, credentials, service-account JSON, `*.pem`/`*.key`; sanitize real env files to
+   `.env.example` (names + descriptions, no values); strip `.DS_Store`. If you copied any
+   credential into a build dir to make tooling work, delete it before finishing.
+3. **Verify rendered output** — after creating PDFs, screenshot each (headless browser
+   `--screenshot`) and visually confirm. Catches illegible/empty diagrams and truncation.
+   Do not trust `file`'s page count — use `mdls -name kMDItemNumberOfPages` on macOS.
+4. **Delivery email** — always draft one. Thai for Thai customer teams, Code Passion
+   framing (from Code Passion → client). Leave recipient/contact as fill-in blanks.
+
+## Workflow
+
+1. **Clarify** (ask, don't assume): audience (customer vs internal); which documents are
+   wanted; document language (default: English docs + Thai email); output format (PDF?);
+   package structure — **plain docs package (default)** or **ISO/IEC 29110 work-product
+   layout** (offer it, see [REFERENCE.md](../c9n-deliverables/REFERENCE.md)); any contractual scope.
+2. **Inventory** the codebase — detect stack, framework, DB, API doc tooling; decide which
+   generators apply. Skip what doesn't fit the stack.
+3. **Generate** the doc set (only what was requested). Common artifacts and recipes are in
+   [REFERENCE.md](../c9n-deliverables/REFERENCE.md): system/architecture overview (+ Mermaid diagrams),
+   database design (ER diagram + data dictionary), API reference (export spec → PDF),
+   deployment runbook, configuration reference, source snapshot.
+4. **Render PDFs** with `scripts/md-to-pdf.mjs` (Markdown+Mermaid) and
+   `scripts/openapi-to-pdf.mjs` (OpenAPI). Then run gate 3 (verify).
+5. **Organize** per the chosen structure. Master `README.md` index; for 29110 include a
+   supporting-artifact → work-product traceability map.
+6. **Security gate** (gate 2), then **package**: zip the organized folder directly (or, if a
+   dedicated packaging skill such as `deliverables-packager` is installed, hand off to it for
+   final folder polish + zip).
+7. **Delivery email** (gate 4).
+
+## Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `scripts/md-to-pdf.mjs <in.md> <out.pdf>` | Markdown → PDF, renders Mermaid. Needs a Chromium-family browser. |
+| `scripts/openapi-to-pdf.mjs <spec.json> <out.pdf> [guide.md]` | OpenAPI → print-friendly PDF (no lazy-load truncation). |
+| `scripts/export-openapi.cjs <out.json>` | TEMPLATE: boot a NestJS app, dump Swagger spec. Adapt to project. |
+| `scripts/data-dictionary.cjs <out.md>` | Data dictionary from live MySQL `INFORMATION_SCHEMA`. |
+| `scripts/snapshot-source.sh <repo> <out.zip>` | Clean `git archive` source snapshot. |
+
+## Gotchas
+
+- **Wide Mermaid diagrams** render as an illegible strip at page width. Use `flowchart TB`
+  and split large ER diagrams into per-domain groups (portrait aspect ratio).
+- **OpenAPI export**: build first (`nest build`); ts-node mis-emits decorator metadata.
+  Booting connects to the DB — use a dev DB, never production.
+- **Redoc/Swagger UI → PDF**: they lazy-render; printing truncates. Use `openapi-to-pdf.mjs`.
+- See [REFERENCE.md](../c9n-deliverables/REFERENCE.md) for the ISO/IEC 29110 layout and per-artifact recipes.
+
+
+
+---
+
+## Pipeline
+
+Bootstraps the Code Passion (C9N) CI/CD pipeline into a target repo so a new project deploys the
+same way as the reference implementation (Smiley): **one image per app, built once at the Alpha
+tag, redeployed to Beta/Production by base tag**, env injected at runtime by Coolify. The heavy
+lifting lives in the org reusable workflows `codepassion-team/cicd/.github/workflows/{build,deploy}.yml`
+— the per-repo files this skill generates just call them. The skill's real value is **Phase 3**:
+the interactive ops checklist that encodes every footgun the Smiley setup hit.
+
+Bundled `templates/` are the source skeleton. **Copy them, then substitute tokens** — never edit
+the templates in place for a specific project. The Next.js wiring is an **edit** of files the dev
+already owns, not a file drop (see Phase 2).
+
+## What gets generated
+
+| Path | Template | When |
+|------|----------|------|
+| `<app>/Dockerfile` | `Dockerfile.api` | app has `elysia` |
+| `<app>/Dockerfile` | `Dockerfile.web` | app has `next` |
+| `<app>/Dockerfile` | `Dockerfile.service` | any other deployable app (worker, plain Bun) |
+| `.dockerignore` | `dockerignore` | always (repo root) |
+| `.github/workflows/ci.yml` | `workflows/ci.yml` (+ `_migration-check.partial` if DB) | always |
+| `.github/workflows/deployment.yml` | `workflows/deployment.yml` (+ `_build-job`/`_deploy-job` partials) | always |
+| `<web>/next.config.js` | **edit, not copy** | per web app |
+| `<web>/app/layout.tsx` | **edit, not copy** | per web app |
+
+## Workflow
+
+Run in order; this is a table of contents — rules are below.
+
+1. **Detect (Phase 1).** Scan `apps/*/package.json`. Classify each: `next`→web, `elysia`→api, else
+   →service. Detect DB by **real artifacts** — a migration-generate script in some `package.json`
+   AND a migrations dir on disk — capture their actual names; never assume `drizzle:generate` /
+   `packages/supabase/migrations`. Read root `package.json` for the Bun version / lockfile name.
+   Ask which environments exist (Alpha / Beta / Production). **Print the detected plan and confirm
+   before writing anything.**
+2. **Generate (Phase 2).** Copy templates with tokens substituted. **Diff/confirm per file** — if a
+   target exists, show the diff and ask overwrite/skip/merge; never blind-clobber; leave unrelated
+   files (a hand-kept `staging.yaml`) alone. Then do the **web edits** (below). Run the web build
+   once to prove nothing is baked.
+3. **Checklist (Phase 3).** Walk the dev interactively through the out-of-repo ops (below). This is
+   the deliverable.
+4. **Verify (Phase 4).** After the dev confirms the ops are done, push a tag (or reuse one), watch
+   the Actions run, then `curl` each deployed URL per environment and report pass/fail per app.
+
+## Token substitution
+
+| Token | Source |
+|-------|--------|
+| `{{PACKAGE_NAME}}` | `<project>-<appkey>`, e.g. `smiley-web`. Lowercase. This is the ghcr image name and the `package_name` workflow input. |
+| `{{APP_DIR}}` | The app's path, e.g. `apps/web`. |
+| `{{APP_KEY}}` | Short lowercase id unique per app: `api`, `web`, `worker`. Used in job names. |
+| `{{APP_PORT}}` | `3001` api · `3000` web · service's listen port (drop `EXPOSE` for a portless worker). |
+| `{{BUN_VERSION}}` | Pin from root toolchain, e.g. `1.3.10`. Same across all Dockerfiles. |
+| `{{WORKSPACE_MANIFEST_COPIES}}` | **web template only:** one `COPY <app>/package.json ./<app>/package.json` line **per app** — the `deps` stage runs `bun install` before `COPY . .`, so it needs every workspace manifest to resolve the graph. The api/service compile templates copy only the built app's manifest (matches Smiley's api Dockerfile; avoids pulling a sibling app's postinstall without its src). |
+| `{{MIGRATION_CHECK}}` | `_migration-check.partial.yml` with `{{MIGRATION_SCRIPT}}`/`{{MIGRATIONS_DIR}}` filled, **or empty string** if no DB. |
+| `{{ORG_REF}}` | The org reusable-workflow ref — currently `turborepo`. One place; bump here if the org repo retags. |
+| `{{BUILD_JOBS}}` / `{{DEPLOY_JOBS}}` | Stamp `_build-job.partial` once per app (Alpha only) and `_deploy-job.partial` once per app per environment, pruning unused envs. |
+| `{{DEPLOY_NAME}}` | The org `deploy.yml` `name` input → uppercased to `<NAME>_UUID`. **Only `API` and `WEB` are wired** in the org deploy.yml (see Gotchas). |
+
+## Web edits (surgical — not a file drop)
+
+For each **web** app, edit the files the dev owns; fail loudly if they can't be parsed rather than
+overwrite:
+
+- `next.config.js` — add `output: "standalone"`, `outputFileTracingRoot` (monorepo root), and
+  `transpilePackages` for the workspace packages the app imports.
+- `app/layout.tsx` — add `<head><PublicEnvScript /></head>` (`import { PublicEnvScript } from
+  "next-runtime-env"`). Client code reads public config with `env("NEXT_PUBLIC_X")`, **not**
+  `process.env` (which bakes at build → undefined at runtime).
+- Flag `next-runtime-env` as a dependency to add — **do not run `bun add` yourself**; tell the dev.
+- **Caveat:** runtime values only reach the browser on non-statically-prerendered pages. A page that
+  reads runtime public env must opt out of static caching (`export const dynamic = "force-dynamic"`)
+  or rely on `<PublicEnvScript>` keeping the document dynamic. Note this so future feature work
+  doesn't silently bake a static page.
+
+## Phase 3 — interactive ops checklist (the deliverable)
+
+Derived from the actual `codepassion-team/cicd` reusable workflows. Walk these one at a time:
+
+**Repo prerequisites**
+- A **`develop` branch must exist** — `build.yml` commits the version bump and does
+  `git pull --rebase origin develop` / `push HEAD:develop`. No develop branch → build fails.
+- Tags drive deploys; the exact tag→env mapping is **c9n-semver-deployment** (don't restate it).
+
+**Per environment** — create a GitHub **Environment** named exactly `Alpha` / `Beta` / `Production`:
+- Variables: `COOLIFY_RESOURCE_API_UUID`, `COOLIFY_RESOURCE_WEB_UUID` (the Coolify app UUIDs;
+  `deploy.yml` resolves `${NAME}_UUID`), and `TURBO_TEAM`.
+- Secrets: `COOLIFY_TOKEN` (Coolify API bearer) and `TURBO_TOKEN`. `GITHUB_TOKEN` is automatic
+  (ghcr push uses it; the build job already declares `packages: write`).
+
+**Coolify** (one resource per app per env): source = Docker image
+`ghcr.io/codepassion-team/{{PACKAGE_NAME}}:<base_tag>`; copy each resource's UUID into the matching
+env variable above. Caddy `reverse_proxy <app>:<port>` (api `:3001`, web `:3000`).
+
+**ghcr** — packages are **private**: give Coolify a registry pull credential (or set package
+visibility), or the image pull silently fails.
+
+**Web runtime env in Coolify** (the scars):
+- `PORT=3000` — Next standalone obeys `PORT`; Coolify defaults it to `80`, which 502s behind a
+  Caddy `:3000` proxy. This is the single most common web-deploy failure.
+- `HOSTNAME=0.0.0.0`.
+- The app's `NEXT_PUBLIC_*` values — injected here at runtime, not baked into the image.
+
+## Phase 4 — verify
+
+Push a `v*.*.*` tag (or reuse one), watch the run (`gh run watch`), then for each app per env
+`curl -so /dev/null -w "%{http_code}"` the deployed URL (e.g. `https://api.<proj>.alpha.c9n.co`,
+`https://<proj>.alpha.c9n.co`) and confirm `200`. Report a clean pass/fail table. Don't call it done
+on a green Actions run alone — the 502 class only shows at the live URL.
+
+## Gotchas
+
+- **Combined install mode does not carry `templates/`.** `install.sh combined` copies only the
+  generated `skills/c9n` SKILL.md body. Install via `install.sh claude` (or `project`/`codex`) so the
+  templates come along — same limitation as `c9n-spec`/`c9n-deliverables`.
+- **Org deploy.yml wires only `API_UUID` + `WEB_UUID`.** A third app type (worker) needs a PR to
+  `codepassion-team/cicd` adding `COOLIFY_RESOURCE_<NAME>_UUID` to deploy.yml's `env:` block. Flag
+  this; don't generate a deploy job that silently can't resolve its UUID.
+- **Build once, deploy by base tag.** build.yml strips `-alpha`/`-rc.*`; deploy.yml also strips
+  `-beta.*`. So `v1.2.3` (Alpha) and a later `v1.2.3-beta.1` release both resolve base tag `v1.2.3`
+  and redeploy the same image. Beta/Prod must have an Alpha build of that base version in ghcr first.
+- **`.dockerignore` matters.** Without it, the host's `node_modules` (wrong platform) leaks into the
+  build context and clobbers the linux deps → "failed to load next.config". The template ships it.
+- **Don't touch `.env*`.** Generate `.dockerignore` to exclude them; never read or write env files.
+
+
+
+---
+
+## Sentry
+
+## Sentry — Bun + Elysia + Next.js
+
+## Three landmines (check first)
+
+1. **`@sentry/node` under `bun --compile` fails silently** — valid DSN, zero events. Use `@sentry/elysia` (built on `@sentry/bun`). Never let `@sentry/node` load on the API.
+2. **Runtime public env** — if the project uses `next-runtime-env` (ADR 0005 pattern), the browser DSN MUST use `env("NEXT_PUBLIC_SENTRY_DSN")` not `process.env`. Server/edge/api use `process.env`. Wrong = undefined DSN in prod = dead Sentry.
+3. **PDPA / PII** — add `beforeSend` scrubber + `sendDefaultPii: false`. Strip request body/query/cookies, drop auth headers, recursively redact PII keys. See [REFERENCE.md](REFERENCE.md#pdpa-scrubber).
+
+## Quick start
+
+```
+packages/sentry/          ← @repo/sentry (shared)
+  src/pdpa.ts             ← beforeSend scrubber (shared by all inits)
+  src/bun.ts              ← initBun() for apps/api
+  src/client.ts           ← initClient() for browser (uses env() not process.env)
+  src/server.ts           ← initServer() for Next.js server runtime
+  src/edge.ts             ← initEdge() for Next.js edge runtime
+  package.json            ← exports map: ./bun ./client ./server ./edge ./pdpa
+apps/api/src/lib/sentry.ts   ← import { initBun } from "@repo/sentry/bun"; initBun()
+apps/api/src/index.ts        ← first import: "./lib/sentry.js", then withElysia(new Elysia())
+apps/web/instrumentation.ts  ← register() → dynamic import server/edge config
+apps/web/instrumentation-client.ts ← initClient()
+apps/web/sentry.server.config.ts / sentry.edge.config.ts
+apps/web/next.config.js      ← withSentryConfig + transpilePackages: ["@repo/sentry"]
+```
+
+## Env vars
+
+| Service | Key | Read by |
+|---------|-----|---------|
+| API (Coolify) | `SENTRY_DSN`, `ENVIRONMENT` | `process.env` |
+| Web (Coolify) | `NEXT_PUBLIC_SENTRY_DSN`, `NEXT_PUBLIC_ENVIRONMENT` | `env()` from next-runtime-env (client) / `process.env` (server/edge) |
+
+One Sentry project, same DSN in both vars. Add `initialScope: { tags: { app: "api" } }` to `initBun()` so api vs web events are distinguishable in the shared project.
+
+## Verification checklist
+
+- [ ] `bun install --frozen-lockfile` clean
+- [ ] `bun run check-types` (api + web) clean
+- [ ] `bun run build --compile` on API — confirms `@sentry/node` never loaded (the landmine test)
+- [ ] Web Sentry bundle builds green
+- [ ] After deploy: `window.__ENV.NEXT_PUBLIC_SENTRY_DSN` populated in devtools (runtime env proof)
+- [ ] Trigger a test error → event appears in Sentry tagged correct environment
+- [ ] Open event payload — no phone/otp/lat/lng/member_id (PDPA proof)
+
+## Reference
+
+See [REFERENCE.md](REFERENCE.md) for full file contents, PDPA scrubber code, and `turbo.json` config.
+
+
+
+---
+
+## Spec
+
+Bootstraps the Code Passion (C9N) spec-driven development doc system into a target repo. Drops
+a self-contained, agent-readable documentation skeleton so a fresh project starts with the same
+approval gates, traceability, and glossary discipline as the reference implementation
+(ddg-jewelry). Fully generic — adapt the placeholders to whatever stack the project uses.
+
+Bundled `templates/` are the source skeleton. **Copy them, then substitute tokens** — never edit
+the templates in place for a specific project.
+
+## What gets scaffolded
+
+| File | Role |
+|------|------|
+| `AGENTS.md` | **Canonical** agent context: the full ISO/IEC 29110 spec-driven protocol (inlined, so the repo is self-contained) + C9N stack + module patterns. References the sibling `c9n-*` convention skills rather than copying them. |
+| `CLAUDE.md` | Bridge that `@AGENTS.md`-imports the canonical file (so Claude Code's memory auto-loads the protocol; other tools read AGENTS.md directly). |
+| `CONTEXT.md` | Ubiquitous-language glossary skeleton (no implementation detail). |
+| `DESIGN.md` | Visual design-system rules — **only if the repo has a frontend.** |
+| `docs/SRS.md` | Requirements master registry (feature short-codes + system NFRs). |
+| `docs/architecture.md` | Software-design as-is map. |
+| `docs/traceability.md` | Requirement → design → test master index. |
+| `docs/test-plan.md` | Master test strategy. |
+| `docs/adr/0001-spec-driven-iso29110-docs.md` | Seed ADR: why this doc system exists. |
+| `docs/adr/_TEMPLATE.md` | ADR format for future decisions. |
+| `docs/features/_TEMPLATE.md` | Per-feature deep-doc stub (Requirements · Design · Test Plan · Test Cases · Traceability). |
+| `docs/agents/{issue-tracker,triage-labels,domain}.md` | Agent-process docs (GitHub `gh`, triage vocab, domain-doc consumption). |
+| `.github/pull_request_template.md` | The Definition-of-Done merge gate. |
+
+## Workflow
+
+Run each step in order; this is a table of contents — the rules are below.
+
+1. **Detect repo shape.** Read the target's root `package.json`/workspaces. Decide:
+   monorepo vs single app; **frontend present?** (`apps/web`, or `next`/`astro`/`vite`/`react`
+   in any `package.json`) → include `DESIGN.md`. **Backend/API present?** → keep the API
+   module-patterns section in AGENTS.md; otherwise tell the user it's deletable.
+2. **No-clobber.** For every target path, **skip if it already exists** — never overwrite. Collect
+   skipped paths for the final report. (Re-running the skill must be safe and idempotent.)
+3. **Copy templates** into the target repo, substituting tokens (below). Skip `DESIGN.md` if no
+   frontend. Skip the API section guidance if no backend.
+4. **Optional scan — OFF by default.** Only if the user **explicitly** asks to seed from code
+   ("scan the codebase", "seed the glossary", "reverse-document"): read the codebase and fill
+   - `CONTEXT.md` — first real glossary terms (actors, core entities) from the domain;
+   - `docs/architecture.md` — the actual module map + data-model relationships;
+   - `docs/features/` — one as-built stub per shipped module (low-confidence, no test cases),
+     and register each in `docs/SRS.md` with a fresh short-code.
+   Without this request, leave the placeholders untouched.
+5. **Report.** Print created vs skipped files, then next steps: pick the first feature, write its
+   SRS section (Gate 1), get sign-off, then Design + Test Plan (Gate 2) — no production code
+   before Gate 2.
+
+## Token substitution
+
+When copying, replace these placeholders:
+
+| Token | Source |
+|-------|--------|
+| `{{PROJECT_NAME}}` | Target root dir name, or `package.json` `name` (humanized). |
+| `{{YEAR}}` / `{{DATE}}` | Current year / ISO date (for the seed ADR). |
+| `{{DECIDER}}` | Ask, or default to the repo owner. |
+| Stack rows in AGENTS.md | Keep C9N defaults; trim rows the detected stack doesn't use. |
+
+## Conventions (referenced, not copied)
+
+The scaffolded `AGENTS.md` points at the sibling C9N skills for engineering conventions — it does
+**not** inline them, so they have a single source of truth:
+
+- Commits → `c9n-commit-messages` · Branching → `c9n-git-branching` · PRs → `c9n-pull-requests`
+- Clean code → `c9n-clean-code-typescript` · Lint/types → `c9n-typescript-eslint`
+- Formatting → `c9n-code-formatting` · Review → `c9n-code-review`
+
+For C9N-internal repos every dev has these installed, so the references always resolve. If you
+scaffold into a repo where they may not be installed, tell the user to
+`npx @codepassion/skills install claude`.
+
+## Gotchas
+
+- **Combined install mode does not carry `templates/`.** `install.sh combined` copies only the
+  generated `skills/c9n` SKILL.md body; the bundled templates are absent. Install `c9n-spec` via
+  `install.sh claude` (or `project`/`codex`) so the templates come along. Same limitation as
+  `c9n-deliverables`' scripts.
+- **AGENTS.md vs CLAUDE.md.** AGENTS.md is the real file. CLAUDE.md exists only so Claude Code's
+  memory auto-load reaches the protocol — it does so via the **`@AGENTS.md` import** (Claude Code's
+  memory-import syntax), not a markdown link (a link is inert and pulls nothing into context). Don't
+  duplicate content into CLAUDE.md. If a target tool doesn't support `@`-imports, it reads AGENTS.md
+  directly anyway, so nothing is lost.
+- **Don't grade the stubs.** If you run the optional scan, as-built stubs describe *current*
+  behavior at low confidence with **no** test cases — deepen on touch, per the protocol. Don't
+  invent acceptance criteria for code you only read.
+

package/skills/c9n-deliverables/REFERENCE.md

@@ -0,0 +1,97 @@
+# C9N Deliverables — Reference
+
+## Document set (artifacts & recipes)
+
+Generate only what the clarify step asked for. Each is a Markdown source rendered to PDF.
+
+### System / Architecture Overview
+- Content: tech stack table, module map, auth model, API versioning, **architecture
+  diagrams** (Mermaid `flowchart`): System Context, Layered Request Flow, Deployment.
+- Source from README + code structure. Render with `md-to-pdf.mjs`.
+- Keep flow diagrams `flowchart TB` so they stay legible at page width.
+
+### Database Design
+- ER diagram(s) as Mermaid `erDiagram`. **Split into per-domain groups** — one giant ER is
+  unreadable. Plus a domain-grouped entity catalog.
+- **Data dictionary**: every table & column. Generate from the live DB with
+  `data-dictionary.cjs` (most accurate) — adjust the env var names to the project.
+
+### API Reference
+- Export the spec from the running/built app (`export-openapi.cjs` for NestJS/Swagger, or
+  `curl <host>/api-json`). Render with `openapi-to-pdf.mjs` (optionally pass a guide.md
+  intro covering auth, versioning, how to import the spec).
+- Also ship `openapi.json` (Postman/codegen) and optionally a Redoc HTML for browsing.
+
+### Deployment Runbook
+- Prerequisites, env vars (point to `.env.example`), local dev, build, Docker, CI/CD
+  (e.g. Cloud Build → Cloud Run), production checklist, troubleshooting.
+
+### Configuration Reference
+- Sanitized `.env.example` — variable names + descriptions, **no values**. Plus notes on
+  Docker/compose/CI config files.
+
+### Source Code Snapshot
+- `snapshot-source.sh <repo> <out.zip>`. Run at final delivery so it isn't stale.
+
+## Plain docs package layout (default)
+
+```
+deliverables/
+├── README.md                  # index
+├── 01-documentation/
+│   ├── markdown/              # editable sources
+│   └── pdf/                   # rendered PDFs
+├── 02-database/              # data dictionary, ER
+├── 03-configuration/        # .env.example, notes
+├── 04-utilities/            # helper scripts
+└── 05-source-code/          # snapshot (or placeholder)
+```
+
+## ISO/IEC 29110 layout (Basic Profile, offer when engagement needs it)
+
+Two process groups. Formal work products at their slots; supporting engineering artifacts
+filed under the SI work product they evidence, with a traceability map in the README.
+
+```
+deliverables/
+├── README.md                         # master index + traceability
+├── 00-project-management/            # PM work products
+│   ├── PM-01_Statement-of-Work.pdf
+│   ├── PM-02_Project-Plan.pdf
+│   ├── PM-03_Progress-Status-Record.pdf
+│   ├── PM-04_Change-Request.pdf
+│   ├── PM-05_Acceptance-Record.pdf
+│   └── PM-06_Verification-Validation-Record.pdf
+└── 01-software-implementation/       # SI work products
+    ├── SI-01_Requirements-Specification.pdf
+    ├── SI-02_Software-Design.pdf
+    ├── SI-03_Traceability-Record.pdf
+    ├── SI-04_Test-Cases-and-Procedures.pdf
+    ├── SI-05_Test-Report.pdf
+    ├── SI-06_Product-Operation-Guide.pdf
+    ├── SI-07_Maintenance-Documentation.pdf
+    └── supporting/
+        ├── architecture/   → SI.2
+        ├── database/       → SI.2
+        ├── api/            → SI.2 (interfaces)
+        ├── operations/     → SI.6 / SI.7
+        └── source-code/    → SI Software Components
+```
+
+Traceability: architecture/database/api → **SI.2 Software Design**; operations →
+**SI.6 Product Operation Guide** + **SI.7 Maintenance**; source-code → **SI Software
+Components**. PM acceptance/sign-off rows stay open for the customer.
+
+## Delivery email shape (Thai default)
+
+- Subject: `ส่งมอบชุด Deliverables โครงการ [PROJECT]`
+- From Code Passion → customer team. One paragraph: package attached. One: contents
+  overview. One: PDFs for reading + Markdown sources retained. Note where the source
+  snapshot lives. Close with support availability. Leave `[ชื่อผู้รับ]` / `[ช่องทางติดต่อ]` blanks.
+
+## Dependency notes
+
+- PDF rendering needs a Chromium-family browser (Brave/Chrome/Edge/Chromium). Never auto-
+  install heavy deps (puppeteer, pandoc, LaTeX) without asking the user first.
+- `data-dictionary.cjs` needs `mysql2` resolvable from a project that has it.
+- Mermaid + marked load from CDN → diagram rendering needs internet.

package/skills/c9n-deliverables/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: c9n-deliverables
+description: Generate a customer-facing delivery/handover package FROM a codebase — architecture docs, ER/data-dictionary, API reference, all rendered to PDF, organized, security-scanned, zipped, with a delivery email. Use when handing a project off to a customer or another team, preparing deliverables, "delivery package", "handover", "ส่งมอบงาน", or when asked to document a codebase for an external recipient. Complements deliverables-packager (this generates docs from code + organizes; that packages existing docs).
+---
+
+Repeatable customer project delivery for the Code Passion team. Turns a codebase into a
+clean, customer-ready documentation package. Fully generic — adapt to whatever stack the
+project uses. Bundled `scripts/` are proven references; read and adapt them per project.
+
+## Four mandatory gates
+
+These ALWAYS run, in order — never skip them:
+
+1. **Clarify-first** — interview before generating anything (see Workflow step 1).
+2. **Security/sanitize** — never ship secrets. Before packaging: scan for and exclude
+   `.env`, credentials, service-account JSON, `*.pem`/`*.key`; sanitize real env files to
+   `.env.example` (names + descriptions, no values); strip `.DS_Store`. If you copied any
+   credential into a build dir to make tooling work, delete it before finishing.
+3. **Verify rendered output** — after creating PDFs, screenshot each (headless browser
+   `--screenshot`) and visually confirm. Catches illegible/empty diagrams and truncation.
+   Do not trust `file`'s page count — use `mdls -name kMDItemNumberOfPages` on macOS.
+4. **Delivery email** — always draft one. Thai for Thai customer teams, Code Passion
+   framing (from Code Passion → client). Leave recipient/contact as fill-in blanks.
+
+## Workflow
+
+1. **Clarify** (ask, don't assume): audience (customer vs internal); which documents are
+   wanted; document language (default: English docs + Thai email); output format (PDF?);
+   package structure — **plain docs package (default)** or **ISO/IEC 29110 work-product
+   layout** (offer it, see [REFERENCE.md](../c9n-deliverables/REFERENCE.md)); any contractual scope.
+2. **Inventory** the codebase — detect stack, framework, DB, API doc tooling; decide which
+   generators apply. Skip what doesn't fit the stack.
+3. **Generate** the doc set (only what was requested). Common artifacts and recipes are in
+   [REFERENCE.md](../c9n-deliverables/REFERENCE.md): system/architecture overview (+ Mermaid diagrams),
+   database design (ER diagram + data dictionary), API reference (export spec → PDF),
+   deployment runbook, configuration reference, source snapshot.
+4. **Render PDFs** with `scripts/md-to-pdf.mjs` (Markdown+Mermaid) and
+   `scripts/openapi-to-pdf.mjs` (OpenAPI). Then run gate 3 (verify).
+5. **Organize** per the chosen structure. Master `README.md` index; for 29110 include a
+   supporting-artifact → work-product traceability map.
+6. **Security gate** (gate 2), then **package**: zip the organized folder directly (or, if a
+   dedicated packaging skill such as `deliverables-packager` is installed, hand off to it for
+   final folder polish + zip).
+7. **Delivery email** (gate 4).
+
+## Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `scripts/md-to-pdf.mjs <in.md> <out.pdf>` | Markdown → PDF, renders Mermaid. Needs a Chromium-family browser. |
+| `scripts/openapi-to-pdf.mjs <spec.json> <out.pdf> [guide.md]` | OpenAPI → print-friendly PDF (no lazy-load truncation). |
+| `scripts/export-openapi.cjs <out.json>` | TEMPLATE: boot a NestJS app, dump Swagger spec. Adapt to project. |
+| `scripts/data-dictionary.cjs <out.md>` | Data dictionary from live MySQL `INFORMATION_SCHEMA`. |
+| `scripts/snapshot-source.sh <repo> <out.zip>` | Clean `git archive` source snapshot. |
+
+## Gotchas
+
+- **Wide Mermaid diagrams** render as an illegible strip at page width. Use `flowchart TB`
+  and split large ER diagrams into per-domain groups (portrait aspect ratio).
+- **OpenAPI export**: build first (`nest build`); ts-node mis-emits decorator metadata.
+  Booting connects to the DB — use a dev DB, never production.
+- **Redoc/Swagger UI → PDF**: they lazy-render; printing truncates. Use `openapi-to-pdf.mjs`.
+- See [REFERENCE.md](../c9n-deliverables/REFERENCE.md) for the ISO/IEC 29110 layout and per-artifact recipes.