@pi-unipi/workflow 0.1.7 → 0.1.9

package/skills/debug/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: debug
+description: "Active bug investigation — reproduce, diagnose, root-cause analysis. Produces debug report for /unipi:fix."
+---
+
+# Debugging
+
+Active investigation to reproduce, diagnose, and root-cause bugs. Produces a structured debug report that `/unipi:fix` can consume.
+
+## Boundaries
+
+**This skill MAY:** read codebase, run diagnostic commands, spawn subagents, write debug report to `.unipi/docs/debug/`.
+**This skill MAY NOT:** edit code, fix issues, run tests that modify state, deploy.
+
+**This is diagnosis only — not fixing.**
+
+## Command Format
+
+```
+/unipi:debug <string(greedy)>
+```
+
+- `string(greedy)` — bug description, error message, or reproduction steps
+- Read-only sandbox + write to `.unipi/docs/debug/`
+- Spawns subagents if `@unipi/subagents` extension is installed
+
+## Output Path
+
+```
+.unipi/docs/debug/YYYY-MM-DD-<topic>-debug.md
+```
+
+---
+
+## Process
+
+### Phase 1: Understand the Bug
+
+1. Read the bug description carefully
+2. If unclear, ask clarifying questions (one at a time):
+   - "What's the expected behavior?"
+   - "What's the actual behavior?"
+   - "Steps to reproduce?"
+   - "When did this start happening?"
+3. Identify the scope:
+   - Single function/module
+   - Integration issue
+   - System-wide problem
+
+**Exit:** Bug understood, scope defined.
+
+### Phase 2: Reproduce
+
+Attempt to reproduce the issue:
+
+1. **Find reproduction path:**
+   - Trace the code flow from entry point
+   - Identify the failing code path
+   - Look for error messages, stack traces
+
+2. **Run diagnostic commands:**
+   - `grep` for error messages in code
+   - `find` related files
+   - Check logs if available
+   - Run read-only test commands if safe
+
+3. **If subagents available:**
+   - Spawn explore agents to trace different code paths in parallel
+   - Each agent reports findings
+
+**Exit:** Reproduction steps documented (or confirmed unreproducible).
+
+### Phase 3: Diagnose
+
+Deep dive into root cause:
+
+1. **Trace the failure:**
+   - Start from the error/symptom
+   - Work backwards to find origin
+   - Document each step in the chain
+
+2. **Check common causes:**
+   - Null/undefined values
+   - Type mismatches
+   - Race conditions
+   - Missing error handling
+   - Incorrect assumptions
+   - Off-by-one errors
+   - State corruption
+
+3. **Analyze data flow:**
+   - Input validation
+   - Transformation steps
+   - Output format
+   - Edge cases
+
+4. **Check dependencies:**
+   - Recent changes to related code
+   - External service issues
+   - Configuration changes
+   - Version mismatches
+
+**Exit:** Root cause identified (or hypotheses listed if uncertain).
+
+### Phase 4: Document Findings
+
+Write debug report to `.unipi/docs/debug/YYYY-MM-DD-<topic>-debug.md`:
+
+```markdown
+---
+title: "{Bug Title} — Debug Report"
+type: debug
+date: YYYY-MM-DD
+severity: {critical|high|medium|low}
+status: {root-caused|needs-investigation|unreproducible}
+---
+
+# {Bug Title} — Debug Report
+
+## Summary
+{One-line description of the bug}
+
+## Expected Behavior
+{What should happen}
+
+## Actual Behavior
+{What actually happens}
+
+## Reproduction Steps
+1. {Step 1}
+2. {Step 2}
+3. {Step 3}
+
+## Environment
+- {Relevant context: OS, version, config}
+
+## Root Cause Analysis
+
+### Failure Chain
+1. {Entry point / trigger}
+2. {Intermediate step}
+3. {Failure point}
+
+### Root Cause
+{Detailed explanation of why the bug occurs}
+
+### Evidence
+- File: `{file}:{line}` — {what's wrong}
+- File: `{file}:{line}` — {related code}
+
+## Affected Files
+- `{file}` — {role in the bug}
+- `{file}` — {role in the bug}
+
+## Suggested Fix
+{High-level approach to fixing — NOT implementation}
+
+### Fix Strategy
+1. {Step 1}
+2. {Step 2}
+
+### Risk Assessment
+- {Risk 1}: {mitigation}
+- {Risk 2}: {mitigation}
+
+## Verification Plan
+How to verify the fix works:
+1. {Test case 1}
+2. {Test case 2}
+
+## Related Issues
+- {Link to related bugs, PRs, or discussions}
+
+## Notes
+{Any additional context, gotchas, or observations}
+```
+
+### Phase 5: Present & Handoff
+
+Present summary to user:
+
+> "Debug report written to `.unipi/docs/debug/YYYY-MM-DD-<topic>-debug.md`"
+> 
+> **Root Cause:** {brief summary}
+> **Suggested Fix:** {brief summary}
+
+Then suggest:
+
+**If root cause found:**
+```
+/unipi:fix debug:YYYY-MM-DD-<topic>-debug
+```
+
+**If needs more investigation:**
+> "Root cause unclear. Need to investigate {area} further."
+```
+/unipi:gather-context {area}
+```
+
+**If unreproducible:**
+> "Cannot reproduce with current steps. Can you provide more details?"
+- Wait for user input
+
+---
+
+## Differences from scan-issues
+
+| Aspect | `/unipi:debug` | `/unipi:scan-issues` |
+|--------|----------------|----------------------|
+| Purpose | Investigate specific bug | Find potential issues |
+| Input | Bug report / error message | Scope / category |
+| Output | Debug report with root cause | Issue list with priorities |
+| Depth | Deep single-issue analysis | Broad codebase scan |
+| Handoff | `/unipi:fix` | `/unipi:quick-work` or `/unipi:brainstorm` |
+
+---
+
+## Notes
+
+- Diagnosis only — fixes happen via `/unipi:fix`
+- Debug reports are reusable — `/unipi:fix` can autocomplete them
+- Subagent support enables parallel code path tracing
+- Always document the failure chain — helps verify fixes
+- If bug is complex, suggest `/unipi:consultant` for expert analysis

