create-rigel 0.1.0

package/templates/express/.claude/skills/03-write-plan/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: 03-write-plan
+description: /write-plan — Write an Execution Plan
+verified: 2026-06-19
+libraries: []
+source: docs/PLANS.md
+note: Process skill — no library dependencies, no freshness check needed.
+---
+
+# /write-plan — Write an Execution Plan
+
+Triggered by: `/write-plan`
+
+---
+
+## Step 1 — Find Ready Spec
+
+```bash
+ls docs/product-specs/ready/
+```
+
+If none → tell human to mark a spec READY first. Stop.
+If multiple → list them and ask which one to plan.
+
+> A large spec may span MULTIPLE plans — slice it into shippable milestones, each its own
+> `PLAN-XXX` that ends green (e.g. data model + CRUD; then an external integration; then
+> reporting). Plans are numbered independently, so just create the next plan for the same spec.
+
+## Step 2 — Get Next Plan Number
+```bash
+ls docs/exec-plans/{active,completed}/ 2>/dev/null | grep "PLAN-" | sort | tail -1
+```
+Increment by 1. Start at PLAN-001 if none.
+
+## Step 3 — Read the Spec
+Read the full READY spec. Identify:
+- All entities → determine model + migration + repo + service files
+- All endpoints → determine route files
+- Any background jobs → determine worker files
+- State machines → note in service layer
+- Non-functional requirements → note in tests layer
+
+## Step 4 — Write the Plan
+
+Save to: `docs/exec-plans/active/PLAN-XXX-{slug}.md`
+
+```markdown
+# PLAN-XXX — {Feature Name}
+
+**Status:** IN_PROGRESS
+**Spec:** docs/product-specs/ready/SPEC-XXX-{slug}.md
+**Created:** YYYY-MM-DD
+**Completed:** —
+
+---
+
+## Goal
+{One sentence: what does this plan deliver?}
+
+---
+
+## Layer Build Order
+
+| # | Layer | Files | Gate Focuses On |
+|---|---|---|---|
+| 1 | Types | `src/types/{entity}.types.ts`, `common.types.ts` | Zero imports, zero logic |
+| 2 | Config | `src/config/env.ts` update, `constants.ts` | No process.env elsewhere |
+| 3 | Models | `src/models/{Entity}.model.ts` × N | paranoid, UUIDv7, indexes |
+| 4 | Migrations | `db/migrations/YYYYMMDD-create-{table}.js` × N | Runs clean, has down() |
+| 5 | Repo | `src/repo/{entity}.repo.ts` × N | Zod parse, cursor pagination, ownership, no N+1 |
+| 6 | Service | `src/services/{domain}.service.ts` × N | No express imports, ≥90% coverage |
+| 7 | Runtime | `src/runtime/routes/v1/{resource}.route.ts` × N | Auth first, envelope, rate-limit |
+| 8 | Workers | `src/runtime/workers/{name}.worker.ts` × N | Zod payload, retry, observability |
+| 9 | Tests | `tests/unit/`, `tests/integration/` | Coverage gates, load test |
+
+*(Remove rows that don't apply to this feature)*
+
+---
+
+## Acceptance Criteria
+{Copy from spec — these become the final gate}
+- [ ] criterion
+- [ ] criterion
+
+---
+
+## Progress Log
+
+### {date} — Plan created
+- Spec {SPEC-XXX} confirmed READY
+- {N} layers planned
+
+---
+
+## Decision Log
+
+*(Filled during build)*
+
+---
+
+## Known Constraints
+{Any technical decisions already made or constraints from the spec}
+```
+
+## Step 5 — Update Spec
+In `docs/product-specs/ready/SPEC-XXX.md`, **APPEND** `PLAN-XXX` to the `**Plan:**` field — do
+not overwrite. A spec split across multiple plans lists them all (e.g. `**Plan:** PLAN-003, PLAN-007`).
+If the field is still `—`, replace it with `PLAN-XXX`.
+
+## Step 6 — Update Index
+In `docs/product-specs/index.md`: update status to `PLANNED`
+
+## Step 7 — Tell the Human
+```
+Plan written: docs/exec-plans/active/PLAN-XXX-{slug}.md
+
+{N} layers planned. Build order:
+  1. Types
+  2. Config
+  ...
+
+Run /build-layer to start Layer 1.
+Claude will automatically find the next unchecked layer each time.
+```

