@tianhai/pi-workflow-kit 0.7.0 → 0.8.0

package/README.md

@@ -13,7 +13,7 @@ brainstorm → plan → execute → finalize
 **1 extension** that enforces the rules:
 
 - During brainstorming and planning, `write` and `edit` are **hard-blocked** outside `docs/plans/`. The agent can only read code and discuss the design with you — it literally cannot modify source files.
-- `bash` stays available for investigation (`grep`, `find`, `git log`, etc.).
+- `bash` is **restricted to read-only commands** — file writes, installs, git mutations, and editors are blocked. Safe commands like `grep`, `find`, `git status`, `cat`, `curl` remain available.
 
 No configuration required. Skills and extensions activate automatically after install.
 
@@ -34,7 +34,7 @@ You control each phase explicitly by invoking the skill:
 | **Execute** | `/skill:executing-tasks` | Implement the plan task-by-task with TDD discipline and optional checkpoint review gates |
 | **Finalize** | `/skill:finalizing` | Archive plan docs, update README/CHANGELOG, create PR |
 
-During brainstorm and plan, the extension blocks `write`/`edit` outside `docs/plans/`. During execute and finalize, all tools are available.
+During brainstorm and plan, the extension blocks `write`/`edit` outside `docs/plans/` and restricts `bash` to read-only commands. During execute and finalize, all tools are available.
 
 ### Skills
 

package/docs/plans/completed/2026-04-15-bash-guard-design.md

