LoopForge

中文文档 | English

Solo dev juggling several legacy codebases - no specs, no tests, a pile of spaghetti - and blocked by TDD? 【LoopForge】One command delivers an “AI-collaboration maturity” report + action plan, then scaffolds a structured Claude Code / Codex workflow - so spec-driven development runs on legacy code instead of being blocked by TDD’s iron law.

---

Overview

LoopForge starts from a simple question: how do you keep moving when you're a solo developer maintaining multiple legacy projects in production — no spec docs, no tests, a pile of legacy spaghetti code — without getting stuck?

Excellent frameworks spec-superflow assume a greenfield or test-backed baseline; on untested legacy code they would correctly block every change. LoopForge learned from them and took a different path: a lightweight generator approach (shell + Python) that audits what's missing first, restructures without disrupting existing code, and safely degrades TDD with characterization tests and debt logging where strict rules would otherwise stall.

Built around the industrial-grade three-layer paradigm (OpenSpec + Superpowers + Harness, a.k.a. OSH / Loop Engineering), LoopForge ships as an AI-collaboration optimization skill in two parallel editions — each with its own scaffold.sh (CC edition creates .claude/, Codex edition creates .agents/):

Edition	Skill	AI tool	Live entry file	Discipline (HOW)	Loop driver
Claude Code	loopforge-cc	Claude Code	CLAUDE.md	Superpowers skills in .claude/skills/	/opsx: slash commands
Codex	loopforge-codex	Codex	AGENTS.md	Encoded as instructions in AGENTS.md	openspec CLI + natural language

Both editions scaffold, audit, and restructure a project's AI-collaboration structure against the OSH standard. Three modes in each:

Mode	Purpose
scaffold	Generate a complete new framework from scratch via scaffold.sh
audit	30-check maturity scoring (E1–E4, O1–O8, S1–S9, H1–H8)
restructure	Split a monolithic CLAUDE.md / AGENTS.md into per-stack agents + optimize

Core Philosophy:

• OpenSpec defines direction (WHAT)
• Superpowers enforces discipline (HOW)
• Harness orchestrates collaboration (WHO)

Primary use case: one-person team (OPC) taking over multiple frontend-backend separated legacy projects already in production. The skill set provides:

• 30-check audit to diagnose what each legacy project is missing (specs? tests? agent separation? build verification?)
• Restructure mode to split a monolithic CLAUDE.md/AGENTS.md into per-stack agents without disrupting existing code
• Legacy-aware TDD (characterization tests + debt logging) so you can safely modify untested code without freezing
• Cross-stack coordination (LoopForge coordination docs + workset + OpenSpec --goal tags) so a one-person team can orchestrate frontend + backend changes across separate repos
• SDD (Subagent-Driven Development) to dispatch implementer/reviewer subagents per task, preventing context bloat when juggling multiple projects
• Compile-gated verification via openspec/verify.config.yaml -- the local /opsx:verify L1 build check confirms each stack compiles before push. The three-layer verify produces a verify.md credential that gates archival
• Parallel per-change workflow (2.4.0) -- per-change loop-state.yaml + optional files.yaml ownership declaration + check-conflicts.sh gate, so changes in disjoint modules run in parallel sessions; only archiving stays serial
• Token-efficiency discipline -- targeted context loading, file-backed build/test logs with exit-code summaries, compact contracts/reports, affected-test-first runs, and no automatic UI screenshots

Positioning

The differences are about fit for the scenario, not superiority:

Dimension	spec-superflow	LoopForge
Approach	Runtime (npm + Node.js hooks, always-on)	Generator (scaffold.sh -> static files, zero runtime dep)
Gate enforcement	Node.js code + unit tests (testable, robust)	shell + Python (lightweight, readable; no unit-test coverage)
State machine	8 named states + unit tests	4 phases (key paths mirrored, less granular)
Platform support	17	2 (Claude Code + Codex)
Self-contained	✅ source-level fusion	❌ depends on OpenSpec CLI (+ Superpowers for CC)
Token efficiency	systematic baseline (-60.3%)	per-file budget gates
Legacy migration	❌ none	✅ audit -> restructure -> characterization tests -> debt logging
Cross-stack orchestration	❌ none	✅ per-stack agents + coordination docs
Compile-gated verification	❌ none	✅ verify.config L1 build check + verify.md

