Skip to content

dse120071750/m8m-harness-builder / skills/m8m/m8m-harness-builder

m8m-harness-builder

Flagged

Build 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.

FileKindSize
.gitattributesother112 B
.gitignoreother208 B
LICENSEother673 B
README.mdmarkdown29.8 KB
SKILL.mdskill md1.3 KB
agents/audit_complete.yamlconfig1.6 KB
agents/flow_generated.yamlconfig2.2 KB
agents/harness_validated.yamlconfig2.3 KB
agents/openai.yamlconfig4.6 KB
agents/skill_shipped.yamlconfig2.1 KB
agents/toolbox_ready.yamlconfig1.6 KB
conftest.pyscript275 B
contracts/conformance/expectation_first_runtime/candidate-cases.jsonconfig4.1 KB
contracts/conformance/expectation_first_runtime/common-linear.jsonconfig2.7 KB
contracts/conformance/expectation_first_runtime/schemas/judge-decision.schema.jsonconfig373 B
contracts/conformance/expectation_first_runtime/schemas/result.output.schema.jsonconfig589 B
contracts/conformance/expectation_first_runtime/schemas/source.output.schema.jsonconfig500 B
contracts/conformance/flowstep_flow_v4/invalid/judge-loop-unbound.jsonconfig483 B
contracts/conformance/flowstep_flow_v4/invalid/malformed-execution.jsonconfig571 B
contracts/conformance/flowstep_flow_v4/invalid/no-required-output.jsonconfig455 B
contracts/conformance/flowstep_flow_v4/invalid/nonjudge-bound.jsonconfig763 B
contracts/conformance/flowstep_flow_v4/invalid/unknown-field.jsonconfig469 B
contracts/conformance/flowstep_flow_v4/valid/authoring-union.jsonconfig4.3 KB
contracts/conformance/flowstep_flow_v4/valid/platform-dag.jsonconfig1.9 KB
contracts/file_ref_v2.schema.jsonconfig484 B
contracts/flow_sequence_action_v2.schema.jsonconfig1.5 KB
contracts/flowstep_flow_v4.schema.jsonconfig13.6 KB
contracts/flowstep_output_v2.schema.jsonconfig2.8 KB
contracts/flowstep_output_v3.schema.jsonconfig3.0 KB
contracts/flowstep_skill_audit_v1.schema.jsonconfig5.1 KB
contracts/m8m_builder_configuration_v1.schema.jsonconfig252 B
contracts/m8m_builder_input_v1.schema.jsonconfig183 B
contracts/m8m_builder_installation_receipt_v2.schema.jsonconfig2.9 KB
contracts/m8m_builder_output_v1.schema.jsonconfig453 B
contracts/m8m_builder_request_v3.schema.jsonconfig707 B
contracts/m8m_builder_result_v3.schema.jsonconfig422 B
contracts/m8m_builder_source_audit_v2.schema.jsonconfig6.1 KB
contracts/m8m_builder_source_bundle_v2.schema.jsonconfig8.6 KB
contracts/m8m_builder_toolbox_manifest_v2.schema.jsonconfig2.6 KB
contracts/m8m_builder_validation_report_v2.schema.jsonconfig3.4 KB
contracts/m8m_cache_receipt_v1.schema.jsonconfig1.2 KB
contracts/m8m_candidate_cache_entry_v1.schema.jsonconfig2.8 KB
contracts/m8m_chosen_output_v1.schema.jsonconfig2.3 KB
contracts/m8m_context_capsule_v1.schema.jsonconfig1.9 KB
contracts/m8m_contract_bundle_lock_v1.schema.jsonconfig648 B
contracts/m8m_goal_ledger_v1.schema.jsonconfig1.8 KB
contracts/m8m_milestone_agent_v1.schema.jsonconfig13.8 KB
contracts/m8m_milestone_expectation_v1.schema.jsonconfig1.9 KB
contracts/m8m_milestone_judge_receipt_v1.schema.jsonconfig1.7 KB
contracts/m8m_milestone_judge_request_v1.schema.jsonconfig3.0 KB
contracts/m8m_run_context_v1.schema.jsonconfig994 B
contracts/m8m_run_context_v2.schema.jsonconfig1.2 KB
contracts/m8m_run_storage_contract_v1.schema.jsonconfig894 B
contracts/m8m_runtime_lock_v1.schema.jsonconfig1.7 KB
contracts/m8m_runtime_release_v1.schema.jsonconfig2.2 KB
contracts/m8m_skill_canvas_v1.schema.jsonconfig4.0 KB
contracts/m8m_source_asset_manifest_v1.schema.jsonconfig1.2 KB
contracts/m8m_workflow_package_archive_v1.schema.jsonconfig1.1 KB
contracts/m8m_workflow_source_bundle_proof_v1.schema.jsonconfig1.6 KB
contracts/m8m_workflow_source_bundle_v1.schema.jsonconfig19.5 KB
contracts/tool_vs_intelligence_table_v1.schema.jsonconfig1.3 KB
docs/m8m-chart.jpgbinary172.2 KB
docs/m8m-task-builder-design.zh-HK.mdmarkdown66.9 KB
examples/article_infographic/README.mdmarkdown598 B
examples/article_infographic/planning/m8m-flowchart.jpgbinary186.0 KB
examples/article_infographic/planning/m8m-flowchart.mdmarkdown4.2 KB
flows/m8m_build_v2.yamlconfig9.9 KB
flowsteps/tools/audit_complete_judge/input.schema.jsonconfig190 B
flowsteps/tools/audit_complete_judge/output.schema.jsonconfig477 B
flowsteps/tools/audit_complete_judge/tests/test_tool.pyscript1.1 KB
flowsteps/tools/audit_complete_judge/tool.pyscript1.2 KB
flowsteps/tools/audit_skill/input.schema.jsonconfig250 B
flowsteps/tools/audit_skill/output.schema.jsonconfig136 B
flowsteps/tools/audit_skill/tests/test_tool.pyscript1.9 KB
flowsteps/tools/audit_skill/tool.pyscript2.9 KB
flowsteps/tools/flow_generated_judge/input.schema.jsonconfig190 B
flowsteps/tools/flow_generated_judge/output.schema.jsonconfig475 B
flowsteps/tools/flow_generated_judge/tests/test_tool.pyscript1.1 KB
flowsteps/tools/flow_generated_judge/tool.pyscript1.5 KB
flowsteps/tools/generate_from_audit/input.schema.jsonconfig562 B
flowsteps/tools/generate_from_audit/output.schema.jsonconfig137 B
flowsteps/tools/generate_from_audit/tests/test_tool.pyscript2.2 KB
flowsteps/tools/generate_from_audit/tool.pyscript3.0 KB
flowsteps/tools/harness_validated_judge/input.schema.jsonconfig193 B
flowsteps/tools/harness_validated_judge/output.schema.jsonconfig488 B
flowsteps/tools/harness_validated_judge/tests/test_tool.pyscript1.1 KB
flowsteps/tools/harness_validated_judge/tool.pyscript1.3 KB
flowsteps/tools/install_local_skill/input.schema.jsonconfig733 B
flowsteps/tools/install_local_skill/output.schema.jsonconfig144 B
flowsteps/tools/install_local_skill/tests/test_tool.pyscript2.1 KB
flowsteps/tools/install_local_skill/tool.pyscript3.0 KB
flowsteps/tools/install_toolbox/input.schema.jsonconfig400 B
flowsteps/tools/install_toolbox/output.schema.jsonconfig140 B
flowsteps/tools/install_toolbox/tests/test_tool.pyscript1.9 KB
flowsteps/tools/install_toolbox/tool.pyscript3.0 KB
flowsteps/tools/skill_shipped_judge/input.schema.jsonconfig189 B
flowsteps/tools/skill_shipped_judge/output.schema.jsonconfig484 B
flowsteps/tools/skill_shipped_judge/tests/test_tool.pyscript1.1 KB
flowsteps/tools/skill_shipped_judge/tool.pyscript1.3 KB
flowsteps/tools/toolbox_ready_judge/input.schema.jsonconfig189 B
flowsteps/tools/toolbox_ready_judge/output.schema.jsonconfig490 B
flowsteps/tools/toolbox_ready_judge/tests/test_tool.pyscript1.3 KB
flowsteps/tools/toolbox_ready_judge/tool.pyscript1.6 KB
flowsteps/tools/validate_harness/input.schema.jsonconfig563 B
flowsteps/tools/validate_harness/output.schema.jsonconfig141 B
flowsteps/tools/validate_harness/tests/test_tool.pyscript2.1 KB
flowsteps/tools/validate_harness/tool.pyscript3.0 KB
planning/upgrade.mdmarkdown16.2 KB
references/architecture.mdmarkdown28.1 KB
references/audit_complete.mdmarkdown739 B
references/builder-authoring.mdmarkdown9.8 KB
references/flow_generated.mdmarkdown1.2 KB
references/flowstep-development.mdmarkdown4.3 KB
references/harness-invocation.mdmarkdown2.9 KB
references/harness_validated.mdmarkdown786 B
references/master-prompts.mdmarkdown14.0 KB
references/milestone.mdmarkdown11.4 KB
references/output-lineage.mdmarkdown4.4 KB
references/runtime-packaging.mdmarkdown35.2 KB
references/server-delivery.mdmarkdown6.8 KB
references/skill_shipped.mdmarkdown798 B
references/tool-vs-intelligence.mdmarkdown10.0 KB
references/toolbox_ready.mdmarkdown612 B
requirements.txtmanifest150 B
scripts/audit_harness.pyscript80.7 KB
scripts/candidate_cache.pyscript27.6 KB
scripts/coordinate_workflow.pyscript4.3 KB
scripts/execution_identity.pyscript1.0 KB
scripts/flowchart_jpg.pyscript16.1 KB
scripts/flowstep_instruction.pyscript14.1 KB
scripts/flowstep_runtime.pyscript108.6 KB
scripts/flowstep_tools.pyscript5.7 KB
scripts/gem_text.pyscript5.7 KB
scripts/generate_harness.pyscript61.4 KB
scripts/humanize_chart.pyscript5.6 KB
scripts/humanize_chart_zh.pyscript5.2 KB
scripts/import_flow_v4.pyscript62.3 KB
scripts/m8m_build_steps.pyscript143.2 KB
scripts/m8m_cache.pyscript1.7 KB
scripts/m8m_delivery_common.pyscript3.8 KB
scripts/m8m_deploy.pyscript5.6 KB
scripts/m8m_factory.pyscript10.1 KB
scripts/m8m_flowchart.pyscript16.6 KB
scripts/m8m_local_bundle.pyscript4.5 KB
scripts/migrate_skill_source.pyscript34.2 KB
scripts/milestone_expectation.pyscript3.3 KB
scripts/milestone_pair.pyscript3.1 KB
scripts/package_archive.pyscript7.1 KB
scripts/project_imports.pyscript10.8 KB
scripts/run_flow.pyscript153.8 KB
scripts/run_goal.pyscript14.1 KB
scripts/run_m8m.pyscript3.8 KB
scripts/runtime_release.pyscript45.0 KB
scripts/schema_gate.pyscript5.6 KB
scripts/session_layout.pyscript74.4 KB
scripts/skill_source.pyscript65.3 KB
scripts/source_bundle.pyscript87.7 KB
scripts/teaching_contracts.pyscript8.9 KB
scripts/tool_vs_intelligence.pyscript9.3 KB
scripts/toolbox_plan.pyscript6.1 KB
scripts/validate_harness.pyscript24.1 KB
scripts/verify_platform_contract_parity.pyscript2.9 KB
seeds/branch_receipt/input.schema.jsonconfig1.0 KB
seeds/branch_receipt/output.schema.jsonconfig359 B
seeds/branch_receipt/tests/test_tool.pyscript2.0 KB
seeds/branch_receipt/tool.pyscript3.7 KB
seeds/cycle_receipt/input.schema.jsonconfig1.0 KB
seeds/cycle_receipt/output.schema.jsonconfig319 B
seeds/cycle_receipt/tests/test_tool.pyscript1.5 KB
seeds/cycle_receipt/tool.pyscript2.0 KB
seeds/hash_bind/input.schema.jsonconfig213 B
seeds/hash_bind/output.schema.jsonconfig288 B
seeds/hash_bind/tests/test_tool.pyscript814 B
seeds/hash_bind/tool.pyscript527 B
seeds/ledger_receipt/input.schema.jsonconfig278 B
seeds/ledger_receipt/output.schema.jsonconfig355 B
seeds/ledger_receipt/tests/test_tool.pyscript842 B
seeds/ledger_receipt/tool.pyscript747 B
seeds/ok_receipt/input.schema.jsonconfig280 B
seeds/ok_receipt/output.schema.jsonconfig280 B
seeds/ok_receipt/tests/test_tool.pyscript667 B
seeds/ok_receipt/tool.pyscript682 B
seeds/schema_validate/input.schema.jsonconfig265 B
seeds/schema_validate/output.schema.jsonconfig196 B
seeds/schema_validate/tests/test_tool.pyscript1.0 KB
seeds/schema_validate/tool.pyscript844 B
seeds/slot_write/input.schema.jsonconfig558 B
seeds/slot_write/output.schema.jsonconfig346 B
seeds/slot_write/tests/test_tool.pyscript1.2 KB
seeds/slot_write/tool.pyscript1015 B
tests/__init__.pyscript0 B
tests/support.pyscript668 B
tests/test_audit_harness.pyscript23.5 KB
tests/test_branch.pyscript14.4 KB
tests/test_builder3_templates.pyscript2.4 KB
tests/test_builder_install_integrity.pyscript30.6 KB
tests/test_builder_native_snapshot.pyscript5.0 KB
tests/test_builder_requirements.pyscript26.8 KB
tests/test_builder_self_dogfood.pyscript7.0 KB
tests/test_builder_self_source.pyscript10.3 KB

