diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..e7207ad --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,99 @@ +# AGENTS.md + +Project conventions for agent-assisted development. + +## Project Overview + +This repository provides Pi coding agent skills and extensions. The primary component is **goal-driven-loop** — a skill + extension pair that keeps a session focused on a user-defined goal with explicit acceptance criteria. + +## Repository Structure + +``` +extensions/goal-driven-loop/ # TypeScript extension (Pi Extension API) +.agents/skills/goal-driven-loop/ # Skill instructions (Markdown) +.pi/skills/ → symlink # Pi skill discovery +.pi/extensions/ → symlink # Pi extension discovery +docs/superpowers/ # Design specs and implementation plans +openspec/ # OpenSpec change archive +``` + +Agent directories (`.claude/`, `.agents/`, `.pi/`) are **gitignored**. Only the symlinks and source files at top-level directories are committed. + +## Tech Stack + +- **Skills**: Markdown (Agent Skills standard), no build step +- **Extensions**: TypeScript, loaded via jiti (no compilation needed), depends on `@earendil-works/pi-coding-agent` Extension API +- **Testing**: Manual behavioral tests via `pi -p` / `pi -e`; unit tests run with `npx jiti` against individual modules +- **Workflow**: OpenSpec → comet lifecycle for change tracking + +## Development Commands + +```bash +# Verify skill loads +pi -p "/skill:goal-driven-loop" + +# Verify extension loads +pi -e extensions/goal-driven-loop/index.ts -p "test" + +# Run unit tests for trigger-detector +npx jiti /tmp/test-trigger-detector.mjs + +# Run unit tests for state-injector +npx jiti /tmp/test-state-injector.mjs + +# End-to-end test (create a temp project first) +mkdir -p /tmp/test && cd /tmp/test && git init +pi -e /path/to/pi-setup/extensions/goal-driven-loop/index.ts \ + -p "当前目标是实现 reverseString(s) 函数" +``` + +## Key Design Decisions + +1. **Skill + Extension dual layer**: Skill = instructions (agent reads). Extension = mechanics (event handlers). Do not mix concerns. +2. **File-based state** (`.agents/goal/GOAL.md`): Survives context compaction. Deleted on goal completion. +3. **Extension never blocks user**: All confirms use timed auto-defaults (10s timeout). Fallbacks are safe (continue existing goal). +4. **Anti-triggers are mechanical**: Code blocks, quote blocks, reported speech, trivial keywords — all checked programmatically, not by agent judgment. +5. **Per-iteration retry**: Exponential backoff counter resets each iteration. 10 retries / ~37min coverage. +6. **Comet delegation**: Coarse-grained goals auto-delegate to `comet-open`. Fallback to multi-stage mode if comet unavailable. + +## When Modifying This Project + +### Adding a new skill + +1. Create directory at `.agents/skills//SKILL.md` +2. Follow the Agent Skills standard: YAML frontmatter with `name` and `description` (start with "Use when...") +3. Keep SKILL.md ≤ 500 words; move detailed reference to `references/` subdirectory +4. Create symlink: `ln -s ../../.agents/skills/ .pi/skills/` +5. Test with `pi -p "/skill:"` + +### Adding a new extension + +1. Create directory at `extensions//` +2. Write `index.ts` that exports a default function receiving `ExtensionAPI` +3. Add `package.json` with `{ "pi": { "extensions": ["./index.ts"] } }` +4. Create symlink: `ln -s ../../extensions/ .pi/extensions/` +5. Test with `pi -e extensions//index.ts -p "test"` + +### Modifying goal-driven-loop + +- **Skill layer** (`.agents/skills/goal-driven-loop/`): Changes to instructions, acceptance criteria rules, error handling reference +- **Extension layer** (`extensions/goal-driven-loop/`): + - `trigger-detector.ts` — trigger phrase patterns and anti-trigger logic + - `state-injector.ts` — GOAL.md parsing and injection text generation + - `ui-prompts.ts` — timed confirms and notification helpers + - `index.ts` — event wiring (input, before_agent_start) + +After any change, re-run unit tests and E2E verification. + +## Commit Conventions + +- `feat(skill):` / `feat(ext):` — new features +- `fix(skill):` / `fix(ext):` — bug fixes +- `docs:` — documentation changes +- `chore:` — maintenance (gitignore, archive, etc.) + +## Known Limitations (v1) + +1. Mid-loop granularity upgrade needs skill-side signal (`status: needs-upgrade` in GOAL.md) — extension cannot auto-detect goal complexity increase +2. Agent "estimates < 5 min" anti-trigger is instruction-level only, not mechanical +3. Stagnation dual-signal precise detection needs skill-side passing count history in GOAL.md — extension relies on skill's own stagnation detection diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..d087bd0 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Charles + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index 4ba2800..fe74627 100644 --- a/README.md +++ b/README.md @@ -167,4 +167,4 @@ The skill handles transient failures with exponential backoff (10 retries, ~37mi ## License -MIT (assumed — please confirm with the repository owner). +MIT — see [LICENSE](LICENSE).