@vegastack/skills 0.5.0 → 0.7.0

package/skill/architect/references/web.md

@@ -0,0 +1,152 @@
+# Web — frontend, design system, backend/API taste
+
+## Project layout
+
+- Top-level `server/` (or `packages/*` server code) holds DB, services, integrations — it
+  is sacred: never imported from client code, enforced with `server-only` + a boundary
+  check. The app router lives in `src/app/`; features are self-contained modules under
+  `src/features/<domain>/` (components/hooks per feature); shared pieces in
+  `src/{components,hooks,lib,store,messages}/`. Pages stay thin — they compose features.
+- The house convention scopes agent instructions per directory (a short CLAUDE.md/AGENTS.md
+  at each boundary-bearing directory) — follow it where a project already does this.
+
+## Frontend architecture
+
+- Server state → RSC + TanStack Query; URL state → nuqs; ephemeral UI state → Zustand.
+  Remote/tenant data is never persisted client-side (IndexedDB/local-first was evaluated and
+  rejected for multi-tenant SaaS on governance grounds — a confirmed single-tenant/offline
+  product is the only exception, and that's a decision to ask for, not assume).
+- Next config: `output: 'standalone'`, `cacheComponents: true` (PPR flags no longer exist).
+  Query key factories live in non-`'use client'` `.keys.ts` modules so RSC pages can prefetch.
+- Server Components by default; `'use client'` only at the lowest leaf that needs it.
+  `/server` (or `packages/*` server code) is never imported from client code — `server-only`
+  plus a boundary check, not convention.
+- Request interception: on OpenNext/Cloudflare, `proxy.ts`/Node middleware does NOT work
+  as of 2026-08 (open adapter issues — see infra.md); use what the adapter actually
+  supports and re-check its docs per feature. Either way interception is never the auth
+  boundary (see security.md).
+- Internal navigation uses `next/link`; bare `<a>` only for true external links/downloads.
+- Never TypeScript `any` — `unknown` and narrow.
+- Dependencies: prefer the native/browser API when it covers the need
+  (`Intl.RelativeTimeFormat` over date-fns); self-implement simple behavior (a tween, a diff
+  view) by composing design-system primitives before adding a library; any non-trivial new
+  dependency needs a stated justification and approval. **Why:** self-contained code has no
+  supply-chain, licensing, or upgrade surface, and MK rejects "library because library".
+
+## Design system (consuming `@vegastack/design` / `@vegastack/ui`)
+
+- First-time setup in a fresh project (npm install, Tailwind wiring, provider, registry
+  auth) is a separate, already-built skill — `vegastack-consume` — use it; don't
+  re-derive the wiring here.
+- Consume through the package barrel, never deep imports; never edit shipped component files.
+  A missing component or variant is an upstream request MK decides — the recommended
+  interim pattern is a local presentational composition in the app (inferred — confirm on
+  first use); don't fork the system.
+- Semantic tokens only: no inline `style={}`, no arbitrary values (`bg-[#123]`, `h-[13px]`),
+  no raw palette classes (`bg-neutral-900`), not even for opacity. Dynamic values go through
+  CSS custom properties.
+- Visual language: borders-only cards, flat surfaces (shadows only for true overlays); accent
+  color rationed to the primary action and real selected/active state — never hover, roughly
+  ≤10 accent elements a page. Focus stays visible always (WCAG 2.2 AA floor) — the house
+  mechanism is a darker border or native outline, never a `ring-*` utility. Control heights
+  on the 28/32/40 scale = `h-7`/`h-8`/`h-10` (no off-scale `h-9`); radius: `rounded-md`
+  controls, `rounded-sm` menu items, `rounded-lg` containers, `rounded-full` pills — never
+  `rounded-xl` on cards/dialogs. Touch-target minimum is genuinely unresolved (24px WCAG AA
+  vs 44px mobile-HIG both appear in the record) — ask MK when it matters.
+- Typography: product code caps at `font-semibold` and uses it sparingly (inside the design
+  system package itself the cap is `font-medium`); headings `font-lora`; numbers, versions,
+  costs, and card digits always `font-mono`; uppercase only in mono at ≤14px. Fonts are
+  self-hosted via `next/font` — never a Google Fonts CDN request.
+- Icons: Lucide only. Toasts: sonner, never native/OS prompts. 4px spacing scale.
+- Motion: subtle and minimal — no button hover/press animations, no `transition-all`; motion
+  is for state feedback (success/error) and structural changes. `prefers-reduced-motion`
+  disables animation entirely (instant, not softened).
+- No decorative filler: no gratuitous badges, eyebrow text, or "3 of 3" counters — MK cuts
+  these on sight as AI-generated design tells.
+- Light AND dark theme on every shipped surface (internal-only tools may opt out, stated
+  up front).
+
+## UI completeness bar (every real surface, before it's "done")
+
+- Full state matrix: loading skeleton shaped like the real content · empty state with
+  guidance · error routed to the specific failure (401/403, 404, 410, 429, generic — never
+  swallowed into `{}`) · success feedback. Optimistic updates where a mutation changes
+  visible state; the UI reflects backend mutations without a manual refresh.
+- Forms: Enter submits; spinner replaces the button icon (not beside it); first field
+  auto-focused; all fields disabled while the primary action runs; state resets on error or
+  navigation.
+- Responsive: no horizontal scroll at any width; computed layout math, never hardcoded pixel
+  offsets; truncation driven by available space, not character counts; iOS inputs must not
+  zoom on focus; the mobile keyboard must never occlude the active input.
+- Systemic fixes: a defect found in one component (scroll leaking through an overlay, missing
+  cursor, wrong token) is fixed across the whole family in one sweep, with evidence.
+- Perceived speed is the named pattern "instant shell": the layout shell renders
+  immediately (RSC + `cacheComponents`), every data region streams in behind a skeleton
+  shaped like its content — never a blank page or a full-page spinner.
+- Long lists (>~50 rows) virtualize with `@tanstack/react-virtual` (the approved package —
+  still state the justification when adding it).
+- Cloning/rebranding a reference site: strip every trace of the source tool's provenance
+  (class names, external asset domains, meta) so the result is fully self-contained, and
+  verify parity by clicking through as a real user — screenshot diffing alone doesn't count.
+
+## SEO and metadata (every public-facing app)
+
+- Every route exports `metadata`/`generateMetadata` — not just the root layout. Public
+  apps ship `sitemap.ts` and `robots.ts`; `llms.txt` is generated at build time, never
+  hand-maintained. OG images follow the house convention (generated, mono for
+  names/numbers). i18n uses next-intl `localePrefix: 'as-needed'` (stack.md) so default-
+  locale URLs stay clean. **Why:** MK has demanded "100% SEO" coverage on shipped sites
+  twice — treat it as a completeness bar, not an enhancement.
+
+## Testing (web/backend — test where it pays off)
+
+- Unit-test services and pure logic (Vitest); component/a11y tests run in Vitest browser
+  mode with the Playwright provider (real Chromium — jsdom's ARIA/layout gaps produce
+  false a11y results and are not trusted).
+- E2E is a walking skeleton: one real happy path (boot → auth → core mutation → verify)
+  plus targeted adversarial invariants — not a blanket suite. DB-gated tests are authored
+  even when execution is blocked, and gated behind an env flag (`RUN_DB_TESTS=1` pattern);
+  E2E doubles implement real ports, never a parallel mock pathway.
+- Every confirmed bug gets a regression test; no coverage-percentage targets — "100%"
+  means audit completeness, never a coverage metric. VRT/demo content is deterministic
+  (no `Date.now()`/`Math.random()`).
+
+## Backend / API design
+
+- Contract-first: zod schemas are the single source → OpenAPI 3.1 under `/api/v1`, camelCase,
+  cursor pagination on every list, RFC 9457 problem-details errors with a stable error-code
+  catalog. One contract serves web, Flutter, MCP, and public consumers.
+- Every route: auth before parse, through the shared route-handler wrapper — no route-local
+  zod, no raw `request.json()`. Sanitize responses: secrets and credential references never
+  leave the server. Enforce with a CI ratchet (unwrapped routes fail the build), not review.
+- Return what the view renders, not everything — no mega-responses. Select columns explicitly.
+- Body limits stream: count bytes as they arrive and abort at the limit; never buffer the
+  whole body first.
+- Webhooks over polling; the database is the source of truth. Once provider state lands in
+  Postgres via webhook, don't re-poll the provider — and don't build intermediary "waiting"
+  pages; redirect on success and let the rest arrive in the background.
+- Money paths (Stripe): isolated intake (own worker or route), idempotency keys on every
+  mutation, event dedupe, append-only ledgers as the single cost source of truth, audit
+  events written in the same transaction as the business change. Pricing/quoting math is
+  deterministic code with server-enforced invariants — AI drafts and judges; deterministic
+  code calculates and enforces (a proven client-project pattern; treat as the strong
+  default for money paths).
+- Centralize the boring: one ID helper (never raw `crypto.randomUUID` scattered), one logger
+  (never `console.log`; request/org context auto-injected; never log secrets or PII beyond
+  user IDs), one typed fail-hard zod env parser validated at startup — no
+  `DISABLE_AUTH`-style escape hatches, no plaintext fallbacks.
+- Dead endpoints get deleted, not deprecated-and-kept. (Exception: a versioned `/api/v1`
+  contract consumed by a shipped mobile app outlives web deploy cycles — app-store install
+  lag means mobile clients keep the old contract alive; see mobile.md.)
+- Outbound webhooks to customers (when a product offers them): a defined event catalog,
+  Standard Webhooks-style signing with rotatable secrets, delivery via the transactional
+  outbox → queue with retries/backoff, auto-disable an endpoint after N consecutive
+  failures, and a replay surface. Never fire webhooks inline from request handlers.
+- Platform-native mentions over plain text: when the data allows it, resolve and mention
+  the real entity (Slack user @mentions, Notion Person fields) instead of rendering names
+  as text — the recurring "don't just fix, improve" integration principle.
+- Wizard/checkout flow-state persistence (Zustand + sessionStorage vs server-side draft)
+  is not yet a settled house rule — ask MK when building one.
+- Rate-limited responses return 429 with a `Retry-After` header.
+- Timestamps stored UTC (`timestamptz`), rendered in the user's timezone; durations as
+  integer milliseconds; money in integer minor units.

package/skill/architect/refresh/REFRESH.md

@@ -0,0 +1,29 @@
+# Freshness contract — architect
+
+Most of this skill is durable taste and recorded decisions; it does not go stale on its
+own. Exactly one file decays with the platform landscape: `references/pinned-facts.md`
+(plus the version claims embedded in `references/stack.md` and `references/mobile.md`).
+
+## Mechanism
+
+1. **Weekly scheduled agent (primary).** A scheduled Claude Code/Codex job re-verifies
+   each pinned fact against its stated source URL and opens ONE pull request quoting
+   evidence for anything that changed (fact text, version, date, source). The diffing
+   judgment lives in the agent run, not in maintained scripts. The PR is human-reviewed —
+   never auto-merged.
+2. **Refresh-on-use (safety net, written into SKILL.md).** When a recommendation leans on
+   a pinned fact older than 60 days, the consuming agent re-verifies that one fact first
+   and says so. Never bulk-refresh in-session.
+3. **Registry baseline (`sources.json`).** The repo-shared refresh runner
+   (`tooling/refresh/refresh-evidence.mjs`) keeps checksum baselines for the critical
+   source pages so CI can detect upstream drift deterministically between weekly runs.
+
+## Rules
+
+- Critical sources (Hyperdrive supported versions, Better Auth docs, eve/Workflow SDK
+  deploy constraints) get `critical: true` — drift there warrants a prompt PR, not a
+  batch.
+- Every edited fact keeps the pattern: fact → why it changes a decision → source URL →
+  verified date. The file carries one blanket verified-date for facts checked together;
+  a fact re-verified alone gets its own inline date, superseding the blanket one.
+- A fact that stops being decision-changing is deleted, not kept for completeness.

package/skill/architect/refresh/sources.json

@@ -0,0 +1,244 @@
+{
+  "schemaVersion": 1,
+  "policy": {
+    "criticalTopics": [
+      "hyperdrive-postgres",
+      "better-auth",
+      "eve-deploy"
+    ],
+    "defaultChecksumScope": "html-text-v1",
+    "offline": "Use cached metadata only; fail closed when a critical entry is missing or older than thresholdDays.",
+    "drift": "Any drift requires reading the changed page and a human-reviewed PR updating references/pinned-facts.md (and version claims in references/stack.md / references/mobile.md); never auto-apply.",
+    "copyright": "Store claim metadata, URLs, hashes, and concise excerpts only; never archive third-party documentation corpora.",
+    "cadence": "weekly scheduled-agent refresh; thresholdDays must be >= 14 (2x cadence) so a single missed run never breaches a threshold"
+  },
+  "sources": [
+    {
+      "id": "CF-HYPERDRIVE-VERSIONS",
+      "service": "Cloudflare Hyperdrive supported databases",
+      "kind": "official-docs",
+      "stability": "vendor-docs",
+      "thresholdDays": 14,
+      "critical": true,
+      "urls": {
+        "primary": "https://developers.cloudflare.com/hyperdrive/reference/supported-databases-and-features/"
+      },
+      "versionDetection": {
+        "type": "manual-review"
+      },
+      "topics": [
+        "hyperdrive-postgres"
+      ],
+      "affected": [
+        "references/pinned-facts.md",
+        "references/stack.md",
+        "references/data.md"
+      ],
+      "checksum": "fda2870b95deffce48dca7f3df3707325b1bc4a2d58a17708ee9220bfba5eba1",
+      "retrievedAt": "2026-08-12T14:33:11.062Z"
+    },
+    {
+      "id": "CF-R2-PRICING",
+      "service": "Cloudflare R2 pricing",
+      "kind": "official-docs",
+      "stability": "vendor-docs",
+      "thresholdDays": 30,
+      "critical": false,
+      "urls": {
+        "primary": "https://developers.cloudflare.com/r2/pricing/"
+      },
+      "versionDetection": {
+        "type": "manual-review"
+      },
+      "topics": [
+        "r2-economics"
+      ],
+      "affected": [
+        "references/pinned-facts.md",
+        "references/stack.md"
+      ],
+      "checksum": "bd5e8d26f7bbf2f92182ad4ac1a59ae9b1d90695120062adaf54c281bd88e81f",
+      "retrievedAt": "2026-08-12T14:33:11.062Z"
+    },
+    {
+      "id": "CF-WORKFLOWS-PRICING",
+      "service": "Cloudflare Workflows limits and pricing",
+      "kind": "official-docs",
+      "stability": "vendor-docs",
+      "thresholdDays": 30,
+      "critical": false,
+      "urls": {
+        "primary": "https://developers.cloudflare.com/workflows/reference/limits/"
+      },
+      "versionDetection": {
+        "type": "manual-review"
+      },
+      "topics": [
+        "workflows"
+      ],
+      "affected": [
+        "references/pinned-facts.md",
+        "references/ai-agents.md"
+      ],
+      "checksum": "64e10ca4ced4edc042d12a9a24f2e165ea71cb9481c30ac5f067f2f6c9218cda",
+      "retrievedAt": "2026-08-12T14:33:11.062Z"
+    },
+    {
+      "id": "BETTER-AUTH-DOCS",
+      "service": "Better Auth documentation",
+      "kind": "official-docs",
+      "stability": "vendor-docs",
+      "thresholdDays": 14,
+      "critical": true,
+      "urls": {
+        "primary": "https://better-auth.com/docs/plugins/organization"
+      },
+      "versionDetection": {
+        "type": "npm",
+        "package": "better-auth"
+      },
+      "topics": [
+        "better-auth"
+      ],
+      "affected": [
+        "references/pinned-facts.md",
+        "references/security.md",
+        "references/stack.md"
+      ],
+      "currentVersion": "1.6.27",
+      "versionCheckedAt": "2026-08-12T14:33:11.062Z",
+      "checksum": "30edf1b6658a473a00005153a3eafc07de5c3decd6b8f09fc6c32f3a21c4db1c",
+      "retrievedAt": "2026-08-12T14:33:11.062Z"
+    },
+    {
+      "id": "EVE-DOCS",
+      "service": "Vercel eve agent framework",
+      "kind": "official-docs",
+      "stability": "beta",
+      "thresholdDays": 14,
+      "critical": true,
+      "urls": {
+        "primary": "https://vercel.com/docs/eve"
+      },
+      "versionDetection": {
+        "type": "npm",
+        "package": "eve"
+      },
+      "topics": [
+        "eve-deploy"
+      ],
+      "affected": [
+        "references/pinned-facts.md",
+        "references/ai-agents.md",
+        "references/stack.md"
+      ],
+      "currentVersion": "0.33.2",
+      "versionCheckedAt": "2026-08-12T14:33:11.062Z",
+      "checksum": "a777f9da0cb3966a9c7cc06a3c12be34b2928800b370e966e8b6e0f5a5622915",
+      "retrievedAt": "2026-08-12T14:33:11.062Z"
+    },
+    {
+      "id": "WORKFLOW-SDK-POSTGRES",
+      "service": "Workflow SDK Postgres world deployment constraints",
+      "kind": "official-docs",
+      "stability": "vendor-docs",
+      "thresholdDays": 14,
+      "critical": true,
+      "urls": {
+        "primary": "https://workflow-sdk.dev/worlds/postgres"
+      },
+      "versionDetection": {
+        "type": "npm",
+        "package": "@workflow/world-postgres"
+      },
+      "topics": [
+        "eve-deploy"
+      ],
+      "affected": [
+        "references/pinned-facts.md",
+        "references/ai-agents.md"
+      ],
+      "currentVersion": "4.3.3",
+      "versionCheckedAt": "2026-08-12T14:33:11.062Z",
+      "checksum": "3eca56b5ec9668638d4e00b290c157383dfe8ceaaa334de13bb6244b32fa6839",
+      "retrievedAt": "2026-08-12T14:33:11.062Z"
+    },
+    {
+      "id": "NEXTJS-BLOG",
+      "service": "Next.js release blog",
+      "kind": "official-docs",
+      "stability": "vendor-docs",
+      "thresholdDays": 30,
+      "critical": false,
+      "urls": {
+        "primary": "https://nextjs.org/blog"
+      },
+      "versionDetection": {
+        "type": "npm",
+        "package": "next"
+      },
+      "topics": [
+        "nextjs"
+      ],
+      "affected": [
+        "references/pinned-facts.md",
+        "references/web.md",
+        "references/stack.md"
+      ],
+      "currentVersion": "16.3.0",
+      "versionCheckedAt": "2026-08-12T14:33:11.062Z",
+      "checksum": "9d5d2503e2e8aa7ed1c3f0cb972c78e64b2e3aae5f3ad264bb0a79bd179708f0",
+      "retrievedAt": "2026-08-12T14:33:11.062Z"
+    },
+    {
+      "id": "PG-BOSS-NPM",
+      "service": "pg-boss job queue",
+      "kind": "package-registry",
+      "stability": "stable",
+      "thresholdDays": 30,
+      "critical": false,
+      "urls": {
+        "primary": "https://registry.npmjs.org/pg-boss/latest"
+      },
+      "versionDetection": {
+        "type": "npm",
+        "package": "pg-boss"
+      },
+      "topics": [
+        "jobs"
+      ],
+      "affected": [
+        "references/pinned-facts.md",
+        "references/ai-agents.md"
+      ],
+      "currentVersion": "12.27.0",
+      "versionCheckedAt": "2026-08-12T14:33:11.062Z",
+      "checksumScope": "http-body",
+      "checksum": "abf4bc2795e2df03181a21dfd29c7b9234c933a9dcafa72b4583d590cad609da",
+      "retrievedAt": "2026-08-12T14:33:41.513Z"
+    },
+    {
+      "id": "FLUTTER-RELEASES",
+      "service": "Flutter release notes",
+      "kind": "official-docs",
+      "stability": "vendor-docs",
+      "thresholdDays": 30,
+      "critical": false,
+      "urls": {
+        "primary": "https://docs.flutter.dev/release/release-notes"
+      },
+      "versionDetection": {
+        "type": "manual-review"
+      },
+      "topics": [
+        "flutter"
+      ],
+      "affected": [
+        "references/pinned-facts.md",
+        "references/mobile.md"
+      ],
+      "checksum": "94f9df6f67615ee05d826995f9709309c5453d0d8e4be11232ca5d463929ed2b",
+      "retrievedAt": "2026-08-12T14:33:11.062Z"
+    }
+  ]
+}

package/skill/dev-implement/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: dev-implement
+description: Implement an approved GitHub issue end to end without further user input. Use when given an issue to build - "do issue 12", "implement" plus an issue URL or number, "pick up the next ready issue", "go dark on" an issue - when returning to apply corrections the user left on a for-you issue, or when the user directly asks in chat for a quick fix or small change. Runs preflight, claims the issue, builds on a task branch, tests, gets independent review, and posts one evidence comment in the issue. Not for writing or approving issues (dev-intake), not for creating PRs or merging (dev-ship).
+---
+
+# dev-implement
+
+One issue, one session, end to end: preflight → claim → build dark → verify → review → evidence in the issue → stop. The user reads the result in the issue on their own time; nothing here creates a PR or merges — those are `dev-ship`, on the user's word.
+
+Nearest neighbor: `dev-intake` writes the brief this skill executes; if the issue turns out to need decisions, that's intake work — hand it back via `needs-you`, don't guess. `.vegastack/dev.md` missing → run `dev-setup` first. Read dev.md before anything; its knobs (review, ui-evidence, tests, branch, stop-list) govern this whole skill.
+
+## Direct requests
+
+The gates exist to stop agent-invented authority, never to slow the user down. When the user directly asks in chat for a change ("fix this typo", "bump that timeout"), their words are the approval — do it, verify it, and report; no issue required. Offer to record an issue when the change is material enough that its brief or evidence will matter later. Everything below is the path for issue-driven work.
+
+## Preflight — all must hold, or stop and say which failed
+
+- `gh auth status` works and the issue's repo matches dev.md.
+- The issue is open, labeled `ready`, and carries the recorded approval comment (`Approved by … : "…"`). A label without the comment is not approval.
+- No open blockers (issue dependencies) and no other assignee — an assigned or `working` issue belongs to someone else. A claim from a dead session is released only by the user: take over a `working` issue only when they explicitly hand it to you.
+- Read the complete brief, plus parent issue and milestone for context. If the brief leaves a material decision open — including an unresolved Assumptions entry — do not start: label `needs-you`, comment the smallest question that unblocks it, stop.
+- Re-verify the brief against reality before coding: its cited touch points against the current code (things drift between approval and execution), and volatile dependency claims when stale or version-sensitive. Reality contradicting the brief is a stop — label `needs-you` with the discrepancy; an approved brief is never a license to improvise past what's actually there.
+
+## Claim and branch
+
+Assign yourself, swap `ready` → `working`. Branch from the default branch: `<type>/<issue-number>-<short-slug>` (type from dev.md: feat, fix, docs, chore, refactor).
+
+## Build — dark
+
+No progress updates, no questions. A spike the brief flagged runs first — its result opens the evidence comment and shapes the rest of the build. Decide routine things yourself: file layout, helpers, fixtures, and root-cause fixes inside the issue's change areas. The brief's out-of-scope section and the dev.md stop-list bound you; hitting a stop condition (scope change, new dependency, spending, destructive/production action, unresolvable blocker) ends dark mode — post one `needs-you` comment stating the smallest decision needed with your recommendation, and stop.
+
+Honesty over green: a failing test gets fixed at the root or reported as failing. Weakening a test, an assertion, or acceptance to pass is a cover-up, and cover-ups surface at review with interest.
+
+## Verify
+
+- Run the tests dev.md requires (`tests: required` → every changed behavior has a test that runs and passes; `logic-only` → content/config tweaks may skip). Record commands and results for the evidence comment.
+- A `risky` issue gets focused security, failure, and recovery checks on top of the required tests.
+- UI changed and `ui-evidence: playwright` → capture screenshots of the key states and flows, push them to the evidence repo (dev.md `evidence-repo`) under `<repo>/<issue-number>/`, and link them. Links, not embeds — private-repo images don't render inline in issues. Evidence repo missing or unreachable → name the local file paths in the evidence comment and say so; the hand-back never blocks on it.
+
+## Independent review — per the dev.md knob
+
+- `subagent` (default): spawn a fresh reviewer subagent that gets the diff, the brief, and dev.md — and no memory of writing the code. It checks: does the change do what the brief says, does anything break, are the tests real? In a harness without subagents, do a separate fresh-eyes review pass against the brief and label it a self-review in the evidence comment; prefer cross-agent there for `risky` work.
+- `cross-agent` (or `cross-agent-risky` on a `risky` issue): push the branch, add to the evidence comment "awaiting cross-agent review", keep `working`, and tell the user which agent to point at the issue. The reviewing session posts findings on the issue; you apply them.
+- Fix real findings and rerun affected checks. Disagree with a finding → say why in the evidence comment rather than silently skipping it.
+
+## The evidence comment — exactly one, edited in place
+
+```
+## Result
+**Done:** what changed, in behavior terms
+**Tests:** <command> → <result summary>
+**Review:** <mode> — <findings fixed / none / disputed with reason>
+**UI evidence:** <links>            (when applicable)
+**Not done / limits:** the honest list
+Branch: <name> @ <short-sha>
+```
+
+Post it, swap `working` → `for-you`, unassign nothing, stop. Later corrections update this same comment — a stack of stale result comments hides the current truth.
+
+## Corrections loop
+
+The user's comments on a `for-you` issue are the new frontier: apply them, re-verify what they touch, update the evidence comment, back to `for-you`. Their corrections never need re-approval ceremony unless they change scope — then it's `needs-you` and dev-intake's recording rule.

package/skill/dev-implement/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "dev-implement"
+  short_description: "Implement an approved issue end to end, dark"
+  default_prompt: "Use $dev-implement to build this issue end to end."

package/skill/dev-implement/refresh/REFRESH.md

@@ -0,0 +1,3 @@
+# Refresh contract — dev-implement
+
+Evergreen: this skill asserts no version pins, vendor mechanism names beyond long-stable `gh` subcommands, numeric vendor limits, or dated facts — its content is workflow discipline (preflight, claiming, dark-mode bounds, review modes, the evidence-comment contract), all versionless. Harness mechanics are tracked by `dev-setup`'s registry. Revisit if a future edit introduces a volatile fact.

package/skill/dev-implement/refresh/sources.json

@@ -0,0 +1,6 @@
+{
+  "schemaVersion": 1,
+  "retrievalBaseline": "2026-08-27",
+  "note": "Evergreen waiver recorded in REFRESH.md; sources deliberately empty.",
+  "sources": []
+}

package/skill/dev-intake/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: dev-intake
+description: Turn ideas, brainstorms, feature requests, or SOW documents into GitHub issues an agent can implement without further questions. Use when asked to "turn this into issues", "create tasks from this SOW", "write up an issue for" a feature or bug, "plan this as issues", "slice this epic", or when the user gives approval on a drafted issue and it needs recording. Produces complete inline build briefs with labels, milestones, and blocker links. Not for implementing issues (dev-implement), creating PRs or merging (dev-ship), or project bootstrap (dev-setup).
+---
+
+# dev-intake
+
+Requirements come in as the user's brainstorm, feature thought, or SOW; issues go out complete enough that a fresh agent needs nothing but the URL. Every question gets asked **here** — once implementation starts, dark mode means no questions, so an under-specified issue becomes either an interruption or a guess. This skill exists to make both impossible.
+
+Nearest neighbor: `dev-implement` consumes what this produces — intake writes and gets approval, implement builds. If `.vegastack/dev.md` is missing, run `dev-setup` first, then continue here.
+
+## Ground before you ask
+
+Finding facts is your job, never the user's — and a brief built on unverified facts is a confident mistake waiting for dark mode. The source can be one sentence in chat; thinner material just means the grounding and interview carry more weight. Before the first question:
+
+- **Read the touched code.** Open the actual paths the feature would change: current behavior, existing patterns to reuse, where the new work plugs in. The brief cites these real paths later — a brief naming no files is a sign this step was skipped.
+- **Verify dependencies.** Any library, service, or API capability the approach leans on gets checked against current official docs (docs tools or web search), noted with the date. Consult `architect`'s pinned facts for stack questions before re-researching; re-verify a pinned fact older than 60 days; skip lookups for long-stable basics — judgment, not ritual.
+- **Cross-check the request** against product docs and current behavior. A contradiction is pushback, never a silent resolution: "you asked for X; the code/docs currently do Y — which wins?" Push back on cost the same way: when a simpler version covers most of the need, name it.
+- **Triage every unknown** into exactly three bins: *findable* → find it now, yourself; *only-the-user-knows* → ask, with a recommendation; *only-running-code-can-tell* → flag it as a spike that becomes the issue's first step. Guessing is not a bin.
+
+## The interview
+
+Ask in rounds using your harness's question tool (AskUserQuestion in Claude Code, `request_user_input` in Codex where the mode allows; no tool available → draft with recommended answers marked `TODO confirm` and say so). Each round covers the current frontier: every open decision that does not depend on another answer.
+
+- Number the questions. Give each a **recommended answer with a one-line reason**, so the user can reply "all recommended" or override by number.
+- Stop asking when the bar is met: *a fresh agent could implement each issue without asking anything.* Test every brief against that sentence before calling it done.
+- Do not re-ask what the material or an earlier round already settled.
+
+## The angles, in order
+
+Work the design the way a joint product-and-tech review would; each round's answers feed the next:
+
+1. **Product** — who this is for, the observable outcome, what's in and out of scope now, how it splits into slices or phases, priority.
+2. **Behavior** — primary and alternate flows, rules, permissions, validations, edge and failure cases; for UI, the states, components, and copy.
+3. **Technical** — only the choices that are genuinely the user's: approach trade-offs, data and interface implications, integrations, migration; recommend one and say why. Routine implementation stays the implementer's.
+4. **Quality and risk** — what proves it works (test cases, acceptance), what earns the `risky` label, what should stop a dark run beyond the standing stop-list.
+
+These are the brief template's sections in interview form — a question exists only where reading the material, the codebase, and sensible defaults cannot fill a section.
+
+## Slicing
+
+- One issue = one outcome that fits one agent session, sliced vertically (a thin working path through the stack beats a layer at a time).
+- Blockers use native issue dependencies (blocked-by); phases use milestones; hierarchy uses parent/sub-issues. Labels never duplicate these.
+- A large feature gets a parent issue holding the map and child issues holding the work. **Only child issues ever get `ready`** — a parent brief is context, not an executable task, and an agent must never pick it up whole.
+- Deliberately deferred work ("someday, not now") lives in the parent's out-of-scope section, not as its own issue — icebox issues clutter the tracker. Create a tracking issue for it only when the user asks.
+
+## The brief
+
+Every issue body follows [brief-template](references/brief-template.md): Outcome · Out of scope · Rules and edge cases · UI states (when there is UI) · Approach and touch points · Tests and acceptance · Risks and stop conditions · Assumptions. Write the sections that apply and delete the ones that don't — an empty "N/A" section is noise, not diligence. Details live inline in the issue; links to docs are supporting material, never a substitute for the brief. Evidence over confidence: touch points name real paths, dependency claims carry their check date, and anything material the grounding could not verify goes in **Assumptions — confirm or correct**, never asserted as fact.
+
+## Labels and approval
+
+- A new issue starts at `needs-you`. Add `risky` when it touches security, money, user data, or production.
+- Approval is only the user's explicit words — "approved", "go ahead", clearly tied to this issue, in chat or on the issue. Labels, silence, or the passage of time never create approval.
+- Record it once: comment `Approved by <user> on <date>: "<their words>"`, then swap `needs-you` → `ready`. That comment is what dev-implement's preflight looks for.
+- An issue with an unconfirmed entry in its Assumptions section cannot go `ready` — the recorded approval covers the ledger the user saw, so resolve every entry (confirmed, corrected, or moved to a spike) first.
+- An issue that settles a material cross-cutting decision records it as one comment starting `Decision:` — dev-ship appends that line to the project's decision register at merge.
+- The user edits or corrects a draft → apply, and summarize what changed since they last read it.
+
+## After approval
+
+An approved issue that later needs a material change flips back to `needs-you` with one comment naming what changed; the new approval is recorded the same way. Small wording fixes that change no behavior don't reopen anything.

package/skill/dev-intake/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "dev-intake"
+  short_description: "Turn ideas or SOWs into agent-ready GitHub issues"
+  default_prompt: "Use $dev-intake to turn this into GitHub issues."

package/skill/dev-intake/references/brief-template.md

@@ -0,0 +1,56 @@
+# Issue brief template
+
+The issue body a `ready` issue must have. Write the sections that apply, delete the rest. The test for every section: would a fresh agent have to guess or ask without it?
+
+```markdown
+## Outcome
+
+What exists when this is done, in observable terms — what the user can do, what the
+system produces. One paragraph.
+
+## Out of scope
+
+The nearby things this issue deliberately does NOT do. This is what stops scope creep
+in dark mode — name the tempting adjacent work.
+
+## Rules and edge cases
+
+The behavior that isn't obvious: validations, permissions, limits, empty/error/concurrent
+cases, what happens on failure. Bullet list, one behavior per line.
+
+## UI states            <!-- only when there is UI -->
+
+Loading, empty, error, success, disabled. Which design-system components. Copy for
+user-facing text. Responsive and keyboard behavior when it matters.
+
+## Approach and touch points
+
+The chosen technical approach in a few lines: which parts of the codebase change,
+new/changed interfaces or schemas, data migrations. Routine choices (file names,
+helpers, fixtures) stay the implementer's — don't specify them.
+
+## Tests and acceptance
+
+What proves it works: the cases tests must cover (success, boundary, failure,
+authorization where relevant) and the commands to run. Acceptance = the Outcome plus
+these passing.
+
+## Risks and stop conditions
+
+What could go wrong and what should make the agent stop and ask instead of pushing
+through — beyond the standing stop-list in .vegastack/dev.md.
+
+## Assumptions — confirm or correct
+
+Anything material the grounding investigation could not verify, one per line, each
+awaiting the user's confirm/correct. The issue cannot go `ready` while one is
+unconfirmed. Verified facts never appear here — they live in their section with
+their evidence. Delete the section once every entry is resolved.
+```
+
+## Writing rules
+
+- Inline over linked: the material details live in the issue itself. A link supports; it never substitutes.
+- Concrete over abstract: "rejects amounts over 10,000 with error E402" beats "validates input".
+- Evidence over confidence: touch points name real file paths; a dependency capability claim carries the doc check and its date; what couldn't be verified goes to Assumptions, never stated as fact.
+- The brief binds the agent, so ambiguity is a bug in the brief — if two readings exist, the interview wasn't done.

package/skill/dev-intake/refresh/REFRESH.md

@@ -0,0 +1,3 @@
+# Refresh contract — dev-intake
+
+Evergreen: this skill asserts no version pins, vendor mechanism names, numeric vendor limits, or dated facts — its content is interview discipline, slicing rules, the brief template, and the approval-recording rule, all versionless. The harness question-tool mechanics it leans on are tracked by `dev-setup`'s registry (see `skills/dev-setup/refresh/`). Revisit if a future edit introduces a volatile fact.

package/skill/dev-intake/refresh/sources.json

@@ -0,0 +1,6 @@
+{
+  "schemaVersion": 1,
+  "retrievalBaseline": "2026-08-27",
+  "note": "Evergreen waiver recorded in REFRESH.md; sources deliberately empty.",
+  "sources": []
+}