@vegastack/skills 0.10.0 → 0.11.1

package/skill/dev-intake/SKILL.md

@@ -1,62 +1,68 @@
 ---
 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).
+description: Turn ideas, brainstorms, feature requests, bug reports, or SOW documents into GitHub issues an agent can act on 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, "users report X — make an issue", "plan this as issues", "slice this epic", or when the user gives approval on a drafted issue and it needs recording. Not for writing the implementation plan of an approved issue (dev-plan), 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.
+Requirements come in as the operator's brainstorm, feature thought, bug report, 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. Artifact formats (markers, operator identity, labels, revisions) follow the `dev-setup` skill's `references/conventions.md`.
 
-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.
+Nearest neighbors: `dev-plan` owns the how once a brief is approved — intake owns the what/why and the approval mechanics; `dev-implement` builds. If `.vegastack/dev.md` is missing → run `dev-setup` first, then continue.
 
 ## 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:
+Finding facts is your job, never the operator's — a brief built on unverified facts is a confident mistake waiting for dark mode. 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. Stack, schema, auth, and infra approach choices route through `dev-architect` — its verify-before-you-recommend protocol governs the check (pinned facts first, live docs on a miss or a 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.
+- **Read the touched code.** Open the actual paths the work would change: current behavior, patterns to reuse, where it 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, noted with the date. Stack, schema, auth, and infra choices route through `dev-architect` — its verify protocol governs the check.
+- **Cross-check the request** against product docs and current behavior. A contradiction is pushback, never a silent resolution: "you asked for X; the code currently does 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-operator-knows* → ask, with a recommendation; *only-running-code-can-tell* → a `research` issue or the issue's first spike step. Guessing is not a bin.
 
-## The interview
+## Scope the work — say it out loud
+
+Every issue gets exactly one scope call, announced with its reason, applied as a label, and recorded in the brief's `**Scope:**` line so the reasoning survives the conversation. The operator can override it:
 
