code-annotations

English | 简体中文

Agent writes code-review annotations directly in your source; you audit in your IDE — delete what you don't want, keep what you approve — then agent executes in batch.

Overview

Instead of describing "which file, which line, what to change" in a chat window, let the agent write proposals next to the code itself:

// @anno-propose: extract token refresh into auth.tryRefresh()
// @anno-risk: medium — affects 3 call sites
// @anno-note: duplicated in middleware/auth.ts and handler/login.ts
func refreshToken(ctx context.Context) error {

You open your IDE, see all proposals at a glance, delete the ones you don't want, edit descriptions if needed — then run:

/anno-apply

Agent executes only what's left, removes annotations, and writes ANNOCHANGELOG.md.

Why use it

• Review in your IDE — syntax highlighting, go-to-definition, git diff. Not a chat box.
• Agent does the work — default is "accept". You only delete what's wrong.
• Line-level precision — every proposal sits exactly where the change happens.
• Risk-aware — every annotation tagged low / medium / high, so you see impact before executing.
• Traceable — ANNOCHANGELOG.md records every applied and skipped change.

Install

git clone https://github.com/zlj-zz/code-annotations.git ~/projects/code-annotations
ln -sfn ~/projects/code-annotations ~/.agents/skills/code-annotations

Quick start

1. Review

/anno-review "refactor the auth module to reduce duplication"

Agent scans the codebase, inserts @anno-propose annotations at specific locations, and presents a summary:

12 proposals across 5 files. High risk: 3. Review then /anno-apply.

2. Audit in IDE

Open your IDE. Every proposal is a 3-line annotation next to the target code:

// @anno-propose: add rate limiting middleware
// @anno-risk: low — isolated change, no API impact
// @anno-note: use existing rate-limit package in shared/

• This looks good → leave it
• This is wrong → delete all 3 lines
• Needs adjustment → edit the description

3. Apply

/anno-apply

Agent executes approved proposals, strips annotations, and writes ANNOCHANGELOG.md:

## 2026-01-15 14:30 — anno-apply

| Status | File | Proposal |
|--------|------|----------|
| ✅ done | auth.ts | extract token refresh |
| ✅ done | api.ts | add rate limiting |
| ⏭️ skipped | db.ts | add composite index (user removed) |
| ❌ failed | config.ts | migrate secrets (merge conflict) |

Commands

Command	What	Writes log?
/anno-review <task>	Agent scans code, inserts proposals	No
/anno-apply	Execute approved, strip annotations, write log	Yes
/anno-clear	Remove all annotations without executing	No

Annotation format

// @anno-propose: <one-line description>
// @anno-risk: low | medium | high
// @anno-note: <optional context — why, alternatives, related files>

Field	Purpose
@anno-propose	What to do. One sentence.
@anno-risk	Impact: cosmetic (low), logic change (medium), API/schema (high)
@anno-note	Extra context for the reviewer. Optional.

Language-aware comment prefix: // for TS/JS/Go/Rust, # for Python/Ruby, -- for SQL, <!-- --> for HTML.

Integration with pi-modes

Mode	Behavior
Plan	/anno-review works, /anno-apply blocked
Auto	Both work
Manual	Each apply step confirmed

Design principles

1. Agent writes, human decides — reverse the direction of annotations. Agent does the heavy lifting.
2. Default is "accept" — delete what you don't want. No need to mark "approved".
3. Proposals, not commands — annotations are suggestions. User has final say.
4. Strip + log — source stays clean; ANNOCHANGELOG.md keeps history.

Project structure

code-annotations/
├── SKILL.md                    # skill entry
├── README.md / README.zh.md    # docs
├── assets/
│   └── annochangelog.template.md
├── commands/                   # slash command definitions
│   ├── anno-review.md
│   ├── anno-apply.md
│   └── anno-clear.md
└── LICENSE

License

MIT