110 lines
4.5 KiB
Markdown
110 lines
4.5 KiB
Markdown
# Skills
|
|
|
|
A collection of reusable agent skills that extend an LLM coding assistant's capabilities. Install any skill by cloning or symlinking it into your agent's skills directory — for example, for pi:
|
|
|
|
```bash
|
|
git clone git@git.reeseapps.com:Vibes/skills.git ~/.pi/agent/skills/
|
|
```
|
|
|
|
## Current Skills
|
|
|
|
| Skill | Description |
|
|
|-------|-------------|
|
|
| [phased-execution](./phased-execution/) | Runs phased build pipelines in isolated subprocesses |
|
|
| [find-skills](./find-skills/) | Discovers and installs new skills |
|
|
| [gog](./gog/) | Google Workspace CLI (Gmail, Calendar, Drive, Contacts, Sheets, Docs) |
|
|
|
|
---
|
|
|
|
## phased-execution
|
|
|
|
Runs phased build pipelines in isolated subprocesses. Ported from [opencode](https://github.com/opencode-ai/opencode)'s `next-phase` / `auto-phase` commands.
|
|
|
|
### Overview
|
|
|
|
This skill orchestrates a project's development as a sequence of phases, each executed by the LLM in its own fresh process. Phases are managed via files — not chat context — so even very long-running pipelines don't bloat your session history.
|
|
|
|
Each phase:
|
|
1. Reads the master plan (`.agent/PLAN.md`) and any already-completed phases
|
|
2. Implements all tasks from its phase file
|
|
3. Runs tests, linting, and coverage checks via `.agent/validate.sh`
|
|
4. Retries up to `MAX_FIX_ATTEMPTS` times on failure (resuming the same session)
|
|
5. Moves to `complete/` only when everything passes
|
|
|
|
### Directory Structure
|
|
|
|
```
|
|
<project>/
|
|
├── .agent/
|
|
│ ├── PLAN.md # Master plan; LOCKED DECISIONS are binding
|
|
│ ├── validate.sh # Quality gate (created from skill template on first run)
|
|
│ ├── phases/
|
|
│ │ ├── todo/ # Pending phases: 01_name.md, 02_name.md, …
|
|
│ │ └── complete/ # Finished phases
|
|
│ ├── reports/ # Per-phase executor reports, stderr, validation logs
|
|
│ └── phase-sessions/ # Resumable child sessions
|
|
```
|
|
|
|
### Usage
|
|
|
|
From within a project that has `.agent/phases/todo/`:
|
|
|
|
**Run the next pending phase:**
|
|
```bash
|
|
cd /path/to/project
|
|
bash ~/.pi/agent/skills/phased-execution/scripts/run-phase.sh
|
|
```
|
|
|
|
**Run a specific phase:**
|
|
```bash
|
|
bash ~/.pi/agent/skills/phased-execution/scripts/run-phase.sh 03_api.md
|
|
```
|
|
|
|
**Run the entire pipeline** (all pending phases, in order, stopping at first failure):
|
|
```bash
|
|
bash ~/.pi/agent/skills/phased-execution/scripts/auto-phase.sh
|
|
```
|
|
|
|
Re-running `auto-phase.sh` after a failure continues where it stopped.
|
|
|
|
### Configuration
|
|
|
|
Environment variables passed to the scripts control behavior:
|
|
|
|
| Variable | Default | Meaning |
|
|
|----------|---------|---------|
|
|
| `MAX_FIX_ATTEMPTS` | `3` | Fixer retries per phase |
|
|
| `PHASE_MODEL` | session default | Model for child executors (e.g. `anthropic/claude-sonnet-4-5`) |
|
|
| `PHASE_THINKING` | session default | Thinking level for child executors |
|
|
| `PHASE_COMMIT` | `0` | `1` = auto-git-commit after each passing phase |
|
|
| `PI_TRUST` | `0` | `1` = pass `--approve` to children (load project `.pi/` settings) |
|
|
| `FRESH_FIX` | `0` | `1` = fixer retries start fresh instead of resuming the failed session |
|
|
| `QUIET` | `0` | `1` = suppress live progress display (reports still written) |
|
|
|
|
Example:
|
|
```bash
|
|
PHASE_MODEL=anthropic/claude-sonnet-4-5 PHASE_COMMIT=1 bash ~/.pi/agent/skills/phased-execution/scripts/auto-phase.sh
|
|
```
|
|
|
|
### How It Works
|
|
|
|
1. `run-phase.sh` / `auto-phase.sh` finds the project root (walks up from `PWD` for `.agent/phases/todo/`)
|
|
2. For each phase, it spawns a **separate process** with `--mode json` to capture structured output
|
|
3. `progress.mjs` streams live progress (tool calls, assistant text) to the terminal and writes the final report to `.agent/reports/`
|
|
4. After the child exits, `.agent/validate.sh` is run as the quality gate
|
|
5. On success: phase moves to `complete/`, report is printed
|
|
6. On failure: up to `MAX_FIX_ATTEMPTS` fixer retries (resuming the same session), then the phase stays in `todo/`
|
|
|
|
### After a Run
|
|
|
|
- **Success**: The executor report is printed at the end of the script output. Phases in `.agent/phases/complete/` are already done.
|
|
- **Failure**: Point to `.agent/reports/<phase>.a*.{md,err,validate}` for logs. Resume with:
|
|
```bash
|
|
pi --session-dir .agent/phase-sessions -c
|
|
```
|
|
Or re-run the script to retry automatically.
|
|
|
|
### Creating Phases
|
|
|
|
Phase files are typically created by prompt templates like `/to-phase`, `/audit-create`, `/new-project`, and `/new-python-*`. Each phase file in `todo/` should list concrete tasks the executor must complete, including testing & quality criteria.
|