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

[pragya247]

Description

Adds a new Spec Kit extension — Intelligent Agent Orchestrator — that provides cross-catalog agent discovery
and intelligent prompt-to-command routing.

Problem

Spec Kit has robust discovery (extension/preset/workflow catalogs) and dispatch (workflow engine with 10 step
types), but no intelligent matching layer that connects a user's natural-language intent to the right command.
Users need to already know what exists and where it lives.

Solution

Three new extension commands that implement a discover → index → match → route pipeline:

Command	What it does
speckit.orchestrator.index	Aggregates capabilities from core commands, installed extensions, workflows, and
presets into a unified JSON index
speckit.orchestrator.route	Scores a user prompt against the index using keyword + description matching,
returns ranked results
speckit.orchestrator.discover	Scans linked repositories for agent files (.agent.md, SKILL.md,
extension.yml, etc.) and merges into the index

Design Decisions

• Zero core changes — self-contained extension following existing patterns
• Deterministic matching — keyword-based scoring, no external AI API calls needed
• after_init hook — auto-indexes capabilities on project initialization
• Cross-repo scanning — configurable via linked_repos in orchestrator-config.yml
• Designed as Phase 1 toward a potential native route workflow step type (per discussion in Workflow Engine with Catalog System #2142)

Files

extensions/orchestrator/ ├── extension.yml # Manifest ├── README.md # Usage docs ├── config-template.yml # Matching
strategy & scan settings └── commands/ ├── speckit.orchestrator.route.md # Prompt → command matching ├──
speckit.orchestrator.index.md # Capability indexer └── speckit.orchestrator.discover.md # Cross-repo agent scanner

Ref: #2142

Testing

• Reviewed extension manifest against extensions/template/extension.yml and extensions/git/extension.yml
  for structural correctness
• Verified command naming follows speckit.{extension-id}.{command-name} pattern
• Validated extension.yml schema fields (schema_version, requires, provides, hooks, tags)
• Tested locally with uv run specify --help
• Ran existing tests with uv sync && uv run pytest
• Tested with a sample project (if applicable)

Note: This is an extension scaffold (command markdown + manifest). Runtime behavior depends on AI agent
interpretation of the command files. Integration testing would require installing the extension via specify extension add orchestrator and invoking commands through a configured agent.

AI Disclosure

• I did use AI assistance (describe below)

GitHub Copilot CLI (Claude) was used to:

• Explore the spec-kit codebase to understand extension architecture, catalog system, and workflow engine
• Scaffold the extension files (extension.yml, command markdown files, config template, README)
• Draft the PR description

All design decisions (routing algorithm, phased approach, integration points) were authored by me based on my
existing Agent Orchestrator implementations (Agency plugin + VS Code extension). I reviewed and understand all
generated content.

[Copilot]

Pull request overview

Adds a new built-in Spec Kit extension (“Intelligent Agent Orchestrator”) that scaffolds a discover → index → match → route workflow via extension manifest, config template, and command markdown instructions.

Changes:

• Introduces the orchestrator extension manifest with commands + hook + default config.
• Adds a config template for routing/discovery behavior.
• Adds three new command markdown files (index, route, discover) plus extension README documentation.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
extensions/orchestrator/extension.yml	Defines the extension (commands, config template, hooks, tags, defaults).
extensions/orchestrator/config-template.yml	Provides user-editable routing + discovery configuration template.
extensions/orchestrator/commands/speckit.orchestrator.route.md	Documents prompt-to-command routing behavior and expected output.
extensions/orchestrator/commands/speckit.orchestrator.index.md	Documents building a unified capability index across sources.
extensions/orchestrator/commands/speckit.orchestrator.discover.md	Documents cross-repo scanning for agent/capability sources.
extensions/orchestrator/README.md	User-facing overview, install steps, configuration, and roadmap.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Adds a new orchestrator Spec Kit extension scaffold intended to provide cross-catalog capability indexing, prompt-to-command routing, and cross-repo agent discovery via new extension commands.

Changes:

• Adds extensions/orchestrator/extension.yml manifest with three new speckit.orchestrator.* commands and a proposed init-time hook.
• Adds orchestrator configuration template (config-template.yml) and user-facing docs (README.md).
• Adds three command instruction markdown files implementing the discover → index → route workflow as agent-executable specs.

Show a summary per file

File	Description
extensions/orchestrator/extension.yml	Declares the new extension, its commands, config file, hook, tags, and default settings.
extensions/orchestrator/config-template.yml	Provides a user-editable config template for routing strategy and cross-repo scanning settings.
extensions/orchestrator/commands/speckit.orchestrator.route.md	Defines the agent instructions for scoring and routing user prompts to commands/workflows.
extensions/orchestrator/commands/speckit.orchestrator.index.md	Defines the agent instructions for building a unified JSON capability index.
extensions/orchestrator/commands/speckit.orchestrator.discover.md	Defines the agent instructions for scanning linked repos/submodules for agent/capability files.
extensions/orchestrator/README.md	Documents the extension’s purpose, usage, commands, and configuration.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comments suppressed due to low confidence (2)

extensions/orchestrator/extension.yml:61

• The manifest schema/documentation uses a top-level defaults: key for default configuration values, not config: { defaults: ... }. As written, these defaults are likely to be ignored/misread by tooling and are inconsistent with extensions/template/extension.yml and extensions/EXTENSION-API-REFERENCE.md. Move these values under a top-level defaults: key.

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"

extensions/orchestrator/commands/speckit.orchestrator.route.md:71

• This command describes a fixed weighted scoring algorithm, but the extension config exposes matching_strategy: "keyword" | "weighted". As written, the config setting has no effect and the docs are internally inconsistent. Update the routing steps so keyword uses only keyword matching (or document that weights are always applied) and ensure the implementation reads matching_strategy.

## 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

• Files reviewed: 6/6 changed files
• Comments generated: 3

[mnriem]

Please create it as a community extension as per https://github.com/github/spec-kit/tree/main/extensions

[Copilot]

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 2/2 changed files
• Comments generated: 1

[Copilot]

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 2/2 changed files
• Comments generated: 0 new

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

Comments suppressed due to low confidence (1)

extensions/catalog.community.json:1435

• This catalog already contains an extension with key/id orchestrator (the existing “Spec Orchestrator” entry). The diff appears to embed that existing entry inside the new one, and even if the JSON were fixed, you can’t publish two extensions with the same catalog key/id. Pick a new unique extension id/key for “Intelligent Agent Orchestrator” (and update README/catalog accordingly), or update the existing entry rather than adding a second one.

    "orchestrator": {
      "name": "Intelligent Agent Orchestrator",
      "id": "orchestrator",
      "description": "Cross-catalog agent discovery and intelligent prompt-to-command routing",
      "author": "pragya247",
      "version": "0.1.0",
      "download_url": "https://github.com/pragya247/spec-kit-orchestrator/archive/refs/tags/v0.1.0.zip",
      "repository": "https://github.com/pragya247/spec-kit-orchestrator",
      "homepage": "https://github.com/pragya247/spec-kit-orchestrator",
      "documentation": "https://github.com/pragya247/spec-kit-orchestrator/blob/main/README.md",
      "changelog": "https://github.com/pragya247/spec-kit-orchestrator/blob/main/CHANGELOG.md",
      "license": "MIT",
      "requires": {
        "speckit_version": ">=0.6.1"
      },
      "provides": {
        "commands": 3,
        "hooks": 1
      },
      "tags": [
        "orchestrator",
        "routing",
        "discovery",
        "agent",
        "ai"
      "name": "Spec Orchestrator",
      "id": "orchestrator",
      "description": "Cross-feature orchestration — track state, select tasks, and detect conflicts across parallel specs.",
      "author": "Quratulain-bilal",

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Top-level updated_at string is missing its closing quote, which makes extensions/catalog.community.json invalid JSON and will break catalog parsing. Fix by restoring a valid ISO 8601 string (including the closing ") and ensuring the line ends with a comma.

Suggested change

	"updated_at": "2026-04-28T12:00:00Z,
	"updated_at": "2026-04-28T12:00:00Z",

[Copilot]

The new orchestrator entry is syntactically malformed: the tags array is not closed and there are missing commas/closing braces, causing the JSON to be invalid. Close the tags array (]), add the trailing comma if more fields follow, and ensure the extension object is properly terminated before the next catalog entry.

[Copilot]

The new extension metadata block stops after tags and does not include the standard catalog fields used throughout this file (e.g., verified, downloads, stars, created_at, updated_at). The publishing guide’s example and schema include these fields, so add them for this new entry (with appropriate initial values) once the JSON structure is corrected.

[Copilot]

PR description lists new files under extensions/orchestrator/ being added in this repository, but the changes in this PR appear to only update the community catalog + root README (there is no extensions/orchestrator/ directory in the repo after these changes). Please either add the described extension files, or update the PR description to reflect that this PR is only publishing an external extension via the catalog.

[mnriem]

Please address Copilot feedback. So cool to see this extension!