feat: working TOM agent

This commit is contained in:
2026-10-21 19:47:12 +01:00
commit efe543e6e2
83 changed files with 11779 additions and 0 deletions

View File

@@ -0,0 +1,50 @@
---
name: operating-capabilities
description: >-
The capability catalogue: what an operating organisation may need to be able to
do, in our own words, with the industry frameworks each entry draws on. Use when
choosing the Capabilities of an operating model and writing the Checks on them.
---
# The capability catalogue
`assets/catalogue.yaml` lists the Capabilities an operating model is built from. `assets/sources.yaml` is the register of the frameworks they cite.
## How to use it
1. Your task's context lists the entries code found to apply to this operating spec, under `capabilities_proposed`. Start from those.
2. Take every proposed entry, or say in your Deliverable why one does not apply. Add any other entry the solution needs.
3. A Capability names its entry by `catalogue`. One the catalogue does not have is `custom`, with a `reason`: use it only when no entry fits, never to rename one.
4. Give each Capability the Items it covers and the Operational requirements it serves. Every Item must be covered by at least one Capability, and every Operational requirement served by at least one.
5. An entry's `typical_checks` are where to start when writing Checks. Rewrite each for this solution: name the Item, and put the customer's own numbers in.
## What the sources are for
A source says where an idea comes from. Cite it in a Deliverable as the catalogue does, by framework and by the name of the part. Never quote a framework's text and never say an operating model is certified against, or compliant with, a framework: the catalogue draws on them and promises nothing about them.
The register's `status` says whether a person has checked the references. While it is `unverified`, say so wherever a source is cited to a customer.
## People and teams
Two frameworks shape who does the work, not only what it is:
- **Team Topologies** (`team-topologies`). An operating model for a platform may group its Roles into teams, each of one of four kinds: `stream_aligned`, `platform`, `enabling` or `complicated_subsystem`. Two teams work together in one of three modes: `collaboration`, `x_as_a_service` or `facilitating`. A collaboration is a stage for discovering something together, not a standing arrangement, so it says when it ends.
- **Platform as a product** (`platform-as-a-product`). A platform is run for the teams that build on it, as a product they choose to use: someone owns its roadmap and orders the backlog by what slows those teams down, adoption is earned by a supported default path, and their satisfaction is measured.
For a platform foundation, the catalogue proposes `platform-product-management`, `self-service-and-golden-paths` and `enablement` from these.
## Measuring at three layers
`delivery-and-developer-experience-measurement` draws on three frameworks at once, because each measures a different layer and none stands in for another:
| Layer | Framework | What it tells you |
| --- | --- | --- |
| Outcome | `dora-metrics` | How fast and how safely changes reach production: lagging. |
| Guardrail | `space-framework` | Whether productivity is sustainable across several dimensions, including wellbeing. |
| Leading signal | `devex-framework` | The friction, feedback loops and cognitive load teams meet: what to improve next. |
Never write a Check that measures only one layer and calls it productivity.
Every one of these is a means. In the operating model each is a **Measure** tied to a business outcome the customer stated: deployment frequency to "new products reach customers sooner", developer satisfaction to "we keep the engineers we hire", time to restore to "payments are never down for long". A measure that serves no stated outcome is not measured.
Two things are called DORA. `eu-dora` is the European regulation on operational resilience. `dora-metrics` is the research programme's four delivery measures. Name each in full.

View File

