agentic-team 0.0.0-stage → 6.1.0

package/template/skills/review/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: review
+description: "Reviewing a diff — as the reviewer role, or self-review before submitting. Use for any phase that reviews code rather than writing it."
+---
+
+# Skill: Review
+
+## Review what the gate cannot
+
+By the time a diff exists, a great deal has already been decided
+mechanically. Re-checking any of it spends the only thing a reader has that
+a script does not.
+
+**Already enforced. Do not spend attention here:**
+
+| Concern | Enforced by |
+|---|---|
+| Secrets, in the diff or anywhere in history | gitleaks |
+| String-built SQL | `scripts/policy-check.mjs` |
+| Empty or unreported `catch` | `scripts/policy-check.mjs` |
+| `getByTestId` in a test | `scripts/policy-check.mjs` |
+| A mocked database | `scripts/policy-check.mjs` |
+| Unused imports, dead code, `console.log` | biome |
+| Contrast, ARIA, missing labels | axe, in component tests and e2e |
+| Coverage of the lines this change touched | the diff gate |
+| Anything wrapping a dependency, at 100% | the seam gate |
+| Bundle growth | the bundle ratchet |
+| It compiles, bundles, boots | typecheck, build, e2e |
+| A known critical vulnerability | `yarn npm audit` in CI |
+
+If one of those is wrong the commit does not exist — the gate blocked it.
+Reporting it anyway tells the author you did not know that.
+
+## Yours alone
+
+Every item here needs a reader.
+
+- [ ] **It does what the phase asked.** Re-read the acceptance criteria
+      against the diff. Working code that solves a different problem is the
+      most expensive defect there is, and no gate detects it.
+- [ ] **The error handling is meaningful, not merely present.** A check
+      proves the `catch` is not empty. Only a reader can tell whether the
+      user gets a correct outcome or the failure was made invisible.
+- [ ] **The tests assert behaviour.** Coverage proves a line ran. Read the
+      assertions: a test that calls a function and checks nothing about what
+      it did passes every gate we have.
+- [ ] **Authorization is on the route**, not in a helper a future route can
+      forget to call. Named as unmechanizable in
+      `.claude/rules/security.orchestra.md` — so it is yours.
+- [ ] **No PII in logs, errors or analytics.** Redaction covers known keys;
+      a new field carrying a person's name is invisible to it.
+- [ ] **Query shape.** N+1, a missing index, a transaction that should exist
+      and does not.
+- [ ] **Readiness probes what it claims.** A new dependency without a probe
+      is a broken release that gets promoted.
+- [ ] **The abstraction earns itself.** Extracted after the second
+      duplication, not before. Was a simpler alternative available?
+- [ ] **Loading, empty and failure states exist** for anything a user waits
+      on.
+- [ ] **Anything that will be wrong later.** A pinned version with no reason
+      written beside it, a TODO with no owner, a workaround presented as a
+      fix.
+
+## Severity
+
+Defined once, in `.claude/agents/reviewer.md` under Severity — Blocking,
+Important, Suggestion, and which of them hold the pull request. Read it
+there; a second copy here drifted from it before.
+
+## Common mistakes
+
+- Reviewing the diff without opening the file. Context-dependent bugs live
+  in the lines that did not change.
+- Re-reporting something a gate already decided.
+- Nitpicking style a formatter owns.
+- A vague finding. Say what, where, and why.
+
+## Never ask for a test to be loosened
+
+Nor a threshold lowered, nor an ignore added. If a gate is wrong, that is a
+finding **about the gate** — a change to `.orchestra/stacks/`, not to the
+project under review.

