Software delivery has always been a relay race. A product owner writes requirements. A developer interprets them, sometimes correctly, sometimes not. Code gets written. Tests get written separately. A reviewer reads both and sends feedback. The developer fixes, the reviewer re-reads, and the cycle repeats until everyone agrees (or gives up).
I started wondering: what if instead of one AI assistant generating code snippets, you had an entire squad of specialized AI agents. Each owning a single stage of the delivery pipeline, they could collaborate, self-correct, and produce a complete, traceable output from a plain-text requirement?
That's Engineering Squad: an open-source, multi-agent framework built with LangGraph, Azure OpenAI, and Foundry Local. Nine agents. One pipeline. Zero manual handoffs.
You give it a requirement. It gives you back:
- User stories with acceptance criteria
- Technical design (API contracts, data models, architecture)
- Full implementation code (written into real files, not markdown)
- Unit tests and Playwright E2E tests
- Automated code review with a self-correcting feedback loop
When the Code Reviewer finds a bug, it doesn't just flag it, it routes the work back to the exact agent that needs to fix it.
When the Spec Agent hits ambiguity, it stops and asks you rather than guessing. The loop runs up to 5 iterations, and every run is versioned under a unique Run ID for full traceability.
It runs on Azure OpenAI for heavy reasoning, Foundry Local for lightweight tasks or entirely offline with --local-only mode. No cloud required.
How It Works
The squad is a directed graph of 9 specialized agents. Each agent has a single responsibility and a tuned system prompt. The orchestration is handled by LangGraph's StateGraph, which routes work through the pipeline and handles feedback loops.
The Agents
| Agent | Model | Responsibility |
|---|---|---|
| Product Owner | Azure OpenAI gpt-4.1 | Reads requirements, classifies impact scope |
| Story Agent | Foundry Local (qwen2.5-7b) | Converts requirements → structured user stories |
| Spec Agent | Azure OpenAI o3 | Resolves ambiguity — asks the user interactively |
| Technical Design | Azure OpenAI gpt-4.1 | Architecture, API contracts, data models, error handling |
| Developer | Azure OpenAI gpt-4.1 | Writes code directly into the codebase |
| Unit Tester | Azure OpenAI gpt-4.1 | Writes unit tests and evaluates them against implementation |
| Test Writer | Foundry Local (qwen2.5-7b) | Writes Playwright E2E tests using Page Object Model |
| Tester | Azure OpenAI o3 | Final evaluation of code against all specs and tests |
| Code Reviewer | Azure OpenAI o3 | Reviews everything, decides: approve or route back |
The Self-Correcting Loop
This is where it gets interesting. The Code Reviewer doesn't just say "approved" or "rejected" — it makes a routing decision using structured output:
class ReviewDecision(BaseModel):
decision: Literal[
"approved", # Ship it
"requirement_confusion", # → Spec Agent (clarify ambiguity)
"clarity_missing", # → Technical Design (refine design)
"code_missing", # → Developer (fix implementation)
"bug_found", # → Developer (fix bugs)
"test_case_missing", # → Test Writer (add coverage)
]
feedback: str # Actionable feedback for the target agent
LangGraph's conditional edges route the workflow back to the exact agent that needs to act. The loop runs up to 5 iterations with a hard stop to prevent infinite cycles.
workflow.add_conditional_edges(
"code_reviewer",
route_review,
{
END: END,
"spec_agent": "spec_agent",
"technical_design": "technical_design",
"developer": "developer",
"test_writer": "test_writer",
},
)
Key Design Decisions
1. Impact Classification — Don't Run What You Don't Need
Not every change needs the full pipeline. The squad classifies scope first:
| Scope | What Runs |
|---|---|
| config | Impact Analysis → Developer → Unit Tester → Reviewer |
| bugfix | Impact Analysis → Developer → Unit Tester → Tester → Reviewer |
| enhancement | Stories → Design (if needed) → Developer → All Tests → Reviewer |
| feature | Stories → Design → Developer → All Tests → Reviewer |
| refactor | Impact Analysis → Developer → Unit Tester → Reviewer |
A config change doesn't need user stories. A bugfix doesn't need a full architectural design. This keeps runs fast and focused.
2. Code Goes Into Real Files, Not Markdown
This was a deliberate choice. The Developer Agent edits actual source files in your project — it doesn't dump code into a markdown artifact. The code_changes.md artifact is a change log that records what was modified and why, for traceability.
3. Existing Projects vs. Greenfield
Set PROJECT_TYPE: existing in requirements_input.txt, point it at your repos, and the squad will:
- Scan your codebase for patterns, conventions, and architecture
- Make targeted changes only — no rewriting from scratch
- Preserve your existing coding style, error handling, and naming conventions
4. Two LLM Tiers — Cloud + Local
The framework uses a hybrid model strategy:
- Azure OpenAI (gpt-4.1, o3) for complex reasoning: code generation, technical design, code review
- Foundry Local (qwen2.5-7b, phi-3.5-mini) for lightweight tasks: user stories, test writing
This keeps costs down while maintaining quality where it matters. And with --local-only mode, you can run the entire squad on Foundry Local with zero cloud dependencies.
Running It Locally with Foundry Local
One of my favorite features: the entire squad can run 100% locally using Foundry Local. No Azure subscription, no API keys, no internet required.
Setup
# Install Foundry Local CLI (one-time)
winget install Microsoft.FoundryLocal
# Install Python dependencies
pip install foundry-local-sdk openai langchain-openai langgraph python-dotenv
# Run in local-only mode
python main.py --local-only
When --local-only is set, every agent that would normally call Azure OpenAI gets redirected to Foundry Local:
def get_azure_llm(deployment: str, temperature: float = 0.1):
# Local-only mode: redirect to Foundry Local
if os.getenv("SQUAD_LOCAL_ONLY", "").lower() in ("true", "1", "yes"):
from models.local_llm import get_local_llm
return get_local_llm(temperature=temperature)
# Otherwise: use Azure OpenAI with DefaultAzureCredential
...
The foundry-local-sdk (v1.1.0+) handles everything — initializing the runtime, downloading models, and loading them:
from foundry_local_sdk import FoundryLocalManager, Configuration
# Initialize once (singleton)
config = Configuration(app_name="my-app")
manager = FoundryLocalManager(config)
# Start OpenAI-compatible web service
manager.start_web_service()
print(manager.urls[0]) # SDK auto-discovers the endpoint
# Download & load a model
model = manager.catalog.get_model("qwen2.5-7b")
model.download()
model.load()
# Chat directly — no web service needed
chat = model.get_chat_client()
response = chat.complete_chat([{"role": "user", "content": "Hello!"}])
Jupyter Notebook
The repo includes a Jupyter notebook (foundry_local.ipynb) that walks you through:
- Installing Foundry Local
- Loading a model
- Sending chat completions (streaming and non-streaming)
- Running the full Engineering Squad in local-only mode
Traceability — Every Run Is Versioned
Every squad execution gets a unique Run ID and produces a structured artifact set:
output/
runs/
20260524_a3f9b1/
run_metadata.json ← run ID, timestamp, requirement hash, decision
impact_classification.md
user_stories.md
technical_design.md
code_changes.md ← change log (code is in real files)
unit_test_results.md
tests.md
test_results.md
review_feedback.md
latest/ ← symlink to most recent approved run
The run_metadata.json is structured for future Azure DevOps integration — auto-creating work items, tasks, and test cases from squad output.
Two Ways to Run
| Mode | Best For |
|---|---|
| GitHub Copilot Agent Mode | Existing codebases — Copilot has full workspace context via #codebase |
| Python CLI (python main.py) | New projects, CI pipelines, fully automated runs |
Running with GitHub Copilot Agent Mode
This is the recommended way to run the squad on existing projects. Copilot has full access to your workspace — it can read files, write code, and run terminal commands — so it naturally understands your architecture, patterns, and conventions.
Prerequisites
- VS Code with the GitHub Copilot and GitHub Copilot Chat extensions installed
- A Copilot subscription that supports Agent Mode (Copilot Pro, Business, or Enterprise)
Setup
- Clone the repo and open it in VS Code:
git clone https://github.com/prasunagga/engineeringSquad.git code engineeringSquad - Switch to Agent Mode — In the Copilot Chat panel, click the mode dropdown (top of the chat input) and select "Agent". This is required — Ask and Edit modes don't have tool access.
- Enable tools — Click the 🔧 tools icon (or gear/settings icon) at the bottom of the chat input area. Make sure the following tools are enabled:
- File operations (read, create, edit files)
- Terminal (run commands)
- Code search / workspace context
- Edit your requirement — Open requirements_input.txt and write your requirement:
PROJECT_TYPE: existing FRONTEND_PATH: plant-catalog BACKEND_PATH: Build a cart page where users can add plants, adjust quantities, and see totals.
Running the Squad
In Copilot Chat (Agent Mode), type:
/run-squad
This triggers the .github/prompts/run-squad.prompt.md file — a prompt file with mode: agent in its YAML frontmatter that orchestrates the full workflow:
---
mode: agent
description: Run the full Engineering Squad workflow
tools:
- read_file
- create_file
- replace_in_file
- insert_text
- delete_file_range
---
Copilot will then execute the full pipeline: read requirements → classify impact → generate stories → design → write code → write tests → run tests → code review → approve or loop back.
How It Differs from Python CLI
| Copilot Agent Mode | Python CLI | |
|---|---|---|
| Context | Full workspace awareness via #codebase | Reads files from paths in requirements_input.txt |
| Human-in-loop | Spec Agent asks you directly in chat | Spec Agent prints questions to stdout |
| Code editing | Uses VS Code's file editing tools | Writes files via Python open() |
| Test execution | Runs npm test / playwright test in VS Code terminal | Runs via subprocess |
| Model | Uses whichever model is selected in Copilot | Uses Azure OpenAI / Foundry Local |
Individual Agent Prompts
The .github/prompts/ directory also contains standalone prompt files for running individual agents:
| Prompt | Purpose |
|---|---|
| run-squad.prompt.md | Full orchestrated pipeline |
| developer.prompt.md | Developer agent only |
| code-reviewer.prompt.md | Code review only |
| story-agent.prompt.md | Generate user stories only |
| technical-design.prompt.md | Technical design only |
| test-writer.prompt.md | Write E2E tests only |
Extending the Framework
The squad is designed to be modular. Here are the most common extension points:
Add a New Agent
Every agent follows the same pattern — a function that takes SquadState, calls an LLM, and returns updated fields:
# agents/my_agent.py
from langchain_core.prompts import ChatPromptTemplate
from graph.state import SquadState
from models.azure_llm import get_azure_llm, DEPLOYMENT_DEVELOPER
PROMPT = ChatPromptTemplate.from_messages([
("system", "You are a security review specialist."),
("human", "Review this code for vulnerabilities:\n{code}"),
])
def my_agent_node(state: SquadState) -> dict:
llm = get_azure_llm(deployment=DEPLOYMENT_DEVELOPER)
result = (PROMPT | llm).invoke({"code": state["code"]})
return {"security_review": result.content}
Then wire it in:
- Add state fields in graph/state.py
- Register the node and edges in graph/workflow.py
- Add artifact output in main.py
Swap the LLM for Any Agent
Each agent calls get_azure_llm(deployment=...) or get_local_llm(). You can:
- Change the model — edit .env (e.g., AZURE_DEPLOYMENT_DEVELOPER=gpt-5.4)
- Go fully local — python main.py --local-only
- Use a different provider — replace get_azure_llm() with any LangChain-compatible LLM (Anthropic, Ollama, Groq, etc.)
Customize Agent Prompts
Each agent's system prompt is defined as a ChatPromptTemplate at the top of its file in agents/. Edit the prompt directly — no configuration layer to navigate.
Change the Review Loop
The routing logic lives in graph/workflow.py → route_review(). Add new decision strings, change the routing map, or adjust MAX_ITERATIONS (default: 5).
VS Code Copilot Agent Mode
The .github/prompts/ directory contains prompt files for running individual agents in VS Code Copilot Agent Mode. Edit these to customize agent behavior when running through Copilot.
What I Learned Building This
- Structured output is essential for routing. Without Pydantic models for review decisions, the conditional edge routing would be fragile and string-matching-dependent.
- Impact classification saves significant time. Running 9 agents for a one-line config change is wasteful. Classifying scope first makes the system practical.
- The self-correcting loop works — but needs a hard stop. Left unchecked, agents can ping-pong feedback indefinitely. The 5-iteration cap is a pragmatic safety net.
- Hybrid local + cloud models are the right balance. Not every task needs GPT-4.1. User story generation and test writing work well on smaller local models, cutting costs without sacrificing quality.
- "Ask, don't guess" is the single most important principle. When the Spec Agent encounters ambiguous requirements, it stops and asks the user rather than hallucinating assumptions. This one rule prevents the most costly category of errors.
Try It Yourself
The framework is open source and designed to be extensible:
git clone https://github.com/prasunagga/engineeringSquad.git
cd engineeringSquad
pip install -r requirements.txt
# Edit your requirement
notepad requirements_input.txt
# Run (local-only, no Azure needed)
python main.py --local-only
Requirements:
- Python 3.10+
- Windows, macOS, or Linux
- For local-only: Foundry Local (winget install Microsoft.FoundryLocal)
- For cloud mode: Azure OpenAI endpoint + az login
What's Next
- Azure DevOps MCP integration — Auto-sync stories, tasks, and test cases to ADO boards
- CI/CD trigger — Auto-run the squad on PR creation or work item assignment
- Multi-repo support — Frontend, backend, and infra in separate repositories
- Cost estimation — Estimate effort and cloud costs from the technical design
Links
- GitHub: github.com/prasunagga/engineeringSquad
- Foundry Local docs: learn.microsoft.com/en-us/azure/foundry-local/what-is-foundry-local
- LangGraph docs: langchain.com/langgraph
- Azure OpenAI docs: azure.microsoft.com/en-us/products/ai-foundry/models/openai