package/skills/fix/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: fix
+description: "Fix bugs using debug reports. Autocomplete for debug files. Records fixes in docs/fix/."
+---
+
+# Fixing Bugs
+
+Implement fixes based on debug reports. Autocomplete available for debug file selection.
+
+## Boundaries
+
+**This skill MAY:** read/write code, run tests, commit, write fix report to `.unipi/docs/fix/`.
+**This skill MAY NOT:** create worktrees, merge branches, deploy.
+
+## Command Format
+
+```
+/unipi:fix debug:<path>(optional) <string(greedy)>(optional)
+```
+
+- `debug:<path>` — debug report to fix from (autocomplete available)
+- `string(greedy)` — optional scope or additional context
+- If no debug provided → agent lists available debug reports and asks
+- Full read/write sandbox
+
+## Output Path
+
+```
+.unipi/docs/fix/YYYY-MM-DD-<topic>-fix.md
+```
+
+---
+
+## Process
+
+### Phase 1: Load Debug Report
+
+**If `debug:` arg provided:**
+1. Read the debug report from `.unipi/docs/debug/`
+2. Understand: root cause, affected files, suggested fix, verification plan
+
+**If no debug provided:**
+1. List available debug reports in `.unipi/docs/debug/`
+2. Present to user for selection (autocomplete-style)
+3. Or ask if fixing without debug report (→ suggest `/unipi:quick-fix`)
+
+**Exit:** Debug report loaded, fix strategy clear.
+
+### Phase 2: Plan the Fix
+
+Based on debug report:
+
+1. Review suggested fix strategy
+2. Identify all files that need changes
+3. Plan the order of changes
+4. Consider side effects
+
+If debug report is unclear or incomplete:
+> "Debug report suggests {approach}, but I need to verify {aspect}. Should I investigate further or proceed with the suggested fix?"
+
+**Exit:** Fix plan ready.
+
+### Phase 3: Implement Fix
+
+1. Make the code changes as suggested in debug report
+2. Follow the fix strategy step by step
+3. If strategy doesn't work:
+   - Document what happened
+   - Try alternative approach
+   - Update debug report if root cause was wrong
+
+4. After each change:
+   - Verify it compiles/parses
+   - Check for immediate regressions
+
+**Exit:** Code changes made.
+
+### Phase 4: Verify Fix
+
+Run verification as specified in debug report:
+
+1. **Reproduce original bug** — confirm it no longer occurs
+2. **Run test cases** — from debug report's verification plan
+3. **Run project tests** — `npm test` or equivalent
+4. **Check for regressions** — related functionality still works
+
+If verification fails:
+- Go back to Phase 3
+- Update debug report with new findings
+- Try alternative fix approach
+
+**Exit:** Fix verified.
+
+### Phase 5: Write Fix Report
+
+Write to `.unipi/docs/fix/YYYY-MM-DD-<topic>-fix.md`:
+
+```markdown
+---
+title: "{Bug Title} — Fix Report"
+type: fix
+date: YYYY-MM-DD
+debug-report: {path-to-debug-report}
+status: {fixed|partial-fix|could-not-fix}
+---
+
+# {Bug Title} — Fix Report
+
+## Summary
+{One-line description of what was fixed}
+
+## Debug Report Reference
+- Report: `.unipi/docs/debug/{filename}`
+- Root Cause: {brief summary}
+
+## Changes Made
+
+### Files Modified
+- `{file}` — {what changed and why}
+- `{file}` — {what changed and why}
+
+### Code Changes
+{Key code changes, or "See git diff for details"}
+
+## Fix Strategy
+{How the fix addresses the root cause}
+
+1. {Step 1}
+2. {Step 2}
+
+## Verification
+
+### Test Results
+- ✓ Original bug no longer reproduces
+- ✓ Test case 1: {description}
+- ✓ Test case 2: {description}
+- ✓ Project tests pass
+
+### Regression Check
+- ✓ {Related feature 1} still works
+- ✓ {Related feature 2} still works
+
+## Risks & Mitigations
+- {Risk}: {mitigation}
+
+## Notes
+{Any additional context, gotchas, or follow-ups}
+
+## Follow-up
+- [ ] {Optional follow-up task}
+```
+
+### Phase 6: Commit & Report
+
+1. Commit changes with descriptive message
+2. Report to user:
+
+> "Fixed. Changes committed."
+> 
+> **Fix:** {brief summary}
+> **Files:** {list of changed files}
+> **Report:** `.unipi/docs/fix/YYYY-MM-DD-<topic>-fix.md`
+
+Suggest next steps:
+
+**If fix was straightforward:**
+```
+/unipi:consolidate
+```
+
+**If fix revealed deeper issues:**
+> "The fix works, but I noticed {issue}. Consider:"
+```
+/unipi:scan-issues focus on {area}
+```
+
+**If fix was complex:**
+> "This was a tricky fix. Consider documenting the pattern:"
+```
+/unipi:document {area}
+```
+
+---
+
+## Autocomplete Behavior
+
+When user types `/unipi:fix debug:`, autocomplete shows:
+
+```
+Available debug reports:
+┌─────────────────────────────────────────┬────────────┬──────────────┐
+│ File                                    │ Date       │ Status       │
+├─────────────────────────────────────────┼────────────┼──────────────┤
+│ 2026-04-28-auth-timeout-debug.md        │ 2026-04-28 │ root-caused  │
+│ 2026-04-27-login-crash-debug.md         │ 2026-04-27 │ root-caused  │
+│ 2026-04-26-slow-query-debug.md          │ 2026-04-26 │ needs-inv.   │
+└─────────────────────────────────────────┴────────────┴──────────────┘
+```
+
+User selects one, or types path manually.
+
+---
+
+## Notes
+
+- Debug reports are the primary input — they guide the fix
+- Fixes without debug reports should use `/unipi:quick-fix` instead
+- Always verify against the debug report's verification plan
+- Fix reports provide audit trail for future reference
+- If debug report's suggested fix doesn't work, document why and try alternatives

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
 ---
