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

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)

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

Then add to your project's .pi/settings.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):

{
  "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

# 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.