@@ -0,0 +1,281 @@
# The capability catalogue: what an operating organisation may need to be able to do.
#
# Every entry is in our own words and cites the frameworks it draws on, each of
# which must be in sources.yaml. `domain` groups entries. `applies_when` says when
# code proposes the entry for an operating spec:
# always: true every operating model
# item_kinds: [database, storage] when the spec lists an Item of one of these kinds
# compliance: [DORA] when the spec names one of these frameworks
# sourcing: [shared] for these sourcing models
# engagement_kinds: [platform_foundation] for these kinds of engagement
# `follows_support_hours: true` marks a capability that must be staffed for at
# least the hours the spec says faults are responded to.
schema_version: 1
capabilities:
- id: incident-management
name: Incident management
domain: service_operations
purpose: Restore a service that is degraded or down, and say what happened.
applies_when: {always: true}
follows_support_hours: true
typical_checks:
- The most serious incident is acknowledged within the agreed time, at any hour faults are responded to.
- Every incident of the most serious kind has a written review.
sources:
- {framework: itil-4, reference: Incident management practice}
- {framework: google-sre, reference: Managing Incidents}
- {framework: iso-20000-1, reference: Incident management}
- {framework: eu-dora, reference: "Article 17, ICT-related incident management process"}
- id: monitoring-and-alerting
name: Monitoring and alerting
domain: service_operations
purpose: Know the state of what is run, and tell the right people when it needs them.
applies_when: {always: true}
follows_support_hours: true
typical_checks:
- Every Item has a signal that shows whether it is serving, and an alert when it is not.
- Every alert names who receives it and what they do.
sources:
- {framework: itil-4, reference: Monitoring and event management practice}
- {framework: google-sre, reference: Monitoring Distributed Systems}
- {framework: nist-csf-2, reference: "Detect: Continuous Monitoring"}
- {framework: eu-dora, reference: "Article 10, Detection"}
- id: problem-management
name: Problem management
domain: service_operations
purpose: Find why incidents happen and remove the cause.
applies_when: {always: true}
typical_checks:
- A recurring incident has a named cause and an owner for removing it.
sources:
- {framework: itil-4, reference: Problem management practice}
- {framework: google-sre, reference: "Postmortem Culture: Learning from Failure"}
- id: service-request-fulfilment
name: Service request fulfilment
domain: service_operations
purpose: Handle what users and teams ask for that is not a fault, such as access or a new environment.
applies_when: {always: true}
typical_checks:
- Each kind of request has a stated way to ask and a stated time to fulfil.
sources:
- {framework: itil-4, reference: Service request management practice}
- {framework: iso-20000-1, reference: Service request management}
- id: change-enablement
name: Change enablement
domain: change
purpose: Make changes to what is run with the risk of each understood and accepted.
applies_when: {always: true}
typical_checks:
- Every change to a production Item is reviewed by someone other than its author before it is applied.
- Every change can be traced to who approved it.
sources:
- {framework: itil-4, reference: Change enablement practice}
- {framework: iso-20000-1, reference: Change management}
- {framework: dora-metrics, reference: Change failure rate}
- id: release-and-deployment
name: Release and deployment
domain: change
purpose: Put approved changes into service repeatably, and take them out again when they fail.
applies_when: {always: true}
typical_checks:
- A failed deployment can be rolled back within the agreed recovery time.
sources:
- {framework: itil-4, reference: Release management and Deployment management practices}
- {framework: google-sre, reference: Release Engineering}
- {framework: dora-metrics, reference: Deployment frequency and lead time for changes}
- id: configuration-management
name: Configuration management
domain: change
purpose: Know what is run, how it is configured, and that it matches what was approved.
applies_when: {always: true}
typical_checks:
- The configuration of every Item is held in version control and compared with what is running.
sources:
- {framework: itil-4, reference: Service configuration management practice}
- {framework: nist-csf-2, reference: "Identify: Asset Management"}
- id: backup-and-recovery
name: Backup and recovery
domain: resilience
purpose: Keep copies of what cannot be rebuilt, and prove they can be restored.
applies_when: {item_kinds: [database, storage, data]}
typical_checks:
- A restore of every data store is tested on a schedule, and the result recorded.
sources:
- {framework: itil-4, reference: Service continuity management practice}
- {framework: nist-csf-2, reference: "Recover: Incident Recovery Plan Execution"}
- {framework: eu-dora, reference: "Article 12, Backup policies and procedures, restoration and recovery procedures and methods"}
- id: service-continuity
name: Service continuity
domain: resilience
purpose: Restore service after the loss of a site, a region or a supplier, within the agreed time.
applies_when: {always: true}
typical_checks:
- Recovery from the loss of the primary location is rehearsed, and takes no longer than the agreed recovery time.
sources:
- {framework: itil-4, reference: Service continuity management practice}
- {framework: iso-20000-1, reference: Service continuity management}
- {framework: eu-dora, reference: "Article 11, Response and recovery"}
- id: capacity-and-performance
name: Capacity and performance management
domain: resilience
purpose: Keep enough capacity for demand, and no more than is paid for knowingly.
applies_when: {always: true}
typical_checks:
- Each Item's use is reviewed against its limits on a schedule.
sources:
- {framework: itil-4, reference: Capacity and performance management practice}
- {framework: iso-20000-1, reference: Capacity management}
- id: access-management
name: Access management
domain: security_operations
purpose: Give people and systems the access they need, and take it away when they no longer do.
applies_when: {always: true}
typical_checks:
- Access to production is granted for a stated reason and reviewed on a schedule.
- The team that responds to incidents has a tested way in at any hour it is on call.
sources:
- {framework: nist-csf-2, reference: "Protect: Identity Management, Authentication, and Access Control"}
- {framework: iso-27001, reference: Access control}
- {framework: eu-dora, reference: "Article 9, Protection and prevention"}
- id: vulnerability-and-patch-management
name: Vulnerability and patch management
domain: security_operations
purpose: Find weaknesses in what is run and remove them within an agreed time.
applies_when: {always: true}
typical_checks:
- A weakness of the most serious kind is fixed or accepted in writing within the agreed time.
sources:
- {framework: nist-csf-2, reference: "Protect: Platform Security"}
- {framework: iso-27001, reference: Management of technical vulnerabilities}
- {framework: eu-dora, reference: "Article 9, Protection and prevention"}
- id: security-monitoring-and-response
name: Security monitoring and response
domain: security_operations
purpose: Detect misuse of what is run and respond to it.
applies_when: {always: true}
follows_support_hours: true
typical_checks:
- Security events from every Item reach the people who watch for them.
sources:
- {framework: nist-csf-2, reference: "Detect: Adverse Event Analysis; Respond: Incident Management"}
- {framework: iso-27001, reference: Information security incident management}
- {framework: eu-dora, reference: "Article 10, Detection"}
- id: cost-management
name: Cost management
domain: financial_operations
purpose: Know what running costs, who it is spent for, and when it departs from plan.
applies_when: {always: true}
typical_checks:
- Spend is reported against budget monthly, by Item.
- Spend that departs from forecast raises an alert to a named Role.
sources:
- {framework: finops-framework, reference: "Allocation; Budgeting; Forecasting; Anomaly Management"}
- id: service-level-management
name: Service level management
domain: governance
purpose: Agree what the service must achieve, measure it, and report it.
applies_when: {always: true}
typical_checks:
- Each service level the customer stated is measured and reported on a schedule.
sources:
- {framework: itil-4, reference: Service level management practice}
- {framework: google-sre, reference: Service Level Objectives}
- {framework: iso-20000-1, reference: Service level management}
- id: platform-product-management
name: Platform product management
domain: platform_product
purpose: >-
Run the platform as a product for the teams that build on it: learn what slows
them down, keep a roadmap and a backlog ordered by that friction, and measure
whether they choose to use it.
applies_when: {engagement_kinds: [platform_foundation]}
typical_checks:
- A named Role owns the platform's roadmap and orders its backlog by what slows the teams that use it.
- Adoption and the satisfaction of the teams that use the platform are measured on a schedule and reported.
sources:
- {framework: platform-as-a-product, reference: Platform as a product; Measuring platform success}
- {framework: team-topologies, reference: Platform team; Thinnest viable platform}
- id: self-service-and-golden-paths
name: Self-service and golden paths
domain: platform_product
purpose: >-
Offer what the teams building on the platform need as self-service, with a
supported default way to do the common things, so that using it is the
easier choice rather than a rule.
applies_when: {engagement_kinds: [platform_foundation]}
typical_checks:
- The common requests of the teams that use the platform are met through self-service, with no ticket.
- Every self-service path is documented and has a named owner.
sources:
- {framework: team-topologies, reference: X-as-a-Service interaction mode}
- {framework: platform-as-a-product, reference: Platform capabilities; Self-service}
- id: enablement
name: Enablement
domain: platform_product
purpose: >-
Help the teams that build on the platform adopt it, by pairing, pilots,
documentation and training, for a stated time, rather than by mandate.
applies_when: {engagement_kinds: [platform_foundation]}
typical_checks:
- Each engagement to help a team adopt the platform has a stated goal and end date.
sources:
- {framework: team-topologies, reference: Enabling team; Facilitating interaction mode}
- {framework: platform-as-a-product, reference: Platform as a product}
- id: delivery-and-developer-experience-measurement
name: Delivery and developer experience measurement
domain: governance
purpose: >-
Measure how well work flows through the platform at three layers that answer
different questions: delivery speed and stability, the outcome; productivity
and wellbeing across the team, the guardrail; and the friction teams meet,
the leading signal of what to improve next. No one layer stands in for another.
applies_when: {engagement_kinds: [platform_foundation, workload]}
typical_checks:
- Deployment frequency, lead time for changes, change failure rate and time to restore service are measured and reported monthly.
- Productivity is reviewed across more than one dimension, including satisfaction and wellbeing, and never by an activity count alone.
- The friction teams meet, their feedback loops and their cognitive load, are surveyed on a schedule and set the order of the platform's backlog.
sources:
- {framework: dora-metrics, reference: Deployment frequency; Lead time for changes; Change failure rate; Time to restore service}
- {framework: space-framework, reference: "Satisfaction and well-being; Performance; Activity; Communication and collaboration; Efficiency and flow"}
- {framework: devex-framework, reference: Feedback loops; Cognitive load; Flow state}
- id: supplier-management
name: Supplier management
domain: governance
purpose: Hold the suppliers the service depends on to what they agreed.
applies_when: {sourcing: [provider_operated, shared]}
typical_checks:
- Each supplier the service depends on has a named owner and a way to escalate.
sources:
- {framework: itil-4, reference: Supplier management practice}
- {framework: iso-20000-1, reference: Supplier management}
- {framework: eu-dora, reference: "Article 28, General principles on ICT third-party risk"}
- id: regulatory-evidence
name: Regulatory evidence and reporting
domain: governance
purpose: Keep the evidence a regulation asks for and report what it requires, when it requires it.
applies_when: {compliance: [DORA, PCI_DSS_v4, ISO27001, ISO_27001, SOC_2]}
typical_checks:
- Evidence each named framework asks for is kept for as long as it asks.
sources:
- {framework: eu-dora, reference: "Article 19, Reporting of major ICT-related incidents"}
- {framework: iso-27001, reference: Compliance with legal and contractual requirements}

