Engineering Judgement in AI-assisted Development

AI can accelerate delivery, but engineering judgment keeps the work grounded in evidence. Develop Loop uses three quality levels: L1 phase self-review, L2 /devloop gate decisions, and L3 structural verification through loop-verify.sh and CI. See How Develop Loop enforces quality.

How do I validate requirements? Check that the problem, users, constraints, and acceptance criteria are explicit, testable, and traceable. L1 captures the requirement artifacts and review-log.md; L2 confirms the requirements gate can advance; L3 checks the package evidence and traceability files are present and consistent.
How do I validate design decisions? Review the design against accepted requirements, risks, dependencies, and operational constraints. Use architecture.md, the design review-log.md, the design gate, and the trace matrix to confirm acceptance criteria map to design choices and that trade-offs are recorded for human review. See How to review design quality.
How do I validate implementation quality? Do not judge code alone. Review the implementation plan, changed files, coding log, tests, code-review evidence, test-report evidence, and later gates; then confirm the AC -> design -> test -> code links remain intact and loop-verify.sh --enforce <id> passes for CI-level structure. See How to review implementation quality.

develop-loop-skills

AI-native SDLC loop skills for Cursor, Codex, and Claude Code.

Overview

Develop Loop turns coding agents into engineering process executors — producing reviewable, versioned, traceable artifacts across the full SDLC.

If you are adopting Develop Loop in an application repo, start with Install (consumers) and Use (in your project) below. The maintainer packaging notes are included later for contributors to this framework itself.

The skill set is distributed in two layers:

Layer	What	Where
Global skills	Agent behavior — orchestrator + 7 phase skills + traceability	`~/.cursor/skills/`, `~/.claude/skills/`, `~/.codex/AGENTS.md`
Project scaffold	Repo state — config, templates, verify scripts, artifact dirs	`.ai/`, `artifacts/`, `traceability/`, `AGENTS.md`

Phase evidence such as PRDs, design docs, review logs, and release notes lives in artifacts/. Gate records live in .ai/packages/<id>/gates/. Package-level traceability evidence lives in traceability/. Application code stays in your normal repo paths (src/, tests/, etc.) and is linked via changed-files.md and the trace matrix.

Package (maintainers)

The distributable is built from this repo into pack/ (gitignored). It is not committed — consumers get it via devloop CLI or npm.

Build the pack

./scripts/build-pack.sh

Produces:

pack/
  VERSION                 # e.g. 0.3.0 (from repo VERSION file)
  skills/                 # 9 self-contained SKILL.md trees
    devloop/
    01-requirement/ … 07-release-retro/
    traceability/
  templates/              # copied into target projects by devloop init
    .ai/config/profiles.yaml
    .ai/packages/_template/package.yaml
    .ai/packages/_template/classification.yaml
    scripts/loop-verify.sh
    scripts/test-loop-verify.sh
    artifacts/.gitkeep
    traceability/.gitkeep
    AGENTS.md
    .cursor/rules/devloop.mdc
    .devloop-version
    .github/workflows/loop-verify.yml  (added to projects only via init --with-ci)

Source of truth for skills remains .ai/skills/ in this repo. build-pack.sh copies them into pack/skills/ for distribution.

Verify the pack

./scripts/test-build-pack.sh      # layout: 9 skills + templates
./scripts/test-devloop-cli.sh     # install + init + doctor in temp dirs
./scripts/test-loop-verify.sh     # L3 verifier regression

Or run all via npm:

npm test

CI

Two GitHub Actions workflows guard this repo:

Workflow	Trigger	What it runs
`.github/workflows/build-pack.yml`	PRs/pushes touching `.ai/`, `bin/`, `templates/`, `VERSION`, or build scripts	`test-build-pack.sh` + `test-devloop-cli.sh` (pack layout + CLI install/init/doctor)
`.github/workflows/loop-verify.yml`	Pull requests	`loop-verify` in enforce mode (L3 contract checks)

Release checklist

Bump VERSION (and package.json version to match).
Run npm test.
Tag and publish (tarball from repo clone, or npm publish when configured).

