Merge remote-tracking branch 'origin/staging' into develop

.agents/README.md

@@ -0,0 +1,90 @@
+# Agent skills
+
+This folder is the single home for the skills our coding agents use.
+Each skill is a folder with a `SKILL.md` inside — a short instruction
+manual that an agent loads only when it needs it.
+
+One copy serves every tool:
+
+- **opencode** reads this folder directly.
+- **Claude Code** reads it through the `.claude/skills` symlink.
+- **Codex** reads it directly.
+
+To change how the agents behave, edit the `SKILL.md` here. There is no
+second copy to keep in sync.
+
+## How the skills are organized
+
+**Flows** are the six skills you invoke by name. Each one covers one step
+in the life of a change: plan it, review the plan, implement it, review
+the code, open the pull request.
+
+**References** hold the quality standards. A flow's reviewer loads them;
+you rarely touch them directly.
+
+**Procedures** define how one concrete step is done — a plan document, an
+issue, a commit. Flows call them, but they also work on their own.
+
+**Utilities** are small helpers for everyday work: search, file lookup,
+JSON, REPL access, and so on.
+
+## Flows
+
+| Skill | What it does | When you would say |
+|---|---|---|
+| [`make-a-plan`](skills/make-a-plan/SKILL.md) | Researches the task, writes an implementation plan, asks you the open questions in plain language, and saves the plan to `.agents/plans/`. | "make a plan for the token refresh bug" |
+| [`review-plan`](skills/review-plan/SKILL.md) | Evaluates a plan before anyone writes code: completeness, ordering, risks. Approves it or asks for changes. | "review this plan before we start" |
+| [`implement-plan`](skills/implement-plan/SKILL.md) | Executes a ready plan and ends with one commit. Starting from a base branch (`main`, `develop`, `staging`), it first creates a GitHub issue and a matching `issue-NNNN` branch; already on a feature branch, it continues there without creating anything. | "implement the plan" |
+| [`review-code`](skills/review-code/SKILL.md) | Reviews a diff, branch, or PR and returns findings ranked by impact. | "review my changes before I push" |
+| [`create-pr`](skills/create-pr/SKILL.md) | Opens a pull request for the current branch — with checks on base branch, commits, issue, and push state — or updates an existing PR's title and description. | "open a PR for this branch" |
+| [`resolve-git-conflicts`](skills/resolve-git-conflicts/SKILL.md) | Untangles merge or rebase conflicts: explains both sides, proposes a resolution, applies it after you approve. Never runs `git rebase --continue`. | "resolve these conflicts" |
+
+## References
+
+| Skill | What it holds |
+|---|---|
+| [`plan-review-criteria`](skills/plan-review-criteria/SKILL.md) | The plan review rubric: six axes, severity levels, approval standard, output format. The `review-plan` reviewer loads it. |
+| [`code-review-criteria`](skills/code-review-criteria/SKILL.md) | The code review rubric: five axes, core principles (DRY, KISS, YAGNI), severity format, verdict. The `review-code` reviewer loads it. |
+
+## Procedures
+
+| Skill | What it does |
+|---|---|
+| [`planner`](skills/planner/SKILL.md) | The spec of a good plan: context, architecture decisions, tasks with acceptance criteria, checkpoints. Used by `make-a-plan`. |
+| [`create-issue`](skills/create-issue/SKILL.md) | Creates a GitHub issue that follows Penpot conventions. Used by `implement-plan`; also works on its own. |
+| [`create-commit`](skills/create-commit/SKILL.md) | Makes a commit the Penpot way: emoji subject, clear body, `AI-assisted-by` trailer. Used by `implement-plan`; also works alone when you say "commit this". |
+
+## Utilities
+
+| Skill | What it does |
+|---|---|
+| [`bat-cat`](skills/bat-cat/SKILL.md) | Read files in the terminal with syntax highlighting and line numbers. |
+| [`fd-find`](skills/fd-find/SKILL.md) | Find files by name or pattern, respecting `.gitignore`. |
+| [`ripgrep`](skills/ripgrep/SKILL.md) | Fast content search with regular expressions. |
+| [`jq-json-processor`](skills/jq-json-processor/SKILL.md) | Slice, filter, and reshape JSON output. |
+| [`nrepl-eval`](skills/nrepl-eval/SKILL.md) | Run Clojure or ClojureScript code in the live REPL sessions (backend and frontend). |
+| [`taiga`](skills/taiga/SKILL.md) | Look up Penpot issues, user stories, and tasks in Taiga. |
+| [`testing`](skills/testing/SKILL.md) | The repo's testing rules and TDD workflow, loaded before writing tests. |
+| [`security-and-hardening`](skills/security-and-hardening/SKILL.md) | Security checks for code that handles user input, auth, or external services. |
+| [`ste`](skills/ste/SKILL.md) | Rewrites prose in Simplified Technical English. Loads only when you name it. |
+| [`refine-prompt`](skills/refine-prompt/SKILL.md) | Rewrites a rough prompt into a clearer one. Never runs the prompt. |
+| [`update-changelog`](skills/update-changelog/SKILL.md) | Regenerates `CHANGES.md` from a GitHub milestone. |
+
+## A typical round
+
+1. `/make-a-plan` — you get a plan and a saved file in `.agents/plans/`.
+2. `/review-plan` — a second opinion; approve or request changes.
+3. `/implement-plan` — the code gets written and committed. Starting from a base branch, it also opens the GitHub issue and the `issue-NNNN` branch; the plans that follow continue on that same branch.
+4. `/review-code` — a reviewer checks the commit.
+5. `/create-pr` — the branch goes up as a pull request.
+
+Every step also works on its own, and you can always say what you want
+in plain words — the agents pick the right skill from what you say.
+
+## Adding or changing a skill
+
+Create a folder here with a `SKILL.md` inside. The file needs `name` and
+`description` in its frontmatter, and a clear "When to use" section so
+agents know when to reach for it. Keep one job per skill, and keep the
+two families apart: flows are named with a verb first; reference skills
+end in `-criteria`.

