|
| 1 | +# AGENTS.md - Open CoDesign |
| 2 | + |
| 3 | +Instructions for Codex and other AI coding agents working in this repository. Read this before making changes. |
| 4 | + |
| 5 | +This file is the canonical public agent guide. `CLAUDE.md` mirrors it for Claude Code. Maintainer-local `docs/VISION.md`, `docs/PRINCIPLES.md`, and `docs/v0.2-plan.md` may contain fresher planning details when present, but public contributors and bots must not assume those files exist. |
| 6 | + |
| 7 | +## What This Project Is |
| 8 | + |
| 9 | +Open CoDesign is an open-source desktop design agent. It turns prompts, local files, skills, scaffolds, brand systems, and model output into design artifacts on the user's laptop. |
| 10 | + |
| 11 | +The v0.2 direction is no longer a single-prompt generator. Each design is a long-running pi session with a real workspace. The agent can read and edit files, run permissioned commands, ask structured questions, preview artifacts, expose tweak controls, generate images when the configured model supports it, and produce `DESIGN.md` design-system artifacts. |
| 12 | + |
| 13 | +The original inspiration was Claude Design. The product boundary is now clearer: Open CoDesign borrows proven coding-agent mechanics, then adds design-specific tools and a local-first workspace model. |
| 14 | + |
| 15 | +`docs/` is mostly maintainer-local and gitignored. Some public research notes may exist, but internal plans, handoffs, and roadmap files usually do not. Do not cite `docs/**` in public PR review comments unless the exact file exists in the public checkout and is directly relevant. |
| 16 | + |
| 17 | +## Hard Constraints |
| 18 | + |
| 19 | +These are project commitments, not preferences: |
| 20 | + |
| 21 | +1. No bundled model runtimes. Do not ship Ollama, llama.cpp, Python, browser binaries, or model weights inside the installer. Use system installs or lazy-download with user-visible consent. |
| 22 | +2. BYOK only. No hosted account, proxied API, or telemetry by default. User credentials stay in human-readable local config. |
| 23 | +3. Local-first storage. v0.2 uses pi JSONL sessions plus real workspace files. Existing v0.1 SQLite data may be migrated, but do not add new SQLite tables for sessions, chat history, comments, snapshots, or design files. |
| 24 | +4. Every design has a workspace. No sealed/open split in v0.2. The workspace filesystem is the source of truth for artifacts and assets. |
| 25 | +5. MIT-compatible permissive licenses only. Reject GPL, AGPL, SSPL, proprietary deps, and unclear copied assets. Check licenses before adding scaffolds, brand refs, or package deps. |
| 26 | +6. Lazy-load heavy features. PPTX export, web capture, scaffolds, skills, brand refs, and image generation must load on demand rather than at app start. |
| 27 | +7. Reuse pi primitives first. `pi-coding-agent` owns sessions, built-in tools, bash execution, event streaming, model registry, provider registration, and capability data unless a design-specific need proves otherwise. |
| 28 | +8. Brand values are data, not model memory. Use `DESIGN.md`, user files, official CSS/SVG/screenshots, or brand URLs. Do not invent brand hex values from memory. |
| 29 | +9. PRs should satisfy Principles 5b: compatible, upgradeable, no bloat, elegant. |
| 30 | + |
| 31 | +## Current Architecture Direction |
| 32 | + |
| 33 | +### Agent Runtime |
| 34 | + |
| 35 | +- Use `pi-coding-agent` and `pi-ai`. |
| 36 | +- Use pi built-ins for `read`, `write`, `edit`, `bash`, `grep`, `find`, and `ls`. |
| 37 | +- Gate tools through the pi `tool_call` hook and the Open CoDesign permission UI. |
| 38 | +- Read capabilities from pi `Model<T>` fields such as `input`, `reasoning`, `cost`, `contextWindow`, and `maxTokens`. |
| 39 | +- Register custom providers through `pi.registerProvider()`. Do not build a parallel provider SDK layer. |
| 40 | +- All LLM calls go through `pi-ai`; do not import provider SDKs directly in app code. |
| 41 | + |
| 42 | +### Storage |
| 43 | + |
| 44 | +- Design equals pi session. |
| 45 | +- Session history lives under app user data as pi JSONL. |
| 46 | +- Design files, generated HTML/JSX/CSS, assets, exports, `AGENTS.md`, and `DESIGN.md` live in the user workspace. |
| 47 | +- Workspace settings live in `.codesign/settings.json` with `schemaVersion`. |
| 48 | +- `settings.local.json` is personal and should stay gitignored. |
| 49 | +- v0.1 SQLite is legacy data to migrate, not the v0.2 storage model. |
| 50 | + |
| 51 | +### Tools |
| 52 | + |
| 53 | +The v0.2 tool surface is pi's seven built-ins plus Open CoDesign design tools: |
| 54 | + |
| 55 | +- `ask(questions)` renders structured questions and waits for the user. |
| 56 | +- `scaffold(kind, path)` copies a curated starter into the workspace. |
| 57 | +- `skill(name)` lazy-loads skill text from a manifest. |
| 58 | +- `preview(path)` renders artifacts and returns console errors, asset errors, DOM outline, metrics, and screenshots for vision models. |
| 59 | +- `gen_image(prompt, path)` writes generated images to disk when capability and provider config allow it. |
| 60 | +- `tweaks(blocks)` declares editable controls across files. |
| 61 | +- `todos(items)` shows task state for complex turns. |
| 62 | +- `done(path)` ends a turn after preview self-check. |
| 63 | + |
| 64 | +Do not reintroduce a verifier subagent, snip tool, custom bash tool, custom list-files tool, or agent-written working memory for v0.2 unless the plan changes. |
| 65 | + |
| 66 | +### Design System |
| 67 | + |
| 68 | +- `DESIGN.md` follows the Google spec and can be both input and output. |
| 69 | +- Agent-generated multi-screen work should keep visual consistency by updating `DESIGN.md` as tokens emerge. |
| 70 | +- Built-in brand refs must include attribution, source, license metadata, and a "not affiliated" note. |
| 71 | +- Built-in skills use the agentskills-style `SKILL.md` format. |
| 72 | +- Skill and scaffold manifests should carry license and source metadata. |
| 73 | + |
| 74 | +## Stack and Conventions |
| 75 | + |
| 76 | +- Package manager: `pnpm` only. Never use `npm` or `yarn`. |
| 77 | +- Build orchestration: Turborepo. |
| 78 | +- Lint and format: Biome. |
| 79 | +- Tests: Vitest for unit tests, Playwright for E2E. |
| 80 | +- TypeScript: strict mode, `verbatimModuleSyntax`, bundler resolution, no `any`. |
| 81 | +- Commits: Conventional Commits. |
| 82 | +- Versioning: Changesets. Do not hand-edit `CHANGELOG.md`. |
| 83 | +- Node: 22 LTS, pinned by `.nvmrc` and `engines`. |
| 84 | +- Exact package versions live in `package.json`, workspace manifests, and `pnpm-lock.yaml`. Read those files instead of trusting stale docs. |
| 85 | + |
| 86 | +### Frontend |
| 87 | + |
| 88 | +- React + Vite + Tailwind v4 + CSS variables. |
| 89 | +- State uses Zustand. Do not introduce Redux, Recoil, or MobX. |
| 90 | +- Components use Radix primitives and custom shadcn-style wrappers in `packages/ui`. |
| 91 | +- Icons use `lucide-react`. |
| 92 | +- Forms use native `<form>` and `FormData`. |
| 93 | +- Animations use Tailwind transitions. Do not introduce framer-motion or motion. |
| 94 | +- App chrome must use `packages/ui` tokens. Artifact output may define its own visual system. |
| 95 | +- Sandbox preview remains Electron iframe `srcdoc` plus runtime tooling. |
| 96 | + |
| 97 | +## Repository Layout |
| 98 | + |
| 99 | +```text |
| 100 | +apps/ |
| 101 | + desktop/ # Electron app shell, main process, renderer |
| 102 | +packages/ |
| 103 | + core/ # Agent orchestration, prompts, design tools |
| 104 | + providers/ # pi integration and provider compatibility shims |
| 105 | + runtime/ # Sandbox renderer and preview runtime |
| 106 | + ui/ # Shared app UI tokens and components |
| 107 | + artifacts/ # Artifact schemas and bundle formats |
| 108 | + exporters/ # PDF / PPTX / ZIP exporters, lazy-loaded |
| 109 | + templates/ # Built-in examples and starter templates |
| 110 | + shared/ # Shared types, utils, schemas |
| 111 | +docs/ # Mostly maintainer-local plans/research; many files are gitignored |
| 112 | +examples/ # Public demo reproductions |
| 113 | +``` |
| 114 | + |
| 115 | +## Doing Tasks Here |
| 116 | + |
| 117 | +- Read `AGENTS.md` or `CLAUDE.md` first, depending on your agent runtime. |
| 118 | +- For non-trivial architecture or product work, also read `docs/VISION.md`, `docs/PRINCIPLES.md`, and `docs/v0.2-plan.md` when they exist locally. |
| 119 | +- Use planning files in `.Codex/workspace/` or your agent's local workspace for tasks spanning more than five tool calls or more than three files. |
| 120 | +- Use git worktrees for parallel or unrelated feature work. Do not mix two unrelated branches in one checkout. |
| 121 | +- Check `docs/RESEARCH_QUEUE.md` when it exists before touching sandbox, inline comments, tweaks, PPTX, pi capabilities, scaffolds, skills, or brand refs. |
| 122 | +- Keep edits scoped. Avoid drive-by refactors. |
| 123 | +- Before adding a dependency, check license, install size, alternatives, and whether it can be a peer dep. |
| 124 | +- Add or update Vitest coverage for feature work. Broaden tests when changing migrations, permissions, tool hooks, or shared contracts. |
| 125 | +- Prefer manifest and switch logic over registries until two real callers need more. |
| 126 | +- Comment only when the reason would surprise the next maintainer. |
| 127 | + |
| 128 | +## Permission Model |
| 129 | + |
| 130 | +Open CoDesign uses one permission model with tiers: |
| 131 | + |
| 132 | +- Tier 0: workspace-local reads/writes, simple file commands, and read-only git may run without interruption. |
| 133 | +- Tier 1: installs, build commands, non-local network fetches, and cwd-external commands ask once and can be allowlisted. |
| 134 | +- Tier 2: publishing, pushing, sudo, and high-blast-radius commands ask every time. |
| 135 | +- Tier 3: destructive system commands, `curl | sh`, and system-directory writes are blocked without override. |
| 136 | + |
| 137 | +Do not hide blocked tool calls. Show the command, path, tier, and reason. |
| 138 | + |
| 139 | +## Things to Avoid |
| 140 | + |
| 141 | +- Adding `node_modules`, build outputs, `.env*`, generated release artifacts, or private local files to git. |
| 142 | +- Importing `@anthropic-ai/sdk`, `openai`, `@google/genai`, or other provider SDKs in app code. |
| 143 | +- Writing tests that mock the LLM at the SDK level. Mock at the core or pi boundary. |
| 144 | +- Adding tracking, analytics, account flows, cloud sync, or auto-update without explicit opt-in UX. |
| 145 | +- Hard-coding user paths. Respect XDG, Electron `app.getPath()`, and workspace roots. |
| 146 | +- Adding new SQLite-backed feature state for v0.2 session/design data. |
| 147 | +- Introducing `project` as a product abstraction in v0.2. Multiple sessions can share a workspace, but the sidebar lists sessions. |
| 148 | +- Exposing session branching UI, undo/version rollback, MCP support, or community skill installation in v0.2 unless the plan changes. |
| 149 | +- Using `console.*` in `apps/desktop/src/main/**`, `packages/core/**`, `packages/providers/**`, `packages/exporters/**`, or `packages/shared/**`. Use the project logger. |
| 150 | + |
| 151 | +## Useful Commands |
| 152 | + |
| 153 | +```bash |
| 154 | +pnpm i |
| 155 | +pnpm dev |
| 156 | +pnpm test |
| 157 | +pnpm test:e2e |
| 158 | +pnpm lint |
| 159 | +pnpm typecheck |
| 160 | +pnpm build |
| 161 | +pnpm changeset |
| 162 | +``` |
0 commit comments