@codepassion/skills 1.1.1 → 1.4.0

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)

package/skills/c9n-spec/templates/AGENTS.md

@@ -0,0 +1,179 @@
+# AGENTS.md
+
+AI-assisted development context for the **{{PROJECT_NAME}}** repo.
+
+> This is the canonical agent file. `CLAUDE.md` is a one-line pointer to it. Codex, Cursor,
+> OpenCode, and Claude Code all read this file.
+
+## Spec-Driven Development Protocol (read first)
+
+This repo follows a spec-driven, ISO/IEC 29110-aligned documentation system (Software
+Implementation work products). This section is the **canonical source** — agents MUST follow it.
+The repo is authoritative.
+
+### Doc map
+
+| File                                           | ISO 29110 work product     | Holds                                                                        |
+| ---------------------------------------------- | -------------------------- | ---------------------------------------------------------------------------- |
+| `AGENTS.md` / `CLAUDE.md`                       | — (agent protocol)         | This protocol + stack + patterns                                             |
+| [`CONTEXT.md`](CONTEXT.md)                       | Domain glossary            | Ubiquitous language only — no implementation                                 |
+| [`DESIGN.md`](DESIGN.md)                         | — (visual design system)   | UI design language: color/type/component **intent & rules** (values in code) |
+| [`docs/SRS.md`](docs/SRS.md)                     | Requirements Specification | Master registry: features + requirement IDs + system NFRs                    |
+| [`docs/architecture.md`](docs/architecture.md)   | Software Design            | System map, module boundaries, data model, integrations                      |
+| [`docs/traceability.md`](docs/traceability.md)   | Traceability Record        | Master index: requirement → design → test                                    |
+| [`docs/test-plan.md`](docs/test-plan.md)         | Test Cases & Procedures    | Master test strategy                                                         |
+| `docs/adr/NNNN-*.md`                            | Architecture Decisions     | One ADR per hard-to-reverse decision                                         |
+| `docs/features/<name>.md`                       | Per-feature deep doc       | Sections: Requirements · Design · Test Plan · Test Cases · Traceability      |
+
+**Master-then-split (two levels):** a feature starts as a section in the master files →
+graduates to its own `docs/features/<name>.md` when it outgrows the section → graduates to a
+folder `docs/features/<name>/` (one file per section) only when a _section_ outgrows one file.
+Default to the smallest form that fits.
+
+**Feature ID:** every functional feature has a unique **short-code** — a 2–4 letter
+human-readable mnemonic (`PAY`, `INV`, `AUTH`). The short-code _is_ the feature ID; it prefixes
+all the feature's child IDs. Short-codes are **append-only** — pick a fresh, unused one for a new
+feature (check `docs/SRS.md`), and never reuse one even after a feature is removed. `docs/SRS.md`
+is the authoritative registry.
+
+**Child IDs:** feature-prefixed, append-only — `PAY-REQ-001` (requirement), `PAY-TC-001` (test
+case). Never reuse or renumber.
+
+**"Design" disambiguation:** `DESIGN.md` = **visual** design (UI). The `## Design` sections in
+`docs/features/*.md` and `docs/architecture.md` = **software** design (engineering). Different
+layers — don't conflate them.
+
+### Approval gates (no code before blueprint)
+
+A new feature passes three sequential gates, each needing the owner's sign-off:
+
+1. **SRS approved** — the _what_ (requirements + acceptance criteria).
+2. **Design + Test Plan approved** — the _how_ + how we'll prove it.
+3. **Code** — only now. The PR links the approved docs.
+
+### Definition of Ready (before touching code)
+
+1. Read [`CONTEXT.md`](CONTEXT.md) (glossary) and [`docs/architecture.md`](docs/architecture.md) (system map).
+2. Identify the feature; read its `docs/features/<name>.md` (or its master SRS section).
+3. For **UI work**, also read [`DESIGN.md`](DESIGN.md) first.
+4. For a **new feature**, Gate 1 **and** Gate 2 must already be approved. **No production code
+   before Gate 2 sign-off.**
+
+### Definition of Done (before opening the PR)
+
+Apply the **behavior-change rule**: update docs **iff** the change alters observable behavior, a
+requirement, an interface, or a test outcome.
+
+| Change kind                                  | Doc action                                                     |
+| -------------------------------------------- | -------------------------------------------------------------- |
+| New/changed requirement                      | Update SRS + traceability + test cases                         |
+| Behavior/architecture change                 | Update design (+ ADR if hard-to-reverse) + affected test cases |
+| Bug fix toward spec                          | Add a regression test case                                     |
+| Visual _intent_ change                       | Update `DESIGN.md`                                             |
+| Token _value_ change in Tailwind/CSS         | No doc update (`DESIGN.md` references values, never copies)    |
+| Refactor / rename / dep-bump / typo / format | No doc update (code-only PR)                                   |
+
+The `.github/pull_request_template.md` checklist is the merge gate.
+
+### Reverse-documentation policy
+
+Existing shipped modules each get an **as-built stub** in `docs/features/` (reverse-documented
+from code, **not grilled** — requirements describe current behavior at low confidence, no test
+cases). When a module is next touched, **deepen its stub** to the full chain (acceptance criteria
++ Test Cases + Traceability) for the part you change — don't try to deepen the whole stub at once.
+New features still get the full chain up front via the gates.
+
+## C9N engineering conventions (referenced, not duplicated)
+
+These follow the Code Passion skill family — the single source of truth. Don't restate the rules
+here; consult the skill:
+
+| Topic            | Skill                       |
+| ---------------- | --------------------------- |
+| Commit messages  | `c9n-commit-messages`       |
+| Git branching    | `c9n-git-branching`         |
+| Pull requests    | `c9n-pull-requests`         |
+| Code review      | `c9n-code-review`           |
+| Clean Code (TS)  | `c9n-clean-code-typescript` |
+| ESLint / types   | `c9n-typescript-eslint`     |
+| Formatting       | `c9n-code-formatting`       |
+| SemVer / deploy  | `c9n-semver-deployment`     |
+
+Install: `npx @codepassion/skills install claude`.
+
+## Tech Stack
+
+C9N defaults — trim rows this project doesn't use.
+
+| Layer      | Technology                                       |
+| ---------- | ------------------------------------------------ |
+| Runtime    | Bun                                              |
+| API        | ElysiaJS                                         |
+| Frontend   | Next.js / React (or Astro)                       |
+| Database   | PostgreSQL via Drizzle ORM                       |
+| Storage    | Supabase Storage + Auth                          |
+| Build      | Turborepo (monorepo)                             |
+| Validation | Zod (shared with Drizzle via drizzle-zod)        |
+| Lint       | ESLint + Prettier (no semicolons, double quotes) |
+| Commits    | Conventional Commits (commitlint + Husky)        |
+
+## Project Structure
+
+<!-- Describe the actual repo layout here. C9N monorepo default: -->
+
+```text
+{{PROJECT_NAME}}/
+  apps/
+    api/        -- backend (if any)
+    web/        -- frontend (if any)
+  packages/
+    database/   -- Drizzle ORM schemas + client
+    ...
+```
+
+<!-- =========================================================================
+     API MODULE PATTERNS — delete this whole section for a web-only repo.
+     ========================================================================= -->
+
+## API Module Structure (delete if no backend)
+
+Each feature lives under `apps/api/src/modules/<feature>/`:
+
+```text
+modules/<feature>/
+  models/      -- Zod schemas + types as namespace exports
+  use-cases/   -- Business logic as abstract static classes
+  services/    -- External API / infrastructure integrations
+  models.ts    -- Barrel export
+  use-cases.ts -- Barrel export
+  constants.ts -- Shared constants
+  types.ts     -- Shared TS interfaces
+  index.ts     -- Elysia route definitions
+```
+
+### Key patterns
+
+- **Models** — Zod `namespace` pattern; error messages as `z.literal()` so they're both
+  type-safe constants and response schema.
+- **Use cases** — `abstract class` with a public `static execute(...)`; private `static` helpers
+  hold the how. `execute()` reads like a table of contents (each line a clear step), no inline
+  env-extraction/conditional-throw/DB-query.
+- **Services** — same abstract-static shape, wrapping external integrations.
+- **Routes** — `new Elysia({ prefix })`; `throw status(404, "...")` for HTTP errors.
+- **Enum value objects** — `as const satisfies Record<string, T>` for type-safe dot access.
+
+<!-- ===================== END deletable API section ===================== -->
+
+## Environment Variables
+
+<!-- List required env vars and which module/package consumes each. -->
+
+| Variable       | Used by |
+| -------------- | ------- |
+| `DATABASE_URL` | …       |
+
+## Code Style
+
+Per `c9n-code-formatting` + `c9n-typescript-eslint`: no semicolons, double quotes, no trailing
+commas. Barrel exports per subdirectory. Use the project's error-reporting path (e.g.
+`Sentry.captureException`) — no `console.error`/`console.log` for errors.

