dev-flow-skills

Dev Flow Skills

English | 中文

Governed development-flow skills for AI coding agents.

clarify -> OpenSpec plan/tasks -> execute (subagent) -> review -> accept

Dev Flow Skills turns /dev-flow into a disciplined software-delivery workflow. It is designed for agents that need to clarify requirements, maintain OpenSpec/opsx artifacts, build an executable task plan, coordinate TDD implementation via subagents with independent per-task review, handle Git safely, and finish with acceptance evidence instead of a chat-only summary. It also includes Loop Engineering commands for goal-preserving multi-round control, candidate discovery, safe handoff, and approved scheduler management.

flowchart LR
  A[Clarify] --> B[OpenSpec\nplan and tasks]
  B --> D[Execute\nsubagent]
  D --> R[Review\nper-task]
  R --> E[Accept]
  D -->|Requirement changes| B
  D -->|Task failure / drift| B

Why this exists

Most coding-agent failures are workflow failures:

• the agent starts coding before clarifying the requirement
• the agent writes plans but does not turn them into executable tasks
• execution stops after one task instead of continuing through the whole plan
• requirement changes are applied directly to code without updating docs and orchestration
• sub-agents fail or drift while the main agent reports success too early
• Git side effects happen without an explicit safety boundary

Dev Flow Skills adds gates, handoffs, runtime state, and final acceptance checks so the agent keeps moving without skipping the decisions that must remain user-owned.

The workflow provides built-in debugging, planning, verification/TDD, and review contracts. Installed or marketplace skills may add domain-specific capabilities, but are not workflow dependencies.

Quick start

Recommended: install from npm

Install once and use /dev-flow in any project.

npm install -g dev-flow-skills
dev-flow install --global    # OpenCode
dev-flow install-codex       # Codex
dev-flow install-claude      # Claude Code

Update to the latest version:

npm install -g dev-flow-skills@latest
dev-flow update --global     # OpenCode
dev-flow update-codex        # Codex
dev-flow update-claude       # Claude Code

Check the install:

dev-flow doctor --global

Alternative: install from GitHub

Use this if you want to test the repository version before an npm release:

git clone https://github.com/paulLee778899/dev-flow-skills.git
cd dev-flow-skills
npm install -g .
dev-flow install --global

When working from the cloned repo, npm run update:all updates all three platforms in one step.

Optional: project-local install

Use this when a repository should pin and commit its workflow.

cd your-project
dev-flow install

Project-local installs write to ./.opencode/ and override global installs for that project.

Install with an AI agent

Tell your coding agent:

Fetch and follow the Dev Flow Skills agent installation instructions from:
https://raw.githubusercontent.com/paulLee778899/dev-flow-skills/main/install/agent-install.md

Install globally by default unless I explicitly ask for project-local installation.
Detect the current agent platform and follow the matching platform guide when one exists.
Do not overwrite modified local files unless I explicitly approve --force.
After installation, run the relevant doctor command and report exactly what changed.

For a longer prompt and platform-specific details, see install/agent-install.md.

Platform guides

• OpenCode: install/opencode.md
• Codex: .codex/INSTALL.md
• Claude Code: install/claude.md
• Agent installation: install/agent-install.md
• Manual installation details: install/manual-install.md

Skill map

Typical flow

User: /dev-flow 给订单后台增加退款审批流，完整走 dev flow

