@codepassion/skills 1.2.0 → 1.5.0

package/skills/c9n-pipeline/templates/Dockerfile.api

@@ -0,0 +1,49 @@
+# -----------------------------------------------------------------------------
+# {{PACKAGE_NAME}} (Elysia BFF) — compiled to a single Bun binary, run on
+# debian slim. Generated by c9n-pipeline; tune freely after.
+# -----------------------------------------------------------------------------
+
+FROM oven/bun:{{BUN_VERSION}} AS build
+
+WORKDIR /app
+
+# Root manifests + lockfile
+COPY package.json bun.lock ./
+
+# This app's manifest + shared packages (compile needs only this member's graph)
+COPY {{APP_DIR}}/package.json ./{{APP_DIR}}/package.json
+COPY packages/ ./packages/
+
+# Source needed to compile (copied before install so workspace links resolve)
+COPY {{APP_DIR}}/src ./{{APP_DIR}}/src
+
+RUN bun install
+
+ENV NODE_ENV=production
+
+# Compile the API to a standalone binary from the repo root
+RUN bun build \
+    --compile \
+    --minify-whitespace \
+    --minify-syntax \
+    --target=bun \
+    --outfile /app/server \
+    ./{{APP_DIR}}/src/index.ts
+
+# Runtime image — debian slim for compiled-Bun-binary compatibility
+FROM debian:bookworm-slim
+
+WORKDIR /app
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends ca-certificates && \
+    rm -rf /var/lib/apt/lists/*
+
+COPY --from=build /app/server ./server
+RUN chmod +x ./server
+
+ENV NODE_ENV=production
+
+EXPOSE {{APP_PORT}}
+
+CMD ["./server"]

package/skills/c9n-pipeline/templates/Dockerfile.service

@@ -0,0 +1,45 @@
+# -----------------------------------------------------------------------------
+# {{PACKAGE_NAME}} (generic Bun service / worker) — compiled to a single Bun
+# binary, run on debian slim. Generated by c9n-pipeline.
+# A worker with no HTTP port: drop the EXPOSE line and skip its Coolify domain.
+# NOTE: the org deploy.yml only wires API_UUID + WEB_UUID — a third app type
+# needs a PR to codepassion-team/cicd to add its COOLIFY_RESOURCE_<NAME>_UUID.
+# -----------------------------------------------------------------------------
+
+FROM oven/bun:{{BUN_VERSION}} AS build
+
+WORKDIR /app
+
+COPY package.json bun.lock ./
+COPY {{APP_DIR}}/package.json ./{{APP_DIR}}/package.json
+COPY packages/ ./packages/
+COPY {{APP_DIR}}/src ./{{APP_DIR}}/src
+
+RUN bun install
+
+ENV NODE_ENV=production
+
+RUN bun build \
+    --compile \
+    --minify-whitespace \
+    --minify-syntax \
+    --target=bun \
+    --outfile /app/server \
+    ./{{APP_DIR}}/src/index.ts
+
+FROM debian:bookworm-slim
+
+WORKDIR /app
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends ca-certificates && \
+    rm -rf /var/lib/apt/lists/*
+
+COPY --from=build /app/server ./server
+RUN chmod +x ./server
+
+ENV NODE_ENV=production
+
+EXPOSE {{APP_PORT}}
+
+CMD ["./server"]

package/skills/c9n-pipeline/templates/Dockerfile.web

@@ -0,0 +1,55 @@
+# -----------------------------------------------------------------------------
+# {{PACKAGE_NAME}} (Next.js app) — Bun multi-stage build.
+# Public env is read at RUNTIME via next-runtime-env (<PublicEnvScript>), so this
+# image bakes no NEXT_PUBLIC_* — Coolify injects them at run, like the API image.
+# Generated by c9n-pipeline; see the ADR this skill points you to.
+#
+# {{BUN_VERSION}} must be >= 1.3.10 — 1.2.x breaks `next build` on Linux.
+# Single-app repo: {{APP_DIR}}=. and {{WORKSPACE_MANIFEST_COPIES}}= empty; also
+# delete the `COPY packages/ ./packages/` line below (no packages/ dir). See the
+# "Single-app repos" section in SKILL.md.
+# -----------------------------------------------------------------------------
+
+FROM oven/bun:{{BUN_VERSION}} AS base
+WORKDIR /app
+
+# Install dependencies with bun
+FROM base AS deps
+COPY package.json bun.lock ./
+{{WORKSPACE_MANIFEST_COPIES}}
+COPY packages/ ./packages/
+RUN bun install
+
+# Rebuild the source code only when needed
+FROM base AS builder
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+
+# Next.js expects {{APP_DIR}}/.env to exist; intentionally empty — no public env
+# is baked at build (it is injected at runtime via next-runtime-env).
+RUN touch {{APP_DIR}}/.env
+
+RUN cd {{APP_DIR}} && bun run build
+
+# Production image — serve the Next.js standalone output
+FROM base AS runner
+WORKDIR /app
+
+ENV NODE_ENV=production \
+    PORT={{APP_PORT}} \
+    HOSTNAME="0.0.0.0"
+
+RUN groupadd --system --gid 1001 nodejs && \
+    useradd --system --uid 1001 nextjs
+
+# Leverage Next.js output file tracing to keep the image small
+COPY --from=builder --chown=nextjs:nodejs /app/{{APP_DIR}}/.next/standalone ./
+COPY --from=builder --chown=nextjs:nodejs /app/{{APP_DIR}}/.next/static ./{{APP_DIR}}/.next/static
+COPY --from=builder --chown=nextjs:nodejs /app/{{APP_DIR}}/public ./{{APP_DIR}}/public
+
+USER nextjs
+
+EXPOSE {{APP_PORT}}
+
+CMD ["bun", "{{APP_DIR}}/server.js"]

package/skills/c9n-pipeline/templates/dockerignore

@@ -0,0 +1,18 @@
+.next
+node_modules
+**/node_modules
+**/.next
+**/dist
+.git
+.turbo
+**/.turbo
+npm-debug.log
+yarn-error.log
+bun-debug.log
+.env
+**/.env
+.env.*
+**/.env.*
+
+# Next.js telemetry
+.next/telemetry

