张宗平
e1b1469a4e
Comet lifecycle complete: open → design → build → verify → archive All 44 unit tests passing, 16 E2E tests passing.
49 lines
3.5 KiB
Markdown
49 lines
3.5 KiB
Markdown
## Context
|
|
|
|
Pi coding agent has no built-in mechanism for persisting a user-defined goal across a session. Skills can provide instructions, but cannot subscribe to events or inject state automatically. Extensions can, but have no declarative goal-tracking format. This change combines both layers.
|
|
|
|
## Goals / Non-Goals
|
|
|
|
**Goals:**
|
|
- Detect goal-setting phrases in user messages across languages
|
|
- Persist goal state to a file that survives context compaction
|
|
- Automatically inject goal context on every agent turn
|
|
- Eliminate unnecessary user interaction (timed auto-defaults, auto-retry, auto-recovery)
|
|
- Delegate coarse-grained goals to comet automatically
|
|
- Verify completion against explicit acceptance criteria before declaring done
|
|
|
|
**Non-Goals:**
|
|
- Multi-goal concurrent tracking (only one active goal at a time)
|
|
- Cross-session goal tracking beyond file persistence
|
|
- Subagent orchestration (agent uses existing Pi tools)
|
|
- Comet skill modifications
|
|
|
|
## Decisions
|
|
|
|
1. **Two-layer architecture (skill + extension)**: Skill provides instructions the agent reads; extension provides mechanical automation. This separates judgment (criteria quality, iteration work) from mechanics (trigger detection, state injection, timed confirms).
|
|
|
|
2. **File-based state (`.agents/goal/GOAL.md`)**: Markdown with YAML frontmatter. Survives context compaction. Human-readable and editable. Deleted on completion.
|
|
|
|
3. **Extension-driven state injection via `before_agent_start`**: Every agent turn re-injects goal context from the file. This is the primary mechanism for context-compaction resistance — even if conversation is compacted, the extension rebuilds goal context.
|
|
|
|
4. **Timed auto-default confirms (10s timeout)**: Stale state resolution, criteria confirmation, and other checkpoints use `ctx.ui.select({ timeout: 10000 })` with safe defaults. User can intervene but doesn't have to.
|
|
|
|
5. **Per-iteration exponential backoff (10 retries, ~37min)**: Tool failures and LLM API errors retry automatically. Counter resets per-iteration. After 10 retries, status becomes `blocked` and extension injects strategy-change prompt.
|
|
|
|
6. **Dual-signal stagnation detection**: Criteria passing count unchanged for 3 iterations AND no progress keywords in Progress Log. Both required. Extension auto-injects recovery prompt twice before notifying user.
|
|
|
|
7. **Granularity split with comet delegation**: Coarse-grained goals (file count > 5, multi-module, architectural) automatically invoke `comet-open`. Fallback to multi-stage mode if comet unavailable.
|
|
|
|
8. **Anti-trigger rules are mechanical**: Quote blocks, code blocks, reported speech, trivial-task keywords, and short descriptions without architectural keywords — all checked programmatically in the extension, not subjectively by the agent.
|
|
|
|
## Risks / Trade-offs
|
|
|
|
| Risk | Mitigation |
|
|
|------|------------|
|
|
| Agent rationalizes skipping criteria | Red flags list in error-handling reference; criteria modification requires logged reason |
|
|
| Sleep timeout in Pi bash tool | `timeout = delay + 30` parameter |
|
|
| Extension bugs block the loop | Extension failures degrade gracefully — skill instructions still work without extension |
|
|
| User loses ability to intervene | Explicit abandon and material criteria change still user-controllable |
|
|
| Context tension detection imprecise | `ctx.getContextUsage() > 0.8` threshold with auto-save directive |
|
|
| Mid-loop granularity upgrade needs skill-side signal | Skill can set `status: needs-upgrade` in GOAL.md; extension reads it on next turn |
|