oat-cursor-cloud-projects

name	oat-cursor-cloud-projects
version	1.0.2
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
metadata	{"internal":true}

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:

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:

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:

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:

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/SKILL.md by absolute path, falling back to repo/bundled tiers only when the user skill is absent.
3. Resolve and read the selected user-scope subagent-orchestration/references/model-selection-principles.md and subagent-orchestration/references/provider-cursor.md by absolute path, with the same fallback rule.
4. Resolve and read the selected user-scope oat-dispatch-subagents/references/provider-cursor.md mechanics reference by absolute path, with the same fallback rule.
5. Let oat-project-dispatch-subagents adapt lifecycle scope and policy.
6. 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:

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

/oat-cursor-cloud-projects

Conversational

I need to continue an OAT project in this Cursor Cloud workspace.

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.