Archived framework/archive/phase-0/15-claude-code-scaffold.md

Claude Code Scaffold (CLAUDE.md + .claude/)

Invoked by create-patties --agent claude-code (CLI 05).

Invoked by create-patties --agent claude-code (CLI 05).

Purpose

When a developer opts into Claude Code during scaffolding, ship a CLAUDE.md and .claude/ directory pre-tuned for the Patties framework. The goal: a fresh claude session in a fresh Patties project is productive on the first message — no prompt engineering, no permission churn, no "where does this go?".

This is separate from AGENTS.md (framework spec 11):

  • AGENTS.md is the open, vendor-neutral context file — generated on every build, for every project, regardless of which agent the developer uses.
  • CLAUDE.md and .claude/ are Claude-Code-specific tooling — opt-in, scaffolded once, owned by the developer afterwards (they may edit freely; we never overwrite).

Files produced

<project-root>/
  CLAUDE.md
  .claude/
    settings.json
    commands/
      new-route.md
      new-island.md
      new-agent.md
      new-tool.md
    agents/
      patties-reviewer.md

File specifications

CLAUDE.md

The per-app context file. Mirrors the structure of the contributor-facing CLAUDE.md from the OSS guide, but scoped to the user's project rather than the framework repo.

Required sections:

  1. What this project is — one line: project name + "Built with Patties — Bun-native full-stack meta-framework."
  2. Stack — Bun runtime · Bun.serve({ routes }) dispatcher · React renderer (react-dom/server + react-dom/client) · <configured target> deploy.
  3. File conventions — copy the table from framework spec 13-conventions, so the agent sees it without chasing links.
  4. Critical rules — the 10 numbered "Never use X / Always use Y" rules from spec 13. These are bright lines for any agent editing the project.
  5. How to run — bun install, bun dev, bun build, bun test. Project-specific scripts added if the template adds any.
  6. How to add a feature — point at the slash commands in .claude/commands/ and at AGENTS.md for the live inventory.
  7. Where to find things — pointer to AGENTS.md (auto-regenerated by patties build) for the current route/island/agent/tool map. Explicit instruction: "Trust AGENTS.md over this file for inventory questions; trust this file for rules and conventions."

The file is static after scaffolding. It does not get regenerated by builds. Drift between rules in this file and the framework is acceptable — it's the developer's copy.

.claude/settings.json

Project-scoped Claude Code settings. Minimum content:

{
  "permissions": {
    "allow": [
      "Bash(bun install)",
      "Bash(bun install:*)",
      "Bash(bun add:*)",
      "Bash(bun remove:*)",
      "Bash(bun dev)",
      "Bash(bun run:*)",
      "Bash(bun test)",
      "Bash(bun test:*)",
      "Bash(bun build)",
      "Bash(bunx patties:*)",
      "Bash(git status)",
      "Bash(git diff:*)",
      "Bash(git log:*)"
    ]
  }
}

Notes:

  • Only safe, frequently-used commands are pre-allowed. Mutating git operations (commit, push, reset) stay prompt-gated.
  • The framework core is vendor-neutral, so the base scaffold does not pre-allow any vendor CLI (wrangler, vercel, deployctl, netlify, etc.). Each official deploy plugin ships its own .claude/settings.json fragment that the scaffolder merges in when that plugin is selected during create-patties. Example: installing @patties/deploy-cloudflare contributes Bash(bunx wrangler:*), Bash(bunx wrangler whoami), Bash(bunx wrangler tail:*). Installing @patties/deploy-vercel contributes Bash(bunx vercel:*). The base scaffold stays vendor-free.
  • The file uses Claude Code's settings schema as of the scaffold date; the scaffolder pins the schema version it was generated against in a top-level // generated by create-patties vX.Y.Z comment is not allowed in JSON — instead, a sibling .claude/settings.json.meta records the generator version. The developer can delete it.

.claude/commands/

