Building an AI Development Team: How Agents Work Together to Ship Software

Why This Document Exists

Over the past weeks, I've built something that doesn't have a standard name yet: an AI development team. Not a single AI assistant that helps you code, but a coordinated system of specialized AI agents that take a Jira ticket, design the UI, implement the frontend and backend in parallel, review their own code for security issues, run tests, generate reports, and update Jira with the results — all from a single command.

This document explains how it works. Not the marketing version — the actual architecture, the design decisions, the things that worked and the things that didn't. It's written for engineers and technical leads who want to understand what's possible with agent orchestration today, and what the practical constraints are.

The Core Idea: Markdown Files That Become AI Teams

Claude Code has a feature called custom slash commands. You write a Markdown file in .claude/commands/, and it becomes a command you can run in the terminal. The Markdown file is the prompt — it tells Claude what role to play, what steps to follow, what tools to use, and when to spawn sub-agents.

The insight that makes this work: a sufficiently detailed Markdown prompt is an executable specification. If you describe a 5-phase pipeline with decision points, agent handoffs, and file-based communication — Claude will execute it. The Markdown file is simultaneously the documentation and the implementation.

# Example: .claude/commands/jira.md (simplified)

You are the **Jira Ticket Orchestrator**.
Fetch the ticket, analyze it, plan the work,
coordinate implementation agents, and update Jira.

## PHASE 1: Fetch & Analyze
Fetch the ticket via REST API...
Ask the user for project paths...

## PHASE 2: Design (if UI changes)
Launch a UI Designer agent in Paper.design...
Present designs to user for approval...

## PHASE 3: Implementation
Launch Frontend + Backend agents in parallel...

## PHASE 4: Report & Update Jira
Generate HTML report, post to Jira...

That's it. No framework, no SDK, no deployment pipeline. A Markdown file in a folder. When a user types /jira FO-2847, Claude reads the Markdown, and the pipeline begins.

Architecture Overview

The system has three layers:

The Agent Team: Roles and Responsibilities

Each agent is a Claude instance with a specialized prompt. When the orchestrator spawns an agent, it passes the full context that agent needs: the ticket details, the stack profile, the file paths, and the specific task. Agents don't know about each other — they each do their job and write their output to a report file.

The Orchestrator You

The orchestrator isn't a separate agent — it's the main Claude instance running the command. It's the only one that can interact with the user. It reads the command Markdown, executes the phases, spawns sub-agents, and presents results for user approval.

Responsibilities:

• Fetch and parse Jira tickets
• Detect project stack and ask user for paths
• Classify work scope (UI / Backend / Full-stack)
• Present plans and designs for user approval
• Spawn and coordinate all other agents
• Post results back to Jira

UI Designer Design Agent

Creates visual mockups in Paper.design using MCP tools. Reads the feature plan, existing code patterns, and any screenshots of the current app. Produces artboards with HTML/CSS designs and writes a design specification.

Tools used: mcp__paper__create_artboard, mcp__paper__write_html, mcp__paper__get_screenshot, mcp__paper__get_jsx

Output: Paper artboards + reports/feature-ui-plan.md

Key constraint: The user MUST review and approve designs before implementation begins. This is a hard gate — no code is written until designs are approved.

Frontend Developer Implementation Agent

Implements UI changes based on the approved design spec and feature plan. Creates components, pages, routes, hooks. Updates navigation. Follows the existing project's patterns and the API contract exactly.

Input: Feature plan + UI design spec + existing codebase patterns

Output: reports/feature-ui-implementation.md

Runs in parallel with: Backend Developer (when scope is full-stack)

Backend Developer Implementation Agent

Implements API endpoints, database schema changes, middleware. Uses parameterized SQL, proper auth, input validation. Follows the API contract from the feature plan exactly.

Input: Feature plan + existing codebase patterns

Output: reports/feature-backend-implementation.md

Also used for: Fixing issues found by Security Auditor and Quality Engineer in the dev-team loop

Security Auditor Review Agent

Scans every source file for OWASP Top 10 vulnerabilities: injection, broken auth, data exposure, XSS, access control, misconfiguration. Categorizes findings as CRITICAL, WARNING, or INFO.

Output: reports/security-audit.md

Runs in parallel with: Code Quality Engineer

Code Quality Engineer Review Agent

Scans for code smells, bugs, anti-patterns: type safety issues, error handling gaps, performance problems, dead code, API design issues. Same severity categorization.

Output: reports/quality-audit.md

Test Engineer Testing Agent

Writes unit tests for every fix. Covers edge cases and security regression scenarios. Runs all tests (existing + new) and iterates until 100% pass. Supports 9 stacks: Java/JUnit, C#/xUnit, JS/Jest, Python/pytest, Go, Rust, PHP, Ruby.

Output: reports/test-report.md or reports/unit-test-report.html

Code Analyst Review Agent

