vscode-agent-todos: Instructions file for GitHub Copilot

Project Overview

This extension provides VS Code agent mode with todo management tools through MCP (Model Context Protocol) and an integrated VS Code tree view. It enables AI assistants to proactively track tasks during development workflows with support for subtasks, priorities, auto-injection into Copilot instructions.

For more details:

• Main README - Feature overview and usage
• MCP Server Documentation - Server architecture, protocol details, and completion support
• MCP TypeScript SDK

IMPORTANT:

• ALWAYS plan changes using detailed todos
• ALWAYS keep .github/copilot-instructions.md up-to-date with the latest architecture and coding standards, addressing any drifts in implementation!
• ALWAYS validate changes by running compile and test commands!
• NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.
• NEVER make changes backwards compatible unless explicitly requested by the User.
• NEVER create one-off scripts to test changes.

Architecture

graph TB
    subgraph VSCodeExtension[VS Code Extension]
        EXT[Extension Entry<br/>extension.ts]
        TM[TodoManager<br/>Singleton]
        TTP[TodoTreeProvider]
        TDP[TodoDecorationProvider]
        SM[SubtaskManager<br/>Static Methods]
        TV[TodoValidator<br/>Static Methods]
        PM[PerformanceMonitor<br/>Static Class]
    end

    subgraph StorageLayer[Storage Layer]
        ITS[ITodoStorage<br/>Interface]
        WSS[WorkspaceStateStorage<br/>Default]
        IMS[InMemoryStorage<br/>Testing/Standalone]
    end

    subgraph ExportLayer[Export Layer]
        CIM[CopilotInstructionsManager<br/>Write-only Export]
        SCW[StandaloneCopilotWriter<br/>Write-only Export]
    end

    subgraph MCPIntegration[MCP Integration]
        MCP[TodoMCPServerProvider]
        MCPS[TodoMCPServer<br/>HTTP/SSE]
        TT[TodoTools<br/>read/write handlers]
        TS[TodoSync<br/>Bidirectional]
        STM[StandaloneTodoManager<br/>Singleton]

        subgraph SessionMgmt[Session Management]
            TRM[Transports Map]
            SRM[Servers Map]
            STR[StreamableHTTPServerTransport]
        end
    end

    subgraph ExternalInterfaces[External Interfaces]
        VSC[VS Code API]
        CI[todos.instructions.md]
        MC[MCP Clients<br/>AI Assistants]
        MCPAPI[VS Code MCP API]
    end

    %% Core initialization
    EXT --> TM
    EXT --> TTP
    EXT --> TDP
    EXT --> MCP

    %% Storage configuration
    TM --> WSS
    STM --> IMS
    WSS -.-> ITS
    IMS -.-> ITS
    MCP --> WSS

    %% UI and decorations
    TTP --> VSC
    TDP --> VSC
    TM --> TTP
    TM --> TDP

    %% View events
    TM -.->|onShouldOpenView| EXT
    TM -.->|onDidChange| TTP

    %% Export to markdown (write-only)
    TM -.->|auto-inject writes| CIM
    CIM -->|write-only| CI
    STM -.->|auto-inject writes| SCW
    SCW -->|write-only| CI

    %% MCP server setup
    MCP --> MCPS
    MCP --> MCPAPI
    MCPS --> TT
    MCPS --> STR
    STR --> TRM
    STR --> SRM

    %% Bidirectional sync
    MCP --> TS
    TS <--> TM
    TS <--> STM

    %% Tool handling
    TT --> STM
    TT --> TS

    %% External communication
    MC <-->|HTTP POST/GET/SSE| MCPS

    %% Utility usage
    TM --> SM
    TM --> TV
    TM -.-> PM
    STM --> TV