Skip to content

first-time-setup.md

Latest commit

 

History

History
186 lines (128 loc) · 5.26 KB

first-time-setup.md

File metadata and controls

186 lines (128 loc) · 5.26 KB
Raw

First-Time Setup

This guide is the recommended first-time path for getting Agent Workflow Framework (AWF) installed and working against your first target repository.

What this setup covers

By the end of this guide you will have:

  • installed AWF once on your machine
  • bootstrapped a target repository with the .wi/ artifacts
  • enabled the adapters already available on your machine
  • verified the repo setup with AWF diagnostics
  • started your first story

Step 1: Confirm dependencies

Make sure the machine has:

  • Node.js and npm
  • Git
  • PowerShell on Windows or Bash on macOS/Linux
  • at least one supported adapter CLI if you want AWF to launch agents directly:
    • Codex
    • Claude
    • Gemini
    • GitHub Copilot CLI exposed as copilot

For dependency details, see DEPENDENCIES.md.

Step 2: Install AWF

From the framework repo root, run:

./installers/install-framework.ps1

Or on Bash:

./installers/install-framework.sh

This installs the framework into a shared location so you can reuse it across many repos.

On Windows, install-framework.ps1 also adds the AWF bin directory to your user PATH when needed. Open a new terminal after install if awf is not available in the current session yet.

On Bash, the installer does not edit your shell profile for you, so add ~/.awf/bin to PATH if you want to launch awf from any terminal.

Step 3: Pick the target repo you want AWF to manage

Move to the repository where you want AWF to create and manage the .wi/ working artifacts.

If you want to inspect what tooling AWF can already detect before changing anything, run:

./bin/awf.ps1 tooling-status --repo C:\repo
./bin/awf tooling-status --repo /repo

Step 4: Run the first-time setup helper

Use the guided bootstrap flow for your first repo:

./bin/awf.ps1 bootstrap-repo --repo C:\repo --enable-installed
./bin/awf bootstrap-repo --repo /repo --enable-installed

This is AWF's closest equivalent to an installation wizard. In one pass it:

  • initializes .wi/
  • detects the supported CLIs already installed on the machine
  • updates .wi/config.json
  • enables the installed adapters you already have
  • runs a validation pass so you can catch setup problems early

If you prefer the installer wrapper instead of calling the CLI directly, use:

./installers/bootstrap-repo.ps1 -RepoPath C:\repo -EnableInstalled
./installers/bootstrap-repo.sh --repo /repo --enable-installed

Step 5: Review the generated repo artifacts

After bootstrap, check these files in the target repo:

  • .wi/config.json
  • .wi/story.json
  • .wi/tasks.json
  • .wi/acceptance.json
  • .wi/runtime/orientation.json

Not every file will contain active work yet, but the structure should now exist and be ready for the workflow.

Step 6: Re-check tooling health

Run:

./bin/awf.ps1 tooling-status --repo C:\repo
./bin/awf tooling-status --repo /repo

If AWF reports missing tools, install the missing CLI and rerun:

./bin/awf.ps1 configure-tooling --repo C:\repo --enable-installed
./bin/awf configure-tooling --repo /repo --enable-installed

Step 7: Launch the shell

After bootstrap, the guided shell is the recommended entry point for all day-to-day work:

./bin/awf.ps1 shell --repo C:\repo

The shell shows the current workflow state, recommends the next safe action, and walks you through intake, planning, implementation, review, and verification without needing to remember individual flags.

Step 8: Start your first story

The shell will prompt you through story intake. If you prefer to run it directly from the command line, here are the equivalent commands.

From Markdown:

./bin/awf.ps1 start-story --repo C:\repo --story-file C:\repo\story.md

From Jira:

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

If the story depends on a design doc, include it so the AI intake pass can compare story vs design:

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

If intake reports needs_clarification, use the interactive loop:

./bin/awf.ps1 clarify-story --repo C:\repo --interactive

Step 9: Run the normal workflow

Once intake is stable, the shell will guide you through the rest. The equivalent direct commands are:

./bin/awf.ps1 plan --repo C:\repo
./bin/awf.ps1 run-next --repo C:\repo
./bin/awf.ps1 review --repo C:\repo
./bin/awf.ps1 verify-story --repo C:\repo

Common first-time recommendations

  • Start with bootstrap-repo instead of init-repo unless you deliberately want the bare minimum scaffold.
  • Use --enable-installed on the first pass so AWF only enables tooling that actually exists on your machine.
  • Run tooling-status before and after setup when you want a quick diagnostic without guessing.
  • Keep auto-commit off until you are comfortable with the workflow in your repo.

If something does not work

Use these references next: