@evertonferreira96/agents 0.0.0-stage → 0.1.0

package/.claude/skills/review-animations/STANDARDS.md

@@ -0,0 +1,187 @@
+# Animation Standards Reference
+
+The precise values, curves, and rules behind the review. Cite these in findings instead of approximating. Distilled from Emil Kowalski's design engineering philosophy.
+
+## Should it animate? (frequency table)
+
+| Frequency | Decision |
+| --- | --- |
+| 100+ times/day (keyboard shortcuts, command palette toggle) | No animation. Ever. |
+| Tens of times/day (hover effects, list navigation) | Remove or drastically reduce |
+| Occasional (modals, drawers, toasts) | Standard animation |
+| Rare / first-time (onboarding, feedback, celebrations) | Can add delight |
+
+**Never animate keyboard-initiated actions** — they repeat hundreds of times daily; animation makes them feel slow and disconnected. (Raycast has no open/close animation — correct for something used hundreds of times a day.)
+
+Valid purposes for motion: spatial consistency, state indication, explanation, feedback, preventing jarring change. "It looks cool" on a frequently-seen element is not valid.
+
+## Easing
+
+Decision order:
+- Entering or exiting → **`ease-out`** (starts fast, feels responsive)
+- Moving / morphing on screen → **`ease-in-out`**
+- Hover / color change → **`ease`**
+- Constant motion (marquee, progress) → **`linear`**
+- Default → **`ease-out`**
+
+**Never `ease-in` on UI.** It starts slow, delaying the exact moment the user is watching. `ease-out` at 200ms *feels* faster than `ease-in` at 200ms.
+
+Built-in CSS easings are too weak. Use strong custom curves:
+
+```css
+--ease-out: cubic-bezier(0.23, 1, 0.32, 1);        /* strong ease-out for UI */
+--ease-in-out: cubic-bezier(0.77, 0, 0.175, 1);    /* strong ease-in-out for on-screen movement */
+--ease-drawer: cubic-bezier(0.32, 0.72, 0, 1);     /* iOS-like drawer curve (Ionic) */
+```
+
+Find curves at [easing.dev](https://easing.dev/) or [easings.co](https://easings.co/) — don't hand-roll from scratch.
+
+## Duration
+
+| Element | Duration |
+| --- | --- |
+| Button press feedback | 100–160ms |
+| Tooltips, small popovers | 125–200ms |
+| Dropdowns, selects | 150–250ms |
+| Modals, drawers | 200–500ms |
+| Marketing / explanatory | Can be longer |
+
+**Rule: UI animations stay under 300ms.** A 180ms dropdown feels more responsive than a 400ms one. Faster spinners make load feel faster (same actual time). Instant tooltips after the first (skip delay + animation) make a toolbar feel faster.
+
+## Physicality
+
+- **Never `scale(0)`.** Start from `scale(0.9–0.97)` + `opacity: 0`. Nothing in the real world appears from nothing.
+- **Origin-aware popovers.** Scale from the trigger, not center:
+  ```css
+  .popover { transform-origin: var(--transform-origin); } /* Base UI */
+  ```
+  **Modals are exempt** — they appear centered in the viewport, keep `transform-origin: center`.
+- **Button press feedback.** `transform: scale(0.97)` on `:active`, `transition: transform 160ms ease-out`. Subtle (0.95–0.98). Applies to any pressable element.
+
+## Springs
+
+Feel natural because they simulate physics; no fixed duration — they settle on parameters. Use for: drag with momentum, "alive" elements (Dynamic Island), interruptible gestures, decorative mouse-tracking.
+
+```js
+// Apple-style (easier to reason about) — recommended
+{ type: "spring", duration: 0.5, bounce: 0.2 }
+
+// Traditional physics (more control)
+{ type: "spring", mass: 1, stiffness: 100, damping: 10 }
+```
+
+Keep bounce subtle (0.1–0.3); avoid bounce in most UI — reserve for drag-to-dismiss and playful interactions. Springs maintain velocity when interrupted (keyframes restart from zero), so they're ideal for gestures users may reverse mid-motion.
+
+Mouse interactions: interpolate with `useSpring` rather than tying value directly to mouse position (direct = artificial, no momentum). Only do this when the motion is decorative.
+
+## Interruptibility
+
+CSS **transitions** can be interrupted and retargeted mid-animation; **keyframes** restart from zero. For anything triggered rapidly (toasts being added, toggles), transitions are smoother.
+
+```css
+/* Interruptible — good for dynamic UI */
+.toast { transition: transform 400ms ease; }
+
+/* Not interruptible — avoid for dynamic UI */
+@keyframes slideIn { from { transform: translateY(100%); } to { transform: translateY(0); } }
+```
+
+Use `@starting-style` for entry without JS:
+
+```css
+.toast {
+  opacity: 1; transform: translateY(0);
+  transition: opacity 400ms ease, transform 400ms ease;
+  @starting-style { opacity: 0; transform: translateY(100%); }
+}
+```
+
+Legacy fallback: `useEffect(() => setMounted(true), [])` + `data-mounted` attribute.
+
+## Asymmetric timing
+
+Slow where the user is deciding, fast where the system responds.
+
+```css
+.overlay { transition: clip-path 200ms ease-out; }            /* release: fast */
+.button:active .overlay { transition: clip-path 2s linear; }  /* press: slow, deliberate */
+```
+
+## Performance
+
+- **Only animate `transform` and `opacity`** — they skip layout/paint and run on the GPU. `padding`/`margin`/`height`/`width`/`top`/`left` trigger all three rendering steps.
+- **Don't drive child transforms via a CSS variable on the parent** — it recalcs styles for all children. Set `transform` directly on the element.
+  ```js
+  element.style.setProperty('--swipe-amount', `${d}px`); // bad: recalc on all children
+  element.style.transform = `translateY(${d}px)`;        // good: only this element
+  ```
+- **Framer Motion shorthands are NOT hardware-accelerated.** `x`/`y`/`scale` run on the main thread via rAF and drop frames under load. Use the full transform string:
+  ```jsx
+  <motion.div animate={{ x: 100 }} />                          // drops frames under load
+  <motion.div animate={{ transform: "translateX(100px)" }} />  // hardware accelerated
+  ```
+- **CSS animations beat JS under load** — they run off the main thread; rAF-based animations stutter while the browser loads/scripts/paints. Use CSS for predetermined motion, JS for dynamic/interruptible.
+- **WAAPI** gives JS control with CSS performance (hardware-accelerated, interruptible, no library):
+  ```js
+  element.animate([{ clipPath: 'inset(0 0 100% 0)' }, { clipPath: 'inset(0 0 0 0)' }],
+    { duration: 1000, fill: 'forwards', easing: 'cubic-bezier(0.77, 0, 0.175, 1)' });
+  ```
+
+## Transforms & clip-path
+
+- **`translate` percentages** are relative to the element's own size — `translateY(100%)` moves by the element's height regardless of dimensions (how Sonner/Vaul position toasts/drawers). Prefer over hardcoded px.
+- **`scale()` scales children too** (font, icons, content) — a feature for press feedback.
+- **3D**: `rotateX/Y` + `transform-style: preserve-3d` for depth/orbit/flip without JS.
+- **`clip-path: inset(t r b l)`** is a powerful animation tool: each value eats in from that side. Uses: reveal-on-scroll (`inset(0 0 100% 0)` → `inset(0 0 0 0)`), hold-to-delete overlay, seamless tab color transitions (duplicate + clip the active copy), comparison sliders.
+
+## Gestures & drag
+
+- **Momentum dismissal**: don't require crossing a distance threshold — compute velocity (`Math.abs(distance)/elapsedMs`); dismiss if `> ~0.11`. A flick should be enough.
+- **Damping at boundaries**: dragging past a natural edge moves less the further you go (real things slow before stopping).
+- **Pointer capture** once dragging starts, so it continues when the pointer leaves bounds.
+- **Multi-touch protection**: ignore extra touch points after the drag begins (`if (isDragging) return`) — prevents jumps.
+- **Friction over hard stops** — allow over-drag with rising resistance rather than an invisible wall.
+
+## Masking imperfect crossfades
+
+When a crossfade shows two overlapping states despite tuning easing/duration, add subtle `filter: blur(2px)` during the transition to blend them into one perceived transformation. Keep blur < 20px (heavy blur is expensive, especially Safari).
+
+## Stagger
+
+Stagger group entrances; 30–80ms between items. Longer delays feel slow. Stagger is decorative — never block interaction while it plays.
+
+```css
+.item { opacity: 0; transform: translateY(8px); animation: fadeIn 300ms ease-out forwards; }
+.item:nth-child(2) { animation-delay: 50ms; }
+.item:nth-child(3) { animation-delay: 100ms; }
+@keyframes fadeIn { to { opacity: 1; transform: translateY(0); } }
+```
+
+## Accessibility
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  .element { animation: fade 0.2s ease; } /* keep opacity/color, drop transform-based motion */
+}
+@media (hover: hover) and (pointer: fine) {
+  .element:hover { transform: scale(1.05); } /* gate hover motion — touch fires false hovers on tap */
+}
+```
+
+```jsx
+const reduce = useReducedMotion();
+const closedX = reduce ? 0 : '-100%';
+```
+
+Reduced motion means fewer and gentler animations, not zero — keep transitions that aid comprehension, remove movement/position changes.
+
+## Debugging (recommend in reviews when feel is uncertain)
+
+- **Slow motion**: bump duration 2–5× or use DevTools animation inspector. Check colors crossfade cleanly, easing doesn't stop abruptly, `transform-origin` is right, coordinated properties stay in sync.
+- **Frame-by-frame**: Chrome DevTools Animations panel reveals timing drift between coordinated properties.
+- **Real devices** for gestures (drawers, swipe) — connect a phone, hit the dev server by IP, use Safari remote devtools.
+- **Fresh eyes next day** — imperfections invisible during development surface later.
+
+## Cohesion
+
+Match motion to the component's personality: playful can be bouncier; a professional dashboard should be crisp and fast. Sonner feels right partly because easing, duration, design, and even the name are in harmony — slightly slower, `ease` rather than `ease-out`, to feel elegant. Opacity + height in entering/exiting lists is trial and error; there's no formula — adjust until it feels right.

package/.claude/skills/review-animations/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Review Animations"
+  short_description: "Reviews animation and motion code against a high craft bar derived from Emil..."
+policy:
+  allow_implicit_invocation: false

package/.claude/skills/tdd/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: tdd
+description: Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests.
+---
+
+# Test-Driven Development
+
+TDD is the red → green loop. This skill is the reference that makes that loop produce tests worth keeping: what a good test is, where tests go, the anti-patterns, and the rules of the loop. Every section applies on every cycle: consult them before and during the loop, not after.
+
+When exploring the codebase, read `GLOSSARY.md` (if it exists) so test names and interface vocabulary match the project's domain language, and respect ADRs in the area you're touching.
+
+## What a good test is
+
+Tests verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't. A good test reads like a specification: "user can checkout with valid cart" tells you exactly what capability exists, and it survives refactors because it doesn't care about internal structure.
+
+See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines.
+
+## Seams: where tests go
+
+A **seam** is the public boundary you test at: the interface where you observe behavior without reaching inside. Tests live at seams, never against internals.
+
+**Test only at pre-agreed seams.** Before writing any test, write down the seams under test and confirm them with the user. No test is written at an unconfirmed seam. You can't test everything, so agreeing the seams up front is how testing effort lands on the critical paths and complex logic instead of every edge case.
+
+Ask: "What's the public interface, and which seams should we test?" Give each proposed seam a one-line note on what it catches and what it misses.
+
+When the shape of that interface is itself in question (how deep the module is, where the seam belongs, what the interface should expose), call the Skill tool with "codebase-design" for the vocabulary. It is the shared source of the module, interface, depth, seam, adapter, leverage and locality terms, and it is a reference to consult, not a session to run.
+
+## Anti-patterns
+
+- **Implementation-coupled**: mocks internal collaborators, tests private methods, or verifies through a side channel (querying the database instead of using the interface). The tell: the test breaks when you refactor but behavior hasn't changed.
+- **Tautological**: the assertion recomputes the expected value the way the code does (`expect(add(a, b)).toBe(a + b)`, a snapshot derived by hand the same way, a constant asserted equal to itself), so it passes by construction and can never disagree with the code. Expected values must come from an independent source of truth: a known-good literal, a worked example, the spec.
+- **Horizontal slicing**: writing all tests first, then all implementation. Bulk tests verify _imagined_ behavior: you test the _shape_ of things rather than user-facing behavior, the tests go insensitive to real changes, and you commit to test structure before understanding the implementation. Work in **vertical slices** instead: one test → one implementation → repeat, each test a **tracer bullet** that responds to what the last cycle taught you.
+
+## Rules of the loop
+
+- **Red before green.** Write the failing test first, then only enough code to pass it. Don't anticipate future tests or add speculative features.
+- **One slice at a time.** One seam, one test, one minimal implementation per cycle.
+- **Refactoring is not part of the loop.** It belongs to the review stage (see the `code-review` skill), not the red → green implementation cycle.

package/.claude/skills/tdd/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "TDD"
+  short_description: "Test-driven red-green-refactor"

package/.claude/skills/tdd/mocking.md

@@ -0,0 +1,59 @@
+# When to Mock
+
+Mock at **system boundaries** only:
+
+- External APIs (payment, email, etc.)
+- Databases (sometimes - prefer test DB)
+- Time/randomness
+- File system (sometimes)
+
+Don't mock:
+
+- Your own classes/modules
+- Internal collaborators
+- Anything you control
+
+## Designing for Mockability
+
+At system boundaries, design interfaces that are easy to mock:
+
+**1. Use dependency injection**
+
+Pass external dependencies in rather than creating them internally:
+
+```typescript
+// Easy to mock
+function processPayment(order, paymentClient) {
+  return paymentClient.charge(order.total);
+}
+
+// Hard to mock
+function processPayment(order) {
+  const client = new StripeClient(process.env.STRIPE_KEY);
+  return client.charge(order.total);
+}
+```
+
+**2. Prefer SDK-style interfaces over generic fetchers**
+
+Create specific functions for each external operation instead of one generic function with conditional logic:
+
+```typescript
+// GOOD: Each function is independently mockable
+const api = {
+  getUser: (id) => fetch(`/users/${id}`),
+  getOrders: (userId) => fetch(`/users/${userId}/orders`),
+  createOrder: (data) => fetch('/orders', { method: 'POST', body: data }),
+};
+
+// BAD: Mocking requires conditional logic inside the mock
+const api = {
+  fetch: (endpoint, options) => fetch(endpoint, options),
+};
+```
+
+The SDK approach means:
+- Each mock returns one specific shape
+- No conditional logic in test setup
+- Easier to see which endpoints a test exercises
+- Type safety per endpoint

package/.claude/skills/tdd/tests.md

@@ -0,0 +1,77 @@
+# Good and Bad Tests
+
+## Good Tests
+
+**Integration-style**: Test through real interfaces, not mocks of internal parts.
+
+```typescript
+// GOOD: Tests observable behavior
+test("user can checkout with valid cart", async () => {
+  const cart = createCart();
+  cart.add(product);
+  const result = await checkout(cart, paymentMethod);
+  expect(result.status).toBe("confirmed");
+});
+```
+
+Characteristics:
+
+- Tests behavior users/callers care about
+- Uses public API only
+- Survives internal refactors
+- Describes WHAT, not HOW
+- One logical assertion per test
+
+## Bad Tests
+
+**Implementation-detail tests**: Coupled to internal structure.
+
+```typescript
+// BAD: Tests implementation details
+test("checkout calls paymentService.process", async () => {
+  const mockPayment = jest.mock(paymentService);
+  await checkout(cart, payment);
+  expect(mockPayment.process).toHaveBeenCalledWith(cart.total);
+});
+```
+
+Red flags:
+
+- Mocking internal collaborators
+- Testing private methods
+- Asserting on call counts/order
+- Test breaks when refactoring without behavior change
+- Test name describes HOW not WHAT
+- Verifying through external means instead of interface
+
+```typescript
+// BAD: Bypasses interface to verify
+test("createUser saves to database", async () => {
+  await createUser({ name: "Alice" });
+  const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);
+  expect(row).toBeDefined();
+});
+
+// GOOD: Verifies through interface
+test("createUser makes user retrievable", async () => {
+  const user = await createUser({ name: "Alice" });
+  const retrieved = await getUser(user.id);
+  expect(retrieved.name).toBe("Alice");
+});
+```
+
+**Tautological tests**: Expected value restates the implementation, so the test passes by construction.
+
+```typescript
+// BAD: Expected value is recomputed the way the code computes it
+test("calculateTotal sums line items", () => {
+  const items = [{ price: 10 }, { price: 5 }];
+  const expected = items.reduce((sum, i) => sum + i.price, 0);
+  expect(calculateTotal(items)).toBe(expected);
+});
+
+// GOOD: Expected value is an independent, known literal
+test("calculateTotal sums line items", () => {
+  expect(calculateTotal([{ price: 10 }, { price: 5 }])).toBe(15);
+});
+```

package/.claude/skills/triage/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: triage
+description: One-pass intake for a raw bug report, feature request or ticket that is not yet shaped for work - classify it, check whether it already exists in the code, reproduce the bug or list exactly what is missing, size it S/M/L and return an agent-ready brief. Use when the user pastes an error, a support message, a Shortcut or GitHub ticket, or says "triage this"; never writes to the tracker.
+---
+
+# Triage
+
+Turn a raw report into something `orchestrate` can take, in one pass. No state machine, no tracker writes (rule `tickets`): the output is text the user pastes or approves.
+
+## 1. Read
+
+- The report as given; the ticket when an id is given (`gh issue view`, Shortcut text, read only).
+- `GLOSSARY.md` for the domain words; `graphify query` when `graphify-out/graph.json` exists; otherwise a targeted grep by **domain concept**, not by the report's wording.
+
+## 2. Classify and check
+
+- `bug` (something that worked, or should, does not), `enhancement` (new behavior), `question` (needs an answer, not a change).
+- Already implemented? Search for the behavior by concept and say where you looked. Found: verdict `already-implemented`, point to the code, stop.
+- Contradicts an Accepted ADR or an out-of-scope decision in the plan files? Verdict `wontfix-candidate` with the reference; the user decides.
+
+## 3. Verify (bugs only)
+
+Reproduce from the reporter's steps, at most three attempts, with a command you can show (test, curl, script, CLI with a fixture). Three outcomes:
+
+- **Confirmed**: the command and its output, redacted, plus the code path.
+- **Not reproduced**: what you ran, what you saw.
+- **Insufficient detail**: verdict `needs-info` with specific questions (version, environment, exact input, expected vs actual), never "please provide more info".
+
+## 4. Size
+
+S / M / L per `orchestrate` section 1, with the architecture and security triggers named when they apply. Unknown cause: say so; `orchestrate` makes the diagnosis the first ticket.
+
+## 5. Return
+
+```markdown
+## Triage: <title>
+Category: bug | enhancement | question
+Verdict: ready-for-agent | needs-info | already-implemented | wontfix-candidate
+Size: S | M | L (triggers: <none | architecture | security>)
+
+### Brief
+- Objective: <one sentence, user outcome>
+- Repro: <command> -> <observed>  (bugs; or "unknown cause")
+- Acceptance criteria: - [ ] ...
+- Paths: <where it lives, from the search>
+- Context: <facts established; glossary terms>
+
+### Needs info (only for needs-info)
+- <specific question>
+```
+
+Hand the Brief to `orchestrate` (S goes to `/quick`; M/L to the plan). Nothing here creates, updates or comments on a ticket.
+
+## It's working if
+
+- The user never has to re-read the original report: the Brief carries what matters and the repro proves it.
+- "Already implemented" and "wontfix" come with a code path or an ADR, not an opinion.
+- A `needs-info` lists questions a reporter can answer in one message.

package/.claude/skills/triage/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Triage"
+  short_description: "Shape a raw report into an agent-ready brief"