# Loop Workflow

> Use when implementing or reviewing changes in this repository and you need a strict, repeatable local development loop: align with repo docs, execute one mainline task at a time, run pnpm-based targeted verification, run codex review for code changes, and prepare clean commits/PR context.

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

---


# Loop Workflow

## Scope

Use this workflow for day-to-day implementation in this repository.
Apply it to changes across:

- `apps/playground-web`
- `packages/core`
- `packages/contracts`
- `packages/db`
- `packages/runtime-pi`
- `packages/shared`

Operate from repository root and use `pnpm` workspace commands.

## Mandatory alignment before coding

1. Read constraints in:
   - `AGENTS.md`
   - relevant docs under `docs/`
2. Confirm affected package boundaries and interfaces before editing.
3. Keep one mainline objective.
   - Park side ideas in docs/notes instead of scope hopping.

## Default development loop

1. Pick one task and define acceptance
   - State expected behavior and where it is verified.

2. Update docs first when behavior or constraints change
   - Keep architecture and runtime expectations synchronized with code changes.

3. Add or update the smallest useful tests
   - Prefer focused tests near changed package behavior (`packages/*/test`).

4. Implement minimal reversible diff
   - Avoid unrelated formatting churn or cross-package drift.

5. Run targeted verification
   - Global strict check when needed: `pnpm typecheck`
   - Package tests: `pnpm --filter <package> test`
   - DB flows:
     - `pnpm --filter @agent-infra/db db:generate` (when schema changes)
     - `pnpm --filter @agent-infra/db db:migrate` (when migration apply is required)
   - Runtime smoke:
     - `pnpm --filter @agent-infra/runtime-pi smoke` (when runtime adapter/repository behavior is touched)
   - Full workspace tests only when risk requires: `pnpm test`

6. Run codex review gate for code changes
   - Execute before staging/commit:
   - `codex review --uncommitted -c model="gpt-5.3-codex" -c model_reasoning_effort="medium"`
   - Use tool timeout `>= 1200000` ms.
   - Skip only for pure docs-only changes unless explicitly requested.
   - If review is clean, do not keep accumulating unrelated work in the same local diff.
   - Default behavior after a clean review is to commit the current loop item immediately.
   - Only defer the commit if the user explicitly asks to keep batching multiple loop items together.

7. Pre-commit gate
   - Check scope: `git status --short`
   - Review staged diff: `git diff --cached --stat` (or full `git diff --cached`)
   - Ensure docs are updated when behavior changed.

8. Commit and PR hygiene
   - Keep one concern per commit.
   - Use imperative subject.
   - In normal loop execution, a clean review should transition directly into commit, not into another implementation item.
   - When user asks to commit, generate Conventional Commit format:
     - `type(scope): summary`
     - max 72 chars, imperative.

## Guardrails

- Use `pnpm` only for package and task execution.
- Keep edits localized to affected package boundaries.
- Prefer explicit exports and strict TypeScript-safe changes.
- Do not commit secrets, local DB files, or `.env.local`.
- For risky runtime changes, prefer log/evidence-backed diagnosis before adding abstractions.

## Quick command reference

See `references/command-matrix.md` for command mapping by change type.

## Done criteria for one loop item

- Task acceptance is explicit and validated.
- Relevant checks/tests for touched packages passed.
- Docs are synchronized with behavior changes.
- Diff is focused and reviewable.
- If review was required and came back clean, the loop item is committed before starting the next item unless the user explicitly asks otherwise.

## Full todo execution mode

When the user explicitly asks to execute the whole todo, for example:

- "按照 loop-workflow skill 开始执行吧，一直运行到所有的 [] 都变成 [x]"
- "run the todo until everything is checked off"
- "complete all loops in docs/todolist.md"

then the workflow changes from "one loop item and stop" to "continue loop-by-loop until the todo is complete".

Rules:

1. Use `docs/todolist.md` as the execution source.
   - Work from top to bottom.
   - Keep checkbox state current as each item is completed.
   - Do not mark an item `[x]` until it is actually done and verified.

2. Execute one meaningful loop at a time.
   - Finish that loop's implementation, targeted verification, `codex review`, and commit handling before moving to the next loop.
   - After a clean review and commit, immediately continue to the next unchecked loop item instead of stopping.

3. Continue until completion.
   - Stop only when every applicable `[ ]` item in `docs/todolist.md` is `[x]`, or when a real blocker prevents safe progress.
   - If an item becomes intentionally not applicable, update the todo text to record that decision instead of silently skipping it.

4. Preserve normal review and commit discipline.
   - Keep one concern per commit unless the user explicitly requests batching.
   - Run the repository's review profile for each meaningful code-change loop.
   - Do not accumulate multiple implementation loops into one unreviewed diff.

5. Final response for full todo execution.
   - Summarize completed loops.
   - State verification and review outcomes.
   - Mention any items left unchecked and why; if none remain, say the todo is fully checked off.