@alexgorbatchev/pi-agentation 3.0.0 → 3.1.0

package/bin/pi-agentation

@@ -14,7 +14,50 @@ done
 SCRIPT_DIR="$(cd -P "$(dirname "${SOURCE_PATH}")" && pwd)"
 PACKAGE_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
 
-exec pi \
+find_local_bin() {
+  local start_dir="$1"
+  local executable_name="$2"
+  local current_dir="${start_dir}"
+
+  while true; do
+    local candidate_path="${current_dir}/node_modules/.bin/${executable_name}"
+    if [[ -x "${candidate_path}" ]]; then
+      printf '%s\n' "${candidate_path}"
+      return 0
+    fi
+
+    local parent_dir
+    parent_dir="$(dirname "${current_dir}")"
+    if [[ "${parent_dir}" == "${current_dir}" ]]; then
+      return 1
+    fi
+
+    current_dir="${parent_dir}"
+  done
+}
+
+resolve_executable() {
+  local executable_name="$1"
+  local resolved_path=""
+
+  if resolved_path="$(find_local_bin "${PWD}" "${executable_name}")"; then
+    printf '%s\n' "${resolved_path}"
+    return 0
+  fi
+
+  if resolved_path="$(command -v "${executable_name}" 2>/dev/null)"; then
+    printf '%s\n' "${resolved_path}"
+    return 0
+  fi
+
+  printf 'Required executable "%s" was not found in node_modules/.bin or PATH\n' "${executable_name}" >&2
+  exit 1
+}
+
+PI_BIN="$(resolve_executable pi)"
+AGENTATION_BIN="$(resolve_executable agentation)"
+
+exec env PI_AGENTATION_AGENTATION_BIN="${AGENTATION_BIN}" "${PI_BIN}" \
   -e "${PACKAGE_ROOT}/agentation.ts" \
-  --skill "${PACKAGE_ROOT}/skills/agentation-fix-loop/SKILL.md" \
+  --skill "${PACKAGE_ROOT}/skills/agentation/SKILL.md" \
   "$@"

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@alexgorbatchev/pi-agentation",
-  "version": "3.0.0",
-  "description": "pi extension launcher for the Agentation fix loop",
+  "version": "3.1.0",
+  "description": "pi extension launcher for Agentation Fork",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alexgorbatchev/pi-agentation"
+  },
   "license": "MIT",
   "keywords": [
     "pi-package",
@@ -23,19 +27,17 @@
     "agentation.ts",
     "README.md",
     "bin/pi-agentation",
-    "skills/agentation-fix-loop/SKILL.md"
+    "skills/agentation/SKILL.md"
   ],
   "peerDependencies": {
     "@mariozechner/pi-coding-agent": "*"
   },
   "devDependencies": {
-    "@alexgorbatchev/agentation-skills": "^1.0.0",
+    "@alexgorbatchev/agentation-cli": "^1.0.3",
     "@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",
+    "check": "npm run verify:package && npm run verify:launcher",
     "verify:package": "npm pack --dry-run > /dev/null",
     "verify:launcher": "PI_OFFLINE=1 ./bin/pi-agentation --list-models > /dev/null"
   },

package/skills/agentation/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: agentation
+description: >-
+  Process exactly one Agentation Fork batch that was already fetched by the
+  pi-agentation extension. Acknowledge each annotation, make the requested code
+  change, then resolve, reply, or dismiss it. Use when the extension dispatches
+  `/skill:agentation <project-id>` for a ready batch, or when the user
+  explicitly wants to continue the current batch.
+targets:
+  - '*'
+---
+
+# Agentation Fork Batch Processor
+
+Process exactly one Agentation Fork annotation batch for the supplied `<project-id>`.
+
+If this skill is invoked as `/skill:agentation <project-id>`, treat the user-supplied argument as the authoritative project ID for this run.
+
+## Extension contract
+
+The `pi-agentation` extension owns polling and batching.
+
+That means:
+
+- The extension already ran `agentation pending` or `agentation watch`
+- The extension injected the current batch as an extension context message
+- You must process **only that provided batch**
+- You must **not** start or manage your own polling loop
+
+## Do not do these commands here
+
+Do **not** run any of the following from this skill:
+
+- `agentation start`
+- `agentation status`
+- `agentation projects`
+- `agentation pending`
+- `agentation watch`
+
+Those belong to the extension, not to this skill.
+
+## Allowed Agentation Fork CLI commands
+
+Use only the annotation lifecycle commands needed to process the provided batch:
+
+- `agentation ack <annotation-id>`
+- `agentation resolve <annotation-id> --summary "..."`
+- `agentation reply <annotation-id> --message "..."`
+- `agentation dismiss <annotation-id> --reason "..."`
+
+## Required workflow
+
+For each annotation in the provided batch, in order:
+
+1. **Acknowledge it first**
+
+   ```bash
+   agentation ack <annotation-id>
+   ```
+
+2. **Understand the request**
+   - Read the annotation fields from the extension-provided batch context
+   - Inspect the relevant files
+   - Infer the smallest correct change
+
+3. **Implement the fix**
+   - Keep changes minimal
+   - Follow repo conventions
+   - Do not broaden scope without evidence
+
+4. **Finish the annotation with exactly one terminal action**
+
+   Resolve when fixed:
+
+   ```bash
+   agentation resolve <annotation-id> --summary "<short file + change summary>"
+   ```
+
+   Reply when clarification is required:
+
+   ```bash
+   agentation reply <annotation-id> --message "I need clarification on ..."
+   ```
+
+   Dismiss when not actionable:
+
+   ```bash
+   agentation dismiss <annotation-id> --reason "Not actionable because ..."
+   ```
+
+## Important execution rules
+
+- Process annotations in the order they appear in the provided batch
+- Do not invent or fetch another batch
+- Do not leave the skill running after the provided batch is handled
+- Run each `agentation ack|resolve|reply|dismiss` as a **separate bash command** so the extension can track completion reliably
+- Keep resolve summaries concise and concrete
+- Only resolve once the requested change is actually implemented
+
+## If no batch context is present
+
+If the extension context says there is no active batch:
+
+- report that clearly
+- do not try to poll Agentation Fork yourself
+- tell the user to resume the extension loop with `/agentation-loop-start`
+
+## Completion condition
+
+Stop after the current provided batch has been fully processed.
+
+This is a **one-shot batch processor**, not a watcher.

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

@@ -1,199 +0,0 @@
----
-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.