pi-skills/openspec/changes/archive/2026-06-10-goal-driven-loop/design.md

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