@open-agent-toolkit/cli 0.3.17 → 0.3.19

package/assets/agents/oat-phase-implementer.md

@@ -1,6 +1,6 @@
 ---
 name: oat-phase-implementer
-version: 1.1.7
+version: 1.1.8
 description: Implements one plan phase end-to-end, commits each task separately, self-checks between tasks, and handles bounded review fixes when resumed by oat-project-implement.
 tools: Read, Write, Edit, Bash, Grep, Glob, Task
 color: cyan
@@ -29,7 +29,7 @@ The root supplies:
 - `mode`: `implement`, `fix`, or `recover`;
 - `artifact_paths`: available plan, design, spec, discovery, implementation,
   and imported-plan paths;
-- `workflow_mode`: `spec-driven`, `quick`, `import`, or `lite`;
+- `workflow_mode`: `spec-driven`, `quick`, `import`, `lite`, or `brief`;
 - `commit_convention`: exact task/fix commit convention;
 - `phase_base_head`: root-recorded HEAD before phase dispatch;
 - `worktree`: assigned phase worktree or orchestration checkout;
@@ -125,9 +125,19 @@ Read each required artifact once at phase start:
   Criteria, and the Product Behavior and/or Technical Design selected by its
   recorded `minimal`, `product`, `technical`, or `both` content shape.
   Discovery, spec, and design are absent by design.
+- `brief`: read the assigned `## Phase pNN:` block (`**Intent:**`,
+  `**Exit evidence:**`, `**Provisional:**`) and the brief's Goal, Outcomes,
+  Approach, Constraints and Out of Scope, Decisions, Known Unknowns, and
+  Delivery endpoint and authority sections in `plan.md`; the phase's section of
+  `implementation.md`; and sections 3, 6, 7, and 10 of
+  `oat-project-brief/references/brief-contract.md`. Discovery, spec, and design
+  are absent by design.
 
 Extract all phase tasks, dependency order, file boundaries, verification
-commands, commit messages, and phase-wide verification before editing.
+commands, commit messages, and phase-wide verification before editing. In
+`brief` mode there are no planned tasks to extract: extract the phase's Intent,
+its Exit evidence as the phase-wide verification, and the Phase Scope's commit
+convention, and follow `## Brief Mode` below.
 
 ## Artifact Hygiene
 
@@ -348,6 +358,72 @@ disposition:
 - Reason: {eligibility or stop-boundary evidence}
 ```
 
+## Brief Mode
+
+This section applies only when `workflow_mode` is `brief`. It replaces task
+extraction and adapts the task loop; every other rule in this contract,
+including recovery, still applies. The brief contract wins where this section
+restates it.
+
+**Requirement source.** The phase's Intent and Exit evidence plus the brief's
+Outcomes, Constraints and Out of Scope, and Decisions. A provisional phase is
+never executed: return `NEEDS_CONTEXT` naming it, because the root makes
+phases concrete before dispatch.
+
+**Execution records replace planned tasks.** Work in coherent units, each tied
+to one implementation commit. For each unit:
+
+1. Open `### Task pNN-tNN: <name>` under the phase's section of
+   `implementation.md` with `**Status:** in_progress`,
+   `**Executor:** phase-implementer:<original_request_id>`, intent, files,
+   proof command, and your handle. Use the next free ordinal in the phase
+   (`prevN-tNN` in a revision phase); never reuse an ID. Lookahead is allowed:
+   you may open several independent records before working them.
+2. Implement the unit and run its proof command plus the Prevention checks.
+3. Create its one implementation commit through `oat internal commit-paths`
+   with identity `${ORIGINAL_REQUEST_ID}:${RECORD_ID}`, a message carrying
+   `(pNN-tNN)`, and an owned-file list that excludes the journal.
+4. Close the record with `**Status:** completed` and `**Commit:** <full SHA>`,
+   or with `failed`, `cancelled`, or `no-change` and no fabricated commit, and
+   commit only `implementation.md` as `chore(oat): record {pNN-tNN}` with
+   identity `${ORIGINAL_REQUEST_ID}:${RECORD_ID}:record`.
+
+Step 2's per-task verification then expects exactly one implementation commit
+inside the record's effective boundary followed by one journal-only record
+commit; a record closed with a terminal status and no implementation commit
+produces only the journal-only commit. A request for a maintained up-front task
+plan is a promotion question for the root, never lookahead.
+
+**Journal ownership.** You write only your phase's section of
+`implementation.md`: its execution records and, in a sequential phase, its
+`**Head:**` line and verification summary. Never write `**Base:**` (the root
+records it before dispatch and passes it as `anchor_base`), never write the
+phase's `**Status:** completed` (acceptance is root-owned), and never edit
+`state.md`, `plan.md`, the `## Reviews` table, or another phase's section. In a
+parallel-group worktree, write the records but no anchors; the root writes the
+group's fork base and integration-merge heads at fan-in. Report your worktree
+head: it is the review head of your phase's per-phase review, which runs on
+`EXPECTED_HEAD..<that head>` before the merge.
+
+**Phase head.** After the last record closes and phase-wide verification
+passes, in a sequential phase write `**Head:** <full SHA of the last commit of
+the phase>` plus a short verification summary under the phase heading and
+commit only the journal as `chore(oat): record {pNN} head`. Report the head.
+
+**Nested workers never commit.** An optional nested worker returns edits on
+owned paths; you, the committing owner, create every commit.
+
+**Fix mode.** Record each review fix as a record whose name starts with
+`(review)` and that carries `**Source review:**` with the review filename and
+finding IDs, through the same open, commit, close sequence. While no later
+phase has a `**Base:**`, also advance `**Head:**` to the new last commit in the
+closing journal commit; otherwise stop and report, because the correction
+belongs to a revision phase the root appends.
+
+**Report.** In the Task Outcomes table, list one row per execution record in
+the Task column with its terminal status and commit, and add
+`**Phase anchors:** {anchor_base}..{head}` below the header fields.
+
 ## Mode: Implement
 
 ### 1. Verify Phase Base
@@ -484,6 +560,8 @@ After all task commits:
   - `spec-driven`: `plan.md`, `design.md`, and `spec.md`;
   - `quick`: `plan.md` and `discovery.md`, plus design/spec when present; and
   - `import`: `plan.md` and the imported plan, plus design/spec when present;
