Files
gcp_solution_architecture_a…/.scratch/scoping-and-work-breakdown/spec.md
Jonathan Boniface afe78640f8
Some checks failed
validation / verify (push) Failing after 10s
feat: start an Execution from a scope spec (ADR-0008, iteration 9 step 1)
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>
2026-10-11 17:53:00 +01:00

21 KiB

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. New terms this would add are in Language below.
  • Builds on: ADR-0005 (ids along the Requirements chain), ADR-0006 (Change requests), ADR-0002 (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.

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.

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

{
  "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.