package/skills/c9n-pipeline/templates/workflows/_build-job.partial.yml

@@ -0,0 +1,13 @@
+# One BUILD job per app. Alpha only — the image is built once at the tag push
+# and redeployed to Beta/Production by base tag (no rebuild). {{APP_KEY}} is a
+# lowercase id unique per app (e.g. api, web). {{ORG_REF}} is the org workflow
+# ref (e.g. turborepo) — keep it identical across every job in this file.
+  build-{{APP_KEY}}-alpha:
+    name: Build
+    if: github.event_name != 'release' && startsWith(github.ref, 'refs/tags/v')
+    uses: codepassion-team/cicd/.github/workflows/build.yml@{{ORG_REF}}
+    with:
+      environment: Alpha
+      build_path: ./{{APP_DIR}}
+      package_name: {{PACKAGE_NAME}}
+    secrets: inherit

package/skills/c9n-pipeline/templates/workflows/_deploy-job.partial.yml

@@ -0,0 +1,17 @@
+# One DEPLOY job per app per environment. {{DEPLOY_NAME}} is the org deploy.yml
+# name input that resolves the Coolify UUID var: it is uppercased to
+# ${{DEPLOY_NAME_UPPER}}_UUID, so it MUST be a key the org deploy.yml wires
+# (currently only API and WEB). Stamp the right {{IF_CONDITION}} per environment
+# from c9n-semver-deployment:
+#   Alpha       -> needs: build-{{APP_KEY}}-alpha ; if: github.event_name != 'release' && startsWith(github.ref, 'refs/tags/v')
+#   Beta        -> (no needs) ; if: github.event_name == 'release' && github.event.release.prerelease == true && startsWith(github.event.release.tag_name, 'v')
+#   Production  -> (no needs) ; if: github.event_name == 'release' && github.event.release.prerelease == false && startsWith(github.event.release.tag_name, 'v')
+  deploy-{{APP_KEY}}-{{ENV_KEY}}:
+    name: Deploy
+    if: {{IF_CONDITION}}
+    {{NEEDS_LINE}}
+    uses: codepassion-team/cicd/.github/workflows/deploy.yml@{{ORG_REF}}
+    with:
+      name: {{DEPLOY_NAME}}
+      environment: {{ENVIRONMENT}}
+    secrets: inherit

