Superteam

  ____  _   _ ____  _____ ____  _____ _____    _    __  __ 
 / ___|| | | |  _ \| ____|  _ \|_   _| ____|  / \  |  \/  |
 \___ \| | | | |_) |  _| | |_) | | | |  _|   / _ \ | |\/| |
  ___) | |_| |  __/| |___|  _ <  | | | |___ / ___ \| |  | |
 |____/ \___/|_|   |_____|_| \_\ |_| |_____/_/   \_\_|  |_|

      Personal AI Squad · Claude Code + GitHub Copilot + Foundry Local

SUPERTEAM

17 specialist AI agents that coordinate like a team. One voice in, clean answer out.

---

Start Here — Navigation

New to Superteam? Read these in order:

1. HOW-TO-DEPLOY.md — install on a new machine, per-surface setup, verify install
2. docs/using-superteam.md — per-surface usage + test cases + troubleshooting
3. docs/skills-catalogue.md — every skill the squad ships with, one-liner per skill
4. This README's ## The Squad section — who does what
5. This README's ## Skills section (below) — how to invoke /deliver, /sprint, /decide, /research, /mirror

Building or extending Superteam?

• CONTRIBUTING.md — dev + PR conventions
• docs/install.md — deep install reference (fresh laptop + -InitProject + -Fresh modes)
• docs/pattern-b-upgrade.md — post-hackathon HTTP transport upgrade path
• mcp-server/README.md — MCP server architecture, tool inventory, DB schema
• vscode-extension/README.md — VS Code extension architecture

Squad + framework mechanics (read only when needed):

• .squad/decisions/ — every architectural decision as an ADR, dated + slugged. Search here first when asking "why is X the way it is."
• .squad/blueprints/ — Bob's system designs, Marlo's UX specs, Kevin's docs plans
• .squad/backlog/backlog.md — Paulien's sprint plan + post-hackathon backlog (SPX-020+)
• .squad/coach/game-tape/ — Coach's post-push observations (game tapes, one per date)
• .squad/coach/knowledge/ — Athanasios research briefs + Nexus alignment briefs (indexed at INDEX.md)

Deep dives (rarely needed):

• squad/ — framework reference tree (architecture models, playbook, onboarding, ceremonies) — canonical explanations, not per-project state
• hooks/ — PowerShell scripts wired to Claude Code session events (session-boot drift check, pre-push Vera gate, pre-commit Kevin gate, pre-edit clearance checks)
• scripts/ — install-superteam.ps1 (Stage 8) + generate-platform-files.ps1 (Stage 7) + SuperteamControl.psm1 (autostart control module)
• agents/*.md — canonical agent identity files (16 personas). Generated fan-out lives in .github/agents/
• skills/*/SKILL.md — 25 skills the squad ships with. Full catalogue: docs/skills-catalogue.md

Understanding the folder layout:

