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

package/packages/skill-registry/skills/scan-issues/SKILL.md

@@ -1,195 +0,0 @@
----
-name: scan-issues
-description: "Passive codebase scan — find potential bugs, anti-patterns, security issues. Spawns subagents if available."
----
-
-# Scanning for Issues
-
-Passive investigation of codebase to find potential bugs, anti-patterns, security issues, and technical debt.
-
-## Boundaries
-
-**This skill MAY:** read codebase, run read-only analysis commands, spawn subagents, write findings.
-**This skill MAY NOT:** edit code, fix issues, run tests that modify state, deploy.
-
-**This is investigation only — not fixing.**
-
-**Note:** For active debugging of specific bugs, use `the debug step` instead. scan-issues finds potential problems; debug diagnoses known issues.
-
-## Command Format
-
-```
-the issue scan <string(greedy)>(optional)
-```
-
-- `string(greedy)` — optional scope (e.g., "focus on auth", "check for SQL injection", "find dead code")
-- If not provided → full codebase scan
-- Read-only sandbox
-- Spawns subagents if `@unipi/subagents` extension is installed
-
----
-
-## Process
-
-### Phase 1: Determine Scope
-
-**If scope provided:**
-1. Parse the focus area
-2. Determine scan type:
-   - Security scan
-   - Bug hunt
-   - Anti-pattern detection
-   - Tech debt assessment
-   - Performance issues
-
-**If no scope:**
-1. Ask user what to focus on, or
-2. Run broad scan covering all categories
-
-**Exit:** Scope defined.
-
-### Phase 2: Deep Investigation
-
-If subagents available:
-1. Spawn parallel subagents for different scan types
-2. Each subagent investigates independently
-3. Collect findings from all subagents
-
-If no subagents:
-1. Investigate sequentially
-2. Use grep, find, read commands
-3. Build findings incrementally
-
-**Scan categories:**
-
-**Security:**
-- Hardcoded secrets/credentials
-- SQL injection vulnerabilities
-- XSS vulnerabilities
-- Insecure dependencies
-- Missing input validation
-- Exposed sensitive data
-
-**Bugs:**
-- Null/undefined handling
-- Race conditions
-- Error handling gaps
-- Edge cases missed
-- Logic errors
-- Off-by-one errors
-
-**Anti-patterns:**
-- Code duplication
-- God objects/functions
-- Circular dependencies
-- Tight coupling
-- Magic numbers/strings
-- Inconsistent patterns
-
-**Tech debt:**
-- TODO/FIXME comments
-- Deprecated API usage
-- Outdated dependencies
-- Dead code
-- Missing tests
-- Poor naming
-
-**Performance:**
-- N+1 queries
-- Unnecessary re-renders
-- Large bundle imports
-- Missing caching
-- Inefficient algorithms
-
-**Exit:** Findings collected.
-
-### Phase 3: Categorize & Prioritize
-
-Organize findings by severity:
-
-**Critical (P0):**
-- Security vulnerabilities
-- Data loss risks
-- Production-breaking bugs
-
-**High (P1):**
-- Significant bugs
-- Major anti-patterns
-- Performance bottlenecks
-
-**Medium (P2):**
-- Minor bugs
-- Tech debt
-- Code smells
-
-**Low (P3):**
-- Style issues
-- Minor improvements
-- Nice-to-haves
-
-### Phase 4: Present Findings
-
-```markdown
-## Issue Scan Results
-
-### Critical (P0)
-- {Finding} — {file:line} — {description}
-
-### High (P1)
-- {Finding} — {file:line} — {description}
-
-### Medium (P2)
-- {Finding} — {file:line} — {description}
-
-### Low (P3)
-- {Finding} — {file:line} — {description}
-
-### Summary
-- Total issues: {count}
-- Critical: {count}
-- High: {count}
-- Medium: {count}
-- Low: {count}
-```
-
-### Phase 5: Handoff
-
-Based on findings:
-
-**If critical issues found:**
-> "Critical issues found. Recommend addressing immediately."
-```
-a quick work pass "fix critical security issue in auth.ts"
-```
-
-**If many issues:**
-> "Multiple issues found. Consider planning a cleanup sprint."
-```
-the brainstorm skill "tech debt cleanup plan"
-```
-
-**If few/no issues:**
-> "Codebase looks healthy. No critical issues found."
-```
-the consolidate step
-```
-
----
-
-## Notes
-
-- Investigation only — findings are reported, not fixed
-- Subagent support enables parallel scanning when available
-- Can focus on specific categories or scan broadly
-- Prioritized findings help triage what to fix first
-- Natural lead-in to quick-work (for critical) or brainstorm (for planned cleanup)
-
-## Differences from debug
-
-| Aspect | `the issue scan` | `the debug step` |
-|--------|----------------------|----------------|
-| Purpose | Find potential issues | Investigate specific bug |
-| Input | Scope / category | Bug report / error message |
-| Output | Issue list with priorities | Debug report with root cause |
-| Depth | Broad codebase scan | Deep single-issue analysis |
-| Handoff | `a quick work pass` or `the brainstorm skill` | `the fix step` |

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

