diff --git a/.opencode/agents/commiter.md b/.opencode/agents/commiter.md index 51d74710f5..202e4fde04 100644 --- a/.opencode/agents/commiter.md +++ b/.opencode/agents/commiter.md @@ -1,6 +1,6 @@ --- name: commiter -description: Git commit assistant following CONTRIBUTING.md commit rules +description: Git commit assistant mode: all --- @@ -15,16 +15,11 @@ including the rationale if proceed. * Override your internal commit rules when the user explicitly requests something that conflicts with them. -* Read `CONTRIBUTING.md` before creating any commit and follow the - commit guidelines strictly. -* Use commit messages in the form `:emoji: `. -* Keep the subject capitalized, concise, 70 characters or fewer, and - without a trailing period. +* Read `.serena/memories/workflows/creating-commits.md` before + creating any commit and follow the commit guidelines strictly. * Keep the description (commit body) with maximum line length of 80 characters. Use manual line breaks to wrap text before it exceeds this limit. -* Separate the subject from the body with a blank line. -* Write a clear and concise body when needed. * Use `git commit -s` so the commit includes the required `Signed-off-by` line. * Do not guess or hallucinate git author information (Name or diff --git a/.opencode/agents/engineer.md b/.opencode/agents/engineer.md index b5ba1bf3f7..9857ba9d2a 100644 --- a/.opencode/agents/engineer.md +++ b/.opencode/agents/engineer.md @@ -1,37 +1,25 @@ --- -name: Penpot Engineer +name: Engineer description: Senior Full-Stack Software Engineer mode: primary --- -Role: You are a high-autonomy Senior Full-Stack Software Engineer working on -Penpot, an open-source design tool. 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. +## Role -Tech stack: Clojure (backend), ClojureScript (frontend/exporter), Rust/WASM -(render-wasm), TypeScript (plugins/mcp), SCSS. +You are a high-autonomy Senior Full-Stack Software Engineer working on Penpot, an +open-source design tool. 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. -Requirements: +## Before Start -* Read the root `AGENTS.md` to understand the repository and application - architecture. Then read the `AGENTS.md` **only** for each affected module. - Not all modules have one — verify before reading. -* Before writing code, analyze the task in depth and describe your plan. If the - task is complex, break it down into atomic steps. -* When searching code, prefer `ripgrep` (`rg`) over `grep` — it respects - `.gitignore` by default. +**Read `AGENTS.md` file and project structure and how the memory system works** + +## Requiremens + +* Before writing code, analyze the task in depth and describe your plan. If the task is + complex, break it down into atomic steps. * Do **not** touch unrelated modules unless the task explicitly requires it. * Only reference functions, namespaces, or APIs that actually exist in the codebase. Verify their existence before citing them. If unsure, search first. * Be concise and autonomous — avoid unnecessary explanations. -* After making changes, run the applicable lint and format checks for the - affected module before considering the work done (see module `AGENTS.md` for - exact commands). -* Make small and logical commits following the commit guideline described in - `CONTRIBUTING.md`. Commit only when explicitly asked. -- Do not guess or hallucinate git author information (Name or Email). Never include the - `--author` flag in git commands unless specifically instructed by the user for a unique - case; assume the local environment is already configured. Allow git commit to - automatically pull the identity from the local git config `user.name` and `user.email`. diff --git a/.opencode/agents/planner.md b/.opencode/agents/planner.md index ff838d77a5..8ced366d34 100644 --- a/.opencode/agents/planner.md +++ b/.opencode/agents/planner.md @@ -1,13 +1,11 @@ --- -name: Penpot Planner +name: Planner description: Software architect for planning and analysis only mode: primary permission: edit: ask --- -# Penpot Planner - ## Role You are a Senior Software Architect working on Penpot, an open-source design @@ -29,10 +27,8 @@ or problem domain. Assume they don't know good test design very well. ## Requirements * Analyze the codebase architecture and identify affected modules. -* Read `AGENTS.md` files (root and per-module) to understand structure and - conventions. -* Search code using `ripgrep` skill (`rg`) to trace dependencies, find patterns, - and understand existing implementations. +* Read `AGENTS.md` file and project structure and how the memory system works and how to + navigate and read relevant information conventions. * Break down complex features or bugs into atomic, actionable steps. * Propose solutions with clear rationale, trade-offs, and sequencing. * Identify risks, edge cases, and testing considerations. diff --git a/.opencode/agents/prompt-assistant.md b/.opencode/agents/prompt-assistant.md index 9e6141e768..dddcbd1c3f 100644 --- a/.opencode/agents/prompt-assistant.md +++ b/.opencode/agents/prompt-assistant.md @@ -4,8 +4,6 @@ description: Refines and improves prompts for maximum clarity and effectiveness mode: all --- -# Prompt Assistant - ## Role You are an expert Prompt Engineer with strong knowledge of @@ -15,15 +13,14 @@ well-structured version possible — ready to be used with any AI model. ## Requirements -* You do NOT execute tasks. You do NOT write code. You only design and - refine prompts -* Read the root `AGENTS.md` to understand the repository and application - architecture. Then read the `AGENTS.md` **only** for each affected module. -* Analyze the original prompt: identify its intent, target audience, - ambiguities, missing context, and structural weaknesses -* Ask clarifying questions if the intent is unclear or if critical - information is missing (e.g. target model, expected output format, - tone, constraints). Keep questions concise and grouped +* You do NOT execute tasks. You do NOT write code. You only design and refine prompts +* Read `AGENTS.md` file and project structure and how the memory system works and how to + navigate and read relevant information conventions. +* Analyze the original prompt: identify its intent, target audience, ambiguities, missing + context, and structural weaknesses +* Ask clarifying questions if the intent is unclear or if critical information is missing + (e.g. target model, expected output format, tone, constraints). Keep questions concise + and grouped * Rewrite the prompt using prompt engineering best practices diff --git a/.serena/memories/backend/core.md b/.serena/memories/backend/core.md index e7f3936c3a..65f513e17c 100644 --- a/.serena/memories/backend/core.md +++ b/.serena/memories/backend/core.md @@ -2,7 +2,11 @@ Backend: JVM Clojure; Integrant; PostgreSQL; Redis/Valkey; RPC; HTTP; storage; mail; audit/logging; workers. -Focused routing: RPC/DB/workers -> `mem:backend/rpc-db-worker-subtleties`; HTTP/session/storage/media/file-data -> `mem:backend/http-storage-filedata-subtleties`; auth/permissions/product domains -> `mem:backend/auth-permissions-product-domains`. +## Focused memories + +- RPC, DB helpers, workers, cron: `mem:backend/rpc-db-worker-subtleties` +- HTTP sessions, config, storage, media, file data persistence: `mem:backend/http-storage-filedata-subtleties` +- Auth flows, permission model, teams, projects, invitations, comments, webhooks, audit: `mem:backend/auth-permissions-product-domains` ## Stable namespace map @@ -16,7 +20,7 @@ Focused routing: RPC/DB/workers -> `mem:backend/rpc-db-worker-subtleties`; HTTP/ - `app.worker`: task execution/cron plumbing. - `app.main`: Integrant system map and component wiring. - `app.config`: `PENPOT_*` env config and feature flags. -- `app.srepl.*`: development REPL helpers for manual backend operations. +- `app.srepl.*`: development REPL helpers for manual backend operations (data inspection, migration helpers, one-off admin tasks). - `app.nitrate`, `app.rpc.commands.nitrate`, and `app.rpc.management.nitrate`: external Nitrate subscription/organization integration, gated by the `:nitrate` feature flag and shared-key HTTP calls. ## RPC conventions @@ -32,32 +36,65 @@ Backend RPC command areas without focused memories include access tokens, binfil - Use `db/run!` for multiple operations on one connection. - Use `db/tx-run!` for transactions. -Development DB: `postgresql://penpot:penpot@postgres/penpot`. -Test DB: `postgresql://penpot:penpot@postgres/penpot_test`. Database migrations live in `backend/src/app/migrations/`; pure SQL migrations are under `backend/src/app/migrations/sql/`. SQL filenames conventionally start with a sequence and verb/table description, e.g. `0026-mod-profile-table-add-is-active-field`. Applied migrations are tracked in the `migrations` table. -To inspect the whole DB schema in devenv, use `pg_dump -h postgres -s > schema.sql` from inside the environment. +For deeper details on transaction semantics, advisory locks, Transit vs JSON helpers, and dev/test DB URLs: `mem:backend/rpc-db-worker-subtleties`. ## Background tasks A task handler is an Integrant component with `ig/assert-key`, `ig/expand-key`, and `ig/init-key`, returning the function run by the worker. New tasks also need wiring in `app.main`: handler config, worker registry entry, and cron entry if scheduled. -## REPL and fixtures +For worker dispatch, cron, retry semantics, deduplication, and queue internals: `mem:backend/rpc-db-worker-subtleties`. -In devenv, backend nREPL is exposed on port 6064. `backend/scripts/nrepl` starts a REPLy client. +## REPL -For an in-process backend REPL, stop the running backend first so port 9090 is free, then run `backend/scripts/repl`. Useful top-level helpers include `(start)`, `(stop)`, `(restart)`, `(run-tests)`, and `(repl/refresh-all)`. Many `app.srepl.main` helpers accept the global `system` var, e.g. manual email or maintenance operations. +In devenv, backend nREPL is exposed on port 6064. + +### Non-interactive eval (preferred for agents) + +`./tools/nrepl-eval.mjs` connects to an already-running nREPL server and evaluates code. Session state (defs, `in-ns`) persists across invocations via a stored session ID in `/tmp/penpot-nrepl-session--`. + +```bash +./tools/nrepl-eval.mjs '(+ 1 2)' # single expression +./tools/nrepl-eval.mjs "(require '[my.ns :as ns] :reload)" # reload after edits +./tools/nrepl-eval.mjs -e # inspect last exception (*e) +./tools/nrepl-eval.mjs --reset-session '(def x 0)' # discard session, start fresh +./tools/nrepl-eval.mjs <<'EOF' # multi-expression heredoc +(def x 10) +(+ x 20) +EOF +``` + +Default port is 6064. Use `-p ` for a different port. Use `-t ` to override the 120s timeout. Do not start the nREPL server — assume it is already running. + +### Interactive REPL + +`backend/scripts/nrepl` starts a REPLy client connected to the running nREPL. + +For an in-process backend REPL (where you control the JVM lifecycle), stop the running backend first so port 9090 is free, then run `backend/scripts/repl`. Useful top-level helpers include `(start)`, `(stop)`, `(restart)`, `(run-tests)`, and `(repl/refresh-all)`. Many `app.srepl.main` helpers accept the global `system` var, e.g. manual email or maintenance operations. + +## Fixtures Fixtures can populate local data for manual testing/perf work. From the backend REPL, run `(app.cli.fixtures/run {:preset :small})`; fixture users conventionally look like `profileN@example.com` with password `123123`. Standalone fixture aliases may exist, but check current `backend/deps.edn` before relying on old command names. -## Commands +## Performance -From `backend/`: -- Focused test: `clojure -M:dev:test --focus backend-tests.some-ns-test`. -- Full backend test suite: `clojure -M:dev:test` or `pnpm run test`. -- Watch/focused testing is also available through `(run-tests ...)` in the backend REPL. -- Lint: `pnpm run lint`. -- Format check: `pnpm run check-fmt`. -- Format fix: `pnpm run fmt`. +* **Type Hinting:** Use explicit JVM type hints (e.g. `^String`, `^long`) in performance-critical paths to avoid reflection overhead. +* **Batch inserts:** Use `db/insert-many!` for bulk row inserts — generates a single SQL with multiple parameter tuples. Avoid on very large datasets (SQL length / parameter count limits). +* **Server-side cursors:** Use `db/plan` (fetch-size 1000, forward-only, read-only) or `db/cursor` for large result sets. Never fetch large collections into memory at once. +* **Transaction discipline:** Use `tx-run!` for writes (opens a transaction), `run!` for reads (single connection, no transaction). Set `:read-only` on `tx-run!` when applicable to let PostgreSQL optimize. -Use JVM type hints in performance-critical paths to avoid reflection. \ No newline at end of file +## Lint and Format + +IMPORTANT: all CLI commands must be executed from the `backend/` subdirectory. + +* **Linting:** `pnpm run lint` from the repository root. +* **Formatting:** `pnpm run check-fmt`. Use `pnpm run fmt` to fix. Avoid unrelated whitespace diffs. + +## Testing + +IMPORTANT: all CLI commands must be executed from the `backend/` subdirectory. + +* **Coverage:** If code is added or modified in `src/`, corresponding tests in `test/backend_tests/` must be added or updated. +* **Isolated run:** `clojure -M:dev:test --focus backend-tests.my-ns-test` for a specific test namespace. +* **Regression run:** `clojure -M:dev:test` to ensure no regressions in related functional areas. diff --git a/.serena/memories/critical-info.md b/.serena/memories/critical-info.md index 142d303310..008b611b8b 100644 --- a/.serena/memories/critical-info.md +++ b/.serena/memories/critical-info.md @@ -12,24 +12,30 @@ You are working on the GitHub project `penpot/penpot`, a monorepo. - Commit only when explicitly asked. Commit/PR format + changelog: `mem:workflow/creating-commits`, `mem:workflow/creating-prs`. - You have access to the GitHub CLI `gh` or corresponding MCP tools. - Issues are also managed on Taiga. Read issues using the `read_taiga_issue` tool. +- Before writing code, analyze the task in depth and describe your plan. If the task is complex, break it down into atomic steps. +* After making changes, run the applicable lint and format checks for the affected module before considering the work done (per example `mem:backend/core` or `mem:frontend/core`). + # Project modules This is a monorepo. Principles that apply to one module do *not* generally apply to others. Do not make assumptions. -- `frontend/`: ClojureScript + SCSS SPA/design editor. -- `backend/`: JVM Clojure HTTP/RPC server with PostgreSQL, Redis, storage, mail, and workers. -- `common/`: shared CLJC data types, geometry, schemas, file/change logic, and utilities. -- `render-wasm/`: Rust -> WebAssembly Skia renderer consumed by frontend. -- `exporter/`: ClojureScript/Node headless Playwright SVG/PDF export. -- `mcp/`: TypeScript Model Context Protocol integration. -- `plugins/`: TypeScript plugin runtime/examples and Plugin API types. -- `library/`: design library workflows. -- `docs/`: documentation site. +- `frontend/`: ClojureScript + SCSS SPA/design editor. +- `backend/`: JVM Clojure HTTP/RPC server with PostgreSQL, Redis, storage, mail, and workers. +- `common/`: shared CLJC data types, geometry, schemas, file/change logic, and utilities. +- `render-wasm/`: Rust -> WebAssembly Skia renderer consumed by frontend. +- `exporter/`: ClojureScript/Node headless Playwright SVG/PDF export. +- `mcp/`: TypeScript Model Context Protocol integration. +- `plugins/`: TypeScript plugin runtime/examples and Plugin API types. +- `library/`: design library workflows. +- `docs/`: documentation site. + +The memory is structured in a way that you can get the critical information about the +module. You can read it from `mem:/core` # Low-centrality project paths -- `docker/` contains devenv related code, not needed unless specifically instructed. +- `docker/` contains devenv related code, not needed unless specifically instructed. More info in docs/technical-guide if instructed to work on this. - `experiments/` contains standalone experimental HTML/JS/scripts; treat it as non-core unless the user explicitly asks about it. - `sample_media/` contains sample image/icon media and config used as fixtures/demo material; do not infer app behavior from it. @@ -49,6 +55,6 @@ semantics change. ## Detecting Crashes -The Penpot frontend can crash silently from the JS API's perspective: `execute_code` calls return successfully, but 1-2s later the workspace becomes unusable (Internal Error page). +The Penpot frontend can crash silently from the JS API's perspective: `execute_code` calls return successfully, but 1-2s later the workspace becomes unusable (Internal Error page). The `execute_code` tool then stops working, but `cljs_repl` still works. Use it to detect a crash via `(some? (:exception @app.main.store/state))`. For details on handling crashes, read memory `mem:frontend/handling-crashes`. diff --git a/.serena/memories/frontend/core.md b/.serena/memories/frontend/core.md index f37b50b172..7e0638ece2 100644 --- a/.serena/memories/frontend/core.md +++ b/.serena/memories/frontend/core.md @@ -14,6 +14,18 @@ Frontend: CLJS SPA; React/Rumext; Potok; RxJS; okulary refs; SCSS modules; share - `frontend/packages/*` and `frontend/text-editor`: JS/TS workspace packages consumed by the app. - Nitrate subscription/organization UI and flows live under `app.main.data.nitrate` and `app.main.ui.nitrate*`; backend/API behavior is covered by backend memories, and shared permission rules are in `common/src/app/common/types/nitrate_permissions.cljc`. + +## Lint and Format + +From `frontend/`: + +- CLJ/CLJS lint: `pnpm run lint:clj`. +- JS lint currently no-ops via `pnpm run lint:js`. +- SCSS lint: `pnpm run lint:scss`. +- Format checks: `pnpm run check-fmt:clj`, `pnpm run check-fmt:js`, `pnpm run check-fmt:scss`. +- Format fix: `pnpm run fmt`, or targeted `fmt:clj` / `fmt:js` / `fmt:scss`. +- Translation formatting after i18n edits: `pnpm run translations`. + ## Focused memory routing UI and packages: @@ -34,9 +46,9 @@ Diagnostics and validation: - Runtime inspection and navigation: `mem:frontend/cljs-repl`. - Source-edit compile/hot-reload diagnostics: `mem:frontend/compile-diagnostics`. - Runtime crash recovery: `mem:frontend/handling-crashes`. -- Tests, lint, format, and live verification: `mem:frontend/testing`. +- Tests and live verification: `mem:frontend/testing`. - Real pointer/keyboard gesture reproduction: `mem:frontend/playwright-gestures`. ## Areas without focused memories -These frontend areas currently have no dedicated Serena memory beyond this architecture entry and nearby source/tests: clipboard, drawing tools, boolean/path operations, interactions/prototyping, color/style asset management, grid-layout editing UI, comments UI, fonts UI, and many dashboard/settings subflows. Treat work there as less memory-covered and inspect source/tests more carefully. \ No newline at end of file +These frontend areas currently have no dedicated Serena memory beyond this architecture entry and nearby source/tests: clipboard, drawing tools, boolean/path operations, interactions/prototyping, color/style asset management, grid-layout editing UI, comments UI, fonts UI, and many dashboard/settings subflows. Treat work there as less memory-covered and inspect source/tests more carefully. diff --git a/.serena/memories/frontend/testing.md b/.serena/memories/frontend/testing.md index 30c32e2fef..a4e3b8f6df 100644 --- a/.serena/memories/frontend/testing.md +++ b/.serena/memories/frontend/testing.md @@ -28,18 +28,8 @@ Integration tests fake backend behavior by intercepting network/websocket traffi Locator priority should follow user-facing semantics: `getByRole`, `getByLabel`, `getByPlaceholder`, `getByText`, then semantic alternatives such as alt/title, with `getByTestId` as the last resort. Name tests from the user's perspective and prefer positive, single-purpose assertions. -## Lint and format - -From `frontend/`: -- CLJ/CLJS lint: `pnpm run lint:clj`. -- JS lint currently no-ops via `pnpm run lint:js`. -- SCSS lint: `pnpm run lint:scss`. -- Format checks: `pnpm run check-fmt:clj`, `pnpm run check-fmt:js`, `pnpm run check-fmt:scss`. -- Format fix: `pnpm run fmt`, or targeted `fmt:clj` / `fmt:js` / `fmt:scss`. -- Translation formatting after i18n edits: `pnpm run translations`. - ## Live browser verification Because CLJC compiles to both JVM and CLJS, JVM/common tests can miss frontend-only state caused by browser runtime, WASM modifier math, or real pointer events. Use `mem:frontend/cljs-repl` to inspect live app state and `mem:frontend/playwright-gestures` when real input is needed. -For stale hot reload or failed CLJ/CLJC/CLJS source builds, read `mem:frontend/compile-diagnostics`. For Internal Error pages or delayed runtime crashes after automation/API actions, read `mem:frontend/handling-crashes`. Translation `.po` changes are bundled into `index.html` and require a browser refresh. \ No newline at end of file +For stale hot reload or failed CLJ/CLJC/CLJS source builds, read `mem:frontend/compile-diagnostics`. For Internal Error pages or delayed runtime crashes after automation/API actions, read `mem:frontend/handling-crashes`. Translation `.po` changes are bundled into `index.html` and require a browser refresh. diff --git a/.serena/memories/workflow/creating-commits.md b/.serena/memories/workflow/creating-commits.md index 43298e88d0..1ff2916b8e 100644 --- a/.serena/memories/workflow/creating-commits.md +++ b/.serena/memories/workflow/creating-commits.md @@ -2,6 +2,12 @@ Commit only on explicit request. Before commit: `git status`; exclude unrelated user changes. +Do not guess or hallucinate git author information (Name or Email). Never include the +`--author` flag in git commands unless specifically instructed by the user for a unique +case; assume the local environment is already configured. Allow git commit to +automatically pull the identity from the local git config `user.name` and `user.email`. + + ## Message Format ``` @@ -16,17 +22,19 @@ Co-authored-by: `:bug:` bug fix · `:sparkles:` enhancement · `:tada:` new feature · `:recycle:` refactor · `:lipstick:` cosmetic · `:ambulance:` critical fix · `:books:` docs · `:construction:` WIP · `:boom:` breaking · `:wrench:` config · `:zap:` perf · `:whale:` docker · `:paperclip:` other · `:arrow_up:` dep upgrade · `:arrow_down:` dep downgrade · `:fire:` removal · `:globe_with_meridians:` translations · `:rocket:` epic/highlight + ## Changelogs +**IMPORTANT:** do not modify the changelog unless it explicitly asked. + For user-facing or notable changes, update the relevant changelog under the unreleased section: - Main app/modules (`backend`, `frontend`, `common`, `render-wasm`, `exporter`, `mcp`): root `CHANGES.md`. - Plugin subproject changes: `plugins/CHANGELOG.md`. -Entry format uses the matching category (`:sparkles:`, `:bug:`, etc.) and references the GitHub issue or Taiga story when available: +Entry format uses the matching category (`:sparkles:`, `:bug:`, etc.) and references the GitHub issue: ``` -- Description of change [Github #NNNN](https://github.com/penpot/penpot/issues/NNNN) -- Description of change [Taiga #NNNN](https://tree.taiga.io/project/penpot/us/NNNN) +- Short description of change [#NNNN](https://github.com/penpot/penpot/issues/NNNN) ``` -Plugin API changelog prefixes: type/signature -> `**plugin-types:**`; runtime behavior -> `**plugin-runtime:**` in `plugins/CHANGELOG.md`. \ No newline at end of file +Plugin API changelog prefixes: type/signature -> `**plugin-types:**`; runtime behavior -> `**plugin-runtime:**` in `plugins/CHANGELOG.md`. diff --git a/AGENTS.md b/AGENTS.md index 33bd1b0ebb..08103521e0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,79 @@ -CRITICAL: Read `.serena/memories/critical-info.md` NOW for important project information and instructions. +# AI AGENT GUIDE -In general, information about this project is stored in memories located in `.serena/memories/`. -Memories reference other memories via `mem:name` (e.g. `mem:foo/bar` maps to `.serena/memories/foo/bar.md`). +## CRITICAL: Read module memories BEFORE writing any code -NOTE: When not using the Penpot agentic devenv, some tools mentioned in the memories will be unavailable. +Do this **before planning, before coding, before touching any file**: + +1. Read `critical-info` (use `serena_read_memory critical-info` or read `.serena/memories/critical-info.md`). + It describes the project structure and tells you which modules exist. +2. From `critical-info`, identify which modules your task affects. +3. Read each affected module's **core memory** — the name is `/core` + (e.g. `frontend/core`, `backend/core`, `common/core`). +4. If the core memory references deeper `mem:` memories relevant to your task, read those too. + +**STOP: Do not proceed until you have read the core memory of every affected module.** +Skipping this step is the #1 cause of incorrect or incomplete work. + +--- + +# Memory system + +Memories are the **primary project guidance** — not docs or readme files. +They are dense, agent-oriented notes: terse bullets, invariants, no prose. + +## Entry point + +Start at `critical-info` (the graph root). It describes the project structure, +module dependency graph, and references section-level core memories. + +## Progressive discovery model + +Memories form a **reference graph**, not a flat list: + +``` +critical-info ← read first (graph root) + └─
/core ← top-level memory per section (e.g. frontend/core, backend/core) + └─ ← focused memories (e.g. frontend/handling-errors-and-debugging) + └─ ... ← deeper memories as needed +``` + +When working on a task: +1. Read `critical-info` to identify which sections are affected. +2. Read the affected section's `core` memory for an overview. +3. Follow `mem:` references in the core memory to focused memories relevant to your task. +4. Continue following references deeper as needed. + +## Accessing memories + +- **If `serena_read_memory` / `serena_list_memories` tools are available**: use them. + `serena_read_memory` takes a memory name (e.g. `critical-info`, `frontend/core`). +- **If tools are NOT available**: read the filesystem directly. + Memory name `mem:foo/bar` maps to file `.serena/memories/foo/bar.md`. + +## Cross-reference convention + +Memories reference other memories with `mem:
/` inside backticks. +Example: `mem:common/changes-architecture`. +When you encounter a `mem:` reference relevant to your task, read that memory next. + +## Topic/folder organization + +Memories are grouped into folders that mirror project modules or topics: +`backend/`, `common/`, `frontend/`, `render-wasm/`, `exporter/`, `workflow/`, etc. +Each folder's top-level memory is `/core`. + +--- + +# 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. diff --git a/scripts/start-serena b/scripts/start-serena new file mode 100755 index 0000000000..c3fbb06247 --- /dev/null +++ b/scripts/start-serena @@ -0,0 +1,14 @@ +#!/usr/bin/env bash + +set -e + +CONTEXT="${CONTEXT:-copilot-cli}" + +while [[ $# -gt 0 ]]; do + case "$1" in + --context) CONTEXT="$2"; shift 2 ;; + *) echo "Unknown option: $1"; exit 1 ;; + esac +done + +serena start-mcp-server --transport streamable-http --port 14281 --project penpot --context "$CONTEXT" --host 0.0.0.0