[Extension]: Add Loop Engineering

[formin]

Extension ID

loop

Extension Name

Loop Engineering

Version

1.0.0

Description

Engineer safe autonomous agent loops for spec-driven development: a maker/checker split, externalized loop state, and stay-the-engineer guardrails against comprehension debt and cognitive surrender

Author

formin

Repository URL

https://github.com/formin/spec-kit-loop

Download URL

https://github.com/formin/spec-kit-loop/archive/refs/tags/v1.0.0.zip

License

MIT

Homepage (optional)

https://github.com/formin/spec-kit-loop

Documentation URL (optional)

https://github.com/formin/spec-kit-loop/blob/main/README.md

Changelog URL (optional)

https://github.com/formin/spec-kit-loop/blob/main/CHANGELOG.md

Required Spec Kit Version

=0.2.0

Required Tools (optional)

Number of Commands

5

Number of Hooks (optional)

2

Tags

loop-engineering, automation, verification, maker-checker, workflow

Key Features

• Operationalizes Loop Engineering (Addy Osmani, https://addyo.substack.com/p/loop-engineering) for spec-driven development: a loop is a recursive goal — define a purpose, let the agent iterate until complete — but built "like someone who intends to stay the engineer."
• /speckit.loop.define — write the loop as a contract: purpose, explicit checkable done-criteria (it refuses an open-ended loop with no stop condition), iteration budget, maker/checker roles, allowed tools, and guardrails. Creates five externalized state files (loop.md, iterations.md, verdicts.md, debt.md, memory.md).
• /speckit.loop.run — the maker: produce one reviewable increment toward the goal, externalize it to disk, and hand off. Never grades itself; max_iterations is a hard ceiling so making can't drift.
• /speckit.loop.check — the independent, adversarial checker: grades the latest iteration against each done-criterion at the primary source (the model that wrote the code shouldn't grade it). Records pass/fail/uncertain + method + confidence.
• /speckit.loop.guard — the stay-the-engineer checkpoint: comprehension-debt sweep, unattended-verification flags, anti-cognitive-surrender questions, and a human sign-off gate. The only command that can close the loop.
• /speckit.loop.status — budget-aware rendering of loop state + one recommended next action; safe session resume.
• Optional hooks: after_tasks -> speckit.loop.define, after_implement -> speckit.loop.check. Prompt-only — no external tools or network access.

Testing Checklist

• Extension installs successfully via download URL
• All commands execute without errors
• Documentation is complete and accurate
• No security vulnerabilities identified
• Tested on at least one real project

Submission Requirements

• Valid extension.yml manifest included
• README.md with installation and usage instructions
• LICENSE file included
• GitHub release created with version tag
• All command files exist and are properly formatted
• Extension ID follows naming conventions (lowercase-with-hyphens)

Testing Details

Tested on:

• Windows 11, specify CLI 0.10.1 (uv/uvx), Claude Code integration.

Test project: fresh specify init loop-ext-test --integration claude scaffold.

Test scenarios:

1. Manifest validated: YAML parses; id matches ^[a-z0-9-]+$; version 1.0.0; all five provides.commands[].file paths resolve; command names match speckit.{ext-id}.{command}; hooks reference defined commands; description 197 chars (<200).
2. Installed via specify extension add <dir> --dev -> specify extension list shows Loop Engineering 1.0.0 (5 commands, 2 hooks, Enabled); five speckit-loop-* skills registered for Claude; config-template.yml copied to .specify/extensions/loop/; loop present in .specify/extensions/.registry.
3. Installed from the release archive: specify extension add loop --from https://github.com/formin/spec-kit-loop/archive/refs/tags/v1.0.0.zip (HTTP 200, application/zip) -> installs and enables.
4. Lifecycle end-to-end on a scaffold feature (agent-executed): define -> run -> check -> guard -> status. State files created; criteria transition pending -> maker-ready -> checker-pass; done-gate holds Phase: done only after checker-pass on all criteria AND a recorded human sign-off.
5. Confirmed define is idempotent and status is read-only.

Example Usage

# Install
specify extension add loop --from https://github.com/formin/spec-kit-loop/archive/refs/tags/v1.0.0.zip

# After /speckit.tasks, turn the task list into a bounded, graded loop
/speckit.loop.define Drive tasks.md to done max_iterations=8   # contract + checkable done-criteria
/speckit.loop.run                                              # maker: one externalized increment
/speckit.loop.check                                            # checker (fresh session): adversarial verdicts
/speckit.loop.run D3                                           # address a checker-fail
/speckit.loop.guard                                            # comprehension-debt sweep + anti-surrender prompt
/speckit.loop.guard signoff                                    # human sign-off -> Phase: done
/speckit.loop.status                                           # resume / decide next, from files only

Proposed Catalog Entry

{
  "loop": {
    "name": "Loop Engineering",
    "id": "loop",
    "description": "Engineer safe autonomous agent loops for spec-driven development: a maker/checker split, externalized loop state, and stay-the-engineer guardrails against comprehension debt and cognitive surrender",
    "author": "formin",
    "version": "1.0.0",
    "download_url": "https://github.com/formin/spec-kit-loop/archive/refs/tags/v1.0.0.zip",
    "repository": "https://github.com/formin/spec-kit-loop",
    "homepage": "https://github.com/formin/spec-kit-loop",
    "documentation": "https://github.com/formin/spec-kit-loop/blob/main/README.md",
    "changelog": "https://github.com/formin/spec-kit-loop/blob/main/CHANGELOG.md",
    "license": "MIT",
    "category": "process",
    "effect": "read-write",
    "requires": { "speckit_version": ">=0.2.0" },
    "provides": { "commands": 5, "hooks": 2 },
    "tags": ["loop-engineering", "automation", "verification", "maker-checker", "workflow"],
    "verified": false,
    "downloads": 0,
    "stars": 0,
    "created_at": "2026-06-14T00:00:00Z",
    "updated_at": "2026-06-14T00:00:00Z"
  }
}

Additional Context

This is a process extension (read-write): it wraps the build-and-verify portion of the Spec Kit workflow (tasks -> implement) in a bounded, graded, signed-off loop, and never edits spec.md/plan.md/tasks.md. Prompt-only — the "infrastructure" is markdown files in the feature directory — so it works with any agent Spec Kit supports and needs no external tools or network access. Design adapts Addy Osmani's "Loop Engineering" essay (https://addyo.substack.com/p/loop-engineering); per-mechanism mapping and honest limits are in docs/concepts.md. Not affiliated with the author or GitHub.

[github-actions]

cc @github/spec-kit-maintainers — new catalog submission for review.

[github-actions]

cc @github/spec-kit-maintainers — new catalog submission for review.