Skip to content

Commit 8c289b1

Browse files
author
pragya247
committed
feat(extension): add orchestrator extension for intelligent agent routing
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: #2142
1 parent 3467d26 commit 8c289b1

6 files changed

Lines changed: 704 additions & 0 deletions

File tree

‎extensions/orchestrator/README.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# Intelligent Agent Orchestrator — Spec Kit Extension
2+
3+
Cross-catalog agent discovery and intelligent prompt-to-command routing for [Spec Kit](https://github.com/github/spec-kit).
4+
5+
## What It Does
6+
7+
| Capability | Description |
8+
|-----------|-------------|
9+
| **Route** | Match natural-language prompts to the best-fit Spec Kit command |
10+
| **Index** | Build a unified capability index across core commands, extensions, workflows, and presets |
11+
| **Discover** | Scan linked repositories for agent definitions (`.agent.md`, `SKILL.md`, etc.) |
12+
13+
## Quick Start
14+
15+
```bash
16+
# Install the extension
17+
specify extension add orchestrator
18+
19+
# Build the capability index
20+
> /speckit.orchestrator.index
21+
22+
# Route a prompt to the best command
23+
> /speckit.orchestrator.route "I want to create a spec for user authentication"
24+
```
25+
26+
## Commands
27+
28+
### `/speckit.orchestrator.route`
29+
30+
Match a user prompt to the most relevant command:
31+
32+
```bash
33+
> /speckit.orchestrator.route "set up git branching"
34+
35+
🎯 Routing Results:
36+
1 0.91 /speckit.git.feature extension:git
37+
2 0.72 /speckit.git.initialize extension:git
38+
```
39+
40+
### `/speckit.orchestrator.index`
41+
42+
Index all available capabilities:
43+
44+
```bash
45+
> /speckit.orchestrator.index
46+
47+
✅ Capability index built!
48+
📊 Total: 15 capabilities indexed
49+
```
50+
51+
### `/speckit.orchestrator.discover`
52+
53+
Find agents across linked repositories:
54+
55+
```bash
56+
> /speckit.orchestrator.discover --all
57+
58+
🌐 Discovered 8 agents across 4 repositories
59+
```
60+
61+
## Configuration
62+
63+
Edit `.specify/extensions/orchestrator/orchestrator-config.yml`:
64+
65+
```yaml
66+
matching_strategy: "keyword" # "keyword" or "weighted"
67+
confidence_threshold: 0.5 # 0.0 - 1.0
68+
cross_repo_scan: true
69+
70+
linked_repos:
71+
- path: "../frontend-app"
72+
name: "Frontend"
73+
- path: "../backend-api"
74+
name: "Backend API"
75+
```
76+
77+
## How Routing Works
78+
79+
1. **Index** — Aggregates all capabilities from core commands, installed extensions, workflows, and presets into a single JSON index
80+
2. **Score** — For each capability, computes relevance against the user prompt using keyword matching, description similarity, and name matching
81+
3. **Rank** — Sorts by score, filters by confidence threshold
82+
4. **Suggest** — Presents top matches with scores and offers to execute the best match
83+
84+
## Roadmap
85+
86+
- [ ] Semantic matching (beyond keyword-based)
87+
- [ ] Integration as a native workflow `route` step type
88+
- [ ] Catalog-level search aggregation
89+
- [ ] Learning from user selections to improve future routing
90+
91+
## Author
92+
93+
**Pragya Chaurasia** — [pragya247](https://github.com/pragya247)
94+
95+
## License
96+
97+
MIT

‎extensions/orchestrator/commands/speckit.orchestrator.discover.md‎

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
---
2+
description: "Discover agents and capabilities across linked repositories"
3+
---
4+
5+
# Discover Cross-Repository Agents
6+
7+
Scan linked repositories for agent definitions, skill files, and capability manifests. Builds a unified view of all available agents across your development ecosystem.
8+
9+
## User Input
10+
11+
```text
12+
$ARGUMENTS
13+
```
14+
15+
You **MUST** consider the user input before proceeding (if not empty). The user may provide a specific repo path or URL to scan.
16+
17+
## Prerequisites
18+
19+
1. Ensure Git is available (`git rev-parse --is-inside-work-tree`)
20+
2. Load orchestrator configuration from `.specify/extensions/orchestrator/orchestrator-config.yml`
21+
22+
## Step 1: Identify Repositories to Scan
23+
24+
Determine which repositories to scan:
25+
26+
### Option A: Current Repository
27+
28+
Always scan the current working directory.
29+
30+
### Option B: Linked Repositories
31+
32+
Check for linked repos in orchestrator config:
33+
34+
```yaml
35+
# orchestrator-config.yml
36+
linked_repos:
37+
- path: "../frontend-app"
38+
name: "Frontend"
39+
- path: "../backend-api"
40+
name: "Backend API"
41+
- path: "../shared-libs"
42+
name: "Shared Libraries"
43+
```
44+
45+
### Option C: Git Submodules
46+
47+
If the current repo has submodules, include them:
48+
49+
```bash
50+
if [ -f ".gitmodules" ]; then
51+
echo "📂 Found git submodules, including in scan..."
52+
git submodule foreach --quiet 'echo $toplevel/$path'
53+
fi
54+
```
55+
56+
## Step 2: Scan Each Repository
57+
58+
For each repository, search for agent-related files:
59+
60+
```bash
61+
echo "🔍 Scanning repository: $repo_name ($repo_path)"
62+
63+
# Scan for these patterns:
64+
scan_patterns=(
65+
".agent.md"
66+
"SKILL.md"
67+
"AGENTS.md"
68+
".claude/skills/*.md"
69+
".github/copilot-instructions.md"
70+
".specify/extensions/*/extension.yml"
71+
".specify/workflows/*/workflow.yml"
72+
".kimi/skills/*.md"
73+
)
74+
75+
for pattern in "${scan_patterns[@]}"; do
76+
find "$repo_path" -path "*/$pattern" -type f 2>/dev/null
77+
done
78+
```
79+
80+
## Step 3: Parse Discovered Files
81+
82+
For each discovered file, extract agent metadata:
83+
84+
### Agent Files (`.agent.md`, `SKILL.md`)
85+
86+
Extract:
87+
- **Name**: From the first `# Heading` in the file
88+
- **Description**: From the first paragraph or `description` frontmatter
89+
- **Triggers**: Keywords and phrases that indicate when this agent should be invoked
90+
- **Capabilities**: List of actions the agent can perform
91+
92+
### Extension Manifests (`extension.yml`)
93+
94+
Extract:
95+
- **Extension ID**: From `extension.id`
96+
- **Commands**: From `provides.commands[]`
97+
- **Tags**: From `tags[]`
98+
99+
### Workflow Definitions (`workflow.yml`)
100+
101+
Extract:
102+
- **Workflow ID**: From `workflow.id`
103+
- **Steps**: From `steps[]` — what the workflow can do
104+
- **Integrations**: Which AI agents it supports
105+
106+
## Step 4: Build Discovery Report
107+
108+
Generate a human-readable report and machine-readable JSON:
109+
110+
```bash
111+
echo ""
112+
echo "🌐 Cross-Repository Agent Discovery Report"
113+
echo "════════════════════════════════════════════"
114+
echo ""
115+
echo "📂 Repositories Scanned: 3"
116+
echo ""
117+
echo " Repository Agents Commands Workflows"
118+
echo " ────────────────── ────── ──────── ─────────"
119+
echo " Current (spec-kit) 2 13 1"
120+
echo " Frontend 1 0 0"
121+
echo " Backend API 1 3 0"
122+
echo ""
123+
echo "🤖 Discovered Agents:"
124+
echo ""
125+
echo " Agent Repo Type"
126+
echo " ─────────────────────── ───────────── ──────────"
127+
echo " Claude Code Agent Current .agent.md"
128+
echo " Copilot Instructions Current .github"
129+
echo " API Testing Agent Backend API SKILL.md"
130+
echo " UI Component Helper Frontend .agent.md"
131+
echo ""
132+
echo "💾 Full report saved to .specify/extensions/orchestrator/discovery-report.json"
133+
echo ""
134+
```
135+
136+
## Step 5: Update the Capability Index
137+
138+
Merge discovered agents into the main orchestrator index:
139+
140+
```bash
141+
echo "🔄 Updating capability index with discovered agents..."
142+
# Merge into .specify/extensions/orchestrator/index.json
143+
echo "✅ Index updated with cross-repo agents"
144+
```
145+
146+
## Notes
147+
148+
- Discovery scans local file system only — repos must be cloned
149+
- Files are parsed for metadata, not executed
150+
- Large monorepos may take longer to scan — use `scan_patterns` in config to narrow scope
151+
- Run periodically or after pulling changes in linked repos
152+
153+
## Examples
154+
155+
### Example 1: Scan current repo
156+
157+
```bash
158+
> /speckit.orchestrator.discover
159+
160+
🌐 Discovered 4 agents across 1 repository
161+
```
162+
163+
### Example 2: Scan specific repo
164+
165+
```bash
166+
> /speckit.orchestrator.discover ../backend-api
167+
168+
🌐 Discovered 2 agents in backend-api
169+
```
170+
171+
### Example 3: Scan all linked repos
172+
173+
```bash
174+
> /speckit.orchestrator.discover --all
175+
176+
🌐 Discovered 8 agents across 4 repositories
177+
```

0 commit comments

Comments
 (0)