@normful/picadillo 2.0.3 → 2.1.0

package/CHANGELOG.md

@@ -1,8 +1,26 @@
+## [2.1.0] - 2026-02-17
+
+### 🚀 Features
+
+- *(extension)* Add mulch extension for project learning management
+- *(extension)* Add gastown extension for gt integration
+
+### 🚜 Refactor
+
+- *(test)* Replace `vi.fn()` with `mock` from `bun:test` in parrot tests
+
+### 📚 Documentation
+
+- Update README with reorganized skills and extensions sections
 ## [2.0.3] - 2026-02-16
 
 ### 📚 Documentation
 
 - *(README)* Add parrot extension demo screenshot to README
+
+### ⚙️ Miscellaneous Tasks
+
+- Release 2.0.3
 ## [2.0.2] - 2026-02-16
 
 ### 🚀 Features

package/README.md

@@ -27,7 +27,8 @@ repeatedly poke reality until it tastes better.”
 pi install https://github.com/normful/picadillo
 ```
 
-Configure what you don't want with `pi config`. It will modify `~/.pi/agent/settings.json`
+Configure what you don't want with `pi config`. It will modify
+`~/.pi/agent/settings.json`
 
 ## Dependencies
 
@@ -35,19 +36,38 @@ Configure what you don't want with `pi config`. It will modify `~/.pi/agent/sett
 
 ## Skills
 
-| Skill | Description |
-|-------|-------------|
-| [run-in-tmux](skills/run-in-tmux/) | Run commands in a new tmux session with split panes. Useful for dev environments, parallel processes, and persistent background tasks. |
+### run-in-tmux
 
