Skip to content

notque/vexjoy-agent / skills/meta/toolkit

toolkit

Verified

Toolkit management: create and evaluate skills and agents, manage routing tables, generate Claude.md.

FileKindSize
SKILL.mdskill md15.5 KB
agents/skill-creator/analyzer.mdmarkdown4.8 KB
agents/skill-creator/comparator.mdmarkdown4.7 KB
agents/skill-creator/grader.mdmarkdown3.9 KB
assets/skill-creator/eval_viewer.htmlother57.1 KB
references/agent-comparison.mdmarkdown11.5 KB
references/agent-comparison/benchmark-tasks.mdmarkdown6.8 KB
references/agent-comparison/do-creation-compliance-tasks.jsonconfig8.5 KB
references/agent-comparison/examples-and-errors.mdmarkdown1.0 KB
references/agent-comparison/grading-rubric.mdmarkdown4.3 KB
references/agent-comparison/methodology.mdmarkdown7.4 KB
references/agent-comparison/optimization-guide.mdmarkdown12.0 KB
references/agent-comparison/optimization-tasks.example.jsonconfig853 B
references/agent-comparison/optimize-phase.mdmarkdown9.3 KB
references/agent-comparison/read-only-ops-short-tasks.jsonconfig375 B
references/agent-comparison/report-template.mdmarkdown3.8 KB
references/agent-comparison/socratic-debugging-body-short-tasks.jsonconfig372 B
references/agent-comparison/socratic-debugging-trigger-tasks.jsonconfig2.8 KB
references/agent-creator.mdmarkdown10.9 KB
references/agent-creator/agent-design-patterns.mdmarkdown12.4 KB
references/agent-creator/agent-eval-design.mdmarkdown7.7 KB
references/agent-creator/agent-frontmatter-template.mdmarkdown9.3 KB
references/agent-evaluation.mdmarkdown10.6 KB
references/agent-evaluation/batch-evaluation.mdmarkdown1.6 KB
references/agent-evaluation/common-issues.mdmarkdown2.1 KB
references/agent-evaluation/report-templates.mdmarkdown2.2 KB
references/agent-evaluation/scoring-rubric.mdmarkdown2.4 KB
references/blind-ab-tests.mdmarkdown7.8 KB
references/generate-claudemd.mdmarkdown11.0 KB
references/generate-claudemd/CLAUDEMD_TEMPLATE.mdmarkdown4.1 KB
references/generate-claudemd/examples-and-errors.mdmarkdown7.4 KB
references/github-profile-rules.mdmarkdown7.5 KB
references/github-profile-rules/github-api-patterns.mdmarkdown8.2 KB
references/github-profile-rules/rule-categories.mdmarkdown4.8 KB
references/hook-development.mdmarkdown10.9 KB
references/hook-development/architecture.mdmarkdown3.7 KB
references/hook-development/code-examples.mdmarkdown9.4 KB
references/hook-development/preferred-patterns.mdmarkdown6.5 KB
references/hook-development/telemetry-database.mdmarkdown6.5 KB
references/routing-table-updater.mdmarkdown10.2 KB
references/routing-table-updater/batch-mode.mdmarkdown2.1 KB
references/routing-table-updater/conflict-resolution.mdmarkdown3.8 KB
references/routing-table-updater/error-handling.mdmarkdown1.9 KB
references/routing-table-updater/examples.mdmarkdown4.8 KB
references/routing-table-updater/extraction-patterns.mdmarkdown2.2 KB
references/routing-table-updater/routing-format.mdmarkdown3.6 KB
references/routing-table-updater/skill-examples.mdmarkdown2.7 KB
references/skill-composer.mdmarkdown9.1 KB
references/skill-composer/compatibility-matrix.mdmarkdown13.0 KB
references/skill-composer/composition-patterns.mdmarkdown4.9 KB
references/skill-composer/examples.mdmarkdown17.1 KB
references/skill-composer/skill-patterns.mdmarkdown12.5 KB
references/skill-creator.mdmarkdown28.9 KB
references/skill-creator/agent-template.mdmarkdown18.5 KB
references/skill-creator/artifact-schemas.mdmarkdown8.2 KB
references/skill-creator/bundled-components.mdmarkdown2.3 KB
references/skill-creator/complexity-tiers.mdmarkdown8.0 KB
references/skill-creator/domain-research-targets.mdmarkdown13.2 KB
references/skill-creator/enrichment-workflow.mdmarkdown9.9 KB
references/skill-creator/error-catalog.mdmarkdown9.9 KB
references/skill-creator/preferred-patterns.mdmarkdown11.7 KB
references/skill-creator/progressive-disclosure.mdmarkdown8.5 KB
references/skill-creator/skill-template.mdmarkdown14.6 KB
references/skill-creator/workflow-patterns.mdmarkdown7.6 KB
references/system-upgrade.mdmarkdown11.0 KB
references/system-upgrade/component-audit-checklists.mdmarkdown8.4 KB
references/system-upgrade/upgrade-failure-modes.mdmarkdown8.7 KB
references/system-upgrade/upgrade-signal-parsing.mdmarkdown7.3 KB
references/toolkit-evolution.mdmarkdown14.5 KB
references/toolkit-evolution/diagnose-scripts.mdmarkdown9.5 KB
references/toolkit-evolution/evolution-history.mdmarkdown5.5 KB
references/toolkit-evolution/evolution-report-template.mdmarkdown716 B
references/toolkit-evolution/evolve-preferred-patterns.mdmarkdown6.9 KB
references/toolkit-evolution/evolve-scripts.mdmarkdown3.7 KB
references/toolkit-governance.mdmarkdown16.0 KB
references/toolkit-governance/adr-lifecycle.mdmarkdown10.9 KB
references/toolkit-governance/frontmatter-compliance.mdmarkdown11.1 KB
references/toolkit-governance/hook-standardization.mdmarkdown21.5 KB
references/toolkit-governance/routing-table-patterns.mdmarkdown11.6 KB
references/weak-model-uplift.mdmarkdown10.3 KB
scripts/agent-comparison/compare.pyscript2.3 KB
scripts/agent-comparison/generate_variant.pyscript19.6 KB
scripts/agent-comparison/optimize_loop.pyscript89.3 KB
scripts/agent-comparison/trigger_eval.pyscript19.5 KB
scripts/routing-table-updater/extract_metadata.pyscript10.8 KB
scripts/routing-table-updater/generate_routes.pyscript10.5 KB
scripts/routing-table-updater/scan.pyscript4.7 KB
scripts/routing-table-updater/update_routing.pyscript12.4 KB
scripts/routing-table-updater/validate.pyscript7.3 KB
scripts/skill-composer/build_dag.pyscript12.5 KB
scripts/skill-composer/discover_skills.pyscript12.1 KB
scripts/skill-composer/validate.pyscript12.3 KB
scripts/skill-creator/aggregate_benchmark.pyscript10.0 KB
scripts/skill-creator/eval_compare.pyscript10.2 KB
scripts/skill-creator/optimize_description.pyscript12.5 KB
scripts/skill-creator/package_results.pyscript7.8 KB
scripts/skill-creator/run_eval.pyscript6.3 KB

