Capability Discovery

Capability Discovery Skill

This skill enables dynamic discovery and mapping of installed plugins to abstract capability categories, allowing the workflow to route tasks to appropriate agents without hardcoding plugin names. It includes explicit delegation announcements so users understand routing decisions.

Core Principles

1. Technology Agnostic: Map capabilities, not specific plugins 2. Dynamic Discovery: Scan at runtime, not compile time 3. Graceful Fallback: Use internal default agents when no plugin matches 4. Project-Aware Routing: Prefer plugins matching detected project type 5. Transparent Delegation: Always announce why a particular agent was chosen

Capability Categories

Discovery Process

Step 1: Enumerate Installed Plugins

1. Locate Plugins/ directory
2. List all subdirectories (each is a plugin)
3. For each plugin:
   a. Read .claude-plugin/plugin.json for metadata
   b. Scan agents/*.md for agent definitions
   c. Scan commands/*.md for command definitions
4. Build plugin registry

Step 2: Extract Descriptions

For each agent/command file, extract the description from YAML frontmatter:

---
name: implementer
description: TDD implementation specialist for .NET. Use to write minimal code that makes tests pass.
model: opus
tools: [Read, Write, Edit, Bash, Grep, Glob]
---

Step 3: Map to Capabilities (Keyword Scoring)

Apply keyword matching to descriptions:

For each plugin agent/command:
  1. Tokenize description into words (lowercase)
  2. Match against capability keywords
  3. Calculate score:
     - Exact keyword match: +10 points
     - Partial match (word contains keyword): +3 points
     - Keyword in first sentence: +5 bonus
     - Multiple keywords from same category: +2 each after first
  4. Assign to highest-scoring capability
  5. Record match confidence (High: 25+, Medium: 15-24, Low: <15)

Step 4: Detect Project Type

Scan project root for technology indicators:

Step 5: Cache Results in FLOW.md

Store capability mappings in the Capabilities Cache section of FLOW.md.

Delegation Priority System

When routing a task to an agent, follow this priority order:

Priority 1: Project-Type Match

If project is detected (e.g., dotnet), prefer plugins with matching technology keywords in their description.

Detected: dotnet project
Capability needed: tdd-implementation

Matches:
- dotnet-tdd:implementer (description: "TDD for .NET") → Score: 35 + project bonus
- node-tdd:implementer (description: "TDD for Node.js") → Score: 30

Winner: dotnet-tdd:implementer (project type match)

Priority 2: Exact Keyword Match

Prefer agents with exact keyword matches over partial matches.

Priority 3: Agent Over Command

When both an agent and a command match a capability, prefer the agent (more capable).

Priority 4: Internal Default

When no plugin matches the capability, use the appropriate default agent.

Delegation Announcement Pattern

CRITICAL: Always announce delegation decisions to the user with reasoning.

When Plugin Found

**Delegating [capability]** → [plugin-name]:[agent-name]

Matched via keyword scoring:
- Keywords: [matched keywords]
- Score: [score] (High confidence)
- Project type: [type] (matched)

Spawning agent...

When Using Default

**Using built-in agent** for [capability] → flow-workflow:defaults/[agent]

No installed plugin matched this capability.
- Searched: [N] plugins
- Keywords tried: [keywords]

Consider installing: [suggested plugin type]

Quick Delegation (For Status/Logs)

→ [capability]: [plugin:agent] (keyword match)
→ [capability]: defaults/[agent] (no plugin match)

Routing Logic

When Phase Needs Capability

1. Determine capability needed for current task
2. Look up FLOW.md capability cache
3. If cache stale (>24h) or missing, re-scan plugins
4. If multiple matches for capability:
   a. Filter by project type preference
   b. Prefer exact keyword matches
   c. Prefer agents over commands
5. If single match:
   a. Announce delegation with reasoning
   b. Return agent reference
6. If no match:
   a. Announce using default
   b. Return default agent reference

Capability → Phase Mapping

Default Agents

When no plugin matches a capability:

Re-Discovery Triggers

Re-scan plugins when:

1. /flow-workflow:start is run on uninitialized project 2. FLOW.md capability cache is older than 24 hours 3. Requested capability returns no match (try fresh scan) 4. User explicitly requests refresh via /flow-workflow:status --refresh

Capability Gap Logging

When no plugin matches a capability, log in FLOW.md:

## Capability Warnings

**[TIMESTAMP]**: No plugin found for capability 'infrastructure'
- Searched: 5 plugins
- Keywords tried: infra, devops, pipeline, deploy
- Using: flow-workflow:defaults/executor
- Suggestion: Consider installing a DevOps plugin

Integration Points

• State Management: Cache capability map in FLOW.md
• Coordinator Agent: Performs discovery on initialization, uses for routing
• Smart Continuation: Uses cached capabilities for agent selection

See categories.md for detailed capability category definitions.

Capability Category Definitions

Overview

Capability categories provide an abstraction layer between workflow phases and specific plugin implementations. This enables technology-agnostic orchestration with transparent delegation.

Category Definitions

requirements-gathering

Purpose: Structured elicitation of project requirements from stakeholders

When Used: DISCUSS phase, when understanding what to build

Keywords: requirements, interview, elicitation, stakeholder, gathering, discover, needs

Expected Behaviors:

• Conduct structured interviews
• Ask clarifying questions
• Document functional requirements
• Document non-functional requirements
• Identify constraints and assumptions

Default Agent: flow-workflow:defaults/interviewer

---

codebase-analysis

Purpose: Understanding existing code, patterns, and architecture

When Used: DISCUSS phase (for brownfield projects), PLAN phase (for implementation planning)

Keywords: codebase, analyze, reverse-engineer, patterns, architecture, existing, legacy

Expected Behaviors:

• Scan project structure
• Identify design patterns
• Detect technologies in use
• Find integration points
• Document existing behavior

Default Agent: flow-workflow:defaults/researcher

---

brainstorming

Purpose: Creative exploration of ideas and options

When Used: DISCUSS phase, when exploring possible approaches

Keywords: brainstorm, ideation, workshop, creative, explore, options, ideas

Expected Behaviors:

• Facilitate idea generation
• Divergent thinking exercises
• Option comparison
• Trade-off analysis
• Convergent selection

Default Agent: flow-workflow:defaults/interviewer (with brainstorming prompts)

---

tdd-implementation

Purpose: Test-driven development with RED-GREEN-REFACTOR cycle

When Used: EXECUTE phase, when implementing with tests first

Keywords: tdd, test-driven, red-green, refactor, tests first, failing test

Expected Behaviors:

• Write failing tests first (RED)
• Implement minimal code to pass (GREEN)
• Refactor for quality (REFACTOR)
• Maintain test coverage
• Follow clean code principles

Default Agent: flow-workflow:defaults/executor (with TDD guidance)

---

code-implementation

Purpose: General code writing and modification

When Used: EXECUTE phase, for any coding task

Keywords: implement, developer, code, write, create, build, feature

Expected Behaviors:

• Write production code
• Follow project conventions
• Handle errors appropriately
• Integrate with existing code
• Document as needed

Default Agent: flow-workflow:defaults/executor

---

infrastructure

Purpose: DevOps, CI/CD, and infrastructure tasks

When Used: EXECUTE phase, for deployment and operations

Keywords: infra, devops, pipeline, deploy, docker, kubernetes, ci, cd, terraform, azure

Expected Behaviors:

• Configure build pipelines
• Write deployment scripts
• Manage infrastructure as code
• Set up environments
• Configure monitoring

Default Agent: flow-workflow:defaults/executor (with infrastructure guidance)

---

code-review

Purpose: Quality validation of implemented code

When Used: VERIFY phase, after implementation

Keywords: review, quality, clean code, solid, dry, kiss, standards

Expected Behaviors:

• Review code for quality
• Check adherence to standards
• Identify potential issues
• Suggest improvements
• Validate best practices

Default Agent: flow-workflow:validator

---

requirements-validation

Purpose: Verify implementation meets requirements

When Used: VERIFY phase, for acceptance testing

Keywords: validate, verification, compliance, acceptance, requirements, uat

Expected Behaviors:

• Check requirements coverage
• Validate acceptance criteria
• Identify gaps
• Conduct UAT
• Document compliance

Default Agent: flow-workflow:validator

---

Keyword Matching Algorithm

Scoring Rules

1. Exact keyword match: +10 points
2. Partial match (word contains keyword): +3 points
3. Keyword in first sentence: +5 bonus
4. Multiple keywords from same category: +2 each after first
5. Project type match: +10 bonus

Confidence Levels

Matching Example

Description: "TDD implementation specialist for .NET. Write minimal code that makes tests pass."

Keyword matches:
- "TDD" → tdd-implementation (+10)
- "implementation" → code-implementation (+10)
- "tests" → tdd-implementation (+10)
- ".NET" → (project type indicator)

Scores:
- tdd-implementation: 20 + 5 (first sentence) = 25 (High)
- code-implementation: 10 (Low)

Winner: tdd-implementation

---

Project Type Routing

When Multiple Capabilities Match

If multiple plugins match a capability, filter by project type:

Capability: tdd-implementation
Matches:
- dotnet-tdd:implementer (description contains ".NET")
- node-tdd:implementer (description contains "Node.js")

Detected project type: dotnet

Selected: dotnet-tdd:implementer (+10 project bonus)

Project Type Keywords

---

Default Agent Summary

---

Capability Gap Handling

When No Plugin Matches

1. Log warning to FLOW.md with timestamp 2. Announce to user: "Using built-in agent (no plugin matched)" 3. Use appropriate default agent 4. Suggest plugin installation if capability is important

Suggested Plugins by Capability

---

Delegation Announcement Templates

Plugin Match

**Delegating requirements-gathering** → business-analyst:stakeholder-interviewer

Matched via keyword scoring:
- Keywords: requirements, interview, stakeholder
- Score: 30 (High confidence)
- Project type: dotnet (neutral)

Default Agent

**Using built-in agent** for infrastructure → flow-workflow:defaults/executor

No installed plugin matched this capability.
- Searched: 5 plugins
- Keywords tried: infra, devops, pipeline, deploy

Consider installing: devops-azure-infrastructure or similar

Short Form (For Logs)

→ requirements-gathering: business-analyst:stakeholder-interviewer (keyword match)
→ infrastructure: defaults/executor (no plugin match)