📚 Improve agent workflow safeguards

Protect staged changes when rewriting commit messages and close plans
after verified commits. Clarify checks and remove the unused Taiga skill.

AI-assisted-by: gpt-6.1-terra
This commit is contained in:
Andrey Antukh 2026-11-18 19:06:44 +00:00
parent 7d5fef711c
commit 9b24b6c7c9
8 changed files with 27 additions and 147 deletions

View File

@ -508,7 +508,6 @@ JSON, REPL access, and so on.
| [`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. |
| [`local-ci`](skills/local-ci/SKILL.md) | Run CI-style lint, test, and format checks for the modules you touched with `scripts/ci`, and read the logs when they fail. |
| [`security-and-hardening`](skills/security-and-hardening/SKILL.md) | Security checks for code that handles user input, auth, or external services. |

View File

@ -7,7 +7,7 @@ slash: true
# Skill: create-commit
Produce a git commit that follows Penpot's commit message conventions. This
skill owns the commit format, staging review, and safety checks — it does not
skill handles staging review and safety checks — it does not
implement features or push.
## When to Use
@ -23,15 +23,9 @@ subject/body limits, and the `AI-assisted-by` trailer. Follow it exactly.
## Iron Rules (non-negotiable)
1. **Wrap every body line at 80 characters or fewer.** Count characters, do
not eyeball. Exceptions: `Signed-off-by:` / `AI-assisted-by:` trailers and
lines carrying a URL. This is the rule agents skip most often.
2. **Subject ≤80 chars**, imperative, capitalized, no trailing period.
`Merge`/`Revert`/`Reapply` commits skip the length check.
3. **Blank line between subject and body.**
4. **Run `./scripts/check-commit` and require exit code 0.** It mechanically
checks rules 1–3. A non-zero exit is a hard blocker: fix the message and
re-commit. Never report the commit as done with a failing checker.
Follow the message rules and exceptions in `mem:workflow/creating-commits`.
**Run `./scripts/check-commit` and require exit code 0.** A non-zero exit is a
hard blocker: fix the message and re-check it before reporting success.
## Workflow
@ -67,4 +61,4 @@ subject/body limits, and the `AI-assisted-by` trailer. Follow it exactly.
bots are rejected by `./scripts/check-commit`; for AI participation use the
`AI-assisted-by:` trailer.
- Do not add untracked files that were not created in this session.
- Do not skip the `scripts/check-commit` verification step (Iron Rule 4).
- Do not skip the `scripts/check-commit` verification step.

View File

@ -116,19 +116,20 @@ Implement every task in one go. Work methodically, keeping changes
focused on what the issue requires. Respect the plan's proposed
parallelization when it applies.
When the implementation is complete, close the plan file first: flip its
`Status` to `done` and append one UTC ISO 8601 line to its `Review Log`
with the issue URL when one exists (standalone mode, e.g.
`https://github.com/penpot/penpot/issues/NNNN`); in continue/direct
mode with no issue, just `done` with no invented identifier. Never
record commit hashes. Leave the closed plan file local and uncommitted.
Then load the **`create-commit`** skill and follow its workflow to commit
When the implementation is complete, load the **`create-commit`** skill and
follow its workflow to commit
only the implementation, tests, memory, and documentation changes. Before
committing, verify that the staged file list does not contain the plan
file. Provide a brief summary of what was implemented and why, the issue
reference (`issue-NNNN`) when there is one, and the model name you are
running as so the `AI-assisted-by` trailer is set correctly.
Only after the commit exists and passes its checks, close the plan: flip
`Status` to `done` and append one UTC ISO 8601 line to `Review Log` with the
issue URL when one exists; otherwise record `done` without inventing an
identifier. Never record commit hashes. Leave the plan local and uncommitted.
If the commit or its checks fail, do not close the plan.
### Step-by-step mode (on request)
When the user asks for it — "step by step", "task by task", "one commit

View File

@ -86,7 +86,7 @@ log path.
./scripts/ci --lint frontend
# Changed common/ — validate its consumers too
./scripts/ci frontend backend exporter
./scripts/ci common frontend backend exporter
# Preview what would run, without running it
./scripts/ci --dry-run --all

View File

@ -42,9 +42,10 @@ Skipping this step is the #1 cause of incorrect or incomplete plans.
only file you may write is the plan itself, and only when the command or
user explicitly instructs you to save it.
- You do **not** run builds, tests, linters, or any commands that modify state.
- You do **not** create git commits or interact with version control.
- You do **not** execute shell commands beyond read-only searches (`rg`, `ls`,
`find`, `cat`, `bat`).
- You do **not** create commits or run commands that modify version control.
Read-only inspection such as `git status`, `git log`, `git show` and
`git diff` is allowed.
- Shell commands must be read-only.
- Your output is a structured plan or analysis, ready for handoff to an
engineer agent or developer.

View File

@ -6,9 +6,8 @@ slash: true
# Skill: rewrite-commit-message
HEAD's message is a concatenation of older messages (typical after a
squash): several subjects, bodies and repeated trailers stacked in a
single message. Replace it with one proper message and amend HEAD.
Rewrite HEAD's title and description from its own diff. This also handles a
squash message with several subjects, bodies and repeated trailers.
## When to Use
@ -17,9 +16,11 @@ single message. Replace it with one proper message and amend HEAD.
## Steps
1. Read the full current message (`git log -1 --format=%B HEAD`) and
the branch diff (`git diff develop..HEAD --stat`, plus the code
when the summary needs grounding).
1. Check `git diff --cached` first. If any changes are staged, stop and ask
the user to handle them; an amend must never include those changes. Read
the full current message (`git log -1 --format=%B HEAD`) and HEAD's own
diff (`git show --format= --stat HEAD` and the patch). Respect the project
rule on amending pushed commits.
2. Collect every DISTINCT `AI-assisted-by:` value in the current
message. All of them survive into the new message, one line each:
attributions are never dropped in a rewrite, even when most of
@ -27,7 +28,7 @@ single message. Replace it with one proper message and amend HEAD.
3. Draft one message per `mem:workflow/creating-commits` (read it
end-to-end first): single subject (imperative, capitalized, no
trailing period, ≤80 chars), blank line, body wrapped at ≤80
chars covering the whole diff (not the old per-commit slices),
chars covering HEAD's diff (not the old per-commit slices),
then the preserved trailers.
4. Write it to a file (a heredoc keeps real newlines; inline `-m`
with `\n` does not) and `git commit --amend -F <file>`.

