@alexgorbatchev/pi-agentation 3.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Gorbatchev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,72 @@
+# pi plugin for Agentation Fork
+
+A pi extension that continuously runs an Agentation fix loop by repeatedly sending:
+
+- `/skill:agentation-fix-loop <project-id>`
+
+It starts automatically when the session starts, resolves the project ID for the current repository (searching for `<Agentation projectId=... />`), and keeps re-queuing the same project-scoped prompt after each agent run until pi exits (or you stop it).
+
+See:
+
+- [Agentation Fork](https://github.com/alexgorbatchev/agentation)
+- [CLI](https://github.com/alexgorbatchev/agentation-cli)
+- [Agentation Skills](https://github.com/alexgorbatchev/agentation-skills)
+
+> [!IMPORTANT]
+> This loops AI until manually stopped and so it can consume tokens while idling. Don't forget to stop it when you no longer using it.
+
+## Behavior
+
+- The launcher (`pi-agentation`) injects the local packaged fix-loop skill via `--skill`
+- Extension checks that `/skill:agentation-fix-loop` is available before running
+- On session start/switch/fork, the extension:
+  - runs `agentation projects --json`
+  - runs `rg` to discover literal `projectId="..."` or `projectId='...'` values in the repo
+  - intersects both lists
+  - auto-starts if exactly one project matches, otherwise prompts you to choose in the TUI
+- The resolved project ID is stored in the current Pi session so reloads/resume do not re-prompt that same session
+- On `agent_end`: sends the next project-scoped loop prompt
+- On `session_shutdown`: stops loop automatically
+- If the skill is missing, no repo project IDs are found, or no discovered repo IDs are known to Agentation yet: plugin requests shutdown and exits with code `1`
+
+## Commands
+
+- `/agentation-loop-start` — resume/start looping
+- `/agentation-loop-stop` — pause looping
+
+## Installation
+
+Install both project packages:
+
+```bash
+npm install -D @alexgorbatchev/agentation @alexgorbatchev/pi-agentation
+```
+
+`@alexgorbatchev/pi-agentation` ships its own packaged copy of the fix-loop skill. That file is synced from [`@alexgorbatchev/agentation-skills`](https://github.com/alexgorbatchev/agentation-skills) during packaging, so you do not need to install the skill package separately.
+
+Required executables on `PATH`:
+
+- `pi`
+- `agentation`
+- `rg`
+
+The `agentation` [CLI](https://github.com/alexgorbatchev/agentation-cli) is distributed separately from these npm packages and must be downloaded and placed on your `PATH`.
+
+## Usage
+
+Before running the pi, you need to start the [CLI](https://github.com/alexgorbatchev/agentation-cli) and connect from the front end which has `<Agentation projectId="..." />` at least once in the last 24h. Then run the launcher from your project:
+
+```bash
+npx pi-agentation
+```
+
+If your shell already exposes local package binaries on `PATH`, you can run:
+
+```bash
+pi-agentation
+```
+
+## Notes
+
+- This loop is intentionally persistent and can consume tokens quickly.
+- Use `/agentation-loop-stop` if you want to pause it without exiting Pi.

package/agentation.ts

@@ -0,0 +1,432 @@
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import process from "node:process";
+
+const LOOP_SKILL_NAME = "agentation-fix-loop";
+const LOOP_PROMPT = `/skill:${LOOP_SKILL_NAME}`;
+const PROJECT_SELECTION_ENTRY_TYPE = "agentation-project-selection";
+const PROJECT_ID_PATTERN = /^projectId=(?:"([^"\r\n]+)"|'([^'\r\n]+)')$/;
+
+type ExecResult = Awaited<ReturnType<ExtensionAPI["exec"]>>;
+
+type CommandOutcome = {
+  code: number | undefined;
+  errorMessage?: string;
+  killed: boolean;
+  stderr: string;
+  stdout: string;
+};
+
+interface IProjectSelectionData {
+  projectId: string;
+}
+
+export default function agentation(pi: ExtensionAPI): void {
+  let currentProjectId: string | null = null;
+  let isLoopEnabled = true;
+
+  const isLoopSkillAvailable = (): boolean => {
+    return pi.getCommands().some((command) => {
+      if (command.source !== "skill") {
+        return false;
+      }
+
+      return command.name === LOOP_SKILL_NAME || command.name === `skill:${LOOP_SKILL_NAME}`;
+    });
+  };
+
+  const reportError = (ctx: ExtensionContext, message: string): void => {
+    console.error(message);
+    ctx.ui.notify(message, "error");
+  };
+
+  const shutdownForFatalError = (ctx: ExtensionContext, message: string): void => {
+    currentProjectId = null;
+    isLoopEnabled = false;
+    process.exitCode = 1;
+    reportError(ctx, message);
+    ctx.shutdown();
+  };
+
+  const ensureLoopSkillAvailable = (ctx: ExtensionContext): boolean => {
+    if (isLoopSkillAvailable()) {
+      return true;
+    }
+
+    shutdownForFatalError(ctx, `Missing required skill ${LOOP_PROMPT}. Exiting.`);
+    return false;
+  };
+
+  const queueLoopPrompt = (projectId: string, deliverAsFollowUp: boolean): void => {
+    if (!isLoopEnabled) {
+      return;
+    }
+
+    const loopPrompt = `${LOOP_PROMPT} ${projectId}`;
+    if (deliverAsFollowUp) {
+      pi.sendUserMessage(loopPrompt, { deliverAs: "followUp" });
+      return;
+    }
+
+    pi.sendUserMessage(loopPrompt);
+  };
+
+  const persistProjectSelection = (projectId: string): void => {
+    if (currentProjectId === projectId) {
+      return;
+    }
+
+    currentProjectId = projectId;
+    pi.appendEntry(PROJECT_SELECTION_ENTRY_TYPE, { projectId });
+  };
+
+  const restoreProjectSelection = (ctx: ExtensionContext): string | null => {
+    let latestProjectId: string | null = null;
+    let latestTimestamp = "";
+
+    for (const entry of ctx.sessionManager.getBranch()) {
+      if (entry.type !== "custom" || entry.customType !== PROJECT_SELECTION_ENTRY_TYPE) {
+        continue;
+      }
+
+      if (!isProjectSelectionData(entry.data)) {
+        continue;
+      }
+
+      const normalizedProjectId = normalizeProjectId(entry.data.projectId);
+      if (normalizedProjectId === null) {
+        continue;
+      }
+
+      if (entry.timestamp >= latestTimestamp) {
+        latestTimestamp = entry.timestamp;
+        latestProjectId = normalizedProjectId;
+      }
+    }
+
+    currentProjectId = latestProjectId;
+    return latestProjectId;
+  };
+
+  const execCommand = async (command: string, args: string[]): Promise<CommandOutcome> => {
+    try {
+      const result: ExecResult = await pi.exec(command, args);
+      return {
+        code: result.code,
+        killed: result.killed,
+        stderr: result.stderr,
+        stdout: result.stdout,
+      };
+    } catch (error) {
+      return {
+        code: undefined,
+        errorMessage: error instanceof Error ? error.message : String(error),
+        killed: false,
+        stderr: "",
+        stdout: "",
+      };
+    }
+  };
+
+  const listKnownProjectIds = async (): Promise<{ errorMessage?: string; projectIds: string[] }> => {
+    let projectsResult = await execCommand("agentation", ["projects", "--json"]);
+    if (!didCommandSucceed(projectsResult)) {
+      await execCommand("agentation", ["start", "--background"]);
+      projectsResult = await execCommand("agentation", ["projects", "--json"]);
+    }
+
+    if (!didCommandSucceed(projectsResult)) {
+      const failureMessage = formatCommandOutcome(projectsResult);
+      return {
+        errorMessage: `Failed to load Agentation projects via \`agentation projects --json\`: ${failureMessage}`,
+        projectIds: [],
+      };
+    }
+
+    const projectIds = parseJsonStringArray(projectsResult.stdout);
+    if (projectIds === null) {
+      return {
+        errorMessage: "`agentation projects --json` returned invalid JSON.",
+        projectIds: [],
+      };
+    }
+
+    return { projectIds };
+  };
+
+  const discoverRepoProjectIds = async (): Promise<{ errorMessage?: string; projectIds: string[] }> => {
+    const rgResult = await execCommand("rg", [
+      "-o",
+      "--no-filename",
+      "--glob",
+      "*.{tsx,jsx}",
+      "projectId=(?:\"[^\"]+\"|'[^']+')",
+      ".",
+    ]);
+
+    if (didCommandSucceed(rgResult)) {
+      return { projectIds: extractProjectIdsFromRgOutput(rgResult.stdout) };
+    }
+
+    if (rgResult.code === 1 && !rgResult.killed && rgResult.errorMessage === undefined) {
+      return { projectIds: [] };
+    }
+
+    return {
+      errorMessage: `Failed to discover project IDs via \`rg\`: ${formatCommandOutcome(rgResult)}`,
+      projectIds: [],
+    };
+  };
+
+  const resolveProjectId = async (ctx: ExtensionContext): Promise<string | null> => {
+    const knownProjectsResult = await listKnownProjectIds();
+    if (knownProjectsResult.errorMessage !== undefined) {
+      shutdownForFatalError(ctx, knownProjectsResult.errorMessage);
+      return null;
+    }
+
+    const repoProjectsResult = await discoverRepoProjectIds();
+    if (repoProjectsResult.errorMessage !== undefined) {
+      shutdownForFatalError(ctx, repoProjectsResult.errorMessage);
+      return null;
+    }
+
+    if (repoProjectsResult.projectIds.length === 0) {
+      const missingProjectIdMessage = [
+        "No literal Agentation `projectId` values were found in this repository.",
+        "Agentation requires an approved literal `projectId` pattern.",
+      ].join(" ");
+      shutdownForFatalError(ctx, missingProjectIdMessage);
+      return null;
+    }
+
+    const candidateProjectIds = intersectProjectIds(repoProjectsResult.projectIds, knownProjectsResult.projectIds);
+    if (candidateProjectIds.length === 0) {
+      const repoProjectIds = repoProjectsResult.projectIds.join(", ");
+      const unknownProjectMessage = [
+        `Found repository project IDs (${repoProjectIds}), but none are known to Agentation yet.`,
+        "Open the UI so it connects to the server at least once, then retry.",
+      ].join(" ");
+      shutdownForFatalError(ctx, unknownProjectMessage);
+      return null;
+    }
+
+    if (candidateProjectIds.length === 1) {
+      return candidateProjectIds[0] ?? null;
+    }
+
+    if (!ctx.hasUI) {
+      const candidateProjectLabel = candidateProjectIds.join(", ");
+      const selectionMessage = [
+        `Multiple Agentation projects matched this repository (${candidateProjectLabel}),`,
+        "but no interactive UI is available to choose one.",
+      ].join(" ");
+      shutdownForFatalError(ctx, selectionMessage);
+      return null;
+    }
+
+    const selectedProjectId = await ctx.ui.select("Select Agentation project", candidateProjectIds);
+    if (selectedProjectId === undefined) {
+      shutdownForFatalError(ctx, "Agentation project selection was cancelled.");
+      return null;
+    }
+
+    return selectedProjectId;
+  };
+
+  const initializeLoopForSession = async (ctx: ExtensionContext): Promise<void> => {
+    restoreProjectSelection(ctx);
+
+    if (!isLoopEnabled) {
+      return;
+    }
+
+    if (!ensureLoopSkillAvailable(ctx)) {
+      return;
+    }
+
+    let projectId = currentProjectId;
+    if (projectId === null) {
+      projectId = await resolveProjectId(ctx);
+      if (projectId === null) {
+        return;
+      }
+      persistProjectSelection(projectId);
+    }
+
+    ctx.ui.notify(`Agentation loop started for ${projectId}`, "info");
+    queueLoopPrompt(projectId, !ctx.isIdle());
+  };
+
+  pi.on("session_start", async (_event, ctx) => {
+    await initializeLoopForSession(ctx);
+  });
+
+  pi.on("session_switch", async (_event, ctx) => {
+    await initializeLoopForSession(ctx);
+  });
+
+  pi.on("session_fork", async (_event, ctx) => {
+    await initializeLoopForSession(ctx);
+  });
+
+  pi.on("agent_end", async (_event, ctx) => {
+    if (!isLoopEnabled) {
+      return;
+    }
+
+    if (!ensureLoopSkillAvailable(ctx)) {
+      return;
+    }
+
+    if (currentProjectId === null) {
+      reportError(ctx, "Agentation loop is enabled, but no project ID is selected for this session.");
+      return;
+    }
+
+    queueLoopPrompt(currentProjectId, !ctx.isIdle());
+  });
+
+  pi.on("session_shutdown", async () => {
+    currentProjectId = null;
+    isLoopEnabled = false;
+  });
+
+  pi.registerCommand("agentation-loop-start", {
+    description: "Start the automatic Agentation fix loop",
+    handler: async (_args, ctx) => {
+      if (isLoopEnabled) {
+        ctx.ui.notify("Agentation loop is already running", "info");
+        return;
+      }
+
+      if (!ensureLoopSkillAvailable(ctx)) {
+        return;
+      }
+
+      let projectId = currentProjectId ?? restoreProjectSelection(ctx);
+      if (projectId === null) {
+        projectId = await resolveProjectId(ctx);
+        if (projectId === null) {
+          return;
+        }
+        persistProjectSelection(projectId);
+      }
+
+      isLoopEnabled = true;
+      ctx.ui.notify(`Agentation loop resumed for ${projectId}`, "info");
+      queueLoopPrompt(projectId, !ctx.isIdle());
+    },
+  });
+
+  pi.registerCommand("agentation-loop-stop", {
+    description: "Stop the automatic Agentation fix loop",
+    handler: async (_args, ctx) => {
+      isLoopEnabled = false;
+      ctx.ui.notify("Agentation loop paused", "warning");
+    },
+  });
+}
+
+function didCommandSucceed(commandOutcome: CommandOutcome): boolean {
+  return commandOutcome.code === 0 && !commandOutcome.killed && commandOutcome.errorMessage === undefined;
+}
+
+function formatCommandOutcome(commandOutcome: CommandOutcome): string {
+  if (commandOutcome.errorMessage !== undefined) {
+    return commandOutcome.errorMessage;
+  }
+
+  const stderr = commandOutcome.stderr.trim();
+  if (stderr !== "") {
+    return stderr;
+  }
+
+  const stdout = commandOutcome.stdout.trim();
+  if (stdout !== "") {
+    return stdout;
+  }
+
+  if (commandOutcome.killed) {
+    return "command was killed";
+  }
+
+  if (commandOutcome.code !== undefined) {
+    return `exit code ${commandOutcome.code}`;
+  }
+
+  return "unknown failure";
+}
+
+function normalizeProjectId(projectId: string): string | null {
+  const trimmedProjectId = projectId.trim();
+  if (trimmedProjectId === "") {
+    return null;
+  }
+
+  return trimmedProjectId;
+}
+
+function normalizeProjectIds(projectIds: readonly string[]): string[] {
+  const normalizedProjectIds = new Set<string>();
+  for (const projectId of projectIds) {
+    const normalizedProjectId = normalizeProjectId(projectId);
+    if (normalizedProjectId !== null) {
+      normalizedProjectIds.add(normalizedProjectId);
+    }
+  }
+
+  return Array.from(normalizedProjectIds).sort((leftProjectId, rightProjectId) => {
+    return leftProjectId.localeCompare(rightProjectId);
+  });
+}
+
+function intersectProjectIds(repoProjectIds: readonly string[], knownProjectIds: readonly string[]): string[] {
+  const knownProjectIdSet = new Set(normalizeProjectIds(knownProjectIds));
+  return normalizeProjectIds(repoProjectIds).filter((projectId) => {
+    return knownProjectIdSet.has(projectId);
+  });
+}
+
+function extractProjectIdsFromRgOutput(output: string): string[] {
+  const projectIds: string[] = [];
+  for (const line of output.split(/\r?\n/)) {
+    const trimmedLine = line.trim();
+    if (trimmedLine === "") {
+      continue;
+    }
+
+    const match = PROJECT_ID_PATTERN.exec(trimmedLine);
+    const extractedProjectId = match?.[1] ?? match?.[2];
+    if (extractedProjectId !== undefined) {
+      projectIds.push(extractedProjectId);
+    }
+  }
+
+  return normalizeProjectIds(projectIds);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+function isProjectSelectionData(value: unknown): value is IProjectSelectionData {
+  if (!isRecord(value)) {
+    return false;
+  }
+
+  const projectId = value["projectId"];
+  return typeof projectId === "string" && projectId.trim() !== "";
+}
+
+function parseJsonStringArray(jsonText: string): string[] | null {
+  try {
+    const parsed = JSON.parse(jsonText);
+    return isStringArray(parsed) ? normalizeProjectIds(parsed) : null;
+  } catch {
+    return null;
+  }
+}

package/bin/pi-agentation

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SOURCE_PATH="${BASH_SOURCE[0]}"
+while [[ -L "${SOURCE_PATH}" ]]; do
+  SOURCE_DIRECTORY="$(cd -P "$(dirname "${SOURCE_PATH}")" && pwd)"
+  SOURCE_PATH="$(readlink "${SOURCE_PATH}")"
+
+  if [[ "${SOURCE_PATH}" != /* ]]; then
+    SOURCE_PATH="${SOURCE_DIRECTORY}/${SOURCE_PATH}"
+  fi
+done
+
+SCRIPT_DIR="$(cd -P "$(dirname "${SOURCE_PATH}")" && pwd)"
+PACKAGE_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+
+exec pi \
+  -e "${PACKAGE_ROOT}/agentation.ts" \
+  --skill "${PACKAGE_ROOT}/skills/agentation-fix-loop/SKILL.md" \
+  "$@"

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@alexgorbatchev/pi-agentation",
+  "version": "3.0.0",
+  "description": "pi extension launcher for the Agentation fix loop",
+  "license": "MIT",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "agentation"
+  ],
+  "bin": {
+    "pi-agentation": "./bin/pi-agentation"
+  },
+  "pi": {
+    "extensions": [
+      "./agentation.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "files": [
+    "agentation.ts",
+    "README.md",
+    "bin/pi-agentation",
+    "skills/agentation-fix-loop/SKILL.md"
+  ],
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@alexgorbatchev/agentation-skills": "^1.0.0",
+    "@mariozechner/pi-coding-agent": "^0.61.0"
+  },
+  "scripts": {
+    "check": "npm run sync-skill && npm run verify:package && npm run verify:launcher",
+    "prepack": "npm run sync-skill",
+    "sync-skill": "node ./scripts/syncBundledSkill.js",
+    "verify:package": "npm pack --dry-run > /dev/null",
+    "verify:launcher": "PI_OFFLINE=1 ./bin/pi-agentation --list-models > /dev/null"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/agentation-fix-loop/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: agentation-fix-loop
+description: >-
+  Watch for Agentation annotations and fix each one using the Agentation CLI.
+  Runs `agentation watch` in a loop — acknowledges each annotation, makes the
+  code fix, then resolves it. Use when the user says "watch annotations",
+  "fix annotations", "annotation loop", "agentation fix loop", or wants
+  autonomous processing of design feedback from the Agentation toolbar.
+targets:
+  - '*'
+---
+
+# Agentation Fix Loop (CLI)
+
+Watch for annotations from the Agentation toolbar and fix each one in the codebase using the `agentation` CLI.
+
+If this skill is invoked as `/skill:agentation-fix-loop <project-id>`, treat the user-supplied argument as the authoritative project ID for this run and skip repo discovery.
+
+## CLI commands used by this skill
+
+- `agentation start` / `agentation stop` / `agentation status`
+- `agentation projects --json`
+- `agentation pending <project-id> --json`
+- `agentation watch <project-id> --json`
+- `agentation ack <id>`
+- `agentation resolve <id> --summary "..."`
+- `agentation reply <id> --message "..."`
+- `agentation dismiss <id> --reason "..."`
+
+## Preflight (required)
+
+### 1) Ensure the Agentation CLI is available
+
+```bash
+command -v agentation >/dev/null || { echo "agentation CLI not found on PATH"; exit 1; }
+```
+
+If this fails, install or build the Agentation CLI first and ensure the `agentation` binary is on `PATH`.
+
+### 2) Check whether the Agentation stack is already running
+
+```bash
+agentation status
+```
+
+Then verify API reachability (default `http://127.0.0.1:4747`):
+
+```bash
+agentation projects --json >/dev/null
+```
+
+If not running or unreachable, **start it before doing anything else**:
+
+```bash
+agentation start --background
+# or foreground during debugging
+agentation start --foreground
+```
+
+Re-check after start:
+
+```bash
+agentation status
+agentation projects --json >/dev/null
+```
+
+If you only want the HTTP API without router for this run:
+
+```bash
+AGENTATION_ROUTER_ADDR=0 agentation start --background
+```
+
+### 3) Determine the project ID and fetch pending work
+
+If the skill was invoked with a user argument (for example `/skill:agentation-fix-loop project-alpha`), use that `<project-id>` directly and skip discovery.
+
+Otherwise, quickly extract project IDs from your app code:
+
+```bash
+rg -n --glob '*.{tsx,ts,jsx,js}' '<Agentation[^>]*projectId='
+```
+
+If you want to extract a literal string value quickly (when set as `projectId="..."` or `projectId='...'`):
+
+```bash
+rg -o --no-filename --glob '*.{tsx,ts,jsx,js}' "projectId=(?:\"[^\"]+\"|'[^']+')" \
+  | head -n1 \
+  | sed -E "s/projectId=(\"([^\"]+)\"|'([^']+)')/\2\3/"
+```
+
+Then fetch the initial batch:
+
+```bash
+agentation pending <project-id> --json
+```
+
+Process that batch first, then enter watch mode.
+
+### CLI behavior notes
+
+- `agentation start` manages server + router under one process by default.
+- One running Agentation stack is enough for multiple local projects/sessions.
+- Do not start extra instances unless intentionally isolating ports/storage.
+
+## Behavior
+
+1. Call:
+
+```bash
+agentation watch <project-id> --timeout 300 --batch-window 10 --json
+```
+
+2. For each annotation in the returned batch:
+
+   a. **Acknowledge**
+
+   ```bash
+   agentation ack <annotation-id>
+   ```
+
+   b. **Understand**
+   - Read annotation text (`comment`)
+   - Read target context (`element`, `elementPath`, `url`, `nearbyText`, `reactComponents`)
+   - Map to likely source files before editing
+
+   c. **Fix**
+   - Make the code change requested by the annotation
+   - Keep changes minimal and aligned with project conventions
+
+   d. **Resolve**
+
+   ```bash
+   agentation resolve <annotation-id> --summary "<short file + change summary>"
+   ```
+
+3. After processing the batch, loop back to step 1.
+
+4. Stop when:
+   - user says stop, or
+   - watch times out repeatedly with no new work.
+
+## Rules
+
+- Always acknowledge before starting work.
+- Keep resolve summaries concise (1–2 sentences, mention file(s) + result).
+- If unclear, ask via thread reply instead of guessing:
+
+```bash
+agentation reply <annotation-id> --message "I need clarification on ..."
+```
+
+- If not actionable, dismiss with reason:
+
+```bash
+agentation dismiss <annotation-id> --reason "Not actionable because ..."
+```
+
+- Process annotations in received order.
+- Only resolve once the requested change is implemented.
+
+## Required project-scoped loop
+
+Use `<project-id>` as the first argument for all pending/watch commands. Use timeout of at least 300s:
+
+```bash
+agentation projects --json
+agentation pending <project-id> --json
+agentation watch <project-id> --timeout 300 --batch-window 10 --json
+```
+
+## Loop template
+
+```text
+Round 1:
+  agentation pending <project-id> --json
+  -> process all returned annotations
+
+Round 2:
+  agentation watch <project-id> --timeout 300 --batch-window 10 --json
+  -> got 2 annotations
+  -> ack #1, fix, resolve #1
+  -> ack #2, reply (needs clarification)
+
+Round 3:
+  agentation watch <project-id> --timeout 300 --batch-window 10 --json
+  -> got 1 annotation (clarification follow-up)
+  -> ack, fix, resolve
+
+Round 4:
+  agentation watch <project-id> --timeout 300 --batch-window 10 --json
+  -> timeout true, no annotations
+  -> exit (or continue if user requested persistent watch mode)
+```
+
+## Troubleshooting
+
+- `agentation pending` fails: Agentation is not running, base URL is wrong (`agentation start --background`), or `<project-id>` is missing.
+- If using non-default server URL, pass `--base-url` or set `AGENTATION_BASE_URL`.
+- If frontend keeps creating new sessions unexpectedly, verify localStorage/session behavior in the host app or Storybook setup.