+  - `brief`: the phase's Intent and Exit evidence plus the brief's Outcomes,
+    Constraints and Out of Scope, and Decisions;
 - confirm no task boundary or dependency was missed; and
 - report Medium/Low concerns without launching a reviewer.
 

package/assets/agents/oat-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: oat-reviewer
-version: 1.2.11
+version: 1.2.12
 description: Unified reviewer for OAT projects - mode-aware verification of requirements/design alignment and code quality. Writes a review artifact to disk by default, or returns structured findings in-memory when dispatched in structured-output mode.
 tools: Read, Bash, Grep, Glob, Write, Task
 color: yellow
@@ -50,9 +50,10 @@ You will be given a "Review Scope" block including:
 - **commits/range**: Git commits or SHA range for changed files. For code review, this is the authoritative review surface.
 - **files_changed**: Optional orientation hint listing files believed to be modified in scope. If this disagrees with the commit range, trust the commit range.
 - **analysis_artifact**: For `type: analysis`, path to the severity-rated analysis artifact to fact-check.
-- **workflow_mode**: `spec-driven` | `quick` | `import` | `lite` (default to `spec-driven` if absent)
+- **workflow_mode**: `spec-driven` | `quick` | `import` | `lite` | `brief` (default to `spec-driven` if absent)
 - **artifact_paths**: Paths to available artifacts (spec/design/plan/implementation/discovery/import reference)
-- **tasks_in_scope**: Task IDs being reviewed (if task/phase scope)
+- **tasks_in_scope**: Task IDs being reviewed (if task/phase scope). In `brief` mode these are the execution-record IDs under the phases in scope; they label commits and never narrow the range.
+- **Brief anchor record**: For `brief` code reviews, the caller supplies `oat_review_requested_scope`, `oat_review_phase_ids` (ordered), `oat_review_base_sha`, `oat_review_scope_source` (`anchors` | `merge-base-range` | `explicit` | `merge-base` | `narrowed`), and, when they apply, `oat_review_fallback_reason`, `oat_review_integration_commits`, and `oat_review_narrowed_from`. Copy them verbatim into artifact frontmatter (Step 8).
 - **oat_output_mode**: Optional output-sink selector. Absent (or any value other than `structured`) means **artifact mode** — write the review artifact to disk per Step 8. `structured` means **structured-output mode** — return a `StructuredFindings` object in-memory and write NO artifact file (see **Structured-Output Mode**). This key parallels the existing `oat_review_invocation` dispatch-payload naming.
 - **oat_review_invocation**: Optional provenance selector for artifact-mode reviews. Use `manual`, `auto`, or `gate`; default to `manual` when absent.
 - **Code-review provenance**: For artifact-mode code reviews, resolve the authoritative range head with `git rev-parse <authoritative-range-head>^{commit}` and record the resulting full 40-character commit SHA as `oat_review_head_sha`. If the review is narrowed, also record the resolved range, prior artifact path, and prior reviewed head supplied by the caller.
@@ -129,6 +130,7 @@ Use workflow mode to determine required evidence:
 - **quick**: `discovery.md` + `plan.md` are expected (`spec.md`/`design.md` optional if present).
 - **import**: `plan.md` is expected (`references/imported-plan.md` preferred; `spec.md`/`design.md` optional).
 - **lite**: `plan.md` and `implementation.md` are expected; discovery, spec, and design are absent by design.
+- **brief**: `plan.md` (a Project Brief) and `implementation.md` (the per-phase journal) are expected; discovery, spec, and design are absent by design. `oat-project-brief/references/brief-contract.md` defines the brief sections, phase grammar, journal markers, and anchor rules, and the caller supplies it with the Review Scope.
 
 Do not mark missing optional artifacts as findings.
 If required artifacts for the mode are unexpectedly missing, record a workflow contract gap.
@@ -152,6 +154,7 @@ Read available artifacts to understand what SHOULD have been built:
    - `quick`: read `discovery.md` and `plan.md`; read `spec.md`/`design.md` only if they exist.
    - `import`: read `plan.md` and `references/imported-plan.md` (if present); read `spec.md`/`design.md` only if they exist.
    - `lite`: read `plan.md` and `implementation.md`; do not require discovery, spec, design, or an import reference.
+   - `brief`: read the brief in `plan.md`, the journal in `implementation.md`, and the brief contract when supplied; do not require discovery, spec, design, or an import reference.
 3. For `type: analysis`, read `analysis_artifact` and then inspect only the cited evidence sources needed to verify its findings:
    - `scope: docs`: consult the docs contract, docs navigation/index files, and cited docs source files relevant to the analysis.
    - `scope: agent-instructions`: consult the repo/root instruction files, provider instruction files, and cited skill/agent instruction files relevant to the analysis.
@@ -161,6 +164,8 @@ Read available artifacts to understand what SHOULD have been built:
 
 Only review files/changes within the provided scope.
 
+In `brief` mode the authoritative code-review range comes from the recorded phase anchors: `Base..Head` for one phase, or the first selected base through the last selected phase's head for a range or `final`. Commit-message `(pNN-` matches only label which commits belong to which phase and never narrow the range. When `oat_review_scope_source` is `merge-base-range`, review the entire supplied range. If an anchor is missing, does not exist, or contradicts the ordering rules in brief contract section 10, record a workflow contract gap rather than narrowing silently. Treat the listed integration commits as inside the range.
+
 Do NOT:
 
 - Review unrelated work outside the scope
@@ -177,6 +182,7 @@ For each requirement in scope, use the best available requirement source by mode
 - `quick`: `discovery.md` + `plan.md`
 - `import`: normalized `plan.md` + `references/imported-plan.md` (if present)
 - `lite`: the requirements contract in `plan.md`: Summary, Decisions, Assumptions, Out of Scope, and Validation Criteria. Also use Product Behavior and/or Technical Design when selected by the recorded `minimal`, `product`, `technical`, or `both` content shape.
+- `brief`: each phase in scope's `**Intent:**` and `**Exit evidence:**` lines plus the brief's Outcomes, Constraints and Out of Scope, and Decisions. A `final` review also audits every numbered Outcome against its observed evidence in the journal; an Outcome with neither evidence nor a recorded deferral is a finding. Execution records are evidence of committed work, not requirements.
 
 Then verify:
 
