Loop Engineering

Give AI coding agents a clear finish line—and a safe way to reach it.

Reusable Agent Skills and execution profiles for OpenAI Codex, Anthropic Claude Code, and established software projects.

Important

shape-goal is the main command. Run it outside an active /goal. It asks one question, saves it, and stops so you can reply normally. Autonomous work starts only after you approve what “done” means.

🚀 Start in three steps

1. Install—or update

Install once

npx -y skills@latest add chrisduvillard/loop-engineering-goal-library \
  --skill '*' --global --agent codex --agent claude-code --yes

Get the latest version later

npx -y skills@latest update shape-goal goal-engine --global --yes

Restart Codex or Claude Code after updating. See INSTALL.md for verification and a safe reinstall fallback.

2. Shape the next goal

Claude Code	Codex CLI / IDE
/shape-goal Continue this project	$shape-goal Continue this project

shape-goal reads the repository, resolves facts itself, and asks only decisions that belong to you. Every question and answer is saved in:

docs/goals/<goal-id>/SHAPING.md

After each question, it ends the turn. Your next normal message is the answer—no Steer message required.

Tip

There is no target question count. It may ask two questions or twenty. It stops only when the draft has one material interpretation, no hidden high- or medium-impact assumption, and verifiable completion evidence. “You decide” is recorded as bounded delegation—not blank authority.

Need more depth or a stronger challenge?

Need	Claude Code	Codex CLI / IDE
Explore new lenses	/shape-goal Deepen the current goal	$shape-goal Deepen the current goal
Challenge ambiguity	/shape-goal Stress-test the current goal	$shape-goal Stress-test the current goal

Earlier answers stay intact. Deepening explores new decisions; stress-testing looks for ambiguous wording, hidden assumptions, weak proof, and alternate interpretations.

3. Approve, then execute

Review four things: outcome, proof, protected behavior, and authority.

After approval, shape-goal returns the exact /goal command for goal-engine. Paste it once; the agent can then work autonomously:

Orient → Reconcile → Select → Verify → Change
       → Check → Review → Record → Repeat

🧭 Why two phases?

A native /goal automatically starts another turn until its condition is met. That is excellent for implementation, but awkward when the agent must wait for your answer.

Interactive shaping	Autonomous execution
shape-goal asks one question and stops	/goal + goal-engine keeps working
You answer normally	The agent verifies, retries, and records
You approve what “done” means	Evidence decides when it stops

If you see Pursuing goal… while a shaping question is waiting:

• Codex: /goal pause or /goal clear, then $shape-goal Resume goal-id
• Claude Code: /goal clear, then /shape-goal Resume goal-id

Tip

Running a high-impact audit? Use the isolated specialist reviewer team: contract/state, agent control, security, portability, verification, and documentation.

Goal profiles

You usually do not need to choose one: shape-goal can select the best profile from repository evidence. Choose directly only when the type of work is already clear.

🟣 Core goals (7)

Profile	Best for
Brownfield Continue / Finish	Understand the real current state and keep completing the most important unblocked work.
PRD / Spec Compliance	Compare the real product with its requirements and close every proven gap.
Next Milestone	Deliver one useful next milestone without wandering into the whole backlog.
Deep Audit + Remediation	Find important problems, prove they are real, fix root causes, and prevent recurrence.
QA / Regression / UAT	Exercise the real product until required workflows and regression gates pass.
Safe Refactor / Modernization	Improve internals while proving users and integrations still see the intended behavior.
Release Readiness	Remove verified release blockers and stop at release-ready.

🔵 Specialist goals (9)

Profile	Best for
Incident Recovery / Stabilization	Contain damage, restore health, prove the cause, and add prevention.
Dependency / Framework Upgrade	Upgrade through safe version steps while checking the full compatibility surface.
Data Migration / Integrity	Migrate data through reversible phases and prove no unexplained loss, duplication, or corruption.
Branch Rescue / Integration	Recover useful behavioral slices without overwriting newer target work.
Measured Optimization / Benchmark	Freeze a baseline, test one challenger at a time, and keep only reproducible wins.
Technical Spike / Feasibility	Run an isolated experiment and return a Go, Conditional Go, or No-Go decision.
AI / LLM Evaluation & Improvement	Build a trustworthy eval set, classify failures, test one change at a time, and keep only improvements that survive repeated runs.
Deprecation / Legacy Sunset	Find who still depends on the old path, provide a safe migration, prove adoption, then remove it in controlled stages.
Codebase Onboarding / Knowledge Recovery	Turn an unfamiliar repository into a verified map that a new maintainer or agent can safely use.