View File

@@ -0,0 +1,82 @@
# The register of frameworks the capability catalogue cites.
#
# A capability's entry is written in our own words. A framework is named as a
# source, by the title of the part drawn on, and never quoted. `status` says
# whether a person has checked the entry's references against the framework:
# every reference here was drafted from general knowledge of the framework and is
# `unverified` until someone has.
schema_version: 1
status: unverified
frameworks:
itil-4:
name: ITIL 4
publisher: PeopleCert
version: "4"
licence: Proprietary; cited by practice name, not reproduced.
google-sre:
name: "Site Reliability Engineering: How Google Runs Production Systems"
publisher: Google / O'Reilly
version: "2016"
licence: Published under a no-derivatives licence; cited by chapter title, not reproduced.
finops-framework:
name: FinOps Framework
publisher: FinOps Foundation
version: "2024"
licence: Openly licensed with attribution; cited by capability name.
nist-csf-2:
name: NIST Cybersecurity Framework
publisher: National Institute of Standards and Technology
version: "2.0"
licence: Public domain; cited by function and category.
iso-20000-1:
name: ISO/IEC 20000-1
publisher: ISO/IEC
version: "2018"
licence: Proprietary; cited by requirement title, not reproduced.
iso-27001:
name: ISO/IEC 27001
publisher: ISO/IEC
version: "2022"
licence: Proprietary; cited by control theme, not reproduced.
eu-dora:
# The EU regulation. Not the DevOps Research and Assessment programme's metrics.
name: Regulation (EU) 2022/2554, the Digital Operational Resilience Act
publisher: European Union
version: "2022"
licence: Public law; cited by article.
dora-metrics:
# The research programme's delivery metrics. Not the EU regulation above.
name: DevOps Research and Assessment (DORA) software delivery metrics
publisher: Google Cloud
version: "2023"
licence: Publicly published research; cited by metric name.
# Socio-technical and organisational frameworks: how people, teams and
# responsibilities are structured around what is operated.
team-topologies:
name: "Team Topologies: Organizing Business and Technology Teams for Fast Flow"
publisher: Matthew Skelton and Manuel Pais, IT Revolution
version: "2019"
licence: Proprietary; cited by the names of its team types and interaction modes, not reproduced.
platform-as-a-product:
# The practice of running an internal platform as a product for the teams that
# use it. Cited from the CNCF's write-up of it, the most widely referenced one.
name: CNCF Platforms White Paper (platform as a product)
publisher: Cloud Native Computing Foundation, TAG App Delivery
version: "2023"
licence: Openly published; its licence is to be confirmed; cited by section, not reproduced.
# Measuring how well the work flows, at three layers. None replaces another.
space-framework:
name: "The SPACE of Developer Productivity"
publisher: Forsgren, Storey, Maddila, Zimmermann, Houck and Butler, ACM Queue
version: "2021"
licence: Published article; cited by its five dimensions, not reproduced.
devex-framework:
name: "DevEx: What Actually Drives Productivity"
publisher: Noda, Storey, Forsgren and Greiler, ACM Queue
version: "2023"
licence: Published article; cited by its three dimensions, not reproduced.
sfia:
name: Skills Framework for the Information Age
publisher: SFIA Foundation
version: "9"
licence: Proprietary; cited by skill name, not reproduced.

