agentic-team 0.0.0-stage → 6.2.0

package/template/skills/android-testing/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: android-testing
+description: "Testing strategy for native Android apps — Kotlin, Compose, JUnit, Robolectric and instrumented tests. Use for any phase that writes or changes tests in a native Android app."
+---
+
+# Skill: Android Testing
+
+## The fact everything else follows from
+
+**A debug build passing proves very little about the release build.**
+
+R8 shrinks, optimises and obfuscates. Reflection stops resolving, a
+serialisation library loses the field names it needed, a keep rule that was
+never written removes a class the app loads by name. Every test is green,
+`assembleDebug` is fine, and the release APK crashes on launch.
+
+So `assembleRelease` belongs in the gate, not in the release checklist.
+
+## The layers
+
+| Layer | What belongs here | Runs on |
+|---|---|---|
+| Unit (JUnit) | Pure logic and view models — no Android framework | JVM, fast |
+| Compose UI | Semantics tree, state, interaction | **JVM via Robolectric** |
+| Integration | The real HTTP client against MockWebServer | JVM |
+| Instrumented | 3–5 journeys, one of them launch | Emulator |
+| Build | `assembleDebug` **and** `assembleRelease` | The gate |
+
+## Compose UI tests belong on the JVM
+
+`createComposeRule()` with Robolectric runs the real Compose runtime under
+the JVM — no emulator, seconds instead of minutes. That speed is what makes
+it realistic to test every component rather than a token few.
+
+Keep `androidTest` for the handful of journeys that genuinely need a device:
+permissions, the real keyboard, process death and restore.
+
+## The semantics tree is the accessibility tree
+
+```kotlin
+onNodeWithText("Add water").performClick()                  // yes
+onNodeWithContentDescription("Add water").performClick()    // yes
+onNodeWithTag("btn_add_water").performClick()               // last resort
+```
+
+Compose's semantics tree is what TalkBack reads. Query it and **a control
+with no text or content description fails the test** — accessibility becomes
+enforced rather than reviewed.
+
+`testTag` is for something with no user-visible identity at all. Reaching for
+it first hides exactly the bug the query would have found.
+
+## MockWebServer, not a mocked API interface
+
+```kotlin
+val server = MockWebServer()
+server.enqueue(MockResponse().setBody(json).setResponseCode(200))
+```
+
+Real OkHttp, real serialisation, real error mapping, real timeouts. Mocking
+the Retrofit interface instead skips every one of those — and they are where
+a dependency bump breaks you.
+
+It also lets you test what a mocked interface cannot: a 500, a truncated
+body, a socket timeout.
+
+## Never
+
+- **Screenshot tests as the main assertion.** They change with every
+  emulator image and get re-recorded unread.
+- Testing that Compose recomposes, or that Navigation navigates. Assert the
+  action fires with the right argument.
+- `Thread.sleep`. Compose has `waitUntil` and an idling clock; a sleep is a
+  flake with a delay.
+- Emulator-only verification. Emulators have no thermal throttling, no real
+  memory pressure, and an unrealistically fast disk.
+
+## Configuration coverage is a real axis
+
+The same code behaves differently across API level, screen size, locale,
+dark mode, and font scale. Robolectric can parameterise `@Config(sdk = [...])`
+cheaply — use it for the minSdk boundary at least, because that is where
+platform behaviour actually diverges.
+
+RTL and a large font scale break more layouts than any other setting. Both
+are one line to test and neither is ever tested by hand.
+
+## The JDK is a constraint, not a preference
+
+AGP's minimum is 17. Robolectric's stubbed jar for a recent API level
+refuses to start below **21** — `Android SDK 36 requires Java 21 (have Java
+17)` — and it reports that only after a full compile.
+
+So the toolchain is JDK 21, and `verify.sh` checks it up front where the
+message is actionable.
+
+Robolectric also lags the platform: its newest stubbed API level is behind
+`compileSdk`, so `robolectric.properties` pins `sdk` explicitly. Letting it
+inherit `targetSdk` fails every test before one runs.
+
+## Versions
+
+Gradle forbids a dynamic version, and rightly — a build must resolve the
+same way twice. That is a reason to write the version down, not a reason to
+write it from memory: the version catalog is generated from the repositories
+at scaffold time. See `.claude/rules/dependency-upgrade.orchestra.md`.
+
+## Release risk
+
+A Play Store release rolls back only for users who have not yet updated.
+Staged rollout and a server-side kill switch are part of the strategy, not an
+operational afterthought — see `.claude/rules/observability.orchestra.md`.

