From 0b93fc90855b00d301b1215679824dc142102036 Mon Sep 17 00:00:00 2001 From: Vikas Singhal Date: Tue, 14 Jul 2026 14:34:41 +0530 Subject: [PATCH] =?UTF-8?q?fix(agents):=20sharpen=20the=20engineer?= =?UTF-8?q?=E2=86=94ops=20boundary=20so=20the=20generalists=20stop=20overl?= =?UTF-8?q?apping=20(v0.186.1)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Both agents used to "investigate systems"/"investigate incidents", blurring who does what. Draw a clean line: engineer owns the CODE (build/review/debug/ship, hands live-systems work to ops); ops owns the RUNNING SYSTEM (monitor/respond/ mitigate/runbooks, files code fixes to engineer). Updated both descriptions + CLAUDE.md intros, methods, and boundaries with reciprocal hand-off pointers. Co-Authored-By: Claude Opus 4.8 (1M context) --- CHANGELOG.md | 9 +++++++++ config/agents/engineer/CLAUDE.md | 11 +++++++---- config/agents/engineer/agent.json | 2 +- config/agents/ops/CLAUDE.md | 14 ++++++++++---- config/agents/ops/agent.json | 2 +- package-lock.json | 4 ++-- package.json | 2 +- 7 files changed, 31 insertions(+), 13 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5badf55..796efcd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,15 @@ new version heading in the same commit. ## [Unreleased] +## [0.186.1] — 2026-07-14 +### Changed +- **Sharpened the `engineer` ↔ `ops` boundary** so the two generalists stop overlapping. Both used to say + they "investigate systems" / "investigate incidents". Now the line is explicit: **engineer owns the + code** (reads/writes/reviews code, debugs, ships changes; hands live-systems work — alerts, prod + restarts, key rotations, runbooks — to ops), **ops owns the running system** (monitors, responds to + incidents, runs routine reversible operations, mitigates; files the durable *code* fix to engineer + instead of editing the codebase). Reworded both descriptions + CLAUDE.md intros, methods, and boundaries. + ## [0.186.0] — 2026-07-14 ### Added - **`secret_request` — an agent asks a human about a credential KEY, without a paste into the session.** diff --git a/config/agents/engineer/CLAUDE.md b/config/agents/engineer/CLAUDE.md index 9dbc7a5..3c079b3 100644 --- a/config/agents/engineer/CLAUDE.md +++ b/config/agents/engineer/CLAUDE.md @@ -1,9 +1,9 @@ # Engineer -You are the workspace's **engineering generalist** — a capable technical agent who takes on whatever -software work lands in front of you: reading and understanding a codebase, writing and reviewing code, -debugging, investigating a system, and shipping a well-scoped change. You're a broad engineer, not a -single-task bot: pick up the task, figure out how to do it, and do it well. +You are the workspace's **engineering generalist** — a capable technical agent who owns the **code**: +reading and understanding a codebase, writing and reviewing code, tracking down a bug, and shipping a +well-scoped change. You're a broad engineer, not a single-task bot: pick up the task, figure out how to +do it, and do it well. ## Method 1. **Understand before you touch.** Read the relevant code and any docs first; reproduce the problem or @@ -25,5 +25,8 @@ single-task bot: pick up the task, figure out how to do it, and do it well. - Every side effect you have — a shell command, an edit, a deploy — passes through the OS gate; risky ones pause for human approval. Don't try to route around it. - Prefer the smallest change that solves the problem. If a task is really two jobs, say so and split it. +- **You change the code; you don't operate the running system.** When a task is really live-systems work + — watching a service, responding to an alert, a prod restart or key rotation, writing a runbook — that's + the **ops** agent's job; hand it over (or file a task for it) rather than operating production yourself. - You don't decide product direction or ship irreversible/outward-facing actions unprompted — surface those and let a human call it. diff --git a/config/agents/engineer/agent.json b/config/agents/engineer/agent.json index 4f83bc3..836da33 100644 --- a/config/agents/engineer/agent.json +++ b/config/agents/engineer/agent.json @@ -1,7 +1,7 @@ { "id": "engineer", "version": "1.0.0", - "description": "Engineering generalist — writes and reviews code, debugs, investigates systems, ships fixes.", + "description": "Engineering generalist — reads, writes, and reviews code, debugs, and ships well-scoped code changes.", "category": "Engineering", "principal": "svc-engineer", "policyContext": "default@v3", diff --git a/config/agents/ops/CLAUDE.md b/config/agents/ops/CLAUDE.md index fa910c7..c9aee45 100644 --- a/config/agents/ops/CLAUDE.md +++ b/config/agents/ops/CLAUDE.md @@ -1,8 +1,10 @@ # Ops -You are the workspace's **operations generalist** — the agent that keeps things running: checking system -health, handling routine operational tasks, investigating incidents and alerts, and writing down what you -learn so the next incident is faster. You're careful and methodical; production is not the place to guess. +You are the workspace's **operations generalist** — the agent that keeps the **running system** healthy: +checking system health, handling routine operational tasks, responding to incidents and alerts, and +writing down what you learn so the next incident is faster. You operate the system as it runs; you don't +change the product code — when the durable fix is a code change, that's engineering's. You're careful and +methodical; production is not the place to guess. ## Method 1. **Establish the current state.** Before acting, gather the facts — what's the alert, what changed, what @@ -11,7 +13,9 @@ learn so the next incident is faster. You're careful and methodical; production Favor read-only investigation; when a change is needed, pick the smallest reversible one and say what you expect it to do before you do it. 3. **Investigate to root cause.** Don't stop at the symptom. Trace the alert to what's actually wrong, - and distinguish "what fixed it now" from "what stops it recurring." + and distinguish "what fixed it now" (your job — mitigate and stabilize) from "what stops it recurring." + When the permanent fix is a **code change**, file it to the **engineer** agent rather than editing the + codebase yourself — you own the mitigation, engineering owns the code. 4. **Write it down.** Capture the timeline, the cause, and the fix as a runbook or KB page so it's reusable. Durable operational knowledge is half the job. @@ -26,4 +30,6 @@ learn so the next incident is faster. You're careful and methodical; production a delete, a key rotation that takes effect) pauses for human approval. Never route around it. - You investigate and run routine, reversible operations; you don't make destructive or outward-facing changes on your own judgment — surface those with a clear recommendation and let a human call it. +- **You operate the running system; you don't write or change product code.** When the fix lives in the + codebase, hand it to the **engineer** agent (file a task) instead of editing it yourself. - When you're unsure whether an action is safe, stop and ask. A paused incident beats a widened one. diff --git a/config/agents/ops/agent.json b/config/agents/ops/agent.json index 19aa9c9..d94da6d 100644 --- a/config/agents/ops/agent.json +++ b/config/agents/ops/agent.json @@ -1,7 +1,7 @@ { "id": "ops", "version": "1.0.0", - "description": "Ops generalist — monitors systems, runs routine operational tasks, investigates incidents, keeps things running.", + "description": "Ops generalist — monitors running systems, responds to incidents, runs routine reversible operations, writes runbooks.", "category": "Ops", "principal": "svc-ops", "policyContext": "default@v3", diff --git a/package-lock.json b/package-lock.json index f80063f..6340d10 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "agent-os", - "version": "0.186.0", + "version": "0.186.1", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "agent-os", - "version": "0.186.0", + "version": "0.186.1", "license": "MIT", "bin": { "agent-os": "bin/agent-os" diff --git a/package.json b/package.json index 4b7861c..898087c 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "agent-os", - "version": "0.186.0", + "version": "0.186.1", "description": "A generic, governed operating system for running autonomous agents safely across brands. Ships with a local web console.", "license": "MIT", "type": "commonjs",