scripts/skill-composer/build_dag.py

View on GitHub
#!/usr/bin/env python3
"""
DAG builder for skill composition.
Analyzes tasks and creates execution directed acyclic graphs.
"""

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


class DAGBuildError(Exception):
    """DAG building related errors."""

    pass


class SkillDAGBuilder:
    """Build execution DAG from task and skill index."""

    def __init__(self, skill_index: Dict[str, Any]):
        self.skill_index = skill_index
        self.skill_map = skill_index["skill_map"]

    def analyze_task(self, task_description: str) -> Dict[str, Any]:
        """Analyze task to identify required skills."""
        task_lower = task_description.lower()

        analysis = {
            "primary_goals": [],
            "quality_requirements": [],
            "domain_hints": [],
            "execution_hints": [],
        }

        # Identify primary goals
        if any(word in task_lower for word in ["add", "implement", "create", "build"]):
            analysis["primary_goals"].append("implementation")
        if any(word in task_lower for word in ["fix", "debug", "resolve", "repair"]):
            analysis["primary_goals"].append("debugging")
        if any(word in task_lower for word in ["analyze", "review", "examine", "investigate"]):
            analysis["primary_goals"].append("analysis")
        if any(word in task_lower for word in ["document", "comment", "explain"]):
            analysis["primary_goals"].append("documentation")

        # Identify quality requirements
        if any(word in task_lower for word in ["test", "tested", "testing"]):
            analysis["quality_requirements"].append("testing")
        if any(word in task_lower for word in ["verify", "validation", "check"]):
            analysis["quality_requirements"].append("verification")
        if any(word in task_lower for word in ["quality", "lint", "style"]):
            analysis["quality_requirements"].append("quality_checks")

        # Identify domain hints
        if "go" in task_lower or "golang" in task_lower:
            analysis["domain_hints"].append("golang")
        if any(word in task_lower for word in ["pr", "pull request", "review"]):
            analysis["domain_hints"].append("pr_review")
        if "workflow" in task_lower or "orchestrat" in task_lower:
            analysis["domain_hints"].append("workflow")

        # Identify execution hints
        if "and" in task_lower or "," in task_description:
            analysis["execution_hints"].append("multiple_steps")
        if any(word in task_lower for word in ["then", "after", "before"]):
            analysis["execution_hints"].append("sequential")
        if any(word in task_lower for word in ["also", "parallel", "simultaneously"]):
            analysis["execution_hints"].append("parallel")

        return analysis

    def select_skills(self, task_analysis: Dict[str, Any]) -> List[str]:
        """Select applicable skills based on task analysis."""
        selected = []

        # Map analysis to skill categories
        category_map = {
            "implementation": ["workflow", "testing"],
            "debugging": ["debugging"],
            "analysis": ["code-analysis"],
            "documentation": ["documentation"],
            "testing": ["testing"],
            "verification": ["quality"],
            "quality_checks": ["quality"],
        }

        # Collect applicable categories
        applicable_categories = set()
        for goal in task_analysis["primary_goals"]:
            applicable_categories.update(category_map.get(goal, []))
        for req in task_analysis["quality_requirements"]:
            applicable_categories.update(category_map.get(req, []))

        # Select skills from applicable categories
        categories = self.skill_index.get("categories", {})
        for category in applicable_categories:
            if category in categories:
                selected.extend(categories[category])

        # Remove duplicates while preserving order
        seen = set()
        unique_selected = []
        for skill in selected:
            if skill not in seen:
                seen.add(skill)
                unique_selected.append(skill)

        return unique_selected

    def build_dependency_graph(self, selected_skills: List[str]) -> Dict[str, List[str]]:
        """Build dependency graph from selected skills."""
        graph = {}

        for skill_name in selected_skills:
            skill = self.skill_map.get(skill_name)
            if not skill:
                continue

            # Get dependencies that are also selected
            deps = skill.get("dependencies", [])
            applicable_deps = [d for d in deps if d in selected_skills]

            if applicable_deps:
                graph[skill_name] = applicable_deps

        return graph

    def topological_sort(self, skills: List[str], dependencies: Dict[str, List[str]]) -> List[str]:
        """Perform topological sort on skills."""
        # Build in-degree map
        in_degree = {skill: 0 for skill in skills}
        for skill, deps in dependencies.items():
            for dep in deps:
                if dep in in_degree:
                    in_degree[skill] += 1

        # Find skills with no dependencies
        queue = [skill for skill, degree in in_degree.items() if degree == 0]
        result = []

        while queue:
            # Process skill with no remaining dependencies
            skill = queue.pop(0)
            result.append(skill)

            # Reduce in-degree for dependent skills
            for dependent, deps in dependencies.items():
                if skill in deps:
                    in_degree[dependent] -= 1
                    if in_degree[dependent] == 0:
                        queue.append(dependent)

        # Check if all skills were processed (DAG is valid)
        if len(result) != len(skills):
            unprocessed = set(skills) - set(result)
            raise DAGBuildError(f"Circular dependency detected. Unprocessed skills: {unprocessed}")

        return result

    def identify_parallel_phases(
        self, sorted_skills: List[str], dependencies: Dict[str, List[str]]
    ) -> List[Dict[str, Any]]:
        """Identify which skills can run in parallel."""
        phases = []
        remaining = set(sorted_skills)
        processed = set()

        while remaining:
            # Find skills with all dependencies satisfied
            ready = []
            for skill in remaining:
                deps = dependencies.get(skill, [])
                if all(dep in processed for dep in deps):
                    ready.append(skill)

            if not ready:
                raise DAGBuildError(f"Cannot determine next phase. Remaining: {remaining}")

            # Create phase
            phase = {
                "phase": len(phases) + 1,
                "parallel": len(ready) > 1,
                "skills": ready,
            }
            phases.append(phase)

            # Update state
            remaining -= set(ready)
            processed.update(ready)

        return phases

    def build_dag(self, task_description: str) -> Dict[str, Any]:
        """Build complete execution DAG from task."""
        # Step 1: Analyze task
        task_analysis = self.analyze_task(task_description)

        # Step 2: Select applicable skills
        selected_skills = self.select_skills(task_analysis)

        if not selected_skills:
            raise DAGBuildError(f"No applicable skills found for task: {task_description}")

        # Step 3: Build dependency graph
        dependencies = self.build_dependency_graph(selected_skills)

        # Step 4: Topological sort
        sorted_skills = self.topological_sort(selected_skills, dependencies)

        # Step 5: Identify parallel execution opportunities
        phases = self.identify_parallel_phases(sorted_skills, dependencies)

        # Build final DAG
        dag = {
            "task": task_description,
            "task_analysis": task_analysis,
            "selected_skills": selected_skills,
            "dependencies": dependencies,
            "execution_order": sorted_skills,
            "phases": phases,
            "total_phases": len(phases),
            "parallel_phases": sum(1 for p in phases if p["parallel"]),
        }

        return dag


