agentic-team 0.0.0-stage → 6.2.0

package/template/skills/error-handling/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: error-handling
+description: "What to do when something fails — typed errors, propagation, what the user sees, and degrading instead of crashing. Use for any phase that adds a failure path, a catch, or an error response."
+---
+
+# Skill: Error Handling
+
+The rule is in `.claude/rules/observability.orchestra.md` and a check
+enforces it: **a catch either handles the error meaningfully or reports it and
+rethrows.** `scripts/policy-check.mjs` fails the gate on an empty catch and on
+a catch whose only body is a log.
+
+That check proves a catch is not empty. It cannot tell whether the user got a
+correct outcome. This skill is about the part that needs a person.
+
+## The fact everything else follows from
+
+**"Handled" means the caller gets a correct outcome — not that the crash was
+hidden.**
+
+```ts
+try {
+  await chargeCard(order);
+} catch (e) {
+  reportError(e);
+  return { ok: true };   // the gate passes. the customer was not charged.
+}
+```
+
+Reported, rethrown-shaped, and wrong. Nothing downstream can tell the
+difference between a payment that succeeded and one that vanished. Deciding
+which of those two this is, is the entire job.
+
+## Three kinds of failure, three different answers
+
+| Kind | Example | Answer |
+|---|---|---|
+| **Expected** | invalid input, not found, conflict | Not exceptional. Return it as a value or throw a typed error the boundary maps to a status. |
+| **Transient** | timeout, 503 from a provider, deadlock | Retry if idempotent, with backoff and a bound. Then give up deliberately. |
+| **A bug** | undefined is not a function, a broken invariant | Do not catch it here. Let it reach the boundary, be reported with its stack, and answer 500. |
+
+The most common mistake is treating the third as the first: a broad `catch`
+around a whole handler turns every bug into a polite message and the defect
+is never seen again.
+
+## Typed at the boundary
+
+The backend stack ships `AppError` with a closed `ErrorCode` union, and
+`toErrorBody` maps it to a status and a body. Use it.
+
+```ts
+throw new AppError("not_found", "Order not found");
+```
+
+- **Never throw a bare `Error` across a route boundary.** It becomes a 500,
+  which tells the caller nothing and pages someone for a 404.
+- **Never let internal detail into the response.** `toErrorBody` returns the
+  minimum for anything unrecognised, deliberately — a stack trace in a body
+  is an information leak, and the message often contains a query.
+- The code is a **closed union**, not a string. A new failure mode is a new
+  member and a new status, decided once, rather than a literal invented at a
+  call site.
+
+Adding a code is a real decision: it is part of the API contract, and a
+client will branch on it.
+
+## Validate once, at the edge
+
+Parse input at the boundary and let everything inside work with a type that
+cannot be invalid. A function that re-checks its arguments is a function that
+does not trust its own signature — and the check will disagree with the
+schema eventually.
+
+That is why the boundary owns validation and the interior does not:
+`.claude/rules/security.orchestra.md` puts it in the same place for the same
+reason.
+
+## Keep the cause
+
+```ts
+throw new AppError("internal", "could not load order");           // no
+throw new Error("could not load order", { cause: original });      // yes
+```
+
+Wrapping is fine; discarding is not. The original stack is the only thing
+that says which line failed. When you rethrow, carry the cause; when you
+report, report the cause too.
+
+## What the user sees
+
+Two audiences, two texts, and they are rarely the same string.
+
+- **The user** gets something actionable: what happened, and what they can do.
+  Not an error code alone, and never a stack.
+- **The operator** gets the detail, in the log, with the correlation id — so
+  a user quoting `x-request-id` from a bug report leads straight to the line.
+  The request logger echoes that header back for exactly this reason.
+
+If a screen can fail, it has a failure state, and the failure state has a way
+forward. `.claude/skills/review/SKILL.md` treats a missing one as a finding.
+
+## Degrading instead of failing
+
+Some dependencies are not required to answer. Say so explicitly, and say what
+the answer is without them.
+
+```ts
+// Recommendations are a nice-to-have; the page renders without them.
+const recommended = await getRecommendations(userId).catch((e) => {
+  report(e);
+  return [];
+});
+```
+
+This is the one place an error is swallowed, and it carries a comment saying
+why failure is acceptable — the exception named in the observability rule.
+Two conditions, both required:
+
+1. The feature is genuinely optional to the outcome.
+2. The failure is still **reported**, so "optional" does not quietly become
+   "permanently broken".
+
+For anything gating a risky path the fallback is **false** — the same
+direction the feature-flag registry falls, and for the same reason.
+
+## Failure paths are tested, not assumed
+
+- Every catch you write has a test that reaches it. An untested error path is
+  usually a broken error path — it is the code least likely to have been run
+  even once.
+- Provider failures are faked **at the HTTP boundary**, never by mocking your
+  own wrapper: the wrapper is where a provider's change bites you, so mocking
+  it tests nothing. `.claude/rules/testing-standards.orchestra.md`.
+- The cases worth writing: a 500 from the provider, a timeout, a malformed
+  body, and the retry that eventually gives up.
+
+Coverage will not tell you these exist. Mutation testing would, which is why
+it is wired even while it waits on the compiler.
+
+## Anti-patterns
+
+- **`catch (e) { report(e) }` in a write path.** The caller now believes the
+  write happened.
+- **Catching to convert everything to `null`.** The caller has no idea
+  whether "nothing" means empty or broken.
+- **One broad try/catch wrapping an entire handler.** It catches your bugs
+  along with the expected failures, and turns both into the same response.
+- **Retrying a non-idempotent write.** This is how a customer gets charged
+  twice.
+- **A message that names the wrong actor.** "Something went wrong" when the
+  input was invalid sends the user looking in the wrong place.
+- **Logging and rethrowing at every level.** One failure, six lines, and none
+  of them the one with the stack. Report where you handle it, not on the way
+  past.

