@pi-unipi/workflow 0.1.0

package/skills/work/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: work
+description: "Execute plan — implement in worktree, test, commit on done. Resumable across sessions."
+---
+
+# Executing Plans
+
+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.
+
+## Command Format
+
+```
+/unipi:work worktree:<branch>(optional) specs:<path>(multiple,optional) <string(greedy)>(optional)
+```
+
+- `worktree:<branch>` — branch to work on (auto-suggested, agent asks if not provided)
+- `specs:<path>` — plan(s) to execute (auto-suggested, agent asks if not provided)
+- `string(greedy)` — scope guidance (e.g., "only task 1 and 2")
+- **Recommended: new session** — this command switches pi's internal worktree
+
+## Sandbox
+
+- **Read/Write:** full access within worktree directory
+- **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
+
+2. **Specs:**
+   - List available plans in `.unipi/docs/plans/`
+   - "Which plan(s) to execute?"
+   - Can select multiple
+
+3. **Scope:**
+   - If `string(greedy)` provided, use to scope tasks
+   - Otherwise execute all incomplete tasks
+
+**Exit:** Worktree set, plan(s) loaded, scope defined.
+
+---
+
+## Phase 2: Review Plan
+
+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)
+
+**Exit:** Plan reviewed, ready to execute.
+
+---
+
+## Phase 3: Execute Tasks
+
+For each task in order:
+
+1. Mark task as `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
+5. Update plan file with progress
+
+### When to Stop and Ask
+
+**STOP immediately when:**
+- Hit blocker (missing dependency, test fails, instruction unclear)
+- Plan has critical gaps
+- You don't understand an instruction
+- Verification fails repeatedly
+
+Ask for clarification rather than guessing.
+
+### When to Revisit Earlier Steps
+
+**Return to review when:**
+- Partner updates plan based on feedback
+- Fundamental approach needs rethinking
+
+Don't force through blockers — stop and ask.
+
+---
+
+## Phase 4: Commit Progress
+
+After each task or group of tasks:
+1. Stage changes
+2. Commit with descriptive message referencing task name
+3. Continue to next task
+
+Don't wait until end to commit — incremental commits are safer.
+
+---
+
+## Phase 5: Complete
+
+When all tasks marked `[x]`:
+
+1. Run final verification (tests, lint, build)
+2. Commit all remaining changes
+3. Update plan with completion status
+4. Inform user:
+
+> "All tasks complete. Worktree: `feat/<branch>`. Recommend reviewing before merge."
+
+Suggest next step:
+```
+/unipi:review-work plan:<plan-path>
+```
+
+**Recommend starting a new session** for review.
+
+---
+
+## Resumability
+
+If user runs `/unipi:work` and plan has partial `[x]` marks:
+1. Read plan
+2. Identify first `[ ]` task
+3. Ask user: "Resume from Task N: {name}?"
+4. Continue from there
+
+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
+- Each worktree session is independent — no coordination with other worktrees

package/skills/worktree-create/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: worktree-create
+description: "Create git worktree for parallel work. Agent-driven naming."
+---
+
+# Creating Worktrees
+
+Create a git worktree for isolated parallel work.
+
+## Boundaries
+
+**This skill MAY:** run git worktree commands, ask user for branch name, suggest names.
+**This skill MAY NOT:** edit code, run tests, implement features.
+
+## Command Format
+
+```
+/unipi:worktree-create <string(greedy)>
+```
+
+- `string(greedy)` — description or desired branch name
+- Agent asks user for exact name or suggests based on description
+
+---
+
+## Process
+
+### Phase 1: Parse Input
+
+1. Read the string input
+2. Assess if it's a branch name or a description:
+   - Branch name: `feat/auth`, `fix/login-bug` → use directly
+   - Description: "add user authentication" → suggest name
+
+### Phase 2: Name Resolution
+
+**If clear branch name:**
+> "Creating worktree on branch `feat/auth`. Confirm?"
+
+**If description:**
+> "Based on your description, I suggest: `feat/user-auth`. What name would you like?"
+
+Let user confirm or provide different name.
+
+### Phase 3: Create Worktree
+
+1. Check if branch already exists (local or remote)
+2. If exists: ask user if they want to reuse or create new
+3. Create worktree:
+   ```bash
+   git worktree add .unipi/worktrees/<branch> -b <branch>
+   ```
+4. Verify creation succeeded
+
+### Phase 4: Confirm
+
+Report:
+> "Worktree created: `.unipi/worktrees/<branch>` (branch: `<branch>`)"
+> "To work in this worktree: `/unipi:work worktree:<branch> specs:<plan>`"
+
+---
+
+## Notes
+
+- Worktrees stored in `.unipi/worktrees/` directory
+- Each worktree is a full working copy with its own branch
+- Multiple worktrees can exist for parallel work
+- Use `/unipi:worktree-list` to see all worktrees
+- Use `/unipi:worktree-merge` to merge back to main

package/skills/worktree-list/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: worktree-list
+description: "List all unipi worktrees. Shows branch, path, and status."
+---
+
+# Listing Worktrees
+
+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.
+
+## Command Format
+
+```
+/unipi:worktree-list
+```
+
+No arguments. Lists all unipi worktrees.
+
+---
+
+## Process
+
+### Phase 1: Gather 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
+
+### Phase 2: Present
+
+Display in table format:
+
+```
+Worktrees:
+┌──────────────────┬────────────────────────────────┬─────────┐
+│ Branch           │ Path                           │ Status  │
+├──────────────────┼────────────────────────────────┼─────────┤
+│ feat/auth        │ .unipi/worktrees/feat/auth     │ clean   │
+│ fix/login-bug    │ .unipi/worktrees/fix/login-bug │ dirty   │
+└──────────────────┴────────────────────────────────┴─────────┘
+```
+
+If no worktrees:
+> "No unipi worktrees. Create one with `/unipi:worktree-create`"
+
+### Phase 3: Suggest Actions
+
+Based on state:
+- If dirty worktrees exist → suggest reviewing or committing
+- If clean worktrees exist → suggest working or merging
+- Always available: `/unipi:worktree-create`, `/unipi:worktree-merge`
+
+---
+
+## Notes
+
+- Only shows worktrees under `.unipi/worktrees/`
+- Ignores worktrees in other locations
+- Status: `clean` = no uncommitted changes, `dirty` = has changes

package/skills/worktree-merge/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: worktree-merge
+description: "Merge worktrees back to main branch. Multi-branch support with auto-suggest."
+---
+
+# Merging Worktrees
+
+Merge completed worktree branches back into main.
+
+## Boundaries
+
+**This skill MAY:** run git merge, git branch, git worktree commands, ask user for confirmation.
+**This skill MAY NOT:** edit code, implement features, force push.
+
+## Command Format
+
+```
+/unipi:worktree-merge <branch>(multiple,optional) <string(greedy)>(optional)
+```
+
+- `<branch>` — one or more branches to merge (auto-suggested from worktree-list)
+- `string(greedy)` — optional context (e.g., "merge all clean worktrees" or "merge auth first")
+- If no branches provided → agent lists worktrees and asks user to select
+
+---
+
+## Process
+
+### Phase 1: Resolve Target Branch
+
+1. Check for `main` branch
+2. If no `main`, check for `master`
+3. If neither exists:
+   > "No main or master branch found. Which branch should I merge into?"
+   - Ask user for target branch
+
+**Exit:** Target branch identified (e.g., `main`).
+
+### Phase 2: Resolve Source Branches
+
+If branches provided in args:
+1. Verify each branch exists
+2. Check for uncommitted changes in worktree
+3. Warn if dirty: "Branch `feat/auth` has uncommitted changes. Commit first?"
+
+If no branches provided:
+1. List all unipi worktrees
+2. Show status (clean/dirty)
+3. Ask user to select which to merge
+
+**Exit:** Source branch(es) confirmed, all clean.
+
+### Phase 3: Merge
+
+For each source branch:
+
+1. Switch to target branch (`git checkout main`)
+2. Merge source branch (`git merge feat/auth`)
+3. Handle conflicts if any:
+   - Report conflicts clearly
+   - Ask user how to resolve
+   - Don't force-merge
+4. If merge succeeds:
+   - Remove worktree (`git worktree remove .unipi/worktrees/feat/auth`)
+   - Delete branch if user confirms (`git branch -d feat/auth`)
+
+### Phase 4: Report
+
+Summary:
+```
+Merged 2 worktrees into main:
+✓ feat/auth — merged successfully, worktree removed
+✓ fix/login-bug — merged successfully, worktree removed
+```
+
+Or if issues:
+```
+Merged 1 of 2 worktrees:
+✓ feat/auth — merged successfully
+✗ fix/login-bug — CONFLICT in src/auth.ts, needs manual resolution
+```
+
+### Phase 5: Suggest Next
+
+After merge:
+- If all merged → suggest `/unipi:consolidate` to capture learnings
+- If conflicts remain → suggest resolving and retrying
+- If partial merge → suggest `/unipi:worktree-merge` for remaining
+
+---
+
+## Notes
+
+- Merges are standard git merges — no rebasing by default
+- Worktree removal keeps filesystem clean
+- Branch deletion is optional — ask user
+- Conflicts require human intervention — don't force
+- Order matters if branches depend on each other