pi-plan-task 1.0.0

package/extensions/planning-and-task-breakdown.md

@@ -0,0 +1,287 @@
+# Planning and Task Breakdown
+
+## Overview
+
+Decompose work into small, verifiable tasks with explicit acceptance criteria. Good task breakdown is the difference between an agent that completes work reliably and one that produces a tangled mess. Every task should be small enough to implement, test, and verify in a single focused session.
+
+## When to Use
+
+- You have a spec and need to break it into implementable units
+- A task feels too large or vague to start
+- Work needs to be parallelized across multiple agents or sessions
+- You need to communicate scope to a human
+- The implementation order isn't obvious
+
+**When NOT to use:** Single-file changes with obvious scope, or when the spec already contains well-defined tasks.
+
+## The Planning Process
+
+### Step 1: Enter Plan Mode
+
+Before writing any code, operate in read-only mode:
+
+- Read the spec and relevant codebase sections
+- Identify existing patterns and conventions
+- Map dependencies between components
+- Note risks and unknowns
+
+**Do NOT write code during planning.** The output is a plan document saved to `.plan_task/plan.md` and a task list saved to `.plan_task/task.md`, not implementation.
+
+### Step 2: Identify the Dependency Graph
+
+Map what depends on what:
+
+```
+Database schema
+    │
+    ├── API models/types
+    │       │
+    │       ├── API endpoints
+    │       │       │
+    │       │       └── Frontend API client
+    │       │               │
+    │       │               └── UI components
+    │       │
+    │       └── Validation logic
+    │
+    └── Seed data / migrations
+```
+
+Implementation order follows the dependency graph bottom-up: build foundations first.
+
+### Step 3: Slice Vertically
+
+Instead of building all the database, then all the API, then all the UI — build one complete feature path at a time:
+
+**Bad (horizontal slicing):**
+```
+Task 1: Build entire database schema
+Task 2: Build all API endpoints
+Task 3: Build all UI components
+Task 4: Connect everything
+```
+
+**Good (vertical slicing):**
+```
+Task 1: User can create an account (schema + API + UI for registration)
+Task 2: User can log in (auth schema + API + UI for login)
+Task 3: User can create a task (task schema + API + UI for creation)
+Task 4: User can view task list (query + API + UI for list view)
+```
+
+Each vertical slice delivers working, testable functionality.
+
+### Step 4: Write Tasks
+
+Each task follows this structure:
+
+```markdown
+## Task [N]: [Short descriptive title]
+
+**Description:** One paragraph explaining what this task accomplishes.
+
+**Acceptance criteria:**
+- [ ] [Specific, testable condition]
+- [ ] [Specific, testable condition]
+
+**Verification:**
+- [ ] Tests pass: [the repository's focused-test command]
+- [ ] Build succeeds: [the repository's build command]
+- [ ] Manual check: [description of what to verify]
+
+**Dependencies:** [Task numbers this depends on, or "None"]
+
+**Files likely touched:**
+- `src/path/to/file.ts`
+- `tests/path/to/test.ts`
+
+**Estimated scope:** [Small: 1-2 files | Medium: 3-5 files | Large: 5+ files]
+```
+
+### Step 5: Order and Checkpoint
+
+Arrange tasks so that:
+
+1. Dependencies are satisfied (build foundation first)
+2. Each task leaves the system in a working state
+3. Verification checkpoints occur after every 2-3 tasks
+4. High-risk tasks are early (fail fast)
+
+Add explicit checkpoints to the task list:
+
+```markdown
+## Checkpoint: After Tasks 1-3
+- [ ] All tests pass
+- [ ] Application builds without errors
+- [ ] Core user flow works end-to-end
+- [ ] Review with human before proceeding
+```
+
+## Task Sizing Guidelines
+
+| Size | Files | Scope | Example |
+|------|-------|-------|---------|
+| **XS** | 1 | Single function or config change | Add a validation rule |
+| **S** | 1-2 | One component or endpoint | Add a new API endpoint |
+| **M** | 3-5 | One feature slice | User registration flow |
+| **L** | 5-8 | Multi-component feature | Search with filtering and pagination |
+| **XL** | 8+ | **Too large — break it down further** | — |
+
+If a task is L or larger, it should be broken into smaller tasks. An agent performs best on S and M tasks.
+
+**When to break a task down further:**
+- It would take more than one focused session (roughly 2+ hours of agent work)
+- You cannot describe the acceptance criteria in 3 or fewer bullet points
+- It touches two or more independent subsystems (e.g., auth and billing)
+- You find yourself writing "and" in the task title (a sign it is two tasks)
+
+## Output Files
+
+- **Plan document:** Save the implementation plan to `.plan_task/plan.md`. This is always a markdown file — design decisions, risks, and open questions don't map cleanly onto individual tracker issues.
+- **Task list:** Record each task in `.plan_task/task.md`.
+
+Create the `.plan_task/` directory if it does not exist.
+
+The checklist at the top of `.plan_task/task.md` is the source of truth for `/build`. Keep items in the form `- [ ] N. Title` so later sessions can resume.
+
+After the checklist, write one `## Task [N]:` section per item using the Step 4 structure. Put `## Checkpoint:` sections after the tasks they cover, not in the top checklist.
+
+Example `.plan_task/task.md`:
+
+```markdown
+- [ ] 1. User can create an account
+- [ ] 2. User can log in
+
+## Task 1: User can create an account
+
+**Description:** Registration schema, API, and UI as one vertical slice.
+
+**Acceptance criteria:**
+- [ ] A new user can register with email and password
+- [ ] Duplicate emails are rejected
+
+**Verification:**
+- [ ] Tests pass: [the repository's focused-test command]
+- [ ] Build succeeds: [the repository's build command]
+- [ ] Manual check: submit the registration form
+
+**Dependencies:** None
+
+**Files likely touched:**
+- `src/auth/register.ts`
+- `tests/auth/register.test.ts`
+
+**Estimated scope:** Medium: 3-5 files
+
+## Task 2: User can log in
+
+**Description:** Auth session API and login UI.
+
+**Acceptance criteria:**
+- [ ] Valid credentials create a session
+- [ ] Invalid credentials are rejected
+
+**Verification:**
+- [ ] Tests pass: [the repository's focused-test command]
+- [ ] Manual check: log in with the account from Task 1
+
+**Dependencies:** 1
+
+**Files likely touched:**
+- `src/auth/login.ts`
+- `tests/auth/login.test.ts`
+
+**Estimated scope:** Small: 1-2 files
+
+## Checkpoint: After Tasks 1-2
+- [ ] Registration and login work end-to-end
+- [ ] Review with human before proceeding
+```
+
+## Plan Document Template
+
+```markdown
+# Implementation Plan: [Feature/Project Name]
+
+## Overview
+[One paragraph summary of what we're building]
+
+## Architecture Decisions
+- [Key decision 1 and rationale]
+- [Key decision 2 and rationale]
+
+## Task List
+
+### Phase 1: Foundation
+- [ ] 1. ...
+- [ ] 2. ...
+
+### Checkpoint: Foundation
+- [ ] Tests pass, builds clean
+
+### Phase 2: Core Features
+- [ ] 3. ...
+- [ ] 4. ...
+
+### Checkpoint: Core Features
+- [ ] End-to-end flow works
+
+### Phase 3: Polish
+- [ ] 5. ...
+- [ ] 6. ...
+
+### Checkpoint: Complete
+- [ ] All acceptance criteria met
+- [ ] Ready for review
+
+## Risks and Mitigations
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| [Risk] | [High/Med/Low] | [Strategy] |
+
+## Open Questions
+- [Question needing human input]
+```
+
+## Parallelization Opportunities
+
+When multiple agents or sessions are available:
+
+- **Safe to parallelize:** Independent feature slices, tests for already-implemented features, documentation
+- **Must be sequential:** Database migrations, shared state changes, dependency chains
+- **Needs coordination:** Features that share an API contract (define the contract first, then parallelize)
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "I'll figure it out as I go" | That's how you end up with a tangled mess and rework. 10 minutes of planning saves hours. |
+| "The tasks are obvious" | Write them down anyway. Explicit tasks surface hidden dependencies and forgotten edge cases. |
+| "Planning is overhead" | Planning is the task. Implementation without a plan is just typing. |
+| "I can hold it all in my head" | Context windows are finite. Written plans survive session boundaries and compaction. |
+
+## Red Flags
+
+- Starting implementation without a written task list
+- Writing tasks somewhere other than `.plan_task/task.md`
+- Tasks that say "implement the feature" without acceptance criteria
+- No verification steps in the plan
+- All tasks are XL-sized
+- No checkpoints between tasks
+- Dependency order isn't considered
+
+## Verification
+
+Before starting implementation, confirm:
+
+- [ ] Every task has acceptance criteria
+- [ ] Every task has a verification step
+- [ ] Task dependencies are identified and ordered correctly
+- [ ] Tasks are recorded in `.plan_task/task.md`
+- [ ] No task touches more than ~5 files
+- [ ] Checkpoints exist between major phases
+- [ ] The human has reviewed and approved the plan
+
+## See Also
+
+Acceptance criteria are per-task and answer "did we build the right thing?". They sit on top of any project-wide Definition of Done, the standing bar every task clears before it counts as done.

