Skip to content

richfrem/agent-plugins-skills / plugins/agent-orchestration/.apm/skills/orchestrating-agent-work

orchestrating-agent-work

Verified

Interactive orchestrator for complex engineering work. Analyzes the task, conducts a diagnostic interview to select the appropriate execution strategy (Directed Acyclic Graph versus Loop, and which Loop type), plans the artifact, and supervises execution and verification. Use for "how should I orchestrate this", "plan this workflow", "should this be a DAG or a loop", "run these jobs in parallel", "delegate this to a worker agent", or "run/resume this graph manifest". Not for single trivial edits or skill self-improvement.

FileKindSize
SKILL.mdskill md6.8 KB
assets/templates/dual-loop-meta-tasks.mdmarkdown1.6 KB
assets/templates/loop_retrospective_template.mdmarkdown1.5 KB
assets/templates/red_team_briefing_template.mdmarkdown747 B
assets/templates/scratchpad-template.mdmarkdown991 B
assets/templates/strategy-packet-template.mdmarkdown1.2 KB
assets/templates/workflow-retrospective-template.mdmarkdown1.3 KB
evals/evals.jsonconfig7.0 KB
references/PATTERN_GUIDE.mdmarkdown6.2 KB
references/acceptance-criteria.mdmarkdown6.8 KB
references/agentic-os-reuse-map.mdmarkdown2.5 KB
references/bot-delegation-patterns.mdmarkdown5.2 KB
references/cheapest_models.jsonconfig845 B
references/cheapest_models.mdmarkdown1.1 KB
references/cli-agent-executor.mdmarkdown3.5 KB
references/delegated-dag-refactoring-playbook.mdmarkdown5.5 KB
references/diagrams/agent_swarm.mmdother1.8 KB
references/diagrams/dual_loop_architecture.mmdother1.4 KB
references/diagrams/graph-planner-flow.mmdother540 B
references/diagrams/graph_execution_state_machine.mmdother823 B
references/diagrams/orchestrating_agent_work_architecture.mmdother4.5 KB
references/dispatch-preflight.mdmarkdown2.1 KB
references/fallback-tree.mdmarkdown9.7 KB
references/graph-execution.mdmarkdown4.1 KB
references/graph-manifest-schema.jsonconfig7.0 KB
references/graph-planning.mdmarkdown3.0 KB
references/learning-loop.mdmarkdown4.9 KB
references/patterns.jsonconfig2.0 KB
references/post_run_survey.mdmarkdown1.4 KB
references/routing-and-closure.mdmarkdown2.4 KB
references/strategy-agent-swarm.mdmarkdown2.1 KB
references/strategy-dual-loop.mdmarkdown1.6 KB
references/strategy-red-team-review.mdmarkdown2.0 KB
references/strategy-selection.mdmarkdown4.0 KB
references/topology-rules.mdmarkdown6.0 KB
scripts/agent_orchestrator.pyscript7.6 KB
scripts/dispatch_guard.pyscript1.1 KB
scripts/graph_runner.pyexecutablescript36.3 KB
scripts/select_strategy.pyscript13.1 KB
scripts/swarm_run.pyscript28.0 KB
scripts/validate_manifest.pyexecutablescript19.8 KB
scripts/work_loop.pyscript28.0 KB
tests/_loop_fixtures.pyscript2.5 KB
tests/test_graph_fixes.pyscript12.6 KB
tests/test_graph_runner.pyscript30.0 KB
tests/test_isolation.pyscript3.5 KB
tests/test_loop_strategies.pyscript7.7 KB
tests/test_select_strategy.pyscript7.8 KB
tests/test_swarm_run.pyscript9.4 KB
tests/test_swarm_run_models.pyscript3.1 KB
tests/test_validate_manifest.pyscript18.1 KB
tests/test_work_loop_e2e.pyscript3.8 KB
tests/test_work_loop_hardening.pyscript27.3 KB

scripts/select_strategy.py

