@open-agent-toolkit/cli 0.0.53 → 0.0.54

package/assets/docs/cli-utilities/configuration.md

@@ -137,8 +137,9 @@ Workflow preferences let power users answer repetitive confirmation prompts once
 
 ### Preference keys
 
-All seven workflow preference keys live under the `workflow.*` namespace:
+All eight workflow preference keys live under the `workflow.*` namespace:
 
+- `workflow.designMode` — `collaborative`, `selective`, or `draft`. Default design interaction mode. `selective` applies only to full `oat-project-design`; quick-start lightweight design treats it as collaborative because quick-start keeps the smaller collaborative/draft choice.
 - `workflow.hillCheckpointDefault` — `every` or `final`. Default HiLL checkpoint behavior in `oat-project-implement`: pause after every phase or only after the last phase. When unset, the skill prompts.
 - `workflow.archiveOnComplete` — boolean. Skip the "Archive after completion?" prompt in `oat-project-complete`. When unset, the skill prompts.
 - `workflow.createPrOnComplete` — boolean. Skip the "Open a PR?" prompt in `oat-project-complete`; when true, completion auto-triggers PR creation. When unset, the skill prompts.
@@ -168,12 +169,15 @@ oat config set workflow.postImplementSequence pr --user
 oat config set workflow.reviewExecutionModel subagent --user
 oat config set workflow.autoReviewAtHillCheckpoints true --user
 oat config set workflow.autoNarrowReReviewScope true --user
+oat config set workflow.designMode selective --user
 
 # Shared repo: team decision for this repo
 oat config set workflow.createPrOnComplete false --shared
+oat config set workflow.designMode collaborative --shared
 
 # Repo-local: personal override for this repo (default when no flag)
 oat config set workflow.hillCheckpointDefault every
