Files
solution_architecture_agent/app/solution_architecture/work_breakdown.py
Jonathan Boniface c84dbdea20 feat: the solution architecture agent on the shared Execution engine
The reference agent's subject, cloud solution architecture, as an agent in
the operating model agent's pattern: the Execution engine (from
orchestration_engine) and one Workflow in app/solution_architecture,
built for the settings and provider bundle by assembly.workflow_for.

Copied from gcp_solution_architecture_agent at 8b397cd without its own
engine: its role files, Skills, provider bundle, ADRs, vocabulary, scripts
and evaluation datasets. The image takes the engine from a named build
context and installs Terraform. It is called through the Orchestration
engine, and its files are what the operating model agent digests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-21 19:49:28 +01:00

560 lines
22 KiB
Python

"""The work breakdown structure: a plan for building the Target architecture.
A Specialist divides the build into work packages and activities and estimates each
activity's days. Everything after that is code, as it is for the architecture
diagram: the plan is checked against the design, the schedule is computed from the
days and the dependencies, and the three views a reader sees are written from the
result. So the timeline cannot disagree with the plan, and no part of the design can
be left out of it.
work packages a hierarchy; each delivers named Elements, and is done when the
Checks on those Elements pass
activities what is done, in which work package, for how many days, after
which other activities, and by whom
schedule each activity's start and finish day, on a relative axis from
Day 0, with no more of the team's activities at once than the
team has people; and the critical path
"""
from __future__ import annotations
import datetime as dt
import json
import math
from collections.abc import Mapping, Sequence
from dataclasses import dataclass
from typing import Any
from app.solution_architecture.chain import Upstream, agreed_scope, read_graph
WORK_BREAKDOWN_FILE = "work-breakdown.json"
TIMELINE_FILE = "timeline.mmd"
DICTIONARY_HEADING = "WBS dictionary"
TEAM, CUSTOMER = "team", "customer"
OWNERS = (TEAM, CUSTOMER)
DEFAULT_TEAM_SIZE = 2
DEFAULT_WEEK = 5
MAX_DAYS = 120 # one activity; anything longer is a work package, not an activity
_CHART_WIDTH = 60
@dataclass(frozen=True)
class Scheduled:
id: str
start: float
finish: float
critical: bool
def _text(value: Any) -> str:
return " ".join(str(value or "").split())
def _list(value: Any) -> list[str]:
return [str(item) for item in value] if isinstance(value, list) else []
def parse(text: str) -> tuple[list[dict[str, Any]], list[dict[str, Any]], list[str]]:
"""(work packages, activities, problems) from the data file."""
name = WORK_BREAKDOWN_FILE
try:
data = json.loads(text)
except ValueError as exc:
return [], [], [f"{name}: not valid JSON ({exc})"]
if not isinstance(data, Mapping):
return [], [], [f"{name}: must be an object with work_packages and activities"]
packages = [p for p in data.get("work_packages") or [] if isinstance(p, Mapping)]
activities = [a for a in data.get("activities") or [] if isinstance(a, Mapping)]
return [dict(p) for p in packages], [dict(a) for a in activities], []
def check_work_breakdown(
attachments: Mapping[str, str], upstream: Upstream | None
) -> list[str]:
name = WORK_BREAKDOWN_FILE
packages, activities, problems = parse(attachments.get(name, ""))
if problems:
return problems
if not packages:
return [f"{name}: lists no work packages"]
if not activities:
return [f"{name}: lists no activities"]
ids = [str(p.get("id", "")) for p in packages]
problems += [f"{name}: a work package has no id"] if "" in ids else []
problems += [
f"{name}: work package id {dup} is used more than once"
for dup in sorted({i for i in ids if i and ids.count(i) > 1})
]
known = set(ids)
parents = {str(p.get("id")): p.get("parent") for p in packages}
for package in packages:
ident, parent = str(package.get("id")), package.get("parent")
if not _text(package.get("name")):
problems.append(f"{name}: {ident} has no name")
if parent is not None and str(parent) not in known:
problems.append(
f"{name}: {ident} has parent {parent}, which does not exist"
)
seen, node = {ident}, parent
while node is not None and str(node) in parents:
if str(node) in seen:
problems.append(f"{name}: {ident} is its own ancestor")
break
seen.add(str(node))
node = parents[str(node)]
graph = read_graph(upstream)
if graph is not None:
elements = {element.id for element in graph.elements}
covered: set[str] = set()
for package in packages:
listed = _list(package.get("elements"))
covered.update(listed)
problems += [
f"{name}: {package.get('id')} delivers {element}, which is not an "
"Element of the Target architecture"
for element in listed
if element not in elements
]
left = sorted(elements - covered)
if left:
problems.append(
f"{name}: no work package delivers {', '.join(left)}; every Element "
"of the Target architecture belongs to one"
)
activity_ids = [str(a.get("id", "")) for a in activities]
problems += [
f"{name}: activity id {dup} is used more than once"
for dup in sorted({i for i in activity_ids if i and activity_ids.count(i) > 1})
]
known_activities = set(activity_ids)
with_work = set()
for activity in activities:
ident = str(activity.get("id", ""))
if not ident or not _text(activity.get("name")):
problems.append(f"{name}: an activity needs an id and a name")
continue
within = str(activity.get("work_package", ""))
if within not in known:
problems.append(f"{name}: {ident} is in {within}, not a work package")
with_work.add(within)
days = activity.get("days")
if isinstance(days, bool) or not isinstance(days, (int, float)) or days <= 0:
problems.append(f"{name}: {ident} needs `days`, a number above 0")
elif days > MAX_DAYS:
problems.append(
f"{name}: {ident} is {days} days; split anything over {MAX_DAYS}"
)
problems += [
f"{name}: {ident} comes after {before}, which is not an activity"
for before in _list(activity.get("after"))
if before not in known_activities
]
if activity.get("owner", TEAM) not in OWNERS:
problems.append(f"{name}: {ident} owner must be one of {', '.join(OWNERS)}")
has_children = {str(parent) for parent in parents.values() if parent is not None}
problems += [
f"{name}: {ident} has no activity and no work package beneath it"
for ident in ids
if ident and ident not in with_work and ident not in has_children
]
if not problems and _cycle(activities):
problems.append(
f"{name}: activities depend on each other in a circle: "
+ " -> ".join(_cycle(activities))
)
return problems
def _cycle(activities: Sequence[Mapping[str, Any]]) -> list[str]:
"""Activities that depend on each other in a circle; empty when none do."""
after = {str(a["id"]): _list(a.get("after")) for a in activities}
state: dict[str, int] = {}
def visit(node: str, path: list[str]) -> list[str]:
state[node] = 1
for before in after.get(node, ()):
if state.get(before) == 1:
return (
[*path[path.index(before) :], before]
if before in path
else [before, node]
)
if state.get(before, 0) == 0:
found = visit(before, [*path, before])
if found:
return found
state[node] = 2
return []
for node in after:
if state.get(node, 0) == 0:
found = visit(node, [node])
if found:
return found
return []
def schedule(
activities: Sequence[Mapping[str, Any]], team_size: int = DEFAULT_TEAM_SIZE
) -> dict[str, Scheduled]:
"""Each activity's start and finish day, from Day 0.
An activity starts when everything it comes after has finished. The team's own
activities also wait for a free person: no more run at once than `team_size`.
What the customer owns, such as a supplier's lead time, takes nobody from the
team. The critical path is every activity with no slack: delay it and the end
moves.
"""
team_size = max(1, int(team_size))
by_id = {str(a["id"]): a for a in activities}
after = {ident: _list(a.get("after")) for ident, a in by_id.items()}
days = {ident: float(a["days"]) for ident, a in by_id.items()}
# The longest chain of work that follows an activity: what to start first when
# people are short.
followers: dict[str, list[str]] = {ident: [] for ident in by_id}
for ident, befores in after.items():
for before in befores:
followers[before].append(ident)
tail: dict[str, float] = {}
def remaining(ident: str) -> float:
if ident not in tail:
tail[ident] = days[ident] + max(
(remaining(f) for f in followers[ident]), default=0.0
)
return tail[ident]
start: dict[str, float] = {}
finish: dict[str, float] = {}
busy: list[tuple[float, float]] = [] # the team's activities already placed
pending = set(by_id)
while pending:
ready = [i for i in pending if all(b in finish for b in after[i])]
ready.sort(key=lambda i: (-remaining(i), i))
ident = min(
ready,
key=lambda i: (
max((finish[b] for b in after[i]), default=0.0),
-remaining(i),
i,
),
)
earliest = max((finish[b] for b in after[ident]), default=0.0)
if by_id[ident].get("owner", TEAM) == TEAM:
candidates = sorted({earliest, *(end for _, end in busy if end > earliest)})
for moment in candidates:
overlapping = sum(
1 for s, e in busy if s < moment + days[ident] and e > moment
)
if overlapping < team_size:
earliest = moment
break
busy.append((earliest, earliest + days[ident]))
start[ident], finish[ident] = earliest, earliest + days[ident]
pending.discard(ident)
end = max(finish.values(), default=0.0)
latest: dict[str, float] = {}
def latest_finish(ident: str) -> float:
if ident not in latest:
latest[ident] = min(
(latest_finish(f) - days[f] for f in followers[ident]), default=end
)
return latest[ident]
return {
ident: Scheduled(
ident,
start[ident],
finish[ident],
critical=latest_finish(ident) - finish[ident] < 1e-6,
)
for ident in by_id
}
# --- what the plan is checked against, from the agreed scope ----------------------------
def _scoped(scope: Mapping[str, Any], path: str) -> Any:
"""A field of the agreed scope, stated or assumed; None when it is neither."""
node: Any = scope.get("stated") or {}
for part in path.split("."):
node = node.get(part) if isinstance(node, Mapping) else None
if node is not None:
return node
for item in scope.get("assumed") or []:
if isinstance(item, Mapping) and item.get("field") == path:
return item.get("value")
return None
def delivery_terms(upstream: Upstream | None) -> dict[str, Any]:
"""Team size, working week, window and start date, from the agreed scope."""
scope = agreed_scope(upstream)
def number(path: str, default: int) -> int:
value = _scoped(scope, path)
ok = (
isinstance(value, (int, float))
and not isinstance(value, bool)
and value > 0
)
return int(value) if ok else default
window = _scoped(scope, "delivery.window_weeks")
start = _scoped(scope, "delivery.target_start_date")
try:
start_date = dt.date.fromisoformat(str(start)) if start else None
except ValueError:
start_date = None
return {
"team_size": number("delivery.team_size", DEFAULT_TEAM_SIZE),
"team_size_stated": _scoped(scope, "delivery.team_size") is not None,
"week": number("delivery.working_days_per_week", DEFAULT_WEEK),
"window_weeks": window if isinstance(window, (int, float)) else None,
"start": start_date,
}
# --- the three views --------------------------------------------------------------------
def _day(value: float) -> str:
return str(int(value)) if float(value).is_integer() else f"{value:.1f}"
def _calendar(start: dt.date, day: float, week: int) -> dt.date:
"""The calendar date of a working day counted from `start`."""
weeks, days = divmod(math.floor(day), week)
return start + dt.timedelta(days=weeks * 7 + days)
def render(attachments: Mapping[str, str], upstream: Upstream | None) -> str:
"""The WBS dictionary, the activity sequence and the timeline, as markdown
written from the data file. "" when the file cannot be read."""
packages, activities, problems = parse(attachments.get(WORK_BREAKDOWN_FILE, ""))
if problems or not packages or not activities:
return ""
terms = delivery_terms(upstream)
plan = schedule(activities, terms["team_size"])
graph = read_graph(upstream)
checks: dict[str, list[str]] = {}
for check in graph.checks if graph else ():
checks.setdefault(check.applies_to, []).append(check.id)
parents = {str(p["id"]): p.get("parent") for p in packages}
def depth(ident: str) -> int:
level, node = 0, parents.get(ident)
while node is not None and str(node) in parents and level < 10:
level, node = level + 1, parents.get(str(node))
return level
effort: dict[str, float] = {}
for activity in activities:
effort[str(activity["work_package"])] = effort.get(
str(activity["work_package"]), 0.0
) + float(activity["days"])
def cell(value: Any) -> str:
return _text(value).replace("|", "\\|") or "-"
lines = [
f"## {DICTIONARY_HEADING}",
"",
"Each work package, what it delivers, and the Checks that say it is done.",
"",
"| Id | Work package | Scope | Produces | Elements | Done when these pass | Skills | Days |",
"| --- | --- | --- | --- | --- | --- | --- | --- |",
]
for package in packages:
ident = str(package["id"])
elements = _list(package.get("elements"))
accepted = [c for element in elements for c in checks.get(element, [])]
lines.append(
"| "
+ " | ".join(
[
ident,
("&nbsp;&nbsp;" * depth(ident)) + cell(package.get("name")),
cell(package.get("scope")),
cell("; ".join(_list(package.get("produces")))),
cell(", ".join(elements)),
cell(", ".join(accepted)),
cell(", ".join(_list(package.get("skills")))),
_day(effort[ident]) if ident in effort else "-",
]
)
+ " |"
)
ordered = sorted(activities, key=lambda a: (plan[str(a["id"])].start, str(a["id"])))
dated = terms["start"] is not None
lines += [
"",
"## Activity sequence",
"",
"| Id | Activity | Work package | Days | After | Start | Finish |"
+ (" Dates |" if dated else "")
+ " Owner | Critical |",
"| --- | --- | --- | --- | --- | --- | --- |"
+ (" --- |" if dated else "")
+ " --- | --- |",
]
for activity in ordered:
item = plan[str(activity["id"])]
row = [
str(activity["id"]),
cell(activity.get("name")),
str(activity.get("work_package")),
_day(float(activity["days"])),
cell(", ".join(_list(activity.get("after")))),
f"Day {_day(item.start)}",
f"Day {_day(item.finish)}",
]
if dated:
begins = _calendar(terms["start"], item.start, terms["week"])
ends = _calendar(terms["start"], max(item.finish - 1e-9, 0), terms["week"])
row.append(f"{begins.isoformat()} to {ends.isoformat()}")
row += [str(activity.get("owner", TEAM)), "yes" if item.critical else ""]
lines.append("| " + " | ".join(row) + " |")
total = max(item.finish for item in plan.values())
weeks = total / terms["week"]
lines += [
"",
"## Timeline",
"",
"```text",
*_chart(ordered, plan, total),
"```",
"",
]
summary = (
f"{_day(total)} working days, about {weeks:.1f} weeks, with a team of "
f"{terms['team_size']}"
+ (
""
if terms["team_size_stated"]
else " (assumed; the scope gives no team size)"
)
+ f" and a {terms['week']}-day week."
)
lines.append(summary)
window = terms["window_weeks"]
if window is not None:
if weeks <= window + 1e-9:
lines.append(
f"That is inside the {window}-week delivery window, with "
f"{window - weeks:.1f} weeks to spare."
)
else:
path = [str(a["id"]) for a in ordered if plan[str(a["id"])].critical]
lines.append(
f"**That is {weeks - window:.1f} weeks over the {window}-week delivery "
f"window.** The critical path is {' -> '.join(path)}: only shortening "
"or removing work on it, or adding people where it waits for them, "
"brings the end in."
)
theirs = [a for a in ordered if a.get("owner", TEAM) == CUSTOMER]
if theirs:
lines += ["", "The customer owns these, and the plan waits on them:"]
lines += [
f"- {a['id']} {_text(a.get('name'))}: {_day(float(a['days']))} days"
+ (f". {_text(a.get('assumption'))}" if _text(a.get("assumption")) else "")
for a in theirs
]
lines += [
"",
(
"Durations are estimates made without knowing the team, and are "
"indicative. Days are working days counted from Day 0, the day work "
"starts; each of the team's activities takes one person."
),
]
return "\n".join(lines) + "\n"
def _chart(
ordered: Sequence[Mapping[str, Any]], plan: Mapping[str, Scheduled], total: float
) -> list[str]:
"""The timeline as text: one row per activity along a relative day axis."""
scale = min(1.0, _CHART_WIDTH / total) if total else 1.0
labels = [f"{a['id']} {_text(a.get('name'))}"[:38] for a in ordered]
width = max(len(label) for label in labels) + 2
step = max(1, math.ceil(total / 6 / 5.0) * 5)
axis = [" "] * (int(total * scale) + 8)
for day in range(0, int(total) + 1, step):
mark = str(day)
at = int(day * scale)
axis[at : at + len(mark)] = mark
rows = [" " * width + "Day " + "".join(axis).rstrip()]
for label, activity in zip(labels, ordered, strict=True):
item = plan[str(activity["id"])]
begin = round(item.start * scale)
length = max(1, round((item.finish - item.start) * scale))
block = "░" if activity.get("owner", TEAM) == CUSTOMER else "█"
flag = " *" if item.critical else ""
rows.append(f"{label.ljust(width)} {' ' * begin}{block * length}{flag}")
rows += ["", "█ the team ░ the customer * on the critical path"]
return rows
def mermaid(attachments: Mapping[str, str], upstream: Upstream | None) -> str:
"""A Mermaid Gantt chart on calendar dates, when the scope gives a start date.
"" otherwise: a relative plan has no dates to draw."""
packages, activities, problems = parse(attachments.get(WORK_BREAKDOWN_FILE, ""))
terms = delivery_terms(upstream)
if problems or not activities or terms["start"] is None:
return ""
plan = schedule(activities, terms["team_size"])
names = {str(p["id"]): _text(p.get("name")) for p in packages}
lines = ["gantt", " dateFormat YYYY-MM-DD", " excludes weekends"]
for package in packages:
own = [
a for a in activities if str(a.get("work_package")) == str(package["id"])
]
if not own:
continue
lines.append(f" section {names[str(package['id'])].replace(':', ' ')}")
for activity in sorted(own, key=lambda a: plan[str(a["id"])].start):
item = plan[str(activity["id"])]
begins = _calendar(terms["start"], item.start, terms["week"])
tag = "crit, " if item.critical else ""
label = _text(activity.get("name")).replace(":", " ")
lines.append(
f" {label} :{tag}{activity['id']}, {begins.isoformat()}, "
f"{max(1, math.ceil(float(activity['days'])))}d"
)
return "\n".join(lines) + "\n"
def summary(
attachments: Mapping[str, str], upstream: Upstream | None
) -> dict[str, Any]:
"""The plan in a few numbers, for an Approval and for the Execution's record."""
packages, activities, problems = parse(attachments.get(WORK_BREAKDOWN_FILE, ""))
if problems or not activities:
return {}
terms = delivery_terms(upstream)
plan = schedule(activities, terms["team_size"])
total = max(item.finish for item in plan.values())
weeks = round(total / terms["week"], 1)
return {
"work_packages": len(packages),
"activities": len(activities),
"working_days": round(total, 1),
"weeks": weeks,
"team_size": terms["team_size"],
"window_weeks": terms["window_weeks"],
"within_window": None
if terms["window_weeks"] is None
else weeks <= terms["window_weeks"],
"critical_path": [i for i, item in plan.items() if item.critical],
}