def detect_cycles(graph: Dict[str, List[str]]) -> List[List[str]]:
    """Detect cycles in dependency graph using DFS."""
    cycles = []
    visited = set()
    rec_stack = []

    def dfs(node: str, path: List[str]):
        if node in rec_stack:
            # Found cycle
            cycle_start = rec_stack.index(node)
            cycle = rec_stack[cycle_start:] + [node]
            cycles.append(cycle)
            return

        if node in visited:
            return

        visited.add(node)
        rec_stack.append(node)

        for neighbor in graph.get(node, []):
            dfs(neighbor, path + [neighbor])

        rec_stack.pop()

    for node in graph:
        if node not in visited:
            dfs(node, [node])

    return cycles


def format_dag_output(dag: Dict[str, Any]) -> str:
    """Format DAG for human-readable display."""
    lines = [
        "=" * 60,
        "EXECUTION DAG",
        "=" * 60,
        "",
        f"Task: {dag['task']}",
        "",
        "Task Analysis:",
        f"  Primary goals: {', '.join(dag['task_analysis']['primary_goals'])}",
        f"  Quality requirements: {', '.join(dag['task_analysis']['quality_requirements'])}",
        "",
        f"Selected Skills ({len(dag['selected_skills'])}): {', '.join(dag['selected_skills'])}",
        "",
        "Execution Plan:",
        "",
    ]

    for phase in dag["phases"]:
        parallel_marker = " (PARALLEL)" if phase["parallel"] else ""
        lines.append(f"Phase {phase['phase']}{parallel_marker}:")
        for skill in phase["skills"]:
            lines.append(f"  → {skill}")
        lines.append("")

    lines.extend(
        [
            "Summary:",
            f"  Total phases: {dag['total_phases']}",
            f"  Parallel phases: {dag['parallel_phases']}",
            f"  Skills: {len(dag['selected_skills'])}",
            "=" * 60,
        ]
    )

    return "\n".join(lines)


