Some checks failed
validation / verify (push) Failing after 10s
A scope spec is a YAML file of what the customer wants and the facts a design depends on, complete or partly filled. It sits beside the Intent, which stays in the customer's words. - skills/scoping holds a provider-neutral catalogue of 63 fields; the Cloud provider's bundle supplies the values it allows for the fields left to it. - app/scope.py reads a spec against the catalogue with no model: it refuses an unknown field or a value of the wrong type, and yields what is stated, what is left to the agent, what is unknown and how pressing each gap is. A field may say ask, decide or not_applicable. - ExecutionEngine.start(scope=...), /generate, A2A metadata and evaluation cases accept one. Its statement is the request, its engagement reference names the Customer case, and its run options apply. A pre-approved start is refused when an essential field is not settled. - The spec as supplied is kept unaltered beside a completed copy with assumptions, gaps, provenance, readiness and a status. - Every Specialist is shown the spec and given the Skill: a stated choice binds, exclusions are out of scope. - Covers workloads and platform foundations; case-08-landing-zone starts from a benchmark spec. Plans for scoping (iteration 9) and the work breakdown structure (iteration 10, nothing built), and the design spec they come from. Not run with real models. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
365 lines
21 KiB
Markdown
365 lines
21 KiB
Markdown
# Spec: Scoping from a scope spec, and a work breakdown structure
|
|
|
|
Status: ready-for-agent
|
|
|
|
Accepted by the owner on 2026-10-11. Stage 1 is built; `.agents/plans/iter-09-scoping/` says what is done.
|
|
|
|
- Glossary: [`CONTEXT.md`](../../CONTEXT.md). New terms this would add are in **Language** below.
|
|
- Builds on: [ADR-0005](../../docs/adr/0005-the-target-architecture-is-an-explicit-graph.md) (ids along the Requirements chain), [ADR-0006](../../docs/adr/0006-a-change-request-starts-from-a-baseline-execution.md) (Change requests), [ADR-0002](../../docs/adr/0002-skills-are-the-portable-unit-of-behaviour.md) (behaviour in Skills).
|
|
- Would need: one new ADR, for a new first Phase and a new start to the Requirements chain.
|
|
|
|
## Problem
|
|
|
|
The Intent is the customer's request, saved word for word. For case 06 it is one sentence. Everything else a design needs (how many users, what availability, which region, what budget, which compliance regime, what exists today) is assumed by the requirements analyst or, in the evaluation, supplied by pattern-matched answers.
|
|
|
|
Three days of runs trace most downstream trouble to what nobody stated: Checks the validator asks for on topics the customer never raised, checklist items the request cannot settle, a "low-carbon region" no code can show. Nothing tells the customer at the start how much of their design rests on assumption, and a requirement does not record whether the customer stated it or the agent assumed it.
|
|
|
|
Separately, the agent delivers a design and its code but no plan for building it.
|
|
|
|
## Decisions taken
|
|
|
|
The owner accepted these defaults on 2026-10-11.
|
|
|
|
1. **Scoping is a Phase the customer approves,** before requirements discovery.
|
|
2. **Its centre is a scope spec:** a YAML file that may arrive complete, partly filled or not at all.
|
|
3. **Architects write the spec,** the owner and colleagues, not end customers. Field names may be technical.
|
|
4. **A small set of fields is essential** and always settled before work starts. Which they are depends on the kind of engagement.
|
|
5. **Two files.** The file supplied is never altered. A completed copy is written beside it.
|
|
6. **The run options live in the spec,** so one file starts an Execution.
|
|
7. **Where the spec and the prose request disagree, the spec wins** and the customer is shown the conflict.
|
|
8. **The work breakdown structure is a new Deliverable,** after validation, in the packaging Phase, grouped by component as the technical decomposition is, covering the technical build.
|
|
9. **Scoping is built before the work breakdown structure.**
|
|
|
|
## Language
|
|
|
|
Terms to add to `CONTEXT.md` when built:
|
|
|
|
- **Scope spec:** the structured statement of what the customer wants and the facts a design depends on, as a file. It sits beside the Intent, which stays in the customer's words.
|
|
- **Scoping:** the Phase that completes the scope spec and has the customer approve it.
|
|
- **Work breakdown structure:** the Deliverable that divides building the Target architecture into work packages and activities, with a timeline.
|
|
- **Work package:** a unit of work that delivers named Elements and is done when their Checks pass.
|
|
|
|
Already in the glossary and used here: Intent, Customer question, Change request, Baseline, Requirements chain.
|
|
|
|
## The scope spec
|
|
|
|
### What a field can say
|
|
|
|
Every field holds a value or one of three words:
|
|
|
|
| Written | Meaning | What the agent does |
|
|
|---|---|---|
|
|
| a value | The customer states this | Uses it. Recorded as `supplied`. |
|
|
| `ask`, or the field left out | Not known yet | Asks, when someone is present. Otherwise treats it as `decide` and lists it under `discovery_gaps`. |
|
|
| `decide` | You choose | Picks a default, recorded as `assumed` with the default and what it affects. |
|
|
| `not_applicable` | Does not apply | Asks nothing and assumes nothing. |
|
|
|
|
A field name the catalogue does not have is an error that names the field. Nothing is silently ignored.
|
|
|
|
### Tiers
|
|
|
|
| Tier | When it is settled |
|
|
|---|---|
|
|
| essential | Always, before any work: asked when someone is present, and refused with a list when nobody is and it is neither supplied nor `decide`. |
|
|
| important | Asked when someone is present; defaulted otherwise. |
|
|
| optional | Defaulted unless supplied. |
|
|
|
|
### The draft
|
|
|
|
Revised on 2026-10-11 to combine the first draft with the owner's own example, an engagement spec for a regulated landing zone. What each brought is listed under **How the two were combined**. Essential fields are marked; which are essential depends on `engagement.kind`. Values shown are from the owner's example.
|
|
|
|
```yaml
|
|
schema_version: 1 # the catalogue this file is written against
|
|
|
|
metadata:
|
|
customer_case: fintech-global-landing-zone # essential: groups this work's Executions
|
|
engagement_reference: ENG-2026-UK-084 # yours; carried through, never interpreted
|
|
client_name: FinTech Global UK
|
|
author: Pre-Sales Engineering
|
|
revision: "1.1.0" # yours: the version of this document
|
|
status: DRAFT # written by the agent; see Status below
|
|
|
|
engagement:
|
|
kind: platform_foundation # essential: workload | platform_foundation | migration
|
|
|
|
# 1. What the customer said. The source of truth; nothing here is rewritten.
|
|
intent:
|
|
statement: | # essential: verbatim, or consolidated from calls and documents
|
|
We are a UK-regulated payment platform expanding into Google Cloud. We need an
|
|
enterprise-grade landing zone ready in under 10 weeks ...
|
|
requirements: # what the customer stated outright, with their ids
|
|
- id: REQ-01
|
|
category: Timeline
|
|
statement: Platform foundation must be ready for workload ingestion within 10 weeks.
|
|
- id: REQ-03
|
|
category: Networking
|
|
statement: 10Gbps on-premises hybrid connectivity; centralized Palo Alto inspection for egress.
|
|
exclusions:
|
|
- Application container deployment (managed by app squads).
|
|
- Active-active secondary region in phase 1 (warm standby acceptable).
|
|
success_criteria: decide
|
|
|
|
# 2. Where it runs.
|
|
estate:
|
|
cloud_provider: gcp # essential; must be a provider this deployment has
|
|
mode: greenfield # essential: greenfield | brownfield_expansion | migration
|
|
regions:
|
|
primary: europe-west2 # essential
|
|
secondary: europe-west1
|
|
resiliency_tier: warm_standby
|
|
data_residency: United Kingdom # essential
|
|
existing_systems: ask
|
|
|
|
# 3. Who uses it and how hard. Essential for kind workload; not_applicable for a foundation.
|
|
workload:
|
|
users: {who: not_applicable, count: not_applicable, peak_concurrent: not_applicable}
|
|
availability: {target: ask, hours: always, recovery_time: ask, recovery_point: ask}
|
|
|
|
# 4. Regulation and governance.
|
|
compliance:
|
|
industry: financial_services
|
|
frameworks: [DORA, ISO27001, PCI_DSS_v4] # essential; an empty list means none apply
|
|
data_classification: confidential # essential
|
|
encryption: {type: cmek, key_rotation_days: 90}
|
|
audit_logging: {retention_days: 365, immutable_retention_policy: true}
|
|
|
|
# 5. Network.
|
|
networking:
|
|
exposure: internal_only # internal_only | internet_facing
|
|
topology: shared_vpc_hub_and_spoke # allowed values come from the Cloud provider's catalogue
|
|
hybrid_connectivity: {enabled: true, type: cloud_interconnect, bandwidth_gbps: 10}
|
|
egress_control: {model: centralized_appliance, appliance_vendor: palo_alto}
|
|
cidr_allocations: ask
|
|
|
|
# 6. Identity, environments and operations.
|
|
governance:
|
|
identity_source_of_truth: entra_id
|
|
pipeline_authentication: workload_identity_federation
|
|
environment_tiers:
|
|
- {name: development, archetype: corp_workload}
|
|
- {name: staging, archetype: corp_workload}
|
|
- {name: production, archetype: pci_regulated_workload}
|
|
operations:
|
|
operating_model: central_platform_broker
|
|
support_hours: decide
|
|
monitoring: decide
|
|
integrations: []
|
|
|
|
# 7. How it will be delivered. The work breakdown structure is built from this.
|
|
delivery:
|
|
target_start_date: 2026-11-01
|
|
window_weeks: 10 # essential when the customer has a deadline
|
|
commercial_model: fixed_price_milestone
|
|
iac_tooling: terraform
|
|
ci_cd: github_actions
|
|
team_size: ask
|
|
working_days_per_week: 5
|
|
|
|
cost:
|
|
monthly_budget: ask # essential for kind workload
|
|
currency: GBP
|
|
|
|
# 8. How to run the agent.
|
|
run:
|
|
pre_approved: false
|
|
allow_cloud_read: false
|
|
overlay_skills: []
|
|
terraform_modules: false
|
|
```
|
|
|
|
### Sections the agent writes
|
|
|
|
Only in the completed copy. The supplied file never has to carry them, and if it does they are read as the last run's and replaced.
|
|
|
|
```yaml
|
|
inferred_assumptions:
|
|
- id: ASSUMP-01
|
|
field: networking.hybrid_connectivity
|
|
category: Network Telecom
|
|
statement: Assumes the client manages the carrier circuit lead time for the 10Gbps interconnect.
|
|
impact_if_invalid: Blocks the hybrid routing test; delays every activity after it.
|
|
|
|
discovery_gaps:
|
|
- field: networking.cidr_allocations
|
|
prompt: Specify IP subnet sizes for spoke workloads, for example /22 per environment.
|
|
severity: HIGH # HIGH is an essential field; MEDIUM important; LOW optional
|
|
|
|
provenance: # where every settled value came from
|
|
estate.regions.primary: supplied
|
|
cost.monthly_budget: answered
|
|
operations.monitoring: assumed
|
|
|
|
readiness: {supplied: 34, answered: 3, assumed: 6, unknown: 2}
|
|
```
|
|
|
|
`provenance` is one of `supplied`, `answered`, `discovered` (read from the customer's cloud environment), `assumed`, `unknown`. Every `assumed` field has an entry in `inferred_assumptions`, and every `unknown` one in `discovery_gaps`.
|
|
|
|
### Status
|
|
|
|
The owner's example carries a status. The agent sets it in the completed copy from what has happened; a status written by the author is not trusted.
|
|
|
|
| Status | Means |
|
|
|---|---|
|
|
| `DRAFT` | Gaps remain, or the conversation is still filling them. |
|
|
| `UNDER_REVIEW` | Complete, and waiting for the scoping Approval. |
|
|
| `APPROVED` | The customer approved it; requirements and the later Phases run from it. |
|
|
| `BASELINE_LOCKED` | Its Execution completed. This copy is the record a Change request starts from, and is never altered. |
|
|
|
|
### How the two were combined
|
|
|
|
| From the owner's example | How it is kept |
|
|
|---|---|
|
|
| The request, verbatim, inside the spec | `intent.statement`. It is also still saved as the Intent, as today. |
|
|
| The customer's stated requirements, with ids | `intent.requirements`. The agent's requirements trace to these ids, so the Requirements chain starts at what the customer wrote. |
|
|
| Stated exclusions | `intent.exclusions`. The design is checked for nothing built that is excluded. |
|
|
| Engagement metadata and status | `metadata`, with the status set by the agent. |
|
|
| Estate, compliance, networking and governance sections | Kept as written. |
|
|
| Start date, delivery window, commercial model, tooling | `delivery`. The window becomes a limit the plan is checked against. |
|
|
| Assumptions with their impact, and gaps with a prompt and a severity | The two agent-written sections, in place of the first draft's flat provenance table. Severity is the tier. |
|
|
|
|
| From the first draft | How it is kept |
|
|
|---|---|
|
|
| `ask`, `decide` and `not_applicable` | Unchanged. The example had no way to say "not known" other than omission. |
|
|
| Tiers | Kept, as the severity of a gap. |
|
|
| Two files | Kept. The author's file is untouched; the agent's sections go in the completed copy. |
|
|
| Where each value came from | Kept, as `provenance`. |
|
|
| Users, scale, availability target, budget | Kept under `workload` and `cost`, and essential only for a workload. |
|
|
| Run options | Kept under `run`. |
|
|
|
|
### Where the two pull apart
|
|
|
|
Four tensions, each with the resolution proposed. They are the owner's to confirm.
|
|
|
|
1. **The example states solution choices; the agent keeps requirements free of them.** A hub-and-spoke topology, an interconnect, customer-managed keys and a named inspection appliance are design decisions. The rule that requirements name no products exists so the agents do not pick a design before the design Phase. It should not stop a customer who has already decided. Proposed: a choice the spec states is a constraint the design must honour and may not change, recorded as supplied. The agents still add none of their own.
|
|
2. **The example is a landing zone; the agent has only designed workloads.** Every benchmark case is an application. A platform foundation has no users or response times, and has an organisation hierarchy, shared networking and environment archetypes the cases have never exercised. `engagement.kind` lets one spec serve both, but a platform foundation is a new kind of work for the agent and needs its own evaluation case before it is relied on.
|
|
3. **The example uses one Cloud provider's vocabulary in general fields.** `shared_vpc_hub_and_spoke`, `cloud_interconnect` and `cmek` are Google Cloud's terms. Proposed: the general catalogue says a field such as `networking.topology` exists; the Cloud provider's bundle supplies its allowed values. A second provider then brings its own list and the spec's shape does not change.
|
|
4. **"Engagement" is a word the glossary avoids.** The agent's term is Customer case. Proposed: `customer_case` stays the key the agent groups by, and `engagement_reference` carries the owner's own number untouched. If the owner would rather the agent's term became Engagement, that is a glossary change to make before this is built.
|
|
|
|
### Where the catalogue lives
|
|
|
|
A provider-neutral Skill holds the catalogue: each field's type, tier by engagement kind, the question to ask, and guidance for the default. A Cloud provider's bundle adds its allowed values and any fields of its own. An overlay Skill may raise a field's tier, so an organisation can make `compliance.encryption` essential. Code validates a spec against the catalogue; no model decides what is missing.
|
|
|
|
## How scoping runs
|
|
|
|
| What arrives | What happens |
|
|
|---|---|
|
|
| A complete spec | Validated. No gaps, no questions. With `pre_approved` the Phase passes without stopping. |
|
|
| A partly filled spec, someone present | Gaps are asked for, essential first, a few related fields at a time, with a count of how many are settled. |
|
|
| A partly filled spec, nobody present | Essential gaps refuse the start, with the list. Others are defaulted and recorded. |
|
|
| Only a sentence | A model drafts a spec from it, marking everything it did not find as `ask`. It is then a partly filled spec. |
|
|
|
|
In conversation an answer is a value, "you decide", or "skip". A skipped field becomes `unknown` and a Customer question in the output. A free-text answer is turned into the field's value and read back before it is written. The customer may supply an edited file at any point in place of answering.
|
|
|
|
The Phase ends when the customer approves the completed spec.
|
|
|
|
### What it writes
|
|
|
|
Under the Customer case, beside the Intent:
|
|
|
|
```
|
|
intent/
|
|
001.md # the request, in the customer's words (as today)
|
|
001.scope.yaml # the spec as supplied, unaltered; absent when none was
|
|
001.scope.completed.yaml # the completed copy: status, assumptions, gaps, provenance, readiness
|
|
```
|
|
|
|
The scoping Deliverable is a short document written from the completed copy: the scope statement, the information register as a table, and the readiness summary. The solution guide opens with that summary.
|
|
|
|
### What it changes downstream
|
|
|
|
- **The requirements analyst derives; it no longer asks or assumes.** Each requirement names the stated requirement (`REQ-03`) or the spec field it comes from, so the Requirements chain starts at what the customer wrote. A requirement from an `assumed` field says so.
|
|
- **A stated choice binds the design.** A product, topology or setting the spec states is carried to the design as a constraint, and a design that departs from it is refused.
|
|
- **Exclusions are checked.** Nothing in `intent.exclusions` may appear in the Target architecture.
|
|
- **Customer questions** from the pillar checklists (built 2026-10-10) are joined by the `unknown` fields.
|
|
- **A Change request may be an edited spec.** Code compares the two specs field by field, and that list is what changed. A sentence still works, as now.
|
|
- **An evaluation case becomes a spec,** replacing the pattern-matched answers.
|
|
|
|
## The work breakdown structure
|
|
|
|
A new Deliverable in the packaging Phase, produced by a new Specialist after validation, summarised in the solution guide.
|
|
|
|
### Its data file
|
|
|
|
```json
|
|
{
|
|
"work_packages": [
|
|
{"id": "WP-1", "name": "Network foundation", "parent": null,
|
|
"components": ["C-2"], "elements": ["E-1", "E-2"],
|
|
"scope": "The VPC, its subnet and outbound access.",
|
|
"produces": ["a private network the services attach to"],
|
|
"skills": ["network engineering"]}
|
|
],
|
|
"activities": [
|
|
{"id": "A-1", "work_package": "WP-1", "name": "Create the VPC and subnet",
|
|
"days": 1, "after": []},
|
|
{"id": "A-2", "work_package": "WP-1", "name": "Configure outbound access",
|
|
"days": 1, "after": ["A-1"]}
|
|
]
|
|
}
|
|
```
|
|
|
|
### What code checks and computes
|
|
|
|
- Every Element belongs to a work package, and every work package to a component or a parent. A design cannot be left out of the plan.
|
|
- A work package's acceptance criteria are the Checks on its Elements. They are read from the Target architecture, not written again.
|
|
- Activities form no cycle, and every `after` names an activity that exists.
|
|
- **The plan is checked against the delivery window.** When `delivery.window_weeks` is set and the computed total exceeds it, the Deliverable says so and names the critical path; it does not shorten estimates to fit.
|
|
- **An assumption can hold up the plan.** An entry in `inferred_assumptions` that an activity depends on, such as a carrier's lead time, appears as a dependency the customer owns, so its `impact_if_invalid` is visible on the timeline.
|
|
- **Milestones.** With a `commercial_model` of fixed price by milestone, each top-level work package ends in a milestone.
|
|
- **The schedule is computed, not written.** From each activity's days and what it comes after, code works out its earliest start and finish, the critical path and the total. With `delivery.team_size` it limits how many activities run at once.
|
|
|
|
### What it renders
|
|
|
|
Three views, all written by code from the data file, as the architecture diagram is:
|
|
|
|
- **WBS dictionary:** the hierarchy, each work package with its scope, what it produces, its Elements, its acceptance Checks and the skills it needs.
|
|
- **Activity sequence list:** each activity with its days, what it follows, its start and finish day, and whether it is on the critical path.
|
|
- **Timeline** on a relative axis, Day 0 to Day N:
|
|
|
|
```
|
|
Activity Day 0 5 10 15 18
|
|
A-1 Create the VPC and subnet ██
|
|
A-2 Configure outbound access ██
|
|
A-3 Provision the database █████
|
|
A-4 Deploy the application ████
|
|
A-5 Load balancer and access ███
|
|
A-6 Monitoring and alerts ██
|
|
A-7 Validation in test ████
|
|
```
|
|
|
|
The chart format is to be settled when built: a Mermaid Gantt chart if it can show a relative day axis, and otherwise a drawn table like the one above.
|
|
|
|
### What it says about itself
|
|
|
|
Durations are a model's estimates. The Deliverable states their basis (working days, the team size from the spec) and that they are indicative. The timeline stays on a relative day axis; when `delivery.target_start_date` is set, the activity list also gives calendar dates.
|
|
|
|
## Order of work
|
|
|
|
| Stage | What | Usable on its own |
|
|
|---|---|---|
|
|
| 1 | The catalogue, validation, the gap list, the two files saved beside the Intent, the run options read from the spec | Yes: a complete spec starts a pre-approved Execution |
|
|
| 2 | The conversation that fills gaps; scoping as a Phase with its Deliverable and Approval; a spec drafted from a sentence | Yes |
|
|
| 3 | Requirements traced to spec fields; readiness in the guide | Yes |
|
|
| 4 | An edited spec as a Change request | Yes |
|
|
| 5 | The work breakdown structure | Yes, with stage 1 for `delivery` |
|
|
| 6 | Evaluation cases as specs | Yes |
|
|
|
|
## Not in this spec
|
|
|
|
- Attaching documents (a statement of work, a diagram) as a source for the spec.
|
|
- Reading the customer's cloud environment to fill `current_estate`. The `discovered` source is reserved for it.
|
|
- Delivery activities beyond the technical build, such as security review, user acceptance and cutover.
|
|
- Cost of the work, or named people.
|
|
|
|
## Open questions
|
|
|
|
1. The four tensions under **Where the two pull apart**: are the proposed resolutions right?
|
|
2. Which fields are essential for each engagement kind? The draft marks them; the owner's example suggests the delivery window and compliance frameworks matter more than budget for a foundation.
|
|
3. In `pre_approved` runs an essential gap refuses the start. Is that right, or should it default and warn?
|
|
4. Should the scoping Approval be skippable when the spec arrived complete and someone is present?
|
|
5. Is a platform foundation in scope now, with its own evaluation case, or should scoping be built against workloads first?
|
|
|
|
## Comments
|
|
|
|
- 2026-10-11, the owner: a platform foundation is in scope now; an engagement name and a Customer case are equivalent references; the implementation will eventually be provider-agnostic. The other tensions and open questions were taken as proposed: a stated choice binds the design; an essential gap refuses a pre-approved start; the scoping Approval is not skipped. Recorded in ADR-0008.
|