engineering-delivery-workflow

name	engineering-delivery-workflow
description	Shared workflow for multi-agent software delivery with planner, system-architect, coder, and tester roles. Use when engineering work should be explicitly scoped, designed, implemented, and verified through structured handoffs, acceptance criteria, artifact templates, or independent testing in this project.

Engineering Delivery Workflow

Use this skill as the common operating contract for the project's coding agents. Keep the process explicit, bounded, and easy to audit.

Prefer document-driven collaboration on the planned path: planner writes the plan doc first, system-architect confirms the task document location and writes the architecture doc, and downstream agents read those docs before acting.

Routing Modes

Direct Path

Use coder directly for small, localized, already-bounded tasks, including many Add to Chat implementation requests.

Flow:

1. coder implements the change.
2. coder adds or updates unit tests.
3. If the change is boundary-sensitive, tester runs integration or end-to-end verification.
4. The agents return the relevant report artifacts.

Planned Path

Use the full path only for complex work.

1. planner creates an Execution Brief with the objective, repository facts, assumptions, risks, task breakdown, delegation plan, and acceptance criteria.
2. planner chooses an initial task doc root and writes plan.md.
3. system-architect is engaged when the task affects architecture, boundaries, interfaces, data shape, rollout, or test strategy. The architect reads plan.md, confirms or refines the task doc root, and writes architecture.md.
4. If the architecture note recommends approval, planner gets explicit user confirmation before coding starts.
5. coder reads the agreed task docs, implements the bounded change, meets the agreed unit-test coverage gate, and produces implementation.md.
6. tester reads the task docs, checks that the unit-test gate was met or explicitly waived, then independently verifies integration and end-to-end behavior and produces verification.md.
7. planner records the final decision in the same task document set, decides whether rework is needed, and returns the final answer.

Sizing Rules

• Use planner only for large, ambiguous, cross-module, or high-risk work.
• Skip system-architect for clearly local, low-risk changes with no boundary or contract impact.
• Route small but boundary-sensitive direct tasks through tester even when planner is not needed.
• Skip tester only when the task does not require integration or end-to-end verification.
• Skip no role silently on the planned path. State why a role is omitted.
• Keep the planned path serial. Use parallelism only for independent analysis or disjoint write scopes.
• Never let multiple agents edit the same file set in parallel.

Handoff Standard

Every substantial handoff should include:

• Goal
• Relevant repository facts
• Owned write scope
• Constraints and non-goals
• Acceptance criteria
• Required docs to read first
• Expected output artifact

Do not pass unbounded repository context or vague "figure it out" prompts to specialists.

Boundary-sensitive direct work includes changes to API contracts, shared types, database access, migrations, auth, permissions, environment flags, queues, events, webhooks, and cross-service boundaries.

Completion Rules

• Do not claim verification without commands, evidence, or clearly described manual checks.
• Require coder to own unit tests for changed behavior.
• On planned work, require a measurable unit-test coverage gate before handoff to tester. Default that gate to at least 80% coverage unless the repository already enforces a stricter standard.
• Do not treat missing feasible unit tests as an acceptable Known Gaps item unless there is a concrete blocker or explicit waiver.
• Treat missing integration or end-to-end coverage as a risk on complex tasks.
• Treat static checks as repository automation enforced by Husky or CI, not by an agent role.
• Surface assumptions explicitly.
• Prefer the smallest reversible change that meets the acceptance criteria.

Task Doc Checkbox Convention

In plan.md, verification.md, and other artifacts under the task doc root:

• Completed / satisfied: - [√]
• Not done / unselected: - [ ]
• Do not use - [x] for completion in this repository (visual convention for Chinese-facing docs).

Some Markdown previews may not style √ like GitHub’s [x]; treat the symbol as the canonical “done” marker.

Artifact Persistence

• For planned tasks, use a task document set rather than a single long artifact file.
• Start with a task doc root like docs/agent-artifacts/<YYYY-MM-DD>-<task-slug>/.
• Let system-architect confirm or refine that location if the repository has a better document convention.
• Default planned-path files are plan.md, architecture.md, implementation.md, verification.md, and optionally final.md.
• For direct tasks, persistence is optional unless the task spans multiple turns, needs tester involvement, or the user asks for a durable record.

References

• Read references/workflow-playbook.md for orchestration rules, routing, and rework loops.
• Read references/artifact-contract.md for the exact output templates each agent should use.
• Read references/checklists.md for role-specific quality checks.

Keep this skill lean. Load only the reference file needed for the current step.