The Punch Project Playbook
Every Punch website project, start to finish. What to collect, what skill to run, who owns it. One row per step. Highlighted rows are gates — stop, verify, sign off, then proceed.
Phase 0
Discovery & Strategy
Understand the client, lock the Big Idea, agree on the site shape.
| # | Step | Collect | Skill | Owner |
|---|---|---|---|---|
| 01 | Run kickoff + discovery interviews to understand the client's business, audience, voice, and goals. | Discovery questionnaire, meeting recording, existing brand materials, links to current site | — | PM + Strategist |
| 02 | First-pass the full internal creative brief from the discovery materials. | Kickoff notes, recording, client brand docs, competitor links | punch-content-brief |
Strategist |
| 03 | Generate three Big Idea / theme directions, each anchored on a distinct emotional truth. | Locked brief, Copy Brief in progress | punch-theme-taglines |
Strategist + Creative Strategist |
| 04 | Draft the sitemap from the audit, analytics, and content strategy. | Existing site audit, GA analytics, brief | punch-sitemap |
Strategist + Sr. Strategist |
| 05 | Abbreviate the brief into the client-portal version — the short, client-facing brief that goes into the project portal. | Full internal brief from step 02 | — | Strategist |
| G1 | Gate 1 — Client signs off on the abbreviated brief and the sitemap. The three Big Ideas pass to the design team for Creative Theme Design — they are not approved verbally; the client will pick among them visually at G2. | Abbreviated client brief, sitemap (presented). Three Big Ideas handed to design. | Pulse-check feedback artifact | PM + client |
Phase 1
Foundation
Build the project structure, ship the wireframe, design the homepage.
| # | Step | Collect | Skill | Owner |
|---|---|---|---|---|
| 06 | Scaffold the website project into _Website/ (brand, source, content, sandbox, assets). |
Client name, slug, project type, CMS target | punch-project-init |
PM |
| 07 | Decode any reference templates the project is emulating. | Reference URL + 4–6 screenshots per reference (screenshots required) | punch-webflow-decode |
Lead Designer |
| 08 | ∥ Parallel with step 09. Draft the homepage content first — Claude generates the first pass from the brief, sitemap row, and brand voice; strategist + copywriter refine into the locked homepage copy that step 12 will compose against. | Internal brief, sitemap, copy-brief.md, Big Idea direction |
punch-content-brief + punch-web-copywriter |
Strategist + Copywriter |
| 09 | ∥ Parallel with step 08. Design team creates three creative theme designs in Figma — one visualizing each Big Idea. Each theme is a real branded visual direction (palette, type, illustration approach, hero treatment), not a moodboard. This work happens in Figma, not Cowork — Cowork composition begins at step 12 (two homepage variations). | Three Big Ideas from G1, decoded references, punch-website master library + tokens (in Figma) |
Figma (Punch Master library) | Lead Designer + 2 designers |
| G2 | Gate 2 — Client picks one of three creative theme designs. The picked direction becomes the brand's visual spine for the rest of the project. | Three creative theme designs (presented as composed visual takes) | Pulse-check feedback artifact | PM + Lead Designer + client |
| 10 | Flesh out the chosen creative theme — every brand facet the project needs (full palette, type system, logo direction, illustration / photography style, motion direction, component treatment). This becomes the project's locked visual system. | Chosen theme from G2, decoded references, Copy Brief | — | Lead Designer + Strategist |
| 11 | Export tokens, text styles, components, and the client logo from the Figma fork into the build sandbox. | Figma fork with Punch Tokens populated + Brand Mark frame + components defined | punch-token-export + punch-component-export |
Lead Designer |
| 12 | Build two homepage variations in HTML using the fleshed-out theme + the locked homepage copy. The two variations differ in hero treatment — typically interactive vs traditional. Both fully functioning, real copy, real design system. | tokens.css, components.html, locked content/homepage.md, fleshed theme spec |
Direct Cowork compose + punch-page-polish |
Lead Designer + Designers |
| G3 | Gate 3 — Client picks one of two homepage variations. The picked hero treatment dictates the remaining site styles. | Two composed homepage variations (hosted, real copy) | Pulse-check feedback artifact | PM + Lead Designer + client |
| 13 | Polish the picked homepage — refine the visual decisions, lock interactions and motion. This is the foundational page every other page is shaped from. | Picked homepage variation from G3, client + internal feedback | punch-page-polish |
Lead Designer |
| 14 | Fill in brand/visual-direction.md with the locked visual system, mode (light/dark/mixed), palette rules, and idioms borrowed from decoded references. This becomes the spec every remaining page composes against. |
Picked homepage from step 13, fleshed theme from step 10, decoded reference files | — | Lead Designer + Strategist |
| 15 | Write content briefs for every remaining page in the sitemap — Claude drafts the first pass from sitemap + locked creative brief + brand voice + Big Idea direction; strategist + copywriter refine. Apply no-enhancement-rule.md — the renderer pours source verbatim, so trailing periods, eyebrow choices, and CTA wording are the writer's responsibility now, not the wireframe's. Apply the source-grounding rule (v0.7.5+): for any factual page (products, capabilities, technical detail, compliance), source material must be in source/ before the brief runs. The skill refuses to fabricate factual content and emits a visible MISSING SOURCE marker for any section that can't be grounded, plus auto-appends a chase-list entry to source/_missing.md. PM owns the source folder; strategist verifies it's populated for factual pages before invoking the skill. |
Sitemap, copy-brief.md, no-enhancement-rule.md, internal creative brief, Big Idea direction, populated source/ folder for factual pages |
punch-content-brief + punch-web-copywriter |
Strategist + Copywriter (PM owns source/) |
| 16 | Generate the content wireframe for the remaining pages — a fully functioning interactive newspaper-greyscale site (traditional centered nav with dropdowns, tabs, count-up, reveal-on-scroll, ARIA, AEO/SEO/UX best practices). Governed by wireframe-principles.md — source-fidelity rendering, eyebrow scarcity, light/dark theme toggle, canonical Punch Docs feedback splash on every page, multi-H1 allowance on index.html only. Auria-reference fidelity. Homepage already exists as designed HTML. Any MISSING SOURCE markers in the content briefs render as visible client-facing "Information needed" blocks in the wireframe — never silently filled. If a page still shows an "Information needed" block at Gate 4, the page can't ship until source lands; do not proceed to Phase 2 composition on that page. |
sitemap.yaml, all remaining content/*.md briefs (may contain MISSING SOURCE markers), brand/copy-brief.md, assets/logo.svg, wireframe-principles.md, no-enhancement-rule.md |
punch-wireframe |
Strategist or PM |
| G4 | Gate 4 — Client reads the remaining-pages wireframe end-to-end and signs off on copy + structure. Once locked, design composition of remaining pages can begin. | Hosted wireframe URL (remaining pages) | Pulse-check feedback artifact | PM + client |
Phase 2
Expansion
Build the showcase pages, amplify the standards, pilot the CMS.
| # | Step | Collect | Skill | Owner |
|---|---|---|---|---|
| 17 | Compose every other showcase page (the 20% that earn the budget) in Cowork. | Per-page content briefs (locked at G4), visual-direction.md, components | Direct Cowork compose + punch-page-polish |
Lead Designer |
| 18 | Amplify the standard 80% pages from the homepage + sitemap. | Finished homepage, sitemap, site-llm summary including blog content | /website-design-amplifier:amplify (Claude Code) |
Production Artist |
| 19 | Lead Designer audits the amplified pages for design quality — visual rhythm, hierarchy, type usage, alignment with the showcase pages, idiom consistency. Amplified pages don't advance until the Lead Designer signs off on design. Findings go back to the Production Artist as a fix list. | Amplified output, finished homepage + showcase pages (as the reference) | design:design-critique + Lead Designer's eye |
Lead Designer |
| 20 | Pilot one page through the chosen CMS to de-risk the migration path. This is a sandboxed feasibility test, not production migration — full migration is blocked behind Gate 6. | CMS instance (WordPress, HubSpot, Punch CMS, etc.), one piloted page | /website-to-static:convert (Claude Code) + CMS-specific tooling |
Dev |
| 21 | Run self-QA on every amplified or composed page BEFORE handing to TDM. (Designer-audit fixes from step 19 must be applied first.) | Amplified output + composed showcase pages (post-designer-audit) | punch-production-artist-qa (auto-calls copy-lint + link-check) |
Production Artist |
| G5 | Gate 5 — TDM runs per-batch QA and confirms each batch is brand-consistent, breakpoints solid, copy clean, assets correctly placed. | Artist-cleaned pages | punch-copy-lint + punch-link-check + punch-asset-audit |
TDM |
| 22 | Lead Designer creates the project's rich visual layer for the whole site — original hero treatments, custom illustrations, photography curation/direction, motion + video + GIF moments. Assets flow into the showcase and amplified pages, elevating them from competent to distinctive. This is the creative work the automation frees up the Lead Designer's time for. Output becomes part of The Build the client reviews at G6. | The Build at structural completion (post-G5), fleshed theme spec, brand voice, decoded references, asset library / stock / commissioned photography | — | Lead Designer |
| G6 | Gate 6 — Client signs off on The Build (the complete designed website hosted as functioning HTML, with the Lead Designer's rich visual layer applied). Run the pre-launch QA orchestrator on the static Build first (QA pass #1) so the client reviews a clean build. CMS migration cannot begin until this gate passes. Client walks through The Build end-to-end; sign-off is captured in writing. | Hosted Build URL, full sitemap walked, all showcase + standard pages reviewable | punch-pre-launch-qa (static pass) + pulse-check artifact |
PM + TDM + client |
Phase 3
Ship
Migrate to CMS, optimize, run the pre-launch orchestrator, launch, verify.
| # | Step | Collect | Skill | Owner |
|---|---|---|---|---|
| 23 | Migrate every page from the static sandbox into the chosen CMS. Source of truth: the signed-off Build from G6. | Signed-off Build (G6), CMS content model | CMS-specific tooling (Dev's stack) | Dev |
| 24 | Apply CMS-format content polish (typography fine-tunes, image handling, CMS-specific copy edits). | Migrated CMS pages | punch-copy-lint (re-run on CMS-format) |
Production Artist |
| 25 | Run SEO + AEO pass — meta tags, JSON-LD, direct-answer paragraphs, sitemap.xml, robots.txt, 301 redirects. | Keyword strategy, redirect map from old site | (punch-seo-aeo-check when built) + manual audit |
TDM + Strategist + Dev |
| 26 | Run accessibility + performance audits and fix what's flagged. | Live preview URL | design:accessibility-review + Lighthouse |
TDM + Dev |
| G7 | Gate 7 — TDM re-runs the comprehensive Pre-Launch QA orchestrator against the CMS-migrated site (QA pass #2 — the first ran on the static Build before G6, this one catches anything migration introduced); zero BLOCKERS or launch is blocked. | Full project state (assets-manifest populated, sitemap final, pages composed, CMS migration complete) | punch-pre-launch-qa (orchestrator runs all sub-skills) |
TDM |
| 27 | Deliver client training (live 60–90 min session, recorded, plus PDF training guide for the actual CMS). | CMS client access, training agenda, training guide template | — | TDM + PM |
| G8 | Gate 8 — Launch. DNS cut over, redirects live, analytics confirmed firing. | TDM sign-off, DNS access, analytics tag | — | PM + TDM + Dev |
| G9 | Gate 9 — Within 48 hours, re-run pre-launch QA against production URL; verify all integrations + analytics + forms working end-to-end. | Live production URL, analytics dashboard, form submission test | punch-pre-launch-qa (re-run on production) |
PM + TDM |
| 37 | Run the project retrospective — what fired, what didn't, what terminology drifted, what should become a rule. 20 minutes max, fixed agenda. Findings feed the next refresher and the rule files. | Project folder, Asana template, terminology.yaml, last refresher | punch-retrospective |
PM (facilitator) + Lead Designer + Strategist |
Continuous / anytime skills
A few skills don't map to a single step — they run in the background or get invoked anytime a condition is met. Don't wait for a row to tell you to use them.
| Skill | When it fires | Source / input | Owner |
|---|---|---|---|
punch-term-drift |
Anytime — catches stale terminology against the canonical glossary. Runs every time a doc or brief is touched. | terminology.yaml |
All — flagged drift lands in #punch-process |
punch-copy-lint |
Anytime during wireframe or composition — auto-catches double spaces, comment leaks, placeholder text, banned hype words, smart-quote inconsistency. Also runs at Gate 5. | HTML in sandbox/ + briefs in content/ |
Strategist or PM |
Legend
- Skill
- The Cowork (
punch-*,design:*) or Claude Code (/website-*) skill to invoke at that step. "—" means no skill applies; this is human work. - Owner
- The single person accountable for that step. May coordinate with others, but ONE name signs off.
- Gate row
- Highlighted rows (G1–G9) are decision points. Stop, verify, sign off in writing, then proceed. Don't push work through a failed gate. Gates G1, G2, G3, G4, G6, and G8 require client sign-off — the rest are internal Punch sign-offs.
- Direct Cowork
- When the skill column says "Direct Cowork compose call," you don't trigger a named skill — you direct Cowork conversationally against the project files. The pattern is:
"Build [page] in sandbox/[file].html. Apply visual-direction.md. Use [components]."
Files humans write by hand
Skills scaffold and first-pass most files, but several require real human authoring or refinement. Don't let a skill's stub stand as the final version — the human owner is the one signing off on content.
| File | What goes in it | How it gets started | Owner (refines + signs off) |
|---|---|---|---|
brand/copy-brief.md (the Copy Brief) |
Big Idea + audience + brand personality + voice characteristics (3–5 adjectives) + banned and preferred words + wording / term preferences + punctuation rules + tone-by-context + CTA strategy by page type + reference quotes | Stubbed by punch-project-init from the canonical template; strategist fills out by hand and refines through the project |
Strategist |
brand/theme-notes.md |
Chosen creative theme: name, palette direction, typography personality, photography/illustration direction, motion direction, reference inspiration | Stubbed by punch-project-init; filled by hand from the picked theme |
Lead Designer + Strategist |
brand/visual-direction.md |
Overall character (1 paragraph), site mode (light/dark/mixed) + per-section breakdown, logo treatment, specific idioms borrowed (and NOT borrowed) from decoded references, palette/surface/typography rules | Stubbed by punch-project-init; filled by hand citing decoded references |
Lead Designer + Strategist |
content/sitemap.yaml |
Every page on the site: url, title, page_type, tier (showcase / standard), brief filename, plus footer pages | Drafted by punch-sitemap, then refined by hand |
Strategist |
content/homepage.md |
Homepage content brief: hero (eyebrow, headline, subhead, CTA), intro, feature sections, integration grid, stat strip, compliance, quote, CTA, footer — actual prose, not placeholders | First-pass drafted by punch-web-copywriter, then heavily refined by hand |
Copywriter + Strategist |
content/[every other page].md |
One brief per page in the sitemap (product, use case, about, demo, etc.) — same schema as homepage.md, scoped to that page's content | First-pass drafted by punch-web-copywriter, then refined by hand |
Copywriter + Strategist |
content/assets-manifest.yaml |
Map of every asset (image, video, logo, icon) to the page + section where it belongs, plus alt text and source notes | Stubbed by punch-project-init; filled by hand as assets land |
Lead Designer + PM |
Everything else in the project folder (tokens.css, text-styles.css, components.html, logo.svg, the wireframe HTML, the composed page HTML) is generated by skills or by Cowork composition. Don't hand-edit those — re-run the skill that produces them, or update the upstream source (Figma fork, content brief) and let the skill regenerate.
If a gate fails, don't push the work through and "fix in next phase." Fix it in place, re-run the gate. The agency death spiral is what happens when Phase 3 becomes "fix everything Phase 1 missed." Recent post-mortems are reminders of the cost.
If a skill isn't in your Cowork, the plugin is stale. Install the latest
punch-website plugin (currently v0.7.1). Ask Cowork "what Punch skills are available?" to confirm — should be 17 skills.
Brand projects (no website) stop at G2 — chosen creative theme. Phase 0 is identical. Phase 1 stops once the theme is fleshed out (step 10); steps 12 onward (homepage variations, wireframe, composition, asset creation, CMS) don't apply. Phase 2–3 become collateral and template work. The brand-only playbook lives separately.
Production Artists and Dev work in Claude Code. Everyone else works in Cowork. The two surfaces aren't interchangeable. If you find yourself wanting to open the other tool, you're probably reaching for the wrong one for your role.
Related docs. Onboarding (first-read for new hires): Designer · Strategist · PM. Re-entry for the existing team: What's New at Punch (ongoing changelog) · Quarterly Refresher. Rule files referenced by this playbook:
wireframe-principles.md · no-enhancement-rule.md · wireframe-copy-and-seo-rules.md · terminology.yaml.