deck-studio

deck-studio

A deck is a deck.yaml; the engine renders it. The craft lives in three places that do not depend on who is building that day: a brand stack (one token file every render reads), a block library with measured build gates, and a design team (art director, parallel designers, a cold critic) that learns taste from a reference library of approved and rejected work.

Everything runs through one CLI. $DS below means python3 <this skill>/scripts/deck.py. The user's work lives in a workspace, ~/deck-studio (or $DECK_STUDIO_HOME), never inside this skill folder.

Rules that hold on every run

1. Harvest before you write. No slide copy until the context step is done and written down with sources. Facts come from sources, never from you.
2. Nothing invented. Every customer name, logo and number traces to a source line in the deal brief or to library/proof.yaml with verified: true. The build enforces this for stat, case-study and practice slides; you enforce it everywhere else. An empty number slot is honest; an invented one is not.
3. Their words beat yours. Priorities and problems go on slides near verbatim from calls and emails.
4. Look at every render before showing it. The build measures fit and lint; you judge the idea. Open the PNGs.
5. Gates that need a person: brand sheet approval (setup), master deck approval (setup), deck review before it is pushed anywhere a buyer can see it, and any image spend over the daily image budget (default $5, DECK_STUDIO_IMAGE_BUDGET; the image command refuses past it).
6. One clean headline phrase, no trailing period, no em dashes, nothing under 14px. The build fails on these; do not look for a flag to skip them.

First run: set up (once per company)

Tell the user what setup will do and roughly how long (30-60 minutes, most of it automated), then run these in order. Detail for each step is in the reference named; read it when you reach that step.

1. Install and check. $DS doctor. If anything REQUIRED is missing, ask the user once, then run $DS setup (installs the Python packages and Chromium, creates the workspace, re-runs doctor). references/setup.md if it fails.
2. Harvest company context. Inventory every source you can reach and pull everything about the user's own company: site, positioning, existing decks, case studies, pricing, customer proof, ICP. references/context-harvest.md (Part 1: the source inventory, Part 2: company context).
3. Build the brand stack. $DS brand extract <their site> writes the evidence and a starter brand/brand.json. Look at the evidence, correct the starter, delete its _review key, $DS brand apply, open brand/sheet.png. Show the sheet and get an explicit yes. references/brand-stack.md.
4. Seed proof. Write every customer, logo and figure you found into library/proof.yaml with its source, verified: false. Ask the user to confirm which are verified and cleared for external use. Unconfirmed stays false.
5. Build the master deck. Rewrite decks/master/deck.yaml from the company context (the template is a skeleton), $DS build ~/deck-studio/decks/master, open review.png and then every slide, fix, show the user. Remove draft: true once they approve and every figure is verified. references/blocks.md.
6. Optional: Google Slides. references/push-to-slides.md. Without it the build's .pptx still works.

Each deal (about 20 minutes)

1. $DS new-deal <slug> --client-domain <their domain> (scaffolds the deck, the brief and their logo chip).
2. Harvest the deal. In parallel, one subagent per source: every call transcript, email thread, CRM record and note, shared doc and chat thread about this deal, plus web research on the company and each stakeholder. Each writes a sourced summary into decks/<slug>/context/. Then synthesize context/brief.md. references/context-harvest.md (Part 3). Ask the user only about what is still a gap.
3. Structure and copy. references/deal-deck-method.md: the running order, the "what we heard" slide from their words, which master slides to reuse and what to override. Give the key slides a notes: talk track from the brief; it becomes the speaker notes.
4. Custom graphics. For each idea that needs showing, not telling (usually one per workstream or proposed solution), run the design team. references/design-team.md. Run separate ideas in parallel.
5. Build and look. $DS build ~/deck-studio/decks/<slug>. Fix every FAIL; read every warn. Open review.png, then every PNG. Check product mockups against the vendor's real docs.
6. Review with the user. Show them review.png (or the PDF). Once they say yes, remove draft: true, rebuild, and deliver: the PDF or .pptx from the deck folder, or Google Slides with $DS push <deck> --new "<title>" (or --presentation-id <id>), then $DS verify <deck> --presentation-id <id>. Never push over a presentation id the user did not give you for this; look at it first. references/push-to-slides.md.

