@maxiaochao/pi-toolkit 0.9.1 → 0.9.3

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 2026-09-30 - v0.9.3
+
+- refine global agent guidance and add repository issue, triage, and domain instructions
+
+## 2026-09-30 - v0.9.2
+
+- show contiguous queue positions in the todo widget while retaining stable internal task IDs
+
 ## 2026-09-30 - v0.9.1
 
 - redesign the todo lifecycle with plan replacement, cancellation, automatic advancement, active-only widget rendering, concise model guidance, and deterministic state tests

package/README.md

@@ -38,7 +38,7 @@ To synchronize the file directly from a checkout instead:
 bash scripts/install.sh
 ```
 
-The `todo` tool maintains a session checklist for explicit plans and multi-step work. It automatically keeps one task active and advances the next queued task; `replace` starts a clean plan after a change of direction, while `cancelled` records obsolete work honestly. The persistent widget shows active work only, and `/todos` shows active and closed tasks in the current plan.
+The `todo` tool maintains a session checklist for explicit plans and multi-step work. It automatically keeps one task active and advances the next queued task; `replace` starts a clean plan after a change of direction, while `cancelled` records obsolete work honestly. The persistent widget numbers active work by queue position; `/todos` shows active and closed tasks with their stable internal IDs.
 
 The `/btw` side chat is a separate agent session. It can inspect the main conversation and repository, and its thread stays out of the main context until you close it and choose to inject a summary. Use `/btw` to open it or `/btw <question>` to ask directly. While the BTW overlay has focus, use `Up` / `Down` to scroll its transcript one line at a time and `PageUp` / `PageDown` to move by one transcript page.
 

package/extensions/tests/todo-state.mjs

@@ -1,5 +1,6 @@
 import assert from "node:assert/strict";
 import {
+	activeTodoRows,
 	activeTodos,
 	applyTodoAction,
 	restoreTodoState,
@@ -7,6 +8,19 @@ import {
 
 const empty = { todos: [], nextId: 1 };
 
+assert.deepEqual(
+	activeTodoRows([
+		{ id: 8, text: "closed", status: "done" },
+		{ id: 9, text: "current", status: "doing" },
+		{ id: 11, text: "next", status: "todo" },
+	]).map(({ position, todo }) => ({ position, id: todo.id })),
+	[
+		{ position: 1, id: 9 },
+		{ position: 2, id: 11 },
+	],
+	"active rows expose contiguous queue positions independently of internal IDs",
+);
+
 const replaced = applyTodoAction(empty, {
 	action: "replace",
 	items: ["Inspect the failure", "Implement the fix", "Run verification"],

package/extensions/todo-state.ts

@@ -19,6 +19,11 @@ export interface TodoState {
 	nextId: number;
 }
 
+export interface ActiveTodoRow {
+	position: number;
+	todo: Todo;
+}
+
 export interface TodoActionInput {
 	action: TodoAction;
 	text?: string;
@@ -73,6 +78,10 @@ export function activeTodos(todos: Todo[]): Todo[] {
 	return todos.filter((todo) => todo.status === "doing" || todo.status === "todo");
 }
 
+export function activeTodoRows(todos: Todo[]): ActiveTodoRow[] {
+	return activeTodos(todos).map((todo, index) => ({ position: index + 1, todo }));
+}
+
 function cloneState(state: TodoState): TodoState {
 	return { todos: state.todos.map((todo) => ({ ...todo })), nextId: state.nextId };
 }

package/extensions/todo.ts

@@ -9,7 +9,7 @@ import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-c
 import { matchesKey, Text, truncateToWidth } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import {
-	activeTodos,
+	activeTodoRows,
 	applyTodoAction,
 	countTodoStatuses,
 	normalizeTodo,
@@ -80,6 +80,11 @@ function renderTodoLine(theme: Theme, todo: Todo): string {
 	return `${icon} ${theme.fg("accent", `#${todo.id}`)} ${theme.fg("text", todo.text)}`;
 }
 
+function renderActiveTodoLine(theme: Theme, todo: Todo, position: number): string {
+	const icon = themedStatus(theme, todo.status, statusMarker(todo.status));
+	return `${icon} ${theme.fg("accent", `${position}.`)} ${theme.fg("text", todo.text)}`;
+}
+
 class TodoListComponent {
 	private cachedWidth?: number;
 	private cachedLines?: string[];
@@ -134,7 +139,7 @@ export default function (pi: ExtensionAPI) {
 
 	const refreshUI = (ctx: ExtensionContext) => {
 		if (!ctx.hasUI) return;
-		const visible = activeTodos(state.todos);
+		const visible = activeTodoRows(state.todos);
 		if (visible.length === 0) {
 			ctx.ui.setWidget(WIDGET_KEY, undefined);
 			return;
@@ -146,7 +151,7 @@ export default function (pi: ExtensionAPI) {
 				render(width: number): string[] {
 					return [
 						truncateToWidth(`${theme.fg("accent", "●")} ${theme.fg("muted", taskSummary(state.todos))}`, width),
-						...sortedTodos(visible).map((todo) => truncateToWidth(`  ${renderTodoLine(theme, todo)}`, width)),
+						...visible.map(({ position, todo }) => truncateToWidth(`  ${renderActiveTodoLine(theme, todo, position)}`, width)),
 					];
 				},
 				invalidate() {},

package/global/AGENTS.md

@@ -1,51 +1,38 @@
 # AGENTS.md
 
-Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
-
-**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+Behavioral guidelines to reduce common LLM coding mistakes. Project-specific instructions override this file when they conflict.
 
 ## 1. Think Before Coding
 
-**Don't assume. Don't hide confusion. Surface tradeoffs.**
+**Surface tradeoffs. Name confusion instead of resolving it silently.**
 
-Before implementing:
-- State your assumptions explicitly. If uncertain, ask.
-- If multiple interpretations exist, present them - don't pick silently.
+- State your material assumptions explicitly.
+- If multiple interpretations exist, present them rather than picking one silently.
 - If a simpler approach exists, say so. Push back when warranted.
-- If something is unclear, stop. Name what's confusing. Ask.
-- If requirements conflict (e.g., durability vs latency, correctness vs speed), name the conflict explicitly. Never average conflicting requirements into something that satisfies neither.
+- If requirements conflict (durability vs latency, correctness vs speed), name the conflict explicitly. Never average conflicting requirements into something that satisfies neither.
+- When unresolved ambiguity would materially change the result, ask. When no human is reachable (headless, async, subagent), choose the interpretation you can defend, state it as an assumption, and proceed under Rule 4.
 
 ## 2. Simplicity First
 
-**Minimum code that solves the problem. Nothing speculative.**
-
-- No features beyond what was asked.
-- No abstractions for single-use code.
-- No "flexibility" or "configurability" that wasn't requested.
-- No error handling for impossible scenarios.
-- If you write 200 lines and it could be 50, rewrite.
+**YAGNI cuts what you don't need; KISS keeps what remains simple.**
 
-Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+- Build what was asked, for the callers that exist today.
+- Introduce an abstraction after repeated use reveals a stable concept.
+- For states excluded by enforced invariants, fail visibly instead of inventing fallback behavior.
+- Each function you write does one thing. If it runs past a couple of screens or nests past three levels, review whether splitting it improves clarity.
 
 ## 3. Surgical Changes
 
 **Touch only what you must. Clean up only your own mess.**
 
-When editing existing code:
-- Don't "improve" adjacent code, comments, or formatting.
-- Don't refactor things that aren't broken.
-- Match existing style, even if you'd do it differently.
-- If you notice unrelated dead code, mention it - don't delete it.
-
-When your changes create orphans:
-- Remove imports/variables/functions that YOUR changes made unused.
-- Don't remove pre-existing dead code unless asked.
+The test: every changed line traces to the user's request, or to a defect that request reveals.
 
-The test: Every changed line should trace directly to the user's request.
+- Match existing style, even if you'd do it differently.
+- Remove imports, variables, and functions that YOUR changes made unused. Leave pre-existing dead code in place and mention it.
 
 When fixing a bug, fix the root cause, not the symptom. Find where the defect actually lives:
-- Grep every caller of the function you touch; a report names a symptom, and patching only the path the ticket mentions leaves sibling callers still broken.
-- If the shared function is wrong, fix it once - do not scatter per-caller guards.
+- Find every statically discoverable caller and relevant implementation; a report names a symptom, and patching only the path the ticket mentions leaves sibling callers still broken.
+- If the shared function is wrong, fix it once - do not scatter per-caller guards. Name the sibling callers the fix now affects.
 - If one caller is wrong, fix that caller - do not add defensive handling to a correct shared function.
 
 ## 4. Goal-Driven Execution
@@ -56,11 +43,10 @@ Transform tasks into verifiable goals:
 - "Add validation" -> "Write tests for invalid inputs, then make them pass"
 - "Fix the bug" -> "Write a test that reproduces it, then make it pass"
 - "Refactor X" -> "Ensure tests pass before and after"
+- "Make X fast" -> "Write and test a simple reference implementation, then optimize against its results"
 
-For multi-step tasks, state a brief plan:
+For multi-step or materially ambiguous tasks, state a brief plan where every step carries its own check:
 1. [Step] -> verify: [check]
-2. [Step] -> verify: [check]
-3. [Step] -> verify: [check]
 
 Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
 
@@ -68,32 +54,21 @@ Strong success criteria let you loop independently. Weak criteria ("make it work
 
 **Understand adjacent code before changing it. "Looks orthogonal" is a dangerous assumption.**
 
-Before adding code to any file:
+Before changing a file:
 - Read the file's exports and public API.
 - Read the immediate callers of the function you're modifying.
-- Check shared utilities in the same module.
-- If you're unsure why code is structured a certain way, ask before writing.
 
 ## 6. Fail Visibly, Not Silently
 
-**Silent skips are failures. Surface uncertainty instead of hiding it.**
+**Silent skips are failures.**
 
 - "Completed" is wrong if anything was silently skipped.
-- "Tests pass" is wrong if any test was skipped.
-- Default to surfacing uncertainty. When in doubt, over-communicate what you're unsure about.
+- "Tests pass" is wrong if any required test was skipped or not run.
 - If a required input, file, or tool is missing (or a step is impossible under the stated constraints), do NOT fabricate it to make a check pass. Report what is missing and what you need.
 
 ## 7. Reuse Before Writing
 
 **Before writing new code, check in order:**
-1. Does it already exist in this codebase? Reuse it - do not re-implement it yourself, even with the standard library. (If the existing helper is itself the bug, fix it once - see Rule 3.)
-2. Does the standard library cover it? Use it.
-3. Only then: write the minimum code that works.
-
-## 8. Use Available Editing Tools
-
-**Follow the current harness's tool surface; do not assume a shell patch helper exists.**
-
-- Use the native file-editing tools exposed by the current environment. In pi, use `edit` for precise replacements and `write` for new files or complete rewrites.
-- Do not run `apply_patch` as a shell command unless `command -v apply_patch` confirms that executable is available.
-- If the harness exposes `apply_patch` as a dedicated tool rather than a command, invoke it only through that tool interface.
+1. Reuse an existing project abstraction when it encodes project semantics. (If it is itself the bug, fix it once - see Rule 3.)
+2. Otherwise use the standard library or a direct dependency already declared by the project.
+3. Only then write it yourself.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-toolkit",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "description": "Personal pi coding agent toolkit: /todos, /btw, /cache_export and apply_patch extensions, browser automation, and bundled theme/skills.",
   "type": "module",
   "keywords": [