npm - @open-agent-toolkit/cli - Versions diffs - 0.3.18 → 0.3.20 - Mend

@open-agent-toolkit/cli 0.3.18 → 0.3.20

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (132) hide show

package/assets/docs/skills/index.md CHANGED Viewed

@@ -42,7 +42,7 @@ make only the changes you approve.
 ## Key Skills by Use Case
-- Start a new tracked project: `oat-project-new`, `oat-project-quick-start`, or `oat-project-lite` for a single-sitting change with one batched interview and one approval (quick start accepts a project name plus optional description; if you omit the description it should ask before discovery begins)
+- Start a new tracked project: `oat-project-new`, `oat-project-quick-start`, `oat-project-lite` for a single-sitting change with one batched interview and one approval (quick start accepts a project name plus optional description; if you omit the description it should ask before discovery begins), `oat-project-brief` for one delivery agreed in conversation, or `oat-project-goal` for an outcome delivered in milestones
 - Resume an existing project: `oat-project-open` to select it,
   `oat-project-progress` to see where it stands, then `oat-project-next` to
   continue. See
@@ -118,6 +118,8 @@ for policy, storage, approval, and recovery details.
     - `oat-project-new`
     - `oat-project-quick-start`
     - `oat-project-lite`
+    - `oat-project-brief`
+    - `oat-project-goal`
     - `oat-project-import-plan`
     - `oat-project-promote-spec-driven`
     - `oat-project-open`
@@ -305,14 +307,16 @@ Visibility reports source metadata: “user” is `user-invocable` and “model
 ### Project entry
