@pi-unipi/unipi 0.1.1

package/packages/workflow/skills/consultant/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: consultant
+description: "Expert consultation — advisory with framework-based analysis. Read-only. Use when you need expert advice before brainstorming."
+---
+
+# Expert Consultation
+
+Provide expert advisory using structured frameworks. Analyze problems, evaluate options, give recommendations.
+
+## Boundaries
+
+**This skill MAY:** read codebase, research, analyze, discuss, provide recommendations.
+**This skill MAY NOT:** edit code, create files, run tests, implement anything.
+
+**This is advisory only — no implementation.**
+
+## Command Format
+
+```
+/unipi:consultant <string(greedy)>
+```
+
+- `string(greedy)` — the question, problem, or topic to consult on
+- Read-only sandbox — agent analyzes and advises, doesn't touch code
+
+---
+
+## Frameworks
+
+Apply relevant framework based on the question type:
+
+### Architecture Questions
+- **Decision Matrix** — evaluate options against weighted criteria
+- **ADR format** — document architectural decisions with context and consequences
+- **C4 Model** — system context, containers, components, code
+
+### Code Quality Questions
+- **SOLID principles** — assess adherence
+- **Code smells** — identify and prioritize
+- **Tech debt quadrant** — reckless vs prudent, deliberate vs inadvertent
+
+### Strategy Questions
+- **SWOT analysis** — strengths, weaknesses, opportunities, threats
+- **Cost-benefit** — quantify trade-offs
+- **Risk matrix** — likelihood vs impact
+
+### Debugging Questions
+- **5 Whys** — root cause analysis
+- **Fishbone diagram** — categorize potential causes
+- **Binary search** — narrow down systematically
+
+---
+
+## Process
+
+### Phase 1: Understand the Question
+
+1. Read the question carefully
+2. If ambiguous, ask clarifying question (one at a time)
+3. Determine which framework applies
+4. Read relevant codebase context if needed
+
+### Phase 2: Analyze
+
+1. Apply the relevant framework
+2. Research codebase for evidence
+3. Consider multiple perspectives
+4. Form recommendations
+
+### Phase 3: Advise
+
+Present analysis with:
+- **Framework used** — so user knows the lens
+- **Key findings** — what I discovered
+- **Recommendation** — what I'd do and why
+- **Alternatives** — what else was considered
+- **Risks** — what could go wrong
+
+### Phase 4: Handoff
+
+After advising:
+
+> "If you'd like to explore this further, I can help you brainstorm solutions."
+```
+/unipi:brainstorm <topic>
+```
+
+Or if user has more questions, continue consulting.
+
+---
+
+## Notes
+
+- This is read-only advisory — no code changes
+- Frameworks are tools, not rules — adapt to context
+- Recommendations are starting points for discussion, not final answers
+- Natural lead-in to brainstorm when user wants to act on advice

package/packages/workflow/skills/document/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: document
+description: "Generate documentation — README, API docs, guides. Use when you need to document code or features."
+---
+
+# Generating Documentation
+
+Create documentation for code, features, or the project. Works with gather-context for thorough docs.
+
+## Boundaries
+
+**This skill MAY:** read codebase, run read-only commands, write docs to `.unipi/docs/generated/`.
+**This skill MAY NOT:** edit source code, run tests, implement features.
+
+## Command Format
+
+```
+/unipi:document <string(greedy)>(optional)
+```
+
+- `string(greedy)` — optional scope (e.g., "document the auth module", "write API docs for /api/users")
+- If not provided → agent asks what to document
+- Output: `.unipi/docs/generated/` in markdown
+
+---
+
+## Process
+
+### Phase 1: Determine Scope
+
+**If scope provided:**
+1. Parse what to document
+2. Confirm with user: "I'll document {scope}. Sound right?"
+
+**If no scope:**
+1. Ask user what to document:
+   - "What should I document? (e.g., specific module, feature, or entire project)"
+2. Ask doc type:
+   - "What type of documentation? (README, API docs, guide, architecture doc)"
+
+**Exit:** Scope and type confirmed.
+
+### Phase 2: Gather Context
+
+1. Read relevant source code
+2. Check for existing documentation
+3. Identify gaps
+4. Use gather-context patterns if needed:
+   - Find related files
+   - Check git history for context
+   - Look for comments and docstrings
+
+**Exit:** Context gathered. Ready to write.
+
+### Phase 3: Generate Documentation
+
+Based on doc type:
+
+**README:**
+- Project overview
+- Installation
+- Usage examples
+- Configuration
+- Contributing
+
+**API docs:**
+- Endpoints/routes
+- Request/response formats
+- Authentication
+- Error codes
+- Examples
+
+**Guides:**
+- Step-by-step instructions
+- Code examples
+- Common patterns
+- Troubleshooting
+
+**Architecture doc:**
+- System overview
+- Module responsibilities
+- Data flow
+- Key decisions
+
+### Phase 4: Write
+
+Write to `.unipi/docs/generated/YYYY-MM-DD-<topic>.md`:
+
+```markdown
+---
+title: "{Title}"
+type: documentation
+date: YYYY-MM-DD
+scope: {what was documented}
+---
+
+# {Title}
+
+{Content based on doc type}
+```
+
+### Phase 5: Present
+
+Show summary to user:
+> "Documentation written to `.unipi/docs/generated/YYYY-MM-DD-<topic>.md`"
+> "Covers: {summary of what's documented}"
+
+Ask:
+1. **Review it** — read and suggest changes
+2. **Add more** — extend documentation
+3. **Done** — documentation complete
+
+---
+
+## Notes
+
+- Output in markdown — portable, readable, diffable
+- `.unipi/docs/generated/` keeps docs separate from workflow artifacts
+- Can document code, features, architecture, or processes
+- Natural extension of gather-context — research then document