package/skills/c9n-pipeline/templates/workflows/_migration-check.partial.yml

@@ -0,0 +1,16 @@
+# Inject in place of {{MIGRATION_CHECK}} in ci.yml ONLY when a DB is detected
+# (a migration-generate script exists in some package.json AND a migrations dir
+# exists). Substitute {{MIGRATION_SCRIPT}} and {{MIGRATIONS_DIR}} with the real
+# detected names — do not assume drizzle:generate / packages/supabase/migrations.
+# If no DB, {{MIGRATION_CHECK}} is the empty string and ci.yml ends at Build.
+      - name: Verify migrations are up to date
+        run: bun run {{MIGRATION_SCRIPT}} -- --name check
+      - name: Check for uncommitted migration changes
+        run: |
+          if git diff --name-only --exit-code {{MIGRATIONS_DIR}}; then
+            echo "Migrations are up to date"
+          else
+            echo "Detected uncommitted migration changes. Run 'bun run {{MIGRATION_SCRIPT}}' locally and commit the result."
+            git diff {{MIGRATIONS_DIR}}
+            exit 1
+          fi

package/skills/c9n-pipeline/templates/workflows/ci.yml

@@ -0,0 +1,50 @@
+name: CI
+on:
+  push:
+    branches: ['main', 'develop']
+  pull_request:
+    types: [opened, synchronize]
+jobs:
+  build:
+    name: Check
+    timeout-minutes: 15
+    runs-on: ubuntu-latest
+    env:
+      TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
+      TURBO_TEAM: ${{ vars.TURBO_TEAM }}
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+      - name: Cache turbo build setup
+        uses: actions/cache@v4
+        with:
+          path: .turbo
+          key: ${{ runner.os }}-turbo-${{ github.sha }}
+          restore-keys: |
+            ${{ runner.os }}-turbo-
+      - uses: oven-sh/setup-bun@v2
+      - name: Setup Node.js environment
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+      - name: Install dependencies
+        run: bun install
+      - name: Check types
+        run: bun run check-types
+      - name: Build
+        # Placeholder NEXT_PUBLIC_* values satisfy module-init that reads them at import
+        # time (e.g. Supabase clients) — CI has no .env files, so without these
+        # `next build` throws "Error: supabaseUrl is required" collecting page
+        # data. Real values are injected at runtime via next-runtime-env, never
+        # baked. Mirrors the Dockerfile build stage. Add one line per public var
+        # the app constructs a client from at import.
+        run: SKIP_ENV_VALIDATION=1 bun run build
+        env:
+          NEXT_PUBLIC_SUPABASE_URL: http://placeholder.invalid
+          NEXT_PUBLIC_SUPABASE_ANON_KEY: placeholder
+{{MIGRATION_CHECK}}
+# Single-app repos (no turbo.json): remove the TURBO_TOKEN/TURBO_TEAM `env:` and
+# the `.turbo` cache step above, and swap `bun run check-types` for
+# `bunx tsc --noEmit` if the repo has no check-types script.

package/skills/c9n-pipeline/templates/workflows/deployment.yml

@@ -0,0 +1,21 @@
+name: Deployment
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - 'v*.*.*'
+  release:
+    types: [published]
+
+# Assembled by c9n-pipeline from the partials below. The triggers and the
+# event->environment mapping follow c9n-semver-deployment (single source of
+# truth): tag push -> Alpha, prerelease -> Beta, release -> Production.
+#
+# Stamp one BUILD job per app (Alpha only — built once, redeployed by base tag),
+# then one DEPLOY job per app per environment the project actually has. Prune
+# environments the project does not use.
+
+jobs:
+{{BUILD_JOBS}}
+{{DEPLOY_JOBS}}

package/skills/c9n-sentry/REFERENCE.md

