From 8c289b127a9ef5109f7765efd2a9f350a80bff89 Mon Sep 17 00:00:00 2001 From: pragya247 Date: Wed, 15 Apr 2026 18:04:52 +0530 Subject: [PATCH] feat(extension): add orchestrator extension for intelligent agent routing MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a new Spec Kit extension that provides cross-catalog agent discovery and intelligent prompt-to-command routing. Commands: - speckit.orchestrator.route — Match user prompts to best-fit commands - speckit.orchestrator.index — Build unified capability index across all catalogs - speckit.orchestrator.discover — Scan linked repos for agent definitions Includes: - extension.yml manifest with after_init hook for auto-indexing - config-template.yml with matching strategy and cross-repo scan settings - README with usage examples and routing algorithm description Ref: github/spec-kit#2142 --- extensions/orchestrator/README.md | 97 ++++++++++ .../commands/speckit.orchestrator.discover.md | 177 ++++++++++++++++++ .../commands/speckit.orchestrator.index.md | 174 +++++++++++++++++ .../commands/speckit.orchestrator.route.md | 155 +++++++++++++++ extensions/orchestrator/config-template.yml | 40 ++++ extensions/orchestrator/extension.yml | 61 ++++++ 6 files changed, 704 insertions(+) create mode 100644 extensions/orchestrator/README.md create mode 100644 extensions/orchestrator/commands/speckit.orchestrator.discover.md create mode 100644 extensions/orchestrator/commands/speckit.orchestrator.index.md create mode 100644 extensions/orchestrator/commands/speckit.orchestrator.route.md create mode 100644 extensions/orchestrator/config-template.yml create mode 100644 extensions/orchestrator/extension.yml diff --git a/extensions/orchestrator/README.md b/extensions/orchestrator/README.md new file mode 100644 index 000000000..b1ba1445f --- /dev/null +++ b/extensions/orchestrator/README.md @@ -0,0 +1,97 @@ +# Intelligent Agent Orchestrator — Spec Kit Extension + +Cross-catalog agent discovery and intelligent prompt-to-command routing for [Spec Kit](https://github.com/github/spec-kit). + +## What It Does + +| Capability | Description | +|-----------|-------------| +| **Route** | Match natural-language prompts to the best-fit Spec Kit command | +| **Index** | Build a unified capability index across core commands, extensions, workflows, and presets | +| **Discover** | Scan linked repositories for agent definitions (`.agent.md`, `SKILL.md`, etc.) | + +## Quick Start + +```bash +# Install the extension +specify extension add orchestrator + +# Build the capability index +> /speckit.orchestrator.index + +# Route a prompt to the best command +> /speckit.orchestrator.route "I want to create a spec for user authentication" +``` + +## Commands + +### `/speckit.orchestrator.route` + +Match a user prompt to the most relevant command: + +```bash +> /speckit.orchestrator.route "set up git branching" + +🎯 Routing Results: + 1 0.91 /speckit.git.feature extension:git + 2 0.72 /speckit.git.initialize extension:git +``` + +### `/speckit.orchestrator.index` + +Index all available capabilities: + +```bash +> /speckit.orchestrator.index + +✅ Capability index built! +📊 Total: 15 capabilities indexed +``` + +### `/speckit.orchestrator.discover` + +Find agents across linked repositories: + +```bash +> /speckit.orchestrator.discover --all + +🌐 Discovered 8 agents across 4 repositories +``` + +## Configuration + +Edit `.specify/extensions/orchestrator/orchestrator-config.yml`: + +```yaml +matching_strategy: "keyword" # "keyword" or "weighted" +confidence_threshold: 0.5 # 0.0 - 1.0 +cross_repo_scan: true + +linked_repos: + - path: "../frontend-app" + name: "Frontend" + - path: "../backend-api" + name: "Backend API" +``` + +## How Routing Works + +1. **Index** — Aggregates all capabilities from core commands, installed extensions, workflows, and presets into a single JSON index +2. **Score** — For each capability, computes relevance against the user prompt using keyword matching, description similarity, and name matching +3. **Rank** — Sorts by score, filters by confidence threshold +4. **Suggest** — Presents top matches with scores and offers to execute the best match + +## Roadmap + +- [ ] Semantic matching (beyond keyword-based) +- [ ] Integration as a native workflow `route` step type +- [ ] Catalog-level search aggregation +- [ ] Learning from user selections to improve future routing + +## Author + +**Pragya Chaurasia** — [pragya247](https://github.com/pragya247) + +## License + +MIT diff --git a/extensions/orchestrator/commands/speckit.orchestrator.discover.md b/extensions/orchestrator/commands/speckit.orchestrator.discover.md new file mode 100644 index 000000000..6aa8f81c5 --- /dev/null +++ b/extensions/orchestrator/commands/speckit.orchestrator.discover.md @@ -0,0 +1,177 @@ +--- +description: "Discover agents and capabilities across linked repositories" +--- + +# Discover Cross-Repository Agents + +Scan linked repositories for agent definitions, skill files, and capability manifests. Builds a unified view of all available agents across your development ecosystem. + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). The user may provide a specific repo path or URL to scan. + +## Prerequisites + +1. Ensure Git is available (`git rev-parse --is-inside-work-tree`) +2. Load orchestrator configuration from `.specify/extensions/orchestrator/orchestrator-config.yml` + +## Step 1: Identify Repositories to Scan + +Determine which repositories to scan: + +### Option A: Current Repository + +Always scan the current working directory. + +### Option B: Linked Repositories + +Check for linked repos in orchestrator config: + +```yaml +# orchestrator-config.yml +linked_repos: + - path: "../frontend-app" + name: "Frontend" + - path: "../backend-api" + name: "Backend API" + - path: "../shared-libs" + name: "Shared Libraries" +``` + +### Option C: Git Submodules + +If the current repo has submodules, include them: + +```bash +if [ -f ".gitmodules" ]; then + echo "📂 Found git submodules, including in scan..." + git submodule foreach --quiet 'echo $toplevel/$path' +fi +``` + +## Step 2: Scan Each Repository + +For each repository, search for agent-related files: + +```bash +echo "🔍 Scanning repository: $repo_name ($repo_path)" + +# Scan for these patterns: +scan_patterns=( + ".agent.md" + "SKILL.md" + "AGENTS.md" + ".claude/skills/*.md" + ".github/copilot-instructions.md" + ".specify/extensions/*/extension.yml" + ".specify/workflows/*/workflow.yml" + ".kimi/skills/*.md" +) + +for pattern in "${scan_patterns[@]}"; do + find "$repo_path" -path "*/$pattern" -type f 2>/dev/null +done +``` + +## Step 3: Parse Discovered Files + +For each discovered file, extract agent metadata: + +### Agent Files (`.agent.md`, `SKILL.md`) + +Extract: +- **Name**: From the first `# Heading` in the file +- **Description**: From the first paragraph or `description` frontmatter +- **Triggers**: Keywords and phrases that indicate when this agent should be invoked +- **Capabilities**: List of actions the agent can perform + +### Extension Manifests (`extension.yml`) + +Extract: +- **Extension ID**: From `extension.id` +- **Commands**: From `provides.commands[]` +- **Tags**: From `tags[]` + +### Workflow Definitions (`workflow.yml`) + +Extract: +- **Workflow ID**: From `workflow.id` +- **Steps**: From `steps[]` — what the workflow can do +- **Integrations**: Which AI agents it supports + +## Step 4: Build Discovery Report + +Generate a human-readable report and machine-readable JSON: + +```bash +echo "" +echo "🌐 Cross-Repository Agent Discovery Report" +echo "════════════════════════════════════════════" +echo "" +echo "📂 Repositories Scanned: 3" +echo "" +echo " Repository Agents Commands Workflows" +echo " ────────────────── ────── ──────── ─────────" +echo " Current (spec-kit) 2 13 1" +echo " Frontend 1 0 0" +echo " Backend API 1 3 0" +echo "" +echo "🤖 Discovered Agents:" +echo "" +echo " Agent Repo Type" +echo " ─────────────────────── ───────────── ──────────" +echo " Claude Code Agent Current .agent.md" +echo " Copilot Instructions Current .github" +echo " API Testing Agent Backend API SKILL.md" +echo " UI Component Helper Frontend .agent.md" +echo "" +echo "💾 Full report saved to .specify/extensions/orchestrator/discovery-report.json" +echo "" +``` + +## Step 5: Update the Capability Index + +Merge discovered agents into the main orchestrator index: + +```bash +echo "🔄 Updating capability index with discovered agents..." +# Merge into .specify/extensions/orchestrator/index.json +echo "✅ Index updated with cross-repo agents" +``` + +## Notes + +- Discovery scans local file system only — repos must be cloned +- Files are parsed for metadata, not executed +- Large monorepos may take longer to scan — use `scan_patterns` in config to narrow scope +- Run periodically or after pulling changes in linked repos + +## Examples + +### Example 1: Scan current repo + +```bash +> /speckit.orchestrator.discover + +🌐 Discovered 4 agents across 1 repository +``` + +### Example 2: Scan specific repo + +```bash +> /speckit.orchestrator.discover ../backend-api + +🌐 Discovered 2 agents in backend-api +``` + +### Example 3: Scan all linked repos + +```bash +> /speckit.orchestrator.discover --all + +🌐 Discovered 8 agents across 4 repositories +``` diff --git a/extensions/orchestrator/commands/speckit.orchestrator.index.md b/extensions/orchestrator/commands/speckit.orchestrator.index.md new file mode 100644 index 000000000..f34528cca --- /dev/null +++ b/extensions/orchestrator/commands/speckit.orchestrator.index.md @@ -0,0 +1,174 @@ +--- +description: "Index all available commands, extensions, workflows, and presets" +--- + +# Index Capabilities + +Scan and index all available Spec Kit capabilities — core commands, installed extensions, workflows, and presets — into a unified searchable index for intelligent routing. + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). The user may specify flags like `--force` to rebuild the index or `--verbose` for detailed output. + +## Prerequisites + +1. Ensure the project has been initialized (`specify init` has been run) +2. Check that `.specify/` directory exists + +## Step 1: Discover Core Commands + +Enumerate all built-in Spec Kit commands and their descriptions: + +| Command | Description | Keywords | +|---------|-------------|----------| +| `speckit.constitution` | Set up project constitution and rules | constitution, rules, setup, project | +| `speckit.specify` | Generate a specification from a feature description | spec, specification, feature, describe, requirements | +| `speckit.clarify` | Clarify and refine a specification | clarify, refine, questions, ambiguity | +| `speckit.plan` | Generate an implementation plan from a specification | plan, implementation, design, architecture | +| `speckit.tasks` | Break down a plan into actionable tasks | tasks, breakdown, issues, work items | +| `speckit.implement` | Implement code from tasks | implement, code, build, develop | +| `speckit.checklist` | Generate a review checklist | checklist, review, verify, quality | +| `speckit.analyze` | Analyze existing code or specifications | analyze, analysis, inspect, audit | + +## Step 2: Discover Installed Extensions + +Scan the extension registry at `.specify/extensions/.registry`: + +```bash +registry_file=".specify/extensions/.registry" + +if [ -f "$registry_file" ]; then + echo "📦 Scanning installed extensions..." + # Parse registry JSON for each extension + # For each extension, read its extension.yml manifest + # Extract: id, commands[], description, tags[] +fi +``` + +For each installed extension: +1. Read `.specify/extensions/{ext_id}/extension.yml` +2. Extract all commands from `provides.commands[]` +3. Extract keywords from `tags[]` and description +4. Record source as `extension:{ext_id}` + +## Step 3: Discover Installed Workflows + +Scan the workflow registry at `.specify/workflows/workflow-registry.json`: + +```bash +workflow_registry=".specify/workflows/workflow-registry.json" + +if [ -f "$workflow_registry" ]; then + echo "🔄 Scanning installed workflows..." + # Parse registry for each workflow + # Extract: id, name, description, tags +fi +``` + +For each installed workflow: +1. Read the workflow YAML definition +2. Extract: id, name, description, steps (for keyword extraction) +3. Record source as `workflow:{workflow_id}` + +## Step 4: Discover Installed Presets + +Scan the preset registry at `.specify/presets/.registry`: + +```bash +preset_registry=".specify/presets/.registry" + +if [ -f "$preset_registry" ]; then + echo "📝 Scanning installed presets..." + # Parse registry for each preset +fi +``` + +## Step 5: Cross-Repository Scan (Optional) + +If `cross_repo_scan` is enabled in config, scan for agent files in linked repositories: + +```bash +echo "🔍 Scanning for cross-repo agents..." + +# Scan patterns from config (default): +# - .agent.md +# - SKILL.md +# - AGENTS.md + +# For each discovered file: +# 1. Parse name, description, trigger phrases +# 2. Add to index as type: "external-agent" +# 3. Record source as "repo:{repo_path}" +``` + +## Step 6: Build and Save the Index + +Compile all discovered capabilities into a unified index: + +```bash +output_file=".specify/extensions/orchestrator/index.json" + +cat > "$output_file" < /speckit.orchestrator.index + +✅ Capability index built successfully! +📊 Total: 15 capabilities indexed +``` + +### Example 2: Force rebuild + +```bash +> /speckit.orchestrator.index --force + +🔄 Rebuilding index from scratch... +✅ Capability index rebuilt! 15 capabilities indexed +``` diff --git a/extensions/orchestrator/commands/speckit.orchestrator.route.md b/extensions/orchestrator/commands/speckit.orchestrator.route.md new file mode 100644 index 000000000..60cc4c71f --- /dev/null +++ b/extensions/orchestrator/commands/speckit.orchestrator.route.md @@ -0,0 +1,155 @@ +--- +description: "Match a user prompt to the best-fit command across all catalogs" +--- + +# Intelligent Prompt Router + +Match a user's natural-language request to the most relevant Spec Kit command, extension, or workflow by searching across all installed catalogs. + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input as the prompt to route. + +## Prerequisites + +1. Verify the orchestrator index exists at `.specify/extensions/orchestrator/index.json` +2. If the index does not exist, run `/speckit.orchestrator.index` first to build it +3. Load orchestrator configuration from `.specify/extensions/orchestrator/orchestrator-config.yml` (use defaults if missing) + +## Step 1: Load the Capability Index + +Load the cached capability index: + +```bash +index_file=".specify/extensions/orchestrator/index.json" + +if [ ! -f "$index_file" ]; then + echo "⚠️ Index not found. Building index first..." + # Trigger index rebuild +fi + +echo "📋 Loaded capability index" +``` + +The index contains entries in this format: + +```json +{ + "capabilities": [ + { + "id": "speckit.specify", + "type": "core-command", + "name": "Specify", + "description": "Generate a specification from a feature description", + "keywords": ["spec", "specification", "feature", "describe", "requirements"], + "source": "core" + }, + { + "id": "speckit.git.feature", + "type": "extension-command", + "name": "Create Feature Branch", + "description": "Create a feature branch with sequential or timestamp numbering", + "keywords": ["git", "branch", "feature", "create"], + "source": "extension:git" + } + ] +} +``` + +## Step 2: Score Each Capability Against the Prompt + +For each capability in the index, compute a relevance score: + +1. **Keyword match** (weight: 0.4) — Count how many of the capability's keywords appear in the user prompt +2. **Description match** (weight: 0.3) — Check if words from the user prompt appear in the capability description +3. **Name match** (weight: 0.2) — Check if the capability name is mentioned or closely related +4. **Type bonus** (weight: 0.1) — Prefer workflows > extension commands > core commands for complex prompts; prefer core commands for simple ones + +Normalize scores to a 0.0–1.0 range. + +## Step 3: Rank and Filter Results + +1. Sort capabilities by score (descending) +2. Apply the confidence threshold from config (default: 0.5) +3. Take the top 5 results that exceed the threshold + +## Step 4: Present Results + +Display the routing results to the user: + +```bash +echo "" +echo "🎯 Routing Results for: \"$ARGUMENTS\"" +echo "" +echo " Rank Score Command Source" +echo " ──── ───── ───────────────────────────── ──────────" +echo " 1 0.92 /speckit.specify core" +echo " 2 0.78 /speckit.orchestrator.discover extension" +echo " 3 0.61 sdd-full-cycle (workflow) workflow" +echo "" +echo "💡 Suggested: Run /speckit.specify to proceed" +echo "" +``` + +If no results exceed the threshold: + +```bash +echo "" +echo "🤷 No confident match found for: \"$ARGUMENTS\"" +echo "" +echo "Suggestions:" +echo " • Try rephrasing your request" +echo " • Run /speckit.orchestrator.index to refresh the index" +echo " • Use 'specify extension search ' to browse available extensions" +echo "" +``` + +## Step 5: Offer to Execute + +If a top result has confidence ≥ 0.8, offer to execute it: + +```bash +echo "Would you like me to run /speckit.specify with your prompt? (y/n)" +``` + +## Notes + +- The routing is deterministic (keyword-based) — no external AI API calls required +- Scores are cached per prompt in `.specify/extensions/orchestrator/route-cache.json` +- Re-run `/speckit.orchestrator.index` after installing new extensions to update the index + +## Examples + +### Example 1: Finding the right command + +```bash +> /speckit.orchestrator.route "I want to create a specification for a login feature" + +🎯 Routing Results: + 1 0.95 /speckit.specify core + 2 0.62 /speckit.plan core +``` + +### Example 2: Cross-catalog discovery + +```bash +> /speckit.orchestrator.route "set up git branching for my project" + +🎯 Routing Results: + 1 0.91 /speckit.git.feature extension:git + 2 0.72 /speckit.git.initialize extension:git +``` + +### Example 3: Workflow matching + +```bash +> /speckit.orchestrator.route "run the full development cycle end to end" + +🎯 Routing Results: + 1 0.88 sdd-full-cycle workflow:speckit + 2 0.54 /speckit.specify core +``` diff --git a/extensions/orchestrator/config-template.yml b/extensions/orchestrator/config-template.yml new file mode 100644 index 000000000..06ff3cd5c --- /dev/null +++ b/extensions/orchestrator/config-template.yml @@ -0,0 +1,40 @@ +# Orchestrator Configuration +# Configure intelligent agent routing and cross-repo discovery + +# Matching strategy for prompt-to-command routing +# Options: "keyword" (fast, deterministic), "weighted" (keyword + description scoring) +matching_strategy: "keyword" + +# Minimum confidence score (0.0 - 1.0) for a match to be shown +# Lower = more results, higher = more precise +confidence_threshold: 0.5 + +# Enable scanning across linked repositories for agent discovery +cross_repo_scan: true + +# File patterns to scan for agent definitions +scan_patterns: + - ".agent.md" + - "SKILL.md" + - "AGENTS.md" + - ".claude/skills/*.md" + - ".github/copilot-instructions.md" + - ".specify/extensions/*/extension.yml" + - ".specify/workflows/*/workflow.yml" + +# Linked repositories to include in cross-repo discovery +# Add paths (relative or absolute) to repos you want to scan +linked_repos: [] + # - path: "../frontend-app" + # name: "Frontend" + # - path: "../backend-api" + # name: "Backend API" + +# Caching settings +cache: + # Cache duration for the capability index (in seconds) + # Default: 3600 (1 hour) + index_ttl: 3600 + + # Cache route results for repeated queries + route_cache_enabled: true diff --git a/extensions/orchestrator/extension.yml b/extensions/orchestrator/extension.yml new file mode 100644 index 000000000..51ce1d1d5 --- /dev/null +++ b/extensions/orchestrator/extension.yml @@ -0,0 +1,61 @@ +schema_version: "1.0" + +extension: + id: orchestrator + name: "Intelligent Agent Orchestrator" + version: "0.1.0" + description: "Cross-catalog agent discovery and intelligent prompt-to-command routing" + author: "Pragya Chaurasia" + repository: "https://github.com/pragya247/spec-kit-orchestrator" + license: "MIT" + homepage: "https://github.com/pragya247/spec-kit-orchestrator" + +requires: + speckit_version: ">=0.6.1" + +provides: + commands: + - name: speckit.orchestrator.route + file: commands/speckit.orchestrator.route.md + description: "Match a user prompt to the best-fit command across all catalogs" + + - name: speckit.orchestrator.index + file: commands/speckit.orchestrator.index.md + description: "Index all available commands, extensions, workflows, and presets" + + - name: speckit.orchestrator.discover + file: commands/speckit.orchestrator.discover.md + description: "Discover agents and capabilities across linked repositories" + + config: + - name: "orchestrator-config.yml" + template: "config-template.yml" + description: "Orchestrator routing configuration" + required: false + +hooks: + after_init: + command: speckit.orchestrator.index + optional: true + prompt: "Index available commands and agents for intelligent routing?" + description: "Auto-index capabilities after project initialization" + +tags: + - "orchestrator" + - "routing" + - "discovery" + - "agent" + - "ai" + +config: + defaults: + matching_strategy: "keyword" + confidence_threshold: 0.5 + cross_repo_scan: true + scan_patterns: + - ".agent.md" + - "SKILL.md" + - "AGENTS.md" + - "extension.yml" + - "workflow.yml" + - "preset.yml"