package/packages/workflow/skills/gather-context/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: gather-context
+description: "Research codebase — surface patterns, find prior art, prepare for brainstorm. Spawns subagents if available."
+---
+
+# Gathering Context
+
+Research the codebase thoroughly to prepare for brainstorming. Find patterns, prior art, and relevant context.
+
+## Boundaries
+
+**This skill MAY:** read codebase, run read-only commands (find, grep, ls), spawn subagents, write findings.
+**This skill MAY NOT:** edit code, implement features, run tests that modify state.
+
+## Command Format
+
+```
+/unipi:gather-context <string(greedy)>
+```
+
+- `string(greedy)` — what to research (e.g., "authentication patterns", "how we handle errors", "database layer")
+- Read-only sandbox
+- Spawns subagents if `@unipi/subagents` extension is installed
+
+---
+
+## Process
+
+### Phase 1: Parse Research Request
+
+1. Read the research topic
+2. Break into sub-topics if needed
+3. Determine research strategy:
+   - File search (find files related to topic)
+   - Pattern search (grep for patterns, conventions)
+   - Structure analysis (directory layout, module organization)
+   - History analysis (git log for related changes)
+
+**Exit:** Research plan ready.
+
+### Phase 2: Gather Context
+
+If subagents available:
+1. Spawn parallel subagents for different sub-topics
+2. Each subagent researches independently
+3. Collect findings from all subagents
+
+If no subagents:
+1. Research sequentially
+2. Use find, grep, read commands
+3. Build context incrementally
+
+**Research areas:**
+
+**Code structure:**
+- Directory layout
+- Module organization
+- Key files and their purposes
+- Entry points
+
+**Patterns & conventions:**
+- Naming conventions
+- Import patterns
+- Error handling patterns
+- Testing patterns
+
+**Prior art:**
+- Similar features that exist
+- Past approaches (from git history)
+- Reusable components
+- Known issues or tech debt
+
+**Dependencies:**
+- External libraries used
+- Internal module dependencies
+- Configuration files
+
+**Exit:** Context gathered from all areas.
+
+### Phase 3: Synthesize
+
+Organize findings into clear categories:
+
+```markdown
+## Key Findings
+
+### Structure
+- {Finding about project structure}
+
+### Patterns
+- {Finding about patterns used}
+
+### Prior Art
+- {Finding about existing similar work}
+
+### Gaps
+- {Finding about what's missing}
+
+### Recommendations
+- {Suggestion for brainstorm based on findings}
+```
+
+### Phase 4: Present & Handoff
+
+Present findings to user. Then:
+
+> "Context gathered. Ready to brainstorm solutions?"
+```
+/unipi:brainstorm <topic>
+```
+
+The brainstorm will start with this context already available — no need to re-research.
+
+---
+
+## Notes
+
+- This is a research skill — read-only, no changes
+- Subagent support enables parallel research when available
+- Findings feed directly into brainstorm — natural workflow
+- Can be run standalone for exploration, or as pre-brainstorm step
+- Output is ephemeral (in conversation) unless user requests saving

package/packages/workflow/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/packages/workflow/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