@@ -1,218 +0,0 @@
----
-name: work
-description: "Execute plan — implement tasks, test, commit on done. Works in worktree or on main branch. Resumable."
----
-
-# Executing Plans
-
-Load plan, review critically, execute tasks, commit when complete.
-
-## Boundaries
-
-**This skill MAY:** read/write code, read/write the project's `docs/`, run tests, commit, create worktree.
-**This skill MAY NOT:** merge branches, deploy.
-
-**Worktree vs Main:**
-- If `workbranch` in plan → work within worktree directory
-- If `workbranch` empty → work directly on main branch (current directory)
-
-## Command Format
-
-```
-the implementation step worktree:<branch>(optional) specs:<path>(multiple,optional) <string(greedy)>(optional)
-```
-
-- `worktree:<branch>` — branch to work on (auto-suggested, agent asks if not provided)
-- `specs:<path>` — plan(s) to execute (auto-suggested, agent asks if not provided)
-- `string(greedy)` — scope guidance (e.g., "only task 1 and 2")
-- **Recommended: new session** — this command switches pi's internal worktree
-
-## Sandbox
-
-- **Read/Write:** full access within worktree (or project root if on main)
-- **Write:** `docs/` in the project for progress tracking (Create the folder if it does not exist — it is an ordinary project folder, not a unipi store.)
-
----
-
-## Phase 1: Resolve Args
-
-1. **Specs:**
-   - If `specs:` arg provided, read those plan files
-   - If not, list available plans in `docs/plans/` and ask user
-   - Can select multiple
-
-2. **Read `workbranch` from plan frontmatter:**
-   - If `workbranch:` is **non-empty** → use that branch/worktree
-     - If worktree arg also provided → use worktree arg (override)
-     - Create worktree if not exists: `git worktree add .unipi/worktrees/{branch} -b {branch}`
-     - Work within worktree directory
-   - If `workbranch:` is **empty or missing** → work on current branch (main)
-     - No worktree creation needed
-     - Edit files directly in project root
-   - If neither plan nor args specify branch → ask user:
-     > "Where should this work happen?"
-     > 1. Current branch (main)
-     > 2. New worktree (provide branch name)
-
-3. **Scope:**
-   - If `string(greedy)` provided, use to scope tasks
-   - Otherwise execute all incomplete tasks
-
-**Exit:** Branch/worktree resolved. Plan(s) loaded. Scope defined.
-
----
-
-## Phase 2: Review Plan
-
-1. Read plan file(s)
-2. Review critically — identify questions or concerns
-3. If concerns: raise with user before starting
-4. Identify task status: `unstarted:` (pending), `in-progress:` (started), `completed:` (done), `failed:` (needs investigation), `awaiting_user:` (needs user action), `blocked:` (waiting on dependency), `skipped:` (deferred)
-
-**Exit:** Plan reviewed, ready to execute.
-
-### Ralph Loop Decision
-
-Count the non-completed tasks (`unstarted:`, `in-progress:`, `failed:`). If you have the `ralph_start` tool available and 3+ non-trivial tasks remain, consider a ralph loop for resilience:
-
-```
-ralph_start({
-  name: "{plan-topic}",
-  taskContent: "# {Plan Title}\n\n{overview}\n\n## Goals\n- {goal1}\n- {goal2}\n\n## Checklist\n- [ ] {task1}\n- [ ] {task2}\n- [ ] {task3}",
-  maxIterations: 50,
-  itemsPerIteration: 2,
-  reflectEvery: 5
-})
-```
-
-**To skip:** Just proceed to Phase 3 and execute tasks directly. Ralph is a helper, not a requirement.
-
----
-
-## Phase 3: Execute Tasks
-
-For each task in order, skip `completed:`, `skipped:`, and `awaiting_user:` tasks:
-
-### If `unstarted:`
-1. Change `unstarted:` to `in-progress:` in plan
-2. Follow each step exactly (plan has bite-sized steps)
-3. Run verifications as specified in acceptance criteria
-4. Change `in-progress:` to `completed:` when complete
-5. Update plan file with progress
-
-### If `in-progress:`
-1. Continue from where it left off
-2. Follow remaining steps
-3. Change to `completed:` when done
-
-### If `failed:`
-1. Read failure notes
-2. Investigate root cause
-3. Fix and re-verify
-4. Change to `completed:` when fixed, or keep `failed:` if still broken
-
-### If `awaiting_user:`
-1. Remind user what's needed
-2. Wait for user response
-3. Resume when user provides input
-
-### If `blocked:`
-1. Check if blocker is resolved
-2. If resolved → change to `unstarted:` and continue
-3. If still blocked → skip and move to next task
-
-### When to Stop and Ask
-
-**STOP immediately when:**
-- Hit blocker (missing dependency, test fails, instruction unclear)
-- Plan has critical gaps
-- You don't understand an instruction
-- Verification fails repeatedly
-
-Ask for clarification rather than guessing.
-
-### When to Revisit Earlier Steps
-
-**Return to review when:**
-- Partner updates plan based on feedback
-- Fundamental approach needs rethinking
-
-Don't force through blockers — stop and ask.
-
----
-
-## Phase 4: Commit Progress
-
-After each task or group of tasks:
-1. Stage changes
-2. Commit with descriptive message referencing task name
-3. Continue to next task
-
-Don't wait until end to commit — incremental commits are safer.
-
----
-
-## Phase 5: Complete
-
-When all tasks are `completed:`:
-
-1. Run final verification (tests, lint, build)
-2. Commit all remaining changes
-3. If using a ralph loop, emit `COMPLETE` and call `ralph_done` to cleanly exit
-4. Inform user based on branch strategy:
-
-**If working in worktree:**
-> "All tasks complete. Worktree: `{branch}`. Recommend reviewing before merge."
-
-If `ask_user` is available, offer an automatic handoff:
-```ts
-ask_user({
-  question: "Review this work now?",
-  options: [
-    {
-      label: "Proceed to the review step",
-      description: "Review before merge",
-      value: "review",
-      action: "new_session",
-      prefill: "the review step plan:<plan-path>",
-    },
-    { label: "Done for now", value: "done", action: "end_turn" },
-  ],
-  allowFreeform: false,
-})
-```
-Copyable fallback:
-```
-the review step plan:<plan-path>
-```
-**Recommend starting a new session** for review; the ask_user launcher can compact/direct queue the command.
-
-**If working on main branch:**
-> "All tasks complete. All changes committed directly on main."
-
-If `ask_user` is available, offer the same review handoff with `prefill: "the review step plan:<plan-path>"`. Copyable fallback:
-```
-the review step plan:<plan-path>
-```
-No merge needed — changes already on main.
-
----
-
-## Resumability
-
-If user runs `the implementation step` and plan has `completed:` or `in-progress:` tasks:
-1. Read plan
-2. Identify first `unstarted:` task
-3. Ask user: "Resume from Task N: {name}?"
-4. Continue from there
-
-If user provides scope string, only execute matching tasks.
-
----
-
-## Notes
-
-- Agent reads plan on start — finds what's incomplete
-- Worktree: changes don't affect main branch until merge (skip for small tasks)
-- Main branch: changes committed directly, no merge needed
-- Each worktree session is independent — no coordination with other worktrees