View on GitHub
#!/usr/bin/env python3
"""
Deterministic Strategy Selector for Agent Orchestration
=======================================================

Single front door for choosing an orchestration pattern based on a 3-dimension diagnostic model.
Zero external dependencies (stdlib only).

Dimensions:
1. unit_structure: minimal_direct | one_bounded | distinct_steps | many_identical
2. ordering_convergence: none | barrier | ordered_mutations
3. assurance_need: normal | adversarial

Self-improvement and open-ended research are out of scope (agent-agentic-os os-lab owns them);
a legacy `task_nature` answer is accepted and ignored.
"""

import sys
import os
import json
import argparse
from pathlib import Path
from typing import Dict, Any, List, Optional, Set

SCRIPT_DIR = Path(__file__).resolve().parent
PATTERNS_FILE = SCRIPT_DIR.parent / "references" / "patterns.json"

DIMENSION_OPTIONS: Dict[str, Set[str]] = {
    "unit_structure": {"minimal_direct", "one_bounded", "distinct_steps", "many_identical"},
    "ordering_convergence": {"none", "barrier", "ordered_mutations"},
    "assurance_need": {"normal", "adversarial"},
}

VALID_PATTERNS: Set[str] = {
    "direct",
    "dual-loop",
    "graph",
    "agent-swarm",
    "red-team-review",
}

QUESTIONS: Dict[str, Dict[str, Any]] = {
    "unit_structure": {
        "prompt": "What is the structural unit breakdown of the task?",
        "options": [
            {"label": "Option A [Recommended]: One bounded change (single localized feature or bugfix)", "value": "one_bounded"},
            {"label": "Option B: Minimal direct change (single-line fix, typo, or trivial doc edit)", "value": "minimal_direct"},
            {"label": "Option C: Distinct steps with dependencies (stages, parallel fan-out, or sequential checkpoints)", "value": "distinct_steps"},
            {"label": "Option D: Many identical independent units (bulk operations across 10+ files or items)", "value": "many_identical"},
        ],
        "default": "one_bounded",
    },
    "ordering_convergence": {
        "prompt": "What ordering or convergence constraints apply to the results?",
        "options": [
            {"label": "Option A [Recommended]: None (steps do not need to merge at a synchronization barrier)", "value": "none"},
            {"label": "Option B: Results must merge at a barrier (e.g. parallel analysis joined before decisions)", "value": "barrier"},
            {"label": "Option C: Ordered mutations with gates between them (strict step-by-step state changes)", "value": "ordered_mutations"},
        ],
        "default": "none",
    },
    "assurance_need": {
        "prompt": "What level of assurance or review is required?",
        "options": [
            {"label": "Option A [Recommended]: Normal (standard test verification and code review)", "value": "normal"},
            {"label": "Option B: Adversarial review required (security boundary, architecture stress test)", "value": "adversarial"},
        ],
        "default": "normal",
    },
}


def load_patterns_catalog() -> Dict[str, Dict[str, Any]]:
    """Load canonical patterns catalog if present, or return defaults."""
    if PATTERNS_FILE.is_file():
        try:
            data = json.loads(PATTERNS_FILE.read_text(encoding="utf-8"))
            if isinstance(data, dict):
                return data
        except Exception:
            pass
    return {
        "graph": {"pattern": "graph", "next_skill": "orchestrating-agent-work", "next_step": "graph-planning", "plan_artifact": "docs/plans/work-tasks/<task-id>/<task-id>-graph-manifest.json"},
        "dual-loop": {"pattern": "dual-loop", "next_skill": "orchestrating-agent-work", "next_step": "strategy-dual-loop", "plan_artifact": "handoffs/task_packet_<task-id>.md"},
        "agent-swarm": {"pattern": "agent-swarm", "next_skill": "orchestrating-agent-work", "next_step": "strategy-agent-swarm", "plan_artifact": "docs/plans/work-tasks/<task-id>/<task-id>.job.md"},
        "direct": {"pattern": "direct", "next_skill": None, "next_step": None, "plan_artifact": "docs/plans/work-tasks/<task-id>/<task-id>-implementation-plan.md"},
        "red-team-review": {"pattern": "red-team-review", "next_skill": "orchestrating-agent-work", "next_step": "strategy-red-team-review", "plan_artifact": "docs/plans/work-tasks/<task-id>/<task-id>-threat-model.md"},
    }