package/template/skills/frontend-design/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: frontend-design
+description: "Building UI that looks deliberate rather than generic — typography, colour, spacing, motion. Use for any phase where visual quality is part of the acceptance criteria."
+---
+
+# Skill: Frontend Design
+
+## When to Use
+Phase involves building UI that needs to look polished, professional, and distinctive — not generic.
+
+## Checklist
+- [ ] **Bold aesthetic direction:** commit to a clear visual concept — not timid, not generic
+- [ ] **Distinctive typography:** avoid overused fonts (Inter, Roboto, Arial) — choose fonts with character
+- [ ] **Cohesive color scheme:** limited palette (3-5 colors) with sharp accent colors
+- [ ] **Intentional layout:** use asymmetry, overlap, or diagonal elements where appropriate — not everything grid-aligned
+- [ ] **Layered shadows:** multiple transparent shadows instead of solid borders (`box-shadow: 0 1px 2px rgba(0,0,0,0.1), 0 4px 12px rgba(0,0,0,0.05)`)
+- [ ] **Concentric border radius:** outer radius = inner radius + padding (nested elements)
+- [ ] **Micro-interactions:** hover states, focus transitions, loading animations — all < 300ms
+- [ ] **Staggered enter animations:** split elements, ~100ms delay between each
+- [ ] **Font smoothing:** `-webkit-font-smoothing: antialiased` for crisp text
+- [ ] **Tabular numbers:** `font-variant-numeric: tabular-nums` for data tables and counters
+- [ ] **Optical alignment:** icons and text optically centered, not geometrically
+
+## Common Mistakes
+- Generic AI-slop aesthetics → every AI tool produces the same look, be distinctive
+- Solid borders everywhere → layered transparent shadows look more refined
+- Geometric centering for icons → optical centering looks correct to the eye
+- Harsh easing functions → use `cubic-bezier(0.4, 0, 0.2, 1)` for natural motion
+- Missing exit animations → enter with animation, exit abruptly looks broken
+- System fonts without thought → typography is 80% of visual quality

