Autogoal

Use this when the user asks for a durable objective, long-running autonomous work, goal setup, or when a governing repo skill requires goal setup before work starts.

This skill turns a vague "keep going" instruction into a thread-scoped completion contract: what should be true, how it is verified, what must not change, and when Codex should stop.

Core Take

A normal prompt says: do the next thing.

A goal says: keep working until this outcome is true, or until the evidence shows a real blocker.

Goals are for work where the next move depends on what Codex learns along the way: debugging, migrations, flaky tests, benchmark tuning, deep research, large refactors, prototypes, browser-proof loops, and pass-gated plans.

Goals are not a permission slip to wander. They are a scoped, evidence-checked contract.

No measurable outcome, no goal. A goal must have a verification surface and a completion threshold before create_goal is called. Prefer numbers: score, count, latency, coverage, pass count, failing-to-passing repro count, issue rows, or explicit command success. When a numeric target does not fit, use a binary artifact checklist that can be audited from files, commands, screenshots, browser proof, or source-backed citations.

Universal Boundary

autogoal is the goal lifecycle kernel. It owns:

• objective shape
• measurable completion thresholds
• evidence standards
• active goal conflict handling
• durable plan state
• blocker and completion rules
• repair routing when a goal-backed workflow misses expectations

It does not own project policy. Keep repo commands, package managers, browser tools, release rules, PR policy, scorecards, issue ledgers, and lane-specific pass schedules in derived skills or project-owned docs/plans/templates/<template>.md.

Derived skills may be stricter than autogoal; they should not duplicate the goal lifecycle. autogoal says how work remains honest. The derived skill says what the lane actually requires.

Template Composition

Goal plans are composable, but only through static materialization.

The model is:

1. one active goal
2. one root docs/plans plan file
3. one primary template
4. optional materialized packs
5. optional linked child docs/plans plan files for independently owned sub-tasks

The primary template is chosen by dominant risk: task for normal execution, docs for docs-dominant work, major-task for heavyweight architecture or proposal work, and repo-specific templates for domain lanes.

Packs are chosen by touched surface. They add recurring gates without becoming parents:

• docs: docs are touched but not the dominant deliverable
• agent-native: agent instructions, skills, hooks, commands, prompts, or user-action tooling changed
• browser: real browser, route, UI, native browser/OS, console, network, or interaction proof is required
• package-api: package exports, public API, release artifacts, package boundaries, or package-level checks changed
• performance-observability: user-facing latency, payload size, query count, database access, cache/index behavior, runtime pooling, repeated-unit work, subscription fan-out, or throughput can change

A public API or architecture that adds, retains, or changes a runtime layer, cache, index, projection, store, subscription, scheduler, geometry owner, or other repeated hot work must materialize performance-observability before the target is accepted. The plan needs an executable comparison against the current owner, using a disposable target prototype when the proposed path does not yet exist. An asymptotic table, review score, future benchmark plan, or "measure during implementation" note is not pre-acceptance evidence.

Core execution and proof gates belong in the primary template. Autoreview is never a universal goal or completion gate. Only after a complete end-to-end feature is already verified may the final handoff recommend it as an optional second pass; run it only when the user explicitly requests or accepts it. Packs are only for optional touched surfaces that would otherwise be absent from that template.

Do not create runtime inheritance between templates. The helper copies pack rows into the generated plan's Start Gates, Work Checklist, and Completion Gates. After creation, the generated plan is the truth; the checker validates that materialized plan only.

Linked child plans are different from packs. Use them when one parent goal supervises multiple independently owned task plans, such as one PRD/full-loop plan linking one task plan per issue. The parent records the child links and rollup status; each child owns its own source, proof, review, and closeout packet. check-complete.mjs on the parent must fail while any linked child plan is missing or incomplete.

The generated plan is the dedicated plan shell. Fill that exact file immediately after generation: replace placeholders, resolve every gate row, and mark non-applicable generated rows as N/A: <reason> with evidence. Do not delete, wholesale replace, or hand-narrow the generated plan into an ad hoc smaller plan after durable work has started. If the selected template is plainly wrong and no substantive work has started, regenerate once with the right template and record why. If work has already started, keep the generated plan and close it honestly.

The first plan checkpoint is requirement extraction. Codex output can compact and lose prompt constraints, so before implementation or broad exploration, copy every explicit user requirement into the plan as checkable rows: scope, non-goals, timing/duration, stop conditions, deliverables, final handoff sections, verification surface, and success criteria. Do not continue into implementation until this is complete or explicitly marked N/A with reason.

Use packs like this:

node .agents/skills/autogoal/scripts/create-goal-scratchpad.mjs \
  --template task \
  --with docs \
  --with agent-native \
  --title "<short task title>"

