feat(extension): add orchestrator extension for intelligent agent rou…

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

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
+```