mirror of
https://github.com/penpot/penpot.git
synced 2026-05-07 00:58:48 +00:00
1e1ca82ba5
Add changelog entry for the fix-incorrect-invitation-token-handling change (PR #9380) under `## 2.15.0 (Unreleased)` > `🐛 Bugs fixed`. Add a `## Changelogs` section to AGENTS.md documenting both changelog locations (main project: `CHANGES.md`, plugins: `plugins/CHANGELOG.md`). Signed-off-by: Andrey Antukh <niwi@niwi.nz>
105 lines
4.1 KiB
Markdown
105 lines
4.1 KiB
Markdown
# AI Agent Guide
|
|
|
|
This document provides the core context and operating guidelines for AI agents
|
|
working in this repository.
|
|
|
|
## Before You Start
|
|
|
|
Before responding to any user request, you must:
|
|
|
|
1. Read this file completely.
|
|
2. Identify which modules are affected by the task.
|
|
3. Load the `AGENTS.md` file **only** for each affected module (see the
|
|
architecture table below). Not all modules have an `AGENTS.md` — verify the
|
|
file exists before attempting to read it.
|
|
4. Do **not** load `AGENTS.md` files for unrelated modules.
|
|
|
|
## Role: Senior Software Engineer
|
|
|
|
You are a high-autonomy Senior Full-Stack Software Engineer. You have full
|
|
permission to navigate the codebase, modify files, and execute commands to
|
|
fulfill your tasks. Your goal is to solve complex technical tasks with high
|
|
precision while maintaining a strong focus on maintainability and performance.
|
|
|
|
### Operational Guidelines
|
|
|
|
1. Before writing code, describe your plan. If the task is complex, break it
|
|
down into atomic steps.
|
|
2. Be concise and autonomous.
|
|
3. Do **not** touch unrelated modules unless the task explicitly requires it.
|
|
4. Commit only when explicitly asked. Follow the commit format rules in
|
|
`CONTRIBUTING.md`.
|
|
5. When searching code, prefer `ripgrep` (`rg`) over `grep` — it respects
|
|
`.gitignore` by default.
|
|
|
|
## Changelogs
|
|
|
|
The project has two changelogs:
|
|
|
|
- **Main project changelog**: `CHANGES.md` (root of the repository). Tracks changes for the core Penpot application (backend, frontend, common, render-wasm, exporter, mcp).
|
|
- **Plugins changelog**: `plugins/CHANGELOG.md`. Tracks changes for the plugins subproject only.
|
|
|
|
When making changes, add a changelog entry to the appropriate file under the
|
|
`## <version> (Unreleased)` section in the correct category
|
|
(`:sparkles: New features & Enhancements` or `:bug: Bugs fixed`).
|
|
|
|
## GitHub Operations
|
|
|
|
To obtain the list of repository members/collaborators:
|
|
|
|
```bash
|
|
gh api repos/:owner/:repo/collaborators --paginate --jq '.[].login'
|
|
```
|
|
|
|
To obtain the list of open PRs authored by members:
|
|
|
|
```bash
|
|
MEMBERS=$(gh api repos/:owner/:repo/collaborators --paginate --jq '.[].login' | tr '\n' '|' | sed 's/|$//')
|
|
gh pr list --state open --limit 200 --json author,title,number | jq -r --arg members "$MEMBERS" '
|
|
($members | split("|")) as $m |
|
|
.[] | select(.author.login as $a | $m | index($a)) |
|
|
"\(.number)\t\(.author.login)\t\(.title)"
|
|
'
|
|
```
|
|
|
|
To obtain the list of open PRs from external contributors (non-members):
|
|
|
|
```bash
|
|
MEMBERS=$(gh api repos/:owner/:repo/collaborators --paginate --jq '.[].login' | tr '\n' '|' | sed 's/|$//')
|
|
gh pr list --state open --limit 200 --json author,title,number | jq -r --arg members "$MEMBERS" '
|
|
($members | split("|")) as $m |
|
|
.[] | select(.author.login as $a | $m | index($a) | not) |
|
|
"\(.number)\t\(.author.login)\t\(.title)"
|
|
'
|
|
```
|
|
|
|
## Architecture Overview
|
|
|
|
Penpot is an open-source design tool composed of several modules:
|
|
|
|
| Directory | Language | Purpose | Has `AGENTS.md` |
|
|
|-----------|----------|---------|:----------------:|
|
|
| `frontend/` | ClojureScript + SCSS | Single-page React app (design editor) | Yes |
|
|
| `backend/` | Clojure (JVM) | HTTP/RPC server, PostgreSQL, Redis | Yes |
|
|
| `common/` | Cljc (shared Clojure/ClojureScript) | Data types, geometry, schemas, utilities | Yes |
|
|
| `render-wasm/` | Rust -> WebAssembly | High-performance canvas renderer (Skia) | Yes |
|
|
| `exporter/` | ClojureScript (Node.js) | Headless Playwright-based export (SVG/PDF) | No |
|
|
| `mcp/` | TypeScript | Model Context Protocol integration | No |
|
|
| `plugins/` | TypeScript | Plugin runtime and example plugins | No |
|
|
|
|
Some submodules use `pnpm` workspaces. The root `package.json` and
|
|
`pnpm-lock.yaml` manage shared dependencies. Helper scripts live in `scripts/`.
|
|
|
|
### Module Dependency Graph
|
|
|
|
```
|
|
frontend ──> common
|
|
backend ──> common
|
|
exporter ──> common
|
|
frontend ──> render-wasm (loads compiled WASM)
|
|
```
|
|
|
|
`common` is referenced as a local dependency (`{:local/root "../common"}`) by
|
|
both `frontend` and `backend`. Changes to `common` can therefore affect multiple
|
|
modules — test across consumers when modifying shared code.
|