package/template/skills/fullstack-infrastructure/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: fullstack-infrastructure
+description: "TypeScript and React conventions that hold in any app — types, hooks, rendering, data flow, performance, i18n. Which libraries, which structure and which tooling are decided by .orchestra/stacks/, not here. Use when writing TypeScript or React in any app."
+---
+
+# TypeScript & React Conventions
+
+What is true regardless of which stack scaffolded the app.
+
+## What this file does not decide
+
+It used to carry a tech stack table and a monorepo tree of its own, naming an
+ORM, an auth scheme, an HTTP client and a component kit. Every one of those is
+decided somewhere that can enforce it, and a skill restating a choice is a
+second source of truth: whichever the agent reads last wins, and nothing
+notices when they drift apart.
+
+| Question | Answered by |
+|---|---|
+| Which libraries, package manager, tooling | `.orchestra/stacks/<stack>/setup.sh` — it installs them |
+| Where a new file goes | `.claude/skills/project-structure/SKILL.md` |
+| Where a component comes from | the web `stack.md`, and `src/components/README.md` |
+| What "handled" means for an error | `.claude/skills/error-handling/SKILL.md` |
+| Testing, commits, security, observability | `.claude/rules/*.orchestra.md` |
+
+What the stacks scaffold today, for orientation only: Drizzle rather than
+Prisma, server-side sessions rather than JWT, `fetch` in
+`src/integrations/<provider>/` rather than an Axios wrapper class, feature-first
+`src/features/<domain>/` rather than a layer-first tree.
+
+**If this file ever disagrees with a stack, the stack is right** — it is the
+thing that actually ran.
+
+## TypeScript
+
+- `strict`, with no per-file exemptions.
+- No `any`. Use `unknown` and narrow it — `any` disables the checker at
+  exactly the boundary you added it to guard.
+- `interface` for object shapes, `type` for unions and intersections.
+- Discriminated unions for anything with states. A boolean pair that can
+  express `loading && error` is a bug waiting for a screenshot.
+- Explicit return types on exported functions. Inference is fine inside a
+  module and a liability across one — a return type that changes silently is
+  a breaking change nobody reviewed.
+- Prefer a union of literals to an enum. It erases at compile time and
+  narrows without an import.
+
+## React
+
+- Function components only.
+- Custom hooks are prefixed `use` — the linter's rules-of-hooks check keys
+  off the name, so a mis-named hook is simply unchecked.
+- `useMemo` and `useCallback` where a measurement says they help. Applied by
+  reflex they add allocation and a dependency array to get wrong.
+- Composition over prop drilling. Context for what is genuinely ambient
+  (theme, locale, session), not to avoid passing two props.
+- Stable keys from the data. An array index makes React reuse the wrong node
+  the first time the list reorders, and the bug looks like corrupted state.
+- `React.lazy` with `Suspense` at route boundaries.
+
+## Data flow
+
+- **Server cache and client state are different things.** Copying a response
+  into a client store gives you two truths and a stale one.
+- Every backend call goes through a wrapper in `src/integrations/<provider>/`
+  — never a raw client call from a component. That is where the timeout, the
+  retry bound and the error mapping live, and it is the only place a test can
+  hold. See `.claude/skills/project-structure/SKILL.md`.
+- Which cache or store library, if any, is the stack's decision. If a project
+  adopts one, it goes in the stack's `setup.sh` so it is installed and
+  covered — not named here.
+
+## Classes vs functions
+
+**Class** when there is lifecycle to hold: an SDK that needs init and
+teardown, or shared configuration across calls.
+**Function** when it is stateless and single-purpose — `formatDate`,
+`slugify`.
+
+Prefer writing a small utility to adding a dependency for it. Reach for a
+package when the implementation is genuinely hard — dates, time zones,
+collation — not when it is twelve lines.
+
+## Performance
+
+- Lazy load routes and anything heavy below the fold.
+- Virtualize long lists.
+- Debounce or throttle high-frequency events at the source, not in the
+  handler.
+- Derive loading and error state from the request, not from booleans set by
+  hand in three places.
+
+## Environment variables
+
+Validated at startup against a schema, so the process refuses to boot on bad
+configuration rather than failing on the first request that needs it.
+
+`.env.example` is **generated from that schema**, never written beside it —
+see `.claude/rules/security.orchestra.md`.
+
+## i18n
+
+Ask whether it is needed before the first string is written; retrofitting
+means touching every component.
+
+When it is: every user-facing string is a key, namespaced by feature. No
+concatenated sentences — word order is not universal, and a sentence built
+from three fragments cannot be translated correctly into most languages.

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

