Contributing

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

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

.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 Recipes Step-by-step examples for creating instructions, skills, agents, and hooks.

Extensibility Overview Decision tree for choosing the right extension mechanism.

Changelog Version history and recent changes.