Improve Packref agent skill package inspection workflow

[adelrodriguez]

This patch refines the Packref agent skill's inspection workflow with clearer sequencing and more precise language throughout.

The workflow now explicitly handles the case where .packref/packref-lock.json is absent, directing the agent to explain that the project is not initialized rather than proceeding silently. Step 3 is restructured to first identify the exact package identity and local source path before deciding whether to run any command, making the distinction between npx packref install (restores locked references without side effects) and npx packref add or npx packref sync (which can change or remove project state) more explicit.

The command boundaries section is rewritten to describe each command's behavior and guard conditions in consistent imperative form, reinforcing which commands are safe to run autonomously and which require explicit user authorization or request.

The examples are tightened to show the full path after lockfile matching and to clarify that npx packref add should only run when the task scope includes obtaining new source. The failure and fallback section now directs the agent to read the error before taking any corrective action.

[adelrodriguez]

• Improve Packref agent skill package inspection workflow #47 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[pullfrog]

ℹ️ No correctness problems — two coverage gaps inline and one scope question below.

Reviewed changes — a docs-only rewrite of the first-party Packref agent skill, plus its changeset. I checked every command, path, and behavioral claim in the new prose against src/commands/*.ts and src/lib/.

• Missing-lockfile branch made explicit — step 1 now tells the agent to explain that the project is not initialized instead of proceeding, and gates npx packref init behind user authorization.
• Identity-before-command sequencing — step 3 resolves the package identity and reference path before steps 4/5 decide whether to run anything, keeping the non-mutating install distinct from add.
• sync description corrected — the command-boundaries bullet now states that sync can update or remove references, which matches SyncPlan.removals / SyncResult.removed in src/commands/sync.ts.
• install claim verified — "restores all locked references without changing the lockfile" holds; installPackageReferences only reads the lockfile (src/lib/references/install.ts:128).
• Path examples verified — .packref/packages/npm/@effect/platform/0.90.0/ and .packref/packages/npm/react/19.1.0/ match the layout in src/lib/workspace/paths.ts and the reference tests.
• Changeset — patch, consistent with prior practice (CHANGELOG.md 0.2.0 already carries a changeset entry for a skill-only change).

ℹ️ Command guidance now lives in two places and only one was improved

The same command boundaries are documented twice: in this skill, and in the AGENTS.md section template at src/lib/workspace/integration.ts, which ships in dist and is written into every project by packref init. The template is what most agents actually read, and it still describes sync as update-only with none of the authorization guardrails this PR adds. Worth deciding whether the two should track each other or whether the skill is intentionally the richer artifact.

Technical details

# Skill guidance and the shipped AGENTS.md template have diverged

## Affected sites
- `src/lib/workspace/integration.ts:37` — `packref sync` is described as "update dependency-tracked lock entries to match current `package.json` dependency versions", with no mention that it can remove references. `skills/packref/SKILL.md:50-51` now correctly says it can.
- `src/lib/workspace/integration.ts:32-41` — the template's command list carries no "only when the user requests it" guardrails for `remove`, `prune`, `clean`, or `clean --global`. `skills/packref/SKILL.md:52-55` does.

## Required outcome
- A decision on whether the AGENTS.md template is meant to stay a short reference card (in which case nothing to do) or the primary agent-facing contract (in which case the `sync` removal behavior and the destructive-command guardrails should propagate).
- If they are meant to track each other, the divergence should not be able to reappear silently on the next edit to either file.

## Open questions for the human
- Is `skills/packref/SKILL.md` the source of truth for agent guidance, with the AGENTS.md section deliberately abbreviated?

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}

[pullfrog]

This says init "is interactive", but the command has a non-interactive mode built specifically for coding agents: --non-interactive combined with --ignore and --agents (src/commands/init.ts:20-30). Since this skill's whole audience is agents, worth naming that path — and noting that --ignore/--agents without --non-interactive fail with InitFlagsRequireNonInteractiveError (src/commands/init.ts:51-53), which is an easy trap to walk into.

[pullfrog]

Both this bullet and step 5 read as registry-only, but packref add also accepts a direct repository spec, e.g. packref add metaideas/packref (src/commands/add.ts:19-23). The skill already explains source.directory provenance for repository-sourced entries, so an agent can encounter one without ever learning how to create one — and @<version> is the wrong mental model for those.