Design: docs/superpowers/specs/2026-06-12-devloop-packaging-design.md

Install (consumers)

Option A — from a git clone (recommended today)

git clone https://github.com/renshengjun-coder/develop-loop-skills.git
cd develop-loop-skills

# 1. Global skills (once per machine)
./bin/devloop install --global

# 2. Project scaffold (once per app repo)
cd /path/to/my-app
/path/to/develop-loop-skills/bin/devloop init
# optional CI workflow:
/path/to/develop-loop-skills/bin/devloop init --with-ci

# 3. Verify
/path/to/develop-loop-skills/bin/devloop doctor

bin/devloop runs build-pack.sh automatically if pack/ is missing.

Option B — npm (when published)

npm i -g @develop-loop/skills
devloop install --global
cd my-app && devloop init --with-ci
devloop doctor

Install targets per runtime

Runtime	Global (`devloop install --global`)	Project (`devloop init`)
Cursor	`~/.cursor/skills/<skill>/SKILL.md`	`.cursor/rules/devloop.mdc`, merged `AGENTS.md`
Claude Code	`~/.claude/skills/<skill>/SKILL.md`	merged `AGENTS.md`
Codex	Develop Loop block in `~/.codex/AGENTS.md`	merged `AGENTS.md`

Limit runtimes: devloop install --global --runtimes cursor,claude

Upgrade

If you installed from a local git clone, rebuild the generated pack/ before upgrading so the global install picks up the latest skill sources:

git pull
./scripts/build-pack.sh
./bin/devloop install --global --upgrade
cd /path/to/my-app
/path/to/develop-loop-skills/bin/devloop init --upgrade
/path/to/develop-loop-skills/bin/devloop doctor

If you installed via npm, use the published CLI directly:

devloop install --global --upgrade   # refresh global skills
devloop init --upgrade               # refresh template-managed project files

devloop init --upgrade updates scaffolded files such as:

.ai/config/profiles.yaml
.ai/packages/_template/package.yaml
scripts/loop-verify.sh
.cursor/rules/devloop.mdc
.devloop-version
the Develop Loop block inside AGENTS.md

It does not rewrite package-specific working evidence under .ai/packages/<id>/, artifacts/<id>/, or traceability/<id>/.

devloop install --global --upgrade also removes stale legacy lifecycle-loop skill directories from Cursor and Claude installs when present.

`devloop` CLI reference

Command	Description
`devloop install --global`	Copy 9 skills to user-level agent dirs
`devloop install --global --upgrade`	Overwrite global skills with current pack version
`devloop install --global --runtimes cursor,claude,codex`	Limit install targets
`devloop init`	Scaffold project (idempotent; skips existing files)
`devloop init --with-ci`	Also add `.github/workflows/loop-verify.yml`
`devloop init --upgrade`	Refresh templates and verify scripts
`devloop init --force`	Overwrite template files (prompts for confirmation)
`devloop doctor`	Check global skills + project scaffold

Use (in your project)

After global install + project init, open your app repo in Cursor, Claude Code, or Codex.

Quick start

/devloop start FEAT-001          # create package, classify, pick profile
/devloop run FEAT-001            # start E2E loop; pauses at human checkpoints
/devloop continue FEAT-001       # resume from the last checkpoint or stop
/devloop status FEAT-001         # package status, blockers, run_control

Agent slash commands

Orchestrator: /devloop (not /loop — avoids Cursor built-in collision).

Command	Description
`/devloop start <id>`	Create package from template, classify, select profile
`/devloop run <id>`	E2E orchestration (loop mode; pauses after human-gate checkpoints and waits for `/devloop continue <id>` before any later phase starts)
`/devloop continue <id>`	Resume from a checkpoint, gate-fail stop, escalation stop, error stop, or interrupted run
`/devloop run <id> --pipeline`	Single pass per phase; stop on first gate fail
`/devloop gate <id> <phase>`	L2 gate check for one phase
`/devloop status <id>`	Summarize package, gates, blockers, and `run_control`
`/devloop classify <id>`	Re-run or confirm complexity classification