Agent:
1. Enters `dev-flow-master`.
2. Loads `dev-flow-intent` and classifies the task type.
3. Routes debugging, UI/UX, and review requests to focused protocols when appropriate.
4. Classifies feature/change work as lightweight, medium, or heavyweight.
5. For lightweight work, uses opsx/OpenSpec artifacts such as `/opsx:ff`, `/opsx:apply`, and `/opsx:verify`.
6. Enters planning mode when governed planning is required.
7. Treats an explicit implement/change/build request as authorization for necessary planning artifacts and asks only genuinely blocking decisions.
8. Writes the OpenSpec artifacts and keeps their task artifact as the only implementation task source; dependent tasks reference prerequisite task IDs inline.
9. Runs one combined planning checker over OpenSpec, the execution plan, verification, and Git/writer assumptions.
10. Shows the proposed execution actor at the single Phase Planning Gate.
11. Dispatches one writing task at a time in stable OpenSpec order; the main agent coordinates only and does not edit files directly.
12. After each sub-agent reports final_success, a reviewer sub-agent independently verifies the diff and evidence before the task is settled.
13. If requirements or material dependencies change, updates the affected OpenSpec artifacts/tasks once and reruns the combined planning checkpoint.
14. Reuses still-valid task verification evidence; a focused checker runs only for new cross-task scope, risk, or behavior.
15. Writes delivery evidence and suggests optional `/dev-flow-cr`; CR remains independent and non-automatic.

Loop Engineering

Loop Engineering is an outer control plane, not a /dev-flow phase.

• /dev-flow-loop <goal> prepares the required content baseline (requirements.md, design.md, test-plan.md, and test-cases.xlsx), the Loop Phase DAG, and envelope, runs one combined loop-start checker, then asks once at the Loop Start Gate and persists loop_start_ready.
• An explicit delivery or implementation invocation authorizes drafting or updating the four content artifacts, Loop Phase DAG, envelope, and loop-state.md before the gate. Explicit review and triage stay read-only; drafting does not authorize execution, and the only start-bundle user approval is the Loop Start Gate.
• design.md combines high-level and detailed design in one human-reviewable template. Chapters 1-3 cover overview, system definition, and mechanisms/flows; candidate chapters 4-8 cover protocols, APIs, state/timing, exceptions, and deployment/resources only when applicable. Inapplicable chapters are deleted and continuously renumbered. Cross-document traceability uses stable M/PROTO/API/SM/EX/RES design item IDs instead of section numbers, and Appendix B remains in the delivered design.
• design.md always includes a project-specific system architecture diagram and a flowchart or sequence diagram for every retained typical workflow. Add other diagrams only when short prose is insufficient.
• /dev-flow-triage scans available evidence and builds a read-only Candidate Inbox.
• /dev-flow-scheduler creates, updates, views, pauses, resumes, or deletes approved cron/heartbeat automations; it does not scan candidates or design loop logic.
• Triage never writes code, commit, push, open PRs, create worktrees, mutate trackers, create schedulers, run /dev-flow, or run /dev-flow-cr automatically.
• A confirmed delivery loop may auto-continue within the approved content baseline. Loop derives the Ready Phase Set from the Phase DAG. At the one Loop Start Gate, the user decides Phase parallelism; when enabled, one worktree per Phase is the default and the Gate records max_parallel_phases, fallback, Loop integration branch, local commit/integration authority, final delivery, and cleanup. A Phase Planning Gate validates the inherited policy without asking again.
• Each Phase owns one OpenSpec change and executes its tasks with one writer at a time. Parallelism applies only to dependency-ready, non-overlapping Phase nodes.
• Every implementation task runs in an isolated sub-agent context and receives an independent reviewer score from 0-100. The target is 95, the floor is 90, and P0/P1 findings block. The original implementation agent gets at most Fix 1, Fix 2, and Fix 3 after the initial review.
• Acceptance reuses task reviewer evidence and produces phase_accepted. Loop integrates accepted Phase branches serially into the Loop integration branch in stable Phase-ID order, verifies each integration, and runs cross-Phase checks after the wave. phase_eval consumes acceptance and integration evidence without duplicate review.
• Loop-owned artifacts live in Docs/<topic>/loop/ or docs/<topic>/loop/. Phase OpenSpec/opsx originals stay in openspec/changes/<change-id>/ or the project's standard OpenSpec/opsx location. Do not move or copy OpenSpec/opsx originals into the loop artifact directory; record phase mappings in phase-artifacts.md or opsx-index.md.
• Loop checkpoints use quality target: 95 and convergence floor: 90. A 90–94 result may pass when objective checks pass, no P0/P1 or unresolved material finding remains, and either the current checker reports only non-material findings or the latest re-review improves by fewer than 2 points.
• Freezing the initial content baseline, approving the Loop Phase DAG, enabling within_confirmed_baseline, and choosing Phase parallel/Git integration policy are explicitly approved at the Loop Start Gate; exceeding baseline, budget, concurrency, integration, stop-condition, or side-effect boundaries requires stopping and asking the user.
• Loop start uses loop_start_ready, one combined checker, one shared max_checker_evaluations budget, and one user approval. Each phase-level OpenSpec/opsx change contains only deltas from the approved four-file content baseline.
• loop_start_ready is static and contains no current Phase cursor. Resolve the Ready Phase Set from DAG nodes whose prerequisites are accepted, integrated, and verified plus their phase-index entries.
• If a candidate should be implemented or reviewed, the agent asks a concrete handoff question. After the user explicitly confirms a specific candidate, the agent may enter the equivalent /dev-flow or /dev-flow-cr owner flow without requiring another slash command.
• Recurring repo scans should use read-only Candidate Inbox prompts; automatic fixes and full code review stay off by default.

