@open-agent-toolkit/cli 0.0.53 → 0.0.55

package/assets/docs/cli-utilities/config-and-local-state.md

@@ -57,6 +57,10 @@ Archive lifecycle settings live here as shared repo config:
 - `archive.s3SyncOnComplete`
 - `archive.summaryExportPath`
 - `archive.wrapUpExportPath`
+- `archive.awsProfile`
+- `archive.awsRegion`
+
+`archive.awsProfile` and `archive.awsRegion` are forwarded as `AWS_PROFILE` / `AWS_REGION` env vars into every `aws` spawn that runs during `oat-project-complete` and `oat project archive sync`. The per-invocation `oat project archive sync --profile <profile>` and `--region <region>` flags override the config for a single run; an `AWS_PROFILE` / `AWS_REGION` already set in the parent shell sits between the flag and the config in precedence (flag > shell env > config). Raw access keys (`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`) remain a shell-environment concern — there is no config plumbing for them.
 
 Tool-pack installation state also lives here as shared repo config:
 

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

@@ -83,6 +83,8 @@ Common keys in `.oat/config.json`:
 - `archive.s3SyncOnComplete` — upload archived projects to S3 during completion
 - `archive.summaryExportPath` — export `summary.md` into a durable tracked directory during completion
 - `archive.wrapUpExportPath` — optional tracked destination for `oat-wrap-up` reports; when unset, the skill falls back to `.oat/repo/reference/wrap-ups`
+- `archive.awsProfile` — optional AWS named profile forwarded as `AWS_PROFILE` to every `aws` invocation in archive flows
+- `archive.awsRegion` — optional AWS region forwarded as `AWS_REGION` to every `aws` invocation in archive flows
 - `tools.<pack>` — whether a bundled tool pack is currently installed in the repo or user scopes after lifecycle reconciliation
 
 Tool-pack state example:
@@ -101,6 +103,8 @@ oat config set archive.s3Uri s3://example-bucket/oat-archive
 oat config set archive.s3SyncOnComplete true
 oat config set archive.summaryExportPath .oat/repo/reference/project-summaries
 oat config set archive.wrapUpExportPath .oat/repo/reference/wrap-ups
+oat config set archive.awsProfile work-sso
+oat config set archive.awsRegion us-east-1
 ```
 
 With those values configured:
@@ -110,6 +114,27 @@ With those values configured:
 - completion also copies `summary.md` into `<archive.summaryExportPath>/20260401-my-project.md`
 - `oat project archive sync` can later pull archive data back down from S3 and materialize the latest snapshot into the local bare archive path `.oat/projects/archived/<project>/`
 - `oat-wrap-up` can write tracked reports into `<archive.wrapUpExportPath>/YYYY-MM-DD-wrap-up-<label>.md`; if the key is unset, the skill uses `.oat/repo/reference/wrap-ups/`
+- every `aws` spawn (preflight `aws sts get-caller-identity`, `aws s3 ls`, `aws s3 sync`) inherits `AWS_PROFILE` / `AWS_REGION` from `archive.awsProfile` / `archive.awsRegion` when the parent shell does not already set them
+
+### Credential resolution
+
+Profile and region resolve with the following precedence per `aws` invocation, highest first:
+
+1. CLI flag passed to `oat project archive sync` (`--profile <profile>`, `--region <region>`)
+2. The parent shell's existing `AWS_PROFILE` / `AWS_REGION` env vars
+3. The repo's shared `archive.awsProfile` / `archive.awsRegion` config
+
+If none of the three are present for a given var, OAT does not inject it — the AWS CLI's own resolution chain takes over.
+
+The `oat project archive sync` flags only override for that single invocation:
+
+```bash
+oat project archive sync --profile work-sso --region us-east-1
+```
+
+`oat-project-complete` does not accept per-invocation flags. Set the shared config (or your shell env) ahead of time if completion needs a specific profile.
+
+Raw access keys (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and friends) remain a shell-environment concern. OAT does not expose config keys for them — set them in your shell before running `oat-project-complete` or `oat project archive sync` and they are inherited by the spawned `aws` process unchanged.
 
 ## Repo-local and user state
 
@@ -137,8 +162,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 +194,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 +216,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.55",
+  "docs-config": "0.0.55",
+  "docs-theme": "0.0.55",
+  "docs-transforms": "0.0.55"
 }