Framework Architecture

This page explains how the framework is organized: how agents collaborate, how context moves between phases, and how traceability is maintained from vision to code.

Design Principles

The framework is shaped by a few deliberate choices about how agents behave, how they’re engineered, and how they fit into an existing codebase.

Socratic by Design

Agents ask before they act. Scope, engineering practices, and architectural choices are surfaced as questions, not defaults silently applied on the user’s behalf. Teams learn the why, not just the steps.

Human-in-the-loop by Impact

Autonomy scales with risk. Low-impact changes execute directly, medium ones require a plan, and high-impact changes require explicit approval plus an ADR. The developer decides; the AI accelerates.

Specs are Living Artifacts

Specs and ADRs are refined as implementation reveals new understanding. The framework has a named seam for amending them mid-flight, so discoveries made during the work update the shared model instead of being silently absorbed or lost. See Spec Amendment.

Flexibility

Use the conductor for a guided flow, or invoke specialist agents directly when the task is clear. Both paths produce the same artifacts.

Context Isolation by Default

Sub-agents run in their own context windows and return only structured results, keeping the main conversation small and decisions traceable across long-running work.

Principle of Least Privilege

Each agent exposes only the granular tools it needs, not full access to every MCP server. This reduces blast radius and cuts model overhead from oversized tool catalogs during selection.

Trusted MCP Servers Only

Ships with a curated set of first-party MCP servers. No opaque third-party servers are required, which keeps the tool surface reliable and makes enterprise security review straightforward.

Decisions as Transparent Artifacts

Every core architectural choice is recorded as an ADR with ranked priorities, evaluated options, and trade-offs. Specs, plans, and contracts live as files on disk; session context is ephemeral, the repository is the permanent reference.

Extensibility without Forking

Custom instructions, skills, agents, hooks, and tool extensions layer on top of the framework, so stack or domain adaptations don’t require modifying core.

Stack and Model Agnostic

Engineering discipline travels with your stack. Agents bake in test-first implementation, ADRs, security review, quality gates, and source verification against official docs regardless of the language or AI model. Team- and stack-specific coding guidelines live in a file you own (.github/docs/coding-guidelines.md) and can be rewritten any time.

Architecture Overview

Agent Interaction

The framework follows a conductor pattern: the user interacts with the devsquad conductor, which delegates to specialist agents by phase. Complex specialist agents also act as coordinators, delegating to focused worker sub-agents with isolated context. This nested sub-agent architecture enables parallel execution and context isolation without adding extra user requests.

flowchart LR
  user["User"] --> conductor["devsquad<br>(conductor)"]
  user -.->|"direct invocation"| agents

  conductor -->|"delegates<br/>by phase"| agents

  subgraph agents["Specialist Agents"]
    subgraph agents-row1[" "]
      direction LR
      init["init"]
      envision["envision"]
      kickoff["kickoff"]
      specify["specify"]
    end
    subgraph agents-row2[" "]
      direction LR
      plan[["plan"]]
      decompose["decompose"]
      implement[["implement"]]
      sprint["sprint"]
    end
    subgraph agents-row3[" "]
      direction LR
      review[["review"]]
      refine[["refine"]]
      security["security"]
      extend["extend"]
    end
  end

  agents -->|"work items<br/>and repos"| github-ado
  agents -->|"Azure services<br/>and policies"| azure
  agents -->|"documentation<br/>and guidance"| learn

  subgraph mcp["MCP Servers"]
    direction LR
    github-ado["GitHub /<br/>Azure DevOps"]
    learn["Microsoft<br/>Learn"]
    azure["Azure"]
  end

Double-bordered nodes are coordinator agents. They can delegate internally to worker sub-agents.

Nested Sub-agent Detail

The current worker topology centers on plan, implement, review, and refine. Workers run with isolated context windows and are hidden from the user-facing agent picker.

flowchart TD
  subgraph impl["implement (coordinator)"]
    direction TB
    impl-validate["validate"]
    impl-execute["execute"]
    impl-verify["verify"]
    impl-finalize["finalize"]
  end

  impl --> review

  subgraph review["review (coordinator)"]
    direction TB
    subgraph review-parallel["parallel"]
      direction LR
      rev-spec["spec"]
      rev-adr["adr"]
      rev-code["code"]
      rev-sec["security"]
      rev-tests["tests"]
    end
  end

  subgraph plan-box["plan (coordinator)"]
    direction TB
    subgraph plan-parallel["parallel"]
      direction LR
      plan-ctx["context"]
      plan-arch["architecture"]
    end
    plan-design["design"]
  end

  plan-box --> security["security<br/>(sub-agent)"]

  subgraph refine-box["refine (coordinator)"]
    direction TB
    subgraph refine-parallel["parallel"]
      direction LR
      ref-artifacts["artifacts"]
      ref-health["health"]
    end
  end

Tip

Nested sub-agent workflows require VS Code 1.113.0 or later and the chat.subagents.allowInvocationsFromSubagents setting enabled.

