agentic-team 0.0.0-stage → 6.2.0

package/template/.orchestra/stacks/backend-hono/claude/commands/endpoint.md

@@ -0,0 +1,13 @@
+Add an API endpoint.
+
+Usage: `/api:endpoint {method} {path}`
+
+1. Load the `api-endpoint` skill. Follow its order — it is not optional.
+2. Copy the shape of `src/features/health/`. It is the reference.
+3. Schema first: Zod with realistic examples on every non-obvious field.
+4. Declare every status code the route can return, errors included.
+5. Keep the handler thin. Throw `AppError`; never format an error inline.
+6. Add a service **only** if there is a decision to make. A forwarder is not.
+7. Write the four required tests, through the real app object.
+8. Run `npm run typecheck && npm run lint && npm run test:coverage`.
+9. Read your endpoint in Swagger UI as a caller would before reporting done.

package/template/.orchestra/stacks/backend-hono/claude/skills/api-endpoint/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: api-endpoint
+description: "Add or change a Hono endpoint — schema, route definition, handler, service decision, tests. Use for any work under src/features/."
+---
+
+# Adding an endpoint
+
+Copy the shape of `src/features/health/`. It is the reference
+implementation, not a placeholder.
+
+## 1. Schema — `schema.ts`
+
+Zod first. This object is the validator and the OpenAPI document.
+
+```ts
+export const CreateUserBody = z.object({
+  email: z.string().email().openapi({ example: "ada@example.com" }),
+  name: z.string().min(1).openapi({ example: "Ada Lovelace" }),
+}).openapi("CreateUserBody");
+```
+
+Every field carries a realistic example unless it is self-evident. Not
+`"string"`. Not `"foo"`. Someone reads these to decide how to call you,
+and a useless example costs them an hour.
+
+## 2. Route definition — `routes.ts`
+
+```ts
+const route = createRoute({
+  method: "post",
+  path: "/users",
+  tags: ["users"],
+  summary: "Create a user",
+  description: "Creates a user and returns it. Email must be unique.",
+  request: { body: { content: { "application/json": { schema: CreateUserBody } } } },
+  responses: {
+    201: { content: { "application/json": { schema: UserResponse } }, description: "Created" },
+    409: { content: { "application/json": { schema: ErrorSchema } }, description: "Email taken" },
+  },
+});
+```
+
+Declare **every** status code the handler can return, errors included. An
+undocumented 404 is a lie in the spec.
+
+## 3. Handler
+
+Parse, authorize, delegate, respond. That is the whole job.
+
+```ts
+export function userRoutes(deps: Deps) {
+  return new OpenAPIHono().openapi(route, async (c) => {
+    const body = c.req.valid("json");
+    const user = await createUser(deps, body);   // throws AppError on conflict
+    return c.json(user, 201);
+  });
+}
+```
+
+Throw `AppError`. Never format an error response in a handler — the single
+`onError` in `app.ts` owns that.
+
+## 4. Service — only if there is a decision
+
+Add `service.ts` when the feature branches, orchestrates more than one
+source, or enforces a rule that holds regardless of transport.
+
+If the handler validates and then touches one store, **do not add one**. A
+service that forwards a single call means the next person opens two files
+to learn nothing happened in the first.
+
+## 5. Tests
+
+Minimum four, through the real app:
+
+```ts
+const app = createApp({ ...fakes });
+
+it("creates a user", …)                    // happy path
+it("rejects an invalid email", …)          // validation → 400
+it("rejects an unauthenticated caller", …) // authorization → 401
+it("returns the shared error shape on conflict", …) // 409 body shape
+```
+
+Never mock our own code. Mock only the true edges: outbound HTTP, the
+clock, randomness, the database driver.
+
+If this endpoint calls a third-party library, test our wrapper — a
+Dependabot bump that changes behavior has to turn the suite red.
+
+## 6. Verify
+
+```bash
+npm run typecheck && npm run lint && npm run test:coverage
+```
+
+Coverage thresholds are enforced at 100. Then open Swagger UI and read
+your endpoint as a caller would. If it reads badly there, it is wrong.
+
+## Checklist
+
+- [ ] schemas defined with Zod, realistic examples on every non-obvious field
+- [ ] every returnable status code declared, errors included
+- [ ] summary, description, tag
+- [ ] handler is thin; `AppError` thrown, never formatted inline
+- [ ] service added only because there was a decision to make
+- [ ] authorization enforced on the route
+- [ ] four tests minimum, through the real app
+- [ ] coverage still 100
+- [ ] correct and readable in Swagger UI
+- [ ] no stack trace, query, or internal path in any response body

package/template/.orchestra/stacks/backend-hono/claude/skills/testing/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: testing
+description: "Decide what kind of test to write and what must be covered in this API. Use when adding tests, or when a coverage threshold fails."
+---
+
+# Testing this API
+
+## Which kind of test
+
+| Situation | Test |
+|---|---|
+| An endpoint exists | Integration through `app.request()` |
+| Pure logic with real branching | Unit test |
+| A function wrapping a third-party library | Unit test on our wrapper |
+| A function that only forwards | None — delete the forwarder instead |
+
+**Integration-first** is the default. Driving the real app object covers
+routing, validation, the handler, serialisation, and the error shape in
+one test, with no server and no network. It fails for the reasons things
+actually break.
+
+## What never to mock
+
+Our own code. If a test needs to mock a module we wrote, the design is
+telling you those two things are tangled — fix the design.
+
+Mock only true edges:
+
+- outbound HTTP
+- the clock (`deps.now`)
+- randomness and id generation
+- the database driver
+
+These are injected through `Deps`, so a fake is a plain object, not a
+framework.
+
+## The Dependabot rule
+
+> If one of our functions calls into a third-party library, that function
+> has a test.
+
+This is the entire reason the suite exists. When a bump changes behavior,
+the suite must go red — otherwise a green build means nothing and every
+dependency PR needs a human to read the changelog.
+
+## Every endpoint, four tests minimum
+
+1. happy path — correct status, correct body
+2. validation failure — 400 and the shared error shape
+3. authorization failure — 401 or 403
+4. the documented error case — 404, 409, whatever the route declares
+
+An endpoint with only a happy-path test is untested. The failure paths are
+where the bugs are.
+
+## Coverage
+
+100% lines, functions, branches, statements — enforced in
+`vitest.config.ts`. A drop fails the run.
+
+Only `src/index.ts` is excluded, because it binds a port and nothing else.
+Any new exclusion needs a comment justifying it, and "hard to test" is not
+a justification — it is usually the design telling you something.
+
+Chasing the last few percent by testing getters is not the point. If a
+branch is uncoverable, ask whether it should exist.
+
+## Test style
+
+- One behavior per test. The name says the scenario, not the method.
+- Arrange with real objects where possible. A fixture builder beats a
+  twelve-line literal repeated in nine tests.
+- No shared mutable state between tests. Each builds its own app.
+- Assert on the whole response body, not one field — that is how you catch
+  an accidental extra property leaking out.