scripts/flowchart_jpg.py

View on GitHub
"""Draw the portable audit JPEG: canvas + inside one milestone."""

from __future__ import annotations

from pathlib import Path
from typing import Any

from flowstep_runtime import normalize_flowsteps
from humanize_chart import focus_milestone, humanize_flowstep, humanize_milestone


NAVY = (27, 58, 75)
BLUE = (214, 230, 245)
BLUE_EDGE = (91, 141, 184)
YELLOW = (245, 215, 110)
YELLOW_EDGE = (180, 140, 20)
GREEN = (46, 125, 50)
GREEN_BG = (232, 245, 233)
RED = (183, 28, 28)
RED_BG = (255, 235, 238)
AMBER = (255, 243, 224)
AMBER_EDGE = (230, 145, 56)
BG = (247, 248, 250)
WHITE = (255, 255, 255)
GRAY = (90, 98, 110)

STATUS_FILL = {
    "DONE": GREEN_BG,
    "BLOCKED": RED_BG,
    "PENDING": WHITE,
}
STATUS_EDGE = {
    "DONE": GREEN,
    "BLOCKED": RED,
    "PENDING": NAVY,
}


def _font(size: int):
    from PIL import ImageFont

    for name in (
        "C:/Windows/Fonts/segoeui.ttf",
        "C:/Windows/Fonts/arial.ttf",
        "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
        "/System/Library/Fonts/Helvetica.ttc",
    ):
        path = Path(name)
        if path.is_file():
            try:
                return ImageFont.truetype(str(path), size)
            except OSError:
                continue
    return ImageFont.load_default()


