Contributing to AI Atelier

Thank you for your interest in contributing to AI Atelier! We welcome contributions from humans and from agent CLIs (Claude Code, Codex, Kimi, OpenCode, Cursor, etc.).

This guide covers everything you need to know to contribute effectively.

中文

为 AI Atelier 做贡献

感谢你对 AI Atelier 的兴趣！我们欢迎人类和智能体 CLI（Claude Code、Codex、Kimi、OpenCode、Cursor 等）的贡献。

本指南涵盖了你有效贡献所需了解的一切。

How to Contribute
Prerequisites
Setting Up Agent CLI Integration
Setting Up Locally
Git Branching & Commit Style
Pull Request Workflow
Coding Conventions
Testing
Dev-Time Skills
The ship-task Workflow
Need Help?

中文

How to Contribute

Find an issue — browse open issues or open a new one
Discuss — comment on the issue to let others know you're working on it
Fork & branch — create a feature branch from main
Implement — follow the conventions below
Test — ensure the Critical User Journey passes
Open a PR — with a clear title and description referencing the issue

If you are an agent CLI, the dev-time skills will guide you through each step automatically.

中文

如何贡献

查找 issue — 浏览开放的 issue 或新建一个
讨论 — 在 issue 中评论，让他人知道你在处理
Fork 并创建分支 — 从 main 创建功能分支
实现 — 遵循以下规范
测试 — 确保关键用户旅程通过
打开 PR — 使用清晰的标题和描述，引用相关 issue

如果你是智能体 CLI，开发时技能将自动引导你完成每个步骤。

Prerequisites

