@asterxsk/kiln 0.3.0 → 0.4.2

package/agent/extensions/goal/README.md

@@ -1,50 +1,50 @@
-# goal
-
-Keep the agent working until a goal is achieved.
-
-## Command
-
-| Command | Action |
-|---|---|
-| `/goal <prompt>` | Runs the workflow below, looping until you confirm the goal is achieved |
-| `/goal` | Prompts for the goal interactively, then runs the same workflow |
-
-`/goal` with no argument opens an input dialog; if the dialog is cancelled or
-left empty, nothing runs.
-
-## Workflow
-
-`/goal <prompt>` injects an instruction into the main agent that runs four
-phases in order:
-
-1. **Research** — web-search the goal to ground the design.
-2. **Design** — follow the `brainstorming` skill; present the design for
-   approval, then save the design doc to `docs/superpowers/specs/`.
-3. **Plan** — follow the `writing-plans` skill; save a bite-sized plan to
-   `docs/superpowers/plans/`.
-4. **Implement and verify** — write the code, tests, and docs; run them and
-   fix failures until the goal actually works.
-
-### The loop
-
-After the agent settles, `/goal` asks you what to do next:
-
-- **Continue working toward the goal** — re-engages the agent to keep going,
-  respecting the phase gates (it won't skip design approval).
-- **Goal achieved - stop** — ends the loop.
-- **Pause - stop checking** — ends the loop and leaves you to take over
-  manually.
-
-The loop runs in the interactive TUI (it needs to ask you). In RPC and
-print/JSON modes there is no dialog, so the agent works a single pass and the
-loop ends. The workflow always stops after Phase 2 and waits for you to approve
-the design doc before planning and implementing.
-
-## Files
-
-- `index.ts` — registers the `/goal` command, builds the phase instruction,
-  and re-engages the agent on `agent_settled`
-- `README.md` — this file
-
-Nothing is written into the extension folder; the design and plan land in the
-project's `docs/superpowers/` tree (the skills' default locations).
+# goal
+
+Keep the agent working until a goal is achieved.
+
+## Command
+
+| Command | Action |
+|---|---|
+| `/goal <prompt>` | Runs the workflow below, looping until you confirm the goal is achieved |
+| `/goal` | Prompts for the goal interactively, then runs the same workflow |
+
+`/goal` with no argument opens an input dialog; if the dialog is cancelled or
+left empty, nothing runs.
+
+## Workflow
+
+`/goal <prompt>` injects an instruction into the main agent that runs four
+phases in order:
+
+1. **Research** — web-search the goal to ground the design.
+2. **Design** — follow the `brainstorming` skill; present the design for
+   approval, then save the design doc to `docs/superpowers/specs/`.
+3. **Plan** — follow the `writing-plans` skill; save a bite-sized plan to
+   `docs/superpowers/plans/`.
+4. **Implement and verify** — write the code, tests, and docs; run them and
+   fix failures until the goal actually works.
+
+### The loop
+
+After the agent settles, `/goal` asks you what to do next:
+
+- **Continue working toward the goal** — re-engages the agent to keep going,
+  respecting the phase gates (it won't skip design approval).
+- **Goal achieved - stop** — ends the loop.
+- **Pause - stop checking** — ends the loop and leaves you to take over
+  manually.
+
+The loop runs in the interactive TUI (it needs to ask you). In RPC and
+print/JSON modes there is no dialog, so the agent works a single pass and the
+loop ends. The workflow always stops after Phase 2 and waits for you to approve
+the design doc before planning and implementing.
+
+## Files
+
+- `index.ts` — registers the `/goal` command, builds the phase instruction,
+  and re-engages the agent on `agent_settled`
+- `README.md` — this file
+
+Nothing is written into the extension folder; the design and plan land in the
+project's `docs/superpowers/` tree (the skills' default locations).

package/agent/extensions/goal/index.ts

