pi-skills/README.md

# pi-setup

Pi coding agent (https://github.com/badlogic/pi-mono) — skills, extensions, and configuration for goal-driven development workflows.

## What This Repository Provides

| Component | Path | Purpose |
|-----------|------|---------|
| **Skill: `goal-driven-loop`** | `.agents/skills/goal-driven-loop/` | Keeps a session focused on a user-defined goal with explicit acceptance criteria. Iterates until all criteria pass or stagnation is detected. |
| **Extension: `goal-driven-loop`** | `extensions/goal-driven-loop/` | TypeScript extension that automates trigger detection, state injection on every agent turn, context tension detection, and timed auto-default confirms. |
| **Symlinks for Pi discovery** | `.pi/skills/`, `.pi/extensions/` | Pi-specific discovery points — point to the real source files in `.agents/skills/` and `extensions/`. |
| **Spec & plan** | `docs/superpowers/` | Design spec and implementation plan that produced the skill + extension. |
| **Comet archive** | `openspec/changes/archive/` | Formal change record from the OpenSpec lifecycle. |

The skill and extension work as a pair. The skill is the instruction layer (what the agent reads). The extension is the automation layer (mechanical trigger detection, state injection, timed confirms).

## Repository Layout

```
pi-setup/
├── .gitignore                  # ignores .claude/, .agents/, .pi/
├── extensions/
│   └── goal-driven-loop/       # Extension source (git-tracked)
│       ├── index.ts            # Event wiring
│       ├── trigger-detector.ts # Phrase matching + anti-triggers
│       ├── state-injector.ts   # GOAL.md parsing + injection
│       ├── ui-prompts.ts       # Timed auto-defaults
│       └── package.json
├── docs/
│   └── superpowers/
│       ├── specs/2026-06-10-goal-driven-loop-design.md
│       └── plans/2026-06-10-goal-driven-loop.md
├── openspec/
│   └── changes/archive/2026-06-10-goal-driven-loop/
├── .agents/skills/             # (gitignored) Skill source
│   └── goal-driven-loop/
│       ├── SKILL.md
│       └── references/error-handling.md
├── .pi/                        # (gitignored) Pi discovery symlinks
│   ├── skills/goal-driven-loop → ../../.agents/skills/goal-driven-loop
│   └── extensions/goal-driven-loop → ../../extensions/goal-driven-loop
└── .claude/                    # (gitignored) Claude Code state
```

## Installation

The skill and extension source are committed at the top level. The agent-specific directories (`.agents/`, `.pi/`, `.claude/`) are gitignored and only hold symlinks/discovery points on the local machine.

### Option 1: Clone and use locally

```bash
git clone <repo-url> pi-setup
cd pi-setup

# Create symlinks so Pi can discover the skill and extension
mkdir -p .agents/skills
ln -s ../extensions/../.agents/skills/goal-driven-loop .agents/skills/goal-driven-loop
mkdir -p .pi/skills .pi/extensions
ln -s ../../.agents/skills/goal-driven-loop .pi/skills/goal-driven-loop
ln -s ../../extensions/goal-driven-loop .pi/extensions/goal-driven-loop
```

Or use the project's `.pi` settings to point at the source directly (see Option 3).

### Option 2: Install into another project (as a Git submodule)

```bash
cd your-project
git submodule add <repo-url> vendor/pi-setup
```

Then add to your project's `.pi/settings.json`:

```json
{
  "skills": ["vendor/pi-setup/.agents/skills"],
  "extensions": ["vendor/pi-setup/extensions/goal-driven-loop"]
}
```

### Option 3: Configure Pi to discover via settings (no copy)

In `.pi/settings.json` (project) or `~/.pi/agent/settings.json` (user):

```json
{
  "skills": ["/path/to/pi-setup/.agents/skills"],
  "extensions": ["/path/to/pi-setup/extensions/goal-driven-loop"]
}
```

Pi loads skills from any directory in this list, so the source files at the top level are used directly — no symlinks required.

## Verifying Installation

```bash
# 1. Skill loads
pi -p "/skill:goal-driven-loop"
# → "Goal-Driven Loop is active. Awaiting your goal statement."

# 2. Extension loads
pi -e extensions/goal-driven-loop/index.ts -p "test"
# → no errors, normal output

# 3. End-to-end trigger
mkdir -p /tmp/test && cd /tmp/test && git init
pi -e /path/to/pi-setup/extensions/goal-driven-loop/index.ts \
   -p "当前目标是实现 reverseString(s) 函数"
# → Goal-driven loop activates, implements, tests, completes
```

## Usage

Set a goal with a trigger phrase (Chinese, English, or other language with similar meaning):

```
设定当前目标为给 auth 模块加 rate limiting
当前目标是实现 camelCase 函数
my goal is to add caching, acceptance: hit rate > 80%
```

The skill auto-generates verifiable acceptance criteria if you don't provide them, persists state to `.agents/goal/GOAL.md`, and iterates until all criteria pass.

To abandon a goal:

```
放弃
不要了
cancel
```

To override auto-defaults within the timed window, just type your choice. After 10 seconds, the system defaults to "continue" on stale state prompts.

## Trigger Reference

| Language | Patterns |
|----------|----------|
| Chinese | 设定当前目标为 / 当前目标是 / 把当前目标设为 / 我的目标是 |
| English | set current goal to / current goal is / my goal is / the goal is |
| Other | semantically equivalent phrasings |

The skill does **not** activate when the phrase is inside a quote block, code block, or reported speech; when the message contains trivial-task keywords (hotfix, tweak, quick fix, 修个bug, 小改); or when the goal is ≤ 10 characters without architectural keywords.

## Architecture

```
User: "设定当前目标为 X"
        ↓
[Extension: input event] detectTrigger(X) → validates against anti-triggers
        ↓
[Extension: before_agent_start] reads .agents/goal/GOAL.md, injects state
        ↓
[Skill: SKILL.md] instructs agent on iteration steps
        ↓
[Agent] implements, verifies, updates GOAL.md
        ↓
[Extension: before_agent_start] on next turn re-injects updated state
        ↓
[Skill: completion] deslop pass + cleanup + output summary
```

State is file-based — `.agents/goal/GOAL.md` — so it survives context compaction. The extension re-injects the goal state on every agent turn.

## Error Handling

The skill handles transient failures with exponential backoff (10 retries, ~37min total coverage). Stagnation uses dual-signal detection (criteria count + progress keywords) with auto-recovery injection before user notification. See `docs/superpowers/specs/2026-06-10-goal-driven-loop-design.md` for the full design.

## License

MIT — see [LICENSE](LICENSE).