Standalone phase skills

You do not need /devloop run for every task. Invoke phase skills directly, e.g.:

Requirements — PRD, user stories, acceptance criteria
Design — architecture, API design
Test plan — test strategy, test cases
Implementation — plan, code, changed-files.md
Code review — AI review artifacts
Test report — execution summary, coverage
Release & retro — release notes, retro

Each phase writes to artifacts/<id>/<phase-folder>/ and updates .ai/packages/<id>/package.yaml.

Important: standalone phase skills create or update phase artifacts, but they do not issue a final pass decision on their own. The authoritative L2 gate record is written by /devloop run or /devloop gate.

Where things live

What	Path
Change package manifest	`.ai/packages/<id>/package.yaml`
Run control state	`.ai/packages/<id>/package.yaml` → `run_control`
Gate decisions (L2)	`.ai/packages/<id>/gates/`
SDLC artifacts	`artifacts/<id>/`
Trace matrix	`traceability/<id>/matrix.md`
Workflow profiles	`.ai/config/profiles.yaml`
Application code	Normal repo paths (`src/`, `lib/`, `tests/`, …)

How Develop Loop enforces quality

Develop Loop does not try to guarantee quality with a single check. It uses three levels so both humans and automation can inspect the same evidence:

Level	Trigger	Owner	Evidence written
L1	Automatically at phase end (Self Review), before Archive	Phase skill (agent)	`artifacts/<id>/<phase>/review-log.md`
L2	Automatically when `/devloop` finishes a phase and is about to advance (or `/devloop gate <id> <phase>`)	`devloop` skill only	`.ai/packages/<id>/gates/<phase>-<n>.md`
L3	Not during `/devloop run`. Manual `./scripts/loop-verify.sh` or CI on PRs touching `.ai/`, `artifacts/`, `traceability/`, or the script	Bash (no LLM)	stdout `PASS`/`FAIL` (no gate file)

Phase skill generates artifacts
        ↓
L1  Self Review  →  review-log.md   (inside the phase skill, before archive)
        ↓
Human review (only if phase is in human_gates)
        ↓
Archive phase (package.yaml → archived)
        ↓
L2  Gate check   →  gates/<phase>-n.md   (devloop, before next phase)
        ↓
Next phase / checkpoint / done
        ↓
L3  loop-verify.sh   (manual or CI — not inside /devloop run)

One-line summary:

Level	Question it answers
L1	“Is this phase’s output good enough to archive?”
L2	“May we advance past this phase?”
L3	“Does the repo’s evidence tree structurally match what we claim?”

In practice, this means the framework helps guarantee:

each archived phase has a defined evidence set for the active profile
gate records bind the exact artifact paths used for the decision
traceability evidence exists at the package level, not only inside phase folders
higher-risk work uses more human checkpoints than routine work
CI can independently reject missing or inconsistent evidence even if a phase looked complete locally

It does not automatically guarantee business correctness, good product decisions, or runtime behavior by itself. L3 is a structural quality door, not a substitute for thoughtful requirements, real tests, or human review.

L1 — phase self-review (concrete checks)

Owned by each phase skill. Blocking failures must be fixed before Archive. Phase skills never write gate PASS.

Phase	Concrete checks in `review-log.md`
Requirements	Clear user value; testable ACs; no ambiguity; boundaries defined; ≥1 AC per story; risks + mitigation; open questions closed; goals justified (YAGNI)
Design	Every AC covered; performance/NFRs; ≥2 failure scenarios; security if applicable; testable interfaces; ≥1 tradeoff documented
Test plan	Every AC has ≥1 TC; edge cases; boundaries; security tests if applicable; regression/smoke set
Implementation	Scope-only changes; design conformance; tests present (or N/A rationale); error handling; `changed-files.md` complete
Code review	Findings cite paths; repo comparison coherent; every changed path dispositioned; blocker ledger consistent; AC conformance; design-decision inventory; security lens; testability
Test report	Upstream inputs/digests match; every AC executed or waived; commands/results recorded; failures routed; coverage reconciled; go/no-go explicit; version set frozen; honest reporting
Release	Release notes / known issues / retro completeness via the release-retro skill’s own self-review checklist

