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>
560 lines
22 KiB
Python
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,
|
|
(" " * 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],
|
|
}
|