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/teaching_contracts.py

View on GitHub
"""Teaching contracts live on the flow, like tools live in the repo toolbox."""

from __future__ import annotations

import shutil
from pathlib import Path
from typing import Any

from gem_text import with_milestone_outline
from milestone_pair import is_wait_milestone


TEACHING_DIRNAME = "references"
EMPTY = "—"


def _is_teaching(path: Path) -> bool:
    if path.suffix.lower() != ".md":
        return False
    if path.name.startswith("."):
        return False
    if "worker" in path.stem.lower():
        return False
    return True


def list_teaching(root: Path) -> list[Path]:
    folder = Path(root) / TEACHING_DIRNAME
    if not folder.is_dir():
        return []
    return [path for path in sorted(folder.glob("*.md")) if _is_teaching(path)]


def build_teaching_plan(
    skill_root: Path,
    harness_dir: Path | None = None,
) -> list[dict[str, str]]:
    skill_root = Path(skill_root).resolve()
    harness = Path(harness_dir).resolve() if harness_dir else None
    skill_files = {path.name: path for path in list_teaching(skill_root)}
    flow_files = {path.name: path for path in list_teaching(harness)} if harness else {}
    names = sorted(set(skill_files) | set(flow_files))
    rows: list[dict[str, str]] = []
    for name in names:
        dest_rel = f"{TEACHING_DIRNAME}/{name}"
        if name in flow_files and name in skill_files:
            if skill_root == harness:
                action = "already_in_flow"
                source = dest_rel
            else:
                action = "already_in_flow"
                source = f"{TEACHING_DIRNAME}/{name}"
        elif name in flow_files:
            action = "already_in_flow"
            source = dest_rel
        else:
            action = "promote"
            source = f"{TEACHING_DIRNAME}/{name}"
        rows.append(
            {
                "id": Path(name).stem,
                "name": name,
                "source": source,
                "destination": dest_rel,
                "action": action,
            }
        )
    return rows


def render_teaching_plan_markdown(plan: list[dict[str, str]]) -> str:
    lines = [
        "## Teaching contracts",
        "",
        "Same rule as tools. Teaching, instruction context, and judge rubrics",
        "live on the **flow** (`flowsteps/flows/<id>/references/`), not in",
        "`~/.codex/skills` or `~/.claude/skills`. Promote markdown from the",
        "skill `references/`.",
        "",
        "| Contract | Existing on the flow | Promote from skill references |",
        "| --- | --- | --- |",
    ]
    if not plan:
        lines.append("| (none) | | |")
        lines.append("")
        return "\n".join(lines)
    for row in plan:
        existing = f"`{row['destination']}`" if row.get("action") == "already_in_flow" else EMPTY
        promote = (
            f"`{row['id']}` ← `{row['source']}`" if row.get("action") == "promote" else EMPTY
        )
        lines.append(f"| `{row['id']}` | {existing} | {promote} |")
    lines.append("")
    return "\n".join(lines)


def copy_teaching_contracts(
    harness: Path,
    audit: dict[str, Any],
    *,
    overwrite: bool = False,
) -> list[str]:
    target = Path(str(audit.get("target") or ""))
    written: list[str] = []
    dest_dir = Path(harness) / TEACHING_DIRNAME
    for row in audit.get("teaching_plan") or []:
        name = str(row.get("name") or Path(str(row.get("destination") or "")).name)
        if not name:
            continue
        candidates = []
        if target:
            candidates.append(target / TEACHING_DIRNAME / name)
        source = row.get("source")
        if source:
            raw = Path(str(source))
            candidates.append(raw if raw.is_absolute() else (target / raw if target else raw))
        src = next((path for path in candidates if path.is_file()), None)
        if src is None:
            continue
        dest = dest_dir / name
        dest.parent.mkdir(parents=True, exist_ok=True)
        if dest.exists() and not overwrite:
            if dest.resolve() != src.resolve():
                continue
            continue
        if dest.resolve() == src.resolve():
            continue
        shutil.copy2(src, dest)
        written.append(str(dest))
    return written


def list_flow_teaching_rel(harness: Path) -> list[str]:
    return [f"{TEACHING_DIRNAME}/{path.name}" for path in list_teaching(harness)]