@@ -0,0 +1,100 @@
+---
+name: ios-testing
+description: "Testing strategy for native iOS apps — Swift, SwiftUI, XCTest and XCUITest. Use for any phase that writes or changes tests in a native iOS app."
+---
+
+# Skill: iOS Testing
+
+## The fact everything else follows from
+
+**A unit test does not prove the app launches.**
+
+An iOS app dies for reasons no XCTest sees: a missing Info.plist key, an
+entitlement the provisioning profile lacks, a `@main` that throws before the
+first view, a bundle resource that was never copied. The suite is green and
+the app crashes on the splash screen.
+
+So the launch test is not the top of a pyramid you get to later. It is the
+first test worth writing.
+
+## The layers
+
+| Layer | What belongs here | Runs on |
+|---|---|---|
+| Unit | Pure logic and view models — no UIKit, no SwiftUI | Host, fast |
+| View | SwiftUI views: state transitions and the accessibility tree | Simulator |
+| Integration | The real networking stack, stubbed at the transport | Simulator |
+| UI (XCUITest) | 3–5 journeys, one of them launch | Real simulator |
+| Build | `xcodebuild` for a device architecture | The gate |
+
+## Stub the transport, not your client
+
+```swift
+final class StubProtocol: URLProtocol { /* … */ }
+
+let config = URLSessionConfiguration.ephemeral
+config.protocolClasses = [StubProtocol.self]
+let session = URLSession(configuration: config)
+```
+
+Register a `URLProtocol` subclass and the real `URLSession` runs — your
+request building, your headers, your decoding, your error mapping.
+
+Injecting a `MockAPIClient` instead tests the mock. The client is the thing
+that breaks when the API changes, so it is the thing that must stay in the
+test.
+
+## Query the accessibility tree
+
+```swift
+app.buttons["Add water"].tap()          // yes — the accessible name
+app.buttons["btn_add_water"].tap()      // no — an identifier nobody hears
+```
+
+XCUITest resolves elements through the accessibility tree, which is the same
+tree VoiceOver uses. Query by label and **a control with no accessible name
+fails the test** — accessibility becomes something the suite enforces.
+
+Use `accessibilityIdentifier` only where the visible label genuinely changes
+with locale or data, and keep the label correct anyway.
+
+## Swift Testing for units, XCTest for UI
+
+`import Testing` with `@Test` and `#expect` is the current framework for unit
+and view tests — clearer failures, real parameterised cases, native async.
+
+XCUITest is still XCTest. Do not try to unify them.
+
+Both need `await` discipline: a `@MainActor` view model tested from a
+non-isolated context passes locally and races in CI.
+
+## Never
+
+- **Snapshot tests as the main assertion.** A recorded PNG changes with every
+  OS point release, gets re-recorded without being read, and passes while the
+  button does nothing. Assert state and the accessibility tree instead.
+- Testing that SwiftUI re-renders, or that `NavigationStack` navigates.
+  Assert that the action fires with the right argument.
+- Sleeping to wait. `XCTestExpectation` and `waitForExistence(timeout:)`
+  exist; a `sleep` is a flake with a delay.
+- A simulator-only definition of done. The simulator has no memory pressure,
+  no thermal throttling, no real camera and a different keyboard.
+
+## The build is part of the suite
+
+Build for a **device** architecture in the gate, not only the simulator.
+Simulator builds are x86/arm64-host and skip code signing, so a missing
+entitlement, an unsupported architecture or a bad bitcode setting only
+appears when a real build is attempted.
+
+A release build additionally runs optimisation and dead-code stripping,
+which is where `#if DEBUG` mistakes surface.
+
+## Release risk
+
+An App Store release cannot be rolled back. There is no equivalent of an
+over-the-air JavaScript update unless one was deliberately built.
+
+That makes phased release and a server-side kill switch part of the testing
+strategy rather than an operational afterthought — see
+`.claude/rules/observability.orchestra.md`.

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

