@vegastack/skills 0.7.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vegastack/skills",
-  "version": "0.7.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

@@ -1,13 +1,13 @@
 ---
 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).
+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-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.
+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
 
@@ -18,8 +18,8 @@ The gates exist to stop agent-invented authority, never to slow the user down. W
 - `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.
+- 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
 
@@ -27,7 +27,7 @@ Assign yourself, swap `ready` → `working`. Branch from the default branch: `<t
 
 ## 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.
+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.
 
@@ -35,6 +35,7 @@ Honesty over green: a failing test gets fixed at the root or reported as failing
 
 - 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
@@ -55,8 +56,8 @@ Honesty over green: a failing test gets fixed at the root or reported as failing
 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.
+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-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.
+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-intake/SKILL.md

@@ -50,13 +50,13 @@ Every issue body follows [brief-template](references/brief-template.md): Outcome
 
 ## Labels and approval
 
-- A new issue starts at `needs-you`. Add `risky` when it touches security, money, user data, or production.
+- 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-you` → `ready`. That comment is what dev-implement's preflight looks for.
+- 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-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.
+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-setup/SKILL.md

@@ -19,6 +19,8 @@ Facts are your job; decisions are the user's. Gather these silently and present
 | 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` |
 
@@ -39,6 +41,8 @@ Ask with your harness's question tool — AskUserQuestion in Claude Code, `reque
 
 **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
@@ -50,10 +54,10 @@ Everything else — merge style, branch naming, the stop-and-ask list — takes
 
 | Target | Action |
 |---|---|
-| `.vegastack/dev.md` | render [dev-profile template](assets/dev-profile.md.template) with the answers |
+| `.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-you` FBCA04 (waiting on the user) · `ready` 0E8A16 (approved, agent may start) · `working` 1D76DB (claimed by an agent) · `for-you` 5319E7 (result awaiting user review) · `risky` B60205 (security, money, data, or production) |
+| 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

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

@@ -3,7 +3,9 @@
 
 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-you`. Start only on `ready` issues. These five labels are the whole workflow vocabulary — use them and no others: `needs-you` (waiting on the user) → `ready` (approved) → `working` (claimed by an agent) → `for-you` (result awaiting user review); `risky` flags security, money, data, or production work.
+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). Material decisions get one dated line in the decision register dev.md names (`decisions:` knob).
+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

@@ -1,5 +1,7 @@
 # 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}}`
@@ -14,10 +16,33 @@ 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 user 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.
+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
 

package/skill/dev-ship/SKILL.md

@@ -1,19 +1,19 @@
 ---
 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-you 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).
+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-you` issue with its evidence comment; ship packages and lands it. Corrections found here go back through implement's corrections loop.
+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-you` with the evidence comment present, and the branch is pushed. Not there yet → say what's missing instead of creating a premature PR.
+- 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.
@@ -28,6 +28,10 @@ On the user's separate merge instruction:
 - 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-integrity.json

@@ -24,7 +24,7 @@
     },
     "dev-implement": {
       "files": {
-        "SKILL.md": "7a3f700cb116b9ad70596851536c74794497f780b0a79626fa44658556eaa005",
+        "SKILL.md": "2fe266bf755632fa98b0a3bd0e663a06ff6ef8d6e45bdbce63744e91606a16f2",
         "agents/openai.yaml": "1abab383deca54d32749fd9156f9a6211fe96e02e0166dc8a16ff8459ac31b74",
         "refresh/REFRESH.md": "013d7f667e489a08bbe12768ca2093fc305113920c1e510b5e96ba335af8de48",
         "refresh/sources.json": "7bd883e5b3512e236a909ad6ff20c97f3555785867c31fd728256c7c2c514c74"
@@ -32,7 +32,7 @@
     },
     "dev-intake": {
       "files": {
-        "SKILL.md": "1b9bdabf2c5aae56d3511972b2800f0328ac07d91dbfa7b23ea3c76dc37ed0f3",
+        "SKILL.md": "18b2c1464559c7789b3ff942e87a508d4931fc2d8d05c71995cea5eeca3b2ed5",
         "agents/openai.yaml": "5473d2d3efffc518c07dfa8e6788c6535a5054ceca696119c5856ad265ef5581",
         "references/brief-template.md": "c09e6b7964ad524d5c5bad11206df200dea6ab3d72d23bb950b21a2f11b1263a",
         "refresh/REFRESH.md": "bb5265cee98c243c775c3e5fbc59de4b84ab54e828f3290d7c19e47291d66f71",
@@ -41,10 +41,10 @@
     },
     "dev-setup": {
       "files": {
-        "SKILL.md": "6fda960bcb0c729c5acac8edfa0e1f40b2f72178c3323f31a77c3e6cdb73b741",
+        "SKILL.md": "585332564adf234058a5c98e6a51f9fa78c842cfd5ef84d58f6f28e1ddf80c15",
         "agents/openai.yaml": "0b53bece25736b0dfbe990c05973f06d83905bfd6314d36fe64ae23d46393941",
-        "assets/agents-section.md.template": "615b1b69a62ccca351a00cc85435fc663ad6c35a478ddcff6e1ecc777a35f342",
-        "assets/dev-profile.md.template": "6a586ff63af64098252a4910eb093db9139d66ed849a30cdb5c1af158806db6d",
+        "assets/agents-section.md.template": "1e219ecbf4fa6dd90f94572af0d6290a7f7910e14ab1eafc405510cb2d5d9760",
+        "assets/dev-profile.md.template": "c9530440e5e0a6d864f6827fc517893966f7fd4ad63792f46133b54172143b5c",
         "references/harness-facts.md": "cabecde6ad6d2a2aa16ad1f6acdb57fd47c335948e734938cb0f7fdb27e085e6",
         "refresh/REFRESH.md": "9d5eef2ee900819120334ae9cf7dfc591d33bdeef241bbab6653c11c10ecff30",
         "refresh/sources.json": "1c8c5ebd22472b4c88630e3f626986b0aad97da367e122c4c7cd3f9677f41948"
@@ -52,7 +52,7 @@
     },
     "dev-ship": {
       "files": {
-        "SKILL.md": "18af2ac434b0b5b7b9f04fb32b5558337234d83aa910e06c1ce463f7cf45f722",
+        "SKILL.md": "e8180591aadbdacf4ce61edc96eb1ebc8fa22763266530caaecb1193130e1a87",
         "agents/openai.yaml": "4eae616fb85e1e637a73a0aec5b132c644bf9bbc33d3958525c65c8db59ca87f",
         "refresh/REFRESH.md": "4c6b46b211604006da943604845127a1f9939cf7e5e31d941452ba02d05db7c9",
         "refresh/sources.json": "7bd883e5b3512e236a909ad6ff20c97f3555785867c31fd728256c7c2c514c74"