pi-goal 0.1.5 → 0.1.6

package/.pi/extensions/pi-goal/goal-state.ts

@@ -0,0 +1,115 @@
+export type GoalStatus = "active" | "paused" | "budget_limited" | "complete";
+
+export type GoalState = {
+	version: 1;
+	id: string;
+	objective: string;
+	status: GoalStatus;
+	tokenBudget: number | null;
+	tokensUsed: number;
+	timeUsedSeconds: number;
+	createdAt: number;
+	updatedAt: number;
+};
+
+export type GoalEventKind = "active" | "continuation" | "paused" | "resumed" | "cleared" | "budget_limited" | "complete";
+
+export function parseTokenBudget(input: string): { objective: string; tokenBudget: number | null; error?: string } {
+	const match = input.match(/(?:^|\s)--tokens(?:=|\s+)(\S+\s*[kKmM]?)(?:\s|$)/);
+	if (!match) return { objective: input.trim(), tokenBudget: null };
+
+	const raw = match[1].replace(/\s+/g, "");
+	const suffix = raw.slice(-1).toLowerCase();
+	const numeric = suffix === "k" || suffix === "m" ? raw.slice(0, -1) : raw;
+	const value = Number(numeric);
+	if (!Number.isFinite(value) || value <= 0) {
+		return { objective: input.trim(), tokenBudget: null, error: "Token budget must be positive." };
+	}
+	const multiplier = suffix === "m" ? 1_000_000 : suffix === "k" ? 1_000 : 1;
+	const tokenBudget = Math.round(value * multiplier);
+	const objective = (input.slice(0, match.index) + " " + input.slice((match.index ?? 0) + match[0].length)).trim();
+	return { objective, tokenBudget };
+}
+
+export function normalizeTokenBudget(value: unknown): { tokenBudget: number | null; error?: string } {
+	if (value == null) return { tokenBudget: null };
+	const tokenBudget = Math.round(Number(value));
+	if (!Number.isFinite(tokenBudget) || tokenBudget <= 0) {
+		return { tokenBudget: null, error: "tokenBudget must be a positive number when provided." };
+	}
+	return { tokenBudget };
+}
+
+export function formatTokens(value: number): string {
+	if (value >= 1_000_000) return `${Math.round(value / 100_000) / 10}M`;
+	if (value >= 1_000) return `${Math.round(value / 100) / 10}K`;
+	return String(value);
+}
+
+export function formatElapsed(seconds: number): string {
+	if (seconds < 60) return `${seconds}s`;
+	const minutes = Math.floor(seconds / 60);
+	if (minutes < 60) return `${minutes}m`;
+	const hours = Math.floor(minutes / 60);
+	const remMinutes = minutes % 60;
+	return remMinutes ? `${hours}h ${remMinutes}m` : `${hours}h`;
+}
+
+export function statusLine(state: GoalState | null): string | undefined {
+	if (!state) return undefined;
+	const budget = state.tokenBudget ? ` (${formatTokens(state.tokensUsed)} / ${formatTokens(state.tokenBudget)})` : ` (${formatElapsed(state.timeUsedSeconds)})`;
+	if (state.status === "active") return `Pursuing goal${budget}`;
+	if (state.status === "paused") return "Goal paused (/goal resume)";
+	if (state.status === "budget_limited") return state.tokenBudget ? `Goal unmet${budget}` : "Goal abandoned";
+	return `Goal achieved${budget}`;
+}
+
+export function goalUsage(state: GoalState): string {
+	if (state.tokenBudget != null) return `${formatTokens(state.tokensUsed)} / ${formatTokens(state.tokenBudget)} tokens`;
+	return formatElapsed(state.timeUsedSeconds);
+}
+
+export function truncateObjective(objective: string, max = 96): string {
+	const singleLine = objective.replace(/\s+/g, " ").trim();
+	return singleLine.length > max ? `${singleLine.slice(0, max - 1)}…` : singleLine;
+}
+
+export function goalEventStatus(kind: GoalEventKind): string {
+	const labels: Record<GoalEventKind, string> = {
+		active: "active",
+		continuation: "continuing",
+		paused: "paused",
+		resumed: "resumed",
+		cleared: "cleared",
+		budget_limited: "budget reached",
+		complete: "achieved",
+	};
+	return labels[kind];
+}
+
+export function createGoalState(objective: string, tokenBudget: number | null, now = Date.now(), random = Math.random()): GoalState {
+	return {
+		version: 1,
+		id: `${now}-${random.toString(16).slice(2)}`,
+		objective,
+		status: "active",
+		tokenBudget,
+		tokensUsed: 0,
+		timeUsedSeconds: 0,
+		createdAt: now,
+		updatedAt: now,
+	};
+}
+
+export function accountGoalTurn(state: GoalState, tokenDelta: number, elapsedSeconds: number, now = Date.now()): GoalState {
+	let next: GoalState = {
+		...state,
+		tokensUsed: state.tokensUsed + Math.max(0, tokenDelta),
+		timeUsedSeconds: state.timeUsedSeconds + Math.max(0, elapsedSeconds),
+		updatedAt: now,
+	};
+	if (next.status === "active" && next.tokenBudget != null && next.tokensUsed >= next.tokenBudget) {
+		next = { ...next, status: "budget_limited" };
+	}
+	return next;
+}

