build-handoff
Turn approved product, tech, toolchain and design definitions into a build-ready repository and a handoff for the coding agent, by orchestrating Matt Pocock's setup, to-spec and to-tickets skills - writes AGENTS.md (alongside Next.js's managed block) and CLAUDE.md, publishes a spec and tracer-bullet tickets on GitHub Issues, adds the human-only setup checklist, lands the docs on main, and gives the paste-ready Code-tab prompt with the Code-tab plugin and MCP setup. Handoff phase called by start-project or askmatt, or when the user explicitly asks for tickets or a Code-tab prompt.
- License 许可
- MIT
- 最近更新
- 2026-10-07
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- build-handoff
- description
- Turn approved product, tech, toolchain and design definitions into a build-ready repository and a handoff for the coding agent, by orchestrating Matt Pocock's setup, to-spec and to-tickets skills - writes AGENTS.md (alongside Next.js's managed block) and CLAUDE.md, publishes a spec and tracer-bullet tickets on GitHub Issues, adds the human-only setup checklist, lands the docs on main, and gives the paste-ready Code-tab prompt with the Code-tab plugin and MCP setup. Handoff phase called by start-project or askmatt, or when the user explicitly asks for tickets or a Code-tab prompt.
02 资源文件 2
- 参考文档references/agents-md-template.md8.4 KB
- 参考文档references/code-tab-prompt.md2.2 KB
03 SKILL.md 正文
Build Handoff
Planning happens in Cowork; building in the Code tab, which doesn't see this conversation. The repo must carry everything. Danish to the user, English in files. Invoke skills with the Skill tool (user-only and refused → read ../<name>/SKILL.md and follow it).
Order of play
- Instruction files first.
AGENTS.mdis the one project instruction file (Claude Code, Codex and Cursor all read it). Write ourproduct-studio:managedblock fromreferences/agents-md-template.md. If Next.js's<!-- BEGIN:nextjs-agent-rules -->block already exists, keep it untouched above ours; if it doesn't exist yet, don't fake its markers: the walking-skeleton ticket adds it. Update our block in place on later runs; never touch the user's own sections.CLAUDE.mdcontains@AGENTS.md(Next.js convention). If aCLAUDE.mdwith other content exists, move project rules intoAGENTS.mdand leaveCLAUDE.mdimporting it (tell the user in one line).
- Configure the repo once. If
docs/agents/issue-tracker.mdis missing, runproduct-studio:setup-matt-pocock-skillswith answers pre-filled for a one-word "ja": editAGENTS.md(the file carrying the rules;CLAUDE.mdonly imports it); tracker = GitHub Issues whenever the project will live on GitHub, even if this session can't reach GitHub yet; default triage labels; single-context. Setup owns the## Agent skillsblock; it goes inside our managed block. Create the labels now if this session has GitHub reach, otherwise addgh label create … --forcelines to the Code tab's step 0. - Toolchain outputs in place. Confirm
docs/toolchain.md,.mcp.json,.claude/settings.jsonfrom define-toolchain exist and match; if the toolchain phase is still running in the background, wait for it here. - Spec and tickets.
- Multi-session build (normal for a new project): run
product-studio:to-spec. You pick the test seams yourself (the user can't judge them) and state them in one line; the spec is always saved todocs/specs/YYYY-MM-DD-<feature>.md. Show a ≤10-bullet summary and wait for "godkendt" before it's published. Thenproduct-studio:to-tickets: tracer-bullet vertical slices with blocking edges, quizzed in plain Danish before publishing. Always include:- 00 Setup (human-only steps, step 5), labelled
ready-for-human, blocking everything. No Docker required: database tests run in thedb-testsCI job. Optional: a Docker-compatible runtime on the Mac (Docker Desktop or OrbStack; a 16 GB Mac recommended) for faster local runs in the Code tab. Supabase branching is optional (paid plan, about $0.013/hour per branch, outside the Spend Cap) and never replaces the CI test job. - 01 Walking skeleton: scaffold with
create-next-appin a temporary folder (it refuses a non-empty directory and writes its own AGENTS.md/CLAUDE.md), then merge it into the repo: keep Next's AGENTS.md block, keep our managed block after it, keepCLAUDE.md=@AGENTS.md, keep every doc. Thensupabase init(commitsupabase/config.toml;supabase startin thedb-testsjob needs it),supabase/tests/00000-supabase_test_helpers.sqlcopied from harden's assets, Supabase clients, auth, one real screen on a Vercel preview, CI green. Also:CONSTRAINTS.mdwritten withproduct-studio:constraint-driven-developmentusing our stack defaults as recommended answers (you fill them; the user decides only product, feel and money), plusscripts/floor-guard.mjsadapted from itsreferences/floor-guard.md; and a baseci.yml(lint, typecheck, test, build,semgrep scan --config p/default --error --metrics=offin thesemgrep/semgrepcontainer (skipped for dependabot), floor-guard withfetch-depth: 0, adb-testsjob (triggered onpull_requestand onpushtofeat/**; setup-cli →supabase start -x studio,imgproxy,vector,logflare,mailpit→supabase test db), Playwright report uploaded on failure) withdependabot.yml. - 02 Capture the design system: run impeccable
documentin scan mode now that code exists, turning the seedDESIGN.mdinto real tokens + Components +.impeccable/design.json, and wire the tokens into Tailwind/shadcn CSS variables perdocs/design/component-states.md.
- 00 Setup (human-only steps, step 5), labelled
- Small change (from askmatt): one ticket, labelled
size:boundedwhen it's an existing flow, one seam and no schema/RLS/auth change (build-ticket then skips the plan document), with acceptance criteria, including visual acceptance ("cards match DESIGN.md hover state"), the impeccable command to apply if the route came from a design critique, and, for data changes, "supabase-security-reviewer finds no blocker". Show before publishing. - Publishing. With GitHub reach: publish now (issues with native blocking links; label
ready-for-agent, except 00). Without: write the tickets as files indocs/specs/<feature>/tickets/NN-<slug>.md(Matt's local-ticket template) and let the Code tab publish them in its step 0.
- Multi-session build (normal for a new project): run
- Human-only steps (ticket 00): a numbered checklist with direct links and exact clicks: create the Supabase project in the chosen EU region; install the Vercel↔Supabase integration; import the GitHub repo in Vercel; enable Supabase's GitHub integration/branching if chosen; create a fine-grained GitHub token for this repo if the GitHub MCP is used; add the connectors from define-toolchain. Offer
product-studio:wizardonly if the user will run a script in their own terminal. When Vercel is linked, record the production URL and project name indocs/tech.md. - Commit, and get the docs onto
main. Before the first commit, make sure.gitignorecontains.worktrees/,.superpowers/,.claude/worktrees/,.claude/settings.local.jsonand.env*(except.env.example), so the first build worktree never has to commit a.gitignorefix onmain. Commit in the connected folder (no login needed). With GitHub reach, push: a new repo's first commit goes straight tomain; on an existing repo use branchdocs/<topic>, a PR, and merge after "godkendt". Without GitHub reach, the push is the Code tab's step 0. The build agent branches frommain, so docs land before any ticket starts. Append todocs/log.md. - The Code-tab prompt. One fenced block from
references/code-tab-prompt.md, including step 0 when this session couldn't do the remote parts. Below it, the one-time Code-tab setup fromdocs/toolchain.md:- Preferred: install product-studio in the Code tab too (the same plugin; see the README's "Code tab" section), so
build-ticket, the Superpowers execution skills,next-dev-loopand the review agents exist there. Then don't also installmattpocock-skills, thesuperpowersplugin itself (its SessionStart hook forces its methodology on every session), Addy'sagent-skills, or the vendor plugins whose skills we already bundle (duplicates compete); take their MCPs from the repo's.mcp.jsoninstead. - Optional, design-heavy builds:
/impeccable hooks onin the Code tab (writes to the git-ignored.claude/settings.local.json; suggesthook.quiet: true). Ask yes/no; default no. - If product-studio can't be installed there:
/plugin install mattpocock-skills@claude-plugins-officialand the vendor plugins the toolchain chose (e.g.vercel,supabase,typescript-lsp), and copy our three agents into the repo's.claude/agents/. - Either way:
security-guidance(always-on security checks), and "approve the project MCP servers when the Code tab asks".
- Preferred: install product-studio in the Code tab too (the same plugin; see the README's "Code tab" section), so
- Close the loop. The Code tab opens a PR per ticket; Vercel posts a preview URL;
/hardengives the independent verdict (in the Code tab, or from Cowork with/harden); only SHIP merges. Offer to add harden's CI gate as a required check once the first PR exists.
Done when
Everything is committed in the connected folder and either pushed to main or queued as the Code tab's step 0; the spec and tickets exist (GitHub or docs/specs/<feature>/tickets/); the user has the prompt and the setup lines.
04 同仓库更多 Skills
writing-skills
Use when creating new skills, editing existing skills, or verifying skills work before deployment [Superpowers; user-invoked. Use to write or pressure-test a skill, e.g. product-studio changes.]
writing-plans
Use when you have a spec or requirements for a multi-step task, before touching code [product-studio: canonical Code-tab execution, entered via build-ticket; user-invoked otherwise]
writing-for-agents
Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.
wizard
Generate an interactive bash wizard that walks a human through steps only they can perform. Use when provisioning infrastructure, setting up credentials or CI secrets, walking an unfamiliar third-party dashboard, or running a one-off migration or cutover. Don't invoke this for steps the agent can perform itself.
webapp-testing
Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs. [Python alternative to playwright-skill (canonical for scripted browser checks); user-invoked only.]
web-design-guidelines
Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices".