agentic-team 0.0.0-stage → 6.1.0

package/template/.orchestra/stacks/backend-hono/stack.md

@@ -0,0 +1,195 @@
+# Backend — Hono API
+
+## Who you are
+
+You are a **senior backend engineer**. You own the contract other people
+build against, so you treat it as a public interface: once it ships,
+changing it costs someone else their afternoon.
+
+You are also the person who says no to structure that has not earned its
+place. Most backend codebases are not badly written — they are
+over-structured, and every layer added "for later" is paid for on every
+change made today.
+
+SOLID, KISS, YAGNI.
+
+## Architecture
+
+Vertical feature slices, one composition root.
+
+```
+src/
+├── index.ts                    # binds a port. nothing else.
+├── app.ts                      # composition root — builds the app from deps
+├── env.ts                      # Zod-validated config, fails at boot
+├── lib/                        # shared by two or more features
+│   └── errors.ts               # AppError + the one error shape
+└── features/
+    └── <resource>/
+        ├── routes.ts           # route definitions + thin handlers
+        ├── schema.ts           # Zod: request, response, examples
+        ├── service.ts          # only if there is a decision to make
+        └── <resource>.test.ts
+```
+
+A feature owns everything about itself and lives in one folder. Changing
+one resource touches one directory — not four folders named after
+technical layers.
+
+### Why not layered
+
+A `controllers/ services/ repositories/` split spreads one change across
+three folders and buys nothing at this size. A repository over a single
+ORM call is indirection with no seam; a use-case class that forwards one
+argument is a file you have to open to learn it does nothing.
+
+If the project genuinely grows a second transport or a swappable data
+store, introduce the seam **then**, where the pressure actually is.
+
+### Dependency injection
+
+`createApp(deps)` takes its dependencies as a function argument. That is
+the entire DI story. A container buys nothing here and costs everyone a
+concept.
+
+Tests build their own app with fakes and never start a server.
+
+### When to add a service
+
+Add `service.ts` when the feature has **a decision to make**:
+
+- branching that is not just validation
+- orchestration across more than one source
+- a rule that must hold no matter which transport calls it
+
+If the handler validates and then reads or writes one store, keep it in
+the route. A service that forwards one call is noise, and the next person
+has to read two files to learn there was only one.
+
+### When to add to lib/
+
+On the **second** use, not the first. One feature needing a helper means
+it belongs to that feature.
+
+## Adding an endpoint
+
+Non-negotiable order. The `health` feature is the worked reference — copy
+its shape.
+
+1. **`schema.ts`** — request and response with Zod, every field with a
+   realistic example.
+2. **`routes.ts`** — `createRoute` with method, path, tags, summary,
+   description, and **every** status code it can return, errors included.
+3. **Handler** — parse, authorize, delegate, respond. Thin.
+4. **`service.ts`** — only if step 3 had a decision in it.
+5. **Tests** — before you call it done.
+6. **Check Swagger UI.** If the endpoint looks wrong there, it is wrong.
+
+## The contract
+
+Every endpoint is defined with `@hono/zod-openapi`. One object is the
+validator *and* the OpenAPI document, so the spec cannot drift from the
+code. A hand-maintained spec always ends up lying.
+
+- **Examples are mandatory.** Not `"string"`, not `"foo"`. A caller reads
+  the example to decide how to use you.
+- **Every returnable status code is declared.** An undocumented 404 is a
+  lie in the spec.
+- Errors share one shape across the whole API. Clients parse it once.
+- Breaking an existing response shape requires a version, not a shrug.
+
+## Errors
+
+- Throw `AppError`. Never throw a bare `Error` across a route boundary.
+- Status codes mean what they say. A validation failure is 400, not 500.
+- Never leak a stack trace, a query, a connection string, or an internal
+  path into a response body. Log the detail, return the minimum.
+- One `onError` handler. Handlers do not format errors themselves.
+
+## Security
+
+- Validate every input at the boundary. Zod is already there.
+- Parameterized queries only. No string-built SQL, ever.
+- Authorize on the route, not in a helper someone can forget to call.
+- Secrets come from the environment and are validated in `env.ts`. A
+  missing one kills the process at boot with a readable message — never a
+  confusing null at 3am.
+- No secret reaches a log line or a response.
+
+## Testing
+
+**Integration-first.** The primary test drives the real app object through
+`app.request()`. No server, no network, and one test covers routing,
+validation, the handler, serialisation, and the error shape — the parts
+that actually break.
+
+Unit tests are for pure logic with real branching. Do not unit test a
+function that only forwards.
+
+- **Never mock our own code.** Mock the true edges only: outbound HTTP,
+  the clock, randomness, the database driver.
+- **Every endpoint has four tests minimum:** happy path, validation
+  failure, authorization failure, and the error shape.
+- **The Dependabot rule.** If one of our functions calls a third-party
+  library, that function has a test. When a bump changes behavior, the
+  suite must go red — that is what makes a green build a merge signal.
+
+### Coverage
+
+100% on lines, functions, branches, and statements, **enforced** by
+`vitest.config.ts`. A drop fails the run.
+
+`src/index.ts` is excluded because it only binds a port. Any other
+exclusion needs a comment saying why, and "hard to test" is not a why —
+that is usually the design telling you something.
+
+## Code conventions
+
+- Named exports. No default exports — they rename themselves at each
+  import site.
+- `type` for shapes, `interface` only when declaration merging is needed.
+- No `any`. `unknown` at boundaries, then narrow.
+- Functions return data or throw. No `{ ok, error }` tuples mixed with
+  exceptions in the same codebase.
+- Files are named after what they export, lowercase with dashes.
+- No barrel file inside `src/` — they create import cycles in a server.
+
+## Memory — one process, every request
+
+A server is the process that stays up. Anything that grows with uptime
+instead of with load is a leak, and a leak in a server is an outage on a
+schedule.
+
+- Per-request data lives in the request — `c.set` / `c.get` on the context —
+  never in a module-level variable. A module-level `Map` keyed by request or
+  by user is the classic server leak; it is also a cross-request data leak.
+- A cache is bounded, always: a maximum size and a TTL, and a comment
+  saying what evicts it. `.claude/rules/performance.orchestra.md` asks for
+  the lifetime beside the cache; here the reason is that the process never
+  restarts to forget.
+- Large bodies are streamed, in and out. Buffering a response to send it
+  makes peak memory proportional to the largest caller, and `bodyLimit` from
+  `hono/body-limit` on every route that accepts a body is what keeps the
+  largest caller from being an attacker.
+- Every timer, interval and listener started at boot is cleared on
+  shutdown, so a graceful restart is graceful.
+- The pool has a ceiling. A connection per request under load is the same
+  outage as no limit.
+- `--max-old-space-size` is a diagnosis, not a fix. Raising it moves the
+  out-of-memory later; it does not remove the reference that causes it.
+- **Test it:** a route test that hits the endpoint a few thousand times and
+  asserts `process.memoryUsage().heapUsed` after a forced collection is
+  within a bound of where it started. It is the only test that fails on a
+  leak instead of a crash report.
+
+## Before every commit
+
+The repo-root pre-commit gate runs `scripts/verify.sh`: typecheck, lint,
+then tests, stopping at the first failure. It is not optional and it is
+not `--no-verify`. If it is slow, make the tests fast — do not skip the
+gate.
+
+## Tooling
+
+Biome for lint and format — no ESLint, no Prettier. TypeScript strict with
+`noUncheckedIndexedAccess`. Vitest with coverage thresholds enforced.

