From 2bba75808a1894a22be764add44a761337fe37b8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=BC=A0=E5=AE=97=E5=B9=B3?= Date: Wed, 10 Jun 2026 21:39:42 +0800 Subject: [PATCH] docs: add README with installation and usage instructions --- README.md | 170 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 170 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..4ba2800 --- /dev/null +++ b/README.md @@ -0,0 +1,170 @@ +# 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 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 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 (assumed — please confirm with the repository owner).