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

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

@@ -1,135 +0,0 @@
----
-name: quick-fix
-description: "Fast bug fix without debug report. One-shot fix for clear, simple bugs. Records fixes in docs/fix/."
----
-
-# Quick Fix
-
-Fix simple bugs directly without requiring a debug report. One-shot execution for clear issues.
-
-## 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
-
-```
-a quick fix <string(greedy)>
-```
-
-- `string(greedy)` — bug description or error message
-- Full read/write sandbox
-- One shot — complete the fix in this session
-
-## 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: Understand the Bug
-
-1. Read the bug description
-2. If unclear, ask one clarifying question
-3. Assess scope — is this truly a quick fix?
-   - If complex → suggest `the debug step` first
-   - If appropriate → proceed
-
-**Exit:** Bug understood, scoped as quick fix.
-
-### Phase 2: Find and Fix
-
-1. **Locate the bug:**
-   - Search for error messages
-   - Trace the code path
-   - Find the problematic code
-
-2. **Apply fix:**
-   - Make the minimal correct change
-   - Don't refactor unless necessary
-   - Keep changes focused
-
-3. **Verify:**
-   - Confirm fix works
-   - Run tests if applicable
-   - Check for obvious regressions
-
-**Exit:** Bug fixed.
-
-### Phase 3: Write Fix Report
-
-Write to `docs/fix/YYYY-MM-DD-<topic>-fix.md`:
-
-```markdown
----
-title: "{Bug Title} — Quick Fix"
-type: quick-fix
-date: YYYY-MM-DD
----
-
-# {Bug Title} — Quick Fix
-
-## Bug
-{Description of the bug}
-
-## Root Cause
-{Brief explanation of what was wrong}
-
-## Fix
-{What was changed and why}
-
-### Files Modified
-- `{file}` — {what changed}
-
-## Verification
-{How it was tested}
-
-## Notes
-{Anything worth noting}
-```
-
-### Phase 4: Commit & Report
-
-1. Commit with descriptive message
-2. Report to user:
-
-> "Fixed. Changes committed. Report at `docs/fix/YYYY-MM-DD-<topic>-fix.md`"
-
-No further suggestions needed — this was a quick fix.
-
----
-
-## When to Use quick-fix vs debug+fix
-
-**Use quick-fix for:**
-- Clear, obvious bugs
-- Error messages that pinpoint the issue
-- Simple logic errors
-- Typos in code
-- Missing null checks
-- Wrong variable names
-
-**Use debug+fix for:**
-- Complex bugs with unclear root cause
-- Intermittent issues
-- Performance problems
-- Bugs requiring deep investigation
-- Issues affecting multiple systems
-
-When in doubt, start with quick-fix. If it gets complex, suggest switching to debug.
-
----
-
-## Notes
-
-- No debug report required — direct fix
-- Summary provides record of what was fixed
-- For complex bugs, use `the debug step` first
-- Fix reports go to same `docs/fix/` directory as regular fixes

package/packages/skill-registry/skills/quick-work/SKILL.md