package/packages/skill-registry/skills/worktree-create/SKILL.md

@@ -1,69 +0,0 @@
----
-name: worktree-create
-description: "Create git worktree for parallel work. Agent-driven naming."
----
-
-# Creating Worktrees
-
-Create a git worktree for isolated parallel work.
-
-## Boundaries
-
-**This skill MAY:** run git worktree commands, ask user for branch name, suggest names.
-**This skill MAY NOT:** edit code, run tests, implement features.
-
-## Command Format
-
-```
-the implementation steptree-create <string(greedy)>
-```
-
-- `string(greedy)` — description or desired branch name
-- Agent asks user for exact name or suggests based on description
-
----
-
-## Process
-
-### Phase 1: Parse Input
-
-1. Read the string input
-2. Assess if it's a branch name or a description:
-   - Branch name: `feat/auth`, `fix/login-bug` → use directly
-   - Description: "add user authentication" → suggest name
-
-### Phase 2: Name Resolution
-
-**If clear branch name:**
-> "Creating worktree on branch `feat/auth`. Confirm?"
-
-**If description:**
-> "Based on your description, I suggest: `feat/user-auth`. What name would you like?"
-
-Let user confirm or provide different name.
-
-### Phase 3: Create Worktree
-
-1. Check if branch already exists (local or remote)
-2. If exists: ask user if they want to reuse or create new
-3. Create worktree:
-   ```bash
-   git worktree add .unipi/worktrees/<branch> -b <branch>
-   ```
-4. Verify creation succeeded
-
-### Phase 4: Confirm
-
-Report:
-> "Worktree created: `.unipi/worktrees/<branch>` (branch: `<branch>`)"
-> "To work in this worktree: `the implementation step worktree:<branch> specs:<plan>`"
-
----
-
-## Notes
-
-- Worktrees stored in `.unipi/worktrees/` directory
-- Each worktree is a full working copy with its own branch
-- Multiple worktrees can exist for parallel work
-- Use `the implementation steptree-list` to see all worktrees
-- Use `the implementation steptree-merge` to merge back to main

