Troubleshooting

Plugin not found after update

Clear VS Code cache and restart:

macOS: ~/Library/Application Support/Code/agentPlugins/
Windows: %APPDATA%\Code\agentPlugins\
Linux: ~/.config/Code/agentPlugins/

Hooks fail with “command not found”

Verify paths in hooks.json are relative to the plugin root directory
Ensure bash scripts have executable permissions (chmod +x)
Check shebang line: #!/bin/bash or #!/usr/bin/env bash

Agents not visible in VS Code

Requires VS Code 1.113.0 or later
Enable chat.plugins.enabled in VS Code settings
Verify plugin installation via the Extensions panel

GitHub authentication errors

VS Code: Sign out and sign back in via the Copilot extension
CLI: Run gh auth login and ensure the Copilot scope is included
Verify your token has required permissions (repo, read:org)

MCP servers not connecting

Verify .mcp.json exists at the plugin root
Restart VS Code to reload MCP configuration
Check network connectivity to MCP endpoints
For Azure DevOps MCP: ensure npx @azure-devops/mcp@next resolves

Copilot CLI code intelligence unavailable

New repository without a stack: LSP setup is deferred until source files or build manifests appear. Continue envisioning, specification, and planning without installing servers. The hook records this deferral without warning when it finds no recognizable code or build evidence outside excluded directories; this is not proof that the repository is empty. To prepare an explicitly chosen stack before code exists, request setup for those languages. Configuration and startup can be checked separately; code-navigation verification waits for source files.

Run /lsp to inspect effective language servers. Servers can come from project, plugin, or user configuration.
Use /lsp test SERVER-NAME to verify startup and /lsp logs to inspect failures. A valid JSON file or reachable executable alone does not establish a working server.
If language support is missing, ask “Set up LSP for this repository” to activate the lsp-setup skill. Review the detected languages, installation commands, and scope before approving changes.
After configuration changes, run /lsp reload, then check status and test the server again. Use /lsp help to check support in your installed CLI; restart only if that version requires it.
Verify a definition or reference lookup in a saved file of the intended language. In monorepos, check whether the server requires a subproject rootUri.

.memory/lsp-status.md is a session-start snapshot of CLI configuration file presence. It does not check validity, disabled entries, language coverage, plugin-provided servers, or runtime health. The snapshot refreshes at the next session start, not on /lsp reload.

Project configuration at .github/lsp.json overrides plugin configuration, which overrides user configuration at ~/.copilot/lsp-config.json for matching server names. Shared configuration does not install server binaries on other contributors’ machines.

VS Code: Check the relevant language extension and editor diagnostics. CLI configuration and its status snapshot do not determine whether VS Code language services are available.

Tool extensions not syncing

Ensure .github/devsquad/tool-extensions/ YAML files exist
Run the sync script manually
Check sessionStart hook output for warnings
Verify plugin version matches the extensions

Work items not creating

Verify board configuration in .memory/board-config.md
Check GitHub or Azure DevOps permissions
GitHub: Labels are created automatically if they do not exist
Azure DevOps: Verify process template detection (Scrum, Agile, Basic, CMMI)

Markdown lint warnings

Some rules are intentionally disabled in .markdownlint.yaml:

MD013: Line length (tables and links frequently exceed 80 chars)
MD033: Inline HTML (Azure DevOps mermaid uses :::mermaid)
MD041: First-line heading (agent files start with YAML frontmatter)

Still Stuck?

Check the FAQ for common questions
Open an issue on GitHub