@@ -1,155 +1,155 @@
-/**
- * goal — keep the agent working until the goal is achieved.
- *
- * Commands:
- *   /goal <prompt>   Research → design → plan → implement → verify, looping
- *                    until you confirm the goal is achieved.
- *   /goal            Prompts for the goal interactively.
- *
- * After the agent settles, this extension asks whether to keep working, mark
- * the goal achieved, or pause. "Keep working" re-engages the agent until the
- * goal is done. See README.md for the phase-by-phase workflow.
- */
-
-import { homedir } from "node:os";
-import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-
-const HOME = homedir().replace(/\\/g, "/");
-const BRAINSTORMING_SKILL = `${HOME}/.agents/skills/brainstorming/SKILL.md`;
-const WRITING_PLANS_SKILL = `${HOME}/.agents/skills/writing-plans/SKILL.md`;
-
-/** Shared closing instruction for every /goal pass. */
-const REPORT_TAIL = "When you finish a pass, report what is done, what remains, and whether the goal is achieved.";
-
-/** The goal the agent is currently working toward, or null when idle. */
-let activeGoal: string | null = null;
-
-function shortGoal(goal: string): string {
-	const s = goal.replace(/\s+/g, " ").trim();
-	return s.length > 60 ? `${s.slice(0, 60)}…` : s;
-}
-
-function buildInstruction(goal: string): string {
-	return [
-		"You are executing a /goal workflow: research, then design, then plan, then implement and verify — working until the goal is achieved.",
-		"",
-		"GOAL:",
-		goal,
-		"",
-		"Work through the phases in order.",
-		"",
-		"PHASE 1 — RESEARCH",
-		"- Use web_search to research the goal: relevant technologies, existing libraries and approaches, best practices, constraints, and open questions.",
-		"- Gather grounded facts to inform the design; cite what you learn in the design doc.",
-		"",
-		"PHASE 2 — DESIGN",
-		`- First read the brainstorming skill: ${BRAINSTORMING_SKILL}. Follow it.`,
-		"- Ask clarifying questions one at a time (use ask_user when a choice can be enumerated) to pin down purpose, constraints, and success criteria.",
-		"- Propose 2-3 approaches with trade-offs and a recommendation; present the design in sections and get approval after each section.",
-		"- When the design is approved, save it to docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md and ask the user to review it.",
-		"- STOP here and wait for the user to approve the design doc. Do not begin later phases until the user explicitly approves.",
-		"",
-		"PHASE 3 — PLAN",
-		`- First read the writing-plans skill: ${WRITING_PLANS_SKILL}. Follow it.`,
-		"- Write a detailed, bite-sized implementation plan with no placeholders and save it to docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md.",
-		"",
-		"PHASE 4 — IMPLEMENT AND VERIFY",
-		"- Implement the plan: write the actual code, tests, and docs.",
-		"- Run the tests and any verification; fix failures until everything passes.",
-		"- Verify the goal is actually achieved and working, not just that code was written.",
-		"",
-		REPORT_TAIL,
-	].join("\n");
-}
-
-function buildContinueInstruction(goal: string): string {
-	return [
-		`Continue working toward the goal: ${goal}`,
-		"",
-		"Review the current state and resume the /goal workflow from where you left off, respecting the phase gates:",
-		"- If the design has not been approved yet: present the design and STOP for approval. Do not plan or implement until the user approves.",
-		"- If the design is approved but the plan is not written: follow the writing-plans skill and write the plan.",
-		"- Otherwise: implement and verify, fixing failures until everything passes.",
-		"If you are blocked or need a decision, ask the user.",
-		REPORT_TAIL,
-	].join("\n");
-}
-
-async function runGoal(pi: ExtensionAPI, ctx: ExtensionCommandContext, goal: string): Promise<void> {
-	activeGoal = goal;
-	if (ctx.isIdle()) {
-		await pi.sendUserMessage(buildInstruction(goal));
-	} else {
-		await pi.sendUserMessage(buildInstruction(goal), { deliverAs: "followUp" });
-	}
-	ctx.ui.notify("goal: working until achieved", "info");
-}
-
-export default function (pi: ExtensionAPI) {
-	pi.registerCommand("goal", {
-		description:
-			"Keep the agent working until a goal is achieved: web research, brainstorming design, writing-plans plan, implement and verify",
-		handler: async (args, ctx) => {
-			let goal = (args ?? "").trim();
-			if (!goal) {
-				if (!ctx.hasUI) {
-					console.error("Usage: /goal <goal> - work on it until it is achieved");
-					return;
-				}
-				const typed = await ctx.ui.input("What goal would you like to achieve?", "e.g. add a /goal extension to pi");
-				goal = (typed ?? "").trim();
-				if (!goal) return;
-			}
-			await runGoal(pi, ctx, goal);
-		},
-	});
-
-	// Re-engage the agent after each settle until the goal is achieved.
-	pi.on("agent_settled", async (_event, ctx) => {
-		if (!activeGoal) return;
-
-		// The interactive loop needs the TUI: awaiting a dialog from inside
-		// the settle handler can deadlock RPC clients, and print/JSON modes
-		// can't prompt at all. Stop the loop rather than spin.
-		if (ctx.mode !== "tui") {
-			activeGoal = null;
-			return;
-		}
-
-		const choice = await ctx.ui.select(`Goal: ${shortGoal(activeGoal)}`, [
-			"Continue working toward the goal",
-			"Goal achieved - stop",
-			"Pause - stop checking",
-		]);
-
-		// Esc / cancel → pause, so the loop never runs away.
-		if (!choice || choice === "Pause - stop checking") {
-			activeGoal = null;
-			ctx.ui.notify("goal: paused - take over manually", "info");
-			return;
-		}
-
-		if (choice === "Goal achieved - stop") {
-			activeGoal = null;
-			ctx.ui.notify("goal: marked achieved", "info");
-			return;
-		}
-
-		// "Continue working toward the goal"
-		if (ctx.isIdle()) {
-			await pi.sendUserMessage(buildContinueInstruction(activeGoal));
-		} else {
-			await pi.sendUserMessage(buildContinueInstruction(activeGoal), { deliverAs: "followUp" });
-		}
-		ctx.ui.notify("goal: continuing...", "info");
-	});
-
-	// Reset state on session boundaries so a stale goal never leaks into a
-	// fresh session (or across /reload).
-	pi.on("session_start", () => {
-		activeGoal = null;
-	});
-	pi.on("session_shutdown", () => {
-		activeGoal = null;
-	});
-}
+/**
+ * goal — keep the agent working until the goal is achieved.
+ *
+ * Commands:
+ *   /goal <prompt>   Research → design → plan → implement → verify, looping
+ *                    until you confirm the goal is achieved.
+ *   /goal            Prompts for the goal interactively.
+ *
+ * After the agent settles, this extension asks whether to keep working, mark
+ * the goal achieved, or pause. "Keep working" re-engages the agent until the
+ * goal is done. See README.md for the phase-by-phase workflow.
+ */
+
+import { homedir } from "node:os";
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+
+const HOME = homedir().replace(/\\/g, "/");
+const BRAINSTORMING_SKILL = `${HOME}/.agents/skills/brainstorming/SKILL.md`;
+const WRITING_PLANS_SKILL = `${HOME}/.agents/skills/writing-plans/SKILL.md`;
+
+/** Shared closing instruction for every /goal pass. */
+const REPORT_TAIL = "When you finish a pass, report what is done, what remains, and whether the goal is achieved.";
+
+/** The goal the agent is currently working toward, or null when idle. */
+let activeGoal: string | null = null;
+
+function shortGoal(goal: string): string {
+	const s = goal.replace(/\s+/g, " ").trim();
+	return s.length > 60 ? `${s.slice(0, 60)}…` : s;
+}
+
+function buildInstruction(goal: string): string {
+	return [
+		"You are executing a /goal workflow: research, then design, then plan, then implement and verify — working until the goal is achieved.",
+		"",
+		"GOAL:",
+		goal,
+		"",
+		"Work through the phases in order.",
+		"",
+		"PHASE 1 — RESEARCH",
+		"- Use web_search to research the goal: relevant technologies, existing libraries and approaches, best practices, constraints, and open questions.",
+		"- Gather grounded facts to inform the design; cite what you learn in the design doc.",
+		"",
+		"PHASE 2 — DESIGN",
+		`- First read the brainstorming skill: ${BRAINSTORMING_SKILL}. Follow it.`,
+		"- Ask clarifying questions one at a time (use ask_user when a choice can be enumerated) to pin down purpose, constraints, and success criteria.",
+		"- Propose 2-3 approaches with trade-offs and a recommendation; present the design in sections and get approval after each section.",
+		"- When the design is approved, save it to docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md and ask the user to review it.",
+		"- STOP here and wait for the user to approve the design doc. Do not begin later phases until the user explicitly approves.",
+		"",
+		"PHASE 3 — PLAN",
+		`- First read the writing-plans skill: ${WRITING_PLANS_SKILL}. Follow it.`,
+		"- Write a detailed, bite-sized implementation plan with no placeholders and save it to docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md.",
+		"",
+		"PHASE 4 — IMPLEMENT AND VERIFY",
+		"- Implement the plan: write the actual code, tests, and docs.",
+		"- Run the tests and any verification; fix failures until everything passes.",
+		"- Verify the goal is actually achieved and working, not just that code was written.",
+		"",
+		REPORT_TAIL,
+	].join("\n");
+}
+
+function buildContinueInstruction(goal: string): string {
+	return [
+		`Continue working toward the goal: ${goal}`,
+		"",
+		"Review the current state and resume the /goal workflow from where you left off, respecting the phase gates:",
+		"- If the design has not been approved yet: present the design and STOP for approval. Do not plan or implement until the user approves.",
+		"- If the design is approved but the plan is not written: follow the writing-plans skill and write the plan.",
+		"- Otherwise: implement and verify, fixing failures until everything passes.",
+		"If you are blocked or need a decision, ask the user.",
+		REPORT_TAIL,
+	].join("\n");
+}
+
+async function runGoal(pi: ExtensionAPI, ctx: ExtensionCommandContext, goal: string): Promise<void> {
+	activeGoal = goal;
+	if (ctx.isIdle()) {
+		await pi.sendUserMessage(buildInstruction(goal));
+	} else {
+		await pi.sendUserMessage(buildInstruction(goal), { deliverAs: "followUp" });
+	}
+	ctx.ui.notify("goal: working until achieved", "info");
+}
+
+export default function (pi: ExtensionAPI) {
+	pi.registerCommand("goal", {
+		description:
+			"Keep the agent working until a goal is achieved: web research, brainstorming design, writing-plans plan, implement and verify",
+		handler: async (args, ctx) => {
+			let goal = (args ?? "").trim();
+			if (!goal) {
+				if (!ctx.hasUI) {
+					console.error("Usage: /goal <goal> - work on it until it is achieved");
+					return;
+				}
+				const typed = await ctx.ui.input("What goal would you like to achieve?", "e.g. add a /goal extension to pi");
+				goal = (typed ?? "").trim();
+				if (!goal) return;
+			}
+			await runGoal(pi, ctx, goal);
+		},
+	});
+
+	// Re-engage the agent after each settle until the goal is achieved.
+	pi.on("agent_settled", async (_event, ctx) => {
+		if (!activeGoal) return;
+
+		// The interactive loop needs the TUI: awaiting a dialog from inside
+		// the settle handler can deadlock RPC clients, and print/JSON modes
+		// can't prompt at all. Stop the loop rather than spin.
+		if (ctx.mode !== "tui") {
+			activeGoal = null;
+			return;
+		}
+
+		const choice = await ctx.ui.select(`Goal: ${shortGoal(activeGoal)}`, [
+			"Continue working toward the goal",
+			"Goal achieved - stop",
+			"Pause - stop checking",
+		]);
+
+		// Esc / cancel → pause, so the loop never runs away.
+		if (!choice || choice === "Pause - stop checking") {
+			activeGoal = null;
+			ctx.ui.notify("goal: paused - take over manually", "info");
+			return;
+		}
+
+		if (choice === "Goal achieved - stop") {
+			activeGoal = null;
+			ctx.ui.notify("goal: marked achieved", "info");
+			return;
+		}
+
+		// "Continue working toward the goal"
+		if (ctx.isIdle()) {
+			await pi.sendUserMessage(buildContinueInstruction(activeGoal));
+		} else {
+			await pi.sendUserMessage(buildContinueInstruction(activeGoal), { deliverAs: "followUp" });
+		}
+		ctx.ui.notify("goal: continuing...", "info");
+	});
+
+	// Reset state on session boundaries so a stale goal never leaks into a
+	// fresh session (or across /reload).
+	pi.on("session_start", () => {
+		activeGoal = null;
+	});
+	pi.on("session_shutdown", () => {
+		activeGoal = null;
+	});
+}

