Agent Workflow Framework

Reusable artifact-driven tooling for running intake, planning, implementation, review, and verification across many repositories while keeping each target repo lightweight.

The framework installs once, scaffolds a minimal .wi/ contract into a target repo, and then drives fresh-session handoffs through compact task packets and small structured artifacts instead of long conversation history.

On Windows, install-framework.ps1 adds the AWF bin directory to the user PATH when needed, so awf can be launched from a new terminal after install. See Installation for platform-specific details.

Why this solution matters

Most agent workflows break down in one of three places:

• context becomes too large, noisy, or expensive to replay
• acceptance criteria get lost between planning, implementation, and review
• teams mix multiple CLIs and models, but the handoff between them is informal

AWF addresses those problems with a simple control plane:

• the story is normalized into .wi/story.json
• awf start-story --ai can hand the draft story plus supporting design context to the configured intake adapter so AI can refine AC, ambiguity, risks, and other planning inputs before AWF validates the result
• .wi/intake-context.json preserves the story source and any design/context inputs so later clarification passes can stay grounded
• intake keeps clarifying until the story-derived blocking gaps are explicit enough for planning, and the interactive clarification loop lets you review and revise answers before continuing
• blocking intake questions are tracked in .wi/clarification.json until the story is ready for planning
• the plan is captured in .wi/tasks.json and .wi/acceptance.json
• each task is dispatched through .wi/runtime/task.json, which carries the active story slice, referenced AC text, task priority, and verification contract
• continuity is refreshed in .wi/runtime/orientation.json, while task.json keeps only a compact preview
• review and verification are tracked as explicit repo artifacts instead of chat-only state
• optional path-scoped git commits can be created automatically after each verification-backed task completion

Value for teams

• Lower context cost: each new agent session starts from a compact task packet that already includes the active story slice and referenced AC text instead of a long transcript.
• Stronger traceability: acceptance criteria are mapped to tasks and checked again during review.
• Safer multi-model workflows: planning, implementation, review, and verification can each use different CLIs or models without losing the thread.
• Better repo portability: the framework lives once, while target repos only need a small .wi/ footprint plus their own AGENTS.md.
• Better recovery: if an agent session ends, the next one can resume from artifacts already on disk.

When AWF is a good fit

AWF is especially useful when:

• one team works across many repos
• stories come from Markdown today and Jira tomorrow
• you want Codex, Claude, Gemini, or Copilot to own different phases
• you need auditable task slicing and acceptance-criteria coverage
• fresh sessions are a feature, not a failure mode

Core flow

The recommended entry point is the guided shell:

awf shell

The shell shows the current workflow state, recommends the next safe action, lets you configure adapters by phase, and guides you through every stage — intake, planning, implementation, review, and verification — without needing to remember individual flags.

First time only: bootstrap the target repo once before starting:

awf bootstrap-repo --repo <path> --enable-installed

After that, awf shell covers the full day-to-day loop. Use awf tooling-status any time you want a quick check of detected CLIs, Jira MCP readiness, and setup hints.

Direct commands (start-story, plan, run-next, continue, review, verify-story, etc.) remain fully supported for scripting, CI pipelines, and one-off targeted actions. See Quickstart for a full reference of those commands and their flags.

The Council of Systems — Execution Model

AWF's execution cycle is built around four fundamental engineering patterns — not arbitrary phases, but recurring forces observed across real system delivery:

Role	Archetype	Domain
Axiom — The Interpreter	Intake agent	Extracts meaning, resolves ambiguity, and normalizes the problem space from incomplete signals into structured stories.
Vector — The Architect	Planner agent	Selects the path forward — decomposes stories into dependency-aware tasks, aligns constraints, and defines acceptance coverage.
Forge — The Builder	Implementer agent	Transforms structured plans into working systems, executing one task at a time with implementation fidelity.
Sentinel — The Guardian	Reviewer / Verifier agent	Validates outcomes against acceptance criteria, exposes gaps, and ensures what was built matches what was intended.

The cycle flows sequentially — Axiom → Vector → Forge → Sentinel — with Sentinel feeding corrective tasks back into Forge when gaps are found. This mirrors the artifact handoff chain (.wi/story.json → .wi/tasks.json → .wi/runtime/task.json → review/verification logs) that keeps each fresh agent session grounded without replaying long conversation history.

For the full narrative, see The Council of Systems — Execution Cycle Lore.

Where to read next

• Overview
• First-Time Setup
• Workflow Phases
• Quickstart
• Copilot Guide
• Architecture
• Tooling Setup
• Human Review Mode
• Supervised Autonomy Mode