def _text(draw, xy, text, font, fill=NAVY):
    draw.text(xy, text, font=font, fill=fill)


def _box(draw, xy, fill, outline, radius=16, width=3):
    draw.rounded_rectangle(xy, radius=radius, fill=fill, outline=outline, width=width)


def _measure(draw, text, font):
    box = draw.textbbox((0, 0), text, font=font)
    return box[2] - box[0], box[3] - box[1]


def _wrap(draw, text: str, font, max_width: int) -> list[str]:
    words = str(text or "").split()
    if not words:
        return [""]
    lines: list[str] = []
    current = words[0]
    for word in words[1:]:
        trial = f"{current} {word}"
        tw, _ = _measure(draw, trial, font)
        if tw <= max_width:
            current = trial
        else:
            lines.append(current)
            current = word
    lines.append(current)
    return lines


def _center(draw, text, font, cx, cy, fill=NAVY):
    tw, th = _measure(draw, text, font)
    _text(draw, (cx - tw / 2, cy - th / 2), text, font, fill)


def _arrow(draw, x1, y, x2):
    draw.line((x1, y, x2 - 10, y), fill=NAVY, width=8)
    draw.polygon([(x2 - 14, y - 9), (x2, y), (x2 - 14, y + 9)], fill=NAVY)


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"]
        asset = item.get("asset") if isinstance(item.get("asset"), dict) else {}
        kind = str(item.get("asset_kind") or asset.get("kind") or "")
        outputs = [dict(output) for output in (item.get("outputs") or []) if isinstance(output, dict)]
        if outputs:
            kind = str(outputs[0].get("kind") or kind)
        flowsteps, _ = normalize_flowsteps(flowsteps=item.get("flowsteps"), tools=item.get("tools"))
        nodes.append(
            {
                "id": mid,
                "loop": str(item.get("loop") or "none"),
                "ledger": ledger,
                "asset": asset,
                "asset_kind": kind,
                "outputs": outputs,
                "flowsteps": flowsteps,
                "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,
                "success": item.get("success"),
                "worker": item.get("worker"),
                "gem": 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 render_flowchart_image(
    items: list[dict[str, Any]],
    *,
    title: str,
    focus_id: str | None = None,
    statuses: dict[str, str] | None = None,
) -> Any:
    from PIL import Image, ImageDraw

    nodes = _nodes(items, statuses)
    humans = [humanize_milestone(item) for item in nodes]
    focus = focus_milestone(nodes, focus_id)
    flowsteps = []
    if focus:
        flowsteps = [humanize_flowstep(fs, i) for i, fs in enumerate(focus.get("flowsteps") or [], start=1)]

    width = 1600
    count = max(len(nodes), 1)
    box_h = 118
    top_h = 360
    inner_items = max(len(flowsteps), 1) + 1  # + judge
    sw = min(280, max(150, (width - 420) // inner_items - 8))
    height = 920
    image = Image.new("RGB", (width, height), BG)
    draw = ImageDraw.Draw(image)
    title_font = _font(32)
    h2_font = _font(20)
    body_font = _font(16)
    small_font = _font(14)

    _text(draw, (48, 28), "1. Canvas — milestone to milestone", title_font)
    if title:
        tw, _ = _measure(draw, title, small_font)
        _text(draw, (width - 48 - tw, 40), title, small_font, GRAY)

    y = 118
    x = 40
    rw, rh = 100, 48
    request_cy = y + 58
    _box(draw, (x, request_cy - rh / 2, x + rw, request_cy + rh / 2), WHITE, NAVY, radius=24, width=2)
    _center(draw, "request", body_font, x + rw / 2, request_cy)
    x += rw + 8
    _arrow(draw, x, request_cy, x + 36)
    x += 40
    avail = width - x - 40
    gap = 20 if count > 4 else 44
    box_w = min(340, max(140, (avail - gap * max(count - 1, 0)) // count))

    for index, (node, human) in enumerate(zip(nodes, humans)):
        bx = x + index * (box_w + gap)
        status = human.get("status") or ""
        fill = STATUS_FILL.get(status, WHITE)
        edge = STATUS_EDGE.get(status, NAVY)
        _center(draw, "this.in = previous.out", small_font, bx + box_w / 2, y - 18, GRAY)
        _box(draw, (bx, y, bx + box_w, y + box_h), fill, edge, radius=18, width=3)
        head = f"MILESTONE  {human['id']}"
        if status:
            head = f"{head}  {status}"
        _text(draw, (bx + 16, y + 12), head[: 36], small_font, GRAY)
        if node.get("cache"):
            ttl = (node.get("cache") or {}).get("ttl_seconds")
            cache_label = str(node.get("cache_status") or f"TTL {ttl}s")
            _text(draw, (bx + box_w - 116, y + 12), f"cache {cache_label}"[:16], small_font, BLUE_EDGE)
        title_lines = _wrap(draw, human["title"], h2_font, box_w - 32)[:1]
        _text(draw, (bx + 16, y + 36), title_lines[0], h2_font)
        if node.get("branch"):
            _text(draw, (bx + 16, y + 56), "then branch", small_font, BLUE_EDGE)
        elif node.get("on_path"):
            _text(draw, (bx + 16, y + 56), f"path: {node['on_path']}"[: 28], small_font, BLUE_EDGE)
        produce = human.get("success") or human["asset"]
        produce_lines = _wrap(draw, produce, small_font, box_w - 32)[:2]
        py = y + 78 if (node.get("branch") or node.get("on_path")) else y + 68
        for line in produce_lines:
            _text(draw, (bx + 16, py), line, small_font, NAVY)
            py += 18
        ports = ", ".join(str(output.get("id") or "") for output in node.get("outputs") or [] if output.get("id"))
        if ports:
            _text(draw, (bx + 16, y + box_h - 20), f"out: {ports}"[: 38], small_font, GREEN)
        if index < len(humans) - 1:
            _arrow(draw, bx + box_w + 4, request_cy, bx + box_w + gap)

    _box(draw, (width / 2 - 280, y + box_h + 28, width / 2 + 280, y + box_h + 64), RED_BG, RED, radius=8, width=2)
    _center(
        draw,
        "No chosen-output.json → BLOCK. Next milestone does not start.",
        small_font,
        width / 2,
        y + box_h + 46,
        RED,
    )

    draw.line((48, top_h - 24, width - 48, top_h - 24), fill=(210, 214, 220), width=2)
    _text(
        draw,
        (48, top_h - 8),
        "2. Inside one milestone — expectation + FlowSteps + admission + optional judge",
        title_font,
    )

    inner_top = top_h + 44
    inner_bot = height - 56
    _box(draw, (40, inner_top, width - 40, inner_bot), WHITE, BLUE_EDGE, radius=22, width=3)
    if not focus:
        _text(draw, (64, inner_top + 24), "No milestones yet.", body_font)
        return image

    focus_h = humanize_milestone(focus)
    mid = str(focus.get("id") or "")
    gem = str(focus.get("gem") or f"references/{mid}.md")
    has_judge = str(focus.get("loop") or "none") == "judge"
    worker = str(focus.get("worker") or "BLOCKED: missing judge")
    _text(draw, (64, inner_top + 14), f"MILESTONE  {mid}    gem  {gem}", h2_font)
    cap = focus_h.get("success") or (focus_h["title"] + " — " + focus_h["asset"])
    _text(draw, (64, inner_top + 42), f"expectation authority: {cap}"[: 120], small_font, GRAY)

    sh = 108
    sx = 64
    sy = inner_top + 78
    sequence = list(flowsteps)
    if has_judge:
        sequence.append(
            {
                "id": "judge",
                "title": "Judge",
                "tool": worker,
                "kind": "judge",
                "gem": gem,
            }
        )

    for index, fs in enumerate(sequence):
        bx = sx + index * (sw + 28)
        is_judge = fs.get("kind") == "judge"
        if is_judge:
            _box(draw, (bx, sy, bx + sw, sy + sh), YELLOW, YELLOW_EDGE, radius=16, width=3)
            _text(draw, (bx + 14, sy + 8), "JUDGE", small_font, GRAY)
            _text(draw, (bx + 14, sy + 28), "reads this gem", h2_font)
            gem_lines = _wrap(draw, gem, small_font, sw - 28)[:2]
            gy = sy + 56
            for line in gem_lines:
                _text(draw, (bx + 14, gy), line, small_font, NAVY)
                gy += 16
        else:
            _box(draw, (bx, sy, bx + sw, sy + sh), BLUE, BLUE_EDGE, radius=16, width=3)
            _text(draw, (bx + 14, sy + 10), f"FlowStep {index + 1}", small_font, GRAY)
            title_lines = _wrap(draw, fs.get("title") or fs.get("id") or "", h2_font, sw - 28)[:1]
            _text(draw, (bx + 14, sy + 32), title_lines[0], h2_font)
            tool = fs.get("tool") or "—"
            tag = f"tool: {tool}"
            tw, th = _measure(draw, tag[: 28], small_font)
            tag_w = min(sw - 28, tw + 20)
            _box(draw, (bx + 14, sy + sh - 34, bx + 14 + tag_w, sy + sh - 10), WHITE, NAVY, radius=10, width=1)
            _text(draw, (bx + 24, sy + sh - 30), tag[: 28], small_font)
        if index < len(sequence) - 1:
            _arrow(draw, bx + sw + 4, sy + sh / 2, bx + sw + 24)

    out_x = width - 268
    _box(draw, (out_x, sy - 4, out_x + 210, sy + 36), GREEN_BG, GREEN, radius=10, width=2)
    _text(draw, (out_x + 12, sy + 8), "PASS → choose bundle", small_font, GREEN)
    _box(draw, (out_x, sy + 44, out_x + 210, sy + 84), AMBER, AMBER_EDGE, radius=10, width=2)
    retry_text = "RETRY → keep working" if has_judge else "invalid → BLOCK"
    _text(draw, (out_x + 12, sy + 56), retry_text, small_font, YELLOW_EDGE)
    _box(draw, (out_x, sy + 92, out_x + 210, sy + 124), RED_BG, RED, radius=10, width=2)
    _text(draw, (out_x + 12, sy + 100), "no chosen output → BLOCK", small_font, RED)

    _center(
        draw,
        "FlowSteps refine candidates. Admission always runs; optional judge PASS commits chosen-output.json.",
        small_font,
        width / 2,
        inner_bot + 22,
        GRAY,
    )
    return image


def write_flowchart_jpg(
    path: Path,
    items: list[dict[str, Any]],
    *,
    title: str,
    focus_id: str | None = None,
    statuses: dict[str, str] | None = None,
) -> Path:
    path = Path(path)
    path.parent.mkdir(parents=True, exist_ok=True)
    image = render_flowchart_image(items, title=title, focus_id=focus_id, statuses=statuses)
    image.save(path, format="JPEG", quality=92)
    return path


README_DEMO = [
    {
        "id": "source_ready",
        "outputs": [{"id": "source", "name": "Source file", "kind": "file", "cardinality": "one", "required": True}],
        "worker": "source_ready_judge",
        "gem": "references/source_ready.md",
        "success": "The accepted source file is chosen and ready downstream.",
        "tools": ["fetch_record", "hash_bind", "source_ready_judge"],
        "flowsteps": [
            {"id": "fetch_record", "tool": "fetch_record"},
            {"id": "hash_bind", "tool": "hash_bind"},
        ],
    },
    {
        "id": "plan_frozen",
        "outputs": [{"id": "plan", "name": "Plan", "kind": "json", "cardinality": "one", "required": True}],
        "tools": ["compact_editorial_config"],
        "flowsteps": [{"id": "compact_plan", "tool": "compact_editorial_config"}],
    },
    {
        "id": "release_packaged",
        "outputs": [{"id": "package", "name": "Release package", "kind": "file", "cardinality": "one", "required": True}],
        "tools": ["materialize_package"],
        "flowsteps": [{"id": "materialize_package", "tool": "materialize_package"}],
    },
]

ARTICLE_DEMO = [
    {
        "id": "source_ready",
        "outputs": [{"id": "source", "name": "Source", "kind": "file", "cardinality": "one", "required": True}],
        "tools": ["normalize_source_blocks", "hash_bind"],
        "flowsteps": [
            {"id": "normalize_source_blocks", "tool": "normalize_source_blocks"},
            {"id": "hash_bind", "tool": "hash_bind"},
        ],
    },
    {
        "id": "plan_frozen",
        "outputs": [{"id": "plan", "name": "Plan", "kind": "json", "cardinality": "one", "required": True}],
        "tools": ["hash_bind", "schema_validate"],
        "flowsteps": [
            {"id": "hash_bind", "tool": "hash_bind"},
            {"id": "schema_validate", "tool": "schema_validate"},
        ],
    },
    {
        "id": "prompts_frozen",
        "outputs": [{"id": "prompts", "name": "Prompts", "kind": "json", "cardinality": "many", "required": True}],
        "tools": ["hash_bind", "schema_validate"],
        "flowsteps": [
            {"id": "hash_bind", "tool": "hash_bind"},
            {"id": "schema_validate", "tool": "schema_validate"},
        ],
    },
    {
        "id": "assets_bound",
        "outputs": [{"id": "assets", "name": "Bound assets", "kind": "file", "cardinality": "many", "required": True}],
        "loop": "for",
        "ledger": {"path": "pages", "item_schema": "schemas/page_item_v1.json", "max_items": 7},
        "worker": "ledger_receipt",
        "tools": ["hash_bind", "image_size_check", "ledger_receipt"],
        "flowsteps": [
            {"id": "hash_bind", "tool": "hash_bind"},
            {"id": "image_size_check", "tool": "image_size_check"},
        ],
    },
    {
        "id": "cards_rendered",
        "outputs": [{"id": "cards", "name": "Rendered cards", "kind": "image", "cardinality": "many", "required": True}],
        "loop": "judge",
        "worker": "cards_rendered_judge",
        "gem": "references/cards_rendered.md",
        "tools": ["render_html_shell", "footer_geometry_qa", "hash_bind", "cards_rendered_judge"],
        "flowsteps": [
            {"id": "render_html_shell", "tool": "render_html_shell"},
            {"id": "footer_geometry_qa", "tool": "footer_geometry_qa"},
            {"id": "hash_bind", "tool": "hash_bind"},
        ],
    },
    {
        "id": "release_packaged",
        "outputs": [{"id": "package", "name": "Release package", "kind": "file", "cardinality": "one", "required": True}],
        "tools": ["footer_geometry_qa", "hash_bind", "materialize_package", "io_manifest"],
        "flowsteps": [
            {"id": "footer_geometry_qa", "tool": "footer_geometry_qa"},
            {"id": "hash_bind", "tool": "hash_bind"},
            {"id": "materialize_package", "tool": "materialize_package"},
            {"id": "io_manifest", "tool": "io_manifest"},
        ],
    },
]


def write_readme_chart(root: Path | None = None) -> Path:
    root = Path(root) if root else Path(__file__).resolve().parents[1]
    dest = root / "docs" / "m8m-chart.jpg"
    return write_flowchart_jpg(
        dest,
        README_DEMO,
        title="m8m-harness-builder",
        focus_id="source_ready",
    )


if __name__ == "__main__":
    path = write_readme_chart()
    print(path)
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: 119kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall
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: 108kUpdated Claude CodeCodexVerifiedInstall
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: 108kUpdated Claude CodeCodexVerifiedInstall