🟢 Product and quality goals (15)

Profile	Best for
Frontend UI / UX / Accessibility	Improve the real interface through browser-based user journeys, visual evidence, and accessibility checks.
Documentation Synchronization / Knowledge Transfer	Find documentation drift, verify examples and commands, and make the maintained knowledge trustworthy.
Security / Privacy Hardening	Threat-model the scoped system, prove actionable findings, remediate safely, and add lasting protection.
Reliability / Resilience Hardening	Model failure modes, inject safe faults, improve recovery, and prove reliability objectives.
API / Integration Contract Compatibility	Map contracts and consumers, prove compatibility, and evolve interfaces without hidden breakage.
Observability / Operability	Make system health visible and actionable, then prove it with drills.
Developer Experience / Tooling	Make the common developer path work from clean state with clear commands and actionable failures.
Data Quality / Pipeline Assurance	Define data invariants, test the real pipeline, correct root causes, and make quality continuously observable.
Compliance / Audit Readiness	Map controls to implementation and evidence, close technical gaps, and leave an auditable package for qualified human review.
Test Suite / CI Health	Find flaky, misleading, slow, skipped, or environment-dependent checks and turn the test pipeline into reliable evidence.
Infrastructure / Deployment Readiness	Verify that the system can be provisioned and deployed consistently, diagnosed after rollout, and safely rolled back before a human authorizes production change.
Internationalization / Localization Readiness	Find hard-coded locale assumptions, build a locale matrix, test translated and right-to-left experiences, and prove every supported locale works.
Backup / Restore / Disaster Recovery	Define what must survive, create trustworthy backups, restore them in a clean environment, and prove recovery meets the agreed targets.
Product Analytics / Experimentation Integrity	Define the events and metrics, verify collection end to end, test experiment assignment, and prove the numbers mean what the team thinks they mean.
Search / SEO / Web Discoverability	Make public web content crawlable, understandable, fast, and internally connected without promising rankings.

When no preset fits, use the Custom Contract-Driven fallback.

💾 Everything is saved for reuse

GOAL.md                         approved active contract
GOAL_PROGRESS.md                evidence and next action

docs/goals/<goal-id>/
├── SHAPING.md                  questions, answers, corrections, approval
├── CONTRACT.md                 outcome, scope, proof, protections
├── PROGRESS.md                 attempts, evidence, blockers
└── RESULT.md                   result, lessons, residual risk

Stable knowledge is promoted into tests, ADRs, documentation, runbooks, fixtures, evals, locale and crawl matrices, scripts, benchmarks, design references, or the reusable Project Harness. Sensitive answers are redacted when the repository is not a safe place to store them.

When priorities change, run shape-goal again. It can amend, pause, resume, reprioritize, split, supersede, or create a follow-on goal without erasing the old decision trail.

⚙️ Advanced modes

Autonomous and no-skill preflights

Each profile file also contains two advanced /goal prompts:

• Autonomous preflight — use only when an approved artifact already answers every owner decision.
• Self-contained preflight — use when the skills are unavailable.

Both stop as Approval required when a human decision is missing. They never ask a question and keep looping inside /goal.

Learn more

Install · Profiles · Quick reference · Architecture · Worked example · Research

Use conversation to decide what “done” means. Use /goal only after “done” is approved and verifiable.

Beta safety status

Version 0.12.0 adds deterministic lifecycle state, read-only audit controls, reference-closed standalone packages, false-completion guards, and behavioral evaluation scaffolding. The project remains beta until the repeated live-host matrix in docs/HOST_ACCEPTANCE_MATRIX.md passes for supported Codex and Claude Code versions.

Use skills/goal-engine/scripts/goalctl.py doctor to inspect runtime state and goalctl self-test to exercise fingerprints, leases, read-only enforcement, and false-completion protection locally.