package/skills/c9n-spec/templates/CLAUDE.md

@@ -0,0 +1,6 @@
+# {{PROJECT_NAME}}
+
+The canonical agent context for this repo is **AGENTS.md** (cross-tool standard). The import
+below pulls it into Claude Code's memory so the spec-driven protocol auto-loads.
+
+@AGENTS.md

package/skills/c9n-spec/templates/CONTEXT.md

@@ -0,0 +1,53 @@
+# {{PROJECT_NAME}} — Domain Glossary & Project Context
+
+> **Glossary only — no implementation detail.** This file is the ubiquitous language of the
+> project: what each term *means*. Code, schemas, and decisions live elsewhere (`docs/`). Keep it
+> a dictionary, not a spec. Produced/maintained via `/grill-with-docs`.
+
+## Actors
+
+<!-- Who interacts with the system, and how they authenticate / what they can do. -->
+
+### <Actor>
+
+- …
+
+## Core Entities
+
+<!-- The nouns of the domain. For each: code term, customer-facing term, definition,
+     statuses/lifecycle, key fields. Example shape below — replace it. -->
+
+### <Entity> (<local-language term if any>)
+
+- **Code term:** `<table_name>` (database), `/<route>` (API)
+- **Customer-facing term:** "…"
+- **Definition:** …
+- **Statuses:** … → … → …
+- **Lifecycle:** … → … → …
+
+## External Integrations
+
+<!-- Third-party services and what they do for the domain — not how they're wired. -->
+
+### <Service>
+
+- …
+
+## Data Model (Key Relationships)
+
+```
+<Entity A> → <Entity B> (1:N)
+…
+```
+
+## Key Business Decisions
+
+<!-- Domain rules a newcomer would get wrong. One line each. -->
+
+- …
+
+## Glossary Hygiene
+
+- When output names a domain concept, use the term **as defined here** — don't drift to synonyms.
+- If a needed concept isn't here yet: either you're inventing language the project doesn't use
+  (reconsider) or there's a real gap (resolve it via `/grill-with-docs`).