@open-agent-toolkit/cli 0.3.18 → 0.3.20

package/assets/docs/workflows/projects/lifecycle.md

@@ -1,6 +1,6 @@
 ---
 title: Lifecycle
-description: 'End-to-end phase flow from discovery through completion: spec-driven, quick, lite, and import paths.'
+description: 'End-to-end phase flow from discovery through completion: spec-driven, quick, lite, brief, goal, and import paths.'
 ---
 
 # Lifecycle
@@ -29,9 +29,9 @@ For a one-page view of where people approve and what runs automatically in each
 
 ## Quick Look
 
-- What it does: explains the end-to-end lifecycle for tracked OAT projects, including alternate quick, lite, and import lanes.
+- What it does: explains the end-to-end lifecycle for tracked OAT projects, including alternate quick, lite, brief, goal, and import lanes.
 - When to use it: when you need the actual project execution model, not just a high-level overview of workflow mode.
-- Primary entry points: `oat-project-new`, `oat-project-quick-start`, `oat-project-lite`, `oat-project-import-plan`, `oat-project-implement`
+- Primary entry points: `oat-project-new`, `oat-project-quick-start`, `oat-project-lite`, `oat-project-brief`, `oat-project-goal`, `oat-project-import-plan`, `oat-project-implement`
 
 ## Lifecycle Map
 
@@ -51,9 +51,10 @@ For a one-page view of where people approve and what runs automatically in each
       DOC --> C["Complete"]
     ```
 
-This map shows the spec-driven default. The quick, lite, import, and capture
-lanes each skip part of it — see [Lane diagrams](#lane-diagrams) below. Lite in
-particular has no discovery, spec, or design step at all.
+This map shows the spec-driven default. The quick, lite, brief, goal, import,
+and capture lanes each skip part of it — see [Lane diagrams](#lane-diagrams)
+below. Lite, brief, and goal in particular have no discovery, spec, or design
+step at all.
 
 ## Post-implementation flow
 
@@ -337,6 +338,24 @@ See [Implementation Execution](execution/implementation-execution.md) for the fu
 3. Pass the mandatory final review, then route directly to `oat-project-pr-final`
 4. Optional `oat project promote <project-path> --to quick` when the work no longer fits one sitting
 
+### Brief lane steps
+
+1. `oat-project-brief` runs a design-aligned interview in readiness rounds, writes one Project Brief in `plan.md` (Goal, numbered Outcomes, Approach, Constraints and Out of Scope, Decisions, Known Unknowns, Delivery endpoint and authority, and `## Phase pNN:` blocks with Intent and Exit evidence), commits it, runs the independent artifact review and any configured `oat-project-brief` gate, and asks for one approval
+2. Implement: `oat-project-implement` executes one phase-unit at a time (or a declared parallel group), opening `### Task pNN-tNN` execution records in `implementation.md` as work happens and recording each phase's `**Base:**` and `**Head:**` anchors
+3. A fresh independent review of each phase on its anchored range, then the final review, whose scope comes from the anchors; completion is audited against the brief's Outcomes
+4. `oat-project-pr-final`, through the same post-implementation sequence as quick
+5. Optional `oat project promote <project-path> --to quick` when you want a maintained task plan instead
+
+### Goal lane steps
+
+1. `oat-project-goal` runs the brief interview for the whole outcome, writes one Project Brief whose `## Milestones` table assigns every phase to exactly one milestone (`| m01 | p01, p02 |`), runs the artifact review and any configured `oat-project-goal` gate, asks for one approval, and activates the first milestone
+2. Implement: `oat-project-implement` executes the active milestone's phase-units as brief does, then runs the milestone closeout, whose `exit` gate runs before the integrated review
+3. `oat-project-review-provide` reviews the milestone as `code mNN: <ordered phases>`; `oat-project-review-receive` moves a clean review to delivery
+4. `oat-project-pr-progress` checks the evidence with `oat project delivery check`, registers the delivery (`dNN`) in `oat_deliveries`, and opens its pull request
+5. `oat-project-goal` re-aligns at `delivered`: it refreshes delivery observations, captures learnings, amends the brief with the next milestone, takes the amendment through review and approval, and activates it once the previous delivery reaches its agreed endpoint
+6. Repeat from step 2 per milestone; when the user declares the goal met, `oat-project-goal` records an exhaustive outcome audit, `oat-project-pr-final` registers terminal deliveries for any accepted phases no delivery covers, and `oat-project-complete` closes out once every accepted phase is covered
+7. Optional `oat project promote <project-path> --to quick` at a settled delivery boundary
+
 ### Import lane steps
 
 1. `oat-project-import-plan` (checks inherited git state before import scaffolding so sync-generated or unrelated dirty files do not silently roll into project bookkeeping)
@@ -495,6 +514,150 @@ sections, an unresolved scope, or an unreadable template each return a stable
 categorical `reason` and exit non-zero. See
 [CLI Reference](../../reference/cli-reference.md) for the full refusal contract.
 