Examples:

• docs-only work: --template docs
• normal code task that also changes docs: --template task --with docs
• agent workflow task: --template task --with agent-native
• browser behavior task: --template task --with browser
• public app/API or package-boundary task: --template task --with package-api
• query, cache, database, or runtime performance task: --template task --with performance-observability
• major architecture task: --template major-task
• scale-sensitive architecture task: --template major-task --with performance-observability
• major architecture task that also changes docs and package API: --template major-task --with docs --with package-api

If two packs add related gates, keep both when they protect different failure modes. If they duplicate exactly the same proof, keep the more specific pack and record the other as N/A in the plan.

Proportionality Dial

Classify goal-backed work before creating or updating a plan:

• micro: one narrow, auditable outcome; no cross-file state; no meaningful continuation loop. Use a tiny plan only when a repo rule requires it, or record the audit surface directly in the final response.
• normal: multi-step work with concrete evidence and likely continuation. Use the appropriate docs/plans template and close all relevant gates.
• major: architecture, migrations, benchmarks, framework comparisons, broad refactors, pass-gated lanes, or public API/runtime risk. Use a derived skill or project template with phases, risk rows, review gates, and explicit closure criteria.

Do not inflate a micro work item into a ceremony pile. Do not shrink a major work item into a checklist that cannot catch real risk.

Goal Flow Modes

Every goal-backed workflow chooses exactly one flow mode before durable work starts. The mode controls the human review boundary; it does not weaken the evidence or completion rules.

1. One-Shot Execution

Use this for issue-like or work-item-like work where the agent is expected to read the source, derive the local plan, implement, verify, and hand off the result without stopping for plan approval.

Rules:

• Create or continue a goal when the work is non-trivial and auditable.
• Create a plan when durable state is useful or required by the caller.
• The plan is an execution ledger, not a proposal waiting for acceptance.
• Human review happens at the final handoff or explicit user interruption.
• Do not pause merely because the plan has not been reviewed. Pause only for a real blocker, unsafe ambiguity, or a user decision that changes scope.

2. Agent-Led Plan Hardening

Use this when the requested output is a plan and the user wants the agent to drive toward the best plan with minimal human interruption.

Rules:

• The agent owns the review loop: research, compare options, pressure-test, revise, and improve the plan until the confidence threshold is met.
• Ask the user only for decisions that materially change intent, boundaries, risk tolerance, or acceptance criteria.
• Record each self-review pass and plan delta as evidence.
• Stop for one major user review when the plan reaches the stated readiness threshold.
• Do not execute implementation under the planning goal unless the caller's governing workflow explicitly says planning and execution are the same goal.

3. Collaborative Planning

Use this when the user and agent are intentionally shaping the plan together before execution.

Rules:

• The goal outcome is an accepted plan, not implementation.
• Ask focused questions when user judgment changes the plan.
• Keep options, tradeoffs, rejected alternatives, and open decisions visible in the plan.
• Continue revising until the user accepts the plan or a blocker remains.
• Execution starts only after explicit acceptance or a new instruction that changes the flow mode.

Flow-mode selection belongs in the derived skill or the instantiated plan when the caller knows it. If no caller specifies a mode, default to one-shot execution for implementation tasks, agent-led plan hardening for autonomous planning/review requests, and collaborative planning when the user is actively brainstorming or asking for plan acceptance before work.

Use When

• The user asks to set a goal or asks Codex to keep working until a verifiable end state.
• A repo skill says to use create_goal or goal setup.
• Work is long-running, iterative, and has an auditable success condition.
• The path is uncertain but the finish line is auditable.
• The user would otherwise keep saying: "continue", "try the next fix", "rerun the benchmark", "keep going until it works".
• A pass-gated lane needs one durable objective with the pass schedule and closure gates inside it.
• The user says autogoal repair <expectation> after any goal-backed workflow missed their expectation, and they want the owning rule/template repaired for future runs.

Do Not Use When

• The user asks a one-off question or wants one short answer.
• The edit is tiny and no continuation loop is useful.
• The finish line is vague: "make it better", "improve performance", "clean this up" without a verification surface.
• The user explicitly declined goal setup or asked not to use goal tools.
• The only possible next move requires user input.
• Creating a goal would hide uncertainty instead of naming it.
• The user only wants the current artifact fixed once. Repair mode is for recurring workflow expectation misses, not every ordinary bug in a plan file.

Tool Contract

This is agent-native. Use the goal tools directly when available:

• get_goal to inspect the current thread goal.
• create_goal to start a new active goal.
• update_goal(status: complete) only when the objective is genuinely met.
• update_goal(status: blocked) only when no autonomous progress remains and the same blocker has recurred enough to satisfy the tool contract.

