@pi-unipi/unipi 0.1.1

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

@@ -0,0 +1,131 @@
+---
+name: review-work
+description: "Review work — check task completion, run lint/build, mark reviewer remarks. Use after /unipi:work completes."
+---
+
+# Reviewing Work
+
+Review what was built, verify task completion, run codebase checks, add reviewer remarks.
+
+## Boundaries
+
+**This skill MAY:** read codebase, run checks (lint, build, test, docker), write reviewer remarks to plan docs.
+**This skill MAY NOT:** edit code, implement features, create new files.
+
+## Command Format
+
+```
+/unipi:review-work plan:<path>(optional) <string(greedy)>(optional)
+```
+
+- `plan:<path)` — specific plan to review (auto-suggested)
+- `string(greedy)` — scope (e.g., "only review auth tasks" or "just check builds")
+- If no plan provided → agent finds latest plan or asks user
+- Runs in current session (or worktree session if still active)
+
+---
+
+## Phase 1: Load Plan
+
+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
+
+**Exit:** Plan loaded. Know what to review.
+
+---
+
+## Phase 2: Check Task Completion
+
+For each task in plan:
+
+1. Read acceptance criteria
+2. Verify against actual implementation
+3. Determine status:
+   - **Done** — all criteria met
+   - **Partially Done X/Y** — some steps complete, others not
+   - **Unstarted** — nothing done
+
+If `string(greedy)` scope provided, only check matching tasks.
+
+---
+
+## Phase 3: Run Codebase Checks
+
+Run project's verification suite:
+
+1. **Lint** — `npm run lint` or equivalent
+2. **Type check** — `tsc --noEmit` or equivalent
+3. **Tests** — `npm test` or equivalent
+4. **Build** — `npm run build` or equivalent
+5. **Docker** — `docker build .` if Dockerfile exists
+
+Report results. If any fail:
+- Note which checks failed
+- Identify which tasks are affected
+- Don't fix — just report
+
+---
+
+## Phase 4: Write Reviewer Remarks
+
+Add `REVIEWER-REMARK` at the **end of the plan document**, behind a divider:
+
+```markdown
+---
+
+## Reviewer Remarks
+
+REVIEWER-REMARK: Partially Done 3/5
+- Tasks 1-3 complete, verified against acceptance criteria
+- Task 4 stuck: API endpoint returns 500, needs investigation
+- Task 5 unstarted: depends on Task 4
+
+Codebase Checks:
+- ✓ Lint passed
+- ✓ Type check passed
+- ✗ Tests failed: 2 failing in auth.test.ts
+- ✓ Build passed
+- ✓ Docker build passed
+```
+
+### Status Format
+
+```
+REVIEWER-REMARK: <Done | Partially Done X/Y | Unstarted>
+```
+
+Followed by description explaining the status.
+
+---
+
+## Phase 5: Handoff
+
+Based on review results:
+
+**If all tasks done and checks pass:**
+> "All tasks complete and verified. Ready to consolidate."
+```
+/unipi:consolidate
+```
+
+**If tasks incomplete or checks fail:**
+> "Tasks remaining and/or checks failing. Continue work?"
+```
+/unipi:work worktree:<branch> specs:<plan-path>
+```
+
+**If scoped review complete:**
+> "Scoped review complete. Run full review or continue work?"
+```
+/unipi:review-work plan:<plan-path>  (full review)
+/unipi:work specs:<plan-path>        (continue work)
+```
+
+---
+
+## Notes
+
+- Reviewer remarks append to end of plan — don't modify existing content
+- Check results are factual — report pass/fail, don't diagnose
+- This is a checkpoint, not a fix pass — work continues via `/unipi:work`

