---
name: goal-contract-loop
description: Turn a user's high-level coding intent into a clarified Codex goal contract, SPEC.md, Plan.md, tracker, launch prompt, and evidence-driven execution loop. Use when the user asks to convert an idea into a /goal, autonomous Codex loop, implementation plan, repo audit loop, migration loop, performance goal, feature delivery workflow, or reusable service/skill for verified coding work with constraints, budgets, and stop conditions.
---

# Goal Contract Loop

## Overview

Use this skill to transform vague coding intent into a concrete, reviewable contract before launching autonomous work. Keep the loop grounded in explicit outcomes, verification surfaces, editable boundaries, budgets, and pause conditions.

Do not start or create a goal loop until the user has approved the contract, unless the user explicitly asks you to proceed autonomously and the missing details are low risk.

## Workflow

1. Capture the raw intent in the user's words.
2. Interview only for missing decision-critical details.
3. Produce a structured goal contract.
4. Generate planning artifacts: `SPEC.md`, `Plan.md`, `goal_tracker.csv`, and `goal_prompt.md`.
5. Review the artifacts with the user.
6. Launch or hand off the goal loop only after approval.
7. During execution, update the tracker after every meaningful test or blocker.
8. Finish with a report listing passed tasks, blocked tasks, evidence, changed files, and remaining risks.

## Interview Gate

Ask concise questions across these required fields:

- Objective and outcome: what result should exist when done, and how success is recognized.
- Evidence: test commands, benchmarks, builds, lint checks, manual QA, acceptance criteria, or artifacts.
- Boundaries: editable paths, forbidden files, public API/schema compatibility, data safety, and external systems.
- Tools and resources: required frameworks, package managers, plugins, internet access, credentials, and allowed subagents.
- Iteration policy: task priority, fix style, commit cadence, whether parallel worktrees are acceptable, and when to run full checks.
- Stop conditions: success criteria, maximum failed attempts per task, time/token budget, approval gates, and external blockers.

Read `references/interview-questions.md` when the user intent is broad, risky, or missing verification/boundary details.

## Goal Contract

Represent the result as a compact JSON-compatible structure with these keys:

- `objective`: one sentence describing the target outcome.
- `done_when`: list of observable success criteria.
- `evidence`: commands, benchmarks, manual checks, and required artifacts.
- `constraints`: editable paths, protected behavior, off-limits systems, and required tools.
- `iteration_policy`: prioritization, commit policy, test cadence, subagent policy, and maximum attempts.
- `budgets`: time, token, cost, branch, or scope limits.
- `pause_conditions`: reasons to stop and ask the user.
- `tasks`: implementation or audit items with IDs, acceptance criteria, severity, and test commands.
- `assumptions`: explicit assumptions used to avoid over-questioning.
- `open_questions`: unresolved items that need user approval or validation.

Read `references/contract-schema.md` for the full schema, status values, severity values, and examples.

## Planning Artifacts

Create artifacts in the repository root or in a clearly named planning folder if the repo has one. Use the helper script when a contract JSON exists:

```bash
python3 path/to/goal-contract-loop/scripts/generate_goal_package.py --contract goal_contract.json --out .
```

The script writes:

- `SPEC.md`: requirements, assumptions, constraints, and open questions.
- `Plan.md`: task list with acceptance criteria and verification commands.
- `goal_tracker.csv`: tracker with feature status, attempts, last checked time, and notes.
- `goal_prompt.md`: a launchable goal prompt derived from the contract.
- `goal_contract.normalized.json`: normalized contract used to generate the artifacts.

If no contract JSON exists, write the artifacts manually using `references/contract-schema.md` and then optionally backfill `goal_contract.json`.

## Execution Loop

Use this loop after approval:

1. Select the next `Not Started`, `Fail`, or unblocked task according to the priority policy.
2. Inspect the relevant code and tests before editing.
3. Set tracker status to `Implementing` or `Testing`.
4. Make a focused change inside the allowed boundaries.
5. Run the task's test command, then the broader suite according to the test cadence.
6. Record pass/fail evidence, command output summary, attempt count, last checked time, and notes.
7. Mark a task `Pass` only when its acceptance criteria and evidence are satisfied.
8. Mark a task `Blocked` after the configured attempt limit or when a pause condition is hit.
9. Commit small coherent diffs when the user's workflow permits commits.

Use subagents only when tasks are independent, boundaries are clear, and the user has allowed parallel work. Each subagent should receive only the relevant task, constraints, and verification commands.

## Completion

When all tasks are `Pass` or `Blocked`, produce a final report with:

- Outcome summary.
- Tracker summary by status and severity.
- Evidence commands and results.
- Changed files or diff statistics.
- Blockers and required external decisions.
- Recommended next goal, if the blocked work should continue later.

Do not describe partial preflight or planning work as complete execution. Keep verified facts separate from assumptions.