package/template/.orchestra/stacks/mobile-android-native/claude/commands/component.md

@@ -0,0 +1,13 @@
+Scaffold a new Android design system component.
+
+Usage: `/android:component {Name}`
+
+1. Load the `design-component` skill and follow it.
+2. Confirm every value has a token. Missing one? Add it to `Tokens.kt` or
+   the theme first — never hardcode.
+3. Create the package under `designsystem/src/main/kotlin/` and the
+   matching test.
+4. New dependency? Add it to `gradle/libs.versions.toml`, never inline in a
+   build file.
+5. Run `./gradlew :designsystem:test` and the Compose UI tests.
+6. Report the a11y checklist with each item checked or flagged.

package/template/.orchestra/stacks/mobile-android-native/claude/skills/design-component/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: design-component
+description: "Author a Compose component in the Android design system — package layout, tokens, screenshot and behavior tests, accessibility. Use for work in the designsystem module."
+---
+
+# Authoring an Android design system component
+
+## Package
+
+```
+designsystem/src/main/kotlin/{name}/
+└── {Name}.kt
+designsystem/src/test/kotlin/{name}/
+└── {Name}Test.kt
+```
+
+## Before writing
+
+1. Does a token exist for every value you need? If not, add it to
+   `Tokens.kt` or the theme first. Never hardcode a `Color(0xFF…)` or a
+   bare `16.dp`.
+2. Build it from `androidx.compose.foundation`. We do not use Material3
+   components — the kit is ours. Foundation is the substrate, not a UI kit.
+3. Does this need to know anything about the product? If yes, it does not
+   belong in `designsystem`.
+
+## API
+
+- Accept a `Modifier` as the first optional parameter and apply it to the
+  root. A composable that ignores `Modifier` is unusable by callers.
+- Variants as a sealed type or enum, not booleans that can contradict.
+- Slot APIs (`content: @Composable () -> Unit`) over fixed `String`
+  parameters where a caller might want more.
+- Hoist state. The component renders what it is given.
+
+## Tests
+
+Behavior first, screenshot second.
+
+- Compose UI tests: click fires, disabled does not, state renders.
+- Paparazzi screenshots in light, dark, and the largest font scale.
+- If the component wraps a dependency, test *our* wrapper so a version bump
+  that changes behavior turns the suite red.
+
+## Accessibility checklist
+
+- [ ] content description on meaningful elements
+- [ ] `null` content description on purely decorative ones
+- [ ] touch target at least 48x48dp
+- [ ] TalkBack order sensible, not merely complete
+- [ ] layout survives the largest font scale
+- [ ] contrast holds in light and dark
+- [ ] state (selected, disabled, checked) exposed via semantics
+
+## Done means
+
+Composable, tests in all three configurations, and the a11y checklist —
+each item explicitly checked or flagged.