package/template/skills/architecture/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: architecture
+description: "Choosing the shape of a system — deployment units, service boundaries, data ownership, consistency and resilience. Use when writing an RFC, structuring a new app, or deciding whether something should be split out."
+---
+
+# Skill: Architecture
+
+Depth for the design stage. The artifact is `rfc.md`; see
+`.claude/agents/architect.md` for its shape and
+`.claude/rules/analytics-kpi.orchestra.md` for what has to be settled before
+any of this starts.
+
+## The fact everything else follows from
+
+**The default is one deployable unit, and leaving it needs an argument.**
+
+Almost every distributed architecture in a young product exists because it
+was chosen at the start, not because a boundary was discovered. The cost
+arrives later and lands on the one person maintaining it: two deploys to
+coordinate, a transaction that no longer commits, a failure mode that cannot
+be reproduced locally.
+
+A modular monolith gets you the boundary without the network. Modules with
+explicit interfaces, one process, one database, one deploy. When a module
+genuinely needs to scale or fail on its own, the boundary is already drawn
+and the extraction is mechanical.
+
+So: **YAGNI is an architecture rule here**, not a coding one.
+
+## Before the shape: the number
+
+A milestone that cannot say which number it should move is not ready to
+design. Read `milestone.md` for the KPI, its baseline, its target, and how it
+is read.
+
+If the design cannot say **where that number is produced** — which event,
+which query — the observability section of the RFC will be invented later,
+which is the same as not having one.
+
+## Choosing the shape
+
+Work down this list. Take the first row that is actually true, not the first
+that sounds ambitious.
+
+| If | Then | Because |
+|---|---|---|
+| You are starting, or the domain is still moving | **Modular monolith** | Boundaries are cheap to move while they are still wrong |
+| One part has a genuinely different scaling or failure profile | **Extract that one part** | A real reason, and only that part |
+| Separate teams must deploy without coordinating | **Services along team lines** | Conway's law is a constraint, not an observation |
+| Work is long-running, retryable, or bursty | **Queue + worker, same repo** | Async is a boundary you can add without splitting the deploy |
+| An audit trail is a product requirement | **Event sourcing for that aggregate** | Not for the whole system |
+| Load is spiky and idle most of the time | **Serverless for that endpoint** | Per-endpoint, not per-application |
+
+Two facts worth holding on to:
+
+- Below roughly ten engineers, microservices cost more than they return. The
+  overhead is operational and it does not shrink with team size.
+- You cannot skip a stage. Monolith → modular monolith → extracted service.
+  Each step teaches you where the boundary actually is; skipping straight to
+  services means guessing, and a wrong boundary is far more expensive than a
+  late one.
+
+## Drawing boundaries
+
+A module boundary is worth having when it satisfies all three:
+
+1. **It owns its data.** No other module reads its tables directly.
+2. **It has an interface you could call over a network** — even though you
+   are not going to. If the interface only works in-process, it is not a
+   boundary, it is a folder.
+3. **It can be tested through that interface**, against a real database. That
+   is the same seam the testing rule already demands, so drawing it well
+   makes the suite easier, not harder.
+
+If a proposed boundary fails any of these, it is naming, not structure.
+
+## Data
+
+- **One database until a second one is forced.** Two datastores means no
+  transaction spans them, and every write that must span them becomes a
+  distributed problem you now own forever.
+- **Consistency is a per-flow decision, not a system-wide one.** Money, quota
+  and permission changes are transactional. A read model, a feed, a counter
+  can lag.
+- When a flow genuinely spans two owners, choose deliberately: a transaction
+  if they share a database, an outbox if they do not. **Never a plain HTTP
+  call in the middle of a write path** — the failure between "committed" and
+  "notified" is the bug you will spend a week on.
+- Every schema change is forward-compatible with the release before it, and
+  a destructive change is two deploys. See
+  `.claude/skills/deployment/SKILL.md`.
+
+## Resilience
+
+Any call leaving the process — another service, a provider, a queue — needs
+all four. They are not optional extras, and they are cheap to add up front
+and painful to retrofit.
+
+| Control | Rule |
+|---|---|
+| **Timeout** | Always. A call with no timeout is a resource leak with a delay. Per-attempt timeout below the overall budget. |
+| **Retry** | Idempotent operations only, exponential backoff **with jitter**, bounded attempts. Retrying a non-idempotent write is how you double-charge someone. |
+| **Circuit breaker** | Open after consecutive failures; fail fast instead of queueing. Gives the dependency room to recover instead of holding it down. |
+| **Bulkhead** | Bound the pool — connections, concurrency, queue depth. One slow dependency must not consume every worker. |
+
+The fallback is part of the design, not an afterthought: state what the caller
+sees when the dependency is gone. For anything gating a risky path the
+fallback is **false** — the same rule the feature-flag registry follows in
+`.claude/rules/observability.orchestra.md`.
+
+Rate limiting is the mirror image, applied at your own edge. Decide the axis
+deliberately — per user, per key, per endpoint — because "requests per
+second" alone protects nothing when one caller owns all of them.
+
+## Operations belong in the design
+
+These are architecture, not launch tasks. Each one is already enforced
+somewhere; the design decides what goes in them.
+
+- **Every dependency the service cannot serve without gets a readiness
+  probe.** Anything missing from that map can be broken while a release is
+  promoted anyway.
+- **Every risky path ships behind a flag**, so it is turned off without a
+  deploy.
+- **The correlation id crosses every boundary you draw.** A trace that stops
+  at a module edge is a trace you cannot follow.
+- **Name what you would roll back to.** If undoing this milestone is not a
+  single revert, say so in the RFC's Risks section.
+
+## Say what you are not building
+
+The most useful part of a design is usually the exclusions. Write them down —
+the deferred cache, the second datastore, the abstraction over a provider you
+have exactly one of — with the condition that would change the answer.
+
+An abstraction with one implementation is a guess about the future, and it is
+usually wrong in a way that costs more than the migration would have. Extract
+after the second real case.
+
+## Decision records
+
+The RFC is the record for one milestone. A decision that **outlives** the
+milestone — a datastore, an auth model, a boundary, anything expensive to
+reverse — gets its own file in `docs/adr/`, numbered, with: context, the
+decision, the consequences, and the alternatives that were rejected and why.
+
+The rejected alternatives are the point. Six months on, the question is never
+"what did we choose", it is "did we already think about this".
+
+## Depth on the pieces
+
+- `.claude/skills/error-handling/SKILL.md` — what a failure returns, and the
+  difference between handling one and hiding it.
+- `.claude/skills/realtime/SKILL.md` — when a connection is worth its cost,
+  and what it does to deploys and scaling.
+- `.claude/skills/deployment/SKILL.md` — health, promotion, rollback,
+  migrations.
+- `.claude/skills/observability/SKILL.md` — wiring the monitoring the design
+  assumes.
+
+## Anti-patterns
+
+- **Distributed monolith.** Services that must be deployed together. You paid
+  the network cost and kept the coupling.
+- **Shared database between services.** The boundary is decorative; the
+  schema is the real interface and nobody owns it.
+- **Accidental complexity.** The architecture is more elaborate than the
+  domain. Symptom: explaining the system takes longer than explaining the
+  product.
+- **Golden hammer.** The same shape as the last project, chosen before the
+  problem was read.
+- **Vendor coupling in the core.** The provider belongs behind a module you
+  own — which is also the module the testing rule holds at 100%.
+- **Designing for a scale that has no baseline.** If the KPI has no number
+  today, the design cannot be sized. Say so rather than guessing.