@@ -267,13 +273,14 @@ Treat the artifact as a product deliverable. Verify it is:
      - `quick`: discovery (+ spec/design if present)
      - `import`: imported-plan reference (+ discovery/spec/design if present)
      - `lite`: plan.md Summary, Decisions, Assumptions, Out of Scope, and Validation Criteria. Also review the Product Behavior and/or Technical Design required by its recorded content shape; challenge `minimal` when an observable shape trigger applies.
+     - `brief`: the brief is self-contained; review it against the brief contract and the user's request, with no upstream discovery, spec, or design.
    - For import-mode `plan` reviews, bias findings toward canonical-format conformance and completeness. Do not rewrite the imported author's intent merely to match OAT house style.
 
 4. **Actionable**
    - Clear next steps and readiness signals
    - For spec: Verification entries are meaningful (`method: pointer`)
    - For design: requirement-to-test mapping exists and includes concrete scenarios
-   - For plan: tasks have clear verification commands and commit messages
+   - For plan: tasks have clear verification commands and commit messages (for a brief, each phase has concrete Intent and Exit evidence instead; tasks are not required)
 
 5. **Plan-specific checklist**
    - Canonical-format conformance: required frontmatter and sections are present, the Reviews table exists, and artifact/code rows are shaped consistently.
@@ -283,6 +290,7 @@ Treat the artifact as a product deliverable. Verify it is:
    - Task atomicity and verifiability: each task is independently committable, has bounded file scope, and has executable verification intent. Require a proportionate implementation and proof strategy only when the applicable workflow plan contract declares it; otherwise review the task's existing verification commands and evidence.
    - Coverage of design/discovery: every in-scope design component or discovery decision is mapped to at least one task or explicitly deferred/out of scope.
    - Parallelism-claim sanity: any parallel phase group or parallelism statement is consistent with declared file boundaries and dependency order.
+   - **Brief plan review** replaces the task-oriented items above with the brief section list: Goal; numbered Outcomes, each naming its intended evidence; Approach (optional `### Design`); Constraints and Out of Scope; Decisions with rationale and rejected alternatives; Known Unknowns, each with the phase that settles it; Delivery endpoint and authority; an empty `## Milestones` section; `## Phase pNN:` blocks with non-empty Intent and Exit evidence, a `**Provisional:**` value of `yes` or `no`, and a concrete first phase; Parallelism; Reviews (preserved rows); Implementation Complete; References. Stable, never-reused phase IDs in document order replace stable task IDs. There is no task requirement; `### Task` headings in a brief are a finding, because execution records belong in the journal. Check that every Outcome is reachable through some phase's Exit evidence and that any declared parallel group passes the independence test in brief contract section 6.
 
 6. **Necessary**
    - Evaluate whether the proposed approach materially serves the requested
@@ -307,7 +315,7 @@ Treat the artifact as a product deliverable. Verify it is:
 
 This step applies to **code reviews** only.
 
-If `design.md` is absent in quick/import/lite mode, mark design alignment as "not applicable (design artifact not present for mode)" and continue.
+If `design.md` is absent in quick/import/lite/brief mode, mark design alignment as "not applicable (design artifact not present for mode)" and continue. A brief's `### Design` subsection, when present, is the design source for this step.
 
 For each design decision relevant to scope:
 