+oat config set workflow.designMode draft
 ```
 
 Default (no flag) targets `.oat/config.local.json` for workflow keys. Pass at most one of `--user`, `--shared`, or `--local`. Structural keys (`projects.root`, `worktrees.root`, `git.*`, `documentation.*`, `archive.*`, `tools.*`) are still shared-only regardless of flag.
@@ -187,6 +191,7 @@ Not every workflow preference belongs at user level, even though "set once, appl
 Some preferences are **genuinely personal** — their correct value is the same for you regardless of which repo you're in. These are safe to set at `--user`:
 
 - `workflow.hillCheckpointDefault` — your personal tolerance for mid-implementation interruption
+- `workflow.designMode` — your preferred full-design interaction style. Set `selective` when you usually want low-risk sections drafted silently but high-risk sections reviewed live.
 - `workflow.reviewExecutionModel` — depends on your provider environment (Claude Code, Cursor, Codex), not the repo
 - `workflow.autoReviewAtHillCheckpoints` — your preference for automatic lifecycle review at HiLL checkpoints. Shared/local config can still override this when a repo should behave differently.
 - `workflow.autoNarrowReReviewScope` — pure personal workflow preference, no per-repo interaction

package/assets/docs/workflows/projects/design-modes.md

@@ -0,0 +1,108 @@
+---
+title: Design Modes
+description: 'How oat-project-design balances section-by-section collaboration, selective review, and draft-and-review.'
+---
+
+# Design Modes
+
+`oat-project-design` can run full spec-driven design in three interaction modes:
+
+- **Collaborative**: every design section is drafted, presented, confirmed, and then the skill moves to the next section.
+- **Selective collaborative**: the skill drafts every section, but only presents sections that need live review. Routine sections are written silently and recapped at the final review gate.
+- **Draft-and-review**: the skill drafts the full design up front and the user reviews the committed file once at the end.
+
+The default recommendation is collaborative when in doubt. Draft-and-review is never the picker default unless it was selected explicitly through an argument, environment variable, or config preference.
+
+## Collaborative
+
+Use collaborative mode when:
+
+- the design is small enough that confirming every section is reasonable
+- discovery exposed uncertainty across most of the design
+- the repo has sparse knowledge/docs grounding
+- you want maximum user control over the design narrative
+
+The agent does not write `design.md` section-by-section. It drafts sections in conversation, asks for confirmation, and writes the assembled file only after all sections are approved.
+
+## Selective Collaborative
+
+Selective collaborative mode sits between collaborative and draft-and-review. It keeps live review for high-risk or uncertain sections, while letting routine sections move quietly into the design document.
+
+Before drafting, the skill runs a selective review pass and prints a **Section Review Plan**:
+
+| Section      | Classification             | Meaning                                                           |
+| ------------ | -------------------------- | ----------------------------------------------------------------- |
+| `needs-eyes` | Presented for confirmation | The section has at least one risk or uncertainty signal.          |
+| `routine`    | Drafted silently           | The section follows existing patterns and has adequate grounding. |
+
+The user gets one cheap override moment before drafting: they can elevate any `routine` section to `needs-eyes`.
+
+### Needs-eyes Signals
+
+The selective review pass has a conservative bias: any one needs-eyes signal marks the section `needs-eyes`.
+
+High-risk-by-default sections are always `needs-eyes`:
+
+- Overview + Architecture
+- Security Considerations
+- Performance Considerations
+- Error Handling
+- Migration Plan
+
+Other signals include:
+
+- discovery open questions or user-flagged concerns touching the area
+- three or more requirements concentrated in the section
+- new public API, CLI, config, defaults, or workflow semantics
+- cross-module boundaries not already described in repo architecture docs
+- novel patterns not present in repo conventions or stack docs
+- new dependencies, providers, services, storage models, permission boundaries, or integrations
+- missing or thin grounding context for the section
+
+If every section is `needs-eyes`, selective collaborative collapses into full collaborative and the skill explains why. If no section is `needs-eyes`, the skill still forces Overview + Architecture to `needs-eyes` so the user sees the framing.
+
+### Final Review Recap
+
+At the user-review gate, selective collaborative lists sections drafted without live confirmation:
+
+```text
+Drafted without live confirmation: Testing Strategy, Deployment Strategy.
+Please review those sections especially carefully in the committed file.
+```
+
+This keeps the silent path visible without adding live prompts for low-risk sections.
+
+## Draft-and-review
+
+Use draft-and-review when:
+
+- you explicitly want a full draft before reacting
+- the context is non-interactive
+- a persisted preference or command override selected draft mode
+
+In draft-and-review mode, the user-review gate is the only live interaction point.
+
+## Quick-start Parity
+
+Selective collaborative mode is only available in full spec-driven design through `oat-project-design`.
+
+Quick-start lightweight design keeps the smaller two-choice model:
+
+- collaborative lightweight design
+- draft-and-review lightweight design
+
+The quick-start section set is intentionally small and already curated for relevance, so selective review rarely saves enough prompts to justify another picker branch. If a quick project is promoted to spec-driven, selective collaborative becomes available when it enters full `oat-project-design`.
+
+## Configuration
+
+Use `workflow.designMode` to persist a personal or repo preference:
+
+```bash
+oat config set workflow.designMode selective --user
+oat config set workflow.designMode collaborative --shared
+oat config set workflow.designMode draft --local
+```
+
+Valid values are `collaborative`, `selective`, and `draft`.
+
+Runtime non-interactive signals still win over this preference. If `OAT_NON_INTERACTIVE=1` is set, design runs in draft-and-review mode so automation does not block on prompts.

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

@@ -29,6 +29,7 @@ This sub-section is the deep technical surface for how tracked OAT projects exec
 ## Go Deeper
 
 - [Lifecycle](lifecycle.md) - End-to-end flow from discovery through completion.
+- [Design Modes](design-modes.md) - How full design balances collaborative, selective collaborative, and draft-and-review interaction.
 - [HiLL Checkpoints](hill-checkpoints.md) - Human-in-the-Loop Lifecycle configuration and approval behavior.
 - [Artifacts](artifacts.md) - What lives in `state.md`, `discovery.md`, `plan.md`, `implementation.md`, and related files.
 - [State Machine](state-machine.md) - Lifecycle and review status transitions across a project.

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

@@ -23,6 +23,8 @@ OAT lifecycle order:
 
 **Shortcut:** `oat-project-next` reads project state and invokes the correct next skill automatically — use it instead of remembering which skill comes next. Complements `oat-project-progress` (which is read-only diagnostic).
 
+Full spec-driven design supports three interaction modes: collaborative, selective collaborative, and draft-and-review. Selective collaborative drafts routine sections silently and presents high-risk or uncertain sections for live review. Quick-start lightweight design stays simpler and offers only collaborative or draft-and-review. See [Design Modes](design-modes.md) for details.
+
 ## Quick Look
 
 - What it does: explains the end-to-end lifecycle for tracked OAT projects, including alternate quick and import lanes.
@@ -131,6 +133,8 @@ flowchart LR
   I --> R["Review"] --> PR["PR"] --> Doc["Docs (optional)"] --> C["Complete"]
 ```
 
+During the Design step, `oat-project-design` asks how to work through the document unless a mode was selected by argument, environment, or `workflow.designMode`. The three full-design choices are collaborative, selective collaborative, and draft-and-review.
+
 ### Quick lane
 
 ```mermaid
@@ -143,6 +147,8 @@ flowchart LR
   QI --> QR["Review / PR"]
 ```
 
+Quick lane lightweight design intentionally keeps a smaller collaborative/draft choice. Selective collaborative becomes available only after promotion into the full spec-driven design lane.
+
 ### Import lane
 
 ```mermaid

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.0.53",
-  "docs-config": "0.0.53",
-  "docs-theme": "0.0.53",
-  "docs-transforms": "0.0.53"
+  "cli": "0.0.54",
+  "docs-config": "0.0.54",
+  "docs-theme": "0.0.54",
+  "docs-transforms": "0.0.54"
 }