package/template/skills/auth-setup/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: auth-setup
+description: "Authentication, login, signup, session management and user identity. The core decisions are already made and scaffolded — this says what they are, what is still open, and what to check when changing any of it. Use for any phase that establishes or changes who a request belongs to."
+---
+
+# Skill: Auth Setup
+
+## The decisions are made — do not re-open them
+
+This used to open with "choose auth strategy: JWT vs session-based vs OAuth"
+and recommend `bcrypt`, `jose` and `arctic`. The backend stack answered that
+question and shipped code, so re-asking it produces an app that disagrees with
+its own scaffold.
+
+| Decision | What ships | Where |
+|---|---|---|
+| Strategy | Opaque server-side sessions, not JWT | `src/features/auth/sessions.ts` |
+| Why | A session is revocable with a `DELETE`. A JWT is valid until it expires, which is why JWT designs need refresh rotation to claw revocation back | — |
+| Hashing | `node:crypto` scrypt, zero dependency | `src/lib/password.ts` |
+| Parameters | OWASP's N=2^14, r=8, p=5 set (16 MiB), not their 128 MiB primary — a login route allocating 128 MiB per attempt is the cheapest way to exhaust a small container. Measured, and the reason is in a comment beside it | — |
+| Token at rest | SHA-256 of the token, never the token | `sessions.ts` |
+| Transport | httpOnly cookie, `secure` in production, `SameSite=Lax` | `src/features/auth/routes.ts` |
+| CSRF | `SameSite=Lax` blocks the cross-site POST. Strict was rejected: it drops the cookie when someone arrives from an email link, which reads as a random sign-out | — |
+| Rate limit | 10/min on the auth routes, injectable so a test can drive it to the limit | `routes.ts` |
+| Browser lifetime | One session cookie, sliding: a 30-day **idle** window that rolls forward on use, under a 90-day **absolute** ceiling that never moves. OWASP asks for both, and they catch different things | `sessions.ts` |
+| Why no refresh token in a browser | Rotation exists to claw back revocation for a credential that cannot be revoked. This one is a row we delete. Splitting it would cost every client a 401-and-retry interceptor and buy nothing | — |
+| Native / API clients | `POST /auth/token` returns an access token and a rotating refresh token in the body — no cookies. RFC 9700 §2.2.2 asks for rotation for public clients, which a native app is and a first-party cookie session is not | `routes.ts`, `refresh.ts` |
+| Refresh rotation | On every use. A spent token presented again is theft, so the family and every session descended from it are revoked. The spend is a conditional update, so two racing requests cannot both get a successor | `refresh.ts` |
+| Social | Google and Apple, authorization code, zero dependency. `iss`, `aud`, `exp` and `nonce` are all checked; the signature is not, and the OIDC clause permitting that is cited in the code | `src/integrations/{google,apple}/`, `oauth.ts` |
+| Linking | On the provider's subject, never the email — an address can be reassigned, a subject cannot. An address the provider has not verified is refused rather than linked | `oauth.ts` |
+| Apple secret | An ES256 JWT signed per request with `dsaEncoding: "ieee-p1363"`. Node's default is DER, which Apple rejects as `invalid_client` | `integrations/apple/client.ts` |
+| Enumeration | Login compares against a dummy hash when the user does not exist, so the timing does not answer "does this account exist" | `DUMMY_HASH` |
+| Reset | Token hashed, one hour, and the password update, the token delete and the revocation of every session happen in one transaction | `src/features/auth/reset.ts` |
+
+If a phase needs something different, change it in
+`.orchestra/stacks/backend-hono/setup.sh` so the next project gets it too —
+see `.claude/rules/dependency-upgrade.orchestra.md` on fixing the stack rather
+than the project.
+
+## The one that gets re-opened
+
+Somebody will propose putting the browser on a short access token with a
+refresh token behind it, because that is what the OAuth material describes.
+It was tried here and reverted. The reasons, so they do not have to be
+rediscovered:
+
+- The access token is **opaque and checked against a row**, not a JWT. It is
+  revocable now. The short expiry in an OAuth design exists to bound damage
+  for tokens that cannot be revoked; that problem does not exist here.
+- A 15-minute cookie means **every client needs a 401-and-retry
+  interceptor**. Ship the server half alone and users appear signed out every
+  fifteen minutes.
+- Both cookies would be `httpOnly`, so XSS reaches neither, and anything that
+  can read the cookie jar reads both. The theft-detection win is much smaller
+  than it looks.
+
+Rotation is kept where it earns its complexity: a token in device storage on
+a native client, which is RFC 9700's public client.
+
+## What is genuinely still open
+
+These are not decided, and a phase that needs one has to design it:
+
+- **MFA.** Nothing here is a second factor.
+- **Account lockout** beyond rate limiting. Ten attempts a minute is a brake,
+  not a stop.
+- **Unlinking a provider.** Removing the last way into an account is the case
+  to get right: an account with no password and no linked provider cannot be
+  signed into by anybody.
+- **More providers.** The shape is in place; a third one is a new
+  `src/integrations/<provider>/` and a branch in `oauth.ts`. Check its
+  discovery document rather than assuming it looks like Google's — Apple
+  supports no PKCE and returns its callback as a cross-site POST, and both of
+  those had to be discovered rather than recalled.
+
+## Checks for any change to auth
+
+- [ ] The route is closed by default — `src/app.routes.test.ts` calls every
+      declared route with no cookie and fails on anything that is not 401.
+      A new route is caught by that test, not by remembering.
+- [ ] Failure paths return the **same** answer for unknown user, wrong
+      password and expired session. Different answers are an enumeration
+      oracle.
+- [ ] Anything that changes a credential revokes existing sessions **and
+      refresh tokens**, in the same transaction as the change. Sessions alone
+      accomplishes nothing: the refresh tokens outlive them and mint new ones.
+- [ ] The new path is rate limited if it accepts a secret.
+- [ ] Email is normalised — lowercased and trimmed — before lookup and before
+      storage, or the same person gets two accounts.
+- [ ] No token, hash, or password appears in a log line, an error body, or an
+      analytics property.
+- [ ] Tests cover success, failure, expiry, and the limit actually being hit.
+
+## Mistakes still worth naming
+
+- A credential comparison that returns early. Use a constant-time compare.
+- Rate limiting keyed only on IP. One NAT is one key; one botnet is thousands.
+- Reporting "user not found" separately from "wrong password".
+- A password change that leaves other sessions alive.
+- Widening a token's lifetime to fix an expiry bug. The bug is the refresh
+  path, not the number.
+- Trusting an id_token's `sub` without checking its `aud`. Any application
+  registered with the same provider can mint one otherwise.
+- Linking a social account to an existing user by an email address the
+  provider has not marked verified.

