Team adoption

Orcaops Cloud is the collaboration layer for teams. It turns the task records developers capture locally into shared history, web plan approval, and pull-request review.

Project scope complements Cloud by sharing agent skills, instructions, and evaluator configuration through git. It gives every developer a consistent Orcaops setup; it is not a replacement for the shared team workflow in Cloud.

What project scope changes

The default personal install keeps skills in the current developer's home directory and hides .orcaops/ from the worktree. Project scope instead materializes the selected agent support into the repository:

• generated skills and any supported slash commands;
• the Orcaops block in agent instruction files;
• .orcaops/config.json, evaluator configuration, and the install manifest;
• managed .gitignore entries for local artifacts and caches.

Captured plans, checkpoints, reviews, caches, and usage records remain ignored. Committing project scope shares the workflow, not each developer's local task history.

Roll out from one engineer

From a working personal installation:

orcaops update --scope project
git status --short

Review every materialized file before committing it. The following loop stages only supported surfaces that actually exist in your repository:

for path in .orcaops .gitignore .claude .agents .cursor .opencode .aider-desk AGENTS.md CLAUDE.md; do
  if [ -e "$path" ] || [ -L "$path" ]; then
    git add -A -- "$path"
  fi
done
git commit -m "adopt orcaops"

Teammates then:

1. pull the committed setup;
2. install the CLI with npm i -g @orcaops/cli; and
3. run orcaops update in the repository to reconcile their local agent surfaces and runtime support.

If a teammate's setup does not behave as expected, orcaops doctor can diagnose unsupported agents, stale files, evaluator discovery issues, or missing runtimes. It is a troubleshooting tool, not an onboarding requirement.

Decide what belongs in git

Generated agent files are committed by default in project scope. If the team prefers to regenerate them on each machine:

orcaops update --scope project --generated-files ignore

The committed manifest and configuration remain the shared declaration; each developer runs orcaops update to materialize ignored support files locally. This reduces generated-file churn but makes a successful local update part of onboarding.

Review evaluator registrations with particular care. A repository may declare and enable evaluators, but it cannot grant user-local execution trust. Each developer retains control over the capabilities third-party evaluator code may use.

Avoid the personal-config pull collision

If a teammate adopts project scope while another developer still has an untracked personal .orcaops/config.json, git can refuse to check out the tracked file. Move the personal config aside, pull the adoption commit, then run orcaops update to reconcile the installation.

Connect the shared workflow

Project scope standardizes what runs in each developer's environment, but it does not sync task records or create shared web reviews. Connect the team to Orcaops Cloud for shared history, plan approval, and pull-request review. Follow Cloud collaboration for account, organization, sync, and review setup.