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

tests/test_loop_strategies.py

View on GitHub
#!/usr/bin/env python3
"""
Unit tests for agent-orchestration/ skills, pattern selection decision tree, and contracts.
Validates:
- Decision tree logic for all orchestration patterns (asserts pattern = graph, not skill = graph-planner)
- Skill metadata standards (kebab-case, third-person description, line budgets)
- evals.json schema compliance (should_trigger boolean, prompt string)
- Elimination of dead CLI subcommand references in orchestrator
- Pattern-owned plan artifact assertions
"""

import json
import os
import re
import sys
import unittest
from pathlib import Path

REPO_ROOT = Path(__file__).resolve().parent.parent.parent.parent
PLUGIN_ROOT = Path(__file__).resolve().parent.parent


def evaluate_loop_strategy(task_description: str, has_dependencies: bool = False,
                           is_batch: bool = False, is_adversarial: bool = False,
                           is_bounded: bool = False, requires_human_gate: bool = False,
                           is_readonly_dag: bool = False) -> str:
    """
    Deterministic implementation of select-loop-strategy 6-gate decision tree.
    Returns the selected PATTERN name ('graph', 'agent-swarm', 'red-team-review', 'dual-loop', etc.).
    Note: requires_human_gate is orthogonal governance and does NOT force pattern = 'graph'.
    """
    if has_dependencies or is_readonly_dag:
        return "graph"
    if is_batch:
        return "agent-swarm"
    if is_adversarial:
        return "red-team-review"
    if is_bounded:
        return "dual-loop"
    return "learning-loop"


class TestLoopStrategiesDecisionTree(unittest.TestCase):

    def setUp(self):
        """Point at the real agent-orchestration skills/ directory to audit."""
        self.skills_dir = PLUGIN_ROOT / "skills"

    def test_all_expected_skills_exist(self):
        """Assert all core loop, graph planning, and execution skills exist in the plugin."""
        expected_skills = [
            "orchestrator",
            "select-loop-strategy",
            "dual-loop",
            "learning-loop",
            "co-pilot-loop",
            "agent-swarm",
            "red-team-review",
            "triple-loop-learning",
            "graph-planner",
            "graph-execution",
        ]
        for skill_name in expected_skills:
            skill_path = self.skills_dir / skill_name / "SKILL.md"
            self.assertTrue(
                skill_path.exists(),
                f"Expected skill {skill_name}/SKILL.md does not exist",
            )

    def test_routing_decision_tree_patterns(self):
        """
        Assert decision tree returns pattern names (e.g. pattern = graph),
        and verifies that human gates alone do not force graph routing.
        """
        # 1. Structural dependencies route to graph pattern
        pattern = evaluate_loop_strategy("Multi-phase refactor with parallel reads and ordered mutations", has_dependencies=True)
        self.assertEqual(pattern, "graph", "Structural dependencies must select pattern = 'graph'")

        # 2. Read-only DAG routes to graph pattern
        pattern = evaluate_loop_strategy("Multi-repo dependency scan joining at barrier", is_readonly_dag=True)
        self.assertEqual(pattern, "graph", "Read-only DAG must select pattern = 'graph'")

        # 3. Bounded bug fix with human review required routes to dual-loop (NOT graph!)
        pattern = evaluate_loop_strategy("Fix off-by-one bug with human approval gate", is_bounded=True, requires_human_gate=True)
        self.assertEqual(pattern, "dual-loop", "Bounded bug fix with human gate must select pattern = 'dual-loop', not 'graph'")

        # 4. Batch parallel tasks route to agent-swarm
        pattern = evaluate_loop_strategy("Convert 50 files independently", is_batch=True)
        self.assertEqual(pattern, "agent-swarm", "Batch conversion must select pattern = 'agent-swarm'")

        # 5. Security audit routes to red-team-review
        pattern = evaluate_loop_strategy("Stress-test auth flow against OWASP top 10", is_adversarial=True)
        self.assertEqual(pattern, "red-team-review", "Adversarial audit must select pattern = 'red-team-review'")

    def test_skill_frontmatter_and_line_budgets(self):
        """Assert all skills have valid YAML frontmatter and line budget <= 300 lines."""
        for skill_dir in self.skills_dir.iterdir():
            if not skill_dir.is_dir():
                continue
            skill_md = skill_dir / "SKILL.md"
            self.assertTrue(skill_md.exists(), f"Missing SKILL.md in {skill_dir}")
            content = skill_md.read_text(encoding="utf-8")
            lines = content.splitlines()
            
            # Line budget check: must be <= 300 lines for lean context
            self.assertLessEqual(
                len(lines), 300,
                f"Skill {skill_dir.name} has {len(lines)} lines (exceeds 300 lines)",
            )

            # Frontmatter check
            self.assertTrue(content.startswith("---\n"), f"Missing frontmatter in {skill_dir.name}")
            frontmatter_match = re.search(r"^---\n(.*?)\n---", content, re.DOTALL)
            self.assertIsNotNone(frontmatter_match, f"Malformed frontmatter in {skill_dir.name}")
            fm_text = frontmatter_match.group(1)

            # Name match
            name_match = re.search(r"^name:\s*([a-z0-9-]+)", fm_text, re.MULTILINE)
            self.assertIsNotNone(name_match, f"Missing or invalid name in {skill_dir.name}")
            self.assertEqual(name_match.group(1), skill_dir.name, "Skill name does not match directory")

            # Description check: third-person (no 'I ' or 'My ')
            desc_match = re.search(r"^description:\s*[\"']?(.*?)[\"']?$", fm_text, re.MULTILINE)
            self.assertIsNotNone(desc_match, f"Missing description in {skill_dir.name}")
            desc_text = desc_match.group(1)
            self.assertFalse(desc_text.lower().startswith("i "), f"Description must be third-person in {skill_dir.name}")

    def test_evals_schema_compliance(self):
        """Assert every skill with evals.json uses the should_trigger boolean schema."""
        for skill_dir in self.skills_dir.iterdir():
            if not skill_dir.is_dir():
                continue
            evals_file = skill_dir / "evals" / "evals.json"
            if evals_file.exists():
                data = json.loads(evals_file.read_text(encoding="utf-8"))
                self.assertIsInstance(data, list, f"{evals_file} must contain a JSON list")
                for idx, entry in enumerate(data):
                    self.assertIn("prompt", entry, f"Entry {idx} missing 'prompt' in {evals_file}")
                    self.assertIn("should_trigger", entry, f"Entry {idx} missing 'should_trigger' in {evals_file}")
                    self.assertIsInstance(entry["should_trigger"], bool, f"'should_trigger' must be boolean in {evals_file}")

    def test_learning_loop_does_not_contain_triple_loop_typo(self):
        """Verify the copy-paste typo in learning-loop Option B is fixed."""
        learning_loop_md = self.skills_dir / "learning-loop" / "SKILL.md"
        content = learning_loop_md.read_text(encoding="utf-8")
        self.assertNotIn(
            "Open the `triple-loop-learning` SKILL",
            content,
            "learning-loop still contains erroneous cross-reference to triple-loop-learning for Dual Loop option",
        )

    def test_orchestrator_removes_dead_cli_warnings(self):
        """Verify orchestrator does not advertise unimplemented scan/bundle subcommands."""
        orch_md = self.skills_dir / "orchestrator" / "SKILL.md"
        content = orch_md.read_text(encoding="utf-8")
        self.assertNotIn("A `scan` CLI subcommand is not currently implemented", content)
        self.assertNotIn("A `bundle` CLI subcommand is not currently implemented", content)


if __name__ == "__main__":
    unittest.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: 471kUpdated 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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated 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: 322kUpdated Claude CodeCodexVerifiedInstall