package/template/skills/best-practices/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: best-practices
+description: "Web application hardening — security headers, CSP, input handling, browser compatibility. Use for any phase preparing a web app for production."
+---
+
+# Skill: Best Practices
+
+## When to Use
+Phase involves web application security, compatibility, or production hardening.
+
+## Checklist
+- [ ] HTTPS everywhere — no mixed HTTP/HTTPS content
+- [ ] Content Security Policy (CSP) header configured
+- [ ] Security headers set: X-Frame-Options, X-Content-Type-Options, Referrer-Policy
+- [ ] No vulnerable dependencies (`npm audit` clean)
+- [ ] Feature detection, not browser detection (`if ('fetch' in window)` not `if (isChrome)`)
+- [ ] Valid HTML5 doctype, charset first in `<head>`
+- [ ] Viewport meta tag present: `<meta name="viewport" content="width=device-width, initial-scale=1">`
+- [ ] Passive event listeners for scroll/touch events
+- [ ] No `innerHTML` with user input — use `textContent` or sanitize
+- [ ] All user input validated + sanitized on both client and server
+
+## Common Mistakes
+- Mixed HTTP/HTTPS content → browsers block mixed requests
+- XSS via `innerHTML` or `dangerouslySetInnerHTML` without sanitization
+- Synchronous XHR blocking main thread → use `fetch` with async/await
+- Browser detection (`navigator.userAgent`) → breaks on new browsers, use feature detection
+- Missing security headers → easy attack vectors
+- Using `eval()` or `new Function()` with user input → code injection