Generated Artifacts

For implementation work, OpenSpec is the durable artifact set and its task artifact is the only implementation task source. Tasks without dependencies carry no extra metadata; dependent tasks add one inline Depends on reference. Tasks execute serially inside each Phase in stable eligible order rather than producing a second plan. Expected evidence includes:

• openspec/changes/<change>/
• generated proposal/tasks/spec/design artifacts required by the schema
• /opsx:apply implementation/task status
• /opsx:verify output
• Git/patch state and unresolved risk notes
• dev-flow-state.md
• current Phase and task cursor
• progress.md
• delivery-report.md
• cr-report.md when the user later runs /dev-flow-cr

For /dev-flow-loop delivery loops, the required content and control artifacts are:

• Docs/<topic>/loop/requirements.md
• Docs/<topic>/loop/design.md
• Docs/<topic>/loop/test-plan.md
• Docs/<topic>/loop/test-cases.xlsx
• Docs/<topic>/loop/loop-phase-dag.md
• Docs/<topic>/loop/loop-envelope.md
• Docs/<topic>/loop/loop-state.md
• Docs/<topic>/loop/phase-artifacts.md or Docs/<topic>/loop/opsx-index.md

Acceptance reuses still-valid task evidence; a focused checker runs only for newly discovered cross-task scope, risk, or behavior.

Those loop artifacts preserve the approved requirements, design, verification intent, outer goal, and envelope. Phase implementation still uses OpenSpec/opsx originals in openspec/changes/<change-id>/ or the active project's standard OpenSpec/opsx location.

In Git repositories, the canonical artifacts listed above are Git-tracked formal artifacts. Raw checker rounds, captured stdout/stderr, full logs, coverage, screenshots/video, browser traces, benchmark/timing output, debug dumps, temporary patches, and conversion intermediates are transient. Store workflow-created transient output under .dev-flow/runtime/<run-id>/, keep it locally excluded through .git/info/exclude, and use an explicit staging allowlist; do not use git add -A or git add ..

Example layout:

Docs/<topic>/
  loop/
    requirements.md
    design.md
    test-plan.md
    test-cases.xlsx
    loop-phase-dag.md
    loop-envelope.md
    loop-state.md
    phase-artifacts.md
openspec/
  changes/
    <change-id>/
      proposal.md
      tasks.md
      specs/

The loop index links each Phase to its wave ID, OpenSpec/opsx change, declared/planned write scope, worktree/branch, integration-base revision, acceptance/integration states and evidence, and phase_eval_result.

Skill layout

Core skills use progressive disclosure:

• SKILL.md keeps triggers, ownership, hard rules, and the shortest safe route.
• references/ holds detailed contracts, signal tables, task schemas, recovery rules, and format examples that are loaded only when needed.
• assets/baseline-templates/ under dev-flow-loop contains the required requirements.md, combined design.md, test-plan.md, and test-cases.xlsx templates.

This keeps frequently loaded skills small while preserving the full governance contract.

Common commands

dev-flow install --global    # OpenCode
dev-flow install-codex       # Codex
dev-flow install-claude      # Claude Code
dev-flow update --global     # OpenCode
dev-flow update-codex        # Codex
dev-flow update-claude       # Claude Code
dev-flow doctor --global
dev-flow version

Doctor commands check required files, loop baseline template placement, the /dev-flow, /dev-flow-cr, /dev-flow-loop, and /dev-flow-triage commands, core references/, OpenSpec/opsx contract wording, checker gate phrases, Loop Engineering read-only boundaries, stale command-name drift, and core .opencode/skills mirror consistency. Doctor commands also check /dev-flow-scheduler, approved automation boundaries, scheduler skill mirrors, and loop handoff wording.

Safety model

• User confirmation is required before starting or refreshing OpenSpec/opsx artifacts when clarification is incomplete.
• Gate approvals and required signals are recorded in dev-flow-state.md; chat memory is not enough evidence for governed completion.
• All implementation work uses OpenSpec/opsx artifacts as the implementation baseline; if OpenSpec/opsx is unavailable, the workflow stops for user direction instead of silently doing chat-only or ad hoc planning.
• The Loop Start Gate after the Phase DAG approves Phase parallelism, worktrees, local commit/serial integration, final delivery, and cleanup once. Matching Phase Planning Gates validate that inherited policy; plain dev-flow decides applicable Git policy at its own Gate.
• Phase 3 implementation tasks are dispatched to sub-agents only; the main agent coordinates and does not directly edit code, test, or configuration files.
• Each implementing sub-agent's output is independently verified by a reviewer sub-agent before the task is settled. Critical or important findings trigger a fix-and-re-review cycle (max 3 rounds); unresolved critical findings block settlement until the user decides.
• Requirement or material dependency changes return to planning, update the affected OpenSpec artifacts/tasks once, and rerun the combined planning checkpoint; no second task document is synchronized.
• OpenSpec tasks inside each Phase always use one writer at a time. Different phases use parallel worktrees only when DAG-ready, non-overlapping, and approved.
• Accepted Phase branches integrate serially by Phase ID. Conflicts return to the original Phase agent against the latest Loop integration branch for verification and re-review.
• All gate-impacting scores use an independent checker subagent with raw artifacts; the main agent does not self-score for gate passage. Gates target 95 but may converge at 90–94 when objective evidence passes, no P0/P1 or unresolved material finding remains, and only non-material findings remain or score improvement plateaus.
• Final acceptance requires task local verification evidence and canonical Git integration states for every task.
• Final acceptance reuses still-valid task evidence and runs only missing, invalidated, or newly scoped integration/system checks.
• Independent CR is user-triggered through /dev-flow-cr after the user accepts or inspects delivered work; it is not an automatic /dev-flow stage.
• Loop review and triage are read-only. An explicit Loop delivery or implementation request may draft the start bundle before the single Loop Start Gate; execution and external side effects still require their governing approval.
• Delivery loops may auto-continue only inside confirmed loop baseline artifacts and envelope limits; baseline changes, side-effect expansion, Git/PR/push/worktree actions, paid/external mutations, and unresolved P0/P1 deferrals require explicit user approval.
• Scheduler changes are isolated in /dev-flow-scheduler and require explicit approval for create/update/pause/resume/delete actions.
• Local modifications are protected by manifest checksums during update.
• Final success requires verification evidence, not only agent self-reporting.
• Canonical formal artifacts remain tracked; transient verification output remains locally excluded and outside the staged diff.