+Run commands in a new tmux session with split panes. Useful for dev
+environments, parallel processes, and persistent background tasks.
+
+### mulch
+
+Usage examples showing how to use [mulch](https://github.com/jayminwest/mulch)
+to record and retrieve structured project
+learnings.
 
 ## Extensions
 
-| Extension | Description |
-|-----------|-------------|
-| [parrot](extensions/parrot.ts) | Opens the last AI response in an external text editor (respects `$VISUAL` or `$EDITOR`), then sends your edited content back to the chat. Useful for editing AI responses before re-sending, copying output to a full-featured editor, or iterating with custom edits. Usage: `/parrot` or `Alt+R` |
+### parrot
+
+Opens the last AI response in an external text editor (respects `$VISUAL` or
+`$EDITOR`), then sends your edited content back to the chat. Useful for editing
+AI responses before re-sending, copying output to a full-featured editor, or
+iterating with custom edits.
+
+Usage: `/parrot` or `Alt+R`
+
+### gastown
+
+Hooks to automatically run `gt prime` and `gt mail` from [gastown](https://github.com/steveyegge/gastown)
+
+### mulch
 
+Hooks to automatically run [mulch](https://github.com/jayminwest/mulch) for
+recording and retrieving structured project learnings.
 
-### Parrot Extension Demo
+## Parrot Extension Demo
 
 [![asciicast](https://asciinema.org/a/788693.svg)](https://asciinema.org/a/788693)
 

package/extensions/gastown.ts

@@ -0,0 +1,160 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExecResult } from "@mariozechner/pi-coding-agent";
+
+export type { ExecResult };
+export const GASTOWN_MESSAGE_TYPE = "gastown";
+export const AUTONOMOUS_ROLES = new Set(["polecat", "witness", "refinery", "deacon"]);
+
+export interface GastownConfig {
+  role?: string;
+}
+
+/**
+ * Run `gt prime --hook` to get prime text.
+ */
+export async function gastownPrime(execFn: ExtensionAPI["exec"]): Promise<string> {
+  let primeText = "";
+  try {
+    const { stdout } = await execFn("gt", ["prime", "--hook"]);
+    primeText = stdout;
+  } catch (e) {
+    console.error("[gastown] gt prime failed:", e);
+  }
+  return primeText;
+}
+
+/**
+ * Run `gt mail check --inject` to get mail text.
+ */
+export async function gastownMailCheck(execFn: ExtensionAPI["exec"]): Promise<string> {
+  let mailText = "";
+  try {
+    const { stdout } = await execFn("gt", ["mail", "check", "--inject"]);
+    mailText = stdout;
+  } catch (e) {
+    console.error("[gastown] gt mail check --inject failed:", e);
+  }
+  return mailText;
+}
+
+/**
+ * Record session costs using `gt costs record --session <sessionId>`.
+ */
+export async function recordSessionCosts(
+  execFn: ExtensionAPI["exec"],
+  sessionId: string,
+): Promise<void> {
+  try {
+    await execFn("gt", ["costs", "record", "--session", sessionId]);
+  } catch (e) {
+    console.error("[gastown] gt costs record failed:", e);
+  }
+}
+
+/**
+ * Check if the given role is an autonomous role.
+ */
+export function isAutonomousRole(role: string): boolean {
+  return AUTONOMOUS_ROLES.has(role.toLowerCase());
+}
+
+/**
+ * Handle session_start event.
+ * Fetches prime text and mail, sends combined message.
+ */
+export async function handleSessionStart(
+  execFn: ExtensionAPI["exec"],
+  sendMessage: ExtensionAPI["sendMessage"],
+): Promise<void> {
+  const primeText = await gastownPrime(execFn);
+  if (!primeText) return;
+
+  const mailText = await gastownMailCheck(execFn);
+  sendMessage(
+    {
+      customType: GASTOWN_MESSAGE_TYPE,
+      content: primeText + "\n\n" + mailText,
+      display: true,
+    },
+    {
+      deliverAs: "steer",
+      triggerTurn: true,
+    },
+  );
+}
+
+/**
+ * Handle before_agent_start event.
+ * Sends mail text only for autonomous roles.
+ */
+export function handleBeforeAgentStart(
+  role: string,
+  mailText: string,
+): { message: { customType: string; content: string; display: boolean } } | undefined {
+  if (!mailText || !isAutonomousRole(role)) return undefined;
+
+  return {
+    message: {
+      customType: GASTOWN_MESSAGE_TYPE,
+      content: mailText,
+      display: true,
+    },
+  };
+}
+
+/**
+ * Handle session_compact event.
+ * Fetches prime text and sends as follow-up.
+ */
+export async function handleSessionCompact(
+  execFn: ExtensionAPI["exec"],
+  sendMessage: ExtensionAPI["sendMessage"],
+): Promise<void> {
+  const primeText = await gastownPrime(execFn);
+  if (!primeText) return;
+
+  sendMessage(
+    {
+      customType: GASTOWN_MESSAGE_TYPE,
+      content: primeText,
+      display: true,
+    },
+    {
+      deliverAs: "followUp",
+      triggerTurn: true,
+    },
+  );
+}
+
+/**
+ * Handle session_shutdown event.
+ * Records session costs.
+ */
+export async function handleSessionShutdown(
+  execFn: ExtensionAPI["exec"],
+  sessionId: string,
+): Promise<void> {
+  await recordSessionCosts(execFn, sessionId);
+}
+
+export default function (pi: ExtensionAPI) {
+  const role = (process.env.GT_ROLE || "").toLowerCase();
+
+  pi.on("session_start", async (_event, _ctx) => {
+    await handleSessionStart(pi.exec, pi.sendMessage);
+  });
+
+  pi.on("before_agent_start", async (_event, _ctx) => {
+    const mailText = await gastownMailCheck(pi.exec);
+    return handleBeforeAgentStart(role, mailText);
+  });
+
+  pi.on("session_compact", async (_event, _ctx) => {
+    await handleSessionCompact(pi.exec, pi.sendMessage);
+  });
+
+  pi.on("session_shutdown", async (_event, ctx) => {
+    const sessionId = ctx.sessionManager.getSessionId();
+    await handleSessionShutdown(pi.exec, sessionId);
+  });
+}

package/extensions/mulch.ts

@@ -0,0 +1,75 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExecResult } from "@mariozechner/pi-coding-agent";
+
+export type { ExecResult };
+export const MULCH_MESSAGE_TYPE = "mulch";
+
+const APPEND_TO_MULCH_PRIME = `
+---
+
+But you should NOT run any above mulch commands right now.
+I am just letting you know the session close protocol, so that you remember to do it later.
+`;
+
+export async function mulchPrime(
+  execFn: ExtensionAPI["exec"],
+): Promise<string> {
+  let primeText = "";
+  try {
+    const { stdout } = await execFn("mulch", ["prime"]);
+    primeText = stdout;
+  } catch (e) {
+    console.error("mulch prime failed:", e);
+  }
+  return primeText;
+}
+
+export async function handleSessionStart(
+  execFn: ExtensionAPI["exec"],
+  sendMessage: ExtensionAPI["sendMessage"],
+): Promise<void> {
+  const primeText = await mulchPrime(execFn);
+  if (!primeText) return;
+
+  sendMessage(
+    {
+      customType: MULCH_MESSAGE_TYPE,
+      content: primeText + APPEND_TO_MULCH_PRIME,
+      display: true,
+    },
+    {
+      deliverAs: "steer",
+      triggerTurn: true,
+    },
+  );
+}
+
+export async function handleSessionCompact(
+  execFn: ExtensionAPI["exec"],
+  sendMessage: ExtensionAPI["sendMessage"],
+): Promise<void> {
+  const primeText = await mulchPrime(execFn);
+  if (!primeText) return;
+
+  sendMessage(
+    {
+      customType: MULCH_MESSAGE_TYPE,
+      content: primeText + APPEND_TO_MULCH_PRIME,
+      display: true,
+    },
+    {
+      deliverAs: "followUp",
+      triggerTurn: true,
+    },
+  );
+}
+
+export default function (pi: ExtensionAPI) {
+  pi.on("session_start", async (_event, _ctx) => {
+    await handleSessionStart(pi.exec, pi.sendMessage);
+  });
+
+  pi.on("session_compact", async (_event, _ctx) => {
+    await handleSessionCompact(pi.exec, pi.sendMessage);
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@normful/picadillo",
-  "version": "2.0.3",
+  "version": "2.1.0",
   "private": false,
   "description": "pi agent skills/extensions: run-in-tmux, parrot (send AI message with edited version of AI message)",
   "keywords": [

package/skills/mulch/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: mulch
+description: Record and retrieve structured project learnings using `mulch` CLI. Use when working on code and wanting to capture patterns, failures, decisions, conventions, references, or guides for future sessions.
+---
+
+# Mulch Usage
+
+Mulch captures project learnings as structured "records" organized by **domain**. Each domain represents a category of knowledge:
+
+| Domain | Description |
+|--------|-------------|
+| `purpose` | Why the project exists |
+| `identity` | Brand, naming, tone |
+| `public-interface` | APIs, CLI, UI surfaces |
+| `internal-structure` | Code organization |
+| `dependencies` | External libraries |
+| `data` | Database, schemas, models |
+| `configuration` | Env vars, settings |
+| `observability` | Logging, metrics, tracing |
+| `glossary` | Domain-specific terminology |
+
+---
+
+# When to Run Commands
+
+## 1. At Session Start
+
+Load all project expertise into your context:
+
+```bash
+mulch prime                    # load all project learnings
+mulch prime --files src/foo.ts # load only records relevant to specific files
+```
+
+This gives you awareness of existing patterns, decisions, and conventions before you start working.
+
+## 2. While Working
+
+Record insights as you discover them:
+
+```bash
+# Create a new domain if needed
+mulch add purpose
+
+# Record different types of learnings
+mulch record <domain> --type pattern --name "Auth Pattern" --description "Use middleware for auth checks before route handlers"
+mulch record <domain> --type failure --name "Missing Validation" --description "Form field not validated on client" --resolution "Add Zod schema validation"
+mulch record <domain> --type decision --title "Chose PostgreSQL" --rationale "Needed relational queries and ACID compliance"
+mulch record <domain> --type convention --content "API routes go in src/routes/"
+mulch record <domain> --type reference --name "Error Handling" --description "See docs/error patterns"
+mulch record <domain> --type guide --name "Setup Guide" --description "Run npm install then npm run dev"
+
+# Add evidence, files, tags
+mulch record <domain> --type pattern --name "..." --description "..." --evidence-commit abc123
+mulch record <domain> --type pattern --name "..." --description "..." --evidence-bead fix-42   # link to bd issue
+mulch record <domain> --type pattern --name "..." --description "..." --files "src/auth.ts,src/middleware.ts"
+mulch record <domain> --type pattern --name "..." --description "..." --tags "security,auth"
+
+# Link related records
+mulch record <domain> --type pattern --name "..." --description "..." --relates-to mx-abc123
+mulch record <domain> --type pattern --name "..." --description "..." --supersedes mx-old123
+
+# Batch record from JSON file
+mulch record <domain> --batch records.json
+mulch record <domain> --batch records.json --dry-run  # preview first
+```
+
+## 3. Before Finishing Your Task
+
+After all file editing is done (but before committing), run `mulch learn` to see what changed and get recording suggestions:
+
+```bash
+mulch learn
+mulch learn --since HEAD~3  # diff against specific commit
+```
+
+This shows which files were modified and can suggest what to record based on your changes.
+
+Then record any learnings and sync to git:
+
+```bash
+mulch record <domain> ...  # record learnings from this session
+mulch sync                  # validates, stages, and commits .mulch/ changes
+```
+
+**Note:** `mulch sync` runs `mulch validate` automatically before committing, so you don't need a separate validate step.
+
+---
+
+# Querying & Searching
+
+**Tip:** `--json` is a global flag that works with all commands below.
+
+```bash
+# Check domain status
+mulch status --json
+mulch status --json | jq '.'
+
+# Query records in a domain
+mulch query <domain> --json
+mulch query <domain> --type failure --json  # filter by type
+
+# Search across all domains
+mulch search "auth" --json
+mulch search "auth" --type pattern --json      # filter by type
+mulch search "auth" --tag security --json      # filter by tag
+mulch search "auth" --domain <domain> --json   # limit to domain
+
+# Show recent additions
+mulch ready --json
+
+# Show changes since git ref
+mulch diff --json
+mulch diff --since v1.0.0 --json
+```
+
+## Other Useful Commands
+
+```bash
+# Edit a record
+mulch edit <domain> mx-abc123 --description "Updated description"
+
+# Delete a record
+mulch delete <domain> mx-abc123
+
+# Compact similar records
+mulch compact <domain> --analyze
+mulch compact <domain> --apply --type pattern --name "Auth Patterns" --description "Combined from 5 records"
+
+# Generate onboarding snippet for AGENTS.md
+mulch onboard
+mulch onboard --check  # verify it's installed
+
+# Health check
+mulch doctor  # check for issues with --fix option
+
+# Check for updates
+mulch update
+```
+
+## JSON Output
+
+All commands support `--json` for scripting:
+```bash
+mulch status --json | jq '.'
+mulch query <domain> --json | jq '.[] | select(.type == "failure")'
+mulch search "auth" --json | jq '.[] | .name'
+```