package/agent/extensions/goal/install.ps1

@@ -1,27 +1,27 @@
-#!/usr/bin/env pwsh
-# Per-extension installer — Windows / PowerShell
-# Installs npm dependencies for this extension. No-op if no package.json.
-$ErrorActionPreference = "Stop"
-# Drop npm_config_allow_scripts inherited from a parent npm/npx process:
-# npm >=11 rejects it for project installs (EALLOWSCRIPTS). File config still applies.
-Remove-Item Env:\npm_config_allow_scripts -ErrorAction SilentlyContinue
-Remove-Item Env:\NPM_CONFIG_ALLOW_SCRIPTS -ErrorAction SilentlyContinue
-$extDir = $PSScriptRoot
-if (-not $extDir) { $extDir = Split-Path -Parent $MyInvocation.MyCommand.Path }
-if (-not (Test-Path "$extDir/package.json")) {
-  Write-Host "  - no package.json — skipping" -ForegroundColor DarkGray
-  exit 0
-}
-if (-not (Get-Command npm -ErrorAction SilentlyContinue)) {
-  Write-Host "  x npm not found — install Node.js 22+" -ForegroundColor Red
-  exit 1
-}
-if (Test-Path "$extDir/package-lock.json") {
-  Write-Host "  - npm ci" -ForegroundColor DarkGray
-  npm --prefix $extDir ci --no-audit --no-fund
-} else {
-  Write-Host "  - npm install" -ForegroundColor DarkGray
-  npm --prefix $extDir install --no-audit --no-fund
-}
-if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
-Write-Host "  + done" -ForegroundColor Green
+#!/usr/bin/env pwsh
+# Per-extension installer — Windows / PowerShell
+# Installs npm dependencies for this extension. No-op if no package.json.
+$ErrorActionPreference = "Stop"
+# Drop npm_config_allow_scripts inherited from a parent npm/npx process:
+# npm >=11 rejects it for project installs (EALLOWSCRIPTS). File config still applies.
+Remove-Item Env:\npm_config_allow_scripts -ErrorAction SilentlyContinue
+Remove-Item Env:\NPM_CONFIG_ALLOW_SCRIPTS -ErrorAction SilentlyContinue
+$extDir = $PSScriptRoot
+if (-not $extDir) { $extDir = Split-Path -Parent $MyInvocation.MyCommand.Path }
+if (-not (Test-Path "$extDir/package.json")) {
+  Write-Host "  - no package.json — skipping" -ForegroundColor DarkGray
+  exit 0
+}
+if (-not (Get-Command npm -ErrorAction SilentlyContinue)) {
+  Write-Host "  x npm not found — install Node.js 22+" -ForegroundColor Red
+  exit 1
+}
+if (Test-Path "$extDir/package-lock.json") {
+  Write-Host "  - npm ci" -ForegroundColor DarkGray
+  npm --prefix $extDir ci --no-audit --no-fund
+} else {
+  Write-Host "  - npm install" -ForegroundColor DarkGray
+  npm --prefix $extDir install --no-audit --no-fund
+}
+if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+Write-Host "  + done" -ForegroundColor Green