.agents/skills/make-a-plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: make-a-plan
-description: Planning flow — research the subject of this session, produce an implementation plan with the planner skill, resolve open questions with the user in plain language, and save the final plan to .opencode/plans/. Use it when the user asks to plan, design, or break down a task, in any phrasing.
+description: Planning flow — research the subject of this session, produce an implementation plan with the planner skill, resolve open questions with the user in plain language, and save the final plan to .agents/plans/. Use it when the user asks to plan, design, or break down a task, in any phrasing.
 ---
 
 # Make a Plan
@@ -32,7 +32,7 @@ Do not use it to execute a plan — that is the `implement-plan` flow.
    plain language. Assume I know only the high-level project goal, not the codebase,
    architecture, implementation terms, or the problem this task solves.
 3. Once all decisions are answered and the plan is final, save it verbatim to the
-   announced path under `.opencode/plans/` (create the directory if it does not
+   announced path under `.agents/plans/` (create the directory if it does not
    exist). This step is the flow's explicit authorization to write the plan
    file — the only write allowed here. If I later ask for changes, update the
    saved file directly.

.agents/skills/planner/SKILL.md

@@ -235,7 +235,7 @@ explicitly instructs you to save it — and then only that file.
 Announce the suggested save path:
 
 ```
-.opencode/plans/YYYY-MM-DD-<plan-one-line-title>.md
+.agents/plans/YYYY-MM-DD-<plan-one-line-title>.md
 ```
 
 Use today's date in the user's local timezone. The `<plan-one-line-title>`

.agents/skills/review-plan/SKILL.md

@@ -20,7 +20,7 @@ implementation plan.
 
 1. **Determine the plan under review** from the session context (for example, a
    plan just produced by `/make-a-plan`) or from a plan file path given by the
-   user (typically under `.opencode/plans/`). If a file path is given, read the
+   user (typically under `.agents/plans/`). If a file path is given, read the
    file first so the complete plan is in context.
 2. Delegate the review to the `general` subagent (via the task tool), unless the
    user specifies another agent. Include in the prompt the

.claude/skills

@@ -1 +1 @@
-../.opencode/skills
+../.agents/skills

.gitignore

@@ -103,7 +103,7 @@ opencode.json
 /.playwright-mcp
 /.devenv/mcp/
 /opencode.json
-/.opencode/plans
+/.agents/plans
 /.opencode/reports
 /.opencode/prompts
 /.ci-logs

.serena/memories/workflow/creating-issues.md

@@ -351,5 +351,5 @@ gh issue view <NUMBER> --repo penpot/penpot --json title
 ## See Also
 
 - End-to-end orchestration entry point: the `create-issue` skill at
-  `.opencode/skills/create-issue/SKILL.md`. The skill is a thin entry
+  `.agents/skills/create-issue/SKILL.md`. The skill is a thin entry
   point; this memory is the canonical home for all issue-creation rules.