Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 7 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,20 +1,22 @@
# Response Engineering

[![checks](https://github.com/prime-vector/response-engineering/actions/workflows/checks.yml/badge.svg?branch=main)](https://github.com/prime-vector/response-engineering/actions/workflows/checks.yml)

> You shifted left and fixed the pipeline. Production is still a person reading a dashboard at 3am. We engineer that layer.

Operations is a software problem. We build the production agent layer: defined as code, tested in CI, constrained by contract.

Built on [Open Agent Spec](https://github.com/prime-vector/open-agent-spec): a YAML format that defines an agent, its tasks, its output contracts and its sandbox in one file, and a CLI, `oa`, that runs the file and enforces what it declares.
A reference implementation of the investigation layer of incident response: six agents, each defined as an [Open Agent Spec](https://github.com/prime-vector/open-agent-spec) file, working one synthetic incident. Every claim one agent hands another carries a confidence word and the test that would prove it wrong, as required fields the output contract enforces. The Incident Commander's board cannot converge on a cause while any deciding evidence it lists is outstanding. A directed change to production is blocked before it is sent.

**[Watch the walkthrough](https://youtu.be/OTdecUh1C98)**, 4 minutes 37: the incident, the layer, the layer doing it, and the one thing it does not claim.

## What this is

A reference implementation of the investigation layer of incident response: six agents, each defined as an Open Agent Spec file, working one incident. It is not a product. The adapters are mocks and all of the data is synthetic: generated by scripts in this repository, or written by hand for it.
Open Agent Spec is a YAML format that defines an agent, its tasks, its output contracts and its sandbox in one file, and a CLI, `oa`, that runs the file and enforces what it declares. This repository is not a product. The adapters are mocks and all of the data is synthetic: generated by scripts in this repository, or written by hand for it.

The incident is a composite of a recurring pattern. Its hosts, dates, numbers and products are invented; [`SCENARIO.md`](SCENARIO.md) has it in full. A memory exhaustion problem on a production integration host opens and closes itself on thirteen of fifteen days, and nobody acknowledges it once. On day fifteen a business ticket starts an incident call. A careful analysis names a lead and says plainly it is not proof; within the hour it is relayed as one sentence with its caveats gone, and the call converges on a third party. The cause is never established.

The agents here are built so that cannot happen quietly. Every claim one agent hands another carries a confidence word and the test that would prove it wrong, as required fields the output contract enforces. The Incident Commander's board cannot converge on a cause while any deciding evidence it lists is outstanding. A directed change to production is blocked before it is sent. Each of those is a command you can run, below.
The agents here are built so that cannot happen quietly, by the three controls above, and each of those is a command you can run, below.

![Three evidence surfaces, each read by exactly one agent. The Telemetry Analyst, Change Correlator and Precedent Analyst each read one surface, and typed correlation and precedent reach the Incident Commander, with the Telemetry Analyst's findings marked as the handoff the pipeline does not compose, whose live board goes to the Scribe, whose timeline the driver files on the incident record sink, verified in the adapter log.](docs/diagrams/architecture.svg)

Expand All @@ -31,7 +33,6 @@ Every arrow between agents is a typed output whose claims carry `confidence` and
- **Surface**: a tool endpoint an agent reads (telemetry, change registry, precedent archive) or writes (incident record, host). Each is owned by exactly one agent.
- **Contract**: the output schema a task's result must satisfy. The runner refuses output that breaks it, with the gaps listed under Known limits.
- **Sandbox**: a task's allow list of tools. A call outside it is blocked before it is sent.
- **Grok, Sol, Astra**: the models that reviewed this repository's changes, named in PLAN.md and the evals notes where one of them found something. Grok reviews each push; Sol is the pre-merge gate, reading only the brief; Astra was asked once for a design question. None of them is part of what the repository builds.

### Try it without an API key

Expand Down Expand Up @@ -61,7 +62,7 @@ Six agents written, each validating under the OAS 1.6.2 CLI. The five investigat

| Artefact | State |
| --- | --- |
| `SCENARIO.md` | Reviewed, cadence fixed as asserted properties, both sanitisation passes done, the second by someone other than the author. What each pass covered is recorded in `PLAN.md`, including the directories that postdate the second |
| `SCENARIO.md` | Reviewed, cadence fixed as asserted properties |
| `.agents/*.yaml` | Six specs, all written and validating under the OAS 1.6.2 CLI. The Precedent Analyst's recall is verified live against the archive; Comms writes to outward audiences only and is never given the board |
| `interfaces/TELEMETRY.md` | Draft interface contract |
| `fixtures/composite-incident*.json` | Generated, two views (D+1 and D+15) plus three demo forcing inputs, feed properties asserted by the generator |
Expand All @@ -75,8 +76,7 @@ Six agents written, each validating under the OAS 1.6.2 CLI. The five investigat

```
SCENARIO.md source of truth, read this first
PLAN.md milestones and definition of done
CLAUDE.md working rules for this repo
CONTRIBUTING.md how to contribute, and what a change must pass
.agents/incident-commander.yaml holds the hypothesis board
.agents/telemetry-analyst.yaml detects recurrence in the problem feed
.agents/change-correlator.yaml correlates change history against onset
Expand Down
Loading