@open-agent-toolkit/cli 0.1.60 → 0.1.63

package/assets/skills/oat-cursor-cloud-projects/SKILL.md

@@ -0,0 +1,318 @@
+---
+name: oat-cursor-cloud-projects
+version: 1.0.1
+description: Use when OAT work is mentioned in a Cursor Cloud environment. Orients agents to cloud detection, repo-rooted project homes, user-first assets, CLI availability, and Cursor dispatch context without owning lifecycle execution.
+disable-model-invocation: false
+user-invocable: true
+allowed-tools: Read, Write, Bash, Glob, Grep
+---
+
+# OAT in Cursor Cloud
+
+Orient OAT work in Cursor Cloud before any project lifecycle skill runs. This
+skill is a harness-layer adapter: it resolves environment and asset context,
+then returns control to the provider-agnostic OAT lifecycle.
+
+## When to Use
+
+Use automatically when both are true:
+
+- the request involves OAT projects, skills, tools, config, gates, or project
+  artifacts; and
+- the current host may be a Cursor Cloud agent.
+
+Also use when the user asks how OAT is configured in Cursor Cloud, when multiple
+repositories make project location ambiguous, or before Cursor-specific review
+dispatch.
+
+Do not use this skill as the project orchestrator. Explicit autonomous
+end-to-end requests route to `oat-project-autonomous` after orientation.
+
+## Prerequisites
+
+- A shell and Node/npm are available.
+- Read `references/cursor-cloud-mechanics.md` only when model-family identity,
+  dispatch-surface catalogs, or degraded review evidence is needed.
+
+## Mode Assertion
+
+**OAT MODE: Cursor Cloud Orientation**
+
+**Purpose:** Establish trusted cloud, repository, asset, CLI, and dispatch
+context without taking ownership of a lifecycle phase.
+
+**BLOCKED Activities:**
+
+- Creating, approximating, or mutating project artifacts when `oat` is missing.
+- Selecting a repo asset over an existing user-scope asset because its version
+  is higher.
+- Treating semver comparison as source arbitration.
+- Placing projects in the workspace root, user home, or a cross-repo shared
+  directory outside the target repository.
+- Reimplementing provider dispatch mechanics from
+  `oat-dispatch-subagents/references/provider-cursor.md`.
+- Assuming one Cursor model catalog is a superset of another.
+
+**ALLOWED Activities:**
+
+- Detecting Cursor Cloud from environment and run metadata.
+- Resolving the target repository and repo-rooted project home.
+- Resolving user, repo, and bundled asset paths.
+- Verifying or installing the supported OAT CLI.
+- Comparing skill versions as a freshness check.
+- Loading Cursor mechanics and org-layer context skills when relevant.
+- Recording environment anomalies and degraded routes in project learnings.
+
+**Self-Correction Protocol:**
+
+If you catch yourself:
+
+- Reading a repo copy while a user copy exists → STOP and re-read the user copy
+  by absolute path.
+- Switching source because the repo semver is higher → STOP, retain the user
+  source, log the anomaly, and refresh the user tier.
+- Hand-authoring an OAT artifact because the CLI is unavailable → STOP and
+  restore the CLI first.
+- Copying model launch instructions into this skill → STOP and defer to the
+  dispatch provider reference.
+
+**Recovery:**
+
+1. Re-resolve the target repository and absolute user paths.
+2. Record any stale-tier or unavailable-surface anomaly.
+3. Return to the lifecycle skill with the corrected context, or stop when
+   freshness/CLI integrity cannot be restored.
+
+## Progress Indicators (User-Facing)
+
+Print this banner once when orientation performs work:
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+OAT ▸ CURSOR CLOUD ORIENTATION
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Print each indicator only when that step starts:
+
+- `[1/5] Detecting Cursor Cloud context…`
+- `[2/5] Verifying the OAT CLI…`
+- `[3/5] Resolving the target repository and project home…`
+- `[4/5] Selecting user-first OAT assets…`
+- `[5/5] Loading required harness and context guidance…`
+
+## Process
+
+### Step 0: Detect Cursor Cloud
+
+Treat positive run metadata as authoritative. When the `cursor-cloud` MCP is
+available, call `run-info`; use `environment-info` when repository layout,
+environment provenance, or setup status matters.
+
+Environment markers are deterministic supporting evidence:
+
+- `CURSOR_AGENT=1`;
+- `CURSOR_CONVERSATION_ID` beginning with `bc-`;
+- `AWS_PROFILE=cursor-cloud-agent`;
+- `HOSTNAME=cursor`.
+
+One strong marker or positive MCP metadata is sufficient to apply this
+orientation. Record which signal resolved the context. If no signal is present,
+return control without imposing Cursor-specific guidance.
+
+Do not infer model family from self-report. When dispatch identity is needed,
+follow `references/cursor-cloud-mechanics.md`.
+
+### Step 1: Verify the OAT CLI
+
+Before reading or changing OAT project state:
+
+```bash
+if command -v oat >/dev/null 2>&1; then
+  oat --version
+else
+  npm install -g @open-agent-toolkit/cli@latest
+  oat --version
+fi
+```
+
+If installation fails, report the exact non-secret error and stop OAT artifact
+work. Never approximate `oat project new`, state transitions, templates,
+manifest behavior, or configured gates manually.
+
+An OAT source checkout may use its repository-supported source CLI command for
+development verification, but that does not prove the globally installed CLI
+is ready for unrelated repositories.
+
+### Step 2: Resolve Repository and Project Home
+
+First identify the repository that owns the requested product/code change.
+Projects always live under that repository's configured OAT projects root.
+
+Resolve from the target repository:
+
+```bash
+PROJECTS_ROOT="${OAT_PROJECTS_ROOT:-$(oat config get projects.root 2>/dev/null || echo ".oat/projects/shared")}"
+PROJECTS_ROOT="${PROJECTS_ROOT%/}"
+PROJECT_PATH=$(oat config get activeProject 2>/dev/null || true)
+```
+
+Rules:
+
+- **Single-repo workspace:** the sole target repository owns `.oat/`, local
+  config, project artifacts, commits, and PRs.
+- **Multi-repo workspace:** choose the repository whose code and branch own the
+  primary objective. Resolve its local config from that repo, not from the
+  workspace parent or whichever repo happened to be the shell's first cwd.
+- **Cross-repo objective:** anchor the OAT project in one explicitly selected
+  primary repository. Record secondary repositories and their write/commit
+  boundaries in the project plan; never create a workspace-level project home.
+
+If repository ownership is ambiguous and choosing would alter branch, PR, or
+artifact ownership, stop for explicit direction. Once resolved, run lifecycle
+commands from the target repository or pass their supported project path.
+
+### Step 3: Resolve Assets with User Scope First
+
+Apply one source order independently to every asset file:
+
+1. user scope;
+2. target-repository scope when the user asset is absent;
+3. bundled CLI asset when both installed tiers are absent.
+
+User locations:
+
+| Asset    | User source                 |
+| -------- | --------------------------- |
+| Skill    | `~/.agents/skills/<skill>/` |
+| Template | `~/.oat/templates/<file>`   |
+| Script   | `~/.oat/scripts/<file>`     |
+
+Repository locations are `.agents/skills/`, `.oat/templates/`, and
+`.oat/scripts/` within the target repository.
+
+The user tier is provisioned from `@latest` at environment boot and is the
+canonical execution tier. Repository copies in this fleet are not customized;
+a difference indicates staleness, not a local override.
+
+#### Absolute-path loading contract
+
+The p02-t01 environment probe proved OAT-level discovery of
+`~/.agents/skills/` but could not verify fresh Cursor model auto-surfacing.
+Therefore, resolve and read the selected user asset by absolute path as the
+**primary mechanism**:
+
+```bash
+USER_SKILLS_ROOT="${HOME}/.agents/skills"
+USER_TEMPLATES_ROOT="${HOME}/.oat/templates"
+USER_SCRIPTS_ROOT="${HOME}/.oat/scripts"
+```
+
+Do not rely on ambient skill discovery or a provider hot reload for
+correctness. Auto-surfacing is a convenience only.
+
+#### Skill version verification
+
+When both user and repo copies of a skill exist, compare their frontmatter
+`version:` values. This check verifies the expected invariant:
+
+```text
+user version >= repo version
+```
+
+It never chooses the source:
+
+- user version equal to or higher than repo → read the user copy;
+- repo version higher than user → still read the user copy, append an anomaly
+  to `oat-execution-learnings.md`, and flag the user tier for refresh with
+  `oat tools update` or an environment rebuild;
+- if freshness is safety-critical, refresh and re-verify before continuing;
+  stop if the user tier cannot be refreshed safely.
+
+Never silently switch to the repo copy. Apply per-file precedence to templates
+and scripts without using skill semver as their arbitration mechanism.
+
+### Step 4: Load Cursor Dispatch Context When Needed
+
+For Cursor review/worker dispatch:
+
+1. Read `references/cursor-cloud-mechanics.md`.
+2. Resolve and read the selected user-scope
+   `oat-dispatch-subagents/references/provider-cursor.md` by absolute path,
+   falling back to repo/bundled tiers only when the user skill is absent.
+3. Let `oat-project-dispatch-subagents` adapt lifecycle scope and policy.
+4. Let `oat-dispatch-subagents` own capability, catalog, route, launch,
+   recovery, and generic evidence.
+
+This skill supplies identity and catalog context only. Do not restate or alter
+the provider dispatch algorithm.
+
+### Step 5: Surface Adjacent Skills and Record Degradation
+
+- If the user explicitly requested goal-to-PR or resume-to-PR autonomy, load
+  `oat-project-autonomous` from the selected user-first source.
+- Discover context/research skills supplied by the active organization or
+  environment when integrated systems require them. Do not hard-depend on,
+  name, or emulate an absent org layer.
+- When an expected skill, MCP server, CLI surface, or credential is absent,
+  record the gap in the active project's `oat-execution-learnings.md`. Continue
+  only through a documented integrity-preserving route.
+
+Return an orientation summary:
+
+```text
+Cursor Cloud: {detected | not detected} via {signal}
+Target repository: {absolute path}
+Projects root: {repo-relative or absolute configured path}
+Active project: {path | none}
+OAT CLI: {version | blocked}
+Asset tier: user-first; absolute-path loading primary
+Freshness: {verified | anomaly logged | refresh required}
+Dispatch context: {not needed | mechanics loaded}
+```
+
+## Examples
+
+### Basic Usage
+
+```text
+/oat-cursor-cloud-projects
+```
+
+### Conversational
+
+```text
+I need to continue an OAT project in this Cursor Cloud workspace.
+```
+
+```text
+Which OAT skill and template copies should this cloud agent use?
+```
+
+## Troubleshooting
+
+**Multiple repositories contain `.oat/`:** Resolve the repository that owns the
+change and branch. Do not select by lexical order or create a workspace-level
+project.
+
+**User skill is older than repo skill:** Keep the user skill as source, log the
+anomaly, run `oat tools update` or rebuild the environment, and block
+safety-critical work until freshness is restored.
+
+**Skill does not auto-surface:** Read its user-scope `SKILL.md` by absolute path.
+Do not require an agent restart for correctness.
+
+**Cursor model names disagree across commands:** Treat each command/tool as a
+separate dispatch surface and snapshot its current catalog. See
+`references/cursor-cloud-mechanics.md`.
+
+## Success Criteria
+
+- ✅ Cursor Cloud context was resolved from metadata or deterministic markers.
+- ✅ `oat` was verified before project artifact work.
+- ✅ The project home is anchored inside the target repository in both single-
+  and multi-repo environments.
+- ✅ Existing user assets won independently for skills, templates, and scripts.
+- ✅ Skill version comparison verified freshness without changing source.
+- ✅ User assets were read by absolute path as the primary mechanism.
+- ✅ Cursor dispatch mechanics remained delegated to the canonical provider
+  reference.
+- ✅ Missing surfaces and freshness anomalies were recorded rather than hidden.