package/template/skills/code-optimizer/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: code-optimizer
+description: "Performance work — query shape, memory, bundle, hot paths. Use for any phase that optimises existing code rather than adding behaviour."
+---
+
+# Skill: Code Optimizer
+
+## When to Use
+Phase involves performance optimization, refactoring for speed, or audit of existing code performance.
+
+## Checklist
+- [ ] **Database:** N+1 queries eliminated, proper indexes on WHERE/JOIN columns, connection pooling configured
+- [ ] **Memory:** No unbounded caches/arrays, streams used for large data, event listeners cleaned up
+- [ ] **Algorithmic:** No nested loops over large datasets (O(n^2)), use Map/Set for lookups instead of Array.find
+- [ ] **I/O:** Parallel fetch with `Promise.all` where independent, no sequential awaits for unrelated data
+- [ ] **Bundle:** No barrel file imports (`import { x } from './utils'`), use direct imports for tree-shaking
+- [ ] **Dead Code:** Remove unused imports, functions, files — verify with `npx tsc --noEmit` + grep
+- [ ] **Caching:** Expensive computations cached (LRU, memoize), HTTP cache headers set for static assets
+- [ ] **Rendering:** Avoid layout thrashing (batch DOM reads before writes), use `content-visibility: auto` for offscreen content
+
+## Common Mistakes
+- Sequential `await` for independent promises → use `Promise.all([a(), b(), c()])`
+- Importing from barrel files (`index.ts` re-exports) → prevents tree-shaking, bloats bundle
+- Array.find/filter in loops → O(n*m), convert to Map/Set for O(1) lookup
+- Missing database indexes on frequently queried columns → full table scans
+- Unbounded in-memory caches → memory leak over time, use LRU with max size
+- Not cleaning up event listeners, intervals, subscriptions → memory leak

