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

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

@@ -1,212 +0,0 @@
----
-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 `docs/fix/`.
-**This skill MAY NOT:** create worktrees, merge branches, deploy.
-
-## Command Format
-
-```
-the fix step 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
-
-```
-docs/fix/YYYY-MM-DD-<topic>-fix.md
-```
-
-Create the `docs/fix/` folder if it does not exist yet — it is an ordinary project folder, not a unipi store.
-
----
-
-## Process
-
-### Phase 1: Load Debug Report
-
-**If `debug:` arg provided:**
-1. Read the debug report from `docs/debug/`
-2. Understand: root cause, affected files, suggested fix, verification plan
-
-**If no debug provided:**
-1. List available debug reports in `docs/debug/`
-2. Present to user for selection (autocomplete-style)
-3. Or ask if fixing without debug report (→ suggest `a 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 `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: `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:** `docs/fix/YYYY-MM-DD-<topic>-fix.md`
-
-Suggest next steps:
-
-**If fix was straightforward:**
-```
-the consolidate step
-```
-
-**If fix revealed deeper issues:**
-> "The fix works, but I noticed {issue}. Consider:"
-```
-the issue scan focus on {area}
-```
-
-**If fix was complex:**
-> "This was a tricky fix. Consider documenting the pattern:"
-```
-the document step {area}
-```
-
----
-
-## Autocomplete Behavior
-
-When user types `the fix step 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 `a 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/packages/skill-registry/skills/gather-context/SKILL.md

@@ -1,145 +0,0 @@
----
-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
-
-```
-the context-gathering step <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.
-
-#### Save Gate
-
-If the user already specified whether to save (e.g., "save findings to memory" or "just show me"), skip this gate and follow their preference. Otherwise, ask:
-
-```
-ask_user({
-  question: "Save this context?",
-  context: "Context gathered from {N} files across {areas}. Summary includes structure, patterns, prior art, and recommendations.",
-  options: [
-    { label: "Save to memory", description: "Store findings in .unipi/memory/ for future sessions", value: "save" },
-    { label: "Save to file", description: "Write findings to docs/research/<topic>.md", value: "file" },
-    { label: "Don't save", description: "Discard — context was just for this session", value: "discard" }
-  ],
-  allowFreeform: false
-})
-```
-
-- **Save to memory:** Write findings to `.unipi/memory/` following the consolidate skill's memory file format.
-- **Save to file:** Write findings to `docs/research/<topic>.md` (Create the folder if it does not exist — it is an ordinary project folder, not a unipi store.) using the synthesis output format from Phase 3.
-- **Don't save:** Skip — findings stay in conversation only.
-
-After the save decision, hand off:
-
-> "Context gathered. Ready to brainstorm solutions?"
-```
-the brainstorm skill <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 — save gate at end of Phase 4 offers explicit save-to-memory or save-to-file

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

@@ -1,231 +0,0 @@
----
-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 [on|off|view|approve]
-```
-
-- no argument toggles plan mode; `on`/`off` are explicit, `view` shows the current
-  plan file, `approve` runs the approval path
-- scope guidance is ordinary prose in the prompt, not a command argument
-- if it is unclear which spec to plan from → ask the user
-- Runs in the current session, read-only except for the `docs/` folder
-
-## Sandbox
-
-- **Read:** full codebase access for context
-- **Write:** only the project's `docs/` folder
-
-## Output Path
-
-```
-docs/plans/YYYY-MM-DD-<topic>-plan.md
-```
-
-Create the `docs/plans/` folder if it does not exist yet — it is an ordinary project folder, not a unipi store.
-
-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 `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)
-5. **Ask about work branch:**
-
-> "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.
-
----
-
-## Phase 3: Create Implementation Plan
-
-Structure the plan with heart of gold style:
-
-```markdown
----
-title: "{Topic} — Implementation Plan"
-type: plan
-date: YYYY-MM-DD
-workbranch: {branch-name}   # empty string = work on main branch
-specs:
-  - path/to/spec.md
----
-
-# {Topic} — Implementation Plan
-
-## Overview
-{Brief summary of what this plan covers}
-
-## Tasks
-
-- unstarted: 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}
-
-- unstarted: Task 2 — {Task Name}
-  - Description: ...
-  - Dependencies: ...
-  - Acceptance Criteria: ...
-  - Steps: ...
-
-## 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)
-
-### Task Status Lifecycle
-
-Tasks use prefixes to track progress:
-
-| Status | Meaning |
-|--------|----------|
-| `unstarted:` | Not started |
-| `in-progress:` | Being worked on |
-| `completed:` | Done and verified |
-| `failed:` | Attempted but failed, needs investigation |
-| `awaiting_user:` | Needs user action (test, approve, provide input) |
-| `blocked:` | Waiting on dependency or external factor |
-| `skipped:` | Intentionally not doing (deferred, out of scope) |
-
----
-
-## 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.
-
-**Semantics:** Spec `[x]` means "planned" (covered by a plan). It does NOT mean "done". Implementation progress is tracked in the plan file, not the spec.
-
----
-
-## 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)
-- [ ] String greedy scope respected (if provided)
-- [ ] Plan is focused enough for single `the implementation step` session
-
-Do NOT re-read or re-edit the spec checkboxes — Phase 4 already wrote them.
-
----
-
-## Phase 6: Present & Handoff
-
-Present plan summary to user. Then ask what to do next. If `ask_user` is available, prefer structured handoff options using `action: "new_session"` so the selected workflow can be queued automatically:
-
-```ts
-ask_user({
-  question: "What would you like to do next?",
-  options: [
-    {
-      label: "Proceed to the implementation step",
-      description: "Start implementing the plan",
-      value: "work",
-      action: "new_session",
-      prefill: "<work-command>",
-    },
-    {
-      label: "Proceed to the full pipeline",
-      description: "Run full pipeline (work → review → merge)",
-      value: "auto",
-      action: "new_session",
-      prefill: "the full pipeline plan:YYYY-MM-DD-<topic>-plan.md",
-    },
-    { label: "Revise plan", description: "Adjust tasks or scope", value: "revise" },
-    { label: "Done for now", description: "Return later", value: "done", action: "end_turn" },
-  ],
-  allowFreeform: false,
-})
-```
-
-Use the correct `<work-command>`:
-- **Worktree branch** → `the implementation step worktree:<branch-name> specs:YYYY-MM-DD-<topic>-plan`
-- **Main branch** → `the implementation step specs:YYYY-MM-DD-<topic>-plan` (no worktree arg)
-
-Copyable fallback commands when `ask_user` is unavailable:
-```
-the implementation step worktree:<branch-name> specs:YYYY-MM-DD-<topic>-plan
-the implementation step specs:YYYY-MM-DD-<topic>-plan
-the full pipeline plan:YYYY-MM-DD-<topic>-plan.md
-```
-
-Recommend starting a **new session** for work if using a worktree; the ask_user launcher handles compact/direct queuing when available.
-
----
-
-## Resumability
-
-If plan mode starts on an existing plan:
-1. Read the plan — look for `completed:` tasks
-2. Ask user if they want to add tasks, modify existing, or plan new scope