@open-agent-toolkit/cli 0.3.13 → 0.3.15

package/assets/docs/skills/brainstorm.md

@@ -0,0 +1,77 @@
+---
+title: Brainstorm Before Choosing a Workflow
+description: Explore a problem conversationally, compare approaches, and choose an explicit destination without starting implementation.
+---
+
+# Brainstorm Before Choosing a Workflow
+
+## oat-brainstorm
+
+**Invocation:** `/oat-brainstorm` is the reliable way to start it, or ask,
+“Let's brainstorm how to make large imports easier to recover without changing
+the UI yet.” These are agent instructions; Codex can use `$oat-brainstorm`. An
+explicit request to brainstorm activates the mode; an ordinary review,
+debugging session, or status check should not be taken over automatically.
+Looser phrasing such as “I've been thinking about…” gets an ordinary
+conversational answer; after two such exploratory turns the agent offers once
+to switch into structured brainstorm mode. If your opening request says the
+work should become several projects, the skill frames the conversation around
+the child projects and then hands off to `oat-project-split`, which creates
+them.
+
+**Prerequisites:** A topic worth exploring. Needs an active OAT project:
+optional. No OAT project (a tracked unit of work under `.oat/projects/`) or
+repository setup is required to start the conversation; if a project is
+active, the skill can offer to fold the result into it. Installed tool packs
+(groups of OAT skills you install with `oat tools install`) and repository
+capabilities determine which destinations are available later.
+
+**Example scenario:** Support keeps helping customers recover failed uploads,
+but the team does not yet know whether to improve resumability, error
+messages, or operating procedures. Explore the constraints and compare a few
+approaches before deciding whether this needs a project at all. When you say
+you are done, the skill offers the destinations available in your setup; you
+might pick “Doc-to-path,” confirm `docs/brainstorms/import-recovery.md`, and
+get a Markdown write-up of the approaches, the chosen direction, and the open
+questions at that path, with nothing committed.
+
+The skill asks focused questions, presents alternatives with trade-offs, and
+helps establish a recommended direction. It does not treat brainstorming as
+approval to implement code or scaffold a specification. If an active project
+is relevant, it can offer to fold the result into that project or preserve it
+as a reference; an independent idea remains an option. Fold-back writes the
+synthesis into the project's design, discovery, or plan file and commits that
+one file on your current branch (for a synced project, one whose files live in
+a separate project checkout, it pushes that checkout with `oat project push`
+instead). Saving a brainstorming reference file under the active project also
+commits or pushes that file. Promoting to a new project runs
+`oat project new`, which scaffolds the project and makes it your active
+project, and then writes a completed `discovery.md` (or, for a lite project,
+fills in its `plan.md`). Capturing a new idea also sets it as your active
+idea in local OAT config. Each destination is confirmed before anything is
+written.
+
+**What it does without asking:** During the conversation it only reads: it
+checks which tool packs are installed and whether a project is active. If the
+topic is visual it offers, as a separate question, to start a local
+browser-based visual companion; nothing starts unless you accept, and once
+accepted it runs a small local Node server and keeps its session files under
+`.oat/brainstorm/` (or `~/.oat/brainstorm/` at user scope). Nothing else is
+written until you choose a destination and confirm its name, path, or target
+file. After that confirmation the skill writes the destination and, for
+fold-back or a project reference file, commits (or pushes, for a synced
+project) without a further prompt. It does not write code or start the next
+project phase.
+
+**Expected output:** A shared understanding of the problem, candidate
+approaches, and a confirmed next step. Depending on installed packs and your
+choice, the result can be a closing summary in the conversation (no file), a
+Markdown document at a path you name, a new or extended idea (`ideas` pack), a
+backlog item (`project-management` pack), a new OAT project, or an update to
+the active project (`workflows` pack). The destination is confirmed, not
+selected merely because a pack is installed.
+
+**Next step:** Choose where the result belongs and approve that handoff. For
+an unresolved technical assumption, use [research](research.md) first. For a
+direction ready to plan, choose the appropriate project workflow rather than
+treating the brainstorming conversation as an executable plan.

package/assets/docs/skills/diagnostics.md

