@pi-unipi/workflow 0.1.7 → 0.1.9

package/skills/research/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: research
+description: "Read-only research with bash access. Deep codebase investigation, documentation review, external research."
+---
+
+# Research
+
+Deep read-only investigation with bash access. For thorough codebase analysis, documentation review, and external research.
+
+## Boundaries
+
+**This skill MAY:** read codebase, run read-only bash commands, spawn subagents, write findings, use web tools if available.
+**This skill MAY NOT:** edit code, create files (except findings), run tests that modify state, deploy.
+
+**This is research only — not implementation.**
+
+## Command Format
+
+```
+/unipi:research <string(greedy)>
+```
+
+- `string(greedy)` — research topic or question
+- Read-only sandbox + bash access
+- Spawns subagents if `@unipi/subagents` extension is installed
+- Uses web tools if `@unipi/web-api` extension is installed
+
+## Output
+
+Findings presented in conversation. Can be saved to `.unipi/docs/generated/` if user requests.
+
+---
+
+## Process
+
+### Phase 1: Define Research Scope
+
+1. Read the research topic/question
+2. If ambiguous, ask clarifying questions (one at a time)
+3. Determine research type:
+   - **Codebase research** — patterns, architecture, dependencies
+   - **Documentation research** — existing docs, READMEs, comments
+   - **External research** — libraries, APIs, best practices
+   - **Historical research** — git history, past decisions
+   - **Comparative research** — evaluate options/approaches
+
+**Exit:** Research scope defined.
+
+### Phase 2: Codebase Research
+
+Use bash and read tools for deep investigation:
+
+**Structure Analysis:**
+```bash
+find . -type f -name "*.ts" | head -50
+ls -la src/
+tree src/ -L 2
+```
+
+**Pattern Search:**
+```bash
+grep -r "pattern" --include="*.ts" .
+grep -rn "TODO\|FIXME\|HACK" --include="*.ts" .
+```
+
+**Dependency Analysis:**
+```bash
+cat package.json
+grep -r "import.*from" --include="*.ts" . | sort | uniq -c | sort -rn
+```
+
+**Git History:**
+```bash
+git log --oneline -20
+git log --all --oneline --grep="keyword"
+git blame file.ts
+```
+
+**Exit:** Codebase context gathered.
+
+### Phase 3: Documentation Research
+
+1. Read existing documentation:
+   - README files
+   - API docs
+   - Architecture docs
+   - Comments and docstrings
+
+2. Check for gaps:
+   - Missing documentation
+   - Outdated docs
+   - Inconsistent information
+
+3. Cross-reference:
+   - Do docs match code?
+   - Are examples correct?
+
+**Exit:** Documentation context gathered.
+
+### Phase 4: External Research (if web tools available)
+
+Use web tools for external research:
+
+**Library/API Research:**
+```
+web_search(query: "library-name documentation")
+web_read(url: "https://docs.library.com")
+web_llm_summarize(url: "https://library.com/guide", prompt: "Extract key concepts and usage patterns")
+```
+
+**Best Practices:**
+```
+web_search(query: "best practices for X in TypeScript 2026")
+web_search(query: "X vs Y comparison")
+```
+
+**Stack Overflow / GitHub:**
+```
+web_search(query: "site:stackoverflow.com how to X")
+web_search(query: "site:github.com X implementation examples")
+```
+
+**Exit:** External context gathered.
+
+### Phase 5: Synthesize Findings
+
+Organize research into clear categories:
+
+```markdown
+## Research Findings: {Topic}
+
+### Summary
+{One-paragraph overview of findings}
+
+### Key Findings
+1. {Finding 1}
+2. {Finding 2}
+3. {Finding 3}
+
+### Detailed Analysis
+
+#### {Category 1}
+{Detailed findings with evidence}
+
+#### {Category 2}
+{Detailed findings with evidence}
+
+### Codebase Context
+- Current implementation: {description}
+- Patterns used: {list}
+- Gaps identified: {list}
+
+### Recommendations
+- {Recommendation 1}
+- {Recommendation 2}
+
+### Sources
+- {File/code references}
+- {External links}
+- {Documentation references}
+
+### Open Questions
+- {Question that needs further research}
+```
+
+### Phase 6: Present & Handoff
+
+Present findings to user:
+
+> "Research complete on: {topic}"
+
+Then suggest next steps based on findings:
+
+**If research was for planning:**
+> "Ready to brainstorm solutions?"
+```
+/unipi:brainstorm {topic}
+```
+
+**If research found issues:**
+> "Found some issues during research. Consider investigating:"
+```
+/unipi:debug {issue}
+/unipi:scan-issues focus on {area}
+```
+
+**If research was for documentation:**
+> "Ready to document what we found?"
+```
+/unipi:document {topic}
+```
+
+**If research was exploratory:**
+> "Want me to save these findings?"
+- Save to `.unipi/docs/generated/YYYY-MM-DD-research-{topic}.md`
+
+---
+
+## Research Types
+
+### Codebase Research
+- Find patterns and conventions
+- Understand architecture
+- Map dependencies
+- Identify tech debt
+
+### Documentation Research
+- Review existing docs
+- Find gaps and inconsistencies
+- Extract best practices
+- Cross-reference with code
+
+### External Research
+- Library evaluation
+- API documentation
+- Best practices
+- Community solutions
+
+### Historical Research
+- Git history analysis
+- Past decision context
+- Evolution of codebase
+- Bug pattern analysis
+
+### Comparative Research
+- Evaluate alternatives
+- Trade-off analysis
+- Performance comparison
+- Feature comparison
+
+---
+
+## Differences from gather-context
+
+| Aspect | `/unipi:research` | `/unipi:gather-context` |
+|--------|-------------------|-------------------------|
+| Scope | Broad, any topic | Focused on codebase |
+| Bash access | Full read-only bash | Limited commands |
+| External web | Uses web tools | Codebase only |
+| Output | Detailed findings | Concise summary |
+| Handoff | Various options | Always → brainstorm |
+
+---
+
+## Notes
+
+- Read-only with bash — powerful but safe
+- Web tools integration when available
+- Subagent support for parallel research
+- Findings can be saved to docs if requested
+- Natural lead-in to brainstorm, debug, or document

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
@@ -112,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/scan-issues/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: scan-issues
-description: "Deep investigation — find bugs, anti-patterns, security issues. Spawns subagents if available."
+description: "Passive codebase scan — find potential 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.
+Passive investigation of codebase to find potential bugs, anti-patterns, security issues, and technical debt.
 
 ## Boundaries
 
@@ -14,6 +14,8 @@ Deep investigation of codebase to find bugs, anti-patterns, security issues, and
 
 **This is investigation only — not fixing.**
 
+**Note:** For active debugging of specific bugs, use `/unipi:debug` instead. scan-issues finds potential problems; debug diagnoses known issues.
+
 ## Command Format
 
 ```
@@ -181,3 +183,13 @@ Based on findings:
 - 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)
+
+## Differences from debug
+
+| Aspect | `/unipi:scan-issues` | `/unipi:debug` |
+|--------|----------------------|----------------|
+| Purpose | Find potential issues | Investigate specific bug |
+| Input | Scope / category | Bug report / error message |
+| Output | Issue list with priorities | Debug report with root cause |
+| Depth | Broad codebase scan | Deep single-issue analysis |
+| Handoff | `/unipi:quick-work` or `/unipi:brainstorm` | `/unipi:fix` |

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.
 
 ---
 
@@ -134,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
@@ -161,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