AGENT SKILL

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

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

  1. Instruction files first.
    • AGENTS.md is the one project instruction file (Claude Code, Codex and Cursor all read it). Write our product-studio:managed block from references/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.md contains @AGENTS.md (Next.js convention). If a CLAUDE.md with other content exists, move project rules into AGENTS.md and leave CLAUDE.md importing it (tell the user in one line).
  2. Configure the repo once. If docs/agents/issue-tracker.md is missing, run product-studio:setup-matt-pocock-skills with answers pre-filled for a one-word "ja": edit AGENTS.md (the file carrying the rules; CLAUDE.md only 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 skills block; it goes inside our managed block. Create the labels now if this session has GitHub reach, otherwise add gh label create … --force lines to the Code tab's step 0.
  3. Toolchain outputs in place. Confirm docs/toolchain.md, .mcp.json, .claude/settings.json from define-toolchain exist and match; if the toolchain phase is still running in the background, wait for it here.
  4. 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 to docs/specs/YYYY-MM-DD-<feature>.md. Show a ≤10-bullet summary and wait for "godkendt" before it's published. Then product-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 the db-tests CI 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-app in 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, keep CLAUDE.md = @AGENTS.md, keep every doc. Then supabase init (commit supabase/config.toml; supabase start in the db-tests job needs it), supabase/tests/00000-supabase_test_helpers.sql copied from harden's assets, Supabase clients, auth, one real screen on a Vercel preview, CI green. Also: CONSTRAINTS.md written with product-studio:constraint-driven-development using our stack defaults as recommended answers (you fill them; the user decides only product, feel and money), plus scripts/floor-guard.mjs adapted from its references/floor-guard.md; and a base ci.yml (lint, typecheck, test, build, semgrep scan --config p/default --error --metrics=off in the semgrep/semgrep container (skipped for dependabot), floor-guard with fetch-depth: 0, a db-tests job (triggered on pull_request and on push to feat/**; setup-cli → supabase start -x studio,imgproxy,vector,logflare,mailpit → supabase test db), Playwright report uploaded on failure) with dependabot.yml.
      • 02 Capture the design system: run impeccable document in scan mode now that code exists, turning the seed DESIGN.md into real tokens + Components + .impeccable/design.json, and wire the tokens into Tailwind/shadcn CSS variables per docs/design/component-states.md.
    • Small change (from askmatt): one ticket, labelled size:bounded when 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 in docs/specs/<feature>/tickets/NN-<slug>.md (Matt's local-ticket template) and let the Code tab publish them in its step 0.
  5. 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:wizard only if the user will run a script in their own terminal. When Vercel is linked, record the production URL and project name in docs/tech.md.
  6. Commit, and get the docs onto main. Before the first commit, make sure .gitignore contains .worktrees/, .superpowers/, .claude/worktrees/, .claude/settings.local.json and .env* (except .env.example), so the first build worktree never has to commit a .gitignore fix on main. Commit in the connected folder (no login needed). With GitHub reach, push: a new repo's first commit goes straight to main; on an existing repo use branch docs/<topic>, a PR, and merge after "godkendt". Without GitHub reach, the push is the Code tab's step 0. The build agent branches from main, so docs land before any ticket starts. Append to docs/log.md.
  7. 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 from docs/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-loop and the review agents exist there. Then don't also install mattpocock-skills, the superpowers plugin itself (its SessionStart hook forces its methodology on every session), Addy's agent-skills, or the vendor plugins whose skills we already bundle (duplicates compete); take their MCPs from the repo's .mcp.json instead.
    • Optional, design-heavy builds: /impeccable hooks on in the Code tab (writes to the git-ignored .claude/settings.local.json; suggest hook.quiet: true). Ask yes/no; default no.
    • If product-studio can't be installed there: /plugin install mattpocock-skills@claude-plugins-official and 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".
  8. Close the loop. The Code tab opens a PR per ticket; Vercel posts a preview URL; /harden gives 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

phillippasqualato
phillippasqualato/PAPcSetup

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.]

★ 0
phillippasqualato
phillippasqualato/PAPcSetup

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]

★ 0
phillippasqualato
phillippasqualato/PAPcSetup

writing-for-agents

Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.

★ 0
phillippasqualato
phillippasqualato/PAPcSetup

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.

★ 0
phillippasqualato
phillippasqualato/PAPcSetup

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.]

★ 0
phillippasqualato
phillippasqualato/PAPcSetup

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".

★ 0