package/.pi/extensions/pi-goal/index.ts

@@ -1,95 +1,29 @@
 import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
 import { Box, Spacer, Text } from "@mariozechner/pi-tui";
-import { tokenDeltaFromUsage } from "./usage";
+import {
+	accountGoalTurn,
+	createGoalState,
+	goalEventStatus,
+	goalUsage,
+	parseTokenBudget,
+	statusLine,
+	truncateObjective,
+	type GoalEventKind,
+	type GoalState,
+	type GoalStatus,
+	normalizeTokenBudget,
+} from "./goal-state";
+import { tokenDeltaFromUsage, type UsageSnapshot } from "./usage";
 
 const CUSTOM_TYPE = "pi-goal";
 const EVENT_TYPE = "pi-goal-event";
 
-type GoalStatus = "active" | "paused" | "budget_limited" | "complete";
-
-type GoalState = {
-	version: 1;
-	id: string;
-	objective: string;
-	status: GoalStatus;
-	tokenBudget: number | null;
-	tokensUsed: number;
-	timeUsedSeconds: number;
-	createdAt: number;
-	updatedAt: number;
-};
-
-type GoalEventKind = "active" | "continuation" | "paused" | "resumed" | "cleared" | "budget_limited" | "complete";
-
 let goal: GoalState | null = null;
 let statusBarEnabled = true;
 let activeTurnStartedAt: number | null = null;
+let activeGoalThisTurnId: string | null = null;
 let continuationQueued = false;
 