@@ -0,0 +1,102 @@
+---
+name: mobile-testing
+description: "Testing strategy for React Native and Expo apps. Use for any phase that writes or changes tests in a mobile app, or that adds an e2e flow."
+---
+
+# Skill: Mobile Testing
+
+## The fact everything else follows from
+
+**Jest does not run React Native.** The `jest-expo` preset runs components in
+Node against mocked native modules.
+
+On a backend, an integration test exercises the real thing. Here, the
+equivalent test exercises a simulation. The whole JS suite can be green while
+the app fails to build, crashes on launch, or works on iOS and not Android.
+
+So the device layer is not the optional top of a pyramid. It is where the
+risk actually lives.
+
+## The layers
+
+| Layer | What belongs here | Runs against |
+|---|---|---|
+| Pure logic | Calculations, conversions, date and streak logic, reducers — extracted **out** of components into plain modules | Node |
+| Components (RNTL) | Render, interact, assert behaviour | Node, **mocked natives** |
+| API seam (MSW) | Our own backend, faked at the network layer | Node |
+| E2E (Maestro) | 5–10 flows, no more | **Real simulator/emulator** |
+| The build | `expo-doctor`, `expo install --check`, a native build | CI |
+
+## Where mobile bugs actually come from
+
+| Failure | Caught by |
+|---|---|
+| Does not build, or crashes on launch | the build, then e2e |
+| Native module version off the SDK | `expo install --check` |
+| Fine on iOS, broken on Android | e2e on both |
+| Permission denied, backgrounded mid-request | e2e |
+| Offline or flaky network | MSW |
+| Stored data breaks on app upgrade | a dedicated migration test |
+| Small screen, large accessibility font | e2e or manual |
+| A notification that never arrives | nothing automated — a device |
+
+Very little of that column says "component test". Weight the effort
+accordingly.
+
+The last row is the honest one: permission, token refresh, the background
+handler and a deep link from a terminated app are all mocked into success by
+`jest-expo`. Depth in `.claude/skills/push-notifications/SKILL.md`.
+
+## Query by role, never by testID
+
+```ts
+screen.getByRole("button", { name: "Add water" });   // yes
+screen.getByTestId("add-water-btn");                 // no
+```
+
+RNTL resolves roles from `accessibilityRole` and the accessible name. Query
+that way and **a missing accessibility prop becomes a failing test** —
+accessibility stops being a review checklist item and becomes enforced by the
+suite. A `testID` proves nothing about whether a screen reader can use the
+screen.
+
+## Extract the logic out of the component
+
+A component test that exercises clamping, rounding or formatting is testing
+a pure function through three layers of render. Move the function to a plain
+module: it gets faster, it can be mutation-tested, and the component test
+shrinks to "renders what the module returned".
+
+## E2E — Maestro, not Detox
+
+Maestro is YAML flows and needs no native build knowledge. Detox is more
+capable and a great deal more setup; not worth it below a large team. Maestro
+is a CLI, installed by its own installer — not an npm package.
+
+Keep the suite small and end-to-end in the real sense:
+
+1. launch → sign in
+2. the core action of the app, once
+3. the screen reflects it
+4. kill and relaunch — the data is still there
+
+Step 4 catches storage and migration bugs that nothing else sees.
+
+## Never
+
+- Snapshot tests. Huge, meaningless, and "updated" reflexively. A snapshot
+  passes while the handler stops firing.
+- Testing that React Navigation navigates. Assert that pressing the control
+  calls navigate with the right target; the library's own behaviour is not
+  ours to test.
+- Chasing coverage through screen composition files. The value sits in the
+  logic modules and the e2e flows.
+
+## Release risk splits in two
+
+- **JS-only change** — ships over the air (EAS Update). The JS suite really
+  is the gate, and a bad one rolls back in minutes.
+- **Native change** — SDK, a plugin, a native dependency. Needs a build and a
+  device test, and it **cannot be rolled back** once it is in a store.
+
+Treat the second kind as a different category of change, not a bigger one.

