Setup Dream Team

---
name: setup-dream-team
description: >-
  Checks a project against the dream-team flow, applies fixes that change no code after one
  OK, commits its doc edits and files one maintenance issue for the other failing checks. Use when
  the user asks to set up, audit or align a project with the dream-team flow. Not for working an
  issue (use dream-fixer) or closing a milestone (use milestone-close).
disable-model-invocation: true
---

# setup-dream-team

Bringing a project into line is a program, not a change. This skill audits, makes the
**Direct fixes** below after one confirm, commits its doc edits and files one issue for the rest.
It changes no code; the filed issue goes through `dream-fixer`.

## Checks

- Each open milestone is numbered `M<n>`, or `YY.MM` for a version milestone (`v<major>.<minor>`
  in a SemVer repo past 1.0).
- Each milestone has a measurable exit criterion in its tracker description.
- The project `CLAUDE.md` says `Version milestones release in flow mode.` → a version
  milestone's `Exit:` naming its due date and a target headline is its exit criterion.
- A ROADMAP exists, two or more `M<n>` milestones are open, or a `Depends on:` names an open
  `M<n>` milestone → each open `M<n>` milestone has a matching ROADMAP row.
- Each ROADMAP row is a tracker milestone, or has status `planned`, no `#` and no tracker
  milestone.
- A ROADMAP with a dependency graph or a `planned` row → the graph has one node per `M<n>` or
  `planned` row and one edge per row's `Depends on:` entry.
- A milestone gated on field evidence has one open `Evidence:` issue.
- Every open issue has a `type::` label and an `area::` label.
- Every open issue has a milestone, or no milestone and the waiting or blocked label (parked).
- Each milestone description lists `Exit:`, `Gate:` and `Depends on:` as bold bullets.
- An open issue in a milestone carries the waiting label exactly when its milestone has an open
  dependency.
- Every open issue runs problem, proposal, per `scope-issue`, or the older context, problem,
  proposal.
- A `Meta:` issue has no `area::` label and no milestone.
- An issue with an open blocker ends with one `Blocked by #<n>` line per blocker.
- `docs/specs/` holds only specs the code still follows; every other spec carries a
  `Superseded by` line.
- A component table, if the contributor doc has one, matches the code.
- A component table cell says only what the component's name and path don't.
- The architecture diagram matches the code.
- The tracker has the `type::research` and `type::meta` labels.
- Every label in **Label colours** that the tracker has carries its colour from there.
- The project `CLAUDE.md` carries the meaning of every rule in **Project rules** below.
- A CHANGELOG's header links the Keep a Changelog version it follows.

## Project rules

The project `CLAUDE.md` carries these, in its own words:

- The architecture diagram changes in the same MR as a component or pipeline change.
- Detail the code doesn't show goes in the commit, spec or a topic doc, never in module docs.
- A fact the code and paths don't show has one reference doc, updated in the MR that changes it.
- A project with a ROADMAP: its status changes only at milestone close.
- A project with ratchet floors: they rise in the feature MR that earns them.
- A project with a CHANGELOG: each entry is one plain sentence on a notable change, with no
  rationale.
- A CHANGELOG entry has no bold except a `**Breaking:**` or `**Upgrade note:**` prefix.
- A project with open milestones: a new milestone takes only the forms the open milestones
  use: `M<n>`, `YY.MM` for a version milestone, or `v<major>.<minor>` in a SemVer repo past 1.0.
- A project with open `M<n>` milestones: a split takes the next free `M<n>`, never a letter.
- A project whose version milestones release at their due date: the line
  `Version milestones release in flow mode.`, verbatim.
- The contributor doc path is named.

## Label colours

Values from GitLab's label-picker palette; one colour per `type::` value, one for every `area::`.

| Label | Colour | Description |
|---|---|---|
| `type::bug` | `#D9534F` | |
| `type::feature` | `#44AD8E` | |
| `type::maintenance` | `#5BC0DE` | |
| `type::performance` | `#AD4363` | Throughput, CPU, memory or latency work, measured before and after |
| `type::meta` | `#8E44AD` | A `Meta:` checklist of child issues |
| `type::research` | `#F0AD4E` | Research with questions; a findings comment and follow-up issues, no code |
| `area::*` | `#428BCA` | |
| Blocked label (`workflow::blocked` on GitLab) | `#34495E` | |
| Waiting label (`workflow::future` on GitLab) | `#7F8C8D` | |

## Direct fixes

- `CLAUDE.md` lacks a project rule → write it in the file's own words, merged into its existing
  structure.
- The project has neither `CLAUDE.md` nor `AGENTS.md` → create `CLAUDE.md` with the project
  rules.
- The tracker lacks `type::research` or `type::meta` → create the label with its colour and
  description from **Label colours**.
- A label in **Label colours** has another colour → set its colour from there.
- A milestone description has its exit criterion, gate and dependencies, but not as bold bullets
  → rewrite them as `Exit:`, `Gate:` and `Depends on:` bold bullets.
- An issue lacks the `Blocked by #<n>` line for an open blocker → append one line per missing
  blocker.
- An open issue in a milestone carries the waiting label without an open milestone dependency,
  or lacks it with one → add or remove the label.
- The check that every open issue runs problem, proposal fails → an item in the maintenance issue
  (step 13), never a rewrite.
- Any other failing check whose fix changes no code and the draft can state, tracker edits and
  repo docs included → a direct fix, shown in the step 7 draft.
- A failing check that needs a code change, or a decision the draft cannot state such as a missing
  exit criterion → an item in the maintenance issue (step 13).

## Steps

1. Read the project `CLAUDE.md` or `AGENTS.md`, the contributor doc, the ROADMAP and `docs/specs/`.
2. Read the tracker's milestones, labels and open issues through the host's tooling skill.
3. Run every check. Record pass or fail, with the evidence: issue numbers, file and line.
4. Report one line per check to the user before changing or filing anything.
5. All checks pass → say the project is aligned and stop.
6. No direct fix applies → go to step 12.
7. Show one combined draft of every direct fix: the `CLAUDE.md` and repo-doc diffs, the labels to
   create or recolour, the labels and milestone to change per issue, each milestone title,
   milestone description and issue body before and after, and any issue or milestone to create.
8. Ask for one OK on the draft; a direct fix the user declines becomes an item in the
   maintenance issue.
9. Any approved `CLAUDE.md` or repo-doc edit → write them and commit only those files, in one
   commit per `scope-commit`, on the current branch, not pushed.
   - On `main` or `master` with a spec or design doc among those edits → run
     `git checkout -b <topic>` first and name the branch in the report.
10. Make the tracker changes through the host's tooling skill.
11. No failing check is left for the maintenance issue → report the fixes and any commit, and
    stop.
12. Ask which milestone takes the maintenance issue, suggesting one.
13. File one `type::maintenance` issue per `scope-issue`, in that milestone, with one item per
    remaining failing check.
14. A check that fails on many items → one item listing them.
15. Report the fixes, any commit and the filed issue. It is worked through `dream-fixer`.