@vegastack/skills 0.6.0 → 0.8.0

package/README.md

@@ -14,6 +14,10 @@ npx @vegastack/skills add architect
 | `architect` | Architecture advisor: the locked stack and lean-first principles as evidence-distilled decision tables, dated source-verified platform facts, a per-project `.vegastack/arch.md` profile with repo-wins drift detection, and an advisory-only review discipline |
 | `skill-maintainer` | Encodes the Agent Skills standards (Claude Code, Codex, Hermes, agentskills.io) for creating, updating, and releasing skills in a skills repo |
 | `skillify` | Turns a feature or workflow into a complete skill conforming to the VegaStack skills contract, or audits an existing one |
+| `dev-setup` | Bootstraps a project for the issue-driven dev workflow: profile, AGENTS.md section, labels, decision register |
+| `dev-intake` | Turns ideas, brainstorms, and SOWs into agent-ready GitHub issues with recorded user approval |
+| `dev-implement` | Implements an approved issue end to end, dark: preflight, claim, build, test, review, evidence in the issue |
+| `dev-ship` | Opens the PR and merges, each only on the user's explicit word |
 
 ## Commands
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vegastack/skills",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Installer and verifier for VegaStack Agent Skills (Claude Code, Codex, and Hermes)",
   "license": "MIT",
   "type": "module",

package/skill/dev-implement/SKILL.md

@@ -0,0 +1,63 @@
+---
+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-operator 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-operator`, 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-operator`, 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-operator` 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-operator` 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.
+- When dev.md has a `## Verify` runbook, follow it — run the app and smoke-check the flows it names; that live result belongs in the evidence comment alongside the test output.
+- 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-operator`, 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-operator` issue are the new frontier: apply them, re-verify what they touch, update the evidence comment, back to `for-operator`. Their corrections never need re-approval ceremony unless they change scope — then it's `needs-operator` 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-operator`. 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-operator` → `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-operator` 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": []
+}

