pi-skills/AGENTS.md

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

# 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/<name>/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/<name> .pi/skills/<name>
5. Test with pi -p "/skill:<name>"

Adding a new extension

1. Create directory at extensions/<name>/
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/<name> .pi/extensions/<name>
5. Test with pi -e extensions/<name>/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