@pi-unipi/workflow 0.1.0

package/skills/plan/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: plan
+description: "Strategic planning — create implementation plan from brainstorm specs. Tasks, dependencies, acceptance criteria."
+---
+
+# Planning From Specs
+
+Turn brainstorm decisions into an actionable implementation plan.
+
+## Boundaries
+
+**This skill MAY:** read specs, read codebase, ask questions, write plan document, update brainstorm checkboxes.
+**This skill MAY NOT:** edit code, implement anything, run tests, deploy.
+
+**NEVER write code during this skill. This is planning, not implementation.**
+
+## Command Format
+
+```
+/unipi:plan specs:<path>(multiple,optional) <string(greedy)>(optional)
+```
+
+- `specs:<path>` — one or more brainstorm specs to plan from (auto-suggested)
+- `string(greedy)` — optional scope guidance (e.g., "focus on API layer only")
+- If no specs provided → agent asks user which spec to plan from
+- Runs in current session, read-only sandbox + write to `.unipi/docs/`
+
+## Sandbox
+
+- **Read:** full codebase access for context
+- **Write:** only `.unipi/docs/` directory
+
+## Output Path
+
+```
+.unipi/docs/plans/YYYY-MM-DD-<topic>-plan.md
+```
+
+Committed to current branch.
+
+---
+
+## Phase 1: Load Specs
+
+1. If `specs:` arg provided, read those spec files
+2. If not provided, list available specs in `.unipi/docs/specs/` and ask user to choose
+3. Read the spec(s) fully — understand problem, approach, design, checklist
+
+**Exit:** Spec(s) loaded. Understand what to plan.
+
+---
+
+## Phase 2: Review & Ask
+
+1. Review spec critically — identify concerns or gaps
+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)
+
+**Exit:** No blockers. Ready to plan.
+
+---
+
+## Phase 3: Create Implementation Plan
+
+Structure the plan with heart of gold style:
+
+```markdown
+---
+title: "{Topic} — Implementation Plan"
+type: plan
+date: YYYY-MM-DD
+specs:
+  - path/to/spec.md
+---
+
+# {Topic} — Implementation Plan
+
+## Overview
+{Brief summary of what this plan covers}
+
+## 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}
+
+### Task 2: {Task Name}
+...
+
+## Sequencing
+{Order of execution, dependency graph if complex}
+
+## Risks
+{Potential blockers or concerns}
+```
+
+### Task Guidelines
+
+- Each task should be **discrete and completable** in one session
+- **Dependencies** must be explicit — task B can't start before task A
+- **Acceptance criteria** must be verifiable — not "looks good" but "tests pass, builds clean"
+- **Steps** are bite-sized — agent can follow without guessing
+- Order tasks by dependency (foundational work first)
+
+---
+
+## Phase 4: Update Brainstorm Checkboxes
+
+After plan is complete:
+
+1. Read the source brainstorm spec(s)
+2. For each checklist item covered by this plan, mark `[x]`
+3. Leave items not covered as `[ ]`
+4. Write updated spec back
+
+**Example:**
+```markdown
+## Implementation Checklist
+- [x] Set up auth middleware — covered in Task 1
+- [x] Create login endpoint — covered in Task 2
+- [ ] Add OAuth support — deferred to next plan
+- [ ] Rate limiting — out of scope
+```
+
+This creates the link between brainstorm and plan — plan covers some items, others remain for future plans.
+
+---
+
+## Phase 5: Review Plan
+
+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
+
+---
+
+## Phase 6: Present & Handoff
+
+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
+
+If user selects "Proceed to /unipi:work", suggest:
+```
+/unipi:work worktree:feat/<branch-name> specs:YYYY-MM-DD-<topic>-plan
+```
+
+Recommend starting a **new session** for work — it will switch pi's internal worktree.
+
+---
+
+## 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

package/skills/quick-work/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: quick-work
+description: "Fast single-task execution — one shot, done. Use for small tasks that don't need full brainstorm/plan/work flow."
+---
+
+# Quick Work
+
+Execute a single task directly. No brainstorm, no plan — just do it and record what happened.
+
+## Boundaries
+
+**This skill MAY:** read/write code, run tests, commit, write summary to `.unipi/quick-work/`.
+**This skill MAY NOT:** create worktrees, merge branches, deploy.
+
+## Command Format
+
+```
+/unipi:quick-work <string(greedy)>
+```
+
+- `string(greedy)` — what to do (e.g., "add input validation to login form", "fix the typo in README")
+- Full read/write sandbox
+- One shot — complete the task in this session
+
+---
+
+## Process
+
+### Phase 1: Understand Task
+
+1. Read the request
+2. If unclear, ask one clarifying question
+3. Assess scope — is this truly a quick task?
+   - If too complex → suggest `/unipi:brainstorm` instead
+   - If appropriate → proceed
+
+**Exit:** Task understood, scoped appropriately.
+
+### Phase 2: Execute
+
+1. Find relevant files
+2. Make the changes
+3. Verify (run tests if applicable)
+4. Commit with descriptive message
+
+Straightforward — no planning, no discussion, just work.
+
+**Exit:** Task complete.
+
+### Phase 3: Write Summary
+
+Write summary to `.unipi/quick-work/YYYY-MM-DD-<topic>.md`:
+
+```markdown
+---
+title: "{Topic}"
+type: quick-work
+date: YYYY-MM-DD
+---
+
+# {Topic}
+
+## Task
+{What was requested}
+
+## Changes
+- {File 1}: {what changed}
+- {File 2}: {what changed}
+
+## Verification
+{How it was tested — "ran tests", "manual check", etc.}
+
+## Notes
+{Anything worth noting — gotchas, follow-ups, etc.}
+```
+
+### Phase 4: Report
+
+> "Done. Changes committed. Summary at `.unipi/quick-work/YYYY-MM-DD-<topic>.md`"
+
+No further suggestions needed — this was a one-shot task.
+
+---
+
+## When to Use Quick Work vs Full Flow
+
+**Use quick-work for:**
+- Bug fixes (small, clear)
+- Typo corrections
+- Config changes
+- Small feature additions (< 30 min work)
+- Dependency updates
+
+**Use full flow (brainstorm/plan/work) for:**
+- New features
+- Architecture changes
+- Multi-file refactors
+- Anything with design decisions
+- Tasks requiring discussion
+
+When in doubt, start with quick-work. If it gets complex, suggest switching to full flow.
+
+---
+
+## Notes
+
+- No worktree isolation — works on current branch
+- No planning overhead — direct execution
+- Summary provides record of what was done
+- Task should be completable in one session

package/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/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)