def validate_answers(answers: Dict[str, Any]) -> List[str]:
    """Validate that answered dimensions have recognized, legal values."""
    errors = []
    for dim, val in answers.items():
        if dim == "task_nature":
            continue  # legacy dimension: accepted and ignored
        if dim not in DIMENSION_OPTIONS:
            errors.append(f"Unknown dimension '{dim}'")
            continue
        allowed = DIMENSION_OPTIONS[dim]
        if val not in allowed:
            errors.append(f"Invalid value '{val}' for dimension '{dim}'. Allowed values: {sorted(allowed)}")
    return errors


def decide_strategy(answers: Dict[str, str]) -> Dict[str, Any]:
    """Pure decision table mapping explicit validated answers to an orchestration pattern."""
    missing = [dim for dim in ["unit_structure", "ordering_convergence", "assurance_need"] if dim not in answers]
    if missing:
        next_dim = missing[0]
        q = QUESTIONS[next_dim]
        return {
            "status": "needs_clarification",
            "missing_dimension": next_dim,
            "question": {
                "dimension": next_dim,
                "prompt": q["prompt"],
                "options": q["options"],
                "default": q["default"],
            },
        }

    catalog = load_patterns_catalog()
    unit = answers["unit_structure"]
    order = answers["ordering_convergence"]
    assurance = answers["assurance_need"]

    rejected = []
    pattern = "direct"
    rationale = ""

    # Rule 1: Many identical independent units, no ordering -> agent-swarm
    if unit == "many_identical" and order == "none":
        pattern = "agent-swarm"
        rationale = "Task comprises many identical, independent units without inter-step dependencies."
        rejected.append({"pattern": "graph", "reason": "Identical independent units execute more efficiently under swarm workers without DAG barrier overhead"})
        rejected.append({"pattern": "dual-loop", "reason": "Dual-loop does not provide concurrent batch worker dispatch across bulk files"})

    # Rule 2: Distinct steps with dependencies or ordering barriers -> graph
    elif unit == "distinct_steps" or order in ("barrier", "ordered_mutations"):
        pattern = "graph"
        rationale = "Task exhibits distinct dependent phases, parallel fan-out join barriers, or ordered mutations."
        rejected.append({"pattern": "agent-swarm", "reason": "Swarm cannot manage join barriers, topological ordering, or dependency graphs"})
        rejected.append({"pattern": "dual-loop", "reason": "Dual-loop cannot orchestrate parallel fan-out reads or multi-step mutation sequences"})

    # Rule 3: One bounded change -> dual-loop
    elif unit == "one_bounded":
        pattern = "dual-loop"
        rationale = "Task is a single bounded feature or bugfix suitable for supervisor-worker execution."
        rejected.append({"pattern": "graph", "reason": "Single bounded change does not justify the ceremony or token overhead of a DAG runner"})
        rejected.append({"pattern": "agent-swarm", "reason": "Single bounded change is not a bulk batch operation"})

    # Rule 4: Minimal direct edit -> direct
    else:
        pattern = "direct"
        rationale = "Task is a minimal localized change executable directly without subagent overhead."
        rejected.append({"pattern": "graph", "reason": "Trivial edit does not require DAG orchestration"})
        rejected.append({"pattern": "dual-loop", "reason": "Trivial edit does not require supervisor-worker separation"})

    pat_info = catalog.get(pattern, {})
    result: Dict[str, Any] = {
        "status": "success",
        "pattern": pattern,
        "rationale": rationale,
        "rejected": rejected,
        "next_skill": pat_info.get("next_skill"),
        "next_step": pat_info.get("next_step"),
        "plan_artifact": pat_info.get("plan_artifact"),
        "override_requested": None,
    }

    # Adversarial assurance is a modifier wrapper on the build/fix pattern
    if assurance == "adversarial":
        result["assurance"] = "adversarial"
        result["advisory_wrappers"] = ["red-team-review"]
        result["rationale"] += " Wrapped with adversarial red-team review."

    return result