Where spec-superflow is the better choice (and we'd recommend it without hesitation): greenfield projects, multi-person teams, multi-platform toolchains, projects with an existing test baseline, and anywhere strict planning→execution consistency matters. Its engineering quality — typed schemas, unit-tested gates, independently testable skills — is genuinely impressive, and we make no claim to match it.

Where LoopForge simply happens to fit our corner: a one-person team rescuing untested, undocumented legacy codebases — the six capabilities listed in the Overview above. spec-superflow's TDD "iron law" would correctly block real-code changes on a testless 5-year-old project — LoopForge adds a characterization-test + debt-logging degradation path so you can move forward safely instead of freezing.

spec-superflow is the polished, general-purpose solution; LoopForge is a humble, scenario-specific adaptation that learned from it. If your project is already disciplined, use spec-superflow. If you're rescuing legacy code, LoopForge was built for that.

Install

Claude Code - loopforge-cc

Copy the skill into your project (auto-loaded from .claude/skills/):

cp -r skills/loopforge-cc /path/to/project/.claude/skills/loopforge-cc

Trigger via the /loopforge-cc slash command, or just describe the task in natural language.

Codex - loopforge-codex

Install globally into Codex's skills directory, then restart Codex:

cp -R skills/loopforge-codex ~/.codex/skills/loopforge-codex

scaffold.sh ships as a real file inside the skill directory, so a plain copy is enough. After restart, the skill auto-triggers from its description or can be invoked explicitly via $loopforge-codex; openspec init --tools codex additionally generates the OpenSpec workflow skills (.agents/skills/openspec-* in OpenSpec 1.15+). The /opsx:verify three-layer check is LoopForge-added, not part of OpenSpec.

If you previously copied the old version into ~/.codex/skills/loop-eng, remove it first to avoid both skills triggering on the same intent: rm -rf ~/.codex/skills/loop-eng.

Scaffold a new project

Each edition has its own scaffold.sh. CC creates .claude/; Codex creates .agents/. Both generate CLAUDE.md + AGENTS.md mirrors:

# Claude Code (creates .claude/)
./skills/loopforge-cc/scaffold.sh myapp

# Codex (creates .agents/)
./skills/loopforge-codex/scaffold.sh myapp --tools codex

# three stacks (web + mobile)
./skills/loopforge-codex/scaffold.sh myapp --stacks backend,frontend,frontend-mobile --tools codex

# custom target dir + skip init
./skills/loopforge-cc/scaffold.sh myapp --dir ./projects/myapp --no-init

Options: --stacks, --dir, --backend-dir, --frontend-dir, --mobile-dir, --tools (CC defaults claude, Codex defaults codex; affects openspec init only), --no-init.

scaffold.sh CLI subcommands

Beyond the default scaffold, scaffold.sh ships ten more subcommands (run directly or ask the AI to run them):

Subcommand	Purpose
list [opts]	Preview the file manifest without writing anything
check [project]	Self-check (env + script) + LoopForge compliance audit; no arg = self-check only
tokens [project]	Token audit of auto-loaded files - per-file tokens + CJK% (O7 overhead)
validate <change-dir>	Validate a change's artifact structure (proposal/spec/design/tasks)
changes [project]	List all changes and their phase/status
doctor [project]	Health check: deps, scaffold, guard, verify config
version	Print LoopForge version + environment
contract [--force] <change-dir>	Auto-generate execution-contract.md from planning artifacts
restructure [project]	Analyze a monolithic entry file and plan a per-stack split
conflicts [project]	File-ownership overlap check between active changes (parallel-safety gate)

check runs an automatable subset (24 items: 3 env self-check + 21 structure) and prints PASS/PARTIAL/FAIL + a maturity score; ask the skill for the full 30-check semantic audit. tokens measures the O7 CJK overhead per file (CJK_THRESHOLD env, default 10%).

What scaffold.sh generates

myapp/
├── CLAUDE.md                 ← nav hub (≤120 lines) - Claude Code entry
├── AGENTS.md                 ← nav hub for Codex (mirrors CLAUDE.md)
├── openspec/                 ← WHAT: README (incl. Project Overview), specs/{api,data,errors}, changes/_template, changes/archive
│   ├── sdd/                  ← SDD: implementer-prompt.md, reviewer-prompt.md, progress.md
│   ├── guard.sh              ← Phase gate: proposing→applying→verifying→archived
│   ├── ensure-branch.sh      ← Worktree isolation (legacy-aware git resilience)
│   ├── ensure-contract-fresh.sh ← Execution-contract freshness check
│   ├── check-conflicts.sh    ← File-ownership overlap check between active changes
│   ├── loop-state.yaml       ← Legacy shared state machine; per-change state lives in changes/<name>/loop-state.yaml
│   │                           changes/<name>/ optional files.yaml declares file ownership
│   └── verify.config.yaml    ← Per-stack build/test commands (local /opsx:verify L1/L3)
├── .claude/  (CC edition)    ← HOW: settings.json (perms+hooks), rules/, agents/{reviewer,coordinator,implementer}
├── .agents/  (Codex edition) ← HOW: skills/openspec-* (propose/apply/verify/archive + triggers; legacy: .codex/)
├── backend/{CLAUDE,AGENTS}.md   ← Backend Agent (Claude Code / Codex)
└── frontend-web/{CLAUDE,AGENTS}.md ← Frontend Agent (Claude Code / Codex)

CLAUDE.md and AGENTS.md are always generated together (mirrored), so the same project works in either tool. The CC edition creates .claude/; the Codex edition creates .agents/ - each only creates its own tool directory. Non-destructive: existing files are skipped, safe to re-run.

What you must install separately (per edition)

Both: OpenSpec CLI - npm i -g @fission-ai/openspec@latest, or standalone one-line install without Node: curl -fsSL https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/scripts/binary/install.sh | sh (macOS/Linux; irm .../install.ps1 | iex on Windows). Scaffold runs openspec init for you.

Claude Code only: Superpowers skills (brainstorm, writing-plans, executing-plans, code-review, verification-before-completion) and frontend-design (frontend projects). These live in .claude/skills/ and are auto-triggered by the /opsx: commands.

Codex: nothing extra - the Superpowers 5-step discipline is already encoded as instructions in each generated AGENTS.md, and the loop is driven by the openspec CLI.

Then fill [BRACKETS] placeholders in openspec/README.md (## Project Overview), openspec/specs/*, and per-stack CLAUDE.md / AGENTS.md.

Parallel development

Since 2.4.0 the workflow state is per change, not one shared slot - changes touching disjoint files run in parallel sessions:

1. Per-change state - each change owns openspec/changes/<name>/loop-state.yaml (phase, task counters, artifacts_hash). guard.sh and ensure-contract-fresh.sh read it first and fall back to the global openspec/loop-state.yaml (legacy). Cross-session overwrites are gone; the global file remains as fallback/dashboard only.
2. File ownership - declare the paths a change will touch in openspec/changes/<name>/files.yaml (one path per line; optional but recommended). Without it, the conflict check falls back to extracting path tokens from tasks.md / execution-contract.md (heuristic - keep declarations explicit for reliable results).
3. Conflict gate - run bash openspec/check-conflicts.sh (or scaffold.sh conflicts .) before apply. No overlap -> parallel-safe. Overlap -> serialize those changes or use separate git worktrees. The guard.sh proposing->applying gate also prints a non-blocking warning on overlap.
4. Parallel apply, serial archive - implementations run concurrently; only archiving (delta-spec merge into openspec/specs/) stays serialized.

New changes get the state template from openspec/changes/_template/loop-state.yaml. Pre-2.4.0 changes migrate automatically on the next bash openspec/ensure-contract-fresh.sh --update <change-dir> (it creates and seeds the per-change file).

Upgrading an existing project (pre-2.4.0): scaffold is non-destructive and will NOT overwrite already-generated scripts, so refresh the changed ones manually:

# generate a fresh skeleton beside the project, then sync the upgraded scripts
./skills/loopforge-codex/scaffold.sh fresh --dir /tmp/lf-fresh --no-init
cp /tmp/lf-fresh/openspec/guard.sh /tmp/lf-fresh/openspec/ensure-contract-fresh.sh <project>/openspec/
cp /tmp/lf-fresh/openspec/check-conflicts.sh <project>/openspec/
cp /tmp/lf-fresh/openspec/changes/_template/loop-state.yaml <project>/openspec/changes/_template/

Audit an existing project

Trigger the skill (e.g. "audit my project structure"). It runs Phase 0 (environment E1–E4) + Phase 1 (30 checks) and outputs a diagnostic table, maturity grade, top issues, and an action plan.

Codex note: scaffold.sh check is dual-source - it checks AGENTS.md first, then .claude/ as fallback. A Codex-only project (no .claude/) passes E3/E4/S4/S5/S6/S8/S8b via AGENTS.md, no false PARTIAL/FAIL.

Maturity scoring

Environment = E/4 · OpenSpec = O/8 · Superpowers = S/9 · Harness = H/8
Overall = (E + O + S + H) / 29

Score	Level
< 33%	Pre-build
33–66%	Basic
66–90%	Quality
> 90%	Industrial

Restructure a monolith

When a single CLAUDE.md (Claude) or AGENTS.md (Codex) covers multiple stacks, or the audit score is low: trigger the skill to split it into per-stack Agent files, rewrite the root as a nav hub, and apply the Phase 5 restructuring order.

License

See LICENSE.

Conversation playbook (manual): Claude Code edition USAGE-PLAYBOOK.md · Codex edition USAGE-PLAYBOOK-CODEX.md