There can be only one active goal per thread. Repeated create_goal calls fail while a goal exists. Always call get_goal first; call create_goal only when it returns no goal; use update_goal to complete or block the active goal.

Active Goal Conflict Protocol

When get_goal returns a goal, classify it before touching durable state:

• same: the existing goal already describes the current requested end state. Continue under it and keep its plan current.
• same but stale plan: the goal is right but the plan is stale. Repair the plan first, then continue.
• newer user correction: the latest user message narrows, reverses, or corrects the goal. Record the correction in the plan, follow the newest instruction, and do not call the old objective complete unless it is actually true.
• different objective: the active goal is unrelated. Do not hijack it. If no lifecycle tool can pause, resume, cancel, or replace it, say so briefly and proceed only with degraded plan state when the user explicitly says to go.
• paused or externally controlled: do not fake completion or blocked status to escape the tool. Continue only if the latest user instruction clearly authorizes the new work, and record the mismatch in the plan.

Never mark a goal complete because the user changed their mind. Completion means the objective is true. A correction changes the work path; it does not retroactively prove the old objective.

Do not invent a goal state file when a goal tool is available. If goal tools are not available, record degraded control state in the active plan only when the repo workflow requires that fallback; otherwise state that goal tools are not available and continue with the nearest safe workflow.

Goal Anatomy

A strong goal defines eight things:

1. Flow mode: one-shot execution, agent-led plan hardening, or collaborative planning.
2. Outcome: what must be true when done.
3. Completion threshold: the number, pass/fail command, artifact checklist, or explicit acceptance rows that prove done.
4. Verification surface: tests, benchmarks, logs, browser proof, generated artifact, report, issue comment, or source-backed audit.
5. Constraints: what must not regress.
6. Boundaries: files, packages, repos, tools, data, routes, issue scope, or product surfaces Codex may or may not touch.
7. Iteration policy: how to choose the next move after each attempt.
8. Blocked stop condition: when to stop and report the blocker, evidence, and next input needed.

If the user requested a timed checkpoint, the plan must also define the duration, whether it is minimum active work or an explicit hard stop, the initial confidence scorecard when no better metric exists, and how the current loop will finish cleanly after the checkpoint is reached.

The create_goal.objective field is only a short handle for the active goal. Keep it under 240 characters. Put the full contract in the goal plan, not in the tool objective.

Use this tool-objective shape:

<desired end state>; done when <short threshold>; plan <docs/plans/path>.

Do not put commands, full pass schedules, long issue lists, constraints, boundaries, iteration policy, or blocked reports in create_goal.objective. Those belong in the plan sections.

Measurable Outcome Gate

Before calling create_goal, rewrite vague objectives into measurable ones, then compress the tool objective to a short handle. The plan records the full contract.

Required:

• a specific done state
• a flow mode
• a verification surface
• a completion threshold
• a constraint list or explicit no extra constraints
• a blocked condition

Quantitative examples:

• p95 < 120 ms
• score >= 0.92 and no dimension below 0.85
• 0 accepted review findings
• all 12 pass rows complete or skipped with evidence
• focused repro fails before fix and passes 5 consecutive runs after
• no stale symbol matches from rg

Auditable non-numeric examples:

• named file exists with required sections
• named issue rows moved to fixed/improved/related/not-claimed
• named browser route has screenshot proof and no console errors
• named API examples compile and match the accepted public shape

Reject or rewrite:

• "make better"
• "clean up"
• "finish"
• "absolute best" without score rows, pass gates, or evidence
• "review and decide" without an artifact and acceptance criteria

Timed Checkpoints

When the user gives a duration such as 30m, 1h, 2 hours, or 10h, treat it as a minimum active-work checkpoint unless they explicitly say max, stop at, budget cap, or timebox hard stop.

Timed checkpoints are not permission to stop early because the first obvious gates passed. They mean: keep increasing confidence until the duration is reached, then finish the current loop cleanly.

If the goal already has concrete metrics, use those metrics during the timed loop and keep looking for the next highest-value confidence gap until the duration elapses.

If there is no concrete metric, create an initial scorecard in the plan before substantive work. Use a simple 0-100 confidence score with dimensions that fit the task, for example correctness, proof strength, simplicity, maintainability, docs/source alignment, risk, and slop removal. Record:

• initial score and dimension scores;
• what would raise the score;
• what would lower or cap confidence;
• next improvement packet;
• final score at handoff.

After the main implementation gates close, continue with confidence-building work until the timed checkpoint is reached:

• review the diff/output against the newest prompt;
• remove slop, dead code, fake aliases, stale docs, and weak abstractions;
• refactor toward the durable owner when it reduces real complexity;
• add or repair missing tests, proof, diagnostics, and source audits;
• run focused verification again after meaningful changes;
• repair the owning skill/template when the workflow itself missed the user's expectation.