View File

@@ -0,0 +1,51 @@
---
name: operating-chain
description: >-
The data files of a target operating model and how each traces to the one before:
operational requirements, capabilities, the Target operating model graph,
findings and verdicts. Use when writing or checking any of these files, and
whenever a submission is refused for a missing link.
---
# The operating chain
Every Deliverable of a target operating model carries a data file. Each entry has an id, and each file names the ids of the file before it. A submission is refused while a link is missing, and the refusal says which.
```
operating spec solution.items (S-n), solution.conditions (K-n),
intent.requirements, and its settled fields
│
operational-requirements.json OR-n source: a stated requirement, a Condition, or a field
│
capabilities.json C-n serves: OR ids items: S ids
│
target-operating-model.json parties P-n, roles R-n,
responsibilities RS-n capability: C id, role: R id
measures M-n outcome: BO id measured_by: C id
checks OC-n on: C, R or RS id source: OR or K id
│
verdicts.json a verdict on every OC id
```
## What is refused
| File | Refused when |
| --- | --- |
| `operational-requirements.json` | A requirement has no `source`, or names one that is not a stated requirement, a Condition or a settled field. A stated requirement or a binding field is carried by no requirement. |
| `capabilities.json` | A Capability names no catalogue entry and is not `custom` with a reason. It serves nothing, or names an id that does not exist. An Item is covered by no Capability. A requirement is served by none. A Capability that responds to faults is staffed for narrower hours than faults are responded to. Its effort is missing, or has no basis. |
| `target-operating-model.json` | A Role is in no Party, or in a country or at a level the rate card lacks, or outside the countries the customer allows. A Capability has no accountable Role, or more than one, or no responsible Role, or none that works its hours. A Condition is carried by no Check. A Check is on, or sourced from, something that does not exist. |
| measures, in `target-operating-model.json` | A business outcome the customer stated is shown by no Measure. A Measure shows an outcome that was not stated, or is taken by a Capability nobody is responsible for. Where the model measures how work flows, the outcome, guardrail and leading layers are not all measured. |
| `findings.json` | A finding lacks `lacks`, `proposed` or `needed_by`, names no Item of the solution under `about`, or names an id that does not exist. |
| `verdicts.json` | A Check has no verdict. A Check that depends on a finding passes: it is `not_verifiable` while the finding stands, or `fail` when the validator judges the operating model could meet it itself, such as by staffing or hours. |
## What code writes
Never write these yourself. They are computed from your data when you submit, so they cannot disagree with it:
- the responsibility matrix, the organisation chart (`organisation.mmd`) and the staffing and cost (`staffing.json`), from the Target operating model;
- the scenario walk-throughs (`scenarios.json`) and their verdicts, from the Target operating model and the operating spec;
- the verdict `waits_on_finding` on a Check that depends on a finding. The validator gives such a Check `not_verifiable`; it is recorded as waiting on its finding, and nothing is revised for it.
## Ids
Keep an id for as long as the thing it names exists. In a Change request an unchanged entry keeps its id and its text; a new one takes an id never used before; a removed one is left out. Never renumber.