package/agent/extensions/goal/install.sh

@@ -1,24 +1,24 @@
-#!/bin/sh
-# Per-extension installer — macOS / Linux
-# Installs npm dependencies for this extension. No-op if no package.json.
-set -eu
-# Drop npm_config_allow_scripts inherited from a parent npm/npx process:
-# npm >=11 rejects it for project installs (EALLOWSCRIPTS). File config still applies.
-unset npm_config_allow_scripts NPM_CONFIG_ALLOW_SCRIPTS 2>/dev/null || true
-EXT_DIR="$(cd "$(dirname "$0")" && pwd)"
-if [ ! -f "$EXT_DIR/package.json" ]; then
-  echo "  · no package.json — skipping"
-  exit 0
-fi
-if ! command -v npm >/dev/null 2>&1; then
-  echo "  ✖ npm not found — install Node.js 22+" >&2
-  exit 1
-fi
-if [ -f "$EXT_DIR/package-lock.json" ]; then
-  echo "  · npm ci"
-  npm --prefix "$EXT_DIR" ci --no-audit --no-fund
-else
-  echo "  · npm install"
-  npm --prefix "$EXT_DIR" install --no-audit --no-fund
-fi
-echo "  ✓ done"
+#!/bin/sh
+# Per-extension installer — macOS / Linux
+# Installs npm dependencies for this extension. No-op if no package.json.
+set -eu
+# Drop npm_config_allow_scripts inherited from a parent npm/npx process:
+# npm >=11 rejects it for project installs (EALLOWSCRIPTS). File config still applies.
+unset npm_config_allow_scripts NPM_CONFIG_ALLOW_SCRIPTS 2>/dev/null || true
+EXT_DIR="$(cd "$(dirname "$0")" && pwd)"
+if [ ! -f "$EXT_DIR/package.json" ]; then
+  echo "  · no package.json — skipping"
+  exit 0
+fi
+if ! command -v npm >/dev/null 2>&1; then
+  echo "  ✖ npm not found — install Node.js 22+" >&2
+  exit 1
+fi
+if [ -f "$EXT_DIR/package-lock.json" ]; then
+  echo "  · npm ci"
+  npm --prefix "$EXT_DIR" ci --no-audit --no-fund
+else
+  echo "  · npm install"
+  npm --prefix "$EXT_DIR" install --no-audit --no-fund
+fi
+echo "  ✓ done"