+### Brief lane
+
+=== "Diagram"
+
+    ![Brief lane: a design-aligned interview, one reviewed and approved Project Brief, phase-units executed with execution records and anchors, a fresh review per phase, final review audited against Outcomes, and PR, with promotion to quick when a task plan is wanted](/diagrams/project-lifecycle-8-brief-lane-light.svg)
+    ![Brief lane: a design-aligned interview, one reviewed and approved Project Brief, phase-units executed with execution records and anchors, a fresh review per phase, final review audited against Outcomes, and PR, with promotion to quick when a task plan is wanted](/diagrams/project-lifecycle-8-brief-lane-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    flowchart TD
+      A["Alignment interview\n(readiness rounds)"] --> B["Project Brief\n(review, gate, one approval)"]
+      B --> I["Phase-units\n(oat-project-implement)"]
+      I --> PR["Per-phase review\n(anchored range)"]
+      PR -->|Next phase| I
+      PR --> F["Final review\n(audited against Outcomes)"]
+      F --> P["PR (oat-project-pr-final)"]
+      B -->|Task plan wanted| Q["Promote to Quick"]
+    ```
+
+A brief project has one authored artifact: the Project Brief in `plan.md`.
+Each `## Phase pNN:` block is one **phase-unit** with `**Intent:**`,
+`**Exit evidence:**`, and `**Provisional:**` lines; only the next phase must
+be concrete, and the agent may add, split, or reorder phases inside the
+approved outcomes, constraints, and authority. Progress counts phase-units, and
+a phase counts as complete only when the root writes `**Status:** completed`
+under it in `implementation.md` after its review and any selected gate settle.
+Tasks are execution records written as work happens, never a plan, so they
+never change progress totals.
+
+Each phase records `**Base:**` before work starts and `**Head:**` when its work
+ends. Reviews take their range from those anchors rather than from commit
+messages; invalid or contradictory anchors stop and route to
+`oat-project-reconcile`. A fix after a later phase has started becomes an
+appended `p-revN` revision phase. The shared rules live in the bundled brief
+contract (`oat-project-brief/references/brief-contract.md`).
+
+### Promoting a brief project to quick
+
+`oat project promote <project-path> --to quick` converts a brief in place, and
+there is no reverse direction. Accepted phases keep their completed execution
+records as quick tasks (or get one synthesized `Accepted via phase evidence`
+task against the phase head), active phases keep their completed records, and
+pending or provisional phases stay taskless. The command lists the phases that
+still need tasks in `oat_promotion_pending_phases`, and quick plan readiness
+stays false until `oat-project-quick-start` authors them. The brief's
+sections are rendered into `discovery.md` and the original is archived to
+`references/brief-archive.md`.
+
+Promotion writes nothing and refuses with a categorical reason when
+`references/brief-archive.md` already exists (`brief-archive-exists`), a
+journal phase is `extracted` (`extracted-phases`), the brief has no parseable
+phases (`invalid-brief-plan`), or an accepted phase has neither a completed
+record nor a `**Head:**` anchor to synthesize from (`missing-phase-head`, which
+lists the refused phases).
+
+### Goal lane
+
+=== "Diagram"
+
+    ![Goal lane: an alignment interview and one reviewed Project Brief with a Milestones table, then per milestone activation, phase-units with per-phase reviews, milestone closeout with the exit gate, the integrated review, a registered delivery through pr-progress, and re-alignment that loops to the next milestone once the previous delivery reaches its endpoint; finally the terminal declaration with an exhaustive outcome audit and coverage closeout, with promotion to quick at a settled delivery boundary](/diagrams/project-lifecycle-9-goal-lane-light.svg)
+    ![Goal lane: an alignment interview and one reviewed Project Brief with a Milestones table, then per milestone activation, phase-units with per-phase reviews, milestone closeout with the exit gate, the integrated review, a registered delivery through pr-progress, and re-alignment that loops to the next milestone once the previous delivery reaches its endpoint; finally the terminal declaration with an exhaustive outcome audit and coverage closeout, with promotion to quick at a settled delivery boundary](/diagrams/project-lifecycle-9-goal-lane-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    flowchart TD
+      A["Alignment interview\n(whole outcome, milestone split)"] --> B["Project Brief + Milestones\n(review, gate, one approval)"]
+      B --> M["Activate milestone mNN\n(oat-project-goal)"]
+      M --> I["Phase-units\n(implement, per-phase reviews)"]
+      I --> X["Milestone closeout\n(exit gate before the review)"]
+      X --> R["Integrated review\n(code mNN: ordered phases)"]
+      R --> D["Delivery dNN\n(oat-project-pr-progress)"]
+      D --> RA["Re-alignment\n(learnings, amendment, approval)"]
+      RA -->|Next milestone at endpoint| M
+      RA --> T["Terminal declaration\n(exhaustive outcome audit)"]
+      T --> C["Coverage closeout\n(pr-final for uncovered, complete)"]
+      D -->|Settled boundary| Q["Promote to Quick"]
+    ```
+
+A goal project is a brief project delivered in milestones. The Project Brief
+carries a `## Milestones` table (`| Milestone | Phases |`) in which every
+phase, including appended `p-revN` revision phases, belongs to exactly one
+milestone; `oat project validate-plan` reports membership errors as `goal-`
+codes. Each milestone is approved through its own `plan` gate carrier in
+`state.md` (`oat_milestone_gates.mNN.plan`): the first approval also marks
+`plan.md` complete, and every later amendment is approved only by the next
+milestone's carrier.
+
+**Milestone delivery.** For goal the end of the brief ladder is reordered: the
+milestone's `exit` gate runs at closeout before the integrated review, and
+queued fixes invalidate both, so the gate runs again before the next review.
+The integrated review names its milestone (or delivery) and the exact ordered
+phase set, for example `code m01: p01, p02, p-rev1`; that set is never derived
+from a first–last range. `oat-project-pr-progress` registers a delivery only
+when `oat project delivery check --subject <mNN|dNN>` reports `status: ok`,
+writing the `oat_deliveries` entry (`registering`) before it creates the pull
+request so an interrupted run resumes by `gh pr list` instead of opening a
+duplicate.
+
+**Freshness.** Evidence keeps the revision actually reviewed. Commits after it
+count as bookkeeping only when they touch the project's tracking files in
+permitted ways (routing, progress, evidence, project-log appends); a code
+change, an edit to approved brief content such as Outcomes or a phase's Intent,
+or a substantive change followed by its revert stales the delivery.
+`oat project delivery refresh` observes each member pull request with
+`gh pr view` and records staleness; it never writes milestone status or
+recovery. Because the project branch is the delivery's head branch, do not
+push a brief amendment while that delivery is still open.
+
+**Recovery.** Stale evidence on the active milestone's delivery returns it to
+`reviewing`. Fixes or inline feedback for an older milestone open an
+`oat_goal_recovery` record targeting that milestone and delivery, scheduling a
+`p-revN` phase in its row, while the active milestone, its status and the
+execution pointer stay untouched.
+
+**Re-alignment and the end.** At `delivered`, `oat-project-goal` refreshes the
+observations, writes one learnings entry, amends the brief with the next
+milestone, and runs the review, gate and approval for the amendment; it may do
+all of that while a `merged` endpoint is pending, but it activates the next
+milestone only once refresh observes the previous delivery at its endpoint.
+When the user declares the goal met, the declaration is recorded in
+`implementation.md` and `state.md` gets `oat_goal_status: declared_met` and an
+exhaustive outcome audit: every phase `accepted`, `extracted`, `deferred` or
+`retired`, every numbered outcome bound to its exact text. Terminal closeout
+requires the declaration, the audit and delivery coverage of every accepted
+phase; `oat-project-pr-final` registers one terminal delivery per milestone
+that still has uncovered phases, all sharing the head branch's pull request.
+`oat-project-complete` then opens no further pull request, even with
+`workflow.createPrOnComplete: true`, because the deliveries already cover the
+work.
+
+### Promoting a goal project to quick
+
+`oat project promote <project-path> --to quick` accepts a goal project only at
+a settled delivery boundary: the active milestone is `delivered`, every
+registry entry is `at_endpoint` or `superseded`, and no recovery is pending.
+It otherwise refuses without writing, with `goal-milestone-active`,
+`goal-recovery-pending`, or `goal-delivery-unsettled` (which lists the open or
+`registering` deliveries, and also covers an empty registry). A settled goal
+promotes like a brief, and the archive `references/brief-archive.md` carries
+the delivery history (registry, milestone gates and outcome audit) after the
+original brief. `oat-project-quick-start` resumes the promoted project.
+
 ### Import lane
 
 === "Diagram"
@@ -604,15 +767,15 @@ actionable `oat pjm init` stop instead of scaffolding implicitly. See
 
 ### Seeding a new project from a brainstorm
 
-When the brainstorming destination is "promote to a new OAT project", the dispatcher confirms a project slug and one of three modes: `lite`, `quick`, or `spec-driven`. For Quick and Spec-Driven projects, it runs `oat project new <slug> --mode <mode>` and writes `discovery.md` directly from the brainstorming payload — Initial Request, Solution Space with approaches considered, Chosen Direction, Key Decisions, and Open Questions. It writes only `discovery.md` (never a partial `design.md`), then points to `oat-project-quick-start` or `oat-project-design` without auto-chaining. For Lite projects, it instead seeds the five sections in `plan.md`, leaves `discovery.md` and `design.md` absent, and points to `oat-project-lite`.
+When the brainstorming destination is "promote to a new OAT project", the dispatcher confirms a project slug and one of five modes: `lite`, `brief`, `goal`, `quick`, or `spec-driven`. For Quick and Spec-Driven projects, it runs `oat project new <slug> --mode <mode>` and writes `discovery.md` directly from the brainstorming payload — Initial Request, Solution Space with approaches considered, Chosen Direction, Key Decisions, and Open Questions. It writes only `discovery.md` (never a partial `design.md`), then points to `oat-project-quick-start` or `oat-project-design` without auto-chaining. For Lite projects, it instead seeds the five sections in `plan.md`, leaves `discovery.md` and `design.md` absent, and points to `oat-project-lite`. For Brief projects, it writes the payload to a research note under `references/research/`, leaves the scaffolded `plan.md` for the brief interview, and points to `oat-project-brief`. Goal projects arrive the same way and point to `oat-project-goal`, which authors the brief and its milestone split.
 
-This is a parallel entry path into all three lanes, not a new lane. Quick and Spec-Driven users arrive at `oat-project-quick-start` or `oat-project-design` with discovery already populated; Lite users arrive at `oat-project-lite` with the single-phase plan already seeded.
+This is a parallel entry path into all five lanes, not a new lane. Quick and Spec-Driven users arrive at `oat-project-quick-start` or `oat-project-design` with discovery already populated; Lite users arrive at `oat-project-lite` with the single-phase plan already seeded; Brief and goal users arrive at `oat-project-brief` or `oat-project-goal` with the brainstorm payload saved as a research note under `references/research/` and the scaffolded `plan.md` left for the interview.
 
 ### Folding back into an active project
 
 When `oat-brainstorm` fires while a project is active, it offers a 3-way picker before any pack-filtered destination shows up:
 
-- **Related to the project** → for Lite, fold the synthesis into `plan.md` immediately above `## Phase 1` and hand off to `oat-project-lite`; for Quick and Spec-Driven, use the most-specific upstream artifact (`design.md` if it exists, otherwise `discovery.md`) and hand off to `oat-project-quick-start` or `oat-project-plan`. Any mode with an open PR hands off to `oat-project-revise`. The fold-back commit is safety-gated: a preflight `git status --porcelain -- "$ARTIFACT_PATH"` checks for dirty state, staging is exactly `git add -- "$ARTIFACT_PATH"` (never `-A`, never globs), and the handoff prompt only prints after the scoped commit succeeds.
+- **Related to the project** → for Lite, fold the synthesis into `plan.md` immediately above `## Phase 1` and hand off to `oat-project-lite`; for Brief, fold it into `plan.md` immediately above the first `## Phase` heading so the receiving skill integrates it as new or amended phases; Goal folds into `plan.md` the same way, never editing the `## Milestones` table, and hands off to `oat-project-goal` (or `oat-project-implement` inside the active milestone's approved scope); for Quick and Spec-Driven, use the most-specific upstream artifact (`design.md` if it exists, otherwise `discovery.md`) and hand off to `oat-project-quick-start` or `oat-project-plan`. Any mode with an open PR hands off to `oat-project-revise`. The fold-back commit is safety-gated: a preflight `git status --porcelain -- "$ARTIFACT_PATH"` checks for dirty state, staging is exactly `git add -- "$ARTIFACT_PATH"` (never `-A`, never globs), and the handoff prompt only prints after the scoped commit succeeds.
 - **Independent of the project** → the active project is acknowledged but doesn't constrain the picker; brainstorm routes through its standard pack-filtered terminal-state options (new project, backlog item, idea, doc-to-path, inline).
 - **Related but supplementary** → write a brainstorming reference file at `.oat/projects/<scope>/<project>/brainstorming/YYYY-MM-DD-<topic>.md`, alongside `pr/` and `reviews/`. No lifecycle artifact is touched.
 

package/assets/docs/workflows/projects/planning/hill-checkpoints.md

@@ -60,6 +60,22 @@ auto-review preference prompt are all skipped in both interactive and autonomous
 runs. Only HiLL approval pauses are absent — the root-owned per-phase review and
 the final review remain required.
 
+### Brief and goal checkpoint resolution
+
+Brief and goal projects read `oat_plan_hill_phases` with a brief meaning: `[]`
+and an absent field both mean **no checkpoints**, never "every phase". The
+brief scaffold, which goal projects share, writes `oat_plan_hill_phases: [] # [] = none for brief modes`, and
+`oat-project-implement` then writes:
+
+```yaml
+oat_auto_review_at_hill_checkpoints: false # brief: no checkpoints
+```
+
+and skips the workflow preference check and the first-run checkpoint question.
+To opt in, record an explicit phase array such as `['p03']`; implementation
+keeps it without re-asking and pauses after exactly those phases. The
+per-phase reviews and the final review run either way.
+
 The rest of this section applies to `spec-driven`, `quick`, and `import`
 projects.
 
@@ -125,7 +141,8 @@ See [Workflow preferences in the Configuration guide](../../../reference/configu
 A HiLL (human-in-the-loop lifecycle) checkpoint is a point where the
 implementing agent stops and waits for a person to approve before it continues.
 This choice decides how often that happens during implementation. Lite projects
-have no checkpoints, so it does not apply to them.
+have no checkpoints, and brief and goal projects have none unless they list
+phases explicitly, so it does not apply to them.
 
 | Choice             | Choose it when                                    | What you give up                             |
 | ------------------ | ------------------------------------------------- | -------------------------------------------- |

package/assets/docs/workflows/projects/planning/planning-skills.md

@@ -13,7 +13,7 @@ For a spec-driven project (one using the full workflow: discovery, design, plan,
 then implementation), the usual path is discovery, then design, then plan.
 Design confirms requirements and produces `spec.md` as well as `design.md`.
 Standalone spec is optional when you want to review requirements before
-designing. Quick, lite, and import workflows author their own plans through
+designing. Quick, lite, brief, goal, and import workflows author their own plans through
 their entry skills. Do not send those projects through spec-driven planning
 just because they contain a file named `plan.md`.
 
@@ -55,8 +55,8 @@ A _HiLL (human-in-the-loop lifecycle) checkpoint_ is a point where a skill stops
 and waits for your explicit approval before marking a phase complete. Projects
 created with `oat-project-new` have HiLL approvals on discovery and design **by
 default**: each skill stops after writing its artifact and waits for your
-explicit approval before marking it complete. Quick, lite, and import projects
-have no workflow-phase HiLL checkpoints. Configured exit gates (optional reviews
+explicit approval before marking it complete. Quick, lite, brief, goal, and import
+projects have no workflow-phase HiLL checkpoints. Configured exit gates (optional reviews
 or commands your repository runs before a skill marks its work complete) can
 also keep an artifact in progress. See [HiLL checkpoints](hill-checkpoints.md).
 The [skill catalog](../../../skills/index.md) lists the broader lifecycle tools.
@@ -83,7 +83,7 @@ spec-driven project. The repository knowledge index must exist at
 `oat-repo-knowledge-index` first. The skill checks knowledge staleness and asks
 whether to refresh or continue when the index is stale.
 
-Quick, import, and lite projects use their own next step instead. Mentioning a
+Quick, import, lite, brief, and goal projects use their own next step instead. Mentioning a
 new idea does not authorize automatic discovery invocation.
 
 **Example scenario:** The webhook-delivery project is active, but the team has
@@ -270,11 +270,14 @@ skill asks for a project name and sets it as the active project. The project
 must use spec-driven mode, with `design.md` recording `oat_status: complete` and
 `oat_ready_for: oat-project-plan`.
 
-Quick, import, and lite projects never use this skill to author a plan. On a
+Quick, import, lite, brief, and goal projects never use this skill to author a plan. On a
 quick project, it resumes quick-start if the plan is not ready, and **starts
 `oat-project-implement` immediately** if the plan is ready. On an import project
 with a plan, it points you to `oat-project-implement`. On a lite project, it
-points you to `oat-project-lite`. Do not invoke it on those projects unless you
+points you to `oat-project-lite`. On a brief project, it stops and points you
+to `oat-project-brief`, which owns the Project Brief. On a goal project, it
+stops and points you to `oat-project-goal`, which owns the brief, its
+milestones, and its amendments. Do not invoke it on those projects unless you
 intend that handoff.
 
 **Example scenario:** The webhook design now defines persistence, retries, and
@@ -338,14 +341,14 @@ Promote the active cache-refresh project, keeping its imported plan and complete
 skill asks for a project name and sets it as the active project. The active
 project's `state.md` must record quick or import workflow mode. A spec-driven
 project is already promoted, so the skill reports a no-op unless you request
-artifact refresh. Lite must promote to quick first through the actual terminal
-command:
+artifact refresh. Lite, brief, and goal projects must promote to quick first through
+the actual terminal command:
 
 ```bash
-oat project promote <lite-project-path> --to quick
+oat project promote <lite-brief-or-goal-project-path> --to quick
 ```
 
-Use the reported lite project path, for example
+Use the reported project path, for example
 `.oat/projects/synced/retry-message` in the default synced scope. Then use this
 skill against the active quick project.
 

package/assets/docs/workflows/projects/planning/starting-projects.md

@@ -7,17 +7,19 @@ description: 'Choose a project entry skill, import an existing plan, capture com
 
 Choose an entry path based on what you already know and what already exists.
 These skills do not require an existing active project. They create or import
-tracked work, although quick-start and lite resume an active project of their
-own mode, and import writes into whichever project is active.
-
-| Your situation                                                     | Entry skill               | Result                                                                         |
-| ------------------------------------------------------------------ | ------------------------- | ------------------------------------------------------------------------------ |
-| Requirements need discovery and a full technical design.           | `oat-project-new`         | A spec-driven scaffold, ready to begin discovery.                              |
-| The outcome is bounded, with optional design decisions to resolve. | `oat-project-quick-start` | Discovery and an executable plan, with lightweight design when needed.         |
-| The change fits one implementation sitting.                        | `oat-project-lite`        | One approved plan with requirements and validation criteria.                   |
-| You already have a Markdown plan.                                  | `oat-project-import-plan` | The original source preserved beside a normalized OAT plan.                    |
-| Implementation happened without project tracking.                  | `oat-project-capture`     | Retroactive discovery and implementation records from the session and commits. |
-| A confirmed scope contains several coordinated projects.           | `oat-project-split`       | A coordination parent and children that resume at discovery.                   |
+tracked work, although quick-start, lite, brief, and goal resume an active
+project of their own mode, and import writes into whichever project is active.
+
+| Your situation                                                       | Entry skill               | Result                                                                            |
+| -------------------------------------------------------------------- | ------------------------- | --------------------------------------------------------------------------------- |
+| Requirements need discovery and a full technical design.             | `oat-project-new`         | A spec-driven scaffold, ready to begin discovery.                                 |
+| The outcome is bounded, with optional design decisions to resolve.   | `oat-project-quick-start` | Discovery and an executable plan, with lightweight design when needed.            |
+| The change fits one implementation sitting.                          | `oat-project-lite`        | One approved plan with requirements and validation criteria.                      |
+| One delivery whose outcome and design you can agree in conversation. | `oat-project-brief`       | One reviewed, approved Project Brief whose phases carry intent and exit evidence. |
+| An outcome that needs several deliveries over time.                  | `oat-project-goal`        | One approved Project Brief with milestones, delivered and re-aligned in turn.     |
+| You already have a Markdown plan.                                    | `oat-project-import-plan` | The original source preserved beside a normalized OAT plan.                       |
+| Implementation happened without project tracking.                    | `oat-project-capture`     | Retroactive discovery and implementation records from the session and commits.    |
+| A confirmed scope contains several coordinated projects.             | `oat-project-split`       | A coordination parent and children that resume at discovery.                      |
 
 For the broader mode decision, see [Choose a workflow](../../choose-workflow.md).
 For an existing project's discovery, design, or plan, see
@@ -68,15 +70,15 @@ in a fresh repository.
    overrides the setting for one shell.
 
 3. **Only `oat-project-new` takes a scope.** It accepts `--scope shared|local|synced`.
-   Quick-start, lite, import, capture, and split have no scope argument.
-   Quick-start, lite, import, and capture always create projects in the
+   Quick-start, lite, brief, goal, import, capture, and split have no scope argument.
+   Quick-start, lite, brief, goal, import, and capture always create projects in the
    default scope. Split uses the active project's scope, or `shared` when no
    project is active. Set the default first if you do not want `synced`.
 
 4. **Build the knowledge index before spec-driven discovery.** `oat-project-discover`
    refuses to start until `.oat/repo/knowledge/project-index.md` exists. Run
    `/oat-repo-knowledge-index` once before your first spec-driven project.
-   Quick-start, lite, import, and capture do not check for it.
+   Quick-start, lite, brief, goal, import, and capture do not check for it.
 
 5. **Know what happens when a project is already active.** Check with
    `oat config get activeProject` before you start:
@@ -88,6 +90,9 @@ in a fresh repository.
    - `oat-project-lite` resumes an active lite project and ignores the name and
      description you pass. With any other project active, it creates a new lite
      project.
+   - `oat-project-brief` resumes an active brief project at the earliest step
+     whose output is missing. With any other project active, it creates a new
+     brief project.
    - `oat-project-import-plan` writes into any active project, whatever its
      mode. It rewrites that project's `plan.md` and switches it to import mode.
    - `oat-project-split` makes its first child the active project.
@@ -106,14 +111,14 @@ Project creation normally activates the new project in `.oat/config.local.json`.
 Check the reported project path before continuing, especially when another
 project is already active.
 
-The new, quick-start, lite, and import skills check inherited Git changes before
+The new, quick-start, lite, brief, goal, and import skills check inherited Git changes before
 scaffolding. Unrelated changes require an explicit disposition in interactive
 runs. One exception: if the only change is `.oat/sync/manifest.json`, it is
 committed automatically as `chore: run sync`. Capture does not run this check.
 Do not assume starting a project also authorizes implementation or a PR.
 
-**Dispatch policy.** Before a plan is marked ready, quick-start, lite, and
-import ask you to choose a _dispatch policy_: the highest tier of models and
+**Dispatch policy.** Before a plan is marked ready, quick-start, lite, brief,
+goal, and import ask you to choose a _dispatch policy_: the highest tier of models and
 effort OAT may use when it dispatches implementation and review agents. The
 choices come from `oat project dispatch-ceiling choices`. If your configuration
 has no complete dispatch ladder (the list of models for each tier), the skill
@@ -125,9 +130,11 @@ deliberately. The plan stays not ready until this resolves. See
 **Approval checkpoints.** A _HiLL (human-in-the-loop lifecycle) checkpoint_ is
 a point where a skill stops and waits for your explicit approval before it marks
 a phase complete. Projects created by `oat-project-new` have checkpoints on
-discovery and design by default. Quick, lite, import, and captured projects have
-no workflow-phase checkpoints before implementation. Lite still asks you to
-approve its plan once. See [HiLL checkpoints](hill-checkpoints.md).
+discovery and design by default. Quick, lite, brief, goal, import, and
+captured projects have no workflow-phase checkpoints before implementation.
+Lite still asks you to approve its plan once, brief asks you to approve its
+reviewed brief once, and goal asks for that approval and then one per later
+milestone. See [HiLL checkpoints](hill-checkpoints.md).
 
 Several skills also run a configured _exit gate_, an optional review or command
 your repository configures to run before a skill marks its work complete. When
@@ -299,6 +306,117 @@ keeping or disabling configured gates for this project.
 **Next step:** Run `oat-project-implement` after the approved lite plan is ready.
 If the scope grows, continue through `oat-project-quick-start` after promotion.
 
+## oat-project-brief
+
+Use brief for one delivery whose outcome and design you can agree in
+conversation. Brief replaces discovery, design, and a task plan with one
+reviewed Project Brief in `plan.md`. Its phases state intent and exit evidence
+instead of tasks.
+
+**Invocation:** Provide the slug and the intended outcome.
+
+```text
+/oat-project-brief export-audit "Let administrators export the audit log as CSV from the settings page."
+```
+
+**Prerequisites:** No active project is needed. If the active project is a
+brief project, brief resumes it in place.
+
+**Example scenario:** Administrators need the audit log as CSV. Brief
+interviews you in short rounds, settling facts from the code itself and
+putting the design choices to you, such as streaming against buffering the
+export. It writes the agreed outcomes, approach, decisions, and phases into the
+brief, runs artifact review and any configured gate, and asks you to approve
+the reviewed brief once.
+
+**Expected output:** One Project Brief in `plan.md` with a Goal, numbered
+Outcomes that each name their evidence, the Approach (with an optional
+`### Design` subsection), Constraints and Out of Scope, Decisions with the
+alternatives you rejected, Known Unknowns with the phase that settles each,
+the Delivery endpoint and authority, and `## Phase pNN:` blocks. Each phase
+states its `**Intent:**`, `**Exit evidence:**`, and whether it is
+`**Provisional:**`; only the first phase has to be concrete now. The skill also
+initializes `implementation.md` as a per-phase journal with one section per
+phase and no execution records yet. There is no `discovery.md`, `spec.md`, or
+`design.md`, and no task list: tasks are recorded in the journal as the work
+runs.
+
+The interview runs in readiness rounds. The agent settles facts from the code,
+docs, or research itself and brings you only decisions, each with a
+recommendation and its tradeoff. It writes the brief once you have explicitly
+agreed the design, so the approval confirms a design you already accepted.
+Within the approved outcomes, constraints, and authority, the agent may later
+add, split, or reorder phases and make provisional phases concrete, and logs
+each change; a change to an Outcome, a Constraint, the authority, the endpoint,
+a Decision, or the Approach comes back to you first.
+
+**What it does without asking:** It creates the project through
+`oat project new --mode brief` in the default scope and makes it active,
+commits the authored brief before any review, runs the independent artifact
+review (the reviewer receives the brief and the bundled brief contract, not the
+conversation), runs any configured `oat-project-brief` gate and records its
+outcome as `oat_brief_gate` in `state.md`, and commits the approved brief and
+journal. In synced scope each commit is an `oat project push` to `origin`. It
+asks before: proceeding with a dirty working tree, the interview decisions,
+adopting a dispatch ladder into config, choosing the dispatch policy, keeping
+or disabling configured gates for this project, and the single approval
+(approve, revise, or promote to quick).
+
+**Promotion to quick.** Choose promote at the approval, or later run
+`oat project promote <project-path> --to quick`, when you want a maintained,
+approved up-front task plan. Promotion keeps completed execution records as
+quick tasks, lists phases that still need tasks in
+`oat_promotion_pending_phases`, and hands off to `oat-project-quick-start`.
+Before the brief is written and committed there is nothing to promote: abandon
+the scaffold and start `oat-project-quick-start` instead. See
+[Lifecycle](../lifecycle.md#promoting-a-brief-project-to-quick).
+
+**Next step:** Run `oat-project-implement` after the brief is approved.
+
+## oat-project-goal
+
+Use goal when an outcome needs several deliveries over time. Goal writes one
+reviewed Project Brief like brief does, and adds a `## Milestones` table that
+groups its phases into milestones. Each milestone is implemented, reviewed,
+delivered as its own pull request, and followed by a short re-alignment before
+the next one starts.
+
+**Invocation:** Provide the slug and the intended outcome.
+
+```text
+/oat-project-goal audit-exports "Give administrators audit exports in CSV first, then scheduled delivery."
+```
+
+**Prerequisites:** No active project is needed. If the active project is a
+goal project, goal resumes it at the step its state calls for: authoring,
+milestone activation, re-alignment, or the terminal declaration.
+
+**Example scenario:** Administrators need audit exports now and scheduled
+delivery later. Goal interviews you once for the whole outcome, splits it into
+milestone m01 (CSV export) and m02 (scheduled delivery), and activates m01.
+When m01's pull request is delivered, goal asks what changed, amends the brief
+with m02's phases, takes the amendment through review and approval, and
+activates m02 once m01 reaches the endpoint you agreed, such as merged.
+
+**Expected output:** One Project Brief in `plan.md` with
+`oat_plan_source: goal`, a canonical `| Milestone | Phases |` table in which
+every phase belongs to exactly one milestone, and the first milestone approved
+and activated. Each milestone's approval is recorded as its `plan` gate carrier
+in `state.md`; deliveries are recorded in the `oat_deliveries` registry by the
+delivery skills.
+
+**What it does without asking:** It creates the project through
+`oat project new --mode goal`, commits the brief before review, runs the
+artifact review and any configured `oat-project-goal` gate, refreshes delivery
+observations with `oat project delivery refresh`, and appends one project-log
+entry at each activation and re-alignment. It asks before: proceeding with a
+dirty working tree, the interview decisions and milestone split, each approval,
+the re-alignment questions, and declaring the goal met.
+
+**Next step:** Run `oat-project-implement` after the first milestone is
+activated. Between milestones, `oat-project-goal` re-aligns and activates the
+next milestone once the previous delivery reaches its agreed endpoint.
+
 ## oat-project-import-plan
 
 Use import when the plan already exists, including one produced in a provider's

package/assets/docs/workflows/projects/reviews/index.md

@@ -176,7 +176,7 @@ This feature is opt-in and disabled by default (missing or `enabled: false`). Fo
 
 Generated planning and analysis artifacts have a separate review loop from code/phase reviews.
 
-For plans, `oat-project-plan`, `oat-project-quick-start`, `oat-project-lite`, and `oat-project-import-plan` run a bounded `plan.md` artifact review before marking the plan ready for implementation. The loop dispatches `oat-reviewer` in structured-output artifact mode with `scope: plan`, applies unambiguous Critical and High artifact-local fixes, offers Medium and Low fixes, and re-runs until clean or the retry bound is exhausted. A clean result records the `plan` row in the plan's `## Reviews` table as `passed`.
+For plans, `oat-project-plan`, `oat-project-quick-start`, `oat-project-lite`, `oat-project-brief`, `oat-project-goal` (for the brief and each milestone amendment), and `oat-project-import-plan` run a bounded `plan.md` artifact review before marking the plan ready for implementation. The loop dispatches `oat-reviewer` in structured-output artifact mode with `scope: plan`, applies unambiguous Critical and High artifact-local fixes, offers Medium and Low fixes, and re-runs until clean or the retry bound is exhausted. A clean result records the `plan` row in the plan's `## Reviews` table as `passed`.
 
 For analysis artifacts, `oat-docs-analyze` and `oat-agent-instructions-analyze` run a bounded accuracy review after writing their severity-rated artifacts. The reviewer checks cited evidence, severity, and recommendations before the matching apply workflow consumes the artifact. The analysis loop updates tracking metadata to mark the artifact verified.
 
@@ -220,12 +220,45 @@ See [Workflow preferences in the Configuration guide](../../../reference/configu
 
 Use phase-scoped review artifacts during implementation (`p01`, `p02`, etc), then run final review before project closeout.
 
+In a brief project, review scope comes from the journal's anchors instead of
+commit-message inference. A phase scope is its `**Base:**..**Head:**` range, a
+`pNN-pMM` run spans the first selected base through the last selected head,
+and `final` covers every accepted phase, including `p-revN` revision phases.
+The review artifact records the requested scope, the ordered phase IDs, the
+base SHA, and `oat_review_scope_source` (`anchors`, or `merge-base-range` when
+anchors are missing and the range widens to the confirmed merge-base range).
+Commit-message matches only label commits and never narrow the range. Invalid
+or contradictory anchors stop the review and route to `oat-project-reconcile`.
+A brief `final` review also audits every numbered Outcome against the
+journal's evidence.
+
+In a goal project, per-phase reviews (`pNN`, `p-revN`) use the brief anchors.
+A milestone's integrated review names the milestone or delivery and its exact
+ordered phase set, for example `code m01: p01, p02, p-rev1` or
+`code m01/d01: p01, p02, p-rev1`; a `pNN-pMM` or `final` token is refused for
+it, and membership is never expanded from first to last phase. The set must
+match the milestone's `## Milestones` row, a pending `oat_goal_recovery`
+record, or a registered delivery's frozen scope. Before dispatch, the
+milestone's exit carrier must be allowed and fresh; otherwise the review stops
+and routes to implement's milestone closeout. The range runs from the first
+member's base to the last member's head, and phases of other milestones inside
+it are listed under `Intervening changes:` and judged only as context. The
+artifact records `oat_review_requested_scope: mNN` (or `mNN/dNN`) and
+`oat_review_phase_ids` with the exact set, and a narrowed re-review keeps the
+full set. The `## Reviews` Scope cell is the milestone ID (`m01`) or, for a
+registered delivery, the delivery ID (`d01`). The review is recorded as
+`received`; `oat-project-review-receive` moves the milestone to `delivering`
+on a clean receive.
+
 Final review `passed` gate requires:
 
 - No unresolved Critical/High/Medium findings.
 - Deferred Medium findings resurfaced and explicitly dispositioned.
 - Low findings explicitly dispositioned (after plain-language explanation).
 
+A goal milestone delivery is gated by its passed, fresh integrated review and
+exit carrier rather than by a `final` row.
+
 ## Complexity review at budget exhaustion
 
 When a review or gate budget runs out, another round of the same review is
@@ -455,7 +488,8 @@ An artifact review loop runs in the same agent session that wrote the artifact,
 so it is not an independent review. It retries up to the project's retry limit,
 which defaults to two; a limit of zero still allows the first review. Autonomous
 runs turn on review at HiLL checkpoints for every project except lite projects,
-which have no checkpoints.
+which have no checkpoints, and brief projects without explicitly listed
+checkpoint phases.
 
 - If you are a solo developer, or runs are unattended, and your agent tool
   supports subagents, set the final review execution to `subagent`.

package/assets/docs/workflows/projects/reviews/review-flavors.md

@@ -119,7 +119,8 @@ different things can happen, and only two of them stop the workflow:
 - **Operational failures stay blocked.** The reviewer could not start, timed
   out without writing a review, or wrote a review OAT could not validate or
   match to this run. Nothing was reviewed. `oat-project-implement` and
-  `oat-project-lite` keep these failures blocked whatever `onFailure` says.
+  `oat-project-lite` keep these failures blocked whatever `onFailure` says,
+  and so do `oat-project-brief` and `oat-project-goal`.
   The planning skills handle them differently; see
   [When the gate finds blocking problems](../../advanced/workflow-gates.md#when-the-gate-finds-blocking-problems).
 - **Reviewer selection falls back.** By default (`--avoid same-family`) the gate
@@ -457,8 +458,11 @@ request.
 **Prerequisites:** An initialized project must resolve from the active pointer
 or an explicitly supplied project/review target. Its core artifacts must be
 committed before review. Code review needs completed implementation work and
-the mode-appropriate requirements sources; lite review does not require absent
-discovery, spec or design artifacts. Code reviews and plan artifact reviews
+the mode-appropriate requirements sources; lite, brief, and goal reviews do not
+require absent discovery, spec or design artifacts. A brief code review takes
+its range from the journal's phase anchors. A goal integrated review names its
+milestone or delivery and its exact ordered phase set; see
+[Phase and final review](index.md#phase-and-final-review). Code reviews and plan artifact reviews
 also need a resolved dispatch policy (`oat_dispatch_policy` in `state.md` or
 `workflow.dispatchPolicy.*` in config); without one the review stops before
 launching a reviewer. Discovery, spec and design artifact reviews run without