package/templates/express/.claude/skills/04-build-layer/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: 04-build-layer
+description: /build-layer — Build Next Layer from Active Plan
+verified: 2026-06-04
+libraries: [express, sequelize, sequelize-typescript, zod, jose, bullmq, pino]
+source: https://www.npmjs.com
+staleness-threshold-days: 60
+---
+
+# /build-layer — Build Next Layer from Active Plan
+
+Triggered by: `/build-layer` (no argument — reads active plan automatically)
+
+---
+
+## Step 1 — Find the Active Plan and Next Layer
+
+```bash
+# Find active plan
+PLAN=$(ls docs/exec-plans/active/*.md 2>/dev/null | head -1)
+
+if [[ -z "$PLAN" ]]; then
+  echo "No active plan found. Run /write-plan first."
+  exit 1
+fi
+
+echo "Active plan: $PLAN"
+cat "$PLAN"
+```
+
+Parse the **Build Order** table in the plan.
+Find the first row with `[ ]` (unchecked) — this is the layer to build.
+If all rows are `[x]` (checked) → all layers complete, run `/garbage-collect`.
+
+---
+
+## Step 2 — Load Context for This Layer
+
+Read these files before writing a single line of code:
+1. The active plan (already loaded)
+2. The spec linked in the plan (`docs/product-specs/ready/SPEC-XXX.md`)
+3. `ARCHITECTURE.md` — layer rules
+4. The path-scoped rule for this layer type:
+   - Types → `.claude/rules/architecture.md`
+   - Config → `.claude/rules/architecture.md`
+   - Models → `.claude/rules/database.md`
+   - Repo → `.claude/rules/database.md` + `.claude/rules/security.md`
+   - Service → `.claude/rules/architecture.md` + `.claude/rules/security.md`
+   - Runtime → `.claude/rules/api.md` + `.claude/rules/security.md`
+   - Workers → `.claude/rules/jobs.md`
+   - Tests → `.claude/rules/testing.md`
+
+---
+
+## Step 3 — Build the Layer
+
+Write only the files for this layer. Follow the layer rules exactly.
+
+### Layer-specific what-to-build guide:
+
+**Types layer** — `src/types/`
+- One file per domain entity: `{entity}.types.ts`
+- Interfaces, enums, Zod schemas, type aliases
+- `common.types.ts` for shared types: `PageCursor`, `PageResult<T>`, `ApiSuccess<T>`, `ApiError`
+- Zero imports. Zero logic.
+
+**Config layer** — `src/config/`
+- Update `env.ts` if new env vars needed (add to Zod schema + `.env.example`)
+- `constants.ts` for domain constants (stage arrays, limits, etc.)
+
+**Models layer** — `src/models/`
+- One file per entity: `{Entity}.model.ts`
+- Sequelize-typescript decorators
+- `paranoid: true` on every `@Table`
+- `@Default(() => newId())` on every `id` column
+- `indexes` array defined on `@Table` for FK + ORDER BY columns
+- Export all models from `src/models/index.ts`, and register them there with
+  `sequelize.addModels([...])` (`import 'reflect-metadata'` first). Config and runtime must not
+  import the models layer — `models → config` is the legal registration edge.
+
+**Migrations layer** — `db/migrations/`
+- One migration per table: `YYYYMMDDHHMMSS-create-{table}.js`
+- `up`: createTable + addIndex (CONCURRENTLY for new indexes)
+- `down`: dropTable
+- Run: `npx sequelize-cli db:migrate` to verify
+
+**Repo layer** — `src/repo/`
+- One file per entity: `{entity}.repo.ts`
+- EVERY method: `Schema.parse(raw.toJSON())` on results
+- List methods: cursor-based pagination (Op.lt on createdAt + id)
+- Ownership: `findOne({ where: { id, userId } })` — never `findByPk(id)` alone
+- Zod schemas for all entity shapes
+- Export from `src/repo/index.ts`
+
+**Service layer** — `src/services/`
+- One file per domain: `{domain}.service.ts`
+- Takes domain types as input, returns domain types
+- NO `Request`, `Response`, `express` imports
+- Business logic lives here: state machines, validations, orchestration
+- External calls → via Repo layer
+- Async jobs → enqueue via queue (don't process inline)
+- Wrap multi-table operations in `sequelize.transaction()`
+
+**Runtime layer** — `src/runtime/routes/v1/`
+- One file per resource: `{resource}.route.ts`
+- Handler order: auth → validate → service → respond → catch
+- All routes under `/api/v1/`
+- Use `ok()` and `err()` helpers for all responses
+- Rate limiting applied at router level
+
+**Workers layer** — `src/runtime/workers/`
+- One file per queue: `{name}.worker.ts`
+- Validate payload with Zod first
+- Log start/complete/failed
+- Re-throw on error (BullMQ handles retry)
+- Register shutdown hook in server.ts
+
+**Tests layer** — `tests/`
+- `tests/unit/services/{service}.test.ts` — service layer
+- `tests/unit/utils/{util}.test.ts` — utils
+- `tests/integration/{feature}.test.ts` — route-level
+- `tests/integration/{resource}.isolation.test.ts` — REQUIRED for every owned resource
+  (copy `tests/integration/isolation.test.template.ts`); `tests/architecture/isolation.test.ts`
+  fails the gate if a userId-scoped repo has no matching isolation test
+- Meet coverage thresholds from `.claude/rules/testing.md`
+
+---
+
+## Step 4 — Run Gate
+
+Call the `gate-checker` agent with the layer name.
+
+**If FAIL:**
+- Read each ITEM from the gate report
+- Fix it automatically (no asking the human)
+- Log: `[Auto-fix] item description → fix applied`
+- Re-run gate (max 3 attempts)
+- If still failing after 3 attempts → present to human with specific blocker
+
+**If PASS:**
+- Tick the checkbox in the plan:
+  `- [ ] Layer N: Types` → `- [x] Layer N: Types`
+- Write ADR if any non-obvious decision was made during this layer
+
+---
+
+## Step 5 — Write ADR (if needed)
+
+An ADR is needed when you made a decision that a future engineer would question.
+Examples: chose approach A over B, moved responsibility between layers, added a constraint.
+
+```markdown
+# ADR-XXX — [Short Decision Title]
+
+**Date:** YYYY-MM-DD
+**Plan:** PLAN-XXX Layer N
+**Status:** ACCEPTED
+
+## Context
+What situation forced this decision?
+
+## Decision
+What was chosen.
+
+## Alternatives Considered
+- Option A: [why not chosen]
+- Option B: [why not chosen]
+
+## Consequences
+What this decision costs / enables.
+```
+
+Save to: `docs/design-docs/decisions/ADR-XXX-{slug}.md`
+Update: `docs/design-docs/decisions/index.md`
+
+---
+
+## Step 6 — Commit and Push
+
+```bash
+git add -A
+git commit -m "{type}({scope}): {description}
+
+{bullet points of what was built}
+
+PLAN-XXX Layer N/Total"
+
+git push origin main
+```
+
+Conventional commit types: `feat`, `fix`, `chore`, `refactor`, `test`, `docs`
+Scope: layer name (types, config, models, repo, service, runtime, worker, tests)
+
+---
+
+## Step 7 — Report to Human
+
+```
+═══════════════════════════════════════════
+✅ Layer N ({layer-name}) — COMPLETE
+═══════════════════════════════════════════
+Files created: [list]
+Gate attempts: 1 (or N with auto-fixes)
+Auto-fixed:    [list of fixes if any]
+ADR written:   ADR-XXX / None needed
+Committed:     [commit hash]
+
+Progress: [x] Layer 1 [x] Layer 2 [ ] Layer 3 ...
+
+Ready for Layer N+1: {next-layer-name}
+Confirm to continue? [human must respond]
+═══════════════════════════════════════════
+```
+
+**Wait for human confirmation before building the next layer.**
+Human response of "yes", "y", "continue", "proceed" or similar → start next layer.

package/templates/express/.claude/skills/05-validate-layer/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: 05-validate-layer
+description: /validate-layer — Run Gate Check Without Building
+verified: 2026-06-04
+libraries: []
+source: .claude/agents/gate-checker.md
+note: Process skill — delegates to gate-checker agent, no library dependencies.
+---
+
+# /validate-layer — Run Gate Check Without Building
+
+Triggered by: `/validate-layer`
+Use ad-hoc to check any layer at any time.
+
+---
+
+## What It Does
+Calls the `gate-checker` agent on the current state of `src/`.
+Does NOT build anything. Does NOT commit anything.
+Useful for: checking state mid-build, verifying after manual edits.
+
+## Steps
+
+1. Determine which layer to check:
+   - Read `docs/exec-plans/active/PLAN-XXX.md`
+   - Find the most recently checked layer (last `[x]`)
+   - Or ask the human: "Which layer do you want to validate?"
+
+2. Call `gate-checker` agent with the layer name
+
+3. Present the full PASS/FAIL report
+
+4. If FAIL: list items but do NOT auto-fix (this is an inspection tool)
+   - To auto-fix: run `/build-layer` which includes auto-fix logic
+
+## Output
+```
+VALIDATION REPORT — Layer: {name}
+{full gate output}
+
+This was a read-only validation.
+To auto-fix failures: run /build-layer
+```

package/templates/express/.claude/skills/06-push-layer/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: 06-push-layer
+description: /push-layer — Commit and Push Current Layer
+verified: 2026-06-04
+libraries: []
+source: git
+note: Process skill — git operations only, no library dependencies.
+---
+
+# /push-layer — Commit and Push Current Layer
+
+Triggered by: `/push-layer`
+Called automatically by /build-layer after gate passes.
+Can be called manually if needed.
+
+---
+
+## Steps
+
+1. Check gate status:
+   ```bash
+   # Run quick gate check before allowing push
+   npx tsc --noEmit && npx eslint src/ --max-warnings=0
+   ```
+   If either fails → abort and tell human to fix or run `/build-layer`
+
+2. Stage all changes:
+   ```bash
+   git add -A
+   git status  # show what's being committed
+   ```
+
+3. Determine commit message from active plan:
+   - Read plan → find most recently completed layer
+   - Format: `{type}({layer}): {description}`
+
+4. Commit:
+   ```bash
+   git commit -m "{conventional commit message}"
+   ```
+
+5. Push:
+   ```bash
+   git push origin $(git branch --show-current)
+   ```
+
+6. Report:
+   ```
+   Pushed: {commit hash} — {message}
+   Branch: {branch name}
+   ```
+
+## Conventional Commit Types
+- `feat` — new feature layer (types, service, runtime)
+- `chore` — infrastructure, config, migrations
+- `test` — test layer
+- `refactor` — refactoring existing layer
+- `fix` — fixing a bug in existing layer
+- `docs` — documentation only

package/templates/express/.claude/skills/07-layer-check/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: 07-layer-check
+description: /layer-check — Ad-hoc Architecture Violation Scan
+verified: 2026-06-04
+libraries: []
+source: ARCHITECTURE.md
+note: Process skill — architecture scan, no library dependencies.
+---
+
+# /layer-check — Ad-hoc Architecture Violation Scan
+
+Triggered by: `/layer-check`
+Scans the entire codebase for architecture violations right now.
+Does not require an active plan.
+
+---
+
+## Scans
+
+```bash
+echo "=== 1. Circular Imports ==="
+npx madge --circular src/ --extensions ts
+
+echo "=== 2. File Size Violations ==="
+find src/ -name "*.ts" | xargs wc -l | awk '$1 > 400 { print "VIOLATION:", $2, $1, "lines" }' | sort -rn
+
+echo "=== 3. console.log in src/ ==="
+grep -rn "console\.\(log\|error\|warn\|info\)" src/ \
+  --include="*.ts" \
+  --exclude-dir="config"
+
+echo "=== 4. process.env outside config ==="
+grep -rn "process\.env" src/ --include="*.ts" | grep -v "src/config/env.ts"
+
+echo "=== 5. TypeScript compilation ==="
+npx tsc --noEmit 2>&1
+
+echo "=== 6. ESLint ==="
+npx eslint src/ --max-warnings=0 2>&1
+
+echo "=== 7. Architecture structural tests ==="
+npx jest tests/architecture/ --no-coverage --verbose 2>&1
+
+echo "=== 8. Unsafe casts in repo ==="
+grep -rn "return raw as\|as Application\|as User\|as Note" src/repo/ --include="*.ts"
+```
+
+## Output
+```
+LAYER CHECK — {timestamp}
+
+Circular imports:     NONE / {list}
+File size violations: NONE / {list}
+console.log:          NONE / {list}
+process.env:          NONE / {list}
+TypeScript:           CLEAN / {errors}
+ESLint:               CLEAN / {errors}
+Arch tests:           PASS / FAIL
+Unsafe casts in repo: NONE / {list}
+
+OVERALL: ✅ CLEAN  /  ❌ {N} violations
+```

package/templates/express/.claude/skills/08-garbage-collect/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: 08-garbage-collect
+description: /garbage-collect — End-of-Feature Cleanup
+verified: 2026-06-04
+libraries: []
+source: docs/QUALITY_SCORE.md
+note: Process skill — cleanup workflow, no library dependencies.
+---
+
+# /garbage-collect — End-of-Feature Cleanup
+
+Triggered by: `/garbage-collect`
+Run after every feature is complete (all plan layers checked off).
+
+---
+
+## Steps (run in order, auto-fix everything)
+
+### 1. File Size
+```bash
+find src/ -name "*.ts" | xargs wc -l | awk '$1 > 400 { print $2, $1 }' | sort -rn
+```
+For any file over 400 lines: split it. Update imports everywhere.
+
+### 2. Layer Violations
+```bash
+npx madge --circular src/ --extensions ts
+npx eslint src/ --max-warnings=0
+```
+Fix any violations.
+
+### 3. Stale Documentation
+- Read `AGENTS.md` — does it list all current skills and agents?
+- Read `ARCHITECTURE.md` — does it match current source structure?
+- Read `docs/design-docs/decisions/index.md` — are all ADRs listed?
+Update anything stale.
+
+### 4. Update QUALITY_SCORE.md
+```bash
+npm test -- --coverage --coverageReporters=text 2>&1 | grep -A20 "Coverage summary"
+```
+Update grade for every domain touched in this feature.
+
+### 5. Log Tech Debt
+Any shortcuts taken → add to `docs/exec-plans/tech-debt-tracker.md`.
+
+### 6. Close the Plan
+- Read active plan
+- Confirm ALL layer checkboxes are `[x]`
+- Confirm ALL acceptance criteria are checked (or note which aren't and why)
+- Set `**Status:** COMPLETE` and `**Completed:** YYYY-MM-DD`
+- Move: `docs/exec-plans/active/PLAN-XXX.md` → `docs/exec-plans/completed/PLAN-XXX.md`
+
+### 7. Mark Spec Shipped
+- In `docs/product-specs/ready/SPEC-XXX.md`: set `**Status:** SHIPPED`
+- In `docs/product-specs/index.md`: update row status
+
+### 8. Final Commit
+```bash
+git add -A
+git commit -m "chore: garbage collect — close PLAN-XXX
+
+- QUALITY_SCORE.md updated: [domain: grade, ...]
+- Tech debt logged: [N] items
+- PLAN-XXX → completed/
+- SPEC-XXX marked SHIPPED"
+git push origin main
+```
+
+### 9. Report
+```
+═══════════════════════════════════════
+GARBAGE COLLECT COMPLETE
+═══════════════════════════════════════
+Files split:         N
+Violations fixed:    N
+Stale docs updated:  N
+Quality scores:
+  {domain}: {grade} ({coverage}%)
+Debt logged:         N items (see tech-debt-tracker.md)
+Plan closed:         PLAN-XXX
+Spec shipped:        SPEC-XXX
+
+Next: /write-spec for the next feature
+═══════════════════════════════════════
+```

package/templates/express/.claude/skills/09-doc-garden/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: 09-doc-garden
+description: /doc-garden — Scan and Fix Stale Documentation
+verified: 2026-06-04
+libraries: []
+source: AGENTS.md
+note: Process skill — documentation sync, no library dependencies.
+---
+
+# /doc-garden — Scan and Fix Stale Documentation
+
+Triggered by: `/doc-garden`
+
+---
+
+## What It Checks
+
+### 1. AGENTS.md
+- Lists all skills that exist in `.claude/skills/`?
+- Lists all agents that exist in `.claude/agents/`?
+- Navigation table matches actual `docs/` structure?
+
+### 2. ARCHITECTURE.md
+- Layer definitions match what's actually in `src/`?
+- Directory structure example is current?
+
+### 3. docs/product-specs/index.md
+- Every spec file in `draft/` and `ready/` has a row?
+- Status column matches actual file status?
+
+### 4. docs/exec-plans/tech-debt-tracker.md
+- RESOLVED items not cluttering the open list?
+
+### 5. docs/design-docs/decisions/index.md
+- Every ADR file in `decisions/` is listed?
+
+### 6. .env.example
+- Every variable in `src/config/env.ts` EnvSchema has a row in `.env.example`?
+
+## Steps
+For each stale item found:
+1. Update the document to match reality
+2. Note what was changed
+
+## Report
+```
+DOC GARDEN COMPLETE — {timestamp}
+
+Updated:
+  - AGENTS.md: added {skill} to slash commands table
+  - docs/product-specs/index.md: synced 2 spec statuses
+  - .env.example: added {NEW_VAR} from env.ts
+
+No changes needed:
+  - ARCHITECTURE.md ✓
+  - tech-debt-tracker.md ✓
+```
+
+Commit if anything changed:
+```bash
+git add docs/ AGENTS.md ARCHITECTURE.md .env.example
+git commit -m "docs: doc garden — sync stale documentation"
+git push origin main
+```