Loop Engineering Workflow

Loop Engineering Workflow is a Codex skill for running a small, safe, verified development loop inside an existing project.

It helps Codex inspect a repository, maintain lightweight project planning files, define a task contract, choose practical next steps, implement the smallest useful change, verify it, trace failures, and record progress.

• Analyzes the current project structure before editing.
• Creates useful workflow documents from stable templates only for requested setup/repair; continuation reuses existing project conventions.
• Supports setup, continue, audit-only, repair, matrix, and doctor modes.
• Separates planner, builder, and evaluator responsibilities through an explicit task contract.
• Completes the agreed scope in small verified steps, with optional impact, risk, effort and confidence scoring. A bare continuation selects one next task only when no broader scope was agreed.
• Runs checks appropriate to the change and mandatory project verification; stack-specific guidance is loaded when needed.
• Records what changed, which checks ran, what should happen next, the current bottleneck, trace evidence, and a handoff note for the next loop.
• Follows the user or project language; English is the fallback when neither specifies one.

flowchart LR
  A["Inspect relevant context"] --> B["Define agreed scope"]
  B --> C["Choose next safe step"]
  C --> D["Concrete acceptance checks"]
  D --> E["Implement minimal change"]
  E --> F["Verify"]
  F --> G["Trace or restart"]
  G --> H["Record progress"]
  H --> I{"Requested scope complete?"}
  I -->|No| C
  I -->|Yes or blocked| J["Report evidence"]

.
+-- AGENTS.md
+-- SKILL.md
+-- agents/
|   +-- openai.yaml
+-- CHANGELOG.md
+-- examples/
|   +-- contract.md
|   +-- doctor-report.md
|   +-- prompts.md
|   +-- trace.md
|   +-- verification-matrix.md
+-- install.sh
+-- LICENSE
+-- README.md
+-- references/
|   +-- setup.md
|   +-- diagnostics.md
|   +-- verification.md
+-- scripts/
|   +-- check.sh
|   +-- check_links.py
+-- templates/
|   +-- AGENTS.md
|   +-- contract.md
|   +-- loop.md
|   +-- progress.md
|   +-- project-analysis.md
|   +-- roadmap.md
|   +-- trace.md
|   +-- verification.md
+-- verification.md

Install with the included script:

curl -fsSL https://raw.githubusercontent.com/Dezoff-max/loop-engineering-workflow/main/install.sh | bash

Or clone this repository manually into your Codex skills directory:

mkdir -p ~/.codex/skills
git clone https://github.com/Dezoff-max/loop-engineering-workflow.git ~/.codex/skills/loop-engineering-workflow

You can install into a custom location with:

curl -fsSL https://raw.githubusercontent.com/Dezoff-max/loop-engineering-workflow/main/install.sh | INSTALL_DIR="$HOME/.codex/skills/loop-dev" bash

If the target install directory already exists and is not this repository, the installer stops without changing it.

If the legacy path ~/.codex/skills/loop exists and the default path does not, the installer stops to avoid duplicate skills with the same name: loop. If both paths already exist, the installer warns so you can keep only one active copy.

Inside Codex, invoke the skill with:

$loop

You can also ask for it naturally:

Loop: continue this project from the roadmap.

More examples:

$loop analyze this repository and run the first safe task.

Use Loop Engineering to continue from roadmap.md and progress.md.

Loop: set up the project planning files, verify the app, and report the next task.

Loop setup: create the planning files and run the first safe task.

Loop continue: pick the next roadmap item, implement it, verify it, and update progress.

Loop audit-only: inspect the project and report what should happen next without editing files.

Loop repair: clean up stale Loop docs and verification instructions without changing app code.

Loop matrix: build or refresh the project's verification matrix without changing app code.

Loop doctor: check whether the Loop files are healthy and ready to continue.

These templates are available when needed; they are not a mandatory document set for every task:

contract.md separates the roles in the loop:

