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

ADDED Requirements

Requirement: Trigger Detection

The extension MUST detect goal-setting phrases in user input across Chinese ("设定当前目标为", "当前目标是", "把当前目标设为", "我的目标是"), English ("set current goal to", "current goal is", "my goal is", "the goal is"), and semantic variants in other languages.

Scenario: Chinese trigger phrase

• WHEN user input contains "设定当前目标为实现用户认证"
• THEN the extension detects a trigger and extracts goalText "实现用户认证"

Scenario: English trigger phrase

• WHEN user input contains "my goal is to add rate limiting"
• THEN the extension detects a trigger and extracts goalText "to add rate limiting"

Requirement: Anti-Trigger Rules

The extension MUST NOT activate when: (1) trigger phrase is inside a markdown quote block or code block with no trigger outside it, (2) trigger phrase is in the same sentence as reported speech markers, (3) message contains trivial-task keywords (hotfix, tweak, fix a bug, quick fix, 修个bug, 小改), (4) goal description is ≤ 10 chars without architectural keywords.

Scenario: Trigger inside quote block only

• WHEN user input is "> 他说当前目标是重构整个系统"
• THEN the extension does NOT detect a trigger

Scenario: Trigger outside quote block

• WHEN user input is "> 引用文字\n当前目标是实现新功能模块"
• THEN the extension detects a trigger from the non-quote content

Scenario: Trivial task keyword

• WHEN user input contains "hotfix" or "修个bug"
• THEN the extension does NOT detect a trigger

Requirement: Goal State Persistence

The skill MUST persist goal state to .agents/goal/GOAL.md with YAML frontmatter (goal, created, updated, iteration, status) and markdown body (Acceptance Criteria with checkboxes, Progress Log, Blocked section).

Scenario: Goal state created

• WHEN a fine-grained goal trigger is detected
• THEN .agents/goal/GOAL.md is created with status "in-progress"

Scenario: Goal state cleaned up on completion

• WHEN all acceptance criteria pass and deslop pass completes
• THEN .agents/goal/GOAL.md is deleted

Requirement: State Injection on Every Agent Turn

The extension MUST inject goal state summary into the system prompt via before_agent_start whenever .agents/goal/GOAL.md exists with status "in-progress".

Scenario: Active goal injected

• WHEN agent starts a turn and GOAL.md exists with status "in-progress"
• THEN the system prompt includes "[goal-driven-loop] ACTIVE GOAL" with progress summary

Scenario: Blocked goal injected

• WHEN agent starts a turn and GOAL.md exists with status "blocked"
• THEN the system prompt includes "[goal-driven-loop] GOAL BLOCKED" with blocker details and strategy-change directive

Requirement: Context Tension Detection

The extension MUST detect context tension via ctx.getContextUsage() > 0.8 and inject a save-progress directive.

Scenario: Context near limit

• WHEN context usage exceeds 80% of context window
• THEN extension injects "Finalize .agents/goal/GOAL.md updates before completing this turn"

Requirement: Timed Auto-Default Confirms

Stale state resolution MUST use ctx.ui.select({ timeout: 10000 }) with auto-default "continue" on timeout.

Scenario: Stale state timeout

• WHEN GOAL.md exists and a new trigger is detected, and user does not respond within 10s
• THEN the system defaults to "continue" (resume existing goal)

Requirement: Exponential Backoff Retry

Transient failures MUST be retried with exponential backoff: 30s initial delay, ×2 factor, 300s max delay, 10 retries per iteration.

Scenario: Tool failure retry

• WHEN a bash command returns non-zero exit code
• THEN the skill retries after min(30 * 2^(retry-1), 300) seconds

Requirement: Dual-Signal Stagnation Detection

Stagnation MUST be detected only when BOTH: (1) criteria passing count unchanged for 3 consecutive iterations, AND (2) no progress keywords in the last 3 iterations. Extension auto-injects strategy-change prompt; after 2 consecutive auto-recoveries with no progress, notifies user.

Scenario: Stagnation auto-recovery

• WHEN stagnation is detected for the first time
• THEN extension injects a strategy-change prompt without blocking the user

Requirement: Granularity Split

Coarse-grained goals (file count > 5, multi-module, architectural) MUST be delegated to comet-open automatically. If comet is unavailable, fallback to multi-stage mode.

Scenario: Coarse goal delegation

• WHEN goal contains "migrate" or "rewrite" or "整个" and openspec directory exists
• THEN extension invokes comet-open with the goal

Requirement: Acceptance Criteria Verifiability

Auto-generated acceptance criteria MUST be verifiable. Non-verifiable criteria (e.g., "code quality is good") MUST be rewritten before writing GOAL.md.

Requirement: Abandon Detection

User input containing "abandon", "cancel", "不要了", "放弃" MUST delete GOAL.md and terminate the loop.

Scenario: User abandons

• WHEN user says "放弃" and GOAL.md exists
• THEN GOAL.md is deleted and notification is shown