Loop engineering, not prompt engineering. A durable, open-source operating system for planning and building products across Codex, Claude Code, Cursor, Grok Build, OpenCode, and any other coding agent.
The public interface is the skill layer: type /plan-loop, /develop-product,
/loop-engine, or describe what you want in your coding agent. The installed loop
executable is an internal deterministic runtime bridge used by those skills; normal users
do not operate the product through a terminal CLI. See
docs/INTERNAL_RUNTIME.md.
| Loop | Skill / command | Purpose |
|---|---|---|
| Step 1 - Planning | /plan-loop or skill skills/plan-loop |
Initialize product → brainstorm → fact-check → PRD → architecture → task breakdown |
| Step 2 - Build | /develop-product or skill skills/develop-product |
Implement → review → QA → security/compliance → CI/CD → deploy |
| All-in-one | /loop-engine or skill skills/loop-engine |
Route between planning, task compilation, development, QA, and release gates |
Everything else in this repo (AI-agent-development scaffolding, research search, feature specs, frontend animation, deployment, release checks, ...) is auto-detected and wired into these three - see docs/PROCESS.md and the full command table in AGENTS.md.
Each master command is a router. A deterministic script reads the workspace - plan state,
doubts, tasks, gates, the source tree, the verification ledger - and writes one phase line
into plan/SESSION_MANIFEST.md. The command loads that phase's file, finishes it,
recomputes, and continues until its terminus or a named Stop Condition. Every run opens
with loop session-start and closes with loop session-end, which is what keeps memory
durable across tools.
| Phase | Runs when |
|---|---|
| grill | the plan is uninitialized, or pivoting |
| resolve-doubts | a blocking doubt can be answered now |
| council | an open decision records two or more options |
| ultraplan | platform scale with an incomplete step |
| spec-clarify / spec-checklist | the active feature spec is missing, open, or unchecked |
| task-compiler | the spec is ready: AC-numbered acceptance, files, size caps |
Terminus: tasks compiled and a go/no-go for build.
| Phase | Runs when |
|---|---|
| clarify | a blocking doubt can be answered now |
| scaffold | there is no source tree yet |
| implement | a task is active - plan the diff, loop plan-check, build, loop test |
| test | a QA task, or built but not verified for the current source |
| converge | verified - drift, caps, duplicates, independent review, loop verify done |
| evaluate | eval cases exist and the score is stale or regressed |
| release / deploy | every task done - prod-gap, security, CI/CD, then approved deployment |
Terminus: the build slice is complete, verified, reviewed and converged.
Routes to the planning branch while plan gates are blocked, and carries straight on into the build branch when they pass. Needs-a-decision blocks, unsatisfied contracts between sub-products and blocking doubts are worked first.
Loads the full plan surface, routes each stated fact to the file that owns it, reopens any gate the change invalidates, and records the revision - instead of re-running grill.
Every skill stays; not every skill sits in every session. A skill description in front of the model on every run is paid for on every run, and a large menu is itself a failure mode - gains from skills halve past three per task, and self-generated or heavyweight skills made tasks worse (SkillsBench).
| Tier | What it is | How it loads |
|---|---|---|
| Core (38) | Entry points and the skills most runs need | Listed in every harness with its description |
| Library (90) | Everything else, none removed | A phase file names it; the session manifest matches its signals against your words and the active task; or loop skills find "<need>" |
manifests/skill_triggers.json holds the split and the signals. Each harness gets the
cheapest install it supports: Claude Code hides library descriptions and keeps /name
typable (disable-model-invocation), slash-command harnesses keep every command with a
one-line description, and natural-language-only harnesses get core routers only.
Windows:
irm https://raw.githubusercontent.com/harshpgoti/loop-engineer/main/install.ps1 | iexmacOS / Linux:
curl -fsSL https://raw.githubusercontent.com/harshpgoti/loop-engineer/main/install.sh | bashThen open your agent in %USERPROFILE%\.loop-engineer\app (Windows) or ~/.loop-engineer/app (macOS/Linux) and run /plan-loop.
Full install options: docs/INSTALL.md.
Main/
├── loop-engineer/
└── product/
Open the agent in loop-engineer/, then register the product workspace once:
/setup-loop-engine
Use:
/setup-loop-engine
/plan-loop
/develop-product
/loop-engine
Agents should interpret these commands by reading skills/. On first run, /plan-loop initializes the user's product data automatically into plan/main_plan.md, plan/, memories/MEMORY.md, DOUBTS.md, and TASKS.yml - all inside the workspace data root, never inside the tool repo.
In central-tool setup, those product files are written to the registered product workspace, not into loop-engineer/.
Tools that do not auto-read repository instructions use AGENTS.md directly.
For install/copy instructions, see docs/INSTALL.md.
For central-tool vs embedded setup, see docs/DATA_LAYOUT.md.
For data layout and auto-detection, see docs/DATA_LAYOUT.md.
These live in the workspace (the folder you run in) - created at setup from templates/starter/. The tool repo carries no live state files.
| File | Purpose |
|---|---|
memories/MEMORY.md |
Human-mind progress: what happened, what is happening, what is next |
memories/USER.md |
User profile and durable preferences |
memories/SOUL.md |
Agent voice/behavior for this product |
DOUBTS.md |
Open user questions and grill points |
CONTEXT.md |
Repo map, conventions, and ## Language - the product's own words |
plan/main_plan.md |
Full product plan for the current user |
plan/ |
Per-step product plans |
CURRENT_STATE.md |
What is true right now |
TASKS.yml |
Active backlog |
DECISIONS.md |
Decision log |
EVIDENCE_LOG.md |
Source-backed claims only |
HANDOFF.md |
Next agent instructions |
GATES.yml |
Hard stop/go criteria per phase |
Every agent session that touches the product runs the internal lifecycle, in any tool:
loop session-start --command "<slash-command>" --tool "<tool>"
# read plan/SESSION_MANIFEST.md
# ... do the work ...
loop session-end --summary "<progress>"These are internal runtime calls shown for maintainers; the user does not run them. This is
what makes memory durable across chat sessions and tool switches - see
docs/SESSION_LIFECYCLE.md. The agent runs it, not the user.
A task is not done because an agent said so. loop test records every run with a
fingerprint of the source it ran against, and loop verify done <task> is the only way a
task closes: it needs a green run for the current source, or a written reason tests could
not run. The build router sends built-but-unverified work back to test, /commit runs
loop check (credential values, unscoped tenant queries, diffs over the task's cap,
untested source), and where hooks are installed an existing test cannot be edited to get
green. A red test is a finding; stopping with a named blocker is a successful outcome.
Three things used to sit in a file waiting for someone to remember them. All three are now
raised in the session, with a recommended answer, by /plan-loop, /develop-product,
/loop-engine and /revise-plan.
Doubts are asked in rounds. A doubt can declare what it waits on:
### DQ-009: Which PMS do we integrate first?
- **Status:** open
- **Blocking:** yes
- **Depends on:** DQ-005
- **Default if unavailable:** Whichever the design partner already runs.Without that line this gets asked in the same breath as DQ-005, and the only honest answer is
"ask me again once I have a partner". With it, the round holds DQ-009 back and says what it is
waiting on. Answering or deferring DQ-005 advances the frontier - going with the default is
a decision. A prerequisite written only in prose gets caught by loop doubts lint.
Questions that are not yours to answer leave the critical path. Mark one
- **Ask:** the clearinghouse rep and loop doubts questionnaire writes their questions out as
a document to send, with the assumption we proceed on if nobody replies.
A parent product's disagreements are derived fresh every session from both plans and asked
the same way, never queued. See docs/SCOPES.md.
A plan has three kinds of unknown, and each has somewhere to live:
| Where | ||
|---|---|---|
| A question you can state | DOUBTS.md |
Asked in rounds, with a recommendation |
| A decision you can see coming but cannot yet phrase | plan/main_plan.md → ## Not yet specified |
Timed; chased once it stops clearing |
| Work you have ruled out | plan/main_plan.md → ## Out of scope |
Never graduates - stops it being re-suggested |
The test for the middle one is whether you can state it precisely now, not whether you can answer it. Fog is meant to clear, so it is timed from when the patch first appeared: after 28 days the session manifest says so, and the active planning command either promotes it to a real question or records it as work deliberately ruled out.
CONTEXT.md gets a ## Language section: one opinionated name per concept, and the synonyms
it displaces.
**Denial**
A claim the payer adjudicated and refused to pay.
_Avoid_: rejection, declineThe internal glossary validator counts where a displaced synonym is still used across the plan, most-entrenched first, and surfaces it in the session manifest. It reports and never rewrites - when two words turn out to name different things the answer is two definitions, not a rename, and that call is yours.
In order of a real product journey - every command works the same in Cursor, Claude Code, Codex, OpenCode, Grok Build, or any other coding agent with filesystem access.
/setup-loop-engine # registers this workspace and seeds starter files
/migrate-import # imports memory/skills from another tool when needed
/plan-loop
/plan-loop an AI receptionist for dental clinics that answers calls and books appointments
Initializes the product on first run (asks name, target user, problem, first step, deployment targets), then: grill → product council → fact-check → PRD → architecture → feature spec → task compiler. Auto-detects platform-vs-convenient scale and routes /ultraplan-loop when needed.
Grilling happens in rounds. Each round is the set of questions whose prerequisites are already settled, numbered, every one carrying a recommended answer. Questions that depend on an answer you have not given yet wait for the next round instead of being asked early - see Questions get asked, not queued.
/develop-product
Builds from the approved plan, one task at a time: implementation plan → smallest safe diff → tests → code review → QA → security/compliance → docs → prod-gap. Frontend motion/3D and AI-agent work auto-route to the right built-in skills.
Code review runs on two axes reported separately - Spec (does it do what the task asked?)
and Standards (is it built the way this repo builds things?) - because a change can pass
either while failing the other. A red test whose cause is not obvious routes to
/diagnose-loop.
/loop-engine
/loop-engine a marketplace for local tutors with escrow payments
The primary entry point: routes between planning and development based on gates - give it an idea and keep re-running it.
/ask-loop # answer a question about the plan or the build from full context - read-only, cites sources
/revise-plan # correct or extend an existing plan; routes the edit to the right file
/plan-reconcile # reconcile a reform across every file it touches; retire dead planning
/resolve-doubts # clear every open blocker plan-wide, then give a go/no-go for development
/diagnose-loop # something is broken: build a loop that goes red on it, then hypothesise
/eval-loop # score the product's golden cases, catch regressions, let the failures pick the next task
/diagnose-loop refuses to theorise before it can name one command it has already run that
drives the real code path and asserts the symptom. /eval-loop also runs itself after any
change to agent behaviour - a prompt, a model, a tool definition - which unit tests cannot see.
/agent-builder # design/scaffold an AI agent as the product - auto-activates in /plan-loop + /develop-product
/research-search # search arXiv / Research Square / SSRN
/market-research # TAM/SAM/SOM, competitors, interviews, positioning, kill criterion
/competitive-platform-analysis # structured competitive analysis (direct / indirect / substitute)
/grill # the structured interview (66 questions, 11 categories) behind /plan-loop
/feature-new # create and activate a numbered feature spec
/spec-clarify # structured clarification on the active feature spec
/spec-checklist # spec quality gate before feature-plan
/feature-converge # post-build drift check vs spec/tasks
/feature-workflow # full per-feature pipeline: spec -> clarify -> checklist -> feature-plan -> tasks
/ultraplan-loop # deep per-step planning for platform-scale products
/frontend-animation # route to built-in GSAP / Motion.dev / 3D skills
/dynamic-workflow # design a task-local harness (Objective, Inputs, Loop, Eval, Handoff, Human_gate)
/council # four-voice council (Architect / Skeptic / Pragmatist / Critic) for ambiguous decisions
/council-multi-model # external-model critique on a council decision, with provider labels and consent
/dev-team # preset four-persona parallel review (PM / Architect / Developer / QA)
/adr # capture an architectural decision as a durable ADR
/decision-ledger # append a revisit to the recursive decision ledger
/recursive-decision-ledger # record prior winner, fresh evidence, search space, and outcome
/codebase-onboarding # 4-phase recon -> architecture -> conventions -> ONBOARDING.md
/inherit-legacy-style # codify a hand-written legacy codebase's style into .ai-style-rules.md
/api-design # REST/HTTP conventions: resources, status codes, error envelopes, versioning
/error-handling # map internal exceptions to the public error envelope; typed errors
/contract-first # canonical cross-boundary contracts (OpenAPI / AsyncAPI / JSON Schema)
/loop-design-check # 5-failure-mode review of a closed loop's design
/latency-critical-systems # p99 budget, hot path, profile before/after, CI regression test
/safeguard # prompt-defense baseline for skills/agents that handle user input
/gateguard # enforce a release gate as a machine-verifiable Stop hook
/strategic-compact # suggest /compact at phase boundaries, not token thresholds
/code-simplifier # read-then-edit refactor that preserves behavior
/comment-analyzer # verify comment accuracy/staleness (Inaccurate / Stale / Incomplete / Low-value)
/performance-optimizer # algorithmic complexity + Web Vitals + bundle analysis, profiled
/refactor-cleaner # dead-code hunter (knip / depcheck / ts-prune); SAFE / CAREFUL / RISKY
/type-design-analyzer # score type design (Encapsulation / Invariant / Usefulness / Enforcement)
/pr-test-analyzer # test quality not count; Critical / Important / Nice-to-have gaps
/harness-optimizer # eval-driven harness tuning via pass@k / pass^k
/agent-eval # head-to-head agent comparison on a YAML task suite in isolated worktrees
/qa-validation # unit, integration, E2E, golden, schema, tenant-isolation checks
/security-compliance # secrets, sensitive data, tenant isolation, audit logs, prompt injection, IDOR
/data-engineering # data models, migrations, pipelines, quality, lineage, retention
/ml-engineering # dataset versioning, training, evaluation, registry, inference, rollback
/operations # observability, SLOs, incident response, backups, capacity, recovery
/living-docs-governance # detect docs/code drift; deterministic checks; drift report + tasks
/network-architect # subnets, firewall rules, DNS, load balancers, VPN, ingress design
/network-troubleshooter # read-only OSI-layer diagnosis with evidence-based root cause
/network-config-reviewer # audit running network device config (SSH, SNMP, AAA, Telnet, HTTP)
/lint # run the project's linter
/test # run the project's test suite
/format # format the project
/commit # stage and commit with a conventional-commits message
/docs # create/update product docs (plans, PRDs, ADRs, runbooks, release notes)
/handoff # read or write HANDOFF.md at any chain transition
/learn-curator # promote eligible observations to staged records (runs at /session-end)
/revise-skill # revise an existing skill's SKILL.md safely: checklist, audit, tests, minimal diff
/iterative-retrieval # three-round retrieval loop; each round refines the query
/plan-orchestrate # coordinate a multi-plan DAG run; emit ORCHESTRATION_LOG.md
/parallel-execution-optimizer # decide sequential vs parallel for a multi-step task; emit a plan
/dashboard-builder # self-contained HTML dashboard from a YAML spec (no JS frameworks, no CDN)
A product too big for one folder gets a main folder with the master plan and sub-product
folders that plan and build on their own - each with its own .loop-engineer/:
main-product/
├── .loop-engineer/ THE workspace - master plan + every sub-product's plan
│ └── plan/products/auth/ one sub-product: prd, steps, features, TASKS, GATES, DOUBTS
├── services/auth/ its code (or another repo entirely - scope.json says where)
└── apps/portal/
Sub-products under the main folder are found automatically. For one in another repo, tell
the agent “link ../billing as a sub-product” while using /product-tree. Working inside a sub-product still uses that
sub-product's workspace - the difference is that the main plan can now see them, and says
when a sub-product's plan contradicts it (conflicting cloud, datastore, or decision;
unmapped sub-product; missing contract). Corrections are staged into the sub-product
for approval, never written into it. Single-product workspaces are unaffected.
/product-tree # roles, roll-up, and where a sub-product's plan contradicts the master plan
A row typed sub-product in plan/PRODUCT_MAP.md is a statement that the work will live
from the row title (which is what map_id binds on), seeds the workspace, hands over the
row's step plan so it does not re-plan from nothing, and links both ends. It reports the
main-product tasks carrying the gate the row declares - and does not move them, because
the new workspace compiles its own.
The layout above gives every sub-product its own workspace, and everything that keeps the two ends agreeing is a bridge across that boundary. A sub-product needing something from another sub-product has no channel at all - it can only be reported as two plans disagreeing.
The alternative is one workspace, with each sub-product as a scope:
main-product/
├── .loop-engineer/plan/products/auth/ plan, tasks, gates, doubts - all of it here
├── .loop-engineer/plan/contracts/ what auth provides, and who consumes it
├── services/auth/ its code
└── apps/portal/
Everything is run from the main folder, naming the sub-product in the command:
/plan-loop start working on auth product
/develop-product continue the portal checkout flow
/scope # which sub-products exist, and which one is active
/scope check auth and portal # contracts, blockers, cycles across sub-products
/scope absorb the auth-service folder # fold its own workspace into this one
Or just say it: "work on the portal checkout flow", "merge the auth sub-product into the main workspace".
A portal task can now be blocked_by an auth task, and a contract has one provider and
real consumers - so nothing needs syncing. Sub-products in another repo stay
federated, exactly as above. /scope absorb migrates an existing one and
/scope eject reverses it.
Details: docs/SCOPES.md
Details of the federated model: docs/SCOPES.md
/develop-product reaches deployment on its own once the release gate passes and the
plan names a real cloud - or say "lets deploy this" to go there now.
/deploy # deploy the chosen environment to the chosen cloud
/deploy to staging
what did we create in AWS? # the inventory, per environment
what can I delete? # dev resources that have outlived their reason
Two things make it safe to repeat. It reads the provider's current official docs before running any command rather than deploying from memory, and it records every resource the moment it is created - what it serves, which sub-product, which environment, and the command that removes it:
| ID | Env | Provider | Service | Resource | Purpose | Scope |
| R-001 | dev | aws | ECS | denial-api-dev | denial engine API | denial |
| R-002 | dev | aws | RDS | denial-db-dev | application database | denial |
That is what makes a temporary environment findable later. dev rows are treated as
disposable and are the ones offered for teardown; prod and staging never are.
Creating and deleting both stop and ask first - one question listing everything, with
costs, not a prompt per resource.
Details: docs/DEPLOYMENT.md
/status # snapshot: workspace, gate, task, blockers, next command
/doctor # health-check runtime + workspace
/prod-gap # launch-gap analysis into plan/PROD-GAP.md
/sync-loop-state # reconcile MEMORY / HANDOFF / TASKS / GATES drift
/deployment-plan # write or refresh DEPLOYMENT_PLAN.md
/release-check # pre-production readiness check
/session-start # durable context summary before long runs or tool switches
/migrate-import # import another tool's data after setup; add --scan to classify arbitrary files by content
/upgrade-loop-engineer # update tool files without touching product data
/config-gc # walk the workspace for env vars / flags / config entries no longer referenced
/automation-audit-ops # audit every automation (CI, hooks, scripts) for stale, unowned, or risky ones
/codehealth-mcp # code-health snapshot: lint debt, coverage, churn, dep freshness, doc coverage
/self-audit # walk the LE app's own state: policy consistency, reachability, budgets
/roles # list every role: class, model tier, skills, hand-off targets, independence
/skill-list # list every skill: class, owning capability, activation paths
/agent-sort # classify skills/commands/agents as DAILY vs LIBRARY with evidence tables
/skill-scout # before creating a skill, search local + adjacent ecosystems; vet externals
/hookify-rules # turn a one-off hook event into a reusable rule; verify before adoption
/chain-bench # inventory of the chain's size - not a quality score
/bench-history # record and diff chain benchmarks over time; trend deltas vs prior snapshot
/chain-catalog # render the full chain surface as a single Markdown catalog page
/harness-catalog # consolidate per-coding-agent harness JSON into one discoverable view
/onboard # print/open the Loop Engineer contributor onboarding guide
/conversation-analyzer # mine session transcripts for corrections, repeated mistakes, injection attempts
loop test # run the configured tests and record the result against the current source
loop tests impacted # the tests that cover the files you changed
loop verify done <task> # close a task, citing the green run (or --waiver "<why>")
loop plan-check --plan <file> # what an implementation plan names that the spec never does
loop check # executable constraints on the working tree
loop mutation # mutation score for the task's tests, when a mutator is configured
loop skills find "<need>" # the skill for a need, core or library
loop hooks install # hard enforcement hooks where the format is verified (Claude Code, Cursor)
loop providers --tool <tool> # whether review and council run on a second provider
loop probe # which context-file lines agents actually use, from the trace
/session-start # recall, manifest, auto-skills; normally automatic
/session-end # memory review and state history; normally automatic
/session-recall # recall only (normally inside session-start)
/memory-review # memory curation only (normally inside session-end)
Full, current list: loop skill-list. Find one for a need: loop skills find "<need>".
For recurring Cursor work:
/loop 2h /loop-engine
| Tool | Entry |
|---|---|
| Cursor | CURSOR.md, AGENTS.md |
| Claude Code | CLAUDE.md, AGENTS.md |
| Codex | CODEX.md, AGENTS.md |
| OpenCode | OPENCODE.md, AGENTS.md |
| Grok Build | GROK.md, AGENTS.md |
| Any other agent | AGENTS.md (portable interpretation) |
Canonical skills are in skills/; adapter files must stay thin.
When someone downloads this repo and runs /plan-loop, the agent must:
- Detect whether
plan/main_plan.mdis still uninitialized. - Ask for product name, target user, problem, constraints, and first product step.
- Ask for deployment targets during planning: cloud provider, single vs multi-cloud, LLM provider/model, and related infrastructure choices.
- If the user is unavailable, record questions in
DOUBTS.md. - Create or update
plan/step_01_<slug>.md. - Update
memories/MEMORY.md,TASKS.yml,GATES.yml,HANDOFF.md, and.ai/SESSION_LOG.md.
No product-specific data should be committed to this template repo.
Agents may use:
python scripts/init_product.py --name "<product>" --first-step "<step>" --target-user "<user>" --problem "<problem>"To validate the template before publishing:
python scripts/validate_template.pySee docs/PROCESS.md for architecture, CI gates, and the product loop.
See docs/PROCESS.md for the /plan-loop, /develop-product, and /loop-engine process architecture.
Four reference skills the build loop loads when they apply. None of them needs a command - the phase that needs one reads it.
| Skill | When it loads | What it settles |
|---|---|---|
codebase-design |
Placing a seam or shaping an interface | Shared words: module, interface, depth, seam, adapter, leverage, locality |
tdd |
Writing or reviewing tests | Which seam to test at, and the three ways a test ends up proving nothing |
code-reviewer |
After code edits | Spec and Standards as separate axes, plus a twelve-smell baseline |
diagnose-loop |
A bug the diff does not explain | A feedback loop that goes red before any theory is allowed |
The bar tdd adds to "tests required" is mostly about the tautological test - where the
expected value is computed the way the code computes it, so the test passes by construction and
can never disagree with the code:
expected = sum(i.price for i in items) # recomputes the implementation
assert calculate_total(items) == expected # proves nothing
assert calculate_total([{"price": 10}, {"price": 5}]) == 15 # an independent factEvery check below is deterministic, and each one exists because something drifted without anyone noticing: an unreachable command, an orphaned skill, a README five commits stale.
python scripts/validate_template.py
python scripts/validate_outputs.py --workspace <your-product-workspace>
python scripts/doctor.py
python scripts/detect_workspace.py
python scripts/migrate_workspace.py --list
python scripts/skill_triggers.py check # every skill has a tier; descriptions fit 25 wordsSee Operations & maintenance in Command Usage above. After upgrading the runtime, apply workspace migrations:
python scripts/migrate_workspace.py --workspace ../productUse:
/session-start
This updates plan/SESSION_MANIFEST.md so Codex, Claude Code, Cursor, OpenCode, Grok Build, or any other agent can continue without relying on chat history.
For parent workspace setup:
python scripts/compact_context.pyUse:
/upgrade-loop-engineer
See docs/UPGRADE.md. The upgrade flow preserves product-state files like plan/main_plan.md, plan/, memories/MEMORY.md, TASKS.yml, EVIDENCE_LOG.md, and HANDOFF.md.
Rubrics:
evals/plan_quality_rubric.mdevals/development_quality_rubric.md