package/packages/skill-registry/skills/worktree-list/SKILL.md

@@ -1,78 +0,0 @@
----
-name: worktree-list
-description: "List all unipi worktrees. Shows branch, path, and status."
----
-
-# Listing Worktrees
-
-List all git worktrees created by unipi.
-
-## Boundaries
-
-**This skill MAY:** read filesystem (ls, read), grep for git info.
-**This skill MAY NOT:** edit anything, create worktrees, merge branches, run bash.
-
-## Command Format
-
-```
-the implementation steptree-list
-```
-
-No arguments. Lists all unipi worktrees.
-
----
-
-## Process
-
-### Phase 1: Discover Worktrees
-
-1. `ls .unipi/worktrees/` — list worktree directories
-2. For each directory:
-   - Read `.unipi/worktrees/<branch>/.git` file to get gitdir path
-   - Check for uncommitted changes: `ls .unipi/worktrees/<branch>/` and read key files
-3. If `.unipi/worktrees/` doesn't exist or is empty → no worktrees
-
-**Exit:** List of worktrees discovered.
-
-### Phase 2: Determine Status
-
-For each worktree directory:
-
-1. Check if `HEAD` file exists in gitdir
-2. Check for modified files by reading directory listing
-3. Determine status:
-   - **clean** — no uncommitted changes
-   - **dirty** — has uncommitted changes
-
-### Phase 3: Present
-
-Display in table format:
-
-```
-Worktrees:
-┌──────────────────┬────────────────────────────────┬─────────┐
-│ Branch           │ Path                           │ Status  │
-├──────────────────┼────────────────────────────────┼─────────┤
-│ feat/auth        │ .unipi/worktrees/feat/auth     │ clean   │
-│ fix/login-bug    │ .unipi/worktrees/fix/login-bug │ dirty   │
-└──────────────────┴────────────────────────────────┴─────────┘
-```
-
-If no worktrees:
-> "No unipi worktrees. Create one with `the implementation steptree-create`"
-
-### Phase 4: Suggest Actions
-
-Based on state:
-- If dirty worktrees exist → suggest reviewing or committing
-- If clean worktrees exist → suggest working or merging
-- Always available: `the implementation steptree-create`, `the implementation steptree-merge`
-
----
-
-## Notes
-
-- Only shows worktrees under `.unipi/worktrees/`
-- Ignores worktrees in other locations
-- Status: `clean` = no uncommitted changes, `dirty` = has changes
-- No bash required — uses ls, read, grep for all discovery

package/packages/skill-registry/skills/worktree-merge/SKILL.md

