Skip to content

quickstart.md

Latest commit

 

History

History
185 lines (123 loc) · 5.19 KB

quickstart.md

File metadata and controls

185 lines (123 loc) · 5.19 KB
Raw

Quickstart

If you want the complete first-time onboarding path, see First-Time Setup.

Recommended: use the shell

awf shell is the preferred way to run AWF day-to-day. It shows the current workflow state, recommends the next safe action, lets you configure adapters by phase, and guides you through the full loop without needing to remember individual flags.

awf shell --repo C:\repo

Shell commands you can type once inside:

  • /flow — show the workflow diagram with the current step highlighted
  • /stage — move back to planning, implementation, review, or verification
  • /configure — set adapters by stage
  • /resume — run the best safe next action

First time only: bootstrap the target repo before launching the shell:

awf bootstrap-repo --repo C:\repo --enable-installed

Check detected CLIs and setup hints any time:

awf tooling-status

Direct commands reference

The commands below are for scripting, CI pipelines, and one-off targeted actions. --repo / --path defaults to the current folder when omitted.

Start a story

From a Markdown file:

awf start-story --repo C:\repo --story-file C:\repo\story.md

From Jira via the Atlassian Rovo MCP server:

awf start-story --repo C:\repo --jira-url https://your-site.atlassian.net/browse/ABC-123

Add --design-file to include a supporting design or architecture doc so the AI intake pass can compare story vs design:

awf start-story --repo C:\repo --story-file C:\repo\story.md --design-file C:\repo\design.md --ai

Add --ai alone to let the configured intake adapter refine the story draft before AWF validates it. Add --launch when the adapter has an automatic launch command.

Add --interactive to walk the clarification questions in the same terminal session:

awf start-story --repo C:\repo --story-file C:\repo\story.md --interactive

Clarify a story

If intake returns needs_clarification, reopen the interactive loop:

awf clarify-story --repo C:\repo --interactive

To have the AI re-read the story and persisted design context after your answers:

awf clarify-story --repo C:\repo --interactive --ai

For a one-shot scripted answer:

awf clarify-story --repo C:\repo --ac "User can save a document update and an audit record is written"

Replace the acceptance criteria instead of appending:

awf clarify-story --repo C:\repo --set-ac "First criterion" --set-ac "Second criterion"

Plan, implement, and verify

awf plan --repo C:\repo
awf run-next --repo C:\repo

After the implementation session:

awf continue --repo C:\repo --status completed --summary "Added audit insert" --changed-file src/AuditService.cs
awf review --repo C:\repo
awf verify-story --repo C:\repo

--summary, --changed-file, --key-change, and the other awf continue fields are optional continuity metadata. They improve the next handoff but are not required.

Set the phase adapter from the command line

AWF persists the choice into .wi/config.json and reuses it when the flag is omitted next time:

awf plan --repo C:\repo --adapter codex --model gpt-5.4 --agent awf-planner
awf run-next --repo C:\repo --adapter claude --model claude-sonnet-4-5 --agent awf-implementer --launch
awf review --repo C:\repo --adapter gemini --model gemini-2.5-pro --agent awf-reviewer

The same pattern works for start-story and verify-story.

Bare-minimum scaffold (no guided setup)

awf init-repo --path C:\repo --adapter claude --auto-commit false

Optional modes

Automatic task commits

Enable only when you want AWF to create a git commit after each successfully verified task:

awf set-auto-commit --repo C:\repo --enabled true

Pass --changed-file to awf continue to keep the commit path-scoped.

Supervised autonomy

Disabled by default. Advances the workflow to the next supervision boundary automatically:

awf set-supervised-autonomy --repo C:\repo --enabled true
awf run-supervised --repo C:\repo

Human review gate

Disabled by default. Pauses the workflow for manual approval after a successful review:

awf set-human-review --repo C:\repo --enabled true

Approve or reject:

awf approve-review --repo C:\repo --reviewer "Jose"
awf reject-review --repo C:\repo --reviewer "Jose" --reason "Design direction needs revisiting" --return-phase planning

Stable phase routing via config

Edit .wi/config.json directly when you prefer fixed defaults over per-command flags:

{
  "default_adapter": "codex",
  "phase_execution": {
    "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" }
  }
}

To use Copilot custom agents for those phases, install the bundled profiles first:

./installers/install-copilot-agents.ps1