Oliver/banner_studio
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
banner_studio/README.md
Simeon Schecter 988a47c797 Initial commit: Day 1 + Day 2 of the vertical slice 
Day 1 (monorepo + Node layout engine):
- Turborepo + pnpm workspaces with apps/web, apps/render-worker, and
  packages for types, layout-engine, prompts, api-lib.
- @banner-studio/types: BannerSpec contract, every layer kind, ResolvedLayer,
  zod schemas mirroring each interface.
- @banner-studio/layout-engine: Dropflow WASM wrapper, text measurement,
  shrink-to-fit, push_siblings, resolveLayout. Snapshot-tested.

Day 2 (browser parity + AI pipeline):
- Layout engine ./browser subpath: same resolveLayout in the browser via
  Dropflow WASM build. Quarantined wasm-locator import (dropflow 0.5.1
  exports gap).
- Cross-group push_siblings bug fix: deltas now thread through group
  recursion via a shared accumulator; regression test added.
- DEMO_TEMPLATE_300x250 promoted to packages/layout-engine/src/templates/.
- @banner-studio/prompts: versioned extract + generate prompts with
  zod-defined tool schemas (claude-sonnet-4-6, forced tool-use).
- @banner-studio/api-lib: CSV feed loader, extract/generate/route-node/
  assemble agents, orchestrator returning fully-resolved BannerSpec.
  Generate agent retries on character-limit overflow.
- apps/web (Next.js 14 App Router): /api/generate route, /parity diff page,
  promise-singleton browser engine init.
- feeds/demo.csv with five hand-authored rows of varied length.
- SLICE_DEVIATIONS.md documents the five intentional gaps from
  ARCHITECTURE.md with V1 reversal paths.

Verified end-to-end: POST /api/generate against the live Claude API
returns three resolved BannerSpecs and two honestly-skipped rows
(overflow after two attempts). 26 unit + integration tests passing.
2026-05-15 10:25:21 -04:00

2.7 KiB
Raw Permalink Blame History

Banner Studio — Claude Code Briefing Bundle

This bundle contains everything needed to begin building the agentic HTML5 banner production platform with Claude Code, plus an executive summary for non-engineering audiences.

What's in here

For Claude Code (drop these in the project root):

  • CLAUDE.md — Read on every session. Locked decisions, conventions, what not to do. The operational source of truth.
  • PROJECT_STRUCTURE.md — Monorepo layout, package by package, file by file. Use as the scaffolding target.
  • PHASE_1_BRIEF.md — Step-by-step prompts for the first week of work. Foundation phase, no UI yet.
  • BUILD_SEQUENCE.md — All 14 phases with exit criteria. Expand each phase into Claude Code prompts as you reach it.
  • ARCHITECTURE.md — The full architecture spec (the document you authored). Source of truth for data shapes, algorithms, and rationale.
  • RESEARCH.md — Research backing the locked decisions. Reference for the "why" behind stack and pattern choices.

For leadership and stakeholder decks:

  • EXECUTIVE_SUMMARY.md — Plain-prose briefing. The PPT source document. Sections map naturally to slides.

How to start

  1. Create the project repo. Copy CLAUDE.md, PROJECT_STRUCTURE.md, PHASE_1_BRIEF.md, BUILD_SEQUENCE.md, ARCHITECTURE.md, and RESEARCH.md into the root.

  2. Open Claude Code in that directory.

  3. First prompt:

    Read CLAUDE.md, then PHASE_1_BRIEF.md. We are at Step 1.1. Begin.

  4. Work through Phase 1 step by step. Do not skip the unit tests on the layout engine. Do not skip Step 1.9 (the type-safety proof) — it confirms the contract chain works before you build anything substantial on top of it.

  5. At Phase 1 exit, tag v0.1.0-foundation and start Phase 2.

A note on the documents

CLAUDE.md is intentionally opinionated. It states what is locked, what is forbidden, and where to look for the why. This is the right shape for a Claude Code briefing — it tells the model what decisions have already been made so it doesn't waste context re-deriving them, and it tells it where to look when a deeper question comes up.

PHASE_1_BRIEF.md is the only phase with literal prompts pre-written. As you complete Phase 1 and start Phase 2, expand that phase's summary in BUILD_SEQUENCE.md into a similar step-by-step brief. The first phase needed prompts because zero-state is the hardest moment; later phases can lean on the patterns established in Phase 1.

EXECUTIVE_SUMMARY.md is written to be read by people who will never touch the code. It's the document that gets adapted into a 10-slide deck or a one-pager for a stakeholder conversation. Sections are sized to map to slides without further editing.