open-codesign AGENTS.md

AGENTS.md - Open CoDesign

Instructions for Codex and other AI coding agents working in this repository. Read this before making changes.

CLAUDE.md may lag behind the current plan. For Codex work, treat this file as the public source of truth. If local internal docs such as docs/VISION.md, docs/PRINCIPLES.md, or docs/v0.2-plan.md exist, use them as additional context; if they are missing, do not block public-contributor work on them.

What This Project Is

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.

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.

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.

Product model: a Design owns a workspace. The agent edits design source files in that workspace; the preview runtime turns those sources into a rendered web document; exporters turn the rendered/source document into standard outputs such as HTML, PDF, PPTX, ZIP, or Markdown. In v0.2 the default source entry is App.jsx; index.html is reserved for standalone exports or legacy workspace files.

docs/ is gitignored. Maintainers may have internal plans, handoffs, and research locally; public contributors may not. Do not cite docs/** in public PR review comments unless the file exists in the public checkout.

Hard Constraints

These are project commitments, not preferences:

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.
2. BYOK only. No hosted account, proxied API, or telemetry by default. User credentials stay in human-readable local config.
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.
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.
5. Shipped app/runtime dependencies, bundled assets, scaffolds, skills, brand refs, and copied code must be MIT-compatible permissive. Reject GPL, AGPL, SSPL, proprietary deps, and unclear copied assets in anything that is bundled, linked, imported by app code, or distributed to users. Workflow-only CI/release tools may use copyleft licenses when they are not vendored, bundled, linked, or copied into the product; document the reason and keep their outputs limited to ordinary metadata or manifests.
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.
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.
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.
9. PRs should stay compatible, upgradeable, lean, and elegant. If docs/PRINCIPLES.md is present, use its Principles 5b wording as the detailed checklist.