Bun >= 1.2.x (install: curl -fsSL https://bun.sh/install | bash)
Node.js >= 20.x (for some agent CLIs)
An agent CLI — at least one of: Claude Code, Codex, Kimi, OpenCode, Cursor, Copilot, Gemini CLI, Qwen CLI, Hermes
Playwright browsers (for E2E tests): bunx playwright install chromium

中文

前置条件

Bun >= 1.2.x（安装：curl -fsSL https://bun.sh/install | bash）
Node.js >= 20.x（某些智能体 CLI 需要）
一个智能体 CLI — 至少其中之一：Claude Code、Codex、Kimi、OpenCode、Cursor、Copilot、Gemini CLI、Qwen CLI、Hermes
Playwright 浏览器（用于 E2E 测试）：bunx playwright install chromium

Setting Up Agent CLI Integration

This repo is designed to work with multiple agent CLIs. The dev-time skills and project configuration are agent-agnostic.

Claude Code

Claude Code discovers .claude/skills/, AGENTS.md, and .mcp.json automatically.

# Install Claude Code
npm install -g @anthropic-ai/claude-code

# Start a session
claude

OpenCode

OpenCode reads .claude/skills/, AGENTS.md, and opencode.json.

# Install OpenCode
npm install -g opencode

# Start a session
opencode

Other Agents

For Codex, Kimi, Cursor, etc., follow their respective CLI setup guides. The AGENTS.md file provides project orientation for any AGENTS.md-aware CLI.

中文

设置智能体 CLI 集成

本仓库设计为与多个智能体 CLI 配合使用。开发时技能和项目配置与智能体无关。

Claude Code

Claude Code 自动发现 .claude/skills/、AGENTS.md 和 .mcp.json。

# 安装 Claude Code
npm install -g @anthropic-ai/claude-code

# 启动会话
claude

OpenCode

OpenCode 读取 .claude/skills/、AGENTS.md 和 opencode.json。

# 安装 OpenCode
npm install -g opencode

# 启动会话
opencode

其他智能体

对于 Codex、Kimi、Cursor 等，请遵循各自的 CLI 设置指南。AGENTS.md 文件为任何支持 AGENTS.md 的 CLI 提供项目定位。

Setting Up Locally

# Clone the repository
git clone https://github.com/aiatelie/ai-atelie.git
cd ai-atelie

# Install workspace dependencies
bun install

# Copy environment variables (if applicable)
cp .env.example .env

# Start development (web + API)
bun dev

The development server starts:

Web app at http://localhost:5173
API server at http://localhost:5174

中文

本地设置

# 克隆仓库
git clone https://github.com/aiatelie/ai-atelie.git
cd ai-atelie

# 安装工作空间依赖
bun install

# 复制环境变量（如适用）
cp .env.example .env

# 启动开发环境（Web + API）
bun dev

开发服务器启动：

Web 应用在 http://localhost:5173
API 服务器在 http://localhost:5174

Git Branching & Commit Style

Branch Naming

feat/<description>     — New features
fix/<description>      — Bug fixes
docs/<description>     — Documentation changes
refactor/<description> — Code refactoring
chore/<description>    — Maintenance tasks

Commit Style

<type>(<scope>): <imperative subject>

[optional body]

Examples:

feat(web): add zoom controls to canvas
fix(api): handle null model response gracefully
docs(repo): update README with new architecture diagram
chore(deps): bump playwright to 1.52.0

Rules:

Subject is imperative, lowercase, no trailing period
One branch per logical change — do not split a feature across multiple PRs
One branch can have multiple semantic commits
CHANGELOG is auto-generated by changelogen + bumpp — write commit bodies that read well in the changelog

中文

Git 分支与提交风格

分支命名

feat/<description>     — 新功能
fix/<description>      — 错误修复
docs/<description>     — 文档更改
refactor/<description> — 代码重构
chore/<description>    — 维护任务

提交风格

<type>(<scope>): <imperative subject>

[optional body]

示例：

feat(web): add zoom controls to canvas
fix(api): handle null model response gracefully
docs(repo): update README with new architecture diagram
chore(deps): bump playwright to 1.52.0

规则：

主题使用祈使句、小写、无句尾句号
每个逻辑更改一个分支——不要将一个功能分散到多个 PR 中
一个分支可以有多个语义化提交
CHANGELOG 由 changelogen + bumpp 自动生成——编写在变更日志中易于阅读的提交正文

Pull Request Workflow

Create a PR from your feature branch to main
Title should follow Conventional Commits format: type(scope): description
Description should include:
- What the change does
- Why it's needed (link to the issue)
- How it was tested
- Screenshots or screen recordings for UI changes
CI will run automatically — ensure all checks pass
Review — at least one maintainer review required
Merge — squash-merge into main

中文

Pull Request 工作流程

创建 PR — 从你的功能分支到 main
标题 — 应遵循 Conventional Commits 格式：type(scope): description
描述 — 应包括：
- 更改内容
- 更改原因（链接到 issue）
- 测试方式
- UI 更改的截图或录屏
CI — 将自动运行，确保所有检查通过
审查 — 至少需要一位维护者审查
合并 — squash-merge 到 main

Coding Conventions

General

TypeScript — strict mode. Avoid any unless absolutely necessary
React — functional components with hooks. No class components
CSS — Tailwind utility classes + a single src/index.css for custom styles
State management — Zustand for global state, useReducer for complex local state
Comments — default to none. Only annotate non-obvious why — hidden constraints, surprising invariants, workarounds for specific bugs

Formatting & Linting

The project uses Prettier for formatting and ESLint for linting:

# Format code
bun run format

# Check for lint issues
bun run lint

Atelier Rulebook

Design-related contributions should respect the atelier/ rulebook files:

atelier/
  typography.md       — Font stack, sizes, line heights
  color.md            — Palette, contrast, usage
  animation.md        — Motion principles and timing
  accessibility.md    — ARIA, keyboard, color contrast
  anti-ai-slop.md     — Quality standards for AI-generated output
  form-validation.md  — Validation patterns
  state-coverage.md   — UI state requirements
  rtl-and-bidi.md     — Right-to-left and bidirectional support

中文

编码规范

通用

TypeScript — 严格模式。除非绝对必要，否则避免使用 any
React — 使用 hooks 的函数组件。无类组件
CSS — Tailwind 工具类 + 单个 src/index.css 用于自定义样式
状态管理 — Zustand 用于全局状态，useReducer 用于复杂的局部状态
注释 — 默认为无。仅注释非显而易见的原因——隐藏约束、令人惊讶的不变量、特定错误的解决方法

格式化和检查

项目使用 Prettier 进行格式化，ESLint 进行检查：

# 格式化代码
bun run format

# 检查 lint 问题
bun run lint

Atelier 规则手册

与设计相关的贡献应尊重 atelier/ 规则手册文件：

atelier/
  typography.md       — 字体栈、大小、行高
  color.md            — 调色板、对比度、使用
  animation.md        — 动效原则和时序
  accessibility.md    — ARIA、键盘、色彩对比度
  anti-ai-slop.md     — AI 生成内容的质量标准
  form-validation.md  — 验证模式
  state-coverage.md   — UI 状态要求
  rtl-and-bidi.md     — 从右到左和双向支持

Testing

Critical User Journey (CUJ)

The load-bearing test is the CUJ suite at web/tests/e2e/cuj.spec.ts. Any change that plausibly affects routes, onboarding, canvas, or chat must keep it green.

# Run the full journey suite
bun run journeys

E2E Tests

Additional Playwright specs live in web/tests/e2e/:

# Run all E2E tests (excludes journeys)
bun run test:e2e

# Run a specific test file
bunx playwright test web/tests/e2e/cuj.spec.ts

Evidence Pipeline

When opening a PR, include evidence of testing:

Run bun run journeys to generate video/screenshot evidence
The pr-evidence skill will inject the evidence block into your PR body
Evidence is uploaded as GitHub user-attachments and displayed inline

中文

测试

关键用户旅程（CUJ）

负载测试是 web/tests/e2e/cuj.spec.ts 中的 CUJ 套件。任何可能影响路由、入门流程、画布或聊天的更改都必须保持其通过。

# 运行完整的旅程套件
bun run journeys

E2E 测试

其他 Playwright 规范位于 web/tests/e2e/：

# 运行所有 E2E 测试（不包括旅程）
bun run test:e2e

# 运行特定测试文件
bunx playwright test web/tests/e2e/cuj.spec.ts

证据管道

打开 PR 时，包含测试证据：

运行 bun run journeys 生成视频/截图证据
pr-evidence 技能将证据块注入你的 PR 正文
证据作为 GitHub 用户附件上传并内联显示

Dev-Time Skills

The repo includes automated skills for contributors under .claude/skills/. These are auto-discovered by Claude Code and OpenCode.

Skill	Purpose
`ship-task`	Full contributor loop: understand → implement → verify → commit → PR
`verify-with-playwright`	Per-task browser verification with evidence capture
`semantic-commit`	Drafts Conventional Commits messages
`pr-evidence`	Injects inline evidence block into PR body
`cuj-guardian`	Runs and triages the CUJ suite on every PR change
`frontend-design`	Aesthetic + convention guide for host app chrome
`canvas-sync`	DesignCanvas parity enforcement across canonical/mirror/host
`grill-me`	Code review critique skill

中文

开发时技能

仓库在 .claude/skills/ 下包含供贡献者使用的自动化技能。这些技能会被 Claude Code 和 OpenCode 自动发现。

技能	用途
`ship-task`	完整贡献循环：理解 → 实现 → 验证 → 提交 → PR
`verify-with-playwright`	逐任务浏览器验证和证据捕获
`semantic-commit`	起草 Conventional Commits 消息
`pr-evidence`	将内联证据块注入 PR 正文
`cuj-guardian`	在每个 PR 更改时运行和分类 CUJ 套件
`frontend-design`	主机应用界面的美学和约定指南
`canvas-sync`	DesignCanvas 在规范/镜像/主机中的一致性强制
`grill-me`	代码审查技能

The `ship-task` Workflow

The ship-task skill orchestrates the full contributor loop:

Understand — read the issue, quote acceptance criteria, confirm understanding
Implement — make the minimum change needed. No drive-by refactors
Verify — run verify-with-playwright for browser-based testing with evidence
Blast-radius check — forced-format regression report with:
- All importers/call sites of changed code
- Data-flow paths affected
- Non-local effects (config, types, exports, tests)
- Verdict: SAFE, SHALLOW, or DEEP
Commit — use semantic-commit to draft a proper commit message
PR — push and open a PR with the pr-evidence template

中文

ship-task 工作流程

ship-task 技能编排完整的贡献循环：

理解 — 阅读 issue，引用验收标准，确认理解
实现 — 进行最小必要的更改。不进行附带重构
验证 — 运行 verify-with-playwright 进行基于浏览器的测试和证据捕获
影响范围检查 — 强制格式的回归报告，包括：
- 更改代码的所有导入者/调用点
- 受影响的数据流路径
- 非局部影响（配置、类型、导出、测试）
- verdict：SAFE、SHALLOW 或 DEEP
提交 — 使用 semantic-commit 起草合适的提交消息
PR — 推送并使用 pr-evidence 模板打开 PR

Need Help?

Discord: discord.gg/aiatelie
GitHub Discussions: github.com/aiatelie/ai-atelie/discussions
File an issue: github.com/aiatelie/ai-atelie/issues/new

中文

需要帮助？

Discord：discord.gg/aiatelie
GitHub Discussions：github.com/aiatelie/ai-atelie/discussions
提交 issue：github.com/aiatelie/ai-atelie/issues/new

Uh oh!

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History

CONTRIBUTING.md

File metadata and controls

Contributing to AI Atelier

为 AI Atelier 做贡献

Table of Contents

目录

How to Contribute

如何贡献

Prerequisites

前置条件

Setting Up Agent CLI Integration

Claude Code

OpenCode

Other Agents

设置智能体 CLI 集成

Claude Code

OpenCode

其他智能体

Setting Up Locally

本地设置

Git Branching & Commit Style

Branch Naming

Commit Style

Git 分支与提交风格

分支命名

提交风格

Pull Request Workflow

Pull Request 工作流程

Coding Conventions

General

Formatting & Linting

Atelier Rulebook

编码规范

通用

格式化和检查

Atelier 规则手册

Testing

Critical User Journey (CUJ)

E2E Tests

Evidence Pipeline

测试

关键用户旅程（CUJ）

E2E 测试

证据管道

Dev-Time Skills

开发时技能

The ship-task Workflow

ship-task 工作流程

Need Help?

需要帮助？

The `ship-task` Workflow