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

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

@@ -1,465 +0,0 @@
----
-name: auto
-description: "Full pipeline — brainstorm → plan → work → review → merge. One command, end to end."
----
-
-# Auto Pipeline
-
-Run the complete development pipeline from idea to merged code. This skill is self-contained — it includes all the logic needed to execute each phase without loading other skills.
-
-## Command Format
-
-```
-the full pipeline <string(greedy)>(optional) plan:<path>(optional) specs:<path>(optional)
-```
-
-- `string(greedy)` — what to build (triggers full pipeline from brainstorm)
-- `plan:<path>` — existing plan to execute (skips brainstorm + plan, starts at work)
-- `specs:<path>` — existing spec to plan from (skips brainstorm, starts at plan)
-- No args → ask user what to do
-
-## Pipeline Stages
-
-```
-brainstorm → plan → work → review → merge
-```
-
-Each phase must complete before the next begins. User can intervene at any gate.
-
----
-
-## Phase 1: Determine Entry Point
-
-Based on args:
-
-**If `string(greedy)` provided (no plan/specs):**
-→ Start at Phase 2 (Brainstorm). Full pipeline.
-
-**If `specs:<path>` provided (no plan):**
-→ Start at Phase 3 (Plan). Skip brainstorm.
-
-**If `plan:<path>` provided:**
-→ Start at Phase 4 (Work). Skip brainstorm + plan.
-
-**If no args:**
-→ Ask user:
-1. "What do you want to build?" → brainstorm
-2. "I have a spec, plan from it" → provide spec path
-3. "I have a plan, execute it" → provide plan path
-4. "I have a plan, just review + merge" → provide plan path
-
-**Exit:** Entry point determined. Pipeline scope clear.
-
----
-
-## Phase 2: Brainstorm
-
-### 2.1: Explore Context
-
-1. Run read-only commands to understand current state:
-   ```
-   find . -type f -name "*.ts" | head -20
-   ls -la src/
-   cat package.json
-   git log --oneline -10
-   ```
-2. Identify relevant files and patterns
-3. Note existing conventions
-
-### 2.2: Ask Clarifying Questions
-
-Ask **one question at a time**:
-1. "What problem are we actually solving?"
-2. "Who has this problem and when?"
-3. "What does success look like?"
-
-Prefer multiple choice when natural options exist.
-
-### 2.3: Propose Approaches
-
-Propose 2-3 approaches with trade-offs:
-- What each optimizes for (speed, flexibility, simplicity)
-- What each costs (complexity, maintenance, time)
-- Recommendation with reasoning
-
-Present conversationally. Ask user to choose.
-
-### 2.4: Design
-
-Once approach chosen, present design in sections:
-- Architecture / components
-- Data flow
-- Error handling
-- Testing approach
-
-Ask after each section if it looks right.
-
-### 2.5: Write Spec
-
-Create `docs/specs/YYYY-MM-DD-<topic>-design.md` (Create the folder if it does not exist — it is an ordinary project folder, not a unipi store.):
-
-```markdown
----
-title: "{Topic}"
-type: brainstorm
-date: YYYY-MM-DD
----
-
-# {Topic}
-
-## Problem Statement
-{The actual problem, reframed}
-
-## Context
-{Key findings from exploration}
-
-## 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}
-```
-
-### 2.6: Self-Review
-
-Before presenting:
-1. Any "TBD", "TODO", incomplete sections? Fix them.
-2. Do sections contradict each other?
-3. Could any requirement be interpreted two ways? Pick one.
-
-### 2.7: Design Gate
-
-> "Spec written to `docs/specs/YYYY-MM-DD-<topic>-design.md`. Please review and let me know if you want changes before we plan."
-
-**WAIT for user approval.** If changes requested, make them and re-review.
-
-**Exit:** User approves design. Proceed to Phase 3.
-
----
-
-## Phase 3: Plan
-
-### 3.1: Load Spec
-
-1. Read the spec file (from Phase 2 or from `specs:` arg)
-2. Understand: problem, approach, design, checklist
-
-### 3.2: Ask Clarifying Questions
-
-1. Review spec critically — identify concerns or gaps
-2. If concerns: raise with user before proceeding
-3. 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)
-
-Record the decision for plan frontmatter.
-
-### 3.3: Create Implementation Plan
-
-Create `docs/plans/YYYY-MM-DD-<topic>-plan.md`:
-
-```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 Status Lifecycle:**
-| Status | Meaning |
-|--------|----------|
-| `unstarted:` | Not started |
-| `in-progress:` | Being worked on |
-| `completed:` | Done and verified |
-| `failed:` | Attempted but failed |
-| `awaiting_user:` | Needs user action |
-| `blocked:` | Waiting on dependency |
-| `skipped:` | Intentionally not doing |
-
-### 3.4: Update Spec Checkboxes
-
-After plan is complete:
-1. Read the source spec
-2. For each checklist item covered by this plan, mark `[x]`
-3. Leave items not covered as `[ ]`
-4. Write updated spec back
-
-**Semantics:** Spec `[x]` means "planned" (covered by a plan). It does NOT mean "done".
-
-### 3.5: Self-Review
-
-- [ ] Every task has clear acceptance criteria
-- [ ] Dependencies are correct (no circular, no missing)
-- [ ] Steps are bite-sized (agent can follow without guessing)
-- [ ] Plan is focused enough for single work session
-
-### 3.6: Plan Gate
-
-Present plan summary to user.
-
-**WAIT for user approval.** If changes requested, make them.
-
-**Exit:** User approves plan. Proceed to Phase 4.
-
----
-
-## Phase 4: Work
-
-### 4.1: Setup
-
-1. Read `workbranch` from plan frontmatter
-2. If `workbranch` non-empty:
-   - Create worktree: `git worktree add .unipi/worktrees/{branch} -b {branch}`
-   - Work within worktree directory
-3. If `workbranch` empty:
-   - Work directly on current branch (main)
-
-### 4.2: 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
-
-### 4.3: 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.
-
-### 4.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.
-
-### 4.5: Work Complete
-
-When all tasks are `completed:`:
-1. Run final verification (tests, lint, build)
-2. Commit all remaining changes
-
-**Exit:** All tasks complete. Proceed to Phase 5.
-
----
-
-## Phase 5: Review
-
-### 5.1: Setup
-
-1. Read `workbranch` from plan frontmatter
-2. If `workbranch` exists and not empty → switch to that branch/worktree
-3. If `workbranch` missing or empty → review on current branch (main)
-
-### 5.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
-   - **Failed** — attempted but broken
-
-### 5.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
-
-### 5.4: Write Reviewer Remarks
-
-Add `REVIEWER-REMARK` at the **end of the plan document**, behind a divider:
-
-```markdown
----
-
-## Reviewer Remarks
-
-REVIEWER-REMARK: Done
-- All tasks complete, verified against acceptance criteria
-
-Codebase Checks:
-- ✓ Lint passed
-- ✓ Type check passed
-- ✓ Tests passed
-- ✓ Build passed
-```
-
-### 5.5: Review Gate
-
-**If all tasks done and checks pass:**
-→ Proceed to Phase 6
-
-**If tasks incomplete or checks fail:**
-> "Tasks remaining and/or checks failing. Continuing back to work phase."
-→ Go back to Phase 4 with failure context
-
-**Exit:** All checks pass. Reviewer remarks say Done. Proceed to Phase 6.
-
----
-
-## Phase 6: Merge (if worktree)
-
-### 6.1: Check Branch Strategy
-
-If `workbranch` was set (worktree):
-1. Load worktree-merge logic
-2. Merge worktree branch back to main
-3. Clean up worktree and branch
-4. Run final verification on main
-
-If `workbranch` was empty (main branch):
-→ Skip merge — changes already on main.
-
-**Exit:** Code on main. Worktree cleaned (if applicable).
-
----
-
-## Phase 7: Summary
-
-Report pipeline results:
-
-```
-Pipeline Complete: {topic}
-
-✓ Brainstorm — docs/specs/{spec}
-✓ Plan — docs/plans/{plan}
-✓ Work — {N} tasks completed on {branch or "main"}
-✓ Review — all checks passed
-✓ Merge — {merged to main, worktree cleaned or "already on main"}
-
-Artifacts:
-- Spec: docs/specs/{spec}
-- Plan: docs/plans/{plan}
-```
-
-Suggest next steps:
-- `the consolidate step` — save learnings
-- `the issue scan` — deeper code review
-- `the document step` — generate docs
-
----
-
-## Interruption Handling
-
-If any phase fails or user interrupts:
-
-1. Record current phase and progress
-2. Suggest resuming from the failed phase
-3. Don't lose context — spec/plan/progress preserved
-
-Example:
-> "Pipeline paused at review phase. 3/5 tasks complete, tests failing.
-> Resume with: `the full pipeline plan:<plan-path>`"
-
----
-
-## Coexist Triggers
-
-When packages are present, auto pipeline enhances:
-
-| Package | Enhancement |
-|---------|-------------|
-| `@unipi/ask-user` | Use `ask_user` for decision gates |
-| `@unipi/subagents` | Parallel task execution in work phase |
-| `@unipi/mcp` | MCP tools available throughout |
-| `@unipi/web-api` | Web research in brainstorm phase |
-| `@unipi/ralph` | Ralph loop for 3+ tasks in work phase |
-
----
-
-## Notes
-
-- This skill is self-contained — no need to load other skills
-- Gates between phases ensure user oversight
-- Pipeline is resumable — can restart from any phase
-- Worktree isolation protects main branch (skipped for small tasks)
-- Auto command has `full` sandbox — all tools available

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

@@ -1,219 +0,0 @@
----
-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
-
-```
-the brainstorm skill <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
-
-```
-docs/specs/YYYY-MM-DD-<topic>-design.md
-```
-
-Create the `docs/specs/` folder if it does not exist yet — it is an ordinary project folder, not a unipi store.
-
-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
-
-Use `ask_user` for structured decisions (approach selection, scope tradeoffs) when the tool is available. If `ask_user` is not available, use conversational text with clearly numbered options (e.g., "1. Option A — ... 2. Option B — ... Please pick one."). Use conversational text for open-ended exploration. 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. Use `ask_user` with clearly labeled options and descriptions for each approach when available; otherwise present numbered options conversationally.
-
-**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 (use `ask_user` for "approve / needs changes / go back" checkpoints if available; otherwise ask conversationally and wait for response)
-- 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 `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 plan mode (`/unipi:plan`) covers this item
-- **`[x]` does NOT mean done** — implementation progress is tracked in the plan file (`unstarted:` / `in-progress:` / `completed:`)
-- 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 `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. If `ask_user` is available, prefer structured options so the plan handoff can run automatically:
-
-```ts
-ask_user({
-  question: "What would you like to do next?",
-  options: [
-    {
-      label: "Proceed to plan mode",
-      description: "Turn decisions into an implementation plan",
-      value: "plan",
-      action: "new_session",
-      prefill: "/unipi:plan",
-    },
-    { label: "Keep exploring", description: "Refine questions or decisions", value: "explore" },
-    { label: "Done for now", description: "Return later", value: "done", action: "end_turn" },
-  ],
-  allowFreeform: false,
-})
-```
-
-If `ask_user` is unavailable, ask conversationally with the same options. Keep this copyable fallback command visible:
-```
-/unipi:plan
-```
-
----
-
-## 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
-- [ ] plan mode can start from this document without asking "what did you decide about X?"