def main():
    """Main entry point."""
    parser = argparse.ArgumentParser(description="Build execution DAG from task and skill index")
    parser.add_argument("--task", type=str, required=True, help="Task description")
    parser.add_argument("--skill-index", type=Path, required=True, help="Path to skill index JSON")
    parser.add_argument("--output", type=Path, required=True, help="Output DAG JSON file")
    parser.add_argument("--verbose", action="store_true", help="Enable verbose output")

    args = parser.parse_args()

    try:
        # Load skill index
        if not args.skill_index.exists():
            raise DAGBuildError(f"Skill index not found: {args.skill_index}")

        with open(args.skill_index, "r", encoding="utf-8") as f:
            skill_index = json.load(f)

        # Build DAG
        print(f"Analyzing task: {args.task}", file=sys.stderr)
        builder = SkillDAGBuilder(skill_index)
        dag = builder.build_dag(args.task)

        # Check for cycles
        cycles = detect_cycles(dag["dependencies"])
        if cycles:
            cycle_strs = [" → ".join(cycle) for cycle in cycles]
            raise DAGBuildError("Circular dependencies detected:\n" + "\n".join(cycle_strs))

        # Write output
        args.output.parent.mkdir(parents=True, exist_ok=True)
        with open(args.output, "w", encoding="utf-8") as f:
            json.dump(dag, f, indent=2, ensure_ascii=False)

        print(f"\nDAG written to: {args.output}", file=sys.stderr)

        # Print formatted DAG
        print("\n" + format_dag_output(dag), file=sys.stderr)

        # Output success to stdout
        print(
            json.dumps(
                {
                    "status": "success",
                    "total_phases": dag["total_phases"],
                    "skills": len(dag["selected_skills"]),
                    "output_file": str(args.output),
                },
                indent=2,
            )
        )

    except DAGBuildError as e:
        print(
            json.dumps(
                {"status": "error", "error_type": "DAGBuildError", "message": str(e)},
                indent=2,
            ),
            file=sys.stderr,
        )
        sys.exit(1)
    except Exception as e:
        print(
            json.dumps(
                {"status": "error", "error_type": type(e).__name__, "message": str(e)},
                indent=2,
            ),
            file=sys.stderr,
        )
        sys.exit(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: 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