View File

@@ -0,0 +1,27 @@
---
name: operating-guide
description: >-
The template of the operating model guide and who writes each part of it: the
packager writes the summary, and code writes every table and figure from the
data. Use when packaging a target operating model into its guide.
---
# The operating model guide
`assets/guide-template.md` is the guide's template. It has nine sections, in a fixed order.
## What you write
Only the **Summary**: one or two short paragraphs for the person who will run the solution. Say what is operated, who operates it and how the work is divided between the Parties, during which hours, and what they should look at first: a finding, a Check that waits on one, a scenario that fails, a cost over its budget.
State no number of people, no cost and no count. The key figures are set under your paragraph from the data, and a figure you wrote could differ from them.
## What is written for you
Every other section. Submit each of the template's headings with nothing under it, or a line saying it is written from the data: whatever you put there is replaced when you submit. The tables, the figures, the verdicts and the citations all come from the data files of the other Deliverables, so they cannot disagree with them.
## What you never do
- Never add a decision, a recommendation or a caveat of your own. The guide assembles what was decided.
- Never restate a figure, even in the summary.
- Never say the operating model complies with, or is certified against, a framework.

View File

@@ -0,0 +1,58 @@
# Operating model guide: <the solution, in a few words>
## Summary
<Written by the packager. One or two short paragraphs for the person who will run
the solution: what is operated, who operates it and how the work is divided between
the Parties, during which hours, and what they should look at first. No number of
people, no cost and no count: the key figures are set under this paragraph from the
data.>
### Key figures
<Written by code: what is operated, the hours, the Capabilities, people and cost
with the rate card's version, the scenario walk-throughs, and the findings.>
## Business outcomes
<Written by code: each business outcome the customer stated, with the Measures
that show it is served, their layer and framework, the Capability that takes each,
and the Role answerable for it.>
## What is operated
<Written by code from the operating scope: the Items, the Conditions that must be
kept true, and anything known to be at risk when operations begin.>
## Operational requirements
<Written by code: each requirement, its kind, and what it comes from.>
## Capabilities
<Written by code: each Capability, the requirements it serves, the Items it covers,
its hours and its effort.>
## Who does what
<Written by code: the Roles and their Parties, and the responsibility matrix.>
## Staffing and cost
<Written by code from the rate card: people and cost for each Role and in total,
the budget when one was stated, the rate card's version, and the conversion rate.>
## Validation
<Written by code: the verdict on each Check with its evidence, and each scenario
walk-through with the path traced for it.>
## Findings and open questions
<Written by code: every finding, everything assumed for the customer, and
everything still unknown.>
## Sources
<Written by code: the frameworks the Capabilities draw on, cited by framework and
by the name of the part, and whether those references have been checked.>