Slash commands that encode the framework's "how to add X" workflows. Each is a Markdown file whose body becomes the prompt when invoked.

new-route.md — /new-route <path>

Create a new Patties route.

Rules from CLAUDE.md:
- Page routes live in app/routes/ as .tsx files.
- API routes live in app/routes/api/ as .ts files exporting GET/POST/PUT/DELETE.
- Dynamic segments use [param].tsx; catch-alls use [...rest].tsx.

User intent: $ARGUMENTS

Decide whether the user wants a page or an API route based on the path and intent.
Create the file. Show me the diff. Do not run the dev server.

new-island.md — /new-island <Name>

Create a new interactive island.

Rules:
- Islands live in app/islands/ only.
- Use React (`react-dom/server` on the server, `react-dom/client` for islands). Never import from `hono/jsx` or `hono/jsx/dom`.
- Props must be JSON-serializable.

Component name: $ARGUMENTS

Scaffold the island file, then show me the diff and tell me which page should import it.

new-agent.md — /new-agent <name>

Create a Patties agent in app/agents/<name>.ts using defineAgent from "patties/ai".

Ask me which tools it should have access to (list tools from app/tools/).
Default model: claude-sonnet-4-6.
Add a triggers entry only if I asked for auto-wiring.

Agent name: $ARGUMENTS

new-tool.md — /new-tool <name>

Create a Patties tool in app/tools/<name>.ts using defineTool from "patties/ai".

Define the input schema with Zod. Ask me for the input shape if it's not obvious from the name.
Implement a stub handler that returns a placeholder result and a TODO comment.

Tool name: $ARGUMENTS

.claude/agents/patties-reviewer.md

A subagent definition tuned to review changes against the framework's bright lines.

---
name: patties-reviewer
description: Review staged or recent changes for Patties convention violations. Use after writing new routes, islands, agents, or tools.
tools: Read, Grep, Glob, Bash
---

You review code changes in a Patties project for violations of the framework's bright lines:

1. No imports from "next".
2. No node:http, fs.watch, chokidar, webpack, vite. No `hono/jsx` or `hono/jsx/dom`. No `renderToPipeableStream` (Node-only React API).
3. Islands must live in app/islands/.
4. API routes export GET/POST/PUT/DELETE — never default-export handlers.
5. Page routes return Response or a React element (rendered via `react-dom/server`).
6. Middleware default-exports a `Middleware` (`(req, ctx, next) => Promise<Response>`) from `patties/middleware`. Never `MiddlewareHandler` from `"hono"` — there is no Hono.
7. Routes register through `Bun.serve({ routes })` (Bun target) or the framework's edge matcher (edge target). Never `app.use` / `app.get` — there is no Hono `app`.

For each violation, cite the file:line and quote the offending code. Suggest the corrected form.
If no violations, say so in one line.

Idempotency

  • The scaffolder writes these files only if they do not already exist. It never overwrites a CLAUDE.md or anything under .claude/ the user already has.
  • If the developer re-runs create-patties into a fresh directory and answers "claude-code" again, they get an identical scaffold.

Non-goals

  • Generating .claude/ for other agents (Cursor, Cline, etc.). Add new --agent choices via RFC as those tools' file conventions stabilize.
  • Auto-updating CLAUDE.md when the framework's rules evolve. The file is the developer's; AGENTS.md is the live one.
  • Shipping MCP server configs in .claude/ — defer until Patties has a first-party MCP surface worth wiring.

Acceptance criteria

  • bunx create-patties foo --agent claude-code produces foo/CLAUDE.md and foo/.claude/ with every file listed above.
  • bunx create-patties foo --agent none produces neither.
  • Re-running into a directory where CLAUDE.md exists is refused (same as the existing "non-empty directory" rule).
  • The scaffolded .claude/settings.json parses as valid JSON and matches the Claude Code settings schema.
  • Opening the scaffolded project with claude and typing /new-route /hello produces a working app/routes/hello.tsx without further prompts.