skills/README.md

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:

git clone https://github.com/user/my-skill ~/.pi/agent/skills/my-skill

Current Skills

Skill	Description
phased-execution	Runs phased build pipelines in isolated subprocesses
find-skills	Discovers and installs new skills
gog	Google Workspace CLI (Gmail, Calendar, Drive, Contacts, Sheets, Docs)

---

phased-execution

Runs phased build pipelines in isolated subprocesses. Ported from 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:

cd /path/to/project
bash ~/.pi/agent/skills/phased-execution/scripts/run-phase.sh

Run a specific phase:

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 ~/.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:

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:

  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.