@@ -0,0 +1,39 @@
+# Bash Guard for Workflow Guard Extension
+
+## Problem
+
+`workflow-guard.ts` blocks `write`/`edit` outside `docs/plans/` during brainstorm and plan phases, but ignores `bash` entirely. The LLM can mutate files via bash (e.g. `echo "..." > file.ts`, `sed -i`, `tee`, heredocs).
+
+## Design
+
+Adopt the `isSafeCommand()` approach from [pi-mono plan-mode example](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/examples/extensions/plan-mode/utils.ts).
+
+### Approach
+
+**No changes to `pi.setActiveTools()`** — `write`/`edit` remain active so the existing path-based `tool_call` guard continues to allow writes to `docs/plans/`.
+
+**Add a bash guard** in the existing `tool_call` handler using `isSafeCommand()`:
+- Copy SAFE_PATTERNS and DESTRUCTIVE_PATTERNS from the example's `utils.ts` as-is
+- Copy `isSafeCommand()` logic as-is
+- In the `tool_call` handler, when phase is set and tool is `bash`, check `isSafeCommand(event.input.command)`
+- Block with reason if not safe
+- Notify via `ctx.ui.notify()` when blocking
+
+### Changes
+
+1. **`extensions/workflow-guard.ts`**
+   - Add `isSafeCommand()` function (copied from example, with DESTRUCTIVE_PATTERNS and SAFE_PATTERNS)
+   - Extend `tool_call` handler to also intercept `bash` when phase is set
+   - Check `event.input.command` against `isSafeCommand()`
+   - Block and notify if unsafe
+
+2. **`tests/workflow-guard.test.ts`**
+   - Add tests for bash guard: safe commands pass, destructive commands blocked, redirects blocked
+   - Import and test `isSafeCommand` directly (it's a pure function, easy to unit test)
+
+### What stays the same
+
+- Phase detection via `/skill:` commands (no change)
+- `write`/`edit` path-based blocking for `docs/plans/` (no change)
+- `docs/plans/` write exception (no change)
+- No `pi.setActiveTools()` usage

package/docs/plans/completed/2026-04-15-bash-guard-implementation.md

@@ -0,0 +1,229 @@
+# Bash Guard Implementation Plan
+
+Based on `docs/plans/2026-04-15-bash-guard-design.md`.
+
+## Task 1 — Add `isSafeCommand()` to workflow-guard.ts [new feature, checkpoint: test]
+
+**File:** `extensions/workflow-guard.ts`
+
+- Add `isSafeCommand` as a named export (so tests can import it directly)
+- Copy `DESTRUCTIVE_PATTERNS` and `SAFE_PATTERNS` from [plan-mode utils.ts](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/examples/extensions/plan-mode/utils.ts) as-is
+- Copy the `isSafeCommand()` logic as-is
+
+```ts
+// Destructive commands blocked in brainstorm/plan phases
+const DESTRUCTIVE_PATTERNS = [
+	/\brm\b/i,
+	/\brmdir\b/i,
+	/\bmv\b/i,
+	/\bcp\b/i,
+	/\bmkdir\b/i,
+	/\btouch\b/i,
+	/\bchmod\b/i,
+	/\bchown\b/i,
+	/\bchgrp\b/i,
+	/\bln\b/i,
+	/\btee\b/i,
+	/\btruncate\b/i,
+	/\bdd\b/i,
+	/\bshred\b/i,
+	/(^|[^<])>(?!>)/,
+	/>>/,
+	/\bnpm\s+(install|uninstall|update|ci|link|publish)/i,
+	/\byarn\s+(add|remove|install|publish)/i,
+	/\bpnpm\s+(add|remove|install|publish)/i,
+	/\bpip\s+(install|uninstall)/i,
+	/\bapt(-get)?\s+(install|remove|purge|update|upgrade)/i,
+	/\bbrew\s+(install|uninstall|upgrade)/i,
+	/\bgit\s+(add|commit|push|pull|merge|rebase|reset|checkout|branch\s+-[dD]|stash|cherry-pick|revert|tag|init|clone)/i,
+	/\bsudo\b/i,
+	/\bsu\b/i,
+	/\bkill\b/i,
+	/\bpkill\b/i,
+	/\bkillall\b/i,
+	/\breboot\b/i,
+	/\bshutdown\b/i,
+	/\bsystemctl\s+(start|stop|restart|enable|disable)/i,
+	/\bservice\s+\S+\s+(start|stop|restart)/i,
+	/\b(vim?|nano|emacs|code|subl)\b/i,
+];
+
+const SAFE_PATTERNS = [
+	/^\s*cat\b/,
+	/^\s*head\b/,
+	/^\s*tail\b/,
+	/^\s*less\b/,
+	/^\s*more\b/,
+	/^\s*grep\b/,
+	/^\s*find\b/,
+	/^\s*ls\b/,
+	/^\s*pwd\b/,
+	/^\s*echo\b/,
+	/^\s*printf\b/,
+	/^\s*wc\b/,
+	/^\s*sort\b/,
+	/^\s*uniq\b/,
+	/^\s*diff\b/,
+	/^\s*file\b/,
+	/^\s*stat\b/,
+	/^\s*du\b/,
+	/^\s*df\b/,
+	/^\s*tree\b/,
+	/^\s*which\b/,
+	/^\s*whereis\b/,
+	/^\s*type\b/,
+	/^\s*env\b/,
+	/^\s*printenv\b/,
+	/^\s*uname\b/,
+	/^\s*whoami\b/,
+	/^\s*id\b/,
+	/^\s*date\b/,
+	/^\s*cal\b/,
+	/^\s*uptime\b/,
+	/^\s*ps\b/,
+	/^\s*top\b/,
+	/^\s*htop\b/,
+	/^\s*free\b/,
+	/^\s*git\s+(status|log|diff|show|branch|remote|config\s+--get)/i,
+	/^\s*git\s+ls-/i,
+	/^\s*npm\s+(list|ls|view|info|search|outdated|audit)/i,
+	/^\s*yarn\s+(list|info|why|audit)/i,
+	/^\s*node\s+--version/i,
+	/^\s*python\s+--version/i,
+	/^\s*curl\s/i,
+	/^\s*wget\s+-O\s*-/i,
+	/^\s*jq\b/,
+	/^\s*sed\s+-n/i,
+	/^\s*awk\b/,
+	/^\s*rg\b/,
+	/^\s*fd\b/,
+	/^\s*bat\b/,
+	/^\s*eza\b/,
+];
+
+export function isSafeCommand(command: string): boolean {
+	const isDestructive = DESTRUCTIVE_PATTERNS.some((p) => p.test(command));
+	const isSafe = SAFE_PATTERNS.some((p) => p.test(command));
+	return !isDestructive && isSafe;
+}
+```
+
+- Write failing tests in `tests/workflow-guard.test.ts` for `isSafeCommand`:
+
+```ts
+import { isSafeCommand } from "../extensions/workflow-guard";
+
+describe("isSafeCommand", () => {
+	it("allows safe read-only commands", () => {
+		expect(isSafeCommand("cat file.ts")).toBe(true);
+		expect(isSafeCommand("grep -r 'foo' src/")).toBe(true);
+		expect(isSafeCommand("git status")).toBe(true);
+		expect(isSafeCommand("git log --oneline -5")).toBe(true);
+		expect(isSafeCommand("npm list")).toBe(true);
+		expect(isSafeCommand("ls -la")).toBe(true);
+		expect(isSafeCommand("curl https://example.com")).toBe(true);
+	});
+
+	it("blocks destructive commands", () => {
+		expect(isSafeCommand("rm -rf node_modules")).toBe(false);
+		expect(isSafeCommand("touch newfile.ts")).toBe(false);
+		expect(isSafeCommand("mv old.ts new.ts")).toBe(false);
+		expect(isSafeCommand("mkdir src/components")).toBe(false);
+	});
+
+	it("blocks file-writing bash patterns", () => {
+		expect(isSafeCommand("echo 'hello' > file.ts")).toBe(false);
+		expect(isSafeCommand("cat config > backup.txt")).toBe(false);
+		expect(isSafeCommand("echo 'log' >> output.log")).toBe(false);
+		expect(isSafeCommand("tee output.txt")).toBe(false);
+		expect(isSafeCommand("sed -i 's/old/new/g' file.ts")).toBe(false);
+	});
+
+	it("blocks git mutations but allows read-only git", () => {
+		expect(isSafeCommand("git add .")).toBe(false);
+		expect(isSafeCommand("git commit -m 'msg'")).toBe(false);
+		expect(isSafeCommand("git push")).toBe(false);
+		expect(isSafeCommand("git checkout -b feature")).toBe(false);
+		expect(isSafeCommand("git status")).toBe(true);
+		expect(isSafeCommand("git log --oneline")).toBe(true);
+		expect(isSafeCommand("git diff")).toBe(true);
+	});
+
+	it("blocks editors", () => {
+		expect(isSafeCommand("vim file.ts")).toBe(false);
+		expect(isSafeCommand("nano file.ts")).toBe(false);
+		expect(isSafeCommand("code .")).toBe(false);
+	});
+
+	it("blocks sudo", () => {
+		expect(isSafeCommand("sudo apt install foo")).toBe(false);
+	});
+
+	it("blocks npm installs but allows read-only npm", () => {
+		expect(isSafeCommand("npm install lodash")).toBe(false);
+		expect(isSafeCommand("npm list")).toBe(true);
+		expect(isSafeCommand("npm audit")).toBe(true);
+	});
+});
+```
+
+- Run: `npx vitest run tests/workflow-guard.test.ts`
+- Verify: all new `isSafeCommand` tests fail (function doesn't exist yet)
+- Implement `isSafeCommand()` in `extensions/workflow-guard.ts`
+- Run: `npx vitest run tests/workflow-guard.test.ts`
+- Verify: all tests pass
+- `git add -A && git commit -m "feat: add isSafeCommand bash guard to workflow-guard"`
+
+## Task 2 — Wire bash guard into tool_call handler [modifying tested code]
+
+**File:** `extensions/workflow-guard.ts`
+
+Replace the tool_call guard from:
+```ts
+if (event.toolName !== "write" && event.toolName !== "edit") return;
+```
+
+To:
+```ts
+if (event.toolName === "bash") {
+	const command = (event.input as { command?: string }).command ?? "";
+	if (!isSafeCommand(command)) {
+		if (ctx.hasUI) {
+			ctx.ui.notify(
+				`Blocked bash command during ${phase} phase: ${command}`,
+				"warning",
+			);
+		}
+		return {
+			block: true,
+			reason: `⚠️ ${phase.toUpperCase()} PHASE: Bash command blocked (not allowlisted). Only read-only commands are permitted during brainstorming and planning.\nCommand: ${command}`,
+		};
+	}
+	return;
+}
+
+if (event.toolName !== "write" && event.toolName !== "edit") return;
+```
+
+- Run: `npx vitest run tests/workflow-guard.test.ts`
+- Verify: existing tests pass (the "should allow bash" test needs updating — see Task 3)
+- `git add -A && git commit -m "feat: wire bash guard into tool_call handler"`
+
+## Task 3 — Update existing test for new bash behavior [modifying tested code]
+
+**File:** `tests/workflow-guard.test.ts`
+
+The test `"should allow bash regardless of phase"` is now incorrect — bash with unsafe commands should be blocked. Update it:
+
+```ts
+it("should block unsafe bash during brainstorm (safe bash tested via isSafeCommand)", () => {
+	// The tool_call handler now guards bash via isSafeCommand.
+	// Direct testing of safe/unsafe commands is in the isSafeCommand describe block.
+	// This just confirms bash is no longer blanket-allowed.
+	expect(isSafeCommand("rm -rf /")).toBe(false);
+});
+```
+
+- Run: `npx vitest run tests/workflow-guard.test.ts`
+- Verify: all tests pass
+- `git add -A && git commit -m "test: update bash guard test for new blocking behavior"`

package/extensions/workflow-guard.ts

@@ -1,15 +1,112 @@
+import { resolve } from "node:path";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 
 /**
  * Workflow Guard extension.
  *
- * Blocks write/edit outside docs/plans/ during brainstorm and plan phases.
+ * Blocks write/edit outside docs/plans/ and unsafe bash during brainstorm and plan phases.
  * You control phases explicitly via /skill: commands — no auto-detection,
  * no state persistence, no prompts.
  */
 
 type Phase = "brainstorm" | "plan" | null;
 
+// Destructive commands blocked in brainstorm/plan phases
+const DESTRUCTIVE_PATTERNS = [
+	/\brm\b/i,
+	/\brmdir\b/i,
+	/\bmv\b/i,
+	/\bcp\b/i,
+	/\bmkdir\b/i,
+	/\btouch\b/i,
+	/\bchmod\b/i,
+	/\bchown\b/i,
+	/\bchgrp\b/i,
+	/\bln\b/i,
+	/\btee\b/i,
+	/\btruncate\b/i,
+	/\bdd\b/i,
+	/\bshred\b/i,
+	/(^|[^<])>(?!>)/,
+	/>>/,
+	/\bnpm\s+(install|uninstall|update|ci|link|publish)/i,
+	/\byarn\s+(add|remove|install|publish)/i,
+	/\bpnpm\s+(add|remove|install|publish)/i,
+	/\bpip\s+(install|uninstall)/i,
+	/\bapt(-get)?\s+(install|remove|purge|update|upgrade)/i,
+	/\bbrew\s+(install|uninstall|upgrade)/i,
+	/\bgit\s+(add|commit|push|pull|merge|rebase|reset|checkout|branch\s+-[dD]|stash|cherry-pick|revert|tag|init|clone)/i,
+	/\bsudo\b/i,
+	/\bsu\b/i,
+	/\bkill\b/i,
+	/\bpkill\b/i,
+	/\bkillall\b/i,
+	/\breboot\b/i,
+	/\bshutdown\b/i,
+	/\bsystemctl\s+(start|stop|restart|enable|disable)/i,
+	/\bservice\s+\S+\s+(start|stop|restart)/i,
+	/\b(vim?|nano|emacs|code|subl)\b/i,
+];
+
+const SAFE_PATTERNS = [
+	/^\s*cat\b/,
+	/^\s*head\b/,
+	/^\s*tail\b/,
+	/^\s*less\b/,
+	/^\s*more\b/,
+	/^\s*grep\b/,
+	/^\s*find\b/,
+	/^\s*ls\b/,
+	/^\s*pwd\b/,
+	/^\s*echo\b/,
+	/^\s*printf\b/,
+	/^\s*wc\b/,
+	/^\s*sort\b/,
+	/^\s*uniq\b/,
+	/^\s*diff\b/,
+	/^\s*file\b/,
+	/^\s*stat\b/,
+	/^\s*du\b/,
+	/^\s*df\b/,
+	/^\s*tree\b/,
+	/^\s*which\b/,
+	/^\s*whereis\b/,
+	/^\s*type\b/,
+	/^\s*env\b/,
+	/^\s*printenv\b/,
+	/^\s*uname\b/,
+	/^\s*whoami\b/,
+	/^\s*id\b/,
+	/^\s*date\b/,
+	/^\s*cal\b/,
+	/^\s*uptime\b/,
+	/^\s*ps\b/,
+	/^\s*top\b/,
+	/^\s*htop\b/,
+	/^\s*free\b/,
+	/^\s*git\s+(status|log|diff|show|branch|remote|config\s+--get)/i,
+	/^\s*git\s+ls-/i,
+	/^\s*npm\s+(list|ls|view|info|search|outdated|audit)/i,
+	/^\s*yarn\s+(list|info|why|audit)/i,
+	/^\s*node\s+--version/i,
+	/^\s*python\s+--version/i,
+	/^\s*curl\s/i,
+	/^\s*wget\s+-O\s*-/i,
+	/^\s*jq\b/,
+	/^\s*sed\s+-n/i,
+	/^\s*awk\b/,
+	/^\s*rg\b/,
+	/^\s*fd\b/,
+	/^\s*bat\b/,
+	/^\s*eza\b/,
+];
+
+export function isSafeCommand(command: string): boolean {
+	const isDestructive = DESTRUCTIVE_PATTERNS.some((p) => p.test(command));
+	const isSafe = SAFE_PATTERNS.some((p) => p.test(command));
+	return !isDestructive && isSafe;
+}
+
 const SKILL_TO_PHASE: Record<string, Phase> = {
 	brainstorming: "brainstorm",
 	"writing-plans": "plan",
@@ -28,15 +125,17 @@ export default function (pi: ExtensionAPI) {
 
 	pi.on("input", (event) => {
 		const text = event.text ?? "";
-		for (const [skill, p] of Object.entries(SKILL_TO_PHASE)) {
-			if (text.includes(skill)) {
-				phase = p;
+		const match = text.match(/^\/skill:([\w-]+)/);
+		if (match) {
+			const skill = match[1];
+			if (skill in SKILL_TO_PHASE) {
+				phase = SKILL_TO_PHASE[skill];
 				return;
 			}
 		}
 		if (
-			text.includes("executing-tasks") ||
-			text.includes("finalizing")
+			text.startsWith("/skill:executing-tasks") ||
+			text.startsWith("/skill:finalizing")
 		) {
 			phase = null;
 		}
@@ -45,12 +144,31 @@ export default function (pi: ExtensionAPI) {
 	pi.on("tool_call", (event, ctx) => {
 		if (!phase) return;
 
+		if (event.toolName === "bash") {
+			const command = (event.input as { command?: string }).command ?? "";
+			if (!isSafeCommand(command)) {
+				if (ctx.hasUI) {
+					ctx.ui.notify(
+						`Blocked bash command during ${phase} phase: ${command}`,
+						"warning",
+					);
+				}
+				return {
+					block: true,
+					reason: `⚠️ ${phase.toUpperCase()} PHASE: Bash command blocked (not allowlisted). Only read-only commands are permitted during brainstorming and planning.\nCommand: ${command}`,
+				};
+			}
+			return;
+		}
+
 		if (event.toolName !== "write" && event.toolName !== "edit") return;
 
 		const filePath = (event.input as { path?: string }).path ?? "";
 		if (!filePath) return;
 
-		if (filePath.startsWith("docs/plans/")) return;
+		const absolute = resolve(ctx.cwd, filePath);
+		const plansDir = resolve(ctx.cwd, "docs/plans");
+		if (absolute.startsWith(plansDir + "/")) return;
 
 		if (ctx.hasUI) {
 			ctx.ui.notify(
@@ -60,7 +178,7 @@ export default function (pi: ExtensionAPI) {
 		}
 
 		return {
-			blocked: true,
+			block: true,
 			reason: `⚠️ ${phase.toUpperCase()} PHASE: Cannot ${event.toolName} to ${filePath}. Only docs/plans/ is writable during brainstorming and planning.`,
 		};
 	});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tianhai/pi-workflow-kit",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Workflow skills and enforcement extensions for pi",
   "keywords": [
     "pi-package"

package/docs/plans/2026-04-11-finalizing-merge-options-design.md

@@ -1,33 +0,0 @@
-# Finalizing: Merge Strategy Options
-
-## Problem
-
-The finalizing skill hard-codes "Create PR" as the only shipping option. In practice, small features often don't need a PR — they can be merged directly back to the parent branch.
-
-## Design
-
-Add a merge strategy step after updating documentation. The human chooses one of four options:
-
-1. **Create PR** — push and open a PR for external review via `gh pr create`
-2. **Rebase & merge** (recommended) — rebase onto parent, fast-forward merge, push parent, delete feature branch. Preserves per-task commit history linearly.
-3. **Squash & merge** — squash all commits into one on parent, push parent, delete feature branch. Clean single-commit history.
-4. **Merge commit** — merge with `--no-ff`, push parent, delete feature branch. Preserves all commits and branch topology.
-
-### Flow for options 2–4 (local merge)
-
-1. Detect parent branch (compare `main` vs `master`, fall back to `git show-branch`)
-2. Switch to parent branch and pull latest
-3. Execute the chosen merge strategy:
-   - Rebase: `git rebase <parent>` on feature branch, then `git merge --ff-only <feature>` on parent
-   - Squash: `git merge --squash <feature>` on parent, then `git commit`
-   - Merge commit: `git merge --no-ff <feature>` on parent
-4. Push parent to origin
-5. Delete feature branch locally and remotely
-
-### Prompting
-
-The skill should ask the human which option they prefer, presenting rebase & merge as the default recommendation.
-
-## Changes
-
-- Update `skills/finalizing/SKILL.md` to replace the hard-coded PR step with the 4-option choice.