@@ -0,0 +1,56 @@
+---
+title: Diagnose Your OAT Setup
+description: Inspect OAT configuration, repository adoption, instructions, documentation, and installed tools before choosing a repair.
+---
+
+# Diagnose Your OAT Setup
+
+## oat-doctor
+
+**Invocation:** `/oat-doctor` for the diagnostic sweep, or
+`/oat-doctor --summary` for the compact tools/dashboard view. These are agent
+instructions rather than shell commands; Codex uses `$oat-doctor`. The skill
+is explicit-invocation only, so use the slash or `$` form rather than relying
+on the agent to pick it when you describe the problem. Summary mode is not a
+shortened run of every diagnostic area.
+
+**Prerequisites:** Access to the repository and the OAT CLI available as
+`oat` on your PATH. Needs an active OAT project: no. An uninitialized
+repository can still receive bootstrap guidance; missing adoption (the
+repository has not been set up for that OAT feature yet) is a finding, not
+evidence that all checks passed.
+
+**Example scenario:** A teammate installed a tool pack but cannot see its
+skills in their provider. Run the full doctor sweep to distinguish installed
+tools, configuration, and provider-instruction issues before reinstalling
+anything. Pick the tools area when the report asks which area to explore, then
+approve or run the fix it names. Use summary mode
+later when you only need the tools/dashboard snapshot.
+
+The full sweep covers configuration, project-management adoption, agent
+instructions, documentation, and tools. The skill interprets diagnostic
+findings rather than assuming a nonzero diagnostic exit means the entire tool
+is broken. After the report, it asks which area to explore further (an area,
+`all`, or `done`) and repeats until you choose `done`. Inspection is read-only
+by default. In an interactive run, a specifically approved, supported repair
+command can be executed once; a general request to diagnose is not approval
+for updates, installation, or synchronization. Non-interactive and report-only
+runs stop at the report.
+
+**What it does without asking:** It runs read-only `oat` commands with JSON
+output and reads configuration and instruction files. It writes, deletes, and
+commits nothing, and starts no subagents. It runs a repair only after you
+approve that exact command, and only if the command is one of `oat config set`,
+`oat config unset`, `oat config adopt`, `oat pjm init`,
+`oat instructions sync`, `oat tools update`, or `oat tools install`. It never
+runs any other command, such as `oat sync` to refresh provider views; those
+commands, and hand-offs to other skills, are yours to run.
+
+**Expected output:** A diagnostic report explaining what is healthy, what is
+missing or inconsistent, and which bounded action could address it. A report
+does not itself establish that a proposed repair ran or that the provider has
+reloaded the result.
+
+**Next step:** Approve the exact repair you want, or investigate the reported
+area separately. After a repair, rerun the relevant check and verify the
+original symptom rather than relying only on command completion.

package/assets/docs/{workflows/skills → skills}/explainer-kit.md

@@ -192,3 +192,124 @@ oat tools install workflows
 
 The adapter checks the installed canonical core path and compatible version
 before reading OAT configuration. It never falls back to a source checkout.
