Goal

Goal Skill

Use this skill when the user asks to start, continue, inspect, complete, or block a goal, especially with prompts such as /goal ..., set a goal, continue the goal, what is the goal status, or mark the goal complete.

The goal state lives in .copilot-goals/current.md and .copilot-goals/goals.sqlite at the workspace root.

• current.md is the compact human-readable context Copilot should read before continuing.
• goals.sqlite contains a Codex-shaped thread_goals table for structured status, budget, token, and elapsed-time accounting.

Commands

If terminal access is available, run the helper from this skill directory:

bash scripts/goal.sh start "objective text"
bash scripts/goal.sh start --budget 250000 "objective text"
bash scripts/goal.sh status
bash scripts/goal.sh plan "next step"
bash scripts/goal.sh note "evidence or progress note"
bash scripts/goal.sh account --tokens 12000 --seconds 90
bash scripts/goal.sh complete "verification summary"
bash scripts/goal.sh block "specific blocker"
bash scripts/goal.sh pause "reason"
bash scripts/goal.sh resume "reason"
bash scripts/goal.sh db-path

If the script is not available, edit .copilot-goals/current.md directly using the same sections described below. If sqlite3 is unavailable, continue with markdown-only state.

SQLite Ledger

The helper creates a thread_goals table shaped after the observed Codex local goal database:

thread_id TEXT PRIMARY KEY
goal_id TEXT NOT NULL
objective TEXT NOT NULL
status TEXT CHECK(status IN ('active','paused','blocked','usage_limited','budget_limited','complete'))
token_budget INTEGER
tokens_used INTEGER DEFAULT 0
time_used_seconds INTEGER DEFAULT 0
created_at_ms INTEGER
updated_at_ms INTEGER

Copilot cannot read true model billing counters by itself. Use account only when token or elapsed-time numbers are available from the environment, the user, or another tool. If the token budget is reached, the helper marks the goal budget_limited; after that, do not start new substantive work unless the user changes the budget or explicitly resets the goal.

State File Sections

Every goal state file should contain:

• Objective: the exact user outcome.
• State: active, paused, blocked, usage_limited, budget_limited, or complete.
• Completion criteria: observable facts that prove the goal is done.
• Assumptions: only the assumptions needed to keep moving.
• Budget policy: how to minimize Copilot usage for this goal.
• Plan: ordered checklist with only one active step.
• Evidence: commands run, files changed, URLs created, or other proof.
• Blockers: missing permissions, missing secrets, unavailable services, or unresolved user decisions.
• Notes: compact context for future continuation.

Start A Goal

1. Parse the objective from the user's prompt.
2. Ask at most one concise, batched clarification if the objective is missing or materially ambiguous.
3. Create .copilot-goals/current.md.
4. Create or update the SQLite thread_goals row through goal.sh.
5. Define completion criteria before doing implementation work.
6. Create a short plan with one in-progress step.
7. Start work immediately when the objective is clear.

Continue A Goal

1. Read .copilot-goals/current.md.
2. Check .copilot-goals/goals.sqlite through goal.sh status when terminal access is available.
3. Summarize current state in one or two sentences.
4. Continue the next unfinished plan item.
5. Update evidence and plan state before responding.

Complete A Goal

Only mark a goal complete when the objective is actually satisfied.

Before completion:

1. Re-read the objective and completion criteria.
2. Run the relevant validation, or record why validation cannot run.
3. Update evidence with concrete proof.
4. Run goal.sh complete "verification summary" or otherwise set markdown and SQLite state to complete.
5. Give the user the result, validation, and any residual risk.

Block A Goal

Only mark blocked when meaningful progress requires user input or an external state change.

Record:

• the exact blocker
• attempts already made
• what input, permission, secret, account access, or service state is required
• the smallest next action once unblocked

Usage Discipline

Minimize Copilot AI-credit or legacy premium-request usage:

• Front-load the objective and completion criteria into one goal state file.
• Prefer local search, file reads, tests, and tool calls over user follow-up prompts.
• Batch clarifying questions.
• Keep notes compact. Do not copy large file contents into the goal file.
• Use prompt files and this skill to avoid retyping process instructions.
• Use lightweight or auto-selected models for routine status checks when the user controls model choice.
• Escalate to a stronger model only for hard reasoning, architecture, or debugging.

For legacy request-based Copilot plans, user prompts can consume premium requests while autonomous agent tool calls do not add separate premium requests. Do as much discoverable work as possible inside the active goal turn.

If a goal is budget_limited, stop expanding scope. Summarize progress, remaining work, and the smallest next action. Do not mark the goal complete unless the completion criteria are actually satisfied.

Response Format

Keep responses short and operational:

Goal: active|paused|blocked|usage_limited|budget_limited|complete
Progress: ...
Validation: ...
Next: ...