Reviews ONLY the git diff — not the entire codebase. Checks new code for SQL injection, XSS, command injection, hardcoded secrets, null refs, race conditions, missing auth. Auto-fixes critical issues.

Output: reports/code-analysis.md

Key distinction from Security Auditor: The Security Auditor scans the whole codebase. The Code Analyst reviews only what changed. One is for audits, the other is for pull request-style review.

Documentation Lead Report Agent

Compiles all agent reports into a single, polished HTML report. Dark theme, collapsible sections, severity badges, code snippets, testing checklists. The report is the artifact that gets attached to the Jira ticket.

Input: All reports/*.md files from other agents

Output: reports/master-report.html or reports/feature-report.html or reports/jira-{KEY}-report.html

How Agents Communicate

Agents don't talk to each other directly. They communicate through three mechanisms:

1. Report Files (Primary)

Every agent writes its output to a file in reports/. The orchestrator reads these files and passes relevant content to downstream agents. For example:

1. Security Auditor writes findings to reports/security-audit.md
2. Quality Engineer writes findings to reports/quality-audit.md
3. Orchestrator spawns Backend Developer, telling it: "Read the findings from both reports and fix everything"
4. Backend Developer writes what it changed to reports/fixes-applied.md
5. Orchestrator spawns Test Engineer, telling it: "Read the fixes and write tests for each one"

This is effectively a message-passing system where the messages are Markdown files. It's simple, inspectable (you can read the files), and robust (files don't disappear if an agent crashes).

2. Prompt Injection (Secondary)

When the orchestrator spawns an agent, it includes all necessary context directly in the prompt. The agent receives: the Jira ticket details, the stack profile, the file paths, the design spec, and whatever else it needs. This is redundant with the file system, but it ensures the agent has everything without needing to read files first.

3. Tool Calls (External Systems)

Agents interact with external systems via tool calls: Jira REST API (via curl), Paper MCP tools, JAM MCP tools, Docker CLI, Git commands, Playwright. The orchestrator handles Jira authentication centrally (credentials are in .env), and agents inherit this through sourcing the same file.

User: /jira FO-2847
  │
  ▼
Orchestrator ──── curl ────▶ Jira REST API (fetch ticket)
  │                           │
  │ ◄── ticket JSON ──────────┘
  │
  ├── Detect JAM links? ──── mcp ────▶ JAM MCP (video analysis)
  │
  ├── Ask user for project paths (AskUserQuestion)
  │
  ├── UI changes? ──── spawn ────▶ UI Designer Agent ──── mcp ────▶ Paper MCP
  │                                   │
  │ ◄── reports/feature-ui-plan.md ───┘
  │
  ├── User approves designs? (AskUserQuestion)
  │
  ├── spawn (parallel) ──────▶ Frontend Dev Agent ──▶ reports/feature-ui-implementation.md
  │                    └─────▶ Backend Dev Agent  ──▶ reports/feature-backend-implementation.md
  │
  ├── spawn ──────────────────▶ Code Analyst ──▶ reports/code-analysis.md
  │
  ├── spawn ──────────────────▶ Doc Lead ──▶ reports/jira-FO-2847-report.html
  │
  ├── curl ────▶ Jira (upload report + screenshots + comment)
  │
  └── curl ────▶ Jira (transition status + log time)
  

The Command System: 28 Slash Commands

Each command is a Markdown file in .claude/commands/. Some are standalone (single agent, single task), others are orchestrators that spawn multiple agents across phases. Here's the full inventory:

Jira Pipeline Project Management

Feature Development Pipeline Design + Implementation

Development Team Loop Iterative Quality

Testing & Dependencies Quality Assurance

Dependency Health Security & Maintenance

Docker Pipeline DevOps

Universal Commands Any Project

Git Operations Git

Repository Onboarding Onboarding

External Integrations

Key Design Decisions (and Why)

1. File-based communication, not memory

Decision: Agents communicate through reports/*.md files, not through shared memory or context.

Why: Sub-agents in Claude Code start with a fresh context. They have no memory of the parent or other agents. Files are the natural handoff mechanism — they're persistent, inspectable, and don't depend on context window management. An agent that writes to reports/security-audit.md produces an artifact that any other agent (or human) can read.

2. Always ask the user for project paths

Decision: The pipeline never auto-detects which codebase to work in. It always asks.

Why: The AI incorrectly assumed a ticket belonged to gateway-backend when it was actually control-backend-api. In a multi-project environment, the cost of working in the wrong codebase is catastrophic — you're modifying the wrong code. Asking takes 5 seconds. Fixing a wrong-codebase mistake takes much longer.

3. User approval gates before implementation

Decision: Two mandatory approval points: (1) the feature plan, and (2) the UI design. No code is written until both are approved.

Why: Agent work is cheap to redo at the planning stage but expensive at the implementation stage. A wrong plan means multiple agents building the wrong thing. Catching misunderstandings at the plan/design stage saves massive amounts of token spend and time.

4. Parallel agents where possible, sequential where necessary

Decision: Security + Quality scans run in parallel. Frontend + Backend implementation run in parallel. But design must complete before implementation, and implementation must complete before code review.

Why: True parallelism saves time (two agents working simultaneously is faster than two agents working sequentially). But dependencies must be respected: you can't implement a UI that hasn't been designed, and you can't review code that hasn't been written.

5. Stack-agnostic commands with runtime detection

Decision: Commands like /unit-test and /deps detect the project's tech stack at runtime and adapt their behavior. The same command works for Java/Maven, C#/.NET, JavaScript/npm, Python/pip, Go, Rust, PHP, and Ruby.

Why: We work across multiple stacks (Java backend, React frontend, .NET APIs). Having separate commands per stack would be unmaintainable. Runtime detection lets one command serve all projects.

6. Mandatory reports for every pipeline

Decision: Every pipeline generates an HTML report, regardless of whether the user asked for one.

Why: Reports serve three purposes: (1) they're the artifact that gets uploaded to Jira, (2) they're the communication mechanism between agents, and (3) they're the audit trail. If something goes wrong, the report tells you what each agent did and found.

Patterns That Work Well

The Iterative Loop Pattern

Used in /dev-team and /unit-test. Scan, fix, verify, re-scan. Continue until zero findings. This is the most reliable pattern because it's self-correcting: if a fix introduces a new issue, the next scan catches it.

The Scope-Based Branching Pattern

Used in /jira and /new-feature. Classify the work as UI-only, backend-only, or full-stack, then branch the pipeline accordingly. UI-only skips backend agents. Backend-only skips design and frontend. Full-stack runs everything.

The Parallel-Then-Merge Pattern

Launch two or more agents simultaneously, wait for all to complete, then merge their outputs into the next step. Used for Security + Quality scanning, and for Frontend + Backend implementation.

The User Gate Pattern

Present results to the user with explicit options (Accept / Change / Reject). Block pipeline progression until the user responds. Used for plan approval, design review, and Jira update decisions.

The Project Name Resolution Pattern

Commands accept either a full path or a project name (e.g., control-backend-api). The system resolves names to paths based on known project directories. If resolution fails, it asks the user. This makes commands feel like CLI tools — short, memorable invocations.

Patterns That Don't Work

Letting agents guess project paths

This caused the AI to work in the wrong codebase. Never again. Always ask.

One giant agent that does everything

A single agent trying to scan, fix, test, and report in one go produces worse results than specialized agents. The context window gets polluted with too many concerns, and the agent loses focus. Specialization works.

Skipping the design phase "because it's a small change"

Even a one-line color change benefits from a Paper mockup. The user seeing the change before it's implemented catches misunderstandings that are trivial to fix at design time and expensive to fix after implementation.

Running all tests in one shot without iterating

Newly created tests frequently fail on the first run due to mock misconfiguration, wrong assertions, or compilation errors. The fix loop (run, analyze failures, fix, re-run, up to 5 iterations) is essential. Without it, you'd hand the user a pile of broken tests.

Token Efficiency: What Actually Matters

Agent orchestration is expensive in tokens. Every agent spawn is a fresh context. Every tool call costs tokens. Every report file that gets read costs tokens. Here's what we've learned about managing costs:

Lessons Learned

1. The prompt IS the product

In a traditional software project, you write code and the code runs. In this system, you write prompts and the prompts run. The quality of the output is directly proportional to the quality of the prompt. A vague prompt produces vague results. A prompt that specifies exact file paths, exact output formats, and exact decision criteria produces reliable, reproducible results. We treat our .claude/commands/ Markdown files with the same rigor as production code.

2. Agents need more structure than humans

A human developer can be told "fix the bug" and figure out the rest. An agent needs: which project directory, what language, what test framework, what files to read first, what patterns to follow, where to write the output, and what to do when it encounters an edge case. The more structure you provide, the better the output.

3. File-based communication is surprisingly robust

We initially worried about agents writing to the wrong files, overwriting each other's output, or producing incompatible formats. In practice, this almost never happens. Agents are good at following naming conventions when you tell them explicitly what to write and where.

4. User gates save more time than they cost

Every user approval point adds 30-60 seconds of human time. But each gate prevents 5-15 minutes of wasted agent work when the plan or design is wrong. The math is clear: always gate before expensive operations.

5. The iterative loop is the most powerful pattern

Single-pass pipelines (scan once, fix once, done) miss things. The loop pattern (scan, fix, re-scan, repeat until clean) catches issues introduced by fixes, previously masked issues, and interaction effects between changes. It consistently produces cleaner output than single-pass.

6. JAM MCP integration changed bug analysis

Before JAM integration, bug tickets had text descriptions and maybe a screenshot. With JAM MCP, the agent can analyze the actual video recording: see what the user clicked, read the console errors, check the network requests. It turns a vague bug report into a structured, actionable analysis. The auto-detection of JAM links in Jira tickets means this happens automatically — no extra steps.

What's Next

Full Command Reference