dse120071750/m8m-harness-builder / skills/m8m/m8m-harness-builder
m8m-harness-builder
FlaggedBuild and edit M8M harnesses that coordinate existing tools and FlowSteps, validate milestone outputs, and track progress and resume. Reuse working implementations in place. Compile workflow changes without runtime packaging; build portable packages when requested and deliver server installations through the dedicated M8M server installer.
scripts/m8m_flowchart.py
View on GitHub"""Single M8M flowchart markdown: milestones, schema gates, and foreach loops."""
from __future__ import annotations
from pathlib import Path
from typing import Any
from flowstep_runtime import normalize_flowsteps, utc_now
from humanize_chart import humanize_flowstep, humanize_milestone
from toolbox_plan import render_toolbox_plan_markdown
FLOWCHART_REL = Path("planning/m8m-flowchart.md")
ELSE_BLOCKED = "BLOCKED"
def flowchart_path(root: Path) -> Path:
return root / FLOWCHART_REL
def _nodes(items: list[dict[str, Any]], statuses: dict[str, str] | None = None) -> list[dict[str, Any]]:
statuses = statuses or {}
nodes: list[dict[str, Any]] = []
for item in items:
mid = str(item.get("id") or "")
if not mid:
continue
ledger = item.get("ledger") if isinstance(item.get("ledger"), dict) else None
if ledger is None and isinstance(item.get("foreach"), dict):
ledger = item["foreach"]
nodes.append(
{
"id": mid,
"intelligence": item.get("intelligence") or item.get("model") or "none",
"tools": [str(tool) for tool in (item.get("tools") or []) if tool],
"loop": str(item.get("loop") or "none"),
"ledger": ledger,
"worker": item.get("worker"),
"receipt_schema": item.get("receipt_schema"),
"next": [],
"else": None,
"join": None,
"output_contract": str(item.get("output_contract") or ""),
"outputs": [dict(output) for output in (item.get("outputs") or []) if isinstance(output, dict)],
"flowsteps": normalize_flowsteps(
flowsteps=item.get("flowsteps"),
tools=item.get("tools"),
)[0],
"status": str(statuses.get(mid) or item.get("status") or ""),
"branch": item.get("branch") if isinstance(item.get("branch"), dict) else None,
"on_path": item.get("on_path"),
"cycle": item.get("cycle") if isinstance(item.get("cycle"), dict) else None,
"on_cycle": item.get("on_cycle"),
"success": item.get("success"),
"gem": str(item.get("gem") or f"references/{mid}.md"),
"cache": item.get("cache") if isinstance(item.get("cache"), dict) else None,
"cache_status": str(item.get("cache_status") or ""),
}
)
return nodes
def _when_label(edge: dict[str, Any]) -> str:
schema = edge.get("schema")
if isinstance(schema, dict):
props = schema.get("properties") if isinstance(schema.get("properties"), dict) else {}
required = list(schema.get("required") or [])
for field in required + [key for key in props if key not in required]:
prop = props.get(field)
if not isinstance(prop, dict):
continue
if "const" in prop:
return f"{field}={prop['const']}"
if "enum" in prop:
return str(field)
when = str(edge.get("when") or "gate")
stem = Path(when).stem
if stem.endswith(".schema"):
stem = stem[: -len(".schema")]
if "_" in stem:
field, value = stem.rsplit("_", 1)
if field and value:
return f"{field}={value}"
return stem
def _blocked_id(mid: str) -> str:
return f"blocked_{mid}"
def render_mermaid(items: list[dict[str, Any]]) -> str:
nodes = _nodes(items)
ids = [item["id"] for item in nodes]
then_of = {str(edge["then"]) for item in nodes for edge in item["next"]}
for item in nodes:
for path in (item.get("branch") or {}).get("paths") or []:
if isinstance(path, dict) and path.get("then"):
then_of.add(str(path["then"]))
join_ids = {item["id"] for item in nodes if item.get("join")}
lines = ["flowchart TD", " request([request])"]
for item in nodes:
mid = item["id"]
tools = ",".join(item["tools"] or [])
tool_line = f"<br/>{tools}" if tools else ""
output_ports = ",".join(str(output.get("id") or "") for output in item.get("outputs") or [] if output.get("id"))
output_line = f"<br/>out:{output_ports}" if output_ports else ""
loop_line = ""
if item.get("loop") == "for" and item.get("ledger"):
fe = item["ledger"]
loop_line = f"<br/>for:{fe.get('path')} max={fe.get('max_items')}"
elif item.get("loop") == "judge":
loop_line = "<br/>judge until PASS"
elif item.get("branch"):
paths = []
for path in (item.get("branch") or {}).get("paths") or []:
if isinstance(path, dict) and path.get("id"):
paths.append(str(path["id"]))
loop_line = "<br/>branch:" + "/".join(paths[:4])
cache_line = "<br/>cache:candidate" if item.get("cache") else ""
extra = ""
if item["intelligence"] not in {None, "none"}:
extra = f"<br/>intel:{item['intelligence']}"
lines.append(f' {mid}["{mid}{extra}{output_line}{loop_line}{cache_line}{tool_line}"]')
if ids:
lines.append(f" request --> {ids[0]}")
for item in nodes:
mid = item["id"]
if item["next"]:
for edge in item["next"]:
label = _when_label(edge).replace('"', "")
lines.append(f' {mid} -->|"{label}"| {edge["then"]}')
else_to = item.get("else") or ELSE_BLOCKED
if else_to in {ELSE_BLOCKED, "BLOCKED"}:
lines.append(f' {mid} -->|"else BLOCKED"| {_blocked_id(mid)}')
else:
lines.append(f' {mid} -->|"else"| {else_to}')
continue
br = item.get("branch") if isinstance(item.get("branch"), dict) else None
if br and br.get("paths"):
for path in br["paths"]:
if not isinstance(path, dict):
continue
then = str(path.get("then") or "")
label = str(path.get("id") or "").replace('"', "")
if then:
lines.append(f' {mid} -->|"{label}"| {then}')
continue
by_id = {item["id"]: item for item in nodes}
for item in nodes:
if item.get("join"):
for src in item["join"]:
if src in by_id:
lines.append(f' {src} -->|"join"| {item["id"]}')
for index, item in enumerate(nodes):
if item["next"]:
continue
if item.get("join"):
pass
for later in ids[index + 1 :]:
if later in then_of:
continue
dest = by_id[later]
src_path = item.get("on_path")
dest_path = dest.get("on_path")
if dest_path and src_path and dest_path != src_path:
continue
if dest_path and item.get("branch"):
continue
if dest.get("join") and item["id"] in (dest.get("join") or []):
break
if dest.get("join"):
continue
lines.append(f" {item['id']} --> {later}")
break
return "\n".join(lines)
def render_flowchart(
items: list[dict[str, Any]],
*,
title: str,
flow_id: str | None = None,
source: str = "audit",
toolbox_plan: list[dict[str, Any]] | None = None,
statuses: dict[str, str] | None = None,
) -> str:
nodes = _nodes(items, statuses)
mermaid = render_mermaid(items)
lines = [
f"# M8M flowchart: {title}",
"",
"One chart. Milestone to milestone. Each node declares named output ports.",
"FlowSteps refine candidates; admission always runs and an authored judge is optional. Without chosen-output.json the node is BLOCKED.",
"Run state is authoritative. Optional cross-run cache only supplies a candidate for the current judge.",
"Execution context is isolated: a fresh run does not inherit orchestration chat or prior-row memory.",
"FlowSteps inside a node are a guide (one preferred tool each), not a compulsory path.",
"cycle = wrap over a frozen ledger (pass preserves, fail purges). judge = optional semantic retry until PASS.",
"The JPEG is the audit copy: portable, human-labeled, native to review.",
"It is rewritten on generate and on every step edit.",
"",
f"- flow_id: `{flow_id or title}`",
f"- source: `{source}`",
f"- updated_at: {utc_now()}",
"",
"## Chart",
"",
"Portable JPEG for audit. Humanizer names each milestone and FlowStep.",
"Regenerated on generate and on every step edit (`write` / `mark`).",
"",
f"",
"",
"```text",
mermaid,
"```",
"",
]
if toolbox_plan:
lines.extend(render_toolbox_plan_markdown(toolbox_plan).splitlines())
lines.append("")
lines.extend(
[
"## Nodes",
"",
"| Milestone | What it means | Success | Declared output ports | Status | Intelligence | Tools | Control | Cache |",
"| --- | --- | --- | --- | --- | --- | --- | --- | --- |",
]
)
if not nodes:
lines.append("| (none) | | | | | | | | |")
for item in nodes:
tools = ", ".join(f"`{tool}`" for tool in item["tools"]) or "none"
if item.get("loop") == "for" and item.get("ledger"):
fe = item["ledger"]
control = f"for `{fe.get('path')}` max={fe.get('max_items')}"
elif item.get("loop") == "judge":
control = "judge until PASS"
elif item.get("branch"):
paths = []
for path in (item.get("branch") or {}).get("paths") or []:
if isinstance(path, dict) and path.get("id"):
paths.append(str(path["id"]))
control = "branch " + " / ".join(paths)
elif item.get("on_path"):
control = f"on_path `{item['on_path']}`"
elif item.get("cycle"):
control = "cycle pass|fail → ledger"
elif item.get("on_cycle"):
control = f"on_cycle `{item['on_cycle']}`"
else:
control = "linear"
ports = []
for output in item.get("outputs") or []:
oid = str(output.get("id") or "")
kind = str(output.get("kind") or "")
cardinality = str(output.get("cardinality") or "one")
required = "required" if output.get("required") else "optional"
ports.append(f"`{oid}` ({kind}, {cardinality}, {required})")
port_text = "<br>".join(ports) or "missing (BLOCKED)"
human = humanize_milestone(item)
status = human.get("status") or "—"
cache = item.get("cache") or {}
cache_text = f"candidate, TTL {cache.get('ttl_seconds')}s" if cache else "off"
if item.get("cache_status"):
cache_text += f", status `{item['cache_status']}`"
lines.append(
f"| `{item['id']}` | {human['title']} | {human.get('success') or human['asset']} | {port_text} | `{status}` | "
f"`{item['intelligence']}` | {tools} | {control} | {cache_text} |"
)
lines.extend(
[
"",
"## FlowSteps (guide)",
"",
"Sequence inside each milestone. Prefer the named tool. Optional.",
"Start from the complete milestone master prompt, including during recovery.",
"FlowStep notes are optional. Admission is compulsory; semantic judgment is optional.",
"",
"| Milestone | # | FlowStep | What it means | Preferred tool | Milestone master prompt |",
"| --- | ---: | --- | --- | --- | --- |",
]
)
guide_rows = 0
for item in nodes:
gem = str(item.get("gem") or f"references/{item['id']}.md")
for index, fs in enumerate(item.get("flowsteps") or [], start=1):
guide_rows += 1
human_fs = humanize_flowstep(fs, index)
fid = str(fs.get("id") or fs.get("tool") or "")
lines.append(
f"| `{item['id']}` | {index} | `{fid}` | "
f"{human_fs['caption']} | `{fs.get('tool') or '—'}` | `{gem}` |"
)
if not guide_rows:
lines.append("| (none) | | | | | |")
lines.extend(["", "## Cycle", ""])
cycles = [item for item in nodes if item.get("cycle")]
if not cycles:
lines.append("None. No cycle wrap. Freeze a ledger first, then wrap milestones.")
else:
lines.extend(
[
"Freeze a ledger, then wrap. `cycle_receipt` writes pass|fail and updates the ledger.",
"Finished rounds are preserved. Unfinished residue is purged. The ledger is resumable.",
"",
"| Last milestone | Ledger | Start | Join | Worker | Pass means |",
"| --- | --- | --- | --- | --- | --- |",
]
)
for item in cycles:
cy = item.get("cycle") or {}
lines.append(
f"| `{item['id']}` | `{cy.get('ledger') or '—'}` | `{cy.get('start') or item['id']}` | "
f"`{cy.get('join') or '—'}` | `{cy.get('worker') or 'cycle_receipt'}` | "
f"{cy.get('pass') or 'semantic pass on this ledger row'} |"
)
lines.extend(["", "## Optional semantic judge", ""])
judges = [item for item in nodes if item.get("loop") == "judge"]
if not judges:
lines.append("None. These milestones commit after structural admission with zero judge calls.")
else:
lines.extend(
[
"| Milestone | Worker | Receipt schema |",
"| --- | --- | --- |",
]
)
for item in judges:
lines.append(
f"| `{item['id']}` | `{item.get('worker') or 'BLOCKED: missing judge'}` | "
f"`{item.get('receipt_schema') or 'BLOCKED: missing schema'}` |"
)
lines.extend(["", "## Branch (after the milestone)", ""])
branches = [item for item in nodes if item.get("branch")]
if not branches:
lines.append("None. No branch after a milestone.")
else:
lines.extend(
[
"After candidate admission, the runtime invokes the exact bound control worker for `{ok, branch}`. Skip is not BLOCK.",
"",
"| Milestone | Worker | Default | Paths | Join |",
"| --- | --- | --- | --- | --- |",
]
)
for item in branches:
br = item.get("branch") or {}
paths = []
for path in br.get("paths") or []:
if isinstance(path, dict):
paths.append(f"`{path.get('id')}`→`{path.get('then') or path.get('id')}`")
else:
paths.append(f"`{path}`")
lines.append(
f"| `{item['id']}` | `{br.get('worker') or item.get('worker') or 'branch_receipt'}` | "
f"`{br.get('default') or '—'}` | {', '.join(paths)} | `{br.get('join') or '—'}` |"
)
lines.extend(
[
"",
"Proceed only after structural admission and, when declared, semantic judge `PASS`; then commit current named outputs as `chosen-output.json`.",
"Branch is after that commit. Candidate handlers never write control; the runtime-owned control call writes `branch`.",
"",
]
)
return "\n".join(lines)
def write_flowchart(
root: Path,
items: list[dict[str, Any]],
*,
title: str,
flow_id: str | None = None,
source: str = "audit",
toolbox_plan: list[dict[str, Any]] | None = None,
statuses: dict[str, str] | None = None,
focus_id: str | None = None,
) -> Path:
path = flowchart_path(root)
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(
render_flowchart(
items,
title=title,
flow_id=flow_id,
source=source,
toolbox_plan=toolbox_plan,
statuses=statuses,
),
encoding="utf-8",
newline="\n",
)
from flowchart_jpg import write_flowchart_jpg
write_flowchart_jpg(
path.with_suffix(".jpg"),
items,
title=title,
focus_id=focus_id,
statuses=statuses,
)
return path
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies. | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |
| meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要". | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |