v3.11.0

brew update && brew upgrade agentops · update skills · checksums · verify provenance

---

Highlights

AgentOps 3.11 is a skills release. It adds three skills, bringing the menu to 32, and changes 28 of the 29 existing skills, mostly by folding in methods from a survey of other public skill libraries, each rewritten in AgentOps terms. No command or skill name changes.

The new skills:

• Triage turns an incoming bug report, feature request, external PR or alert into a decision backed by evidence. For accepted work it writes a brief an agent can act on without the conversation.
• Architecture finds where a codebase's structure makes change expensive and compares interface designs before any code moves.
• Ergonomics checks whether an agent can discover a CLI, API or tool, read its output and recover from its errors.

Unlike 3.10, this release ships no evaluation. None of the skill changes has been measured with Skill Eval or the plugin evaluator, so treat them as guidance to try, not a measured improvement. Skill bodies are about a third longer than in 3.10, which costs context each time a skill loads.

Two other changes reach users. The Claude Code plugin installs from a generated plugin/ folder that holds only what the plugin loads. And ao's help and briefing text now states the 3.9 review rule instead of the retired one.

Upgrade Notes

• Update the plugin, the npx install or Homebrew as usual. Every 3.10 command and skill name still works, and nothing needs migrating.
• The Claude Code plugin's marketplace entry now points at ./plugin. Install and update commands are unchanged.
• The plugin no longer puts bin/factory and bin/ralph on the Bash PATH. They are operator tools; run them from a repository checkout.
• Research no longer pre-approves Bash and Write. Expect a permission prompt where it runs a command or writes a file, as with the other skills.
• With the plugin's hooks on, expect a permission prompt when an agent writes ~/.agents/ao/policy-waivers. Approve it only for a waiver you asked for. Prefixing one command with AOP_WAIVE= never waived a policy; set it in the environment Claude is launched with instead.
• In a source checkout, run git pull --ff-only, then rerun ao skills link with the selectors you used before. Add --skill triage --skill architecture --skill ergonomics for the new skills. Without selectors it links every skill in the library.
• A plugin update replaces the installed copy of every skill. If you changed skills in place, move those changes to a fork or a source checkout first. The README's "Make it yours" section shows how.
• Upgrading from 3.9 or earlier: read the 3.10 release notes first.

At a Glance

Area	What changes for the user
New skills	Triage, Architecture and Ergonomics. The menu is 32 skills.
Skill content	28 of the 29 existing skills change, mostly with methods from other public skill libraries rewritten in AgentOps terms. Not measured.
Hooks	The plugin's guard asks before an agent writes the policy waiver file.
Claude plugin	Installs from a generated plugin/ folder; bin/factory and bin/ralph leave the plugin's PATH.
ao CLI	Help and briefings state the current review rule. ao doctor fix keeps recovery details when its report write fails.
Release gates	The publisher waits for a green Validate run on the tagged commit.

Product Areas

Skills and Workflows

• Added: Triage, Architecture and Ergonomics, described above. None has been measured with Skill Eval yet.
• Changed: A survey of other public skill libraries added methods to nineteen skills. Doc brings documentation current after a change, describes a change for reviewers and writes release notes for a range. Research checks a document's claims by re-deriving them another way and treats an empty search as absence only when it could have matched. Security reviews what actually ships for a publish question and covers CI definitions. Validate counts green obtained by changing the subject or the gate as weakened acceptance. The changelog lists the rest.
• Changed: A second pass read every line of the two public skill libraries closest to AgentOps. 173 methods survived a check against current skill text and went into 27 skills. Implement confirms the failing run executes the code in question and repairs a defect class rather than one instance. Test derives expected values from a specification, never the code under test. Review binds the subject to the merge base and holds a finding under pushback unless new evidence arrives.
• Changed: Doc, Implement, Security and Test gained optional references for developer journeys, difficult failures, attacker-path evidence, exploratory QA, suite audits and workload performance.
• Changed: Agent Native's per-packet result and Orchestrate's status line report the last observed activity. RPI names a stall by category and the fact observed, with no counts. Plan writes into existing intent only with authority and otherwise proposes an amendment.
• Changed: Using GC's Mayor template no longer pushes or opens a PR unless publishing is authorized.
• Changed: The implement-wave workflow runs its implementer lanes one at a time in the caller's working tree, so a wave takes the sum of its lane times. Arguments and the result shape are unchanged.
• Fixed: Research no longer pre-approves Bash and unscoped Write through allowed-tools.
• Fixed: Retired review-rule wording (a fresh read and repair on every change) is gone from Doc's references, and Domain's shipped Go standard no longer states AgentOps contributor facts as general guidance.

CLI and Operator Commands

• Changed: ao --help, ao quick-start, ao demo and ao robot-docs state the review rule from 3.9: checks and CI gate an ordinary change, and one fresh read happens only where a mistake is costly. The 3.10 binary still printed the retired rule that every change needs a fresh judgment.
• Fixed: ao doctor fix keeps the run ID, the actions it applied and the backup paths in its error output when it cannot write its report. It still exits 74, so you can inspect or undo before retrying.

Install, Upgrade, and Distribution

• Changed: The Claude Code plugin installs from plugin/, a generated folder that holds skills, agents, the policy hook dispatcher, Workflow tool scripts, the manifest and a new listing icon. scripts/regen-plugin-tree.sh builds it, and scripts/regen-all.sh --check fails when it is stale.
• Changed: The plugin no longer puts bin/factory and bin/ralph on the Bash PATH.
• Changed: The release publisher waits for a green Validate run on the exact tagged commit before it publishes. scripts/retag-release.sh pushes main before it changes any tag or release.

Codex and Runtime Integrations

• Changed: The Codex plugin reads the same skills/ tree, so it carries the three new skills and every skill change above. Its manifest and layout are otherwise unchanged.

Hooks and Lifecycle

• Added: The plugin's guard asks before an agent writes the policy waiver file, ~/.agents/ao/policy-waivers, with a redirect, tee, a copy, an in-place edit, or Edit or Write. Approve only a waiver you asked for. It makes such writes visible; it is not tamper-proofing, and other writers or a relocated waiver file are not caught.
• Fixed: The hook installer no longer says to prefix one command with AOP_WAIVE=<policy-id>. That never waived dispatcher policies, because the hook reads its own environment. Set AOP_WAIVE in the environment Claude is launched with, or add a <policy-id> <expiry-unix-epoch> line to the waiver file.
• Fixed: The hooks tree no longer contains an npx launcher string, which the Claude Code plugin marketplace validator reported as blocking.

Eval, Validation, and Release Gates

• Changed: Validate's summary check fails when a lane is cancelled or times out, and a full run fails on any skipped lane.
• Changed: Two gates that could not fail, always.mutation-route and always.file-manifest-overlap, are retired.
• Changed: The RPI plugin-eval criterion c3 grades the conditional review rule, and two core eval cases expect the current rule.
• Changed: Steps that install the skill evaluator (in Validate, the nightly run and the release publisher) stay on Python 3.14, because Harbor's litellm dependency has no Python 3.15 release.

Docs and Onboarding

• Changed: The README's "When you need to…" table lists Triage, Architecture and Ergonomics.
• Changed: The upgrade guide, the vocabulary and bounded-context contracts, the trust-factory page, the component map and the kernel template state the current review rule. ADR-0017 records it as a dated amendment and marks the passages it superseded.

Security, Privacy, and Supply Chain

• Changed: Go toolchain 1.27.3, golang.org/x/text 0.43.0, golangci-lint 2.14.0 and updated GitHub Action pins, including the Claude Code Action and GoReleaser Action.

Contributor/Internal Refactors

• Changed: AGENTS.md has a 14,336-byte budget on top of its line limit, and the Go and Python rules files load only for their own paths.
• Changed: The PR template asks authors to repeat gate trailers in the description, because squash merges use the PR body.

Known Issues

• No skill change in this release has been measured. Skill Eval, the plugin evaluator and the probe runner were not run on 3.11, and Architecture and Ergonomics show as unmeasured in probe coverage. The 3.10 evaluation results do not carry over.
• Skill bodies are about a third longer than in 3.10, and references grew by about a fifth. A loaded skill costs more context than before.
• The 3.10 known issues were not re-measured and may still apply, including skills that did not load on a blind request. See the 3.10 release notes.

Full changelog

---

Full changelog

AgentOps 3.11 adds three skills, bringing the menu to 32, and changes 28 of the 29 existing skills, mostly by folding in methods from a survey of other public skill libraries, rewritten in AgentOps terms. None of these skill changes has been measured with Skill Eval or the plugin evaluator, so this release claims no improvement in outcomes. The Claude Code plugin now installs from a generated plugin/ folder, and ao's help and briefing text states the review rule that 3.9 introduced. No command or skill name changes.

See the curated release notes for upgrade notes and known limits.

Added

• Three skills, bringing the menu to 32. Triage turns an incoming bug report, feature request, external PR or alert into a decision backed by evidence and, for accepted work, a brief an agent can act on without the conversation. Architecture finds where a codebase's structure makes change expensive and compares interface designs before any code moves. Ergonomics checks whether an agent can discover a CLI, API or tool, read its output and recover from its errors. None has been measured with Skill Eval yet.
• The plugin's guard asks before an agent writes the policy waiver file, ~/.agents/ao/policy-waivers, with a redirect, tee, a copy, an in-place edit, or Edit or Write (core.policy:self-waive). Approve only a waiver you asked for. It makes such writes visible; it is not tamper-proofing.

Changed

• Nineteen skills picked up methods from a survey of other public skill libraries, rewritten in AgentOps terms. Doc brings documentation current after a change, describes a change for reviewers, writes release notes for a range, keeps facts and their certainty when rewriting, links only what the reader can open, and checks a handoff against current state before resuming from it. Research checks a document's claims by re-deriving them another way, traces how a decision got its shape, answers adoption questions only with both sides evidenced, explains a library from the version actually resolved, strips internal details from outside searches, and treats an empty search as absence only when it could have matched. Security names the snapshot, lists unread inputs, reviews what actually ships (history included) for a publish question, and covers CI definitions. Validate counts green obtained by changing the subject or the gate as weakened acceptance. Idea Genie drafts along several angles before judging, weighs today's workarounds over stated interest, and compares challenges by mechanism. Skill Builder covers fixing a skill at the layer that owns the behavior. Skill Eval prefers cases from real use and measures noise before cutting. Navigate handles epics that still need decisions. Reality Check reports a read-only health snapshot and looks for placeholder implementations behind a done claim. Agent Native accounts for every item in a packet and proves content is integrated before a workspace is removed. Domain proposes a decision record only when one is warranted. Plan and Interview expose consequential intent gaps; Refactor compares interfaces before restructuring. Implement handles uncertain writes, shared indexes and conditional change safety. Test covers meaningful kind/action outcomes, recovery and performance evidence; Review checks the request and its callers. Memory traces corrected claims and audits instructions within existing authority. Postmortem checks what happened to earlier recommendations when those reports are among its inputs.
• A second pass read every line of two public skill libraries closest to AgentOps and checked each method against current skill text; 173 survived and were folded into 27 skills, again in AgentOps terms. Implement confirms the failing run executes the code in question, grounds each cause against its strongest rival, and repairs a defect class rather than one instance. Test derives expected values from a specification, never the code under test, and pins untested code with characterization tests before changing it. Review binds the subject to the merge base and holds a finding under pushback unless new evidence arrives. Agent Native treats a capacity refusal as backpressure, checks each worker's starting commit, and names the actions a packet must not take. Doc writes a questionnaire when only another person holds the answers and keeps one live statement instead of stacked updates. Triage reads the whole thread and splits compound reports. Research checks that a citation asserts the claim and that "nothing calls this" survives re-exports and reflection. Smaller additions reach Plan, Interview, Council, Domain, Idea Genie, Security, Skill Builder, Skill Eval and the rest. None has been measured with Skill Eval.
• A refresh of the 2026-10 practice-ranking snapshot fixed what it found still wrong. Retired review-rule wording (a fresh read and repair on every change) is gone from the upgrade guide, the vocabulary and bounded-context contracts, the trust-factory page, the component map, the kernel template, Doc's references and two eval cases; ADR-0017 marks the sections the 2026-10-03 amendment superseded. The rpi plugin-eval criterion c3 now grades the conditional rule. Domain's shipped Go standard no longer states AgentOps contributor facts as general guidance. RPI defines each stall category by an observable signature, without counts. Memory points a recurring correction a check could catch to Postmortem's lever rule. Doc's description is back under the 180-character budget, and smaller factual fixes reach Idea Genie, Skill Builder, Security, Implement, Review, Premortem, Interview, Research, Navigate, Council, Claude Exec, AGY Native and Agent Native.
• The Claude Code plugin now installs from plugin/, a generated folder that holds only what the plugin loads: skills, agents, the policy hook dispatcher and Workflow tool scripts, plus the manifest and a new listing icon. The marketplace entry points at ./plugin; install commands are unchanged. scripts/regen-plugin-tree.sh regenerates it and scripts/regen-all.sh --check fails when it is stale. The Codex plugin is unchanged.
• The plugin no longer puts bin/factory and bin/ralph on the Bash PATH. They are operator tools; run them from a repository checkout.
• The implement-wave workflow now runs its implementer lanes one at a time in the caller's working tree, as code-write does, so a wave takes the sum of its lane times. Lane scopes remain instructions rather than an enforced boundary, and the workflow no longer claims strictly disjoint ownership. Arguments and the result shape are unchanged. Worktree isolation is deferred.
• ao --help, ao quick-start, ao demo and ao robot-docs now state the review rule from 3.9: checks and CI gate an ordinary change, and one fresh read happens only where a mistake is costly. The 3.10 binary still printed the retired rule that every change needs a fresh judgment. ADR-0017 records the rule as a dated amendment.
• Doc, Implement, Security and Test gained optional references for developer journeys, difficult failures, attacker-path evidence, exploratory QA, suite audits and workload performance. Skill Eval chooses an evaluation by the runtime the caller authorized and by what is being measured.
• Agent Native's per-packet result and Orchestrate's status line report the last observed activity, and RPI's closeout names a stall by category and the fact observed. Plan writes into existing intent only with authority and otherwise proposes an amendment. Using GC's Mayor template no longer pushes or opens a PR unless publishing is authorized.
• Validate's summary check fails when a lane is cancelled or times out, and a full run fails on any skipped lane. The release publisher waits for a green Validate run on the exact tagged commit, and scripts/retag-release.sh pushes main before it changes any tag or release.
• Two gates that could not fail, always.mutation-route and always.file-manifest-overlap, are retired. The constraints.enforce repair hint no longer names the removed ao constraint command.
• Dependencies: Go toolchain 1.27.3, golang.org/x/text 0.43.0, golangci-lint 2.14.0 and updated GitHub Action pins. Steps that install the skill evaluator (in Validate, the nightly run and the release publisher) stay on Python 3.14 because Harbor's litellm dependency has no Python 3.15 release.

Fixed

• ao doctor fix keeps the run ID, the actions it applied and the backup paths in its error output when it cannot write its report. It still exits 74, so you can inspect or undo before retrying.
• Research no longer pre-approves Bash and unscoped Write through allowed-tools. It asks for permission the way the other skills do.
• The hooks tree no longer contains an npx launcher string, which the Claude Code plugin marketplace validator reported as blocking.
• The hook installer no longer says to prefix one command with AOP_WAIVE=<policy-id>. That never waived dispatcher policies, because the hook reads its own environment. Set AOP_WAIVE in the environment Claude is launched with, or add a <policy-id> <expiry-unix-epoch> line to the waiver file.

---

Full Changelog: v3.10.0...v3.11.0