Folder	What it is	Read when
.claude/	Global Claude Code config (install snapshots for ~/.claude/)	You want to see what the install script writes
.copilotstudio/	Copilot Studio declarative agent stub	Building for M365 Copilot enterprise import
.github/agents/	Generated .agent.md × 32 (VS Code + Copilot variants)	Never edit by hand — run pwsh scripts/generate-platform-files.ps1
.github/copilot-instructions.md	Generated Copilot repo-wide roster + rules	Never edit by hand — regenerated from agents/*.md
.squad/	Per-project squad state (decisions, blueprints, backlog, game tape)	Superman + all agents write here during a task
agents/	16 canonical agent identity files	Editing an agent's persona/routing/non-negotiables
docs/	User-facing documentation	Anytime you're using or extending Superteam
hooks/	Session-boot + pre-push/pre-commit hook scripts	Modifying framework enforcement (Coach fence denylist territory)
mcp-server/	TypeScript MCP server (13 tools, 7 resources, 5 prompts, SQLite WAL DB)	Extending MCP capabilities
scripts/	Install script, platform fan-out generator, control module	Machine setup or platform-file regeneration
skills/	25 SKILL.md files (Core + Superpowers + Semantic + Fabric + Enterprise Integration + Hackathon)	Adding a new skill or reviewing existing
squad/	Framework reference tree (architecture, playbook, onboarding)	Deep-dive on framework design (rare)
vscode-extension/	VS Code extension source + VSIX package	Rebuilding or debugging the extension

Note on file counts: Your file explorer sees ~35,000 files but only 349 are tracked in git. The remaining ~34,600 are node_modules/ for the MCP server and VS Code extension — correctly gitignored and never pushed. You can safely delete them and reinstall via npm install in each of those directories.

---

Getting Started

On a new machine: clone the repo and run the install script.

# Either remote works — both are kept in sync
git clone https://github.com/stevemarksava/superteam.git   # personal repo
# or:
# git clone https://github.com/ava-innersource/fde-superteam.git   # Avanade InnerSource (SAML SSO required)
cd superteam
./scripts/install-superteam.ps1

The script detects what is installed, presents a surface menu, configures MCP entries, optionally registers the MCP server as a Windows Task Scheduler autostart, and installs the SuperteamControl PowerShell module. On a fresh laptop add -Fresh — it sequences all prerequisite installs before proceeding.

On each new project: from the project root, run:

./scripts/install-superteam.ps1 -InitProject .

This bootstraps the workspace-scoped files VS Code Copilot and Copilot Desktop App need (.github/agents/, .github/copilot-instructions.md, AGENTS.md, .vscode/mcp.json). Claude Code CLI and Copilot CLI are global — nothing extra needed for those.

Full install guide: docs/install.md

VS Code extension (Management UI + Chat Participants): install the VSIX directly from the repo:

1. Open VS Code → Extensions: Install from VSIX…
2. Select vscode-extension/superteam-management-ui.vsix
3. Run command: Superteam: Show Management UI

The panel shows all 8 runtime surfaces, credit status, Coach dashboard, and Kryptonite C3 denylist fence. All 17 agents are also available as @superteam-<name> participants in Copilot Chat (e.g. @superteam-eric build this).

---

Why Superteam

Most AI assistant setups give you one model and hope. Superteam gives you a squad.

The problem: A single AI agent context gets bloated, loses discipline, and has no memory of what it got wrong last week. Every session starts from zero. Quality is inconsistent. Nobody's accountable.

What Superteam does differently:

• Named specialist agents — Superman leads. Bob blueprints. Eric builds. Vera QA's. Each knows their lane.
• Enforced discipline — Hooks block pushes if Vera hasn't approved. Kryptonite runs a red team before every build. Nothing ships on vibes.
• A coach that remembers — After every push, Coach writes a game tape. Patterns that appear 3 tapes in a row trigger automatic enforcement. The team that finishes project 10 is measurably better than the one that started project 1.
• Cross-project memory — Agents log what they learned. Context from one project informs the next. The knowledge accumulates.
• Works where you work — Claude Code, Claude Desktop, Claude.ai, GitHub Copilot. Same squad, every surface.

One pattern at the core: You talk to Superman. He routes the right specialist, enforces the gates, synthesises the answer, and delivers it to you clean. You never manage agents — you manage outcomes.

---

What Is Superteam

Superteam is a squad of named AI agents — each with a fixed role, a character, and a memory. Talk to them by name. They coordinate. Superman is the default voice. The squad lives in ~/.claude/ and is available in every project automatically, no setup required per-project beyond the initial scaffold.

---

This Repo Is an Installer — Not a Project Template

Clone it once. Run the install script. Then never open it again for project work.

Superteam is a machine-level framework. The install script deploys the squad across every AI surface on the machine — not just Claude Code. Agents and skills land in ~/.claude/ (Claude Code + Claude Desktop), ~/.copilot/ (Copilot CLI), and .github/agents/ (VS Code Copilot + Copilot Desktop). The shared MCP server runs as a local process all surfaces connect to. The VS Code extension installs the Management UI and all 16 agents as @superteam-<name> chat participants.

This repo	Your projects
Clone once per machine	Your actual work lives here
Run install-superteam.ps1 once	Open each project in its own Claude Code session
Never open for day-to-day work	The squad is already there — on every surface

What this means in practice:

• The squad is available everywhere because it lives in ~/.claude/ — not because this repo is open
• Do not clone this repo into client projects or use it as a boilerplate
• No client names, project code, or project-specific content belong here
• If a client project needs Superteam, run install-superteam.ps1 once on the machine — done

If you find yourself doing project work from inside this repo: stop. Open a new Claude Code session in the project's own directory. The squad travels through ~/.claude/, not through this folder.

---

The Squad

Agent	Role	Activate with
Superman	Lead — your one interface	Default / "Superman"
Paulien	Scrum master, planner, backlog owner	"Paulien"
Bob	Solution architect (Build Or Break)	"Bob"
Eric	Coder — leads the dev pod	"Eric"
Marlo	UX designer + product voice	"Marlo"
Kevin	Report builder, documenter, documentation lead	"Kevin"
Vera	Quality gate — nothing ships without her	"Vera"
Athanasios	Researcher, knowledge bank	"Athanasios"
G	Finance, grant reporting	"G"
Coach	Squad coach — game tape, drills, enforcement	"Coach"
Kryptonite	Red team — challenges before Eric builds	"Kryptonite"

Dev Pod (under Eric — say "Eric" to route automatically, or call the specialist directly):

Agent	Speciality	Activate with
Pixel	Frontend: React, TypeScript, Tailwind	"Pixel"
Diesel	Backend: Python, APIs, Node	"Diesel"
Atlas	Data & graph: Neo4j, PostGIS, ETL	"Atlas"
Orbit	DevOps & cloud: Azure, CI/CD	"Orbit"

Specialist (domain-specific — call by name):

Agent	Speciality	Activate with
Nexus	Microsoft platform: Azure, M365, Fabric — GA status, Avanade patterns	"Nexus"
Sage	HVE Core + HVE Learning specialist. Bridges Superteam ↔ HVE. Routes Eric-vs-RPI decisions, coaches on HVE methodology, manages HVE project installs.	"Sage"

Agent files: ~/.claude/agents/<name>.md (global) or .claude/agents/<name>.md (project override)

---

Boot Protocol

What actually happens when a Claude Code session starts:

1. session-boot.ps1 fires automatically — injects Superman's lessons and the latest game tape into the session context
2. ~/.claude/CLAUDE.md loads — global squad config, always available
3. Project CLAUDE.md loads — project-specific context and decisions
4. All agents and skills from ~/.claude/ are available immediately

On a new project with no .squad/ yet — just say "hey Superman". He scaffolds it automatically. See HOW-TO-DEPLOY.md for all three surfaces.

---

How to Talk to the Squad

Activate an Agent

"Superman, let's kick off"         — starts a session, Superman routes from here
"Bob, blueprint this"              — get an architecture design before building
"Kryptonite, challenge this"       — red-team review before Eric builds
"Eric, build it"                   — implementation (Eric routes to pod if specialist needed)
"Pixel, build the [component]"     — direct frontend work
"Diesel, build the [endpoint]"     — direct backend work
"Atlas, model the [data]"          — data/graph modelling
"Orbit, deploy this"               — DevOps/cloud work
"Vera, review this"                — QA sign-off
"Athanasios, research [topic]"     — deep research on anything
"Paulien, plan this sprint"        — sprint planning
"Coach, how's the squad?"          — team health check
"G, what does this cost?"          — financial analysis

Use a Skill

/decide [topic]                          — log a decision before you build
/deliver                                 — full delivery chain (Vera → commit → push → Coach)
/sprint brief="..." acceptanceCriteria="..." — parallel planning + Kryptonite gate + task briefs
/research question="..."                 — 4-angle parallel research → synthesized brief
/mirror                                  — opt-in self + peer reflection at task close

---

Skills

Core delivery skills plus three extended packs — 25 skills available globally in every project. Full reference: docs/skills-catalogue.md.

/deliver

Full delivery chain, in order, no skipping:

1. Brief Vera — she must approve before anything commits
2. Kevin documentation audit — flags any docs that went stale during the build
3. Update any flagged READMEs or squad docs
4. Delete sentinel files (active-task, vera-approved, kryptonite-cleared)
5. Stage relevant files, show the list
6. Commit with co-author line (Co-Authored-By: Claude Sonnet 4.6)
7. Push to origin
8. Confirm the Coach hook fired (check today's game tape)
9. Report a clean delivery summary

/decide

Logs a decision and sets an active task sentinel:

1. Optionally consults Bob + Kryptonite in parallel for major decisions
2. Writes .squad/decisions/YYYY-MM-DD-<slug>.md — decision, reasoning, alternatives rejected, impact
3. Writes .squad/active-task.md — gitignored sentinel; tells the pre-edit hook a tracked task is active
4. The sentinel is deleted automatically when /deliver runs

/sprint

Structured multi-agent sprint using the Workflow tool:

1. Plan (parallel): Paulien breaks down tasks + Bob blueprints — both run simultaneously
2. Red Team: Kryptonite challenges both outputs — returns BLOCKED, BUILD_WITH_CONDITIONS, or CLEAR_TO_BUILD
3. Brief: Returns structured task list with agent assignments and done criteria
4. Superman executes tasks sequentially with the assigned agents, then runs /deliver

/research

Parallel intelligence gathering using the Workflow tool:

1. Research (parallel): Athanasios runs 4 angles simultaneously — technical, competitive, risks, real-world usage
2. Synthesis: Athanasios consolidates into a single intelligence brief
3. Returns the brief to Superman to deliver to you

/mirror

Opt-in self + peer reflection at task close. Run after significant tasks:

1. Superman reads the last 3 game tapes and reflection files
2. Synthesises patterns — what held, what slipped, score delta
3. Writes a reflection file to .squad/coach/mirror/
4. Lesson candidates surfaced here that appear twice become confirmed lessons in lessons.md

Stage 9 — Extended Skills Packs

Superpowers (owner: Eric)

Skill	Purpose
systematic-debugging	Hypothesis-driven bug isolation — reproduce, minimal test case, regression coverage
test-driven-development	RED / GREEN / REFACTOR loop — failing test first, minimum code to green, then clean

Semantic (owner: Atlas)

Skill	Purpose
ontology	Model a domain as OWL/RDF — classes, properties, hierarchies, JSON-LD output
semantic-reasoning	Reason over a knowledge graph — SPARQL, OWL inferencing, SHACL validation
semantic-search	Vector-embedding retrieval with BM25 hybrid ranking and scored results

Microsoft Data + AI Platform (owners per row)

Skill	Owner	Purpose
fabric-medallion	Atlas	Bronze/silver/gold zones, quality gates, promotion policy
fabric-onelake	Atlas	Workspaces, shortcuts, Delta Lake tables, Domains
fabric-power-bi	Atlas + Marlo	Semantic model, DAX, deployment pipelines, accessibility
copilot-studio-build	Nexus + Bob	Declarative agent authoring, knowledge sources, M365 publish
azure-ai-foundry-dev	Nexus + Bob + Diesel	Foundry Agent Service, model catalogue, SDK-based agents
azure-devops	Orbit	Pipelines, boards, artifact feeds, service connections
fabric-notebooks	Atlas + Diesel	Spark config, notebookutils, lakehouse read/write, scheduling

---

Hooks

Four hooks live in ~/.claude/hooks/ and fire automatically — no invocation needed.

Hook	Trigger	What it does
session-boot.ps1	SessionStart	Injects Superman lessons + latest game tape into every session; seeds .squad/telemetry/ skeleton for Coach's 4-level scoring (SPX-032)
post-push-coach.ps1	PostToolUse / git push	Detects a push, spawns Coach to write game tape with 4-level scoring output (Personal / Pair / Pod / Squad) — reads telemetry
pre-push-vera.ps1	PreToolUse / git push	Blocks push without vera-approved.md; advisory warning if telemetry absent
pre-edit-check.ps1	PreToolUse / Write or Edit	Advisory warning if editing squad files without a logged active task

These run globally — every project that runs Claude Code gets them.

---

Non-Negotiables

• Nothing ships without Vera's sign-off
• No significant build starts without Bob's blueprint
• Kryptonite reviews before Eric builds — every time
• Coach writes game tape after every push — the hook handles this automatically
• Every decision goes in .squad/decisions/ — use /decide
• Superman delivers to you — one clean answer

---

New Project Setup

No setup script. No configuration. Just say "hey Superman" in Claude Code, Copilot, or Claude.ai.

Superman detects whether .squad/ exists. If it doesn't, he scaffolds it in one step — decisions log, game tape, agent memory, CLAUDE.md, .github/copilot-instructions.md. Then asks what you're building.

Full instructions for all three surfaces: HOW-TO-DEPLOY.md

---

File Structure

superteam/
├── HOW-TO-DEPLOY.md            <- 8-surface install + test guide (519 lines)
├── README.md                   <- This file
├── CHANGELOG.md                <- Version history (semver, Keep-a-Changelog)
├── AGENTS.md                   <- Generated flat-file agent roster (for Codex/OpenCode)
├── agents/                     <- 17 canonical agent identity files
│   └── {superman,paulien,bob,eric,marlo,kevin,vera,athanasios,g,coach,
│        kryptonite,pixel,diesel,atlas,orbit,nexus,sage}.md
├── skills/                     <- 25 SKILL.md files (Core / Superpowers / Semantic / Fabric / Enterprise Integration / Hackathon)
├── hooks/                      <- PowerShell hook templates (install script deploys to ~/.claude/hooks/)
│   ├── session-boot.ps1        <- SessionStart: version drift check + lesson injection
│   ├── pre-edit-check.ps1      <- PreToolUse: sentinel gates (marlo-specced, kryptonite-cleared, pod-routed)
│   ├── pre-push-vera.ps1       <- PreToolUse (git push): hard-blocks without vera-approved.md
│   ├── pre-commit-kevin.ps1    <- PreToolUse (git commit): hard-blocks without kevin-docs-checked.md
│   └── post-push-coach.ps1     <- PostToolUse (git push): triggers Coach game tape
├── mcp-server/                 <- TypeScript MCP server (13 real tools, 7 resources, 5 prompts)
├── vscode-extension/           <- VS Code extension: Management UI webview + 16 chat participants
├── scripts/
│   ├── install-superteam.ps1   <- Cross-platform installer (menu, -Fresh, -InitProject, -Auto, -Check)
│   ├── generate-platform-files.ps1  <- Fan-out generator (agents/*.md → 32 .agent.md files)
│   ├── SuperteamControl.psm1   <- PowerShell module (Start/Stop/Restart/Get-SuperteamMcpStatus)
│   └── install/                <- detect/menu/autostart helpers
├── docs/                       <- User docs (install, using-superteam, skills-catalogue, pattern-b-upgrade, hackathon script)
├── .github/                    <- Generated: agents/*.agent.md × 32, copilot-instructions.md
├── .copilotstudio/             <- Generated: superteam.agent.json (Copilot Studio import stub)
├── .vscode/                    <- mcp.json (stdio primary, HTTP variant commented)
├── .squad/                     <- Per-project state (decisions, blueprints, backlog, game tape, agent memory)
│   ├── decisions/              <- ADRs (append-only)
│   ├── blueprints/             <- Bob's designs, Marlo's UX specs, Kevin's docs plans
│   ├── backlog/backlog.md      <- Paulien's sprint plan + deferred SPX-020+ tickets
│   ├── coach/game-tape/        <- One file per push date; written by Coach after every /deliver
│   ├── coach/knowledge/        <- Athanasios recon + Nexus alignment briefs (INDEX.md)
│   └── agents/<name>/memory/   <- Per-agent per-project memory
└── squad/                      <- Framework reference tree (architecture, playbook, onboarding — canonical explanations)

Global installed by install script (not in the repo):

~/.claude/
    agents/*.md                  <- 17 agent identity files (copied from agents/)
    skills/<name>/SKILL.md       <- 25 skills globally available
    hooks/*.ps1                  <- 5 hook scripts wired via settings.json
    settings.json                <- Hook + permission configuration
    squad/                       <- Cross-project agent memory + versions.json
~/.copilot/
    agents/*.agent.md            <- 17 agents for Copilot CLI
    mcp-config.json              <- MCP server declaration (mcpServers schema)

---

The Coach Pattern

An original coaching pattern. Coach:

• Writes game tape after every push (automated via hook)
• Runs deliberate practice drills for weak areas
• Tracks per-agent improvement over time
• Has enforcement authority — when 3 tapes show the same slip, Coach builds a hook or skill to prevent recurrence

Agent memory accumulates in two places:

• Global (~/.claude/squad/agents/<name>/memory/) — lessons across all projects
• Project (.squad/agents/<name>/memory/) — this project's specific context

The team that finishes project 10 is demonstrably better than the one that started project 1.

---

Platform Support

Platform	Config file	Status
Claude Code (terminal)	CLAUDE.md	Full — hooks, sub-agents, skills
Claude Desktop	~/.claude/CLAUDE.md	Full
Claude.ai (web)	claude-ai-project-instructions.md	Full
Claude in Chrome	claude-ai-project-instructions.md	Full
GitHub Copilot	.github/copilot-instructions.md	Full

---

VS Code Extension

vscode-extension/ ships a Management UI webview and 16 agent chat participants for VS Code.

Install: Extensions: Install from VSIX… → select vscode-extension/superteam-management-ui.vsix

Activate: command palette → Superteam: Show Management UI

The webview renders:

• 8 Surface cards — runtime status, credit indicator (green / amber / red / grey), and quick-launch for each supported surface
• Credits tab — consolidated credit view across all surfaces; routing recommendations when a surface is near quota
• Coach dashboard — latest game tape entry and active proposals
• Kryptonite C3 fence — denylist proposals shown without an approve button; the approval path does not exist in the UI

Chat participants: all 16 agents are available as @superteam-<name> in Copilot Chat. Call them by name — @superteam-eric, @superteam-vera, @superteam-bob, etc.

Chrome DevTools MCP badge: the panel surfaces Chrome DevTools MCP install status. If not installed and UI work is detected in game tape, Coach will propose it.

Spec: .squad/blueprints/2026-09-04-management-ui-spec.md (Marlo v2). Extension README: vscode-extension/README.md.

---

MCP Server

The Superteam MCP server (mcp-server/) is the cross-platform conductor. It exposes Superteam skills, Coach loops, and runtime routing as Model Context Protocol tools, resources, and prompts. Any MCP-aware host — VS Code Copilot, Claude Code CLI, GitHub Copilot CLI, Copilot Desktop App — connects over stdio and drives the same squad.

Config files written by the install script:

• .vscode/mcp.json — VS Code Copilot and Claude Code CLI (top-level key: servers)
• ~/.copilot/mcp-config.json — GitHub Copilot CLI (top-level key: mcpServers — different schema per surface, install script writes each correctly)

All 13 tools are real (zero stubs): 4 Coach (write_game_tape, observe, review, propose), 5 routing/status (delegate, agent, check_credits, status, run_local), 4 skill wrappers (sprint, deliver, vera_signoff, decide). All 8 target surfaces have adapter code (5 real, 2 inert-when-not-configured, 1 documented Copilot Desktop SDK stub). superteam_run_local invokes Foundry Local via OpenAI-compatible REST. See mcp-server/README.md for the full tool, resource, and prompt inventory. Post-hackathon Pattern B HTTP transport is ready — see docs/pattern-b-upgrade.md.

Legend for terms used above:

• Kryptonite C3 — one of five binding conditions Kryptonite set at framework clearance; C3 requires the Coach fence's UI layer to structurally distinguish denylist-touching proposals from routine ones (implemented as the ApplyHooksModal in the VS Code extension)
• SPX-020+ — sprint ticket numbering for post-hackathon deferred work; see .squad/backlog/backlog.md for the full ticket list with owners + priorities

---

Superteam. Built to grow.