@@ -550,6 +558,8 @@ Gate parsing contract: artifact-mode reviews, including reviews spawned by `oat
 
 For every artifact-mode code review, `oat_review_head_sha` is required and must be the full 40-character commit SHA at the head of the authoritative review range. Resolve it with `git rev-parse <authoritative-range-head>^{commit}`. An abbreviated SHA, symbolic ref, or range string is invalid. When the review narrowed, `oat_review_range`, `oat_prior_review_artifact`, and `oat_prior_review_head_sha` are also required; the prior head must likewise be a full 40-character SHA. These code-review fields are independent of the gate-only block and do not apply to artifact, analysis, or structured-output reviews.
 
+For a `brief` code review, also copy the supplied anchor record fields (`oat_review_requested_scope`, `oat_review_phase_ids`, `oat_review_base_sha`, `oat_review_scope_source`, and any supplied `oat_review_fallback_reason`, `oat_review_integration_commits`, and `oat_review_narrowed_from`) verbatim into frontmatter beside `oat_review_head_sha`, which is the aggregate head of the anchored range. Never infer them from commit messages or the current HEAD.
+
 For a narrowed review, do not restate requirements-coverage claims that this pass did not itself verify. Reference the prior artifact's coverage or mark inherited coverage rows as inherited so the union of passes remains auditable.
 
 For gate-originated artifacts, all six gate-only fields are required when the prompt supplies gate context. Copy the values exactly. Do not parse the provider command, infer values from the target id, or replace configured values with observed/self-reported identity. Any optional self-report belongs in review prose and is non-authoritative; the gate validates the copied frontmatter against its immutable configured invocation record before applying severity thresholds.

package/assets/bundle-metadata.json

@@ -1,4 +1,4 @@
 {
   "schemaVersion": 1,
-  "oatVersion": "0.3.17"
+  "oatVersion": "0.3.19"
 }

package/assets/docs/reference/cli-reference.md

@@ -100,12 +100,15 @@ Lifecycle](../workflows/backlog-and-planning/backlog-lifecycle.md).
 
 Notable commands introduced in the current CLI surface:
 
-- `oat project new <slug> [--mode spec-driven|quick|import|lite] --scope shared|local|synced [--force]` - create a
+- `oat project new <slug> [--mode spec-driven|quick|import|lite|brief] --scope shared|local|synced [--force]` - create a
   project in an explicit scope. `--mode` selects the workflow mode and therefore
   which artifacts are scaffolded; it defaults to `spec-driven`. Use `quick` for a
   bounded feature with clear requirements, `import` to normalize an externally
-  authored plan, and `lite` for a single-sitting change that scaffolds only
-  `plan.md`, `state.md`, and `implementation.md`. See
+  authored plan, `lite` for a single-sitting change that scaffolds only
+  `plan.md`, `state.md`, and `implementation.md`, and `brief` for one delivery
+  planned as a Project Brief, which scaffolds the `plan-brief` and
+  `implementation-brief` templates plus `references/research/`. Start brief
+  projects with `oat-project-brief`, which runs this command itself. See
   [Lifecycle](../workflows/projects/lifecycle.md) for the per-lane flow. Without
   `--scope`, creation uses
   `projects.defaultScope`, which defaults to `synced`. Project slugs are
@@ -190,7 +193,7 @@ Notable commands introduced in the current CLI surface:
 - `oat project status --field <path>` - print one arbitrary dot-path field from the same status payload, e.g. `project.workflowMode` or `project.timestamps.stateUpdated`. Missing/null fields print `null`; object and array fields print compact JSON.
 - `oat project status --project-path <path>` - read from a repo-relative or absolute project path instead of `.oat/config.local.json`'s active project pointer. Combine it with `--field` or `--shell` when a skill has already resolved the target project path.
 - `oat project status --shell NAME=path ...` - print shell-safe assignments for one or more fields from one status read, e.g. `WORKFLOW_MODE='quick'`. This is the preferred multi-field read API for skills. See [Writing Skills → Reading project state](../contributing/skills.md#reading-project-state) for examples and the `npx`-backed `oat` shim contract.
-- `oat project promote <project-path> --to quick [--json]` - promote an authored lite project to quick mode. The command derives `discovery.md` from the lite plan's Summary, Decisions, Assumptions, Out of Scope, and Validation Criteria; carries Product Behavior into Success Criteria and Technical Design into a carried-forward discovery section when those adaptive sections are present; preserves the original as `references/lite-plan.md`; and scaffolds a fresh quick `plan.md`. It refuses unsupported targets, non-lite or unreadable projects, an existing lite-plan reference, invalid authored sections, unresolved scope, unavailable templates, failed writes, or failed persistence. JSON output is `{ status: "promoted" | "refused", reason, files }`; `reason` is the stable categorical contract and refused results exit non-zero.
+- `oat project promote <project-path> --to quick [--json]` - promote an authored lite or brief project to quick mode. For a lite project, the command derives `discovery.md` from the lite plan's Summary, Decisions, Assumptions, Out of Scope, and Validation Criteria; carries Product Behavior into Success Criteria and Technical Design into a carried-forward discovery section when those adaptive sections are present; preserves the original as `references/lite-plan.md`; and scaffolds a fresh quick `plan.md`. For a brief project, it migrates each phase by state: accepted phases keep their completed execution records as quick tasks or get one synthesized `Accepted via phase evidence` task against the phase's `**Head:**`, active phases keep their completed records, and pending or provisional phases stay taskless and are listed in `oat_promotion_pending_phases` (quick plan readiness stays false until that list is empty); it renders the brief's sections into `discovery.md`, archives the original as `references/brief-archive.md`, and sets `oat_promoted_from: brief`. There is no reverse direction. It refuses unsupported targets, projects that are neither lite nor brief, unreadable projects, an existing lite-plan reference, invalid authored sections, an existing brief archive (`brief-archive-exists`), an extracted journal phase (`extracted-phases`), a brief with no parseable phases (`invalid-brief-plan`), an accepted brief phase with no completed record and no `**Head:**` anchor (`missing-phase-head`), unresolved scope, unavailable templates, failed writes, or failed persistence. JSON output is `{ status: "promoted" | "refused", reason, files }`, plus an optional `phases` array naming the refused phases when `reason` is `missing-phase-head`; `reason` is the stable categorical contract and refused results exit non-zero.
 - `oat template resolve <name> [--output <path>] [--json]` - resolve a template in repository (`<repo>/.oat/templates/`), user (`~/.oat/templates/`), then bundled order and report `name`, `found`, `tier` (`repository` | `user` | `bundle`), and `path`. `path` is set only for the repository and user tiers; it is `null` for the bundled tier, so callers never depend on a package-manager path. `<name>` accepts `plan` or `plan.md` and rejects path separators and `..`. `--output <path>` copies the resolved content to that file, replacing an existing file, and does not create missing parent directories; JSON output adds the absolute `output` path. A template missing from every tier exits 1 with `found: false`. Lifecycle skills use `--output` to copy their artifact templates, so a user-scope-only install works without a repository `.oat/templates/` directory.
 - `oat review latest --json` - find the newest review artifact by `oat_generated_at`, scanning the active or specified project's `reviews/` and `reviews/archived/` directories plus ad-hoc review locations. Same-time candidates use target priority, then lifecycle recency (`final` > higher phase/task > lower phase/task). The JSON contract returns `path`, `scope`, `generatedAt`, `kind` (`project` or `adhoc`), `archived`, and `actionable`, with `null` values when no review exists. Archived project reviews remain discoverable as history but return `actionable: false`.
 - `oat project list --json` - summary state for tracked projects under the configured projects root
@@ -200,7 +203,7 @@ Notable commands introduced in the current CLI surface:
 - `oat repo archive sync [project-name]` - hydrate archived project snapshots from the configured repo-scoped S3 archive into `.oat/projects/archived/`. The old `oat project archive sync` path remains as a deprecated shim.
 - `oat project dispatch record --event-file <json-file-or-dash>` - validate one generic dispatch record plus its namespaced OAT evidence event and print the result with `status: validated-only`. The command writes nothing; launches are recorded in the calling workflow's run record. Managed, effort-pinned Claude launches run it before launch: the input carries `claudeLaunch` with the real resolver result, generated definition, and proposed payload, plus `recordBase` and `event`. The command validates their agreement and derives the configured invocation fields; callers cannot copy those fields into `recordBase`. One validation run reports every violation across `claudeLaunch`, `recordBase`, and `event` in a single error message, one `stage path: message` line each; the `recordBase` cross-field rules run even when a required field is missing, checks that need a value that failed to parse are skipped and named on a final line, secret-shaped values and absolute paths are scrubbed from the message, and the exit code stays 1. A validated input per role is published at `.agents/skills/oat-dispatch-subagents/references/managed-claude-example.json`. The command validates evidence only — it never launches a provider. A `runtime-observation` event may carry either a finished `observation` or the provider `metadata` envelope (`provider`, `observedAt`, `entries`) to normalize, but not both. `entries` may be raw provider output: they are projected through the owning parser's allowlist, are never echoed in the output, and both forms have their `match` derived from the record's configured invocation rather than trusted from the caller, with the observation's `provider` bound to the record's. With `--json`, the result adds `runtimeIdentity` with separate `configured` and `observed` objects plus a `match` of `matching`, `mismatching`, `not-comparable`, or `null`; observation is corroboration only and never overrides configured invocation. Error output is redacted on a best-effort basis; absolute paths in identity fields are rejected outright, while some prose forms (colon-prefixed, URL routes) can survive. See [Evidence Layers](../workflows/advanced/evidence-layers.md).
 - `oat project dispatch canonical-role --role <name> --request-id <id> --skill-dir <dir> [--json]` - resolve a canonical role through the loaded, user (`$HOME/.agents`), and project (`<repo>/.agents`) tiers and print the `canonical-role-resolution` event that `oat project dispatch record` accepts unchanged: redacted `canonicalPath` and `selectedPath` in the form `<loaded|user|project>/agents/<name>.md`, the role's `contentDigest`, and `candidateMisses`. `--skill-dir` is required because the loaded tier is derived from the loaded skill's directory; a missing or invalid directory exits 1 with a redacted error. An unknown role prints `missing` evidence with its recovery commands. Read-only; the dependency is the `workflows` pack.
-- `oat project validate-plan --project-path <path>` - validates `oat_plan_parallel_groups` metadata in `plan.md`; exits non-zero on invalid. Lite plans must contain exactly one phase, declare no parallel groups, and give every Validation Criteria bullet either a backticked command or a `manual:` instruction. See [Implementation Execution](../workflows/projects/execution/implementation-execution.md#parallel-phase-groups).
+- `oat project validate-plan --project-path <path>` - validates `oat_plan_parallel_groups` metadata in `plan.md`; exits non-zero on invalid. Lite plans must contain exactly one phase, declare no parallel groups, and give every Validation Criteria bullet either a backticked command or a `manual:` instruction. Brief plans (`oat_workflow_mode: brief`) are validated with the brief profile: phases need non-empty `**Intent:**` and `**Exit evidence:**`, a `**Provisional:**` value of `yes` or `no`, unique IDs, and a concrete first phase; `### Task` headings in a brief are reported as a warning, and taskless parallel groups are valid. See [Implementation Execution](../workflows/projects/execution/implementation-execution.md#parallel-phase-groups).
 - `oat project log append|check|synthesize|rollup` - manage the optional append-only project observation log: append validated judgment or structural entries, inspect grammar and synthesis status, complete end-of-run synthesis, and roll observations into `summary.md` plus the configured repository ledger. See [Project Log](../workflows/projects/execution/project-log.md).
 - `oat project set-mode` — deprecated no-op. Execution mode is no longer user-selectable; emits a deprecation warning and preserves the `--json` contract.
 - `oat gate review <prompt...>` - run a stateful, headless OAT review through the target registry, parse the produced review artifact, and exit nonzero for configured blocking findings. `--timeout-ms <milliseconds>` overrides target, `workflow.gateTimeouts`, environment, and scope defaults; accepted values are 1,000–14,400,000. Final/phase/range code reviews and artifact reviews default to 30 minutes, while task code reviews default to 15 minutes. With `--json`, the result envelope on exit is the canonical completion signal: `status` is `ok` | `blocked` | `review_failed` | `artifact_missing` | `artifact_validation_failed` | `targeting_correlation_failed`, alongside `runId`, `generatedAt`, and `artifactPath` when available. `artifact_missing` means an accepted child exited cleanly without an artifact; fix synchronous review/artifact completion and start a new run, without review-receive or same-run remediation. For `targeting_correlation_failed`, correct the project declaration or artifact routing and start a new run; do not run review-receive even if an artifact path is present. For `artifact_validation_failed`, correct the artifact and rerun the gate until it revalidates as `ok` or `blocked`. Invoke `oat-project-review-receive` only when all three conditions hold: `status` is `ok` or `blocked`, `receiveEligible` is `true`, and `handoff` is non-null. `review_failed` may include structured `refusal`, `noOutputProduced`, and metadata-only `activityEvidence`; these diagnostic fields never make a run receive-eligible. After a timeout, a validated run-correlated artifact returns the ordinary `ok` or `blocked` envelope with additive `lateCompletion: true`. When post-selection work fails after the reviewer already committed a run-correlated artifact, the gate re-validates that selected snapshot through the same eligibility path rather than re-parsing whatever the path now holds, never re-dispatching, and returns the ordinary `ok` or `blocked` envelope with additive `postSelectionRecovery: true`; the artifact must still be present and unchanged for re-validation to succeed. When nothing recovers, `review_failed` names the failing sub-step in `postSelection.step` and its cause in `postSelection.code`. Duplicate run-ID matches or a changed artifact with a mismatched run ID retain `targeting_correlation_failed` and `receiveEligible: false`. Orchestrators should read the structured result rather than poll the filesystem. See [Workflow Gates](../workflows/advanced/workflow-gates.md).

