@juicesharp/rpiv-args 1.1.4 → 1.2.0

package/README.md

@@ -11,7 +11,7 @@
 [![npm version](https://img.shields.io/npm/v/@juicesharp/rpiv-args.svg)](https://www.npmjs.com/package/@juicesharp/rpiv-args)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Pass arguments to your skills like a shell command. `rpiv-args` adds `$1`, `$ARGUMENTS`, `$@`, `${@:N}`, and `${@:N:L}` placeholders to [Pi Agent](https://github.com/badlogic/pi-mono) skills — write `/skill:deploy api production` and your skill body sees `$1` = `api`, `$2` = `production`. Skills without placeholders are untouched, so installing `rpiv-args` is safe for any existing skill collection.
+Pass arguments to your skills like a shell command. `rpiv-args` adds `$1`, `$ARGUMENTS`, `$@`, `${@:N}`, and `${@:N:L}` placeholders to [Pi Agent](https://github.com/badlogic/pi-mono) skills - write `/skill:deploy api production` and your skill body sees `$1` = `api`, `$2` = `production`. Skills without placeholders are untouched, so installing `rpiv-args` is safe for any existing skill collection.
 
 ## Install
 
@@ -31,7 +31,7 @@ Or run `/rpiv-setup` if you have `@juicesharp/rpiv-pi` installed.
 | `${@:N}` | Arguments from position N onward | `/skill:foo a b c` → `${@:2}` = `b c` |
 | `${@:N:L}` | L arguments starting at position N | `/skill:foo a b c d` → `${@:2:2}` = `b c` |
 
-**Indexing is 1-based** — `$1` is the first argument, `$2` is the second.
+**Indexing is 1-based** - `$1` is the first argument, `$2` is the second.
 Out-of-range positions resolve to an empty string. For `${@:N[:L]}`, `N` is
 clamped to `≥ 1` and out-of-range slices yield an empty string.
 
@@ -51,14 +51,14 @@ expansion). When a skill body contains at least one placeholder, the extension:
 1. Parses arguments using shell-style quoting
 2. Substitutes all placeholders in the body
 3. Wraps the result in a `<skill>` block byte-identical to Pi's native format
-4. Appends the raw arguments after the block — matches Pi's standard output so any tool that parses `<skill>` blocks continues to work unchanged
+4. Appends the raw arguments after the block - matches Pi's standard output so any tool that parses `<skill>` blocks continues to work unchanged
 
 When no placeholders are found in the skill body, the output is byte-identical
-to Pi's built-in expansion — zero behavioral change.
+to Pi's built-in expansion - zero behavioral change.
 
 ## Writing skills with arguments
 
-### `$ARGUMENTS` vs `$1` — which to use
+### `$ARGUMENTS` vs `$1` - which to use
 
 Use **`$ARGUMENTS`** (or `$@`) when the input is freeform text the LLM should
 interpret naturally:
@@ -104,7 +104,7 @@ If a positional skill receives natural language input:
 /skill:migrate-component can you migrate the search bar please
 ```
 
-→ `Migrate the can component from you to migrate.` — **broken**.
+→ `Migrate the can component from you to migrate.` - **broken**.
 
 The LLM is good at interpreting `$ARGUMENTS` as a whole, but positional
 placeholders blindly split on spaces. Use `$ARGUMENTS` unless your skill has
@@ -130,17 +130,17 @@ argument-hint: [component] [from] [to]
 ---
 ```
 
-rpiv-args ignores this field — substitution is triggered by placeholders in the body, not the hint.
+rpiv-args ignores this field - substitution is triggered by placeholders in the body, not the hint.
 
 **Note**: Pi currently surfaces `argument-hint` in autocomplete for prompt
 templates (`commands/*.md`) but **not** for skills (`/skill:<name>`). The
 field is read by Pi but not displayed in the `/skill:` autocomplete UI at
-present — treat it as documentation metadata until upstream Pi exposes it.
+present - treat it as documentation metadata until upstream Pi exposes it.
 
 ### Full example
 
 <details>
-<summary>Deploy skill — SKILL.md, invocation, and the exact text the LLM sees</summary>
+<summary>Deploy skill - SKILL.md, invocation, and the exact text the LLM sees</summary>
 
 ```yaml
 ---
@@ -179,7 +179,7 @@ api production
 ```
 
 Note: the raw arguments (`api production`) are also appended after the
-`</skill>` block — this is Pi's standard behavior and is preserved for
+`</skill>` block - this is Pi's standard behavior and is preserved for
 backward compatibility.
 
 </details>

package/args.ts

@@ -1,19 +1,33 @@
 /**
  * rpiv-args — core logic.
  *
- * Intercepts `/skill:<name> <args>` at the input hook and emits a byte-exact
- * Pi skill wrapper with opt-in $N/$ARGUMENTS/$@/${@:N[:L]} substitution on
- * the body. Falls through (returns {action:"continue"}) when the text is not
- * a skill command, the skill is unknown, or the body contains no tokens —
- * keeping Pi's built-in behavior 100% intact for today's 17 rpiv-pi skills.
+ * Intercepts `/skill:<name> <args>` at the input hook and emits a Pi skill
+ * wrapper with opt-in $N/$ARGUMENTS/$@/${@:N[:L]} substitution on the body.
+ * Two emit paths:
+ *   - No-token path: byte-identical to Pi's built-in `_expandSkillCommand`
+ *     output (wrapper + `\n\n${args}` suffix), preserving full backward
+ *     compatibility for skills without placeholders.
+ *   - Token path: substitutes inside the body and INTENTIONALLY drops the
+ *     trailing `\n\n${args}` suffix. The bare imperative outside the block
+ *     hijacks LLM attention from the skill workflow; inside-only emission
+ *     leaves the skill body as the sole user-message payload competing for
+ *     attention. See architecture.md "System-Prompt Protocol & Token-Path
+ *     Divergence".
+ *
+ * Also prepends a skill-invocation protocol to the system prompt every turn
+ * (via before_agent_start) so the LLM treats trailing text after `</skill>`
+ * as the skill's argument input rather than a separate imperative.
  *
  * Byte-exact wrapper requirement: parseSkillBlock regex at
  * node_modules/@mariozechner/pi-coding-agent/dist/core/agent-session.js:40
- * is the load-bearing contract. Do not reformat the template literal below.
+ * is the load-bearing contract for the wrapper itself. Do not reformat the
+ * template literal below.
  */
 
 import { readFileSync } from "node:fs";
 import {
+	type BeforeAgentStartEvent,
+	type BeforeAgentStartEventResult,
 	type ExtensionAPI,
 	getAgentDir,
 	type InputEvent,
@@ -29,13 +43,13 @@ import {
 // ---------------------------------------------------------------------------
 
 /** Matches any placeholder Pi's substituteArgs would replace. Used as the
- *  opt-in gate: absent → pass through verbatim (D2). */
+ *  opt-in gate: absent → pass through verbatim. */
 const TOKEN_REGEX = /\$(?:\d+|ARGUMENTS|@|\{@:\d+(?::\d+)?\})/;
 
-/** Prefix Pi uses (`agent-session.js:829`). Single-space tokenisation (D7). */
+/** Prefix Pi uses (`agent-session.js:829`). Single-space tokenisation. */
 const SKILL_PREFIX = "/skill:";
 
-/** Re-entrancy guard (D8). */
+/** Re-entrancy guard. */
 const WRAPPED_PREFIX = "<skill ";
 
 // ---------------------------------------------------------------------------
@@ -151,13 +165,13 @@ function appendArgs(skillBlock: string, args: string): string {
 export function handleInput(event: InputEvent): InputEventResult {
 	const text = event.text;
 
-	// D8 re-entrancy: already-wrapped text (from our own or any other
+	// Re-entrancy: already-wrapped text (from our own or any other
 	// extension's {action:"transform"}) passes through untouched.
 	if (text.startsWith(WRAPPED_PREFIX)) return { action: "continue" };
 
 	if (!text.startsWith(SKILL_PREFIX)) return { action: "continue" };
 
-	// D7 single-space tokenisation — byte-match Pi's indexOf(" ") at :831.
+	// Single-space tokenisation — byte-match Pi's indexOf(" ") at :831.
 	const spaceIndex = text.indexOf(" ");
 	const skillName = spaceIndex === -1 ? text.slice(SKILL_PREFIX.length) : text.slice(SKILL_PREFIX.length, spaceIndex);
 	const argsString = spaceIndex === -1 ? "" : text.slice(spaceIndex + 1).trim();
@@ -173,17 +187,39 @@ export function handleInput(event: InputEvent): InputEventResult {
 	}
 
 	const { frontmatter } = parseFrontmatter<{ "argument-hint"?: string }>(content);
-	void frontmatter; // informational only in v1 — D3
+	void frontmatter; // informational only in v1
 	const body = stripFrontmatter(content).trim();
 
-	// D2 opt-in gate: if body has no token, emit byte-identical to Pi's :841.
+	// Opt-in gate: if body has no token, emit byte-identical to Pi's :841.
 	if (!TOKEN_REGEX.test(body)) {
 		return { action: "transform", text: appendArgs(buildSkillBlock(entry, body), argsString) };
 	}
 
 	const parsed = parseCommandArgs(argsString);
 	const substituted = substituteArgs(body, parsed);
-	return { action: "transform", text: appendArgs(buildSkillBlock(entry, substituted), argsString) };
+	// Substitution consumes the args — do not also append them after </skill>.
+	// Bare trailing imperatives hijack LLM attention from the skill body. See architecture.md.
+	return { action: "transform", text: buildSkillBlock(entry, substituted) };
+}
+
+// ---------------------------------------------------------------------------
+// Skill-invocation protocol — prepended to the system prompt every turn via
+// before_agent_start. See architecture.md for rationale and re-application
+// semantics (agent-session.js:112-113 — Pi's canonical per-turn pattern).
+// ---------------------------------------------------------------------------
+
+export const SKILL_INVOCATION_PROTOCOL = `## Skill invocation protocol (CRITICAL)
+
+A \`<skill name="..." location="...">...</skill>\` block in a user message is a structured invocation. Handle it as follows:
+
+1. The block body defines the workflow you must execute. Follow it.
+2. Any text after \`</skill>\` is the user's argument input to that skill — never a separate command, even when it reads as an imperative ("create X", "update Y", "delete Z").
+3. Do not bypass the skill's workflow to act on trailing text directly. The user invoked the skill because they want the skill's workflow applied to that input.
+
+`;
+
+export function handleBeforeAgentStart(event: BeforeAgentStartEvent): BeforeAgentStartEventResult {
+	return { systemPrompt: SKILL_INVOCATION_PROTOCOL + event.systemPrompt };
 }
 
 // ---------------------------------------------------------------------------
@@ -192,6 +228,7 @@ export function handleInput(event: InputEvent): InputEventResult {
 
 export function registerArgsHandler(pi: ExtensionAPI): void {
 	pi.on("input", (event) => handleInput(event));
+	pi.on("before_agent_start", (event) => handleBeforeAgentStart(event));
 	pi.on("session_start", (event) => {
 		if (event.reason === "reload" || event.reason === "startup") {
 			invalidateSkillIndex();

package/index.ts

@@ -1,8 +1,9 @@
 /**
  * rpiv-args — Pi extension entry point.
  *
- * Registers the `input` event handler + a `session_start` cache invalidator.
- * All logic lives in args.ts.
+ * Registers the `input` event handler, a `before_agent_start` system-prompt
+ * augmenter, and a `session_start` cache invalidator. All logic lives in
+ * args.ts.
  */
 
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@juicesharp/rpiv-args",
-  "version": "1.1.4",
-  "description": "Pi extension: pass shell-style $1 / $ARGUMENTS placeholders to your Pi skills",
+  "version": "1.2.0",
+  "description": "Pi extension. Shell-style $1 and $ARGUMENTS placeholders, expanded into your Pi skills at invocation.",
   "keywords": [
     "pi-package",
     "pi-extension",