View File

@ -67,7 +67,7 @@ rg "user_\d+"
rg -F "function()"
# Multiline search
rg -U "start.*end"
rg -U '(?s)start.*end'
# Only show matches, not lines
rg -o "https?://[^\s]+"

View File

@ -1,116 +0,0 @@
---
name: taiga
description: Fetch information from Taiga public API for the Penpot project (id 345963) — issues, user stories, and tasks, without authentication.
metadata: {"clawdbot":{"requires":{"bins":["python3"]}}}
---
# Taiga API Skill
Fetch information from Taiga public API for the **Penpot** project
(project id: `345963`, slug: `penpot`).
**No authentication required** — only public project data is accessed.
## When to use
- The user asks about Penpot issues, user stories, or tasks tracked in
Taiga — fetch them via the public API (project id 345963), no
authentication needed.
## Prerequisites
- `python3` — the `scripts/taiga.py` CLI script is self-contained (stdlib only)
## Quick Start
The easiest way is to use the bundled Python script:
```bash
# Pass a Taiga URL directly
python3 scripts/taiga.py https://tree.taiga.io/project/penpot/issue/13714
# Or use "<type> <ref>" syntax
python3 scripts/taiga.py us 14128
python3 scripts/taiga.py task 13648
# Add --json for raw output
python3 scripts/taiga.py --json issue 13714
# See full usage
python3 scripts/taiga.py --help
```
## URL Pattern Reference
Taiga web URLs follow these patterns:
| Type | Web URL Pattern |
|------|----------------|
| Issue | `https://tree.taiga.io/project/penpot/issue/<REF>` |
| User Story | `https://tree.taiga.io/project/penpot/us/<REF>` |
| Task | `https://tree.taiga.io/project/penpot/task/<REF>` |
To extract the **type** and **ref** from a URL:
- `issue/13714` → type=`issue`, ref=`13714`
- `us/14128` → type=`us`, ref=`14128`
- `task/13648` → type=`task`, ref=`13648`
## Python Script Reference
The `scripts/taiga.py` script wraps the Taiga API into a single convenient CLI
with sensible defaults.
### Usage
```
python3 scripts/taiga.py <taiga-url>
python3 scripts/taiga.py <type> <ref>
python3 scripts/taiga.py [--json] <taiga-url>
python3 scripts/taiga.py [--json] <type> <ref>
```
### Examples
```bash
# By URL (recommended — no need to think about type/ref)
python3 scripts/taiga.py https://tree.taiga.io/project/penpot/issue/13714
# By type and ref
python3 scripts/taiga.py us 14128
python3 scripts/taiga.py task 13648
# Raw JSON output
python3 scripts/taiga.py --json issue 13714
```
### Output
The script prints a clean, structured summary:
```text
User Story #11964 — 🔴 [DESIGN TOKENS] Typography Composite Input
================================
Status: Defining
Milestone: design-systems-sprint-26
Points: 3 role(s)
Assignee: Natacha Menjibar
Author: Natacha Menjibar
Created: 2025-09-01
Tags: iop-design-tokens
URL: https://tree.taiga.io/project/penpot/us/11964
================================
<full description text, unmodified>
```
The fields section includes type-specific information:
- **Issues:** Status, Type ID, Severity ID, Priority ID
- **User Stories:** Status, Milestone, Points
- **Tasks:** Status, Milestone, Parent US
## Reference
- API docs: https://docs.taiga.io/api.html
- Taiga instance: https://tree.taiga.io
- API base: https://api.taiga.io/api/v1
- Penpot project id: `345963`
- Penpot project slug: `penpot`