package/extensions/planning-method.test.ts

@@ -0,0 +1,20 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { loadPlanningMethod, PLANNING_METHOD_HEADINGS } from "./planning-method.ts";
+
+describe("loadPlanningMethod", () => {
+	it("keeps the same section headings as planning-and-task-breakdown.md", () => {
+		const method = loadPlanningMethod();
+		let cursor = 0;
+		for (const heading of PLANNING_METHOD_HEADINGS) {
+			const index = method.indexOf(heading, cursor);
+			assert.notEqual(index, -1, `missing heading: ${heading}`);
+			cursor = index + heading.length;
+		}
+		assert.doesNotMatch(method, /^---/);
+		assert.doesNotMatch(method, /This skill/);
+		assert.doesNotMatch(method, /tasks\/todo\.md/);
+		assert.match(method, /\.plan_task\/plan\.md/);
+		assert.match(method, /\.plan_task\/task\.md/);
+	});
+});

package/extensions/planning-method.ts

@@ -0,0 +1,38 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * /plan methodology file.
+ *
+ * Section headings match `planning-and-task-breakdown.md` at the workspace
+ * root so later updates can be copied section-by-section from that file.
+ *
+ * Plan-task-only adaptations (do not copy these from the source blindly):
+ * - Output paths are `.plan_task/plan.md` and `.plan_task/task.md`
+ * - Checklist items must be `- [ ] N. Title`
+ * - No external tracker, no skill frontmatter, no definition-of-done.md link
+ */
+export const PLANNING_METHOD_FILE = resolve(
+	dirname(fileURLToPath(import.meta.url)),
+	"planning-and-task-breakdown.md",
+);
+
+export const PLANNING_METHOD_HEADINGS = [
+	"# Planning and Task Breakdown",
+	"## Overview",
+	"## When to Use",
+	"## The Planning Process",
+	"## Task Sizing Guidelines",
+	"## Output Files",
+	"## Plan Document Template",
+	"## Parallelization Opportunities",
+	"## Common Rationalizations",
+	"## Red Flags",
+	"## Verification",
+	"## See Also",
+] as const;
+
+export function loadPlanningMethod(): string {
+	return readFileSync(PLANNING_METHOD_FILE, "utf8").trim();
+}

