SuperAPI AI Directory

dev-flow

Coding & development

View repository

Updated 10-15 15:57

About this skill

Dev Flow

A general-purpose development executor that does not depend on keel:contract first + test red-green + quality floor + evidence delivery. Start by inputting a plan document, task description, or issue text. Complex governance (numbering system, traceability matrix, document synchronization, review_profile tiering) is left to the keel process.

Language

  • Accept questions in both Chinese and English
  • Always respond in Chinese

Trigger conditions

  • The user provides a plan document (such as a Markdown checklist produced by superpowers writing-plans) and requires item-by-item implementation
  • The user provides a task description / issue text and requires direct development, and the project has no keel document system
  • The user requests a "lightweight/general-purpose/standalone development process"

Routing decision: the project has docs/devdocs/ and the task has a T-XX number → use /dev-workflow; otherwise use this skill.

Input forms

Input Handling method
Plan document path Read the Markdown checklist, select the current item or the user-specified item
Task prompt Directly convert it into an execution contract, and scan the code to supplement context if necessary
Issue text Extract the problem, expected behavior, constraints, and acceptance signals
Code context hints Serve only as scope hints, do not replace the acceptance contract

Only recognize Markdown checklists and natural-language tasks; do not parse any framework-specific planning syntax.Do not introduce a new numbering system: the contract uses only a local checklist for this round, and does not generate DF-XX / AC-XX.

Five-stage process

Stage Purpose Output / Gate
1. Input positioning Read the input, scan the code context Goal, scope, risks, candidate test commands
2. Execution contract Negotiate the Execution Contract Contract yaml;Contract Gate
3. Test first Write the minimal test, confirm the red verification Red verification record + test freeze point;Red-Green Gate
4. Implementation and refactoring Implement only the behavior within the contract, run until green verification Code changes, green verification results
5. Evidence and delivery Quality floor + fresh-context contract review + optional commit Delivery report;Verify Gate

Three hard gates

Gate 1: Contract Gate (the only default human approval point)

Before entering implementation, an executable acceptance contract must be formed (see the template below).Interactive mode: the contract is presented to the user for confirmation via one AskUserQuestion (confirm / modify scope / terminate);headless or clear task: automatically pass and record the reason in the delivery report.

Subsequent ad hoc questions are still allowed (suspected test defects, scope conflicts, dangerous operations), butstage-by-stage approval is prohibited—human control is concentrated at the single high-leverage moment of the contract.

Gate 2: Red-Green Gate

  • When behavior changes and automated testing is feasible,it must be red first and then green: new tests must all fail first (and must not break the existing test baseline), and all pass after implementation
  • Green verification passed, i.e.test freeze: During the implementation phase, test files must not be modified (at completion, mechanically verify the diff; if changed → ⛔ Blocker); if a test defect is suspected → stop implementation and request confirmation; do not silently modify tests
  • Automated testing is infeasible (no test framework / pure configuration / exploratory task):Do not fake TDD— must state in contract evidence_plan the degraded evidence (command / screenshot / manual verification) and the reason it is infeasible

Gate 3: Verify Gate (one gate, two independent verdicts, both must pass)

3a. Evidence Check (quality floor, cannot be lowered; generalized from the 5 quality floor items in shared/constraints.md, "contract behavior" corresponds to the original "behavioral AC"):

  • Green verification passed and skipped/todo = 0
  • test freeze diff check passed
  • claims vs actual diff are consistent (contract behaviors compared one by one against git diff, no unexplained large blocks of changes)
  • each contract behavior has at least 1 piece of independent evidence (test assertion / command output / screenshot / declared manual verification)
  • affected tests pass when run afterward

When automated testing is infeasible (degradation already declared in the contract), the three items green verification/freeze/post-run tests are marked N/A, replaced by evidence_plan degraded evidence + reason; the other two items cannot be exempted.

3b. Fresh-Context Contract Review: dispatch onenew-context sub-Agent(Task tool), to verify only diff ↔ Execution Contract ↔ evidence compliance—whether all contract behaviors are implemented, whether there are changes outside the contract, and whether the evidence truly supports them. Spec compliance takes priority over code quality; do not expand into a full code quality review. contract-critical findings → ⛔ block, re-review after fix.

This is the minimum safeguard for "the coder does not self-evaluate" after removing the default physical dual Agent; it cannot be skipped; for full adversarial review use --audit。

Review is triage: review findings are divided into two categories—① in-contract (including universal invariants: do not break existing tests, test freeze, no unexplained large diff, security baseline) critical → block and fix; ② out-of-contract findings (bugs / bad smells noticed in passing) → do not block, do not fix in passing, list in the delivery report deferred list.

Execution Contract

execution_contract:
  source: "<plan path | prompt | issue text>"
  goal: "<一句话目标>"
  in_scope: ["<本次会做什么>"]
  out_of_scope: ["<明确不做什么>"]
  expected_behavior: ["<用户或系统可观察结果>"]
  evidence_plan:
    - kind: "test | command | screenshot | manual"
      command_or_path: "<验证方式;非 test 时附自动测试不可行原因>"
  risk_flags: ["<public-api | schema | auth | data-loss | ui | low-risk>"]
  stop_conditions: ["<遇到什么必须暂停确认>"]

Ambiguous task handling:

