# Dev.loop

> Drive a development task through planning, execution, verification, and publishing.

- Skill: `kevinslin-skills/dev-loop` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add kevinslin-skills/dev-loop`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kevinslin-skills/dev-loop/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: kevinslin (https://skillmd.com/u/kevinslin-skills)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/kevinslin-skills/dev-loop

---


# Dev Loop

## Setup
Do this only once per repo.
Ensure the `.agents/` folder is ignored in the repo (for example, add `.agents/` to `.gitignore`)

## Usage
User will ask you to run dev.loop. This is usually with either an existing design spec or a stated goal.  

If user gives you an existing spec - go straight to step 2 (Gather Context). Otherwise, start at step 1 (Plan).

If the task is straightforward, you can skip creating a spec and go straight to step 3.

If the user asks you to "check in after creating the spec" or uses similar wording, treat that as a pause point before implementation, not as permission to skip the immediate post-spec gather-context work. Unless the user explicitly says to stop before review, still complete the required spec review, ambiguity/gap analysis, and recommendation fold-in from step 2 before checking in.

In addition to running the whole dev.loop, users can also invoke an individual phase of the dev.loop by referring to it (eg. re-run the "verify" phase). An individually requested Verify phase never pushes; a full dev.loop run continues through the separate Push phase unless the user explicitly instructs not to push.

Whenever practical - use one or more subagents to run any given phase to preserve context

## Workflow Phases

### 1. Plan
- Use $specy to create a feature spec 
- Bias toward answering plan questions yourself; only ask the user when blocked or when user tells you to check with them.
- Ensure the plan includes explicit tests (prefer integration tests).
- List every test or observable outcome the user explicitly requested, the real
  execution boundary it must exercise, and its required infrastructure.
- Honor explicit autonomy and workflow preferences. Ask substantive product
  questions when needed, but do not introduce approval checkpoints for actions
  already authorized; never treat autonomy as permission to exceed task scope.
- Capture the plan prefix from the plan filename: `{YYYY-MM-DD}-{title-in-kebab-case}`.

### 2. Gather Context
- Trace the existing end-to-end lifecycle, including initialization and runtime.
  Identify unmet requested outcomes and unresolved assumptions before introducing
  another mechanism.
- Preflight infrastructure needed for explicitly requested integration proof
  before declaring the task executable. Identify unavailable clusters, runtime
  images, credentials, services, or host capabilities early.
- Record an acceptance-proof matrix mapping each requested outcome to its real
  test command, production boundary, prerequisites, and current status.
- Explicitly answer:
  - What ambiguities or gaps are still left?
  - Are there missing flow docs that, once created, would resolve those ambiguities?
- If there are questions for the user, ask them before continuing.
- If flow docs are missing, propose which flow docs should be generated (title, scope, and why each one resolves a specific gap).
- Summarize this phase in three sections:
  - `Ambiguities/Gaps`
  - `Questions for User`
  - `Proposed Flow Docs`
- After creating the spec, spawn subagent to critical review design doc with $dev.review skill and provide recommendations
- Apply correctness fixes and simplifications within the approved contract.
  Present changes to that contract as product decisions before applying them.
- If the user asked for a post-spec check-in, perform that check-in only after the review feedback and ambiguity summary are incorporated, unless they explicitly asked to stop earlier.

### 3. Execute
- Create a new branch for implementation unless given explicit instructions not to. If user explicitly asks for worktree, create worktree. If a plan branch exists, branch off it to keep the plan commit(s).
- Follow the plan steps in order and check off each task as it is completed in the plan file.
- Use red/green TDD.
- For each phase or milestone, run `@shortcut:precommit-process.md` then `@shortcut:commit-code.md` to commit that phase separately.
- **Always commit after each phase** (do not wait for user prompting). If precommit fails, fix issues and re-run before committing. If no precommit script exists, run the plan’s tests then commit.
- Maintain progress artifacts under `%ROOT_DIR/.agents/progress` (create the folder if it does not exist):
  - `%ROOT_DIR/.agents/progress/{prefix}-progress.md` for status updates, decisions, and blockers.
  - `%ROOT_DIR/.agents/progress/{prefix}-learnings.md` for mistakes, lessons, and adjustments.

### 4. Polish
- Gather session changes by reviewing changed files in the current worktree.
- Identify behavior changes, CLI/API changes, config changes, and workflow changes that need documentation.
- Update `README.md` so relevant behavior changes are documented.
- If `DESIGN.md` exists, update sections affected by the implementation.
- Confirm each meaningful change is reflected in docs, keeping updates specific and accurate.
- If flow docs exist, update relevant flow docs with meaningful changes, including config updates and sudocode details when significant logic changes.

### 5. Verify

#### Evidence reuse and scope

- In the acceptance-proof matrix, distinguish required user/repository checks,
  affected regression checks, and exploratory checks before running them. Do not
  downgrade a required check after it fails.
- Keep one evidence record per check: exact command/selector, exercised boundary,
  relevant source and test/helper versions, runtime/configuration/infrastructure
  identity, result, and log path. Confirm the intended scenarios actually ran;
  keep secret values out of the record.
- Reuse inspected passing evidence while those inputs remain applicable. A new
  agent, phase, commit hash, or unrelated documentation edit alone does not
  invalidate it. The verifier independently checks evidence and its applicability;
  do not rerun solely to change who executed it. Explicit fresh-run requirements
  and current-head CI gates still apply.
- Run cheap checks during implementation; batch expensive live checks after the
  implementation and required base integration stabilize. After a fix or rebase,
  inspect the actual delta and rerun the smallest supported set covering affected
  behavior and regressions. Explain any broader rerun; unchanged areas retain
  their evidence. If applicability is uncertain, rerun the affected check.
- Classify failures as branch-related, established baseline/environmental, or
  unresolved using comparable evidence; one failure alone does not establish
  flakiness. Fix in-scope regressions. Record established unrelated failures once
  and continue unaffected work; do not repeatedly retry unchanged failures or
  expand into unrelated repairs without approval. A blocked required check remains
  blocked until resolved or explicitly rescoped by the user.
- Once required checks, applicable regression coverage, and review findings are
  resolved, proceed to Push. Do not add another full review/test cycle merely
  because a phase changed; preserve the required post-push CI and review gates.

- Satisfy the plan tests with applicable passing evidence or fresh execution under the rules above.
- Check features against the validation plan and existing tests using the evidence-reuse rules above.
- Run every test the user explicitly requested and record its actual outcome.
  A skipped, failed, unavailable, or substitute test does not satisfy that
  acceptance criterion, even when the remaining suite is green.
- Confirm proof exercises the requested real boundary: rendered manifests are
  not a deployment, fixture processes are not production runtimes, and local
  execution is not a live cluster. Report the exact blocker when proof cannot
  be obtained; do not describe the requested verification as complete.
- If there are unstaged changes relevant to your current work, create a scoped local commit. Do not invoke `trigger:commit-code` here because it updates an existing PR after committing.
- Do not push, create or update a PR, or run post-push CI or review during Verify.

### 6. Push
- Do not treat push as optional due to caution, preference, uncertainty, “waiting for review,” or because the implementation already appears done. Only skip push when the user says so explicitly.
- Hard completion gate for any full dev.loop run with code changes:
  - do not send a final handoff until the branch is pushed and a PR URL exists
  - NEVER skip `trigger:push-pr` during Push unless the user explicitly instructs not to push.
  - open the PR as ready for review by default; never make it a draft PR unless the user explicitly asks for a draft
  - include the PR URL in the final handoff
  - if push or PR creation fails, report the exact command error and what retry was attempted, and treat the run as incomplete
- If the user asks a status question such as `did you push a pr?` and the truthful answer is `no`, do not stop after answering. Resume Push immediately and run `trigger:push-pr` unless the user explicitly told you not to push.
- Ensure the PR body includes manual testing steps with checkboxes.
- After push succeeds, spawn two subagents:
  - spawn `worker` subagent to verify CI for the pushed branch is green via `trigger:check-ci`.
  - spawn `a-review` subagent for critical review using the $dev.review skill 
- Wait for both subagents to complete. Address review feedback from coding agents and humans; apply fixes, re-run tests, push, and re-check CI.
- Notify the user when the work is ready.

## Important Reminders
- unless you require user input, don't stop until you finish EVERY phase of the dev.loop
- Verify is local-only; the separate Push phase includes push, CI check, and review. These are required for a full dev.loop run by default and are NEVER optional unless the user explicitly instructs not to push.
- When Push creates a PR, it should be a ready PR by default. Draft PRs require explicit user instruction.
- A dev.loop run that ends without a pushed branch and PR should be treated as incomplete unless the user explicitly said not to push.
- A final answer for a code-changing dev.loop run must include the PR URL, or explicitly state that the run is incomplete because push/PR creation failed. Never end a dev.loop run with only local branch or commit status.
- A passing aggregate suite never overrides an explicitly requested test that
  did not run or pass; name every outstanding acceptance-proof gap in the
  final handoff.

## Phase Overrides
Users can substitute any phase in the dev loop by mentioning they would like to override a particular phase with another set of instrctions. 

Example:
```
## Dev Loop Overrides
Override the following phases of the devloop

### Goal
Use dev.prd to create the goal

### Verify
Make sure that the acceptance criteria from dev.prd have been carried out
```