package/assets/docs/reference/oat-directory-structure.md

@@ -322,6 +322,7 @@ Not all workflow modes require every artifact:
 - `quick`: discovery + plan + implementation (spec/design optional)
 - `import`: imported plan + implementation (spec/design optional)
 - `lite`: single-phase plan + implementation (summary/documentation optional at closeout)
+- `brief`: Project Brief in `plan.md` + per-phase journal in `implementation.md` (`references/research/` scaffolded; no discovery, spec, or design)
 
 ## `.oat/repo/` structure
 

package/assets/docs/reference/project-artifacts.md

@@ -50,7 +50,7 @@ archive metadata own terminal reachability and retry identity.
 
 Mode-sensitive notes:
 
-- `state.md` includes workflow mode metadata (`spec-driven`, `quick`, `import`, `lite`) for routing.
+- `state.md` includes workflow mode metadata (`spec-driven`, `quick`, `import`, `lite`, `brief`) for routing.
 - `plan.md` remains the canonical execution artifact across all modes.
 
 | Mode          | Core authored artifacts                                                                                                                | Optional artifacts                         |
@@ -59,6 +59,7 @@ Mode-sensitive notes:
 | `quick`       | `discovery.md`, `plan.md`                                                                                                              | Lightweight `design.md`, `spec.md`         |
 | `import`      | `references/imported-plan.md`, `plan.md`                                                                                               | `spec.md`, `design.md`                     |
 | `lite`        | Single-phase `plan.md` with Summary, Decisions, Assumptions, Out of Scope, Validation Criteria, and an explicit adaptive content shape | `summary.md` and documentation at closeout |
+| `brief`       | `plan.md` as a Project Brief (phases with Intent and Exit evidence) and `implementation.md` as the per-phase journal                   | `references/research/`, `project-log.md`   |
 
 Every Lite plan keeps Summary, Decisions, Assumptions, Out of Scope, and
 Validation Criteria. User-visible changes add numbered, testable Product
