Supercode is a CLI using GitHub Copilot models via LSP with deep integration into ADO and VS Code to support developer workflows end-to-end.
It is developed using algorithms simulating how claude code works and optimized for the lower context limit of the github copilot models.

# Core principles
- Integration into developer workflow at Microsoft (ADO + Github Copilot)
- Developer-driven - assisting the developer at any point in the development lifecycle, not replacing them
- Developers can choose fully autonomous mode or can choose to jump in and jump out at any phase in development lifecycle
- Add predictability through automation/scripting along with intelligence through agents
- Provide rich features found in leading tools - commands, output-styles, hooks, agents, sub-agents, context-management - with an easy to use facade that incorporates best practices by default.

# Architecture

graph TB
    subgraph External["<div style='font-size:16px'>☁️ <b>EXTERNAL SERVICES</b></div>"]
        direction LR
        ADO["<div style='padding:8px'><b>Azure DevOps</b><br/><br/>📋 Work Items<br/>🔄 Pull Requests<br/>📁 Repositories</div>"]
        Copilot["<div style='padding:8px'><b>GitHub Copilot</b><br/><br/>🤖 AI Suggestions<br/>✨ Code Completion<br/>🧠 Intelligence</div>"]
    end
    
    subgraph Core["<div style='font-size:16px'>⚡ <b>SUPERCODE CORE</b></div>"]
        direction TB
        
        Server["<div style='padding:12px;font-size:14px'><b>🎯 SUPERCODE SERVER</b><br/>━━━━━━━━━━━━━━━━━<br/><br/>Central Orchestrator<br/>State Management<br/>Request Processing</div>"]
        
        subgraph Connect["<div style='font-size:14px'>🔌 <b>Connectors</b></div>"]
            direction LR
            PAT["<div style='padding:6px'><b>🔐 PAT Token</b><br/>Manager</div>"]
            LSP["<div style='padding:6px'><b>📡 LSP</b><br/>Client</div>"]
        end
        
        Server --- Connect
    end
    
    subgraph UI["<div style='font-size:16px'>👥 <b>USER INTERFACES</b></div>"]
        direction TB
        
        subgraph Console["<div style='font-size:13px'>⌨️ Terminal</div>"]
            Terminal["<div style='padding:8px'><b>Console UI</b><br/><br/>CLI Commands<br/>Interactive Mode<br/>Log Streaming</div>"]
        end
        
        subgraph Web["<div style='font-size:13px'>🌐 Web</div>"]
            WebUI["<div style='padding:8px'><b>Web Interface</b><br/><br/>Visual Designer<br/>Code Preview<br/>Dashboard</div>"]
        end
        
        subgraph VSC["<div style='font-size:13px'>🔧 VS Code</div>"]
            direction TB
            VSCodeExt["<div style='padding:8px'><b>Extension Host</b><br/><br/>IDE Integration<br/>IntelliSense</div>"]
            EmbeddedUI["<div style='padding:8px'><b>Embedded UI</b><br/><br/>Web View<br/>Interactive Tools</div>"]
            VSCodeExt -.->|embeds| EmbeddedUI
        end
    end
    
    %% External Connections
    PAT ==>|"🔑 Auth"| ADO
    LSP ==>|"💬 Protocol"| Copilot
    
    %% Core to UI Connections
    Server <=====>|"⚡ WebSocket<br/>Real-time Sync"| Terminal
    Server <=====>|"🌐 HTTP/WS<br/>REST API"| WebUI
    Server <=====>|"🔌 IPC<br/>Extension API"| VSCodeExt
    
    %% Modern Styling
    classDef serverClass fill:#4f46e5,stroke:#312e81,stroke-width:4px,color:#fff,rx:10,ry:10,font-weight:bold
    classDef externalClass fill:#059669,stroke:#064e3b,stroke-width:3px,color:#fff,rx:8,ry:8
    classDef terminalClass fill:#7c3aed,stroke:#5b21b6,stroke-width:3px,color:#fff,rx:8,ry:8
    classDef webClass fill:#0891b2,stroke:#164e63,stroke-width:3px,color:#fff,rx:8,ry:8
    classDef vscodeClass fill:#0284c7,stroke:#075985,stroke-width:3px,color:#fff,rx:8,ry:8
    classDef connectorClass fill:#d97706,stroke:#92400e,stroke-width:2px,color:#fff,rx:6,ry:6
    
    classDef externalGroup fill:#d1fae5,stroke:#059669,stroke-width:3px,rx:12,ry:12
    classDef coreGroup fill:#ddd6fe,stroke:#4f46e5,stroke-width:3px,rx:12,ry:12
    classDef uiGroup fill:#fce7f3,stroke:#9f1239,stroke-width:3px,rx:12,ry:12
    classDef subGroup fill:#f9fafb,stroke:#6b7280,stroke-width:2px,rx:8,ry:8
    
    class Server serverClass
    class ADO,Copilot externalClass
    class Terminal terminalClass
    class WebUI webClass
    class VSCodeExt,EmbeddedUI vscodeClass
    class PAT,LSP connectorClass
    
    class External externalGroup
    class Core coreGroup
    class UI uiGroup
    class Console,Web,VSC,Connect subGroup

# Agentic Developer Workflow

