---
name: agentation-watch
description: Hands-free annotation processor. Watches for Agentation annotations via MCP, reads the referenced code, fixes issues, and resolves annotations automatically. Use when the user says "watch for annotations," "fix annotations," "hands-free mode," "fixer loop," or wants an agent to autonomously process design feedback from the Agentation toolbar.
---
# Agentation Watch (Hands-Free Fixer)
Process Agentation annotations in real-time: watch for new annotations, read the referenced code, fix the issue, and resolve the annotation with a summary.
## Preflight
Before entering the loop, verify the MCP server is connected and has active sessions:
1. Call `agentation_list_sessions` — if empty, the toolbar isn't connected. Tell the user to open a page with `<Agentation endpoint="http://localhost:4747" />` in their browser.
2. Call `agentation_get_all_pending` — process any existing annotations before entering the watch loop.
## The Watch Loop
```
while true:
1. Call agentation_watch_annotations (blocks until annotations arrive)
- Default timeout: 120s, batch window: 10s
- Pass sessionId to watch a specific page, or omit to watch all pages
2. For each annotation in the batch:
a. Call agentation_acknowledge(annotationId) — marks it as "seen"
b. Parse the annotation context:
- comment: What the user wants changed
- intent: "fix" | "change" | "question" | "approve"
- severity: "blocking" | "important" | "suggestion"
- elementPath: CSS selector to find the element
- reactComponents: Component tree path (e.g., "App > Dashboard > Button")
- kind: "feedback" | "placement" | "rearrange" (v3.0+)
- element: HTML tag name
- cssClasses: Classes on the element
- url: Page URL (maps to a route)
c. Locate the code:
- Use reactComponents to find the source file (grep for component name)
- Use the URL path to find the page file (map route to app/ directory)
- Use cssClasses to find Tailwind classes in the component
- Use elementPath as a fallback for identifying the DOM structure
d. Apply the fix:
- For intent "fix": Fix the bug described in the comment
- For intent "change": Implement the requested change
- For intent "question": Call agentation_reply with the answer (don't resolve)
- For intent "approve": Call agentation_resolve with "Acknowledged"
- For kind "placement": See agentation-layout skill
- For kind "rearrange": See agentation-layout skill
e. Call agentation_resolve(annotationId, summary)
- Summary should be 1-2 sentences: what file was changed and what was done
- Example: "Updated Button component in src/components/ui/Button.tsx — changed bg-blue-500 to bg-primary for design system compliance"
3. Loop back to step 1
```
## Resolving vs Dismissing
- **Resolve** (`agentation_resolve`): You fixed or addressed the annotation. Include a summary.
- **Dismiss** (`agentation_dismiss`): The annotation doesn't apply or can't be fixed. Include a reason.
- **Reply** (`agentation_reply`): For questions — add a message to the thread without closing.
Only resolve annotations you actually fixed. If you can't find the code or the fix is ambiguous, reply asking for clarification instead of guessing.
## Code Location Strategy
Annotations contain multiple signals. Use them in this priority order:
1. **reactComponents** — Most reliable. Grep for the component name:
```
grep -r "function ComponentName\|const ComponentName" frontend/src/
```
2. **URL path** — Maps directly to app router file:
- `/67/budget` → `frontend/src/app/(main)/[projectId]/budget/`
- `/settings` → `frontend/src/app/(main)/settings/` or `frontend/src/app/(admin)/settings/`
3. **cssClasses** — Search for the exact class combination:
```
grep -r "className.*specific-class" frontend/src/
```
4. **elementPath** — CSS selector chain gives structural hints:
- `main > div > form > button.submit-btn` suggests a form component
## Design System Awareness
When fixing UI annotations in this project, follow the design system:
- Never hardcode colors — use semantic tokens (`bg-primary`, `text-foreground`, etc.)
- Never use `<button>` — use `<Button>` from `@/components/ui/button`
- Never wrap content in card borders — use whitespace and typography
- Import from `@/components/ds` or `@/components/ui`
- Check `frontend/src/components/ds/GOLDEN-EXAMPLES.tsx` for patterns
## Handling Hot Reloads
When you edit code, the dev server hot-reloads. This can cause:
- The Agentation toolbar to re-render (annotations persist via MCP server)
- Page state to reset (forms clear, tabs reset)
- New sessions to appear in `agentation_list_sessions`
This is normal. The watch loop continues uninterrupted because it listens to the MCP server, not the browser.
## Example Session
```
> Watch for agentation annotations and fix each one
[Calling agentation_get_all_pending — 0 pending]
[Calling agentation_watch_annotations — blocking...]
[Batch received: 1 annotation]
Annotation: "This button should be primary color, not blue-500"
Element: button.bg-blue-500
Component: SubmitButton in DashboardForm
Intent: fix, Severity: important
[Acknowledging annotation...]
[Searching: grep -r "SubmitButton" frontend/src/]
[Found: frontend/src/components/domain/dashboard/DashboardForm.tsx:45]
[Reading file, finding bg-blue-500...]
[Editing: bg-blue-500 → bg-primary]
[Resolving: "Fixed SubmitButton in DashboardForm.tsx — replaced bg-blue-500 with bg-primary token"]
[Calling agentation_watch_annotations — blocking...]
```
## Tips
- Start this before the critic session so annotations are processed as they arrive
- Annotations queue up if the critic is faster — that's fine, process them in order
- For blocking-severity annotations, fix immediately. For suggestions, batch if practical.
- If multiple annotations target the same component, read them all before making changes