package/template/skills/core-web-vitals/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: core-web-vitals
+description: "Frontend performance against LCP, INP and CLS. Use for any phase targeting page experience metrics or a Lighthouse score."
+---
+
+# Skill: Core Web Vitals
+
+## When to Use
+Phase involves frontend performance optimization targeting Google's page experience metrics.
+
+## Checklist
+- [ ] **LCP (Largest Contentful Paint) <= 2.5s:**
+  - Preload LCP image with `<link rel="preload" fetchpriority="high">`
+  - Inline critical CSS (< 14KB)
+  - No render-blocking JavaScript in `<head>` (defer or async)
+  - Server response time (TTFB) < 800ms
+- [ ] **INP (Interaction to Next Paint) <= 200ms:**
+  - No long tasks (> 50ms) on main thread — break up with `requestIdleCallback` or `scheduler.yield()`
+  - Event handlers return quickly — defer heavy work
+  - Avoid forced synchronous layouts (read then write DOM, not interleaved)
+- [ ] **CLS (Cumulative Layout Shift) <= 0.1:**
+  - All images/videos have explicit `width` and `height` or `aspect-ratio`
+  - No content injected above existing content after load
+  - Fonts use `font-display: swap` with `size-adjust` to minimize shift
+  - Reserve space for dynamic content (ads, embeds, lazy content)
+
+## Common Mistakes
+- Images without dimensions → causes layout shift on load
+- Web fonts blocking text rendering → use `font-display: swap`
+- Client-side rendering for LCP element → server-render or prerender it
+- Synchronous third-party scripts in `<head>` → blocks rendering
+- Dynamic banners/modals pushing content down → reserve space or use overlay

