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

View on GitHub
"""Generate and update planning/flowstep-instruction.md — the skill instruction."""

from __future__ import annotations

import argparse
import json
import re
import sys
from pathlib import Path
from typing import Any

from teaching_contracts import list_flow_teaching_rel
from toolbox_plan import render_toolbox_plan_markdown
from tool_vs_intelligence import from_flow as classification_from_flow
from tool_vs_intelligence import render_markdown as render_classification_markdown
from flowstep_runtime import (
    FlowError,
    add_harness_location_args,
    find_flow_path,
    harness_dir_from_args,
    local_tool_package_name,
    load_flow,
    read_json,
    render_flowstep_table,
    utc_now,
)


INSTRUCTION_REL = Path("planning/flowstep-instruction.md")
HEADER = "<!-- flowstep_instruction_v1 -->"
STATUSES = ("PENDING", "DONE", "BLOCKED")
STATUS_RE = re.compile(r"^- status: (PENDING|DONE|BLOCKED)\s*$", re.M)
HEADING_RE = re.compile(r"^### `([a-z][a-z0-9_]*)`\s*$", re.M)


def instruction_path(skill_dir: Path) -> Path:
    return skill_dir / INSTRUCTION_REL


def expected_return(schema: dict[str, Any]) -> str:
    properties = schema.get("properties") or {}
    required = list(schema.get("required") or properties)
    summary: dict[str, Any] = {}
    for key in required:
        prop = properties.get(key) if isinstance(properties.get(key), dict) else {}
        if "enum" in prop:
            summary[key] = " | ".join(str(item) for item in prop["enum"])
        elif "$ref" in prop:
            summary[key] = prop["$ref"]
        else:
            summary[key] = prop.get("type") or "object"
    return json.dumps(summary, ensure_ascii=False)


def _schema_summary(skill_dir: Path, relative: str) -> str:
    path = skill_dir / relative
    if not path.is_file():
        return "{}"
    try:
        return expected_return(read_json(path))
    except (FlowError, OSError, TypeError):
        return "{}"


def parse_statuses(markdown: str) -> dict[str, str]:
    statuses: dict[str, str] = {}
    current: str | None = None
    for line in markdown.splitlines():
        heading = HEADING_RE.match(line)
        if heading:
            current = heading.group(1)
            continue
        if current:
            match = STATUS_RE.match(line)
            if match:
                statuses[current] = match.group(1)
                current = None
    return statuses


