988a47c797
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.
38 lines
2.7 KiB
Markdown
38 lines
2.7 KiB
Markdown
# 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.
|