@@ -1,89 +0,0 @@
----
-name: worktree-merge
-description: "Merge worktree branches back to main. Gathers context from specs/plans, merges, cleans up."
----
-
-# Worktree Merge
-
-Merge completed worktree branches into main. Gather context from docs before merging.
-
-**Note:** Only needed when work was done in a worktree (plan `workbranch` set). If work was on main branch directly, skip this — changes already on main.
-
-## Process
-
-### Phase 1: Gather Context
-
-Before merging, read existing specs and plans to understand what each worktree was implementing:
-
-1. Read all files in `docs/specs/` (if exists)
-2. Read all files in `docs/plans/` (if exists)
-3. Build a map: branch → what it was working on
-
-This context helps during merge conflicts and in the final report.
-
-### Phase 2: Resolve Target Branch
-
-1. Check for `main` branch: `git branch --list main`
-2. If not found, check `master`: `git branch --list master`
-3. If neither exists, ask user for target branch
-
-### Phase 3: Resolve Source Branches
-
-**If branches provided in args:**
-- Verify each branch exists: `git branch --list <name>`
-- Check worktree status for each
-
-**If no branches provided:**
-- List all worktrees: `git worktree list`
-- Filter to `.unipi/worktrees/` paths only
-- Show each with status (clean/dirty via `git status`)
-- Ask user which to merge
-
-### Phase 4: Merge Each Branch
-
-For each source branch (in dependency order if specs indicate ordering):
-
-1. **Checkout target:** `git checkout main`
-2. **Merge:** `git merge <branch> --no-edit`
-3. **If conflict:**
-   - Report which files conflict
-   - Reference the spec/plan context: "This branch was working on: <description>"
-   - **Structured conflict resolution:**
-     1. **Check finalized plan** — read the plan for this branch, understand intended changes
-     2. **Brainstorm resolution** — reason about which changes align with the plan's intent
-     3. **Read codebase** — read the conflicting files to understand current state
-     4. **Ask user** — present options and ask for final decision (always ask, never force)
-   - Options to present:
-     - Accept incoming (their changes)
-     - Accept current (main branch)
-     - Manual merge (describe what each side does, ask user to decide)
-     - Skip this branch
-4. **If success:**
-   - Remove worktree: `git worktree remove .unipi/worktrees/<branch-name>`
-   - Delete branch: `git branch -d <branch>`
-   - Log success with context: "Merged: <what it was doing>"
-
-### Phase 5: Report
-
-```
-Merge Summary:
-✓ feat/auth — merged (auth system implementation from specs/auth-system.md)
-✓ fix/login-bug — merged (login fix from plans/bugfix-login.md)
-✗ feat/dashboard — CONFLICT in src/dashboard.ts, skipped
-
-Worktrees cleaned: 2 removed
-Branches deleted: 2
-```
-
-### Phase 6: Suggest Next
-
-- If all merged cleanly → suggest `the consolidate step` to save learnings
-- If conflicts remain → suggest resolving and retrying `the implementation steptree-merge`
-- If specs/plans exist for merged work → suggest `the document step` to update docs
-
-## Important
-
-- ALWAYS read specs/plans before merging — context prevents bad conflict resolution
-- NEVER force push or force merge
-- Ask user before destructive operations (branch deletion)
-- If a worktree has uncommitted changes, warn and skip

package/packages/subagents/agents/delegate.md

@@ -1,14 +0,0 @@
----
-name: delegate
-description: Lightweight subagent that inherits the parent model with no default reads
-systemPromptMode: append
-inheritProjectContext: true
-tools: read, grep, find, ls, bash, edit, write, contact_supervisor
-inheritSkills: false
----
-
-You are a delegated agent. Execute the assigned task using the provided tools. Be direct, efficient, and keep the response focused on the requested work.
-
-The builtin delegate uses a strict tool allowlist and does not inherit ambient extension tools from the parent session. To use an extension tool, configure a custom agent with the tool name explicitly listed in `tools` and load its provider through `extensions` or `subagentOnlyExtensions`.
-
-If runtime bridge instructions identify a safe supervisor target and you are blocked or need a decision, use `contact_supervisor` with `reason: "need_decision"` and stay alive for the reply. Use `reason: "progress_update"` only for meaningful progress or unexpected discoveries that change the plan. Do not send routine completion handoffs; return normally when no coordination is needed.