@open-agent-toolkit/cli 0.3.12 → 0.3.14

package/assets/docs/workflows/backlog-and-planning/remote-project-management.md

@@ -0,0 +1,303 @@
+---
+title: Remote Project Management
+description: Safely bind OAT planning records to GitHub, Linear, or Jira through provider-neutral host capabilities.
+---
+
+# Remote Project Management
+
+Remote project management connects an OAT backlog item or project to a remote
+GitHub, Linear, or Jira record. OAT owns policy, previews, approvals, durable
+operation state, and authoritative read-back verification. The host agent owns
+live execution capability discovery.
+
+Remote management is deliberately explicit. It does not turn every plan task
+into a remote issue, run background synchronization, or treat a provider result
+as proof of success.
+
+## Prerequisite
+
+Confirm that file-backed project management is adopted before using a remote
+command:
+
+```bash
+oat pjm doctor --json
+```
+
+Continue only when `adoption.state` is `declared` or `inferred-legacy`. Run
+`oat pjm init` first when adoption is absent or only partially initialized.
+
+> [!WARNING]
+> Running `oat pjm init` again, or running `oat pjm migrate --apply`,
+> currently replaces the `pjm` section of `.oat/config.json` and deletes any
+> `pjm.remote` settings, which hold the remote policy described below. Before
+> you rerun either command, back up `.oat/config.json`. Afterwards, run
+> `git diff .oat/config.json` and restore `pjm.remote` if it was removed.
+
+## Lifecycle operations
+
+The command family is `oat pjm remote`:
+
+```bash
+oat pjm remote intake github:example/repository#123 --to-backlog BL-123 --capability-evidence-stdin --json
+oat pjm remote publish --binding rb_example --capability-evidence-stdin --json
+oat pjm remote refresh --binding rb_example --capability-evidence-stdin --json
+oat pjm remote reconcile --binding rb_example --capability-evidence-stdin --json
+oat pjm remote closeout --project .oat/projects/shared/example --capability-evidence-stdin --json
+oat pjm remote discussion --binding rb_example --limit 20 --capability-evidence-stdin --json
+oat pjm remote resolve relink --binding rb_example github:example/repository#456 --capability-evidence-stdin --json
+oat pjm remote resolve detach --binding rb_example --json
+oat pjm remote resolve recreate --binding rb_example --capability-evidence-stdin --json
+oat pjm remote doctor --json
+oat pjm remote migrate --check --json
+```
+
+Before each provider-contacting example, the host discovers live capability and
+supplies only its bounded provider-neutral evidence on standard input. Mutation
+commands also require the current caller-owned authority evidence requested by
+their live help.
+
+- `intake` reads one remote record into a selected local backlog target and
+  creates the binding.
+- `publish` creates or updates one explicitly selected binding.
+- `refresh` updates retained snapshots without writing remotely.
+- `reconcile` classifies local, remote, and baseline changes before proposing
+  any write.
+- `closeout` prepares a reviewed batch while preserving independent per-binding
+  outcomes.
+- `discussion` returns one bounded, sanitized page as non-persisted evidence.
+- `resolve relink`, `detach`, and `recreate` handle anomalous bindings without
+  discarding identity history or retrying an uncertain create blindly.
+- `doctor` and `migrate` diagnose or repair local records without contacting a
+  provider.
+
+Use `--help` on the live command for current options. JSON output uses one
+versioned envelope and may return a nonzero shell exit for a safely persisted
+`pending`, `needs-review`, `partial`, `uncertain`, or `blocked` outcome.
+
+## Repository-owned policy
+
+Remote policy lives only in the shared repository config at `.oat/config.json`.
+The safe defaults are local operational state, no description publication, and
+read-only authority:
+
+```json
+{
+  "pjm": {
+    "remote": {
+      "schemaVersion": 1,
+      "storage": { "state": "local" },
+      "policy": {
+        "description": "none",
+        "authority": { "default": "read-only" }
+      }
+    }
+  }
+}
+```
+
+Use the config command instead of editing nested values by hand:
+
+```bash
+oat config set pjm.remote.policy.description managed-section --shared
+oat config set pjm.remote.policy.authority.operations.update-fields user-approved --shared
+oat config set pjm.remote.policy.providers.github.authority.operations.create user-approved --shared
+```
+
+Description modes are `none`, `managed-section`, and `replace`. Authority modes
+are `read-only`, `user-approved`, `user-authorized`, and `autonomous`.
+For each operation, OAT resolves the repository operation override, then its
+repository default, then the built-in read-only fallback. A matching provider
+operation override or provider default replaces that repository result and may
+broaden it. Binding defaults and operation restrictions then clamp authority,
+while purpose field grants intersect to narrow the outbound fields. Provider
+configuration never bypasses hard approval floors or the requirement for
+current caller-owned authority evidence; missing, stale, or mismatched evidence
+fails closed. Autonomous configuration is not a background grant.
+
+Current CLI bindings have a fixed intake/source or publish/planning purpose
+and empty per-binding restrictions; no command exposes additional binding
+restriction or purpose-grant setters. These remain internal narrowing layers,
+not extra configurable user controls.
+
+## Live host capability boundary
+
+At operation time, the host agent inspects currently granted MCP or connector
+descriptions for the requested semantic operation and exact account, workspace,
+site, or repository context. If no capable connector is available, it may
+inspect the live help of an already configured provider CLI before the first
+provider-contacting command.
+
+OAT does not store provider tool names, native schemas, captured catalogs,
+executable names, flags, or CLI dialects. The host returns only bounded,
+sanitized capability evidence through `--capability-evidence-stdin`. It must not
+install tools, request credential values, or switch execution surfaces after an
+attempt begins. The CLI may then emit one provider-neutral `externalAction`.
+The host executes that exact action at most once and returns one bounded
+observation with `oat pjm remote operation continue`.
+
+## Content and outbound safety
+
+Inbound provider text is retained only through an allowlist of core fields and
+adapter-approved extensions. If a retained text field triggers a conservative
+sensitive-content signal, OAT suppresses that whole field and marks the
+snapshot incomplete. This is a bounded field-safety rule, not general DLP or
+credential-value parsing.
+
+Every remote create or update consumes only an explicit normalized projection.
+The universal provider-neutral pre-write gate evaluates that projection before
+preview, approval, action, and authoritative read-back. It never scans the
+repository, worktree, Git history, or arbitrary files for secrets. Missing,
+stale, failed, or blocked safety evidence prevents execution.
+
+## Previews, approval floors, and uncertainty
+
+Mutation-capable commands persist and return a preview before execution. The
+preview digest binds the target, normalized fields, remote revision,
+capability, safety result, and effective policy. If any load-bearing input
+changes, the approval is stale.
+
+Fresh approval is required for complete description replacement on create,
+relink, detach, recreate, destructive operations, and promotion to shared
+operational storage.
+
+> [!WARNING]
+> In `replace` description mode, only creating an issue always needs fresh
+> approval; later updates follow your `update-fields` authority, so
+> `user-authorized` or `autonomous` authority can overwrite an issue's
+> description without a person approving it. If someone must review each
+> overwrite, set `pjm.remote.policy.authority.operations.update-fields` to
+> `user-approved`.
+
+`user-approved` authority requires applying the exact persisted preview.
+Higher configured authority cannot bypass floors that the operation enforces.
+
+The host submits a bounded observation with `oat pjm remote operation continue`.
+Only an OAT `ok` envelope after authoritative read-back means success. A
+connector response, process exit, or visible remote change is evidence rather
+than a verdict. If a create or update is uncertain, do not retry it blindly;
+use the recovery guidance in the envelope so OAT can search, relink, recreate,
+or reconcile without producing duplicates.
+
+## Storage and worktrees
+
+> [!WARNING]
+> OAT writes every binding record, including bindings for local projects, under
+> `.oat/repo/pjm/remote/bindings/`, and it does not gitignore that directory, so
+> those records are committed unless you exclude them. Review that directory
+> before committing if tracker links should not appear in the repository.
+
+Bindings are not yet stored with the project or backlog item that owns them;
+the owner-specific routing design is not wired into the current store.
+
+Operational snapshots, journals, batches, and receipts default to a
+repository-fingerprinted directory under the Git common directory:
+`.git/oat/pjm-remote/<repository-fingerprint>/`. All linked worktrees for one
+repository therefore share the same local operational state, while another
+clone gets its own store.
+
+Shared operational storage is opt-in and may expose remote planning content to
+everyone with repository access. It requires a persisted preview and fresh
+approval.
+
+> [!WARNING]
+> Shared storage is meant to be refused for local projects, but the current CLI
+> does not enforce that, so a local project's remote state is committed with
+> everyone else's. Do not combine shared storage with local projects.
+
+Preview with `oat pjm remote storage shared` without
+`--apply`, then use the returned approval digest for the explicit apply. The
+help command describes flags; it does not preview proposed storage changes.
+
+## Offline behavior
+
+OAT can inspect portable bindings, the bounded local snapshot, journals,
+receipts, and pending recovery instructions while offline. `remote doctor` and
+`migrate` are local-only. Provider refresh, publication, reconciliation writes,
+and authoritative verification remain pending or blocked until matching live
+capability evidence is available; offline state never fabricates remote
+freshness or success.
+
+## Related references
+
+- [Configuration](../../reference/configuration.md)
+- [CLI Reference](../../reference/cli-reference.md)
+- [File Locations](../../reference/file-locations.md)
+- [Troubleshooting](../../reference/troubleshooting.md)
+
+## Choosing bindings and policy
+
+A **binding** links one local backlog item or project to one GitHub, Linear, or
+Jira issue. You create a binding in one of two ways: **intake** imports an
+existing tracker issue as a local backlog item, and **publish** creates a
+tracker issue from a local item. Both commands need capability evidence from
+the host agent (see [Live host capability boundary](#live-host-capability-boundary)),
+so in practice you ask your agent to run them through the `oat-pjm-remote`
+skill. OAT creates no binding unless you ask, so local work stays complete
+offline.
+
+| Choice     | Choose it when                          | What you give up                                                                                                              |
+| ---------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| No binding | The item matters only in the repository | Visibility in the tracker                                                                                                     |
+| Intake     | The tracker owns the issue              | Title, description, and priority flow only into the repository; local edits never flow back                                   |
+| Publish    | The work starts locally                 | You need write authority (below). Title, priority, and, if the description policy allows, the description then flow both ways |
+
+- If you maintain an open-source project on GitHub, intake reported issues and
+  publish only the work that maintainers start.
+- If your team plans in Linear or Jira, intake the tickets that agents work on.
+
+### How much of the description is sent
+
+| `pjm.remote.policy.description` | Choose it when                            | What you give up                                                                               |
+| ------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `none` (default)                | The local description is sensitive        | OAT never sends or compares a description. Intake still copies the issue's description locally |
+| `managed-section`               | People also edit the issue in the tracker | OAT owns only the text between its marker comments; if the markers are broken, the write stops |
+| `replace`                       | OAT is the only author of the description | Edits made in the tracker are overwritten (see the replace-mode warning above)                 |
+
+### Who may write, and with what approval
+
+Authority is set with `pjm.remote.policy.authority.default`, or per operation
+under `pjm.remote.policy.authority.operations.<operation>`, in shared config
+only. Before any write, OAT saves a preview of exactly what it would send,
+identified by a digest (a content hash).
+
+| Authority             | Choose it when                                                  | What you give up                                                                           |
+| --------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `read-only` (default) | You only intake and refresh issues                              | All writes to the tracker                                                                  |
+| `user-approved`       | A person must see each exact change                             | One approval per write: the person approves the preview digest within five minutes         |
+| `user-authorized`     | An explicit request such as "publish BL-12 to Linear" is enough | Reviewing each change before it is sent                                                    |
+| `autonomous`          | An OAT workflow writes as one of its steps                      | Most live oversight. The workflow's evidence must still match the exact operation and item |
+
+Deleting, recreating, relinking, or detaching a binding, and creating an issue
+in `replace` mode, always need `user-approved` approval, whatever you configure.
+
+- Start with `read-only` and intake.
+- When OAT should create and maintain issues, set both `create` and
+  `update-fields` to `user-approved`.
+- Choose `user-authorized` or `autonomous` only when you deliberately accept
+  that a request or a workflow step authorizes the write without a per-change
+  review.
+
+A provider section, `pjm.remote.policy.providers.<github|linear|jira>`, is unset
+by default and then inherits the repository policy. If one policy fits every
+tracker, leave it unset. If trust differs, for example a private Linear
+workspace versus public GitHub, set a provider policy, but review it carefully:
+it replaces the repository value and can grant more than the repository policy
+does. A provider `authority.default` also replaces the repository's
+per-operation settings, so repeat any per-operation limits you still need under
+that provider.
+
+### Where operation state is stored
+
+Snapshots and journals (OAT's copy of each issue as last read, and its log of
+remote operations) are stored locally by default, under the Git directory.
+Every worktree of one clone shares them; other clones do not see them.
+
+- Keep `local` storage unless teammates need each other's operation logs, for
+  example to recover a create whose outcome was unclear.
+- If you do switch to shared storage, review what it exposes first: it puts
+  remote content and operation journals into Git history, and it does not move
+  existing records. Do not use it with local projects (see the warning above).
+
+Local storage does not make binding records private, because bindings are
+always written to the repository as described in
+[Storage and worktrees](#storage-and-worktrees).

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

@@ -0,0 +1,114 @@
+---
+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.
+---
+
+# Choose a Workflow
+
+Workflows are the part of OAT for tracked, resumable work. They are optional and sit on top of the CLI and provider sync.
+
+Before you choose, read [Approvals and Automation](approvals-and-automation.md): it shows, for each mode, where a person approves, what an agent does without asking, and when OAT pushes or opens a pull request.
+
+Use this section when you want explicit project artifacts, stable task IDs, review loops, and resumable execution across longer-running work. The workflow layer is optional; stay with direct CLI usage when the task is straightforward and the overhead of project artifacts would outweigh the value.
+
+## Where to go from here
+
+- [Brainstorm Before Choosing a Workflow](../skills/brainstorm.md) - Not sure what the work is yet? Talk it through with `/oat-brainstorm` first; it ends with an answer, a document, or a handoff to an idea, a backlog item, or a project.
+- [Ideas Workflow](ideas/index.md) - Lightweight idea capture, brainstorming, and promotion into tracked projects when the work becomes concrete.
+- [Projects](projects/index.md) - Lifecycle, artifacts, reviews, PR flow, and repository analysis.
+- [Wave Workflows](waves/wave-workflows.md) - Program-level coordination for executing a corpus of external plans as ordered wrapper projects.
+- [Skills](../skills/index.md) - Workflow-oriented skill discovery and use-case routing.
+
+## What This Section Is
+
+This section explains when workflow mode is worth the overhead, how OAT projects move through lifecycle phases, and how ideas, skills, reviews, and PR flow fit into that model.
+
+## Who It's For
+
+- Teams doing multi-session or multi-phase work that benefits from tracked artifacts
+- Users who want explicit discovery, planning, implementation, and review state
+- Repos that need a repeatable human-in-the-loop execution model
+
+## When To Use Workflow Mode
+
+Use workflow mode when:
+
+- the work spans multiple sessions or contributors
+- you want explicit discovery, plan, implementation, and review artifacts
+- you need stable task sequencing and resumable execution
+- you want human-in-the-loop checkpoints around risky transitions
+
+Stay with direct CLI usage when:
+
+- the task is straightforward and bounded
+- you mainly need provider sync or a utility command
+- the overhead of project artifacts would outweigh the value
+
+## Workflow Modes In Practice
+
+- 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
+- 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
+
+## Start Here
+
+- Use [Skills](../skills/index.md) when you want task-oriented guidance on the most useful workflow skills.
+- Go to [Workflow & Projects](projects/index.md) when you need the lifecycle and artifact model in detail.
+- Use [Ideas](ideas/index.md) when the work is still exploratory.
+
+## Common Tasks
+
+- Capture or refine early work in [Ideas](ideas/index.md).
+- Understand how tracked projects progress in [Workflow & Projects](projects/index.md).
+- Learn the artifact contract in [Artifacts](../reference/project-artifacts.md).
+- Understand review and PR expectations in [Reviews](projects/reviews/index.md) and [PR Flow](projects/closeout/pr-flow.md).
+
+## Go Deeper
+
+- [Skills](../skills/index.md) - Workflow-oriented skill discovery and use-case routing.
+- [Ideas](ideas/index.md) - Idea capture, refinement, and promotion flows.
+- [Workflow & Projects](projects/index.md) - Lifecycle, artifacts, reviews, PR flow, and repository analysis.
+
+## Which mode should I choose?
+
+A mode decides how much planning happens before any code is written. You pick
+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                                                                                                               |
+
+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,
+`oat-project-complete` opens a pull request without asking when
+`workflow.createPrOnComplete` is `true`. Project files of a project in the
+default _synced_ scope are also pushed to `origin` whenever a skill saves
+them; see [Approvals and Automation](approvals-and-automation.md#what-oat-does-without-asking).
+
+Decide by how clear the requirements are and how risky the design is, not by
+how many tasks the work has. A large but well-understood change can still be a
+quick project. If you run `oat project new` yourself without `--mode`, it
+creates a spec-driven project, but it only creates the files; the entry skill
+is what holds the planning conversation, so start with the skill.
+
+- If you are a solo developer fixing one well-understood bug, choose lite, or
+  skip the project entirely if you will not need to resume or review it later.
+  Lite ends by pushing your current branch and opening a pull request without
+  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 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
+  debated, choose spec-driven so discovery and design are agreed before
+  implementation starts.
+- If you already have an approved plan from another tool, import it rather than
+  repeating discovery and design.

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

@@ -11,13 +11,13 @@ Ideas are intentionally lighter than projects: they are usually gitignored, pers
 
 ## Not Sure If It's an Idea Yet?
 
-> **Direct entry to `oat-idea-ideate` requires an existing target** — either a tracked idea record or an unchecked scratchpad seed in `{IDEAS_ROOT}/scratchpad.md`. For blank-slate brainstorms, route to [`oat-brainstorm`](../../cli-utilities/tool-packs.md) instead.
+> **Direct entry to `oat-idea-ideate` requires an existing target** — either a tracked idea record or an unchecked scratchpad seed in `{IDEAS_ROOT}/scratchpad.md`. For blank-slate brainstorms, route to [`oat-brainstorm`](../../getting-started/tool-packs.md) instead.
 
-If the thought is still pre-shape — you don't know whether it should land as a quick scratchpad note, a captured idea, a scoped backlog item, or a full project — start with [`oat-brainstorm`](../../cli-utilities/tool-packs.md). It's the project-independent brainstorming entry point: Hard Activation fires only on the `brainstorm` verb ("let's brainstorm", "brainstorm this", "can we brainstorm X", "help me brainstorm X", or `/oat-brainstorm`); ambiguous exploratory phrasing answers conversationally without the banner and offers structured mode only after sustained exploration. Once entered, it runs a structured design conversation and routes the outcome into the right destination (including this ideas workflow if that's where the brainstorm lands). Use ideas directly when you already know the work is "an idea worth tracking" and you want to capture or extend one without going through the dispatcher.
+If the thought is still pre-shape — you don't know whether it should land as a quick scratchpad note, a captured idea, a scoped backlog item, or a full project — start with [`oat-brainstorm`](../../getting-started/tool-packs.md). It's the project-independent brainstorming entry point: Hard Activation fires only on the `brainstorm` verb ("let's brainstorm", "brainstorm this", "can we brainstorm X", "help me brainstorm X", or `/oat-brainstorm`); ambiguous exploratory phrasing answers conversationally without the banner and offers structured mode only after sustained exploration. Once entered, it runs a structured design conversation and routes the outcome into the right destination (including this ideas workflow if that's where the brainstorm lands). Use ideas directly when you already know the work is "an idea worth tracking" and you want to capture or extend one without going through the dispatcher.
 
 ## Contents
 
-- [Lifecycle](lifecycle.md) - Capture, ideate, refine, and summarize an idea before promotion or discard.
+- [Ideas Lifecycle](lifecycle.md) - Capture, ideate, refine, and summarize an idea before promotion or discard.
 
 ## When Ideas Fit Better Than Projects