@coralai/sps-cli 0.42.0 → 0.43.0

package/skills/devops-automator/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: devops-automator
+description: Persona skill — automate everything repeatable, measure everything deployable, rehearse every rollback. Overlay on top of `devops`. For the patterns, load `devops`.
+origin: agency-agents-fork + original (https://github.com/msitarzewski/agency-agents, MIT)
+---
+
+# DevOps Automator
+
+Think in pipelines, not heroics. Every manual step is a future incident.
+
+## When to load
+
+- Setting up / reviewing CI/CD
+- Building a new deploy topology
+- Writing a runbook
+- Triaging a deploy or infra issue
+- Deciding "should this be a manual step or automated?"
+
+## The posture
+
+1. **Automate the boring.** Manual steps are breeding grounds for incidents. If it's done twice, it's a script.
+2. **Same artifact dev → prod.** Build once; promote. Building per-environment hides bugs.
+3. **Rollback is a command, not a procedure.** If rollback takes a checklist, the checklist is the bug.
+4. **Observability is pre-launch.** Dashboards + alerts + runbooks exist before the first deploy.
+5. **Plan for the 3am self.** Will you remember at 3am, with dogs barking? Write it down.
+6. **Infrastructure is code.** Clicks in consoles are for exploration, not for prod.
+7. **Least privilege, always.** CI keys, service accounts, human access — scoped.
+
+## The questions you always ask
+
+- **What happens if this step fails partway?** Idempotent? Rerunnable?
+- **What does rollback look like?** One command. Tested.
+- **What signals say "go ahead" to promote?** Metrics + alerts, not vibes.
+- **Who sees this alert, and what do they do?** Runbook.
+- **What's the blast radius of a bad deploy?** Pod / service / cluster / region?
+- **How do we know what's running in prod right now?** SHA / tag should be a keystroke away.
+- **Who has access to prod?** Named humans, not shared creds.
+- **Is this reproducible on a fresh environment?** Disaster recovery test.
+
+## The checklist — shipping a new service
+
+### CI / CD
+- [ ] Lint, typecheck, unit tests, integration tests in pipeline.
+- [ ] Cache deps; pipeline < 10 min on typical change.
+- [ ] Build artifact once; immutable tag.
+- [ ] Gate prod on explicit approval.
+- [ ] Pipeline secrets scoped per env, rotated on a schedule.
+- [ ] Dependency scanning + image scanning.
+
+### Infra
+- [ ] Every resource in IaC (Terraform / Pulumi / CDK / etc.).
+- [ ] State remote + locked + encrypted.
+- [ ] Env-specific variables, not code forks.
+- [ ] Tagging strategy applied everywhere.
+- [ ] Cost allocation visible.
+
+### Deploy
+- [ ] Rolling / canary / blue-green chosen with reason.
+- [ ] Health checks: live vs. ready.
+- [ ] Graceful shutdown on SIGTERM.
+- [ ] Resource limits (CPU, mem, replicas) sized, not defaults.
+- [ ] Feature flags for behaviour-changing releases.
+- [ ] Rollback command documented and tested.
+
+### Secrets
+- [ ] All secrets in a secret manager.
+- [ ] Runtime fetch via workload identity, not long-lived keys.
+- [ ] Rotation schedule defined.
+- [ ] Pre-commit / CI scanning for leaked secrets.
+
+### Observability
+- [ ] Structured logs to stdout.
+- [ ] Four golden signals exposed.
+- [ ] Traces propagated through service boundaries.
+- [ ] Dashboards on first-day launch.
+- [ ] Alerts on symptoms (user impact), not infrastructure noise.
+- [ ] Runbook linked from every alert.
+
+### Backup & DR
+- [ ] Automated backups + tested restore.
+- [ ] Cross-region replication if applicable.
+- [ ] Recovery time objective (RTO) and recovery point objective (RPO) documented.
+- [ ] Disaster recovery drill at least yearly.
+
+## What you push back on
+
+- **"Just SSH in and run this"** as a solution. That's a bug you haven't fixed.
+- **Secrets in env vars set by hand.** Use the secret manager.
+- **Deploys without metrics backing "looks fine"** at the end.
+- **Manual gates that could be automated.** Automated + logged is more trustworthy than "Alice always checks".
+- **Latest-tag deploys.** Never rollback-able.
+- **Dashboards that nobody watches.** Prune.
+- **Alerts that fire and "auto-resolve".** Either it's actionable or it's noise.
+
+## Tradeoffs you name
+
+- **Deploy speed vs. safety gates.** Small deploys can be fast; big ones need gates.
+- **Monolith vs. microservices ops cost.** Each service is its own pipeline, dashboard, alert set.
+- **Own vs. managed.** Self-hosted is cheaper until you count the oncall load.
+- **Auto-healing vs. alert-first.** Orchestrator restarts hide problems. Strike a balance.
+
+## Standard runbook skeleton
+
+```markdown
+# Runbook: <alert name>
+
+## What this means
+One sentence. Who is affected, what's failing.
+
+## Immediate checks
+1. Dashboard link.
+2. Recent deploys link.
+3. Dependency status page.
+
+## Common causes
+- Cause A → check X.
+- Cause B → check Y.
+
+## Mitigation (in order)
+1. Fast: roll back if recent deploy.
+2. Medium: scale up / restart pool.
+3. Slow: escalate to service owner.
+
+## Escalation
+- Primary: @service-owner
+- Secondary: @infra
+- SLA: respond within 15 min
+```
+
+Every alert has one. Update as you learn.
+
+## What a good postmortem looks like
+
+Blameless. Focused on the system.
+
+```
+Summary: One paragraph.
+Impact: Users affected × time × severity.
+Timeline: Minute-by-minute from detection to resolution.
+Root cause: Technical (what broke) AND process (why we didn't catch it).
+Action items: Specific, owned, dated. Tracked.
+Lessons: What surprised us.
+```
+
+Track action items to completion. The same incident should never happen twice for the same reason.
+
+## Forbidden patterns
+
+- Prod secrets on a developer laptop
+- Deploy requires "call John"
+- Untagged, unversioned images in prod
+- "It worked in staging" without staging mirroring prod
+- Alerts without runbooks
+- IaC changes that were really cloud-console changes
+- Long-lived API keys / tokens
+- Pipelines that mask real test failures with `|| true`
+- Single point of failure: one person knows how to deploy
+- Deploys without a recorded event (can't correlate with incidents)
+
+## Pair with
+
+- [`devops`](../devops/SKILL.md) — the patterns and recipes.
+- [`backend/references/observability.md`](../backend/references/observability.md) — app-level signal definitions.
+- [`coding-standards`](../coding-standards/SKILL.md) — how the pipelines enforce quality.

package/skills/frontend/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: frontend
+description: Frontend end skill — components, state, routing, performance, accessibility, testing. Language-neutral (React / Vue / Svelte / SolidJS patterns described conceptually). Pair with a language skill and `coding-standards`.
+origin: ecc-fork + original (https://github.com/affaan-m/everything-claude-code, MIT)
+---
+
+# Frontend
+
+Client-side architecture. **Framework-agnostic by design** — examples use pseudocode or a generic component model. Pair with a language skill (`typescript`) and a framework choice.
+
+## When to load
+
+- Building or reviewing UI in the browser (web / PWA / Electron)
+- State management: local, server, global
+- Routing, navigation, deep linking
+- Rendering performance, bundle size
+- Accessibility, i18n, SEO
+- Frontend testing (component, E2E)
+
+## Core principles
+
+1. **State is the hard part. Components are easy.** Get state shape right and most code writes itself.
+2. **Server state ≠ client state.** Use a dedicated tool (TanStack Query, SWR, Apollo) for server state; don't cram it into your global store.
+3. **Derive, don't duplicate.** If two pieces of state must stay in sync, at least one is derived.
+4. **Optimistic UI for responsiveness, reconciliation for correctness.** Show the expected result immediately; update on server response.
+5. **Measure before optimizing.** Bundle analyzer, Lighthouse, React Profiler / equivalent.
+6. **Accessibility is not optional.** Keyboard navigation, semantic HTML, color contrast, screen-reader labels.
+7. **Keep components dumb.** Props in, events out. Move side effects to hooks / composables / stores.
+
+## How to use references
+
+| Reference | When to load |
+|---|---|
+| [`references/components.md`](references/components.md) | Component shape, props, composition, slots / children, separation of concerns |
+| [`references/state.md`](references/state.md) | Local vs. shared, server state, derived, stores, forms |
+| [`references/routing.md`](references/routing.md) | Client routing, navigation, deep linking, query params, guards |
+| [`references/performance.md`](references/performance.md) | Rendering cost, code-splitting, virtualization, images, fonts |
+| [`references/accessibility.md`](references/accessibility.md) | Semantic HTML, keyboard, ARIA, focus management, contrast |
+| [`references/testing.md`](references/testing.md) | Component tests, snapshot tests, E2E (Playwright), visual regression |
+
+## Forbidden patterns (auto-reject)
+
+- Business logic inside presentational components
+- Global mutable state for server data (keep server data in a cache, not in Redux/Zustand directly)
+- Fetching in a loop of unrelated components (N+1 on the client)
+- Mutating props
+- `any` / untyped props (in typed frontends)
+- Accessibility via `role="button"` on a `<div>` when `<button>` works
+- Inline styles driven by state when a class + CSS toggle would do
+- `dangerouslySetInnerHTML` / `v-html` without a sanitizer
+- `useEffect` / `watchEffect` for derivations — use computed values
+- Animation / loading state toggled by timeouts instead of by actual completion events

package/skills/frontend/references/accessibility.md

@@ -0,0 +1,222 @@
+# Accessibility
+
+Semantic HTML, keyboard, ARIA, focus, contrast. Not optional.
+
+## Who benefits
+
+- 15–20% of users have a disability (motor, visual, cognitive, temporary).
+- Everyone benefits from good a11y: keyboard shortcuts, screen readers, screen-reader-like voice assistants, low-light contrast, slow networks.
+
+Treat it as a correctness requirement, not a "nice to have".
+
+## Semantic HTML first
+
+Every control you use should be the right element for the job.
+
+| Use | For |
+|---|---|
+| `<button>` | Action |
+| `<a href>` | Navigation |
+| `<form>` | Group inputs, submit behaviour |
+| `<input type="checkbox">` / `<input type="radio">` | Single / exclusive choice |
+| `<select>` / `<option>` | Enumerated choice from list |
+| `<label>` | Associate text with an input |
+| `<fieldset>` / `<legend>` | Group related inputs |
+| `<nav>`, `<main>`, `<aside>`, `<header>`, `<footer>` | Landmarks |
+| `<h1>` … `<h6>` | Document outline |
+
+**Rule**: if the right element exists, use it. `<div onClick>` with `role="button"` is twice the work and half the behaviour.
+
+## Keyboard navigation
+
+Every interactive control must be operable with keyboard only:
+
+- **Tab** / **Shift+Tab** — move focus.
+- **Enter** / **Space** — activate (varies: buttons on both, links on Enter).
+- **Arrows** — move within composite widgets (menus, tablists, listboxes, grids).
+- **Escape** — dismiss modal, popover, typeahead.
+
+Test periodically: unplug the mouse.
+
+### Visible focus
+
+Don't remove the focus outline.
+
+```css
+/* ❌ */
+*:focus { outline: none; }
+
+/* ✅ style it, don't remove it */
+:focus-visible {
+  outline: 2px solid var(--color-focus);
+  outline-offset: 2px;
+}
+```
+
+`:focus-visible` shows on keyboard focus but not mouse click — best of both.
+
+### Focus management
+
+Modal opens → move focus into the modal. Modal closes → return focus to the trigger.
+
+```
+function Modal() {
+  useEffect(() => {
+    const prev = document.activeElement;
+    firstInput.focus();
+    return () => prev.focus();        // restore on unmount
+  }, []);
+}
+```
+
+Route changes → announce and move focus to the new page's `<h1>` or main landmark (framework routers handle some of this; verify).
+
+## ARIA — the rule
+
+First rule of ARIA: **don't use ARIA.** Use semantic HTML. Every ARIA attribute is a hand-maintained contract with assistive tech; native elements get it for free.
+
+When you must use ARIA (custom widgets), follow the [ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/) patterns — they are the source of truth.
+
+Common attributes:
+
+| Attribute | Meaning |
+|---|---|
+| `aria-label` | Override accessible name (use sparingly) |
+| `aria-labelledby` | Name by reference to another element |
+| `aria-describedby` | Extra hint / help text |
+| `aria-hidden="true"` | Hide purely decorative element from AT |
+| `aria-live="polite"` / `"assertive"` | Announce changes |
+| `aria-expanded` | Disclosure state on buttons |
+| `aria-controls` | Associates a control with the thing it controls |
+| `aria-current` | The active item in a set (e.g. nav) |
+
+Rules:
+- Don't set `aria-hidden` on a focusable element — screen readers skip, but keyboard doesn't.
+- Don't name duplicates: `<button aria-label="Close">Close</button>` — pick one.
+
+## Labels and descriptions
+
+Every form control has a label. Either:
+
+```
+<label for="email">Email</label>
+<input id="email" name="email">
+
+<!-- or wrap -->
+<label>
+  Email
+  <input name="email">
+</label>
+```
+
+Placeholder is NOT a label. It disappears on focus and has poor contrast.
+
+For help text / errors:
+
+```
+<label for="pw">Password</label>
+<input id="pw" type="password" aria-describedby="pw-help pw-err">
+<span id="pw-help">At least 12 chars.</span>
+<span id="pw-err" role="alert">Too short.</span>
+```
+
+## Color contrast
+
+Minimum WCAG AA:
+- Normal text vs. background: **4.5 : 1**
+- Large text (18 pt+ or 14 pt bold+): **3 : 1**
+- UI components (border, icon vs. background): **3 : 1**
+
+Don't rely on color alone. "Red = error" + icon + text is accessible; red alone isn't for the color-blind.
+
+Tools: Lighthouse flags most contrast issues; for design systems, contrast-aware token generators (radix colors, Open Props).
+
+## Live regions — announce changes
+
+Status updates that aren't caused by the user's last action (notifications, background sync) need an ARIA live region.
+
+```
+<div aria-live="polite" aria-atomic="true">
+  {status}
+</div>
+
+<!-- For urgent errors -->
+<div role="alert">
+  {errorMessage}
+</div>
+```
+
+`polite` queues the announcement; `assertive` / `role="alert"` interrupts. Use `assertive` sparingly.
+
+## Images and alt text
+
+- Content image: `<img alt="screen reader text">` describing what it shows.
+- Decorative image: `<img alt="">` (empty alt, NOT no alt).
+- SVG icon with text next to it: `<svg aria-hidden="true">`.
+- Standalone SVG icon that means something: provide an accessible name.
+
+## Motion and animation
+
+- Respect `prefers-reduced-motion`:
+  ```css
+  @media (prefers-reduced-motion: reduce) {
+    *, *::before, *::after { animation: none !important; transition: none !important; }
+  }
+  ```
+- Don't autoplay videos with audio.
+- Avoid content flashing more than 3 times per second (seizure risk).
+
+## Screen reader testing
+
+Two minutes in a screen reader beats an hour of reading spec.
+
+- macOS: **VoiceOver** (Cmd+F5).
+- Windows: **NVDA** (free) or **JAWS**.
+- iOS: **VoiceOver**. Android: **TalkBack**.
+
+Walk through key flows. If you can't complete a task with only voice output, neither can your users.
+
+## Automated testing
+
+Tools that catch a lot cheaply:
+
+- **axe-core** (or `@axe-core/react`, `vitest-axe`) — unit-test with it.
+- **Lighthouse a11y score** — smoke test in CI.
+- **Playwright / Cypress + axe** — E2E a11y checks.
+- **ESLint `jsx-a11y`** — catches basics at write time.
+
+Automated tools find roughly 30% of issues. The rest needs a human.
+
+## Common patterns — the right way
+
+| Widget | Key rules |
+|---|---|
+| Modal | Trap focus, restore on close, `aria-modal`, visible backdrop |
+| Menu | Button with `aria-expanded`, arrow-key navigation, Escape to close |
+| Tabs | Arrow keys move focus; Tab exits; `aria-selected` on active |
+| Combobox | WAI-ARIA APG pattern — complex; use a library |
+| Tooltip | `aria-describedby`, hover + focus triggers, escape to dismiss |
+| Toast | `role="status"` or `aria-live="polite"`, don't auto-dismiss critical messages |
+| Accordion | Button with `aria-expanded`, content with `role="region"` |
+
+## i18n hooks
+
+Accessibility overlaps with i18n:
+- `lang` attribute on `<html>` and on sections that differ.
+- `dir="rtl"` / `dir="ltr"` for text direction.
+- Locale-aware number / date formatting.
+
+## Anti-patterns
+
+| Anti-pattern | Fix |
+|---|---|
+| `<div onClick>` acting as a button | `<button>` |
+| `outline: none` with no replacement | Style `:focus-visible` |
+| Placeholder-as-label | Visible `<label>` |
+| Tab order that skips around visually | Match DOM order to visual order |
+| Modal without focus trap | Library (`focus-trap-react`) or correct hand-rolled |
+| Color-only error state | Add icon + text |
+| Auto-focusing unexpected things | Focus jumps break the user's place |
+| `aria-hidden` on a focusable control | Either hide visually too, or remove aria-hidden |
+| Missing `lang` | Set on `<html>` |
+| "Click here" link text | Descriptive link text: "Read the pricing guide" |

package/skills/frontend/references/components.md

@@ -0,0 +1,206 @@
+# Components
+
+Shape, composition, props, children / slots.
+
+## One responsibility per component
+
+A component that renders a user profile should not fetch the user. A component that fetches the user shouldn't render it.
+
+```
+<UserProfile data={user} onEdit={handleEdit} />       # presentational
+<UserProfileContainer userId={id} />                   # loads + renders
+```
+
+This split (presentational / container, or dumb / smart) keeps each piece testable in isolation. The container deals with data; the presentational piece with pixels.
+
+## Props in, events out
+
+Data flows down through props. Changes flow up through callbacks / emitted events.
+
+```
+<Button
+  label="Save"
+  disabled={!form.valid}
+  onClick={() => submit()}
+/>
+```
+
+Avoid:
+- Parents reaching into children via refs for non-imperative purposes.
+- Children calling setters on state that belongs to the parent.
+- Two-way binding magic that hides data flow.
+
+## Composition over configuration
+
+Accept children / slots, don't try to anticipate every variant with boolean props.
+
+```
+# ❌ exploding configuration
+<Card
+  hasHeader
+  hasFooter
+  headerText="Hi"
+  footerAction="Dismiss"
+  iconLeft
+  iconRight
+/>
+
+# ✅ composition
+<Card>
+  <CardHeader>Hi</CardHeader>
+  <CardBody>...</CardBody>
+  <CardFooter>
+    <Button onClick={dismiss}>Dismiss</Button>
+  </CardFooter>
+</Card>
+```
+
+Fewer props, more flexibility. The boundary between "configure a primitive" and "compose primitives" is roughly when boolean props start bumping past 3–4 that interact with each other.
+
+## Slots / children
+
+Every modern framework has a way to inject arbitrary content into a component:
+
+| Framework | Name |
+|---|---|
+| React | `children` (and render props) |
+| Vue | `<slot>` (named + scoped) |
+| Svelte | `<slot>` + named slots |
+| Solid | `children` |
+| Web Components | `<slot>` |
+
+Prefer these over passing JSX / VNodes through props. Slots / children are the idiomatic "here's your content".
+
+## Smart vs. dumb — the rough divide
+
+| Smart (container, hook, composable) | Dumb (presentational) |
+|---|---|
+| Fetches data | Renders what it's given |
+| Owns mutable state | Stateless (or local UI state only) |
+| Wires up events to side effects | Emits events, doesn't handle them |
+| Tests: usually via integration | Tests: snapshot / visual |
+
+The boundary is not rigid. Don't create a container for a `<Button>`. But for anything with data or non-trivial behaviour, having the data part extractable is a win.
+
+## Prop typing (typed frameworks)
+
+```ts
+type UserCardProps = {
+  user: User;
+  variant?: 'compact' | 'full';
+  onEdit?: (user: User) => void;
+};
+
+function UserCard({ user, variant = 'full', onEdit }: UserCardProps) { ... }
+```
+
+Rules:
+- Default values inline at destructure.
+- Optional callbacks are fine; treat them as optional behaviour.
+- Don't type `user: any` — if the shape is unclear, define the type.
+
+## Render props vs. hooks / composables
+
+Modern frameworks prefer hooks / composables for reusing logic. Render props / slot props are still useful for reusing *markup+logic* bundles (a `<Downshift>` combobox, a headless UI primitive).
+
+```
+# Hook — reuse logic
+function useDebouncedSearch(value, ms) {
+  const [debounced, setDebounced] = useState(value);
+  useEffect(() => { const t = setTimeout(() => setDebounced(value), ms); return () => clearTimeout(t); }, [value, ms]);
+  return debounced;
+}
+
+# Render prop / slot — reuse logic + markup hooks
+<Combobox items={items}>
+  {({ input, menu, option }) => (
+    <div>
+      <input {...input} />
+      <ul {...menu}>{items.map(i => <li {...option(i)}>{i.label}</li>)}</ul>
+    </div>
+  )}
+</Combobox>
+```
+
+## Controlled vs. uncontrolled inputs
+
+| Controlled | State in the parent; parent dictates the value |
+| Uncontrolled | State in the DOM; parent reads via ref on submit |
+
+Use controlled for forms with validation, dynamic enablement, real-time feedback. Use uncontrolled for simple forms where only the submit value matters — less re-render noise.
+
+## Forwarded refs — the escape hatch
+
+Let a parent attach a ref through a wrapping component to reach an underlying DOM node (focus a text input, scroll into view). Use sparingly — most needs are better solved with props.
+
+## Error boundaries
+
+Every app root should have a boundary that catches render errors and shows a graceful fallback. Otherwise one bad prop crashes the whole tree to white.
+
+```
+<ErrorBoundary fallback={<Error500 />}>
+  <App />
+</ErrorBoundary>
+```
+
+Don't wrap every component in its own boundary — a handful of strategic ones (app shell, each route, expensive widgets) is plenty.
+
+## Suspense / loading states
+
+Where the framework supports it, declarative loading UX beats imperative flags.
+
+```
+# Declarative
+<Suspense fallback={<Skeleton />}>
+  <UserCard id={id} />
+</Suspense>
+
+# Imperative — works too, more verbose
+{loading ? <Skeleton /> : <UserCard user={user} />}
+```
+
+## Folder structure — organize by feature
+
+```
+src/
+├── features/
+│   ├── user/
+│   │   ├── UserCard.tsx
+│   │   ├── UserCard.test.tsx
+│   │   ├── useUser.ts
+│   │   └── api.ts
+│   └── billing/
+│       └── ...
+├── shared/
+│   ├── components/          # truly shared primitives (Button, Input)
+│   ├── hooks/
+│   └── utils/
+└── app/
+    ├── routes.tsx
+    └── root.tsx
+```
+
+Organize by feature first, by type (components, hooks, utils) second. Kitchen-sink `components/` folders become dumping grounds.
+
+## Styling — pick one, consistent
+
+- **CSS modules / scoped styles** — simple, portable.
+- **Utility-first (Tailwind)** — fast to write, mature ecosystem, needs team buy-in.
+- **CSS-in-JS** — component-local; runtime cost varies.
+- **Design tokens** — common layer regardless of above choice (`--color-primary`, `var(...)`).
+
+Mixing strategies across the codebase is the antipattern, not the choice itself.
+
+## Anti-patterns
+
+| Anti-pattern | Fix |
+|---|---|
+| Huge props object passed through many layers | Composition / context / slots |
+| `useEffect` / `watchEffect` to "sync two states" | Derive one from the other |
+| Logic in JSX (`{users.filter(...).map(...).length > 0 && ...}`) | Extract to a named variable or helper |
+| Deep prop drilling | Context / store, or restructure component tree |
+| Rendering a component for each row of thousands | Virtualize (see `performance.md`) |
+| Side effects during render | Side effects belong in effects / handlers |
+| Mutating props or items inside `.map` | Make new objects / arrays |
+| Callback prop recreated on every render causing child re-renders | Memoize or lift |
+| Inline objects / arrays in deps arrays | Memoize or use stable refs |