@vegastack/vegafactory 0.19.0

package/skill/dev-review/references/cross-agent.md

@@ -0,0 +1,39 @@
+# Cross-agent review
+
+The independence upgrade: the review runs on the *other* agent — Codex when Claude built the code, Claude when Codex did — so the reviewer shares no model, no session, and no authorship with the implementer. Used on `risky` issues by default and whenever dev.md's `review:` knob says `cross-agent`.
+
+## Announce, invoke, summarize — the operator is never blind
+
+1. **At trigger time**, tell the operator in plain language: "invoking Codex for the cross-agent review of issue #N" — before the call, not after.
+2. **Invoke** non-interactively with the handoff below passed as ONE argument through an exec arg array — `execFile('codex', ['exec', '-c', 'model=<model>', '-c', 'model_reasoning_effort=<effort>', handoff])` from Claude, `execFile('claude', ['-p', '--model', '<model>', '--effort', '<effort>', handoff])` from Codex — never interpolated into a shell string (the exact pattern this skill's own known-patterns template says to still-flag). `<model>` and `<effort>` come from dev.md's `harness-policy:` `review` entry; with no such line, drop both flag pairs and let the reviewing harness use its own defaults rather than inventing a model id.
+3. **At the end**, summarize: which agent reviewed, the verdict, where its comment is, and what's worth the operator double-checking.
+
+## The handoff — exact format
+
+```
+REVIEW REQUEST (vsk cross-agent v1)
+repo: <absolute path> · issue: <url> · branch: <name> · range: <base7>..<head7>
+brief: the issue description (marker type=brief) · plan: the issue comment
+marked type=plan · package: <path to the review package file> · known-patterns:
+.vegastack/review-known-patterns.md · conventions: references/conventions.md inside ANY installed dev-family skill
+(e.g. .claude/skills/dev-review/references/conventions.md — every dev skill ships a copy)
+axes: spec, standards[, security]
+output contract: post exactly ONE issue comment in the review-comment format
+(marker: <!-- vsk:v1 type=review round=<n> sha=<head7> agent=codex verdict=... -->;
+the reverse direction writes agent=claude);
+on a re-review round, EDIT that same comment — update its single top marker to the
+new round/sha/verdict and append the round section below (never a second marker,
+never a second comment),
+findings as Finding [N] with severities [CRITICAL|MUST-FIX|SHOULD-FIX|NIT] and
+path:line evidence; nitpicks and low-confidence collapsed in <details>.
+constraints: READ-ONLY — never commit, push, edit files, or change labels; your
+only write is the review comment, via gh.
+```
+
+The reviewing agent posts its own comment with its own `agent=` key — independence stays verifiable in the record, never paraphrased by the author.
+
+## Fallbacks and failure honesty
+
+- The other agent's CLI is not installed → fall back to the manual relay (tell the operator which agent to point at the issue), and note that `dev-setup` records the gap and recommends installing it.
+- The invocation fails or times out → say so plainly, fall back to a fresh-subagent review, and label the evidence comment's Review line accordingly — never silently substitute and call it cross-agent.
+- The other agent's review misses the output contract (no marker, no severities) → treat its content as raw findings: post them yourself in the correct format with `agent=` credited, and note the reformatting.

package/skill/dev-review/references/dispatch-prompts.md

@@ -0,0 +1,121 @@
+# Reviewer dispatch prompts
+
+The verbatim briefs each axis subagent receives. Compose with paths and constraints rather than pasted history, because a reviewer handed the session transcript inherits its blind spots. Every dispatch carries the shared preamble, then its axis brief.
+
+## Shared preamble (every axis)
+
+```text
+<document name="brief" path="<issue url or path>"/>
+<document name="plan">the plan comment (marker type=plan) on that issue</document>
+<document name="package" path="<package path>"/>
+<document name="constraints">
+<constraints block, copied verbatim from the brief and plan>
+</document>
+
+You are a fresh-context reviewer with no memory of writing this change and no
+stake in it passing. Read every document above in full, and the full files
+where the diff needs context (30 or more lines around a hunk), because a
+diff-only read misses invariants. Do all reading and judging yourself: a
+reviewer you spawn duplicates this review at full cost and its opinion counts
+for nothing in the process.
+
+Report every finding you see, each with its confidence (high, medium, low)
+and severity; the review loop and adjudication downstream are the filter,
+so a finding left out here is one nobody can weigh. Report verified absence
+of findings the same way. A change that is large, late or almost done gets
+the same reading as any other.
+
+Write your full report to <report path>, each finding as:
+Finding [N]: <title> — [SEVERITY] (confidence: high|medium|low) path:line,
+issue, why it matters, fix (fenced snippet when code).
+Return only short status: verdict, per-severity counts, one line per finding
+(title, severity, path:line) — the detail lives in the report file.
+```
+
+## Spec axis brief
+
+```
+Are there bugs in this change? Judge the diff against the current brief and plan only:
+(a) MISSING — requirements asked for that are absent or partial;
+(b) SCOPE CREEP — behavior in the diff nobody asked for;
+(c) WRONG — requirements that look implemented but don't do what the brief
+    says.
+Quote the exact brief/plan line for every finding. If code and brief diverge
+because the operator changed direction, that is still a finding — the brief
+must be revision-updated before review can pass; say so.
+
+Tests-are-real rubric — flag as [MUST-FIX] any acceptance-relevant test that is:
+- implementation-coupled: mocks internal collaborators, asserts call
+  counts/order, or breaks on refactor without behavior change;
+- tautological: the assertion recomputes the expected value the way the code
+  does, so it can never disagree;
+- horizontal-sliced: bulk tests asserting imagined shapes rather than the
+  behavior the brief names.
+A changed behavior with no covering test at the brief's named seams is MISSING.
+```
+
+## Standards axis brief
+
+```
+Are there bugs or violations of a documented standard in this change? Judge the diff against, in priority order:
+1. .vegastack/review-known-patterns.md — its never-flag entries suppress
+   findings unless their "Still flag if:" clause applies;
+2. the project's documented standards (dev.md Project rules, CONTRIBUTING);
+   a documented repo standard always overrides the baseline below;
+3. the smell baseline — each a labeled judgment call ("possible feature
+   envy"), never a hard violation; skip anything tooling already enforces:
+
+- Mysterious name: a name that doesn't reveal what it does or holds → rename.
+- Duplicated code: the same logic shape in more than one hunk/file → extract.
+- Feature envy: a method reaching into another object's data more than its
+  own → move it to the data it envies.
+- Data clumps: the same fields/params traveling together → bundle into a type.
+- Primitive obsession: a primitive standing in for a domain concept → type it.
+- Repeated switches: the same case-cascade on the same type recurring → one
+  shared map or polymorphism.
+- Shotgun surgery: one logical change forcing scattered edits everywhere →
+  gather it into one module.
+- Divergent change: one module edited for several unrelated reasons → split.
+- Speculative generality: abstraction or hooks for needs the brief doesn't
+  have → delete, inline until a real need shows.
+- Message chains: long a.b().c().d() walks the caller depends on → hide the
+  walk behind one method.
+- Middle man: a unit that mostly delegates onward → cut it, call direct.
+- Refused bequest: an implementer ignoring most of what it inherits → compose
+  instead.
+
+Quiet profile: report style only where a documented rule exists. Hard
+violations of documented standards may be [MUST-FIX]; baseline smells are
+[SHOULD-FIX] or [NIT].
+```
+
+## Security axis brief
+
+Compose the security dispatch from [security-axis](security-axis.md): the shared preamble above, then that file's Method steps, finding format (the three extra lines), severity definitions, and standing red lines, quoted into the prompt — the reviewer must receive them in full, not a pointer it cannot follow.
+
+Where a scanner report exists, add its path and that file's "Scanner evidence" rules to the same dispatch:
+
+```
+Scanner report: <path to skill-scan.json or the project's equivalent>.
+Treat every entry as a CANDIDATE finding, never a verdict: read the source at
+its file:line, trace the flow, and assign severity yourself by exploitability.
+The report's aggregate score is context, not a ranking. Entries the baseline
+suppressed are in scope — judge whether each rule is scoped as narrowly as its
+cause and whether its stated re-trigger condition would actually fire. Say so
+in your verdict line if the report says the scan did not complete.
+```
+
+## Re-review brief (scoped, every fix round)
+
+```
+Inputs: the same brief and plan, the implementer's report file (its fix
+reports are the test evidence — do not re-run suites), and the scoped package
+at <fix package path> covering only <FIX_BASE>..<HEAD>.
+Findings under verification: <the open findings, verbatim>.
+
+For each finding, in order: ADDRESSED or NOT ADDRESSED, with path:line
+evidence. "Attempted" is not addressed — the specific defect must no longer
+exist. Then: new breakage the fix diff itself introduced (severity + line),
+and out-of-scope observations (non-blocking, one line each). Final line:
+"Fix round: all addressed | findings remain open".
+```

package/skill/dev-review/references/security-axis.md

@@ -0,0 +1,45 @@
+# The security axis
+
+Runs on `risky` issues, whenever the diff's touch points hit an auth surface, money, user data, or externally-controlled input, and whenever the diff touches a skill under dev.md's `skill-scan:` root — the trigger is the surface, not the label alone.
+
+## Scanner evidence — a finding's start, never its end
+
+Where the project runs a scanner (the `skill-scan` skill ships this family's scanner for agent skills; a project may name others), its report is an **input to this axis**, on the same footing as the diff. It is evidence, not a verdict:
+
+- **A scanner hit is a candidate finding.** It arrives with a rule ID and a `file:line` and nothing else — no data flow, no attacker, no exploitability. Promote it to a finding only after the Method below fills those in; a hit you cannot trace goes to the collapsed low-confidence block like any other hunch.
+- **Read the source at the location before judging it.** The scanner matched text; whether that text is a vulnerability is your call, made against the file, not the summary.
+- **Severity is yours, not the scanner's.** Map its finding onto this file's ladder by exploitability. A scanner HIGH that cannot be exploited is not `[CRITICAL]`; a scanner MEDIUM with a traced path to a real sink can be.
+- **Never downgrade an unexplained HIGH or CRITICAL** on reputation, score, or "it's our own code". Either the trace shows why it does not hold, or it stands.
+- **The aggregate risk score is not a finding.** It is distorted upward by documentation of the very mechanics being scanned and downward by unrelated suppressions. Quote it for context; never rank on it.
+- **Suppressions are in scope for this axis.** A finding silenced by a baseline rule rather than fixed is reviewable: check the rule is scoped as narrowly as its cause and that its stated re-trigger condition is one that would actually fire.
+- **A degraded or partial scan is not a clean scan.** If the report says the run did not complete, say so in the verdict line rather than reporting its numbers.
+
+## Method — evidence before severity
+
+1. **Trace the data flow** for every candidate finding: origin → transformations → sink. Is the value attacker-controlled at the point of use? A finding without a traced flow is a hunch, not a finding.
+2. **Check defense in depth before flagging a gap.** A missing check at one layer is not a vulnerability if another layer enforces it on every path — name the enforcing layer instead. Flag it only when no layer holds, or the only holding layer is UX (client-side, middleware-as-convenience).
+3. **Verify library defaults** before "missing configuration" findings — frameworks ship safe defaults more often than training-data memory suggests; check the current docs per `dev-architect`'s verify protocol.
+4. **Assess exploitability**: what does the attacker need (auth level, network position, timing, knowledge)? What mitigating controls exist? Severity follows exploitability, never vibes.
+
+## Finding format — three extra lines
+
+On top of the standard finding shape, every security finding carries:
+
+```
+Data flow: <origin> → <transformations> → <sink>
+Attack prerequisites: <what the attacker needs>
+Mitigating controls: <existing defenses that reduce but don't eliminate>
+```
+
+A finding that can't fill the Data flow line goes to the collapsed low-confidence block, not the main list.
+
+## Severity
+
+- **[CRITICAL]** — exploitable now: auth bypass at the enforcement layer, injection with a traced user-input path, secret/credential exposure, unprotected sensitive mutation. Blocks, above MUST-FIX.
+- **[MUST-FIX]** — a real weakness needing prerequisites an attacker can plausibly meet.
+- **[SHOULD-FIX]** — hardening: rate limits, PII in logs, missing timeouts, defense-in-depth gaps with a holding layer.
+- Never round up to look thorough; judge against the project's Architecture facts — platform-scale concerns are not defects on a small internal tool.
+
+## Standing red lines (summary — `dev-architect` remains their home)
+
+Middleware/proxy is never the authorization boundary; authorization lives server-side per resource. No secret in plaintext anywhere — code, config, logs, events, agent state. Permission checks fail closed, and the deny is still audited.

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

@@ -0,0 +1,5 @@
+# Refresh contract — dev-review
+
+Evergreen: this skill asserts no version pins, vendor mechanisms, numeric limits, or dated claims — its content (SKILL.md, `references/dispatch-prompts.md`, `references/security-axis.md`, `references/cross-agent.md`, the known-patterns template) is versionless review discipline: axes, severities, the bounded fix loop, the reviewer briefs, the smell baseline, and the cross-agent handoff. The `codex exec` / `claude -p` invocation forms stay deliberately untracked as durable CLI surfaces; dev-setup's detection covers their presence per machine.
+
+**The waiver was retired on 01-09-2026 (issue #83) and restored on 03-09-2026 (issue #113):** the six volatile SkillSpector facts that retired it — the install command, the `--version` output shape, the releases API, and the uv/brew/pipx channel parsers — moved to the `skill-scan` skill together with the guard that parses them, and are tracked in that skill's registry now. Revisit if a future edit introduces a volatile fact back into this skill.

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

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

package/skill/dev-setup/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: dev-setup
+description: Bootstrap a project for issue-driven agent development — existing repo or brand-new empty directory. Use when asked to "set up the dev workflow", "bootstrap this project for agents", "install the dev workflow here", "set up this new project", "wire the release guards", "create the workflow labels", "set up the changelog convention", "fill the architecture profile section", to re-run setup after machinery appeared or knobs changed, or invoked as dev-setup; also run automatically when any dev-family skill finds no .vegastack/dev.md in the project. Not for architecture advice (dev-architect reads the section this skill writes), authoring skills (skillify), or general CI and app scaffolding.
+---
+
+# dev-setup
+
+Act: give the project everything the dev workflow needs, asking only for the decisions detection cannot make.
+
+Creates the profile/runbooks, thin AGENTS.md section, labels and decision register. Other dev skills call it when `.vegastack/dev.md` is missing. [Conventions](references/conventions.md) owns shared artifact and workspace rules.
+
+Nearest neighbor: `dev-architect` consumes dev.md's `## Architecture` section and gives architecture advice; dev-setup detects the facts and writes the section. There is no separate architecture profile — dev.md is the one file.
+
+## Routing
+
+| Need | Read |
+|---|---|
+| artifact formats and workspaces | [conventions](references/conventions.md) |
+| headless question fallback | [ask-route](references/ask-route.md) |
+| harness, hooks and model facts | [harness-facts](references/harness-facts.md) |
+| stack and release playbooks | [stack-playbooks](references/stack-playbooks.md) |
+| GitHub App and broker | [github-app](references/github-app.md) |
+
+## Step 1 — Detect before asking
+
+Gather these silently and present them as findings — "here's what I found — correct me if wrong" — because facts are detection's job and decisions are the user's:
+
+| What | How |
+|---|---|
+| repo, default branch | `git remote get-url origin` · `gh repo view --json nameWithOwner,defaultBranchRef` |
+| org defaults (control room) | `vegafactory sync --json` first — on a repo with no `control-room:` knob yet, the first run here, `vegafactory sync --org <org> --json` with the org from the repo lookup above, because `sync` otherwise reads the knob this skill has not written — then read the local clone it names: skills read the clone, never the network, so an outage degrades to "last synced <time>" instead of failing; a control room that answers a knob removes that question from Round B; a room that does not exist or cannot be read is a plain finding, and Round B asks; layout and precedence are the `vegafactory-setup` skill's |
+| gh authenticated | `gh auth status` |
+| operator username (the `architect:` knob) | `gh api user -q .login`, fallback `git config user.name` — written as the knob's value with no question, because the architecture owner defaults to whoever runs setup; the decision-register header uses the same lookup |
+| the operator list (the `operators:` knob) | the same `gh api user -q .login` lookup, written as a one-name csv without asking — assignment needs a default owner from run one, and the operator edits the line to add colleagues |
+| gh version | `gh --version` against the floors in [harness-facts](references/harness-facts.md); each feature the version lacks is named in the Step 4 report, so the operator upgrades once instead of hitting the gap mid-run |
+| stack and commands | package.json scripts, lockfiles, framework configs |
+| web app (UI evidence relevant) | framework dependencies (next, react, vue, …) |
+| release/changelog machinery | match signals against [stack-playbooks](references/stack-playbooks.md) — the matched playbook drafts the `## Ship` runbook, the `changelog:` knob, and the guards to offer |
+| environments and run commands | CI/deploy configs, env examples (names only), dev/start scripts — these draft `## Environments` and `## Verify` |
+| architecture (app repos) | wrangler files, drizzle config, better-auth usage, S3/R2 bindings, pg-boss, `eve`/`ai` packages, Dockerfiles/compose, pubspec.yaml — these draft `## Architecture` (a `d1_databases` binding with no Postgres driver is the D1-only class) |
+| existing files | AGENTS.md, CLAUDE.md, `.vegastack/dev.md`, a legacy `.vegastack/arch.md`, the decision register — read before writing, because hand edits in them are the truth |
+| existing labels | `gh label list` |
+| project board | `gh project list --owner <org>` and `gh project field-list` — an existing board drafts `board: <number>`, none found drafts `board: none` |
+| native issue types | `gh api orgs/<org>/issue-types` — an `Epic` type routes parents to it, otherwise the `epic` label ([conventions](references/conventions.md)); the enabled names draft the `issue-types:` knob, `none` where the call 404s |
+| org automation identity | `gh api orgs/<org>/installations` — a `vegafactory` installation means workflows mint tokens from the App ([github-app](references/github-app.md)); owners only, so a 403 is an unknown, not a missing App |
+| native issue fields | `gh api orgs/<org>/issue-fields` — every `single_select` field with its option names, ordered by each option's `priority` key (the array itself comes back alphabetical), drafts the `issue-fields:` knob, `none` where the call 404s; the Priority and Effort options are what dev-intake offers, so they are read, never assumed |
+| harnesses present | `command -v claude codex hermes` and each present one's `--version` — the names and versions become the `harnesses:` knob line, and the AGENTS.md block, the CLAUDE.md import, the hook offer and the `review:` recommendation target only harnesses that exist. Any harness the drafted `harness-policy:` names but the box lacks is absent → record it in `## Environments` with the capability it gates (no Codex → cross-agent review is off and the review stage falls back to a fresh subagent), naming no install command, because the vendor's own docs own that |
+| agent skills in the repo | a directory of skill folders, flat or one group deep, drafts the `skill-scan:` knob at that path (none found drafts `none`), declared once, because a second `skill-scan:` line makes the profile ambiguous and the guard refuses; the knob names the built directory where one exists, because unpackaged fixtures are adversarial on purpose |
+| SkillSpector (skill scanning) | nothing to detect — the skill-scan skill's guard locates the CLI itself and, under `skillspector-update: auto`, installs and upgrades it; confirm the drafted `skillspector-update:` value instead (`auto` provisions silently, `notify` only reports, `off` stays offline) |
+
+Not a git repo, or no origin remote → a greenfield run, not an error: follow the greenfield playbook in [stack-playbooks](references/stack-playbooks.md) — interview for the intended stack, offer `git init` and `gh repo create` each on its own yes, and render dev.md from the playbook's conventions with TODO lines where machinery doesn't exist yet. A declined remote skips labels and records the TODO plainly.
+
+## 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, `clarify` in Hermes ([harness-facts](references/harness-facts.md)). When none is available (headless run, gated mode), write the defaults, mark every unconfirmed knob `# TODO confirm`, and say so, because a wrong invented preference costs more than a TODO. The route the other dev skills take when no tool is available is [ask-route](references/ask-route.md); dev-setup can run before any issue exists, so its own fallback stays the documented defaults above.
+
+**Round A — confirm the detected facts** in one compact summary (repo, stack, commands, web app or not, matched playbook, detected architecture facts). Ask only about what detection could not fill. The summary names which knobs came from the control room and which are this repo's own, because an inherited answer and a local one are corrected in different files.
+
+**Round B — the workflow knobs**, recommended default first:
+
+Every knob `groups/<g>/group.md` or `org.md` already answers is stated as inherited rather than asked — the questions below are only the ones no layer has answered.
+
+1. Review of finished work (`review:` knob, mapped by dev-review): **cross-agent-risky** (subagent axes, the other agent on `risky` — recommended where the Codex CLI was detected; otherwise recommend `subagent`) · `subagent` (no cross-agent) · `cross-agent` (always). Detection found only one harness on the box → recommend `subagent` and say cross-agent is off until a second harness exists, because a knob promising an independent reviewer that cannot run is worse than an honest self-review; the `harness-policy:` line is still drafted in full, so the stage set does not change with the box
+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) · 1 (direct-to-main for single-operator projects: the ship word merges locally and pushes, no PR — everything else unchanged)
+4. Tests: **required for every change** · required for logic changes only
+5. Who may be assigned issues here (`operators:` knob): **just you** (the detected login) · a csv of logins — every human who can receive a `needs-operator` or `for-operator` issue
+
+**Round C — only when the situation exists:**
+
+- Playbook matched → confirm the drafted `## Ship` runbook (steps `auto:`, `ask:`, or `guard:`, each guard with its command inline), the `changelog:` convention and the `release:` knob; keep-a-changelog with no CHANGELOG.md yet → offer to seed the skeleton; no machinery → "Ship: merge only"
+- Guards drafted → offer their CI backstop steps for the project's workflow files, each file on the user's yes — release guards only, because general CI is the project's own
+- Environments or run commands detected → confirm the drafted `## Environments` and `## Verify` bullets
+- Agent skills detected → confirm the drafted `skill-scan:` root, the `skillspector-update:` value (`auto` installs and upgrades the CLI without asking again; `notify` or `off` opt out — say so plainly), the `## Verify` bullet running the guard after the build, and a blocking `guard:` line in `## Ship` before publish, because the published artifact is what the world installs; a declined scan → `skill-scan: none`, said plainly. A project setting a `skill-scan:` root installs the skill-scan skill (`vegafactory skills add skill-scan`), because the knob names a scan the project cannot otherwise run
+- Workflows that write issues, labels, or project items → point the operator at [github-app](references/github-app.md), so the org's automated writes go out as the App and not as a person; this skill drafts those steps and never performs them
+- Project board wanted or detected → offer `.github/workflows/factory-board.yml` from [factory-board template](assets/factory-board.yml.template), written on the user's yes with `{{runs-on}}`, `{{profile}}` and an immutable `{{product-revision}}` bound; the packaged compiler resolves JSON event labels and verifies existing Status options before writing and every line above the `# ---` marker dropped; record the number in `board:`; say plainly that labels drive and the board follows — a card dragged on the board is cosmetic until the next label change — and that the workflow needs the factory App ([github-app](references/github-app.md)) plus gh 2.97.0 on the runner
+- Evidence repo (`ui-evidence: playwright`) → default is the owner's shared `<owner>/dev-review-evidence`, created once with `gh repo create <owner>/dev-review-evidence --private --add-readme` plus the layout/retention README when missing; a naming policy that rejects the name → the closest compliant name, recorded in the knob
+- App architecture detected → confirm the drafted `## Architecture`, asking hosting, stage and kind, which detection can't fill; nothing detected → delete the section, the `stack:` line is enough
+- A legacy `.vegastack/arch.md` exists → fold its knob lines into `## Architecture`, offer each dated `notes:` line to the decision register on the user's yes, then offer to delete arch.md
+- Harnesses detected → confirm the drafted `harness-policy:` line — the six stages are fixed, the models and efforts are the operator's, and the flags each value turns into are in [harness-facts](references/harness-facts.md); a model id the account cannot use fails loudly on first run, and the fix is this knob line, never a skill edit
+- Hooks package → separately offer four per [harness-facts](references/harness-facts.md): ship-guard confirmation; SessionStart context requests bounded verified lessons; Stop heartbeat and legacy decision hook the same nonblocking flush. Directional choices stay session proposals. Each needs its own yes. Deduplicate both config layers while preserving user hooks; replace/report only this package's legacy decision-nudge.sh in place. On that yes, confirm policy then compile the external guard policy; `vegafactory guard sync` refreshes later edits. Copy the shared session-start.mjs adapter for Stop/SessionEnd with one-second advisory timeouts. Apply harness-facts' native-memory exclusion, source trust and configured/invoked/qualified rules; retain project instructions/settings. Trust Codex's project `.codex/` per worktree.
+- Statistics capture (the org's `stats:` policy is on, or no control room exists yet) → offer the three capture hooks separately, one plain sentence each: a local flush request per closed session, pending the managed-hook consumer; which skills a Claude session used and who chose each; the same on Codex from prompt mentions of a skill name, a proxy recorded as one. Say what a record holds — counts and identifiers, never text — that it goes to the org's own control room over the operator's `gh` credential, and that whether anything is recorded is the org's `stats:` policy, not this machine's
+- A parent plan declares independent child groups → route managed execution through `vegafactory children run`, then `vegafactory children join`, inside the active registered parent session and checkout; use `--help` for required arguments. Execution requires current authority, with integration authority checked separately at join. Preserve existing `.claude/workflows/implement-children.js` copies and user configuration: older copies may still contain their own executor; setup neither installs that legacy route nor migrates, overwrites or deletes existing copies
+- An always-on machine plus the ship guard wired → offer `dispatch: local` and, on that machine, `vegafactory service install`: the dispatcher turns `needs-plan`, unassigned `ready` and a 🚀 from a listed operator into headless runs, running as the operator's own user with their `gh` and harness authentication, and every repo stays refused until its own dev.md says `dispatch: local`
+- 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
+- Gitignored files a fresh checkout needs (`.env`) or a setup command detected → confirm `worktree-include:`, `commands: setup` and `worktree-retention:` (default 14d), replayed into every new worktree; nothing detected → `worktree-include: none`
+- No control room exists and the operator wants one → hand the request to `vegafactory-setup`, which bootstraps it; this skill never creates the org repository itself
+- Labels use `scripts/effective-policy.mjs`: defaults accept the complete space/CSV list with scope labels; custom names require five-key `workflow-labels` JSON. Preview semantic conversion; write only an accepted migration, preserving issues and board options. Both knobs must agree.
+- Different label names, `gates: 1` under branch protection (it blocks direct pushes — surface the conflict), or a different decision-register path, when the situation or the user brings it up
+
+Everything else — merge style, branch naming, the stop-and-ask list, the `architect:` owner (the detected username), `chronicle-style: plain`, and `emoji: none` — takes its documented default straight into dev.md, because the profile is plain text the user can edit anytime.
+
+## Step 3 — Write
+
+| Target | Action |
+|---|---|
+| `.vegastack/dev.md` | render [dev-profile template](assets/dev-profile.md.template) with the answers — the project's single canonical process doc (Ship/Verify/Environments/Design from the playbook, Architecture from detection, Decisions test included, placeholders deleted, TODO lines where machinery is absent; `architect:` and `operators:` from the detected username, `harnesses:` from Step 1's detection and `harness-policy:` from the confirmed Round C line, `chronicle-style` and `emoji` at their template defaults). dev.md is short directional bullets — one line per knob or rule — because every skill reads it on every run. The `control-room:` knob records the clone sha the profile was drafted from (`sync`'s `--json` `sha` field), so dev-status can show which knobs moved since |
+| `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>"` for validated semantic state names plus existing scope/modifier labels, skipping ones that exist; creation colors ([conventions](references/conventions.md) holds meanings): state `needs-operator` FBCA04 · `needs-plan` E36209 · `ready` 0E8A16 · `working` 1D76DB · `for-operator` 5319E7; modifiers `risky` B60205 · scope `research` C5DEF5 · `quick-build` 76C7C0 · `full-plan` 2A9D8F · `epic` 24292E (only when the org has no native Epic issue type) |
+| decision register | create the file the `decisions:` knob names (default `.vegastack/decisions.md`) when missing, with a two-line header stating conventions' register-line format (username via `gh api user -q .login`, fallback `git config user.name`); an existing register is kept and the knob points there |
+| project `.gitignore` | add `.vegastack/.worktrees/` when absent — every branch is checked out there ([conventions](references/conventions.md)), never as untracked files in the main checkout |
+| `.vegastack/hooks/session-end.mjs`, `skill-activated.mjs`, `prompt-skill-mention.mjs` | only on their own yes in Round C, wired to SessionEnd, Claude's `PostToolUse` matcher `Skill` and `UserPromptExpansion`, and Codex's `UserPromptSubmit`; SessionEnd uses the bounded managed-hook adapter with explicit harness and one-second timeout; copy its shared session-start.mjs sibling too. Skill hooks keep their existing stats record source; all exit 0 |
+| guard workflows / hook files | only the ones the user said yes to in Round C; a hook or dev.md section the control room's `templates/` overrides is taken from there and this skill's own asset is the fallback, because the org's template is a deliberate default and these are not; hook files (including session-start.mjs beside either advisory consumer) are copied verbatim from `assets/hooks/` (or the control room's override) to `.vegastack/hooks/`, the ship guard's policy is compiled with `node scripts/ship-policy.mjs --write` (outside the repo, in `~/.vegastack/guard/`), and the wiring goes to `.claude/settings.json` (Claude Code), `<repo>/.codex/hooks.json` (Codex) and `~/.hermes/config.yaml` (Hermes, ship guard only), merged never replaced |
+
+## Step 4 — Report
+
+One summary: what was created, what was skipped and why, what remains TODO, what the `issue-types:` and `issue-fields:` knobs ended up holding — and where either is `none`, one plain sentence saying issues here carry their labels and nothing else — what the drafted `harness-policy:` line ended up holding and which harnesses it names that the box does not have, and every gh feature the detected version lacks with the floor that unlocks it (on gh 2.92.0: "native issue types, sub-issues and dependencies need gh 2.94.0; name-based project field edits need gh 2.97.0"). With no App installation detected, say so — no automation identity yet, [github-app](references/github-app.md) is the path out. When `gh` was unauthenticated, print the exact `gh auth login` and `gh label create` commands to run later, and name the gap plainly.
+
+## Re-runs
+
+Re-running is how knobs get revisited and empty sections get filled: diff fresh detection against the existing dev.md, show what differs per target, and change only what the user confirms — propose the delta, because a reset discards the hand edits that made the profile true. The other dev skills send the user here when they notice an empty Ship/Verify section next to newly present machinery. The marked block is the only part of AGENTS.md this skill owns; hand edits inside dev.md win, and the templates are for creation.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "dev-setup"
+  short_description: "Bootstrap any repo, greenfield included, 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,24 @@
+<!-- vsk-dev:start -->
+## Dev workflow
+
+Read `.vegastack/dev.md` (stack, commands, knobs); if missing, run dev-setup first. The stages are the dev-family skills: dev-setup (bootstrap) · dev-intake (ideas to briefs) · dev-plan (approved briefs to plans) · dev-architect (stack judgment) · dev-implement (dark builds) · dev-debug (reproduce-first fixes) · dev-review (independent review) · dev-ship (gated landing) · dev-status (the operator's board) · dev-chronicle (the project's story).
+
+Work flows through GitHub issues, labeled per dev.md's `labels:` knob; artifact formats follow dev-setup's `references/conventions.md`. Route each request by kind:
+
+| Request | Skill |
+|---|---|
+| a new capability, feature, bug report, or SOW — in chat or as an unlabeled issue | dev-intake, which writes the issue and never builds |
+| a `needs-plan` issue | dev-plan |
+| a `ready` issue, a resume handover, or corrections on `for-operator` | dev-implement |
+| a trivial fix asked in chat — one or two files, no new dependency, no behaviour beyond the words | dev-implement's direct path |
+| "make the PR", "merge", "release" | dev-ship |
+| "status", "catch me up" | dev-status, dev-chronicle |
+
+**Local, reversible actions proceed; actions that are hard to reverse, affect shared systems, or are visible to others wait for the operator's word** — push to the default branch, merge, tag, publish, deploy, force-push, a hard reset, branch or worktree deletion, `--no-verify`; green checks, schedules, and standing approvals authorise none of them. The `gates:` knob in dev.md changes how many of those one instruction covers, never whether an instruction is needed. Behavior changes carry their changelog entry (dev.md's `changelog:` knob) before hand-back; after merge, dev.md's `## Ship` runbook says which steps need the operator's word.
+
+Agent conduct: say what you mean — when a literal phrase is available, use it. Lead with the outcome, for a reader who did not watch the work. Report progress only against a tool result from this session; say plainly what is unverified. Pause for the operator only for a destructive or irreversible action, a real scope change, or input only they can provide; then ask and end the turn instead of promising. The approved brief or plan is the scope; extras are a closing note. Edit files surgically rather than rewriting them whole.
+
+Directional decisions (`## Decisions` in dev.md says what qualifies) get one dated line in the register dev.md names: when a session settles such a choice, propose the line and add it only on the user's yes.
+
+dev.md is the project's self-maintained handbook: when a gotcha or repeated instruction surfaces, propose the one line that would have prevented it — folded into existing lines, never 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,102 @@
+# Dev profile — {{owner/repo}}
+
+This file is the project's handbook and its only process document: 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. A section left as TODO because its machinery didn't exist yet: re-run dev-setup detection when the machinery appears.
+
+repo: {{owner/repo}} · default branch {{branch}}
+policy-schema: 2
+stack: {{one line; the `## Architecture` section below carries the architecture facts}}
+commands: test `{{test}}` · build `{{build}}` · dev `{{dev}}` · setup `{{setup}}`
+authority: {{ordered — e.g. "CONTRIBUTING.md → this file → skill defaults"; delete the line when this file is the only process doc}}
+
+## Knobs
+
+review: cross-agent-risky   # subagent (never cross-agent) | cross-agent-risky (other agent on risky) | cross-agent (always) — dev-review maps these
+harnesses: {{claude <version> · codex <version> · hermes absent}}   # what dev-setup found on this box, one `<name> <version|absent>` entry per harness; a re-run refreshes it. An absent harness the policy below names is also recorded in ## Environments with the capability it gates
+harness-policy: intake {{intake-harness}} {{intake-model}} {{intake-effort}} · plan {{plan-harness}} {{plan-model}} {{plan-effort}} · implement {{implement-harness}} {{implement-model}} {{implement-effort}} · review {{review-harness}} {{review-model}} {{review-effort}} · status {{status-harness}} {{status-model}} {{status-effort}} · chronicle {{chronicle-harness}} {{chronicle-model}} {{chronicle-effort}}   # confirm detected supported subscription choices for every stage; placeholders block execution
+ui-evidence: playwright     # playwright | none
+evidence-repo: {{owner}}/dev-review-evidence   # shared across projects; this project's folder = repo name; delete the line when ui-evidence is none
+gates: 3                    # 3 = approve/PR/merge · 2 = approve + one "ship it" · 1 = direct-to-main, ship word merges locally and pushes, no PR
+tests: required             # required | logic-only | best-effort | none; an org lock governs allowed overrides
+skill-scan: none            # one line only — directory holding the agent skills to scan (the BUILT one where a bundle is generated) | none. the skill-scan skill's guard reads this and refuses if a second line gives a different value
+skillspector-update: auto   # off | notify | auto — how the SkillSpector CLI itself is kept current. auto installs it when absent and upgrades it before each scan, falling back to the installed copy on any failure; notify only reports what upstream has published; off never touches the network. one line only, same as above
+merge: squash
+branch: <type>/<issue>-<slug>   # type: feat | fix | docs | chore | refactor — the only place this list lives
+worktree-include: {{files}}   # space-separated gitignored files a fresh checkout needs (local env and secret files) | none — copied into every new worktree
+worktree-retention: 14d     # how long a parked worktree survives with no session, measured from the later of its last commit and its last ledger edit; prune pushes first and never removes uncommitted or unpushed work
+labels: needs-operator needs-plan ready working for-operator risky research quick-build full-plan epic   # epic label marks map parents only where the org has no native Epic issue type
+workflow-labels: {"needsOperator":"needs-operator","needsPlan":"needs-plan","ready":"ready","working":"working","forOperator":"for-operator"}   # custom names need explicit mapping; if labels: remains, both must agree
+board: none                 # project board number the five state labels mirror into, one way, or none — .github/workflows/factory-board.yml reads this line and a card dragged on the board is cosmetic until the next label change
+issue-types: {{Feature=feat · Bug=fix · Task=docs,chore,refactor,research | none}}   # native org issue types dev-setup detected; dev-intake sets one at creation. none = personal repo, or an org that defines none
+issue-fields: {{Priority=<options> default <option> · Effort=<options> default lowest for research/quick-build, middle for full-plan | none}}   # org issue fields dev-setup detected; dev-intake asks for both and writes them at creation. none = org defines none
+changelog: {{changesets | keep-a-changelog | pubspec+changelog | none (reason)}}
+decisions: .vegastack/decisions.md
+release: on-request         # per-merge = Ship runbook runs as part of shipping · on-request = only when the operator says "release"
+chronicle: on               # on = dev-implement writes a .vegastack/chronicle.md story entry per behavior-changing branch · off
+architect: {{github-username}}   # confirmed architecture owner from `gh api user -q .login`; a display/commit author is not identity authority
+control-room: {{org}}/vegafactory-control-room#{{group}}@{{sha7}}   # org control room · this repo's group · the clone sha this profile was drafted from; delete the line when the org has none
+sync-max-age: 30m           # confirmed maximum validated-policy age, not a task deadline; <n>s, <n>m or <n>h
+# stats: off               # a mandatory org lock needs an exact org delegation; refusal prevents capture/export even when the diagnostic effective value is on
+operators: {{github-username}}   # csv of the humans who own issues here — every state flip assigns per conventions' Labels table; dev-setup writes the detected login, and the line is edited to add people
+dispatch: off               # off | local; repo-only opt-in, current scoped approval and validated policy/guard required; invalid values refuse
+chronicle-style: plain      # plain | story | witty — the voice of chronicle entries; the rule and one worked example per style live in dev-chronicle's references/styles.md
+emoji: none                 # none | sparing — sparing allows at most one emoji per chronicle entry, in the title or footer, never inside a field's facts
+
+# provider-mode: subscription-only       # confirmed organization policy; no usage-billed fallback
+# learning: normal-work                  # normal-work | off; verified VegaFactory lessons, no built-in vendor memory
+# learning-adoption: scoped-reversible   # scoped-reversible | propose-only; never changes approval or quality/privacy authority
+
+## Ship — what happens after merge, in order
+
+Line prefixes: `auto:` (agent just does it) · `ask:` (operator's word first) · `guard:` (deterministic check run locally at this position, its runnable command inline on the line; the CI copy is the backstop).
+
+- {{playbook-drafted release steps for the detected stack}}
+- {{guard: lines from the playbook}}
+- {{post-release verification — how to see the release/deploy landed}}
+- {{rollback one-liner from the playbook}}
+- {{versioning policy in 1–2 bullets when the project has one; delete the section's placeholders — "Ship: merge only" is a valid runbook}}
+
+## Verify — how to see it working (pre-merge)
+
+- {{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}}
+- Ship-guard policy lines, one per deployable target: `- <target>: <auto|ask> — <command pattern>` — for example `- preview: auto — wrangler deploy --env preview` and `- production: ask — wrangler deploy --env production`. The pattern runs to the end of the line and is matched as a literal prefix of the resolved command (quotes, wrappers and a path on the first word stripped); the longest match wins; a deploy or publish command matching no line is asked. `.vegastack/hooks/ship-guard.mjs` never reads this file: `vegafactory guard sync` compiles these lines into `~/.vegastack/guard/<owner>__<repo>.json`, and until it runs every guarded command asks.
+
+## Design
+
+- {{pointers: design system / component rules / UI conventions}}
+
+## Architecture
+
+Facts dev-architect reads before advising — knobs, not prose. Decisions with rationale go
+to the register, never here. The repo wins on drift; dev-architect proposes the one-line
+fix. Delete this whole section for repos with no app architecture (pure tooling, docs, or
+content repos) — the `stack:` line at the top is enough.
+
+hosting: {{cloudflare-workers-opennext | self-managed-server | both | vercel (exception - say why)}}
+database: {{postgres via hyperdrive | postgres self-managed | d1 (recorded exception) | none}}
+auth: {{better-auth | none}}            # orgs plugin when multi-tenant
+storage: {{r2 | s3 | minio | none}}
+jobs: {{none | pg-boss}}
+agents: {{none | eve | ai-features}}    # ai-features = AI SDK calls only, no agent runtime
+stage: {{pre-launch | live}}            # pre-launch = delete-not-migrate applies
+kind: {{internal | client | oss}}
+mobile: {{no | flutter (separate repo)}}
+
+## Decisions
+
+Record a decision only when it is directional — it steers work beyond this issue: a real alternative was rejected; it constrains work not yet written; and no dev.md line, lint rule, or guard can enforce it instead (if one can, write the rule). Feature requests, one-off fixes, and routine implementation choices never qualify. Every entry needs the user's explicit yes. One line in the register (`decisions:` knob), append-only, no other metadata:
+
+- DD-MM-YYYY (github-username) — the decision
+
+## Stop and ask
+
+Pause for the operator only when the work genuinely requires them: a destructive or irreversible action, a real scope change, or input only they can provide — ask and end the turn rather than end on a promise. In this project that means: 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. Nothing ships without the operator's explicit instruction — see the AGENTS.md dev section.
+
+## Project rules
+
+- {{project-specific rules, one per line; delete this section if none}}