package/packages/workflow/skills/scan-issues/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: scan-issues
+description: "Deep investigation — find bugs, anti-patterns, security issues. Spawns subagents if available."
+---
+
+# Scanning for Issues
+
+Deep investigation of codebase to find bugs, anti-patterns, security issues, and technical debt.
+
+## Boundaries
+
+**This skill MAY:** read codebase, run read-only analysis commands, spawn subagents, write findings.
+**This skill MAY NOT:** edit code, fix issues, run tests that modify state, deploy.
+
+**This is investigation only — not fixing.**
+
+## Command Format
+
+```
+/unipi:scan-issues <string(greedy)>(optional)
+```
+
+- `string(greedy)` — optional scope (e.g., "focus on auth", "check for SQL injection", "find dead code")
+- If not provided → full codebase scan
+- Read-only sandbox
+- Spawns subagents if `@unipi/subagents` extension is installed
+
+---
+
+## Process
+
+### Phase 1: Determine Scope
+
+**If scope provided:**
+1. Parse the focus area
+2. Determine scan type:
+   - Security scan
+   - Bug hunt
+   - Anti-pattern detection
+   - Tech debt assessment
+   - Performance issues
+
+**If no scope:**
+1. Ask user what to focus on, or
+2. Run broad scan covering all categories
+
+**Exit:** Scope defined.
+
+### Phase 2: Deep Investigation
+
+If subagents available:
+1. Spawn parallel subagents for different scan types
+2. Each subagent investigates independently
+3. Collect findings from all subagents
+
+If no subagents:
+1. Investigate sequentially
+2. Use grep, find, read commands
+3. Build findings incrementally
+
+**Scan categories:**
+
+**Security:**
+- Hardcoded secrets/credentials
+- SQL injection vulnerabilities
+- XSS vulnerabilities
+- Insecure dependencies
+- Missing input validation
+- Exposed sensitive data
+
+**Bugs:**
+- Null/undefined handling
+- Race conditions
+- Error handling gaps
+- Edge cases missed
+- Logic errors
+- Off-by-one errors
+
+**Anti-patterns:**
+- Code duplication
+- God objects/functions
+- Circular dependencies
+- Tight coupling
+- Magic numbers/strings
+- Inconsistent patterns
+
+**Tech debt:**
+- TODO/FIXME comments
+- Deprecated API usage
+- Outdated dependencies
+- Dead code
+- Missing tests
+- Poor naming
+
+**Performance:**
+- N+1 queries
+- Unnecessary re-renders
+- Large bundle imports
+- Missing caching
+- Inefficient algorithms
+
+**Exit:** Findings collected.
+
+### Phase 3: Categorize & Prioritize
+
+Organize findings by severity:
+
+**Critical (P0):**
+- Security vulnerabilities
+- Data loss risks
+- Production-breaking bugs
+
+**High (P1):**
+- Significant bugs
+- Major anti-patterns
+- Performance bottlenecks
+
+**Medium (P2):**
+- Minor bugs
+- Tech debt
+- Code smells
+
+**Low (P3):**
+- Style issues
+- Minor improvements
+- Nice-to-haves
+
+### Phase 4: Present Findings
+
+```markdown
+## Issue Scan Results
+
+### Critical (P0)
+- {Finding} — {file:line} — {description}
+
+### High (P1)
+- {Finding} — {file:line} — {description}
+
+### Medium (P2)
+- {Finding} — {file:line} — {description}
+
+### Low (P3)
+- {Finding} — {file:line} — {description}
+
+### Summary
+- Total issues: {count}
+- Critical: {count}
+- High: {count}
+- Medium: {count}
+- Low: {count}
+```
+
+### Phase 5: Handoff
+
+Based on findings:
+
+**If critical issues found:**
+> "Critical issues found. Recommend addressing immediately."
+```
+/unipi:quick-work "fix critical security issue in auth.ts"
+```
+
+**If many issues:**
+> "Multiple issues found. Consider planning a cleanup sprint."
+```
+/unipi:brainstorm "tech debt cleanup plan"
+```
+
+**If few/no issues:**
+> "Codebase looks healthy. No critical issues found."
+```
+/unipi:consolidate
+```
+
+---
+
+## Notes
+
+- Investigation only — findings are reported, not fixed
+- Subagent support enables parallel scanning when available
+- Can focus on specific categories or scan broadly
+- Prioritized findings help triage what to fix first
+- Natural lead-in to quick-work (for critical) or brainstorm (for planned cleanup)

package/packages/workflow/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/packages/workflow/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/packages/workflow/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/packages/workflow/skills/worktree-merge/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: worktree-merge
+description: "Merge worktree branches back to main. Gathers context from specs/plans, merges, cleans up."
+---
+
+# Worktree Merge
+
+Merge completed worktree branches into main. Gather context from docs before merging.
+
+## Process
+
+### Phase 1: Gather Context
+
+Before merging, read existing specs and plans to understand what each worktree was implementing:
+
+1. Read all files in `.unipi/docs/specs/` (if exists)
+2. Read all files in `.unipi/docs/plans/` (if exists)
+3. Build a map: branch → what it was working on
+
+This context helps during merge conflicts and in the final report.
+
+### Phase 2: Resolve Target Branch
+
+1. Check for `main` branch: `git branch --list main`
+2. If not found, check `master`: `git branch --list master`
+3. If neither exists, ask user for target branch
+
+### Phase 3: Resolve Source Branches
+
+**If branches provided in args:**
+- Verify each branch exists: `git branch --list <name>`
+- Check worktree status for each
+
+**If no branches provided:**
+- List all worktrees: `git worktree list`
+- Filter to `.unipi/worktrees/` paths only
+- Show each with status (clean/dirty via `git status`)
+- Ask user which to merge
+
+### Phase 4: Merge Each Branch
+
+For each source branch (in dependency order if specs indicate ordering):
+
+1. **Checkout target:** `git checkout main`
+2. **Merge:** `git merge <branch> --no-edit`
+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
+4. **If success:**
+   - Remove worktree: `git worktree remove .unipi/worktrees/<branch-name>`
+   - Delete branch: `git branch -d <branch>`
+   - Log success with context: "Merged: <what it was doing>"
+
+### Phase 5: Report
+
+```
+Merge Summary:
+✓ feat/auth — merged (auth system implementation from specs/auth-system.md)
+✓ fix/login-bug — merged (login fix from plans/bugfix-login.md)
+✗ feat/dashboard — CONFLICT in src/dashboard.ts, skipped
+
+Worktrees cleaned: 2 removed
+Branches deleted: 2
+```
+
+### Phase 6: Suggest Next
+
+- If all merged cleanly → suggest `/unipi:consolidate` to save learnings
+- If conflicts remain → suggest resolving and retrying `/unipi:worktree-merge`
+- If specs/plans exist for merged work → suggest `/unipi:document` to update docs
+
+## Important
+
+- ALWAYS read specs/plans before merging — context prevents bad conflict resolution
+- NEVER force push or force merge
+- Ask user before destructive operations (branch deletion)
+- If a worktree has uncommitted changes, warn and skip