L2 — gate before next phase (concrete checks)

From the devloop Gate Steps. All must pass for result: pass:

Required artifacts exist for the active profile (from evidence policy)
review-log.md exists with no unresolved blocking L1 failures
Typed trace links in artifact frontmatter (upstream refs)
Human approval recorded if phase is in human_gates (status: approved or approval.md)
traceability/<id>/matrix.md and package-evidence-index.md exist with no blocking gaps for this phase
Gate artifacts_checked binds the exact artifact paths reviewed (including package evidence; child refs on parent release)

On fail:

pipeline → stop (gate_fail)
loop → re-enter phase up to max_reentry, then escalate

After a human-gated phase passes L2, /devloop run pauses and requires /devloop continue before the next phase.

L3 — `loop-verify.sh` (concrete checks)

Deterministic file/structure checks. No judgment of PRD or design quality.

For each archived phase:

package.yaml + classification.yaml exist; profile set
Evidence policy configured and present
Required artifact files for that profile/phase exist under artifacts/<id>/…
Latest gate file exists and result: pass
Gate structure: profile, mode, reentry, next, artifacts_checked, checklist
Each required phase artifact (and package evidence when policy requires) is listed in artifacts_checked
Human-gate approval markers when phase is in human_gates (e.g. PRD status: approved, or approval.md for code-review/test-report/release)

Package-level:

Required files under traceability/<id>/ (e.g. matrix.md, package-evidence-index.md) — warn normally, error with --enforce
If status: ready_for_release, every profile phase must be archived
Parent release gate: child package refs, evidence index, latest child gate binding/pass/freshness when children exist

Triggers:

./scripts/loop-verify.sh FEAT-001              # local / observe
./scripts/loop-verify.sh --enforce FEAT-003    # CI / merge bar

Plus GitHub Actions on PRs that touch .ai/, artifacts/, traceability/, or the script (when devloop init --with-ci was used and branch protection is configured).

How to review design quality

If the active profile includes design, the clearest review flow is:

Open traceability/<id>/package-evidence-index.md to see current readiness, latest gates, and links.
Review artifacts/<id>/02-design/architecture.md and artifacts/<id>/02-design/review-log.md.
Open .ai/packages/<id>/gates/design-<n>.md and confirm the design gate passed with the expected artifacts_checked, findings, and approvals.
Check traceability/<id>/matrix.md to confirm acceptance criteria map into the design sections you just reviewed.
Run /devloop status <id> or ./scripts/loop-verify.sh --enforce <id> if you want an up-to-date package-level quality view.

How to review implementation quality

For implementation quality, use the same package-first approach but inspect the later phases:

Start at traceability/<id>/package-evidence-index.md.
Review artifacts/<id>/04-implementation/implementation-plan.md, changed-files.md, coding-log.md, and that phase's review-log.md.
Review .ai/packages/<id>/gates/implementation-<n>.md, then the latest code-review and test-report gates.
Use traceability/<id>/matrix.md to verify AC → design → test → code links are still intact after implementation.
Run ./scripts/loop-verify.sh <id> for a normal package check or ./scripts/loop-verify.sh --enforce <id> for CI-level strictness.

The key idea is that you should not judge implementation quality from code alone. Develop Loop expects reviewers to check the linked evidence chain: requirements, design, changed scope, review findings, validation results, and final gate posture.

Example walkthroughs

Package	Scope
FEAT-001	MVP 3-phase (requirements → design → test-plan)
FEAT-003	Full 7-phase with code in trace matrix
FEAT-PARENT / FEAT-CHILD	Parent-child release gate demo

See docs/examples/FEAT-001-walkthrough.md, docs/examples/FEAT-003-walkthrough.md, docs/examples/parent-child-walkthrough.md.

Developing this repo

This repository dogfoods the skills differently from consumer projects:

Authoring: .ai/skills/ (source of truth)
Cursor pointers: .cursor/skills/ (thin stubs → .ai/skills/)
Demos: FEAT-001, FEAT-003, etc. ship here for docs; devloop init does not copy them

To work on skills here, edit .ai/skills/ and use the pointer layout under .cursor/skills/. Run ./scripts/build-pack.sh before testing the distributable CLI.

Shipped features

7 phase skills: requirements through release-retro
3 profiles: routine, standard, high_risk
Parent-child packages: orchestration in devloop
Packaging CLI: bin/devloop (global install + project init)
CI enforce mode: --enforce flag on loop-verify.sh

Directory layout (consumer project after `devloop init`)

.ai/
  config/profiles.yaml
  packages/<id>/
artifacts/<id>/
traceability/<id>/
scripts/loop-verify.sh
AGENTS.md
.devloop-version

Full SDLC design: docs/superpowers/specs/2026-06-12-develop-loop-skills-design.md

Verify locally (L3)

./scripts/loop-verify.sh FEAT-001
./scripts/loop-verify.sh --enforce FEAT-003
./scripts/test-loop-verify.sh

Primary human audit entry point per package: traceability/<id>/package-evidence-index.md. The trace matrix remains the detailed AC-to-evidence map, while the package evidence index summarizes readiness, latest gates, approvals, waivers, and linked evidence in one place.

Human-readable package evidence is contract-defined in .ai/contracts/evidence-policy.yaml. The current policy requires both matrix.md and package-evidence-index.md, requires those files to appear in each archived gate's artifacts_checked list, and treats missing human-readable package evidence as an error.

Parent-child release verification is also policy-driven. For parents with children, the current policy requires bindings to the child package manifest, the child gate for the child's current archived phase, the child package evidence index, and a readable child_evidence block that records status, package, latest_gate, and evidence_index.

For human review, start at traceability/<id>/package-evidence-index.md and follow its links into matrix.md, gates, and phase artifacts as needed.

CI runs loop-verify in enforce mode on pull requests when branch protection is configured (docs/ci/branch-protection.md).

Navigation Menu

Repository files navigation

Engineering Judgement in AI-assisted Development

develop-loop-skills

Overview

Package (maintainers)

Build the pack

Verify the pack

CI

Release checklist

Install (consumers)

Option A — from a git clone (recommended today)

Option B — npm (when published)

Install targets per runtime

Upgrade

`devloop` CLI reference

Use (in your project)

Quick start

Agent slash commands

Standalone phase skills

Where things live

How Develop Loop enforces quality

L1 — phase self-review (concrete checks)

L2 — gate before next phase (concrete checks)

L3 — `loop-verify.sh` (concrete checks)

How to review design quality

How to review implementation quality

Example walkthroughs

Developing this repo

Shipped features

Directory layout (consumer project after `devloop init`)

Verify locally (L3)

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.ai		.ai
.cursor/skills		.cursor/skills
.github/workflows		.github/workflows
artifacts		artifacts
bin		bin
docs		docs
scripts		scripts
templates		templates
traceability		traceability
.gitignore		.gitignore
AGENTS.md		AGENTS.md
README.md		README.md
VERSION		VERSION
package.json		package.json

Latest commit

History

Folders and files

Repository files navigation

Engineering Judgement in AI-assisted Development

develop-loop-skills

Overview

Package (maintainers)

Build the pack

Verify the pack

CI

Release checklist

Install (consumers)

Option A — from a git clone (recommended today)

Option B — npm (when published)

Install targets per runtime

Upgrade

devloop CLI reference

Use (in your project)

Quick start

Agent slash commands

Standalone phase skills

Where things live

How Develop Loop enforces quality

L1 — phase self-review (concrete checks)

L2 — gate before next phase (concrete checks)

L3 — loop-verify.sh (concrete checks)

How to review design quality

How to review implementation quality

Example walkthroughs

Developing this repo

Shipped features

Directory layout (consumer project after devloop init)

Verify locally (L3)

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`devloop` CLI reference

L3 — `loop-verify.sh` (concrete checks)

Directory layout (consumer project after `devloop init`)