def write_milestone_gems(
    harness: Path,
    milestones: list[dict[str, Any]],
    *,
    overwrite: bool = False,
) -> list[str]:
    """Preserve each master prompt and project its current steps, tools, and outputs."""
    from flowstep_runtime import skill_rel
    from humanize_chart import success_line, title_id

    written: list[str] = []
    template = Path(__file__).resolve().parents[1] / "templates" / "milestone" / "gem.md"
    body = template.read_text(encoding="utf-8") if template.is_file() else (
        "# __MID__ — __TITLE__\n\n## Master prompt\n\n__SUCCESS__\n"
    )
    for item in milestones:
        mid = str(item.get("id") or item.get("agent_id") or "").strip()
        if not mid:
            continue
        dest = skill_rel(Path(harness), str(item.get("gem") or f"references/{mid}.md"))
        existing = dest.read_text(encoding="utf-8") if dest.is_file() else None
        authored_prompt = item.get("master_prompt")
        if existing is not None and not overwrite:
            authored_prompt = existing
        if isinstance(authored_prompt, str) and authored_prompt.strip():
            text = with_milestone_outline(authored_prompt, item)
            if text == existing:
                continue
            dest.parent.mkdir(parents=True, exist_ok=True)
            dest.write_text(text, encoding="utf-8", newline="\n")
            written.append(str(dest))
            continue
        declared_outputs = item.get("outputs") if isinstance(item.get("outputs"), list) else []
        kind = str(
            ((declared_outputs[0] or {}).get("kind") if declared_outputs and isinstance(declared_outputs[0], dict) else "")
            or "required"
        )
        loop = str(item.get("loop") or "none")
        worker = str(item.get("worker") or "")
        if loop == "judge" and is_wait_milestone(item):
            judge_line = (
                "- Loop: judge (wait). No draft yet → pause the roster "
                "(row waiting, session exits). Resume: find <run>/roster.json, "
                "write milestones/<id>/work/draft.json. FlowSteps follow the Gem; "
                "the judge evaluates the derived expectation and current candidate. "
                "RETRY → keep working on this box. PASS → next."
            )
        elif loop == "judge":
            judge_line = "- Loop: judge. The separate worker evaluates the derived expectation and returns PASS, RETRY, or BLOCKED."
        elif worker:
            judge_line = "- Loop: none. The worker accepts the current candidate in one shot."
        else:
            judge_line = "- Loop: none. Structural admission validates the closed candidate; no semantic judge runs."
        intelligence = str(item.get("intelligence") or "none")
        if intelligence == "none":
            classification = (
                "This milestone is deterministic tool work (`model: none`). Each "
                "FlowStep uses an existing capability through its declared binding."
            )
        else:
            justification = str(
                item.get("model_justification")
                or "the candidate requires judgment that a fixture cannot decide"
            ).strip()
            classification = (
                f"This milestone uses bounded `{intelligence}` intelligence because "
                f"{justification}. Deterministic sub-operations remain declared "
                "tools; the model returns only candidate data."
            )
        input_lines = []
        for name, binding in (item.get("inputs") or {}).items():
            if isinstance(binding, dict):
                fields = "; ".join(
                    f"`{key}: {binding[key]}`" for key in ("from", "output", "member") if key in binding
                )
                input_lines.append(f"- `{name}`: {fields}.")
            else:
                input_lines.append(f"- `{name}`: `{binding}`.")
        text = (
            body.replace("__TITLE__", str((item.get("observer") or {}).get("title") or item.get("success") or title_id(mid)))
            .replace("__SUCCESS__", str(item.get("success") or success_line(item)))
            .replace("__MID__", mid)
            .replace("__KIND__", kind)
            .replace("__WORKER__", worker or "—")
            .replace("__JUDGE_LINE__", judge_line)
            .replace("__CLASSIFICATION__", classification)
            .replace("__INPUTS__", "\n".join(input_lines) or "Use the request and inputs bound to this milestone.")
        )
        text = with_milestone_outline(text, item)
        dest.parent.mkdir(parents=True, exist_ok=True)
        dest.write_text(text, encoding="utf-8", newline="\n")
        written.append(str(dest))
    return written
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