Do not start a large risky packet near the end unless there is enough time to finish, verify, and keep/revert/quarantine it. When the requested duration is reached, finish the active loop to a clean boundary: complete the current packet, verify it, revert or quarantine unsafe partial work, update the plan, and hand off. Never leave dirty half-work merely because the clock expired.

Stop before the timed checkpoint only for a real blocker, an explicit user interruption, or an unsafe ambiguity that would make further autonomous work harmful. Passing the first checks is not a stop condition.

Completion Gate Policy

Do not make check-complete.mjs the whole goal. That only proves the plan looks closed, not that the work is true.

Use the hybrid rule for every goal:

1. The goal tool objective names the outcome, short threshold, and plan path.
2. The docs/plans goal plan records the verification surface, constraints, boundaries, blocked condition, fresh evidence, and completion threshold.
3. node .agents/skills/autogoal/scripts/check-complete.mjs <docs/plans/path> is the final mechanical gate before update_goal(status: complete). If that plan links child plans, the checker recursively validates them too.

The checker validates that the goal plan has no unchecked required checklist items, no unresolved gate rows, no open phase/pass rows, concrete verification evidence, current reboot status, recorded risks, and no incomplete linked child plans. It does not replace tests, browser proof, source audits, benchmark output, or other named verification evidence.

Evidence Type Contract

Every completion proof should fit at least one evidence type:

• command: exact command, cwd, and pass/fail result.
• source-audit: exact files or search query proving a static property.
• browser: route, interaction, screenshot or console/network caveat.
• artifact: generated file, report, table, PR body, issue comment, or exported asset.
• review: reviewer/tool used, accepted findings, fixes, and remaining rejected findings with reasons.
• external-source: cited URL, issue, paper, docs page, or connected app result used as authority.
• N/A:<reason>: why a recurring gate does not apply.

Evidence must name the owning workspace, package, app, route, or tool when that ownership matters. A root-level check cannot prove a sibling repo, app route, browser surface, or external tracker unless the plan explains why it is the owning surface.

Repair Mode

Trigger this mode when the arguments start with:

repair <expectation>

Repair mode is self-improvement with a leash. It converts a concrete expectation miss from a goal-backed run into the smallest durable change to the owning rule, template, helper, or active plan.

Use it for misses like:

• the generated goal plan lacked a gate the user expected
• a derived skill used the wrong template or completion rule
• the skill completed too early or kept running past the intended boundary
• the final handoff omitted evidence the user expects every time
• the workflow forced too much ceremony or skipped a required review/proof step

Do not use it for:

• one-off wording preferences in a single plan
• a product/runtime bug that belongs in implementation code
• broad "make all skills better" edits
• rewriting generated skills/*/SKILL.md by hand

Target selection order:

1. If the prompt names a plan path, read that plan first. Use its Template:, skill name, phase table, and completion gates to identify the owner.
2. If the prompt names a skill, read skills/<skill>/SKILL.md first, then project-owned docs/plans/templates/<skill>.md when it exists.
3. If there is an active goal, read its plan path from the objective or current plan before editing anything.
4. If the miss belongs to every goal, target the dotai source package: skills/autogoal/SKILL.md and skills/autogoal/assets/templates/goal.md. Do not patch the installed .agents/skills/autogoal copy by hand.
5. If ownership is still unclear after source reads, ask one short targeting question instead of patching multiple templates.

Repair scope matrix:

Miss	Primary repair owner
Current plan has wrong status, row, evidence, or handoff fields	active docs/plans/* plan
Future generated plans need a recurring section, gate, row, or placeholder	project-owned docs/plans/templates/<owner>.md or dotai source skills/autogoal/assets/templates/<owner>.md
Agent chose the wrong workflow, target, proof standard, or completion rule	skills/<owner>/SKILL.md
Prose keeps failing and the miss is mechanically checkable	dotai source skills/autogoal/scripts/* plus focused script proof
Derived skill adds lane-specific ceremony or policy	derived skill rule/template, not autogoal
Universal lifecycle rule is missing across goal-backed work	dotai source skills/autogoal/SKILL.md

Repair workflow:

1. Restate the expectation in one sentence.

2. Identify the miss with source evidence: plan row, final response shape, missing gate, bad status, wrong template, or stale generated skill.

3. Pick exactly one primary owner. Patch secondary owners only when sync is required, such as source rule plus project template.

4. Create a repair plan with:

   node .agents/skills/autogoal/scripts/create-goal-scratchpad.mjs \
     --template goal-repair \
     --title "<short repair title>"