AWF keeps the workflow state in .wi/ and lets you route each phase to the CLI, model, and Copilot custom agent you prefer.
flowchart TD
A[Story source\nMarkdown file or Jira URL] --> B[awf start-story]
B --> C{Clarification needed?}
C -- Yes --> D[awaiting_clarification]
D --> E[awf clarify-story]
E --> C
C -- No --> F[awf plan]
F --> G[.wi/tasks.json + .wi/acceptance.json]
G --> H[awf run-next]
H --> I[.wi/runtime/task.json]
I --> J[Implementation agent session]
J --> K[awf continue]
K --> L{More tasks?}
L -- Yes --> H
L -- No --> M[awf review]
M --> N{Gaps found?}
N -- Yes --> H
N -- No --> O{Human review enabled?}
O -- Yes --> P[awaiting_human_review]
O -- No --> Q[awf verify-story]
P --> R{Approved?}
R -- No --> H
R -- Yes --> Q
Q --> S[Story complete]
flowchart LR
Intake[Intake\nsource normalization] --> Planning[Planning\ntask slicing]
Planning --> Implementation[Implementation\nactive task execution]
Implementation --> Review[Review\nAC gap detection]
Review --> Verification[Final verification\nclose or reopen]
Start-Intake.ps1 or awf start-story normalizes ticket input into .wi/story.json. Markdown intake now preserves common story sections including bullets, numbered lists, and inline labels. awf start-story --ai can also generate an intake handoff for the configured intake adapter so AI can refine the story draft before AWF re-validates it, and --design-file / --design-note let intake compare the story against supporting design context during that pass. .wi/intake-context.json preserves the story source plus those design/context inputs so later clarify-story --ai runs stay grounded. When blocking ambiguity remains, AWF generates clarification questions from the story content itself, records them in .wi/clarification.json, and pauses in awaiting_clarification instead of guessing. That clarification step happens before planning begins, so the proposal/planning boundary is never reached on an ambiguous story.
Use awf clarify-story --interactive to answer those questions in one terminal session. The interactive clarification loop now lets you review and revise answers before continuing. Use the direct flags only when you need a scripted update.
Supported story sources:
- local Markdown or JSON via
--story-file - Jira issue URL via
--jira-url - flexible inline/file/URL input via
--ticket-source
You can set the intake tool on the command line with --adapter, --model, and --agent. AWF persists the selection and reuses it as the last-used value when you omit the flags later.
Start-Planning.ps1 or awf plan generates .wi/tasks.json and .wi/acceptance.json.
Planning now assumes intake is stable. If blocking intake questions are still open, awf plan stops and sends the workflow back to clarification instead of producing speculative tasks.
Use this phase to decide which CLI and model should own decomposition, but keep the output small and implementation-ready.
Start-Implementation.ps1 or awf run-next selects the highest-priority ready task and writes .wi/runtime/task.json.
The runtime packet now carries the active story slice, referenced AC text, task priority metadata, and a compact continuity preview so most implementation sessions can stay inside task.json plus orientation.json. The shell also surfaces changed-file summaries and adapter command previews after implementation dispatch.
This is the phase with built-in adapter launch support today. The runtime packet records the selected adapter, model, and Copilot agent name so the same routing choice is visible inside the repo.
If you need to deliberately go backward, the shell can now move the workflow back to planning, implementation, review, verification, or clarification and then recommend the correct next command for that stage.
Continue-NextTask.ps1 or awf continue records the task outcome, refreshes .wi/runtime/orientation.json, runs the task verification commands before accepting --status completed, optionally creates a path-scoped git commit, and then prepares the next task packet.
The --summary, --changed-file, --key-change, --risk, and related options are optional metadata. They improve the next handoff, but they are not mandatory.
Start-Review.ps1 or awf review checks ticket-goal and AC support, then appends small corrective tasks when needed.
If optional human-review mode is enabled and the review passes, AWF pauses in awaiting_human_review until someone approves or rejects the result.
awf verify-story runs final checks before marking the story complete.
If human-review mode is enabled, final story completion requires an approved human review.
Use it only when you want AWF to create a git commit after each successfully verified task:
./bin/awf.ps1 set-auto-commit --repo C:\repo --enabled trueWhen awf continue receives --changed-file, AWF uses those repo-relative paths to keep the commit scoped to the task instead of pulling in unrelated dirty files. AWF respects the repo's existing git signing policy.
Use it when you want AWF to progress the story automatically until it reaches a supervision boundary:
./bin/awf.ps1 set-supervised-autonomy --repo C:\repo --enabled true
./bin/awf.ps1 run-supervised --repo C:\repo --launchThis mode is disabled by default and pauses on agent execution, human review, review gaps, blockers, or verification failure.
Use it only when you want a person to approve or reject the flow:
./bin/awf.ps1 set-human-review --repo C:\repo --enabled true
./bin/awf.ps1 approve-review --repo C:\repo --reviewer "Jose"
./bin/awf.ps1 reject-review --repo C:\repo --reviewer "Jose" --reason "We do not agree with the design" --return-phase planningThis mode stays lightweight by storing the latest review decision in .wi/human-review.json and copying only the actionable rejection into orientation.json.
Set per-phase ownership in .wi/config.json:
{
"default_adapter": "codex",
"human_review": {
"enabled": false
},
"auto_commit": {
"enabled": false
},
"phase_execution": {
"intake": {
"adapter": "copilot",
"model": "gpt-5",
"agent": "awf-intake"
},
"planning": {
"adapter": "codex",
"model": "gpt-5.4",
"agent": "awf-planner"
},
"implementation": {
"adapter": "claude",
"model": "claude-sonnet-4-5",
"agent": "awf-implementer"
},
"review": {
"adapter": "gemini",
"model": "gemini-2.5-pro",
"agent": "awf-reviewer"
},
"final_verification": {
"adapter": "copilot",
"model": "gpt-5",
"agent": "awf-verifier"
}
}
}You can also update those values from the command line:
./bin/awf.ps1 run-next --repo C:\repo --adapter claude --model claude-sonnet-4-5 --agent awf-implementer --launchNotes:
adapterchooses the CLI family AWF should use for that phase.modelis optional and phase-specific.agentis the matching custom agent profile name from.agents/or your local.copilot/agents/folder.- Command-line phase selections are persisted, so the next run uses the last value unless you override it again.
- The interactive stage wizard also remembers the last adapter/model pair you picked and uses it as the Enter-key default for the next phase.
- AWF currently auto-launches the implementation adapter. The other phase entries are still valuable as the documented routing contract for humans, scripts, and Copilot agent selection.
- The shell stage wizard configures both phase routing and the corresponding adapter enablement so the selected tool is ready to launch.
awf verify-task runs the verification commands for the currently active or last completed task without advancing phase state. Use it when you want a targeted check after making changes without triggering a full continue.
./bin/awf.ps1 verify-task --repo C:\repoawf sync-docs refreshes .wi/README.md from the framework template. Use it after a framework upgrade or when the repo README has drifted from the template.
./bin/awf.ps1 sync-docs --repo C:\repo