-function parseTokenBudget(input: string): { objective: string; tokenBudget: number | null; error?: string } {
-	const match = input.match(/(?:^|\s)--tokens(?:=|\s+)([0-9]+(?:\.[0-9]+)?\s*[kKmM]?)(?:\s|$)/);
-	if (!match) return { objective: input.trim(), tokenBudget: null };
-
-	const raw = match[1].replace(/\s+/g, "");
-	const suffix = raw.slice(-1).toLowerCase();
-	const numeric = suffix === "k" || suffix === "m" ? raw.slice(0, -1) : raw;
-	const value = Number(numeric);
-	if (!Number.isFinite(value) || value <= 0) {
-		return { objective: input.trim(), tokenBudget: null, error: "Token budget must be positive." };
-	}
-	const multiplier = suffix === "m" ? 1_000_000 : suffix === "k" ? 1_000 : 1;
-	const tokenBudget = Math.round(value * multiplier);
-	const objective = (input.slice(0, match.index) + " " + input.slice((match.index ?? 0) + match[0].length)).trim();
-	return { objective, tokenBudget };
-}
-
-function formatTokens(value: number): string {
-	if (value >= 1_000_000) return `${Math.round(value / 100_000) / 10}M`;
-	if (value >= 1_000) return `${Math.round(value / 100) / 10}K`;
-	return String(value);
-}
-
-function formatElapsed(seconds: number): string {
-	if (seconds < 60) return `${seconds}s`;
-	const minutes = Math.floor(seconds / 60);
-	if (minutes < 60) return `${minutes}m`;
-	const hours = Math.floor(minutes / 60);
-	const remMinutes = minutes % 60;
-	return remMinutes ? `${hours}h ${remMinutes}m` : `${hours}h`;
-}
-
-function statusLine(state: GoalState | null): string | undefined {
-	if (!state) return undefined;
-	const budget = state.tokenBudget ? ` (${formatTokens(state.tokensUsed)} / ${formatTokens(state.tokenBudget)})` : ` (${formatElapsed(state.timeUsedSeconds)})`;
-	if (state.status === "active") return `Pursuing goal${budget}`;
-	if (state.status === "paused") return "Goal paused (/goal resume)";
-	if (state.status === "budget_limited") return state.tokenBudget ? `Goal unmet${budget}` : "Goal abandoned";
-	return `Goal achieved${budget}`;
-}
-
-function goalUsage(state: GoalState): string {
-	if (state.tokenBudget != null) return `${formatTokens(state.tokensUsed)} / ${formatTokens(state.tokenBudget)} tokens`;
-	return formatElapsed(state.timeUsedSeconds);
-}
-
-function truncateObjective(objective: string, max = 96): string {
-	const singleLine = objective.replace(/\s+/g, " ").trim();
-	return singleLine.length > max ? `${singleLine.slice(0, max - 1)}…` : singleLine;
-}
-
-function goalEventStatus(kind: GoalEventKind): string {
-	const labels: Record<GoalEventKind, string> = {
-		active: "active",
-		continuation: "continuing",
-		paused: "paused",
-		resumed: "resumed",
-		cleared: "cleared",
-		budget_limited: "budget reached",
-		complete: "achieved",
-	};
-	return labels[kind];
-}
-
 // The `content` field is what the LLM sees in the conversation history.
 // Every goal event MUST carry actionable text — never a cryptic marker.
 // The TUI renderer collapses long bodies down to a compact badge for humans.
@@ -153,20 +87,24 @@ function updateStatusBar(ctx: ExtensionContext) {
 	ctx.ui.setStatus(CUSTOM_TYPE, statusBarEnabled ? statusLine(goal) ?? "" : "");
 }
 
-const GOAL_TOOL_NAMES = ["get_goal", "update_goal"];
+const ACTIVE_GOAL_TOOL_NAMES = ["get_goal", "update_goal"];
 