View File

@@ -0,0 +1,47 @@
---
name: operating-scoping
description: >-
What an operating spec's fields mean and how each is settled: the solution to be
operated, how it must be operated, who operates it, and in which currency its
cost is stated. Use when completing the operating scope, and whenever a
Deliverable must honour what the customer stated.
---
# The operating spec
An operating spec is the structured statement an Execution starts from. It holds what the customer wants from operations, the facts an operating model depends on, and the solution to be operated. `assets/catalogue.yaml` lists every field.
## What a field can say
| Written | Meaning | What you do |
| --- | --- | --- |
| a value | The customer states this | Use it as given. It binds the operating model. |
| `ask`, or the field left out | Not known yet | Ask when someone is present. |
| `decide` | You choose | Pick a value and record it as an assumption, with what it would change. |
| `not_applicable` | Does not apply | Ask and assume nothing. |
## Business outcomes
`intent.business_outcomes` is what the business wants from the solution, in the customer's words, each with an id (`BO-1`) and, where they give one, a target. Every measure in the operating model must show one of them, and each must be shown by at least one. Ask for them when someone is present: an operating model whose measures serve no stated outcome cannot show it is worth what it costs. Never invent one; one the customer did not state is not an outcome of theirs.
## The solution
- `solution.items` is what is to be operated. Every Item must be covered by a Capability. Never add an Item, remove one or rename one: it is the customer's description of their solution, or the digest of their architecture.
- `solution.conditions` is what must be kept true of an Item while it is run. Every Condition must be carried by a Check.
- `source_ref` on an Item or a Condition is its id where it came from, such as an Element or a Check of a solution architecture. Keep it.
- Something operations needs that the solution does not provide is a **finding**. Record it; do not design around it.
## What binds
A stated value of a field marked `binds` in the catalogue, and every requirement under `intent.requirements`, must be named as the `source` of an Operational requirement. What was assumed does not bind: it is shown apart and may change when the customer answers.
## Who operates
- `sourcing.model` says whether the customer, a service provider, or both operate the solution. It decides which Parties the operating model has.
- `sourcing.delivery_countries`, when stated, are the only countries a Role may sit in.
## Cost
- `commercial.currency` is the currency every cost is stated in. It is always settled before work begins.
- The customer's own staff are counted and never priced.
- Nobody states a rate in a spec. Rates are the service provider's, in the rate card Skill.

View File