package/template/skills/testing/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: testing
+description: "The working checklist for writing tests. Strategy lives in the testing-standards rule; each platform has its own skill. Use for any phase that writes or changes tests."
+---
+
+# Skill: Testing
+
+## When to Use
+Phase involves writing tests or improving coverage. The strategy lives in
+`.claude/rules/testing-standards.orchestra.md`; this is the working checklist.
+
+## Checklist
+- [ ] **Detect framework:** check package.json for vitest, jest, pytest — use the project's
+- [ ] **Read existing tests:** match style, naming, and file organisation
+- [ ] **Pick the right layer:** pure logic → unit. Anything touching I/O → integration through the real entry point
+- [ ] **Real database, never a mocked driver:** a fake repository returns what you told it to and cannot tell you the query is wrong
+- [ ] **Fake external services at the network boundary** (MSW or a stub server), never by mocking our own wrapper — the wrapper is the thing that breaks on a provider change
+- [ ] **Happy path, edge cases, and failures:** empty, null, boundary values, and the error branch with its reason
+- [ ] **Async behaviour:** resolve and reject, timeouts, ordering
+- [ ] **One assertion per concept:** the test name states the scenario
+- [ ] **Run them, then break the code and confirm they fail** — a test that has never failed has not been tested
+- [ ] **Isolation:** each test creates its own data; no shared seed fixture, no ordering dependency
+
+## Common Mistakes
+- Mocking the database → you test the mock. Use a real one in a container.
+- Mocking your own module instead of the network → the seam goes untested.
+- Snapshot tests as coverage → a snapshot passes while a handler stops firing.
+- Writing tests to move the coverage number → the gate has started doing harm; say so.
+- Testing implementation details → assert behaviour, not internal calls.
+- Imposing a new style on an existing project → match what is there.
+
+## Related
+
+Each platform has a different shape, and the differences are not stylistic —
+they come from what the test runner can and cannot see.
+
+- Web: `.claude/skills/web-testing/SKILL.md` — jsdom has no layout engine, so
+  component tests run in real Chromium.
+- Mobile: `.claude/skills/mobile-testing/SKILL.md` — jest does not run React
+  Native; the device layer is not optional.
+- iOS: `.claude/skills/ios-testing/SKILL.md` — a green unit suite does not
+  prove the app launches.
+- Android: `.claude/skills/android-testing/SKILL.md` — a passing debug build
+  proves little about the release build.

package/template/skills/web-quality-audit/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: web-quality-audit
+description: "End-to-end quality review of a web app — performance, accessibility, SEO, best practices. Use when auditing an existing app rather than building a feature."
+---
+
+# Skill: Web Quality Audit
+
+## When to Use
+Phase involves comprehensive quality review of a web application — performance, accessibility, SEO, and best practices.
+
+## Checklist
+
+### Performance
+- [ ] Core Web Vitals pass (LCP <= 2.5s, INP <= 200ms, CLS <= 0.1)
+- [ ] Images compressed and properly sized (WebP/AVIF preferred)
+- [ ] JavaScript minified and tree-shaken
+- [ ] Critical CSS inlined, non-critical deferred
+- [ ] Lazy loading for below-the-fold images and components
+- [ ] Caching headers set for static assets (Cache-Control, ETag)
+
+### Accessibility
+- [ ] WCAG 2.1 AA compliant (run axe or similar audit)
+- [ ] Keyboard navigation works for all interactive elements
+- [ ] Screen reader tested (proper headings, landmarks, alt text)
+- [ ] Color contrast ratios meet minimums
+
+### SEO
+- [ ] Unique `<title>` and `<meta name="description">` per page
+- [ ] `robots.txt` present and correct
+- [ ] Sitemap.xml generated and submitted
+- [ ] Structured data (JSON-LD) for key content types
+- [ ] Canonical URLs set for duplicate content
+- [ ] Open Graph and Twitter Card meta tags present
+
+### Best Practices
+- [ ] HTTPS everywhere, no mixed content
+- [ ] No vulnerable dependencies (`npm audit`)
+- [ ] Error pages (404, 500) are user-friendly
+- [ ] Console has no errors or warnings in production
+- [ ] No deprecated APIs used
+
+## Common Mistakes
+- Optimizing only one metric → all four areas matter for real quality
+- Ignoring SEO on SPAs → search engines need server-rendered content or prerendering
+- No structured data → misses rich snippets in search results
+- Performance testing only on fast networks → test on 3G/slow 4G too
+- Missing error pages → users see raw error messages

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