package/skill/dev-setup/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: dev-setup
+description: Bootstrap a project for issue-driven agent development. Use when asked to "set up the dev workflow", "bootstrap this project for agents", "install the dev workflow here", or invoked as dev-setup; also run automatically when dev-intake, dev-implement, or dev-ship find no .vegastack/dev.md in the project. Creates the project profile, the AGENTS.md dev section plus CLAUDE.md import, the five workflow labels on the GitHub repo, and the decision register. Not for architecture profiles or advice (that is architect and .vegastack/arch.md), not for authoring skills, not for repos without git.
+---
+
+# dev-setup
+
+Re-runnable bootstrap that gives a project everything the dev workflow needs: a profile file holding the knobs, a thin AGENTS.md section that both Claude Code and Codex read, the GitHub labels, and the decision register. The other dev skills call this automatically when `.vegastack/dev.md` is missing, then continue with their original request.
+
+Nearest neighbor: `architect` owns `.vegastack/arch.md` (architecture facts and advice); dev-setup owns `.vegastack/dev.md` (workflow facts and knobs). When arch.md exists, point dev.md at it for stack facts instead of duplicating them.
+
+## Step 1 — Detect before asking
+
+Facts are your job; decisions are the user's. Gather these silently and present findings as "here's what I found — correct me if wrong", never as open questions:
+
+| What | How |
+|---|---|
+| repo, default branch | `git remote get-url origin` · `gh repo view --json nameWithOwner,defaultBranchRef` |
+| gh authenticated | `gh auth status` |
+| stack and commands | package.json scripts, lockfiles, framework configs |
+| web app (UI evidence relevant) | framework dependencies (next, react, vue, …) |
+| release/deploy machinery | changesets config, publish or deploy workflows, wrangler/Docker/compose files, registry configs — these draft the `## Ship` runbook |
+| environments and run commands | CI/deploy configs, env examples (names only), dev/start scripts — these draft `## Environments` and `## Verify` |
+| existing files | AGENTS.md, CLAUDE.md, `.vegastack/dev.md`, `.vegastack/arch.md`, docs/decisions.md |
+| existing labels | `gh label list` |
+
+Not a git repo, or no origin remote: stop and say exactly what is missing. A half-installed workflow is worse than none.
+
+## Step 2 — The interview
+
+Ask with your harness's question tool — AskUserQuestion in Claude Code, `request_user_input` in Codex where the mode allows it (availability details: [harness-facts](references/harness-facts.md)). When no question tool is available (headless run, gated mode), write the defaults, mark every unconfirmed knob `# TODO confirm`, and say so in your reply — a wrong invented preference costs more than a TODO.
+
+**Round A — confirm the detected facts** in one compact summary (repo, stack, commands, web app or not). Ask only about what detection could not fill.
+
+**Round B — the four workflow knobs**, recommended default first:
+
+1. Review of finished work: **subagent** · cross-agent (Codex↔Claude) · cross-agent only on `risky` issues
+2. Proof for UI work: **playwright screenshots** · none
+3. Gates: **3** (approve → PR → merge as separate user words) · 2 (approve → one "ship it" covers PR and merge)
+4. Tests: **required for every change** · required for logic changes only
+
+**Round C — only when the situation exists:**
+
+- Release/deploy machinery detected → show the drafted `## Ship` runbook (each step `auto:` or `ask:`) and the `release:` knob (per-merge or on-request) for confirmation; no machinery → "Ship: merge only" and move on
+- Environments or run commands detected → confirm the drafted `## Environments` and `## Verify` bullets
+- AGENTS.md already has content → append the marked section (default) or show a merge proposal first
+- CLAUDE.md already has content → add the `@AGENTS.md` import as its first line (default) or move its content into AGENTS.md and leave only the import
+- Evidence repo for UI screenshots → default `<owner>/dev-review-assets`; offer to create it (`gh repo create --private`) if missing
+- Different label names or a different decision-register path, if the user brings it up
+
+Everything else — merge style, branch naming, the stop-and-ask list — takes its documented default straight into dev.md. The profile is plain text the user can edit anytime; the interview is a convenience, not the source of truth.
+
+## Step 3 — Write
+
+| Target | Action |
+|---|---|
+| `.vegastack/dev.md` | render [dev-profile template](assets/dev-profile.md.template) with the answers — it is the project's self-maintained handbook (short directional bullets; Ship/Verify/Environments/Design sections drafted from detection, placeholders deleted) |
+| `AGENTS.md` | create it, or insert/replace only the block between `<!-- vsk-dev:start -->` and `<!-- vsk-dev:end -->` using the [agents-section template](assets/agents-section.md.template); content outside the markers is the user's and stays untouched |
+| `CLAUDE.md` | ensure its first line is `@AGENTS.md` — Claude Code does not read AGENTS.md natively and needs this import ([harness-facts](references/harness-facts.md)); create the file when absent |
+| labels | `gh label create <name> --color <hex> --description "<text>"`, skipping ones that exist: `needs-operator` FBCA04 (waiting on the user) · `ready` 0E8A16 (approved, agent may start) · `working` 1D76DB (claimed by an agent) · `for-operator` 5319E7 (result awaiting user review) · `risky` B60205 (security, money, data, or production) |
+| decision register | create the file the `decisions:` knob names (default `docs/decisions.md`) with a two-line header and one example entry, when missing; a project with an existing register keeps it and the knob points there |
+
+## Step 4 — Report
+
+One summary: what was created, what was skipped and why, what remains TODO. When `gh` was unauthenticated, print the exact `gh auth login` and `gh label create` commands the user can run later, and name the gap plainly.
+
+## Re-runs
+
+Re-running is safe and is how knobs get revisited: show what differs per target and change only what the user confirms. The marked block is the only part of AGENTS.md this skill owns. Hand edits inside dev.md win — read them and keep them; the templates are for creation, not for resetting.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "dev-setup"
+  short_description: "Bootstrap a repo for the issue-driven dev workflow"
+  default_prompt: "Use $dev-setup to bootstrap this project's dev workflow."

package/skill/dev-setup/assets/agents-section.md.template

