Contributing

Whether you are contributing an agent, skill, instruction, hook, or documentation fix, this page covers the process and conventions.

Local Development Setup

Load DevSquad directly from your checkout to develop and test changes to agents, skills, and hooks. The Getting Started guide covers installation for use in other projects.

Clone the Repository

To contribute changes, fork microsoft/devsquad-copilot and clone your fork. To explore or test locally without submitting changes, you can clone the upstream repository directly.

Replace YOUR-USERNAME with your GitHub username:

git clone https://github.com/YOUR-USERNAME/devsquad-copilot.git
cd devsquad-copilot

The following steps assume that the repository root is your workspace and working directory.

VS Code

Install the GitHub Copilot Chat extension and sign in with your Copilot account. The repository’s .vscode/settings.json enables plugin support and nested subagent workflows:

{
  "chat.plugins.enabled": true,
  "chat.subagents.allowInvocationsFromSubagents": true
}

Open the repository root in VS Code.
Run Preferences: Open User Settings (JSON) from the Command Palette.

Add the local plugin location, preserving any existing entries:

{
  "chat.pluginLocations": {
    ".github/plugins/devsquad": true
  }
}

Saving the setting activates the local plugin. No window reload is required.

chat.pluginLocations only supports User Settings in a local window or Remote Settings in a remote window. Do not add it to .vscode/settings.json. For remote development, add the same entry to Remote Settings with the repository open in the remote workspace.

The relative path assumes that the repository root is open as the workspace. Use an absolute path if you need to target a specific checkout.

GitHub Copilot CLI

From the repository root, start a session with the local plugin:

copilot --plugin-dir .github/plugins/devsquad

No marketplace registration or plugin installation is required. Start a new session with the same command after editing plugin files to load your changes.

Verify the Local Plugin

Confirm that the DevSquad agents and skills are available in your client. In Copilot CLI, use /agent and /skills; in VS Code, check the agent picker and Chat: Configure Skills.

Edit source files under .github/plugins/devsquad/. No .github/agents or .github/skills symlinks are required.

Avoid loading an installed DevSquad copy alongside the local plugin. If one is already enabled, disable it for development so that you test the checkout you are editing.

Reporting Issues

Use GitHub Issues with detailed context:

Steps to reproduce
Expected vs actual behavior
Environment (VS Code version, OS, Node.js version)

Project Structure

.vscode/
  settings.json      # Plugin support and nested subagent settings
.github/
  plugins/devsquad/
    agents/          # Visible agents and internal worker agents (.agent.md)
    skills/          # 18 skill definitions
    hooks/           # Lifecycle scripts + hooks.json
    .mcp.json        # MCP server configuration
  instructions/      # 7 path-scoped instruction files
  docs/              # Internal reference docs
docs/
  framework/         # Architecture documentation
  templates/         # Community file templates

Architecture Decisions

Changes to the framework architecture should go through the ADR (Architecture Decision Record) process. See Decisions for existing ADRs and the template. To propose a new ADR:

Copy the ADR template from docs/architecture/decisions/ADR-TEMPLATE.md
Fill in the Context, Priorities, Options, and Decision sections
Submit with status Proposed. ADRs require review before moving to Accepted.

Contributing by Type

Agents

Naming: devsquad.<phase>.agent.md. Required frontmatter: description, tools. Procedural and imperative instructions. Nested sub-agents are supported in VS Code 1.113+ with chat.subagents.allowInvocationsFromSubagents. Internal workers should use user-invocable: false and minimal tool sets.

Skills

Directory name = frontmatter name (kebab-case). Description optimized for semantic trigger. Max 500 lines. Include use/don’t-use scenarios.

Instructions

One per artifact type. Must include applyTo glob pattern. Concise, actionable rules. Under 50 lines.

Hooks

Bash scripts with shebang. JSON output on single line. 30-second default timeout. Register in hooks.json.

Pull Requests

Clear title and description explaining what and why
Link to related issues
Small, coherent increments (300-500 lines, 5-10 files)
Follow Conventional Commits for commit messages
English only, no emojis or decorative Unicode
Validate with markdownlint before submitting

Next Steps

Extension RecipesStep-by-step examples for creating instructions, skills, agents, and hooks.

Extensibility OverviewDecision tree for choosing the right extension mechanism.

ChangelogVersion history and recent changes.