/autogoal

name: autogoal
description: Create, verify, repair, and close durable Codex goals with measurable outcomes, evidence gates, plan templates, blocker handling, completion audits, and goal-backed workflow repair.

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 behavior, runtime pooling, or throughput can change

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, cach