generate-spec-v2

# generate-spec-v2 Writes `courses/<name>/spec.md` from the course materials with guide v2.8 (`references/guide.md`). It is the same process the guide was validated with (clean-room generation, then builds, on three courses, 2026-10-23/24): 1. the pattern card, confirmed by the owner; 2. one clean-room generator; 3. the spec it writes, unedited, on a new pull request. Running it again on a course is how a spec is iterated: reconfirm or revise the card, then regenerate. ## Files | File | Read by | |---|---| | `references/guide.md` | the clean-room agents only, never the session running this skill | | `references/card-prompt.md` | the card-proposal agent (step 3a) | | `references/generation-prompt.md` | the generator agent (step 4) | | `courses/<name>/pattern.md` | the generator agent, and the owner at step 3 | Fill each prompt's slots before sending it, with absolute paths: - `{GUIDE}`: this skill's `references/guide.md`; - `{COURSE_DIR}`: the course folder; - `{OUT}`: the step's output file. Send the filled prompt exactly as it is; add nothing to it. ## Steps 1. **Check the folder.** Confirm that `materials/notebooks/` and `materials/transcripts/` exist in the current folder. If not, refuse: "Run /generate-spec-v2 from inside a course folder — `cd courses/<name>` first." If `--env` was passed, refuse: "Environment specs use /generate-spec --env=<slug>." Check with `ls` that materials exist; do not read them yet. 2. **Ask which model runs the clean-room agents.** Ask every time, with no default. Use the structured question tool if there is one. Options: opus, sonnet, fable, haiku. The answer is used for both step 3a and step 4. Say once that the guide was validated with opus only. 3. **The pattern card.** The owner confirms it before every generation. An unconfirmed card is never used, because a stale card passes its errors into the spec. a. **No `pattern.md` yet:** spawn a fresh general-purpose agent (never a fork) on the chosen model, with `references/card-prompt.md`. Set `{OUT}` = `<course>/pattern-proposed.md`. It writes a proposed card and stops. b. **Check every quote.** For each quote, in the proposal or in an existing `pattern.md`, grep `materials/` and confirm it is there and says what the item claims. A generator's reading of the course is a claim, not evidence. Report any quote that is missing or reads differently. c. **The owner decides each item, one at a time.** Show the item, its quotes, and whether the check in 3b passed. - You may suggest dropping or rewording an item, with the reason. - The card holds only the essence: what every build must keep, whatever the learner picks. A feature of the full program stays a rule of the recommended build, not a card item. - An item that would block an option the course does not show failing belongs off the card. - The owner's answer decides. With an existing `pattern.md`, the owner keeps, rewords or drops each item. - Separately, the owner decides which parts from other lessons are offered as questions. None is a valid answer, and the usual one. d. **Write `pattern.md`.** The first lines, in italics, record: - the date it was confirmed; - how it was drafted (agent and model); - each change, each marked "suggested by Claude (the orchestrator) and accepted by the owner" or "the owner's own edit". On a reconfirmation, add that day's date and any changes. Keep the format of the card itself: - the line "**The one kind of program:** …"; - "## What every build keeps"; - numbered items, each with its quotes; - "## Offered from other lessons", optional: one line per part, with the learner situation it serves. Absent or empty means none. 4. **Generate.** Spawn a fresh general-purpose agent (never a fork) on the chosen model, with `references/generation-prompt.md`. Set `{OUT}` = `<course>/spec-v2-draft.md`; git ignores that name, so a failed run leaves nothing tracked. - The agent reads only the guide, the card and the materials, writes the spec, and runs the guide's section 10 self-check itself. - Do not audit, check or edit the spec afterwards. The guide was validated on unedited generations. 5. **Open the pull request.** A rewrite of `spec.md` always goes on a new branch and a new pull request, never into an existing branch. ```bash git fetch origin main git worktree add -b spec/<name>-v2-<YYYYMMDD> <tmp-dir> origin/main cp spec-v2-draft.md <tmp-dir>/courses/<name>/spec.md cp pattern.md <tmp-dir>/courses/<name>/pattern.md ``` - Commit both files and push. - Open the pull request with `gh pr create`. The body names the model, the card's confirmation date and the guide version. - Remove the worktree. - If `courses/<name>/materials/` is not on `main` yet, stop and ask the owner which base branch to use. 6. **Report.** Give the owner: - the pull request link and the model used; - the generator's final report in full, unfiltered: the program and its stages, every question with its options, every candidate turned into a background note and why, and every place the guide or the card was unclear. Places where the guide was unclear are findings about the guide. List them; never change the guide here. ## Don't - Don't read `references/guide.md` into this session or summarize it to the agents. They read it themselves. - Don't let the agents read anything beyond what their prompt allows: no other spec, no `builds/`, `evals/`, `experiments/` or `docs/`, no git. - Don't edit the generated spec. A problem in it is a finding for the owner, fixed through the card or the guide and then a regeneration. - Don't change `references/guide.md` or either prompt from this skill.