@pi-unipi/unipi 3.0.0-alpha.2 → 3.0.0-alpha.21

package/packages/skill-registry/skills/consolidate/SKILL.md

@@ -1,142 +0,0 @@
----
-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
-
-```
-the consolidate step <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 `the review step` 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/packages/skill-registry/skills/consultant/SKILL.md

@@ -1,97 +0,0 @@
----
-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
-
-```
-the consultant skill <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."
-```
-the brainstorm skill <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/skill-registry/skills/debug/SKILL.md

@@ -1,228 +0,0 @@
----
-name: debug
-description: "Active bug investigation — reproduce, diagnose, root-cause analysis. Produces debug report for the fix step."
----
-
-# Debugging
-
-Active investigation to reproduce, diagnose, and root-cause bugs. Produces a structured debug report that `the fix step` can consume.
-
-## Boundaries
-
-**This skill MAY:** read codebase, run diagnostic commands, spawn subagents, write debug report to `docs/debug/`.
-**This skill MAY NOT:** edit code, fix issues, run tests that modify state, deploy.
-
-**Write-permission clarification:** "Read-only" means source/project code is read-only for diagnosis. It does **not** prohibit creating or updating the debug report. The agent should use available file-writing tools to write exactly the report under `docs/debug/`. If writing that report fails, report the write failure explicitly.
-
-**This is diagnosis only — not fixing.**
-
-## Command Format
-
-```
-the debug step <string(greedy)>
-```
-
-- `string(greedy)` — bug description, error message, or reproduction steps
-- Source/code read-only sandbox, with explicit permission to write the debug report to `docs/debug/`
-- Spawns subagents if `@unipi/subagents` extension is installed
-
-## Output Path
-
-```
-docs/debug/YYYY-MM-DD-<topic>-debug.md
-```
-
-Create the `docs/debug/` folder if it does not exist yet — it is an ordinary project folder, not a unipi store.
-
----
-
-## 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 `docs/debug/YYYY-MM-DD-<topic>-debug.md` using the available file-writing tool. Do not skip this because the investigation is otherwise read-only:
-
-```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 `docs/debug/YYYY-MM-DD-<topic>-debug.md`"
-> 
-> **Root Cause:** {brief summary}
-> **Suggested Fix:** {brief summary}
-
-Then suggest:
-
-**If root cause found:**
-```
-the fix step debug:YYYY-MM-DD-<topic>-debug
-```
-
-**If needs more investigation:**
-> "Root cause unclear. Need to investigate {area} further."
-```
-the context-gathering step {area}
-```
-
-**If unreproducible:**
-> "Cannot reproduce with current steps. Can you provide more details?"
-- Wait for user input
-
----
-
-## Differences from scan-issues
-
-| Aspect | `the debug step` | `the issue scan` |
-|--------|----------------|----------------------|
-| 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 | `the fix step` | `a quick work pass` or `the brainstorm skill` |
-
----
-
-## Notes
-
-- Diagnosis only — fixes happen via `the fix step`
-- Debug reports are reusable — `the fix step` can autocomplete them
-- Subagent support enables parallel code path tracing
-- Always document the failure chain — helps verify fixes
-- If bug is complex, suggest `the consultant skill` for expert analysis

package/packages/skill-registry/skills/document/SKILL.md

@@ -1,120 +0,0 @@
----
-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 `docs/generated/`.
-**This skill MAY NOT:** edit source code, run tests, implement features.
-
-## Command Format
-
-```
-the document step <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: `docs/generated/` in markdown (Create the folder if it does not exist — it is an ordinary project folder, not a unipi store.)
-
----
-
-## 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 `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 `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
-- `docs/generated/` keeps generated docs separate from hand-written ones
-- Can document code, features, architecture, or processes
-- Natural extension of gather-context — research then document