@@ -1,110 +0,0 @@
----
-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 `docs/quick-work/`.
-**This skill MAY NOT:** create worktrees, merge branches, deploy.
-
-## Command Format
-
-```
-a quick work pass <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 `the brainstorm skill` 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 `docs/quick-work/YYYY-MM-DD-<topic>.md` (Create the folder if it does not exist — it is an ordinary project folder, not a unipi store.):
-
-```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 `docs/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

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

@@ -1,251 +0,0 @@
----
-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
-
-```
-the research step <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 `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?"
-```
-the brainstorm skill {topic}
-```
-
-**If research found issues:**
-> "Found some issues during research. Consider investigating:"
-```
-the debug step {issue}
-the issue scan focus on {area}
-```
-
-**If research was for documentation:**
-> "Ready to document what we found?"
-```
-the document step {topic}
-```
-
-**If research was exploratory:**
-> "Want me to save these findings?"
-- Save to `docs/generated/YYYY-MM-DD-research-{topic}.md` (Create the folder if it does not exist — it is an ordinary project folder, not a unipi store.)
-
----
-
-## 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 | `the research step` | `the context-gathering step` |
-|--------|-------------------|-------------------------|
-| 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/packages/skill-registry/skills/review-work/SKILL.md

@@ -1,187 +0,0 @@
----
-name: review-work
-description: "Review work — check task completion, run lint/build, mark reviewer remarks. Use after the implementation step completes."
----
-
-# Reviewing Work
-
-Review what was built, verify task completion, run codebase checks, add reviewer remarks.
-
-## Boundaries
-
-**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
-
-```
-the review step plan:<path>(optional) <string(greedy)>(optional)
-```
-
-- `plan:<path)` — specific plan to review (auto-suggested)
-- `string(greedy)` — scope (e.g., "only review auth tasks" or "just check builds")
-- If no plan provided → agent finds latest plan or asks user
-- Runs in current session (or worktree session if still active)
-
----
-
-## Phase 1: Load Plan & Switch Branch
-
-1. If `plan:` arg provided, read that plan
-2. If not, list plans in `docs/plans/` and ask user
-3. Read plan fully — understand tasks, acceptance criteria, current status
-4. **Read `workbranch:` from plan frontmatter:**
-   - If `workbranch:` exists and is not empty → switch to that branch/worktree
-   - If `workbranch:` missing or empty → review on current branch (main)
-   - To switch: `git checkout {workbranch}` or use worktree path
-
-**Exit:** On correct branch. Plan loaded.
-
-### Ralph Status Check
-
-If a ralph loop was used for this work (check `.unipi/ralph/` for a matching state file):
-1. Read `.unipi/ralph/{name}.state.json` — note iteration count, reflection findings
-2. Read `.unipi/ralph/{name}.md` — check checklist completion
-3. Note any items marked incomplete or abandoned across iterations
-4. Include this loop context in your reviewer remarks
-
----
-
-## Phase 2: Check Task Completion
-
-For each task in plan:
-
-1. Read acceptance criteria
-2. Verify against actual implementation
-3. Determine status:
-   - **Done** — all criteria met → `completed:`
-   - **Partially Done X/Y** — some steps complete, others not
-   - **Unstarted** — nothing done → `unstarted:`
-   - **Failed** — attempted but broken → `failed:`
-   - **Awaiting User** — needs user action → `awaiting_user:`
-   - **Blocked** — waiting on dependency → `blocked:`
-   - **Skipped** — intentionally not done → `skipped:`
-
-If `string(greedy)` scope provided, only check matching tasks.
-
----
-
-## Phase 3: Run Codebase Checks
-
-Run project's verification suite:
-
-1. **Lint** — `npm run lint` or equivalent
-2. **Type check** — `tsc --noEmit` or equivalent
-3. **Tests** — `npm test` or equivalent
-4. **Build** — `npm run build` or equivalent
-5. **Docker** — `docker build .` if Dockerfile exists
-
-Report results. If any fail:
-- Note which checks failed
-- Identify which tasks are affected
-- Don't fix — just report
-
----
-
-## Phase 4: Write Reviewer Remarks
-
-Add `REVIEWER-REMARK` at the **end of the plan document**, behind a divider:
-
-```markdown
----
-
-## Reviewer Remarks
-
-REVIEWER-REMARK: Partially Done 3/5
-- Tasks 1-3 complete, verified against acceptance criteria
-- Task 4 stuck: API endpoint returns 500, needs investigation
-- Task 5 unstarted: depends on Task 4
-
-Codebase Checks:
-- ✓ Lint passed
-- ✓ Type check passed
-- ✗ Tests failed: 2 failing in auth.test.ts
-- ✓ Build passed
-- ✓ Docker build passed
-```
-
-### Status Format
-
-```
-REVIEWER-REMARK: <Done | Partially Done X/Y | Unstarted>
-```
-
-Followed by description explaining the status.
-
----
-
-## Phase 5: Handoff
-
-Based on review results, use `ask_user` `new_session` options when available so the selected next workflow command can be queued automatically. If `ask_user` is unavailable, present the same choices conversationally and keep copyable commands visible.
-
-**If all tasks done and checks pass:**
-
-*If `workbranch` is set (worktree):*
-> "All tasks complete and verified. Ready to merge back to main."
-
-Offer:
-```ts
-ask_user({
-  question: "Merge this worktree now?",
-  options: [
-    { label: "Proceed to the implementation steptree-merge", value: "merge", action: "new_session", prefill: "the implementation steptree-merge" },
-    { label: "Consolidate learnings", value: "consolidate", action: "new_session", prefill: "the consolidate step" },
-    { label: "Done for now", value: "done", action: "end_turn" },
-  ],
-  allowFreeform: false,
-})
-```
-Copyable fallback:
-```
-the implementation steptree-merge
-```
-
-*If `workbranch` is empty (main branch):*
-> "All tasks complete and verified. Changes already on main — no merge needed."
-
-Offer `the consolidate step` as a `new_session` handoff when available. Copyable fallback:
-```
-the consolidate step
-```
-
-Either way, user can consolidate learnings:
-```
-the consolidate step
-```
-
-**If tasks incomplete or checks fail:**
-> "Tasks remaining and/or checks failing. Continue work?"
-
-Offer the applicable `the implementation step ...` command as a `new_session` handoff when available.
-
-*If `workbranch` is set:*
-```
-the implementation step worktree:<branch> specs:<plan-path>
-```
-
-*If `workbranch` is empty (main):*
-```
-the implementation step specs:<plan-path>
-```
-
-**If scoped review complete:**
-> "Scoped review complete. Run full review or continue work?"
-
-Offer both commands as `new_session` options when available:
-```
-the review step plan:<plan-path>  (full review)
-the implementation step specs:<plan-path>        (continue work)
-```
-
----
-
-## Notes
-
-- Reviewer remarks append to end of plan — don't modify existing content
-- Check results are factual — report pass/fail, don't diagnose
-- This is a checkpoint, not a fix pass — work continues via `the implementation step`