mirror of
https://github.com/github/awesome-copilot.git
synced 2026-02-22 19:35:13 +00:00
Merge branch 'main' into add-rug-swe-qa-agents-collection
This commit is contained in:
Ivan Charapanau
72
.github/plugin/marketplace.json
vendored
72
.github/plugin/marketplace.json
vendored
@@ -19,7 +19,7 @@
|
|||||||
{
|
{
|
||||||
"name": "azure-cloud-development",
|
"name": "azure-cloud-development",
|
||||||
"source": "./plugins/azure-cloud-development",
|
"source": "./plugins/azure-cloud-development",
|
||||||
"description": "Azure cloud development tools including Infrastructure as Code, architecture patterns, and cost optimization.",
|
"description": "Comprehensive Azure cloud development tools including Infrastructure as Code, serverless functions, architecture patterns, and cost optimization for building scalable cloud applications.",
|
||||||
"version": "1.0.0"
|
"version": "1.0.0"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
@@ -34,10 +34,16 @@
|
|||||||
"description": "Tools for REPL-first Clojure workflows featuring Clojure instructions, the interactive programming chat mode and supporting guidance.",
|
"description": "Tools for REPL-first Clojure workflows featuring Clojure instructions, the interactive programming chat mode and supporting guidance.",
|
||||||
"version": "1.0.0"
|
"version": "1.0.0"
|
||||||
},
|
},
|
||||||
|
{
|
||||||
|
"name": "context-engineering",
|
||||||
|
"source": "./plugins/context-engineering",
|
||||||
|
"description": "Tools and techniques for maximizing GitHub Copilot effectiveness through better context management. Includes guidelines for structuring code, an agent for planning multi-file changes, and prompts for context-aware development.",
|
||||||
|
"version": "1.0.0"
|
||||||
|
},
|
||||||
{
|
{
|
||||||
"name": "copilot-sdk",
|
"name": "copilot-sdk",
|
||||||
"source": "./plugins/copilot-sdk",
|
"source": "./plugins/copilot-sdk",
|
||||||
"description": "Build applications with the GitHub Copilot SDK across multiple programming languages. Includes comprehensive instructions for C#, Go, Node.js/TypeScript, and Python.",
|
"description": "Build applications with the GitHub Copilot SDK across multiple programming languages. Includes comprehensive instructions for C#, Go, Node.js/TypeScript, and Python to help you create AI-powered applications.",
|
||||||
"version": "1.0.0"
|
"version": "1.0.0"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
@@ -49,7 +55,7 @@
|
|||||||
{
|
{
|
||||||
"name": "csharp-mcp-development",
|
"name": "csharp-mcp-development",
|
||||||
"source": "./plugins/csharp-mcp-development",
|
"source": "./plugins/csharp-mcp-development",
|
||||||
"description": "Complete toolkit for building Model Context Protocol (MCP) servers in C# using the official SDK.",
|
"description": "Complete toolkit for building Model Context Protocol (MCP) servers in C# using the official SDK. Includes instructions for best practices, a prompt for generating servers, and an expert chat mode for guidance.",
|
||||||
"version": "1.0.0"
|
"version": "1.0.0"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
@@ -61,7 +67,7 @@
|
|||||||
{
|
{
|
||||||
"name": "dataverse-sdk-for-python",
|
"name": "dataverse-sdk-for-python",
|
||||||
"source": "./plugins/dataverse-sdk-for-python",
|
"source": "./plugins/dataverse-sdk-for-python",
|
||||||
"description": "Comprehensive collection for building production-ready Python integrations with Microsoft Dataverse.",
|
"description": "Comprehensive collection for building production-ready Python integrations with Microsoft Dataverse. Includes official documentation, best practices, advanced features, file operations, and code generation prompts.",
|
||||||
"version": "1.0.0"
|
"version": "1.0.0"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
@@ -82,10 +88,16 @@
|
|||||||
"description": "Essential prompts, instructions, and chat modes for modern frontend web development including React, Angular, Vue, TypeScript, and CSS frameworks.",
|
"description": "Essential prompts, instructions, and chat modes for modern frontend web development including React, Angular, Vue, TypeScript, and CSS frameworks.",
|
||||||
"version": "1.0.0"
|
"version": "1.0.0"
|
||||||
},
|
},
|
||||||
|
{
|
||||||
|
"name": "gem-team",
|
||||||
|
"source": "./plugins/gem-team",
|
||||||
|
"description": "A modular multi-agent team for complex project execution with DAG-based planning, parallel execution, TDD verification, and automated testing.",
|
||||||
|
"version": "1.0.0"
|
||||||
|
},
|
||||||
{
|
{
|
||||||
"name": "go-mcp-development",
|
"name": "go-mcp-development",
|
||||||
"source": "./plugins/go-mcp-development",
|
"source": "./plugins/go-mcp-development",
|
||||||
"description": "Complete toolkit for building Model Context Protocol (MCP) servers in Go using the official github.com/modelcontextprotocol/go-sdk.",
|
"description": "Complete toolkit for building Model Context Protocol (MCP) servers in Go using the official github.com/modelcontextprotocol/go-sdk. Includes instructions for best practices, a prompt for generating servers, and an expert chat mode for guidance.",
|
||||||
"version": "1.0.0"
|
"version": "1.0.0"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
@@ -103,91 +115,97 @@
|
|||||||
{
|
{
|
||||||
"name": "kotlin-mcp-development",
|
"name": "kotlin-mcp-development",
|
||||||
"source": "./plugins/kotlin-mcp-development",
|
"source": "./plugins/kotlin-mcp-development",
|
||||||
"description": "Complete toolkit for building Model Context Protocol (MCP) servers in Kotlin using the official io.modelcontextprotocol:kotlin-sdk library.",
|
"description": "Complete toolkit for building Model Context Protocol (MCP) servers in Kotlin using the official io.modelcontextprotocol:kotlin-sdk library. Includes instructions for best practices, a prompt for generating servers, and an expert chat mode for guidance.",
|
||||||
"version": "1.0.0"
|
"version": "1.0.0"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"name": "mcp-m365-copilot",
|
"name": "mcp-m365-copilot",
|
||||||
"source": "./plugins/mcp-m365-copilot",
|
"source": "./plugins/mcp-m365-copilot",
|
||||||
"description": "Comprehensive collection for building declarative agents with Model Context Protocol integration for Microsoft 365 Copilot.",
|
"description": "Comprehensive collection for building declarative agents with Model Context Protocol integration for Microsoft 365 Copilot",
|
||||||
"version": "1.0.0"
|
"version": "1.0.0"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"name": "openapi-to-application-csharp-dotnet",
|
"name": "openapi-to-application-csharp-dotnet",
|
||||||
"source": "./plugins/openapi-to-application-csharp-dotnet",
|
"source": "./plugins/openapi-to-application-csharp-dotnet",
|
||||||
"description": "Generate production-ready .NET applications from OpenAPI specifications. Includes ASP.NET Core project scaffolding, controller generation, and entity framework integration.",
|
"description": "Generate production-ready .NET applications from OpenAPI specifications. Includes ASP.NET Core project scaffolding, controller generation, entity framework integration, and C# best practices.",
|
||||||
"version": "1.0.0"
|
"version": "1.0.0"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"name": "openapi-to-application-go",
|
"name": "openapi-to-application-go",
|
||||||
"source": "./plugins/openapi-to-application-go",
|
"source": "./plugins/openapi-to-application-go",
|
||||||
"description": "Generate production-ready Go applications from OpenAPI specifications. Includes project scaffolding, handler generation, middleware setup, and Go best practices.",
|
"description": "Generate production-ready Go applications from OpenAPI specifications. Includes project scaffolding, handler generation, middleware setup, and Go best practices for REST APIs.",
|
||||||
"version": "1.0.0"
|
"version": "1.0.0"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"name": "openapi-to-application-java-spring-boot",
|
"name": "openapi-to-application-java-spring-boot",
|
||||||
"source": "./plugins/openapi-to-application-java-spring-boot",
|
"source": "./plugins/openapi-to-application-java-spring-boot",
|
||||||
"description": "Generate production-ready Spring Boot applications from OpenAPI specifications. Includes project scaffolding, REST controller generation, and service layer organization.",
|
"description": "Generate production-ready Spring Boot applications from OpenAPI specifications. Includes project scaffolding, REST controller generation, service layer organization, and Spring Boot best practices.",
|
||||||
"version": "1.0.0"
|
"version": "1.0.0"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"name": "openapi-to-application-nodejs-nestjs",
|
"name": "openapi-to-application-nodejs-nestjs",
|
||||||
"source": "./plugins/openapi-to-application-nodejs-nestjs",
|
"source": "./plugins/openapi-to-application-nodejs-nestjs",
|
||||||
"description": "Generate production-ready NestJS applications from OpenAPI specifications. Includes project scaffolding, controller and service generation, and TypeScript best practices.",
|
"description": "Generate production-ready NestJS applications from OpenAPI specifications. Includes project scaffolding, controller and service generation, TypeScript best practices, and enterprise patterns.",
|
||||||
"version": "1.0.0"
|
"version": "1.0.0"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"name": "openapi-to-application-python-fastapi",
|
"name": "openapi-to-application-python-fastapi",
|
||||||
"source": "./plugins/openapi-to-application-python-fastapi",
|
"source": "./plugins/openapi-to-application-python-fastapi",
|
||||||
"description": "Generate production-ready FastAPI applications from OpenAPI specifications. Includes project scaffolding, route generation, and dependency injection.",
|
"description": "Generate production-ready FastAPI applications from OpenAPI specifications. Includes project scaffolding, route generation, dependency injection, and Python best practices for async APIs.",
|
||||||
|
"version": "1.0.0"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "ospo-sponsorship",
|
||||||
|
"source": "./plugins/ospo-sponsorship",
|
||||||
|
"description": "Tools and resources for Open Source Program Offices (OSPOs) to identify, evaluate, and manage sponsorship of open source dependencies through GitHub Sponsors, Open Collective, and other funding platforms.",
|
||||||
"version": "1.0.0"
|
"version": "1.0.0"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"name": "partners",
|
"name": "partners",
|
||||||
"source": "./plugins/partners",
|
"source": "./plugins/partners",
|
||||||
"description": "Custom agents that have been created by GitHub partners.",
|
"description": "Custom agents that have been created by GitHub partners",
|
||||||
"version": "1.0.0"
|
"version": "1.0.0"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"name": "pcf-development",
|
"name": "pcf-development",
|
||||||
"source": "./plugins/pcf-development",
|
"source": "./plugins/pcf-development",
|
||||||
"description": "Complete toolkit for developing custom code components using Power Apps Component Framework for model-driven and canvas apps.",
|
"description": "Complete toolkit for developing custom code components using Power Apps Component Framework for model-driven and canvas apps",
|
||||||
"version": "1.0.0"
|
"version": "1.0.0"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"name": "php-mcp-development",
|
"name": "php-mcp-development",
|
||||||
"source": "./plugins/php-mcp-development",
|
"source": "./plugins/php-mcp-development",
|
||||||
"description": "Comprehensive resources for building Model Context Protocol servers using the official PHP SDK with attribute-based discovery.",
|
"description": "Comprehensive resources for building Model Context Protocol servers using the official PHP SDK with attribute-based discovery, including best practices, project generation, and expert assistance",
|
||||||
"version": "1.0.0"
|
"version": "1.0.0"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"name": "power-apps-code-apps",
|
"name": "power-apps-code-apps",
|
||||||
"source": "./plugins/power-apps-code-apps",
|
"source": "./plugins/power-apps-code-apps",
|
||||||
"description": "Complete toolkit for Power Apps Code Apps development including project scaffolding, development standards, and expert guidance.",
|
"description": "Complete toolkit for Power Apps Code Apps development including project scaffolding, development standards, and expert guidance for building code-first applications with Power Platform integration.",
|
||||||
"version": "1.0.0"
|
"version": "1.0.0"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"name": "power-bi-development",
|
"name": "power-bi-development",
|
||||||
"source": "./plugins/power-bi-development",
|
"source": "./plugins/power-bi-development",
|
||||||
"description": "Comprehensive Power BI development resources including data modeling, DAX optimization, performance tuning, and visualization design.",
|
"description": "Comprehensive Power BI development resources including data modeling, DAX optimization, performance tuning, visualization design, security best practices, and DevOps/ALM guidance for building enterprise-grade Power BI solutions.",
|
||||||
"version": "1.0.0"
|
"version": "1.0.0"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"name": "power-platform-mcp-connector-development",
|
"name": "power-platform-mcp-connector-development",
|
||||||
"source": "./plugins/power-platform-mcp-connector-development",
|
"source": "./plugins/power-platform-mcp-connector-development",
|
||||||
"description": "Complete toolkit for developing Power Platform custom connectors with Model Context Protocol integration for Microsoft Copilot Studio.",
|
"description": "Complete toolkit for developing Power Platform custom connectors with Model Context Protocol integration for Microsoft Copilot Studio",
|
||||||
"version": "1.0.0"
|
"version": "1.0.0"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"name": "project-planning",
|
"name": "project-planning",
|
||||||
"source": "./plugins/project-planning",
|
"source": "./plugins/project-planning",
|
||||||
"description": "Tools and guidance for software project planning, feature breakdown, epic management, implementation planning, and task organization.",
|
"description": "Tools and guidance for software project planning, feature breakdown, epic management, implementation planning, and task organization for development teams.",
|
||||||
"version": "1.0.0"
|
"version": "1.0.0"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"name": "python-mcp-development",
|
"name": "python-mcp-development",
|
||||||
"source": "./plugins/python-mcp-development",
|
"source": "./plugins/python-mcp-development",
|
||||||
"description": "Complete toolkit for building Model Context Protocol (MCP) servers in Python using the official SDK with FastMCP.",
|
"description": "Complete toolkit for building Model Context Protocol (MCP) servers in Python using the official SDK with FastMCP. Includes instructions for best practices, a prompt for generating servers, and an expert chat mode for guidance.",
|
||||||
"version": "1.0.0"
|
"version": "1.0.0"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
@@ -199,13 +217,13 @@
|
|||||||
{
|
{
|
||||||
"name": "rust-mcp-development",
|
"name": "rust-mcp-development",
|
||||||
"source": "./plugins/rust-mcp-development",
|
"source": "./plugins/rust-mcp-development",
|
||||||
"description": "Build high-performance Model Context Protocol servers in Rust using the official rmcp SDK with async/await and procedural macros.",
|
"description": "Build high-performance Model Context Protocol servers in Rust using the official rmcp SDK with async/await, procedural macros, and type-safe implementations.",
|
||||||
"version": "1.0.0"
|
"version": "1.0.0"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"name": "security-best-practices",
|
"name": "security-best-practices",
|
||||||
"source": "./plugins/security-best-practices",
|
"source": "./plugins/security-best-practices",
|
||||||
"description": "Security frameworks, accessibility guidelines, performance optimization, and code quality best practices.",
|
"description": "Security frameworks, accessibility guidelines, performance optimization, and code quality best practices for building secure, maintainable, and high-performance applications.",
|
||||||
"version": "1.0.0"
|
"version": "1.0.0"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
@@ -217,7 +235,7 @@
|
|||||||
{
|
{
|
||||||
"name": "structured-autonomy",
|
"name": "structured-autonomy",
|
||||||
"source": "./plugins/structured-autonomy",
|
"source": "./plugins/structured-autonomy",
|
||||||
"description": "Premium planning, thrifty implementation.",
|
"description": "Premium planning, thrifty implementation",
|
||||||
"version": "1.0.0"
|
"version": "1.0.0"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
@@ -229,25 +247,25 @@
|
|||||||
{
|
{
|
||||||
"name": "technical-spike",
|
"name": "technical-spike",
|
||||||
"source": "./plugins/technical-spike",
|
"source": "./plugins/technical-spike",
|
||||||
"description": "Tools for creation, management and research of technical spikes to reduce unknowns and assumptions before specification and implementation.",
|
"description": "Tools for creation, management and research of technical spikes to reduce unknowns and assumptions before proceeding to specification and implementation of solutions.",
|
||||||
"version": "1.0.0"
|
"version": "1.0.0"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"name": "testing-automation",
|
"name": "testing-automation",
|
||||||
"source": "./plugins/testing-automation",
|
"source": "./plugins/testing-automation",
|
||||||
"description": "Comprehensive collection for writing tests, test automation, and TDD including unit tests, integration tests, and end-to-end testing.",
|
"description": "Comprehensive collection for writing tests, test automation, and test-driven development including unit tests, integration tests, and end-to-end testing strategies.",
|
||||||
"version": "1.0.0"
|
"version": "1.0.0"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"name": "typescript-mcp-development",
|
"name": "typescript-mcp-development",
|
||||||
"source": "./plugins/typescript-mcp-development",
|
"source": "./plugins/typescript-mcp-development",
|
||||||
"description": "Complete toolkit for building Model Context Protocol (MCP) servers in TypeScript/Node.js using the official SDK.",
|
"description": "Complete toolkit for building Model Context Protocol (MCP) servers in TypeScript/Node.js using the official SDK. Includes instructions for best practices, a prompt for generating servers, and an expert chat mode for guidance.",
|
||||||
"version": "1.0.0"
|
"version": "1.0.0"
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"name": "typespec-m365-copilot",
|
"name": "typespec-m365-copilot",
|
||||||
"source": "./plugins/typespec-m365-copilot",
|
"source": "./plugins/typespec-m365-copilot",
|
||||||
"description": "Comprehensive collection of prompts, instructions, and resources for building declarative agents and API plugins using TypeSpec for Microsoft 365 Copilot.",
|
"description": "Comprehensive collection of prompts, instructions, and resources for building declarative agents and API plugins using TypeSpec for Microsoft 365 Copilot extensibility.",
|
||||||
"version": "1.0.0"
|
"version": "1.0.0"
|
||||||
}
|
}
|
||||||
]
|
]
|
||||||
|
|||||||
1
.github/workflows/validate-readme.yml
vendored
1
.github/workflows/validate-readme.yml
vendored
@@ -8,6 +8,7 @@ on:
|
|||||||
- "prompts/**"
|
- "prompts/**"
|
||||||
- "agents/**"
|
- "agents/**"
|
||||||
- "collections/**"
|
- "collections/**"
|
||||||
|
- "plugins/**"
|
||||||
- "*.js"
|
- "*.js"
|
||||||
- "README.md"
|
- "README.md"
|
||||||
- "docs/**"
|
- "docs/**"
|
||||||
|
|||||||
33
AGENTS.md
33
AGENTS.md
@@ -32,9 +32,12 @@ The Awesome GitHub Copilot repository is a community-driven collection of custom
|
|||||||
# Install dependencies
|
# Install dependencies
|
||||||
npm ci
|
npm ci
|
||||||
|
|
||||||
# Build the project (generates README.md)
|
# Build the project (generates README.md and marketplace.json)
|
||||||
npm run build
|
npm run build
|
||||||
|
|
||||||
|
# Generate marketplace.json only
|
||||||
|
npm run plugin:generate-marketplace
|
||||||
|
|
||||||
# Validate collection manifests
|
# Validate collection manifests
|
||||||
npm run collection:validate
|
npm run collection:validate
|
||||||
|
|
||||||
@@ -93,9 +96,18 @@ All agent files (`*.agent.md`), prompt files (`*.prompt.md`), and instruction fi
|
|||||||
- Follow the [GitHub Copilot hooks specification](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/use-hooks)
|
- Follow the [GitHub Copilot hooks specification](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/use-hooks)
|
||||||
- Optionally includes `tags` field for categorization
|
- Optionally includes `tags` field for categorization
|
||||||
|
|
||||||
|
#### Plugin Folders (plugins/*)
|
||||||
|
- Each plugin is a folder containing a `.github/plugin/plugin.json` file with metadata
|
||||||
|
- plugin.json must have `name` field (matching the folder name)
|
||||||
|
- plugin.json must have `description` field (describing the plugin's purpose)
|
||||||
|
- plugin.json must have `version` field (semantic version, e.g., "1.0.0")
|
||||||
|
- Plugin folders can contain any combination of agents, prompts, instructions, skills, and hooks
|
||||||
|
- The `marketplace.json` file is automatically generated from all plugins during build
|
||||||
|
- Plugins are discoverable and installable via GitHub Copilot CLI
|
||||||
|
|
||||||
### Adding New Resources
|
### Adding New Resources
|
||||||
|
|
||||||
When adding a new agent, prompt, instruction, skill, or hook:
|
When adding a new agent, prompt, instruction, skill, hook, or plugin:
|
||||||
|
|
||||||
**For Agents, Prompts, and Instructions:**
|
**For Agents, Prompts, and Instructions:**
|
||||||
1. Create the file with proper front matter
|
1. Create the file with proper front matter
|
||||||
@@ -121,6 +133,14 @@ When adding a new agent, prompt, instruction, skill, or hook:
|
|||||||
5. Update the README.md by running: `npm run build`
|
5. Update the README.md by running: `npm run build`
|
||||||
6. Verify the skill appears in the generated README
|
6. Verify the skill appears in the generated README
|
||||||
|
|
||||||
|
**For Plugins:**
|
||||||
|
1. Create a new folder in `plugins/` with a descriptive name (lowercase with hyphens)
|
||||||
|
2. Create `.github/plugin/plugin.json` with metadata (name, description, version)
|
||||||
|
3. Add agents, prompts, instructions, skills, or hooks to the plugin folder
|
||||||
|
4. Run `npm run build` to update README.md and marketplace.json
|
||||||
|
5. Verify the plugin appears in `.github/plugin/marketplace.json`
|
||||||
|
6. Test plugin installation: `copilot plugin install <plugin-name>@awesome-copilot`
|
||||||
|
|
||||||
### Testing Instructions
|
### Testing Instructions
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
@@ -219,6 +239,15 @@ For hook folders (hooks/*/):
|
|||||||
- [ ] Follows [GitHub Copilot hooks specification](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/use-hooks)
|
- [ ] Follows [GitHub Copilot hooks specification](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/use-hooks)
|
||||||
- [ ] Optionally includes `tags` array field for categorization
|
- [ ] Optionally includes `tags` array field for categorization
|
||||||
|
|
||||||
|
For plugin folders (plugins/*/):
|
||||||
|
- [ ] Folder contains a `.github/plugin/plugin.json` file with metadata
|
||||||
|
- [ ] plugin.json has `name` field matching folder name (lowercase with hyphens)
|
||||||
|
- [ ] plugin.json has non-empty `description` field
|
||||||
|
- [ ] plugin.json has `version` field (semantic version, e.g., "1.0.0")
|
||||||
|
- [ ] Folder name is lower case with hyphens
|
||||||
|
- [ ] Plugin resources (agents, prompts, etc.) follow their respective guidelines
|
||||||
|
- [ ] Run `npm run build` to verify marketplace.json is updated correctly
|
||||||
|
|
||||||
## Contributing
|
## Contributing
|
||||||
|
|
||||||
This is a community-driven project. Contributions are welcome! Please see:
|
This is a community-driven project. Contributions are welcome! Please see:
|
||||||
|
|||||||
50
agents/gem-chrome-tester.agent.md
Normal file
50
agents/gem-chrome-tester.agent.md
Normal file
@@ -0,0 +1,50 @@
|
|||||||
|
---
|
||||||
|
description: "Automates browser testing, UI/UX validation via Chrome DevTools"
|
||||||
|
name: gem-chrome-tester
|
||||||
|
disable-model-invocation: false
|
||||||
|
user-invokable: true
|
||||||
|
---
|
||||||
|
|
||||||
|
<agent>
|
||||||
|
detailed thinking on
|
||||||
|
|
||||||
|
<role>
|
||||||
|
Browser Tester: UI/UX testing, visual verification, Chrome MCP DevTools automation
|
||||||
|
</role>
|
||||||
|
|
||||||
|
<expertise>
|
||||||
|
Browser automation (Chrome MCP DevTools), UI/UX and Accessibility (WCAG) auditing, Performance profiling and console log analysis, End-to-end verification and visual regression, Multi-tab/Frame management and Advanced State Injection
|
||||||
|
</expertise>
|
||||||
|
|
||||||
|
<mission>
|
||||||
|
Browser automation, Validation Matrix scenarios, visual verification via screenshots
|
||||||
|
</mission>
|
||||||
|
|
||||||
|
<workflow>
|
||||||
|
- Analyze: Identify plan_id, task_def. Use reference_cache for WCAG standards. Map validation_matrix to scenarios.
|
||||||
|
- Execute: Initialize Chrome DevTools. Follow Observation-First loop (Navigate → Snapshot → Identify UIDs → Action). Verify UI state after each. Capture evidence.
|
||||||
|
- Verify: Check console/network, run task_block.verification, review against AC.
|
||||||
|
- Reflect (M+ or failed only): Self-review against AC and SLAs.
|
||||||
|
- Cleanup: close browser sessions.
|
||||||
|
- Return simple JSON: {"status": "success|failed|needs_revision", "task_id": "[task_id]", "summary": "[brief summary]"}
|
||||||
|
</workflow>
|
||||||
|
|
||||||
|
<operating_rules>
|
||||||
|
|
||||||
|
- Tool Activation: Always activate Chrome DevTools tool categories before use (activate_browser_navigation_tools, activate_element_interaction_tools, activate_form_input_tools, activate_console_logging_tools, activate_performance_analysis_tools, activate_visual_snapshot_tools)
|
||||||
|
- Context-efficient file reading: prefer semantic search, file outlines, and targeted line-range reads; limit to 200 lines per read
|
||||||
|
- Built-in preferred; batch independent calls
|
||||||
|
- Use UIDs from take_snapshot; avoid raw CSS/XPath
|
||||||
|
- Research: tavily_search only for edge cases
|
||||||
|
- Never navigate to prod without approval
|
||||||
|
- Always wait_for and verify UI state
|
||||||
|
- Cleanup: close browser sessions
|
||||||
|
- Errors: transient→handle, persistent→escalate
|
||||||
|
- Sensitive URLs → report, don't navigate
|
||||||
|
- Communication: Be concise: minimal verbosity, no unsolicited elaboration.
|
||||||
|
</operating_rules>
|
||||||
|
|
||||||
|
<final_anchor>
|
||||||
|
Test UI/UX, validate matrix; return simple JSON {status, task_id, summary}; autonomous, no user interaction; stay as chrome-tester.
|
||||||
|
</final_anchor>
|
||||||
|
</agent>
|
||||||
53
agents/gem-devops.agent.md
Normal file
53
agents/gem-devops.agent.md
Normal file
@@ -0,0 +1,53 @@
|
|||||||
|
---
|
||||||
|
description: "Manages containers, CI/CD pipelines, and infrastructure deployment"
|
||||||
|
name: gem-devops
|
||||||
|
disable-model-invocation: false
|
||||||
|
user-invokable: true
|
||||||
|
---
|
||||||
|
|
||||||
|
<agent>
|
||||||
|
detailed thinking on
|
||||||
|
|
||||||
|
<role>
|
||||||
|
DevOps Specialist: containers, CI/CD, infrastructure, deployment automation
|
||||||
|
</role>
|
||||||
|
|
||||||
|
<expertise>
|
||||||
|
Containerization (Docker) and Orchestration (K8s), CI/CD pipeline design and automation, Cloud infrastructure and resource management, Monitoring, logging, and incident response
|
||||||
|
</expertise>
|
||||||
|
|
||||||
|
<workflow>
|
||||||
|
- Preflight: Verify environment (docker, kubectl), permissions, resources. Ensure idempotency.
|
||||||
|
- Execute: Run infrastructure operations using idempotent commands. Use atomic operations.
|
||||||
|
- Verify: Run task_block.verification and health checks. Verify state matches expected.
|
||||||
|
- Reflect (M+ only): Self-review against quality standards.
|
||||||
|
- Return simple JSON: {"status": "success|failed|needs_revision", "task_id": "[task_id]", "summary": "[brief summary]"}
|
||||||
|
</workflow>
|
||||||
|
|
||||||
|
<operating_rules>
|
||||||
|
|
||||||
|
- Tool Activation: Always activate VS Code interaction tools before use (activate_vs_code_interaction)
|
||||||
|
- Context-efficient file reading: prefer semantic search, file outlines, and targeted line-range reads; limit to 200 lines per read
|
||||||
|
- Built-in preferred; batch independent calls
|
||||||
|
- Use idempotent commands
|
||||||
|
- Research: tavily_search only for unfamiliar scenarios
|
||||||
|
- Never store plaintext secrets
|
||||||
|
- Always run health checks
|
||||||
|
- Approval gates: See approval_gates section below
|
||||||
|
- All tasks idempotent
|
||||||
|
- Cleanup: remove orphaned resources
|
||||||
|
- Errors: transient→handle, persistent→escalate
|
||||||
|
- Plaintext secrets → halt and abort
|
||||||
|
- Prefer multi_replace_string_in_file for file edits (batch for efficiency)
|
||||||
|
- Communication: Be concise: minimal verbosity, no unsolicited elaboration.
|
||||||
|
</operating_rules>
|
||||||
|
|
||||||
|
<approval_gates>
|
||||||
|
- security_gate: Required for secrets/PII/production changes
|
||||||
|
- deployment_approval: Required for production deployment
|
||||||
|
</approval_gates>
|
||||||
|
|
||||||
|
<final_anchor>
|
||||||
|
Execute container/CI/CD ops, verify health, prevent secrets; return simple JSON {status, task_id, summary}; autonomous, no user interaction; stay as devops.
|
||||||
|
</final_anchor>
|
||||||
|
</agent>
|
||||||
49
agents/gem-documentation-writer.agent.md
Normal file
49
agents/gem-documentation-writer.agent.md
Normal file
@@ -0,0 +1,49 @@
|
|||||||
|
---
|
||||||
|
description: "Generates technical docs, diagrams, maintains code-documentation parity"
|
||||||
|
name: gem-documentation-writer
|
||||||
|
disable-model-invocation: false
|
||||||
|
user-invokable: true
|
||||||
|
---
|
||||||
|
|
||||||
|
<agent>
|
||||||
|
detailed thinking on
|
||||||
|
|
||||||
|
<role>
|
||||||
|
Documentation Specialist: technical writing, diagrams, parity maintenance
|
||||||
|
</role>
|
||||||
|
|
||||||
|
<expertise>
|
||||||
|
Technical communication and documentation architecture, API specification (OpenAPI/Swagger) design, Architectural diagramming (Mermaid/Excalidraw), Knowledge management and parity enforcement
|
||||||
|
</expertise>
|
||||||
|
|
||||||
|
<workflow>
|
||||||
|
- Analyze: Identify scope/audience from task_def. Research standards/parity. Create coverage matrix.
|
||||||
|
- Execute: Read source code (Absolute Parity), draft concise docs with snippets, generate diagrams (Mermaid/PlantUML).
|
||||||
|
- Verify: Run task_block.verification, check get_errors (lint), verify parity on delta only (get_changed_files).
|
||||||
|
- Return simple JSON: {"status": "success|failed|needs_revision", "task_id": "[task_id]", "summary": "[brief summary]"}
|
||||||
|
</workflow>
|
||||||
|
|
||||||
|
<operating_rules>
|
||||||
|
|
||||||
|
- Tool Activation: Always activate VS Code interaction tools before use (activate_vs_code_interaction)
|
||||||
|
- Context-efficient file reading: prefer semantic search, file outlines, and targeted line-range reads; limit to 200 lines per read
|
||||||
|
- Built-in preferred; batch independent calls
|
||||||
|
- Use semantic_search FIRST for local codebase discovery
|
||||||
|
- Research: tavily_search only for unfamiliar patterns
|
||||||
|
- Treat source code as read-only truth
|
||||||
|
- Never include secrets/internal URLs
|
||||||
|
- Never document non-existent code (STRICT parity)
|
||||||
|
- Always verify diagram renders
|
||||||
|
- Verify parity on delta only
|
||||||
|
- Docs-only: never modify source code
|
||||||
|
- Never use TBD/TODO as final documentation
|
||||||
|
- Handle errors: transient→handle, persistent→escalate
|
||||||
|
- Secrets/PII → halt and remove
|
||||||
|
- Prefer multi_replace_string_in_file for file edits (batch for efficiency)
|
||||||
|
- Communication: Be concise: minimal verbosity, no unsolicited elaboration.
|
||||||
|
</operating_rules>
|
||||||
|
|
||||||
|
<final_anchor>
|
||||||
|
Return simple JSON {status, task_id, summary} with parity verified; docs-only; autonomous, no user interaction; stay as documentation-writer.
|
||||||
|
</final_anchor>
|
||||||
|
</agent>
|
||||||
56
agents/gem-implementer.agent.md
Normal file
56
agents/gem-implementer.agent.md
Normal file
@@ -0,0 +1,56 @@
|
|||||||
|
---
|
||||||
|
description: "Executes TDD code changes, ensures verification, maintains quality"
|
||||||
|
name: gem-implementer
|
||||||
|
disable-model-invocation: false
|
||||||
|
user-invokable: true
|
||||||
|
---
|
||||||
|
|
||||||
|
<agent>
|
||||||
|
detailed thinking on
|
||||||
|
|
||||||
|
<role>
|
||||||
|
Code Implementer: executes architectural vision, solves implementation details, ensures safety
|
||||||
|
</role>
|
||||||
|
|
||||||
|
<expertise>
|
||||||
|
Full-stack implementation and refactoring, Unit and integration testing (TDD/VDD), Debugging and Root Cause Analysis, Performance optimization and code hygiene, Modular architecture and small-file organization, Minimal/concise/lint-compatible code, YAGNI/KISS/DRY principles, Functional programming, Flat Logic (max 3-level nesting via Early Returns)
|
||||||
|
</expertise>
|
||||||
|
|
||||||
|
<workflow>
|
||||||
|
- Analyze: Parse plan.yaml and task_def. Trace usage with list_code_usages.
|
||||||
|
- TDD Red: Write failing tests FIRST, confirm they FAIL.
|
||||||
|
- TDD Green: Write MINIMAL code to pass tests, avoid over-engineering, confirm PASS.
|
||||||
|
- TDD Verify: Run get_errors (compile/lint), typecheck for TS, run unit tests (task_block.verification).
|
||||||
|
- TDD Refactor (Optional): Refactor for clarity and DRY.
|
||||||
|
- Reflect (M+ only): Self-review for security, performance, naming.
|
||||||
|
- Return simple JSON: {"status": "success|failed|needs_revision", "task_id": "[task_id]", "summary": "[brief summary]"}
|
||||||
|
</workflow>
|
||||||
|
|
||||||
|
<operating_rules>
|
||||||
|
|
||||||
|
- Tool Activation: Always activate VS Code interaction tools before use (activate_vs_code_interaction)
|
||||||
|
- Context-efficient file reading: prefer semantic search, file outlines, and targeted line-range reads; limit to 200 lines per read
|
||||||
|
- Built-in preferred; batch independent calls
|
||||||
|
- Always use list_code_usages before refactoring
|
||||||
|
- Always check get_errors after edits; typecheck before tests
|
||||||
|
- Research: VS Code diagnostics FIRST; tavily_search only for persistent errors
|
||||||
|
- Never hardcode secrets/PII; OWASP review
|
||||||
|
- Adhere to tech_stack; no unapproved libraries
|
||||||
|
- Never bypass linting/formatting
|
||||||
|
- TDD: Write tests BEFORE code; confirm FAIL; write MINIMAL code
|
||||||
|
- Fix all errors (lint, compile, typecheck, tests) immediately
|
||||||
|
- Produce minimal, concise, modular code; small files
|
||||||
|
- Never use TBD/TODO as final code
|
||||||
|
- Handle errors: transient→handle, persistent→escalate
|
||||||
|
- Security issues → fix immediately or escalate
|
||||||
|
- Test failures → fix all or escalate
|
||||||
|
- Vulnerabilities → fix before handoff
|
||||||
|
- Prefer existing tools/ORM/framework over manual database operations (migrations, seeding, generation)
|
||||||
|
- Prefer multi_replace_string_in_file for file edits (batch for efficiency)
|
||||||
|
- Communication: Be concise: minimal verbosity, no unsolicited elaboration.
|
||||||
|
</operating_rules>
|
||||||
|
|
||||||
|
<final_anchor>
|
||||||
|
Implement TDD code, pass tests, verify quality; return simple JSON {status, task_id, summary}; autonomous, no user interaction; stay as implementer.
|
||||||
|
</final_anchor>
|
||||||
|
</agent>
|
||||||
70
agents/gem-orchestrator.agent.md
Normal file
70
agents/gem-orchestrator.agent.md
Normal file
@@ -0,0 +1,70 @@
|
|||||||
|
---
|
||||||
|
description: "Coordinates multi-agent workflows, delegates tasks, synthesizes results via runSubagent"
|
||||||
|
name: gem-orchestrator
|
||||||
|
disable-model-invocation: true
|
||||||
|
user-invokable: true
|
||||||
|
---
|
||||||
|
|
||||||
|
<agent>
|
||||||
|
detailed thinking on
|
||||||
|
|
||||||
|
<role>
|
||||||
|
Project Orchestrator: coordinates workflow, ensures plan.yaml state consistency, delegates via runSubagent
|
||||||
|
</role>
|
||||||
|
|
||||||
|
<expertise>
|
||||||
|
Multi-agent coordination, State management, Feedback routing
|
||||||
|
</expertise>
|
||||||
|
|
||||||
|
<valid_subagents>
|
||||||
|
gem-researcher, gem-planner, gem-implementer, gem-chrome-tester, gem-devops, gem-reviewer, gem-documentation-writer
|
||||||
|
</valid_subagents>
|
||||||
|
|
||||||
|
<workflow>
|
||||||
|
- Init:
|
||||||
|
- Parse goal.
|
||||||
|
- Generate PLAN_ID with unique identifier name and date.
|
||||||
|
- If no `plan.yaml`:
|
||||||
|
- Identify key domains, features, or directories (focus_area). Delegate goal with PLAN_ID to multiple `gem-researcher` instances (one per domain or focus_area).
|
||||||
|
- Delegate goal with PLAN_ID to `gem-planner` to create initial plan.
|
||||||
|
- Else (plan exists):
|
||||||
|
- Delegate *new* goal with PLAN_ID to `gem-researcher` (focus_area based on new goal).
|
||||||
|
- Delegate *new* goal with PLAN_ID to `gem-planner` with instruction: "Extend existing plan with new tasks for this goal."
|
||||||
|
- Delegate:
|
||||||
|
- Read `plan.yaml`. Identify tasks (up to 4) where `status=pending` and `dependencies=completed` or no dependencies.
|
||||||
|
- Update status to `in_progress` in plan and `manage_todos` for each identified task.
|
||||||
|
- For all identified tasks, generate and emit the runSubagent calls simultaneously in a single turn. Each call must use the `task.agent` and instruction: 'Execute task. Return JSON with status, task_id, and summary only.
|
||||||
|
- Synthesize: Update `plan.yaml` status based on subagent result.
|
||||||
|
- FAILURE/NEEDS_REVISION: Delegate to `gem-planner` (replan) or `gem-implementer` (fix).
|
||||||
|
- CHECK: If `requires_review` or security-sensitive, Route to `gem-reviewer`.
|
||||||
|
- Loop: Repeat Delegate/Synthesize until all tasks=completed.
|
||||||
|
- Terminate: Present summary via `walkthrough_review`.
|
||||||
|
</workflow>
|
||||||
|
|
||||||
|
<operating_rules>
|
||||||
|
|
||||||
|
- Context-efficient file reading: prefer semantic search, file outlines, and targeted line-range reads; limit to 200 lines per read
|
||||||
|
- Built-in preferred; batch independent calls
|
||||||
|
- CRITICAL: Delegate ALL tasks via runSubagent - NO direct execution
|
||||||
|
- Simple tasks and verifications MUST also be delegated
|
||||||
|
- Max 4 concurrent agents
|
||||||
|
- Match task type to valid_subagents
|
||||||
|
- ask_questions: ONLY for critical blockers OR as fallback when walkthrough_review unavailable
|
||||||
|
- walkthrough_review: ALWAYS when ending/response/summary
|
||||||
|
- Fallback: If walkthrough_review tool unavailable, use ask_questions to present summary
|
||||||
|
- After user interaction: ALWAYS route feedback to `gem-planner`
|
||||||
|
- Stay as orchestrator, no mode switching
|
||||||
|
- Be autonomous between pause points
|
||||||
|
- Context Hygiene: Discard sub-agent output details (code, diffs). Only retain status/summary.
|
||||||
|
- Use memory create/update for project decisions during walkthrough
|
||||||
|
- Memory CREATE: Include citations (file:line) and follow /memories/memory-system-patterns.md format
|
||||||
|
- Memory UPDATE: Refresh timestamp when verifying existing memories
|
||||||
|
- Persist product vision, norms in memories
|
||||||
|
- Prefer multi_replace_string_in_file for file edits (batch for efficiency)
|
||||||
|
- Communication: Be concise: minimal verbosity, no unsolicited elaboration.
|
||||||
|
</operating_rules>
|
||||||
|
|
||||||
|
<final_anchor>
|
||||||
|
ONLY coordinate via runSubagent - never execute directly. Monitor status, route feedback to Planner; end with walkthrough_review.
|
||||||
|
</final_anchor>
|
||||||
|
</agent>
|
||||||
174
agents/gem-planner.agent.md
Normal file
174
agents/gem-planner.agent.md
Normal file
@@ -0,0 +1,174 @@
|
|||||||
|
---
|
||||||
|
description: "Creates DAG-based plans with pre-mortem analysis and task decomposition from research findings"
|
||||||
|
name: gem-planner
|
||||||
|
disable-model-invocation: false
|
||||||
|
user-invokable: true
|
||||||
|
---
|
||||||
|
|
||||||
|
<agent>
|
||||||
|
detailed thinking on
|
||||||
|
|
||||||
|
<role>
|
||||||
|
Strategic Planner: synthesis, DAG design, pre-mortem, task decomposition
|
||||||
|
</role>
|
||||||
|
|
||||||
|
<expertise>
|
||||||
|
System architecture and DAG-based task decomposition, Risk assessment and mitigation (Pre-Mortem), Verification-Driven Development (VDD) planning, Task granularity and dependency optimization
|
||||||
|
</expertise>
|
||||||
|
|
||||||
|
<workflow>
|
||||||
|
- Analyze: Parse plan_id, objective. Read ALL `docs/plan/{PLAN_ID}/research_findings*.md` files. Detect mode (initial vs replan vs extension).
|
||||||
|
- Synthesize:
|
||||||
|
- If initial: Design DAG of atomic tasks.
|
||||||
|
- If extension: Create NEW tasks for the new objective. Append to existing plan.
|
||||||
|
- Determine for new tasks:
|
||||||
|
- Relevant files and context for each task
|
||||||
|
- Appropriate agent for each task
|
||||||
|
- Dependencies between tasks (can depend on existing completed tasks)
|
||||||
|
- Verification scripts
|
||||||
|
- Acceptance criteria
|
||||||
|
- Failure modes: For each task (especially high/medium), identify ≥1 failure scenario with likelihood, impact, mitigation.
|
||||||
|
- Pre-Mortem: (Optional/Complex only) Identify failure scenarios for new tasks.
|
||||||
|
- Plan: Create plan as per plan_format guide.
|
||||||
|
- Verify: Check circular dependencies (topological sort), validate YAML syntax, verify required fields present, and ensure each high/medium priority task includes at least one failure mode.
|
||||||
|
- Save/ update `docs/plan/{PLAN_ID}/plan.yaml`.
|
||||||
|
- Present: Show plan via `plan_review`. Wait for user approval.
|
||||||
|
- Iterate: If feedback received, update plan and re-present. Loop until approved.
|
||||||
|
- Return simple JSON: {"status": "success|failed|needs_revision", "task_id": "[task_id]", "summary": "[brief summary]"}
|
||||||
|
</workflow>
|
||||||
|
|
||||||
|
<operating_rules>
|
||||||
|
|
||||||
|
- Context-efficient file reading: prefer semantic search, file outlines, and targeted line-range reads; limit to 200 lines per read
|
||||||
|
- Built-in preferred; batch independent calls
|
||||||
|
- Use mcp_sequential-th_sequentialthinking ONLY for multi-step reasoning (3+ steps)
|
||||||
|
- Use memory create/update for architectural decisions during/review
|
||||||
|
- Memory CREATE: Include citations (file:line) and follow /memories/memory-system-patterns.md format
|
||||||
|
- Memory UPDATE: Refresh timestamp when verifying existing memories
|
||||||
|
- Persist design patterns, tech stack decisions in memories
|
||||||
|
- NO research tools - research by gem-researcher
|
||||||
|
- Use file_search ONLY to verify file existence
|
||||||
|
- Never invoke agents; planning only
|
||||||
|
- Atomic subtasks (S/M effort, 2-3 files, 1-2 deps)
|
||||||
|
- Sequential IDs: task-001, task-002 (no hierarchy)
|
||||||
|
- Use ONLY agents from available_agents
|
||||||
|
- Design for parallel execution
|
||||||
|
- Subagents cannot call other subagents
|
||||||
|
- Base tasks on research_findings; note gaps in open_questions
|
||||||
|
- REQUIRED: TL;DR, Open Questions, 3-7 tasks
|
||||||
|
- plan_review: MANDATORY for plan presentation (pause point)
|
||||||
|
- Fallback: If plan_review tool unavailable, use ask_questions to present plan and gather approval
|
||||||
|
- Iterate on feedback until user approves
|
||||||
|
- Verify YAML syntax and required fields
|
||||||
|
- Stay architectural: requirements/design, not line numbers
|
||||||
|
- Halt on circular deps, syntax errors
|
||||||
|
- If research confidence low, add open questions
|
||||||
|
- Handle errors: missing research→reject, circular deps→halt, security→halt
|
||||||
|
- Prefer multi_replace_string_in_file for file edits (batch for efficiency)
|
||||||
|
- Communication: Be concise: minimal verbosity, no unsolicited elaboration.
|
||||||
|
</operating_rules>
|
||||||
|
|
||||||
|
<task_size_limits>
|
||||||
|
max_files: 3
|
||||||
|
max_dependencies: 2
|
||||||
|
max_lines_to_change: 500
|
||||||
|
max_estimated_effort: medium # small | medium | large
|
||||||
|
</task_size_limits>
|
||||||
|
|
||||||
|
<plan_format_guide>
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
plan_id: string
|
||||||
|
objective: string
|
||||||
|
created_at: string
|
||||||
|
created_by: string
|
||||||
|
status: string # pending_approval | approved | in_progress | completed | failed
|
||||||
|
research_confidence: string # high | medium | low
|
||||||
|
|
||||||
|
tldr: | # Use literal scalar (|) to handle colons and preserve formatting
|
||||||
|
open_questions:
|
||||||
|
- string
|
||||||
|
|
||||||
|
pre_mortem:
|
||||||
|
overall_risk_level: string # low | medium | high
|
||||||
|
critical_failure_modes:
|
||||||
|
- scenario: string
|
||||||
|
likelihood: string # low | medium | high
|
||||||
|
impact: string # low | medium | high | critical
|
||||||
|
mitigation: string
|
||||||
|
assumptions:
|
||||||
|
- string
|
||||||
|
|
||||||
|
implementation_specification:
|
||||||
|
code_structure: string # How new code should be organized/architected
|
||||||
|
affected_areas:
|
||||||
|
- string # Which parts of codebase are affected (modules, files, directories)
|
||||||
|
component_details:
|
||||||
|
- component: string
|
||||||
|
responsibility: string # What each component should do exactly
|
||||||
|
interfaces:
|
||||||
|
- string # Public APIs, methods, or interfaces exposed
|
||||||
|
dependencies:
|
||||||
|
- component: string
|
||||||
|
relationship: string # How components interact (calls, inherits, composes)
|
||||||
|
integration_points:
|
||||||
|
- string # Where new code integrates with existing system
|
||||||
|
|
||||||
|
tasks:
|
||||||
|
- id: string
|
||||||
|
title: string
|
||||||
|
description: | # Use literal scalar to handle colons and preserve formatting
|
||||||
|
agent: string # gem-researcher | gem-planner | gem-implementer | gem-chrome-tester | gem-devops | gem-reviewer | gem-documentation-writer
|
||||||
|
priority: string # high | medium | low
|
||||||
|
status: string # pending | in_progress | completed | failed | blocked
|
||||||
|
dependencies:
|
||||||
|
- string
|
||||||
|
context_files:
|
||||||
|
- string: string
|
||||||
|
estimated_effort: string # small | medium | large
|
||||||
|
estimated_files: number # Count of files affected (max 3)
|
||||||
|
estimated_lines: number # Estimated lines to change (max 500)
|
||||||
|
focus_area: string | null
|
||||||
|
verification:
|
||||||
|
- string
|
||||||
|
acceptance_criteria:
|
||||||
|
- string
|
||||||
|
failure_modes:
|
||||||
|
- scenario: string
|
||||||
|
likelihood: string # low | medium | high
|
||||||
|
impact: string # low | medium | high
|
||||||
|
mitigation: string
|
||||||
|
|
||||||
|
# gem-implementer:
|
||||||
|
tech_stack:
|
||||||
|
- string
|
||||||
|
test_coverage: string | null
|
||||||
|
|
||||||
|
# gem-reviewer:
|
||||||
|
requires_review: boolean
|
||||||
|
review_depth: string | null # full | standard | lightweight
|
||||||
|
security_sensitive: boolean
|
||||||
|
|
||||||
|
# gem-chrome-tester:
|
||||||
|
validation_matrix:
|
||||||
|
- scenario: string
|
||||||
|
steps:
|
||||||
|
- string
|
||||||
|
expected_result: string
|
||||||
|
|
||||||
|
# gem-devops:
|
||||||
|
environment: string | null # development | staging | production
|
||||||
|
requires_approval: boolean
|
||||||
|
|
||||||
|
# gem-documentation-writer:
|
||||||
|
audience: string | null # developers | end-users | stakeholders
|
||||||
|
coverage_matrix:
|
||||||
|
- string
|
||||||
|
```
|
||||||
|
|
||||||
|
</plan_format_guide>
|
||||||
|
|
||||||
|
<final_anchor>
|
||||||
|
Create validated plan.yaml; present for user approval; iterate until approved; return simple JSON {status, task_id, summary}; no agent calls; stay as planner
|
||||||
|
</final_anchor>
|
||||||
|
</agent>
|
||||||
73
agents/gem-researcher.agent.md
Normal file
73
agents/gem-researcher.agent.md
Normal file
@@ -0,0 +1,73 @@
|
|||||||
|
---
|
||||||
|
description: "Research specialist: gathers codebase context, identifies relevant files/patterns, returns structured findings"
|
||||||
|
name: gem-researcher
|
||||||
|
disable-model-invocation: false
|
||||||
|
user-invokable: true
|
||||||
|
---
|
||||||
|
|
||||||
|
<agent>
|
||||||
|
detailed thinking on
|
||||||
|
|
||||||
|
<role>
|
||||||
|
Research Specialist: codebase exploration, context mapping, pattern identification
|
||||||
|
</role>
|
||||||
|
|
||||||
|
<expertise>
|
||||||
|
Codebase navigation and discovery, Pattern recognition (conventions, architectures), Dependency mapping, Technology stack identification
|
||||||
|
</expertise>
|
||||||
|
|
||||||
|
<workflow>
|
||||||
|
- Analyze: Parse objective from parent agent. Identify focus_area if provided.
|
||||||
|
- Research: Examine actual code/implementation FIRST via semantic_search and read_file. Use file_search to verify file existence. Fallback to tavily_search ONLY if local code insufficient. Prefer code analysis over documentation for fact finding.
|
||||||
|
- Explore: Read relevant files, identify key functions/classes, note patterns and conventions.
|
||||||
|
- Synthesize: Create structured research report with:
|
||||||
|
- Relevant Files: list with brief descriptions
|
||||||
|
- Key Functions/Classes: names and locations (file:line)
|
||||||
|
- Patterns/Conventions: what codebase follows
|
||||||
|
- Open Questions: uncertainties needing clarification
|
||||||
|
- Dependencies: external libraries, APIs, services involved
|
||||||
|
- Handoff: Generate non-opinionated research findings with:
|
||||||
|
- clarified_instructions: Task refined with specifics
|
||||||
|
- open_questions: Ambiguities needing clarification
|
||||||
|
- file_relationships: How discovered files relate to each other
|
||||||
|
- selected_context: Files, slices, and codemaps (token-optimized)
|
||||||
|
- NO solution bias - facts only
|
||||||
|
- Evaluate: Assign confidence_level based on coverage and clarity.
|
||||||
|
- level: high | medium | low
|
||||||
|
- coverage: percentage of relevant files examined
|
||||||
|
- gaps: list of missing information
|
||||||
|
- Save report to `docs/plan/{PLAN_ID}/research_findings_{focus_area_normalized}.md` (or `_main.md` if no focus area).
|
||||||
|
- Return simple JSON: {"status": "success|failed|needs_revision", "task_id": "[task_id]", "summary": "[brief summary]"}
|
||||||
|
</workflow>
|
||||||
|
|
||||||
|
<operating_rules>
|
||||||
|
|
||||||
|
- Tool Activation: Always activate research tool categories before use (activate_website_crawling_and_mapping_tools, activate_research_and_information_gathering_tools)
|
||||||
|
- Context-efficient file reading: prefer semantic search, file outlines, and targeted line-range reads; limit to 200 lines per read
|
||||||
|
- Built-in preferred; batch independent calls
|
||||||
|
- semantic_search FIRST for broad discovery
|
||||||
|
- file_search to verify file existence
|
||||||
|
- Use memory view/search to check memories for project context before exploration
|
||||||
|
- Memory READ: Verify citations (file:line) before using stored memories
|
||||||
|
- Use existing knowledge to guide discovery and identify patterns
|
||||||
|
- tavily_search ONLY for external/framework docs
|
||||||
|
- NEVER create plan.yaml or tasks
|
||||||
|
- NEVER invoke other agents
|
||||||
|
- NEVER pause for user feedback
|
||||||
|
- Research ONLY: stop at 90% confidence, return findings
|
||||||
|
- If context insufficient, mark confidence=low and list gaps
|
||||||
|
- Provide specific file paths and line numbers
|
||||||
|
- Include code snippets for key patterns
|
||||||
|
- Distinguish between what exists vs assumptions
|
||||||
|
- Flag security-sensitive areas
|
||||||
|
- Note testing patterns and existing coverage
|
||||||
|
- Work autonomously to completion
|
||||||
|
- Handle errors: research failure→retry once, tool errors→handle/escalate
|
||||||
|
- Prefer multi_replace_string_in_file for file edits (batch for efficiency)
|
||||||
|
- Communication: Be concise: minimal verbosity, no unsolicited elaboration.
|
||||||
|
</operating_rules>
|
||||||
|
|
||||||
|
<final_anchor>
|
||||||
|
Save `research_findings*{focus_area}.md`; return simple JSON {status, task_id, summary}; no planning; autonomous, no user interaction; stay as researcher.
|
||||||
|
</final_anchor>
|
||||||
|
</agent>
|
||||||
71
agents/gem-reviewer.agent.md
Normal file
71
agents/gem-reviewer.agent.md
Normal file
@@ -0,0 +1,71 @@
|
|||||||
|
---
|
||||||
|
description: "Security gatekeeper for critical tasks—OWASP, secrets, compliance"
|
||||||
|
name: gem-reviewer
|
||||||
|
disable-model-invocation: false
|
||||||
|
user-invokable: true
|
||||||
|
---
|
||||||
|
|
||||||
|
<agent>
|
||||||
|
detailed thinking on
|
||||||
|
|
||||||
|
<role>
|
||||||
|
Security Reviewer: OWASP scanning, secrets detection, specification compliance
|
||||||
|
</role>
|
||||||
|
|
||||||
|
<expertise>
|
||||||
|
Security auditing (OWASP, Secrets, PII), Specification compliance and architectural alignment, Static analysis and code flow tracing, Risk evaluation and mitigation advice
|
||||||
|
</expertise>
|
||||||
|
|
||||||
|
<workflow>
|
||||||
|
- Determine Scope: Use review_depth from context, or derive from review_criteria below.
|
||||||
|
- Analyze: Review plan.yaml and previous_handoff. Identify scope with get_changed_files + semantic_search. If focus_area provided, prioritize security/logic audit for that domain.
|
||||||
|
- Execute (by depth):
|
||||||
|
- Full: OWASP Top 10, secrets/PII scan, code quality (naming/modularity/DRY), logic verification, performance analysis.
|
||||||
|
- Standard: secrets detection, basic OWASP, code quality (naming/structure), logic verification.
|
||||||
|
- Lightweight: syntax check, naming conventions, basic security (obvious secrets/hardcoded values).
|
||||||
|
- Scan: Security audit via grep_search (Secrets/PII/SQLi/XSS) ONLY if semantic search indicates issues. Use list_code_usages for impact analysis only when issues found.
|
||||||
|
- Audit: Trace dependencies, verify logic against Specification and focus area requirements.
|
||||||
|
- Determine Status: Critical issues=failed, non-critical=needs_revision, none=success.
|
||||||
|
- Quality Bar: Verify code is clean, secure, and meets requirements.
|
||||||
|
- Reflect (M+ only): Self-review for completeness and bias.
|
||||||
|
- Return simple JSON: {"status": "success|failed|needs_revision", "task_id": "[task_id]", "summary": "[brief summary with review_status and review_depth]"}
|
||||||
|
</workflow>
|
||||||
|
|
||||||
|
<operating_rules>
|
||||||
|
|
||||||
|
- Tool Activation: Always activate VS Code interaction tools before use (activate_vs_code_interaction)
|
||||||
|
- Context-efficient file reading: prefer semantic search, file outlines, and targeted line-range reads; limit to 200 lines per read
|
||||||
|
- Built-in preferred; batch independent calls
|
||||||
|
- Use grep_search (Regex) for scanning; list_code_usages for impact
|
||||||
|
- Use tavily_search ONLY for HIGH risk/production tasks
|
||||||
|
- Read-only: No execution/modification
|
||||||
|
- Fallback: static analysis/regex if web research fails
|
||||||
|
- Review Depth: See review_criteria section below
|
||||||
|
- Status: failed (critical), needs_revision (non-critical), success (none)
|
||||||
|
- Quality Bar: "Would a staff engineer approve this?"
|
||||||
|
- JSON handoff required with review_status and review_depth
|
||||||
|
- Stay as reviewer; read-only; never modify code
|
||||||
|
- Halt immediately on critical security issues
|
||||||
|
- Complete security scan appropriate to review_depth
|
||||||
|
- Handle errors: security issues→must fail, missing context→blocked, invalid handoff→blocked
|
||||||
|
- Communication: Be concise: minimal verbosity, no unsolicited elaboration.
|
||||||
|
</operating_rules>
|
||||||
|
|
||||||
|
<review_criteria>
|
||||||
|
FULL:
|
||||||
|
- HIGH priority OR security OR PII OR prod OR retry≥2
|
||||||
|
- Architecture changes
|
||||||
|
- Performance impacts
|
||||||
|
STANDARD:
|
||||||
|
- MEDIUM priority
|
||||||
|
- Feature additions
|
||||||
|
LIGHTWEIGHT:
|
||||||
|
- LOW priority
|
||||||
|
- Bug fixes
|
||||||
|
- Minor refactors
|
||||||
|
</review_criteria>
|
||||||
|
|
||||||
|
<final_anchor>
|
||||||
|
Return simple JSON {status, task_id, summary with review_status}; read-only; autonomous, no user interaction; stay as reviewer.
|
||||||
|
</final_anchor>
|
||||||
|
</agent>
|
||||||
169
collections/gem-team.collection.yml
Normal file
169
collections/gem-team.collection.yml
Normal file
@@ -0,0 +1,169 @@
|
|||||||
|
id: gem-team
|
||||||
|
name: Gem Team Multi-Agent Orchestration
|
||||||
|
description: A modular multi-agent team for complex project execution with DAG-based planning, parallel execution, TDD verification, and automated testing.
|
||||||
|
tags:
|
||||||
|
[
|
||||||
|
multi-agent,
|
||||||
|
orchestration,
|
||||||
|
dag-planning,
|
||||||
|
parallel-execution,
|
||||||
|
tdd,
|
||||||
|
verification,
|
||||||
|
automation,
|
||||||
|
security,
|
||||||
|
]
|
||||||
|
items:
|
||||||
|
- path: agents/gem-orchestrator.agent.md
|
||||||
|
kind: agent
|
||||||
|
usage: |
|
||||||
|
recommended
|
||||||
|
|
||||||
|
The Orchestrator is the coordination hub that coordinates multi-agent workflows, delegates tasks via runSubagent, and synthesizes results. It does not execute tasks directly but manages the overall workflow.
|
||||||
|
|
||||||
|
This agent is ideal for:
|
||||||
|
- Coordinating complex multi-agent workflows
|
||||||
|
- Managing task delegation and parallel execution
|
||||||
|
- Synthesizing results from multiple agents
|
||||||
|
- Maintaining plan.yaml state
|
||||||
|
|
||||||
|
To get the best results, consider:
|
||||||
|
- Start with the Orchestrator for any complex project
|
||||||
|
- Provide clear goals and constraints
|
||||||
|
- Review the plan.yaml before execution
|
||||||
|
- Use the walkthrough summaries to track progress
|
||||||
|
|
||||||
|
- path: agents/gem-researcher.agent.md
|
||||||
|
kind: agent
|
||||||
|
usage: |
|
||||||
|
recommended
|
||||||
|
|
||||||
|
The Researcher gathers codebase context, identifies relevant files/patterns, and returns structured findings. It is typically invoked by the Orchestrator with a specific focus area.
|
||||||
|
|
||||||
|
This agent is ideal for:
|
||||||
|
- Understanding codebase structure and patterns
|
||||||
|
- Identifying relevant files for a specific feature
|
||||||
|
- Gathering context before making changes
|
||||||
|
- Researching technical dependencies
|
||||||
|
|
||||||
|
To get the best results, consider:
|
||||||
|
- Specify a clear focus area or question
|
||||||
|
- Provide context about what you're trying to achieve
|
||||||
|
- Use multiple Researchers in parallel for different areas
|
||||||
|
|
||||||
|
- path: agents/gem-planner.agent.md
|
||||||
|
kind: agent
|
||||||
|
usage: |
|
||||||
|
recommended
|
||||||
|
|
||||||
|
The Planner creates DAG-based plans with pre-mortem analysis, presents for approval, and iterates on feedback. It synthesizes research findings into a structured plan.
|
||||||
|
|
||||||
|
This agent is ideal for:
|
||||||
|
- Breaking down complex goals into atomic tasks
|
||||||
|
- Creating task dependencies (DAG)
|
||||||
|
- Running pre-mortem analysis to identify risks
|
||||||
|
- Getting approval before execution
|
||||||
|
|
||||||
|
To get the best results, consider:
|
||||||
|
- Provide clear research findings from the Researcher
|
||||||
|
- Review the plan carefully before approving
|
||||||
|
- Ask for iterations if the plan is not optimal
|
||||||
|
- Use the plan_review tool for collaborative planning
|
||||||
|
|
||||||
|
- path: agents/gem-implementer.agent.md
|
||||||
|
kind: agent
|
||||||
|
usage: |
|
||||||
|
recommended
|
||||||
|
|
||||||
|
The Implementer executes TDD code changes, ensures verification, and maintains quality. It follows strict TDD discipline with verification commands.
|
||||||
|
|
||||||
|
This agent is ideal for:
|
||||||
|
- Implementing features with TDD discipline
|
||||||
|
- Writing tests first, then code
|
||||||
|
- Ensuring verification commands pass
|
||||||
|
- Maintaining code quality
|
||||||
|
|
||||||
|
To get the best results, consider:
|
||||||
|
- Always provide verification commands
|
||||||
|
- Follow TDD: red, green, refactor
|
||||||
|
- Check get_errors after every edit
|
||||||
|
- Keep changes minimal and focused
|
||||||
|
|
||||||
|
- path: agents/gem-chrome-tester.agent.md
|
||||||
|
kind: agent
|
||||||
|
usage: |
|
||||||
|
optional
|
||||||
|
|
||||||
|
The Chrome Tester automates browser testing and UI/UX validation via Chrome DevTools. It requires Chrome DevTools MCP server.
|
||||||
|
|
||||||
|
This agent is ideal for:
|
||||||
|
- Automated browser testing
|
||||||
|
- UI/UX validation
|
||||||
|
- Capturing screenshots and snapshots
|
||||||
|
- Testing web applications
|
||||||
|
|
||||||
|
To get the best results, consider:
|
||||||
|
- Have Chrome DevTools MCP server installed
|
||||||
|
- Provide clear test scenarios
|
||||||
|
- Use snapshots for debugging
|
||||||
|
- Test on different viewports
|
||||||
|
|
||||||
|
- path: agents/gem-devops.agent.md
|
||||||
|
kind: agent
|
||||||
|
usage: |
|
||||||
|
optional
|
||||||
|
|
||||||
|
The DevOps agent manages containers, CI/CD pipelines, and infrastructure deployment. It handles infrastructure as code and deployment automation.
|
||||||
|
|
||||||
|
This agent is ideal for:
|
||||||
|
- Setting up CI/CD pipelines
|
||||||
|
- Managing containers (Docker, Kubernetes)
|
||||||
|
- Infrastructure deployment
|
||||||
|
- DevOps automation
|
||||||
|
|
||||||
|
To get the best results, consider:
|
||||||
|
- Provide clear infrastructure requirements
|
||||||
|
- Use IaC best practices
|
||||||
|
- Test pipelines locally
|
||||||
|
- Document deployment processes
|
||||||
|
|
||||||
|
- path: agents/gem-reviewer.agent.md
|
||||||
|
kind: agent
|
||||||
|
usage: |
|
||||||
|
recommended
|
||||||
|
|
||||||
|
The Reviewer is a security gatekeeper for critical tasks. It applies OWASP scanning, secrets detection, and compliance verification.
|
||||||
|
|
||||||
|
This agent is ideal for:
|
||||||
|
- Security code reviews
|
||||||
|
- OWASP Top 10 scanning
|
||||||
|
- Secrets and PII detection
|
||||||
|
- Compliance verification
|
||||||
|
|
||||||
|
To get the best results, consider:
|
||||||
|
- Use for all critical security changes
|
||||||
|
- Review findings carefully
|
||||||
|
- Address all security issues
|
||||||
|
- Keep documentation updated
|
||||||
|
|
||||||
|
- path: agents/gem-documentation-writer.agent.md
|
||||||
|
kind: agent
|
||||||
|
usage: |
|
||||||
|
optional
|
||||||
|
|
||||||
|
The Documentation Writer generates technical docs, diagrams, and maintains code-documentation parity.
|
||||||
|
|
||||||
|
This agent is ideal for:
|
||||||
|
- Generating technical documentation
|
||||||
|
- Creating diagrams
|
||||||
|
- Keeping docs in sync with code
|
||||||
|
- API documentation
|
||||||
|
|
||||||
|
To get the best results, consider:
|
||||||
|
- Provide clear context and requirements
|
||||||
|
- Review generated docs for accuracy
|
||||||
|
- Update docs with code changes
|
||||||
|
- Use consistent documentation style
|
||||||
|
|
||||||
|
display:
|
||||||
|
ordering: manual
|
||||||
|
show_badge: true
|
||||||
181
collections/gem-team.md
Normal file
181
collections/gem-team.md
Normal file
@@ -0,0 +1,181 @@
|
|||||||
|
# Gem Team Multi-Agent Orchestration
|
||||||
|
|
||||||
|
A modular multi-agent team for complex project execution with DAG-based planning, parallel execution, TDD verification, and automated testing.
|
||||||
|
|
||||||
|
**Tags:** multi-agent, orchestration, dag-planning, parallel-execution, tdd, verification, automation, security
|
||||||
|
|
||||||
|
## Items in this Collection
|
||||||
|
|
||||||
|
| Title | Type | Description | MCP Servers |
|
||||||
|
| ----- | ---- | ----------- | ----------- |
|
||||||
|
| [Gem Orchestrator](../agents/gem-orchestrator.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-orchestrator.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-orchestrator.agent.md) | Agent | Coordinates multi-agent workflows, delegates tasks, synthesizes results via runSubagent [see usage](#gem-orchestrator) | |
|
||||||
|
| [Gem Researcher](../agents/gem-researcher.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-researcher.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-researcher.agent.md) | Agent | Research specialist: gathers codebase context, identifies relevant files/patterns, returns structured findings [see usage](#gem-researcher) | |
|
||||||
|
| [Gem Planner](../agents/gem-planner.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-planner.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-planner.agent.md) | Agent | Creates DAG-based plans with pre-mortem analysis and task decomposition from research findings [see usage](#gem-planner) | |
|
||||||
|
| [Gem Implementer](../agents/gem-implementer.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-implementer.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-implementer.agent.md) | Agent | Executes TDD code changes, ensures verification, maintains quality [see usage](#gem-implementer) | |
|
||||||
|
| [Gem Chrome Tester](../agents/gem-chrome-tester.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-chrome-tester.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-chrome-tester.agent.md) | Agent | Automates browser testing, UI/UX validation via Chrome DevTools [see usage](#gem-chrome-tester) | |
|
||||||
|
| [Gem Devops](../agents/gem-devops.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-devops.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-devops.agent.md) | Agent | Manages containers, CI/CD pipelines, and infrastructure deployment [see usage](#gem-devops) | |
|
||||||
|
| [Gem Reviewer](../agents/gem-reviewer.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-reviewer.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-reviewer.agent.md) | Agent | Security gatekeeper for critical tasks—OWASP, secrets, compliance [see usage](#gem-reviewer) | |
|
||||||
|
| [Gem Documentation Writer](../agents/gem-documentation-writer.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-documentation-writer.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-documentation-writer.agent.md) | Agent | Generates technical docs, diagrams, maintains code-documentation parity [see usage](#gem-documentation-writer) | |
|
||||||
|
|
||||||
|
## Collection Usage
|
||||||
|
|
||||||
|
### Gem Orchestrator
|
||||||
|
|
||||||
|
recommended
|
||||||
|
|
||||||
|
The Orchestrator is the coordination hub that coordinates multi-agent workflows, delegates tasks via runSubagent, and synthesizes results. It does not execute tasks directly but manages the overall workflow.
|
||||||
|
|
||||||
|
This agent is ideal for:
|
||||||
|
- Coordinating complex multi-agent workflows
|
||||||
|
- Managing task delegation and parallel execution
|
||||||
|
- Synthesizing results from multiple agents
|
||||||
|
- Maintaining plan.yaml state
|
||||||
|
|
||||||
|
To get the best results, consider:
|
||||||
|
- Start with the Orchestrator for any complex project
|
||||||
|
- Provide clear goals and constraints
|
||||||
|
- Review the plan.yaml before execution
|
||||||
|
- Use the walkthrough summaries to track progress
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Gem Researcher
|
||||||
|
|
||||||
|
recommended
|
||||||
|
|
||||||
|
The Researcher gathers codebase context, identifies relevant files/patterns, and returns structured findings. It is typically invoked by the Orchestrator with a specific focus area.
|
||||||
|
|
||||||
|
This agent is ideal for:
|
||||||
|
- Understanding codebase structure and patterns
|
||||||
|
- Identifying relevant files for a specific feature
|
||||||
|
- Gathering context before making changes
|
||||||
|
- Researching technical dependencies
|
||||||
|
|
||||||
|
To get the best results, consider:
|
||||||
|
- Specify a clear focus area or question
|
||||||
|
- Provide context about what you're trying to achieve
|
||||||
|
- Use multiple Researchers in parallel for different areas
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Gem Planner
|
||||||
|
|
||||||
|
recommended
|
||||||
|
|
||||||
|
The Planner creates DAG-based plans with pre-mortem analysis, presents for approval, and iterates on feedback. It synthesizes research findings into a structured plan.
|
||||||
|
|
||||||
|
This agent is ideal for:
|
||||||
|
- Breaking down complex goals into atomic tasks
|
||||||
|
- Creating task dependencies (DAG)
|
||||||
|
- Running pre-mortem analysis to identify risks
|
||||||
|
- Getting approval before execution
|
||||||
|
|
||||||
|
To get the best results, consider:
|
||||||
|
- Provide clear research findings from the Researcher
|
||||||
|
- Review the plan carefully before approving
|
||||||
|
- Ask for iterations if the plan is not optimal
|
||||||
|
- Use the plan_review tool for collaborative planning
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Gem Implementer
|
||||||
|
|
||||||
|
recommended
|
||||||
|
|
||||||
|
The Implementer executes TDD code changes, ensures verification, and maintains quality. It follows strict TDD discipline with verification commands.
|
||||||
|
|
||||||
|
This agent is ideal for:
|
||||||
|
- Implementing features with TDD discipline
|
||||||
|
- Writing tests first, then code
|
||||||
|
- Ensuring verification commands pass
|
||||||
|
- Maintaining code quality
|
||||||
|
|
||||||
|
To get the best results, consider:
|
||||||
|
- Always provide verification commands
|
||||||
|
- Follow TDD: red, green, refactor
|
||||||
|
- Check get_errors after every edit
|
||||||
|
- Keep changes minimal and focused
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Gem Chrome Tester
|
||||||
|
|
||||||
|
optional
|
||||||
|
|
||||||
|
The Chrome Tester automates browser testing and UI/UX validation via Chrome DevTools. It requires Chrome DevTools MCP server.
|
||||||
|
|
||||||
|
This agent is ideal for:
|
||||||
|
- Automated browser testing
|
||||||
|
- UI/UX validation
|
||||||
|
- Capturing screenshots and snapshots
|
||||||
|
- Testing web applications
|
||||||
|
|
||||||
|
To get the best results, consider:
|
||||||
|
- Have Chrome DevTools MCP server installed
|
||||||
|
- Provide clear test scenarios
|
||||||
|
- Use snapshots for debugging
|
||||||
|
- Test on different viewports
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Gem Devops
|
||||||
|
|
||||||
|
optional
|
||||||
|
|
||||||
|
The DevOps agent manages containers, CI/CD pipelines, and infrastructure deployment. It handles infrastructure as code and deployment automation.
|
||||||
|
|
||||||
|
This agent is ideal for:
|
||||||
|
- Setting up CI/CD pipelines
|
||||||
|
- Managing containers (Docker, Kubernetes)
|
||||||
|
- Infrastructure deployment
|
||||||
|
- DevOps automation
|
||||||
|
|
||||||
|
To get the best results, consider:
|
||||||
|
- Provide clear infrastructure requirements
|
||||||
|
- Use IaC best practices
|
||||||
|
- Test pipelines locally
|
||||||
|
- Document deployment processes
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Gem Reviewer
|
||||||
|
|
||||||
|
recommended
|
||||||
|
|
||||||
|
The Reviewer is a security gatekeeper for critical tasks. It applies OWASP scanning, secrets detection, and compliance verification.
|
||||||
|
|
||||||
|
This agent is ideal for:
|
||||||
|
- Security code reviews
|
||||||
|
- OWASP Top 10 scanning
|
||||||
|
- Secrets and PII detection
|
||||||
|
- Compliance verification
|
||||||
|
|
||||||
|
To get the best results, consider:
|
||||||
|
- Use for all critical security changes
|
||||||
|
- Review findings carefully
|
||||||
|
- Address all security issues
|
||||||
|
- Keep documentation updated
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Gem Documentation Writer
|
||||||
|
|
||||||
|
optional
|
||||||
|
|
||||||
|
The Documentation Writer generates technical docs, diagrams, and maintains code-documentation parity.
|
||||||
|
|
||||||
|
This agent is ideal for:
|
||||||
|
- Generating technical documentation
|
||||||
|
- Creating diagrams
|
||||||
|
- Keeping docs in sync with code
|
||||||
|
- API documentation
|
||||||
|
|
||||||
|
To get the best results, consider:
|
||||||
|
- Provide clear context and requirements
|
||||||
|
- Review generated docs for accuracy
|
||||||
|
- Update docs with code changes
|
||||||
|
- Use consistent documentation style
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*This collection includes 8 curated items for **Gem Team Multi-Agent Orchestration**.*
|
||||||
15
collections/ospo-sponsorship.collection.yml
Normal file
15
collections/ospo-sponsorship.collection.yml
Normal file
@@ -0,0 +1,15 @@
|
|||||||
|
id: ospo-sponsorship
|
||||||
|
name: Open Source Sponsorship
|
||||||
|
description: Tools and resources for Open Source Program Offices (OSPOs) to identify, evaluate, and manage sponsorship of open source dependencies through GitHub Sponsors, Open Collective, and other funding platforms.
|
||||||
|
tags: [ospo, sponsorship, open-source, funding, github-sponsors]
|
||||||
|
items:
|
||||||
|
# Agent Skills
|
||||||
|
- path: skills/sponsor-finder/SKILL.md
|
||||||
|
kind: skill
|
||||||
|
usage: |
|
||||||
|
Find which of a GitHub repository's dependencies are sponsorable via GitHub Sponsors.
|
||||||
|
Invoke by providing a GitHub owner/repo (e.g., "find sponsorable dependencies in expressjs/express").
|
||||||
|
display:
|
||||||
|
ordering: alpha # or "manual" to preserve the order above
|
||||||
|
show_badge: true # set to true to show collection badge on items
|
||||||
|
featured: false
|
||||||
22
collections/ospo-sponsorship.md
Normal file
22
collections/ospo-sponsorship.md
Normal file
@@ -0,0 +1,22 @@
|
|||||||
|
# Open Source Sponsorship
|
||||||
|
|
||||||
|
Tools and resources for Open Source Program Offices (OSPOs) to identify, evaluate, and manage sponsorship of open source dependencies through GitHub Sponsors, Open Collective, and other funding platforms.
|
||||||
|
|
||||||
|
**Tags:** ospo, sponsorship, open-source, funding, github-sponsors
|
||||||
|
|
||||||
|
## Items in this Collection
|
||||||
|
|
||||||
|
| Title | Type | Description |
|
||||||
|
| ----- | ---- | ----------- |
|
||||||
|
| [Sponsor Finder](../skills/sponsor-finder/SKILL.md) | Skill | Find which of a GitHub repository's dependencies are sponsorable via GitHub Sponsors. Uses deps.dev API for dependency resolution across npm, PyPI, Cargo, Go, RubyGems, Maven, and NuGet. Checks npm funding metadata, FUNDING.yml files, and web search. Verifies every link. Shows direct and transitive dependencies with OSSF Scorecard health data. Invoke by providing a GitHub owner/repo (e.g. "find sponsorable dependencies in expressjs/express"). [see usage](#sponsor-finder) |
|
||||||
|
|
||||||
|
## Collection Usage
|
||||||
|
|
||||||
|
### Sponsor Finder
|
||||||
|
|
||||||
|
Find which of a GitHub repository's dependencies are sponsorable via GitHub Sponsors.
|
||||||
|
Invoke by providing a GitHub owner/repo (e.g., "find sponsorable dependencies in expressjs/express").
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*This collection includes 1 curated items for **Open Source Sponsorship**.*
|
||||||
@@ -73,6 +73,14 @@ Custom agents for GitHub Copilot, making it easy for users and organizations to
|
|||||||
| [Expert .NET software engineer mode instructions](../agents/expert-dotnet-software-engineer.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fexpert-dotnet-software-engineer.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fexpert-dotnet-software-engineer.agent.md) | Provide expert .NET software engineering guidance using modern software design patterns. | |
|
| [Expert .NET software engineer mode instructions](../agents/expert-dotnet-software-engineer.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fexpert-dotnet-software-engineer.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fexpert-dotnet-software-engineer.agent.md) | Provide expert .NET software engineering guidance using modern software design patterns. | |
|
||||||
| [Expert React Frontend Engineer](../agents/expert-react-frontend-engineer.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fexpert-react-frontend-engineer.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fexpert-react-frontend-engineer.agent.md) | Expert React 19.2 frontend engineer specializing in modern hooks, Server Components, Actions, TypeScript, and performance optimization | |
|
| [Expert React Frontend Engineer](../agents/expert-react-frontend-engineer.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fexpert-react-frontend-engineer.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fexpert-react-frontend-engineer.agent.md) | Expert React 19.2 frontend engineer specializing in modern hooks, Server Components, Actions, TypeScript, and performance optimization | |
|
||||||
| [Fedora Linux Expert](../agents/fedora-linux-expert.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Ffedora-linux-expert.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Ffedora-linux-expert.agent.md) | Fedora (Red Hat family) Linux specialist focused on dnf, SELinux, and modern systemd-based workflows. | |
|
| [Fedora Linux Expert](../agents/fedora-linux-expert.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Ffedora-linux-expert.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Ffedora-linux-expert.agent.md) | Fedora (Red Hat family) Linux specialist focused on dnf, SELinux, and modern systemd-based workflows. | |
|
||||||
|
| [Gem Chrome Tester](../agents/gem-chrome-tester.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-chrome-tester.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-chrome-tester.agent.md) | Automates browser testing, UI/UX validation via Chrome DevTools | |
|
||||||
|
| [Gem Devops](../agents/gem-devops.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-devops.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-devops.agent.md) | Manages containers, CI/CD pipelines, and infrastructure deployment | |
|
||||||
|
| [Gem Documentation Writer](../agents/gem-documentation-writer.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-documentation-writer.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-documentation-writer.agent.md) | Generates technical docs, diagrams, maintains code-documentation parity | |
|
||||||
|
| [Gem Implementer](../agents/gem-implementer.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-implementer.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-implementer.agent.md) | Executes TDD code changes, ensures verification, maintains quality | |
|
||||||
|
| [Gem Orchestrator](../agents/gem-orchestrator.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-orchestrator.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-orchestrator.agent.md) | Coordinates multi-agent workflows, delegates tasks, synthesizes results via runSubagent | |
|
||||||
|
| [Gem Planner](../agents/gem-planner.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-planner.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-planner.agent.md) | Creates DAG-based plans with pre-mortem analysis and task decomposition from research findings | |
|
||||||
|
| [Gem Researcher](../agents/gem-researcher.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-researcher.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-researcher.agent.md) | Research specialist: gathers codebase context, identifies relevant files/patterns, returns structured findings | |
|
||||||
|
| [Gem Reviewer](../agents/gem-reviewer.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-reviewer.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgem-reviewer.agent.md) | Security gatekeeper for critical tasks—OWASP, secrets, compliance | |
|
||||||
| [Gilfoyle Code Review Mode](../agents/gilfoyle.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgilfoyle.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgilfoyle.agent.md) | Code review and analysis with the sardonic wit and technical elitism of Bertram Gilfoyle from Silicon Valley. Prepare for brutal honesty about your code. | |
|
| [Gilfoyle Code Review Mode](../agents/gilfoyle.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgilfoyle.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgilfoyle.agent.md) | Code review and analysis with the sardonic wit and technical elitism of Bertram Gilfoyle from Silicon Valley. Prepare for brutal honesty about your code. | |
|
||||||
| [GitHub Actions Expert](../agents/github-actions-expert.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgithub-actions-expert.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgithub-actions-expert.agent.md) | GitHub Actions specialist focused on secure CI/CD workflows, action pinning, OIDC authentication, permissions least privilege, and supply-chain security | |
|
| [GitHub Actions Expert](../agents/github-actions-expert.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgithub-actions-expert.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgithub-actions-expert.agent.md) | GitHub Actions specialist focused on secure CI/CD workflows, action pinning, OIDC authentication, permissions least privilege, and supply-chain security | |
|
||||||
| [Go MCP Server Development Expert](../agents/go-mcp-expert.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgo-mcp-expert.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgo-mcp-expert.agent.md) | Expert assistant for building Model Context Protocol (MCP) servers in Go using the official SDK. | |
|
| [Go MCP Server Development Expert](../agents/go-mcp-expert.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgo-mcp-expert.agent.md)<br />[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgo-mcp-expert.agent.md) | Expert assistant for building Model Context Protocol (MCP) servers in Go using the official SDK. | |
|
||||||
|
|||||||
@@ -29,11 +29,13 @@ Curated collections of related prompts, instructions, and agents organized aroun
|
|||||||
| [Dataverse SDK for Python](../collections/dataverse-sdk-for-python.md) | Comprehensive collection for building production-ready Python integrations with Microsoft Dataverse. Includes official documentation, best practices, advanced features, file operations, and code generation prompts. | 17 items | dataverse, python, integration, sdk |
|
| [Dataverse SDK for Python](../collections/dataverse-sdk-for-python.md) | Comprehensive collection for building production-ready Python integrations with Microsoft Dataverse. Includes official documentation, best practices, advanced features, file operations, and code generation prompts. | 17 items | dataverse, python, integration, sdk |
|
||||||
| [DevOps On-Call](../collections/devops-oncall.md) | A focused set of prompts, instructions, and a chat mode to help triage incidents and respond quickly with DevOps tools and Azure resources. | 5 items | devops, incident-response, oncall, azure |
|
| [DevOps On-Call](../collections/devops-oncall.md) | A focused set of prompts, instructions, and a chat mode to help triage incidents and respond quickly with DevOps tools and Azure resources. | 5 items | devops, incident-response, oncall, azure |
|
||||||
| [Frontend Web Development](../collections/frontend-web-dev.md) | Essential prompts, instructions, and chat modes for modern frontend web development including React, Angular, Vue, TypeScript, and CSS frameworks. | 11 items | frontend, web, react, typescript, javascript, css, html, angular, vue |
|
| [Frontend Web Development](../collections/frontend-web-dev.md) | Essential prompts, instructions, and chat modes for modern frontend web development including React, Angular, Vue, TypeScript, and CSS frameworks. | 11 items | frontend, web, react, typescript, javascript, css, html, angular, vue |
|
||||||
|
| [Gem Team Multi-Agent Orchestration](../collections/gem-team.md) | A modular multi-agent team for complex project execution with DAG-based planning, parallel execution, TDD verification, and automated testing. | 8 items | multi-agent, orchestration, dag-planning, parallel-execution, tdd, verification, automation, security |
|
||||||
| [Go MCP Server Development](../collections/go-mcp-development.md) | Complete toolkit for building Model Context Protocol (MCP) servers in Go using the official github.com/modelcontextprotocol/go-sdk. Includes instructions for best practices, a prompt for generating servers, and an expert chat mode for guidance. | 3 items | go, golang, mcp, model-context-protocol, server-development, sdk |
|
| [Go MCP Server Development](../collections/go-mcp-development.md) | Complete toolkit for building Model Context Protocol (MCP) servers in Go using the official github.com/modelcontextprotocol/go-sdk. Includes instructions for best practices, a prompt for generating servers, and an expert chat mode for guidance. | 3 items | go, golang, mcp, model-context-protocol, server-development, sdk |
|
||||||
| [Java Development](../collections/java-development.md) | Comprehensive collection of prompts and instructions for Java development including Spring Boot, Quarkus, testing, documentation, and best practices. | 12 items | java, springboot, quarkus, jpa, junit, javadoc |
|
| [Java Development](../collections/java-development.md) | Comprehensive collection of prompts and instructions for Java development including Spring Boot, Quarkus, testing, documentation, and best practices. | 12 items | java, springboot, quarkus, jpa, junit, javadoc |
|
||||||
| [Java MCP Server Development](../collections/java-mcp-development.md) | Complete toolkit for building Model Context Protocol servers in Java using the official MCP Java SDK with reactive streams and Spring Boot integration. | 3 items | java, mcp, model-context-protocol, server-development, sdk, reactive-streams, spring-boot, reactor |
|
| [Java MCP Server Development](../collections/java-mcp-development.md) | Complete toolkit for building Model Context Protocol servers in Java using the official MCP Java SDK with reactive streams and Spring Boot integration. | 3 items | java, mcp, model-context-protocol, server-development, sdk, reactive-streams, spring-boot, reactor |
|
||||||
| [Kotlin MCP Server Development](../collections/kotlin-mcp-development.md) | Complete toolkit for building Model Context Protocol (MCP) servers in Kotlin using the official io.modelcontextprotocol:kotlin-sdk library. Includes instructions for best practices, a prompt for generating servers, and an expert chat mode for guidance. | 3 items | kotlin, mcp, model-context-protocol, kotlin-multiplatform, server-development, ktor |
|
| [Kotlin MCP Server Development](../collections/kotlin-mcp-development.md) | Complete toolkit for building Model Context Protocol (MCP) servers in Kotlin using the official io.modelcontextprotocol:kotlin-sdk library. Includes instructions for best practices, a prompt for generating servers, and an expert chat mode for guidance. | 3 items | kotlin, mcp, model-context-protocol, kotlin-multiplatform, server-development, ktor |
|
||||||
| [MCP-based M365 Agents](../collections/mcp-m365-copilot.md) | Comprehensive collection for building declarative agents with Model Context Protocol integration for Microsoft 365 Copilot | 5 items | mcp, m365-copilot, declarative-agents, api-plugins, model-context-protocol, adaptive-cards |
|
| [MCP-based M365 Agents](../collections/mcp-m365-copilot.md) | Comprehensive collection for building declarative agents with Model Context Protocol integration for Microsoft 365 Copilot | 5 items | mcp, m365-copilot, declarative-agents, api-plugins, model-context-protocol, adaptive-cards |
|
||||||
|
| [Open Source Sponsorship](../collections/ospo-sponsorship.md) | Tools and resources for Open Source Program Offices (OSPOs) to identify, evaluate, and manage sponsorship of open source dependencies through GitHub Sponsors, Open Collective, and other funding platforms. | 1 items | ospo, sponsorship, open-source, funding, github-sponsors |
|
||||||
| [OpenAPI to Application - C# .NET](../collections/openapi-to-application-csharp-dotnet.md) | Generate production-ready .NET applications from OpenAPI specifications. Includes ASP.NET Core project scaffolding, controller generation, entity framework integration, and C# best practices. | 3 items | openapi, code-generation, api, csharp, dotnet, aspnet |
|
| [OpenAPI to Application - C# .NET](../collections/openapi-to-application-csharp-dotnet.md) | Generate production-ready .NET applications from OpenAPI specifications. Includes ASP.NET Core project scaffolding, controller generation, entity framework integration, and C# best practices. | 3 items | openapi, code-generation, api, csharp, dotnet, aspnet |
|
||||||
| [OpenAPI to Application - Go](../collections/openapi-to-application-go.md) | Generate production-ready Go applications from OpenAPI specifications. Includes project scaffolding, handler generation, middleware setup, and Go best practices for REST APIs. | 3 items | openapi, code-generation, api, go, golang |
|
| [OpenAPI to Application - Go](../collections/openapi-to-application-go.md) | Generate production-ready Go applications from OpenAPI specifications. Includes project scaffolding, handler generation, middleware setup, and Go best practices for REST APIs. | 3 items | openapi, code-generation, api, go, golang |
|
||||||
| [OpenAPI to Application - Java Spring Boot](../collections/openapi-to-application-java-spring-boot.md) | Generate production-ready Spring Boot applications from OpenAPI specifications. Includes project scaffolding, REST controller generation, service layer organization, and Spring Boot best practices. | 3 items | openapi, code-generation, api, java, spring-boot |
|
| [OpenAPI to Application - Java Spring Boot](../collections/openapi-to-application-java-spring-boot.md) | Generate production-ready Spring Boot applications from OpenAPI specifications. Includes project scaffolding, REST controller generation, service layer organization, and Spring Boot best practices. | 3 items | openapi, code-generation, api, java, spring-boot |
|
||||||
|
|||||||
@@ -24,12 +24,14 @@ Skills differ from other primitives by supporting bundled assets (scripts, code
|
|||||||
| ---- | ----------- | -------------- |
|
| ---- | ----------- | -------------- |
|
||||||
| [agentic-eval](../skills/agentic-eval/SKILL.md) | Patterns and techniques for evaluating and improving AI agent outputs. Use this skill when:<br />- Implementing self-critique and reflection loops<br />- Building evaluator-optimizer pipelines for quality-critical generation<br />- Creating test-driven code refinement workflows<br />- Designing rubric-based or LLM-as-judge evaluation systems<br />- Adding iterative improvement to agent outputs (code, reports, analysis)<br />- Measuring and improving agent response quality | None |
|
| [agentic-eval](../skills/agentic-eval/SKILL.md) | Patterns and techniques for evaluating and improving AI agent outputs. Use this skill when:<br />- Implementing self-critique and reflection loops<br />- Building evaluator-optimizer pipelines for quality-critical generation<br />- Creating test-driven code refinement workflows<br />- Designing rubric-based or LLM-as-judge evaluation systems<br />- Adding iterative improvement to agent outputs (code, reports, analysis)<br />- Measuring and improving agent response quality | None |
|
||||||
| [appinsights-instrumentation](../skills/appinsights-instrumentation/SKILL.md) | Instrument a webapp to send useful telemetry data to Azure App Insights | `LICENSE.txt`<br />`examples/appinsights.bicep`<br />`references/ASPNETCORE.md`<br />`references/AUTO.md`<br />`references/NODEJS.md`<br />`references/PYTHON.md`<br />`scripts/appinsights.ps1` |
|
| [appinsights-instrumentation](../skills/appinsights-instrumentation/SKILL.md) | Instrument a webapp to send useful telemetry data to Azure App Insights | `LICENSE.txt`<br />`examples/appinsights.bicep`<br />`references/ASPNETCORE.md`<br />`references/AUTO.md`<br />`references/NODEJS.md`<br />`references/PYTHON.md`<br />`scripts/appinsights.ps1` |
|
||||||
|
| [aspire](../skills/aspire/SKILL.md) | Aspire skill covering the Aspire CLI, AppHost orchestration, service discovery, integrations, MCP server, VS Code extension, Dev Containers, GitHub Codespaces, templates, dashboard, and deployment. Use when the user asks to create, run, debug, configure, deploy, or troubleshoot an Aspire distributed application. | `references/architecture.md`<br />`references/cli-reference.md`<br />`references/dashboard.md`<br />`references/deployment.md`<br />`references/integrations-catalog.md`<br />`references/mcp-server.md`<br />`references/polyglot-apis.md`<br />`references/testing.md`<br />`references/troubleshooting.md` |
|
||||||
| [azure-deployment-preflight](../skills/azure-deployment-preflight/SKILL.md) | Performs comprehensive preflight validation of Bicep deployments to Azure, including template syntax validation, what-if analysis, and permission checks. Use this skill before any deployment to Azure to preview changes, identify potential issues, and ensure the deployment will succeed. Activate when users mention deploying to Azure, validating Bicep files, checking deployment permissions, previewing infrastructure changes, running what-if, or preparing for azd provision. | `references/ERROR-HANDLING.md`<br />`references/REPORT-TEMPLATE.md`<br />`references/VALIDATION-COMMANDS.md` |
|
| [azure-deployment-preflight](../skills/azure-deployment-preflight/SKILL.md) | Performs comprehensive preflight validation of Bicep deployments to Azure, including template syntax validation, what-if analysis, and permission checks. Use this skill before any deployment to Azure to preview changes, identify potential issues, and ensure the deployment will succeed. Activate when users mention deploying to Azure, validating Bicep files, checking deployment permissions, previewing infrastructure changes, running what-if, or preparing for azd provision. | `references/ERROR-HANDLING.md`<br />`references/REPORT-TEMPLATE.md`<br />`references/VALIDATION-COMMANDS.md` |
|
||||||
| [azure-devops-cli](../skills/azure-devops-cli/SKILL.md) | Manage Azure DevOps resources via CLI including projects, repos, pipelines, builds, pull requests, work items, artifacts, and service endpoints. Use when working with Azure DevOps, az commands, devops automation, CI/CD, or when user mentions Azure DevOps CLI. | None |
|
| [azure-devops-cli](../skills/azure-devops-cli/SKILL.md) | Manage Azure DevOps resources via CLI including projects, repos, pipelines, builds, pull requests, work items, artifacts, and service endpoints. Use when working with Azure DevOps, az commands, devops automation, CI/CD, or when user mentions Azure DevOps CLI. | None |
|
||||||
| [azure-resource-visualizer](../skills/azure-resource-visualizer/SKILL.md) | Analyze Azure resource groups and generate detailed Mermaid architecture diagrams showing the relationships between individual resources. Use this skill when the user asks for a diagram of their Azure resources or help in understanding how the resources relate to each other. | `LICENSE.txt`<br />`assets/template-architecture.md` |
|
| [azure-resource-visualizer](../skills/azure-resource-visualizer/SKILL.md) | Analyze Azure resource groups and generate detailed Mermaid architecture diagrams showing the relationships between individual resources. Use this skill when the user asks for a diagram of their Azure resources or help in understanding how the resources relate to each other. | `LICENSE.txt`<br />`assets/template-architecture.md` |
|
||||||
| [azure-role-selector](../skills/azure-role-selector/SKILL.md) | When user is asking for guidance for which role to assign to an identity given desired permissions, this agent helps them understand the role that will meet the requirements with least privilege access and how to apply that role. | `LICENSE.txt` |
|
| [azure-role-selector](../skills/azure-role-selector/SKILL.md) | When user is asking for guidance for which role to assign to an identity given desired permissions, this agent helps them understand the role that will meet the requirements with least privilege access and how to apply that role. | `LICENSE.txt` |
|
||||||
| [azure-static-web-apps](../skills/azure-static-web-apps/SKILL.md) | Helps create, configure, and deploy Azure Static Web Apps using the SWA CLI. Use when deploying static sites to Azure, setting up SWA local development, configuring staticwebapp.config.json, adding Azure Functions APIs to SWA, or setting up GitHub Actions CI/CD for Static Web Apps. | None |
|
| [azure-static-web-apps](../skills/azure-static-web-apps/SKILL.md) | Helps create, configure, and deploy Azure Static Web Apps using the SWA CLI. Use when deploying static sites to Azure, setting up SWA local development, configuring staticwebapp.config.json, adding Azure Functions APIs to SWA, or setting up GitHub Actions CI/CD for Static Web Apps. | None |
|
||||||
| [chrome-devtools](../skills/chrome-devtools/SKILL.md) | Expert-level browser automation, debugging, and performance analysis using Chrome DevTools MCP. Use for interacting with web pages, capturing screenshots, analyzing network traffic, and profiling performance. | None |
|
| [chrome-devtools](../skills/chrome-devtools/SKILL.md) | Expert-level browser automation, debugging, and performance analysis using Chrome DevTools MCP. Use for interacting with web pages, capturing screenshots, analyzing network traffic, and profiling performance. | None |
|
||||||
|
| [copilot-cli-quickstart](../skills/copilot-cli-quickstart/SKILL.md) | Use this skill when someone wants to learn GitHub Copilot CLI from scratch. Offers interactive step-by-step tutorials with separate Developer and Non-Developer tracks, plus on-demand Q&A. Just say "start tutorial" or ask a question! Note: This skill targets GitHub Copilot CLI specifically and uses CLI-specific tools (ask_user, sql, fetch_copilot_cli_documentation). | None |
|
||||||
| [copilot-sdk](../skills/copilot-sdk/SKILL.md) | Build agentic applications with GitHub Copilot SDK. Use when embedding AI agents in apps, creating custom tools, implementing streaming responses, managing sessions, connecting to MCP servers, or creating custom agents. Triggers on Copilot SDK, GitHub SDK, agentic app, embed Copilot, programmable agent, MCP server, custom agent. | None |
|
| [copilot-sdk](../skills/copilot-sdk/SKILL.md) | Build agentic applications with GitHub Copilot SDK. Use when embedding AI agents in apps, creating custom tools, implementing streaming responses, managing sessions, connecting to MCP servers, or creating custom agents. Triggers on Copilot SDK, GitHub SDK, agentic app, embed Copilot, programmable agent, MCP server, custom agent. | None |
|
||||||
| [create-web-form](../skills/create-web-form/SKILL.md) | Create robust, accessible web forms with best practices for HTML structure, CSS styling, JavaScript interactivity, form validation, and server-side processing. Use when asked to "create a form", "build a web form", "add a contact form", "make a signup form", or when building any HTML form with data handling. Covers PHP and Python backends, MySQL database integration, REST APIs, XML data exchange, accessibility (ARIA), and progressive web apps. | `references/accessibility.md`<br />`references/aria-form-role.md`<br />`references/css-styling.md`<br />`references/form-basics.md`<br />`references/form-controls.md`<br />`references/form-data-handling.md`<br />`references/html-form-elements.md`<br />`references/html-form-example.md`<br />`references/hypertext-transfer-protocol.md`<br />`references/javascript.md`<br />`references/php-cookies.md`<br />`references/php-forms.md`<br />`references/php-json.md`<br />`references/php-mysql-database.md`<br />`references/progressive-web-app.md`<br />`references/python-as-web-framework.md`<br />`references/python-contact-form.md`<br />`references/python-flask-app.md`<br />`references/python-flask.md`<br />`references/security.md`<br />`references/styling-web-forms.md`<br />`references/web-api.md`<br />`references/web-performance.md`<br />`references/xml.md` |
|
| [create-web-form](../skills/create-web-form/SKILL.md) | Create robust, accessible web forms with best practices for HTML structure, CSS styling, JavaScript interactivity, form validation, and server-side processing. Use when asked to "create a form", "build a web form", "add a contact form", "make a signup form", or when building any HTML form with data handling. Covers PHP and Python backends, MySQL database integration, REST APIs, XML data exchange, accessibility (ARIA), and progressive web apps. | `references/accessibility.md`<br />`references/aria-form-role.md`<br />`references/css-styling.md`<br />`references/form-basics.md`<br />`references/form-controls.md`<br />`references/form-data-handling.md`<br />`references/html-form-elements.md`<br />`references/html-form-example.md`<br />`references/hypertext-transfer-protocol.md`<br />`references/javascript.md`<br />`references/php-cookies.md`<br />`references/php-forms.md`<br />`references/php-json.md`<br />`references/php-mysql-database.md`<br />`references/progressive-web-app.md`<br />`references/python-as-web-framework.md`<br />`references/python-contact-form.md`<br />`references/python-flask-app.md`<br />`references/python-flask.md`<br />`references/security.md`<br />`references/styling-web-forms.md`<br />`references/web-api.md`<br />`references/web-performance.md`<br />`references/xml.md` |
|
||||||
| [excalidraw-diagram-generator](../skills/excalidraw-diagram-generator/SKILL.md) | Generate Excalidraw diagrams from natural language descriptions. Use when asked to "create a diagram", "make a flowchart", "visualize a process", "draw a system architecture", "create a mind map", or "generate an Excalidraw file". Supports flowcharts, relationship diagrams, mind maps, and system architecture diagrams. Outputs .excalidraw JSON files that can be opened directly in Excalidraw. | `references/element-types.md`<br />`references/excalidraw-schema.md`<br />`scripts/.gitignore`<br />`scripts/README.md`<br />`scripts/add-arrow.py`<br />`scripts/add-icon-to-diagram.py`<br />`scripts/split-excalidraw-library.py`<br />`templates/business-flow-swimlane-template.excalidraw`<br />`templates/class-diagram-template.excalidraw`<br />`templates/data-flow-diagram-template.excalidraw`<br />`templates/er-diagram-template.excalidraw`<br />`templates/flowchart-template.excalidraw`<br />`templates/mindmap-template.excalidraw`<br />`templates/relationship-template.excalidraw`<br />`templates/sequence-diagram-template.excalidraw` |
|
| [excalidraw-diagram-generator](../skills/excalidraw-diagram-generator/SKILL.md) | Generate Excalidraw diagrams from natural language descriptions. Use when asked to "create a diagram", "make a flowchart", "visualize a process", "draw a system architecture", "create a mind map", or "generate an Excalidraw file". Supports flowcharts, relationship diagrams, mind maps, and system architecture diagrams. Outputs .excalidraw JSON files that can be opened directly in Excalidraw. | `references/element-types.md`<br />`references/excalidraw-schema.md`<br />`scripts/.gitignore`<br />`scripts/README.md`<br />`scripts/add-arrow.py`<br />`scripts/add-icon-to-diagram.py`<br />`scripts/split-excalidraw-library.py`<br />`templates/business-flow-swimlane-template.excalidraw`<br />`templates/class-diagram-template.excalidraw`<br />`templates/data-flow-diagram-template.excalidraw`<br />`templates/er-diagram-template.excalidraw`<br />`templates/flowchart-template.excalidraw`<br />`templates/mindmap-template.excalidraw`<br />`templates/relationship-template.excalidraw`<br />`templates/sequence-diagram-template.excalidraw` |
|
||||||
@@ -55,6 +57,7 @@ Skills differ from other primitives by supporting bundled assets (scripts, code
|
|||||||
| [refactor](../skills/refactor/SKILL.md) | Surgical code refactoring to improve maintainability without changing behavior. Covers extracting functions, renaming variables, breaking down god functions, improving type safety, eliminating code smells, and applying design patterns. Less drastic than repo-rebuilder; use for gradual improvements. | None |
|
| [refactor](../skills/refactor/SKILL.md) | Surgical code refactoring to improve maintainability without changing behavior. Covers extracting functions, renaming variables, breaking down god functions, improving type safety, eliminating code smells, and applying design patterns. Less drastic than repo-rebuilder; use for gradual improvements. | None |
|
||||||
| [scoutqa-test](../skills/scoutqa-test/SKILL.md) | This skill should be used when the user asks to "test this website", "run exploratory testing", "check for accessibility issues", "verify the login flow works", "find bugs on this page", or requests automated QA testing. Triggers on web application testing scenarios including smoke tests, accessibility audits, e-commerce flows, and user flow validation using ScoutQA CLI. IMPORTANT: Use this skill proactively after implementing web application features to verify they work correctly - don't wait for the user to ask for testing. | None |
|
| [scoutqa-test](../skills/scoutqa-test/SKILL.md) | This skill should be used when the user asks to "test this website", "run exploratory testing", "check for accessibility issues", "verify the login flow works", "find bugs on this page", or requests automated QA testing. Triggers on web application testing scenarios including smoke tests, accessibility audits, e-commerce flows, and user flow validation using ScoutQA CLI. IMPORTANT: Use this skill proactively after implementing web application features to verify they work correctly - don't wait for the user to ask for testing. | None |
|
||||||
| [snowflake-semanticview](../skills/snowflake-semanticview/SKILL.md) | Create, alter, and validate Snowflake semantic views using Snowflake CLI (snow). Use when asked to build or troubleshoot semantic views/semantic layer definitions with CREATE/ALTER SEMANTIC VIEW, to validate semantic-view DDL against Snowflake via CLI, or to guide Snowflake CLI installation and connection setup. | None |
|
| [snowflake-semanticview](../skills/snowflake-semanticview/SKILL.md) | Create, alter, and validate Snowflake semantic views using Snowflake CLI (snow). Use when asked to build or troubleshoot semantic views/semantic layer definitions with CREATE/ALTER SEMANTIC VIEW, to validate semantic-view DDL against Snowflake via CLI, or to guide Snowflake CLI installation and connection setup. | None |
|
||||||
|
| [sponsor-finder](../skills/sponsor-finder/SKILL.md) | Find which of a GitHub repository's dependencies are sponsorable via GitHub Sponsors. Uses deps.dev API for dependency resolution across npm, PyPI, Cargo, Go, RubyGems, Maven, and NuGet. Checks npm funding metadata, FUNDING.yml files, and web search. Verifies every link. Shows direct and transitive dependencies with OSSF Scorecard health data. Invoke by providing a GitHub owner/repo (e.g. "find sponsorable dependencies in expressjs/express"). | None |
|
||||||
| [terraform-azurerm-set-diff-analyzer](../skills/terraform-azurerm-set-diff-analyzer/SKILL.md) | Analyze Terraform plan JSON output for AzureRM Provider to distinguish between false-positive diffs (order-only changes in Set-type attributes) and actual resource changes. Use when reviewing terraform plan output for Azure resources like Application Gateway, Load Balancer, Firewall, Front Door, NSG, and other resources with Set-type attributes that cause spurious diffs due to internal ordering changes. | `references/azurerm_set_attributes.json`<br />`references/azurerm_set_attributes.md`<br />`scripts/.gitignore`<br />`scripts/README.md`<br />`scripts/analyze_plan.py` |
|
| [terraform-azurerm-set-diff-analyzer](../skills/terraform-azurerm-set-diff-analyzer/SKILL.md) | Analyze Terraform plan JSON output for AzureRM Provider to distinguish between false-positive diffs (order-only changes in Set-type attributes) and actual resource changes. Use when reviewing terraform plan output for Azure resources like Application Gateway, Load Balancer, Firewall, Front Door, NSG, and other resources with Set-type attributes that cause spurious diffs due to internal ordering changes. | `references/azurerm_set_attributes.json`<br />`references/azurerm_set_attributes.md`<br />`scripts/.gitignore`<br />`scripts/README.md`<br />`scripts/analyze_plan.py` |
|
||||||
| [vscode-ext-commands](../skills/vscode-ext-commands/SKILL.md) | Guidelines for contributing commands in VS Code extensions. Indicates naming convention, visibility, localization and other relevant attributes, following VS Code extension development guidelines, libraries and good practices | None |
|
| [vscode-ext-commands](../skills/vscode-ext-commands/SKILL.md) | Guidelines for contributing commands in VS Code extensions. Indicates naming convention, visibility, localization and other relevant attributes, following VS Code extension development guidelines, libraries and good practices | None |
|
||||||
| [vscode-ext-localization](../skills/vscode-ext-localization/SKILL.md) | Guidelines for proper localization of VS Code extensions, following VS Code extension development guidelines, libraries and good practices | None |
|
| [vscode-ext-localization](../skills/vscode-ext-localization/SKILL.md) | Guidelines for proper localization of VS Code extensions, following VS Code extension development guidelines, libraries and good practices | None |
|
||||||
|
|||||||
@@ -1,6 +1,30 @@
|
|||||||
# Contributor Reporting (Maintainers) 🚧
|
# Contributor Reporting (Maintainers) 🚧
|
||||||
|
|
||||||
This directory contains a lightweight helper to generate human-readable reports about missing contributors.
|
This directory contains build scripts and utilities for maintaining the repository.
|
||||||
|
|
||||||
|
## Build Scripts
|
||||||
|
|
||||||
|
### `update-readme.mjs`
|
||||||
|
Generates the main README.md and documentation files from the repository content (agents, prompts, instructions, skills, hooks, collections).
|
||||||
|
|
||||||
|
### `generate-marketplace.mjs`
|
||||||
|
Automatically generates `.github/plugin/marketplace.json` from all plugin directories in the `plugins/` folder. This file is used by the GitHub Copilot CLI to discover and install plugins from this repository.
|
||||||
|
|
||||||
|
**How it works:**
|
||||||
|
- Scans all directories in `plugins/`
|
||||||
|
- Reads each plugin's `.github/plugin/plugin.json` for metadata
|
||||||
|
- Generates a consolidated `marketplace.json` with all available plugins
|
||||||
|
- Runs automatically as part of `npm run build`
|
||||||
|
|
||||||
|
**To run manually:**
|
||||||
|
```bash
|
||||||
|
npm run plugin:generate-marketplace
|
||||||
|
```
|
||||||
|
|
||||||
|
### `generate-website-data.mjs`
|
||||||
|
Generates JSON data files for the website from repository content.
|
||||||
|
|
||||||
|
## Contributor Tools
|
||||||
|
|
||||||
- `contributor-report.mjs` — generates a markdown report of merged PRs for missing contributors (includes shared helpers).
|
- `contributor-report.mjs` — generates a markdown report of merged PRs for missing contributors (includes shared helpers).
|
||||||
- `add-missing-contributors.mjs` — on-demand maintainer script to automatically add missing contributors to `.all-contributorsrc` (infers contribution types from merged PR files, then runs the all-contributors CLI).
|
- `add-missing-contributors.mjs` — on-demand maintainer script to automatically add missing contributors to `.all-contributorsrc` (infers contribution types from merged PR files, then runs the all-contributors CLI).
|
||||||
|
|||||||
99
eng/generate-marketplace.mjs
Executable file
99
eng/generate-marketplace.mjs
Executable file
@@ -0,0 +1,99 @@
|
|||||||
|
#!/usr/bin/env node
|
||||||
|
|
||||||
|
import fs from "fs";
|
||||||
|
import path from "path";
|
||||||
|
import { ROOT_FOLDER } from "./constants.mjs";
|
||||||
|
|
||||||
|
const PLUGINS_DIR = path.join(ROOT_FOLDER, "plugins");
|
||||||
|
const MARKETPLACE_FILE = path.join(ROOT_FOLDER, ".github", "plugin", "marketplace.json");
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Read plugin metadata from plugin.json file
|
||||||
|
* @param {string} pluginDir - Path to plugin directory
|
||||||
|
* @returns {object|null} - Plugin metadata or null if not found
|
||||||
|
*/
|
||||||
|
function readPluginMetadata(pluginDir) {
|
||||||
|
const pluginJsonPath = path.join(pluginDir, ".github", "plugin", "plugin.json");
|
||||||
|
|
||||||
|
if (!fs.existsSync(pluginJsonPath)) {
|
||||||
|
console.warn(`Warning: No plugin.json found for ${path.basename(pluginDir)}`);
|
||||||
|
return null;
|
||||||
|
}
|
||||||
|
|
||||||
|
try {
|
||||||
|
const content = fs.readFileSync(pluginJsonPath, "utf8");
|
||||||
|
return JSON.parse(content);
|
||||||
|
} catch (error) {
|
||||||
|
console.error(`Error reading plugin.json for ${path.basename(pluginDir)}:`, error.message);
|
||||||
|
return null;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Generate marketplace.json from plugin directories
|
||||||
|
*/
|
||||||
|
function generateMarketplace() {
|
||||||
|
console.log("Generating marketplace.json...");
|
||||||
|
|
||||||
|
if (!fs.existsSync(PLUGINS_DIR)) {
|
||||||
|
console.error(`Error: Plugins directory not found at ${PLUGINS_DIR}`);
|
||||||
|
process.exit(1);
|
||||||
|
}
|
||||||
|
|
||||||
|
// Read all plugin directories
|
||||||
|
const pluginDirs = fs.readdirSync(PLUGINS_DIR, { withFileTypes: true })
|
||||||
|
.filter(entry => entry.isDirectory())
|
||||||
|
.map(entry => entry.name)
|
||||||
|
.sort();
|
||||||
|
|
||||||
|
console.log(`Found ${pluginDirs.length} plugin directories`);
|
||||||
|
|
||||||
|
// Read metadata for each plugin
|
||||||
|
const plugins = [];
|
||||||
|
for (const dirName of pluginDirs) {
|
||||||
|
const pluginPath = path.join(PLUGINS_DIR, dirName);
|
||||||
|
const metadata = readPluginMetadata(pluginPath);
|
||||||
|
|
||||||
|
if (metadata) {
|
||||||
|
plugins.push({
|
||||||
|
name: metadata.name,
|
||||||
|
source: `./plugins/${dirName}`,
|
||||||
|
description: metadata.description,
|
||||||
|
version: metadata.version || "1.0.0"
|
||||||
|
});
|
||||||
|
console.log(`✓ Added plugin: ${metadata.name}`);
|
||||||
|
} else {
|
||||||
|
console.log(`✗ Skipped: ${dirName} (no valid plugin.json)`);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Create marketplace.json structure
|
||||||
|
const marketplace = {
|
||||||
|
name: "awesome-copilot",
|
||||||
|
metadata: {
|
||||||
|
description: "Community-driven collection of GitHub Copilot plugins, agents, prompts, and skills",
|
||||||
|
version: "1.0.0",
|
||||||
|
pluginRoot: "./plugins"
|
||||||
|
},
|
||||||
|
owner: {
|
||||||
|
name: "GitHub",
|
||||||
|
email: "copilot@github.com"
|
||||||
|
},
|
||||||
|
plugins: plugins
|
||||||
|
};
|
||||||
|
|
||||||
|
// Ensure directory exists
|
||||||
|
const marketplaceDir = path.dirname(MARKETPLACE_FILE);
|
||||||
|
if (!fs.existsSync(marketplaceDir)) {
|
||||||
|
fs.mkdirSync(marketplaceDir, { recursive: true });
|
||||||
|
}
|
||||||
|
|
||||||
|
// Write marketplace.json
|
||||||
|
fs.writeFileSync(MARKETPLACE_FILE, JSON.stringify(marketplace, null, 2) + "\n");
|
||||||
|
|
||||||
|
console.log(`\n✓ Successfully generated marketplace.json with ${plugins.length} plugins`);
|
||||||
|
console.log(` Location: ${MARKETPLACE_FILE}`);
|
||||||
|
}
|
||||||
|
|
||||||
|
// Run the script
|
||||||
|
generateMarketplace();
|
||||||
@@ -6,7 +6,7 @@
|
|||||||
"private": true,
|
"private": true,
|
||||||
"scripts": {
|
"scripts": {
|
||||||
"start": "npm run build",
|
"start": "npm run build",
|
||||||
"build": "node ./eng/update-readme.mjs",
|
"build": "node ./eng/update-readme.mjs && node ./eng/generate-marketplace.mjs",
|
||||||
"contributors:add": "all-contributors add",
|
"contributors:add": "all-contributors add",
|
||||||
"contributors:report": "node ./eng/contributor-report.mjs",
|
"contributors:report": "node ./eng/contributor-report.mjs",
|
||||||
"contributors:generate": "all-contributors generate",
|
"contributors:generate": "all-contributors generate",
|
||||||
@@ -17,6 +17,7 @@
|
|||||||
"skill:create": "node ./eng/create-skill.mjs",
|
"skill:create": "node ./eng/create-skill.mjs",
|
||||||
"plugin:migrate": "node ./eng/collection-to-plugin.mjs",
|
"plugin:migrate": "node ./eng/collection-to-plugin.mjs",
|
||||||
"plugin:refresh": "PLUGIN_MODE=refresh node ./eng/collection-to-plugin.mjs",
|
"plugin:refresh": "PLUGIN_MODE=refresh node ./eng/collection-to-plugin.mjs",
|
||||||
|
"plugin:generate-marketplace": "node ./eng/generate-marketplace.mjs",
|
||||||
"website:data": "node ./eng/generate-website-data.mjs",
|
"website:data": "node ./eng/generate-website-data.mjs",
|
||||||
"website:dev": "npm run website:data && npm run --prefix website dev",
|
"website:dev": "npm run website:data && npm run --prefix website dev",
|
||||||
"website:build": "npm run build && npm run website:data && npm run --prefix website build",
|
"website:build": "npm run build && npm run website:data && npm run --prefix website build",
|
||||||
|
|||||||
10
plugins/gem-team/.github/plugin/plugin.json
vendored
Normal file
10
plugins/gem-team/.github/plugin/plugin.json
vendored
Normal file
@@ -0,0 +1,10 @@
|
|||||||
|
{
|
||||||
|
"name": "gem-team",
|
||||||
|
"description": "A modular multi-agent team for complex project execution with DAG-based planning, parallel execution, TDD verification, and automated testing.",
|
||||||
|
"version": "1.0.0",
|
||||||
|
"author": {
|
||||||
|
"name": "Awesome Copilot Community"
|
||||||
|
},
|
||||||
|
"repository": "https://github.com/github/awesome-copilot",
|
||||||
|
"license": "MIT"
|
||||||
|
}
|
||||||
33
plugins/gem-team/README.md
Normal file
33
plugins/gem-team/README.md
Normal file
@@ -0,0 +1,33 @@
|
|||||||
|
# Gem Team Multi-Agent Orchestration Plugin
|
||||||
|
|
||||||
|
A modular multi-agent team for complex project execution with DAG-based planning, parallel execution, TDD verification, and automated testing.
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Using Copilot CLI
|
||||||
|
copilot plugin install gem-team@awesome-copilot
|
||||||
|
```
|
||||||
|
|
||||||
|
## What's Included
|
||||||
|
|
||||||
|
### Agents
|
||||||
|
|
||||||
|
| Agent | Description |
|
||||||
|
|-------|-------------|
|
||||||
|
| `gem-orchestrator` | Coordinates multi-agent workflows, delegates tasks, synthesizes results via runSubagent |
|
||||||
|
| `gem-researcher` | Research specialist: gathers codebase context, identifies relevant files/patterns, returns structured findings |
|
||||||
|
| `gem-planner` | Creates DAG-based plans with pre-mortem analysis and task decomposition from research findings |
|
||||||
|
| `gem-implementer` | Executes TDD code changes, ensures verification, maintains quality |
|
||||||
|
| `gem-chrome-tester` | Automates browser testing, UI/UX validation via Chrome DevTools |
|
||||||
|
| `gem-devops` | Manages containers, CI/CD pipelines, and infrastructure deployment |
|
||||||
|
| `gem-reviewer` | Security gatekeeper for critical tasks—OWASP, secrets, compliance |
|
||||||
|
| `gem-documentation-writer` | Generates technical docs, diagrams, maintains code-documentation parity |
|
||||||
|
|
||||||
|
## Source
|
||||||
|
|
||||||
|
This plugin is part of [Awesome Copilot](https://github.com/github/awesome-copilot), a community-driven collection of GitHub Copilot extensions.
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
MIT
|
||||||
1
plugins/gem-team/agents/gem-chrome-tester.md
Symbolic link
1
plugins/gem-team/agents/gem-chrome-tester.md
Symbolic link
@@ -0,0 +1 @@
|
|||||||
|
../../../agents/gem-chrome-tester.agent.md
|
||||||
1
plugins/gem-team/agents/gem-devops.md
Symbolic link
1
plugins/gem-team/agents/gem-devops.md
Symbolic link
@@ -0,0 +1 @@
|
|||||||
|
../../../agents/gem-devops.agent.md
|
||||||
1
plugins/gem-team/agents/gem-documentation-writer.md
Symbolic link
1
plugins/gem-team/agents/gem-documentation-writer.md
Symbolic link
@@ -0,0 +1 @@
|
|||||||
|
../../../agents/gem-documentation-writer.agent.md
|
||||||
1
plugins/gem-team/agents/gem-implementer.md
Symbolic link
1
plugins/gem-team/agents/gem-implementer.md
Symbolic link
@@ -0,0 +1 @@
|
|||||||
|
../../../agents/gem-implementer.agent.md
|
||||||
1
plugins/gem-team/agents/gem-orchestrator.md
Symbolic link
1
plugins/gem-team/agents/gem-orchestrator.md
Symbolic link
@@ -0,0 +1 @@
|
|||||||
|
../../../agents/gem-orchestrator.agent.md
|
||||||
1
plugins/gem-team/agents/gem-planner.md
Symbolic link
1
plugins/gem-team/agents/gem-planner.md
Symbolic link
@@ -0,0 +1 @@
|
|||||||
|
../../../agents/gem-planner.agent.md
|
||||||
1
plugins/gem-team/agents/gem-researcher.md
Symbolic link
1
plugins/gem-team/agents/gem-researcher.md
Symbolic link
@@ -0,0 +1 @@
|
|||||||
|
../../../agents/gem-researcher.agent.md
|
||||||
1
plugins/gem-team/agents/gem-reviewer.md
Symbolic link
1
plugins/gem-team/agents/gem-reviewer.md
Symbolic link
@@ -0,0 +1 @@
|
|||||||
|
../../../agents/gem-reviewer.agent.md
|
||||||
10
plugins/ospo-sponsorship/.github/plugin/plugin.json
vendored
Normal file
10
plugins/ospo-sponsorship/.github/plugin/plugin.json
vendored
Normal file
@@ -0,0 +1,10 @@
|
|||||||
|
{
|
||||||
|
"name": "ospo-sponsorship",
|
||||||
|
"description": "Tools and resources for Open Source Program Offices (OSPOs) to identify, evaluate, and manage sponsorship of open source dependencies through GitHub Sponsors, Open Collective, and other funding platforms.",
|
||||||
|
"version": "1.0.0",
|
||||||
|
"author": {
|
||||||
|
"name": "Awesome Copilot Community"
|
||||||
|
},
|
||||||
|
"repository": "https://github.com/github/awesome-copilot",
|
||||||
|
"license": "MIT"
|
||||||
|
}
|
||||||
26
plugins/ospo-sponsorship/README.md
Normal file
26
plugins/ospo-sponsorship/README.md
Normal file
@@ -0,0 +1,26 @@
|
|||||||
|
# Open Source Sponsorship Plugin
|
||||||
|
|
||||||
|
Tools and resources for Open Source Program Offices (OSPOs) to identify, evaluate, and manage sponsorship of open source dependencies through GitHub Sponsors, Open Collective, and other funding platforms.
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Using Copilot CLI
|
||||||
|
copilot plugin install ospo-sponsorship@awesome-copilot
|
||||||
|
```
|
||||||
|
|
||||||
|
## What's Included
|
||||||
|
|
||||||
|
### Skills
|
||||||
|
|
||||||
|
| Skill | Description |
|
||||||
|
|-------|-------------|
|
||||||
|
| `SKILL.md` | Find which of a GitHub repository's dependencies are sponsorable via GitHub Sponsors. Uses deps.dev API for dependency resolution across npm, PyPI, Cargo, Go, RubyGems, Maven, and NuGet. Checks npm funding metadata, FUNDING.yml files, and web search. Verifies every link. Shows direct and transitive dependencies with OSSF Scorecard health data. Invoke by providing a GitHub owner/repo (e.g. "find sponsorable dependencies in expressjs/express"). |
|
||||||
|
|
||||||
|
## Source
|
||||||
|
|
||||||
|
This plugin is part of [Awesome Copilot](https://github.com/github/awesome-copilot), a community-driven collection of GitHub Copilot extensions.
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
MIT
|
||||||
1
plugins/ospo-sponsorship/skills/sponsor-finder
Symbolic link
1
plugins/ospo-sponsorship/skills/sponsor-finder
Symbolic link
@@ -0,0 +1 @@
|
|||||||
|
../../../skills/sponsor-finder
|
||||||
231
skills/aspire/SKILL.md
Normal file
231
skills/aspire/SKILL.md
Normal file
@@ -0,0 +1,231 @@
|
|||||||
|
---
|
||||||
|
name: aspire
|
||||||
|
description: 'Aspire skill covering the Aspire CLI, AppHost orchestration, service discovery, integrations, MCP server, VS Code extension, Dev Containers, GitHub Codespaces, templates, dashboard, and deployment. Use when the user asks to create, run, debug, configure, deploy, or troubleshoot an Aspire distributed application.'
|
||||||
|
---
|
||||||
|
|
||||||
|
# Aspire — Polyglot Distributed-App Orchestration
|
||||||
|
|
||||||
|
Aspire is a **code-first, polyglot toolchain** for building observable, production-ready distributed applications. It orchestrates containers, executables, and cloud resources from a single AppHost project — regardless of whether the workloads are C#, Python, JavaScript/TypeScript, Go, Java, Rust, Bun, Deno, or PowerShell.
|
||||||
|
|
||||||
|
> **Mental model:** The AppHost is a *conductor* — it doesn't play the instruments, it tells every service when to start, how to find each other, and watches for problems.
|
||||||
|
|
||||||
|
Detailed reference material lives in the `references/` folder — load on demand.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## References
|
||||||
|
|
||||||
|
| Reference | When to load |
|
||||||
|
|---|---|
|
||||||
|
| [CLI Reference](references/cli-reference.md) | Command flags, options, or detailed usage |
|
||||||
|
| [MCP Server](references/mcp-server.md) | Setting up MCP for AI assistants, available tools |
|
||||||
|
| [Integrations Catalog](references/integrations-catalog.md) | Discovering integrations via MCP tools, wiring patterns |
|
||||||
|
| [Polyglot APIs](references/polyglot-apis.md) | Method signatures, chaining options, language-specific patterns |
|
||||||
|
| [Architecture](references/architecture.md) | DCP internals, resource model, service discovery, networking, telemetry |
|
||||||
|
| [Dashboard](references/dashboard.md) | Dashboard features, standalone mode, GenAI Visualizer |
|
||||||
|
| [Deployment](references/deployment.md) | Docker, Kubernetes, Azure Container Apps, App Service |
|
||||||
|
| [Testing](references/testing.md) | Integration tests against the AppHost |
|
||||||
|
| [Troubleshooting](references/troubleshooting.md) | Diagnostic codes, common errors, and fixes |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Researching Aspire Documentation
|
||||||
|
|
||||||
|
The Aspire team ships an **MCP server** that provides documentation tools directly inside your AI assistant. See [MCP Server](references/mcp-server.md) for setup details.
|
||||||
|
|
||||||
|
### Aspire CLI 13.2+ (recommended — has built-in docs search)
|
||||||
|
|
||||||
|
If running Aspire CLI **13.2 or later** (`aspire --version`), the MCP server includes docs search tools:
|
||||||
|
|
||||||
|
| Tool | Description |
|
||||||
|
|---|---|
|
||||||
|
| `list_docs` | Lists all available documentation from aspire.dev |
|
||||||
|
| `search_docs` | Performs weighted lexical search across indexed documentation |
|
||||||
|
| `get_doc` | Retrieves a specific document by its slug |
|
||||||
|
|
||||||
|
These tools were added in [PR #14028](https://github.com/dotnet/aspire/pull/14028). To update: `aspire update --self --channel daily`.
|
||||||
|
|
||||||
|
For more on this approach, see David Pine's post: https://davidpine.dev/posts/aspire-docs-mcp-tools/
|
||||||
|
|
||||||
|
### Aspire CLI 13.1 (integration tools only)
|
||||||
|
|
||||||
|
On 13.1, the MCP server provides integration lookup but **not** docs search:
|
||||||
|
|
||||||
|
| Tool | Description |
|
||||||
|
|---|---|
|
||||||
|
| `list_integrations` | Lists available Aspire hosting integrations |
|
||||||
|
| `get_integration_docs` | Gets documentation for a specific integration package |
|
||||||
|
|
||||||
|
For general docs queries on 13.1, use **Context7** as your primary source (see below).
|
||||||
|
|
||||||
|
### Fallback: Context7
|
||||||
|
|
||||||
|
Use **Context7** (`mcp_context7`) when the Aspire MCP docs tools are unavailable (13.1) or the MCP server isn't running:
|
||||||
|
|
||||||
|
**Step 1 — Resolve the library ID** (one-time per session):
|
||||||
|
|
||||||
|
Call `mcp_context7_resolve-library-id` with `libraryName: ".NET Aspire"`.
|
||||||
|
|
||||||
|
| Rank | Library ID | Use when |
|
||||||
|
|---|---|---|
|
||||||
|
| 1 | `/microsoft/aspire.dev` | Primary source. Guides, integrations, CLI reference, deployment. |
|
||||||
|
| 2 | `/dotnet/aspire` | API internals, source-level implementation details. |
|
||||||
|
| 3 | `/communitytoolkit/aspire` | Non-Microsoft polyglot integrations (Go, Java, Node.js, Ollama). |
|
||||||
|
|
||||||
|
**Step 2 — Query docs:**
|
||||||
|
|
||||||
|
```
|
||||||
|
libraryId: "/microsoft/aspire.dev", query: "Python integration AddPythonApp service discovery"
|
||||||
|
libraryId: "/communitytoolkit/aspire", query: "Golang Java Node.js community integrations"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Fallback: GitHub search (when Context7 is also unavailable)
|
||||||
|
|
||||||
|
Search the official docs repo on GitHub:
|
||||||
|
- **Docs repo:** `microsoft/aspire.dev` — path: `src/frontend/src/content/docs/`
|
||||||
|
- **Source repo:** `dotnet/aspire`
|
||||||
|
- **Samples repo:** `dotnet/aspire-samples`
|
||||||
|
- **Community integrations:** `CommunityToolkit/Aspire`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Prerequisites & Install
|
||||||
|
|
||||||
|
| Requirement | Details |
|
||||||
|
|---|---|
|
||||||
|
| **.NET SDK** | 10.0+ (required even for non-.NET workloads — the AppHost is .NET) |
|
||||||
|
| **Container runtime** | Docker Desktop, Podman, or Rancher Desktop |
|
||||||
|
| **IDE (optional)** | VS Code + C# Dev Kit, Visual Studio 2022, JetBrains Rider |
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Linux / macOS
|
||||||
|
curl -sSL https://aspire.dev/install.sh | bash
|
||||||
|
|
||||||
|
# Windows PowerShell
|
||||||
|
irm https://aspire.dev/install.ps1 | iex
|
||||||
|
|
||||||
|
# Verify
|
||||||
|
aspire --version
|
||||||
|
|
||||||
|
# Install templates
|
||||||
|
dotnet new install Aspire.ProjectTemplates
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Project Templates
|
||||||
|
|
||||||
|
| Template | Command | Description |
|
||||||
|
|---|---|---|
|
||||||
|
| **aspire-starter** | `aspire new aspire-starter` | ASP.NET Core/Blazor starter + AppHost + tests |
|
||||||
|
| **aspire-ts-cs-starter** | `aspire new aspire-ts-cs-starter` | ASP.NET Core/React starter + AppHost |
|
||||||
|
| **aspire-py-starter** | `aspire new aspire-py-starter` | FastAPI/React starter + AppHost |
|
||||||
|
| **aspire-apphost-singlefile** | `aspire new aspire-apphost-singlefile` | Empty single-file AppHost |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. AppHost Quick Start (Polyglot)
|
||||||
|
|
||||||
|
The AppHost orchestrates all services. Non-.NET workloads run as containers or executables.
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
var builder = DistributedApplication.CreateBuilder(args);
|
||||||
|
|
||||||
|
// Infrastructure
|
||||||
|
var redis = builder.AddRedis("cache");
|
||||||
|
var postgres = builder.AddPostgres("pg").AddDatabase("catalog");
|
||||||
|
|
||||||
|
// .NET API
|
||||||
|
var api = builder.AddProject<Projects.CatalogApi>("api")
|
||||||
|
.WithReference(postgres).WithReference(redis);
|
||||||
|
|
||||||
|
// Python ML service
|
||||||
|
var ml = builder.AddPythonApp("ml-service", "../ml-service", "main.py")
|
||||||
|
.WithHttpEndpoint(targetPort: 8000).WithReference(redis);
|
||||||
|
|
||||||
|
// React frontend (Vite)
|
||||||
|
var web = builder.AddViteApp("web", "../frontend")
|
||||||
|
.WithHttpEndpoint(targetPort: 5173).WithReference(api);
|
||||||
|
|
||||||
|
// Go worker
|
||||||
|
var worker = builder.AddGolangApp("worker", "../go-worker")
|
||||||
|
.WithReference(redis);
|
||||||
|
|
||||||
|
builder.Build().Run();
|
||||||
|
```
|
||||||
|
|
||||||
|
For complete API signatures, see [Polyglot APIs](references/polyglot-apis.md).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Core Concepts (Summary)
|
||||||
|
|
||||||
|
| Concept | Key point |
|
||||||
|
|---|---|
|
||||||
|
| **Run vs Publish** | `aspire run` = local dev (DCP engine). `aspire publish` = generate deployment manifests. |
|
||||||
|
| **Service discovery** | Automatic via env vars: `ConnectionStrings__<name>`, `services__<name>__http__0` |
|
||||||
|
| **Resource lifecycle** | DAG ordering — dependencies start first. `.WaitFor()` gates on health checks. |
|
||||||
|
| **Resource types** | `ProjectResource`, `ContainerResource`, `ExecutableResource`, `ParameterResource` |
|
||||||
|
| **Integrations** | 144+ across 13 categories. Hosting package (AppHost) + Client package (service). |
|
||||||
|
| **Dashboard** | Real-time logs, traces, metrics, GenAI visualizer. Runs automatically with `aspire run`. |
|
||||||
|
| **MCP Server** | AI assistants can query running apps and search docs via CLI (STDIO). |
|
||||||
|
| **Testing** | `Aspire.Hosting.Testing` — spin up full AppHost in xUnit/MSTest/NUnit. |
|
||||||
|
| **Deployment** | Docker, Kubernetes, Azure Container Apps, Azure App Service. |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. CLI Quick Reference
|
||||||
|
|
||||||
|
Valid commands in Aspire CLI 13.1:
|
||||||
|
|
||||||
|
| Command | Description | Status |
|
||||||
|
|---|---|---|
|
||||||
|
| `aspire new <template>` | Create from template | Stable |
|
||||||
|
| `aspire init` | Initialize in existing project | Stable |
|
||||||
|
| `aspire run` | Start all resources locally | Stable |
|
||||||
|
| `aspire add <integration>` | Add an integration | Stable |
|
||||||
|
| `aspire publish` | Generate deployment manifests | Preview |
|
||||||
|
| `aspire config` | Manage configuration settings | Stable |
|
||||||
|
| `aspire cache` | Manage disk cache | Stable |
|
||||||
|
| `aspire deploy` | Deploy to defined targets | Preview |
|
||||||
|
| `aspire do <step>` | Execute a pipeline step | Preview |
|
||||||
|
| `aspire update` | Update integrations (or `--self` for CLI) | Preview |
|
||||||
|
| `aspire mcp init` | Configure MCP for AI assistants | Stable |
|
||||||
|
| `aspire mcp start` | Start the MCP server | Stable |
|
||||||
|
|
||||||
|
Full command reference with flags: [CLI Reference](references/cli-reference.md).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. Common Patterns
|
||||||
|
|
||||||
|
### Adding a new service
|
||||||
|
|
||||||
|
1. Create your service directory (any language)
|
||||||
|
2. Add to AppHost: `Add*App()` or `AddProject<T>()`
|
||||||
|
3. Wire dependencies: `.WithReference()`
|
||||||
|
4. Gate on health: `.WaitFor()` if needed
|
||||||
|
5. Run: `aspire run`
|
||||||
|
|
||||||
|
### Migrating from Docker Compose
|
||||||
|
|
||||||
|
1. `aspire new aspire-apphost-singlefile` (empty AppHost)
|
||||||
|
2. Replace each `docker-compose` service with an Aspire resource
|
||||||
|
3. `depends_on` → `.WithReference()` + `.WaitFor()`
|
||||||
|
4. `ports` → `.WithHttpEndpoint()`
|
||||||
|
5. `environment` → `.WithEnvironment()` or `.WithReference()`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. Key URLs
|
||||||
|
|
||||||
|
| Resource | URL |
|
||||||
|
|---|---|
|
||||||
|
| **Documentation** | https://aspire.dev |
|
||||||
|
| **Runtime repo** | https://github.com/dotnet/aspire |
|
||||||
|
| **Docs repo** | https://github.com/microsoft/aspire.dev |
|
||||||
|
| **Samples** | https://github.com/dotnet/aspire-samples |
|
||||||
|
| **Community Toolkit** | https://github.com/CommunityToolkit/Aspire |
|
||||||
|
| **Dashboard image** | `mcr.microsoft.com/dotnet/aspire-dashboard` |
|
||||||
|
| **Discord** | https://aka.ms/aspire/discord |
|
||||||
|
| **Reddit** | https://www.reddit.com/r/aspiredotdev/ |
|
||||||
341
skills/aspire/references/architecture.md
Normal file
341
skills/aspire/references/architecture.md
Normal file
@@ -0,0 +1,341 @@
|
|||||||
|
# Architecture — Deep Dive
|
||||||
|
|
||||||
|
This reference covers Aspire's internal architecture: the DCP engine, resource model, service discovery, networking, telemetry, and the eventing system.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Developer Control Plane (DCP)
|
||||||
|
|
||||||
|
The DCP is the **runtime engine** that Aspire uses in `aspire run` mode. Key facts:
|
||||||
|
|
||||||
|
- Written in **Go** (not .NET)
|
||||||
|
- Exposes a **Kubernetes-compatible API server** (local only, not a real K8s cluster)
|
||||||
|
- Manages resource lifecycle: create, start, health-check, stop, restart
|
||||||
|
- Runs containers via the local container runtime (Docker, Podman, Rancher)
|
||||||
|
- Runs executables as native OS processes
|
||||||
|
- Handles networking via a proxy layer with automatic port assignment
|
||||||
|
- Provides the foundation for the Aspire Dashboard's real-time data
|
||||||
|
|
||||||
|
### DCP vs Kubernetes
|
||||||
|
|
||||||
|
| Aspect | DCP (local dev) | Kubernetes (production) |
|
||||||
|
|---|---|---|
|
||||||
|
| API | Kubernetes-compatible | Full Kubernetes API |
|
||||||
|
| Scope | Single machine | Cluster |
|
||||||
|
| Networking | Local proxy, auto ports | Service mesh, ingress |
|
||||||
|
| Storage | Local volumes | PVCs, cloud storage |
|
||||||
|
| Purpose | Developer inner loop | Production deployment |
|
||||||
|
|
||||||
|
The Kubernetes-compatible API means Aspire understands the same resource abstractions, but DCP is **not** a Kubernetes distribution — it's a lightweight local runtime.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Resource Model
|
||||||
|
|
||||||
|
Everything in Aspire is a **resource**. The resource model is hierarchical:
|
||||||
|
|
||||||
|
### Type hierarchy
|
||||||
|
|
||||||
|
```
|
||||||
|
IResource (interface)
|
||||||
|
└── Resource (abstract base)
|
||||||
|
├── ProjectResource — .NET project reference
|
||||||
|
├── ContainerResource — Docker/OCI container
|
||||||
|
├── ExecutableResource — Native process (polyglot apps)
|
||||||
|
├── ParameterResource — Config value or secret
|
||||||
|
└── Infrastructure resources
|
||||||
|
├── RedisResource
|
||||||
|
├── PostgresServerResource
|
||||||
|
├── MongoDBServerResource
|
||||||
|
├── SqlServerResource
|
||||||
|
├── RabbitMQServerResource
|
||||||
|
├── KafkaServerResource
|
||||||
|
└── ... (one per integration)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Resource properties
|
||||||
|
|
||||||
|
Every resource has:
|
||||||
|
- **Name** — unique identifier within the AppHost
|
||||||
|
- **State** — lifecycle state (Starting, Running, FailedToStart, Stopping, Stopped, etc.)
|
||||||
|
- **Annotations** — metadata attached to the resource
|
||||||
|
- **Endpoints** — network endpoints exposed by the resource
|
||||||
|
- **Environment variables** — injected into the process/container
|
||||||
|
|
||||||
|
### Annotations
|
||||||
|
|
||||||
|
Annotations are metadata bags attached to resources. Common built-in annotations:
|
||||||
|
|
||||||
|
| Annotation | Purpose |
|
||||||
|
|---|---|
|
||||||
|
| `EndpointAnnotation` | Defines an HTTP/HTTPS/TCP endpoint |
|
||||||
|
| `EnvironmentCallbackAnnotation` | Deferred env var resolution |
|
||||||
|
| `HealthCheckAnnotation` | Health check configuration |
|
||||||
|
| `ContainerImageAnnotation` | Docker image details |
|
||||||
|
| `VolumeAnnotation` | Volume mount configuration |
|
||||||
|
| `CommandLineArgsCallbackAnnotation` | Dynamic CLI arguments |
|
||||||
|
| `ManifestPublishingCallbackAnnotation` | Custom publish behavior |
|
||||||
|
|
||||||
|
### Resource lifecycle states
|
||||||
|
|
||||||
|
```
|
||||||
|
NotStarted → Starting → Running → Stopping → Stopped
|
||||||
|
↓ ↓
|
||||||
|
FailedToStart RuntimeUnhealthy
|
||||||
|
↓
|
||||||
|
Restarting → Running
|
||||||
|
```
|
||||||
|
|
||||||
|
### DAG (Directed Acyclic Graph)
|
||||||
|
|
||||||
|
Resources form a dependency graph. Aspire starts resources in topological order:
|
||||||
|
|
||||||
|
```
|
||||||
|
PostgreSQL ──→ API ──→ Frontend
|
||||||
|
Redis ────────↗
|
||||||
|
RabbitMQ ──→ Worker
|
||||||
|
```
|
||||||
|
|
||||||
|
1. PostgreSQL, Redis, and RabbitMQ start first (no dependencies)
|
||||||
|
2. API starts after PostgreSQL and Redis are healthy
|
||||||
|
3. Frontend starts after API is healthy
|
||||||
|
4. Worker starts after RabbitMQ is healthy
|
||||||
|
|
||||||
|
`.WaitFor()` adds a health-check gate to the dependency edge. Without it, the dependency starts but the downstream doesn't wait for health.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Service Discovery
|
||||||
|
|
||||||
|
Aspire injects environment variables into each resource so services can find each other. No service registry or DNS is needed — it's pure environment variable injection.
|
||||||
|
|
||||||
|
### Connection strings
|
||||||
|
|
||||||
|
For databases, caches, and message brokers:
|
||||||
|
|
||||||
|
```
|
||||||
|
ConnectionStrings__<resource-name>=<connection-string>
|
||||||
|
```
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
```
|
||||||
|
ConnectionStrings__cache=localhost:6379
|
||||||
|
ConnectionStrings__catalog=Host=localhost;Port=5432;Database=catalog;Username=postgres;Password=...
|
||||||
|
ConnectionStrings__messaging=amqp://guest:guest@localhost:5672
|
||||||
|
```
|
||||||
|
|
||||||
|
### Service endpoints
|
||||||
|
|
||||||
|
For HTTP/HTTPS services:
|
||||||
|
|
||||||
|
```
|
||||||
|
services__<resource-name>__<scheme>__0=<url>
|
||||||
|
```
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
```
|
||||||
|
services__api__http__0=http://localhost:5234
|
||||||
|
services__api__https__0=https://localhost:7234
|
||||||
|
services__ml__http__0=http://localhost:8000
|
||||||
|
```
|
||||||
|
|
||||||
|
### How .WithReference() works
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
var redis = builder.AddRedis("cache");
|
||||||
|
var api = builder.AddProject<Projects.Api>("api")
|
||||||
|
.WithReference(redis);
|
||||||
|
```
|
||||||
|
|
||||||
|
This does:
|
||||||
|
1. Adds `ConnectionStrings__cache=localhost:<auto-port>` to the API's environment
|
||||||
|
2. Creates a dependency edge in the DAG (API depends on Redis)
|
||||||
|
3. In the API service, `builder.Configuration.GetConnectionString("cache")` returns the connection string
|
||||||
|
|
||||||
|
### Cross-language service discovery
|
||||||
|
|
||||||
|
All languages use the same env var pattern:
|
||||||
|
|
||||||
|
| Language | How to read |
|
||||||
|
|---|---|
|
||||||
|
| C# | `builder.Configuration.GetConnectionString("cache")` |
|
||||||
|
| Python | `os.environ["ConnectionStrings__cache"]` |
|
||||||
|
| JavaScript | `process.env.ConnectionStrings__cache` |
|
||||||
|
| Go | `os.Getenv("ConnectionStrings__cache")` |
|
||||||
|
| Java | `System.getenv("ConnectionStrings__cache")` |
|
||||||
|
| Rust | `std::env::var("ConnectionStrings__cache")` |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Networking
|
||||||
|
|
||||||
|
### Proxy architecture
|
||||||
|
|
||||||
|
In `aspire run` mode, DCP runs a reverse proxy for each exposed endpoint:
|
||||||
|
|
||||||
|
```
|
||||||
|
Browser → Proxy (auto-assigned port) → Actual Service (target port)
|
||||||
|
```
|
||||||
|
|
||||||
|
- **port** (the external port) — auto-assigned by DCP unless overridden
|
||||||
|
- **targetPort** — the port your service actually listens on
|
||||||
|
- All inter-service traffic goes through the proxy for observability
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
// Let DCP auto-assign the external port, service listens on 8000
|
||||||
|
builder.AddPythonApp("ml", "../ml", "main.py")
|
||||||
|
.WithHttpEndpoint(targetPort: 8000);
|
||||||
|
|
||||||
|
// Fix the external port to 3000
|
||||||
|
builder.AddViteApp("web", "../frontend")
|
||||||
|
.WithHttpEndpoint(port: 3000, targetPort: 5173);
|
||||||
|
```
|
||||||
|
|
||||||
|
### Endpoint types
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
// HTTP endpoint
|
||||||
|
.WithHttpEndpoint(port?, targetPort?, name?)
|
||||||
|
|
||||||
|
// HTTPS endpoint
|
||||||
|
.WithHttpsEndpoint(port?, targetPort?, name?)
|
||||||
|
|
||||||
|
// Generic endpoint (TCP, custom schemes)
|
||||||
|
.WithEndpoint(port?, targetPort?, scheme?, name?, isExternal?)
|
||||||
|
|
||||||
|
// Mark endpoints as externally accessible (for deployment)
|
||||||
|
.WithExternalHttpEndpoints()
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Telemetry (OpenTelemetry)
|
||||||
|
|
||||||
|
Aspire configures OpenTelemetry automatically for .NET services. For non-.NET services, you configure OpenTelemetry manually, pointing at the DCP collector.
|
||||||
|
|
||||||
|
### What's auto-configured (.NET services)
|
||||||
|
|
||||||
|
- **Distributed tracing** — HTTP client/server spans, database spans, messaging spans
|
||||||
|
- **Metrics** — Runtime metrics, HTTP metrics, custom metrics
|
||||||
|
- **Structured logging** — Logs correlated with trace context
|
||||||
|
- **Exporter** — OTLP exporter pointing at the Aspire Dashboard
|
||||||
|
|
||||||
|
### Configuring non-.NET services
|
||||||
|
|
||||||
|
The DCP exposes an OTLP endpoint. Set these env vars in your non-.NET service:
|
||||||
|
|
||||||
|
```
|
||||||
|
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
|
||||||
|
OTEL_SERVICE_NAME=<your-service-name>
|
||||||
|
```
|
||||||
|
|
||||||
|
Aspire auto-injects `OTEL_EXPORTER_OTLP_ENDPOINT` via `.WithReference()` for the dashboard collector.
|
||||||
|
|
||||||
|
### ServiceDefaults pattern
|
||||||
|
|
||||||
|
The `ServiceDefaults` project is a shared configuration library that standardizes:
|
||||||
|
- OpenTelemetry setup (tracing, metrics, logging)
|
||||||
|
- Health check endpoints (`/health`, `/alive`)
|
||||||
|
- Resilience policies (retries, circuit breakers via Polly)
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
// In each .NET service's Program.cs
|
||||||
|
builder.AddServiceDefaults(); // adds OTel, health checks, resilience
|
||||||
|
// ... other service config ...
|
||||||
|
app.MapDefaultEndpoints(); // maps /health and /alive
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Health Checks
|
||||||
|
|
||||||
|
### Built-in health checks
|
||||||
|
|
||||||
|
Every integration adds health checks automatically on the client side:
|
||||||
|
- Redis: `PING` command
|
||||||
|
- PostgreSQL: `SELECT 1`
|
||||||
|
- MongoDB: `ping` command
|
||||||
|
- RabbitMQ: Connection check
|
||||||
|
- etc.
|
||||||
|
|
||||||
|
### WaitFor vs WithReference
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
// WithReference: wires connection string + creates dependency edge
|
||||||
|
// (downstream may start before dependency is healthy)
|
||||||
|
.WithReference(db)
|
||||||
|
|
||||||
|
// WaitFor: gates on health check — downstream won't start until healthy
|
||||||
|
.WaitFor(db)
|
||||||
|
|
||||||
|
// Typical pattern: both
|
||||||
|
.WithReference(db).WaitFor(db)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Custom health checks
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
var api = builder.AddProject<Projects.Api>("api")
|
||||||
|
.WithHealthCheck("ready", "/health/ready")
|
||||||
|
.WithHealthCheck("live", "/health/live");
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Eventing System
|
||||||
|
|
||||||
|
The AppHost supports lifecycle events for reacting to resource state changes:
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
builder.Eventing.Subscribe<ResourceReadyEvent>("api", (evt, ct) =>
|
||||||
|
{
|
||||||
|
// Fires when "api" resource becomes healthy
|
||||||
|
Console.WriteLine($"API is ready at {evt.Resource.Name}");
|
||||||
|
return Task.CompletedTask;
|
||||||
|
});
|
||||||
|
|
||||||
|
builder.Eventing.Subscribe<BeforeResourceStartedEvent>("db", async (evt, ct) =>
|
||||||
|
{
|
||||||
|
// Run database migrations before the DB resource is marked as started
|
||||||
|
await RunMigrations();
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
### Available events
|
||||||
|
|
||||||
|
| Event | When |
|
||||||
|
|---|---|
|
||||||
|
| `BeforeResourceStartedEvent` | Before a resource starts |
|
||||||
|
| `ResourceReadyEvent` | Resource is healthy and ready |
|
||||||
|
| `ResourceStateChangedEvent` | Any state transition |
|
||||||
|
| `BeforeStartEvent` | Before the entire application starts |
|
||||||
|
| `AfterEndpointsAllocatedEvent` | After all ports are assigned |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
### Parameters
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
// Plain parameter
|
||||||
|
var apiKey = builder.AddParameter("api-key");
|
||||||
|
|
||||||
|
// Secret parameter (prompted at run, not logged)
|
||||||
|
var dbPassword = builder.AddParameter("db-password", secret: true);
|
||||||
|
|
||||||
|
// Use in resources
|
||||||
|
var api = builder.AddProject<Projects.Api>("api")
|
||||||
|
.WithEnvironment("API_KEY", apiKey);
|
||||||
|
|
||||||
|
var db = builder.AddPostgres("db", password: dbPassword);
|
||||||
|
```
|
||||||
|
|
||||||
|
### Configuration sources
|
||||||
|
|
||||||
|
Parameters are resolved from (in priority order):
|
||||||
|
1. Command-line arguments
|
||||||
|
2. Environment variables
|
||||||
|
3. User secrets (`dotnet user-secrets`)
|
||||||
|
4. `appsettings.json` / `appsettings.{Environment}.json`
|
||||||
|
5. Interactive prompt (for secrets during `aspire run`)
|
||||||
307
skills/aspire/references/cli-reference.md
Normal file
307
skills/aspire/references/cli-reference.md
Normal file
@@ -0,0 +1,307 @@
|
|||||||
|
# CLI Reference — Complete Command Reference
|
||||||
|
|
||||||
|
The Aspire CLI (`aspire`) is the primary interface for creating, running, and publishing distributed applications. It is cross-platform and installed standalone (not coupled to the .NET CLI, though `dotnet` commands also work).
|
||||||
|
|
||||||
|
**Tested against:** Aspire CLI 13.1.0
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Linux / macOS
|
||||||
|
curl -sSL https://aspire.dev/install.sh | bash
|
||||||
|
|
||||||
|
# Windows PowerShell
|
||||||
|
irm https://aspire.dev/install.ps1 | iex
|
||||||
|
|
||||||
|
# Verify
|
||||||
|
aspire --version
|
||||||
|
|
||||||
|
# Update the CLI itself
|
||||||
|
aspire update --self
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Global Options
|
||||||
|
|
||||||
|
All commands support these options:
|
||||||
|
|
||||||
|
| Option | Description |
|
||||||
|
| --------------------- | ---------------------------------------------- |
|
||||||
|
| `-d, --debug` | Enable debug logging to the console |
|
||||||
|
| `--non-interactive` | Disable all interactive prompts and spinners |
|
||||||
|
| `--wait-for-debugger` | Wait for a debugger to attach before executing |
|
||||||
|
| `-?, -h, --help` | Show help and usage information |
|
||||||
|
| `--version` | Show version information |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Command Reference
|
||||||
|
|
||||||
|
### `aspire new`
|
||||||
|
|
||||||
|
Create a new project from a template.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
aspire new [<template>] [options]
|
||||||
|
|
||||||
|
# Options:
|
||||||
|
# -n, --name <name> Project name
|
||||||
|
# -o, --output <dir> Output directory
|
||||||
|
# -s, --source <source> NuGet source for templates
|
||||||
|
# -v, --version <version> Version of templates to use
|
||||||
|
# --channel <channel> Channel (stable, daily)
|
||||||
|
|
||||||
|
# Examples:
|
||||||
|
aspire new aspire-starter
|
||||||
|
aspire new aspire-starter -n MyApp -o ./my-app
|
||||||
|
aspire new aspire-ts-cs-starter
|
||||||
|
aspire new aspire-py-starter
|
||||||
|
aspire new aspire-apphost-singlefile
|
||||||
|
```
|
||||||
|
|
||||||
|
Available templates:
|
||||||
|
|
||||||
|
- `aspire-starter` — ASP.NET Core/Blazor starter + AppHost + tests
|
||||||
|
- `aspire-ts-cs-starter` — ASP.NET Core/React + AppHost
|
||||||
|
- `aspire-py-starter` — FastAPI/React + AppHost
|
||||||
|
- `aspire-apphost-singlefile` — Empty single-file AppHost
|
||||||
|
|
||||||
|
### `aspire init`
|
||||||
|
|
||||||
|
Initialize Aspire in an existing project or solution.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
aspire init [options]
|
||||||
|
|
||||||
|
# Options:
|
||||||
|
# -s, --source <source> NuGet source for templates
|
||||||
|
# -v, --version <version> Version of templates to use
|
||||||
|
# --channel <channel> Channel (stable, daily)
|
||||||
|
|
||||||
|
# Example:
|
||||||
|
cd my-existing-solution
|
||||||
|
aspire init
|
||||||
|
```
|
||||||
|
|
||||||
|
Adds AppHost and ServiceDefaults projects to an existing solution. Interactive prompts guide you through selecting which projects to orchestrate.
|
||||||
|
|
||||||
|
### `aspire run`
|
||||||
|
|
||||||
|
Start all resources locally using the DCP (Developer Control Plane).
|
||||||
|
|
||||||
|
```bash
|
||||||
|
aspire run [options] [-- <additional arguments>]
|
||||||
|
|
||||||
|
# Options:
|
||||||
|
# --project <path> Path to AppHost project file
|
||||||
|
|
||||||
|
# Examples:
|
||||||
|
aspire run
|
||||||
|
aspire run --project ./src/MyApp.AppHost
|
||||||
|
```
|
||||||
|
|
||||||
|
Behavior:
|
||||||
|
|
||||||
|
1. Builds the AppHost project
|
||||||
|
2. Starts the DCP engine
|
||||||
|
3. Creates resources in dependency order (DAG)
|
||||||
|
4. Waits for health checks on gated resources
|
||||||
|
5. Opens the dashboard in the default browser
|
||||||
|
6. Streams logs to the terminal
|
||||||
|
|
||||||
|
Press `Ctrl+C` to gracefully stop all resources.
|
||||||
|
|
||||||
|
### `aspire add`
|
||||||
|
|
||||||
|
Add a hosting integration to the AppHost.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
aspire add [<integration>] [options]
|
||||||
|
|
||||||
|
# Options:
|
||||||
|
# --project <path> Target project file
|
||||||
|
# -v, --version <version> Version of integration to add
|
||||||
|
# -s, --source <source> NuGet source for integration
|
||||||
|
|
||||||
|
# Examples:
|
||||||
|
aspire add redis
|
||||||
|
aspire add postgresql
|
||||||
|
aspire add mongodb
|
||||||
|
```
|
||||||
|
|
||||||
|
### `aspire publish` (Preview)
|
||||||
|
|
||||||
|
Generate deployment manifests from the AppHost resource model.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
aspire publish [options] [-- <additional arguments>]
|
||||||
|
|
||||||
|
# Options:
|
||||||
|
# --project <path> Path to AppHost project file
|
||||||
|
# -o, --output-path <path> Output directory (default: ./aspire-output)
|
||||||
|
# --log-level <level> Log level (trace, debug, information, warning, error, critical)
|
||||||
|
# -e, --environment <env> Environment (default: Production)
|
||||||
|
# --include-exception-details Include stack traces in pipeline logs
|
||||||
|
|
||||||
|
# Examples:
|
||||||
|
aspire publish
|
||||||
|
aspire publish --output-path ./deploy
|
||||||
|
aspire publish -e Staging
|
||||||
|
```
|
||||||
|
|
||||||
|
### `aspire config`
|
||||||
|
|
||||||
|
Manage Aspire configuration settings.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
aspire config <subcommand>
|
||||||
|
|
||||||
|
# Subcommands:
|
||||||
|
# get <key> Get a configuration value
|
||||||
|
# set <key> <value> Set a configuration value
|
||||||
|
# list List all configuration values
|
||||||
|
# delete <key> Delete a configuration value
|
||||||
|
|
||||||
|
# Examples:
|
||||||
|
aspire config list
|
||||||
|
aspire config set telemetry.enabled false
|
||||||
|
aspire config get telemetry.enabled
|
||||||
|
aspire config delete telemetry.enabled
|
||||||
|
```
|
||||||
|
|
||||||
|
### `aspire cache`
|
||||||
|
|
||||||
|
Manage disk cache for CLI operations.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
aspire cache <subcommand>
|
||||||
|
|
||||||
|
# Subcommands:
|
||||||
|
# clear Clear all cache entries
|
||||||
|
|
||||||
|
# Example:
|
||||||
|
aspire cache clear
|
||||||
|
```
|
||||||
|
|
||||||
|
### `aspire deploy` (Preview)
|
||||||
|
|
||||||
|
Deploy the contents of an Aspire apphost to its defined deployment targets.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
aspire deploy [options] [-- <additional arguments>]
|
||||||
|
|
||||||
|
# Options:
|
||||||
|
# --project <path> Path to AppHost project file
|
||||||
|
# -o, --output-path <path> Output path for deployment artifacts
|
||||||
|
# --log-level <level> Log level (trace, debug, information, warning, error, critical)
|
||||||
|
# -e, --environment <env> Environment (default: Production)
|
||||||
|
# --include-exception-details Include stack traces in pipeline logs
|
||||||
|
# --clear-cache Clear deployment cache for current environment
|
||||||
|
|
||||||
|
# Example:
|
||||||
|
aspire deploy --project ./src/MyApp.AppHost
|
||||||
|
```
|
||||||
|
|
||||||
|
### `aspire do` (Preview)
|
||||||
|
|
||||||
|
Execute a specific pipeline step and its dependencies.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
aspire do <step> [options] [-- <additional arguments>]
|
||||||
|
|
||||||
|
# Options:
|
||||||
|
# --project <path> Path to AppHost project file
|
||||||
|
# -o, --output-path <path> Output path for artifacts
|
||||||
|
# --log-level <level> Log level (trace, debug, information, warning, error, critical)
|
||||||
|
# -e, --environment <env> Environment (default: Production)
|
||||||
|
# --include-exception-details Include stack traces in pipeline logs
|
||||||
|
|
||||||
|
# Example:
|
||||||
|
aspire do build-images --project ./src/MyApp.AppHost
|
||||||
|
```
|
||||||
|
|
||||||
|
### `aspire update` (Preview)
|
||||||
|
|
||||||
|
Update integrations in the Aspire project, or update the CLI itself.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
aspire update [options]
|
||||||
|
|
||||||
|
# Options:
|
||||||
|
# --project <path> Path to AppHost project file
|
||||||
|
# --self Update the Aspire CLI itself to the latest version
|
||||||
|
# --channel <channel> Channel to update to (stable, daily)
|
||||||
|
|
||||||
|
# Examples:
|
||||||
|
aspire update # Update project integrations
|
||||||
|
aspire update --self # Update the CLI itself
|
||||||
|
aspire update --self --channel daily # Update CLI to daily build
|
||||||
|
```
|
||||||
|
|
||||||
|
### `aspire mcp`
|
||||||
|
|
||||||
|
Manage the MCP (Model Context Protocol) server.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
aspire mcp <subcommand>
|
||||||
|
|
||||||
|
# Subcommands:
|
||||||
|
# init Initialize MCP server configuration for detected agent environments
|
||||||
|
# start Start the MCP server
|
||||||
|
```
|
||||||
|
|
||||||
|
#### `aspire mcp init`
|
||||||
|
|
||||||
|
```bash
|
||||||
|
aspire mcp init
|
||||||
|
|
||||||
|
# Interactive — detects your AI environment and creates config files.
|
||||||
|
# Supported environments:
|
||||||
|
# - VS Code (GitHub Copilot)
|
||||||
|
# - Copilot CLI
|
||||||
|
# - Claude Code
|
||||||
|
# - OpenCode
|
||||||
|
```
|
||||||
|
|
||||||
|
Generates the appropriate configuration file for your detected AI tool.
|
||||||
|
See [MCP Server](mcp-server.md) for details.
|
||||||
|
|
||||||
|
#### `aspire mcp start`
|
||||||
|
|
||||||
|
```bash
|
||||||
|
aspire mcp start
|
||||||
|
|
||||||
|
# Starts the MCP server using STDIO transport.
|
||||||
|
# This is typically invoked by your AI tool, not run manually.
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Commands That Do NOT Exist
|
||||||
|
|
||||||
|
The following commands are **not valid** in Aspire CLI 13.1. Use alternatives:
|
||||||
|
|
||||||
|
| Invalid Command | Alternative |
|
||||||
|
| --------------- | -------------------------------------------------------------------- |
|
||||||
|
| `aspire build` | Use `dotnet build ./AppHost` |
|
||||||
|
| `aspire test` | Use `dotnet test ./Tests` |
|
||||||
|
| `aspire dev` | Use `aspire run` (includes file watching) |
|
||||||
|
| `aspire list` | Use `aspire new --help` for templates, `aspire add` for integrations |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## .NET CLI equivalents
|
||||||
|
|
||||||
|
The `dotnet` CLI can perform some Aspire tasks:
|
||||||
|
|
||||||
|
| Aspire CLI | .NET CLI Equivalent |
|
||||||
|
| --------------------------- | -------------------------------- |
|
||||||
|
| `aspire new aspire-starter` | `dotnet new aspire-starter` |
|
||||||
|
| `aspire run` | `dotnet run --project ./AppHost` |
|
||||||
|
| N/A | `dotnet build ./AppHost` |
|
||||||
|
| N/A | `dotnet test ./Tests` |
|
||||||
|
|
||||||
|
The Aspire CLI adds value with `publish`, `deploy`, `add`, `mcp`, `config`, `cache`, `do`, and `update` — commands that have no direct `dotnet` equivalent.
|
||||||
226
skills/aspire/references/dashboard.md
Normal file
226
skills/aspire/references/dashboard.md
Normal file
@@ -0,0 +1,226 @@
|
|||||||
|
# Dashboard — Complete Reference
|
||||||
|
|
||||||
|
The Aspire Dashboard provides real-time observability for all resources in your distributed application. It launches automatically with `aspire run` and can also run standalone.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Features
|
||||||
|
|
||||||
|
### Resources view
|
||||||
|
|
||||||
|
Displays all resources (projects, containers, executables) with:
|
||||||
|
|
||||||
|
- **Name** and **type** (Project, Container, Executable)
|
||||||
|
- **State** (Starting, Running, Stopped, FailedToStart, etc.)
|
||||||
|
- **Start time** and **uptime**
|
||||||
|
- **Endpoints** — clickable URLs for each exposed endpoint
|
||||||
|
- **Source** — project path, container image, or executable path
|
||||||
|
- **Actions** — Stop, Start, Restart buttons
|
||||||
|
|
||||||
|
### Console logs
|
||||||
|
|
||||||
|
Aggregated raw stdout/stderr from all resources:
|
||||||
|
|
||||||
|
- Filter by resource name
|
||||||
|
- Search within logs
|
||||||
|
- Auto-scroll with pause
|
||||||
|
- Color-coded by resource
|
||||||
|
|
||||||
|
### Structured logs
|
||||||
|
|
||||||
|
Application-level structured logs (via ILogger, OpenTelemetry):
|
||||||
|
|
||||||
|
- **Filterable** by resource, log level, category, message content
|
||||||
|
- **Expandable** — click to see full log entry with all properties
|
||||||
|
- **Correlated** with traces — click to jump to the related trace
|
||||||
|
- Supports .NET ILogger structured logging properties
|
||||||
|
- Supports OpenTelemetry log signals from any language
|
||||||
|
|
||||||
|
### Distributed traces
|
||||||
|
|
||||||
|
End-to-end request traces across all services:
|
||||||
|
|
||||||
|
- **Waterfall view** — shows the full call chain with timing
|
||||||
|
- **Span details** — HTTP method, URL, status code, duration
|
||||||
|
- **Database spans** — SQL queries, connection details
|
||||||
|
- **Messaging spans** — queue operations, topic publishes
|
||||||
|
- **Error highlighting** — failed spans shown in red
|
||||||
|
- **Cross-service correlation** — trace context propagated automatically for .NET; manual for other languages
|
||||||
|
|
||||||
|
### Metrics
|
||||||
|
|
||||||
|
Real-time and historical metrics:
|
||||||
|
|
||||||
|
- **Runtime metrics** — CPU, memory, GC, thread pool
|
||||||
|
- **HTTP metrics** — request rate, error rate, latency percentiles
|
||||||
|
- **Custom metrics** — any metrics your services emit via OpenTelemetry
|
||||||
|
- **Chartable** — time-series graphs for each metric
|
||||||
|
|
||||||
|
### GenAI Visualizer
|
||||||
|
|
||||||
|
For applications using AI/LLM integrations:
|
||||||
|
|
||||||
|
- **Token usage** — prompt tokens, completion tokens, total tokens per request
|
||||||
|
- **Prompt/completion pairs** — see the exact prompt sent and response received
|
||||||
|
- **Model metadata** — which model, temperature, max tokens
|
||||||
|
- **Latency** — time per AI call
|
||||||
|
- Requires services to emit [GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/) via OpenTelemetry
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Dashboard URL
|
||||||
|
|
||||||
|
By default, the dashboard runs on an auto-assigned port. Find it:
|
||||||
|
|
||||||
|
- In the terminal output when `aspire run` starts
|
||||||
|
- Via MCP: `list_resources` tool
|
||||||
|
- Override with `--dashboard-port`:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
aspire run --dashboard-port 18888
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Standalone Dashboard
|
||||||
|
|
||||||
|
Run the dashboard without an AppHost — useful for existing applications that already emit OpenTelemetry:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker run --rm -d \
|
||||||
|
-p 18888:18888 \
|
||||||
|
-p 4317:18889 \
|
||||||
|
mcr.microsoft.com/dotnet/aspire-dashboard:latest
|
||||||
|
```
|
||||||
|
|
||||||
|
| Port | Purpose |
|
||||||
|
| ---------------- | ------------------------------------------------------------ |
|
||||||
|
| `18888` | Dashboard web UI |
|
||||||
|
| `4317` → `18889` | OTLP gRPC receiver (standard OTel port → dashboard internal) |
|
||||||
|
|
||||||
|
### Configure your services
|
||||||
|
|
||||||
|
Point your OpenTelemetry exporters at the dashboard:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Environment variables for any language's OpenTelemetry SDK
|
||||||
|
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
|
||||||
|
OTEL_SERVICE_NAME=my-service
|
||||||
|
```
|
||||||
|
|
||||||
|
### Docker Compose example
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
services:
|
||||||
|
dashboard:
|
||||||
|
image: mcr.microsoft.com/dotnet/aspire-dashboard:latest
|
||||||
|
ports:
|
||||||
|
- "18888:18888"
|
||||||
|
- "4317:18889"
|
||||||
|
|
||||||
|
api:
|
||||||
|
build: ./api
|
||||||
|
environment:
|
||||||
|
- OTEL_EXPORTER_OTLP_ENDPOINT=http://dashboard:18889
|
||||||
|
- OTEL_SERVICE_NAME=api
|
||||||
|
|
||||||
|
worker:
|
||||||
|
build: ./worker
|
||||||
|
environment:
|
||||||
|
- OTEL_EXPORTER_OTLP_ENDPOINT=http://dashboard:18889
|
||||||
|
- OTEL_SERVICE_NAME=worker
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Dashboard configuration
|
||||||
|
|
||||||
|
### Authentication
|
||||||
|
|
||||||
|
The standalone dashboard supports authentication via browser tokens:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker run --rm -d \
|
||||||
|
-p 18888:18888 \
|
||||||
|
-p 4317:18889 \
|
||||||
|
-e DASHBOARD__FRONTEND__AUTHMODE=BrowserToken \
|
||||||
|
-e DASHBOARD__FRONTEND__BROWSERTOKEN__TOKEN=my-secret-token \
|
||||||
|
mcr.microsoft.com/dotnet/aspire-dashboard:latest
|
||||||
|
```
|
||||||
|
|
||||||
|
### OTLP configuration
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Accept OTLP over gRPC (default)
|
||||||
|
-e DASHBOARD__OTLP__GRPC__ENDPOINT=http://0.0.0.0:18889
|
||||||
|
|
||||||
|
# Accept OTLP over HTTP
|
||||||
|
-e DASHBOARD__OTLP__HTTP__ENDPOINT=http://0.0.0.0:18890
|
||||||
|
|
||||||
|
# Require API key for OTLP
|
||||||
|
-e DASHBOARD__OTLP__AUTHMODE=ApiKey
|
||||||
|
-e DASHBOARD__OTLP__PRIMARYAPIKEY=my-api-key
|
||||||
|
```
|
||||||
|
|
||||||
|
### Resource limits
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Limit log entries retained
|
||||||
|
-e DASHBOARD__TELEMETRYLIMITS__MAXLOGCOUNT=10000
|
||||||
|
|
||||||
|
# Limit trace entries retained
|
||||||
|
-e DASHBOARD__TELEMETRYLIMITS__MAXTRACECOUNT=10000
|
||||||
|
|
||||||
|
# Limit metric data points
|
||||||
|
-e DASHBOARD__TELEMETRYLIMITS__MAXMETRICCOUNT=50000
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Copilot integration
|
||||||
|
|
||||||
|
The dashboard integrates with GitHub Copilot in VS Code:
|
||||||
|
|
||||||
|
- Ask questions about resource status
|
||||||
|
- Query logs and traces in natural language
|
||||||
|
- The MCP server (see [MCP Server](mcp-server.md)) provides the bridge
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Non-.NET service telemetry
|
||||||
|
|
||||||
|
For non-.NET services to appear in the dashboard, they must emit OpenTelemetry signals. Aspire auto-injects the OTLP endpoint env var when using `.WithReference()`:
|
||||||
|
|
||||||
|
### Python (OpenTelemetry SDK)
|
||||||
|
|
||||||
|
```python
|
||||||
|
from opentelemetry import trace
|
||||||
|
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
|
||||||
|
from opentelemetry.sdk.trace import TracerProvider
|
||||||
|
from opentelemetry.sdk.trace.export import BatchSpanProcessor
|
||||||
|
import os
|
||||||
|
|
||||||
|
# Aspire injects OTEL_EXPORTER_OTLP_ENDPOINT automatically
|
||||||
|
endpoint = os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT", "http://localhost:4317")
|
||||||
|
|
||||||
|
provider = TracerProvider()
|
||||||
|
provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter(endpoint=endpoint)))
|
||||||
|
trace.set_tracer_provider(provider)
|
||||||
|
```
|
||||||
|
|
||||||
|
### JavaScript (OpenTelemetry SDK)
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
|
||||||
|
const { OTLPTraceExporter } = require("@opentelemetry/exporter-trace-otlp-grpc");
|
||||||
|
|
||||||
|
const provider = new NodeTracerProvider();
|
||||||
|
provider.addSpanProcessor(
|
||||||
|
new BatchSpanProcessor(
|
||||||
|
new OTLPTraceExporter({
|
||||||
|
url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || "http://localhost:4317",
|
||||||
|
})
|
||||||
|
)
|
||||||
|
);
|
||||||
|
provider.register();
|
||||||
|
```
|
||||||
237
skills/aspire/references/deployment.md
Normal file
237
skills/aspire/references/deployment.md
Normal file
@@ -0,0 +1,237 @@
|
|||||||
|
# Deployment — Complete Reference
|
||||||
|
|
||||||
|
Aspire separates **orchestration** (what to run) from **deployment** (where to run it). The `aspire publish` command translates your AppHost resource model into deployment manifests for your target platform.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Publish vs Deploy
|
||||||
|
|
||||||
|
| Concept | What it does |
|
||||||
|
|---|---|
|
||||||
|
| **`aspire publish`** | Generates deployment artifacts (Dockerfiles, Helm charts, Bicep, etc.) |
|
||||||
|
| **Deploy** | You run the generated artifacts through your CI/CD pipeline |
|
||||||
|
|
||||||
|
Aspire does NOT deploy directly. It generates the manifests — you deploy them.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Supported Targets
|
||||||
|
|
||||||
|
### Docker
|
||||||
|
|
||||||
|
**Package:** `Aspire.Hosting.Docker`
|
||||||
|
|
||||||
|
```bash
|
||||||
|
aspire publish -p docker -o ./docker-output
|
||||||
|
```
|
||||||
|
|
||||||
|
Generates:
|
||||||
|
- `docker-compose.yml` — service definitions matching your AppHost
|
||||||
|
- `Dockerfile` for each .NET project
|
||||||
|
- Environment variable configuration
|
||||||
|
- Volume mounts
|
||||||
|
- Network configuration
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
// AppHost configuration for Docker publishing
|
||||||
|
var api = builder.AddProject<Projects.Api>("api")
|
||||||
|
.PublishAsDockerFile(); // override default publish behavior
|
||||||
|
```
|
||||||
|
|
||||||
|
### Kubernetes
|
||||||
|
|
||||||
|
**Package:** `Aspire.Hosting.Kubernetes`
|
||||||
|
|
||||||
|
```bash
|
||||||
|
aspire publish -p kubernetes -o ./k8s-output
|
||||||
|
```
|
||||||
|
|
||||||
|
Generates:
|
||||||
|
- Kubernetes YAML manifests (Deployments, Services, ConfigMaps, Secrets)
|
||||||
|
- Helm chart (optional)
|
||||||
|
- Ingress configuration
|
||||||
|
- Resource limits based on AppHost configuration
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
// AppHost: customize K8s publishing
|
||||||
|
var api = builder.AddProject<Projects.Api>("api")
|
||||||
|
.WithReplicas(3) // maps to K8s replicas
|
||||||
|
.WithExternalHttpEndpoints(); // maps to Ingress/LoadBalancer
|
||||||
|
```
|
||||||
|
|
||||||
|
### Azure Container Apps
|
||||||
|
|
||||||
|
**Package:** `Aspire.Hosting.Azure.AppContainers`
|
||||||
|
|
||||||
|
```bash
|
||||||
|
aspire publish -p azure -o ./azure-output
|
||||||
|
```
|
||||||
|
|
||||||
|
Generates:
|
||||||
|
- Bicep templates for Azure Container Apps Environment
|
||||||
|
- Container App definitions for each service
|
||||||
|
- Azure Container Registry configuration
|
||||||
|
- Managed identity configuration
|
||||||
|
- Dapr components (if using Dapr integration)
|
||||||
|
- VNET configuration
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
// AppHost: Azure-specific configuration
|
||||||
|
var api = builder.AddProject<Projects.Api>("api")
|
||||||
|
.WithExternalHttpEndpoints() // maps to external ingress
|
||||||
|
.WithReplicas(3); // maps to min replicas
|
||||||
|
|
||||||
|
// Azure resources are auto-provisioned
|
||||||
|
var storage = builder.AddAzureStorage("storage"); // creates Storage Account
|
||||||
|
var cosmos = builder.AddAzureCosmosDB("cosmos"); // creates Cosmos DB account
|
||||||
|
var sb = builder.AddAzureServiceBus("messaging"); // creates Service Bus namespace
|
||||||
|
```
|
||||||
|
|
||||||
|
### Azure App Service
|
||||||
|
|
||||||
|
**Package:** `Aspire.Hosting.Azure.AppService`
|
||||||
|
|
||||||
|
```bash
|
||||||
|
aspire publish -p appservice -o ./appservice-output
|
||||||
|
```
|
||||||
|
|
||||||
|
Generates:
|
||||||
|
- Bicep templates for App Service Plans and Web Apps
|
||||||
|
- Connection string configuration
|
||||||
|
- Application settings
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Resource model to deployment mapping
|
||||||
|
|
||||||
|
| AppHost concept | Docker Compose | Kubernetes | Azure Container Apps |
|
||||||
|
|---|---|---|---|
|
||||||
|
| `AddProject<T>()` | `service` with Dockerfile | `Deployment` + `Service` | `Container App` |
|
||||||
|
| `AddContainer()` | `service` with `image:` | `Deployment` + `Service` | `Container App` |
|
||||||
|
| `AddRedis()` | `service: redis` | `StatefulSet` | Managed Redis |
|
||||||
|
| `AddPostgres()` | `service: postgres` | `StatefulSet` | Azure PostgreSQL |
|
||||||
|
| `.WithReference()` | `environment:` vars | `ConfigMap` / `Secret` | App settings |
|
||||||
|
| `.WithReplicas(n)` | `deploy: replicas: n` | `replicas: n` | `minReplicas: n` |
|
||||||
|
| `.WithVolume()` | `volumes:` | `PersistentVolumeClaim` | Azure Files |
|
||||||
|
| `.WithHttpEndpoint()` | `ports:` | `Service` port | Ingress |
|
||||||
|
| `.WithExternalHttpEndpoints()` | `ports:` (host) | `Ingress` / `LoadBalancer` | External ingress |
|
||||||
|
| `AddParameter(secret: true)` | `.env` file | `Secret` | Key Vault reference |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## CI/CD integration
|
||||||
|
|
||||||
|
### GitHub Actions example
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
name: Deploy
|
||||||
|
on:
|
||||||
|
push:
|
||||||
|
branches: [main]
|
||||||
|
|
||||||
|
jobs:
|
||||||
|
deploy:
|
||||||
|
runs-on: ubuntu-latest
|
||||||
|
steps:
|
||||||
|
- uses: actions/checkout@v4
|
||||||
|
|
||||||
|
- name: Setup .NET
|
||||||
|
uses: actions/setup-dotnet@v4
|
||||||
|
with:
|
||||||
|
dotnet-version: '10.0.x'
|
||||||
|
|
||||||
|
- name: Install Aspire CLI
|
||||||
|
run: curl -sSL https://aspire.dev/install.sh | bash
|
||||||
|
|
||||||
|
- name: Generate manifests
|
||||||
|
run: aspire publish -p azure -o ./deploy
|
||||||
|
|
||||||
|
- name: Deploy to Azure
|
||||||
|
uses: azure/arm-deploy@v2
|
||||||
|
with:
|
||||||
|
template: ./deploy/main.bicep
|
||||||
|
parameters: ./deploy/main.parameters.json
|
||||||
|
```
|
||||||
|
|
||||||
|
### Azure DevOps example
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
trigger:
|
||||||
|
branches:
|
||||||
|
include: [main]
|
||||||
|
|
||||||
|
pool:
|
||||||
|
vmImage: 'ubuntu-latest'
|
||||||
|
|
||||||
|
steps:
|
||||||
|
- task: UseDotNet@2
|
||||||
|
inputs:
|
||||||
|
version: '10.0.x'
|
||||||
|
|
||||||
|
- script: curl -sSL https://aspire.dev/install.sh | bash
|
||||||
|
displayName: 'Install Aspire CLI'
|
||||||
|
|
||||||
|
- script: aspire publish -p azure -o $(Build.ArtifactStagingDirectory)/deploy
|
||||||
|
displayName: 'Generate deployment manifests'
|
||||||
|
|
||||||
|
- task: AzureResourceManagerTemplateDeployment@3
|
||||||
|
inputs:
|
||||||
|
deploymentScope: 'Resource Group'
|
||||||
|
templateLocation: '$(Build.ArtifactStagingDirectory)/deploy/main.bicep'
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Environment-specific configuration
|
||||||
|
|
||||||
|
### Using parameters for secrets
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
// AppHost
|
||||||
|
var dbPassword = builder.AddParameter("db-password", secret: true);
|
||||||
|
var postgres = builder.AddPostgres("db", password: dbPassword);
|
||||||
|
```
|
||||||
|
|
||||||
|
In deployment:
|
||||||
|
- **Docker:** Loaded from `.env` file
|
||||||
|
- **Kubernetes:** Loaded from `Secret` resource
|
||||||
|
- **Azure:** Loaded from Key Vault via managed identity
|
||||||
|
|
||||||
|
### Conditional resources
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
// Use Azure services in production, emulators locally
|
||||||
|
if (builder.ExecutionContext.IsPublishMode)
|
||||||
|
{
|
||||||
|
var cosmos = builder.AddAzureCosmosDB("cosmos"); // real Azure resource
|
||||||
|
}
|
||||||
|
else
|
||||||
|
{
|
||||||
|
var cosmos = builder.AddAzureCosmosDB("cosmos")
|
||||||
|
.RunAsEmulator(); // local emulator
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Dev Containers & GitHub Codespaces
|
||||||
|
|
||||||
|
Aspire templates include `.devcontainer/` configuration:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"name": "Aspire App",
|
||||||
|
"image": "mcr.microsoft.com/devcontainers/dotnet:10.0",
|
||||||
|
"features": {
|
||||||
|
"ghcr.io/devcontainers/features/docker-in-docker:2": {},
|
||||||
|
"ghcr.io/devcontainers/features/node:1": {}
|
||||||
|
},
|
||||||
|
"postCreateCommand": "curl -sSL https://aspire.dev/install.sh | bash",
|
||||||
|
"forwardPorts": [18888],
|
||||||
|
"portsAttributes": {
|
||||||
|
"18888": { "label": "Aspire Dashboard" }
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Port forwarding works automatically in Codespaces — the dashboard and all service endpoints are accessible via forwarded URLs.
|
||||||
68
skills/aspire/references/integrations-catalog.md
Normal file
68
skills/aspire/references/integrations-catalog.md
Normal file
@@ -0,0 +1,68 @@
|
|||||||
|
# Integrations Catalog
|
||||||
|
|
||||||
|
Aspire has **144+ integrations** across 13 categories. Rather than maintaining a static list, use the MCP tools to get live, up-to-date integration data.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Discovering integrations (MCP tools)
|
||||||
|
|
||||||
|
The Aspire MCP server provides two tools for integration discovery — these work on **all CLI versions** (13.1+) and do **not** require a running AppHost.
|
||||||
|
|
||||||
|
| Tool | What it does | When to use |
|
||||||
|
| ---------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
|
||||||
|
| `list_integrations` | Returns all available Aspire hosting integrations with their NuGet package IDs | "What integrations are available for databases?" / "Show me all Redis-related integrations" |
|
||||||
|
| `get_integration_docs` | Retrieves detailed documentation for a specific integration package (setup, configuration, code samples) | "How do I configure PostgreSQL?" / "Show me the docs for `Aspire.Hosting.Redis`" |
|
||||||
|
|
||||||
|
### Workflow
|
||||||
|
|
||||||
|
1. **Browse** — Call `list_integrations` to see what's available. Filter results by category or keyword.
|
||||||
|
2. **Deep dive** — Call `get_integration_docs` with the package ID (e.g., `Aspire.Hosting.Redis`) and version (e.g., `9.0.0`) to get full setup instructions.
|
||||||
|
3. **Add** — Run `aspire add <integration>` to install the hosting package into your AppHost.
|
||||||
|
|
||||||
|
> **Tip:** These tools return the same data as the [official integrations gallery](https://aspire.dev/integrations/gallery/). Prefer them over static docs — integrations are added frequently.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Integration pattern
|
||||||
|
|
||||||
|
Every integration follows a two-package pattern:
|
||||||
|
|
||||||
|
- **Hosting package** (`Aspire.Hosting.*`) — adds the resource to the AppHost
|
||||||
|
- **Client package** (`Aspire.*`) — configures the client SDK in your service with health checks, telemetry, and retries
|
||||||
|
- **Community Toolkit** (`CommunityToolkit.Aspire.*`) — community-maintained integrations from [Aspire Community Toolkit](https://github.com/CommunityToolkit/Aspire)
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
// === AppHost (hosting side) ===
|
||||||
|
var redis = builder.AddRedis("cache"); // Aspire.Hosting.Redis
|
||||||
|
var api = builder.AddProject<Projects.Api>("api")
|
||||||
|
.WithReference(redis);
|
||||||
|
|
||||||
|
// === Service (client side) — in API's Program.cs ===
|
||||||
|
builder.AddRedisClient("cache"); // Aspire.StackExchange.Redis
|
||||||
|
// Automatically configures: connection string, health checks, OpenTelemetry, retries
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Categories at a glance
|
||||||
|
|
||||||
|
Use `list_integrations` for the full live list. This summary covers the major categories:
|
||||||
|
|
||||||
|
| Category | Key integrations | Example hosting package |
|
||||||
|
| ------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------- |
|
||||||
|
| **AI** | Azure OpenAI, OpenAI, GitHub Models, Ollama | `Aspire.Hosting.Azure.CognitiveServices` |
|
||||||
|
| **Caching** | Redis, Garnet, Valkey, Azure Cache for Redis | `Aspire.Hosting.Redis` |
|
||||||
|
| **Cloud / Azure** | Storage, Cosmos DB, Service Bus, Key Vault, Event Hubs, Functions, SQL, SignalR (25+) | `Aspire.Hosting.Azure.Storage` |
|
||||||
|
| **Cloud / AWS** | AWS SDK integration | `Aspire.Hosting.AWS` |
|
||||||
|
| **Databases** | PostgreSQL, SQL Server, MongoDB, MySQL, Oracle, Elasticsearch, Milvus, Qdrant, SQLite | `Aspire.Hosting.PostgreSQL` |
|
||||||
|
| **DevTools** | Data API Builder, Dev Tunnels, Mailpit, k6, Flagd, Ngrok, Stripe | `Aspire.Hosting.DevTunnels` |
|
||||||
|
| **Messaging** | RabbitMQ, Kafka, NATS, ActiveMQ, LavinMQ | `Aspire.Hosting.RabbitMQ` |
|
||||||
|
| **Observability** | OpenTelemetry (built-in), Seq, OTel Collector | `Aspire.Hosting.Seq` |
|
||||||
|
| **Compute** | Docker Compose, Kubernetes | `Aspire.Hosting.Docker` |
|
||||||
|
| **Reverse Proxies** | YARP | `Aspire.Hosting.Yarp` |
|
||||||
|
| **Security** | Keycloak | `Aspire.Hosting.Keycloak` |
|
||||||
|
| **Frameworks** | JavaScript, Python, Go, Java, Rust, Bun, Deno, Orleans, MAUI, Dapr, PowerShell | `Aspire.Hosting.Python` |
|
||||||
|
|
||||||
|
For polyglot framework method signatures, see [Polyglot APIs](polyglot-apis.md).
|
||||||
|
|
||||||
|
---
|
||||||
195
skills/aspire/references/mcp-server.md
Normal file
195
skills/aspire/references/mcp-server.md
Normal file
@@ -0,0 +1,195 @@
|
|||||||
|
# MCP Server — Complete Reference
|
||||||
|
|
||||||
|
Aspire exposes an **MCP (Model Context Protocol) server** that lets AI coding assistants query and control your running distributed application, and search Aspire documentation. This enables AI tools to inspect resource status, read logs, view traces, restart services, and look up docs — all from within the AI assistant's context.
|
||||||
|
|
||||||
|
Reference: https://aspire.dev/get-started/configure-mcp/
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Setup: `aspire mcp init`
|
||||||
|
|
||||||
|
The easiest way to configure the MCP server is using the Aspire CLI:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Open a terminal in your project directory
|
||||||
|
aspire mcp init
|
||||||
|
```
|
||||||
|
|
||||||
|
The command walks you through an interactive setup:
|
||||||
|
|
||||||
|
1. **Workspace root** — prompts for the path to your workspace root (defaults to current directory)
|
||||||
|
2. **Environment detection** — detects supported AI environments (VS Code, Copilot CLI, Claude Code, OpenCode) and asks which to configure
|
||||||
|
3. **Playwright MCP** — optionally offers to configure the Playwright MCP server alongside Aspire
|
||||||
|
4. **Config creation** — writes the appropriate configuration files (e.g., `.vscode/mcp.json`)
|
||||||
|
5. **AGENTS.md** — if one doesn't already exist, creates an `AGENTS.md` with Aspire-specific instructions for AI agents
|
||||||
|
|
||||||
|
> **Note:** `aspire mcp init` uses interactive prompts (Spectre.Console). It must be run in a real terminal — the VS Code integrated terminal may not handle the prompts correctly. Use an external terminal if needed.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Understanding the Configuration
|
||||||
|
|
||||||
|
When you run `aspire mcp init`, the CLI creates configuration files appropriate for your detected environment.
|
||||||
|
|
||||||
|
### VS Code (GitHub Copilot)
|
||||||
|
|
||||||
|
Creates or updates `.vscode/mcp.json`:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"servers": {
|
||||||
|
"aspire": {
|
||||||
|
"type": "stdio",
|
||||||
|
"command": "aspire",
|
||||||
|
"args": ["mcp", "start"]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## MCP Tools
|
||||||
|
|
||||||
|
The tools available depend on your Aspire CLI version. Check with `aspire --version`.
|
||||||
|
|
||||||
|
### Tools available in 13.1+ (stable)
|
||||||
|
|
||||||
|
#### Resource management tools
|
||||||
|
|
||||||
|
These tools require a running AppHost (`aspire run`).
|
||||||
|
|
||||||
|
| Tool | Description |
|
||||||
|
| ---------------------------- | ------------------------------------------------------------------------------------ |
|
||||||
|
| `list_resources` | Lists all resources, including state, health status, source, endpoints, and commands |
|
||||||
|
| `list_console_logs` | Lists console logs for a resource |
|
||||||
|
| `list_structured_logs` | Lists structured logs, optionally filtered by resource name |
|
||||||
|
| `list_traces` | Lists distributed traces. Traces can be filtered using an optional resource name parameter |
|
||||||
|
| `list_trace_structured_logs` | Lists structured logs for a specific trace |
|
||||||
|
| `execute_resource_command` | Executes a resource command (accepts resource name and command name) |
|
||||||
|
|
||||||
|
#### AppHost management tools
|
||||||
|
|
||||||
|
| Tool | Description |
|
||||||
|
| ---------------- | ------------------------------------------------------------------------------------------- |
|
||||||
|
| `list_apphosts` | Lists all detected AppHost connections, showing which are in/out of working directory scope |
|
||||||
|
| `select_apphost` | Selects which AppHost to use when multiple are running |
|
||||||
|
|
||||||
|
#### Integration tools
|
||||||
|
|
||||||
|
These work without a running AppHost.
|
||||||
|
|
||||||
|
| Tool | Description |
|
||||||
|
| ---------------------- | ----------------------------------------------------------------------------------------------------------------- |
|
||||||
|
| `list_integrations` | Lists available Aspire hosting integrations (NuGet packages for databases, message brokers, cloud services, etc.) |
|
||||||
|
| `get_integration_docs` | Gets documentation for a specific Aspire hosting integration package |
|
||||||
|
|
||||||
|
### Tools added in 13.2+ (documentation search)
|
||||||
|
|
||||||
|
> **Version gate:** These tools were added in [PR #14028](https://github.com/dotnet/aspire/pull/14028) and ship in Aspire CLI **13.2**. If you are on 13.1, these tools will NOT appear. To get them early, update to the daily channel: `aspire update --self --channel daily`.
|
||||||
|
|
||||||
|
| Tool | Description |
|
||||||
|
| ------------- | ------------------------------------------------------------------------ |
|
||||||
|
| `list_docs` | Lists all available documentation from aspire.dev |
|
||||||
|
| `search_docs` | Performs weighted lexical search across indexed aspire.dev documentation |
|
||||||
|
| `get_doc` | Retrieves a specific document by its slug |
|
||||||
|
|
||||||
|
These tools index aspire.dev content using the `llms.txt` specification and provide weighted lexical search (titles 10x, summaries 8x, headings 6x, code 5x, body 1x). They work without a running AppHost.
|
||||||
|
|
||||||
|
### Fallback for documentation (13.1 users)
|
||||||
|
|
||||||
|
If you are on Aspire CLI 13.1 and don't have `list_docs`/`search_docs`/`get_doc`, use **Context7** as a fallback for documentation queries. See the [SKILL.md documentation research section](../SKILL.md#1-researching-aspire-documentation) for details.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Excluding Resources from MCP
|
||||||
|
|
||||||
|
Resources and associated telemetry can be excluded from MCP results by annotating the resource:
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
var builder = DistributedApplication.CreateBuilder(args);
|
||||||
|
|
||||||
|
var apiService = builder.AddProject<Projects.Api>("apiservice")
|
||||||
|
.ExcludeFromMcp(); // Hidden from MCP tools
|
||||||
|
|
||||||
|
builder.AddProject<Projects.Web>("webfrontend")
|
||||||
|
.WithExternalHttpEndpoints()
|
||||||
|
.WithReference(apiService);
|
||||||
|
|
||||||
|
builder.Build().Run();
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Supported AI Assistants
|
||||||
|
|
||||||
|
The `aspire mcp init` command supports:
|
||||||
|
|
||||||
|
- [VS Code](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) (GitHub Copilot)
|
||||||
|
- [Copilot CLI](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/use-copilot-cli#add-an-mcp-server)
|
||||||
|
- [Claude Code](https://docs.claude.com/en/docs/claude-code/mcp)
|
||||||
|
- [OpenCode](https://opencode.ai/docs/mcp-servers/)
|
||||||
|
|
||||||
|
The MCP server uses the **STDIO transport protocol** and may work with other agentic coding environments that support this protocol.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Usage Patterns
|
||||||
|
|
||||||
|
### Debugging with AI assistance
|
||||||
|
|
||||||
|
Once MCP is configured, your AI assistant can:
|
||||||
|
|
||||||
|
1. **Inspect running state:**
|
||||||
|
|
||||||
|
- "List all my Aspire resources and their status"
|
||||||
|
- "Is the database healthy?"
|
||||||
|
- "What port is the API running on?"
|
||||||
|
|
||||||
|
2. **Read logs:**
|
||||||
|
|
||||||
|
- "Show me the recent logs from the ML service"
|
||||||
|
- "Are there any errors in the worker logs?"
|
||||||
|
|
||||||
|
3. **View traces:**
|
||||||
|
|
||||||
|
- "Show me the trace for the last failed request"
|
||||||
|
- "What's the latency for API → Database calls?"
|
||||||
|
|
||||||
|
4. **Control resources:**
|
||||||
|
|
||||||
|
- "Restart the API service"
|
||||||
|
- "Stop the worker while I debug the queue"
|
||||||
|
|
||||||
|
5. **Search docs (13.2+):**
|
||||||
|
- "Search the Aspire docs for Redis caching"
|
||||||
|
- "How do I configure service discovery?"
|
||||||
|
- _(Requires CLI 13.2+. On 13.1, use Context7 or `list_integrations`/`get_integration_docs` for integration-specific docs.)_
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Security Considerations
|
||||||
|
|
||||||
|
- The MCP server only exposes resources from the local AppHost
|
||||||
|
- No authentication is required (local development only)
|
||||||
|
- The STDIO transport only works for the AI tool that spawned the process
|
||||||
|
- **Do not expose the MCP endpoint to the network in production**
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Limitations
|
||||||
|
|
||||||
|
- AI models have limits on data processing. Large data fields (e.g., stack traces) may be truncated.
|
||||||
|
- Requests involving large collections of telemetry may be shortened by omitting older items.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
If you run into issues, check the [open MCP issues on GitHub](https://github.com/dotnet/aspire/issues?q=is%3Aissue+is%3Aopen+label%3Aarea-mcp).
|
||||||
|
|
||||||
|
## See Also
|
||||||
|
|
||||||
|
- [aspire mcp command](https://aspire.dev/reference/cli/commands/aspire-mcp/)
|
||||||
|
- [aspire mcp init command](https://aspire.dev/reference/cli/commands/aspire-mcp-init/)
|
||||||
|
- [aspire mcp start command](https://aspire.dev/reference/cli/commands/aspire-mcp-start/)
|
||||||
|
- [GitHub Copilot in the Dashboard](https://aspire.dev/dashboard/copilot/)
|
||||||
|
- [How I taught AI to read Aspire docs](https://davidpine.dev/posts/aspire-docs-mcp-tools/)
|
||||||
296
skills/aspire/references/polyglot-apis.md
Normal file
296
skills/aspire/references/polyglot-apis.md
Normal file
@@ -0,0 +1,296 @@
|
|||||||
|
# Polyglot APIs — Complete Reference
|
||||||
|
|
||||||
|
Aspire supports 10+ languages/runtimes. The AppHost is always .NET, but orchestrated workloads can be any language. Each language has a hosting method that returns a resource you wire into the dependency graph.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Hosting model differences
|
||||||
|
|
||||||
|
| Model | Resource type | How it runs | Examples |
|
||||||
|
|---|---|---|---|
|
||||||
|
| **Project** | `ProjectResource` | .NET project reference, built by SDK | `AddProject<T>()` |
|
||||||
|
| **Container** | `ContainerResource` | Docker/OCI image | `AddContainer()`, `AddRedis()`, `AddPostgres()` |
|
||||||
|
| **Executable** | `ExecutableResource` | Native OS process | `AddExecutable()`, all `Add*App()` polyglot methods |
|
||||||
|
|
||||||
|
All polyglot `Add*App()` methods create `ExecutableResource` instances under the hood. They don't require the target language's SDK on the AppHost side — only that the workload's runtime is installed on the dev machine.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Official (Microsoft-maintained)
|
||||||
|
|
||||||
|
### .NET / C\#
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
builder.AddProject<Projects.MyApi>("api")
|
||||||
|
```
|
||||||
|
|
||||||
|
**Chaining methods:**
|
||||||
|
- `.WithHttpEndpoint(port?, targetPort?, name?)` — expose HTTP endpoint
|
||||||
|
- `.WithHttpsEndpoint(port?, targetPort?, name?)` — expose HTTPS endpoint
|
||||||
|
- `.WithEndpoint(port?, targetPort?, scheme?, name?)` — generic endpoint
|
||||||
|
- `.WithReference(resource)` — wire dependency (connection string or service discovery)
|
||||||
|
- `.WithReplicas(count)` — run multiple instances
|
||||||
|
- `.WithEnvironment(key, value)` — set environment variable
|
||||||
|
- `.WithEnvironment(callback)` — set env vars via callback (deferred resolution)
|
||||||
|
- `.WaitFor(resource)` — don't start until dependency is healthy
|
||||||
|
- `.WithExternalHttpEndpoints()` — mark endpoints as externally accessible
|
||||||
|
- `.WithOtlpExporter()` — configure OpenTelemetry exporter
|
||||||
|
- `.PublishAsDockerFile()` — override publish behavior to Dockerfile
|
||||||
|
|
||||||
|
### Python
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
// Standard Python script
|
||||||
|
builder.AddPythonApp("service", "../python-service", "main.py")
|
||||||
|
|
||||||
|
// Uvicorn ASGI server (FastAPI, Starlette, etc.)
|
||||||
|
builder.AddUvicornApp("fastapi", "../fastapi-app", "app:app")
|
||||||
|
```
|
||||||
|
|
||||||
|
**`AddPythonApp(name, projectDirectory, scriptPath, args?)`**
|
||||||
|
|
||||||
|
Chaining methods:
|
||||||
|
- `.WithHttpEndpoint(port?, targetPort?, name?)` — expose HTTP
|
||||||
|
- `.WithVirtualEnvironment(path?)` — use venv (default: `.venv`)
|
||||||
|
- `.WithPipPackages(packages)` — install pip packages on start
|
||||||
|
- `.WithReference(resource)` — wire dependency
|
||||||
|
- `.WithEnvironment(key, value)` — set env var
|
||||||
|
- `.WaitFor(resource)` — wait for dependency health
|
||||||
|
|
||||||
|
**`AddUvicornApp(name, projectDirectory, appModule, args?)`**
|
||||||
|
|
||||||
|
Chaining methods:
|
||||||
|
- `.WithHttpEndpoint(port?, targetPort?, name?)` — expose HTTP
|
||||||
|
- `.WithVirtualEnvironment(path?)` — use venv
|
||||||
|
- `.WithReference(resource)` — wire dependency
|
||||||
|
- `.WithEnvironment(key, value)` — set env var
|
||||||
|
- `.WaitFor(resource)` — wait for dependency health
|
||||||
|
|
||||||
|
**Python service discovery:** Environment variables are injected automatically. Use `os.environ` to read:
|
||||||
|
```python
|
||||||
|
import os
|
||||||
|
redis_conn = os.environ["ConnectionStrings__cache"]
|
||||||
|
api_url = os.environ["services__api__http__0"]
|
||||||
|
```
|
||||||
|
|
||||||
|
### JavaScript / TypeScript
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
// Generic JavaScript app (npm start)
|
||||||
|
builder.AddJavaScriptApp("frontend", "../web-app")
|
||||||
|
|
||||||
|
// Vite dev server
|
||||||
|
builder.AddViteApp("spa", "../vite-app")
|
||||||
|
|
||||||
|
// Node.js script
|
||||||
|
builder.AddNodeApp("worker", "server.js", "../node-worker")
|
||||||
|
```
|
||||||
|
|
||||||
|
**`AddJavaScriptApp(name, workingDirectory)`**
|
||||||
|
|
||||||
|
Chaining methods:
|
||||||
|
- `.WithHttpEndpoint(port?, targetPort?, name?)` — expose HTTP
|
||||||
|
- `.WithNpmPackageInstallation()` — run `npm install` before start
|
||||||
|
- `.WithReference(resource)` — wire dependency
|
||||||
|
- `.WithEnvironment(key, value)` — set env var
|
||||||
|
- `.WaitFor(resource)` — wait for dependency health
|
||||||
|
|
||||||
|
**`AddViteApp(name, workingDirectory)`**
|
||||||
|
|
||||||
|
Chaining methods (same as `AddJavaScriptApp` plus):
|
||||||
|
- `.WithNpmPackageInstallation()` — run `npm install` before start
|
||||||
|
- `.WithHttpEndpoint(port?, targetPort?, name?)` — Vite defaults to 5173
|
||||||
|
|
||||||
|
**`AddNodeApp(name, scriptPath, workingDirectory)`**
|
||||||
|
|
||||||
|
Chaining methods:
|
||||||
|
- `.WithHttpEndpoint(port?, targetPort?, name?)` — expose HTTP
|
||||||
|
- `.WithNpmPackageInstallation()` — run `npm install` before start
|
||||||
|
- `.WithReference(resource)` — wire dependency
|
||||||
|
- `.WithEnvironment(key, value)` — set env var
|
||||||
|
|
||||||
|
**JS/TS service discovery:** Environment variables are injected. Use `process.env`:
|
||||||
|
```javascript
|
||||||
|
const redisUrl = process.env.ConnectionStrings__cache;
|
||||||
|
const apiUrl = process.env.services__api__http__0;
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Community (CommunityToolkit/Aspire)
|
||||||
|
|
||||||
|
All community integrations follow the same pattern: install the NuGet package in your AppHost, then use the `Add*App()` method.
|
||||||
|
|
||||||
|
### Go
|
||||||
|
|
||||||
|
**Package:** `CommunityToolkit.Aspire.Hosting.Golang`
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
builder.AddGolangApp("go-api", "../go-service")
|
||||||
|
.WithHttpEndpoint(targetPort: 8080)
|
||||||
|
.WithReference(redis)
|
||||||
|
.WithEnvironment("LOG_LEVEL", "debug")
|
||||||
|
.WaitFor(redis);
|
||||||
|
```
|
||||||
|
|
||||||
|
Chaining methods:
|
||||||
|
- `.WithHttpEndpoint(port?, targetPort?, name?)`
|
||||||
|
- `.WithReference(resource)`
|
||||||
|
- `.WithEnvironment(key, value)`
|
||||||
|
- `.WaitFor(resource)`
|
||||||
|
|
||||||
|
**Go service discovery:** Standard env vars via `os.Getenv()`:
|
||||||
|
```go
|
||||||
|
redisAddr := os.Getenv("ConnectionStrings__cache")
|
||||||
|
```
|
||||||
|
|
||||||
|
### Java (Spring Boot)
|
||||||
|
|
||||||
|
**Package:** `CommunityToolkit.Aspire.Hosting.Java`
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
builder.AddSpringApp("spring-api", "../spring-service")
|
||||||
|
.WithHttpEndpoint(targetPort: 8080)
|
||||||
|
.WithReference(postgres)
|
||||||
|
.WaitFor(postgres);
|
||||||
|
```
|
||||||
|
|
||||||
|
Chaining methods:
|
||||||
|
- `.WithHttpEndpoint(port?, targetPort?, name?)`
|
||||||
|
- `.WithReference(resource)`
|
||||||
|
- `.WithEnvironment(key, value)`
|
||||||
|
- `.WaitFor(resource)`
|
||||||
|
- `.WithMavenBuild()` — run Maven build before start
|
||||||
|
- `.WithGradleBuild()` — run Gradle build before start
|
||||||
|
|
||||||
|
**Java service discovery:** Env vars via `System.getenv()`:
|
||||||
|
```java
|
||||||
|
String dbConn = System.getenv("ConnectionStrings__db");
|
||||||
|
```
|
||||||
|
|
||||||
|
### Rust
|
||||||
|
|
||||||
|
**Package:** `CommunityToolkit.Aspire.Hosting.Rust`
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
builder.AddRustApp("rust-worker", "../rust-service")
|
||||||
|
.WithHttpEndpoint(targetPort: 3000)
|
||||||
|
.WithReference(redis)
|
||||||
|
.WaitFor(redis);
|
||||||
|
```
|
||||||
|
|
||||||
|
Chaining methods:
|
||||||
|
- `.WithHttpEndpoint(port?, targetPort?, name?)`
|
||||||
|
- `.WithReference(resource)`
|
||||||
|
- `.WithEnvironment(key, value)`
|
||||||
|
- `.WaitFor(resource)`
|
||||||
|
- `.WithCargoBuild()` — run `cargo build` before start
|
||||||
|
|
||||||
|
### Bun
|
||||||
|
|
||||||
|
**Package:** `CommunityToolkit.Aspire.Hosting.Bun`
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
builder.AddBunApp("bun-api", "../bun-service")
|
||||||
|
.WithHttpEndpoint(targetPort: 3000)
|
||||||
|
.WithReference(redis);
|
||||||
|
```
|
||||||
|
|
||||||
|
Chaining methods:
|
||||||
|
- `.WithHttpEndpoint(port?, targetPort?, name?)`
|
||||||
|
- `.WithReference(resource)`
|
||||||
|
- `.WithEnvironment(key, value)`
|
||||||
|
- `.WaitFor(resource)`
|
||||||
|
- `.WithBunPackageInstallation()` — run `bun install` before start
|
||||||
|
|
||||||
|
### Deno
|
||||||
|
|
||||||
|
**Package:** `CommunityToolkit.Aspire.Hosting.Deno`
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
builder.AddDenoApp("deno-api", "../deno-service")
|
||||||
|
.WithHttpEndpoint(targetPort: 8000)
|
||||||
|
.WithReference(redis);
|
||||||
|
```
|
||||||
|
|
||||||
|
Chaining methods:
|
||||||
|
- `.WithHttpEndpoint(port?, targetPort?, name?)`
|
||||||
|
- `.WithReference(resource)`
|
||||||
|
- `.WithEnvironment(key, value)`
|
||||||
|
- `.WaitFor(resource)`
|
||||||
|
|
||||||
|
### PowerShell
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
builder.AddPowerShell("ps-script", "../scripts/process.ps1")
|
||||||
|
.WithReference(storageAccount);
|
||||||
|
```
|
||||||
|
|
||||||
|
### Dapr
|
||||||
|
|
||||||
|
**Package:** `Aspire.Hosting.Dapr` (official)
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
var dapr = builder.AddDapr();
|
||||||
|
var api = builder.AddProject<Projects.Api>("api")
|
||||||
|
.WithDaprSidecar("api-sidecar");
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Complete mixed-language example
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
var builder = DistributedApplication.CreateBuilder(args);
|
||||||
|
|
||||||
|
// Infrastructure
|
||||||
|
var redis = builder.AddRedis("cache");
|
||||||
|
var postgres = builder.AddPostgres("pg").AddDatabase("catalog");
|
||||||
|
var mongo = builder.AddMongoDB("mongo").AddDatabase("analytics");
|
||||||
|
var rabbit = builder.AddRabbitMQ("messaging");
|
||||||
|
|
||||||
|
// .NET API (primary)
|
||||||
|
var api = builder.AddProject<Projects.CatalogApi>("api")
|
||||||
|
.WithReference(postgres)
|
||||||
|
.WithReference(redis)
|
||||||
|
.WithReference(rabbit)
|
||||||
|
.WaitFor(postgres)
|
||||||
|
.WaitFor(redis);
|
||||||
|
|
||||||
|
// Python ML service (FastAPI)
|
||||||
|
var ml = builder.AddUvicornApp("ml", "../ml-service", "app:app")
|
||||||
|
.WithHttpEndpoint(targetPort: 8000)
|
||||||
|
.WithVirtualEnvironment()
|
||||||
|
.WithReference(redis)
|
||||||
|
.WithReference(mongo)
|
||||||
|
.WaitFor(redis);
|
||||||
|
|
||||||
|
// TypeScript frontend (Vite + React)
|
||||||
|
var web = builder.AddViteApp("web", "../frontend")
|
||||||
|
.WithNpmPackageInstallation()
|
||||||
|
.WithHttpEndpoint(targetPort: 5173)
|
||||||
|
.WithReference(api);
|
||||||
|
|
||||||
|
// Go event processor
|
||||||
|
var processor = builder.AddGolangApp("processor", "../go-processor")
|
||||||
|
.WithReference(rabbit)
|
||||||
|
.WithReference(mongo)
|
||||||
|
.WaitFor(rabbit);
|
||||||
|
|
||||||
|
// Java analytics service (Spring Boot)
|
||||||
|
var analytics = builder.AddSpringApp("analytics", "../spring-analytics")
|
||||||
|
.WithHttpEndpoint(targetPort: 8080)
|
||||||
|
.WithReference(mongo)
|
||||||
|
.WithReference(rabbit)
|
||||||
|
.WaitFor(mongo);
|
||||||
|
|
||||||
|
// Rust high-perf worker
|
||||||
|
var worker = builder.AddRustApp("worker", "../rust-worker")
|
||||||
|
.WithReference(redis)
|
||||||
|
.WithReference(rabbit)
|
||||||
|
.WaitFor(redis);
|
||||||
|
|
||||||
|
builder.Build().Run();
|
||||||
|
```
|
||||||
|
|
||||||
|
This single AppHost starts 6 services across 5 languages plus 4 infrastructure resources, all wired together with automatic service discovery.
|
||||||
281
skills/aspire/references/testing.md
Normal file
281
skills/aspire/references/testing.md
Normal file
@@ -0,0 +1,281 @@
|
|||||||
|
# Testing — Complete Reference
|
||||||
|
|
||||||
|
Aspire provides `Aspire.Hosting.Testing` for running integration tests against your full AppHost. Tests spin up the entire distributed application (or a subset) and run assertions against real services.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Package
|
||||||
|
|
||||||
|
```xml
|
||||||
|
<PackageReference Include="Aspire.Hosting.Testing" Version="*" />
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Core pattern: DistributedApplicationTestingBuilder
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
// 1. Create a testing builder from your AppHost
|
||||||
|
var builder = await DistributedApplicationTestingBuilder
|
||||||
|
.CreateAsync<Projects.MyAppHost>();
|
||||||
|
|
||||||
|
// 2. (Optional) Override resources for testing
|
||||||
|
// ... see customization section below
|
||||||
|
|
||||||
|
// 3. Build and start the application
|
||||||
|
await using var app = await builder.BuildAsync();
|
||||||
|
await app.StartAsync();
|
||||||
|
|
||||||
|
// 4. Create HTTP clients for your services
|
||||||
|
var client = app.CreateHttpClient("api");
|
||||||
|
|
||||||
|
// 5. Run assertions
|
||||||
|
var response = await client.GetAsync("/health");
|
||||||
|
Assert.Equal(HttpStatusCode.OK, response.StatusCode);
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## xUnit examples
|
||||||
|
|
||||||
|
### Basic health check test
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
public class HealthTests(ITestOutputHelper output)
|
||||||
|
{
|
||||||
|
[Fact]
|
||||||
|
public async Task AllServicesAreHealthy()
|
||||||
|
{
|
||||||
|
var builder = await DistributedApplicationTestingBuilder
|
||||||
|
.CreateAsync<Projects.AppHost>();
|
||||||
|
|
||||||
|
await using var app = await builder.BuildAsync();
|
||||||
|
await app.StartAsync();
|
||||||
|
|
||||||
|
// Test each service's health endpoint
|
||||||
|
var apiClient = app.CreateHttpClient("api");
|
||||||
|
var apiHealth = await apiClient.GetAsync("/health");
|
||||||
|
Assert.Equal(HttpStatusCode.OK, apiHealth.StatusCode);
|
||||||
|
|
||||||
|
var workerClient = app.CreateHttpClient("worker");
|
||||||
|
var workerHealth = await workerClient.GetAsync("/health");
|
||||||
|
Assert.Equal(HttpStatusCode.OK, workerHealth.StatusCode);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### API integration test
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
public class ApiTests(ITestOutputHelper output)
|
||||||
|
{
|
||||||
|
[Fact]
|
||||||
|
public async Task CreateOrder_ReturnsCreated()
|
||||||
|
{
|
||||||
|
var builder = await DistributedApplicationTestingBuilder
|
||||||
|
.CreateAsync<Projects.AppHost>();
|
||||||
|
|
||||||
|
await using var app = await builder.BuildAsync();
|
||||||
|
await app.StartAsync();
|
||||||
|
|
||||||
|
var client = app.CreateHttpClient("api");
|
||||||
|
|
||||||
|
var order = new { ProductId = 1, Quantity = 2 };
|
||||||
|
var response = await client.PostAsJsonAsync("/orders", order);
|
||||||
|
|
||||||
|
Assert.Equal(HttpStatusCode.Created, response.StatusCode);
|
||||||
|
|
||||||
|
var created = await response.Content.ReadFromJsonAsync<Order>();
|
||||||
|
Assert.NotNull(created);
|
||||||
|
Assert.Equal(1, created.ProductId);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Testing with wait for readiness
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
[Fact]
|
||||||
|
public async Task DatabaseIsSeeded()
|
||||||
|
{
|
||||||
|
var builder = await DistributedApplicationTestingBuilder
|
||||||
|
.CreateAsync<Projects.AppHost>();
|
||||||
|
|
||||||
|
await using var app = await builder.BuildAsync();
|
||||||
|
await app.StartAsync();
|
||||||
|
|
||||||
|
// Wait for the API to be fully ready (all dependencies healthy)
|
||||||
|
await app.WaitForResourceReadyAsync("api");
|
||||||
|
|
||||||
|
var client = app.CreateHttpClient("api");
|
||||||
|
var response = await client.GetAsync("/products");
|
||||||
|
|
||||||
|
Assert.Equal(HttpStatusCode.OK, response.StatusCode);
|
||||||
|
var products = await response.Content.ReadFromJsonAsync<List<Product>>();
|
||||||
|
Assert.NotEmpty(products);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## MSTest examples
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
[TestClass]
|
||||||
|
public class IntegrationTests
|
||||||
|
{
|
||||||
|
[TestMethod]
|
||||||
|
public async Task ApiReturnsProducts()
|
||||||
|
{
|
||||||
|
var builder = await DistributedApplicationTestingBuilder
|
||||||
|
.CreateAsync<Projects.AppHost>();
|
||||||
|
|
||||||
|
await using var app = await builder.BuildAsync();
|
||||||
|
await app.StartAsync();
|
||||||
|
|
||||||
|
var client = app.CreateHttpClient("api");
|
||||||
|
var response = await client.GetAsync("/products");
|
||||||
|
|
||||||
|
Assert.AreEqual(HttpStatusCode.OK, response.StatusCode);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## NUnit examples
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
[TestFixture]
|
||||||
|
public class IntegrationTests
|
||||||
|
{
|
||||||
|
[Test]
|
||||||
|
public async Task ApiReturnsProducts()
|
||||||
|
{
|
||||||
|
var builder = await DistributedApplicationTestingBuilder
|
||||||
|
.CreateAsync<Projects.AppHost>();
|
||||||
|
|
||||||
|
await using var app = await builder.BuildAsync();
|
||||||
|
await app.StartAsync();
|
||||||
|
|
||||||
|
var client = app.CreateHttpClient("api");
|
||||||
|
var response = await client.GetAsync("/products");
|
||||||
|
|
||||||
|
Assert.That(response.StatusCode, Is.EqualTo(HttpStatusCode.OK));
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Customizing the test AppHost
|
||||||
|
|
||||||
|
### Override resources
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
var builder = await DistributedApplicationTestingBuilder
|
||||||
|
.CreateAsync<Projects.AppHost>();
|
||||||
|
|
||||||
|
// Replace a real database with a test container
|
||||||
|
builder.Services.ConfigureHttpClientDefaults(http =>
|
||||||
|
{
|
||||||
|
http.AddStandardResilienceHandler();
|
||||||
|
});
|
||||||
|
|
||||||
|
// Add test-specific configuration
|
||||||
|
builder.Configuration["TestMode"] = "true";
|
||||||
|
|
||||||
|
await using var app = await builder.BuildAsync();
|
||||||
|
await app.StartAsync();
|
||||||
|
```
|
||||||
|
|
||||||
|
### Exclude resources
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
var builder = await DistributedApplicationTestingBuilder
|
||||||
|
.CreateAsync<Projects.AppHost>(args =>
|
||||||
|
{
|
||||||
|
// Don't start the worker for API-only tests
|
||||||
|
args.Args = ["--exclude-resource", "worker"];
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
### Test with specific environment
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
var builder = await DistributedApplicationTestingBuilder
|
||||||
|
.CreateAsync<Projects.AppHost>(args =>
|
||||||
|
{
|
||||||
|
args.Args = ["--environment", "Testing"];
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Connection string access
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
// Get the connection string for a resource in tests
|
||||||
|
var connectionString = await app.GetConnectionStringAsync("db");
|
||||||
|
|
||||||
|
// Use it to query the database directly in tests
|
||||||
|
using var conn = new NpgsqlConnection(connectionString);
|
||||||
|
await conn.OpenAsync();
|
||||||
|
var count = await conn.ExecuteScalarAsync<int>("SELECT COUNT(*) FROM products");
|
||||||
|
Assert.True(count > 0);
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Best practices
|
||||||
|
|
||||||
|
1. **Use `WaitForResourceReadyAsync`** before making requests — ensures all dependencies are healthy
|
||||||
|
2. **Each test should be independent** — don't rely on state from previous tests
|
||||||
|
3. **Use `await using`** for the app — ensures cleanup even on test failure
|
||||||
|
4. **Test real infrastructure** — Aspire spins up real containers (Redis, PostgreSQL, etc.), giving you high-fidelity integration tests
|
||||||
|
5. **Keep test AppHost lean** — exclude resources you don't need for specific test scenarios
|
||||||
|
6. **Use test-specific configuration** — override settings for test isolation
|
||||||
|
7. **Timeout protection** — set reasonable test timeouts since containers take time to start:
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
[Fact(Timeout = 120_000)] // 2 minutes
|
||||||
|
public async Task SlowIntegrationTest() { ... }
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Project structure
|
||||||
|
|
||||||
|
```
|
||||||
|
MyApp/
|
||||||
|
├── src/
|
||||||
|
│ ├── MyApp.AppHost/ # AppHost project
|
||||||
|
│ ├── MyApp.Api/ # API service
|
||||||
|
│ ├── MyApp.Worker/ # Worker service
|
||||||
|
│ └── MyApp.ServiceDefaults/ # Shared defaults
|
||||||
|
└── tests/
|
||||||
|
└── MyApp.Tests/ # Integration tests
|
||||||
|
├── MyApp.Tests.csproj # References AppHost + Testing package
|
||||||
|
└── ApiTests.cs # Test classes
|
||||||
|
```
|
||||||
|
|
||||||
|
```xml
|
||||||
|
<!-- MyApp.Tests.csproj -->
|
||||||
|
<Project Sdk="Microsoft.NET.Sdk">
|
||||||
|
<PropertyGroup>
|
||||||
|
<TargetFramework>net10.0</TargetFramework>
|
||||||
|
<IsAspireTestProject>true</IsAspireTestProject>
|
||||||
|
</PropertyGroup>
|
||||||
|
|
||||||
|
<ItemGroup>
|
||||||
|
<PackageReference Include="Aspire.Hosting.Testing" Version="*" />
|
||||||
|
<PackageReference Include="Microsoft.NET.Test.Sdk" Version="*" />
|
||||||
|
<PackageReference Include="xunit" Version="*" />
|
||||||
|
<PackageReference Include="xunit.runner.visualstudio" Version="*" />
|
||||||
|
</ItemGroup>
|
||||||
|
|
||||||
|
<ItemGroup>
|
||||||
|
<ProjectReference Include="..\..\src\MyApp.AppHost\MyApp.AppHost.csproj" />
|
||||||
|
</ItemGroup>
|
||||||
|
</Project>
|
||||||
|
```
|
||||||
194
skills/aspire/references/troubleshooting.md
Normal file
194
skills/aspire/references/troubleshooting.md
Normal file
@@ -0,0 +1,194 @@
|
|||||||
|
# Troubleshooting — Diagnostics & Common Issues
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Diagnostic Codes
|
||||||
|
|
||||||
|
Aspire emits diagnostic codes for common issues. These appear in build warnings/errors and IDE diagnostics.
|
||||||
|
|
||||||
|
### Standard diagnostics
|
||||||
|
|
||||||
|
| Code | Severity | Description |
|
||||||
|
| ------------- | -------- | ---------------------------------------------------------- |
|
||||||
|
| **ASPIRE001** | Warning | Resource name contains invalid characters |
|
||||||
|
| **ASPIRE002** | Warning | Duplicate resource name detected |
|
||||||
|
| **ASPIRE003** | Error | Missing required package reference |
|
||||||
|
| **ASPIRE004** | Warning | Deprecated API usage |
|
||||||
|
| **ASPIRE005** | Error | Invalid endpoint configuration |
|
||||||
|
| **ASPIRE006** | Warning | Health check not configured for resource with `.WaitFor()` |
|
||||||
|
| **ASPIRE007** | Warning | Container image tag not specified (using `latest`) |
|
||||||
|
| **ASPIRE008** | Error | Circular dependency detected in resource graph |
|
||||||
|
|
||||||
|
### Experimental diagnostics (ASPIREHOSTINGX\*)
|
||||||
|
|
||||||
|
These codes indicate usage of experimental/preview APIs. They may require `#pragma warning disable` or `<NoWarn>` if you intentionally use experimental features:
|
||||||
|
|
||||||
|
| Code | Area |
|
||||||
|
| ------------------------- | -------------------------------- |
|
||||||
|
| ASPIRE_HOSTINGX_0001–0005 | Experimental hosting APIs |
|
||||||
|
| ASPIRE_HOSTINGX_0006–0010 | Experimental integration APIs |
|
||||||
|
| ASPIRE_HOSTINGX_0011–0015 | Experimental deployment APIs |
|
||||||
|
| ASPIRE_HOSTINGX_0016–0022 | Experimental resource model APIs |
|
||||||
|
|
||||||
|
To suppress experimental warnings:
|
||||||
|
|
||||||
|
```xml
|
||||||
|
<!-- In .csproj -->
|
||||||
|
<PropertyGroup>
|
||||||
|
<NoWarn>$(NoWarn);ASPIRE_HOSTINGX_0001</NoWarn>
|
||||||
|
</PropertyGroup>
|
||||||
|
```
|
||||||
|
|
||||||
|
Or per-line:
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
#pragma warning disable ASPIRE_HOSTINGX_0001
|
||||||
|
var resource = builder.AddExperimentalResource("test");
|
||||||
|
#pragma warning restore ASPIRE_HOSTINGX_0001
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Common Issues & Solutions
|
||||||
|
|
||||||
|
### Container runtime
|
||||||
|
|
||||||
|
| Problem | Solution |
|
||||||
|
| --------------------------------- | ------------------------------------------------------------------------------------------------------ |
|
||||||
|
| "Cannot connect to Docker daemon" | Start Docker Desktop / Podman / Rancher Desktop |
|
||||||
|
| Container fails to start | Check `docker ps -a` for exit codes; check dashboard console logs |
|
||||||
|
| Port already in use | Another process is using the port; Aspire auto-assigns, but `targetPort` must be free on the container |
|
||||||
|
| Container image pull fails | Check network connectivity; verify image name and tag |
|
||||||
|
| "Permission denied" on Linux | Add user to `docker` group: `sudo usermod -aG docker $USER` |
|
||||||
|
|
||||||
|
### Service discovery
|
||||||
|
|
||||||
|
| Problem | Solution |
|
||||||
|
| ----------------------------- | ---------------------------------------------------------------------------- |
|
||||||
|
| Service can't find dependency | Verify `.WithReference()` in AppHost; check env vars in dashboard |
|
||||||
|
| Connection string is null | The reference resource name doesn't match; check `ConnectionStrings__<name>` |
|
||||||
|
| Wrong port in service URL | Check `targetPort` vs actual service listen port |
|
||||||
|
| Env var not set | Rebuild AppHost; verify resource name matches exactly |
|
||||||
|
|
||||||
|
### Python workloads
|
||||||
|
|
||||||
|
| Problem | Solution |
|
||||||
|
| --------------------------------- | --------------------------------------------------------------- |
|
||||||
|
| "Python not found" | Ensure Python is on PATH; specify full path in `AddPythonApp()` |
|
||||||
|
| venv not found | Use `.WithVirtualEnvironment()` or create venv manually |
|
||||||
|
| pip packages fail to install | Use `.WithPipPackages()` or install in venv before `aspire run` |
|
||||||
|
| ModuleNotFoundError | venv isn't activated; `.WithVirtualEnvironment()` handles this |
|
||||||
|
| "Port already in use" for Uvicorn | Check `targetPort` — another instance may be running |
|
||||||
|
|
||||||
|
### JavaScript / TypeScript workloads
|
||||||
|
|
||||||
|
| Problem | Solution |
|
||||||
|
| ----------------------------- | ---------------------------------------------------------------- |
|
||||||
|
| "node_modules not found" | Use `.WithNpmPackageInstallation()` to auto-install |
|
||||||
|
| npm install fails | Check `package.json` is valid; check npm registry connectivity |
|
||||||
|
| Vite dev server won't start | Verify `vite` is in devDependencies; check Vite config |
|
||||||
|
| Port mismatch | Ensure `targetPort` matches the port in your JS framework config |
|
||||||
|
| TypeScript compilation errors | These happen in the service, not Aspire — check service logs |
|
||||||
|
|
||||||
|
### Go workloads
|
||||||
|
|
||||||
|
| Problem | Solution |
|
||||||
|
| -------------------------- | ---------------------------------------------------------- |
|
||||||
|
| "go not found" | Ensure Go is installed and on PATH |
|
||||||
|
| Build fails | Check `go.mod` exists in working directory |
|
||||||
|
| "no Go files in directory" | Verify `workingDir` points to the directory with `main.go` |
|
||||||
|
|
||||||
|
### Java workloads
|
||||||
|
|
||||||
|
| Problem | Solution |
|
||||||
|
| ------------------------ | ------------------------------------------------------- |
|
||||||
|
| "java not found" | Ensure JDK is installed and `JAVA_HOME` is set |
|
||||||
|
| Maven/Gradle build fails | Verify build files exist; check build tool installation |
|
||||||
|
| Spring Boot won't start | Check `application.properties`; verify main class |
|
||||||
|
|
||||||
|
### Rust workloads
|
||||||
|
|
||||||
|
| Problem | Solution |
|
||||||
|
| -------------------- | -------------------------------------------------------------------- |
|
||||||
|
| "cargo not found" | Install Rust via rustup |
|
||||||
|
| Build takes too long | Rust compile times are normal; use `.WithCargoBuild()` for pre-build |
|
||||||
|
|
||||||
|
### Health checks & startup
|
||||||
|
|
||||||
|
| Problem | Solution |
|
||||||
|
| ---------------------------- | ------------------------------------------------------------------------------ |
|
||||||
|
| Resource stuck in "Starting" | Health check endpoint not responding; check service logs |
|
||||||
|
| `.WaitFor()` timeout | Increase timeout or fix health endpoint; default is 30 seconds |
|
||||||
|
| Health check always fails | Verify endpoint path (default: `/health`); check service binds to correct port |
|
||||||
|
| Cascading startup failures | A dependency failed; check the root resource first |
|
||||||
|
|
||||||
|
### Dashboard
|
||||||
|
|
||||||
|
| Problem | Solution |
|
||||||
|
| ------------------------------------- | ------------------------------------------------------------------------- |
|
||||||
|
| Dashboard doesn't open | Check terminal for URL; use `--dashboard-port` for fixed port |
|
||||||
|
| No logs appearing | Service may not be writing to stdout/stderr; check console output |
|
||||||
|
| No traces for non-.NET services | Configure OpenTelemetry SDK in the service; see [Dashboard](dashboard.md) |
|
||||||
|
| Traces don't show cross-service calls | Propagate trace context headers (`traceparent`, `tracestate`) |
|
||||||
|
|
||||||
|
### Build & configuration
|
||||||
|
|
||||||
|
| Problem | Solution |
|
||||||
|
| ----------------------------------------- | ------------------------------------------------------------------- |
|
||||||
|
| "Project not found" for `AddProject<T>()` | Ensure `.csproj` is in the solution and referenced by AppHost |
|
||||||
|
| Package version conflicts | Pin all Aspire packages to the same version |
|
||||||
|
| AppHost won't build | Check `Aspire.AppHost.Sdk` is in the project; run `dotnet restore` |
|
||||||
|
| `aspire run` build error | Fix the build error first; `aspire run` requires a successful build |
|
||||||
|
|
||||||
|
### Deployment
|
||||||
|
|
||||||
|
| Problem | Solution |
|
||||||
|
| ---------------------------------------- | -------------------------------------------------------------------- |
|
||||||
|
| `aspire publish` fails | Check publisher package is installed (e.g., `Aspire.Hosting.Docker`) |
|
||||||
|
| Generated Bicep has errors | Check for unsupported resource configurations |
|
||||||
|
| Container image push fails | Verify registry credentials and permissions |
|
||||||
|
| Missing connection strings in deployment | Check generated ConfigMaps/Secrets match resource names |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Debugging strategies
|
||||||
|
|
||||||
|
### 1. Check the dashboard first
|
||||||
|
|
||||||
|
The dashboard shows resource state, logs, traces, and metrics. Start here for any issue.
|
||||||
|
|
||||||
|
### 2. Check environment variables
|
||||||
|
|
||||||
|
In the dashboard, click a resource to see all injected environment variables. Verify connection strings and service URLs are correct.
|
||||||
|
|
||||||
|
### 3. Read console logs
|
||||||
|
|
||||||
|
Dashboard → Console Logs → filter by the failing resource. Raw stdout/stderr often contains the root cause.
|
||||||
|
|
||||||
|
### 4. Check the DAG
|
||||||
|
|
||||||
|
If services fail to start, check the dependency order. A failed dependency blocks all downstream resources.
|
||||||
|
|
||||||
|
### 5. Use MCP for AI-assisted debugging
|
||||||
|
|
||||||
|
If MCP is configured (see [MCP Server](mcp-server.md)), ask your AI assistant:
|
||||||
|
|
||||||
|
- "What resources are failing?"
|
||||||
|
- "Show me the logs for [service]"
|
||||||
|
- "What traces show errors?"
|
||||||
|
|
||||||
|
### 6. Isolate the problem
|
||||||
|
|
||||||
|
Run just the failing resource by commenting out others in the AppHost. This narrows whether the issue is the resource itself or a dependency.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Getting help
|
||||||
|
|
||||||
|
| Channel | URL |
|
||||||
|
| ----------------------- | ---------------------------------------------- |
|
||||||
|
| GitHub Issues (runtime) | https://github.com/dotnet/aspire/issues |
|
||||||
|
| GitHub Issues (docs) | https://github.com/microsoft/aspire.dev/issues |
|
||||||
|
| Discord | https://aka.ms/aspire/discord |
|
||||||
|
| Stack Overflow | Tag: `dotnet-aspire` |
|
||||||
|
| Reddit | https://www.reddit.com/r/aspiredotdev/ |
|
||||||
774
skills/copilot-cli-quickstart/SKILL.md
Normal file
774
skills/copilot-cli-quickstart/SKILL.md
Normal file
@@ -0,0 +1,774 @@
|
|||||||
|
---
|
||||||
|
name: copilot-cli-quickstart
|
||||||
|
description: >
|
||||||
|
Use this skill when someone wants to learn GitHub Copilot CLI from scratch.
|
||||||
|
Offers interactive step-by-step tutorials with separate Developer and
|
||||||
|
Non-Developer tracks, plus on-demand Q&A. Just say "start tutorial" or
|
||||||
|
ask a question! Note: This skill targets GitHub Copilot CLI specifically
|
||||||
|
and uses CLI-specific tools (ask_user, sql, fetch_copilot_cli_documentation).
|
||||||
|
allowed-tools: ask_user, sql, fetch_copilot_cli_documentation
|
||||||
|
---
|
||||||
|
|
||||||
|
# 🚀 Copilot CLI Quick Start — Your Friendly Terminal Tutor
|
||||||
|
|
||||||
|
You are an enthusiastic, encouraging tutor that helps beginners learn GitHub Copilot CLI.
|
||||||
|
You make the terminal feel approachable and fun — never scary. 🐙 Use lots of emojis, celebrate
|
||||||
|
small wins, and always explain *why* before *how*.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎯 Three Modes
|
||||||
|
|
||||||
|
### 🎓 Tutorial Mode
|
||||||
|
Triggered when the user says things like "start tutorial", "teach me", "lesson 1", "next lesson", or "begin".
|
||||||
|
|
||||||
|
### ❓ Q&A Mode
|
||||||
|
Triggered when the user asks a specific question like "what does /plan do?" or "how do I mention files?"
|
||||||
|
|
||||||
|
### 🔄 Reset Mode
|
||||||
|
Triggered when the user says "reset tutorial", "start over", or "restart".
|
||||||
|
|
||||||
|
If the intent is unclear, ask! Use the `ask_user` tool:
|
||||||
|
```
|
||||||
|
"Hey! 👋 Would you like to jump into a guided tutorial, or do you have a specific question?"
|
||||||
|
choices: ["🎓 Start the tutorial from the beginning", "❓ I have a question"]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🛤️ Audience Detection
|
||||||
|
|
||||||
|
On the very first tutorial interaction, determine the user's track:
|
||||||
|
|
||||||
|
```
|
||||||
|
Use ask_user:
|
||||||
|
"Welcome to Copilot CLI Quick Start! 🚀🐙
|
||||||
|
|
||||||
|
To give you the best experience, which describes you?"
|
||||||
|
choices: [
|
||||||
|
"🧑💻 Developer — I write code and use the terminal",
|
||||||
|
"🎨 Non-Developer — I'm a PM, designer, writer, or just curious"
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
Store the choice in SQL:
|
||||||
|
```sql
|
||||||
|
CREATE TABLE IF NOT EXISTS user_profile (
|
||||||
|
key TEXT PRIMARY KEY,
|
||||||
|
value TEXT
|
||||||
|
);
|
||||||
|
INSERT OR REPLACE INTO user_profile (key, value) VALUES ('track', 'developer');
|
||||||
|
-- or ('track', 'non-developer')
|
||||||
|
```
|
||||||
|
|
||||||
|
If the user says "switch track", "I'm actually a developer", or similar — update the track and adjust the lesson list.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📊 Progress Tracking
|
||||||
|
|
||||||
|
On first interaction, create the tracking table:
|
||||||
|
|
||||||
|
```sql
|
||||||
|
CREATE TABLE IF NOT EXISTS lesson_progress (
|
||||||
|
lesson_id TEXT PRIMARY KEY,
|
||||||
|
title TEXT NOT NULL,
|
||||||
|
track TEXT NOT NULL,
|
||||||
|
status TEXT DEFAULT 'not_started',
|
||||||
|
completed_at TEXT
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
Insert lessons based on the user's track (see lesson lists below).
|
||||||
|
|
||||||
|
Before starting a lesson, check what's done:
|
||||||
|
```sql
|
||||||
|
SELECT * FROM lesson_progress ORDER BY lesson_id;
|
||||||
|
```
|
||||||
|
|
||||||
|
After completing a lesson:
|
||||||
|
```sql
|
||||||
|
UPDATE lesson_progress SET status = 'done', completed_at = datetime('now') WHERE lesson_id = ?;
|
||||||
|
```
|
||||||
|
|
||||||
|
### 🔄 Reset Tutorial
|
||||||
|
When the user says "reset tutorial" or "start over":
|
||||||
|
```sql
|
||||||
|
DROP TABLE IF EXISTS lesson_progress;
|
||||||
|
DROP TABLE IF EXISTS user_profile;
|
||||||
|
```
|
||||||
|
Then confirm: "Tutorial reset! 🔄 Ready to start fresh? 🚀" and re-run audience detection.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📚 Lesson Structure
|
||||||
|
|
||||||
|
### Shared Lessons (Both Tracks)
|
||||||
|
|
||||||
|
| ID | Lesson | Both tracks |
|
||||||
|
|----|--------|-------------|
|
||||||
|
| `S1` | 🏠 Welcome & Verify | ✅ |
|
||||||
|
| `S2` | 💬 Your First Prompt | ✅ |
|
||||||
|
| `S3` | 🎮 The Permission Model | ✅ |
|
||||||
|
|
||||||
|
### 🧑💻 Developer Track
|
||||||
|
|
||||||
|
| ID | Lesson | Developer only |
|
||||||
|
|----|--------|----------------|
|
||||||
|
| `D1` | 🎛️ Slash Commands & Modes | ✅ |
|
||||||
|
| `D2` | 📎 Mentioning Files with @ | ✅ |
|
||||||
|
| `D3` | 📋 Planning with /plan | ✅ |
|
||||||
|
| `D4` | ⚙️ Custom Instructions | ✅ |
|
||||||
|
| `D5` | 🚀 Advanced: MCP, Skills & Beyond | ✅ |
|
||||||
|
|
||||||
|
### 🎨 Non-Developer Track
|
||||||
|
|
||||||
|
| ID | Lesson | Non-developer only |
|
||||||
|
|----|--------|---------------------|
|
||||||
|
| `N1` | 📝 Writing & Editing with Copilot | ✅ |
|
||||||
|
| `N2` | 📋 Task Planning with /plan | ✅ |
|
||||||
|
| `N3` | 🔍 Understanding Code (Without Writing It) | ✅ |
|
||||||
|
| `N4` | 📊 Getting Summaries & Explanations | ✅ |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🏠 Lesson S1: Welcome & Verify Your Setup
|
||||||
|
|
||||||
|
**Goal:** Confirm Copilot CLI is working and explore the basics! 🎉
|
||||||
|
|
||||||
|
> 💡 **Key insight:** Since the user is talking to you through this skill, they've already
|
||||||
|
> installed Copilot CLI! Celebrate this — don't teach installation. Instead, verify and explore.
|
||||||
|
|
||||||
|
**Teach these concepts:**
|
||||||
|
|
||||||
|
1. **You did it!** 🎉 — Acknowledge that they're already running Copilot CLI. That means installation is done! No need to install anything. They're already here!
|
||||||
|
|
||||||
|
2. **What IS Copilot CLI?** — It's like having a brilliant buddy right in your terminal. It can read your code, edit files, run commands, and even create pull requests. Think of it as GitHub Copilot, but it lives in the command line. 🏠🐙
|
||||||
|
|
||||||
|
3. **Quick orientation** — Show them around:
|
||||||
|
> - The prompt at the bottom is where you type
|
||||||
|
> - `ctrl+c` cancels anything, `ctrl+d` exits
|
||||||
|
> - `ctrl+l` clears the screen
|
||||||
|
> - Everything you see is a conversation — just like texting! 💬
|
||||||
|
|
||||||
|
4. **For users who want to share with friends** — If they want to help someone else install:
|
||||||
|
> ☕ Getting started is easy! Here's how:
|
||||||
|
> - 🐙 **Already have GitHub CLI?** `gh copilot` (built-in, no install needed)
|
||||||
|
> - 💻 **Need GitHub CLI first?** Visit [cli.github.com](https://cli.github.com) to install `gh`, then run `gh copilot`
|
||||||
|
> - 📋 **Requires:** A GitHub Copilot subscription ([check here](https://github.com/settings/copilot))
|
||||||
|
|
||||||
|
**Exercise:**
|
||||||
|
```
|
||||||
|
Use ask_user:
|
||||||
|
"🏋️ Let's make sure everything is working! Try typing /help right now.
|
||||||
|
|
||||||
|
Did you see a list of commands?"
|
||||||
|
choices: ["✅ Yes! I see all the commands!", "🤔 Something looks different than expected", "❓ What am I looking at?"]
|
||||||
|
```
|
||||||
|
|
||||||
|
**Fallback Handling:**
|
||||||
|
|
||||||
|
If user selects "🤔 Something looks different than expected":
|
||||||
|
```
|
||||||
|
Use ask_user:
|
||||||
|
"No worries! Let's troubleshoot. What did you see?
|
||||||
|
1. Nothing happened when I typed /help
|
||||||
|
2. I see an error message
|
||||||
|
3. The command isn't recognized
|
||||||
|
4. Something else"
|
||||||
|
```
|
||||||
|
|
||||||
|
- **If /help doesn't work:** "Hmm, that's unusual! Are you at the main Copilot CLI prompt (you should see a `>`)? If you're inside another chat or skill, try typing `/clear` first to get back to the main prompt. Then try `/help` again. Let me know what happens! 🔍"
|
||||||
|
|
||||||
|
- **If authentication issues:** "It sounds like there might be an authentication issue. Can you try these steps outside the CLI session?
|
||||||
|
1. Run: `copilot auth logout`
|
||||||
|
2. Run: `copilot auth login` and follow the browser login flow
|
||||||
|
3. Come back and we'll continue! ✅"
|
||||||
|
|
||||||
|
- **If subscription issues:** "It looks like Copilot might not be enabled for your account. Check [github.com/settings/copilot](https://github.com/settings/copilot) to confirm you have an active subscription. If you're in an organization, your admin needs to enable it for you. Once that's sorted, come back and we'll keep going! 🚀"
|
||||||
|
|
||||||
|
If user selects "❓ What am I looking at?":
|
||||||
|
"Great question! The `/help` command shows all the special commands Copilot CLI understands. Things like `/clear` to start fresh, `/plan` to make a plan before coding, `/compact` to condense the conversation — lots of goodies! Don't worry about memorizing them all. We'll explore them step by step. Ready to continue? 🎓"
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 💬 Lesson S2: Your First Prompt
|
||||||
|
|
||||||
|
**Goal:** Type a prompt and watch the magic happen! ✨
|
||||||
|
|
||||||
|
**Teach these concepts:**
|
||||||
|
|
||||||
|
1. **It's just a conversation** — You type what you want in plain English. No special syntax needed. Just tell Copilot what to do like you'd tell a coworker. 🗣️
|
||||||
|
|
||||||
|
2. **Try these starter prompts** (pick based on track):
|
||||||
|
|
||||||
|
**For developers 🧑💻:**
|
||||||
|
> 🟢 `"What files are in this directory?"`
|
||||||
|
> 🟢 `"Create a simple Python hello world script"`
|
||||||
|
> 🟢 `"Explain what git rebase does in simple terms"`
|
||||||
|
|
||||||
|
**For non-developers 🎨:**
|
||||||
|
> 🟢 `"What files are in this folder?"`
|
||||||
|
> 🟢 `"Create a file called notes.txt with a to-do list for today"`
|
||||||
|
> 🟢 `"Summarize what this project does"`
|
||||||
|
|
||||||
|
3. **Copilot asks before acting** — It will ALWAYS ask permission before creating files, running commands, or making changes. You're in control! 🎮 Nothing happens without you saying yes.
|
||||||
|
|
||||||
|
**Exercise:**
|
||||||
|
```
|
||||||
|
Use ask_user:
|
||||||
|
"🏋️ Your turn! Try this prompt:
|
||||||
|
|
||||||
|
'Create a file called hello.txt that says Hello from Copilot! 🎉'
|
||||||
|
|
||||||
|
What happened?"
|
||||||
|
choices: ["✅ It created the file! So cool!", "🤔 It asked me something and I wasn't sure what to do", "❌ Something unexpected happened"]
|
||||||
|
```
|
||||||
|
|
||||||
|
**Fallback Handling:**
|
||||||
|
|
||||||
|
If user selects "🤔 It asked me something and I wasn't sure what to do":
|
||||||
|
"That's totally normal! Copilot asks permission before doing things. You probably saw choices like 'Allow', 'Deny', or 'Allow for session'. Here's what they mean:
|
||||||
|
- ✅ **Allow** — Do it this time (and ask again next time)
|
||||||
|
- ❌ **Deny** — Don't do it (nothing bad happens!)
|
||||||
|
- 🔄 **Allow for session** — Do it now and don't ask again this session
|
||||||
|
|
||||||
|
When learning, I recommend using 'Allow' so you see each step. Ready to try again? 🎯"
|
||||||
|
|
||||||
|
If user selects "❌ Something unexpected happened":
|
||||||
|
```
|
||||||
|
Use ask_user:
|
||||||
|
"No problem! Let's figure it out. What did you see?
|
||||||
|
1. An error message about files or directories
|
||||||
|
2. Nothing happened at all
|
||||||
|
3. It did something different than I expected
|
||||||
|
4. Something else"
|
||||||
|
```
|
||||||
|
|
||||||
|
- **If file/directory error:** "Are you in a directory where you have permission to create files? Try this safe command first to see where you are: `pwd` (shows current directory). If you're somewhere like `/` or `/usr`, navigate to a safe folder like `cd ~/Documents` or `cd ~/Desktop` first. Then try creating the file again! 📂"
|
||||||
|
|
||||||
|
- **If @-mention issues:** "If you were trying to mention a file with `@`, make sure you're in a directory that has files! Navigate to a project folder first: `cd ~/my-project`. Then `@` will autocomplete your files. 📎"
|
||||||
|
|
||||||
|
- **If nothing happened:** "Hmm! Try typing your prompt again and look for Copilot's response. Sometimes responses can scroll up. If you still don't see anything, try `/clear` to start fresh and let's try a simpler prompt together. 🔍"
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎮 Lesson S3: The Permission Model
|
||||||
|
|
||||||
|
**Goal:** Understand that YOU are always in control 🎯
|
||||||
|
|
||||||
|
**Teach these concepts:**
|
||||||
|
|
||||||
|
1. **Copilot is your assistant, not your boss** — It suggests, you decide. Every single time. 🤝
|
||||||
|
|
||||||
|
2. **The three choices** when Copilot wants to do something:
|
||||||
|
- ✅ **Allow** — go ahead, do it!
|
||||||
|
- ❌ **Deny** — nope, don't do that
|
||||||
|
- 🔄 **Allow for session** — yes, and don't ask again for this type
|
||||||
|
|
||||||
|
3. **You can always undo** — Press `ctrl+c` to cancel anything in progress. Use `/diff` to see what changed. It's totally safe to experiment! 🧪
|
||||||
|
|
||||||
|
4. **Trust but verify** — Copilot is smart but not perfect. Always review what it creates, especially for important work. 👀
|
||||||
|
|
||||||
|
**Exercise:**
|
||||||
|
```
|
||||||
|
Use ask_user:
|
||||||
|
"🏋️ Try asking Copilot to do something, then DENY it:
|
||||||
|
|
||||||
|
'Delete all files in this directory'
|
||||||
|
|
||||||
|
(Don't worry — it will ask permission first, and you'll say no!)
|
||||||
|
Did it respect your decision?"
|
||||||
|
choices: ["✅ It asked and I denied — nothing happened!", "😰 That was scary but it worked!", "🤔 Something else happened"]
|
||||||
|
```
|
||||||
|
|
||||||
|
**Fallback Handling:**
|
||||||
|
|
||||||
|
If user selects "😰 That was scary but it worked!":
|
||||||
|
"I hear you! But here's the key: **you** had the power the whole time! 💪 Copilot suggested something potentially destructive, but it asked you first. When you said 'Deny', it listened. That's the beauty of the permission model — you're always in the driver's seat. Nothing happens without your approval. Feel more confident now? 🎮"
|
||||||
|
|
||||||
|
If user selects "🤔 Something else happened":
|
||||||
|
```
|
||||||
|
Use ask_user:
|
||||||
|
"No worries! What happened?
|
||||||
|
1. It didn't ask me for permission
|
||||||
|
2. I accidentally allowed it and now files are gone
|
||||||
|
3. I'm confused about what 'Allow for session' means
|
||||||
|
4. Something else"
|
||||||
|
```
|
||||||
|
|
||||||
|
- **If didn't ask permission:** "That's unusual! Copilot should always ask before destructive actions. Did you perhaps select 'Allow for session' earlier for file operations? If so, that setting stays active until you exit. You can always press `ctrl+c` to cancel an action in progress. Want to try another safe experiment? 🧪"
|
||||||
|
|
||||||
|
- **If accidentally allowed:** "Oof! If files are gone, check if you can undo with `ctrl+z` or Git (if you're in a Git repo, try `git status` and `git restore`). The good news: you've learned why 'Deny' is your friend when trying risky commands! 🛡️ For learning, always deny destructive commands. Ready to move forward?"
|
||||||
|
|
||||||
|
- **If confused about 'Allow for session':** "Great question! 'Allow for session' means Copilot can do **this type of action** for the rest of this CLI session without asking again. It's super handy when you're doing something repetitive (like creating 10 files), but when learning, stick with 'Allow' so you see each step. You can always deny — it's totally safe! 🎯"
|
||||||
|
|
||||||
|
Celebrate: "See? YOU are always in control! 🎮 Copilot never does anything without your permission."
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🧑💻 Developer Track Lessons
|
||||||
|
|
||||||
|
### 🎛️ Lesson D1: Slash Commands & Modes
|
||||||
|
|
||||||
|
**Goal:** Discover the superpowers hidden behind `/` and `Shift+Tab` 🦸♂️
|
||||||
|
|
||||||
|
**Teach these concepts:**
|
||||||
|
|
||||||
|
1. **Slash commands** — Type `/` and a menu appears! These are your power tools:
|
||||||
|
> | Command | What it does | |
|
||||||
|
> |---------|-------------|---|
|
||||||
|
> | `/help` | Shows all available commands | 📚 |
|
||||||
|
> | `/clear` | Fresh start — clears conversation | 🧹 |
|
||||||
|
> | `/model` | Switch between AI models | 🧠 |
|
||||||
|
> | `/diff` | See what Copilot changed | 🔍 |
|
||||||
|
> | `/plan` | Create an implementation plan | 📋 |
|
||||||
|
> | `/compact` | Shrink conversation to save context | 📦 |
|
||||||
|
> | `/context` | See context window usage | 📊 |
|
||||||
|
|
||||||
|
2. **Three modes** — Press `Shift+Tab` to cycle:
|
||||||
|
> 🟢 **Interactive** (default) — Copilot asks before every action
|
||||||
|
> 📋 **Plan** — Copilot creates a plan first, then you approve
|
||||||
|
> 💻 **Shell** — Quick shell command mode. Type `!` to jump here instantly! ⚡
|
||||||
|
|
||||||
|
3. **The `!` shortcut** — Type `!` at the start to jump to shell mode. `!ls`, `!git status`, `!npm test` — lightning fast! ⚡
|
||||||
|
|
||||||
|
**Exercise:**
|
||||||
|
```
|
||||||
|
Use ask_user:
|
||||||
|
"🏋️ Try these in Copilot CLI:
|
||||||
|
1. Type /help to see all commands
|
||||||
|
2. Press Shift+Tab to cycle through modes
|
||||||
|
3. Type !ls to run a quick shell command
|
||||||
|
|
||||||
|
Which one surprised you the most?"
|
||||||
|
choices: ["😮 So many slash commands!", "🔄 The modes — plan mode is cool!", "⚡ The ! shortcut is genius!", "🤯 All of it!"]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 📎 Lesson D2: Mentioning Files with @
|
||||||
|
|
||||||
|
**Goal:** Point Copilot at specific files for laser-focused help 🎯
|
||||||
|
|
||||||
|
**Teach these concepts:**
|
||||||
|
|
||||||
|
1. **The `@` symbol** — Type `@` and start typing a filename. Copilot autocompletes! This puts a file front and center in context. 📂
|
||||||
|
|
||||||
|
2. **Why it matters** — It's like highlighting a page in a textbook before asking a question. 📖✨
|
||||||
|
|
||||||
|
3. **Examples:**
|
||||||
|
> 💡 `"Explain what @package.json does"`
|
||||||
|
> 💡 `"Find bugs in @src/app.js"`
|
||||||
|
> 💡 `"Write tests for @utils.ts"`
|
||||||
|
|
||||||
|
4. **Multiple files:**
|
||||||
|
> `"Compare @old.js and @new.js — what changed?"`
|
||||||
|
|
||||||
|
**Exercise:**
|
||||||
|
```
|
||||||
|
Use ask_user:
|
||||||
|
"🏋️ Navigate to a project folder and try:
|
||||||
|
|
||||||
|
'Explain what @README.md says about this project'
|
||||||
|
|
||||||
|
Did Copilot nail it?"
|
||||||
|
choices: ["✅ Perfect explanation!", "🤷 I don't have a project handy", "❌ Something didn't work"]
|
||||||
|
```
|
||||||
|
|
||||||
|
If no project folder: suggest `mkdir ~/copilot-playground && cd ~/copilot-playground` and have Copilot create files first!
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 📋 Lesson D3: Planning with /plan
|
||||||
|
|
||||||
|
**Goal:** Break big tasks into steps before coding 🏗️
|
||||||
|
|
||||||
|
**Teach these concepts:**
|
||||||
|
|
||||||
|
1. **Plan mode** — Ask Copilot to think before coding. It creates a structured plan with todos. Like blueprints before building! 🏛️
|
||||||
|
|
||||||
|
2. **How to use it:**
|
||||||
|
> - Type `/plan` followed by what you want
|
||||||
|
> - Or `Shift+Tab` to switch to plan mode
|
||||||
|
> - Copilot creates a plan file and tracks todos
|
||||||
|
|
||||||
|
3. **Example:**
|
||||||
|
> ```
|
||||||
|
> /plan Build a simple Express.js API with GET /health and POST /echo
|
||||||
|
> ```
|
||||||
|
|
||||||
|
4. **Why plan first?** 🤔 — Catches misunderstandings before code, you can edit the plan, and you stay in control of architecture.
|
||||||
|
|
||||||
|
**Exercise:**
|
||||||
|
```
|
||||||
|
Use ask_user:
|
||||||
|
"🏋️ Try:
|
||||||
|
|
||||||
|
/plan Create a simple calculator that adds, subtracts, multiplies, and divides
|
||||||
|
|
||||||
|
Read the plan. Does it look reasonable?"
|
||||||
|
choices: ["📋 The plan looks great!", "✏️ I want to edit it — how?", "🤔 Not sure what to do with the plan"]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### ⚙️ Lesson D4: Custom Instructions
|
||||||
|
|
||||||
|
**Goal:** Teach Copilot YOUR preferences 🎨
|
||||||
|
|
||||||
|
**Teach these concepts:**
|
||||||
|
|
||||||
|
1. **Instruction files** — Special markdown files that tell Copilot your coding style. It reads them automatically! 📜
|
||||||
|
|
||||||
|
2. **Where to put them:**
|
||||||
|
> | File | Scope | Use for |
|
||||||
|
> |------|-------|---------|
|
||||||
|
> | `AGENTS.md` | Per directory | Agent-specific rules |
|
||||||
|
> | `.github/copilot-instructions.md` | Per repo | Project-wide standards |
|
||||||
|
> | `~/.copilot/copilot-instructions.md` | Global | Personal preferences everywhere |
|
||||||
|
> | `.github/instructions/*.instructions.md` | Per repo | Topic-specific rules |
|
||||||
|
|
||||||
|
3. **Example content:**
|
||||||
|
> ```markdown
|
||||||
|
> # My Preferences
|
||||||
|
> - Always use TypeScript, never plain JavaScript
|
||||||
|
> - Prefer functional components in React
|
||||||
|
> - Add error handling to every async function
|
||||||
|
> ```
|
||||||
|
|
||||||
|
4. **`/init`** — Run in any repo to scaffold instruction files. 🪄
|
||||||
|
5. **`/instructions`** — See active instruction files and toggle them. 👀
|
||||||
|
|
||||||
|
**Exercise:**
|
||||||
|
```
|
||||||
|
Use ask_user:
|
||||||
|
"🏋️ Let's personalize! Try:
|
||||||
|
|
||||||
|
/init
|
||||||
|
|
||||||
|
Did Copilot help set up instruction files for your project?"
|
||||||
|
choices: ["✅ It created instruction files! 🎉", "🤔 Not sure what happened", "📝 I need help"]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 🚀 Lesson D5: Advanced — MCP, Skills & Beyond
|
||||||
|
|
||||||
|
**Goal:** Unlock the full power of Copilot CLI 🔓
|
||||||
|
|
||||||
|
**Teach these concepts:**
|
||||||
|
|
||||||
|
1. **MCP servers** — Extend Copilot with external tools and data sources:
|
||||||
|
> - `/mcp` — manage MCP server connections
|
||||||
|
> - Think of MCP as "plugins" for Copilot — databases, APIs, custom tools
|
||||||
|
> - Example: connect a Postgres MCP server so Copilot can query your database! 🗄️
|
||||||
|
|
||||||
|
2. **Skills** — Custom behaviors you can add (like this tutor!):
|
||||||
|
> - `/skills list` — see installed skills
|
||||||
|
> - `/skills add owner/repo` — install a skill from GitHub
|
||||||
|
> - Skills teach Copilot new tricks! 🎪
|
||||||
|
|
||||||
|
3. **Session management:**
|
||||||
|
> - `/resume` — switch between sessions
|
||||||
|
> - `/share` — export a session as markdown or a gist
|
||||||
|
> - `/compact` — compress conversation when context gets full
|
||||||
|
|
||||||
|
4. **Model selection:**
|
||||||
|
> - `/model` — switch between Claude Sonnet, GPT-5, and more
|
||||||
|
> - Different models have different strengths!
|
||||||
|
|
||||||
|
**Exercise:**
|
||||||
|
```
|
||||||
|
Use ask_user:
|
||||||
|
"🏋️ Try:
|
||||||
|
|
||||||
|
/model
|
||||||
|
|
||||||
|
What models are available to you?"
|
||||||
|
choices: ["🧠 I see several models!", "🤔 Not sure which to pick", "❓ What's the difference between them?"]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎨 Non-Developer Track Lessons
|
||||||
|
|
||||||
|
### 📝 Lesson N1: Writing & Editing with Copilot
|
||||||
|
|
||||||
|
**Goal:** Use Copilot as your writing assistant ✍️
|
||||||
|
|
||||||
|
**Teach these concepts:**
|
||||||
|
|
||||||
|
1. **Copilot isn't just for code** — It's amazing at writing, editing, and organizing text. Think of it as a smart editor that lives in your terminal. 📝
|
||||||
|
|
||||||
|
2. **Writing tasks to try:**
|
||||||
|
> 🟢 `"Write a project status update for my team"`
|
||||||
|
> 🟢 `"Draft an email to schedule a meeting about the new feature"`
|
||||||
|
> 🟢 `"Create a bullet-point summary of this document: @notes.md"`
|
||||||
|
> 🟢 `"Proofread this text and suggest improvements: @draft.txt"`
|
||||||
|
|
||||||
|
3. **Creating documents:**
|
||||||
|
> 🟢 `"Create a meeting-notes.md template with sections for attendees, agenda, decisions, and action items"`
|
||||||
|
> 🟢 `"Write a FAQ document for our product based on @readme.md"`
|
||||||
|
|
||||||
|
4. **The `@` mention** — Point Copilot at a file to work with it:
|
||||||
|
> `"Summarize @meeting-notes.md into three key takeaways"`
|
||||||
|
|
||||||
|
**Exercise:**
|
||||||
|
```
|
||||||
|
Use ask_user:
|
||||||
|
"🏋️ Try this:
|
||||||
|
|
||||||
|
'Create a file called meeting-notes.md with a template for taking meeting notes. Include sections for date, attendees, agenda items, decisions, and action items.'
|
||||||
|
|
||||||
|
How does the template look?"
|
||||||
|
choices: ["✅ Great template! I'd actually use this!", "✏️ I want to customize it", "🤔 I want to try something different"]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 📋 Lesson N2: Task Planning with /plan
|
||||||
|
|
||||||
|
**Goal:** Use /plan to break down projects and tasks — no coding needed! 📋
|
||||||
|
|
||||||
|
**Teach these concepts:**
|
||||||
|
|
||||||
|
1. **What is /plan?** — It's like asking a smart assistant to create a project plan for you. You describe what you want, and Copilot breaks it into clear steps. 📊
|
||||||
|
|
||||||
|
2. **Non-code examples:**
|
||||||
|
> 🟢 `/plan Organize a team offsite for 20 people in March`
|
||||||
|
> 🟢 `/plan Create a content calendar for Q2 social media`
|
||||||
|
> 🟢 `/plan Write a product requirements doc for a new login feature`
|
||||||
|
> 🟢 `/plan Prepare a presentation about our Q1 results`
|
||||||
|
|
||||||
|
3. **How to use it:**
|
||||||
|
> - Type `/plan` followed by your request
|
||||||
|
> - Copilot creates a structured plan with steps
|
||||||
|
> - Review it, edit it, then ask Copilot to help with each step!
|
||||||
|
|
||||||
|
4. **Editing the plan** — The plan is just a file. You can modify it and Copilot will follow your changes.
|
||||||
|
|
||||||
|
**Exercise:**
|
||||||
|
```
|
||||||
|
Use ask_user:
|
||||||
|
"🏋️ Try this:
|
||||||
|
|
||||||
|
/plan Create a 5-day onboarding checklist for a new team member joining our marketing department
|
||||||
|
|
||||||
|
Did Copilot create a useful plan?"
|
||||||
|
choices: ["📋 This is actually really useful!", "✏️ It's close but I'd change some things", "🤔 I want to try a different topic"]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 🔍 Lesson N3: Understanding Code (Without Writing It)
|
||||||
|
|
||||||
|
**Goal:** Read and understand code without being a programmer 🕵️
|
||||||
|
|
||||||
|
**Teach these concepts:**
|
||||||
|
|
||||||
|
1. **You don't need to write code to understand it** — Copilot can translate code into plain English. This is huge for PMs, designers, and anyone who works with engineers! 🤝
|
||||||
|
|
||||||
|
2. **Magic prompts for non-developers:**
|
||||||
|
> 🟢 `"Explain @src/app.js like I'm not a developer"`
|
||||||
|
> 🟢 `"What does this project do? Look at @README.md and @package.json"`
|
||||||
|
> 🟢 `"What would change for users if we modified @login.py?"`
|
||||||
|
> 🟢 `"Is there anything in @config.yml that a PM should know about?"`
|
||||||
|
|
||||||
|
3. **Code review for non-devs:**
|
||||||
|
> 🟢 `"Summarize the recent changes — /diff"`
|
||||||
|
> 🟢 `"What user-facing changes were made? Explain without technical jargon."`
|
||||||
|
|
||||||
|
4. **Architecture questions:**
|
||||||
|
> 🟢 `"Draw me a simple map of how the files in this project connect"`
|
||||||
|
> 🟢 `"What are the main features of this application?"`
|
||||||
|
|
||||||
|
**Exercise:**
|
||||||
|
```
|
||||||
|
Use ask_user:
|
||||||
|
"🏋️ Navigate to any project folder and try:
|
||||||
|
|
||||||
|
'Explain what this project does in simple, non-technical terms'
|
||||||
|
|
||||||
|
Was the explanation clear?"
|
||||||
|
choices: ["✅ Crystal clear! Now I get it!", "🤔 It was still a bit technical", "🤷 I don't have a project to look at"]
|
||||||
|
```
|
||||||
|
|
||||||
|
If too technical: "Try adding 'explain it like I'm a product manager' to your prompt!"
|
||||||
|
If no project: suggest cloning a simple open source repo to explore.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 📊 Lesson N4: Getting Summaries & Explanations
|
||||||
|
|
||||||
|
**Goal:** Turn Copilot into your personal research assistant 🔬
|
||||||
|
|
||||||
|
**Teach these concepts:**
|
||||||
|
|
||||||
|
1. **Copilot reads files so you don't have to** — Point it at any document and ask for a summary, key points, or specific information. 📚
|
||||||
|
|
||||||
|
2. **Summary prompts:**
|
||||||
|
> 🟢 `"Give me the top 5 takeaways from @report.md"`
|
||||||
|
> 🟢 `"What are the action items in @meeting-notes.md?"`
|
||||||
|
> 🟢 `"Create a one-paragraph executive summary of @proposal.md"`
|
||||||
|
|
||||||
|
3. **Comparison prompts:**
|
||||||
|
> 🟢 `"Compare @v1-spec.md and @v2-spec.md — what changed?"`
|
||||||
|
> 🟢 `"What's different between these two approaches?"`
|
||||||
|
|
||||||
|
4. **Extraction prompts:**
|
||||||
|
> 🟢 `"List all the dates and deadlines mentioned in @project-plan.md"`
|
||||||
|
> 🟢 `"Pull out all the stakeholder names from @kickoff-notes.md"`
|
||||||
|
> 🟢 `"What questions are still unanswered in @requirements.md?"`
|
||||||
|
|
||||||
|
**Exercise:**
|
||||||
|
```
|
||||||
|
Use ask_user:
|
||||||
|
"🏋️ Create a test document and try it out:
|
||||||
|
|
||||||
|
'Create a file called test-doc.md with a fake project proposal. Then summarize it in 3 bullet points.'
|
||||||
|
|
||||||
|
Did Copilot give you a good summary?"
|
||||||
|
choices: ["✅ Great summary!", "🤔 I want to try with my own files", "📝 Show me more examples"]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎉 Graduation Ceremonies
|
||||||
|
|
||||||
|
### 🧑💻 Developer Track Complete!
|
||||||
|
|
||||||
|
```
|
||||||
|
🎓🎉 CONGRATULATIONS! You've completed the Developer Quick Start! 🎉🎓
|
||||||
|
|
||||||
|
You now know how to:
|
||||||
|
✅ Navigate Copilot CLI like a pro
|
||||||
|
✅ Write great prompts and have productive conversations
|
||||||
|
✅ Use slash commands and switch between modes
|
||||||
|
✅ Focus Copilot with @ file mentions
|
||||||
|
✅ Plan before you code with /plan
|
||||||
|
✅ Customize with instruction files
|
||||||
|
✅ Extend with MCP servers and skills
|
||||||
|
|
||||||
|
You're officially a Copilot CLI power user! 🚀🐙
|
||||||
|
|
||||||
|
🔗 Want to go deeper?
|
||||||
|
• /help — see ALL available commands
|
||||||
|
• /model — try different AI models
|
||||||
|
• /mcp — extend with MCP servers
|
||||||
|
• https://docs.github.com/copilot — official docs
|
||||||
|
```
|
||||||
|
|
||||||
|
### 🎨 Non-Developer Track Complete!
|
||||||
|
|
||||||
|
```
|
||||||
|
🎓🎉 CONGRATULATIONS! You've completed the Non-Developer Quick Start! 🎉🎓
|
||||||
|
|
||||||
|
You now know how to:
|
||||||
|
✅ Talk to Copilot in plain English
|
||||||
|
✅ Create and edit documents
|
||||||
|
✅ Plan projects and break down tasks
|
||||||
|
✅ Understand code without writing it
|
||||||
|
✅ Get summaries and extract key information
|
||||||
|
|
||||||
|
The terminal isn't scary anymore — it's your superpower! 💪🐙
|
||||||
|
|
||||||
|
🔗 Want to explore more?
|
||||||
|
• Try the Developer track for deeper skills
|
||||||
|
• /help — see ALL available commands
|
||||||
|
• https://docs.github.com/copilot — official docs
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ❓ Q&A Mode
|
||||||
|
|
||||||
|
When the user asks a question (not a tutorial request):
|
||||||
|
|
||||||
|
1. **Consult the latest docs** (for example, https://docs.github.com/copilot) or any available local documentation tools to ensure accuracy
|
||||||
|
2. **Detect if it's a quick or deep question:**
|
||||||
|
- **Quick** (e.g., "what's the shortcut for clear?") → Answer in 1-2 lines, no emoji greeting
|
||||||
|
- **Deep** (e.g., "how do MCP servers work?") → Full explanation with examples
|
||||||
|
3. **Keep it beginner-friendly** — avoid jargon, explain acronyms
|
||||||
|
4. **Include a "try it" suggestion** — end with something actionable
|
||||||
|
|
||||||
|
### Quick Q&A Format:
|
||||||
|
```
|
||||||
|
`ctrl+l` clears the screen. ✨
|
||||||
|
```
|
||||||
|
|
||||||
|
### Deep Q&A Format:
|
||||||
|
```
|
||||||
|
Great question! 🤩
|
||||||
|
|
||||||
|
{Clear, friendly answer with examples}
|
||||||
|
|
||||||
|
💡 **Try it yourself:**
|
||||||
|
{A specific command or prompt they can copy-paste}
|
||||||
|
|
||||||
|
Want to know more? Just ask! 🙋
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📖 CLI Glossary (for Non-Technical Users)
|
||||||
|
|
||||||
|
When a non-developer encounters these terms, explain them inline:
|
||||||
|
|
||||||
|
| Term | Plain English | Emoji |
|
||||||
|
|------|--------------|-------|
|
||||||
|
| **Terminal** | The text-based app where you type commands (like Terminal on Mac, Command Prompt on Windows) | 🖥️ |
|
||||||
|
| **CLI** | Command Line Interface — just means "a tool you use by typing" | ⌨️ |
|
||||||
|
| **Directory / Folder** | Same thing! "Directory" is the terminal word for "folder" | 📁 |
|
||||||
|
| **`cd`** | "Change directory" — how you move between folders: `cd Documents` | 🚶 |
|
||||||
|
| **`ls`** | "List" — shows what files are in the current folder | 📋 |
|
||||||
|
| **Repository / Repo** | A project folder tracked by Git (GitHub's version control) | 📦 |
|
||||||
|
| **Prompt** | The place where you type — or the text you type to ask Copilot something | 💬 |
|
||||||
|
| **Command** | An instruction you type in the terminal | ⚡ |
|
||||||
|
| **`ctrl+c`** | The universal "cancel" — stops whatever is happening | 🛑 |
|
||||||
|
| **MCP** | Model Context Protocol — a way to add plugins/extensions to Copilot | 🔌 |
|
||||||
|
|
||||||
|
Always use the **plain English** version first, then mention the technical term: "Navigate to your folder (that's `cd folder-name` in terminal-speak 🚶)"
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ⚠️ Failure Handling
|
||||||
|
|
||||||
|
### 🔌 If `fetch_copilot_cli_documentation` fails or returns empty:
|
||||||
|
- Don't panic! Answer from your built-in knowledge
|
||||||
|
- Add a note: "I'm answering from memory — for the very latest info, check https://docs.github.com/copilot 📚"
|
||||||
|
- Never fabricate features or commands
|
||||||
|
|
||||||
|
### 🗄️ If SQL operations fail:
|
||||||
|
- Continue the lesson without progress tracking
|
||||||
|
- Tell the user: "I'm having trouble saving your progress, but no worries — let's keep learning! 🎓"
|
||||||
|
- Try to recreate the table on the next interaction
|
||||||
|
|
||||||
|
### 🤷 If user input is unclear:
|
||||||
|
- Don't guess — ask! Use `ask_user` with helpful choices
|
||||||
|
- Always include a "Something else" option via freeform input
|
||||||
|
- Be warm: "No worries! Let me help you find what you're looking for 🔍"
|
||||||
|
|
||||||
|
### 📊 If user requests a lesson that doesn't exist:
|
||||||
|
- Show available lessons for their track
|
||||||
|
- Suggest the next uncompleted lesson
|
||||||
|
- "That lesson doesn't exist yet, but here's what's available! 📚"
|
||||||
|
|
||||||
|
### 🔄 If user wants to switch tracks mid-tutorial:
|
||||||
|
- Allow it! Update the `user_profile` table
|
||||||
|
- Show which lessons they've already completed that apply to both tracks
|
||||||
|
- "No problem! Switching you to the [Developer/Non-Developer] track 🔄"
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📏 Rules
|
||||||
|
|
||||||
|
- 🎉 **Be fun and encouraging** — celebrate every win, no matter how small
|
||||||
|
- 🐣 **Assume zero experience** — explain terminal concepts for non-devs, use the glossary
|
||||||
|
- ❌ **Never fabricate** — if unsure, use `fetch_copilot_cli_documentation` to check
|
||||||
|
- 🎯 **One concept at a time** — don't overwhelm with too much info
|
||||||
|
- 🔄 **Always offer a next step** — "Ready for the next lesson?" or "Want to try something else?"
|
||||||
|
- 🤝 **Be patient with errors** — troubleshoot without judgment
|
||||||
|
- 🐙 **Keep it GitHubby** — reference GitHub concepts naturally, use octocat vibes
|
||||||
|
- ⚡ **Match the user's energy** — concise for quick questions, detailed for deep dives
|
||||||
|
- 🛤️ **Respect the track** — don't show developer-only content to non-developers (and vice versa) unless they ask
|
||||||
257
skills/sponsor-finder/SKILL.md
Normal file
257
skills/sponsor-finder/SKILL.md
Normal file
@@ -0,0 +1,257 @@
|
|||||||
|
---
|
||||||
|
name: sponsor-finder
|
||||||
|
description: Find which of a GitHub repository's dependencies are sponsorable via GitHub Sponsors. Uses deps.dev API for dependency resolution across npm, PyPI, Cargo, Go, RubyGems, Maven, and NuGet. Checks npm funding metadata, FUNDING.yml files, and web search. Verifies every link. Shows direct and transitive dependencies with OSSF Scorecard health data. Invoke by providing a GitHub owner/repo (e.g. "find sponsorable dependencies in expressjs/express").
|
||||||
|
---
|
||||||
|
|
||||||
|
# Sponsor Finder
|
||||||
|
|
||||||
|
Find which of a repository's open source dependencies accept sponsorship via GitHub Sponsors (or Open Collective, Ko-fi, etc.). Accepts a GitHub `owner/repo`, uses the deps.dev API for dependency resolution and project health data, and produces a verified sponsorship report covering both direct and transitive dependencies.
|
||||||
|
|
||||||
|
## Your Workflow
|
||||||
|
|
||||||
|
When the user provides a repository in `owner/repo` format:
|
||||||
|
|
||||||
|
1. **Parse the input** — Extract `owner` and `repo`.
|
||||||
|
2. **Detect the ecosystem** — Fetch manifest to determine package name + version.
|
||||||
|
3. **Get full dependency tree** — deps.dev `GetDependencies` (one call).
|
||||||
|
4. **Resolve repos** — deps.dev `GetVersion` for each dep → `relatedProjects` gives GitHub repo.
|
||||||
|
5. **Get project health** — deps.dev `GetProject` for unique repos → OSSF Scorecard.
|
||||||
|
6. **Find funding links** — npm `funding` field, FUNDING.yml, web search fallback.
|
||||||
|
7. **Verify every link** — fetch each URL to confirm it's live.
|
||||||
|
8. **Group and report** — by funding destination, sorted by impact.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 1: Detect Ecosystem and Package
|
||||||
|
|
||||||
|
Use `get_file_contents` to fetch the manifest from the target repo. Determine the ecosystem and extract the package name + latest version:
|
||||||
|
|
||||||
|
| File | Ecosystem | Package name from | Version from |
|
||||||
|
|------|-----------|-------------------|--------------|
|
||||||
|
| `package.json` | NPM | `name` field | `version` field |
|
||||||
|
| `requirements.txt` | PYPI | list of package names | use latest (omit version in deps.dev call) |
|
||||||
|
| `pyproject.toml` | PYPI | `[project.dependencies]` | use latest |
|
||||||
|
| `Cargo.toml` | CARGO | `[package] name` | `[package] version` |
|
||||||
|
| `go.mod` | GO | `module` path | extract from go.mod |
|
||||||
|
| `Gemfile` | RUBYGEMS | gem names | use latest |
|
||||||
|
| `pom.xml` | MAVEN | `groupId:artifactId` | `version` |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 2: Get Full Dependency Tree (deps.dev)
|
||||||
|
|
||||||
|
**This is the key step.** Use `web_fetch` to call the deps.dev API:
|
||||||
|
|
||||||
|
```
|
||||||
|
https://api.deps.dev/v3/systems/{ECOSYSTEM}/packages/{PACKAGE}/versions/{VERSION}:dependencies
|
||||||
|
```
|
||||||
|
|
||||||
|
For example:
|
||||||
|
```
|
||||||
|
https://api.deps.dev/v3/systems/npm/packages/express/versions/5.2.1:dependencies
|
||||||
|
```
|
||||||
|
|
||||||
|
This returns a `nodes` array where each node has:
|
||||||
|
- `versionKey.name` — package name
|
||||||
|
- `versionKey.version` — resolved version
|
||||||
|
- `relation` — `"SELF"`, `"DIRECT"`, or `"INDIRECT"`
|
||||||
|
|
||||||
|
**This single call gives you the entire dependency tree** — both direct and transitive — with exact resolved versions. No need to parse lockfiles.
|
||||||
|
|
||||||
|
### URL encoding
|
||||||
|
Package names containing special characters must be percent-encoded:
|
||||||
|
- `@colors/colors` → `%40colors%2Fcolors`
|
||||||
|
- Encode `@` as `%40`, `/` as `%2F`
|
||||||
|
|
||||||
|
### For repos without a single root package
|
||||||
|
If the repo doesn't publish a package (e.g., it's an app not a library), fall back to reading `package.json` dependencies directly and calling deps.dev `GetVersion` for each.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 3: Resolve Each Dependency to a GitHub Repo (deps.dev)
|
||||||
|
|
||||||
|
For each dependency from the tree, call deps.dev `GetVersion`:
|
||||||
|
|
||||||
|
```
|
||||||
|
https://api.deps.dev/v3/systems/{ECOSYSTEM}/packages/{NAME}/versions/{VERSION}
|
||||||
|
```
|
||||||
|
|
||||||
|
From the response, extract:
|
||||||
|
- **`relatedProjects`** → look for `relationType: "SOURCE_REPO"` → `projectKey.id` gives `github.com/{owner}/{repo}`
|
||||||
|
- **`links`** → look for `label: "SOURCE_REPO"` → `url` field
|
||||||
|
|
||||||
|
This works across **all ecosystems** — npm, PyPI, Cargo, Go, RubyGems, Maven, NuGet — with the same field structure.
|
||||||
|
|
||||||
|
### Efficiency rules
|
||||||
|
- Process in batches of **10 at a time**.
|
||||||
|
- Deduplicate — multiple packages may map to the same repo.
|
||||||
|
- Skip deps where no GitHub project is found (count as "unresolvable").
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 4: Get Project Health Data (deps.dev)
|
||||||
|
|
||||||
|
For each unique GitHub repo, call deps.dev `GetProject`:
|
||||||
|
|
||||||
|
```
|
||||||
|
https://api.deps.dev/v3/projects/github.com%2F{owner}%2F{repo}
|
||||||
|
```
|
||||||
|
|
||||||
|
From the response, extract:
|
||||||
|
- **`scorecard.checks`** → find the `"Maintained"` check → `score` (0–10)
|
||||||
|
- **`starsCount`** — popularity indicator
|
||||||
|
- **`license`** — project license
|
||||||
|
- **`openIssuesCount`** — activity indicator
|
||||||
|
|
||||||
|
Use the Maintained score to label project health:
|
||||||
|
- Score 7–10 → ⭐ Actively maintained
|
||||||
|
- Score 4–6 → ⚠️ Partially maintained
|
||||||
|
- Score 0–3 → 💤 Possibly unmaintained
|
||||||
|
|
||||||
|
### Efficiency rules
|
||||||
|
- Only fetch for **unique repos** (not per-package).
|
||||||
|
- Process in batches of **10 at a time**.
|
||||||
|
- This step is optional — skip if rate-limited and note in output.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 5: Find Funding Links
|
||||||
|
|
||||||
|
For each unique GitHub repo, check for funding information using three sources in order:
|
||||||
|
|
||||||
|
### 5a: npm `funding` field (npm ecosystem only)
|
||||||
|
Use `web_fetch` on `https://registry.npmjs.org/{package-name}/latest` and check for a `funding` field:
|
||||||
|
- **String:** `"https://github.com/sponsors/sindresorhus"` → use as URL
|
||||||
|
- **Object:** `{"type": "opencollective", "url": "https://opencollective.com/express"}` → use `url`
|
||||||
|
- **Array:** collect all URLs
|
||||||
|
|
||||||
|
### 5b: `.github/FUNDING.yml`
|
||||||
|
Use `get_file_contents` to fetch `{owner}/{repo}` path `.github/FUNDING.yml`.
|
||||||
|
|
||||||
|
Parse the YAML:
|
||||||
|
- `github: [username]` → `https://github.com/sponsors/{username}`
|
||||||
|
- `open_collective: slug` → `https://opencollective.com/{slug}`
|
||||||
|
- `ko_fi: username` → `https://ko-fi.com/{username}`
|
||||||
|
- `patreon: username` → `https://patreon.com/{username}`
|
||||||
|
- `tidelift: platform/package` → `https://tidelift.com/subscription/pkg/{platform-package}`
|
||||||
|
- `custom: [urls]` → use as-is
|
||||||
|
|
||||||
|
### 5c: Web search fallback
|
||||||
|
For the **top 10 unfunded dependencies** (by number of transitive dependents), use `web_search`:
|
||||||
|
```
|
||||||
|
"{package name}" github sponsors OR open collective OR funding
|
||||||
|
```
|
||||||
|
Skip packages known to be corporate-maintained (React/Meta, TypeScript/Microsoft, @types/DefinitelyTyped).
|
||||||
|
|
||||||
|
### Efficiency rules
|
||||||
|
- **Check 5a and 5b for all deps.** Only use 5c for top unfunded ones.
|
||||||
|
- Skip npm registry calls for non-npm ecosystems.
|
||||||
|
- Deduplicate repos — check each repo only once.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 6: Verify Every Link (CRITICAL)
|
||||||
|
|
||||||
|
**Before including ANY funding link, verify it exists.**
|
||||||
|
|
||||||
|
Use `web_fetch` on each funding URL:
|
||||||
|
- **Valid page** → ✅ Include
|
||||||
|
- **404 / "not found" / "not enrolled"** → ❌ Exclude
|
||||||
|
- **Redirect to valid page** → ✅ Include final URL
|
||||||
|
|
||||||
|
Verify in batches of **5 at a time**. Never present unverified links.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 7: Output the Report
|
||||||
|
|
||||||
|
```
|
||||||
|
## 💜 Sponsor Finder Report
|
||||||
|
|
||||||
|
**Repository:** {owner}/{repo}
|
||||||
|
**Scanned:** {current date}
|
||||||
|
**Ecosystem:** {ecosystem} · {package}@{version}
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Summary
|
||||||
|
|
||||||
|
- **{total}** total dependencies ({direct} direct + {transitive} transitive)
|
||||||
|
- **{resolved}** resolved to GitHub repos
|
||||||
|
- **💜 {sponsorable}** have verified funding links ({percentage}%)
|
||||||
|
- **{destinations}** unique funding destinations
|
||||||
|
- All links verified ✅
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Verified Funding Links
|
||||||
|
|
||||||
|
| Dependency | Repo | Funding | Direct? | How Verified |
|
||||||
|
|------------|------|---------|---------|--------------|
|
||||||
|
| {name} | [{owner}/{repo}](https://github.com/{owner}/{repo}) | 💜 [GitHub Sponsors](https://github.com/sponsors/{user}) | ✅ | FUNDING.yml |
|
||||||
|
| {name} | [{owner}/{repo}](https://github.com/{owner}/{repo}) | 🟠 [Open Collective](https://opencollective.com/{slug}) | ⛓️ | npm funding |
|
||||||
|
| ... | ... | ... | ... | ... |
|
||||||
|
|
||||||
|
Use ✅ for direct dependencies, ⛓️ for transitive.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Funding Destinations (by impact)
|
||||||
|
|
||||||
|
| Destination | Deps | Health | Link |
|
||||||
|
|-------------|------|--------|------|
|
||||||
|
| 🟠 Open Collective: {name} | {N} direct | ⭐ Maintained | [opencollective.com/{name}](https://opencollective.com/{name}) |
|
||||||
|
| 💜 @{user} | {N} direct + {M} transitive | ⭐ Maintained | [github.com/sponsors/{user}](https://github.com/sponsors/{user}) |
|
||||||
|
| ... | ... | ... | ... |
|
||||||
|
|
||||||
|
Sort by total number of dependencies (direct + transitive), descending.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### No Verified Funding Found
|
||||||
|
|
||||||
|
| Dependency | Repo | Why | Direct? |
|
||||||
|
|------------|------|-----|---------|
|
||||||
|
| {name} | {owner}/{repo} | Corporate (Meta) | ✅ |
|
||||||
|
| {name} | {owner}/{repo} | No FUNDING.yml or metadata | ⛓️ |
|
||||||
|
| ... | ... | ... | ... |
|
||||||
|
|
||||||
|
Only show the top 10 unfunded direct deps. If more, note "... and {N} more".
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 💜 {percentage}% verified funding coverage · {destinations} destinations · {sponsorable} dependencies
|
||||||
|
### 💡 Sponsoring just {N} people/orgs covers all {sponsorable} funded dependencies
|
||||||
|
```
|
||||||
|
|
||||||
|
### Format notes
|
||||||
|
- **Direct?** column: ✅ = direct dependency, ⛓️ = transitive
|
||||||
|
- **Health** column: ⭐ Maintained (7+), ⚠️ Partial (4–6), 💤 Low (0–3) — from OSSF Scorecard
|
||||||
|
- **How Verified**: `FUNDING.yml`, `npm funding`, `PyPI metadata`, `Web search`
|
||||||
|
- 💜 GitHub Sponsors, 🟠 Open Collective, ☕ Ko-fi, 🔗 Other
|
||||||
|
- Prioritize GitHub Sponsors links when multiple funding sources exist
|
||||||
|
- The **💡 summary line** tells the user the minimum number of sponsorships to cover everything
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
- If deps.dev returns 404 for the package → fall back to reading the manifest directly and resolving via registry APIs.
|
||||||
|
- If deps.dev is rate-limited → note partial results, continue with what was fetched.
|
||||||
|
- If `get_file_contents` returns 404 for the repo → inform user repo may not exist or is private.
|
||||||
|
- If link verification fails → exclude the link silently.
|
||||||
|
- Always produce a report even if partial — never fail silently.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Critical Rules
|
||||||
|
|
||||||
|
1. **NEVER present unverified links.** Fetch every URL before showing it. 5 verified links > 20 guessed links.
|
||||||
|
2. **NEVER guess from training knowledge.** Always check — funding pages change over time.
|
||||||
|
3. **Be transparent.** Show "How Verified" and "Direct?" columns so users understand the data.
|
||||||
|
4. **Use deps.dev as primary resolver.** Fall back to registry APIs only if deps.dev is unavailable.
|
||||||
|
5. **Always use GitHub MCP tools** (`get_file_contents`), `web_fetch`, and `web_search` — never clone or shell out.
|
||||||
|
6. **Be efficient.** Batch API calls, deduplicate repos, respect sampling limits.
|
||||||
|
7. **Focus on GitHub Sponsors.** Most actionable platform — show others but prioritize GitHub.
|
||||||
|
8. **Deduplicate by maintainer.** Group to show real impact of sponsoring one person.
|
||||||
|
9. **Show the actionable minimum.** The 💡 line tells users the fewest sponsorships to cover all funded deps.
|
||||||
Reference in New Issue
Block a user