Conductor Pattern

The central devsquad agent implements a Mediated Coordinator-Worker pattern (ADR 0001):

• Detects user intent and delegates to the appropriate specialist agent
• Allows coordinator specialists to continue delegation to focused worker sub-agents
• Dual-mode: guided (through conductor) or direct (invoke specialists)
• Resilient: if the conductor fails, specialist agents remain accessible independently
• No domain logic: the conductor routes and relays; specialists own all phase logic

Communication Protocol

Sub-agents operate in two modes via a prefix-based protocol (ADR 0002):

Mode	Trigger	Behavior
Via Conductor	[CONDUCTOR] prefix present	Returns structured actions: [ASK], [CREATE], [EDIT], [BOARD], [CHECKPOINT], [DONE]
Direct	No prefix	Interacts directly with the user

Single codebase handles both modes; the prefix check determines the output format.

Context Management

Phases execute sequentially or across sessions. Context isolation prevents assumption contamination (ADR 0003):

• Disk artifacts are the source of truth (spec.md, plan.md, ADRs, tasks.md)
• Each phase starts with clean context and reads artifacts from disk
• Handoff Envelope explicitly transfers inherited assumptions, pending decisions, and discarded info
• Persistence via git; auditability via versioned artifacts

Component Catalog

Component	Count	Description
Agents	13 visible + internal workers	One conductor, 12 specialist agents, and hidden worker sub-agents for nested execution
Skills	18	Reusable capabilities loaded on demand
Instructions	7	Path-specific behavioral rules
Hooks	5	Lifecycle hooks for deterministic operations
MCP Servers	5	Remote servers for external integrations
Context Management	-	Memory, handoff envelopes, disk persistence
Extensibility	6	Extension mechanisms for customization

Extension Mechanisms

Four mechanisms extend agent capabilities without modifying agent code. Each has a different activation model (ADR 0004):

flowchart TD
  instructions["Path-specific Instructions<br/>(deterministic, by file glob)"]
  skills["Skills<br/>(semantic, by context relevance)"]

  instructions -.->|"auto-injected when<br/>file glob matches"| agents["Specialist Agents"]
  skills -.->|"auto-injected when<br/>context is relevant"| agents

  agents -->|"post-action<br/>validation"| hooks["Hooks<br/>(deterministic, by lifecycle event)"]
  agents -->|"tool calls to<br/>external systems"| mcpservers["MCP Servers<br/>(external system access)"]

Dashed arrows: auto-activated (agent does not explicitly request). Solid arrows: agent-initiated. See Extensibility for the full decision tree.

Usage Scenarios

Iterative

Discover scope incrementally as you specify and plan. The framework’s default posture: each pass through the loop produces a thin slice, and what you learn shapes the next one.

specify > plan > discover B > specify > plan > decompose > implement

Emergent scope

Clear vision, undefined scope. Features emerge during specification while exploring solutions.

envision > kickoff (epic only) > specify (features emerge) > plan > decompose > implement

Kickoff generates only the epic. Specify is used for brainstorming and exploring features incrementally.

Scope-stable

Start with a clear product idea and work through the full lifecycle. Use when the slice boundary is known up front (regulated contexts, migrations, contractually fixed scope).

envision > kickoff > specify > plan > decompose > implement > review

Features are defined during envisioning, then specified, planned, and implemented in sequence.

Architecture-first

Start with technical decisions before feature work.

envision > kickoff > plan > specify > decompose > implement

Architecture decisions (ADRs) are made first, then features are specified to align with them.

Validation-first

Build a PoC first, validate assumptions, then build the MVP.

envision > kickoff > plan > decompose > implement (PoC), then validate, then full cycle (MVP)

Board-first

Map an existing board structure and fill in specs.

kickoff (map existing) > specify > plan > decompose > implement

Known Limitations

Caution

• No automatic impact propagation: When specs or ADRs are updated, dependent artifacts are not automatically refreshed. Use @devsquad.refine to detect inconsistencies.
• Single board assumption: The framework assumes a single GitHub Issues or Azure DevOps board. Cross-platform sync is not supported.

Note

Changes to upstream artifacts (specs, ADRs, priorities) are not automatically propagated to downstream work items. See Team Coordination for the full limitation matrix and recommended manual steps.

See Team Coordination for multi-developer guardrails.

Versioning

The framework uses Semantic Versioning with git tags (vMAJOR.MINOR.PATCH):

Change Type	Version Bump	Example
Bug fixes, no behavior change	PATCH	v0.6.0 to v0.6.1
New backward-compatible features	MINOR	v0.5.0 to v0.6.0
Breaking changes	MAJOR	v0.x to v1.0.0

Coming from a Different Angle?

For Developers Install the plugin and run your first guided workflow.

For Leadership How guardrails keep delivery predictable and traceable.

For Platform Teams Customize with your own instructions, skills, agents, and hooks.