package/template/skills/crud-api/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: crud-api
+description: "Creating a resource with standard create/read/update/delete routes. Use for any phase adding a new REST or RPC resource."
+---
+
+# Skill: CRUD API
+
+## When to Use
+Phase involves creating a new resource with standard create/read/update/delete operations.
+
+## Checklist
+- [ ] Define resource schema (Zod or equivalent validation)
+- [ ] Create migration for DB table
+- [ ] Implement endpoints: POST (create), GET (list + detail), PUT/PATCH (update), DELETE
+- [ ] Add input validation on all mutation endpoints
+- [ ] Add pagination on list endpoint (cursor-based preferred over offset)
+- [ ] Add filtering and sorting on list endpoint
+- [ ] Return consistent error format (status code + message + details)
+- [ ] Add proper HTTP status codes: 201 (created), 200 (success), 404 (not found), 422 (validation)
+- [ ] Test all CRUD operations + edge cases (not found, duplicate, invalid input)
+
+## Common Mistakes
+- No pagination on list endpoints (will crash with large datasets)
+- Using offset pagination (slow on large tables) → use cursor-based
+- Not validating request body → runtime crashes
+- Returning 200 for everything → use semantic HTTP codes
+- DELETE without checking ownership → authorization bypass
+
+## Patterns
+- Schema → Type → Validation → Migration flow
+- Repository pattern for DB access (separate query logic from handler)
+- Consistent error response: `{ error: { code, message, details } }`

package/template/skills/debug/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: debug
+description: "Investigating a bug whose cause is not obvious — unexpected behaviour, a production incident, a flaky test. Use when the fix is not yet known."
+---
+
+# Skill: Debug
+
+## When to Use
+Phase involves investigating a complex bug, unexpected behavior, or production issue that isn't immediately obvious.
+
+## Checklist
+- [ ] **Document current state:** exact error message, steps to reproduce, expected vs actual behavior
+- [ ] **Map the system:** trace the execution path from input to error — which files, functions, APIs are involved?
+- [ ] **Gather evidence BEFORE hypothesizing:** read logs, check git blame, inspect network requests, check env vars
+- [ ] **Form hypotheses:** list 2-3 possible causes ranked by likelihood
+- [ ] **Test each hypothesis minimally:** change ONE thing, observe result, revert if wrong
+- [ ] **Check external factors:** dependency versions, API changes, environment differences (dev vs prod)
+- [ ] **Verify the fix:** reproduce the original bug, apply fix, confirm it's resolved, check for regressions
+- [ ] **Document root cause:** what happened, why, and what prevents it from recurring
+
+## Common Mistakes
+- Assuming the bug is where the error appears → trace upstream, the root cause is often elsewhere
+- Changing multiple things at once → can't tell which change fixed it
+- Not reproducing before fixing → you might fix a different bug
+- Treating your own code with less skepticism → YOUR code is the most likely source
+- Proposing fixes without evidence → "I think it might be X" without testing is guessing
+- Not checking if the bug exists in other environments → might be env-specific
+- Fixing the symptom, not the cause → bug will return in a different form