def main() -> None:
    parser = argparse.ArgumentParser(description="Deterministic Strategy Selector for Agent Orchestration")
    parser.add_argument("--answers", help="JSON string or path to JSON file containing dimension answers")
    parser.add_argument("--out", help="Optional output directory for decision record (default: stdout only, no tree pollution)")
    parser.add_argument("--override", help="Caller override pattern (e.g. graph, dual-loop, agent-swarm, direct)")
    parser.add_argument("--override-reason", help="Reason for requested override")
    parser.add_argument("--non-interactive", action="store_true", help="Fail closed if any dimension is missing")

    args = parser.parse_args()

    answers: Dict[str, str] = {}

    # 1. Parse explicit answers
    if args.answers:
        raw_ans = args.answers.strip()
        if raw_ans.startswith("{"):
            try:
                answers.update(json.loads(raw_ans))
            except json.JSONDecodeError as e:
                print(f"Error: Invalid JSON for --answers: {e}", file=sys.stderr)
                sys.exit(1)
        else:
            ans_path = Path(raw_ans)
            if not ans_path.is_file():
                print(f"Error: Answers file not found: {ans_path}", file=sys.stderr)
                sys.exit(1)
            try:
                answers.update(json.loads(ans_path.read_text(encoding="utf-8")))
            except Exception as e:
                print(f"Error: Failed to read answers file {ans_path}: {e}", file=sys.stderr)
                sys.exit(1)

    # 2. Validate answer values
    val_errors = validate_answers(answers)
    if val_errors:
        for err in val_errors:
            print(f"Error: {err}", file=sys.stderr)
        sys.exit(1)

    is_non_interactive = args.non_interactive or not sys.stdin.isatty() or bool(args.answers)

    # 3. Evaluate decision
    decision = decide_strategy(answers)

    if decision.get("status") == "needs_clarification":
        if is_non_interactive:
            print(json.dumps(decision, indent=2))
            print(f"Non-interactive mode: missing required answer for '{decision.get('missing_dimension')}'.", file=sys.stderr)
            sys.exit(2)
        else:
            # Interactive question flow
            q = decision["question"]
            dim = q["dimension"]
            print(f"\n{q['prompt']}")
            for opt in q["options"]:
                print(f"  - {opt['label']}")
            print(f"Default: [{q['default']}]")
            val = input(f"Select value ({', '.join([o['value'] for o in q['options']])}) [{q['default']}]: ").strip()
            if not val:
                val = q["default"]
            answers[dim] = val

            # Validate input
            val_errs = validate_answers({dim: val})
            if val_errs:
                for err in val_errs:
                    print(f"Error: {err}", file=sys.stderr)
                sys.exit(1)

            decision = decide_strategy(answers)

    # 4. Handle override if requested
    if args.override:
        if args.override not in VALID_PATTERNS:
            print(f"Error: Invalid override pattern '{args.override}'. Valid patterns: {sorted(VALID_PATTERNS)}", file=sys.stderr)
            sys.exit(1)

        catalog = load_patterns_catalog()
        target_info = catalog.get(args.override, {})
        decision["override_requested"] = {
            "from": decision.get("pattern"),
            "to": args.override,
            "reason": args.override_reason or "Caller requested override",
        }
        decision["pattern"] = args.override
        decision["next_skill"] = target_info.get("next_skill")
        decision["plan_artifact"] = target_info.get("plan_artifact")

    # 5. Output handling: Only write to disk if --out is explicitly provided
    if args.out:
        out_dir = Path(args.out)
        out_dir.mkdir(parents=True, exist_ok=True)
        out_file = out_dir / "select-loop-strategy-decision.json"
        out_file.write_text(json.dumps(decision, indent=2), encoding="utf-8")

        md_file = out_dir / "select-loop-strategy-decision.md"
        md_content = (
            f"# Orchestration Strategy Decision\n\n"
            f"- **Pattern**: `{decision.get('pattern')}`\n"
            f"- **Rationale**: {decision.get('rationale')}\n"
            f"- **Next Skill**: `{decision.get('next_skill')}`\n"
            f"- **Plan Artifact**: `{decision.get('plan_artifact')}`\n"
        )
        if decision.get("override_requested"):
            ov = decision["override_requested"]
            md_content += f"- **Requested Override**: From `{ov.get('from')}` to `{ov.get('to')}` ({ov.get('reason')})\n"
        md_file.write_text(md_content, encoding="utf-8")

    print(json.dumps(decision, indent=2))


if __name__ == "__main__":
    main()
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 321kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 321kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 321kUpdated Claude CodeCodexVerifiedInstall