dev-setup

Files (23)

• SKILL.md
• openai.yaml · agents/
• agents-section.md.template · assets/
• dev-profile.md.template · assets/
• factory-board.yml.template · assets/
• evals.json · evals/
• ask-route.md · references/
• conventions.md · references/
• github-app.md · references/
• harness-facts.md · references/
• stack-playbooks.md · references/
• effective-policy.mjs · scripts/
• questions.mjs · scripts/
• effective-policy.test.ts · tests/
• factory-board.test.ts · tests/
• dev.md · tests/fixtures/control-room/
• group.md · tests/fixtures/control-room/groups/dev/
• org.md · tests/fixtures/control-room/
• trigger-queries.json · tests/fixtures/
• gitignore.test.ts · tests/
• labels.test.ts · tests/
• questions.test.ts · tests/
• snippets.test.ts · tests/

SKILL.md (first lines)

# 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 | [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` to refresh the copy, then `vegafactory sync profile --json` for the answer: it returns the resolved `values`, the `sources` naming which layer each came from, the org's `locked` lines, and `blocks`. Read the profile from that command and never by opening files in the copy — the command is what checks the copy is the one the record describes, and a file read around it is a file read around every one of those checks. On a repo with no `control-room:` knob yet, the first run here, pass the org from the repo lookup above to `sync` (`--org`), because `sync` otherwise reads the knob this skill has not written. Skills read the copy, never the network, so an outage degrades to a stale answer instead of failing; a control room that answers a knob removes that question from Round B; a non-empty `blocks`, or no room at all, 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` — the names feed the Round C label migration, which is the only thing that removes a label |
| 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` and each present one's `--version` — the names and versions become the `harnesses:` knob line, and the AGENTS.md block, the CLAUDE.md import and the hook offer 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-tool review is off and reviews fall back to a labelled same-tool self-review), naming no install command, because the vendor's own docs own that |
| VegaFactory CLI | nothing to detect — session hooks and workers read `vegafactory-update:`; confirm the drafted value instead (`auto` updates the global CLI in the background, `notify` only reports, `off` makes no registry check) |

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 ([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. Nothing to choose for review: `vegafactory review` always runs the other tool. Detection found only one harness on the box → say plainly that cross-tool review is off until the other one is installed and that reviews fall back to a labelled same-tool self-review; record the gap in `## Environments`. 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. Tests: **required for every change** · required for logic changes only
4. Who may be assigned issues here (`operators:` knob): **just you** (the detected login) · a csv of logins — every human who can receive a `waiting-on-operator` or `ready-to-ship` 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
- 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 — `<stage> <agent> default|<model id> <effort>`, six fixed stages, `default` in the model position (the recommended value: the tool's own model, nothing to go stale) and the effort the operator wants; the flags each value turns into are in [harness-facts](references/harness-facts.md). A pinned model id the account cannot use fails loudly on the first run, and the fix is this knob line, never a skill edit
- Hooks → offer them as one set, on one yes, per [harness-facts](references/harness-facts.md): every event runs `vegafactory hook <event> --harness <h>` — the ship guard (asks before the always-ask commands and the backticked commands on the `## Ship` section's `ask:` lines), session context, the claim heartbeat and a WIP commit each turn. A deploy that needs the operator's word goes on an `ask:` line with its command in backticks. Merge into both config layers, preserving user hooks and removing this package's old `.vegastack/hooks/` entries. Codex needs the project's `.codex/` layer trusted per worktree — say so before wiring.
- 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
- Existing repo whose labels predate this workflow → show the migration before touching anything. `planLabelMigration` in [effective-policy](scripts/effective-policy.mjs) takes the repo's label names, its open issues with their labels, the board's Status options **and its items**, plus the existing `.vegastack/dev.md` text, and returns the steps in the order they must run. **Deleting a label or a board option takes it off every issue or card that has it**, so nothing is deleted until its replacement is in place:
  1. `rename` — the replacement name is free, so the label is renamed in place (`gh label edit`) and every issue keeps it, history included. This is most of the list.
  2. `transfer` — the replacement already exists, so each named issue gets the new label added before the old one is deleted.
  3. `create` — the labels no old name maps to.
  4. `board.rename`, `board.transfer`, `board.create` — Status options move with the states; where the board already carries both names, the named cards move to the replacement first.
  5. **The deletions, last** — the plan's two removal lists name the transferred labels and board options, and only at this point is anything deleted.
  6. `dropKnob` — the migration's last step: delete the `workflow-labels:` line, once nothing depends on the names it holds.

  **A repo that renamed its labels through the removed `workflow-labels` knob calls them anything at all**, so that line is read once, as migration input: its five semantic keys give this repo's own name for each state, and those names are migrated like any other. They are never written back — after the migration `labels:` carries the fixed set and the knob line is gone. A `labels:` line still naming an old label, or a leftover `workflow-labels:` or `gates:` line, blocks the profile until then, and the block says so.

  Show `rename`, `transfer`, `create`, `board` and `keep` before acting; `keep` is the project's own labels, which the migration never touches. Act only on the user's yes; a no leaves the repo exactly as it was and the report says the workflow cannot resolve a state until the set exists
- 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 sha of the copy 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 `waiting-on-operator` FBCA04 · `planning` E36209 · `queued` 0E8A16 · `in-progress` 1D76DB · `ready-to-ship` 5319E7; flags `risky` B60205 · `epic` 24292E (only when the org has no native Epic issue type); sizes `small` C2E0C6 · `medium` 76C7C0 · `large` 2A9D8F · `research` C5DEF5 |
| 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/.tmp/` and `.vegastack/.worktrees/`, each when absent — branches are checked out in one and drafts, the issue cache and the lessons queue are written in the other ([conventions](references/conventions.md)); without both lines the turn checkpoint commits and pushes them |
| guard workflows / hook wiring | only the ones the user said yes to in Round C; the hook wiring from [harness-facts](references/harness-facts.md) goes to `.claude/settings.json` (Claude Code) and `<repo>/.codex/hooks.json` (Codex), 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.

From vegastack/vegafactory, MIT.

More from vegastack/vegafactory