• Planner defines why the task matters and what done means.
• Builder works only inside the allowed scope.
• Evaluator checks the result against the contract and verification matrix.

The contract must be concrete enough to evaluate, but can remain internal for a simple task. Reuse an existing file when project coordination requires it. Role separation does not require separate agents or approval of routine intermediate steps.

Optional prioritization fields include:

• Impact
• Risk
• Effort
• Confidence
• Score

Use these fields when several safe tasks compete. Do not invent scores or tasks to fill a template; several steps can be needed to finish the agreed outcome.

progress.md includes a handoff section with the current state, next recommended task, known blockers, commands that passed or failed, and current bottleneck. This helps the next Loop run continue without rediscovering the same context.

Existing trace records capture useful failure evidence. A repeated failure or inaccurate contract calls for a changed approach and a smaller implementation step, preserving the requested outcome and useful work. It does not automatically require stopping, asking again, or dropping acceptance criteria.

When there is a real bottleneck, name it in progress/handoff: planning, contract, implementation, verification, documentation, architecture, UX, release, or harness.

Read relevant contracts, roadmap/verification sections and the latest useful handoff. Search older history only when needed. Missing workflow documents do not select setup automatically. Audit-only and doctor remain read-only even when a template is missing.

Detailed setup, diagnostics and verification guidance loads only for the relevant mode. Existing templates and examples are preserved.

Use $loop continue and finish TASK-001 and TASK-002, including verification for a bounded multi-task run; use $loop continue for one step only for an explicit one-step limit.

The templates/ directory provides stable starting structures for generated Loop files. Codex should use these templates as a baseline, then adapt them to the current project instead of copying generic placeholders blindly.

Loop chooses the narrowest check that proves the selected task. In matrix mode, the verification matrix itself is the deliverable. The skill includes verification guidance for:

• Node, Next.js, Vite, React, and TypeScript projects.
• Python projects.
• Swift, iOS, and macOS projects.
• Static HTML, CSS, and vanilla JavaScript projects.
• Documentation-only and knowledge projects.

doctor mode is read-only. It reports Loop health as pass, warn, or fail, then recommends the next mode: repair, matrix, continue, or setup.

It checks the project-required documents, contract quality, progress evidence, useful trace records, stale commands, unnecessary process and unsafe instructions. Missing optional files or scoring fields are not failures.

doctor reports use a health table with Check, Result, Evidence, and Recommendation.

matrix reports use a verification table with Area, Command or check, When to run, Success signal, and Fallback.

Examples live in examples/.

The maintainer self-test requires Bash and Python 3.9+ (standard library only). The skill itself has no runtime dependency. Run:

scripts/check.sh

It validates the skill frontmatter, packaged references and templates, documented modes, shell syntax, template fields, local Markdown links, and trailing whitespace. This is structural validation, not proof of agent behavior.

Repository-specific maintenance rules live in AGENTS.md. Verification expectations for this skill repository live in verification.md.

• Prefer small, reviewable changes over broad rewrites.
• Preserve the project's existing stack, structure, and visual style.
• Do not delete important files or run destructive commands without explicit approval.
• Do not publish, deploy, or expose anything publicly without explicit approval.
• Do not mark a task complete unless verification passed or the task was documentation-only and manually reviewed.

Forks, issues, and pull requests are welcome. If you adapt Loop Engineering Workflow for your own Codex setup, feel free to share improvements that keep the skill small, safe, and easy to verify.

This skill is designed for the Codex skill layout:

~/.codex/skills/loop-engineering-workflow/SKILL.md
~/.codex/skills/loop-engineering-workflow/agents/openai.yaml
~/.codex/skills/loop-engineering-workflow/templates/*.md
~/.codex/skills/loop-engineering-workflow/references/*.md

It is project-agnostic and can be used with web apps, macOS apps, static prototypes, documentation projects, and other repositories where incremental verified work is useful.

MIT License. See LICENSE.