Everything else: ads, one-pagers, infographics, carousels, heroes, custom art

The design team makes every other kind of visual with the same brand, canon and gates. Pick the mode that matches the ask (references/design-team.md has the table; references/modes/<mode>.md is the craft for each):

The ask	Mode	You get
"a LinkedIn / Meta ad", "ad creative"	ad (or ad-linkedin, ad-meta)	one concept rendered at every placement, safe zones enforced
"a one-pager", "a leave-behind", "a PDF"	one-pager	vector PDF (Letter or A4) + page PNGs
"an infographic"	infographic	a data story at feed or long-form size
"a carousel", "a document post"	carousel	multi-page PDF + one PNG per page
"a hero image", "a banner", "custom art"	hero (or --formats WxH)	generated plate + exact type, cropped per format
"a graphic for this slide"	graphic	a 1600x900 piece shipped into the deck

The flow is the design-team loop: harvest the facts the piece needs (Part 3 of context-harvest if it is for a deal; company context otherwise), studio direct --mode <mode>, parallel designers, render, critic, iterate, show the user, then studio ship --export <dir> (or --deck-diagram for a slide).

Scope decides the message. Every piece is brand-level unless --deal <slug> (or --campaign <brief>) narrows it. A brand piece (ad, hero, one-pager, infographic, social, carousel, a graphic not tied to a deal) takes its message from the company's whole offer: the art director writes company/offer-map.json from company context (every offer line, the core marked, a source on each), and the direction records which lines the piece covers. Deal briefs and company/context/campaign-*.md never feed a brand piece. studio new refuses a brand piece that skips the core or cites a deal source; the critic judges "representative of the business" from the pixels; ship --export refuses a brand piece the critic did not clear. One deal's angle leading the brand ad set is the failure this exists to stop. Logos of other companies come from $DS logo <domain> (references/logos.md); never draw one. Generated imagery follows references/image-generation.md: the image model paints the scene, HTML sets every word and logo, spend is logged against a daily budget.

Learning (this is what makes it compound)

When the user approves a graphic or slide, add it to library/reference-library.md as a canon entry in their words. When they reject one, add an anti-example with their quote and the fix. A graphic that proves itself across deals gets promoted into the master deck. Do this in the same turn as the feedback.

Harness notes

• Subagents. The design team and the context harvest want parallel, independent agents: designers must not see each other's work, and the critic must never be one of the designers. In Claude Code use the Agent tool (one message, several calls). In Codex use subagents if enabled; otherwise run each role as a separate pass that starts from only its prompt file, and run the critic last from only the renders and the report.
• Seeing renders. Open PNGs with your image-reading tool. If your harness cannot view images, say so and ask the user to review the contact sheet.
• Models. Use the strongest model you have for the art director, the critic and client-facing designers.

Files

Path	What
scripts/deck.py	the CLI ($DS --help)
references/setup.md	install, workspace, doctor
references/context-harvest.md	source inventory, company context, deal context, web research
references/brand-stack.md	extract, decide, apply, approve
references/deal-deck-method.md	running order, copy rules, inheritance
references/blocks.md	every slide block and its keys
references/design-team.md	modes, art director, designers, critic, ship, export
references/modes/*.md	the craft and critic checklist for each mode
references/formats.md	every canvas: sizes, safe zones, text floors, file caps
references/image-generation.md	generated imagery: models, prompts, references, edits, one master to many formats
references/logos.md	other companies' logos: sources, forms, sizing, checks
references/push-to-slides.md	Google Slides push, verify, edit gate
assets/templates/	master deck, deal deck, brief, proof, reference library
assets/examples/diagrams/	two approved-bar example graphics, brand-neutral