mirror of
https://github.com/backnotprop/plannotator.git
synced 2026-09-14 14:17:26 +08:00
Michael Ramos
747b5ea7e6
* fix(annotate): resolve natural-language arguments or hand off to the agent Claude Code skills run the CLI through a bash-substitution prefix that executes before the model sees anything, so any trailing natural language in /plannotator-annotate died with 'File not found: the'. Worse, a non-zero exit from that prefix aborts the whole prompt before the model runs (verified empirically), so the error was never even visible to the agent. Three-tier resolution in the binary's annotate argument handling, shared by every host via packages/shared/annotate-target.ts: 1. Fast path: probe each whitespace-delimited token; exactly one naming an existing file, URL, or folder proceeds with it directly. 2. Ambiguity: two or more tokens resolve; error naming every candidate, never guess. 3. Handoff: nothing resolves; emit an agent-addressed message echoing the words tried and asking the reading agent to interpret the request and re-run with a concrete target, preserving flags. In plain mode it lands on stdout with exit 0, the only combination that reaches the model through the bang prefix; in --json/--hook mode it goes to stderr with exit 1 so machine stdout stays clean. Single-token invocations run the unchanged pipeline first, so bare correct invocations are byte-identical. Strict gates (--require-approval or --result-file) bypass the tolerance entirely: a typo'd path stays a startup failure with exit 2 and no agent-facing prose. The CLI resolution pipeline moves to apps/hook/server/annotate-resolution.ts (returns typed outcomes instead of exiting) so the token fallback can run it once with a selected candidate; OpenCode and Pi wire the same shared selection into their own not-found paths. Skill bodies gain one line telling the agent to re-run with a concrete target when the command reports unresolvable arguments. Closes #1182 Reported-by: @technicalpickles * fix(annotate): harden tolerant resolution per review Review fixes for the three-tier annotate argument handling: - A single unresolvable token now falls through to the legacy pipeline verbatim: 'annotate nope.md' is exit 1 with 'File not found: nope.md' again in every non-strict mode, instead of an exit-0 handoff that fail-opened scripts gating on the exit code. The handoff fires only when two or more words resolve to nothing. - Unrecognized dash-prefixed tokens disable tolerance instead of being skipped, so a typo'd flag ('--no-jna') errors the way it did on base rather than silently fetching via Jina. Known flags are stripped before selection as before. - Token selection now receives the original argv tokens, so a quoted missing path ('my notes.md') is probed as one token and can never be re-split into a silently resolving 'notes.md'. - Bare directory names only count as fast-path candidates when they are the sole argument; a stray word matching a directory (or '.') hands off instead of opening folder mode. Explicit paths like 'src/' keep resolving, and the bare-existence probe fallback is file-only. - The handoff re-run suggestion echoes content flags only (--markdown, --no-jina, --render-html), never transport flags (--gate, --json, --hook). - New subprocess suite (annotate-cli.test.ts) spawns the real CLI entry and pins the contract: single-token typo exit 1, strict invocations (--require-approval and --result-file) exit 2 with empty stdout and no handoff prose, unknown-flag error, quoted-token preservation, and the directory-hijack case. Placeholder dist files are created when a build is absent so the suite runs in CI. - The copilot and gemini annotate command bodies gain the same handoff instruction as the Claude, core, and kiro skills. - AGENTS.md documents the three tiers under Annotate Flow and corrects the strict-section sentences that claimed non-strict behavior was fully unchanged; the marketing annotate doc mentions the tolerant arguments. Refs #1182
Plannotator Kiro CLI Integration
Source package for Plannotator's Kiro CLI support. These files are consumed by the main installer
(scripts/install.sh) — there is no separate Kiro installer. A Kiro user installs with the same
one-liner as everyone else.
Contents
-
skills/— Kiro-specific skill packages (plannotator-review,plannotator-annotate), each bakingPLANNOTATOR_ORIGIN=kiro-cliinto its command. -
agents/plannotator.json— an example Kiro custom agent that exposes the Plannotator skills viaskill://resources and aplannotator-scopedshelltool.
How it installs
scripts/install.sh auto-detects Kiro (if ~/.kiro exists or kiro-cli is on PATH — the same
convention used for Codex and Gemini) and installs:
- the 2 Kiro-specific skills above →
~/.kiro/skills - the 2 shared skills
plannotator-setup-goalandplannotator-visual-explainer(pulled fromapps/skills/extra/, not duplicated here) →~/.kiro/skills - the example agent
agents/plannotator.json→~/.kiro/agents/plannotator.json(an existing file is never overwritten)
curl -fsSL https://plannotator.ai/install.sh | bash
Use the Plannotator agent
The installed agent wires all four skills via skill:// resources and, in its prompt, documents
which skill to use for which task (review, annotate, setup-goal, visual-explainer). Launch
it:
kiro-cli chat --agent plannotator
Or add the same skill://~/.kiro/skills/plannotator-*/SKILL.md resources to one of your own agents.
Schema note
agents/plannotator.json is a conservative example. If Kiro changes its custom-agent schema, adapt
the installed copy at ~/.kiro/agents/plannotator.json.