package/template/skills/observability/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: observability
+description: "Wire error monitoring, structured logging, and analytics into an app. Use when setting up a new app, before first release, or when instrumenting a milestone's KPIs."
+---
+
+# Wiring observability
+
+Mandatory before first release. See
+`.claude/rules/observability.orchestra.md` and
+`.claude/rules/analytics-kpi.orchestra.md` for the rules this implements.
+
+## Order
+
+1. **Error monitoring first.** It is the thing you need most on the day
+   something breaks, and the thing hardest to add under pressure.
+2. **Structured logging** — server side.
+3. **Analytics** — once the KPIs are known. Instrumenting before you know
+   what you are measuring produces events nobody reads.
+
+## Error monitoring checklist
+
+- [ ] SDK initialised as early as the app's lifecycle allows
+- [ ] release tagged with version **and** commit sha
+- [ ] symbols uploaded in CI — source maps, dSYMs, mapping files
+- [ ] environment set, so staging noise does not drown production signal
+- [ ] PII scrubbing configured **before** the first event is sent
+- [ ] a deliberate test error verified end to end, in the dashboard
+- [ ] alerting routed somewhere a human actually reads
+
+An error monitor nobody has seen an event from is not wired. Prove it.
+
+## Logging checklist
+
+- [ ] JSON output, one event per line
+- [ ] correlation id per request, on every line for that request
+- [ ] levels used honestly — `error` means someone should look
+- [ ] no secrets, no PII, no full request bodies
+- [ ] `debug` off in production
+
+## Health checklist
+
+Two endpoints, because they answer different questions. `/health` says the
+process is up; `/ready` says it can serve. The platform healthcheck points at
+readiness, so this is the thing that decides whether a release is promoted.
+
+- [ ] `/health` cheap, no dependencies
+- [ ] `/ready` probes every dependency the service cannot serve without
+- [ ] it answers 503 and **names** the dependency that failed
+- [ ] a test makes it fail — a readiness check that cannot fail is worse
+      than none
+- [ ] a new dependency adds its probe and its failing test in the same change
+- [ ] the platform's `healthcheckPath` points at `/ready`
+
+## Feature flag checklist
+
+A flag exists to protect the service, so the lookup must never be able to
+take it down.
+
+- [ ] one typed registry — no string literal at a call site
+- [ ] every lookup bounded by a timeout
+- [ ] a failed lookup is reported and answered with the flag's fallback,
+      never thrown into a handler
+- [ ] a kill switch falls back to **false**: if we cannot ask whether the
+      risky path is allowed, the answer is no
+
+## Analytics checklist
+
+- [ ] event names and payloads in one typed schema module per app
+- [ ] call sites import from the schema — no string literals
+- [ ] naming convention picked once: `object_action`
+- [ ] view event per screen or route
+- [ ] start, success, **and failure with a reason code** on critical flows
+- [ ] no PII in properties
+- [ ] consent gate respected before anything is sent
+- [ ] tests assert the event fires once with the right shape
+- [ ] events observed actually arriving before the milestone closes
+
+## Common failures
+
+**Instrumenting the wrapper, not the action.** An event fired three layers
+from the user eventually fires for the wrong reason. Instrument where the
+action happens.
+
+**Only tracking success.** A funnel with no failure events tells you people
+left but never why — which is the only thing you wanted to know.
+
+**Swallowing the error you just reported.** Report and rethrow, or handle it
+so the user gets a correct outcome. Hiding a crash is not handling it.
+
+**Shipping without verifying.** Untested instrumentation is usually broken
+instrumentation. Send one real event and look at it.