def render_instruction(
    skill_dir: Path,
    flow: dict[str, Any],
    statuses: dict[str, str] | None = None,
    toolbox_plan: list[dict[str, Any]] | None = None,
) -> str:
    statuses = statuses or {}
    last = flow["steps"][-1]
    lines = [
        HEADER,
        f"# FlowStep instruction: {flow['flow_id']}",
        "",
        "This file is the skill instruction. Each section is a milestone.",
        "Milestone inputs are semantic context and bound references; no milestone input schema is required.",
        "Each milestone declares named output ports: FlowSteps refine candidates, structural admission always runs, and an authored semantic judge is optional.",
        "Mark DONE only after admission (and judge PASS when declared) materializes the chosen output bundle in chosen-output.json.",
        "FlowSteps inside a milestone are a guide: prefer one tool each, in table order.",
        "The tool is optional. If it fails, recover like a normal agent. Do not skip required named outputs.",
        "",
        f"- harness: `{skill_dir}`",
        f"- flow_id: `{flow['flow_id']}`",
        f"- final_payload: `{last['output_contract']}` from `{last['id']}`",
        f"- updated_at: {utc_now()}",
        "",
        "## Run",
        "",
        "```powershell",
        "python <installed-skill>/scripts/m8m_run.py "
        "--harness-root C:\\NisanRuntime --request <request.json>",
        "```",
        "",
        "The source repo is code/specification authority only. New mutable run state, goals, retries, checkpoints, milestone media, and candidate cache live under the host-local harness root.",
        "Request file_ref_v2 assets are hash-verified and copied once into inputs/source-assets; milestones receive only the rewritten run-local paths.",
        "File and media candidate paths must already resolve inside the active run; chosen-output commit copies them directly into the chosen bundle.",
        "Resume an exact initialized legacy run only by its exact --run-dir; never discover or migrate it from the source repo.",
        "Generic M8M does not export final packages. Any final archive copy remains the product runtime's authority.",
        "",
        "If a milestone returns ACTION_REQUIRED, write only the frozen draft and advance.",
        "",
        "## Tool vs intelligence",
        "",
        "Schema: `tool_vs_intelligence_table_v1`.",
        "",
        render_classification_markdown(classification_from_flow(flow)),
        "",
    ]
    if flow.get("_v4"):
        lines.extend(
            [
                "## Milestones",
                "",
                "The M8M flowchart is `planning/m8m-flowchart.md` plus `planning/m8m-flowchart.jpg`.",
                "The JPEG is rewritten on generate and on every step edit. It is the portable audit copy.",
                "",
            ]
        )
        if toolbox_plan:
            lines.extend(render_toolbox_plan_markdown(toolbox_plan).splitlines())
            lines.append("")
        used = []
        for step in flow["steps"]:
            for binding in (step.get("execution") or {}).get("tool_bindings") or []:
                if not isinstance(binding, dict) or not binding.get("ref"):
                    continue
                tool_id = local_tool_package_name(
                    str(binding["ref"]),
                    label=(
                        f"{step.get('id')}.execution.tool_bindings"
                        f"[{binding.get('tool')}].ref"
                    ),
                )
                if tool_id not in used:
                    used.append(tool_id)
        lines.extend(["## Toolbox", ""])
        for tool_id in used:
            lines.append(f"- `{tool_id}` — `flowsteps/tools/{tool_id}/tool.py`")
        teaching = list_flow_teaching_rel(skill_dir)
        lines.extend(
            [
                "",
                "## Teaching contracts",
                "",
                "Same rule as tools. These live on the flow, not in `~/.codex/skills` or `~/.claude/skills`.",
                "",
            ]
        )
        if teaching:
            for rel in teaching:
                lines.append(f"- `{rel}`")
        else:
            lines.append("None. Promote skill `references/*.md` into this flow.")
        lines.append("")
        lines.extend(["## Milestone index", ""])
    else:
        lines.extend(["## Step index", ""])
    table = render_flowstep_table(flow).splitlines()
    # drop the title line from the shared table; keep the markdown table
    body = [line for line in table if not line.startswith("# ")]
    lines.extend(body)
    if lines[-1] != "":
        lines.append("")
    lines.append("## Steps")
    lines.append("")
    for index, step in enumerate(flow["steps"], start=1):
        status = statuses.get(step["id"], "PENDING")
        if status not in STATUSES:
            status = "PENDING"
        inputs = ", ".join(f"{name}={ref}" for name, ref in step["inputs"].items())
        block = [
            f"### `{step['id']}`",
            f"- status: {status}",
            f"- order: {index}",
            f"- class: `{step.get('class', 'tool')}`",
            f"- intelligence: `{step.get('intelligence', step.get('model', 'none'))}`",
            f"- assemble: `{step['handler']}`",
            f"- toolbox: {', '.join(f'`{t}`' for t in (step.get('tools') or [])) or 'none'}",
            f"- flowsteps (guide): "
            + (
                ", ".join(
                    f"`{fs.get('id')}`→`{fs.get('tool') or '—'}`"
                    for fs in (step.get("flowsteps") or [])
                )
                or "none"
            ),
            f"- test: `{step.get('test', f'steps/{step['id']}/tests/test_tool.py')}`",
            f"- model: `{step['model']}`",
            f"- model_justification: {step.get('model_justification') or 'none'}",
            f"- inputs: {inputs}",
            f"- output_schema: `{step['output_schema']}`",
            f"- output_contract: `{step['output_contract']}`",
            f"- expected_return: `{_schema_summary(skill_dir, step['output_schema'])}`",
        ]
        if step["model"] != "none":
            block.append(
                f"- draft_schema: `{step.get('draft_schema', f'steps/{step['id']}/draft.schema.json')}`"
            )
        block.append("")
        lines.extend(block)
    lines.append("After a step's tool, schemas, and test are real, mark it DONE.")
    lines.append("Do not start the next step while the current step is PENDING.")
    lines.append("")
    return "\n".join(lines)


