boshu2__agentops/docs/MIGRATION.md

Cathedral Cut migration

AgentOps now owns one small product boundary:

RPI -> Plan -> Implement -> fresh Validate -> durable verdict -> report and stop

The caller owns whether to revise, run another invocation, schedule work, use a tracker, manage Git, or deliver the result. Deterministic repository checks stay under ao gate check; semantic judgment is the Validate skill.

Removed responsibilities

Removed command or surface	Surviving alternative
ao pawl	Invoke the Validate skill for one independent semantic verdict.
ao plan-pawl	Invoke premortem when the caller wants an advisory plan challenge.
ao validate	Use the Validate skill; use ao gate check only for deterministic checks.
ao land	Use the repository's Git or CI delivery process.
ao done, ao close	Report the result to the caller; AgentOps does not close work.
ao governor, ao converge	The caller decides whether to start a new invocation or revision.
ao yield	Observe throughput in the selected runtime or external system.
ao claim, ao next-work	Use the caller's tracker or substrate directly.
ao state, ao reconcile	Inspect the bead or caller intent, derived subject manifest, verdict, and generic provenance as read-only evidence.
ao worktree	Use Git directly.
ao membrane	Record observations as Validate findings or generic provenance.
ao crank	Call an executor directly or use the optional dispatch_once adapter.
ao constraint	Encode accepted mechanical policy in repository-owned linters or checks; AgentOps no longer promotes findings into blocking state.
ao skills edit	Edit canonical skills/<slug>/ sources directly; use normal repository Git policy outside ao.
ao goals trace	Inspect current goal/scenario artifacts directly; the retired directive-to-bead lifecycle chain has no replacement.
ao inject	AgentOps no longer retrieves prior knowledge; use the caller's own memory or context tooling.
ao session memory	Use caller-authored ao session handoff evidence or maintain repository memory through the caller's own policy.
ao verify	Use the Validate skill for semantic judgment and ao gate check for deterministic checks. Delete any ao verify init pre-push ratchet from .git/hooks/pre-push (restore pre-push.agentops-orig if one was set aside); ao verify init --remove no longer exists, and git push --no-verify bypasses a stale hook once.

These names are no longer registered commands. Invoking one fails as an unknown command (exit 1) and prints the matching replacement pointer from the table above; nothing forwards to old code or mutates old state.

Other 3.2 bookkeeping and knowledge verbs (ao beads, ao agents, ao canon, ao ci, ao citation, ao findings, ao forge, ao knowledge, ao mcp, ao metrics, ao notebook, ao patterns, ao pool, ao ratchet, ao registry, ao scope, ao sessions, ao wiki) were pruned from the default build without tombstones. (ao eval returned in 3.3 as the wired measurement surface — deterministic suites, locked Tasks, holdout scenarios — still with no lifecycle authority.) They have no replacement inside AgentOps; use the caller's own tools, ao gate check for deterministic checks, or generic ao provenance records.

Config file location

~/.agentops/config.yaml and ./.agentops/config.yaml moved to ~/.agents/ao/config.yaml and ./.agents/ao/config.yaml. The legacy paths are still read as a fallback for this release (with a deprecation warning on stderr) when no file exists at the new path; move the file to silence the warning:

mkdir -p ~/.agents/ao && mv ~/.agentops/config.yaml ~/.agents/ao/config.yaml

Skills

• plan now contains the useful behavior from discovery, behavior-first-planning, and goal-design.
• swarm exposes only caller-directed dispatch_once; crank was removed.
• learn is an optional later consumer of verdict collections, never a lifecycle phase or authority.
• Canonical mortem names are premortem and postmortem. Hyphenated and underscored variants were removed.
• beads-br and beads-bv were removed from the bundle. Invoke br and bv directly if the caller selects those tools.

Verdicts and identity

verdict.v2 binds acceptance and a deterministic subject-manifest.v1 to distinct declared author and validator context identities. Freshness is an attested trust fact, not cryptographic proof of process isolation. Verdicts are stored atomically by content digest under .agents/ao/verdicts/sha256/ unless a caller supplies another directory.

Historical Pawl, queue, claim, landing, and lifecycle artifacts remain inert evidence. They no longer influence phase sequencing, verdict validity, or CLI outcomes.

Install migration

AgentOps 3.3 supports three install paths: npx skills@latest add boshu2/agentops --all -g (universal across coding agents), runtime plugins for Claude Code and Codex (managed bundles that update with the release), and one canonical checkout plus source symlinks for users who edit skills or contribute:

git clone https://github.com/boshu2/agentops.git ~/.local/share/agentops
cd ~/.local/share/agentops
ao skills link --dry-run
ao skills link

The 3.x curl installers (scripts/install.sh, install-claude.sh, install-codex.sh, install-agy.sh, install-opencode.sh, and install-codex.ps1) are tombstones: they refuse to install and print the supported paths. Internal helpers (install-codex-plugin.sh, install-codex-native-skills.sh) were deleted.

If you switch from a plugin to source links, remove the runtime plugin through that runtime before linking the checkout so only one corpus is visible:

• Claude Code: claude plugin uninstall agentops@agentops-marketplace, then claude plugin marketplace remove agentops-marketplace.
• Codex: codex plugin remove agentops@agentops-marketplace, then codex plugin marketplace remove agentops-marketplace. (Older Codex without the plugin verb: remove ~/.codex/plugins/cache/agentops-marketplace and ~/.codex/.agentops-codex-install.json, then remove the AgentOps plugin enable entry from ~/.codex/config.toml.)
• Gemini/Antigravity: agy plugin disable agentops-core-gemini, then agy plugin uninstall agentops-core-gemini.

ao skills link refuses to replace real directories and foreign links. Resolve each reported conflict deliberately; never delete a user-owned skill merely to make the counts match. Use ao skills unlink to remove only links that point into the current checkout.

Optional runtimes

NTM, Agent Mail, Gas City, councils, and model-specific executors remain caller-selected adapters or strategies. None is a hard dependency of RPI, Plan, Implement, or Validate, and none may translate its own attempts, leases, queues, or delivery state into AgentOps correctness state.