Choose a Workflow

Workflows are the part of OAT for tracked, resumable work. They are optional and sit on top of the CLI and provider sync.

Before you choose, read Approvals and Automation: it shows, for each mode, where a person approves, what an agent does without asking, and when OAT pushes or opens a pull request.

Use this section when you want explicit project artifacts, stable task IDs, review loops, and resumable execution across longer-running work. The workflow layer is optional; stay with direct CLI usage when the task is straightforward and the overhead of project artifacts would outweigh the value.

Where to go from here

• Brainstorm Before Choosing a Workflow - Not sure what the work is yet? Talk it through with /oat-brainstorm first; it ends with an answer, a document, or a handoff to an idea, a backlog item, or a project.
• Ideas Workflow - Lightweight idea capture, brainstorming, and promotion into tracked projects when the work becomes concrete.
• Projects - Lifecycle, artifacts, reviews, PR flow, and repository analysis.
• Wave Workflows - Program-level coordination for executing a corpus of external plans as ordered wrapper projects.
• Skills - Workflow-oriented skill discovery and use-case routing.

What This Section Is

This section explains when workflow mode is worth the overhead, how OAT projects move through lifecycle phases, and how ideas, skills, reviews, and PR flow fit into that model.

Who It's For

• Teams doing multi-session or multi-phase work that benefits from tracked artifacts
• Users who want explicit discovery, planning, implementation, and review state
• Repos that need a repeatable human-in-the-loop execution model

When To Use Workflow Mode

Use workflow mode when:

• the work spans multiple sessions or contributors
• you want explicit discovery, plan, implementation, and review artifacts
• you need stable task sequencing and resumable execution
• you want human-in-the-loop checkpoints around risky transitions

Stay with direct CLI usage when:

• the task is straightforward and bounded
• you mainly need provider sync or a utility command
• the overhead of project artifacts would outweigh the value

Workflow Modes In Practice

• CLI only: direct commands, no tracked project artifacts
• Lite mode: a batched interview and one approval produce a single-phase plan.md for a single-sitting change
• Brief mode: a design-aligned interview produces one reviewed Project Brief whose phases carry intent and exit evidence instead of tasks
• Goal mode: a brief whose phases are grouped into milestones, each delivered as its own pull request and followed by a re-alignment, closed by an explicit declaration audited against the brief's outcomes
• Quick mode: tracked work with a lighter upfront planning path
• Spec-driven mode: explicit discovery, requirements, design, and plan artifacts
• Import mode: an externally-authored plan imported into OAT for tracked execution

Start Here

• Use Skills when you want task-oriented guidance on the most useful workflow skills.
• Go to Workflow & Projects when you need the lifecycle and artifact model in detail.
• Use Ideas when the work is still exploratory.

Common Tasks

• Capture or refine early work in Ideas.
• Understand how tracked projects progress in Workflow & Projects.
• Learn the artifact contract in Artifacts.
• Understand review and PR expectations in Reviews and PR Flow.

Go Deeper

• Skills - Workflow-oriented skill discovery and use-case routing.
• Ideas - Idea capture, refinement, and promotion flows.
• Workflow & Projects - Lifecycle, artifacts, reviews, PR flow, and repository analysis.

Which mode should I choose?

A mode decides how much planning happens before any code is written. You pick it by running that mode's entry skill, and the skill creates the project for you. An OAT project is a folder of tracked files (plan, state, reviews) that lets an agent pick the work up again in a later session.

Type the skill names in your coding agent's chat, not a terminal; Codex uses $ instead of /. No mode ever merges a pull request. Separately, oat-project-complete opens a pull request without asking when workflow.createPrOnComplete is true. Project files of a project in the default synced scope are also pushed to origin whenever a skill saves them; see Approvals and Automation.

Decide by how clear the requirements are and how risky the design is, not by how many tasks the work has. A large but well-understood change can still be a quick project. If you run oat project new yourself without --mode, it creates a spec-driven project, but it only creates the files; the entry skill is what holds the planning conversation, so start with the skill.

• If you are a solo developer fixing one well-understood bug, choose lite, or skip the project entirely if you will not need to resume or review it later. Lite ends by pushing your current branch and opening a pull request without asking, so start it on a feature branch; if you do not want that, choose quick instead, which opens a pull request only when workflow.postImplementSequence asks for one or the run is autonomous.
• If you can agree the outcome and the design with your agent in one conversation and want to approve that once, choose brief. You approve one reviewed Project Brief; the agent then works phase by phase and records each task as it happens rather than planning them all first. Promote it to quick with oat project promote <path> --to quick if you later want a maintained task plan.
• If the outcome needs more than one delivery, such as a first version now and a follow-up once you have seen it used, choose goal. You approve one brief with a milestone split, then each milestone is delivered as its own pull request and re-aligned before the next one starts; you declare the goal met at the end. Goal is never selected by an autonomous run, because each milestone approval and the final declaration need you.
• If your team is building a feature with agreed, bounded requirements, choose quick. A long task list alone does not call for a formal spec.
• If the change is high-risk or regulated, or its requirements are still being debated, choose spec-driven so discovery and design are agreed before implementation starts.
• If you already have an approved plan from another tool, import it rather than repeating discovery and design.