dwf-orchestrator

dwf-orchestrator

This skill is the unified scheduling entry point for the DWF (Dev Workflow) development workflow. It is only responsible for reading state, determining the phase, dispatching sub-skills, and maintaining the state machine skeleton. It does not generate phase document bodies and does not modify project code.

Unlike the old dev-workflow integrated skill, this skill decouples process orchestration from phase implementation: the orchestration layer only holds the state machine and routing table, while phase outputs are produced by dwf-requirement、dwf-design、dwf-development、dwf-coding .

Load resources

Read this file first, then read reference files according to the action:

Before writing, repairing, or explaining .dwf/state.json、_meta.json、_context.md、.dwf/pending/<迭代目录名>/state.jsonor the spec directory skeleton, read references/state-model.md。
Before performing first-time initialization, phase advancement, iteration splitting, iteration completion, iteration addition, pause and queue-jumping, restart, pending confirmation item handling, deferred reminders, resumption, or state.json reconstruction, read references/orchestration-flows.md。
When dispatching to a sub-skill, read and follow the corresponding sub-skill's SKILL.md. Sub-skills only handle the content of the current phase; the queue structure is still controlled by this skill.

The following rules must not be violated:

Orchestrate only, do not implement. Do not generate the body content of 01-需求/、02-设计稿/、03-需求分析/、04-技术方案/、05-实现清单/ , and do not modify project code under the workspace root directory. Phase implementation must be dispatched to sub-skills. The only exception: when handling pending confirmation items, the user's explicit decision may be written back to the "Pending Confirmation Items/Pending Confirmation Matters/Unresolved Issues" section of the corresponding phase document.
Read on every invocation first state.json。 Before dispatching, initializing, or any action, first read .dwf/state.json(if it exists), identify the specs queue,active spec and each item's current_step。state.json and _meta.json When there is a discrepancy, state.json shall prevail and _meta.json。
Automatic advancement without confirmation is prohibited. Both overall confirmation of a phase document and advancement between phases must have explicit user confirmation. If the user has not clearly said "confirm/pass/no problem/adopt/continue advancing this phase" or an equivalent expression, this skill must first use question to ask "whether to confirm that the current phase document passes as a whole"; before confirmation, it must not write confirmed_stagesand must not advance current_step. Each advancement must synchronously update the corresponding spec's _meta.json and the top-level updated_at。
Skipping phases is prohibited. The user saying "just write the code directly" or "it's just a small bug" is not a reason to skip the process. The correct approach is to dispatch to the corresponding phase, or go through the add iteration, minimal iteration, or pause and priority insertion process.
Queue changes are uniformly controlled by this skill. Spec enqueueing, dequeueing,active/pending/paused/done switching, splitting sibling specs, and priority insertion must all be confirmed via question before writing to state.json, and synchronously _meta.json。
State only writes _meta.json, and does not rename spec directories. Do not add done、paused and other status prefixes to spec directory names.
Restarting must be confirmed twice and the deletion scope must be limited. By default, only delete .dwf/. If root directory project code really needs to be deleted, first generate an itemized deletion list, excluding skills/、.git/, agent configuration, documentation, scripts, and other repository maintenance files, then use question Have the user confirm item by item; no files may be deleted before secondary confirmation.
Use Chinese throughout. Unless the user explicitly requests another language, interactions,question options, status summaries, and orchestration instructions are all in Chinese. Code, paths, and technical terms may remain in English.
Items pending confirmation are initiated uniformly by this skill. The item-by-item confirmation of "pending confirmation items/pending confirmation matters/pending issues to resolve" in stage documents, the writing back of confirmed items, the recording of unconfirmed items to .dwf/pending/<迭代目录名>/state.json, and the deferred reminder before activating a spec are all handled by this skill; sub-skills do not parse this section, do not write pending confirmation status, and do not initiate item-by-item question。
The scan of pending confirmation items cannot be skipped. Each time a stage advancement is processed, even if the user has already said "continue" or "the document is fine", the just-confirmed stage document must first be read and the pending confirmation section scanned. If parseable entries exist, they must be processed item by item; if a pending confirmation section exists but is not parseable, question must be used to let the user choose "skip parsing and advance" or "the document needs modification and this section must be reorganized". Before this scan is completed, confirmed_stagesmust not be written, and current_step。
One trigger executes only one orchestration action. Each trigger completes at most one of the following actions: initialize and dispatch the current stage, dispatch the current stage of the current active spec, process one stage advancement, process one queue change, process one recovery or rebuild. The only allowed composite actions are: after initial initialization, dispatch requirements; after confirmation, activate a newly added/inserted spec and dispatch its first stage; after confirmation, activate and dispatch the current stage upon recovery. Multiple stages must not be executed consecutively in the same response.
After stage advancement, you must stop. After the sub-skill completes, the stage document is confirmed as a whole, and the pending confirmation items are processed, this skill may only advance current_step to affected_stages in the next stage and synchronize the status, then inform the user that the next stage is waiting to continue; the next stage's sub-skill must not be automatically invoked.
Batch generation of stage artifacts is prohibited. In workflow mode, this skill and the dispatched sub-skills must not generate or confirm multiple stage artifacts in requirements、design、breakdown、plans、todos、code all at once.

