@open-agent-toolkit/cli 0.3.13 → 0.3.14

package/assets/docs/skills/repo-improve.md

@@ -0,0 +1,254 @@
+---
+title: Repo Improve
+description: 'Turn repository audits, maintainability reviews, and backlog sources into standalone external implementation plans.'
+---
+
+# Repo Improve
+
+Use `oat-repo-improve` when the desired output is an executable implementation plan rather than another analysis report. Every successful run writes one or more standalone plans under `.oat/repo/reference/external-plans/`.
+
+## Choose a source
+
+| Source                 | Use it when                                                                                                                                          |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Repo audit             | You need fresh repository reconnaissance and vetted improvement findings.                                                                            |
+| Maintainability review | A file-backed `oat-repo-maintainability-review` already identifies candidates. Improve verifies selected evidence without repeating the broad audit. |
+| Backlog review         | A living backlog review and optional priority alignment already establish value, dependencies, and sequencing.                                       |
+| Backlog directory      | You want to start from active items. Substantive backlogs should pass through backlog review and alignment before plan generation.                   |
+| Backlog item           | One existing item needs enough repository investigation to become executable.                                                                        |
+
+With no source argument, the skill probes for available review and backlog artifacts, annotates all five options, and asks which source to use.
+
+## Set repo-audit boundaries
+
+Fresh repo audits exclude agent-configuration directories from findings and plan candidates by default. The canonical default directory names are `.agents/`, `.claude/`, `.codex/`, and `.cursor/` at any depth. These locations commonly contain provider configuration, generated views, or externally sourced skills rather than the product surfaces being reviewed.
+
+Before reconnaissance, improve shows that default and asks whether to:
+
+- Keep all four exclusions.
+- Include selected directory names.
+- Include all four directory names.
+
+It then asks whether any other repo-relative directories should be excluded and suggests other recognizable provider directories when present. The resolved scope is shown before work begins and is applied consistently to direct searches and delegated audit lanes.
+
+These are findings exclusions, not absolute read prohibitions. Improve may read bounded instruction, convention, or intent files inside an excluded directory to understand the repository, but it does not turn those files into findings or plan candidates unless the user includes or explicitly targets that directory. A file cited by an artifact-backed source can still be verified after scope confirmation; symlinked provider views are never followed outside the repository.
+
+## Output boundary
+
+External plans are not canonical OAT project `plan.md` files. They contain self-contained context, scope, steps, verification, done criteria, and STOP conditions, but no canonical OAT phase/task IDs or lifecycle bookkeeping. External execution-readiness metadata is a separate thing and is carried deliberately: it describes whether the plan's own prerequisites have merged, not how an OAT project is moving through phases.
+
+After generation, choose either execution path:
+
+- Execute a plan directly as a standalone handoff.
+- Run `oat-project-import-plan <external-plan-path>` to preserve and normalize one plan for tracked OAT execution.
+
+Project-sized candidates are split when possible. If inseparable work needs multiple design decisions or lacks one coherent verification boundary, improve recommends an OAT project workflow instead of emitting a mega-plan.
+
+## Plan readiness and execution readiness
+
+Improve scores candidates on two independent axes. A candidate is plan-ready when it is understood well enough to write a self-contained executable plan, and execution-ready when every hard dependency it names has already merged.
+
+A blocked candidate is still planned. Rather than dropping work whose prerequisite has not landed, improve writes the plan and records the block:
+
+- `oat_execution_status` is `READY` or `BLOCKED` in plan frontmatter.
+- A typed `## Dependencies` table marks each row `Hard`, `Soft`, or `Satisfied`, and every `Hard` row names the state that would unblock it.
+- `## Landing-event impact` records what to re-anchor when a named PR or project lands, and `## Revalidation Before Execution` records when the plan must be re-checked against live state.
+
+Plan provenance is recorded as two separate SHAs: `oat_external_plan_commit` is the full SHA of the `HEAD` whose content was actually inspected, and `oat_external_plan_main_commit` is the fetched `origin/main` or merge-base used only for comparison. They may differ, and normally do when planning happens on a branch.
+
+Plans written before this contract landed are read in legacy mode: a short SHA, a missing comparison SHA, missing sections, and a missing status (read as `READY`) are all accepted, and those plans are never rewritten.
+
+## Optional tracking
+
+Plans are always the primary output. Tracking is optional and source-aware:
+
+- `--backlog-items` creates missing PJM (OAT project management, the repository backlog under `.oat/repo/pjm/`) items for repo-audit or maintainability-review plans. Backlog-backed sources reuse their existing items; they add `external_plans` reverse links on every successful run, with or without this modifier.
+- `--issues` previews one GitHub issue per plan, checks repository visibility and sensitive content, and requires explicit confirmation before publication. It is useful as a fallback when PJM is not installed.
+- Request both modifiers explicitly to create both forms. Neither implies the other.
+
+Failure to publish a backlog item or issue does not invalidate a successfully written plan; the skill reports partial tracking results precisely.
+
+## Orchestration
+
+Full repository audits use bounded read-only reconnaissance while the root
+agent retains classification, vetting, prioritization, cross-lane synthesis,
+and plan writing. Plan writes never move below the caller's model class — a
+parallelized author runs on the caller's model and every plan is
+caller-reviewed before publication or wave composition; the
+`keeps external-plan writes on the caller's model class` case in
+`skills-bundled-docs-contract.test.ts` is the backstop. Before launch, the
+caller loads the durable task classes and model-selection principles from
+`subagent-orchestration` plus exactly one active-provider selection reference.
+
+The internal `oat-dispatch-subagents` skill then owns capability checks, live
+catalog intersection, exact route selection, launch acceptance, recovery, and
+dispatch records. It loads exactly one matching provider mechanics reference;
+selection and mechanics references are not merged into one universal provider
+contract. Dispatch is native-first. Configured project/workflow policy may
+authorize required CLI or cross-runtime routes; an agent-improvised alternate
+route requires explicit current-run approval.
+
+## oat-repo-improve
+
+**Invocation:**
+`/oat-repo-improve maintainability-review .oat/repo/analysis/<review-file>.md`.
+Replace the placeholder with an actual report. This is an agent instruction,
+not a shell command. The slash form is the reliable way to start it; Codex can
+use `$oat-repo-improve`, and asking for the skill by name usually works too.
+Other source modes include a repository audit, a backlog review, a backlog
+directory, or an individual backlog item.
+
+**Prerequisites:** A Git repository and an explicitly chosen source. A
+maintainability-review source must already exist; the skill verifies its
+evidence instead of silently commissioning the same review again. A
+substantive full repository audit requires managed delegation: the `utility`
+tool pack (`oat tools install utility --scope user`), whose
+`oat-dispatch-subagents` and `subagent-orchestration` skills let the agent
+start read-only helper agents. If delegation is unavailable, stop or
+explicitly narrow the audit rather than pretending the full audit ran. Needs
+an active OAT project: no.
+
+**Example scenario:** A review found that package boundaries obscure ownership
+and that integration tests are difficult to run locally. Feed the saved
+review to this skill so it can turn the findings into separate, bounded plans
+with dependencies and verification steps. The goal is executable planning
+material, not an immediate refactor of the repository.
+
+Choose the source mode to avoid redundant work. Repository-audit mode can use
+`quick`, `standard`, or `deep` effort and a focus area; these controls do not
+change the other source modes. Evidence-backed sources should retain their
+provenance and be checked against the current repository. Plans distinguish
+the captured planning HEAD from any comparison baseline, and separate work
+that is ready from work blocked on a concrete dependency. It runs
+`git fetch origin main` to record the comparison SHA.
+
+**What it does without asking:** It asks you to choose the source (when you
+did not name one), the audit exclusions (for a repository audit), and which
+candidates to plan; a non-interactive run picks the top three to five itself.
+For a repository audit it starts read-only helper agents
+through managed delegation, asking once first if your agent requires
+authorization. After you pick candidates, it runs `git fetch origin main`,
+writes the plan files and, for several plans, an index, and then edits each
+source backlog item's frontmatter to add the plan link. It creates backlog
+items only with `--backlog-items` or your answer to its one offer, and
+publishes GitHub issues only after a preview and your explicit confirmation.
+It never commits, pushes, edits source code, or imports a plan into an OAT
+project.
+
+**Expected output:** Standalone external plans under
+`.oat/repo/reference/external-plans/`. When several plans are produced, an
+index helps navigate them, but the index is not itself an importable work
+unit. Each plan should carry a bounded objective, evidence, dependencies,
+verification, and readiness or unblock conditions. The skill does not edit
+source code or execute the plans. When the source is a backlog review,
+directory, or item, it always adds an `external_plans` link and refreshes
+`updated` in each source item's frontmatter after the plan is written.
+Creating new backlog items or publishing GitHub issues is a separate explicit
+option; issue publication requires a preview and confirmation.
+
+**Next step:** Review an individual plan and either execute it directly with
+the appropriate authorization or import that single plan through
+`oat-project-import-plan`. Do not import the multi-plan index or start a
+blocked plan without satisfying its dependency.
+
+## oat-repo-maintainability-review
+
+**Invocation:**
+`/oat-repo-maintainability-review --scope directory --target packages/api --mode tracked --focus testing`.
+The target is illustrative: choose a directory inside your repository. Use
+`--scope repo` for the whole repository. Output modes are `auto`, `tracked`,
+`local`, and `inline`; select one explicitly when the report's destination
+matters. This is an agent instruction; Codex uses
+`$oat-repo-maintainability-review`. The skill is explicit-invocation only, so
+use the slash or `$` form rather than relying on the agent to pick it.
+
+**Prerequisites:** A Git repository with readable source files and a clear
+review scope. Needs an active OAT project: no. Decide whether you need a saved
+artifact before starting: an inline review is useful for discussion but is
+not a file-backed input for a later planning handoff.
+
+**Example scenario:** Before several teams add features to an API package,
+you want to know whether its tests and developer workflow will support the
+growth. Review that directory, emphasize testing, and save the findings so
+the team can prioritize improvements without changing product behavior
+during the review.
+
+The review considers architecture, conventions, documentation, developer
+experience, testing, and maintainability. A focus changes emphasis without
+removing the other dimensions. Findings pair source evidence with both a
+Concern rating (severity) and a Value rating (improvement value), then
+organize recommendations into now, next, and later. A high-severity concern
+and a high-value improvement are not necessarily the same item.
+
+**What it does without asking:** It asks for any missing required argument
+before starting. When your agent can run subagents, it starts six of them,
+one per review dimension, and merges their findings. Unless you chose
+`inline`, it writes one report file to the resolved destination. It does not
+modify code, commit, push, or open issues. It offers a hand-off to
+`oat-repo-improve` afterwards and runs it only if you accept.
+
+**Expected output:** An evidence-backed review, inline or written according
+to the selected mode. Tracked reports live under `.oat/repo/analysis/` with a
+date-based repo-review filename; repeated same-day reports receive distinct
+names. Local reports go to `.oat/projects/local/analysis/`; `auto` mode
+writes there when `.oat/repo/analysis/` is missing or gitignored. Pass a
+local report's path explicitly to `oat-repo-improve`, which only discovers
+reports under `.oat/repo/analysis/` by itself. The review does not modify
+code or publish issues. Readers should be
+able to trace each actionable concern to the repository material that
+supports it.
+
+**Next step:** Discuss the findings and use [oat-repo-improve](#oat-repo-improve)
+to turn a saved report into external plans. If you chose inline mode, first
+explicitly save a report before asking another workflow to consume its path.
+
+## oat-repo-knowledge-index
+
+**Invocation:** `/oat-repo-knowledge-index` in the repository you want to map
+(Codex: `$oat-repo-knowledge-index`). The skill is explicit-invocation only,
+so use the slash or `$` form rather than relying on the agent to pick it. It
+does not require a project name or an active-project pointer.
+
+**Prerequisites:** A Git repository, the OAT CLI, and the ability to dispatch
+the `oat-codebase-mapper` subagent. A preflight checks whether background
+agents can write files and switches to a read-only fallback if they cannot.
+Needs an active OAT project: no. If a knowledge directory already exists,
+choose whether to refresh it or skip the run. Refresh first deletes every
+`.md` file in `.oat/repo/knowledge/`, hand-written files included, and then
+regenerates the set. Move any notes you want to keep before you choose it.
+
+**Example scenario:** A new teammate needs to understand which packages own
+the CLI, how shared configuration reaches applications, and which test
+commands are meaningful. Generate a repository knowledge index before
+starting their first feature so both the teammate and later agents have a
+common source-backed map.
+
+The workflow creates a thin index, maps distinct repository concerns, and
+enriches the index with the resulting knowledge. It records the repository
+HEAD and merge-base provenance so readers can judge freshness. A knowledge
+index is an onboarding and retrieval aid, not a declaration that all
+architecture concerns have been fixed or that every future question is
+answered.
+
+**What it does without asking:** The only question is refresh-or-skip when
+knowledge files already exist. Otherwise it creates `.oat/repo/knowledge/`,
+starts a test subagent and then four `oat-codebase-mapper` subagents in the
+background, and writes the knowledge files. It then runs
+`git add .oat/repo/knowledge/` and `git commit` on your current branch with
+no further prompt; that commit also includes anything you had already staged.
+Afterwards it records the run in `.oat/tracking.json` and regenerates the
+`.oat/state.md` dashboard with `oat state refresh`; those two files are not
+part of the commit. It does not push.
+
+**Expected output:** Eight files under `.oat/repo/knowledge/`:
+`project-index.md`, `stack.md`, `architecture.md`, `structure.md`,
+`conventions.md`, `testing.md`, `integrations.md`, and `concerns.md`. The
+workflow also updates its tracking/dashboard surface and commits the
+knowledge output on the current branch (unstage unrelated changes first; the
+commit includes anything already staged). Despite its name, `project-index.md` describes the
+repository; it does not require a pre-existing OAT lifecycle project.
+
+**Next step:** Read the index and the concern or testing documents relevant
+to your task. Start a project with that context, or use a focused review
+when you need a deeper evaluation. Refresh deliberately when repository
+changes make the captured map stale.

package/assets/docs/skills/research.md

@@ -0,0 +1,237 @@
+---
+title: Research and Evaluate a Decision
+description: Choose a research skill, challenge its conclusions, and combine evidence without confusing research with implementation.
+---
+
+# Research and Evaluate a Decision
+
+Use this family when you need evidence before committing to a direction. Start
+with `analyze` for something you already have, `deep-research` for a topic you
+need to investigate, or `compare` for named alternatives. Use `skeptic` to test
+a claim and `synthesize` to combine compatible research artifacts afterward.
+
+These examples are instructions to an agent, not terminal commands. The slash
+form (for example `/analyze`) is the reliable way to invoke a skill; Codex uses
+the `$name` form (for example `$analyze`). These five skills also let the agent
+pick them up when you ask for one by name. Example paths below stand for files
+you supply. None of these skills needs an OAT project (a tracked unit of work
+that OAT keeps under `.oat/projects/`), and research does not authorize code
+changes, purchases, or publication.
+
+The research skills that write a report share one default location rule. In a
+repository with a `.oat/` directory the agent suggests a folder under `.oat/repo/`;
+with only a user-level `~/.oat/` it suggests a folder there; otherwise it
+suggests the current directory. You can accept the suggestion or name another
+folder, and the skill creates the folder if it does not exist.
+
+## analyze
+
+**Invocation:** `/analyze proposals/import-service.md --context criteria.md`.
+Supply a file, directory, or quoted idea as the target. The optional
+`--context` file or directory supplies the criteria the target is judged
+against (for example, a security policy or a requirements document).
+
+**Prerequisites:** Accessible source material and an installed `deep-research`
+skill, whose artifact schema this skill uses. If that schema is unavailable,
+the skill stops rather than inventing a replacement format. Agree on a report
+destination when asked.
+
+**Example scenario:** A team has drafted an import-service proposal but has not
+decided whether its retry behavior, operating cost, and user-facing recovery
+flow are coherent. Give the agent the proposal and a file explaining the
+team's staffing and reliability constraints. Ask it to analyze the proposal
+before anyone turns it into implementation tasks.
+
+The review covers six angles: adversarial weaknesses, gaps, opportunities,
+structure, consistency, and audience fit. The detected input type (code,
+design document, product spec, presentation, proposal, or unstructured idea)
+decides which angles get deeper treatment; all six always run. Available
+workers can investigate the angles in parallel; otherwise the agent works
+through them sequentially. A persuasive proposal can still receive substantial
+gap findings, so distinguish strengths from issues that must be resolved
+before planning.
+
+**What it does without asking:** It reads the target and any context. When
+your agent can run subagents (helper agents it starts in the background), it
+starts up to six of them, one per angle, and it may start `compare` as a
+subagent if an angle turns up competing options. It then asks where to save
+the report, unless you already gave an output path, creates that folder if
+needed, and writes one file. It does not edit the target, commit, or push.
+
+**Expected output:** A written analysis artifact with evidence-backed findings
+and recommendations, not just an inline assessment. The suggested folder is
+`.oat/repo/analysis/` in an OAT repository, `~/.oat/analysis/` with only a
+user-level OAT setup, or the current directory, and the file is named
+`<topic>-analysis-<model>.md`. Preserve the report with the material it
+evaluated so later readers can tell which version the findings describe.
+
+**Next step:** Resolve the highest-impact gaps, use [compare](#compare) for a
+decision between alternatives, or bring the findings into a planning
+conversation. Do not treat the analysis report as an approved implementation
+plan.
+
+## compare
+
+**Invocation:**
+`/compare "queue-backed import" "synchronous import" --context criteria.md --dimensions "operational complexity, recovery, team fit" --save`.
+Provide at least two alternatives. `--context` supplies your priorities;
+`--dimensions` replaces the default dimensions (context can still add or
+reweight them); `--save` requests a written artifact instead of the default
+inline result.
+
+**Prerequisites:** Named alternatives and enough evidence to evaluate them.
+For a saved report, the installed `deep-research` schema must be available.
+State hard constraints before comparing: a recommendation for a different
+team or operating environment may not be useful to yours. The skill uses web
+search and package registries when they are available; say so if it must stay
+with local sources.
+
+**Example scenario:** Your team can either process a customer upload during
+the request or hand it to a queue. Both fit the current API, but only one
+engineer will operate the service. Compare them against recovery behavior,
+operational complexity, and team fit, using your existing proposal as context.
+
+The skill evaluates each alternative against shared dimensions and explains
+trade-offs. It uses qualitative judgments by default; numerical scoring needs
+an explicit request, not an implied precision that the evidence cannot
+support. For three or more candidates, expect a ranked recommendation. A
+close result should explain the condition that would change the winner.
+
+**What it does without asking:** It researches each option against each
+dimension, using web search when available. Without `--save` it answers in
+the conversation and writes nothing. With `--save` it asks where to save the
+file, unless you already gave an output path, creates that folder if needed,
+and writes one file. It does not commit or push.
+
+**Expected output:** An inline comparison by default, or a structured
+comparative research artifact with `--save`, suggested for
+`.oat/repo/analysis/` in an OAT repository and named after the options and
+the model. It includes a recommendation,
+supporting rationale, and important caveats rather than just a feature table.
+
+**Next step:** Test the recommendation's load-bearing claim with
+[skeptic](#skeptic), investigate an unresolved dimension with
+[deep-research](#deep-research), or confirm a direction before planning work.
+
+## deep-research
+
+**Invocation:**
+`/deep-research "reliable asynchronous imports" --depth standard --focus recovery --context criteria.md`.
+Use `surface`, `standard`, or `exhaustive` depth; `standard` is the default.
+The focus narrows the question, while context establishes your constraints.
+Add a trailing output path (for example `docs/research/`) to skip the
+destination prompt.
+
+**Prerequisites:** A researchable question, permission to use the available
+sources, and a destination for the resulting artifact. An existing project is
+not required. Tell the agent if it must stay within local documents or if
+external research is permitted.
+
+**Example scenario:** You have not selected an import architecture and need to
+understand failure recovery before comparing products. Research how systems
+resume interrupted uploads and avoid duplicate work, constrained by your
+team's operating model. This establishes the evidence base rather than asking
+for an immediate vendor choice.
+
+The skill classifies the question as technical, comparative, conceptual, or
+architectural and picks the matching artifact schema (the fixed set of report
+sections for that kind of topic). It plans three to six research angles (two
+or three at `surface` depth) and gathers evidence through available
+capabilities, in parallel when supported or sequentially otherwise. Greater
+depth expands the investigation; it does not turn inaccessible sources or
+unsupported claims into facts.
+
+**What it does without asking:** It searches the web when available and,
+when your agent can run subagents, starts one general-purpose subagent per
+research angle; it may also start `compare` as a subagent if competing
+options emerge. It then asks where to save the report, unless you gave a
+trailing output path, creates that folder if needed, and writes one file. If
+the chosen folder is not writable, it writes to the current directory and
+tells you. It does not commit or push.
+
+**Expected output:** A written structured research artifact with findings,
+sources, and methodology, named `<topic>-<model>.md`. The suggested folder is
+`.oat/repo/reference/research/` in an OAT repository, `~/.oat/research/` with
+only a user-level OAT setup, or the current directory. Review the evidence and
+limitations before using the conclusion as a requirement.
+
+**Next step:** Compare concrete options using the research, challenge a
+critical conclusion with [skeptic](#skeptic), or combine independent reports
+with [synthesize](#synthesize).
+
+## skeptic
+
+**Invocation:**
+`/skeptic "Retrying this import cannot create duplicate records"`.
+With no explicit claim, the skill evaluates the agent's most recent factual
+assertion in the conversation; quote a claim when there could be ambiguity.
+
+**Prerequisites:** A falsifiable claim and access to relevant evidence. Point
+the agent to the implementation, tests, or research that supposedly supports
+it. No project or output directory is required.
+
+**Example scenario:** A design discussion assumes retries are safe because
+the API accepts an idempotency key. Ask the skill to challenge that assumption
+against the actual write path and failure cases before the team relies on it
+for recovery. The key's existence alone is not the desired conclusion.
+
+The skill first tries to disprove the assertion, then weighs supporting
+evidence. It can use an available skeptical evaluator or perform the same
+evaluation directly. Lack of evidence is a reason to report uncertainty, not
+to validate the claim by default.
+
+**What it does without asking:** It reads local files, tests, lockfiles, and
+Git history, and uses web search when available. When your agent can run
+subagents, it starts one `skeptical-evaluator` subagent to do the
+adversarial search. It writes no file and changes nothing.
+
+**Expected output:** An inline verdict, confidence, and cited evidence. The
+conclusion can be that the claim holds up, that the challenge was correct,
+that the answer is nuanced, or that the evidence is genuinely inconclusive.
+It does not create a research file automatically.
+
+**Next step:** Correct a disproved assumption, qualify a nuanced one, or gather
+the missing evidence. If the result will influence later work, capture it in
+the relevant decision or research artifact rather than relying on chat alone.
+
+## synthesize
+
+**Invocation:** `/synthesize research/ --inline`, or supply explicit research
+files. Omit `--inline` when you want a written synthesis.
+
+**Prerequisites:** Existing structured artifacts with `skill`, `schema`,
+`topic`, `model`, and `generated_at` metadata. These requirements apply to
+explicit files as well as directory discovery. Arbitrary notes or articles
+are not automatically compatible inputs. Invalid explicit artifacts are
+skipped with warnings; fewer than two valid inputs requires confirmation.
+
+**Example scenario:** Two agents separately researched import recovery, and a
+third compared queue-based options. Supply their saved research artifacts and
+ask for a synthesis that separates agreements from contradictions before the
+team chooses a direction. The skill treats agreement across artifacts as high
+confidence and does not detect when several artifacts relied on the same
+original source, so check shared upstream sources yourself before you count
+agreement as independent confirmation.
+
+This skill works only from the supplied artifacts: it does not launch new
+research or browse for missing facts. It preserves provenance, identifies
+shared findings and unique insights, and explains conflicting conclusions.
+A preferred interpretation remains a judgment, not a newly established fact.
+
+**What it does without asking:** It reads the supplied artifacts only; it
+starts no subagents and does no web search. With `--inline` it answers in
+the conversation and writes nothing. Otherwise it asks where to save the
+synthesis, unless you already gave an output path, creates that folder if
+needed, and writes one file. It never modifies the input artifacts and does
+not commit.
+
+**Expected output:** A written, model-tagged synthesis
+(`<topic>-synthesis-<model>.md`), suggested for the source folder when all
+inputs share one folder, or an inline brief with `--inline`. Expect source
+agreements, contradictions with the direction the evidence leans (flagged as
+a lean, not a decision), unique single-source insights, consolidated
+recommendations, and a provenance table rather than concatenated summaries.
+
+**Next step:** Resolve a contradiction with targeted research, challenge the
+proposed direction with [skeptic](#skeptic), or bring the synthesis to a
+planning conversation with its source artifacts attached.

package/assets/docs/skills/session-closeout.md

@@ -0,0 +1,61 @@
+---
+title: Summarize What Shipped
+description: Produce an evidence-backed shipping digest across projects and merged pull requests for a chosen reporting window.
+---
+
+# Summarize What Shipped
+
+Use a shipping digest for a team update or periodic recap. It answers what
+shipped across a time window, not which task an active project should do next.
+
+## oat-wrap-up
+
+**Invocation:** `/oat-wrap-up --past-week --dry-run`. This is an agent
+instruction, not a shell command. The slash form is the reliable way to start
+it; Codex uses `$oat-wrap-up`, and asking for a wrap-up by name usually works
+too. Choose exactly one window: `--past-week`,
+`--past-2-weeks`, `--past-month`, or `--since YYYY-MM-DD` with optional
+`--until YYYY-MM-DD`. Named windows and explicit dates are not combined.
+
+**Prerequisites:** An OAT repository (one with a `.oat/` directory) and
+authenticated GitHub CLI (`gh`) access for merged-PR evidence. Project
+summaries are the `summary.md` files that `oat-project-summary` writes for
+each OAT project; they make the digest richer, but with none in the window the
+report is built from merged PRs alone. Needs an active OAT project: no.
+Archived local summaries also contribute; if a configured archive has not been
+synced, the skill warns and may suggest the separate `oat repo archive sync`
+action rather than silently doing it.
+
+**Example scenario:** Before Friday's team update, you want a concise account
+of changes users can now rely on, including work that crossed several OAT
+projects. Preview the past-week digest, check that its feature and fix claims
+match merged PRs, then rerun without `--dry-run` to save the report.
+
+The skill gathers project summaries and merged PRs for the selected window,
+then synthesizes features, fixes, and capabilities. It deduplicates summaries
+per project and assigns a merged PR to a project only when the project's
+summary cites that PR number. Many summaries do not cite PR numbers, so expect
+some PRs under "Other merged PRs" that belong to a project. Summaries are
+selected by date, not completion status, so an in-progress project's summary
+can appear. Treat the result as an editable draft and check it before sharing.
+This is a reporting workflow: it does not modify source summaries, publish a
+GitHub update, or close projects for you.
+
+**What it does without asking:** It reads local summaries and queries GitHub
+for merged PRs (read-only). Without `--dry-run` it writes one report file to
+the destination below, creating the folder if needed. With `--dry-run` it
+prints the report and writes nothing. It never commits the report, never
+pushes, and never runs `oat repo archive sync` for you.
+
+**Expected output:** With `--dry-run`, the digest is returned without writing
+a file. Otherwise it is saved under the configured `archive.wrapUpExportPath`,
+falling back to `.oat/repo/reference/wrap-ups/`, with a filename derived from
+the reporting end date and window. `--output` can override the destination.
+The report groups meaningful outcomes and keeps links to the underlying
+evidence so readers can follow up. The report is written but not committed;
+run `git add` and `git commit` yourself if you want to keep it in history.
+
+**Next step:** Review the digest for audience fit and evidence gaps, then
+share it through your usual communication process. Saving the report is not
+the same as publishing it. For unfinished work, resume the relevant project
+instead of using the digest as an execution instruction.