@pi-unipi/unipi 0.1.2 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/unipi",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "All-in-one extension suite for Pi coding agent",
   "type": "module",
   "license": "MIT",
@@ -24,6 +24,7 @@
   ],
   "scripts": {
     "typecheck": "npx tsc --noEmit --skipLibCheck",
+    "test": "npm test --workspaces",
     "publish:all": "npm publish --workspaces --access public"
   },
   "files": [
@@ -39,7 +40,8 @@
       "node_modules/@pi-unipi/memory/index.ts",
       "node_modules/@pi-unipi/info-screen/index.ts",
       "node_modules/@pi-unipi/subagents/src/index.ts",
-      "node_modules/@pi-unipi/btw/extensions/btw.ts"
+      "node_modules/@pi-unipi/btw/extensions/btw.ts",
+      "node_modules/@pi-unipi/web-api/src/index.ts"
     ],
     "skills": [
       "node_modules/@pi-unipi/workflow/skills",
@@ -61,7 +63,8 @@
     "@pi-unipi/memory": "*",
     "@pi-unipi/info-screen": "*",
     "@pi-unipi/subagents": "*",
-    "@pi-unipi/btw": "*"
+    "@pi-unipi/btw": "*",
+    "@pi-unipi/web-api": "*"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",

package/packages/memory/index.ts

@@ -26,8 +26,9 @@ import {
   searchAllProjects,
   listAllProjects,
 } from "./storage.js";
-import { registerMemoryTools, MEMORY_TOOLS } from "./tools.js";
+import { registerMemoryTools, MEMORY_TOOLS, GLOBAL_SEARCH_ALIAS } from "./tools.js";
 import { registerMemoryCommands } from "./commands.js";
+import { isEmbeddingReady, hasModelChanged } from "./settings.js";
 
 /** Package version */
 const VERSION = getPackageVersion(new URL(".", import.meta.url).pathname);
@@ -47,6 +48,10 @@ function getStorage(): MemoryStorage {
 }
 
 export default function (pi: ExtensionAPI) {
+  // Lifecycle state — tracks whether recall/store have happened this session
+  let recallDone = false;
+  let storeDone = false;
+
   // Register skills directory
   const skillsDir = new URL("./skills", import.meta.url).pathname;
   pi.on("resources_discover", async (_event, _ctx) => {
@@ -56,11 +61,15 @@ export default function (pi: ExtensionAPI) {
   });
 
   // Register tools and commands
-  registerMemoryTools(pi, getStorage);
+  registerMemoryTools(pi, getStorage, () => { recallDone = true; storeDone = true; });
   registerMemoryCommands(pi, getStorage);
 
   // Session lifecycle
   pi.on("session_start", async (_event, ctx) => {
+    // Reset lifecycle flags
+    recallDone = false;
+    storeDone = false;
+
     // Initialize project storage
     const projectName = getProjectName(ctx.cwd);
     projectStorage = new MemoryStorage(projectName);
@@ -78,13 +87,14 @@ export default function (pi: ExtensionAPI) {
         "unipi:memory-forget",
         "unipi:global-memory-search",
         "unipi:global-memory-list",
+        "unipi:memory-settings",
       ],
       tools: [
         MEMORY_TOOLS.STORE,
         MEMORY_TOOLS.SEARCH,
         MEMORY_TOOLS.DELETE,
         MEMORY_TOOLS.LIST,
-        MEMORY_TOOLS.GLOBAL_SEARCH,
+        GLOBAL_SEARCH_ALIAS,
         MEMORY_TOOLS.GLOBAL_LIST,
       ],
     });
@@ -146,59 +156,76 @@ export default function (pi: ExtensionAPI) {
       const projectCount = projectStorage.listAll().length;
       const allMemories = listAllProjects();
       const projectCountAll = allMemories.length;
+      const vecReady = isEmbeddingReady();
+      const vecIcon = vecReady ? "⚡" : "📝";
       ctx.ui.setStatus(
         "unipi-memory",
-        `🧠 memory ${projectCount}p/${projectCountAll}all`
+        `${vecIcon} memory ${projectCount}p/${projectCountAll}all${hasModelChanged() ? " ⚠" : ""}`
       );
     }
   });
 
-  // Inject memory titles at session start
+  // Inject memory recall reminder at agent start (hidden message, not system prompt)
   pi.on("before_agent_start", async (event, ctx) => {
+    if (recallDone) return;
     if (!projectStorage) return;
 
     const projectName = getProjectName(ctx.cwd);
     const projectMemories = projectStorage.listAll();
 
     if (projectMemories.length === 0) {
-      return; // No memories to inject
-    }
-
-    let injection = "\n\n<memory>\n";
-    injection += `Available memories for project "${projectName}":\n\n`;
-
-    // Project memories
-    for (const m of projectMemories) {
-      injection += `- ${m.title}\n`;
+      recallDone = true; // Nothing to recall, skip
+      return;
     }
 
-    injection += "\nUse memory_search to retrieve full content. Use memory_store to save new memories.\n";
-    injection += "Use global_memory_search to search across ALL projects.\n";
-    injection += "</memory>";
+    const titleList = projectMemories.slice(0, 20).map(m => `- ${m.title}`).join("\n");
+    const extra = projectMemories.length > 20 ? `\n... and ${projectMemories.length - 20} more` : "";
 
     return {
-      systemPrompt: event.systemPrompt + injection,
+      message: {
+        customType: "unipi-memory-recall-reminder",
+        content: [
+          "## 🧠 Memory System Active",
+          "",
+          `You have ${projectMemories.length} memories stored for project "${projectName}".`,
+          "**BEFORE starting work**, call `memory_search` with relevant keywords to check for existing context.",
+          "",
+          "Available memories:",
+          titleList + extra,
+          "",
+          "**AFTER completing the task**, if you learned something non-obvious,",
+          "call `memory_store` to save it for future sessions.",
+          "",
+          "Guardrails: read max 10 memory results per search. Update existing memories instead of creating duplicates.",
+        ].join("\n"),
+        display: false,
+      },
     };
   });
 
-  // Auto-consolidation on compaction
-  pi.on("session_before_compact", async (event, ctx) => {
-    const { preparation } = event;
-
-    // Extract summary text
-    const summary = preparation.previousSummary || "";
-
-    if (!summary || summary.length < 100) {
-      // Summary too short to extract memories from
-      return;
-    }
-
-    // For now, just log that consolidation would happen
-    // Future: Use LLM to extract memories
-    console.log("[unipi/memory] Auto-consolidation triggered, summary length:", summary.length);
+  // After each agent response, remind LLM to save if it hasn't yet
+  pi.on("agent_end", async (_event, _ctx) => {
+    if (storeDone || !recallDone) return;
+
+    pi.sendMessage(
+      {
+        customType: "unipi-memory-retro-reminder",
+        content: [
+          "**🧠 Memory reminder:** If you learned something non-obvious in this task,",
+          "call `memory_store` to save it as a memory for future sessions.",
+          "Update existing memories instead of creating duplicates.",
+        ].join(" "),
+        display: false,
+      },
+      {
+        deliverAs: "nextTurn",
+      },
+    );
+  });
 
-    // Don't modify the compaction summary - return unchanged
-    return {};
+  // After compaction, reset recall state so reminder re-injects
+  pi.on("session_compact", async (_event, _ctx) => {
+    recallDone = false;
   });
 
   // Cleanup on shutdown

package/packages/memory/skills/memory/SKILL.md

@@ -9,7 +9,6 @@ allowed-tools:
   - memory_search
   - memory_delete
   - memory_list
-  - global_memory_store
   - global_memory_search
   - global_memory_list
   - read
@@ -87,16 +86,18 @@ memory_list()
 memory_delete(title: "auth_jwt_prefer_refresh_tokens")
 ```
 
-## Project vs Cross-Project Search
+## Search Scope
 
-| Action | Scope | Tools |
-|--------|-------|-------|
+`memory_search` searches ALL projects by default. Use `scope` param to narrow:
+
+| Action | Scope | Tool |
+|--------|-------|------|
 | **Store** | Always project-scoped | `memory_store` |
-| **Search this project** | Current project only | `memory_search` |
-| **Search all projects** | Cross-project | `global_memory_search` |
+| **Search all projects** | Cross-project (default) | `memory_search(query)` or `memory_search(query, scope="all")` |
+| **Search this project** | Current project only | `memory_search(query, scope="project")` |
 | **List all** | Cross-project | `global_memory_list` |
 
-**All memories are project-scoped.** When you store a memory, it belongs to the current project. Use `global_memory_search` to search across ALL projects when looking for past work or user preferences.
+**All memories are project-scoped.** When you store a memory, it belongs to the current project. `memory_search` searches everything by default — no need to call a separate global search.
 
 ## Update-First Principle
 
@@ -108,7 +109,27 @@ memory_delete(title: "auth_jwt_prefer_refresh_tokens")
 
 This prevents memory duplication and keeps memory clean.
 
-## Consolidation
+## Vector Search (Embeddings)
+
+Memory supports vector similarity search via OpenRouter API.
+
+### Setup
+1. Run `/unipi:memory-settings`
+2. Add your OpenRouter API key
+3. Select embedding model (default: `openai/text-embedding-3-small`)
+
+### How it works
+- Embeddings are generated when storing/searching memories
+- Search combines **vector similarity** + **fuzzy text matching** for best results
+- Vector search finds semantically similar memories even without exact keyword matches
+
+### Model compatibility
+⚠ **Different embedding models produce incompatible vectors.**
+If you switch models, existing embeddings won't match new searches.
+Use `/unipi:memory-settings` → "Re-embed All Memories" to fix.
+
+### No API key?
+Falls back to fuzzy text-only search. Still works, just less semantic.
 
 When the user runs `/unipi:memory-consolidate` or during compaction:
 
@@ -149,3 +170,4 @@ You can read these files directly with the `read` tool for full context.
 | Use vague titles | Use specific `<category>_<detail>` format |
 | Store in wrong scope | Project-specific = project scope, universal = global |
 | Forget to update | When context changes, update the memory |
+| Switch embedding models without re-embedding | Re-embed or accept fuzzy-only fallback |

package/packages/web-api/README.md

@@ -0,0 +1,179 @@
+# @pi-unipi/web-api
+
+Web search, read, and summarize tools with provider-based backend selection for Pi coding agent.
+
+## Overview
+
+`@pi-unipi/web-api` provides agent tools for web access:
+
+- **web_search** — Search the web using various providers
+- **web_read** — Extract content from URLs
+- **web_llm_summarize** — Summarize web content using LLM
+
+Providers are ranked by capability and cost, allowing smart auto-selection.
+
+## Features
+
+- **Provider-based architecture** — Multiple search/read providers with unified interface
+- **Smart selection** — Auto-select cheapest available provider
+- **API key management** — Interactive TUI for key configuration
+- **Caching** — Web content cached with configurable TTL
+- **Subagent integration** — Tools automatically available to spawned subagents
+
+## Installation
+
+```bash
+npm install @pi-unipi/web-api
+```
+
+Add to your pi configuration:
+
+```json
+{
+  "pi": {
+    "extensions": [
+      "node_modules/@pi-unipi/web-api/src/index.ts"
+    ]
+  }
+}
+```
+
+## Providers
+
+### Search Providers
+
+| Provider | Rank | Cost | API Key |
+|----------|------|------|---------|
+| DuckDuckGo | 1 | Free | No |
+| Jina AI Search | 2 | Freemium | Optional |
+| SerpAPI | 3 | Paid | Required |
+| Tavily | 4 | Paid | Required |
+| Perplexity | 5 | Paid | Required |
+
+### Read Providers
+
+| Provider | Rank | Cost | API Key |
+|----------|------|------|---------|
+| Jina AI Reader | 1 | Freemium | Optional |
+| Firecrawl | 2 | Paid | Required |
+| Perplexity | 3 | Paid | Required |
+
+### Summarize Providers
+
+| Provider | Rank | Cost | API Key |
+|----------|------|------|---------|
+| Perplexity | 1 | Paid | Required |
+| LLM Summarize | 2 | LLM tokens | No |
+
+## Configuration
+
+### API Keys
+
+Configure API keys via the interactive settings command:
+
+```
+/unipi:web-settings
+```
+
+Or set environment variables:
+
+```bash
+export SERPAPI_KEY="your-key"
+export TAVILY_API_KEY="your-key"
+export FIRECRAWL_API_KEY="your-key"
+export PERPLEXITY_API_KEY="your-key"
+export JINA_API_KEY="your-key"
+```
+
+### Settings Files
+
+- **Auth:** `~/.unipi/config/web-api/auth.json` (API keys, gitignored)
+- **Config:** `~/.unipi/config/web-api/config.json` (provider settings)
+
+## Usage
+
+### Web Search
+
+```
+# Auto-select cheapest provider
+web_search(query: "TypeScript generics")
+
+# Use specific provider
+web_search(query: "latest AI research", source: 4)  # Tavily
+```
+
+### Web Read
+
+```
+# Auto-select provider
+web_read(url: "https://example.com/article")
+
+# Use specific provider
+web_read(url: "https://example.com/spa", source: 2)  # Firecrawl
+```
+
+### Web Summarize
+
+```
+# Auto-summarize
+web_llm_summarize(url: "https://example.com/long-article")
+
+# Custom prompt
+web_llm_summarize(url: "https://example.com/research", prompt: "Extract key findings")
+```
+
+## Commands
+
+### /unipi:web-settings
+
+Interactive settings dialog for managing providers and API keys.
+
+### /unipi:web-cache-clear
+
+Clear all cached web content.
+
+## Cache
+
+- Default TTL: 1 hour
+- Cache location: `~/.unipi/config/web-api/cache/`
+- Automatic for web_read operations
+
+## Troubleshooting
+
+### No provider available
+
+If you see "No search provider available":
+
+1. Run `/unipi:web-settings`
+2. Enable at least one provider
+3. Add API keys for paid providers
+
+### API key invalid
+
+If API key validation fails:
+
+1. Check the key is correct
+2. Verify the key has sufficient permissions
+3. Check provider status at their website
+
+### Rate limiting
+
+If you hit rate limits:
+
+1. Add an API key for higher limits
+2. Use a different provider
+3. Wait and retry
+
+## Development
+
+```bash
+# Type check
+npm run typecheck
+
+# Build
+npm run build
+```
+
+## License
+
+MIT

package/packages/web-api/skills/web/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: web
+description: "Web search, read, and summarize tools with provider-based backend"
+---
+
+# Web Tools
+
+Use these tools to access web content. Providers are ranked by capability and cost.
+
+## web_search
+
+Search the web for information. Lower `source` = simpler/cheaper providers.
+
+- **Quick facts:** source 1-2 (DuckDuckGo, Jina Search)
+- **Research:** source 3-5 (SerpAPI, Tavily, Perplexity)
+
+**Parameters:**
+- `query` (required): Search query string
+- `source` (optional): Provider selection (1-5)
+
+**Examples:**
+```
+web_search(query: "TypeScript generics tutorial")
+web_search(query: "latest AI research", source: 4)  # Use Tavily
+```
+
+## web_read
+
+Read URL content. Lower `source` = simpler providers.
+
+- **Basic extraction:** source 1 (Jina Reader)
+- **Advanced crawling:** source 2 (Firecrawl)
+
+**Parameters:**
+- `url` (required): URL to read
+- `source` (optional): Provider selection (1-3)
+
+**Examples:**
+```
+web_read(url: "https://example.com/article")
+web_read(url: "https://example.com/spa", source: 2)  # Use Firecrawl
+```
+
+## web_llm_summarize
+
+Summarize URL with LLM. Higher cost (LLM tokens + provider).
+
+- Use for complex content that needs analysis
+- Custom prompts supported for targeted summaries
+
+**Parameters:**
+- `url` (required): URL to summarize
+- `prompt` (optional): Custom summarization prompt
+- `source` (optional): Provider selection for content fetch (1-3)
+
+**Examples:**
+```
+web_llm_summarize(url: "https://example.com/long-article")
+web_llm_summarize(url: "https://example.com/research", prompt: "Extract key findings")
+```
+
+## Provider Selection
+
+- Omit `source` for auto-selection (cheapest available)
+- Specify `source` number for specific provider
+- If provider unavailable, tool throws descriptive error
+
+### Provider Rankings
+
+**Search providers:**
+1. DuckDuckGo (free)
+2. Jina AI Search (freemium)
+3. SerpAPI (paid)
+4. Tavily (paid)
+5. Perplexity (paid)
+
+**Read providers:**
+1. Jina AI Reader (freemium)
+2. Firecrawl (paid)
+3. Perplexity (paid)
+
+**Summarize providers:**
+1. Perplexity (paid)
+2. LLM Summarize (uses pi's LLM)
+
+## Cost Awareness
+
+- **DuckDuckGo:** Free (search only)
+- **Jina:** Freemium (search + read)
+- **SerpAPI/Tavily:** Paid (search)
+- **Firecrawl:** Paid (read)
+- **Perplexity:** Paid (search + summarize)
+- **LLM Summarize:** LLM token cost
+
+## Configuration
+
+Configure providers via `/unipi:web-settings` command.
+
+- Add/remove API keys
+- Enable/disable providers
+- View provider status
+
+## Cache
+
+Web content is cached for 1 hour by default.
+
+- Clear cache: `/unipi:web-cache-clear`
+- Cache is automatic for web_read operations

package/packages/workflow/index.ts

@@ -86,7 +86,16 @@ export default function (pi: ExtensionAPI) {
         systemPrompt:
           event.systemPrompt +
           base +
-          `\nThe write tool is available but restricted to .unipi/docs/specs/ only.\nDo NOT attempt to call blocked tools. Do NOT output tool call XML for them.\nIf the user requests an action that requires a blocked tool, respond that you do not have access.\n</sandbox>`,
+          `\nThe write tool is available but restricted to .unipi/docs/specs/ only.\nbash is available ONLY for specific setup use case (e.g., git init, mkdir). Do NOT use bash for reading files or listing directories — use grep, find, ls instead.\nDo NOT attempt to call blocked tools. Do NOT output tool call XML for them.\nIf the user requests an action that requires a blocked tool, respond that you do not have access.\n</sandbox>`,
+      };
+    }
+
+    if (currentSandboxLevel === "write_unipi") {
+      return {
+        systemPrompt:
+          event.systemPrompt +
+          base +
+          `\nWrite tool is restricted to .unipi/docs/ only (specs and plans).\nUse grep, find, ls for file discovery — do NOT guess filenames.\nbash is blocked — use read, write, edit, grep, find, ls only.\nDo NOT attempt to call blocked tools. Do NOT output tool call XML for them.\nIf the user requests an action that requires a blocked tool, respond that you do not have access.\n</sandbox>`,
       };
     }
 
@@ -94,7 +103,7 @@ export default function (pi: ExtensionAPI) {
       systemPrompt:
         event.systemPrompt +
         base +
-        `\nDo NOT attempt to call blocked tools. Do NOT output tool call XML for them.\nIf the user requests an action that requires a blocked tool, respond that you do not have access.\n</sandbox>`,
+        `\nDo NOT attempt to call blocked tools. Do NOT output tool call XML for them.\nIf the user requires an action that requires a blocked tool, respond that you do not have access.\n</sandbox>`,
     };
   });
 

package/packages/workflow/skills/brainstorm/SKILL.md

@@ -145,6 +145,7 @@ The `## Implementation Checklist` section uses `- [ ]` markdown checkboxes. Thes
 
 - **`[ ]` = unplanned** — not yet covered by a plan
 - **`[x]` = planned** — marked when `/unipi:plan` covers this item
+- **`[x]` does NOT mean done** — implementation progress is tracked in the plan file (`unstarted:` / `in-progress:` / `completed:`)
 - Agent MUST fill in checklist items based on the design
 - Each item should be a discrete, implementable task
 - Items should be ordered by dependency (earlier items don't depend on later ones)

package/packages/workflow/skills/plan/SKILL.md

@@ -70,6 +70,7 @@ Structure the plan with heart of gold style:
 title: "{Topic} — Implementation Plan"
 type: plan
 date: YYYY-MM-DD
+workbranch: {branch-name or empty if on main}
 specs:
   - path/to/spec.md
 ---
@@ -81,16 +82,19 @@ specs:
 
 ## Tasks
 
-### Task 1: {Task Name}
-**Description:** {What needs to be done}
-**Dependencies:** {None, or list of tasks}
-**Acceptance Criteria:** {How to verify done}
-**Steps:**
-1. {Concrete step}
-2. {Concrete step}
+- unstarted: Task 1 — {Task Name}
+  - Description: {What needs to be done}
+  - Dependencies: {None, or list of tasks}
+  - Acceptance Criteria: {How to verify done}
+  - Steps:
+    1. {Concrete step}
+    2. {Concrete step}
 
-### Task 2: {Task Name}
-...
+- unstarted: Task 2 — {Task Name}
+  - Description: ...
+  - Dependencies: ...
+  - Acceptance Criteria: ...
+  - Steps: ...
 
 ## Sequencing
 {Order of execution, dependency graph if complex}
@@ -107,6 +111,20 @@ specs:
 - **Steps** are bite-sized — agent can follow without guessing
 - Order tasks by dependency (foundational work first)
 
+### Task Status Lifecycle
+
+Tasks use prefixes to track progress:
+
+| Status | Meaning |
+|--------|----------|
+| `unstarted:` | Not started |
+| `in-progress:` | Being worked on |
+| `completed:` | Done and verified |
+| `failed:` | Attempted but failed, needs investigation |
+| `awaiting_user:` | Needs user action (test, approve, provide input) |
+| `blocked:` | Waiting on dependency or external factor |
+| `skipped:` | Intentionally not doing (deferred, out of scope) |
+
 ---
 
 ## Phase 4: Update Brainstorm Checkboxes
@@ -129,6 +147,8 @@ After plan is complete:
 
 This creates the link between brainstorm and plan — plan covers some items, others remain for future plans.
 
+**Semantics:** Spec `[x]` means "planned" (covered by a plan). It does NOT mean "done". Implementation progress is tracked in the plan file, not the spec.
+
 ---
 
 ## Phase 5: Review Plan
@@ -138,10 +158,11 @@ Self-check before presenting:
 - [ ] Every task has clear acceptance criteria
 - [ ] Dependencies are correct (no circular, no missing)
 - [ ] Steps are bite-sized (agent can follow without guessing)
-- [ ] Brainstorm checkboxes updated correctly
 - [ ] String greedy scope respected (if provided)
 - [ ] Plan is focused enough for single `/unipi:work` session
 
+Do NOT re-read or re-edit the spec checkboxes — Phase 4 already wrote them.
+
 ---
 
 ## Phase 6: Present & Handoff
@@ -164,6 +185,5 @@ Recommend starting a **new session** for work — it will switch pi's internal w
 ## Resumability
 
 If user runs `/unipi:plan` on an existing plan:
-1. Read the plan
-2. Check what's already marked done
-3. Ask user if they want to add tasks, modify existing, or plan new scope
+1. Read the plan — look for `completed:` tasks
+2. Ask user if they want to add tasks, modify existing, or plan new scope

package/packages/workflow/skills/review-work/SKILL.md

@@ -25,13 +25,17 @@ Review what was built, verify task completion, run codebase checks, add reviewer
 
 ---
 
-## Phase 1: Load Plan
+## Phase 1: Load Plan & Switch Branch
 
 1. If `plan:` arg provided, read that plan
 2. If not, list plans in `.unipi/docs/plans/` and ask user
 3. Read plan fully — understand tasks, acceptance criteria, current status
+4. **Read `workbranch:` from plan frontmatter:**
+   - If `workbranch:` exists and is not empty → switch to that branch/worktree
+   - If `workbranch:` missing or empty → review on current branch (main)
+   - To switch: `git checkout {workbranch}` or use worktree path
 
-**Exit:** Plan loaded. Know what to review.
+**Exit:** On correct branch. Plan loaded.
 
 ---
 
@@ -42,9 +46,13 @@ For each task in plan:
 1. Read acceptance criteria
 2. Verify against actual implementation
 3. Determine status:
-   - **Done** — all criteria met
+   - **Done** — all criteria met → `completed:`
    - **Partially Done X/Y** — some steps complete, others not
-   - **Unstarted** — nothing done
+   - **Unstarted** — nothing done → `unstarted:`
+   - **Failed** — attempted but broken → `failed:`
+   - **Awaiting User** — needs user action → `awaiting_user:`
+   - **Blocked** — waiting on dependency → `blocked:`
+   - **Skipped** — intentionally not done → `skipped:`
 
 If `string(greedy)` scope provided, only check matching tasks.
 

package/packages/workflow/skills/work/SKILL.md

@@ -39,6 +39,7 @@ If args not provided, ask user interactively:
    - "Do you want to work on current branch or create a worktree?"
    - If worktree: "What branch name?" (suggest based on spec topic)
    - Create worktree if not exists
+   - **After creating/confirming worktree:** write `workbranch: {branch-name}` to the plan file frontmatter
 
 2. **Specs:**
    - List available plans in `.unipi/docs/plans/`
@@ -58,7 +59,7 @@ If args not provided, ask user interactively:
 1. Read plan file(s)
 2. Review critically — identify questions or concerns
 3. If concerns: raise with user before starting
-4. Identify which tasks are already `[x]` (done) vs `[ ]` (pending)
+4. Identify task status: `unstarted:` (pending), `in-progress:` (started), `completed:` (done), `failed:` (needs investigation), `awaiting_user:` (needs user action), `blocked:` (waiting on dependency), `skipped:` (deferred)
 
 **Exit:** Plan reviewed, ready to execute.
 
@@ -66,14 +67,36 @@ If args not provided, ask user interactively:
 
 ## Phase 3: Execute Tasks
 
-For each task in order:
+For each task in order, skip `completed:`, `skipped:`, and `awaiting_user:` tasks:
 
-1. Mark task as `in_progress` in plan
+### If `unstarted:`
+1. Change `unstarted:` to `in-progress:` in plan
 2. Follow each step exactly (plan has bite-sized steps)
 3. Run verifications as specified in acceptance criteria
-4. Mark as `[x]` when complete
+4. Change `in-progress:` to `completed:` when complete
 5. Update plan file with progress
 
+### If `in-progress:`
+1. Continue from where it left off
+2. Follow remaining steps
+3. Change to `completed:` when done
+
+### If `failed:`
+1. Read failure notes
+2. Investigate root cause
+3. Fix and re-verify
+4. Change to `completed:` when fixed, or keep `failed:` if still broken
+
+### If `awaiting_user:`
+1. Remind user what's needed
+2. Wait for user response
+3. Resume when user provides input
+
+### If `blocked:`
+1. Check if blocker is resolved
+2. If resolved → change to `unstarted:` and continue
+3. If still blocked → skip and move to next task
+
 ### When to Stop and Ask
 
 **STOP immediately when:**
@@ -107,12 +130,11 @@ Don't wait until end to commit — incremental commits are safer.
 
 ## Phase 5: Complete
 
-When all tasks marked `[x]`:
+When all tasks are `completed:`:
 
 1. Run final verification (tests, lint, build)
 2. Commit all remaining changes
-3. Update plan with completion status
-4. Inform user:
+3. Inform user:
 
 > "All tasks complete. Worktree: `feat/<branch>`. Recommend reviewing before merge."
 
@@ -127,9 +149,9 @@ Suggest next step:
 
 ## Resumability
 
-If user runs `/unipi:work` and plan has partial `[x]` marks:
+If user runs `/unipi:work` and plan has `completed:` or `in-progress:` tasks:
 1. Read plan
-2. Identify first `[ ]` task
+2. Identify first `unstarted:` task
 3. Ask user: "Resume from Task N: {name}?"
 4. Continue from there
 

package/packages/workflow/skills/worktree-list/SKILL.md

@@ -9,8 +9,8 @@ List all git worktrees created by unipi.
 
 ## Boundaries
 
-**This skill MAY:** run git worktree commands, read filesystem.
-**This skill MAY NOT:** edit anything, create worktrees, merge branches.
+**This skill MAY:** read filesystem (ls, read), grep for git info.
+**This skill MAY NOT:** edit anything, create worktrees, merge branches, run bash.
 
 ## Command Format
 
@@ -24,17 +24,27 @@ No arguments. Lists all unipi worktrees.
 
 ## Process
 
-### Phase 1: Gather Worktrees
+### Phase 1: Discover Worktrees
 
-1. Run `git worktree list --porcelain`
-2. Filter for worktrees under `.unipi/worktrees/`
-3. For each worktree, collect:
-   - Branch name
-   - Path
-   - HEAD commit
-   - Whether it has uncommitted changes
+1. `ls .unipi/worktrees/` — list worktree directories
+2. For each directory:
+   - Read `.unipi/worktrees/<branch>/.git` file to get gitdir path
+   - Check for uncommitted changes: `ls .unipi/worktrees/<branch>/` and read key files
+3. If `.unipi/worktrees/` doesn't exist or is empty → no worktrees
 
-### Phase 2: Present
+**Exit:** List of worktrees discovered.
+
+### Phase 2: Determine Status
+
+For each worktree directory:
+
+1. Check if `HEAD` file exists in gitdir
+2. Check for modified files by reading directory listing
+3. Determine status:
+   - **clean** — no uncommitted changes
+   - **dirty** — has uncommitted changes
+
+### Phase 3: Present
 
 Display in table format:
 
@@ -51,7 +61,7 @@ Worktrees:
 If no worktrees:
 > "No unipi worktrees. Create one with `/unipi:worktree-create`"
 
-### Phase 3: Suggest Actions
+### Phase 4: Suggest Actions
 
 Based on state:
 - If dirty worktrees exist → suggest reviewing or committing
@@ -65,3 +75,4 @@ Based on state:
 - Only shows worktrees under `.unipi/worktrees/`
 - Ignores worktrees in other locations
 - Status: `clean` = no uncommitted changes, `dirty` = has changes
+- No bash required — uses ls, read, grep for all discovery

package/packages/workflow/skills/worktree-merge/SKILL.md

@@ -46,8 +46,16 @@ For each source branch (in dependency order if specs indicate ordering):
 3. **If conflict:**
    - Report which files conflict
    - Reference the spec/plan context: "This branch was working on: <description>"
-   - Ask user how to resolve (do NOT force merge)
-   - Skip to next branch if user says so
+   - **Structured conflict resolution:**
+     1. **Check finalized plan** — read the plan for this branch, understand intended changes
+     2. **Brainstorm resolution** — reason about which changes align with the plan's intent
+     3. **Read codebase** — read the conflicting files to understand current state
+     4. **Ask user** — present options and ask for final decision (always ask, never force)
+   - Options to present:
+     - Accept incoming (their changes)
+     - Accept current (main branch)
+     - Manual merge (describe what each side does, ask user to decide)
+     - Skip this branch
 4. **If success:**
    - Remove worktree: `git worktree remove .unipi/worktrees/<branch-name>`
    - Delete branch: `git branch -d <branch>`