@@ -0,0 +1,172 @@
+# Sentry Bun+Elysia+Next.js — Reference
+
+## package.json (`packages/sentry/`)
+
+```json
+{
+  "name": "@repo/sentry",
+  "type": "module",
+  "exports": {
+    "./bun":    { "import": "./src/bun.ts" },
+    "./client": { "import": "./src/client.ts" },
+    "./server": { "import": "./src/server.ts" },
+    "./edge":   { "import": "./src/edge.ts" },
+    "./pdpa":   { "import": "./src/pdpa.ts" }
+  },
+  "dependencies": {
+    "@sentry/elysia": "^10",
+    "@sentry/nextjs": "^10"
+  },
+  "peerDependencies": {
+    "elysia": "*",
+    "next-runtime-env": "*"
+  }
+}
+```
+
+## PDPA scrubber
+
+```ts
+// src/pdpa.ts
+import type { Event } from "@sentry/core"
+
+const PII_KEY = /phone|otp|lat|lng|latitude|longitude|member_?id|token|secret|password/i
+const DROP_HEADERS = ["authorization", "cookie", "set-cookie"]
+
+function redactKeys(obj: unknown): unknown {
+  if (!obj || typeof obj !== "object") return obj
+  if (Array.isArray(obj)) return obj.map(redactKeys)
+  return Object.fromEntries(
+    Object.entries(obj as Record<string, unknown>).map(([k, v]) => [
+      k,
+      PII_KEY.test(k) ? "[redacted]" : redactKeys(v)
+    ])
+  )
+}
+
+export function pdpaBeforeSend(event: Event): Event | null {
+  if (event.request) {
+    event.request.data = undefined
+    event.request.query_string = undefined
+    event.request.cookies = undefined
+    if (event.request.headers) {
+      DROP_HEADERS.forEach(h => { delete (event.request!.headers as Record<string, string>)[h] })
+    }
+  }
+  if (event.extra) event.extra = redactKeys(event.extra) as Record<string, unknown>
+  return event
+}
+```
+
+## src/bun.ts
+
+```ts
+export * from "@sentry/elysia"
+import * as Sentry from "@sentry/elysia"
+import { pdpaBeforeSend } from "./pdpa.js"
+
+export function initBun(): void {
+  const dsn = process.env.SENTRY_DSN
+  if (!dsn) return
+  Sentry.init({
+    dsn,
+    environment: process.env.ENVIRONMENT || "development",
+    tracesSampleRate: 0.1,
+    sendDefaultPii: false,
+    beforeSend: pdpaBeforeSend,
+    initialScope: { tags: { app: "api" } }
+  })
+}
+```
+
+## src/client.ts (runtime env — ADR 0005)
+
+```ts
+export * from "@sentry/nextjs"
+import * as Sentry from "@sentry/nextjs"
+import { env } from "next-runtime-env"   // ← NOT process.env
+import { pdpaBeforeSend } from "./pdpa.js"
+
+export function initClient(): void {
+  const dsn = env("NEXT_PUBLIC_SENTRY_DSN")   // runtime, not build-time
+  if (!dsn) return
+  Sentry.init({
+    dsn,
+    environment: env("NEXT_PUBLIC_ENVIRONMENT") || "development",
+    tracesSampleRate: 0.1,
+    sendDefaultPii: false,
+    beforeSend: pdpaBeforeSend,
+    tags: { app: "web" }
+  })
+}
+```
+
+## apps/api/src/index.ts wiring
+
+```ts
+import "./lib/sentry.js"           // ← must be FIRST import
+// ... other imports ...
+import { withElysia } from "@repo/sentry/bun"
+
+const app = withElysia(new Elysia())  // wraps for auto error capture
+  .use(...)
+  // remove any console.error in onError — withElysia handles it
+```
+
+## apps/web/next.config.js
+
+```js
+import { withSentryConfig } from "@repo/sentry/client"
+const nextConfig = { transpilePackages: ["@repo/sentry"], ... }
+export default withSentryConfig(nextConfig, {
+  silent: true,
+  hideSourceMaps: true,
+  tunnelRoute: "/monitoring"   // guards against in-app-browser/CSP drops
+})
+```
+
+## apps/web/instrumentation.ts
+
+```ts
+export async function register() {
+  if (process.env.NEXT_RUNTIME === "nodejs") {
+    await import("./sentry.server.config")
+  }
+  if (process.env.NEXT_RUNTIME === "edge") {
+    await import("./sentry.edge.config")
+  }
+}
+export { captureRequestError as onRequestError } from "@sentry/nextjs"
+```
+
+## apps/web/instrumentation-client.ts
+
+```ts
+import { initClient, captureRouterTransitionStart } from "@repo/sentry/client"
+initClient()
+export const onRouterTransitionStart = captureRouterTransitionStart
+```
+
+## turbo.json globalEnv additions
+
+```json
+"globalEnv": ["SENTRY_DSN", "ENVIRONMENT"]
+```
+
+Do NOT add `NEXT_PUBLIC_*` to globalEnv — they are runtime-injected via `PublicEnvScript`.
+
+## Sentry project setup
+
+1. sentry.io → **Create Project** → platform: **Next.js** → name: `<project>`
+2. Copy DSN from **Project Settings → Client Keys (DSN)**
+3. Same DSN in both Coolify services (one project, two env var names)
+4. Redeploy both services after setting vars
+
+## ADR checklist (write ADR when adopting)
+
+- Why `@sentry/elysia` not `@sentry/bun` + custom plugin
+- Why `@sentry/elysia` not `@sentry/node` (compiled binary landmine)
+- Client env split reasoning (ADR 0005 or equivalent)
+- PDPA/privacy scrubbing rationale
+- Alpha-state risk acceptance if applicable
+- Generic env naming rationale

