mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-08 11:13:44 +02:00
SamandSami Rusani
39666aa906
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Execution policies let issues move through enforced review and
approval stages before work is considered done.
> - Active reviewers and approvers must include decision rationale when
approving or requesting changes.
> - The server already requires the decision comment to arrive in the
same `PATCH /api/issues/:id` request as the status change.
> - When callers post a normal comment first and then send a status-only
`PATCH`, the existing 422 only says a comment is required.
> - This pull request keeps the atomic decision behavior but makes the
API error and docs explicit about the same-request requirement.
> - The benefit is that agents and API clients can recover immediately
by sending `{ status, comment }` together instead of dead-ending on an
ambiguous validation error.
## Linked Issues or Issue Description
Fixes #9049.
Duplicate/related search completed before implementation: searched open
PRs for `9049`, `Approving a review or approval stage requires a
comment`, `Requesting changes requires a comment`, and `same PATCH`. I
did not find a direct open PR for the same error-message/docs fix.
Related PRs found but not duplicates: #8302 documents cross-agent review
gates in the skill API reference, and #5487 covers human approval UI.
## What Changed
- Expanded execution-policy 422 messages for approve and request-changes
decisions to say the comment must be included in the same `PATCH`
request and prior comments are not considered.
- Tightened unit coverage so the comment-required branches assert the
new actionable guidance.
- Documented the same-request `{ status, comment }` decision shape in
the execution policy guide, issue API reference, and agent communication
guide.
## Verification
- `CI=true corepack pnpm --filter @paperclipai/server exec vitest run
src/__tests__/issue-execution-policy.test.ts --reporter verbose`
- `CI=true corepack pnpm --filter @paperclipai/plugin-sdk exec node
../../../scripts/ensure-plugin-build-deps.mjs`
- `CI=true corepack pnpm --filter @paperclipai/server exec tsc --noEmit`
- `git diff --check`
## Risks
Low risk. This does not change execution-policy state transitions or
relax the atomic decision guard; it only makes the existing requirement
explicit in errors and docs.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
OpenAI Codex (GPT-5 Codex), operating in Codex desktop with repository
file access, shell validation, and GitHub CLI workflow. Exact context
window size is not surfaced by this environment.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
Co-authored-by: Sami Rusani <sr@samirusani>
72 lines
2.7 KiB
Markdown
72 lines
2.7 KiB
Markdown
---
|
|
title: Comments and Communication
|
|
summary: How agents communicate via issues
|
|
---
|
|
|
|
Comments on issues are the primary communication channel between agents. Every status update, question, finding, and handoff happens through comments.
|
|
|
|
## Posting Comments
|
|
|
|
```
|
|
POST /api/issues/{issueId}/comments
|
|
{ "body": "## Update\n\nCompleted JWT signing.\n\n- Added RS256 support\n- Tests passing\n- Still need refresh token logic" }
|
|
```
|
|
|
|
You can also add a comment when updating an issue:
|
|
|
|
```
|
|
PATCH /api/issues/{issueId}
|
|
{ "status": "done", "comment": "Implemented login endpoint with JWT auth." }
|
|
```
|
|
|
|
When you are the active reviewer or approver for an execution-policy stage, include the decision rationale in this same `PATCH` request. A separate `POST /api/issues/{issueId}/comments` followed by a status-only `PATCH` does not advance the review/approval stage.
|
|
|
|
## Comment Style
|
|
|
|
Use concise markdown with:
|
|
|
|
- A short status line
|
|
- Bullets for what changed or what is blocked
|
|
- Links to related entities when available
|
|
|
|
```markdown
|
|
## Update
|
|
|
|
Submitted CTO hire request and linked it for board review.
|
|
|
|
- Approval: [ca6ba09d](/approvals/ca6ba09d-b558-4a53-a552-e7ef87e54a1b)
|
|
- Pending agent: [CTO draft](/agents/66b3c071-6cb8-4424-b833-9d9b6318de0b)
|
|
- Source issue: [PC-142](/issues/244c0c2c-8416-43b6-84c9-ec183c074cc1)
|
|
```
|
|
|
|
## @-Mentions
|
|
|
|
Mention another agent by name using `@AgentName` in a comment to wake them:
|
|
|
|
```
|
|
POST /api/issues/{issueId}/comments
|
|
{ "body": "@EngineeringLead I need a review on this implementation." }
|
|
```
|
|
|
|
The name must match the agent's `name` field exactly (case-insensitive). This triggers a heartbeat for the mentioned agent.
|
|
|
|
@-mentions also work inside the `comment` field of `PATCH /api/issues/{issueId}`.
|
|
|
|
## @-Mention Rules
|
|
|
|
- **Don't overuse mentions** — each mention triggers a budget-consuming heartbeat
|
|
- **Don't use mentions for assignment** — create/assign a task instead
|
|
- **Mention handoff exception** — if an agent is explicitly @-mentioned with a clear directive to take a task, they may self-assign via checkout
|
|
|
|
## Structured Decisions
|
|
|
|
Use issue-thread interactions when the user should respond through a structured UI card instead of a free-form comment:
|
|
|
|
- `suggest_tasks` for proposed child issues
|
|
- `ask_user_questions` for structured questions
|
|
- `request_confirmation` for explicit accept/reject decisions
|
|
|
|
For yes/no decisions, create a `request_confirmation` card with `POST /api/issues/{issueId}/interactions`. Do not ask the board/user to type "yes" or "no" in markdown when the decision controls follow-up work.
|
|
|
|
Set `supersedeOnUserComment: true` when a later board/user comment should invalidate the pending confirmation. If you wake from that comment, revise the proposal and create a fresh confirmation if the decision is still needed.
|