Situation Handling
A single verifiable goal can be derived State "derived contract" and continue execution
Multiple reasonable directions ⚠️ Must confirm; user chooses goal/scope
Completely no acceptance criteria ("optimize it") Do not enter implementation; degrade to contract clarification
Explicit --explore allows spike / proposal / rollbackable experiment;must not claim "completed"

Execution model

DefaultSingle Agent two Passes(semantic barrier):

  1. Test Pass: Write interface skeleton + test assertions based on the contract (assertion values come from the contract expected_behavior, without reference to implementation details) → red verification
  2. Impl Pass: Implement only in-contract behavior → green verification → refactor (keep green)

--strict-tdd or risk_flags contains auth/data-loss/schema/public-api , upgrade tophysical twin Agents(Task tool): The Test Agent does not read the existing implementation, and the Impl Agent does not read the contract derivation process and must not modify tests—same information-barrier semantics as dev-workflow.

Coding Discipline(constant across both modes): follow the /code-quality core threshold table / Naming conventions / Comment conventions(changelog-style, provenance-recording, or reviewer-addressing comments are forbidden, including in fix loops) / Logging conventions(level discipline + minimal context + security red lines + no log-and-throw); test assertion quality follows /testing-guide。

Batch mode (multiple items in the plan document)

  • Onlyindependently executable, independently acceptablechecklist items enter the batch; narrative-type items are first converted into a task queue (confirmed with the user)
  • Execute item by item,fresh context per item(independent sub-Agent or cleared-context restart, to fight context rot)
  • Each item independently goes through the three hard gates(contract formed → red-green → Verify Gate passed); no unified review at the end of the batch
  • On completion of each item: check off the corresponding item in the plan document + atomic commit (--no-commit only check off, no commit)
  • Breakpoint recovery: no checkpoint file, no state machine—before starting each item, re-read the check-off status in the plan document; unchecked means incomplete
  • Single-task prompt input has no batch logic

Flags

flag Purpose
--strict-tdd Mandatory physical twin Agents + information barrier (core logic / high risk)
--audit After the Verify Gate, append a complete independent review (invoke /adversarial-review)
--no-commit Only modify code + output evidence, do not commit
--explore Vague/research tasks: spike mode, produce a plan or a rollbackable experiment

Commit Conventions

workspace_context.mode is not inline (i.e., the code is not in this repo), "one item one commit" expands to N+1 repos; for the protocol see workspace-topology/references/protocol.md § N+1 repo commit protocol. The code root path is taken from the handshake workspace_context(shared/constraints.md §3 task/workspace-context; if not passed in, per the inline default).mode is linked , when the code root is not owned by this repo; each repo commits on its own, ⛔ do not bump the pointer, see protocol.md §6.5。

  • When the user requests a commit or in batch mode commits item by item:Atomic commit, one item one commit, following /commit-convention
  • File moves/deletions follow /git-safety(git mv/rm)
  • Never push to remote; do not commit if the Verify Gate has not passed

Delivery Report

## dev-flow 交付报告

**任务**: <goal> | **来源**: <source> | **结果**: 完成 / 部分完成 / 阻塞
**契约批准**: 用户确认 / 自动通过(理由)

### 证据
| 契约行为 | 证据 | 位置 |
|---|---|---|

### Verify
- Evidence Check: ✅/❌ | Fresh-Context Review: ✅/❌(轮次 N)

### Deferred(契约外发现,未处理)
- <发现 + 位置>

### 建议沉淀项(可选,仅确有可复用惯例/踩坑时输出)
- <一行;用户可自行 /agent-memory 或忽略>

Constraint Checklist

  • The three hard gates cannot be skipped: Contract / Red-Green (when tests are feasible) / Verify (both verdicts must pass)
  • Fresh-Context Review must be a new-context sub-Agent, and must not be self-reviewed by the implementer
  • Discoveries outside the contract are not fixed in passing, they go into the deferred list
  • Without automated tests, do not fake TDD, downgraded evidence must declare the reason
  • Do not generate a numbering system, do not write traceability, do not sync documentation
  • Exclude build/cache artifacts before committing(__pycache__/dist etc. to ensure they do not enter the commit—.gitignore / local exclude / not adding them are all acceptable; artifacts entering the diff count as unexplained changes)
  • Never push to remote

Ecosystem Boundary

Scenario Who uses it
keel project T-XX task execution / traceability / 04-dev-tasks status advancement / review-drain /dev-workflow
Plan documents / ordinary issues / CE·superpowers·BMAD loosely plan-driven development This skill
Task breakdown superpowers writing-plans or /dev-tasks(keel)
Project converted to document-driven /retrofit reverse-generate keel (this skill's delivery report can serve as auxiliary input, not a traceability matrix)

superpowers integration: writing-plans output can be used directly as input; executing-plans can serve as the upper-level plan executor, with individual development gated by this skill.

Skill collaboration

Phase Collaborating Skill Description
Write business code /code-quality Core threshold table, naming/comment conventions, design principles (code-level)
Write tests /testing-guide Assertion quality, weak assertion checks
Full review /adversarial-review Only --audit or explicit user request
Commit /commit-convention + /git-safety Commit message + native git operations
UI tasks /ui-orchestrator Optional collaboration, not a hard dependency