docs: add MIT LICENSE, AGENTS.md for development conventions, update README license section
This commit is contained in:
张宗平
@@ -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/<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
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user