dev-plan

Files (10)

• SKILL.md
• openai.yaml · agents/
• evals.json · evals/
• issue-58-brief.md · evals/files/
• plan-format.md · references/
• plan-lint.mjs · scripts/
• plan-overlapping-groups.md · tests/fixtures/
• plan-with-groups.md · tests/fixtures/
• trigger-queries.json · tests/fixtures/
• plan-lint.test.ts · tests/

SKILL.md (first lines)

# dev-plan

Advise: turn the approved brief into the plan the operator approves and dev-implement executes, against the repo as it is now.

The planning stage: an acked brief goes in, an acked plan comes out, and only then does code exist. A `medium` or `large` issue is planned in a separate session from intake, because code drifts between the brief ack and the build.

Nearest neighbors: `dev-intake` owns the brief and its ack — this skill owns the how; `dev-implement` executes what this produces, task by task.

## Every run

1. Read `.vegastack/dev.md`, then `vegafactory issue sync <n>` and read the files it lists. Run `vegafactory issue check <n> --for plan`: it confirms the `planning` label, the size, and a valid brief ack. Anything else at this door is either intake's inline request (below) or a misroute — say so.
2. **Re-ground before planning** — open the brief's touch points in the current code and verify the flow, names and shapes the plan builds on, because code drifts between approval and build. A claim that no longer matches reality goes back to the operator (`handback` comment, `waiting-on-operator`).
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** — two or three candidates with the trade-off that matters and one recommendation, because a single option is a decision dressed as a question.
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, because a brief gap absorbed into the plan is a decision the operator did not make.

Rounds go out by the ask route (`references/ask-route.md`); an issue-routed round stops the session at `waiting-on-operator` and the next run parses the reply before re-asking anything. 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

Give every task its stable `<issue>-T<n>` identity before approval. 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:

- Walk the brief section by section per plan-format's self-review — every requirement points at a task, names match across tasks, no banned placeholder.
- Tasks inside one issue run in order. For a `large` issue, the plan splits the work into small/medium sub-issues instead; each sub-issue's brief lists the files it touches, so siblings with no overlap (and no generated files, migrations, lockfiles or `package.json`) can run in parallel. A worker runs disjoint groups at the same time; without a declared group, siblings run one at a time.
- 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 and post empty, because dev-status reads a ticked box as progress.

## Labels and acks

Post a new plan with `vegafactory issue comment` and move the issue to `waiting-on-operator` (`vegafactory issue label <n> --state waiting-on-operator`), assigned to the operator. When the operator acks it — in the issue or in this session — record it with `vegafactory issue ack <n> --stage plan --by <login> --quote "<their words>" --source comment:<id>|session`; anything else they say is input to fold into the plan. Then confirm with `vegafactory issue check <n> --for implement`, move the issue to `queued` and unassign; 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 `small` issue that needs real design, a `medium` one that is actually several deliverables. Stop, post one `handback` comment proposing the new size or the epic split (parent map + sub-issues, each sized fresh), `waiting-on-operator`, assigned to the operator. A plan runs about one screen per task — Files, Interfaces, Steps — and 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 making it `small` with the brief's inline approach, and wait for the yes.

## Small-issue 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 ack covers both (`--stage plan`) — no `planning` stop, no second exchange. The re-grounding step collapses to what intake already read; the ratchet still applies.

From vegastack/vegafactory, MIT.

More from vegastack/vegafactory