@pi-unipi/workflow 0.1.6 → 0.1.8

package/commands.ts

@@ -192,6 +192,13 @@ const COMMANDS: WorkflowCommand[] = [
     skillName: "scan-issues",
     argumentHint: "<scope>",
   },
+  {
+    name: WORKFLOW_COMMANDS.AUTO,
+    description:
+      "Full pipeline — brainstorm → plan → work → review → merge",
+    skillName: "auto",
+    argumentHint: "<description> plan:<file> specs:<file>",
+  },
 ];
 
 /**
@@ -207,29 +214,41 @@ export function registerWorkflowCommands(
     pi.registerCommand(fullCommand, {
       description: cmd.description,
       getArgumentCompletions: (prefix: string) => {
+        let items: { value: string; label: string; description: string }[] | null = null;
+
         // Plan command: suggest spec files
         if (cmd.name === WORKFLOW_COMMANDS.PLAN) {
-          return suggestSpecFiles(prefix);
+          items = suggestSpecFiles(prefix);
         }
 
         // Work command: suggest plan files
         if (cmd.name === WORKFLOW_COMMANDS.WORK) {
-          return suggestPlanFiles(prefix);
+          items = suggestPlanFiles(prefix);
         }
 
         // Review-work command: suggest plan files
         if (cmd.name === WORKFLOW_COMMANDS.REVIEW_WORK) {
-          return suggestPlanFiles(prefix);
+          items = suggestPlanFiles(prefix);
         }
 
         // Worktree merge: suggest existing worktrees
         if (cmd.name === WORKFLOW_COMMANDS.WORKTREE_MERGE) {
-          return suggestWorktrees();
+          items = suggestWorktrees();
         }
 
         // Worktree create: suggest existing worktrees as reference
         if (cmd.name === WORKFLOW_COMMANDS.WORKTREE_CREATE) {
-          return suggestWorktrees();
+          items = suggestWorktrees();
+        }
+
+        // Auto command: suggest plan files
+        if (cmd.name === WORKFLOW_COMMANDS.AUTO) {
+          items = suggestPlanFiles(prefix);
+        }
+
+        // Defensive: filter out any items with non-string value
+        if (items) {
+          return items.filter((item) => typeof item.value === "string");
         }
 
         // Other commands: no dynamic completions (free-text args)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/workflow",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Structured development workflow commands for Pi coding agent",
   "type": "module",
   "license": "MIT",
@@ -33,7 +33,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "^0.1.0"
+    "@pi-unipi/core": "^0.1.6"
   },
   "peerDependencies": {
     "@mariozechner/pi-ai": "*",

package/skills/auto/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: auto
+description: "Full pipeline — brainstorm → plan → work → review → merge. One command, end to end."
+---
+
+# Auto Pipeline
+
+Run the complete development pipeline from idea to merged code.
+
+## Command Format
+
+```
+/unipi:auto <description>(optional) plan:<path>(optional) specs:<path>(optional)
+```
+
+- `description` — what to build (triggers brainstorm first)
+- `plan:<path>` — existing plan to execute (skips brainstorm + plan, starts at work)
+- `specs:<path>` — existing spec to plan from (skips brainstorm, starts at plan)
+- No args → ask user what to do
+
+## Pipeline Stages
+
+```
+brainstorm → plan → work → review → merge
+```
+
+Each stage hands off to the next automatically. User can intervene at any gate.
+
+---
+
+## Phase 1: Determine Entry Point
+
+Based on args:
+
+**If `description` provided (no plan/specs):**
+→ Start at brainstorm. Full pipeline.
+
+**If `specs:<path>` provided (no plan):**
+→ Start at plan. Skip brainstorm.
+
+**If `plan:<path>` provided:**
+→ Start at work. Skip brainstorm + plan.
+
+**If no args:**
+→ Ask user:
+1. "What do you want to build?" → brainstorm
+2. "I have a spec, plan from it" → provide spec path
+3. "I have a plan, execute it" → provide plan path
+4. "I have a plan, just review + merge" → provide plan path
+
+**Exit:** Entry point determined. Pipeline scope clear.
+
+---
+
+## Phase 2: Brainstorm (if needed)
+
+1. Load brainstorm skill content
+2. Run full brainstorm flow — explore, question, design, write spec
+3. Wait for user approval at design gate
+4. On approval → proceed to plan
+
+**Gate:** User must approve design before continuing.
+
+---
+
+## Phase 3: Plan (if needed)
+
+1. Load plan skill content
+2. Create implementation plan from spec
+3. Present plan to user
+4. On approval → proceed to work
+
+**Gate:** User must approve plan before continuing.
+
+---
+
+## Phase 4: Work (if needed)
+
+1. Read `workbranch` from plan frontmatter
+2. If `workbranch` non-empty → create worktree, work within it
+3. If `workbranch` empty → work directly on main branch
+4. Load work skill content
+5. Execute all tasks in the plan
+6. Commit incrementally
+7. On completion → proceed to review
+
+**Gate:** All tasks must complete. If blocked → stop and ask.
+
+---
+
+## Phase 5: Review
+
+1. Load review-work skill content
+2. Read `workbranch` from plan — switch to branch if set, else review on main
+3. Check task completion against acceptance criteria
+4. Run codebase checks (lint, type check, test, build)
+5. Write reviewer remarks to plan
+
+**If review passes:** → proceed to merge (or skip if on main)
+**If review fails:** → go back to work (Phase 4) with failure context
+
+**Gate:** All checks must pass. Reviewer remarks must say Done.
+
+---
+
+## Phase 6: Merge (if worktree)
+
+If `workbranch` was set (worktree):
+1. Load worktree-merge skill content
+2. Merge worktree branch back to main
+3. Clean up worktree and branch
+4. Run final verification on main
+
+If `workbranch` was empty (main branch):
+→ Skip merge — changes already on main.
+
+**Exit:** Code on main. Worktree cleaned (if applicable).
+
+---
+
+## Phase 7: Summary
+
+Report pipeline results:
+
+```
+Pipeline Complete: {topic}
+
+✓ Brainstorm — {spec-path}
+✓ Plan — {plan-path}
+✓ Work — {N} tasks completed on {branch or "main"}
+✓ Review — all checks passed
+✓ Merge — {merged to main, worktree cleaned or "already on main"}
+
+Artifacts:
+- Spec: .unipi/docs/specs/{spec}
+- Plan: .unipi/docs/plans/{plan}
+```
+
+Suggest next steps:
+- `/unipi:consolidate` — save learnings
+- `/unipi:scan-issues` — deeper code review
+- `/unipi:document` — generate docs
+
+---
+
+## Interruption Handling
+
+If any phase fails or user interrupts:
+
+1. Record current phase and progress
+2. Suggest resuming from the failed phase
+3. Don't lose context — spec/plan/progress preserved
+
+Example:
+> "Pipeline paused at review phase. 3/5 tasks complete, tests failing.
+> Resume with: `/unipi:auto plan:<plan-path>`"
+
+---
+
+## Notes
+
+- Each phase loads its skill content dynamically
+- Gates between phases ensure user oversight
+- Pipeline is resumable — can restart from any phase
+- Worktree isolation protects main branch (skipped for small tasks — work directly on main)
+- Auto command has `full` sandbox — all tools available

package/skills/plan/SKILL.md

@@ -56,8 +56,20 @@ Committed to current branch.
 2. If concerns: raise with user before proceeding
 3. If `string(greedy)` provided: use it to scope planning (e.g., "focus on auth only")
 4. Ask clarifying questions if needed (one at a time)
+5. **Ask about work branch:**
 
-**Exit:** No blockers. Ready to plan.
+> "Where should this work happen?"
+>
+> 1. **Main branch** — work directly on main (small/medium tasks, low risk)
+> 2. **New branch** — isolated worktree (larger tasks, risky changes)
+>
+> If "New branch": "What branch name? (e.g., `feat/auth`, or press enter for auto-naming based on spec topic)"
+
+Record the decision:
+- Main branch → `workbranch:` will be empty in plan frontmatter
+- New branch → `workbranch: {branch-name}` in plan frontmatter (auto-generate `feat/{topic}` if not provided)
+
+**Exit:** No blockers. Branch strategy decided. Ready to plan.
 
 ---
 
@@ -70,7 +82,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}
+workbranch: {branch-name}   # empty string = work on main branch
 specs:
   - path/to/spec.md
 ---
@@ -111,6 +123,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
@@ -156,15 +182,19 @@ Do NOT re-read or re-edit the spec checkboxes — Phase 4 already wrote them.
 Present plan summary to user. Then ask:
 
 1. **Proceed to /unipi:work** — Start implementing in a worktree
-2. **Revise plan** — Adjust tasks or scope
-3. **Done for now** — Return later
+2. **Proceed to /unipi:auto** — Run full pipeline (work → review → merge)
+3. **Revise plan** — Adjust tasks or scope
+4. **Done for now** — Return later
 
-If user selects "Proceed to /unipi:work", suggest:
-```
-/unipi:work worktree:feat/<branch-name> specs:YYYY-MM-DD-<topic>-plan
-```
+If user selects "Proceed to /unipi:work":
+- **Worktree branch** → suggest: `/unipi:work worktree:<branch-name> specs:YYYY-MM-DD-<topic>-plan`
+- **Main branch** → suggest: `/unipi:work specs:YYYY-MM-DD-<topic>-plan` (no worktree arg)
+
+If user selects "Proceed to /unipi:auto":
+- **Worktree branch** → suggest: `/unipi:auto plan:YYYY-MM-DD-<topic>-plan.md`
+- **Main branch** → suggest: `/unipi:auto plan:YYYY-MM-DD-<topic>-plan.md` (same — auto reads workbranch from plan)
 
-Recommend starting a **new session** for work — it will switch pi's internal worktree.
+Recommend starting a **new session** for work if using a worktree.
 
 ---
 

package/skills/review-work/SKILL.md

@@ -9,7 +9,7 @@ Review what was built, verify task completion, run codebase checks, add reviewer
 
 ## Boundaries
 
-**This skill MAY:** read codebase, run checks (lint, build, test, docker), write reviewer remarks to plan docs.
+**This skill MAY:** read codebase, run checks (lint, build, test, docker), write reviewer remarks to plan docs, run bash for git operations (checkout worktree branch).
 **This skill MAY NOT:** edit code, implement features, create new files.
 
 ## Command Format
@@ -46,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.
 
@@ -108,17 +112,37 @@ Followed by description explaining the status.
 Based on review results:
 
 **If all tasks done and checks pass:**
-> "All tasks complete and verified. Ready to consolidate."
+
+*If `workbranch` is set (worktree):*
+> "All tasks complete and verified. Ready to merge back to main."
+```
+/unipi:worktree-merge
+```
+
+*If `workbranch` is empty (main branch):*
+> "All tasks complete and verified. Changes already on main — no merge needed."
+```
+/unipi:consolidate
+```
+
+Either way, user can consolidate learnings:
 ```
 /unipi:consolidate
 ```
 
 **If tasks incomplete or checks fail:**
 > "Tasks remaining and/or checks failing. Continue work?"
+
+*If `workbranch` is set:*
 ```
 /unipi:work worktree:<branch> specs:<plan-path>
 ```
 
+*If `workbranch` is empty (main):*
+```
+/unipi:work specs:<plan-path>
+```
+
 **If scoped review complete:**
 > "Scoped review complete. Run full review or continue work?"
 ```

package/skills/work/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: work
-description: "Execute plan — implement in worktree, test, commit on done. Resumable across sessions."
+description: "Execute plan — implement tasks, test, commit on done. Works in worktree or on main branch. Resumable."
 ---
 
 # Executing Plans
@@ -9,8 +9,12 @@ Load plan, review critically, execute tasks, commit when complete.
 
 ## Boundaries
 
-**This skill MAY:** read/write code in worktree, read/write `.unipi/docs/`, run tests, commit, create worktree.
-**This skill MAY NOT:** modify files outside worktree, merge branches, deploy.
+**This skill MAY:** read/write code, read/write `.unipi/docs/`, run tests, commit, create worktree.
+**This skill MAY NOT:** merge branches, deploy.
+
+**Worktree vs Main:**
+- If `workbranch` in plan → work within worktree directory
+- If `workbranch` empty → work directly on main branch (current directory)
 
 ## Command Format
 
@@ -25,32 +29,36 @@ Load plan, review critically, execute tasks, commit when complete.
 
 ## Sandbox
 
-- **Read/Write:** full access within worktree directory
+- **Read/Write:** full access within worktree (or project root if on main)
 - **Write:** `.unipi/docs/` for progress tracking
-- **Cannot:** modify files outside worktree
 
 ---
 
 ## Phase 1: Resolve Args
 
-If args not provided, ask user interactively:
-
-1. **Worktree:**
-   - "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/`
-   - "Which plan(s) to execute?"
+1. **Specs:**
+   - If `specs:` arg provided, read those plan files
+   - If not, list available plans in `.unipi/docs/plans/` and ask user
    - Can select multiple
 
+2. **Read `workbranch` from plan frontmatter:**
+   - If `workbranch:` is **non-empty** → use that branch/worktree
+     - If worktree arg also provided → use worktree arg (override)
+     - Create worktree if not exists: `git worktree add .unipi/worktrees/{branch} -b {branch}`
+     - Work within worktree directory
+   - If `workbranch:` is **empty or missing** → work on current branch (main)
+     - No worktree creation needed
+     - Edit files directly in project root
+   - If neither plan nor args specify branch → ask user:
+     > "Where should this work happen?"
+     > 1. Current branch (main)
+     > 2. New worktree (provide branch name)
+
 3. **Scope:**
    - If `string(greedy)` provided, use to scope tasks
    - Otherwise execute all incomplete tasks
 
-**Exit:** Worktree set, plan(s) loaded, scope defined.
+**Exit:** Branch/worktree resolved. Plan(s) loaded. Scope defined.
 
 ---
 
@@ -59,7 +67,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 task status: `unstarted:` (pending), `in-progress:` (started), `completed:` (done)
+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.
 
@@ -67,14 +75,36 @@ If args not provided, ask user interactively:
 
 ## Phase 3: Execute Tasks
 
-For each `unstarted:` task in order:
+For each task in order, skip `completed:`, `skipped:`, and `awaiting_user:` tasks:
 
+### 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. 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:**
@@ -112,17 +142,22 @@ When all tasks are `completed:`:
 
 1. Run final verification (tests, lint, build)
 2. Commit all remaining changes
-3. Inform user:
-
-> "All tasks complete. Worktree: `feat/<branch>`. Recommend reviewing before merge."
+3. Inform user based on branch strategy:
 
-Suggest next step:
+**If working in worktree:**
+> "All tasks complete. Worktree: `{branch}`. Recommend reviewing before merge."
 ```
 /unipi:review-work plan:<plan-path>
 ```
-
 **Recommend starting a new session** for review.
 
+**If working on main branch:**
+> "All tasks complete. All changes committed directly on main."
+```
+/unipi:review-work plan:<plan-path>
+```
+No merge needed — changes already on main.
+
 ---
 
 ## Resumability
@@ -139,6 +174,7 @@ If user provides scope string, only execute matching tasks.
 
 ## Notes
 
-- Agent reads plan regardlessly on start — finds what's incomplete
-- Worktree isolation: changes don't affect main branch until merge
+- Agent reads plan on start — finds what's incomplete
+- Worktree: changes don't affect main branch until merge (skip for small tasks)
+- Main branch: changes committed directly, no merge needed
 - Each worktree session is independent — no coordination with other worktrees

package/skills/worktree-merge/SKILL.md

@@ -7,6 +7,8 @@ description: "Merge worktree branches back to main. Gathers context from specs/p
 
 Merge completed worktree branches into main. Gather context from docs before merging.
 
+**Note:** Only needed when work was done in a worktree (plan `workbranch` set). If work was on main branch directly, skip this — changes already on main.
+
 ## Process
 
 ### Phase 1: Gather Context