MEMORY // CONTEXT // SKILLS
Studio memory that compounds, agents that hand off, approval gates that stay human. This is the working system, not a concept deck.
Every Claude Code session loads context in five layers, in order: root CLAUDE.md → project WORKSPACE.md → sprint CONTEXT.md → references/ → output/. Studio identity, principles, and gates live in studio-memory.md — a core capped at 100 lines, loaded whole at every session start because it is small enough to afford. Everything deeper — accumulated learnings, code standards, creative defaults — loads on demand, named by the sprint CONTEXT.md Inputs table.
The sprint CONTEXT.md is the layer that does the work. It names the exact files (and sections) to load, the contract Claude is held to, and the audit checklist run before the PR opens. references/ carry stable inputs for the sprint; output/ carries this-run artifacts.
The memory grows. After each shipped project, sc-learn captures real learnings — the Next.js trailingSlash trap, the Supabase service-role GRANT lesson, the CSS-only layout reflow pattern — each one a file in learnings/, indexed in a single line. The next sprint starts with that knowledge already addressable.
Thirteen steps, in order. I write a brief. The Planner expands it into a spec. I create the Figma file. The Generator scaffolds the project, sets up deploy and preview workflows, and waits. I design the brand system and pages in Figma. The Generator builds one section per sprint. The Evaluator grades each sprint against the four Shokunin criteria. In a team context, user testing runs here before the merge decision. I review the live preview on desktop and mobile, then merge.
Four approval gates protect the work: Concept (after Planner), Design (after Figma), Development (after Evaluator pass), Delivery (after final review). Nothing crosses a gate without me.
Goal Mode (/goal) only runs between gates. It collapses the per-turn prompting inside an authorized phase. It never replaces a gate.
The Planner turns a one-paragraph brief into a full product spec with sprint breakdown. Runs in Claude.ai with the studio project active. Cheap. One pass.
The Generator builds the sprint. Reads the layered chain — CLAUDE.md → WORKSPACE.md → the sprint's CONTEXT.md — and loads only the files named in that CONTEXT.md's Inputs table. Implements one section, runs the CONTEXT.md audit checklist before opening the PR, ships a PR with a live preview URL and four breakpoint snapshots. Dispatched as a background session in Agent View so it runs without my attention.
The Evaluator grades the sprint against Originality, Design Quality, Craft, and Functionality. Skeptical by design. Catches issues before I review. Single-pass: never put a /goal or /loop on it.
I do four things: brief, approve, review, merge. I am the only one who pushes to main. This is agentic engineering — orchestrating agents with the oversight and quality discipline of engineering, not casual prompting. A circulating ten-rule extension adds six runtime rules for loop-level self-monitoring — Verification (test before fixing), Debugging discipline, Dependency hygiene, Communication (actionable uncertainty), and four named failure modes (Kitchen Sink, Wrong Abstraction, Optimistic Path, Runaway Refactor) the agent should recognize and stop.
Claude Max ($100/mo) gives me Opus and Sonnet on a shared token pool. Sonnet for content and scaffolding; Opus for sprint builds; Fable for planning and evaluator passes.
Claude Design runs on Opus 4.8 with its own independent weekly limit that does not touch the Max pool. I use it for visual inspiration before committing anything to Figma.
Cowork is the Desktop app's third tab. File-based knowledge work — briefs, memory updates, deliverable organization. Same connectors as chat. Remote dispatch from iPhone. Not Claude Code, not Agent View.
Figma + Figma MCP are the design system and the agent's interface to it. Sandbox is creative workspace; Production is canonical. generate_figma_design writes approved frames straight to the Production canvas — no manual promotion step. /sync-figma-token pulls tokens from Sandbox into token-map.md — for projects with their own token set; branded properties consume the shared system instead.
GitHub Actions + Hostinger handle deploys. Every PR opens a live preview at a real URL.
Every step says exactly which tool, which prompt, and which approval gate. I do five of them. AI does the rest.
Before every session. Two pre-session gates from studio-memory.md §6, ahead of any Claude Code session below (scaffold, build, evaluate).
Sync main. The local repo is synced to main (git checkout main && git pull origin main) and confirmed up to date with remote before any branch or worktree is created. Not optional, not skipped because a change "looks small."
Confirm the model. Confirm the selected model before the first prompt. Fable 5 is never the default, it runs only on Planner and Evaluator passes.
These are the files Claude reads at the start of every session. The studio gets smarter with every project because this memory persists.
studio-memory.md is the studio's core institutional memory — identity, design principles, quality criteria, stack defaults, and approval gates, capped at 100 lines and loaded at the start of every session. Depth lives beside it, not inside it: accumulated learnings in learnings/ (one file per lesson, indexed one line each), code standards and creative defaults in playbooks/. Sessions read a detail file only when the work calls for it. The next sprint starts with the relevant learnings already addressable, without paying for the rest in context tokens.
Three real entries from learnings/
2026-05-09
Next.js trailingSlash: true needs skipTrailingSlashRedirect: true for POST routes.
POST requests get 308-redirected and never reach the handler. Stripe webhooks fail silently. Always pair the two settings, or the URL convention quietly breaks server integrations.
2026-05-09
Supabase service role needs explicit GRANT even with RLS disabled.
Disabling row-level security does not grant table access. Backend writes fail with permission errors until grant all on table … to service_role; is added in every table-creation migration.
2026-07-22
Raw session media is processed once — read the derivative, never the transcript.
Transcripts and recordings are write-once inputs. One processing pass produces the derived artifact — the verdict, the brief, the package — and folder structure routes every future session to that derivative. Re-reading raw media burns tokens on already-extracted signal and invites re-deciding what was already decided.
Every project clones from the same template. WORKSPACE.md defines the project. WORKFLOW.md defines the stages and approval gates. token-map.md is the design system source of truth for projects with an isolated token set; Shokunin-branded properties consume the shared system at brand.shokunincrafthouse.com. Stages live in numbered folders so the lifecycle is visible at a glance.
Open any folder below to see what's inside
WORKSPACE.mdRead first. Project identity.
WORKFLOW.mdStage flow + approval gates.
workspace.manifest.yamlMachine-readable index.
claude/CLAUDE.mdPoints Claude Code at WORKSPACE.md.
generic/BOOTSTRAP.mdModel-neutral entry.
brand/Colors, logos, type pairings.
voice/Tone, copy direction.
figma-links.mdCanonical Figma URLs.
token-map.mdExtracted Figma tokens.
ui-rules.mdComponent + layout rules.
CONTEXT.mdStage contract: Inputs, Process, Outputs, Audit.
references/Stable inputs the stage consumes.
output/Stage deliverables (approved spec).
CONTEXT.mdStage contract.
references/Brand inputs, reference imagery.
output/Figma exports, claude-design/ exports.
CONTEXT.mdTop-level build stage contract.
CONTEXT.mdSprint contract: Inputs table, approved contract, audit checklist.
references/Sprint-scoped reference material.
output/Snapshots, evaluator reports for this sprint.
CONTEXT.mdStage contract.
references/Cross-sprint review inputs.
output/Roll-up reports.
CONTEXT.mdStage contract.
references/Launch checklists, runbooks.
output/Deploy notes, post-launch artifacts.
decisions.mdWhy we chose what we chose.
Quality is systematic, not subjective. Each criterion is graded through a named lens library (the sc-design-crit skill), so every finding cites an established framework rather than a reviewer's taste. The Evaluator grades every sprint against four criteria. Two are required passes — sprints cannot ship with failures there. The four approval gates protect the system from drift.
The four criteria
Originality Highest weight
Evidence of deliberate creative decisions. No AI-default patterns. A human designer should see intent.
Design quality Highest weight
Coherent whole. Color, type, layout, imagery, and interaction combine into a distinct mood, not a collection of parts.
Craft Required pass
Typography hierarchy, spacing consistency, color harmony, contrast ratios. The competence floor. Failures here are disqualifying.
Functionality Required pass
Users understand what the interface does, find primary actions, and complete tasks without guessing. The AI Evaluator approximates this from code and snapshots. User testing confirms it from real behavior.
These are the defaults I've encoded so every session starts with a point of view, not a blank canvas. From playbooks/creative-defaults.md. Override with intent and reason, never by accident.
Start monochromatic.
One accent, introduced late, with purpose. Three colors is usually one too many.
Springs over curves.
Springs feel physical; cubic-beziers feel digital. In the studio's motion philosophy system they are the Systemic Restraint default: Cinematic and Experiential projects choose their own easing, and choreographed timelines still use curves.
One typeface family, full range.
Two families only if they refuse to compete. Display vs. body, sharp hierarchy, no overlap.
Grid as premise, not prison.
Break the grid rarely and with force. The break works only because the grid exists.
Know the register.
Dense UIs read as capable. Sparse UIs read as premium. Pick deliberately. Do not default to sparse because it is easier.
Detail is the craft, not the polish.
Scrollbar, favicon, empty state, 404, loading skeleton, form-error copy. These are the work, not the finishing touches.
Copy ships, never lorem.
Button labels, error copy, placeholders, onboarding. All design decisions. Production text is written, never filler.
Three tables. Designed to scan, not read. Claude Design and Cowork get their own callouts because they're often misunderstood.
| If I need to… | Use this | Why |
|---|---|---|
| Persist studio identity across every session | studio-memory.md + Claude Project |
The ≤100-line core loads whole at session start; learnings and playbooks load on demand via the sprint Inputs table. The studio compounds without paying full-file context cost each sprint. |
| Build with the agent | Claude Code (terminal) | All code work — scaffold, build, deploy. Background sessions in Agent View. |
| Protect main from accidents | GitHub branch ruleset | PR required, force-pushes blocked, deletions restricted. I am the only approver. |
| Constrain Claude's reach | ~/.claude/settings.json |
Allowed paths only. SSH, keychains, personal docs blocked. |
| Block specific tool inputs or subagent models | Tool(param:value) permission syntax (v2.1.178) |
Parameter-level matching. Agent(model:opus) blocks Opus subagents; Bash(command:rm*) blocks destructive shell commands. More surgical than blocking the tool entirely. dir/** allow rules now match only <cwd>/dir, use **/dir/** for the old any-depth match; Write(path)/Glob(path) rules show a startup deprecation warning, use Edit(path)/Read(path) instead. |
| Automate post-write actions or scope hooks to specific tools | PostToolUse hook + if field |
A PostToolUse hook fires after every tool call — use it for format-on-save after file writes without IDE dependency. Scope hooks to specific tool patterns with the if field: "if": "Bash(git *)" fires only on Bash calls matching git *. Reduces overhead; hooks run only where they're needed. |
| Notify an external system when a background agent needs input or finishes | Notification hook (v2.1.198) |
The Notification hook fires on agent_needs_input and agent_completed events — the bridge between a background Claude Code session and any external notification system (iMessage dispatch, Cowork remote, a webhook). |
| Run a shell command and have Claude analyze the output | ! bash prefix (v2.1.186) |
Prefix any command with ! to run it in bash and have Claude automatically respond to the output — not just add it to context. Opt out with "respondToBashCommands": false in settings.json to restore the previous context-only behavior. |
| Run Claude Code against private infrastructure | claude self-hosted-runner (v2.1.224, Team/Enterprise) |
Runs Claude Code web, mobile, and desktop sessions on your own machines or containers instead of Anthropic's. The session gets internal network access and whatever custom tooling lives on that box, and the whole execution environment stays inside your own compliance boundary. The path to using an agent against infrastructure that was never going to be reachable from the outside. |
| Keep budget low by default | Sonnet 5 | Sonnet 5 default (1M context). Opus 4.8 for sprint builds, pinned deliberately by ADR regardless of Anthropic's own tier default. Fable 5 only for Planner and Evaluator passes, the two judgment seats. Anthropic's own Claude Code default Opus model moved to Opus 5.5 in v2.1.280 (20% cheaper, $4/$20 per Mtok); Pro and Team Standard plans now default to Opus 5.5 instead of Sonnet, a breaking change for anyone relying on the prior default. Independent benchmark from Boris Cherny (bcherny): a HAProxy C-to-Rust migration ran 9.5h on Opus 5.5 versus 12h on the prior default, at 51% lower cost, evidence worth weighing specifically for large multi-file migrations and long sprint runs; the studio's own Opus 4.8 pin for sprint builds stays the deliberate ADR-backed choice until that changes. |
| Respond to a permission dialog | Enter / Esc (v2.1.280) | The y/n keybindings were removed from permission dialog bindings, approve with Enter, decline with Esc. Hook setups: agent-type hooks were removed from PermissionRequest, use command or http hook types instead. |
| Tune instructions for Claude 5 models | Prune, don't expand | Shorter CLAUDE.md files and skills outperform verbose ones on Sonnet 5, Fable 5, and Mythos 5+. Anthropic cut Claude Code's own system prompt 80% (800 → 164 tokens) with no measured performance loss (claude.com/blog, 2026-08-13). The finding inverts the instinct to add more guidance — prune and distill existing instructions rather than expanding them. |
| If I need to… | Use this | Why |
|---|---|---|
| Turn a brief into a spec | Claude.ai Planner (Fable 5) | Studio context already in project knowledge. One pass. |
| Explore visual direction | Claude Design (Opus 4.8) | Separate weekly limit. Does not draw from Max pool. Free creative resource within its own cap. |
| Choose a project's motion language | sc-motion |
Selects one of three motion philosophies, Systemic Restraint, Cinematic Direction, or Experiential, plus a shared procedural-animation library, and pins the choice as an ADR at Gate 1. One language per project, held to the end. The invariants hold across all three: reduced-motion stays functional, nothing animates without cause, focus and contrast rules stay untouched. |
| Generate or remix a design inside Figma | Figma Agent (beta) | Figma's purpose-built design agent, embedded in the canvas rather than bolted on as a sidebar chat. It generates and remixes designs against an existing design system out of the box, so output lands on the studio's own tokens and components instead of generic defaults, and it absorbs the rote construction work between direction and comp. Gradual beta for Full seats on Professional, Organization, and Enterprise plans; no credits consumed while it is in beta. A community skills library now has 50+ design workflow skills (research, design systems, handoff); the agent can also create a new skill based on context in the active file. |
| Translate Figma into code | Claude Code + Figma MCP | Reads Sandbox, writes code. generate_figma_design also writes approved frames to the Figma Production page. Figma Motion (June 2026) is MCP-compatible: animated frames are inspectable in Dev Mode and can be passed directly to a coding agent for implementation; copy animation code as CSS, JSON, or framework-ready React. Code Connect in MCP is what keeps that output specific: it hands the agent production component context during design-to-code, so the agent reaches for the real component instead of regenerating a generic one, and spends fewer tokens doing it (Figma, 2026-08-05). Auto layout also gained vertical wrap (Sept 2026): a column-direction container now wraps to a new column the way flex-wrap: column does in CSS, closing a gap that previously needed a manual workaround for responsive component layouts. |
| Map a project plan or architecture in FigJam | figma-use-figjam MCP skill |
Three tools: figma-use-figjam writes content into FigJam, generate-project-plan builds a structured plan diagram, get_figjam reads an existing board. Architecture diagram → FigJam → coding agent: sketch the system structure, then the Generator reads the board as sprint context. Figma MCP server expanded June 16 to cover Slides, FigJam, Make, and the Figma design agent. download_assets exports production assets directly from any Figma file. |
| Sync Figma tokens into the repo | /sync-figma-token |
Reads the Sandbox page, extracts tokens, syncs to _config/design-system/token-map.md. First run is clean; later runs show ADDED / REMOVED / CHANGED before overwriting. Bypassed for Shokunin-branded properties, which link the shared CSS from brand.shokunincrafthouse.com instead. |
| Get a live preview on every PR | GitHub Actions preview workflow | Real URL per PR plus snapshot screenshots in the PR body. |
| Run unattended within a phase | /goal after contract approval |
Claude Code 2.1.139+. Sets a session-scoped completion condition; Haiku checks every turn. Use for Step 4 scaffold and Step 9 sprints. Never on the Evaluator. Always cap with or stop after N turns. |
| Re-run a check on an interval in-session | /loop (Claude Code v2.1.71+) |
Session-scoped cron. Re-runs a prompt or slash command on an interval; tasks auto-expire after 3 days. In-session monitoring only: CI watch, preview re-checks. Never on the Evaluator. Not a replacement for Cowork scheduled tasks, which persist. |
| Design a chart or dashboard color system | /dataviz (v2.1.198) |
Built-in skill for chart and dashboard design guidance. Ships a runnable color-palette validator — confirms the palette meets contrast requirements before code lands. |
| Monitor multiple sprints at once | Agent View (claude agents) |
Claude Code 2.1.139+. One screen for every background session — running, waiting, completed, failed. claude agents --json (v2.1.145+) outputs live sessions as JSON for scripting into tmux status bars or session pickers. I cap parallel sessions at 2–3. For larger orchestrated flows, Dynamic Workflows (v2.1.154+) fans work out across tens to hundreds of background agents via /workflows. Background sessions follow the repo's CLAUDE.md git instructions: since v2.1.221 they commit and push to preserve work but open a draft PR only when the task calls for one, not on every completion, which retires the v2.1.198 always-draft-PR behavior and the noise it made on unattended runs. /fork now spawns a background session with its own row here, not an in-session subagent, and inherits the full conversation plus prompt cache by default, cutting context-rebuild cost for branched work; /subtask is the new command for launching a subagent within the current session, and non-teammate subagents spawned in interactive sessions now run in the background by default. /code-review at high, xhigh, or max effort now runs as a background agent too, not just at lower effort levels. Sessions still default to a 200-call cap on WebSearch, but the 200-spawn subagent cap was removed in v2.1.224, so a long orchestration run no longer hits a wall mid-batch; concurrency and depth limits still apply. Sessions can also message each other across machines via SendMessage and ListAgents (v2.1.224/225), so a Remote Control session is reachable by name from another machine instead of only when it initiates contact. Typing @ in the prompt mentions another live session by name and routes the message via SendMessage directly, no confirm step. |
| Grade a sprint | Evaluator, fresh Claude Code session on Fable 5 | Single-pass audit. Never put /goal or /loop on it. Grades through the sc-design-crit lens library; findings cite named frameworks. |
| Change any session setting mid-session | /config key=value (v2.1.181) |
Set any config inline: /config thinking=false, /config effort=low. /config --help lists all keys. Faster than menus; takes effect immediately. |
Recover context lost to /clear |
/rewind (v2.1.191) |
Resumes the conversation from before the last /clear was run. No need to re-establish context manually when a clear was premature. |
| Share session output as a live page | CC Artifacts (beta, Team/Enterprise) | Turns a Claude Code session into a shareable HTML page at a private URL. PR walkthroughs, dashboards, release checklists. |
| Validate decisions with real users | Maze / Lyssna / Dscout | The AI Evaluator grades Functionality from code and snapshots. It cannot replace a real user. Tool scales to company stage — see For Hiring Managers. |
| Verify complex async or concurrent state formally | Formal verification with Claude + Lean/TLA+ | Two short prompts is enough to get started, no prior Lean or TLA+ knowledge required: describe the state machine or concurrency property, then ask Claude to prove it. Boris Cherny's report: a two-prompt pass produced 16 PRs fixing bugs and race conditions. Reach for it on complex async state and concurrency specifically, not as a default technique. |
| Audit CLAUDE.md files, skills, and agents for quality | /doctor prompt-audit (v2.1.283) |
Complements /skill-doctor: audits CLAUDE.md files, skills, and agents for quality issues rather than token usage. Run it after writing or editing a skill, and before a Gate 3 review. |
| If I need to… | Use this | Why |
|---|---|---|
| Sharpen a rough brief | Cowork | File-based, multi-step. Reads cowork-context.md on every task. |
| Close out a sprint's learnings | sc-learn |
Captures repo lessons and the build-log entry automatically; drafts studio promotions for approval. Appends, never rewrites. |
| Organize deliverables before handoff | Cowork | Renames, sorts, flags WIPs. Proposes the structure before changing anything. |
| Synthesize research into a design brief | Cowork + Claude for Chrome | Full browser control. Fewer screen interactions, faster execution. |
| Dispatch a task from iPhone | Cowork remote dispatch | iOS app → Mac runs the task. Mac stays awake. |
| Run a scheduled morning briefing | Cowork scheduled task | Reads WORKSPACE.md across all active projects. Unattended. |
For Hiring Managers
It's rocket AI science
I am the design team.
What I build first:
A WORKSPACE.md for your product, a studio-memory.md for your design patterns, and a sprint workflow tuned to your ship cadence.
It's rocket AI science
I lead a design team.
What I build first: A design quality framework, a team-wide memory system, and an AI-assisted sprint workflow that integrates with your existing engineering cadence.
It's rocket AI science
I lead a design function.
What I build first: A pilot with one product team. Prove the model. Measure velocity, quality scores, and designer satisfaction. Then scale with a governance framework that gives teams autonomy within guardrails.