package/template/skills/deployment/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: deployment
+description: "Getting a service to production and back again — health, release gating, smoke, rollback, migrations. Use for any phase that touches CI/CD, containers, environment configuration, or a deploy."
+---
+
+# Skill: Deployment
+
+Implements `.claude/rules/observability.orchestra.md`. Read it first; this is
+the working checklist.
+
+## The fact everything else follows from
+
+**Nothing here protects a release except being able to undo it.**
+
+There is no percentage canary on the platforms this stack targets. What
+stands between a broken build and every user is three things, in order: the
+healthcheck that decides whether the new deployment is promoted, a smoke test
+against the real URL afterwards, and putting the last good commit back when
+that smoke fails.
+
+Rollback is the same path as a normal deploy, deliberately. An untested
+recovery path is not a recovery path.
+
+## Health is two endpoints
+
+| Endpoint | Question | Cost | Fails when |
+|---|---|---|---|
+| `/health` | is the process up? | no dependencies | it doesn't answer |
+| `/ready` | can it serve? | probes every dependency | **503**, naming the one that failed |
+
+The platform healthcheck points at **`/ready`**. This is load-bearing: the
+previous deployment keeps serving until the new one answers 200, so a
+readiness probe that returns 200 with an unreachable database does not
+mislead a dashboard — it promotes a broken release.
+
+- [ ] `/ready` probes every dependency the service cannot serve without
+- [ ] it answers 503 and names the failed dependency, not a bare status
+- [ ] there is a test that **makes it fail** — a probe that cannot fail is
+      worse than none
+- [ ] adding a dependency adds its probe and its failing test in the same
+      change
+- [ ] `healthcheckPath` in the platform config points at `/ready`, not
+      `/health`
+
+## Releasing
+
+- [ ] deploy is gated on the healthcheck, with an overlap window so the old
+      instance drains rather than being cut
+- [ ] a smoke test runs against the deployed URL, not against localhost
+- [ ] the smoke failing triggers rollback, and the rollback is exercised
+- [ ] the `last-good-deploy` tag moves **only after the smoke passes** — so
+      it always names a release observed working, never one that merely
+      deployed
+- [ ] release and commit sha reach the error monitor and every log line
+
+## Environment
+
+- [ ] every variable is read through one validating schema, and boot fails
+      loudly when a required one is missing
+- [ ] `.env.example` is **generated from that schema**, never written beside
+      it — a hand-kept example is wrong the first time somebody forgets, and
+      a new engineer trusts it anyway
+- [ ] `.env` gitignored, always
+- [ ] a secret that was ever committed is rotated; deleting the commit is not
+      the fix
+
+## Migrations
+
+- [ ] run automatically on deploy, never by hand
+- [ ] forward-compatible with the previous release, because both run at once
+      during the overlap window
+- [ ] a destructive change is two deploys: stop using the column, then drop
+      it
+
+## Containers
+
+- [ ] multi-stage build, runtime stage carries no build tooling
+- [ ] non-root user
+- [ ] `.dockerignore` covers `node_modules`, `.git`, test output
+- [ ] SIGTERM drains in-flight requests before exit — the overlap window is
+      wasted if the process dies instantly
+
+## Feature flags
+
+A risky change ships dark. The lookup must never be able to take the service
+down: bounded by a timeout, failures reported and answered with the flag's
+own fallback rather than thrown into a handler. For a kill switch the
+fallback is **false** — if we cannot ask whether a risky path is allowed, the
+answer is no.
+
+Flags live in one typed registry. A string literal at a call site is how they
+rot.
+
+## Common mistakes
+
+- **A readiness probe that returns a constant.** It passes review, passes
+  CI, and promotes a release with a dead database.
+- Pointing the platform healthcheck at `/health`. Liveness answers yes while
+  nothing works.
+- Rolling back by hand through a dashboard. The path nobody scripted is the
+  path nobody can run at 3am.
+- Tagging the deploy as good when it deployed, rather than when it was
+  observed working.
+- Secrets in the image, or in a build argument, which is the same thing.