-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.
+- **`research`** — a question to answer, not code to keep. The brief is the question plus what "answered" looks like.
+- **`quick-build`** — the objective test (conventions' wording): *a small change AND the flow being changed already exists in the repo to read*. Missing either half — no existing flow, or not actually small — means it is not quick-build; familiarity with the kind of app doesn't count.
+- **`full-plan`** — big or new ground: a new subsystem, a restructuring, a brand-new flow.
 
-- 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.
+In doubt between two classes, take the heavier one. Re-classification after this point belongs to `dev-plan`'s one-way ratchet — never silently downgrade.
 
-## The angles, in order
+## The interview
 
-Work the design the way a joint product-and-tech review would; each round's answers feed the next:
+Ask in rounds with your harness's question tool (no tool available → documented defaults marked `TODO confirm`, and say so). Each round covers the current frontier: every open decision that doesn't depend on another answer. Number the questions; give each a **recommended answer with a one-line reason** so the operator can reply "all recommended"; never re-ask what the material or an earlier round already settled. A vague or self-contradicting answer gets pushback with concrete options — simple words, a mermaid or ASCII sketch when a picture beats prose — never silent absorption. Stop when the bar is met: *a fresh agent could act on each issue without asking anything.*
 
-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 — checking `dev-architect` first so a brief never proposes a recorded rejection or a moving part without its trigger. When the project versions releases (dev.md `changelog:` knob), settle the intended version impact (patch/minor/major) here — the brief records it and dev-implement's changelog entry starts from it. 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.
+The angles, in order — product (who, observable outcome, in/out of scope, slices, priority) → behavior (flows, rules, permissions, edge and failure cases; UI states and copy) → technical (only choices genuinely the operator's, each with a recommendation, checked against `dev-architect`; settle the version impact where the project versions releases) → quality and risk (what proves it works, what earns `risky`, what stops a dark run). Deep approach trade-offs beyond the operator's choices belong to `dev-plan`, not this interview.
 
-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.
+**Bug variant** (`fix:` issues): reproduction steps — or the artifacts needed to obtain them (logs, HAR, recording) — are a required brief section, and the brief names `dev-debug` as the implement path. A bug that can't be reproduced yet becomes a `research` issue first.
 
-## Slicing
+## Slicing and hierarchy
 
-- 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.
+- One issue = one outcome that fits one agent session, sliced vertically. Blockers use native dependencies; phases use milestones; parents use native sub-issues.
+- Deliberately deferred work ("someday, not now") lives in the parent's out-of-scope section, never as its own issue — icebox issues clutter the tracker; a tracking issue exists only on the operator's ask.
+- **Epics:** a multi-deliverable feature gets a parent whose body is a map, never a task — `Destination` (one or two lines every session orients to) · `Decisions so far` (one-line gists linking closed children) · `Not clear yet` (in-scope questions you cannot yet state precisely — the test is whether the question can be phrased sharply now, not answered now; don't pre-slice fog) · `Out of scope` (the tempting adjacent work, named). A mermaid overview when it helps. Each child is classified independently. **Only children ever get `ready`.**
+- Titles carry the type prefix (dev.md `branch:` type list + `research:`) and the native issue type where the org has them — issue, branch, and PR always agree.
 
 ## 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.
+The issue body follows [brief-template](references/brief-template.md), marker line included. Inline over linked; concrete over abstract; evidence over confidence — touch points name real paths, dependency claims carry their check date, and anything unverifiable goes to **Assumptions — confirm or correct**, never asserted. Tests-and-acceptance names the **seams** — the public boundaries tests will live at — because dark mode can't ask later.
+
+**Quick-build issues get their plan now:** after the brief has consensus, invoke `dev-plan`'s inline mode in this same conversation and post brief (description) + plan (comment) together — the operator's single approval covers both.
+
+Before posting any brief, run `node <path-to-this-skill>/scripts/brief-lint.mjs --file <draft> --scope <class> --json` (add `--fix` for fix:-type briefs — it requires the Reproduction section) — structure gaps block (exit 2), quality smells only warn; fix blocks before the operator ever sees the draft. Inline plans additionally pass `dev-plan`'s plan-lint.
 
 ## Labels and approval
 
-- A new issue starts at `needs-operator`. Add `risky` when it touches security, money, user data, or production. (Label names come from dev.md's `labels:` knob; the defaults are used throughout this skill family's prose.)
-- 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 directional decision — one that passes the Decisions test in `.vegastack/dev.md` — records it as one comment starting `Decision:`, in the register's line format; dev-ship appends it at merge after naming it in the merge confirmation. A decision that stands regardless of the issue's fate may go into the register immediately on the user's explicit yes in the same conversation — note "recorded" on the comment so dev-ship doesn't append it twice. Choices that fail the test are brief content, never register lines.
-- The user edits or corrects a draft → apply, and summarize what changed since they last read it.
+- A new issue starts at `needs-operator`, plus its scope label; add `risky` when it touches security, money, user data, or production. (Names come from dev.md's `labels:` knob.)
+- Approval is only the operator's explicit words, clearly tied to the issue. Labels, silence, or time never create approval.
+- Record it as one approval marker comment per conventions — `scope=brief`, or `scope=brief+plan` when the inline plan was posted with it — quoting the operator's words in the operator (username) format. That comment is what preflight verifies.
+- Then flip the state: `research` and `quick-build` → `ready`; `full-plan` → `needs-plan` (dev-plan takes it from there).
+- An issue with an unresolved Assumptions entry cannot leave `needs-operator` — resolve every entry (confirmed, corrected, or moved to a spike) first; the section is deleted once resolved.
+- A directional decision this work settles — one passing the Decisions test in dev.md — is proposed as one register line on the operator's yes; `dev-ship` records at merge.
+- The operator edits 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.
+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, and the brief's revision marker bumps. Small wording fixes that change no behavior don't reopen anything.
+
+End every run with the plain-language summary: what was created or changed, the scope calls made and why, and exactly what awaits the operator's word.

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

@@ -1,13 +1,21 @@
 # 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?
+The issue body a workable 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
+<!-- vsk:v1 type=brief rev=1 scope=research|quick-build|full-plan -->
+**Scope:** research | quick-build | full-plan — the announced reason for the call, one line.
+
 ## Outcome
 
 What exists when this is done, in observable terms — what the user can do, what the
 system produces. One paragraph.
 
+Research issues replace Outcome and the build sections with two headings brief-lint
+expects verbatim in spirit: `## The question` (what this issue resolves) and
+`## What answered looks like` (the evidence that closes it). Risks/stop conditions
+and Assumptions still apply.
+
 ## Out of scope
 
 The nearby things this issue deliberately does NOT do. This is what stops scope creep
@@ -18,6 +26,12 @@ in dark mode — name the tempting adjacent work.
 The behavior that isn't obvious: validations, permissions, limits, empty/error/concurrent
 cases, what happens on failure. Bullet list, one behavior per line.
 
+## Reproduction            <!-- fix: issues only -->
+
+The exact steps (or attached artifacts — logs, HAR, recording) that demonstrate the
+bug today, and the observed vs expected behavior. A bug without this is a `research`
+issue, not a fix. The implement path is dev-debug.
+
 ## UI states            <!-- only when there is UI -->
 
 Loading, empty, error, success, disabled. Which design-system components. Copy for
@@ -26,19 +40,18 @@ 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.
-Name the docs and changelog surfaces this change must update (README section, user
-docs, the changelog entry's gist).
+new/changed interfaces or schemas, data migrations. Routine choices stay the
+implementer's — don't specify them. Name the docs and changelog surfaces this change
+must update. Task-level detail belongs to the plan (dev-plan), not here.
 **Version impact:** patch | minor | major, one-line reason — only when the project
-versions releases (dev.md `changelog:` knob); dev-implement's changelog entry or
-changeset starts from this line.
+versions releases (dev.md `changelog:` knob).
 
 ## 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.
+authorization where relevant), the commands to run, and the **seams** — the public
+boundaries tests live at (dark mode can't negotiate seams later; they're settled
+here). Acceptance = the Outcome plus these passing.
 
 ## Risks and stop conditions
 
@@ -48,9 +61,10 @@ 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.
+awaiting the operator's confirm/correct. The issue cannot leave needs-operator while
+one is unconfirmed. Verified facts never appear here — they live in their section
+with their evidence. Delete the whole section once every entry is resolved (its
+presence alone blocks preflight).
 ```
 
 ## Writing rules
@@ -59,4 +73,5 @@ their evidence. Delete the section once every entry is resolved.
 - 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.
+- Post-approval edits follow the revision-marker rule in dev-setup's `references/conventions.md` (heading `(v2)`, marker `rev=2`, a `Revisions:` line).
 - A `Decision:` comment exists only for a choice that passes the Decisions test in `.vegastack/dev.md` — feature requests and implementation details never qualify; they are brief content, not register lines.

package/skill/dev-intake/references/conventions.md

@@ -0,0 +1,93 @@
+# Workflow conventions
+
+The single spec for the artifacts every dev-family skill reads and writes. One home per rule: skills cite this file, never restate it. Everything here is harness-neutral.
+
+## Comment metadata markers
+
+Every workflow-generated issue comment opens with an invisible HTML marker followed by a human heading:
+
+```markdown
+<!-- vsk:v1 type=<type> rev=<n> [key=value ...] -->
+## <Human title> (v<n>)
+```
+
+| type | required keys | instances |
+|---|---|---|
+| `approval` | `scope=<brief\|brief+plan\|plan>` | one per approval event |
+| `plan` | `rev` | one, edited in place |
+| `ledger` | `branch` | one, edited in place |
+| `evidence` | `rev branch sha` | one, edited in place |
+| `review` | `round sha agent=<claude\|codex> verdict=<clean\|needs-fixes>` | one per review cycle, rounds appended inside |
+| `decision` | — | one per decision proposal |
+| `handback` | — | one per stop event |
+
+`rev=<n>` and the matching `(v<n>)` heading suffix appear only on revisable artifacts — the brief (issue description), `plan`, and `evidence` — starting at `rev=1`/`(v1)`. Single-event comments (`approval`, `decision`, `handback`) and the `ledger` carry neither. Scripts and agents locate comments strictly by marker, never by heading text. A comment without its marker does not count as the artifact — there is no legacy fallback.
+
+## Operator identity
+
+Every human reference in every artifact — approvals, revisions, decisions, changelog attributions, review adjudications — is written `operator (<github-username>)`:
+
+- Approval: `Approved by operator (<username>) on DD-MM-YYYY: "<their words>"`
+- Register line: `- DD-MM-YYYY operator (<username>) — <decision>`
+
+## Revision markers
+
+Any artifact edited after its first approval: the heading gains `(v2)`, the marker gains `rev=2`, and a `Revisions:` line is appended at the bottom — `v2 — DD-MM-YYYY: <what changed>, per operator (<username>) correction`. Existing revision lines are never rewritten.
+
+## Scope classes
+
+Set at intake, applied as a label, announced with its reason (operator can override):
+
+- **`research`** — a question to answer; throwaway code allowed, never merged. No branch/PR/changelog; findings + recommendation are the evidence comment.
+- **`quick-build`** — small change and the flow being changed already exists in the repo to read. Brief (description) + plan (comment) are drafted in the same conversation; **one approval covers both**; then straight to `ready`.
+- **`full-plan`** — big or new ground. Brief approval → `needs-plan` → a separate, fresh-grounded planning session posts the plan → `needs-operator` → "plan approved" → `ready`. Multi-deliverable work becomes an epic; each sub-issue is classified independently.
+
+Scope calls are revisited through the one-way ratchet, whose rules and mechanics live in the `dev-plan` skill — the one home for upgrade/downgrade behavior.
+
+## Labels
+
+State — exactly one per issue (creation colors live in dev-setup's labels row, their one home):
+
+| label | meaning |
+|---|---|
+| `needs-operator` | waiting on the operator: a question, a brief or plan to approve, a proposal |
+| `needs-plan` | brief approved; waiting for the planning stage (full-plan only) |
+| `ready` | fully approved — an agent may start |
+| `working` | claimed, in progress; the ledger comment shows live progress |
+| `for-operator` | done — evidence posted, awaiting operator review |
+
+Modifiers (may coexist with the state label): `risky` · scope `research` / `quick-build` / `full-plan` · `epic` (map parents, only where the org has no native Epic issue type).
+
+## Titles, types, hierarchy
+
+- **Title prefixes** on issues, branches, and PRs identically: dev.md's `branch:` knob type list (that knob stays the list's one home) plus `research:` for research issues. PR title = issue title.
+- **Native issue types** where the org defines them: Feature (feat) · Bug (fix) · Task (docs/chore/refactor/research) · Epic for parents (label fallback otherwise).
+- **Hierarchy:** epic parent = map only (Destination · Decisions so far as one-line gists · Not clear yet · Out of scope), children attached as native sub-issues; issues = the unit of work (brief in description, own approvals/branch/PR/evidence); tasks = checkboxes **in the plan comment only**. Blockers use native issue dependencies; phases use milestones. Only issues — never epics — get `ready`. GitHub caps issue bodies and comments at ~65,536 characters; what a plan nearing that cap means is the `dev-plan` ratchet's call.
+
+## The ledger
+
+Maintained by the implement session as one comment, edited in place:
+
+```markdown
+<!-- vsk:v1 type=ledger branch=<branch> -->
+## Ledger — <branch>
+- Task <N>: complete (commits <base7>..<head7>[, review clean | K parked])
+- Task <N>: fix round <R>/3 (<X> addressed, <Y> open — <one-liners>; commits <a>..<b>)
+- Ruling: <what> — <why> — cost if wrong: <cost>
+- Task <N>: parked — <finding> — Ruling: <why the code stands>
+- Deferred minor: <one-liner>
+```
+
+**Resume protocol:** a fresh, compacted, or (operator-handed) takeover session reads, in order: the brief → the plan comment → the ledger → `git log` on the branch — **nothing else**. Tasks with a `complete` line are DONE, never re-executed; a task whose last line is a fix round resumes at the next round. After compaction, trust the ledger and `git log` over recollection. Every `Ruling:` line surfaces in the evidence comment — a ruling that dies with the session was a decision made in secret.
+
+## `.vegastack/.tmp/` workspace
+
+All transitory artifacts — subagent reports, review packages, plan drafts, extracted diffs — live at `.vegastack/.tmp/<issue-number>-<title-slug>/` (pre-issue intake drafts, which have no number yet: `.vegastack/.tmp/intake-<slug>/`), kept out of git by a self-ignoring `.gitignore` (`printf '*\n' > .vegastack/.tmp/.gitignore`, created on first use). Subagents write full reports to files there and return only short status — a dead subagent's findings survive on disk, and the primary session never holds full reports in context. The workspace lives in the working tree (never under `.git/`, which harnesses protect from writes).
+
+## Verification gate
+
+Before claiming any status: **IDENTIFY** the command that proves the claim → **RUN** it fresh and complete → **READ** the full output and exit code → only then claim, with the evidence. "Should pass", a previous run, or a subagent's say-so are never evidence. Guard scripts follow the same doctrine: machine-verifiable facts **block** (exit 2 with the reason); regex or judgment heuristics only **warn** — no AI inference inside guards, and an unverifiable state fails closed.
+
+## Plain-language collaboration
+
+Every skill run ends with a simple-language summary: what happened, which paths were taken — cross-agent invocations announced at trigger time AND summarized at the end — and what is worth the operator double-checking. Use mermaid or ASCII diagrams in issues wherever a picture beats prose. A vague or self-contradicting operator answer gets pushback with concrete options, never silent absorption.

package/skill/dev-intake/scripts/brief-lint.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+// dev-intake guard: deterministic checks on a drafted brief before posting.
+// Missing structure blocks; quality smells only warn (heuristics never block).
+// Inline quick-build plans are linted separately by dev-plan's plan-lint — the
+// banned-placeholder list lives there, its single home.
+//
+// Exit codes: 0 pass · 1 pass-with-warnings · 2 blocked (reasons printed).
+// Usage: node brief-lint.mjs --file <brief.md> --scope <research|quick-build|full-plan> --json
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const REQUIRED_HEADINGS = {
+  research: [/^##\s+.*question/im, /^##\s+.*answered/im],
+  'quick-build': [/^##\s+Outcome\b/m, /^##\s+Tests and acceptance\b/m, /^##\s+Approach/m],
+  'full-plan': [/^##\s+Outcome\b/m, /^##\s+Out of scope\b/m, /^##\s+Tests and acceptance\b/m, /^##\s+Approach/m],
+};
+
+const VAGUE_SMELLS = [
+  /\bworks (properly|correctly|as expected)\b/i,
+  /\buser[- ]friendly\b/i,
+  /\brobust(ly)?\b/i,
+  /\betc\.?\b/i,
+];
+
+export function lintBrief(text, scope, { fix = false } = {}) {
+  const blocks = [];
+  const warns = [];
+
+  if (!REQUIRED_HEADINGS[scope]) {
+    return { blocks: [`unknown scope class "${scope}" (research | quick-build | full-plan)`], warns };
+  }
+  if (!/<!--\s*vsk:v1\s+type=brief\b/.test(text)) blocks.push('missing brief marker (<!-- vsk:v1 type=brief rev=n scope=... -->)');
+  if (scope !== 'research' && !/^\*\*Scope:\*\*/m.test(text)) {
+    blocks.push('missing the **Scope:** line — the announced reason must survive the conversation');
+  }
+  if (fix && !/^##\s+Reproduction\b/m.test(text)) {
+    blocks.push('fix-type brief without a ## Reproduction section — an unreproducible bug is research first');
+  }
+
+  for (const heading of REQUIRED_HEADINGS[scope]) {
+    if (!heading.test(text)) blocks.push(`missing required section for ${scope}: ${heading.source}`);
+  }
+
+  if (scope !== 'research') {
+    const approach = text.split(/^(?=##\s)/m).find((chunk) => /^##\s+Approach/.test(chunk));
+    if (approach && !/`[^`]*[/.][^`]*`/.test(approach)) {
+      blocks.push('Approach and touch points names no real backticked paths — grounding was skipped or unrecorded');
+    }
+  }
+
+  for (const smell of VAGUE_SMELLS) {
+    const hit = smell.exec(text);
+    if (hit) warns.push(`vague wording: "${hit[0]}" — name the observable behavior instead`);
+  }
+
+  return { blocks, warns };
+}
+
+const invokedDirectly = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (invokedDirectly) {
+  const argv = process.argv.slice(2);
+  const json = argv.includes('--json');
+  const get = (flag) => { const i = argv.indexOf(flag); return i === -1 ? undefined : argv[i + 1]; };
+  let outcome;
+  const file = get('--file');
+  const scope = get('--scope');
+  if (!file || !scope) {
+    outcome = { blocks: ['usage: brief-lint.mjs --file <brief.md> --scope <class> [--fix] [--json]'], warns: [] };
+  } else {
+    try {
+      outcome = lintBrief(readFileSync(file, 'utf8'), scope, { fix: argv.includes('--fix') });
+    } catch (error) {
+      outcome = { blocks: [`cannot read brief: ${error.message}`], warns: [] };
+    }
+  }
+  const ok = outcome.blocks.length === 0;
+  const exitCode = ok ? (outcome.warns.length ? 1 : 0) : 2;
+  if (json) {
+    console.log(JSON.stringify({ guard: 'brief-lint', ok, ...outcome }, null, 2));
+  } else {
+    console.log(`brief-lint: ${ok ? (outcome.warns.length ? 'pass with warnings' : 'pass') : 'BLOCKED'}`);
+    for (const b of outcome.blocks) console.log(`  block: ${b}`);
+    for (const w of outcome.warns) console.log(`  warn: ${w}`);
+  }
+  process.exit(exitCode);
+}

package/skill/dev-plan/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: dev-plan
+description: Write the implementation plan for an approved issue before any code exists. Use when asked to "plan issue 12", "write the plan for" a feature or issue, "plan this before building", when picking up an issue labeled needs-plan, when an approved brief needs its technical approach worked out, or when dev-intake requests the inline plan for a quick-build issue. Not for writing or approving the brief itself (dev-intake), not for executing an approved plan (dev-implement), not for architecture stack advice (dev-architect — this skill consults it while planning).
+---
+
+# dev-plan
+
+The planning stage: an approved brief goes in, an operator-approved plan comes out, and only then does code exist. Plans are written against the repo **as it is now** — a separate session from intake for `full-plan` issues, because code drifts between brief approval and build. Formats follow the `dev-setup` skill's `references/conventions.md` (cited by name — read it wherever dev-setup is installed).
+
+Nearest neighbors: `dev-intake` owns the brief and its approval mechanics — this skill owns the how; `dev-implement` executes what this produces, task by task. If `.vegastack/dev.md` is missing → run `dev-setup` first.
+
+## Every run
+
+1. Read `.vegastack/dev.md` and the issue: brief (description), recorded brief approval (`type=approval` marker), scope label. Full-plan issues arrive labeled `needs-plan`; anything else at this door is either intake's inline request (below) or a misroute — say so.
+2. **Re-ground.** Open the brief's touch points in the current code; verify the flow, names, and shapes the plan will build on. A brief claim that no longer matches reality goes back to the operator (`handback` comment, `needs-operator`) — never plan on top of drift.
+3. Stack-bearing choices (schema, hosting, services, jobs, auth) check `dev-architect` — its verify protocol governs platform claims, and no plan re-proposes a recorded rejection.
+
+## The questionnaire
+
+Numbered rounds over the full frontier (every open question whose prerequisites are settled), each question carrying a recommended answer so the operator can reply "all recommended":
+
+1. **Approaches** — 2–3 candidates with the trade-off that matters and one recommendation. Never a single option.
+2. **System design** — schema, interfaces, migration shape, failure modes; what breaks at the edges.
+3. **Risk** — blast radius, what a rollback looks like, what should stop a dark run beyond the standing stop-list.
+4. **Brief challenge** — anything planning revealed the brief missed or got wrong goes back to the operator as a question, never silently absorbed into the plan.
+
+A vague or self-contradicting answer gets pushback with concrete options — simple words, a mermaid or ASCII sketch in the issue when a picture beats prose (conventions' collaboration rule).
+
+## The plan
+
+Post one comment per [plan-format](references/plan-format.md): Goal · Approach (alternatives named) · Constraints · ordered `- [ ]` tasks, each with exact Files, an Interfaces block (consumes/produces with exact signatures), and Steps that put the failing test before the code. Before posting:
+
+- Self-review: every brief requirement maps to a task; names and types are consistent across tasks; no banned placeholders (the list lives in plan-format).
+- Run this skill's plan-lint: `node <path-to-this-skill>/scripts/plan-lint.mjs --file <draft> --json`; exit 2 = fix before posting (placeholders and structural gaps block).
+
+Checkboxes belong to the implement session — never pre-tick them.
+
+## Labels and approval
+
+Post the plan → flip to `needs-operator`. On the operator's "plan approved": record `<!-- vsk:v1 type=approval scope=plan -->` with their quoted words (`operator (<username>)` format), flip to `ready`, stop — building is dev-implement's.
+
+## The ratchet — one home, this file
+
+- **Upgrade (any time, no permission needed to propose):** planning reveals the work is bigger than its scope label — a quick-build that needs real design, an issue that is actually several deliverables. Stop, post one `handback` comment proposing the reclassification or the epic split (parent map + sub-issues, each classified fresh), `needs-operator`. Never silently plan a monster: a plan approaching GitHub's ~65,536-character comment cap is the slicing telling you it wants to be an epic.
+- **Downgrade (operator's yes only):** planning reveals the work is trivial — propose skipping to `ready` with the brief's inline approach, and wait for the yes.
+
+## Quick-build inline mode
+
+Invoked from inside dev-intake's conversation, after the brief has consensus: same format, proportionally small (a four-item task list is a fine plan), posted as the plan comment alongside the brief. The operator's single approval covers both (`scope=brief+plan`) — no `needs-plan` stop, no second exchange. The re-grounding step collapses to what intake already read; the ratchet still applies.
+
+## Closing
+
+End every run with the plain-language summary: what was planned, which approach won and why, what the operator should double-check, and what happens next.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "dev-plan"
+  short_description: "Plan an approved issue before any code exists"
+  default_prompt: "Use $dev-plan to write the implementation plan for this approved issue."

package/skill/dev-plan/references/conventions.md

@@ -0,0 +1,93 @@
+# Workflow conventions
+
+The single spec for the artifacts every dev-family skill reads and writes. One home per rule: skills cite this file, never restate it. Everything here is harness-neutral.
+
+## Comment metadata markers
+
+Every workflow-generated issue comment opens with an invisible HTML marker followed by a human heading:
+
+```markdown
+<!-- vsk:v1 type=<type> rev=<n> [key=value ...] -->
+## <Human title> (v<n>)
+```
+
+| type | required keys | instances |
+|---|---|---|
+| `approval` | `scope=<brief\|brief+plan\|plan>` | one per approval event |
+| `plan` | `rev` | one, edited in place |
+| `ledger` | `branch` | one, edited in place |
+| `evidence` | `rev branch sha` | one, edited in place |
+| `review` | `round sha agent=<claude\|codex> verdict=<clean\|needs-fixes>` | one per review cycle, rounds appended inside |
+| `decision` | — | one per decision proposal |
+| `handback` | — | one per stop event |
+
+`rev=<n>` and the matching `(v<n>)` heading suffix appear only on revisable artifacts — the brief (issue description), `plan`, and `evidence` — starting at `rev=1`/`(v1)`. Single-event comments (`approval`, `decision`, `handback`) and the `ledger` carry neither. Scripts and agents locate comments strictly by marker, never by heading text. A comment without its marker does not count as the artifact — there is no legacy fallback.
+
+## Operator identity
+
+Every human reference in every artifact — approvals, revisions, decisions, changelog attributions, review adjudications — is written `operator (<github-username>)`:
+
+- Approval: `Approved by operator (<username>) on DD-MM-YYYY: "<their words>"`
+- Register line: `- DD-MM-YYYY operator (<username>) — <decision>`
+
+## Revision markers
+
+Any artifact edited after its first approval: the heading gains `(v2)`, the marker gains `rev=2`, and a `Revisions:` line is appended at the bottom — `v2 — DD-MM-YYYY: <what changed>, per operator (<username>) correction`. Existing revision lines are never rewritten.
+
+## Scope classes
+
+Set at intake, applied as a label, announced with its reason (operator can override):
+
+- **`research`** — a question to answer; throwaway code allowed, never merged. No branch/PR/changelog; findings + recommendation are the evidence comment.
+- **`quick-build`** — small change and the flow being changed already exists in the repo to read. Brief (description) + plan (comment) are drafted in the same conversation; **one approval covers both**; then straight to `ready`.
+- **`full-plan`** — big or new ground. Brief approval → `needs-plan` → a separate, fresh-grounded planning session posts the plan → `needs-operator` → "plan approved" → `ready`. Multi-deliverable work becomes an epic; each sub-issue is classified independently.
+
+Scope calls are revisited through the one-way ratchet, whose rules and mechanics live in the `dev-plan` skill — the one home for upgrade/downgrade behavior.
+
+## Labels
+
+State — exactly one per issue (creation colors live in dev-setup's labels row, their one home):
+
+| label | meaning |
+|---|---|
+| `needs-operator` | waiting on the operator: a question, a brief or plan to approve, a proposal |
+| `needs-plan` | brief approved; waiting for the planning stage (full-plan only) |
+| `ready` | fully approved — an agent may start |
+| `working` | claimed, in progress; the ledger comment shows live progress |
+| `for-operator` | done — evidence posted, awaiting operator review |
+
+Modifiers (may coexist with the state label): `risky` · scope `research` / `quick-build` / `full-plan` · `epic` (map parents, only where the org has no native Epic issue type).
+
+## Titles, types, hierarchy
+
+- **Title prefixes** on issues, branches, and PRs identically: dev.md's `branch:` knob type list (that knob stays the list's one home) plus `research:` for research issues. PR title = issue title.
+- **Native issue types** where the org defines them: Feature (feat) · Bug (fix) · Task (docs/chore/refactor/research) · Epic for parents (label fallback otherwise).
+- **Hierarchy:** epic parent = map only (Destination · Decisions so far as one-line gists · Not clear yet · Out of scope), children attached as native sub-issues; issues = the unit of work (brief in description, own approvals/branch/PR/evidence); tasks = checkboxes **in the plan comment only**. Blockers use native issue dependencies; phases use milestones. Only issues — never epics — get `ready`. GitHub caps issue bodies and comments at ~65,536 characters; what a plan nearing that cap means is the `dev-plan` ratchet's call.
+
+## The ledger
+
+Maintained by the implement session as one comment, edited in place:
+
+```markdown
+<!-- vsk:v1 type=ledger branch=<branch> -->
+## Ledger — <branch>
+- Task <N>: complete (commits <base7>..<head7>[, review clean | K parked])
+- Task <N>: fix round <R>/3 (<X> addressed, <Y> open — <one-liners>; commits <a>..<b>)
+- Ruling: <what> — <why> — cost if wrong: <cost>
+- Task <N>: parked — <finding> — Ruling: <why the code stands>
+- Deferred minor: <one-liner>
+```
+
+**Resume protocol:** a fresh, compacted, or (operator-handed) takeover session reads, in order: the brief → the plan comment → the ledger → `git log` on the branch — **nothing else**. Tasks with a `complete` line are DONE, never re-executed; a task whose last line is a fix round resumes at the next round. After compaction, trust the ledger and `git log` over recollection. Every `Ruling:` line surfaces in the evidence comment — a ruling that dies with the session was a decision made in secret.
+
+## `.vegastack/.tmp/` workspace
+
+All transitory artifacts — subagent reports, review packages, plan drafts, extracted diffs — live at `.vegastack/.tmp/<issue-number>-<title-slug>/` (pre-issue intake drafts, which have no number yet: `.vegastack/.tmp/intake-<slug>/`), kept out of git by a self-ignoring `.gitignore` (`printf '*\n' > .vegastack/.tmp/.gitignore`, created on first use). Subagents write full reports to files there and return only short status — a dead subagent's findings survive on disk, and the primary session never holds full reports in context. The workspace lives in the working tree (never under `.git/`, which harnesses protect from writes).
+
+## Verification gate
+
+Before claiming any status: **IDENTIFY** the command that proves the claim → **RUN** it fresh and complete → **READ** the full output and exit code → only then claim, with the evidence. "Should pass", a previous run, or a subagent's say-so are never evidence. Guard scripts follow the same doctrine: machine-verifiable facts **block** (exit 2 with the reason); regex or judgment heuristics only **warn** — no AI inference inside guards, and an unverifiable state fails closed.
+
+## Plain-language collaboration
+
+Every skill run ends with a simple-language summary: what happened, which paths were taken — cross-agent invocations announced at trigger time AND summarized at the end — and what is worth the operator double-checking. Use mermaid or ASCII diagrams in issues wherever a picture beats prose. A vague or self-contradicting operator answer gets pushback with concrete options, never silent absorption.

package/skill/dev-plan/references/plan-format.md

@@ -0,0 +1,54 @@
+# The plan format
+
+The comment a plan lives in, verbatim. dev-implement executes it task by task and ticks the checkboxes; plan-lint enforces the deterministic parts.
+
+````markdown
+<!-- vsk:v1 type=plan rev=1 -->
+## Plan (v1)
+
+**Goal:** <one sentence: what exists when this plan is done>
+**Approach:** <2–3 sentences — and the alternatives considered with why they lost, one line each>
+**Constraints:** <binding requirements from the brief and Architecture facts, exact values, one per line>
+
+### Tasks
+
+- [ ] **Task 1: <name>**
+  - Files — Create: `exact/path.ts` · Modify: `exact/path.ts` (<which area>) · Test: `exact/path.test.ts`
+  - Interfaces — Consumes: <exact signatures/names from earlier tasks> · Produces: <exact names, parameter and return types later tasks rely on — an implementer may see only this task; this block is how they learn what neighbors use>
+  - Steps: write the failing test (the actual test code, fenced) → run it, expect FAIL with <reason> → implement the minimal code → run, expect PASS → commit `<type>: <message>`
+- [ ] **Task 2: …**
+
+**Revisions:** (absent until a post-approval edit; then one line per edit)
+````
+
+## Rules
+
+- **Task size:** the smallest unit that carries its own test cycle and is worth a fresh reviewer's look. Fold setup/scaffolding/docs into the task whose deliverable needs them; split only where a reviewer could reject one task while approving its neighbor. Each task ends independently verifiable.
+- **Prose tasks** (docs, skill text, config) swap the test-first Steps for edit → verify (the concrete command: `bun run check`, a link-resolution run, a rendered read-through) → commit. The verify step is never omitted.
+- **Revisions:** post-approval edits follow the revision-marker rule in dev-setup's `references/conventions.md` — bump the heading/marker version and append the `Revisions:` line.
+
+## Banned placeholders
+
+These are plan failures — plan-lint rejects them, and a human reviewer should too:
+
+- "TBD", "TODO", "implement later", "fill in details"
+- "Add appropriate error handling" / "add validation" / "handle edge cases"
+- "Write tests for the above" without the actual test code
+- "Similar to Task N" — repeat the content; tasks are read out of order
+- Steps that describe what to do without showing how (code steps require code blocks)
+- References to types, functions, or files no task defines
+
+## Self-review before posting
+
+1. **Coverage:** walk the brief section by section — every requirement points at a task; list any gap (a gap is a question for the operator, not a silent omission).
+2. **Placeholder scan:** search the draft for the banned list above; fix inline.
+3. **Consistency:** names, signatures, and paths used in later tasks match what earlier tasks define — `clearLayers()` in Task 3 but `clearFullLayers()` in Task 7 is a bug now, not at build time.
+
+## Worked micro-example
+
+```markdown
+- [ ] **Task 1: reminder schedule column**
+  - Files — Modify: `server/db/schema/invoices.ts` (invoices table) · Test: `server/db/schema/invoices.test.ts`
+  - Interfaces — Produces: `invoices.reminderAt: timestamp | null` (Drizzle column), read by Task 2's query
+  - Steps: failing test asserting the column exists in the generated schema → run, expect FAIL "no such column" → add the column + regenerate → run, expect PASS → commit `feat: reminder schedule column`
+```

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

@@ -0,0 +1,3 @@
+# Refresh contract — dev-plan
+
+Evergreen: this skill asserts no version pins, vendor mechanisms beyond long-stable GitHub comment behavior (the ~65,536-character comment cap is stated as approximate and directional), numeric vendor limits, or dated claims — its content is planning discipline (questionnaire, plan format, ratchet), all versionless. Revisit if a future edit introduces a volatile fact.

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

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