def write_instruction(
    skill_dir: Path,
    flow: dict[str, Any] | None = None,
    *,
    statuses: dict[str, str] | None = None,
    toolbox_plan: list[dict[str, Any]] | None = None,
    source: str = "edit",
) -> Path:
    skill_dir = skill_dir.resolve()
    flow = flow or load_flow(skill_dir, find_flow_path(skill_dir))
    path = instruction_path(skill_dir)
    merged = {}
    if path.is_file():
        merged.update(parse_statuses(path.read_text(encoding="utf-8")))
    if statuses:
        merged.update(statuses)
    known = {step["id"] for step in flow["steps"]}
    merged = {key: value for key, value in merged.items() if key in known}
    for step in flow["steps"]:
        merged.setdefault(step["id"], "PENDING")
    if toolbox_plan is None:
        saved = skill_dir / "planning" / "toolbox-plan.json"
        if saved.is_file():
            try:
                loaded_plan = json.loads(saved.read_text(encoding="utf-8"))
                if isinstance(loaded_plan, list):
                    toolbox_plan = loaded_plan
            except (OSError, json.JSONDecodeError, TypeError):
                toolbox_plan = None
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_text(
        render_instruction(skill_dir, flow, merged, toolbox_plan=toolbox_plan),
        encoding="utf-8",
        newline="\n",
    )
    if flow.get("_v4"):
        refresh_chart(skill_dir, flow, statuses=merged, source=source)
    return path


def refresh_chart(
    skill_dir: Path,
    flow: dict[str, Any],
    statuses: dict[str, str] | None = None,
    source: str = "edit",
) -> Path:
    from m8m_flowchart import write_flowchart
    from toolbox_plan import build_toolbox_plan

    skill_dir = skill_dir.resolve()
    plan = None
    saved = skill_dir / "planning" / "toolbox-plan.json"
    if saved.is_file():
        try:
            loaded_plan = json.loads(saved.read_text(encoding="utf-8"))
            if isinstance(loaded_plan, list):
                plan = loaded_plan
        except (OSError, json.JSONDecodeError, TypeError):
            plan = None
    if plan is None:
        plan = build_toolbox_plan(flow.get("steps") or [])
    return write_flowchart(
        skill_dir,
        flow.get("steps") or [],
        title=str(flow.get("flow_id") or skill_dir.name),
        flow_id=str(flow.get("flow_id") or ""),
        source=source,
        toolbox_plan=plan,
        statuses=statuses,
    )


def mark_step(skill_dir: Path, step_id: str, status: str) -> Path:
    if status not in STATUSES:
        raise FlowError(f"status must be one of {STATUSES}")
    flow = load_flow(skill_dir.resolve(), find_flow_path(skill_dir.resolve()))
    if step_id not in {step["id"] for step in flow["steps"]}:
        raise FlowError(f"unknown step: {step_id}")
    return write_instruction(skill_dir, flow, statuses={step_id: status})


def sync_statuses_from_errors(skill_dir: Path, flow: dict[str, Any], errors: list[str]) -> Path:
    statuses: dict[str, str] = {}
    for step in flow["steps"]:
        step_errors = [item for item in errors if item.startswith(f"{step['id']}:")]
        if not step_errors:
            statuses[step["id"]] = "DONE"
        elif any("generated stub" in item or "{ok: boolean}" in item for item in step_errors):
            statuses[step["id"]] = "PENDING"
        else:
            statuses[step["id"]] = "BLOCKED"
    return write_instruction(skill_dir, flow, statuses=statuses)


def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(description=__doc__)
    sub = parser.add_subparsers(dest="command", required=True)
    for name in ("write", "show"):
        item = sub.add_parser(name)
        add_harness_location_args(item)
        item.add_argument("--flow")
    mark = sub.add_parser("mark")
    add_harness_location_args(mark)
    mark.add_argument("--step", required=True)
    mark.add_argument("--status", required=True, choices=STATUSES)
    mark.add_argument("--flow")
    return parser


def main(argv: list[str] | None = None) -> int:
    args = build_parser().parse_args(argv)
    skill_dir = harness_dir_from_args(args)
    try:
        flow = load_flow(skill_dir, find_flow_path(skill_dir, getattr(args, "flow", None)))
        if args.command == "mark":
            path = mark_step(skill_dir, args.step, args.status)
        else:
            path = write_instruction(skill_dir, flow)
        text = path.read_text(encoding="utf-8")
        if args.command == "show":
            print(text, end="")
            return 0
        print(
            json.dumps(
                {
                    "schema": "flowstep_instruction_result_v1",
                    "status": "PASS",
                    "instruction_path": str(path),
                    "statuses": parse_statuses(text),
                },
                indent=2,
            )
        )
        return 0
    except FlowError as exc:
        print(json.dumps({"status": "BLOCKED", "blockers": [str(exc)]}, indent=2), file=sys.stderr)
        return 2


if __name__ == "__main__":
    raise SystemExit(main())
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