| name | engineering-workflow |
| description | Overview of the engineering pipeline and how each stage connects. Use when an agent is confused about what stage it's in, what it should do next, or how its output feeds into the next stage. Trigger on: engineering workflow, pipeline, what stage am I in, what comes next, workflow overview, 工程流程, 开发流程, pipeline stage, stage transition.
|
Engineering Workflow Overview
The engineering pipeline runs from requirement to merged code. Each
stage has a specific agent, clear entry/exit conditions, and a
feedback loop that sends work back upstream when quality gates fail.
Pipeline
┌─────────────┐
│ Requirement │ (human writes issue with goal description)
└──────┬───────┘
│ label: engineering
▼
┌─────────────┐ reject: spec incomplete
│ Specifying │◄────────────────────────────┐
│ (spec-agent) │ │
└──────┬───────┘ │
│ label: status:spec-review │
▼ │
┌─────────────┐ │
│ Spec Review │─────────────────────────────┘
│(spec-review) │
└──────┬───────┘
│ label: status:developing
▼
┌─────────────────────────────────────┐
│ Developing │
│ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ test-gen │ │ dev-agent │ │ reject: tests fail
│ │ (writes │ │ (implements │ │ or review rejects
│ │ tests from │ │ code from │◄─┤
│ │ spec) │ │ spec) │ │
│ └──────────────┘ └──────────────┘ │
│ both run in parallel │
└──────┬──────────────────────────────┘
│ both complete, label: status:reviewing
▼
┌─────────────┐ │
│ Reviewing │──────────────────────┘
│(review-agent)│ reject: AC fails
└──────┬───────┘
│ all ACs pass
│ label: status:done
▼
┌─────────────┐
│ Done │ (merge to main, close issue)
└─────────────┘
Stage responsibilities
Specifying (spec-agent)
Input: Issue with a goal description (possibly vague).
Output: Structured spec comment with Interface, Acceptance
Criteria (AC-1..N), and Design Notes.
Exit condition: Spec posted on issue, label → spec-review.
Feedback on rejection: Spec-review tells you which ACs are
untestable and which interfaces are underspecified. Fix those
specific items.
Read the spec-writing skill for detailed guidance on what
makes a good spec.
Spec Review (spec-review-agent)
Input: Issue with spec in body or comments.
Output: Per-AC testability verdict table.
Exit condition: All ACs testable → label → developing.
Or: specific ACs untestable → label → specifying with feedback.
Read the acceptance-criteria skill for testability rules.
Developing (test-gen-agent + dev-agent, parallel)
Two agents run simultaneously on the same branch:
test-gen-agent:
- Reads the spec's ACs
- Writes integration tests (one per AC minimum)
- Verifies tests FAIL without implementation
- Does NOT write any implementation code
dev-agent:
- Reads the spec's Interface and ACs
- Implements the code
- Does NOT write the AC-derived tests (test-gen handles that)
- May write additional unit tests for internal logic
Both push to the same branch. When both complete, the state
advances.
Read the test-design skill for test writing conventions.
Exit condition: Both agents complete, label → reviewing.
Reviewing (review-agent)
Input: Branch with implementation + pre-generated tests.
Output: Per-AC verdict (PASS/FAIL/CANNOT JUDGE) + code
quality findings.
Exit condition: All ACs PASS → label → done.
Or: any AC FAIL → label → developing with per-AC feedback.
Read the code-review-standards skill for review process and
verdict format.
Done
Merge the PR, close the issue. This stage is mechanical — no
agent judgment required.
Feedback loops
Three feedback loops operate at different timescales:
1. Spec loop (specifying ↔ spec-review)
What it catches: Untestable ACs, missing interfaces, vague
requirements.
Cost of a rejection: One spec-agent session (~minutes).
Why it matters: A bad spec that escapes to developing costs
N parallel dev sessions + test-gen + review cycles, all producing
the wrong thing. This is the highest-leverage gate.
2. Dev-review loop (developing ↔ reviewing)
What it catches: Code that doesn't satisfy ACs, quality issues.
Cost of a rejection: One dev-agent session (potentially
expensive with parallel rollouts).
Feedback format: Per-AC verdict with specific failing tests
and error messages. The dev agent on the next round sees exactly
which ACs to fix.
Cap: max_review_cycles (default 3). After 3 dev→review
round-trips, the issue is blocked for human intervention.
3. Turn-level loop (inside each agent session)
What it catches: Agent stuck (repeating same failed command),
agent idle (no productive actions for N turns).
Mechanism: Behavioral observation by the agent runtime (AgentM
atoms or session-level control loop).
Feedback: Injected message: "You've tried the same approach
3 times without progress. Try a different approach."
Parallel development
When the issue specifies rollouts: N (via label rollouts:N),
the developing state dispatches N copies of the dev-agent alongside
one test-gen-agent. All N+1 sessions run in parallel.
At review time, the reviewer:
- Runs the test-gen tests against each dev branch
- Eliminates branches where tests fail
- Selects the best passing branch based on code quality
This is multi-sampling: run N implementations, select the best.
Strictly better than sequential retries when budget allows.
Labels
| Label | Meaning |
|---|
engineering | Issue enters the engineering workflow |
status:specifying | Spec-agent is writing/revising the spec |
status:spec-review | Spec-review-agent is validating the spec |
status:developing | Test-gen + dev agents are working in parallel |
status:reviewing | Review-agent is running tests and reviewing |
status:done | All ACs pass, PR merged |
status:blocked | Waiting for human intervention |
rollouts:N | Request N parallel dev sessions |
When to use this workflow vs default
| Use engineering workflow when | Use default workflow when |
|---|
| The task involves new interfaces or APIs | The task is a simple bug fix with obvious scope |
| Multiple acceptance criteria need verification | One clear criterion: "this test should pass" |
| You want test-gen before implementation | Tests already exist or aren't needed |
| Parallel development is worth the cost | A single dev session is sufficient |
| Spec quality matters (long-lived code) | Quick fix, throwaway, or experiment |