-| Skill                                                                                                    | Description                                                                                                                                                                                                         | Visibility                       | Needs an active project? |
-| -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ------------------------ |
-| [`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                       |
-| [`oat-project-new`](../workflows/projects/planning/starting-projects.md#oat-project-new)                 | Use when starting a spec-driven OAT project from scratch. Scaffolds a new project under PROJECTS_ROOT and sets it active.                                                                                           | user: true; model disabled: true | No                       |
-| [`oat-project-quick-start`](../workflows/projects/planning/starting-projects.md#oat-project-quick-start) | Use when a task is small enough for quick mode or rapid iteration is preferred. Scaffolds a lightweight OAT project from discovery directly to a runnable plan, with optional brainstorming and lightweight design. | user: true; model disabled: true | No                       |
-| [`oat-project-split`](../workflows/projects/planning/starting-projects.md#oat-project-split)             | Use when a discovery or brainstorm should split one broad scope into coordinated OAT child projects.                                                                                                                | user: true; model disabled: true | No                       |
+| 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-goal`](../workflows/projects/planning/starting-projects.md#oat-project-goal)               | Use when an outcome needs several deliveries over time - one approved Project Brief with a Milestones table, a milestone loop of activation, delivery and re-alignment, and a terminal declaration audited against the brief's outcomes. | 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                       |
+| [`oat-project-new`](../workflows/projects/planning/starting-projects.md#oat-project-new)                 | Use when starting a spec-driven OAT project from scratch. Scaffolds a new project under PROJECTS_ROOT and sets it active.                                                                                                                | user: true; model disabled: true | No                       |
+| [`oat-project-quick-start`](../workflows/projects/planning/starting-projects.md#oat-project-quick-start) | Use when a task is small enough for quick mode or rapid iteration is preferred. Scaffolds a lightweight OAT project from discovery directly to a runnable plan, with optional brainstorming and lightweight design.                      | user: true; model disabled: true | No                       |
+| [`oat-project-split`](../workflows/projects/planning/starting-projects.md#oat-project-split)             | Use when a discovery or brainstorm should split one broad scope into coordinated OAT child projects.                                                                                                                                     | user: true; model disabled: true | No                       |
 ### Project execution

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

@@ -336,11 +336,21 @@ 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
-invokes its owning creation skill. If an export-filter project is already
+lite, brief, quick, or spec-driven review density from the actual uncertainty and
+invokes its owning creation skill. It never selects goal: each milestone's
+approval and the final declaration need a person, so an existing goal project
+stops at a product-judgment boundary instead of running unattended. 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/dispatch-ceiling.md CHANGED Viewed

@@ -22,8 +22,8 @@ constraints:
   agents to implement and review each phase, or no cap, or leaving model choice
   to the provider; and deciding where the list of candidate models (the
   _ladder_) is stored.
-- **Who needs it:** anyone starting a quick, spec-driven, lite, or imported
-  project, because planning asks you to choose a policy; and team leads who
+- **Who needs it:** anyone starting a quick, spec-driven, lite, brief, goal,
+  or imported project, because planning asks you to choose a policy; and team leads who
   manage model cost.
 - **Know first:** there is no default policy, and a policy set in any config
   file overrides the one each project chose. A tier is a cap: phase agents may

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

@@ -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`, `oat-project-goal`, 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,26 @@ 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.
+A goal project records its gate outcomes per milestone instead, in
+`oat_milestone_gates`, and never in `oat_brief_gate`. The configured
+`oat-project-goal` gate on the brief or a milestone amendment becomes that
+milestone's `plan` carrier, `oat_milestone_gates[mNN].plan`, written with
+`status: allowed` only after the artifact review, the gate, and your approval;
+for a re-alignment amendment it is the only approval evidence. The implement
+exit gate at milestone closeout writes `oat_milestone_gates[mNN].exit` (never
+`oat_implement_exit_gate`, which goal uses only at terminal closeout). It runs
+before the milestone's integrated review and runs again after queued fixes.
+`oat project delivery check` reports the exit carrier's freshness, and
+`oat project delivery refresh` marks it stale when delivery evidence no longer
+holds.
+`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 +858,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`, `oat-project-goal`, 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,8 +1252,8 @@ 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
-  `onFailure` says, so even a `warn` gate does not let them continue.
+- `oat-project-implement`, `oat-project-lite`, `oat-project-brief`, and
+  `oat-project-goal` 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
   review happened. With `block`, they retry and then hand the problem to you,

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

@@ -15,14 +15,16 @@ 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  |
+| Goal           | The reviewed Project Brief with its milestone split, then each later milestone's amendment, and finally your declaration that the goal is met                                              | None by default inside a milestone; the agent stops at each re-alignment and waits for your approval | Brief review, a review after every phase, an integrated review per milestone | Each milestone opens its own pull request when `oat-project-pr-progress` delivers it; completion opens none when the deliveries cover the work | 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 +48,16 @@ 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.
+- **Goal:** the first approval covers the reviewed Project Brief and its
+  milestone split. Each later milestone is approved separately, at
+  re-alignment, after its amendment is reviewed and gated; the approval is
+  recorded as that milestone's `plan` gate carrier in `state.md`. The goal ends
+  only when you declare it met, and the declaration records an audit of every
+  outcome. Autonomous runs never start or continue a goal project.
 - **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
@@ -123,7 +135,11 @@ and any budget that runs out adds one read-only complexity-review run.
   pushes your branch after archiving a synced project, whether or not it opens
   a pull request. Autonomous runs also push the branch, without force, after
   each lifecycle step such as planning and implementation. See
-  [Autonomous Project Execution](advanced/autonomy.md).
+  [Autonomous Project Execution](advanced/autonomy.md). In a goal project,
+  `oat-project-pr-progress` pushes the branch and opens each milestone's pull
+  request once the milestone's evidence checks fresh, and
+  `oat-project-complete` opens none when the registered deliveries already
+  cover every accepted phase, even with `workflow.createPrOnComplete` set.
 ## Set it up the way you want

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

@@ -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, goal, quick, spec-driven, or imported projects, and what each mode does at the end.
 ---
 # Choose a Workflow
@@ -48,6 +48,8 @@ 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
+- Goal mode: a brief whose phases are grouped into milestones, each delivered as its own pull request and followed by a re-alignment, closed by an explicit declaration audited against the brief's outcomes
 - Quick mode: tracked work with a lighter upfront planning path
 - Spec-driven mode: explicit discovery, requirements, design, and plan artifacts
 - Import mode: an externally-authored plan imported into OAT for tracked execution
@@ -78,13 +80,15 @@ 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                                                                                                                                                                                   |
+| Goal        | `/oat-project-goal`                             | The outcome needs several deliveries over time, and you can agree the first milestone in conversation | The same as brief, plus an approval per milestone and a final declaration that the goal is met                                       | Each milestone's pull request opens when `oat-project-pr-progress` delivers it; any phases no delivery covers go out through `oat-project-pr-final`, and completion opens no extra pull request |
+| 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 +109,18 @@ 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 the outcome needs more than one delivery, such as a first version now and
+  a follow-up once you have seen it used, choose goal. You approve one brief
+  with a milestone split, then each milestone is delivered as its own pull
+  request and re-aligned before the next one starts; you declare the goal met
+  at the end. Goal is never selected by an autonomous run, because each
+  milestone approval and the final declaration need you.
 - If your team is building a feature with agreed, bounded requirements, choose
   quick. A long task list alone does not call for a formal spec.
 - If the change is high-risk or regulated, or its requirements are still being

package/assets/docs/workflows/ideas/index.md CHANGED Viewed

@@ -37,4 +37,4 @@ If the thought is still pre-shape — you don't know whether it should land as a
 ## Promotion Path
-When an idea becomes concrete, summarize it and then start a tracked OAT project in lite, quick, or spec-driven mode depending on scope and design risk. Lite suits a single-sitting change and seeds `plan.md` directly; quick and spec-driven seed `discovery.md` instead.
+When an idea becomes concrete, summarize it and then start a tracked OAT project in lite, brief, goal, quick, or spec-driven mode depending on scope and design risk. Lite suits a single-sitting change and seeds `plan.md` directly; brief and goal write their Project Brief into `plan.md` through an interview; quick and spec-driven seed `discovery.md` instead.

package/assets/docs/workflows/ideas/lifecycle.md CHANGED Viewed

@@ -63,8 +63,9 @@ Where to start:
 - **Worth exploring:** `oat-idea-new`. `oat-idea-ideate` resumes an idea, can
   start one from a scratchpad seed, and can reopen a summarized idea.
 - **Scoped work for later:** `oat-pjm-add-backlog-item` (needs `oat pjm init`).
-- **Ready to build:** `oat-project-lite`, `oat-project-quick-start`,
-  `oat-project-new`, or `oat-project-import-plan` for a plan written elsewhere.
+- **Ready to build:** `oat-project-lite`, `oat-project-brief`,
+  `oat-project-goal`, `oat-project-quick-start`, `oat-project-new`, or
+  `oat-project-import-plan` for a plan written elsewhere.
 Optional moves:

package/assets/docs/workflows/projects/closeout/closeout-skills.md CHANGED Viewed

@@ -131,6 +131,28 @@ For a synced project, project artifacts are published to the project ref with
 refreshes project metadata. Declining leaves the description available without
 claiming a PR exists.
+**Goal projects:** in a goal project a progress PR is a milestone delivery,
+and this skill registers it. Its scope is the router's `deliver mNN` (or
+`deliver mNN/dNN`) context or a pending `oat_goal_recovery` record at stage
+`delivering`: the milestone's ordered phase set, or a registered delivery's
+frozen scope, never a `pNN-pMM` range or commit labels. The description's Git
+range runs from the set's first anchored base to its last anchored head and
+names any other milestone's phases that fall inside it. In place of the
+optional PR question, the skill runs `oat project delivery refresh` when
+deliveries exist and registers only when
+`oat project delivery check --subject <mNN|dNN>` reports `status: ok`. It
+commits a `registering` registry entry before creating anything, then creates
+the PR, or on resume attaches the single PR that `gh pr list` finds for the
+head branch (more than one match stops at `oat-project-reconcile`). It then
+records the member, `status: open`, and `oat_milestone_status: delivered`, and
+appends one structural project-log entry. Stale review or exit-gate evidence
+stops before registration: for the active milestone the skill writes
+`oat_milestone_status: reviewing` and an `oat_goal_recovery` record at the
+stage the missing evidence names; for an older milestone it writes only the
+recovery record. A milestone that already has a registered delivery is
+re-checked and returned to `delivered` when its evidence is fresh, never
+registered twice.
 **Next step:** Review the description and choose whether to open the progress
 PR. Continue remaining project tasks through `oat-project-implement`.
@@ -150,8 +172,9 @@ inputs select its destination and title.
 **Prerequisites:** Needs an active OAT project: yes. If no project is active,
 the skill asks for the project name and sets that project as active. The
 project needs `plan.md`. Spec-driven mode also requires `spec.md` and `design.md`. Quick,
-import, and lite accept their mode-appropriate reduced artifacts. The latest
-`final` code-review event in the plan's Reviews ledger should be `passed`.
+import, lite, brief, and goal accept their mode-appropriate reduced artifacts.
+Outside goal mode, the latest `final` code-review event in the plan's Reviews
+ledger should be `passed`.
 Autonomous execution stops if it is not passed. Interactive execution warns
 and asks before proceeding anyway.
@@ -172,6 +195,19 @@ and base branch when you did not pass them, the only question it asks is
 whether to continue when the latest final review has not passed. It never
 merges the PR.
+**Goal projects:** in a goal project this skill is the terminal delivery
+registration owner, not a second project PR. It runs its own registration step
+in place of the final-review check and PR creation described above. It
+requires `oat_goal_status: declared_met` and a valid outcome audit, read
+through `oat project closeout-check`; any refusal other than `phase-uncovered`
+routes to the skill named in `nextOwner.skill`. When no accepted phase is
+uncovered, it creates no PR and writes no state, because delivery coverage
+already satisfies the `pr` step. Otherwise it registers one terminal delivery
+per milestone that owns uncovered accepted phases, in milestone order, through
+the same registration contract as `oat-project-pr-progress`. Deliveries
+registered from one head branch share its pull request. Coverage completes
+when every terminal delivery reaches its agreed endpoint.
 **Example scenario:** Export filters and audit reporting are implemented, the
 latest final review has passed, and you have authorized publication. Final PR
 summarizes the complete change, including review evidence and verification.
@@ -351,6 +387,17 @@ implementation tracking, and state are updated for execution. Inline requests
 are not severity-triaged. Structured GitHub feedback and review artifacts route
 through their corresponding review-receive skills and use those contracts.
+**Goal projects:** inline feedback needs an explicit target before anything is
+written: a milestone or delivery identity (`mNN` or `mNN/dNN`). The skill asks
+for it when you did not name it, and never infers it from the open PR's commit
+labels. The revision is a phase-only `p-revN` appended to that milestone's
+`## Milestones` row; a registered delivery's frozen scope is never edited. The
+target's exit carrier, and a registered target delivery's integrated review,
+are marked stale. When the target is the active milestone, the skill returns
+it to `oat_milestone_status: implementing`. Feedback on an older milestone
+creates or advances an `oat_goal_recovery` record instead and leaves the
+active milestone's status and execution pointer unchanged.
 **Next step:** If revise did not continue into implementation on its own, run
 `oat-project-implement` to execute the revision tasks. After verification,
 update the open PR and its review evidence. Revise itself does not write code
@@ -378,7 +425,13 @@ path. The target needs `state.md` and at least `plan.md` or
 `implementation.md`. Completed
 implementation provides shipped evidence. If only a plan exists, the skill can
 proceed but must identify recommendations as based on planned work rather than
-verified implementation. Lite projects do not require discovery, spec, or design.
+verified implementation. Lite, brief, and goal projects do not require
+discovery, spec, or design; a brief's documentation sources are the Project
+Brief and the per-phase journal. A goal project adds two shipped-result
+sources from `state.md`: the outcome audit (`oat_goal_outcome_audit`) and the
+delivery registry (`oat_deliveries`). The skill documents only what those
+deliveries shipped and names audited deferrals rather than documenting them as
+delivered.
 **Example scenario:** Export filters shipped, but the user guide still describes
 only unfiltered exports. Document verifies the actual endpoint and CLI behavior,
@@ -430,7 +483,12 @@ Summarize the delivered export filters, the date-format decision, and the audit-
 completed task. Missing implementation tracking blocks summary generation.
 With no completed tasks, the process warns that the summary will be minimal.
 Lite uses its plan contract and implementation results without requiring
-discovery, spec, or design artifacts.
+discovery, spec, or design artifacts. Brief needs at least one accepted
+phase-unit and draws on the brief's Goal, Outcomes, Approach, and Decisions
+plus the journal; its staleness fingerprint changes when a phase is accepted,
+not when execution records change. A goal summary's fingerprint also covers
+the deliveries observed at their agreed endpoint, so a delivery newly reaching
+its endpoint makes the summary stale.
 **Example scenario:** The first export phase is delivered, and another engineer
 will own the reporting phase next week. Summary records the shipped filter
@@ -466,6 +524,15 @@ It only offers, and does not create without your answer, backlog items for
 follow-up entries in the project log. It does not invent tasks or silently
 rewrite the execution plan.
+In a goal project, while `oat project closeout-check` still reports
+`phase-uncovered` and the closeout sequence has not yet run its `pr` step, the
+skill writes only files in the project directory. It defers the repository
+ledger roll-up and decision-record promotion and reports them as deferred,
+because a repository-level commit after the terminal milestone's reviewed
+revision would make the terminal delivery undeliverable. The next summary run
+after `phase-uncovered` clears performs them: a `summary` step configured after
+`pr`, or the summary refresh at completion. Do not decline that refresh.
 **Next step:** Use the summary as a source for documentation, PR description,
 and later project handoff. Refresh it after revisions. Complete the project
 only when its lifecycle closeout requirements are satisfied.
@@ -492,7 +559,12 @@ you invoke it by name. Before it changes anything, it runs a read-only check
 that the project's stored closeout sequence is finished (or that the project
 has none). If an implementation closeout is still incomplete, the skill sends
 you back to `oat-project-implement`; no phase-status value bypasses that
-check.
+check. For a goal project the check also applies the goal boundary: a valid
+declaration, an exhaustive outcome audit, resolved extractions, an observation
+of every terminal delivery's pull requests, and delivery coverage of every
+accepted phase. A goal refusal routes to the skill it names in
+`nextOwner.skill`, such as `oat-project-goal`, `oat-project-pr-progress`, or
+`oat-project-pr-final`, rather than to implement alone.
 **What it does without asking:** the skill asks once, then acts. One combined
 prompt asks you to confirm completion and, where they apply, whether to
@@ -513,6 +585,12 @@ runs `oat-project-summary`, with its own commit and decision promotion, and an
 archive runs `oat project archive`, including an S3 upload when
 `archive.s3SyncOnComplete` is enabled.
+In a goal project whose `pr` step is satisfied by delivery coverage, the skill
+creates no PR, even with `workflow.createPrOnComplete: true`, and reports
+`PR on complete: satisfied by goal delivery coverage`. It opens a separate
+bookkeeping PR for the completion commits only when you ask for one in that
+run, and never counts it as a goal delivery.
 **Example scenario:** The export project has passed final verification and its
 stored closeout sequence, but the PR is still open. Complete finalizes lifecycle
 state and, if selected, archives the durable artifacts and updates the existing

package/assets/docs/workflows/projects/closeout/pr-flow.md CHANGED Viewed

@@ -10,6 +10,10 @@ Two PR paths:
 - `oat-project-pr-progress`: progress PR for one phase or partial scope
 - `oat-project-pr-final`: final project PR into `main`
+In a goal project both skills register deliveries instead: a progress PR is a
+milestone delivery, and pr-final registers terminal deliveries rather than a
+separate final PR.
 ## Inputs
 Expected artifacts:
@@ -18,12 +22,16 @@ Expected artifacts:
 - Required (spec-driven mode): `spec.md`, `design.md`
 - Optional (quick/import): `spec.md`, `design.md`
 - Not expected (lite): `discovery.md`, `spec.md`, or `design.md`
+- Not expected (brief): `discovery.md`, `spec.md`, or `design.md`; the Project Brief in `plan.md` and the per-phase journal in `implementation.md` are the sources
+- Not expected (goal): as brief; the Project Brief with its `## Milestones` table, the journal, and the goal state in `state.md` are the sources
 - Recommended (quick mode): `discovery.md`
 - Recommended (import mode): `references/imported-plan.md`
 - Recommended: `implementation.md` final summary
 - Recommended: `summary.md` — pr-final treats it as the primary source for the PR Summary section and automatically refreshes it first when missing or stale
 - Lite source row: `oat-project-pr-final` uses the plan's Summary, Decisions, and Validation Criteria plus the `implementation.md` Final Summary; it does not create `summary.md` unless lite closeout explicitly opts in
-- Required gate for final PR: review table final row should be `passed`
+- Brief source row: `summary.md` is required as in quick; its sources are the brief's Goal, Outcomes, Approach, and Decisions, the journal's accepted phases and Outcomes audit, and the review rows. Progress PRs scope a phase or `pNN-pMM` run from the journal's `**Base:**`/`**Head:**` anchors rather than a commit-message search
+- Goal source row: a progress PR is a milestone delivery. Its scope is the milestone's ordered phase set, or a registered delivery's frozen scope; its Git range runs from the set's first anchored base to its last anchored head and discloses other milestones' phases inside it. The PR is created only after `oat project delivery check` reports `status: ok` and a `registering` entry is committed to `oat_deliveries`. pr-final registers terminal deliveries for uncovered accepted phases instead of opening a separate final PR
+- Required gate for final PR: review table final row should be `passed` (goal: pr-final does not read the final row; each delivery it registers needs a passed, fresh integrated review and an allowed, fresh exit carrier instead)
 ## Output

package/assets/docs/workflows/projects/execution/execution-skills.md CHANGED Viewed

@@ -92,14 +92,39 @@ choosing `Leave Unresolved` stops the run. A non-interactive run stops with
 needs your authorization, the skill asks once before any work; if you decline,
 it runs the phases inline in the current session instead.
-**Questions on the first run:** Except in a lite project, the first run lists
+**Questions on the first run:** Except in a lite, brief, or goal project, the first run lists
 the plan's phases and asks which checkpoint behavior you want: stop after
 every phase (the default), after specific phases, or only after the final
 phase. Setting `workflow.hillCheckpointDefault` to `every` or `final` answers
 this in advance. It then asks whether to run an extra lifecycle review
 automatically at each checkpoint, unless `workflow.autoReviewAtHillCheckpoints`
 is set. Both answers are written to `plan.md` and are not asked again when you
-resume. A lite project has no checkpoints and skips both questions.
+resume. A lite project has no checkpoints and skips both questions. A brief
+or goal project skips them too unless its `oat_plan_hill_phases` lists phases
+explicitly; for those modes, `[]` means no checkpoints.
+**Brief projects:** Each `## Phase pNN:` block in the brief is one
+phase-unit with Intent and Exit evidence instead of planned tasks. The root
+records the phase's `**Base:**` in a phase-start commit before dispatch, the
+committing owner opens `### Task pNN-tNN` execution records in
+`implementation.md` as work happens and writes `**Head:**` when the phase's
+work ends, a fresh reviewer reviews the anchored `Base..Head` range, and only
+the root writes `**Status:** completed` once review dispositions and selected
+gates settle. Progress and the next-phase decision count phase-units, never
+records.
+**Goal projects:** every brief rule above applies, and each run gets a scope
+from the router: the active milestone's ordered phase set, a recovery scope
+for an older delivery, or the terminal scope after the goal is declared met.
+Implement never widens a scope to another milestone's phases. When every phase
+in the milestone's scope is accepted, it runs the scoped milestone closeout:
+the implement exit gate, written to `oat_milestone_gates[mNN].exit`, then
+`oat_milestone_status: reviewing` and a hand-off to
+`oat-project-review-provide` with `code mNN: <ordered phase ids>`. It never
+activates a milestone, registers a delivery, or writes `declared_met`.
+Terminal closeout starts only after the declaration, and when delivery
+coverage already holds at the `pr` step's position it records that step as
+`satisfied_by: { pr: delivery-coverage }`.
 **What it does without asking:** After those questions, the run continues
 until a checkpoint, a blocker or the end of the plan without asking again,

package/assets/docs/workflows/projects/execution/implementation-execution.md CHANGED Viewed

@@ -16,6 +16,10 @@ and updates project state.
   in dependency order.
 - **Task boundary:** each task still produces exactly one bounded, verified
   commit.
+- **Brief phase-units:** in a brief or goal project each phase carries Intent and Exit
+  evidence instead of tasks; execution records are opened in the journal as
+  work happens, and the phase's `**Base:**`/`**Head:**` anchors scope its
+  review.
 - **Prevention boundary:** formatting, declared task verification, and
   applicable cheap checks run before the task commit.
 - **Recovery boundary:** an eligible post-commit defect may produce a separate
@@ -514,6 +518,17 @@ and declare no parallel groups, so lite implementation is always sequential;
 `oat project validate-plan` enforces both rules. Work that needs more than one
 phase should promote to quick rather than declare a parallel group.
+Brief plans may declare parallel groups of taskless phases once those phases
+are concrete and pass the independence test (no shared files, state,
+generated output, fixtures, or services, and no sequential dependency). A
+group member's per-phase review runs before fan-in on
+`EXPECTED_HEAD..<worktree head>`. At fan-in the root writes every member's
+`**Base:**` as the group's fork commit and its `**Head:**` as the member's
+integration head, which is normally a merge commit but may be the last
+cherry-picked commit; review scope checks only the shared fork base and that
+member heads advance in document order. The fan-in anchors govern the
+`pNN-pMM` and `final` review scopes.
 ## Synced projects in worktrees
 A tracked `.oat/projects/synced/<project>.json` record lets every repository

package/assets/docs/workflows/projects/execution/picking-up-projects.md CHANGED Viewed

@@ -30,7 +30,7 @@ instead of `/`):
    summary that `/oat-repo-knowledge-index` writes under
    `.oat/repo/knowledge/`. If that folder has no Markdown file, progress tells
    you to run `/oat-repo-knowledge-index` and stops without a project report,
-   whatever the project's mode; quick, lite and imported projects never
+   whatever the project's mode; quick, lite, brief, goal and imported projects never
    needed the index before, so this can be the first time you see it. Run
    `/oat-repo-knowledge-index` once and then run progress again, or skip to
    step 3: `/oat-project-next` itself does not check for the index (spec-driven
@@ -81,6 +81,25 @@ durable `## Reviews` disposition, and a substantive task; only then do they
 recommend `oat-project-implement`. Recommendations for lite, spec-driven, and
 import projects are unchanged, because the predicate is quick-workflow policy.
+For a brief project, the router counts phase-units from the journal. While the
+brief is not yet approved, it recommends `oat-project-brief`. After
+implementation, while any phase is provisional or not yet accepted with
+`**Status:** completed`, it recommends `oat-project-implement` ("Incomplete
+phase-units remain in the active scope") before every later check. The
+`.oat/state.md` dashboard does not read phase-units, so at the end of
+implementation it prints a note that `oat project status` and
+`oat-project-next` are the authority for brief projects.
+For a goal project, the router also reads the milestone status, any pending
+`oat_goal_recovery` record, the milestone gate carriers, and the delivery
+registry. It sends `aligning` and `delivered` milestones to `oat-project-goal`,
+scopes `oat-project-implement` to the active milestone's phases (or a recovery
+scope), routes the integrated review as `code mNN: …` to
+`oat-project-review-provide`, and routes registration as `deliver mNN` to
+`oat-project-pr-progress`. In the implement phase the dashboard prints a goal
+note that `oat project status` and `oat-project-next` are the authority for
+goal milestone routing.
 ## What travels
 - The project ref carries the complete active artifact tree and its history.