package/extensions/prompts.test.ts

@@ -0,0 +1,70 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { PLANNING_METHOD_HEADINGS } from "./planning-method.ts";
+import { buildPrompt, buildRequest, buildStatus, buildStatusKey, planPrompt, planRequest } from "./prompts.ts";
+
+describe("planPrompt", () => {
+	it("injects the request, runtime rules, and planning method headings", () => {
+		const source = { kind: "prompt" as const, prompt: "Add login" };
+		const prompt = planPrompt(source);
+		assert.equal(planRequest(source), "Add login");
+		assert.match(prompt, /Request:\nAdd login/);
+		assert.match(prompt, /Runtime rules:/);
+		assert.match(prompt, /\.plan_task\/plan\.md/);
+		assert.match(prompt, /\.plan_task\/task\.md/);
+		assert.match(prompt, /- \[ \] N\. Title/);
+		for (const heading of PLANNING_METHOD_HEADINGS) {
+			assert.match(prompt, new RegExp(heading.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")));
+		}
+		assert.doesNotMatch(prompt, /Planning skill/);
+		assert.doesNotMatch(prompt, /tasks\/todo\.md/);
+		assert.match(prompt, /ask_user_question/);
+	});
+
+	it("inlines a spec file and extra notes", () => {
+		const prompt = planPrompt({
+			kind: "file",
+			displayPath: "docs/spec.md",
+			resolvedPath: "/tmp/docs/spec.md",
+			notes: "focus on OAuth",
+			content: "# Auth\nAdd login.",
+		});
+		assert.match(prompt, /Request:\nWrite a plan from docs\/spec\.md\.\n\nfocus on OAuth/);
+		assert.match(prompt, /Spec file \(docs\/spec\.md\):/);
+		assert.match(prompt, /# Auth\nAdd login\./);
+		assert.match(prompt, /treat it as the primary requirements/);
+	});
+});
+
+describe("buildPrompt", () => {
+	it("scopes work to one task and requires acceptance criteria", () => {
+		const task = {
+			id: 2,
+			title: "Add login UI",
+			done: false,
+			body: "## Task 2: Add login UI\n\n**Acceptance criteria:**\n- [ ] Form submits",
+		};
+		const prompt = buildPrompt(task, 3, false);
+		assert.equal(buildRequest(task), "Execute planned task 2. Add login UI");
+		assert.match(prompt, /Current task: 2\. Add login UI/);
+		assert.match(prompt, /Remaining tasks after this one: 2/);
+		assert.match(prompt, /Form submits/);
+		assert.match(prompt, /acceptance criteria/);
+		assert.match(prompt, /ask_user_question/);
+		assert.match(prompt, /Do not start the next task/);
+	});
+});
+
+describe("buildStatus", () => {
+	it("summarizes checklist progress for later turns", () => {
+		const tasks = [
+			{ id: 1, title: "API", done: true, body: "" },
+			{ id: 2, title: "UI", done: false, body: "" },
+		];
+		const status = buildStatus(tasks, 2);
+		assert.match(status, /Progress 1\/2/);
+		assert.match(status, /\[x\] 1\. API/);
+		assert.match(status, /\[ \] 2\. UI {2}<- current/);
+		assert.equal(buildStatusKey(tasks, 2), "2:1:1,2:0");
+	});
+});

package/extensions/prompts.ts

@@ -0,0 +1,87 @@
+import { loadPlanningMethod } from "./planning-method.ts";
+import type { PlanSource } from "./plan-input.ts";
+import type { TaskItem } from "./types.ts";
+
+export const DEFAULT_PLAN_REQUEST = "Write a plan from the current conversation and repository.";
+
+export function planRequest(source: PlanSource): string {
+	if (source.kind === "empty") return DEFAULT_PLAN_REQUEST;
+	if (source.kind === "prompt") return source.prompt.trim() || DEFAULT_PLAN_REQUEST;
+	const notes = source.notes.trim();
+	const head = `Write a plan from ${source.displayPath}.`;
+	return notes ? `${head}\n\n${notes}` : head;
+}
+
+function specSection(source: PlanSource): string {
+	if (source.kind !== "file") return "";
+	if (source.content !== undefined) {
+		return `\nSpec file (${source.displayPath}):\n\`\`\`\n${source.content}\n\`\`\`\n`;
+	}
+	return `\nSpec file: ${source.displayPath}\nThe file is too large to inline. Read \`${source.resolvedPath}\` with the read tool before writing the plan.\n`;
+}
+
+/** Delivered once when plan mode starts. Not a system-prompt patch. */
+export function planPrompt(source: PlanSource): string {
+	const request = planRequest(source);
+	return `You are in plan mode. Explore the repository and write a plan. Do not implement product code.
+
+Request:
+${request}
+${specSection(source)}
+Runtime rules:
+- Do not modify project files.
+- The only files you may create or edit are \`.plan_task/plan.md\` and \`.plan_task/task.md\`.
+- Use write/edit for those two files. Do not implement the work itself.
+- Follow the planning method below for process, task sizing, templates, and verification.
+- The checklist lines in \`.plan_task/task.md\` must stay in the exact form \`- [ ] N. Title\` so later sessions can resume.
+- If a spec file is provided, treat it as the primary requirements.
+- If a consequential, user-answerable decision remains, call \`ask_user_question\` with 2-4 options, a recommended default, and an Other path. Do not leave blocking decisions as open questions in the plan.
+- When both files are written, stop and wait for /build.
+
+${loadPlanningMethod()}`;
+}
+
+export function buildRequest(task: TaskItem): string {
+	return `Execute planned task ${task.id}. ${task.title}`;
+}
+
+/** Delivered once when a build task starts. Not a system-prompt patch. */
+export function buildPrompt(task: TaskItem, remaining: number, continueAll: boolean): string {
+	const stopRule = continueAll
+		? "After this task is complete, mark it done. Remaining tasks will be assigned automatically. Do not stop to ask about sessions."
+		: "After this task is complete, mark it done and stop. Do not start the next task.";
+	const body = task.body.trim() || `## Task ${task.id}: ${task.title}`;
+	return `Execute exactly one planned task. Do not start any other task.
+
+Current task: ${task.id}. ${task.title}
+Remaining tasks after this one: ${Math.max(0, remaining - 1)}
+
+${body}
+
+Rules:
+- Implement only this task.
+- Follow existing project conventions.
+- Leave the system in a working state when the task ends.
+- Verify against this task's acceptance criteria and verification steps before marking it done.
+- Do not mark the task complete if acceptance criteria are unmet or verification failed.
+- If a consequential decision is still ambiguous, call \`ask_user_question\` instead of guessing.
+- When the task is done, call the plan_task tool with action "complete" and this task id, and keep the matching checklist box checked in \`.plan_task/task.md\`.
+- ${stopRule}`;
+}
+
+export function buildStatus(tasks: TaskItem[], currentId: number): string {
+	const done = tasks.filter((task) => task.done).length;
+	const lines = tasks.map((task) => {
+		const mark = task.done ? "[x]" : "[ ]";
+		const current = task.id === currentId ? "  <- current" : "";
+		return `- ${mark} ${task.id}. ${task.title}${current}`;
+	});
+	return `[BUILD STATUS]
+Progress ${done}/${tasks.length}
+
+${lines.join("\n")}`;
+}
+
+export function buildStatusKey(tasks: TaskItem[], currentId: number): string {
+	return `${currentId}:${tasks.map((task) => `${task.id}:${task.done ? "1" : "0"}`).join(",")}`;
+}

package/extensions/types.ts

@@ -0,0 +1,26 @@
+export interface PlanTaskConfig {
+	planTools: string[];
+}
+
+export interface TaskItem {
+	id: number;
+	title: string;
+	done: boolean;
+	body: string;
+}
+
+export interface TaskFile {
+	raw: string;
+	tasks: TaskItem[];
+}
+
+export const DEFAULT_PLAN_TOOLS = ["read", "bash", "grep", "find", "ls", "pwsh", "rg"] as const;
+
+export const DEFAULT_CONFIG: PlanTaskConfig = {
+	planTools: [...DEFAULT_PLAN_TOOLS],
+};
+
+export const PLAN_DIR_NAME = ".plan_task";
+export const PLAN_FILE_NAME = "plan.md";
+export const TASK_FILE_NAME = "task.md";
+export const CONFIG_FILE_NAME = "plan_task.json";

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "pi-plan-task",
+  "version": "1.0.0",
+  "license": "MIT",
+  "description": "Pi package: /plan, /build, /goal, /tasks.",
+  "keywords": ["pi-package"],
+  "files": ["extensions", "README.md"],
+  "type": "module",
+  "pi": {
+    "extensions": ["./extensions/index.ts"]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  }
+}