@@ -0,0 +1,120 @@
+---
+name: web-testing
+description: "Testing strategy for React web apps — Vite SPA and Next.js. Use for any phase that writes or changes tests in a web app, or that adds an e2e flow."
+---
+
+# Skill: Web Testing
+
+## The fact everything else follows from
+
+**jsdom is not a browser.**
+
+It has no layout engine. `getBoundingClientRect` returns zeros, nothing
+scrolls, CSS is parsed but never applied, focus order is approximated, and
+`:hover`, media queries and container queries do not exist. A component can
+be invisible, unclickable, or overlapping another and every jsdom test still
+passes.
+
+So component tests run in **real Chromium** through Vitest browser mode.
+That is already configured by the stack — do not replace it with jsdom
+because a test is awkward. The awkwardness is usually the bug.
+
+## The layers
+
+| Layer | What belongs here | Runs in |
+|---|---|---|
+| Pure logic | Formatting, validation, reducers, date and money math — extracted **out** of components | Node |
+| Component | Render, interact, assert behaviour and accessibility | **Real Chromium** |
+| API seam (MSW) | Our own backend, faked at the network layer | Chromium |
+| E2E (Playwright) | 3–5 journeys against the **built** app | Real browser |
+| Build | `vite build` / `next build` | The gate |
+
+## Query by role, never by test id
+
+```ts
+screen.getByRole("button", { name: "Save changes" });   // yes
+screen.getByTestId("save-btn");                          // no
+```
+
+Testing Library resolves roles from the accessible tree. Query that way and
+**a div-with-onClick fails the test** — accessibility stops being a review
+checklist item and becomes something the suite enforces.
+
+A `testID` proves a node exists. It proves nothing about whether a keyboard
+or a screen reader can reach it.
+
+Order of preference: role → label → text → `getByTestId` only for something
+genuinely not user-visible.
+
+## Assert accessibility, do not eyeball it
+
+Querying by role already fails a test when a control has no accessible name.
+axe covers what a role query cannot see — contrast, duplicate landmarks,
+orphaned labels, invalid ARIA — and all of it is mechanical, so a machine
+catches it every run instead of a human at review time.
+
+The stack wires two levels, and they see different things:
+
+```ts
+// component test — the mounted subtree
+import { expectNoA11yViolations } from "../test/a11y";
+
+await expectNoA11yViolations(screen.container);
+```
+
+```ts
+// e2e/a11y.spec.ts — the whole built page, already written for you
+const results = await new AxeBuilder({ page }).analyze();
+```
+
+Contrast against the real background, landmark structure and heading order
+only exist on the full page. A component test cannot see any of them, which
+is why both levels are there.
+
+`region` and `page-has-heading-one` are disabled for component tests: a
+mounted subtree legitimately has neither, and a rule that always fails
+trains people to ignore the report.
+
+See `.claude/skills/accessibility/SKILL.md` for what the rules mean.
+
+## The workbench is the render target
+
+`react-cosmos` fixtures are the same artefact used by design parity
+(`.claude/rules/design-parity.orchestra.md`). Write the fixture once: the
+component test renders it, and the parity check screenshots it.
+
+A fixture renders deterministically. A live screen carries real data,
+loading states and timing — differences that have nothing to do with the
+component.
+
+## E2E is about journeys, not components
+
+Three to five, against the **built** app, never the dev server. A dev server
+hides exactly what this layer exists to catch: a bad production bundle, a
+missing environment variable, a route that only resolves in development.
+
+`e2e/smoke.spec.ts` is written by the stack and asserts the app boots and
+throws nothing on load. Add: sign in and survive a reload; the one flow the
+product exists for; and that flow's failure path.
+
+Each one costs a build and a browser. A suite nobody trusts is worse than
+no suite.
+
+## Never
+
+- **Snapshot tests.** Enormous, unread, and "updated" reflexively. A
+  snapshot passes while the click handler stops firing.
+- **jsdom**, for anything about layout, visibility or focus.
+- Testing that the router routes, or that React re-renders. Assert that
+  pressing the control calls the thing with the right argument.
+- Chasing the coverage number through page composition files. The value is
+  in the logic modules, the components, and the journeys.
+
+## The build is part of the suite
+
+`tsc --noEmit` accepts a Next.js app that fails `next build` on a
+server/client boundary or a static-generation error. Neither tests nor lint
+load the bundler.
+
+The gate runs `build` for exactly this reason. When it fails, the fix is the
+code — never a loosened config.