package/agent/extensions/kiln-update/README.md

@@ -1,25 +1,38 @@
-# kiln-update
-
-Nudges you when your installed kiln is behind GitHub.
-
-- On every session start it compares `~/.pi/agent/version.txt` with
-  `agent/version.txt` on the `main` branch.
-- On mismatch: `Kiln update available (X → Y) — to update kiln to the
-  newest version, run: kiln`
-- Silent when up to date, offline, or timed out (5s).
-
-## Manual check
-
-`/kiln-update` — re-check on demand.
-
-## Releasing a new version
-
-1. Make your changes.
-2. Bump `agent/version.txt` (e.g. `0.2.0` → `0.3.0`).
-3. Push to GitHub. No `npm publish` needed — `kiln` installs from git,
-   and every user gets the nudge on their next session.
-
-## Opt out
-
-`KILN_NO_UPDATE_CHECK=1`. Forks can point elsewhere with
-`KILN_VERSION_URL=https://.../version.txt`.
+# kiln-update
+
+A minimal kiln header for pi, and a nudge when your install is behind GitHub.
+
+- Replaces the built-in startup header with:
+
+  ```
+  pi vX kiln vY
+  skills N extensions N
+  ```
+
+- Press `ctrl+o` to expand the header and list every installed skill and
+  extension.
+- When `~/.pi/agent/version.txt` is behind `agent/version.txt` on `main`, the
+  header also shows:
+
+  ```
+  Update Available. To update, run:
+  run npx @asterxsk/kiln@latest
+  ```
+
+- Silent when up to date, offline, or timed out (5s).
+
+## Manual check
+
+`/kiln-update` — re-check on demand, refresh the header, and report the result.
+
+## Releasing a new version
+
+1. Make your changes.
+2. Bump `agent/version.txt` (e.g. `0.2.0` → `0.3.0`).
+3. Push to GitHub. No `npm publish` needed — `kiln` installs from git,
+   and every user gets the nudge on their next session.
+
+## Opt out
+
+`KILN_NO_UPDATE_CHECK=1`. Forks can point elsewhere with
+`KILN_VERSION_URL=https://.../version.txt`.