+
+## explainer-kit
+
+**Invocation:** `/explainer-kit` is the reliable way to start it (Codex:
+`$explainer-kit`); asking for the skill by name usually works too. Then give
+it a recipe, inputs, and an output folder, for example: “Use explainer-kit
+with the engineer-tour recipe,
+`--inputs /abs/path/docs/architecture.md /abs/path/docs/api-flows.md`, and
+`--out /abs/path/explainers/api-tour`.” Use absolute paths: the core's
+scripts run from the installed skill directory, so a relative path would
+resolve there instead of in your repository. This is an agent instruction,
+not a shell command. The core requires explicit inputs and an output
+destination: choose one source mode, `--project`, `--inputs`, or
+`--fact-base`, rather than relying on an OAT active-project pointer.
+
+**Prerequisites:** Node.js on your PATH (every stage runs the bundled `.mjs`
+scripts) and the core installed from the `utility` tool pack
+(`oat tools install utility --scope user`), plus accessible inputs, a
+recipe, and a writable output destination. Needs an active OAT project: no.
+`--inputs` reads only `.md`, `.txt`, `.html`, and `.json` files; any other
+file in an input directory, such as `.ts` or `.py` source, is skipped without
+a warning, and a directory holding only source code fails bundling because no
+facts were collected. If you supply a fact base, it must be an explainer-kit fact-base
+JSON file that passes the bundled schema and contains the evidence the
+explainer needs; the renderer is not a substitute for missing research. Theme
+selection is resolved before the artifact bundle is materialized; with no
+theme, the skill writes the default `clean-neutral` theme file first.
+
+**Example scenario:** A teammate will take over an API module next week. Give
+the skill the module's architecture and design documents (Markdown, text,
+HTML, or JSON) so it can produce an engineer tour grounded in those
+documents. `--inputs` reads only `.md`, `.txt`, `.html`, and `.json` files;
+source-code files in a directory are skipped, so describe the code in
+documents or supply a prepared fact base. Choose an output folder you can
+review before sharing; generating an HTML file is not permission to publish
+it.
+
+**What it does without asking:** It writes everything into the run folder you
+named with `--out`: the fact base and claim ledger under `source/`, the
+resolved theme, the authored `site/index.html`, verification results under
+`qa/`, and finally `manifest.json`. After bundling, it shows a short summary
+of the prepared facts so you can correct the scope before it writes the page.
+Verification uses a host browser or the bundled Playwright probe when one is
+available, to take screenshots. If bundling reports that a satisfied run
+already exists (`reuse: true`), it returns that run unchanged. It does not
+publish, commit, or push anything.
+
+**Expected output:** A self-contained HTML explainer and its supporting fact
+base, claim ledger, resolved theme, and verification record. Inspect the
+verification outcome, not just whether the file opens. `built` means the
+browser and visual checks passed; `built-needs-review` means
+the usable artifact still needs review. Missing visual capability or a
+failed verification must not be reported as a visual pass.
+
+**Next step:** Review the content and available verification evidence, resolve
+remaining issues, then share the artifact through an explicitly chosen
+channel. For OAT artifact binding and repository defaults, use the adapter
+below rather than making the core infer local configuration.
+
+## oat-explainer-kit
+
+**Invocation:** `/oat-explainer-kit` is the reliable way to start it (Codex:
+`$oat-explainer-kit`), for example: “/oat-explainer-kit generate a project
+explainer from this project's approved planning artifacts.” Asking for the
+skill by name usually works too. Name the recipe you want:
+`project-explainer` (after planning), `project-recap` (after
+implementation), or `program-recap` (for a multi-wave program). This request
+is not a terminal command or a promise of a particular CLI flag. OAT
+lifecycle skills also call the adapter automatically at the points listed in
+[OAT lifecycle callers](#oat-lifecycle-callers).
+
+**Prerequisites:** Node.js on your PATH, a compatible `explainer-kit` core
+from the `utility` tool pack (`oat tools install utility --scope user`), and
+this adapter from the `workflows` pack. If the core is missing or too old,
+the adapter stops and prints the install or update command. Needs an active
+OAT project: for `project-explainer` and `project-recap`, yes. Those recipes
+require the project to be the active OAT project (`oat project open <name>`)
+and read its lifecycle artifacts (planning files such as `plan.md`,
+`design.md`, and `spec.md`; for a recap also the completion, summary, and
+project-log records). A repository-level run with a fact base you supply needs no active
+project; its output goes to `.oat/repo/reference/explainers/`.
+
+**Example scenario:** A project has approved planning artifacts, and you need
+to explain the chosen scope and approach to a teammate before implementation
+starts. Make it the active project with `oat project open <name>`, then ask
+for the `project-explainer` recipe. Let the adapter bind those OAT artifacts
+and repository defaults, then use the core to generate the explainer; open
+the resulting `site/index.html` under `<project>/explainers/<run-slug>/` and
+check its verification outcome before sharing it. Do not ask it to present
+planned capabilities as already shipped.
+
+The adapter checks the installed core before resolving OAT configuration.
+It owns source binding, intent, output placement, and defaults; the core owns
+the reusable artifact-generation pipeline. This boundary keeps a project
+explainer grounded in its planning evidence and a recap grounded in its
+actual implementation evidence rather than treating the two as equivalent.
+
+**What it does without asking:** It checks the installed core, then resolves
+whether to generate. With the `workflow.explainers.*` preference set to
+`always` or `never` it decides without asking; with the default `ask` it asks
+once in an interactive run. Before generating, it records that generate or
+skip decision in the project's `state.md` (the project's status file);
+later runs reuse the recorded decision instead of asking again. It then
+writes the run folder (fact base, page, verification results, and manifest)
+under the output path below. If a run fails, an interactive run asks you to
+retry or skip and records a skip in `state.md`. Lifecycle calls never prompt.
+It does not commit, push, or publish the explainer.
+
+**Expected output:** The core explainer bundle under
+`<project>/explainers/<run-slug>/` (project recipes) or
+`.oat/repo/reference/explainers/` (program or repository runs), with its
+verification outcome preserved. The adapter also records the generate or
+skip decision in the project's `state.md`; later runs reuse that decision
+instead of asking again. A lifecycle call can produce it without an
+interactive prompt, but unattended generation does not erase missing
+evidence or upgrade a needs-review outcome.
+
+**Next step:** Inspect the explainer and verification record, then return to
+the relevant planning, implementation, or closeout workflow. An explainer
+helps communicate a decision or outcome; it does not itself approve a plan,
+complete a project, or publish a recap.