@@ -0,0 +1,214 @@
# The operating spec's catalogue: every field an operating spec may hold.
#
# A field is a dotted path. `type` is one of: string, text, integer, number, boolean,
# date, list, enum, records. `tier` says when it must be settled: essential (always,
# before any work), important (asked when someone is present) or optional. A tier
# may differ by the kind of engagement. `question` is what to ask the customer for
# it. `default` guides the choice when the customer says "decide". `affects` says
# what a wrong assumption would change. `binds: true` marks a choice an operating
# model must honour: stated by the customer, it has to reach an Operational
# requirement.
#
# This catalogue names no Cloud provider and no currency. A provider's bundle adds
# the allowed values for the fields marked `provider_values`.
schema_version: 1
kinds: [workload, platform_foundation, migration]
fields:
metadata.customer_case:
type: string
tier: essential
aliases: [metadata.engagement_id]
question: What short reference identifies this engagement?
metadata.client_name:
type: string
metadata.author:
type: string
metadata.revision:
type: string
# Where the spec was digested from, when it was: written by the digest.
metadata.source:
type: string
engagement.kind:
type: enum
values: [workload, platform_foundation, migration]
tier: essential
question: >-
Is what is to be operated an application workload, a platform foundation
such as a landing zone, or systems being migrated?
intent.statement:
type: text
tier: essential
question: In the customer's own words, what do they want from operations?
intent.requirements:
type: records
keys: [id, statement]
optional_keys: [category]
question: Which requirements for operations has the customer stated outright?
intent.business_outcomes:
# What the business wants from the solution, in the customer's words. Every
# measure in the operating model must show one of these.
type: records
keys: [id, outcome]
optional_keys: [target, category]
# Essential: everything measured is tied to one, so they are settled before
# anything is designed. With nobody to ask, they are assumed and shown apart.
tier: essential
question: >-
What does the business want from this solution, and how would it know it was
getting it? Give each outcome a short id, such as BO-1.
default: >-
Take them from what the request says the solution is for. Two or three, each
something the business would notice, such as changes reaching customers
sooner or outages being short.
affects: what is measured, and what each measure is for
intent.exclusions:
type: list
tier: important
question: What has the customer said is out of scope for operations?
default: Nothing is excluded beyond what the statement implies.
affects: which Capabilities are designed
# --- the solution to be operated -----------------------------------------------
solution.cloud_provider:
type: enum
provider_values: true
tier: essential
question: Which Cloud provider does the solution run on?
solution.items:
type: records
keys: [id, name, kind]
# `elements` are the ids of the parts of a design an Item stands for;
# `evidence` is the passage a drafted Item was read from.
optional_keys: [product, environments, source_ref, elements, evidence]
tier: essential
question: What is to be operated? List each thing, with a short id and its kind.
solution.conditions:
type: records
# `on` is the id of the Item it is a condition on, or a list of them.
keys: [id, "on", condition]
optional_keys: [source_ref, evidence]
tier: important
question: What must be kept true of each thing while it is run?
default: None beyond what the service levels state.
affects: the Checks the operating model must carry
solution.build.duration_days:
type: integer
tier: important
question: How many working days is the solution's build planned to take?
default: Not known; the transition is planned without a build to fit.
affects: when Capabilities must be ready
solution.build.customer_owned:
type: list
question: Which parts of the build does the customer or their supplier own?
solution.inherited_risks:
type: records
keys: ["on", risk]
optional_keys: [source_ref]
question: What is already known to be unverified or at risk in the solution?
# --- how it is to be operated ---------------------------------------------------
operations.support_hours:
binds: true
type: enum
values: [business, extended, 24x7]
tier: essential
question: >-
During which hours must faults be responded to: business hours, extended
hours, or every hour of every day?
operations.availability_hours:
type: enum
values: [business, extended, 24x7]
tier: important
question: During which hours must the solution be available to its users?
default: The same as the support hours.
affects: whether support hours are wide enough
operations.change_process:
type: text
tier: important
question: How are changes approved and released today, and must that continue?
default: Changes go through a pipeline with peer review and no separate board.
affects: change enablement and release
operations.monitoring:
type: text
question: Which monitoring and alerting is already in place or required?
sourcing.model:
binds: true
type: enum
values: [customer_operated, provider_operated, shared]
tier: essential
question: >-
Who operates the solution: the customer, a service provider, or the two
together?
sourcing.delivery_countries:
binds: true
type: list
tier: important
question: From which countries may the solution be operated? Use country codes.
default: No restriction beyond where the data may be handled.
affects: where Roles sit, and the cost
organisation.existing_teams:
type: records
keys: [name, party]
optional_keys: [skills, hours, country]
tier: {migration: essential, workload: important, platform_foundation: important}
question: Which teams exist today that will have a part in operating this?
default: None exist; every Role is new.
affects: which Roles are new and which are filled
organisation.headcount_limit:
type: integer
question: Is there a limit on the number of people operating this?
service_management.tooling:
type: text
tier: important
question: Which service management and on-call tooling must be used?
default: The Cloud provider's own operations tooling, with no separate system.
affects: tooling and the processes written for it
service_levels.priority_1_response_minutes:
binds: true
type: integer
tier: important
question: Within how many minutes must the most serious incident be acknowledged?
default: 30
affects: on-call arrangements and staffing
service_levels.recovery_time_hours:
binds: true
type: number
tier: important
question: Within how many hours must service be restored after a major failure?
default: 4
affects: continuity arrangements
compliance.frameworks:
type: list
tier: important
question: Which regulations or standards must operations comply with?
default: None beyond the organisation's own policies.
affects: which Capabilities apply and what they must evidence
commercial.currency:
type: enum
provider_values: true
tier: essential
question: In which currency should the cost of operating be stated?
commercial.monthly_run_budget:
type: number
question: Is there a monthly budget for operating this, in that currency?
transition.go_live_date:
type: date
question: When must the solution be in operation?
# --- how to run the agent -------------------------------------------------------
run.pre_approved:
type: boolean
question: Should the agent run without stopping for approvals?
run.overlay_skills:
type: list
question: Which overlay Skills should this Execution load?

36
skills/rate-card/SKILL.md Normal file
View File

