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

1. Flexibility

Users choose between guided mode (through the conductor) or direct mode (invoking specialist agents individually). Both paths produce the same artifacts.

2. Socratic by Design

Ask before assuming. Verify understanding before acting. Explain the why behind recommendations so teams learn the principles, beyond following steps.

3. Artifacts as Source of Truth

Specs, ADRs, and contracts live in files on disk. Session context is ephemeral; the artifacts in the repository are the permanent reference.

4. Programming Language-Agnostic

The framework does not prescribe a tech stack. Users add context via instructions, skills, hooks, and tool extensions.

5. AI Model-Agnostic

Does not prescribe which AI models to use. Organizations choose per their policies and requirements.

6. Human in Control

No medium or high impact decision is executed without explicit approval. The developer decides; the AI accelerates.

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

Feature-first

Start with a clear product idea and work through the full lifecycle.

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

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.

Iterative

Discover scope incrementally as you specify and plan.

specify > plan > discover B > 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.