Here is how supercode will help developers in each of the stages of development:

flowchart LR
    PG["📝 Prompt<br>Generation"] --> D["🎨 Design"]
    D --> I["⚡ Implementation"]
    I --> R["🔍 Review"] & Val{"✅ Build/Test"}
    R --> M["🛠️ Maintain"]
    M -. Future .-> DO["🔄 DevOps<br>Coming Soon"]
    Dev(["👨‍💻 Developer"]) -.-> PG & D & I & R & M
    Dev -. Future .-> DO
    Val -- Pass --> R
    Val -- Fail --> I
    DO -.-> Pipeline["Pipeline<br>Monitoring"] & Fix["Auto-fix<br>Failures"] & Release["Release<br>Management"]
        
    ADO["🔷 Azure DevOps<br>Integration"]
    VSC["💻 VS Code<br>Integration"]
    GH["🐙 GitHub Copilot<br>Integration"]

    style PG fill:#f3e5f5
    style D fill:#f3e5f5
    style I fill:#f3e5f5
    style R fill:#f3e5f5
    style Val fill:#e8f5e9
    style M fill:#f3e5f5
    style DO fill:#ffebee,stroke:#b71c1c,stroke-width:2px,stroke-dasharray: 5 5
    style Dev fill:#667eea,color:#fff
    style Pipeline fill:#ffebee,stroke:#b71c1c,stroke-width:2px,stroke-dasharray: 5 5
    style Fix fill:#ffebee,stroke:#b71c1c,stroke-width:2px,stroke-dasharray: 5 5
    style Release fill:#ffebee,stroke:#b71c1c,stroke-width:2px,stroke-dasharray: 5 5
    style ADO fill:#0078d7,color:#fff
    style VSC fill:#007ACC,color:#fff
    style GH fill:#24292e,color:#fff

## Prompt generation

1. Developer input: Prompt
2. Developer input: Prompt + Related PR
3. Developer input: Prompt + Work item + (optional Related PR)

- When developer provides PR, the agent gets the changed files and change diff, adds it to context.
- When developer provides work item, the agent extracts summary, discussion, linked PRs and parent work item data and adds them to context.

Uses the details provided to create a comprehensive prompt which includes what changes are expected to be made.

This prompt can be reviewed by the developer and provided to design or implementation step.

## Design

- Developers can provide prompt generated from prompt generation tab or provide the data they can provide the prompt directly with work item or PR references as earlier.
- Developers can generate design one of the two ways:
- A file-by-file implementation plan which contains all the details about the implementation, with file-by-file changes clearly provided.
- A phase-wise implementation plan which contains the task divided into multiple sub-tasks which can be implemented in succession. The phases can be used to create sub-tasks for the initial work item.
- The developers can choose to have the agent implement all the items or choose to implement a few of them and let the agent implement remaining. Allowing for incremental work + PRs for complex features.

> [!Note] Coming soon
> Design review agent which can allow the agent to review the design. This can be used to review agent generated design or developer generated design to capture any gaps/concerns with design.

## Implementation

- The developer can choose to provide a new work item, using direct prompt, enhanced prompt or work item + pull requests.
- The developer can also provide a partially complete work item along with the context about the work item (linking work-item/related PRs)
- The agent will review any existing work and pending work and complete the work as per the instructions.
- The workflow will automatically run deterministic, programmatic validation (build, test, etc.) steps to avoid agent hallucination and provide a feedback loop to ensure the agent completes the work and validation passes.

> [!Note] Coming soon
> Implementation validation agent which uses both deterministic tools + agent intelligence to validate the completion of the work or see if the agent is just bluffing by providing incomplete implementation using TODOs, placeholders or mock data.

## Review

For own ADO PRs:
- Review agent changes or the developer's own changes using the review agent locally before sending out the Pull Request in ADO.
- One-click accept suggestions/fixes from agent OR other developers as part of the PR so the agent can implement them.

For other's ADO PRs:
- Load the pull request of a different developer to get context from agent. Ask questions regarding the changes so the agent can go through the code and answer them for you.
- Send agent's / developer's comment to the PR.

> [!Note] Coming soon
> **Monitor mode for PRs** - you can use this for PRs generated by the agent as well as PRs generated by developers.
> Agent will *listen* to the PR for comments and make changes as requested in the PR as long as they meet the criteria provided by the developer (simple changes, refactor comments)

## Maintain

- Generate/update feature documentation
- Refactor existing code
- Update package versions

> [!Note] Planned work
> **Maintenance templates** - specific command instructions and tools for reading and parsing specialized work-items like S360 work items, codeql files, security work items, etc., so the agent can listen in daemon mode and do heavy lifting for such work items.

## [Coming Soon-ish] Daemon Mode

- Listens to work items assigned to you with supercode tag and performs all the stages of the development above as appropriate.
- Will notify the developer if there are any questions for the developer.
- Use worktrees to parallely work on multiple tasks at the same time.

## [Planned] DevOps

- Run and monitor build pipeline
- Fix any failures encountered during the build pipeline run
- Rerun build pipeline in case of any transient failures

- Run and monitor dev release
- Rerun dev release in case of any transient failures
- Fix any failures in synthetics using logs (via Brainbot MCP)