@@ -170,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/quick-fix/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: quick-fix
+description: "Fast bug fix without debug report. One-shot fix for clear, simple bugs. Records fixes in docs/fix/."
+---
+
+# Quick Fix
+
+Fix simple bugs directly without requiring a debug report. One-shot execution for clear issues.
+
+## Boundaries
+
+**This skill MAY:** read/write code, run tests, commit, write fix report to `.unipi/docs/fix/`.
+**This skill MAY NOT:** create worktrees, merge branches, deploy.
+
+## Command Format
+
+```
+/unipi:quick-fix <string(greedy)>
+```
+
+- `string(greedy)` — bug description or error message
+- Full read/write sandbox
+- One shot — complete the fix in this session
+
+## Output Path
+
+```
+.unipi/docs/fix/YYYY-MM-DD-<topic>-fix.md
+```
+
+---
+
+## Process
+
+### Phase 1: Understand the Bug
+
+1. Read the bug description
+2. If unclear, ask one clarifying question
+3. Assess scope — is this truly a quick fix?
+   - If complex → suggest `/unipi:debug` first
+   - If appropriate → proceed
+
+**Exit:** Bug understood, scoped as quick fix.
+
+### Phase 2: Find and Fix
+
+1. **Locate the bug:**
+   - Search for error messages
+   - Trace the code path
+   - Find the problematic code
+
+2. **Apply fix:**
+   - Make the minimal correct change
+   - Don't refactor unless necessary
+   - Keep changes focused
+
+3. **Verify:**
+   - Confirm fix works
+   - Run tests if applicable
+   - Check for obvious regressions
+
+**Exit:** Bug fixed.
+
+### Phase 3: Write Fix Report
+
+Write to `.unipi/docs/fix/YYYY-MM-DD-<topic>-fix.md`:
+
+```markdown
+---
+title: "{Bug Title} — Quick Fix"
+type: quick-fix
+date: YYYY-MM-DD
+---
+
+# {Bug Title} — Quick Fix
+
+## Bug
+{Description of the bug}
+
+## Root Cause
+{Brief explanation of what was wrong}
+
+## Fix
+{What was changed and why}
+
+### Files Modified
+- `{file}` — {what changed}
+
+## Verification
+{How it was tested}
+
+## Notes
+{Anything worth noting}
+```
+
+### Phase 4: Commit & Report
+
+1. Commit with descriptive message
+2. Report to user:
+
+> "Fixed. Changes committed. Report at `.unipi/docs/fix/YYYY-MM-DD-<topic>-fix.md`"
+
+No further suggestions needed — this was a quick fix.
+
+---
+
+## When to Use quick-fix vs debug+fix
+
+**Use quick-fix for:**
+- Clear, obvious bugs
+- Error messages that pinpoint the issue
+- Simple logic errors
+- Typos in code
+- Missing null checks
+- Wrong variable names
+
+**Use debug+fix for:**
+- Complex bugs with unclear root cause
+- Intermittent issues
+- Performance problems
+- Bugs requiring deep investigation
+- Issues affecting multiple systems
+
+When in doubt, start with quick-fix. If it gets complex, suggest switching to debug.
+
+---
+
+## Notes
+
+- No debug report required — direct fix
+- Summary provides record of what was fixed
+- For complex bugs, use `/unipi:debug` first
+- Fix reports go to same `.unipi/docs/fix/` directory as regular fixes

package/skills/quick-work/SKILL.md

@@ -9,7 +9,7 @@ Execute a single task directly. No brainstorm, no plan — just do it and record
 
 ## Boundaries
 
-**This skill MAY:** read/write code, run tests, commit, write summary to `.unipi/quick-work/`.
+**This skill MAY:** read/write code, run tests, commit, write summary to `.unipi/docs/quick-work/`.
 **This skill MAY NOT:** create worktrees, merge branches, deploy.
 
 ## Command Format
@@ -49,7 +49,7 @@ Straightforward — no planning, no discussion, just work.
 
 ### Phase 3: Write Summary
 
-Write summary to `.unipi/quick-work/YYYY-MM-DD-<topic>.md`:
+Write summary to `.unipi/docs/quick-work/YYYY-MM-DD-<topic>.md`:
 
 ```markdown
 ---
@@ -76,7 +76,7 @@ date: YYYY-MM-DD
 
 ### Phase 4: Report
 
-> "Done. Changes committed. Summary at `.unipi/quick-work/YYYY-MM-DD-<topic>.md`"
+> "Done. Changes committed. Summary at `.unipi/docs/quick-work/YYYY-MM-DD-<topic>.md`"
 
 No further suggestions needed — this was a one-shot task.