package/assets/skills/oat-cursor-cloud-projects/references/cursor-cloud-mechanics.md

@@ -0,0 +1,173 @@
+# Cursor Cloud Mechanics
+
+Load this reference only when Cursor-specific model-family identity, dispatch
+catalog evidence, or degraded review provenance is needed. It supplies context
+to the dispatch substrate; it does not define launch or recovery mechanics.
+
+## Deterministic Producer Family
+
+Never ask a model to identify its own family. Self-report is not dispatch
+evidence.
+
+Resolve identity in this order:
+
+1. Call the `cursor-cloud` MCP `run-info` tool for the current run.
+2. Read `originalModelName` from the returned run metadata.
+3. Preserve the exact slug as producer identity evidence.
+4. Normalize a lowercase copy only for family classification.
+5. Map the normalized value with the ordered rules below.
+
+| Match, in order                                                       | Family     |
+| --------------------------------------------------------------------- | ---------- |
+| contains `claude` or `anthropic`                                      | `claude`   |
+| contains `gpt`, `openai`, `codex`, or an OpenAI reasoning-series slug | `openai`   |
+| contains `grok` or `xai`                                              | `xai`      |
+| contains `composer`                                                   | `composer` |
+| contains `glm`                                                        | `glm`      |
+| no rule matches                                                       | `unknown`  |
+
+Match Grok/xAI before interpreting any generic `cursor-` prefix. For example,
+`cursor-grok-4.5-high` is family `xai`, not family `cursor` or `unknown`.
+
+If `run-info` is unavailable or omits `originalModelName`, record producer
+family as `unknown` with the missing evidence. Do not substitute conversational
+self-report, a guessed family, or a model name observed in a different run.
+Blocking cross-family review must fail closed when the owning review contract
+cannot preserve its independence requirement.
+
+Use `environment-info` for environment/version provenance and repository setup,
+not as a replacement for current-run model identity unless it explicitly
+contains the same authoritative run field.
+
+## Per-Surface Catalog Rule
+
+Treat every Cursor dispatch surface as a distinct curated catalog with its own
+names and availability:
+
+1. Cursor Cloud native Task/subagent surface.
+2. Cursor IDE native agent surface.
+3. Cursor CLI subagent model enum.
+4. Cursor CLI full model list.
+
+These catalogs cross-cut; they do not form nested supersets. A model available
+on one surface is not evidence that another surface accepts the same slug.
+Aliases and effort suffixes are opaque per surface.
+
+Verified snapshot on 2026-07-13:
+
+- the Cursor Cloud native surface included a Sol `xhigh` selector and did not
+  expose the corresponding Sol `max` selector;
+- the Cursor CLI subagent enum exposed the Sol `max` selector and not that
+  native `xhigh` selector.
+
+This snapshot documents the divergence; it is not a permanent allowlist.
+Provisioning the CLI adds a differently shaped surface so cloud-native and CLI
+routes together can reach their union. It does not make either individual
+catalog authoritative for the other.
+
+Before every dispatch:
+
+1. Identify the exact surface that will accept the launch.
+2. Snapshot that surface's current catalog from its own tool schema, enum, or
+   list command.
+3. Record source, observation time, and exact candidate strings.
+4. Intersect only that snapshot with the already-resolved policy candidates.
+5. Pass the resulting context to `oat-dispatch-subagents`.
+
+Do not:
+
+- reuse a catalog snapshot from another surface;
+- assume a successful main-agent selector is accepted by a subagent enum;
+- rewrite, trim, or translate an opaque model slug;
+- select from a stale design-time list when current catalog evidence exists;
+- fall through to another surface after a launch has been accepted.
+
+## Dispatch Ownership
+
+After identity and catalog context are captured, read and follow
+`oat-dispatch-subagents/references/provider-cursor.md` from the user-first asset
+source selected by the orientation skill.
+
+That provider reference owns Cursor launch, acceptance, continuation, retry,
+and recovery mechanics. `oat-project-dispatch-subagents` owns lifecycle scope
+and policy adaptation. Do not duplicate those contracts here.
+
+## Degraded Route Evidence
+
+Degradation is a pre-launch selection outcome, not a post-accept fallback.
+Record it in the canonical dispatch record plus project learnings.
+
+Use this shape for the Cursor-specific evidence supplied to the generic record:
+
+```yaml
+producer_identity:
+  source: cursor-cloud.run-info.originalModelName
+  exact_model: gpt-5.6-sol-xhigh
+  family: openai
+dispatch_surface:
+  name: cursor-cloud-native
+  catalog_snapshot:
+    source: tool-schema
+    observed_at: 2026-07-13T21:00:00Z
+    candidates:
+      - exact-opaque-selector
+selection:
+  selection_source: policy-resolved
+  selection_reason: cross-family-candidate-available
+  selected_target: exact-opaque-selector
+independence:
+  achieved: cross-family-and-context
+  producer_family: openai
+  reviewer_family: claude
+  family_independent: true
+  context_independent: true
+degradation:
+  present: false
+  reason: null
+dispatch_record: dispatch-unique-id
+learnings_entry: null
+```
+
+Allowed `independence.achieved` values:
+
+- `cross-family-and-context`;
+- `same-family-context-independent`;
+- `context-only`;
+- `none`.
+
+When no second family is dispatchable but the owning non-blocking review
+contract allows same-family review:
+
+```yaml
+selection:
+  selection_source: policy-resolved
+  selection_reason: no-cross-family-candidate-on-selected-surface
+independence:
+  achieved: same-family-context-independent
+  family_independent: false
+  context_independent: true
+degradation:
+  present: true
+  reason: catalog-contained-one-dispatchable-family
+learnings_entry: oat-execution-learnings.md#<entry>
+```
+
+Include the exact configured invocation evidence required by the generic record
+schema. Keep runtime confirmation separate and non-authoritative. Never record
+credentials or secret values.
+
+For a blocking review, `none` is not an acceptable achieved independence level.
+If no route meets the owning contract, emit a boundary record rather than
+claiming degraded success.
+
+## Accepted-Launch Terminality
+
+Catalog divergence is resolved before launch. Once a launch is accepted, that
+route is terminal:
+
+- continue or retry only through the accepted handle and identical payload as
+  permitted by the dispatch engine;
+- after bounded recovery, record the terminal blocker;
+- never reinterpret another catalog as a runtime fallback;
+- never launch a cheaper or differently shaped target to replace an accepted
+  route.