@@ -75,6 +76,21 @@ implementation-then-regression, static/build, or manual/visual. Static or build
 checks alone fit only changes that cannot affect runtime behavior; every
 behavioral change needs evidence that fails without the change.
 
+In brief mode, `plan.md` is the Project Brief: Goal, numbered Outcomes (each
+naming its intended evidence), Approach with an optional `### Design`,
+Constraints and Out of Scope, Decisions, Known Unknowns, Delivery endpoint and
+authority, an empty `## Milestones` section reserved for goal mode, and
+`## Phase pNN:` blocks with `**Intent:**`, `**Exit evidence:**`, and
+`**Provisional:**` lines instead of tasks. `implementation.md` is the
+per-phase journal: each phase section carries exact `**Status:**`,
+`**Base:**`, `**Head:**`, and `**Executor:**` marker lines, followed by
+`### Task pNN-tNN` execution records opened as work happens. Progress counts
+phase-units, and `**Status:** completed` under a phase heading is what accepts
+it. The journal's Final Summary adds an `**Outcomes audit:**` block with one
+line per numbered Outcome. When a brief artifact gate is configured,
+`state.md` records its outcome as `oat_brief_gate`, with the same core fields
+as `oat_quick_start_gate`.
+
 ## Blockers in state.md
 
 `oat_blockers` accepts legacy reason strings and structured workflow records:

package/assets/docs/reference/project-state-machine.md

@@ -17,8 +17,8 @@ This page is the compact contract for how project lifecycle state and review sta
 
 === "Diagram"
 
-    ![Project state machine: discovery, spec, design, plan and implementation phases, then PR open and complete; a review loop returns to implementation, a revise loop runs from PR open and back, and lite enters at planning](/diagrams/project-state-machine-light.svg)
-    ![Project state machine: discovery, spec, design, plan and implementation phases, then PR open and complete; a review loop returns to implementation, a revise loop runs from PR open and back, and lite enters at planning](/diagrams/project-state-machine-dark.svg)
+    ![Project state machine: discovery, spec, design, plan and implementation phases, then PR open and complete; a review loop returns to implementation, a revise loop runs from PR open and back, and lite and brief enter at planning](/diagrams/project-state-machine-light.svg)
+    ![Project state machine: discovery, spec, design, plan and implementation phases, then PR open and complete; a review loop returns to implementation, a revise loop runs from PR open and back, and lite and brief enter at planning](/diagrams/project-state-machine-dark.svg)
 
 === "Mermaid source"
 
@@ -41,10 +41,11 @@ This page is the compact contract for how project lifecycle state and review sta
       PASSED --> I
 
       LITE["Lite: batched interview\n(no discovery/spec/design)"] -. entry point .-> P
+      BRIEF["Brief: alignment interview\n(one Project Brief)"] -. entry point .-> P
     ```
 
-The solid chain is the spec-driven progression. Lite enters at **Plan in
-progress** and never sets `oat_phase` to `discovery`, `spec`, or `design`;
+The solid chain is the spec-driven progression. Lite and brief enter at **Plan
+in progress** and never set `oat_phase` to `discovery`, `spec`, or `design`;
 quick and import projects also skip part of the leading chain.
 
 ## Phase status values
@@ -92,6 +93,20 @@ project promote <project-path> --to quick`, which flips `oat_workflow_mode` to
 `quick` and sets `oat_phase: discovery` with `oat_phase_status: complete`. See
 [Lifecycle](../workflows/projects/lifecycle.md#promoting-a-lite-project-to-quick).
 
+Brief progression:
+
+1. Plan in progress (`oat_workflow_mode: brief`, `oat_phase: plan`) — `oat-project-brief` owns the interview, the artifact review, any configured gate, and the single approval
+2. Ready for implement (`plan.md` complete and pointing to `oat-project-implement`)
+3. Implement in progress — progress counts phase-units; a phase is accepted only by `**Status:** completed` under its heading in `implementation.md`
+4. Implement complete (final review passed). While any phase-unit is provisional or unaccepted, the router's brief-unit guard sends the project back to `oat-project-implement` ("Incomplete phase-units remain in the active scope") before every later check
+5. PR open (`pr_open`) through the same post-implementation sequence as quick
+6. Complete
+
+A brief project can move to the quick chain with `oat project promote
+<project-path> --to quick`; quick plan readiness stays false while
+`oat_promotion_pending_phases` lists phases that still need tasks. See
+[Lifecycle](../workflows/projects/lifecycle.md#promoting-a-brief-project-to-quick).
+
 ## Review progression
 
 In `plan.md` Reviews table:

package/assets/docs/skills/brainstorm.md

@@ -47,7 +47,8 @@ instead). Saving a brainstorming reference file under the active project also
 commits or pushes that file. Promoting to a new project runs
 `oat project new`, which scaffolds the project and makes it your active
 project, and then writes a completed `discovery.md` (or, for a lite project,
-fills in its `plan.md`). Capturing a new idea also sets it as your active
+fills in its `plan.md`; for a brief project, writes a research note under
+`references/research/` and leaves the brief to `oat-project-brief`). Capturing a new idea also sets it as your active
 idea in local OAT config. Each destination is confirmed before anything is
 written.
 

package/assets/docs/skills/index.md

@@ -307,6 +307,7 @@ Visibility reports source metadata: “user” is `user-invocable` and “model
 
 | Skill                                                                                                    | Description                                                                                                                                                                                                         | Visibility                       | Needs an active project? |
 | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ------------------------ |
