AGENTS.md

Project orientation for any agent working on this repo (Claude Code, OpenCode, Codex, or other AGENTS.md-aware CLIs).

What this is

AI Atelie — a local-first, MIT-licensed design atelier. Designs live as sandboxed folders of HTML/JSX/CSS that the user and an agent CLI shape together. The repo wires into whichever coding-agent CLI is on PATH (Claude Code, Kimi, Codex, etc.) rather than bundling a proprietary agent.

Workspaces

api/            Bun + Hono SSE server bridging the web UI to the local agent CLI
web/            React + Vite editor; each design at web/projects/<id>/ as raw HTML/JSX/CSS
mcp/            ask-user, starters, capability surface — including DesignCanvas protocol
skills/         end-user product skills loaded into adapter-spawned editor sessions
.claude/skills/ contributor (dev-time) skills loaded when working ON this repo
atelier/        canonical craft rulebook (typography, color, anti-slop, accessibility, …)
docs/           contributor-facing docs and architecture notes

Bun workspaces: api, web, mcp (see package.json).

Common commands

bun install              # install workspace deps
bun run dev              # start api + web together (concurrently)
bun run build            # production build of web
bun run test:e2e         # Playwright e2e (excludes journeys)
bun run test:journeys    # Playwright journey suite (CUJ + per-feature)
bun run journeys         # journeys + inline PR-evidence pipeline

Conventions

• Commits: Conventional Commits 1.0.0 with the closed scope set api | web | mcp | skills | repo | deps. Imperative subject. CHANGELOG is auto-generated by changelogen + bumpp — write commit bodies that read well in the changelog.
• Branching / PRs: one branch with multiple semantic commits, one PR. Don't split a logical change across multiple PRs.
• Comments: default to none. Only annotate non-obvious why — hidden constraints, surprising invariants, workarounds for specific bugs.
• Tests: web/tests/e2e/cuj.spec.ts is the load-bearing Critical User Journey. Any change that plausibly affects routes, onboarding, canvas, or chat must keep it green.

Skills

Dev-time contributor skills live at .claude/skills/<name>/SKILL.md. They are loaded by Claude Code natively; OpenCode also auto-discovers them from .claude/skills/ (alongside its own .opencode/skills/). Skill frontmatter follows the standard name + description schema — no harness-specific fields.

Notable skills:

• ship-task/ — task → understand → implement → verify → semantic commit → PR with evidence
• cuj-guardian/ — gate and triage the CUJ on every PR
• verify-with-playwright/ — drive a real browser, capture screenshots/video for PR evidence
• pr-evidence/ — inject the inline-evidence block into a PR's body
• semantic-commit/ — draft Conventional Commits messages tuned to the scope set
• frontend-design/ — aesthetic + convention guide for the host app's chrome
• canvas-sync/ — keep DesignCanvas coherent across canonical / mirror / host wiring

Architecture notes

Each project at web/projects/<id>/ is served raw to an iframe canvas — no build step inside a project, pages run with CDN React + Babel-Standalone. The canvas surface (mcp/starters/DesignCanvas.jsx) has a byte-identical mirror at web/projects/demo/design-canvas.jsx; the protocol is documented in mcp/CANVAS_PROTOCOL.md. The canvas-sync skill enforces parity.

The agent CLI is launched as a subprocess by the api server; SSE streams responses back to the editor. Skills inside an editor session come from ENV.SKILLS_DIR (the product skills/ directory), not from .claude/skills/ — that's contributor-only.

Runtime AI in artifacts (window.ai.complete)

Generated artifacts (HTML files in the sandboxed preview iframe) can make one-shot AI calls at runtime — no API key in the artifact, no SDK to import, provider-neutral:

const reply = await window.ai.complete("grade this answer: ...");
// or:  await window.ai.complete({ messages: [{ role: "user", content: "..." }] })

How it works:

• A bridge script is auto-injected into every HTML response from /p/:id/* (see api/src/routes/projects.ts → AI_COMPLETE_BRIDGE). Defines window.ai.complete (and window.claude.complete as a legacy alias).
• The artifact postMessages __ai_complete to its parent. The host listener in web/src/lib/tweakBridge.ts forwards to POST /api/artifacts/complete, tagging the request with the active model from loadModelId().
• The route (api/src/routes/artifacts.ts) calls pickAdapter(modelId).complete() — the same dispatch the agent path uses. Each AgentAdapter implements complete() (agents/{claude,kimi,opencode}/complete.ts). OpenCode fans out further to whatever provider/model the user configured.
• Rate-limit (10 req/min per IP+UA) and daily token cap are provider-agnostic.

Use it for: trivia graders, AI-powered tutors, "rewrite this" buttons, in-artifact chatbots — anything that needs an LLM at runtime, not just at generation time. Demo at web/projects/demo/claude-complete-demo.html. The agent's prompt (api/src/services/promptBuilder.ts) already teaches this surface so it can author artifacts that use it.

Local dev quirks

• Vite binds localhost and IPv6, not 127.0.0.1.
• ccr-live-preview auto-restarts on :5173 / :5174 if killed — don't fight it.

OpenCode compatibility

This repo is configured for both Claude Code and OpenCode out of the box:

• .claude/skills/ — read by both natively
• AGENTS.md (this file) — read by both
• opencode.json — points OpenCode at this file via instructions

If you add MCP servers, note that OpenCode and Claude Code use different formats: Claude reads .mcp.json with mcpServers; OpenCode reads mcp in opencode.json with type + array-form command. There's no fallback between them — you'll need to maintain both.