@pi-unipi/workflow 0.1.0

package/skills/brainstorm/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: brainstorm
+description: "Collaborative discovery — explore problem space, evaluate approaches, write design spec. Use before any creative work."
+---
+
+# Brainstorming Ideas Into Designs
+
+Turn ideas into fully formed designs through collaborative dialogue.
+
+## Boundaries
+
+**This skill MAY:** research (read-only), discuss, ask questions, write the brainstorm document.
+**This skill MAY NOT:** edit code, create files beyond the brainstorm document, run tests, deploy, implement anything.
+
+**NEVER write code during this skill. This is a discussion, not implementation.**
+
+## Command Format
+
+```
+/unipi:brainstorm <string(greedy)>
+```
+
+- `string(greedy)` — the topic or problem to brainstorm about
+- No worktree args — brainstorm runs in current session on current branch
+- No visual companion — text-only brainstorming
+
+## Hard Gate
+
+Do NOT write any code, scaffold any project, or take any implementation action until design is presented and user approved. This applies to EVERY project regardless of perceived simplicity.
+
+## Anti-Pattern: "Too Simple For Design"
+
+Every project goes through this process. A todo list, a utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause wasted work. Design can be short, but MUST present and get approval.
+
+## Output Path
+
+```
+.unipi/docs/specs/YYYY-MM-DD-<topic>-design.md
+```
+
+Committed to current branch. Accessible across worktrees via git.
+
+---
+
+## Phase 1: Explore Project Context
+
+1. Check files, docs, recent commits to understand current state
+2. Assess scope: if request describes multiple independent subsystems, flag immediately
+3. If too large for single spec, help decompose into sub-projects
+
+**Exit:** Context gathered. Ready to ask questions.
+
+---
+
+## Phase 2: Ask Clarifying Questions
+
+Ask **one question at a time**. Don't dump a questionnaire.
+
+Start with:
+1. "What problem are we actually solving?" — strip assumptions, get root need
+2. "Who has this problem and when?" — context changes solutions
+3. "What does success look like?" — outcomes, not features
+
+Prefer multiple choice when natural options exist. Validate assumptions explicitly.
+
+**Exit:** Problem statement clear and reframed. Both agree on what solving.
+
+---
+
+## Phase 3: Propose Approaches
+
+Propose 2-3 different approaches with trade-offs:
+- What each optimizes for (speed, flexibility, simplicity)
+- What each costs (complexity, maintenance, time, risk)
+- Prior art in codebase or industry
+
+Present conversationally with recommendation and reasoning.
+
+**If open questions emerge:** MUST ask user about each one. Don't assume.
+
+**Exit:** Approach chosen. User signals decision.
+
+---
+
+## Phase 4: Present Design
+
+Once approach chosen, present design in sections:
+- Scale each section to complexity (few sentences if straightforward, 200-300 words if nuanced)
+- Ask after each section whether it looks right
+- Cover: architecture, components, data flow, error handling, testing
+- Be ready to go back and clarify
+
+**Design for isolation and clarity:**
+- Break into smaller units with one clear purpose
+- Each unit communicates through well-defined interfaces
+- Can someone understand unit without reading internals?
+
+**Exit:** Design approved by user.
+
+---
+
+## Phase 5: Write Design Document
+
+Write to `.unipi/docs/specs/YYYY-MM-DD-<topic>-design.md`:
+
+```markdown
+---
+title: "{Topic}"
+type: brainstorm
+date: YYYY-MM-DD
+---
+
+# {Topic}
+
+## Problem Statement
+{The actual problem, reframed}
+
+## Context
+{Key findings — what exists, what's been tried}
+
+## Chosen Approach
+{High-level description}
+
+## Why This Approach
+{Decision rationale, alternatives rejected}
+
+## Design
+{Architecture, components, data flow}
+
+## Implementation Checklist
+- [ ] Task 1 — description
+- [ ] Task 2 — description
+- [ ] Task 3 — description
+
+## Open Questions
+{Questions for planning phase}
+
+## Out of Scope
+{Explicitly excluded}
+```
+
+### Checklist Items
+
+The `## Implementation Checklist` section uses `- [ ]` markdown checkboxes. These are critical:
+
+- **`[ ]` = unplanned** — not yet covered by a plan
+- **`[x]` = planned** — marked when `/unipi:plan` covers this item
+- Agent MUST fill in checklist items based on the design
+- Each item should be a discrete, implementable task
+- Items should be ordered by dependency (earlier items don't depend on later ones)
+
+---
+
+## Phase 6: Spec Self-Review
+
+After writing, review with fresh eyes:
+
+1. **Placeholder scan:** Any "TBD", "TODO", incomplete sections? Fix them.
+2. **Internal consistency:** Do sections contradict each other?
+3. **Scope check:** Focused enough for single implementation plan?
+4. **Ambiguity check:** Could any requirement be interpreted two ways? Pick one.
+
+Fix issues inline. No need to re-review — fix and move on.
+
+---
+
+## Phase 7: User Review Gate
+
+After self-review passes:
+
+> "Spec written and committed to `.unipi/docs/specs/YYYY-MM-DD-<topic>-design.md`. Please review and let me know if you want changes before we plan."
+
+Wait for user response. If changes requested, make them and re-run self-review.
+
+---
+
+## Phase 8: Handoff
+
+Ask user what to do next:
+
+1. **Proceed to /unipi:plan** — Turn decisions into implementation plan
+2. **Keep exploring** — More questions or refine decisions
+3. **Done for now** — Return later
+
+If user selects "Proceed to /unipi:plan", suggest:
+```
+/unipi:plan specs:YYYY-MM-DD-<topic>-design
+```
+
+---
+
+## Validate
+
+Before delivering, verify:
+
+- [ ] Problem was reframed — not accepted at face value
+- [ ] At least 2 approaches explored with tradeoffs
+- [ ] Every decision has rationale and rejected alternatives documented
+- [ ] Implementation checklist has concrete, discrete tasks with `[ ]` markers
+- [ ] Open questions listed — nothing swept under rug
+- [ ] No code was written — only brainstorm document created
+- [ ] `/unipi:plan` can start from this document without asking "what did you decide about X?"

package/skills/consolidate/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: consolidate
+description: "Consolidate — save learnings to memory, craft skills if reusable. Use at end of work session or to summarize current state."
+---
+
+# Consolidating Learnings
+
+Capture what was learned, update memory, and craft skills when patterns emerge.
+
+## Boundaries
+
+**This skill MAY:** read/write `.unipi/memory/`, read session context, read plans/specs, write skill files if user approves.
+**This skill MAY NOT:** edit production code, run tests, deploy.
+
+## Command Format
+
+```
+/unipi:consolidate <string(greedy)>(optional)
+```
+
+- `string(greedy)` — optional focus (e.g., "focus on auth patterns" or "summarize what we learned about testing")
+- Two modes: **end-of-work** (memory + registry hooks) or **start/middle** (read context, consolidate ideas)
+
+---
+
+## Mode 1: End of Work Session
+
+Triggered when run after `/unipi:review-work` marks work as done.
+
+### Phase 1: Gather Learnings
+
+1. Read session context — what was discussed, decided, built
+2. Read the plan and spec — what was the goal, what was achieved
+3. Identify key learnings:
+   - Patterns discovered
+   - Decisions made and why
+   - Problems encountered and solutions
+   - Things that would be done differently
+   - Reusable approaches
+
+**Exit:** Learnings identified.
+
+### Phase 2: Update Memory
+
+1. Check if `@unipi/memory` extension is installed
+2. If not installed → skip memory, note to user
+3. If installed:
+   - Read existing `.unipi/memory/` files
+   - Find relevant memory files (by topic, date, or tag)
+   - **Update in place** — don't always create new files
+   - Merge new learnings with existing knowledge
+   - Prevent stale data by updating, not appending
+
+**Memory file format:**
+```markdown
+---
+topic: {topic}
+updated: YYYY-MM-DD
+tags: [tag1, tag2]
+---
+
+# {Topic}
+
+## Key Learnings
+- {Learning 1}
+- {Learning 2}
+
+## Patterns
+- {Pattern description}
+
+## Decisions
+- {Decision} — {Rationale}
+```
+
+**Exit:** Memory updated.
+
+### Phase 3: Skill Crafting
+
+1. Check if `@unipi/registry` extension is installed
+2. If not installed → skip, note to user
+3. If installed, assess if learnings are reusable:
+
+**Auto-create skill if:**
+- Pattern will definitely be used in future runs
+- Solution applies to recurring problem
+- Workflow could be standardized
+
+**Ask user if uncertain:**
+> "I discovered a pattern that might be worth capturing as a skill: {description}. Should I create a skill for this?"
+
+**Skip if:**
+- One-off solution, unlikely to recur
+- Too specific to current context
+- User declines
+
+**Exit:** Skill created or skipped.
+
+### Phase 4: Summary
+
+Report to user:
+- What was saved to memory
+- What skills were created (if any)
+- Suggest next steps if any work remains
+
+---
+
+## Mode 2: Start / Middle of Session
+
+Triggered when run without prior work session context.
+
+### Phase 1: Read Context
+
+1. Read session conversation so far
+2. OR read latest brainstorm/spec/plan
+3. Understand current state — what's been discussed, what's decided
+
+### Phase 2: Consolidate Ideas
+
+1. Summarize key points from context
+2. Identify open questions
+3. Identify decisions made
+4. Identify next steps
+
+### Phase 3: Write Summary
+
+Write consolidation to `.unipi/memory/` — same format as Mode 1.
+
+### Phase 4: Present
+
+Present summary to user. Ask:
+1. **Continue to brainstorm** — if ideas need formalizing
+2. **Continue to plan** — if decisions are clear
+3. **Done** — summary captured, return later
+
+---
+
+## Notes
+
+- Memory files are living documents — update, don't always create new
+- Skill creation is opportunistic — only when pattern is clearly reusable
+- Both modes write to `.unipi/memory/` — consistent location
+- Respects extension availability — graceful degradation if extensions not installed

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