+| [`oat-project-brief`](../workflows/projects/planning/starting-projects.md#oat-project-brief)             | Use when one delivery needs a design-aligned interview, a single approved Project Brief with phases of intent and exit evidence instead of planned tasks, and resumable OAT implementation.                         | user: true; model disabled: true | No                       |
 | [`oat-project-capture`](../workflows/projects/planning/starting-projects.md#oat-project-capture)         | Use when work happened outside the OAT project workflow and needs retroactive project tracking. Creates a full project from an existing branch and conversation context.                                            | user: true; model disabled: true | No                       |
 | [`oat-project-import-plan`](../workflows/projects/planning/starting-projects.md#oat-project-import-plan) | Use when you have an external markdown plan to execute with OAT. Preserves the source plan and normalizes it into canonical plan.md format.                                                                         | user: true; model disabled: true | No                       |
 | [`oat-project-lite`](../workflows/projects/planning/starting-projects.md#oat-project-lite)               | Use when a single-sitting change needs a critical interview, an approved single-phase plan, and resumable OAT implementation with minimal ceremony.                                                                 | user: true; model disabled: true | No                       |

package/assets/docs/workflows/advanced/autonomy.md

@@ -336,11 +336,19 @@ must resolve before the run makes any change.
 and a dispatch policy is already configured. You authorize the bounded
 resumable-export goal through a final PR without ordinary mid-run approval
 pauses. Autonomous entry chooses
-lite, quick, or spec-driven review density from the actual uncertainty and
+lite, brief, quick, or spec-driven review density from the actual uncertainty and
 invokes its owning creation skill. If an export-filter project is already
 active, the second example explicitly resumes its earliest incomplete step
 instead of replaying finished phases.
 
+When autonomous entry selects brief, `oat-project-brief` derives the project
+name and description only from the explicit goal and stops if it is not
+substantive. The brief's single approval resolves autonomously under
+`BRIEF-11`: the reviewed brief is approved and the approval line records the
+autonomous run, while contradictory or materially incomplete outcomes stop at
+a product-judgment boundary. A brief records no HiLL checkpoints unless it
+lists phases explicitly.
+
 **Expected output:** Session-only autonomy signals, persisted lifecycle
 progress, reviewed task commits, and project-local execution learnings. Existing
 projects retain their mode. A successful run reports the actual final PR and

package/assets/docs/workflows/advanced/workflow-gates.md

@@ -98,7 +98,7 @@ string, and the lifecycle executes it unchanged; OAT does not inject, reorder,
 or rewrite its shell arguments.
 
 `oat-project-plan`, `oat-project-implement`, `oat-project-quick-start`,
-`oat-project-lite`, and `oat-project-import-plan` are currently gate-aware. Gate awareness is declared
+`oat-project-lite`, `oat-project-brief`, and `oat-project-import-plan` are currently gate-aware. Gate awareness is declared
 in skill frontmatter with `oat_gateable: true`, and
 `oat internal validate-oat-skills` warns when config targets a missing or
 non-gateable skill.
@@ -249,7 +249,7 @@ for it.
 
 ### Gate approval records
 
-Two lifecycle gates persist their outcome in project `state.md` with a shared
+Three lifecycle gates persist their outcome in project `state.md` with a shared
 five-field core:
 
 | Field                | Meaning                                                                                        |
@@ -277,8 +277,13 @@ carries exactly the core:
 - a gate that is not configured writes no record (implement writes
   `allowed/no_gate` instead).
 
-`oat-project-next` and `oat-project-progress` report the quick-start record as
-recorded: status, disposition, `decided_at`, and `config_fingerprint` as
+`oat_brief_gate`, written by `oat-project-brief` for its configured gate on the
+committed brief, carries exactly the same core with the same outcome rules. It
+is provenance only: no route reads it back, and the brief's single approval
+still follows the gate.
+
+`oat-project-next` and `oat-project-progress` report the quick-start record
+(and `oat-project-progress` the brief record) as recorded: status, disposition, `decided_at`, and `config_fingerprint` as
 provenance, or `malformed` when the fields do not form a valid record. They do
 not recompute the fingerprint, because no CLI emits a canonical one for the
 quick-start gate, and they never route on the record: quick plan readiness
@@ -840,7 +845,7 @@ oat gate set oat-project-implement \
 ```
 
 Apply the same command shape to `oat-project-plan`,
-`oat-project-quick-start`, `oat-project-lite`, and `oat-project-import-plan` when those lifecycle
+`oat-project-quick-start`, `oat-project-lite`, `oat-project-brief`, and `oat-project-import-plan` when those lifecycle
 skills have configured review gates. Do not add `--target`; explicit targets
 remain manual/debug or deliberate local/user-specific overrides.
 
@@ -1234,7 +1239,7 @@ as a failed gate, never as a pass.
 
 How the skills handle that case differs:
 
-- `oat-project-implement` and `oat-project-lite` keep it blocked whatever
+- `oat-project-implement`, `oat-project-lite`, and `oat-project-brief` keep it blocked whatever
   `onFailure` says, so even a `warn` gate does not let them continue.
 - `oat-project-plan`, `oat-project-quick-start`, and `oat-project-import-plan`
   apply your `onFailure` setting to any failed gate run, including one where no

package/assets/docs/workflows/approvals-and-automation.md

@@ -15,14 +15,15 @@ to the detail.
 A HiLL (human-in-the-loop lifecycle) checkpoint is a point where the agent
 stops and waits for a person to approve before it continues.
 
-| Mode           | A person approves before code is written                                                                                                                                                   | Pauses during implementation                                                    | Reviews that run automatically                        | At the end                                                                   | Never                  |
-| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------- | ---------------------- |
-| No project     | You direct each step yourself                                                                                                                                                              | None                                                                            | None; run `oat-review-provide` when you want a review | OAT opens no pull request                                                    | Not applicable         |
-| Lite           | Once: the requirements and the single-phase plan                                                                                                                                           | None                                                                            | Plan review, phase review, final review               | Opens a pull request by itself; no setting removes this step                 | Merges a pull request  |
-| Quick          | You confirm the requirements (or the lightweight design). No plan-approval prompt: the plan is marked ready after an automatic review                                                      | First run lists the phases and asks where to stop; suggested: after every phase | Plan review, a review after every phase, final review | Opens a pull request by itself only if `workflow.postImplementSequence` asks | Merges a pull request  |
-| Spec-driven    | Discovery, then the requirements and design. Planning asks you in chat to confirm the task breakdown, but no plan approval is recorded; the plan is marked ready after an automatic review | Same as quick                                                                   | Same as quick                                         | Same as quick                                                                | Merges a pull request  |
-| Imported plan  | No approval step; OAT normalizes your plan and reviews it automatically                                                                                                                    | Same as quick                                                                   | Same as quick                                         | Same as quick                                                                | Merges a pull request  |
-| Autonomous run | None; it answers its own questions and stops only at defined boundaries                                                                                                                    | None; it approves the final checkpoint itself after a passing final review      | All of the above, plus a review at every checkpoint   | Opens a pull request by default                                              | Merges or force-pushes |
+| Mode           | A person approves before code is written                                                                                                                                                   | Pauses during implementation                                                       | Reviews that run automatically                         | At the end                                                                   | Never                  |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------- | ---------------------- |
+| No project     | You direct each step yourself                                                                                                                                                              | None                                                                               | None; run `oat-review-provide` when you want a review  | OAT opens no pull request                                                    | Not applicable         |
+| Lite           | Once: the requirements and the single-phase plan                                                                                                                                           | None                                                                               | Plan review, phase review, final review                | Opens a pull request by itself; no setting removes this step                 | Merges a pull request  |
+| Brief          | Once: the reviewed Project Brief, after you have agreed its design in the interview                                                                                                        | None by default; a pause happens only for a phase listed in `oat_plan_hill_phases` | Brief review, a review after every phase, final review | Same as quick                                                                | Merges a pull request  |
+| Quick          | You confirm the requirements (or the lightweight design). No plan-approval prompt: the plan is marked ready after an automatic review                                                      | First run lists the phases and asks where to stop; suggested: after every phase    | Plan review, a review after every phase, final review  | Opens a pull request by itself only if `workflow.postImplementSequence` asks | Merges a pull request  |
+| Spec-driven    | Discovery, then the requirements and design. Planning asks you in chat to confirm the task breakdown, but no plan approval is recorded; the plan is marked ready after an automatic review | Same as quick                                                                      | Same as quick                                          | Same as quick                                                                | Merges a pull request  |
+| Imported plan  | No approval step; OAT normalizes your plan and reviews it automatically                                                                                                                    | Same as quick                                                                      | Same as quick                                          | Same as quick                                                                | Merges a pull request  |
+| Autonomous run | None; it answers its own questions and stops only at defined boundaries                                                                                                                    | None; it approves the final checkpoint itself after a passing final review         | All of the above, plus a review at every checkpoint    | Opens a pull request by default                                              | Merges or force-pushes |
 
 Phase reviews need no person. The final review always runs, but an interactive
 run first asks how to run it unless `workflow.reviewExecutionModel` is set. If
@@ -46,6 +47,10 @@ What does and does not give a person a say on the plan:
 
 - **Lite:** its single approval covers the requirements and the plan, and the
   decision is written into `plan.md`.
+- **Brief:** its single approval covers the reviewed Project Brief. The
+  interview reaches explicit design alignment first, so approval confirms a
+  design you already agreed to; the artifact review and any configured
+  `oat-project-brief` gate run on the committed brief before you approve.
 - **Spec-driven:** `/oat-project-plan` asks "Does this breakdown make sense? Any
   tasks missing?" in the chat and revises until you confirm. That confirmation
   is not recorded as an approval, and the automatic review that follows can

package/assets/docs/workflows/choose-workflow.md

@@ -1,6 +1,6 @@
 ---
 title: Choose a Workflow
-description: Choose how to run tracked, resumable work in OAT, from no project to lite, quick, spec-driven, or imported projects, and what each mode does at the end.
+description: Choose how to run tracked, resumable work in OAT, from no project to lite, brief, quick, spec-driven, or imported projects, and what each mode does at the end.
 ---
 
 # Choose a Workflow
@@ -48,6 +48,7 @@ Stay with direct CLI usage when:
 
 - 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
 - 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
@@ -78,13 +79,14 @@ 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.
 
-| Mode        | Start it with                                   | Choose it when                                                                 | What you give up                                                                                                | At the end                                                                                                                  |
-| ----------- | ----------------------------------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| No project  | No skill; ask your agent or run CLI commands    | The work is small, or is just provider sync or a single CLI command            | Resuming later, a tracked plan, and lifecycle reviews. Ad-hoc reviews still work                                | OAT pushes nothing and opens no pull request                                                                                |
-| Lite        | `/oat-project-lite`                             | The change fits in one sitting and the outcome is clear                        | Discovery and design documents, multiple phases, and approval pauses between phases. You approve one plan, once | Always pushes your current branch and opens a pull request by itself; no setting removes this step                          |
-| Quick       | `/oat-project-quick-start`                      | The work is bounded and the requirements are clear                             | A formal requirements document (`spec.md`). Design is optional                                                  | Pushes your branch and opens a pull request only when `workflow.postImplementSequence` asks for it, or in an autonomous run |
-| Spec-driven | `/oat-project-new`                              | The requirements are unclear, or the change cuts across many parts of the code | Speed: you approve discovery and design before any planning or code                                             | Same as quick                                                                                                               |
-| Import      | `/oat-project-import-plan` with the plan's path | A plan already exists in another tool or document                              | OAT's own discovery and design steps                                                                            | Same as quick                                                                                                               |
+| Mode        | Start it with                                   | Choose it when                                                                  | What you give up                                                                                                                     | At the end                                                                                                                  |
+| ----------- | ----------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
+| No project  | No skill; ask your agent or run CLI commands    | The work is small, or is just provider sync or a single CLI command             | Resuming later, a tracked plan, and lifecycle reviews. Ad-hoc reviews still work                                                     | OAT pushes nothing and opens no pull request                                                                                |
+| Lite        | `/oat-project-lite`                             | The change fits in one sitting and the outcome is clear                         | Discovery and design documents, multiple phases, and approval pauses between phases. You approve one plan, once                      | Always pushes your current branch and opens a pull request by itself; no setting removes this step                          |
+| Brief       | `/oat-project-brief`                            | The work is one delivery whose outcome and design you can agree in conversation | Discovery and design documents and an up-front task list. Phases state intent and exit evidence; tasks are recorded as the work runs | Same as quick                                                                                                               |
+| Quick       | `/oat-project-quick-start`                      | The work is bounded and the requirements are clear                              | A formal requirements document (`spec.md`). Design is optional                                                                       | Pushes your branch and opens a pull request only when `workflow.postImplementSequence` asks for it, or in an autonomous run |
+| Spec-driven | `/oat-project-new`                              | The requirements are unclear, or the change cuts across many parts of the code  | Speed: you approve discovery and design before any planning or code                                                                  | Same as quick                                                                                                               |
+| Import      | `/oat-project-import-plan` with the plan's path | A plan already exists in another tool or document                               | OAT's own discovery and design steps                                                                                                 | Same as quick                                                                                                               |
 
 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,
@@ -105,6 +107,12 @@ is what holds the planning conversation, so start with the skill.
   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 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