-// Expose goal tools to the LLM only while a goal is actively being pursued.
-// When no goal exists (or it is paused / complete / budget-limited), keep them
-// hidden so unrelated sessions are not tempted to call them every turn.
+// Expose read/update tools to the LLM only while a goal is actively being pursued.
+// Keep create_goal available so the model can start a goal when explicitly asked,
+// but rely on its tool contract to reject inferred goals and existing goals.
 function syncGoalTools(pi: ExtensionAPI) {
-	const want = goal?.status === "active";
+	const wantActiveTools = goal?.status === "active";
 	const active = new Set(pi.getActiveTools());
-	for (const name of GOAL_TOOL_NAMES) (want ? active.add(name) : active.delete(name));
+	active.add("create_goal");
+	for (const name of ACTIVE_GOAL_TOOL_NAMES) (wantActiveTools ? active.add(name) : active.delete(name));
 	pi.setActiveTools(Array.from(active));
 }
 
 function persist(pi: ExtensionAPI, ctx: ExtensionContext, next: GoalState | null) {
 	goal = next;
+	if (next?.status !== "active") {
+		continuationQueued = false;
+	}
 	pi.appendEntry(CUSTOM_TYPE, { goal: next, statusBarEnabled });
 	updateStatusBar(ctx);
 	syncGoalTools(pi);
@@ -205,7 +143,7 @@ Before deciding that the goal is achieved, perform a completion audit against th
 - Identify any missing, incomplete, weakly verified, or uncovered requirement.
 - Treat uncertainty as not achieved; do more verification or continue the work.
 
-Do not rely on intent, partial progress, elapsed effort, memory of earlier work, or a plausible final answer as proof of completion. Only mark the goal achieved when the audit shows that the objective has actually been achieved and no required work remains. If any requirement is missing, incomplete, or unverified, keep working instead of marking the goal complete. If the objective is achieved, call update_goal with status \"complete\".
+Do not rely on intent, partial progress, elapsed effort, memory of earlier work, or a plausible final answer as proof of completion. Only mark the goal achieved when the audit shows that the objective has actually been achieved and no required work remains. If any requirement is missing, incomplete, or unverified, keep working instead of marking the goal complete. If the objective is achieved, call update_goal with status \"complete\" so usage accounting is preserved.
 
 Do not call update_goal unless the goal is complete. Do not mark a goal complete merely because the budget is nearly exhausted or because you are stopping work.`;
 }
@@ -280,10 +218,64 @@ export default function piGoal(pi: ExtensionAPI) {
 		},
 	});
 
+	pi.registerTool({
+		name: "create_goal",
+		label: "Create Goal",
+		description: "Create a new active thread goal only when explicitly requested. A goal must be a durable, evidence-checkable work contract: outcome, verification surface, constraints, boundaries, iteration policy, and blocked stop condition. Fails if a goal already exists.",
+		promptSnippet: "Create a pi-goal objective only when the user explicitly requests goal mode",
+		promptGuidelines: [
+			"Use create_goal only when the user explicitly asks to set/start/follow a goal, or system/developer instructions require a goal.",
+			"Do not infer goals from ordinary coding tasks or one-off prompts.",
+			"Before creating a goal, turn the request into a concrete objective with: outcome, verification surface, constraints, boundaries, iteration policy, and blocked stop condition.",
+			"Use this objective shape when possible: <desired end state>, verified by <specific evidence>, while preserving <constraints>. Use <allowed scope/tools> and avoid <forbidden scope>. Between iterations, <how to choose the next action and what to re-check>. If blocked or no defensible path remains, stop with <evidence gathered, attempted paths, blocker, and next input needed>.",
+			"Prefer a self-contained objective that survives continuation turns and context compaction.",
+			"Do not create vague goals like 'improve this' or 'finish the feature'; ask a clarifying question if missing success criteria or boundaries materially affect the contract.",
+			"Set tokenBudget only when the user explicitly requested a token budget.",
+		],
+		parameters: {
+			type: "object",
+			properties: {
+				objective: {
+					type: "string",
+					description: "The concrete objective to pursue as an active thread goal.",
+				},
+				tokenBudget: {
+					type: "number",
+					description: "Optional positive token budget for the goal, only when explicitly requested.",
+				},
+			},
+			required: ["objective"],
+			additionalProperties: false,
+		} as any,
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			if (goal) {
+				return {
+					content: [{ type: "text", text: "Cannot create a new goal because this thread already has a goal. Use update_goal only when the existing goal is complete, or ask the user to clear/replace it." }],
+					isError: true,
+				};
+			}
+			const objective = typeof params.objective === "string" ? params.objective.trim() : "";
+			if (!objective) {
+				return { content: [{ type: "text", text: "objective is required." }], isError: true };
+			}
+			const parsedBudget = normalizeTokenBudget(params.tokenBudget);
+			if (parsedBudget.error) {
+				return { content: [{ type: "text", text: parsedBudget.error }], isError: true };
+			}
+			const next = createGoalState(objective, parsedBudget.tokenBudget);
+			persist(pi, ctx, next);
+			emitGoalEvent(pi, "active", next, { triggerTurn: ctx.isIdle() });
+			return {
+				content: [{ type: "text", text: JSON.stringify({ goal: next, remainingTokens: next.tokenBudget }, null, 2) }],
+				details: { goal: next },
+			};
+		},
+	});
+
 	pi.registerTool({
 		name: "update_goal",
 		label: "Update Goal",
-		description: "Mark the current thread goal complete. This tool only accepts status=complete.",
+		description: "Mark the current thread goal complete. This tool only accepts status=complete and final turn usage is accounted by the runtime.",
 		promptSnippet: "Mark the current goal complete after a strict completion audit",
 		promptGuidelines: [
 			"Use update_goal only when the current pi-goal objective is fully achieved and verified against concrete evidence.",
@@ -381,17 +373,7 @@ export default function piGoal(pi: ExtensionAPI) {
 				const ok = await ctx.ui.confirm("Replace goal?", `Current: ${goal.objective}\n\nNew: ${parsed.objective}`);
 				if (!ok) return;
 			}
-			const next: GoalState = {
-				version: 1,
-				id: `${now}-${Math.random().toString(16).slice(2)}`,
-				objective: parsed.objective,
-				status: "active",
-				tokenBudget: parsed.tokenBudget,
-				tokensUsed: 0,
-				timeUsedSeconds: 0,
-				createdAt: now,
-				updatedAt: now,
-			};
+			const next = createGoalState(parsed.objective, parsed.tokenBudget, now);
 			persist(pi, ctx, next);
 			emitGoalEvent(pi, "active", next, { triggerTurn: ctx.isIdle() });
 		},
@@ -403,7 +385,8 @@ export default function piGoal(pi: ExtensionAPI) {
 		statusBarEnabled = restored.statusBarEnabled;
 		continuationQueued = false;
 		activeTurnStartedAt = null;
-		// Hide goal tools from the LLM unless we have an active goal to pursue.
+		activeGoalThisTurnId = null;
+		// Keep create_goal available, and hide read/update tools unless there is an active goal to pursue.
 		syncGoalTools(pi);
 		if (goal?.status === "active" && event.reason === "reload") {
 			// Reload pauses an active goal so it does not silently resume.
@@ -431,22 +414,20 @@ export default function piGoal(pi: ExtensionAPI) {
 
 	pi.on("turn_start", (_event, _ctx) => {
 		activeTurnStartedAt = Date.now();
+		activeGoalThisTurnId = goal?.status === "active" ? goal.id : null;
 	});
 
 	pi.on("turn_end", (event, ctx) => {
-		if (!goal || goal.status !== "active") return;
+		if (!goal || activeGoalThisTurnId !== goal.id) {
+			activeTurnStartedAt = null;
+			activeGoalThisTurnId = null;
+			return;
+		}
 		const elapsed = activeTurnStartedAt ? Math.max(0, Math.round((Date.now() - activeTurnStartedAt) / 1000)) : 0;
 		activeTurnStartedAt = null;
+		activeGoalThisTurnId = null;
 		const tokenDelta = tokenDeltaFromUsage((event.message as { usage?: UsageSnapshot } | undefined)?.usage);
-		let next: GoalState = {
-			...goal,
-			tokensUsed: goal.tokensUsed + tokenDelta,
-			timeUsedSeconds: goal.timeUsedSeconds + elapsed,
-			updatedAt: Date.now(),
-		};
-		if (next.tokenBudget != null && next.tokensUsed >= next.tokenBudget) {
-			next = { ...next, status: "budget_limited" };
-		}
+		const next = accountGoalTurn(goal, tokenDelta, elapsed);
 		persist(pi, ctx, next);
 		if (next.status === "budget_limited") {
 			emitGoalEvent(pi, "budget_limited", next, { triggerTurn: true, deliverAs: "followUp" });

package/README.md

@@ -4,7 +4,7 @@
 
 Persistent autonomous goals for [pi](https://github.com/badlogic/pi-mono).
 
-`pi-goal` adds a `/goal` command and goal tools so Pi can keep working toward a long-running objective until the goal is complete, paused, cleared, or token-budget-limited.
+`pi-goal` adds a `/goal` command and goal tools so Pi can keep working toward a long-running, thread-scoped objective until the goal is complete, paused, cleared, or token-budget-limited.
 
 ## Install
 
@@ -23,6 +23,7 @@ pi install git:github.com/Michaelliv/pi-goal
 ```text
 /goal improve benchmark coverage until the suite has strong evidence
 /goal --tokens 50k finish the migration and verify tests
+/goal
 /goal status
 /goal pause
 /goal resume
@@ -36,12 +37,14 @@ The same Pi agent keeps running normal turns in the same session context until i
 
 ## What it adds
 
+- `pi-goal-writer` skill: draft and review strong `/goal` objectives with evidence-based success criteria
 - `/goal [--tokens 50k] <objective>`: set or replace a goal
-- `/goal status`: show the current goal
+- `/goal` or `/goal status`: show the current goal
 - `/goal pause`: stop autonomous continuation without deleting the goal
 - `/goal resume`: reactivate a paused goal
 - `/goal clear`: remove the goal
 - `/goal statusbar on|off`: show or hide the footer status line
+- `create_goal` tool: model can create a goal only when explicitly requested and only if no goal exists
 - `get_goal` tool: read current goal state
 - `update_goal` tool: model can only mark the goal `complete`
 - `get_goal` and `update_goal` are only exposed to the model while a goal is `active`; paused, cleared, complete, and budget-limited goals hide them so unrelated sessions are not tempted to call them
@@ -62,7 +65,7 @@ The same Pi agent keeps running normal turns in the same session context until i
 
 ## Completion behavior
 
-The model is instructed to audit completion against real evidence before calling `update_goal`. The `update_goal` tool deliberately accepts only `status: "complete"`; pausing, resuming, clearing, and budget limiting are controlled by the user or extension runtime.
+The model is instructed to audit completion against real evidence before calling `update_goal`. The `update_goal` tool deliberately accepts only `status: "complete"`; pausing, resuming, clearing, and budget limiting are controlled by the user or extension runtime. The final turn is still accounted even when the model completes the goal mid-turn.
 
 ## State
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-goal",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Persistent autonomous goals for pi — /goal loops until complete, paused, or budget-limited",
   "type": "commonjs",
   "keywords": [
@@ -12,12 +12,16 @@
   ],
   "files": [
     ".pi/",
+    "skills/",
     "README.md",
     "LICENSE"
   ],
   "pi": {
     "extensions": [
       ".pi/extensions/pi-goal"
+    ],
+    "skills": [
+      "skills"
     ]
   },
   "peerDependencies": {

package/skills/pi-goal-writer/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: pi-goal-writer
+description: Drafts and reviews strong /goal objectives for Pi pi-goal and compatible goal-mode agents. Use when the user asks to write, improve, audit, or meta-prompt a long-running agent goal with clear success criteria, verification, constraints, iteration policy, and blocked stop conditions.
+---
+
+# Pi Goal Writer
+
+## Purpose
+
+Write `/goal` prompts that are fit for persistent autonomous work. A goal is not a bigger ordinary prompt; it is a completion contract. The agent will keep using it to decide what to do next and whether it can honestly stop, so the goal must define the desired end state, the evidence that proves it, the constraints that must remain true, and when to stop as blocked instead of drifting.
+
+Use this skill for Pi `pi-goal` first. The same goal-writing principles also apply to Codex Goal mode and compatible `/goal` workflows.
+
+## Core rule
+
+Never produce a vague goal such as “make this better,” “finish the feature,” or “improve the codebase.” Turn the user’s rough intent into a goal with auditable completion criteria.
+
+A strong goal includes six parts:
+
+1. **Outcome** — what must be true when the work is done.
+2. **Verification surface** — tests, commands, benchmark output, report, artifact, diff audit, PR state, screenshots, logs, or other concrete evidence.
+3. **Constraints** — what must not regress or be changed.
+4. **Boundaries** — files, directories, tools, systems, data sources, or permissions the agent may or may not use.
+5. **Iteration policy** — how the agent should choose the next action after each attempt.
+6. **Blocked stop condition** — when the agent should stop honestly, with evidence and the next needed input, instead of continuing blindly.
+
+## Workflow
+
+1. Default to Pi `pi-goal`. Write a Pi-compatible `/goal` command unless the user explicitly asks for another harness. The goal body can usually be reused in Codex Goal mode; Pi also supports optional token budgets such as `/goal --tokens 50k ...`.
+2. Gather context before drafting when the task depends on a repository, issue, test suite, benchmark, PR, design, or external documentation. Read the relevant files or sources instead of inventing the verification surface.
+3. Ask at most three clarifying questions only when missing information changes the goal contract. Prefer making safe assumptions explicit when the user is trying to move quickly.
+4. Draft the goal as a single pasteable command, then include a short rationale or checklist showing how the six parts are covered.
+5. For high-stakes or ambiguous work, provide two options: a narrower goal that is safer to execute and a broader goal that delegates more discovery to the agent. Recommend one.
+
+## Goal template
+
+Use this shape unless the user asks for a different format:
+
+```text
+/goal <desired end state>, verified by <specific evidence>, while preserving <constraints>. Use <allowed inputs/tools/scope> and avoid <forbidden scope>. Between iterations, <how to choose the next best action and what to re-check>. If blocked or no defensible path remains, stop with <evidence gathered, attempted paths, blocker, and next input needed>.
+```
+
+For Pi token budgets:
+
+```text
+/goal --tokens 50k <same goal contract>
+```
+
+## Writing standards
+
+Make the goal self-contained. It should survive context compaction and continuation turns. Include exact command names when known, but do not invent commands. Say “run the relevant project checks identified in AGENTS.md/package scripts” only when exact commands are unknown and the agent can inspect them.
+
+Make completion evidence-based. The goal should require the agent to inspect real artifacts before declaring success: files changed, tests passed, benchmark numbers, rendered screenshots, logs, PR checks, or a written audit. Do not let “tests pass” be the only evidence unless the tests actually cover every requirement.
+
+Bound the scope. Name excluded directories or behaviors when important, such as “do not rewrite CLI user-facing output,” “do not change public API behavior,” or “do not touch generated files except via the generator.”
+
+Preserve honesty under uncertainty. If evidence may be unavailable, require a final report that separates confirmed findings, approximate/proxy evidence, blocked claims, and remaining uncertainty.
+
+Prefer concrete stop language: “If blocked, stop with the exact blocker and what would unlock progress.” Avoid weak endings like “do your best.”
+
+## Review checklist
+
+Before returning a goal, verify it answers:
+
+- Can the agent tell when it is done?
+- Can the user independently audit that completion claim?
+- Are regressions and forbidden approaches named?
+- Does the goal allow iteration without inviting unlimited drift?
+- Does it define what to do when tests, credentials, network, data, or product decisions block progress?
+- Is it pasteable as one `/goal` command?
+
+## Examples
+
+Weak:
+
+```text
+/goal improve logging
+```
+
+Strong:
+
+```text
+/goal Implement structured runtime logging, verified by targeted logger tests, the full project check/type/test suite, and final audits showing no production console.* calls outside approved CLI/UI/logger-sink exceptions. Preserve existing operator-visible console behavior, avoid logging secrets or credentials, and keep the logger generic rather than error-only. Between iterations, inspect the diff and audit remaining catch paths before deciding the next change. If blocked, stop with the unverified requirement, evidence gathered, and the next input needed.
+```
+
+Weak:
+
+```text
+/goal fix flaky checkout test
+```
+
+Strong:
+
+```text
+/goal Diagnose and either fix or conclusively characterize the flaky checkout test, verified by a reliable local reproduction or an evidence-backed failure analysis plus the relevant test command passing when a fix is made. Preserve public checkout behavior and avoid broad timing hacks unless the evidence shows timing is the root cause. Between iterations, record the hypothesis tested, command output, and next most likely cause. If the flake cannot be reproduced or no safe fix remains, stop with attempted reproductions, logs, suspected causes, and the missing evidence needed.
+```
+
+Weak:
+
+```text
+/goal reproduce this paper
+```
+
+Strong:
+
+```text
+/goal Produce the strongest evidence-backed reproduction of the paper using available local resources, verified by a final claim-by-claim report and any generated artifacts or runnable checks. Attempt the headline results where feasible, label approximate reconstructions separately from exact reproductions, and do not overclaim missing seeds, checkpoints, datasets, or implementation details. Between iterations, map claims to available evidence and prioritize the highest-value verifiable claim. If exact reproduction is blocked, stop with confirmed claims, proxy evidence, blocked claims, and the specific missing materials.
+```