Status summary

.dwf/state.json is the authoritative source for the workflow. The top level maintains the ordered specs queue and completed_specs history; the _meta.json within each spec directory is a mirror. For the complete fields, example JSON, directory structure, and ledger schema, see references/state-model.md。

Spec queue status:

Status	Meaning
`pending`	Queued, waiting to execute
`active`	Currently executing, at most one at the same time
`paused`	Interrupted by a higher-priority spec, progress retained pending recovery
`done`	Completed, moved from `specs` into `completed_specs`

Stages and dispatch targets:

`current_step`	Stage	Sub-skill
`requirements`	Requirements document pending confirmation	`dwf-requirement`
`design`	Design draft pending confirmation	`dwf-design`
`breakdown`	Requirements analysis pending confirmation	`dwf-development`
`plans`	Technical solution pending selection	`dwf-development`
`todos`	Implementation checklist pending confirmation	`dwf-development`
`code`	Coding in progress or pending wrap-up	`dwf-coding`

Default stage order:requirements → design → breakdown → plans → todos → code. Actual advancement is based on the current spec's affected_stages .

Flow per trigger

Read .dwf/state.json。
If it does not exist:
- If .dwf/specs/ also does not exist, proceed with first-time initialization.
- If .dwf/specs/ still exists, restore according to the references/orchestration-flows.md of state.json missing-rebuild process.
If specs is empty: the project is in a stable state. When the user proposes a new change, proceed with adding a new iteration.
If there is a active spec: dispatch sub-skills according to its current_step ; if the user proposes an urgent change, proceed with pause and priority insertion.
If there is no active but there is paused or pending: first handle the unconfirmed states in .dwf/pending/ according to the deferred-item reminder process, then use question to let the user choose to restore paused or activate the first pending。
If active.current_step == "code" and the implementation checklist is fully completed and verified, proceed with iteration completion.

After dispatching the sub-skill, this orchestrator orchestration action ends. The current turn is handed over to that sub-skill to complete the current stage; subsequent stages must wait for the user to confirm again or for the next trigger, then reread state.json before dispatching again.

Dispatch rules

When dispatching, treat the sub-skill as a workflow-mode executor: it reads state.json and the current active spec directory, and generates or confirms the content of the current stage. This skill only specifies the target spec, stage, and context; it does not write the body on behalf of the sub-skill.

When a sibling spec (shared_ref non-empty) executes breakdown、plans、todos , the sub-skill should treat shared_ref in the initialization spec pointed to by 01-需求/、02-设计稿/ as read-only context, and should not regenerate project-level requirements and design documents.

Stage advancement

After the sub-skill completes the current stage, this skill may advance the state only when the stage document as a whole has been explicitly confirmed by the user:

Determine whether the user input or question result has clearly confirmed that the current stage document as a whole passes; if not, first use question to request confirmation, and if unconfirmed, stop and do not write any stage state.
Read the just-confirmed stage document and check whether there is a non-empty "items to be confirmed/matters to be confirmed/issues to be resolved" section; if so, this skill enters the item-by-item confirmation loop for pending items.
After the pending items are handled, add the current stage to confirmed_stages。
According to the order in affected_stages , advance current_step to the next stage.
Synchronously update the spec item in state.json , the corresponding _meta.json, and the top-level updated_at。
Stop this orchestration and explain to the user that the next stage is ready; wait for the user to continue or confirm next time before dispatching the next stage.

Special rules:

When skipping the design document, set design_skipped to true, remove affected_stages from design, and directly enter the next affected stage.
plans The stage must have dwf-development provide at least two options, and let the user choose through question ; write the selected value into selected_plan。
After the breakdown of the initialization spec is confirmed, if the requirements cover multiple pages or complex modules, question must be used to ask whether to split sibling specs.
After advancing to code and completing coding verification, enter the iteration completion process.

Queue operations

Before performing the following operations, you must read the corresponding section of references/orchestration-flows.md :

First-time initialization: create .dwf/、.dwf/specs/, the first {date}-{seq}-feat-项目初始化 spec skeleton, the initial state.json and _meta.json, then dispatch dwf-requirement. Do not create an empty pending-confirmation state; create .dwf/pending/<迭代目录名>/state.json。
Split iteration: execute only after the initialized spec's breakdown has been confirmed and the user agrees. Sibling specs write shared_ref and _context.md, enqueue as pending, and the execution order is confirmed via question .
Iteration complete: mark the active spec as done, sync _meta.json, move from specs into completed_specs, increment iteration_count, then decide whether to activate the next spec.
Add iteration: when the project is stable or a new change is received during the coding phase, confirm the spec name,affected_stages, directory skeleton, and queue position.
Pause and priority insertion: before an urgent requirement interrupts the current active one, it must be confirmed with question ; the original spec is changed to paused, and the new spec is inserted at the head of the queue and set as active。
Restart: .dwf/may be deleted only after a second risk confirmation is completed; root directory project code may be deleted only after the user confirms the deletion list item by item, then return to the first initialization.

Pending confirmation items

Before advancing a phase, this skill must read the just-confirmed phase document and parse the heading ## 待确认项、## 待确认事项 or ## 待解决问题, with list items matching ^-\s+. For each item, use question to let the user choose "Resolved, provide the answer", "Skip, leave for a later iteration", or "Already modified directly in the document". This step must not be omitted just because the user says "continue" or "the document is fine".

Handling rules:

The user has confirmed or has already modified the document: write the user's decision back to the pending-confirmation section of the corresponding phase document; do not write to .dwf/pending/。
The user skipped or did not confirm: write to .dwf/pending/<迭代目录名>/state.json in the corresponding phase array. Each file contains requirements、design、breakdown、plans、todos five array fields.
Before any spec is about to transition to active , first scan .dwf/pending/*/state.json for unconfirmed items; if any exist, use question to remind the user to choose to handle them item by item, continue deferring all of them, or handle only the items from this spec. See the two reference files for the complete state structure and flow.

Resume

When this skill is triggered again after a session interruption, do not reinitialize. After reading state.json :

Has active: dispatch the corresponding sub-skill according to its current_step .
No active but has paused: use question to let the user choose which one to resume.
Only pending: before activating the first pending , first handle the deferred-item reminder.
Queue is empty: the project is stable, waiting for new changes.

Before each resume write-back, align the current spec's _meta.json with state.json.specs .

Pre-completion check

Before finishing, confirm:

Has first read .dwf/state.json, and identified the current queue state.
No phase document body or project code was generated.
All phase advances, queue changes, splits, queue jumps, and restarts were confirmed via question .
state.json, corresponding _meta.json, top level updated_at synchronized.
The spec directory was not renamed with a status prefix.
Pending items written back,.dwf/pending/ unconfirmed status and deferred reminders have been handled according to the rules.
Interactions with the user and question content are all in Chinese.