package/skills/c9n-sentry/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: c9n-sentry
+description: Scaffold Sentry error tracking in a Bun + ElysiaJS + Next.js monorepo via a shared @repo/sentry package. Use when user wants to add Sentry, set up error tracking, or wire error monitoring to an ElysiaJS API and/or Next.js frontend in a Turborepo monorepo.
+---
+
+# 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.

package/skills/c9n-spec/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: c9n-spec
+description: Scaffold the C9N spec-driven, ISO/IEC 29110-aligned agentic documentation system INTO a repo — AGENTS.md (protocol + stack) with a CLAUDE.md bridge, CONTEXT.md glossary, DESIGN.md, the docs/ tree (SRS, architecture, traceability, test-plan, ADRs, feature stubs, agent docs), and the PR-template merge gate. Use when bootstrapping a new C9N project, "init docs", "set up the spec-driven docs", "add the agentic workflow files", or porting the ddg-jewelry doc system to another repo. Complements c9n-deliverables (that generates docs OUT of a codebase; this seeds the doc system INTO one).
+---
+
+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-spec/templates/.github/pull_request_template.md

@@ -0,0 +1,29 @@
+<!-- See AGENTS.md › Spec-Driven Development Protocol for the workflow and behavior-change rule. -->
+
+## What & why
+
+<!-- Ticket ID + one-line summary. Link the approved SRS/Design if this is a feature. -->
+
+## Spec-driven gate
+
+- [ ] For a **new feature**: SRS approved (Gate 1) and Design + Test Plan approved (Gate 2) **before** this code.
+- [ ] This PR links the relevant `docs/features/<name>.md` (or master SRS section).
+
+## Behavior-change check
+
+> Does this change **observable behavior, a requirement, an interface, or a test outcome**?
+
+- [ ] **No** — refactor / rename / dep-bump / typo / format. Doc updates N/A. _(skip the next section)_
+- [ ] **Yes** — complete the doc-update checklist below.
+
+### Doc updates (only if "Yes" above)
+
+- [ ] SRS updated (new/changed requirement) — `docs/SRS.md` or `docs/features/<name>.md`
+- [ ] Design updated (behavior/architecture) — `docs/architecture.md` or feature `## Design` (+ ADR if hard-to-reverse)
+- [ ] Test cases updated/added (incl. regression for bug fixes)
+- [ ] Traceability updated — `docs/traceability.md` or feature `## Traceability`
+
+## Verification
+
+- [ ] Tests pass locally
+- [ ] Lint/format clean (no semicolons, double quotes)