@@ -0,0 +1,36 @@
---
name: rate-card
description: >-
The service provider's rate card: day rates by country and level, the
productive days in each country, conversion rates, and the smallest team that
can cover each pattern of hours. Use when placing Roles in countries and
choosing their levels, in the Target operating model and organisation design.
metadata:
scope: the Target operating model and organisation design
owner: the service provider
---
# Rate card
`assets/rates.yaml` is the service provider's rate card. The provider sets every figure in it. Nothing else does: not a caller, not an operating spec, and not you.
While its `version` starts with `draft`, the figures are placeholders and say so wherever a total is shown.
## What you do with it
- Give every Role a `country` and a `level` that the card has. A Role in a country or at a level the card lacks is refused when you submit.
- Place Roles only in the countries the operating spec lists under `sourcing.delivery_countries`, when it lists any.
- Choose the level from what the Role's Capabilities ask of it, using the description of each level in the card. Do not choose a level to reach a cost.
- Choose the country for a reason you state: the hours the Role must cover, the language it must work in, where the data may be handled, where the customer's own teams sit.
## What you never do
- Never write a number of people, a rate or a cost. People per Role, cost per Role and every total are computed from the card when you submit, and written into your Deliverable for you.
- Never use a rate from anywhere else. A rate a customer states is a question for the provider, recorded as a customer question, and changes nothing.
- Never convert a currency. The operating spec states the currency of the result, and the conversion is made from the card's fixed rates when you submit.
## What the card decides
- A Role that covers hours wider than a working day is never sized below the card's `minimum_roster` for that cover, however little effort its Capabilities need. Covering every hour from one country needs a rota; covering it from several countries in turn needs a Role in each, each on `business` or `extended` hours.
- Work outside business hours carries the card's `uplift`.
- The customer's own staff are never priced: a Role in a customer Party is shown as people, with no cost. Of the other Parties, only the kinds the card lists under `prices` are costed.

View File

@@ -0,0 +1,56 @@
# The service provider's rate card. Its prices are set by the provider who runs
# this agent, and by nobody else: not a caller, not an operating spec, not a model.
#
# PLACEHOLDERS: while `version` below starts with `draft`, every figure here was
# drafted to build and test the arithmetic and is not a price anyone has set.
# Set each one, then change `version`.
#
# `day_rate` is what one day of one person at that level is charged at, in
# `currency`. `productive_days` is the days in a year a person works on the
# service, after leave, public holidays and training. `hours_per_day` is the
# working day. Countries are ISO 3166-1 alpha-2 codes.
schema_version: 1
name: rate-card
version: draft-2026-10-13
currency: USD # what the rates below are written in
# The operating spec states the currency of the result (`commercial.currency`).
# These are the fixed rates used to convert into it: units of that currency for
# one unit of `currency` above. Set by the provider with the prices; no rate is
# looked up. A currency not listed cannot be asked for.
conversion:
as_of: 2026-10-13
rates: {USD: 1.00, GBP: 0.79, EUR: 0.92, CAD: 1.37, AUD: 1.52, JPY: 150, INR: 84}
# Which Parties this card prices, by kind. Roles of any other Party are counted
# as people and carry no cost. The customer's own staff are never priced, and
# `customer` may not be listed here.
prices: [provider]
levels:
engineer: Runs established procedures and resolves known faults.
senior: Diagnoses unfamiliar faults, automates, and leads a shift.
lead: Accountable for a Capability; designs the way of working.
# The fewest people who can staff a Role for a pattern of hours, and what is
# added to their rate for it. A Role is never sized below `minimum_roster`,
# however little effort its Capabilities need.
cover:
business: {minimum_roster: 1, uplift: 1.00} # one working day, five days a week
extended: {minimum_roster: 3, uplift: 1.10} # about sixteen hours, five days a week
24x7: {minimum_roster: 5, uplift: 1.25} # every hour of every day, from one country
countries:
US: {name: United States, productive_days: 225, hours_per_day: 8, day_rate: {engineer: 720, senior: 960, lead: 1250}}
CA: {name: Canada, productive_days: 222, hours_per_day: 7.5, day_rate: {engineer: 600, senior: 800, lead: 1020}}
GB: {name: United Kingdom, productive_days: 220, hours_per_day: 7.5, day_rate: {engineer: 600, senior: 800, lead: 1050}}
DE: {name: Germany, productive_days: 215, hours_per_day: 8, day_rate: {engineer: 640, senior: 850, lead: 1100}}
ES: {name: Spain, productive_days: 218, hours_per_day: 8, day_rate: {engineer: 420, senior: 560, lead: 740}}
PL: {name: Poland, productive_days: 220, hours_per_day: 8, day_rate: {engineer: 340, senior: 460, lead: 620}}
HU: {name: Hungary, productive_days: 220, hours_per_day: 8, day_rate: {engineer: 320, senior: 430, lead: 580}}
IN: {name: India, productive_days: 230, hours_per_day: 8, day_rate: {engineer: 180, senior: 260, lead: 380}}
PH: {name: Philippines, productive_days: 230, hours_per_day: 8, day_rate: {engineer: 190, senior: 270, lead: 390}}
BR: {name: Brazil, productive_days: 222, hours_per_day: 8, day_rate: {engineer: 260, senior: 360, lead: 500}}
MX: {name: Mexico, productive_days: 228, hours_per_day: 8, day_rate: {engineer: 280, senior: 380, lead: 520}}
JP: {name: Japan, productive_days: 225, hours_per_day: 8, day_rate: {engineer: 620, senior: 820, lead: 1080}}
AU: {name: Australia, productive_days: 222, hours_per_day: 7.6, day_rate: {engineer: 640, senior: 850, lead: 1100}}