@@ -0,0 +1,11 @@
+<!-- vsk-dev:start -->
+## Dev workflow
+
+Read `.vegastack/dev.md` for this project's stack, commands, and workflow knobs.
+
+Work flows through GitHub issues. An issue labeled `ready` carries the user's recorded approval and a complete brief — implement it end to end per the `dev-implement` skill, post the evidence in the issue, and hand it back with `for-operator`. Start only on `ready` issues. These five labels are the whole workflow vocabulary — use them and no others: `needs-operator` (waiting on the user) → `ready` (approved) → `working` (claimed by an agent) → `for-operator` (result awaiting user review); `risky` flags security, money, data, or production work.
+
+The user holds the gates: they approve the issue, say the word for a PR, and say a separate word to merge (see `gates` in dev.md); after merge, the `## Ship` runbook in dev.md says what happens next and which steps need their word. Material decisions get one dated line in the decision register dev.md names (`decisions:` knob).
+
+dev.md is the project's self-maintained handbook: when a gotcha, surprise, or repeated instruction surfaces in any run, propose one line for the right dev.md section that would have prevented it — fold into existing lines, never append a log — and add it on the user's yes.
+<!-- vsk-dev:end -->

package/skill/dev-setup/assets/dev-profile.md.template

@@ -0,0 +1,49 @@
+# Dev profile — {{owner/repo}}
+
+This file is the project's handbook: short directional bullets, not prose. Skills read the section they need. When reality disagrees with a line, fix the line; when a gotcha or repeated instruction surfaces, fold ONE line into the right section — never append a log.
+
+repo: {{owner/repo}} · default branch {{branch}}
+stack: {{one line, or "see .vegastack/arch.md"}}
+commands: test `{{test}}` · build `{{build}}` · dev `{{dev}}`
+
+## Knobs
+
+review: subagent            # subagent | cross-agent | cross-agent-risky
+ui-evidence: playwright     # playwright | none
+evidence-repo: {{owner}}/dev-review-assets
+gates: 3                    # 3 = approve/PR/merge · 2 = approve/ship
+tests: required             # required | logic-only
+merge: squash
+branch: <type>/<issue>-<slug>   # type: feat | fix | docs | chore | refactor
+decisions: docs/decisions.md
+release: on-request         # per-merge = Ship runbook runs as part of shipping · on-request = only when the operator says "release"
+
+## Ship — what happens after merge, in order
+
+Each line starts `auto:` (agent just does it) or `ask:` (needs the operator's word first).
+
+- {{e.g. "auto: bunx changeset version && bun install, commit as chore: release"}}
+- {{e.g. "ask: git tag v<version> && git push origin main v<version> — tag triggers the publish pipeline"}}
+- {{delete this section's placeholders; "Ship: merge only" is a valid runbook}}
+
+## Verify — how to see it working
+
+- {{start: command · URL}}
+- {{the flows worth smoke-checking after a change}}
+
+## Environments
+
+- {{environments and their targets; which the agent may touch}}
+- {{where secret NAMES are defined — values never appear in this file}}
+
+## Design
+
+- {{pointers: design system / component rules / .vegastack/arch.md / UI conventions}}
+
+## Stop and ask
+
+Dark execution ends and the operator decides when work would involve: a change of scope or product behavior, a significant new dependency or runtime, spending money, anything destructive or touching production, or a blocker the brief cannot resolve.
+
+## Project rules
+
+- {{project-specific rules, one per line; delete this section if none}}

package/skill/dev-setup/references/harness-facts.md

@@ -0,0 +1,22 @@
+# Harness facts
+
+Verified mechanics of the two harnesses this workflow targets. Everything here is volatile — vendors change these — so each claim carries its source; the refresh contract tracks them. Verified 2026-08-27.
+
+## Claude Code
+
+- Claude Code does **not** read AGENTS.md natively. The documented pattern is a CLAUDE.md that imports it: a line containing `@AGENTS.md` (import syntax is `@path/to/file`, resolved relative to the containing file, maximum 4 hops of recursion; `@` inside backticks stays literal). <!-- source: CC-MEMORY -->
+- `CLAUDE.local.md` in the project root loads after CLAUDE.md and is meant to be gitignored — leave it alone; it is the user's personal file. <!-- source: CC-MEMORY -->
+- Project skills load from `.claude/skills/<name>/SKILL.md`; personal skills from `~/.claude/skills/`. <!-- source: CC-SKILLS -->
+- The structured question tool is **AskUserQuestion**. It is unavailable in non-interactive runs (`claude -p`); a configurable timeout can auto-submit pre-selected options. <!-- source: CC-TOOLS -->
+
+## Codex
+
+- Codex reads AGENTS.md natively: from `~/.codex/` (global; `AGENTS.override.md` wins over `AGENTS.md`), then from the repo root down to the working directory, one file per directory, concatenated root-first so closer files override. Combined size is capped by `project_doc_max_bytes`, default 32 KiB. There is **no** `@file` import mechanism — layering is directory-based only. <!-- source: CODEX-AGENTS -->
+- Skills load from `.agents/skills/` in each directory from the working directory up to the repo root, plus `~/.agents/skills/` for the user. Frontmatter requires only `name` and `description`; an optional `agents/openai.yaml` adds display metadata and invocation policy. <!-- source: CODEX-SKILLS -->
+- The structured question tool is **`request_user_input`** — collaboration-mode-gated (available in Plan mode; elsewhere it fails fast with a clear error, and it is not available to subagents). Community posts mention an "ask_user_question"/"clarify" tool; that is a proposal, not a shipped tool — do not design against it. <!-- source: CODEX-SKILLS -->
+- Non-interactive mode is `codex exec`: fully unattended, human-input tools unavailable, AGENTS.md discovery unchanged. <!-- source: CODEX-EXEC -->
+
+## What this means for the dev skills
+
+- AGENTS.md is the shared instruction file; the one-line CLAUDE.md import makes it reach Claude Code. Keep the marked section small — it counts against Codex's 32 KiB budget along with everything else in AGENTS.md.
+- Any skill that wants to ask the user must degrade cleanly: no question tool available → use documented defaults, mark them `# TODO confirm`, and say so.

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

@@ -0,0 +1,13 @@
+# Refresh contract — dev-setup
+
+Instructions for the scheduled refresh agent (and any human running a manual refresh). This file plus `sources.json` is the complete freshness contract for this skill.
+
+## What this skill claims
+
+- **Durable rules** (SKILL.md, assets): the detect-then-ask discipline, the interview rounds and knobs, the marked-section AGENTS.md contract, the label set, the defaults-plus-TODO fallback. Versionless; the refresh agent NEVER edits these — if evidence invalidates one, open an issue quoting it.
+- **Volatile facts**: everything in `references/harness-facts.md` — Claude Code memory/import/skill/question-tool mechanics and Codex AGENTS.md/skills/question-tool/exec mechanics. That file is the only refresh-tracked file; its sentences carry `<!-- source: SOURCE-ID -->` markers matching the registry.
+
+## How to refresh
+
+1. Run the shared runner against this registry; on drift, read the changed page and propose edits to the marked sentences in `references/harness-facts.md` — and to the three harness-mechanism mentions in SKILL.md that mirror it (the two question tools in Step 2, the `@AGENTS.md` import in Step 3) — in the same PR as the registry update.
+2. Never auto-apply harness behavior changes; a human reviews — these facts change what dev-setup writes into user projects.

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

@@ -0,0 +1,152 @@
+{
+  "schemaVersion": 1,
+  "retrievalBaseline": "2026-08-27",
+  "policy": {
+    "criticalTopics": [
+      "claude-code-memory",
+      "codex-agents-md"
+    ],
+    "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/harness-facts.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": "CC-MEMORY",
+      "service": "Claude Code memory files and imports (CLAUDE.md, AGENTS.md, @imports)",
+      "kind": "official-docs",
+      "stability": "vendor-docs",
+      "thresholdDays": 14,
+      "critical": true,
+      "urls": {
+        "primary": "https://code.claude.com/docs/en/memory.md"
+      },
+      "versionDetection": {
+        "type": "manual-review"
+      },
+      "topics": [
+        "claude-code-memory"
+      ],
+      "affected": [
+        "references/harness-facts.md",
+        "SKILL.md"
+      ],
+      "checksum": "e989818335ae45abb756df759d4859aa9daa6764393a3e39c46e505f181a33b6",
+      "retrievedAt": "2026-08-27T08:19:24.132Z"
+    },
+    {
+      "id": "CC-SKILLS",
+      "service": "Claude Code skill discovery locations and frontmatter",
+      "kind": "official-docs",
+      "stability": "vendor-docs",
+      "thresholdDays": 14,
+      "critical": false,
+      "urls": {
+        "primary": "https://code.claude.com/docs/en/skills.md"
+      },
+      "versionDetection": {
+        "type": "manual-review"
+      },
+      "topics": [
+        "claude-code-skills"
+      ],
+      "affected": [
+        "references/harness-facts.md"
+      ],
+      "checksum": "8d03177dcc10ffbff5313c43023da15ff1059197c1fff05eb9dba3fe6361c767",
+      "retrievedAt": "2026-08-27T08:19:24.132Z"
+    },
+    {
+      "id": "CC-TOOLS",
+      "service": "Claude Code AskUserQuestion tool behavior",
+      "kind": "official-docs",
+      "stability": "vendor-docs",
+      "thresholdDays": 14,
+      "critical": false,
+      "urls": {
+        "primary": "https://code.claude.com/docs/en/tools-reference.md"
+      },
+      "versionDetection": {
+        "type": "manual-review"
+      },
+      "topics": [
+        "claude-code-tools"
+      ],
+      "affected": [
+        "references/harness-facts.md",
+        "SKILL.md"
+      ],
+      "checksum": "3bdd8429e76be8213e9263103134ac7b6892f4574820e40bf84032a98c5d0aeb",
+      "retrievedAt": "2026-08-27T08:19:24.132Z"
+    },
+    {
+      "id": "CODEX-AGENTS",
+      "service": "Codex AGENTS.md discovery, merging, and size cap",
+      "kind": "official-docs",
+      "stability": "vendor-docs",
+      "thresholdDays": 14,
+      "critical": true,
+      "urls": {
+        "primary": "https://learn.chatgpt.com/docs/agent-configuration/agents-md.md"
+      },
+      "versionDetection": {
+        "type": "manual-review"
+      },
+      "topics": [
+        "codex-agents-md"
+      ],
+      "affected": [
+        "references/harness-facts.md"
+      ],
+      "checksum": "9eacb3d812b87be4acc1213af58ded35e8f387bcf1589c203bbb452ead0c4774",
+      "retrievedAt": "2026-08-27T08:19:24.132Z"
+    },
+    {
+      "id": "CODEX-SKILLS",
+      "service": "Codex skills discovery, frontmatter, and request_user_input gating",
+      "kind": "official-docs",
+      "stability": "vendor-docs",
+      "thresholdDays": 14,
+      "critical": false,
+      "urls": {
+        "primary": "https://learn.chatgpt.com/docs/build-skills.md"
+      },
+      "versionDetection": {
+        "type": "manual-review"
+      },
+      "topics": [
+        "codex-skills"
+      ],
+      "affected": [
+        "references/harness-facts.md",
+        "SKILL.md"
+      ],
+      "checksum": "44aa6d490f4567c0b1fb064deab642bfac590f0e721228e0c53fe738db191026",
+      "retrievedAt": "2026-08-27T08:19:24.132Z"
+    },
+    {
+      "id": "CODEX-EXEC",
+      "service": "Codex non-interactive mode (codex exec)",
+      "kind": "official-docs",
+      "stability": "vendor-docs",
+      "thresholdDays": 14,
+      "critical": false,
+      "urls": {
+        "primary": "https://learn.chatgpt.com/docs/non-interactive-mode.md"
+      },
+      "versionDetection": {
+        "type": "manual-review"
+      },
+      "topics": [
+        "codex-exec"
+      ],
+      "affected": [
+        "references/harness-facts.md"
+      ],
+      "checksum": "df82c4bbf3b5bffca926a244549222c1235154cfba973b9a0bb1d7a0abd28d66",
+      "retrievedAt": "2026-08-27T08:19:24.132Z"
+    }
+  ]
+}

package/skill/dev-ship/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: dev-ship
+description: Create the pull request and merge for a finished issue, each only on the user's explicit word. Use when the user says "make the PR", "open a pull request" for an issue, "ship it", "merge it", "merge issue 12", or asks to close out a reviewed issue. Verifies the issue is at for-operator with evidence, links the PR to the issue, and squash-merges on the separate merge instruction. Not for implementing issues (dev-implement) or writing and approving them (dev-intake).
+---
+
+# dev-ship
+
+Two gates, each one sentence from the user, each spent when used: their words asking for a PR authorize the PR and nothing more; their words asking to merge authorize the merge. With `gates: 2` in `.vegastack/dev.md`, one "ship it" covers both — that's the only case where they combine. Passing checks, PR permissions, and the calendar authorize nothing by themselves.
+
+Nearest neighbor: `dev-implement` produces the `for-operator` issue with its evidence comment; ship packages and lands it. Corrections found here go back through implement's corrections loop.
+
+## Gate 1 — the PR
+
+On the user's PR instruction:
+
+- Verify the issue is at `for-operator` with the evidence comment present, and the branch is pushed. Not there yet → say what's missing instead of creating a premature PR.
+- `gh pr create` from the task branch: title from the issue, body is `Closes #<n>` plus a link to the evidence comment — the issue holds the report; the PR links it rather than duplicating it.
+- No draft PRs unless the user asks for one.
+- If required checks fail on the PR, that's implement work: hand the failures to the corrections loop, update the evidence comment, and tell the user.
+- User corrections left on the PR itself flow through the same corrections loop on the same branch — the PR updates with the push; nothing gets recreated.
+
+## Gate 2 — the merge
+
+On the user's separate merge instruction:
+
+- Re-check that the PR head is still the revision the evidence comment names and checks are green — a branch that moved since review gets re-verified before it lands.
+- A merge conflict with the default branch is corrections work: update the branch, re-verify what the update touched, and the standing merge instruction holds once checks are green again — unless the update changed behavior, which goes back to the user.
+- Merge per the dev.md `merge` knob (default `gh pr merge --squash`). `Closes #<n>` closes the issue; confirm both happened.
+- If the issue carries a `Decision:` comment (the dev-intake convention), append its one dated line to the register dev.md names (`decisions:` knob) now — the register is append-only and this is its moment.
+
+## After the merge — the Ship runbook
+
+Merge is not the end when dev.md has a `## Ship` section: follow its steps in order — `auto:` lines you just do, `ask:` lines wait for the operator's word. With `release: per-merge`, the runbook is part of shipping the issue; with `release: on-request`, it runs only when the operator says "release" (covering everything merged since the last one). Report each step's outcome; a failing runbook step stops the sequence and goes to the operator — never skip ahead past a failure. A gotcha here (a step that surprised you, an instruction the operator had to repeat) is one proposed line folded into the runbook.
+
+## Report
+
+One short confirmation each gate: what was created or merged, the link, and anything that still needs the user (failing check, moved head, missing evidence). When a gate's condition isn't met, the answer is what's missing — the gate itself never gets skipped to be helpful.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "dev-ship"
+  short_description: "Open the PR and merge, each on the user's word"
+  default_prompt: "Use $dev-ship to create the PR or merge this issue's work."

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

@@ -0,0 +1,3 @@
+# Refresh contract — dev-ship
+
+Evergreen: this skill asserts no version pins, vendor mechanism names beyond long-stable `gh` subcommands, numeric vendor limits, or dated facts — its content is the two-gate discipline, all versionless. Revisit if a future edit introduces a volatile fact.