147 Workflow 9cb3bc5b

# Agent and Skill Workflow

> [Current Version](../VERSION.md) | The 7-step infrastructure development workflow

## Overview

Agentic InfraOps uses a multi-agent orchestration system where specialized AI agents coordinate
through artifact handoffs to transform Azure infrastructure requirements into deployed Bicep code.

The **InfraOps Conductor** (🎼 Maestro) orchestrates the complete workflow, delegating to
specialized agents at each phase while enforcing mandatory approval gates.

## Agent Architecture

### The Conductor Pattern

```mermaid
%%{init: {'theme':'neutral'}}%%
graph TB
    subgraph "Orchestrator"
        COND["InfraOps Conductor<br/>🎼 Maestro"]
    end

    subgraph "Step 1: Requirements"
        REQ["requirements<br/>📜 Scribe"]
    end

    subgraph "Step 2: Architecture"
        ARCH["architect<br/>🏛️ Oracle"]
        MCP["💰 Azure Pricing MCP"]
    end

    subgraph "Step 3: Design Artifacts"
        DIAG["azure-diagrams<br/>🎨 Skill"]
        ADR["azure-adr<br/>📝 Skill"]
    end

    subgraph "Step 4: Planning"
        PLAN["bicep-plan<br/>📐 Strategist"]
    end

    subgraph "Step 5: Implementation"
        CODE["bicep-code<br/>⚒️ Forge"]
        LINT["lint-subagent"]
        WHATIF["whatif-subagent"]
        REVIEW["review-subagent"]
    end

    subgraph "Step 6: Deployment"
        DEP["deploy<br/>🚀 Envoy"]
    end

    subgraph "Step 7: Documentation"
        DOCS["azure-artifacts<br/>📚 Skill"]
    end

    COND -->|"delegates"| REQ
    COND -->|"delegates"| ARCH
    COND -->|"invokes"| DIAG
    COND -->|"invokes"| ADR
    COND -->|"delegates"| PLAN
    COND -->|"delegates"| CODE
    CODE -->|"validates"| LINT
    CODE -->|"validates"| WHATIF
    CODE -->|"validates"| REVIEW
    COND -->|"delegates"| DEP
    COND -->|"invokes"| DOCS

    MCP -.->|"pricing data"| ARCH

    style COND fill:#8957E5,color:#fff
    style REQ fill:#e1f5fe
    style ARCH fill:#fff3e0
    style MCP fill:#fff9c4
    style DIAG fill:#f3e5f5
    style ADR fill:#e8eaf6
    style PLAN fill:#e8f5e9
    style CODE fill:#fce4ec
    style DEP fill:#c8e6c9
    style DOCS fill:#e3f2fd
```

---

## Agent Roster

### Primary Orchestrator

| Agent                  | Persona    | Role                                    | Model           |
| ---------------------- | ---------- | --------------------------------------- | --------------- |
| **InfraOps Conductor** | 🎼 Maestro | Master orchestrator for 7-step workflow | Claude Opus 4.6 |

### Core Agents (7 Steps)

| Step | Agent          | Persona       | Role                                 | Artifact                                             |
| ---- | -------------- | ------------- | ------------------------------------ | ---------------------------------------------------- |
| 1    | `requirements` | 📜 Scribe     | Captures infrastructure requirements | `01-requirements.md`                                 |
| 2    | `architect`    | 🏛️ Oracle     | WAF assessment and design decisions  | `02-architecture-assessment.md`                      |
| 3    | `design`       | 🎨 Artisan    | Diagrams and ADRs                    | `03-des-*.md/.py/.png`                               |
| 4    | `bicep-plan`   | 📐 Strategist | Implementation planning              | `04-implementation-plan.md` + `04-*-diagram.py/.png` |
| 5    | `bicep-code`   | ⚒️ Forge      | Bicep template generation            | `infra/bicep/{project}/`                             |
| 6    | `deploy`       | 🚀 Envoy      | Azure deployment                     | `06-deployment-summary.md`                           |
| 7    | —              | —             | Documentation (via skills)           | `07-*.md`                                            |

### Validation Subagents

| Subagent                | Purpose                                         | Invoked By             |
| ----------------------- | ----------------------------------------------- | ---------------------- |
| `bicep-lint-subagent`   | Syntax validation (`bicep lint`, `bicep build`) | `bicep-code`           |
| `bicep-whatif-subagent` | Deployment preview (`az deployment what-if`)    | `bicep-code`, `deploy` |
| `bicep-review-subagent` | Code review (AVM, security, naming)             | `bicep-code`           |

### Diagnostic Agent

| Agent      | Persona     | Role                                           |
| ---------- | ----------- | ---------------------------------------------- |
| `diagnose` | 🔍 Sentinel | Resource health assessment and troubleshooting |

---

## Approval Gates

The Conductor enforces mandatory pause points for human oversight:

| Gate       | After Step            | User Action                         |
| ---------- | --------------------- | ----------------------------------- |
| **Gate 1** | Requirements (Step 1) | Confirm requirements complete       |
| **Gate 2** | Architecture (Step 2) | Approve WAF assessment              |
| **Gate 3** | Planning (Step 4)     | Approve implementation plan         |
| **Gate 4** | Pre-Deploy (Step 5)   | Approve lint/what-if/review results |
| **Gate 5** | Post-Deploy (Step 6)  | Verify deployment                   |

---

## Workflow Steps

### Step 1: Requirements (📜 Scribe)

**Agent**: `requirements`

Gather infrastructure requirements through interactive conversation.

```text
Invoke: Ctrl+Shift+A → requirements
Output: agent-output/{project}/01-requirements.md
```

**Captures**:

- Functional requirements (what the system does)
- Non-functional requirements (performance, availability, security)
- Compliance requirements (regulatory, organizational)
- Budget constraints

**Handoff**: Passes context to `architect` agent.

---

### Step 2: Architecture (🏛️ Oracle)

**Agent**: `architect`

Evaluate requirements against Azure Well-Architected Framework pillars.

```text
Invoke: Ctrl+Shift+A → architect
Output: agent-output/{project}/02-architecture-assessment.md
```

**Features**:

- WAF pillar scoring (Reliability, Security, Cost, Operations, Performance)
- SKU recommendations with real-time pricing (via Azure Pricing MCP)
- Architecture decisions with rationale
- Risk identification and mitigation

**Handoff**: Suggests `azure-diagrams` skill or `bicep-plan` agent.

---

### Step 3: Design Artifacts (🎨 Artisan | Optional)

**Skills**: `azure-diagrams`, `azure-adr`

Create visual and textual design documentation.

```text
Trigger: "Create an architecture diagram for {project}"
Output: agent-output/{project}/03-des-diagram.py, 03-des-adr-*.md
```

**Diagram types**: Azure architecture, business flows, ERD, timelines

**ADR content**: Decision, context, alternatives, consequences

---

### Step 4: Planning (📐 Strategist)

**Agent**: `bicep-plan`

Create detailed implementation plan with governance discovery.

```text
Invoke: Ctrl+Shift+A → bicep-plan
Output: agent-output/{project}/04-implementation-plan.md, 04-governance-constraints.md
```

**Features**:

- Azure Policy compliance discovery
- AVM module selection
- Resource dependency mapping
- Auto-generated Step 4 diagrams (`04-dependency-diagram.py/.png` and `04-runtime-diagram.py/.png`)
- Naming convention validation
- Phased implementation approach

**Gate 1**: User approves the implementation plan before proceeding.

---

### Step 5: Implementation (⚒️ Forge)

**Agent**: `bicep-code`

Generate Bicep templates following Azure Verified Modules standards.

```text
Invoke: Ctrl+Shift+A → bicep-code
Output: infra/bicep/{project}/main.bicep, modules/
Output: agent-output/{project}/05-implementation-reference.md
```

**Standards**:

- AVM-first approach (Azure Verified Modules from public registry)
- Unique suffix for global resource names
- Required tags on all resources
- Security defaults (TLS 1.2, HTTPS-only, managed identity)

**Preflight Validation** (via subagents):

| Subagent                | Validation                    |
| ----------------------- | ----------------------------- |
| `bicep-lint-subagent`   | Syntax check, linting rules   |
| `bicep-whatif-subagent` | Deployment what-if preview    |
| `bicep-review-subagent` | AVM compliance, security scan |

**Gate 2**: User approves preflight validation results.

---

### Step 6: Deployment (🚀 Envoy)

**Agent**: `deploy`

Execute Azure deployment with preflight validation.

```text
Invoke: Ctrl+Shift+A → deploy
Output: agent-output/{project}/06-deployment-summary.md
```

**Features**:

- Bicep build validation
- What-if analysis before deploy
- Deployment execution with progress tracking
- Post-deployment resource verification

**Gate 3**: User verifies deployed resources.

---

### Step 7: Documentation (📚 Skills)

**Skill**: `azure-artifacts`

Generate comprehensive workload documentation.

```text
Trigger: "Generate documentation for {project}"
Output: agent-output/{project}/07-*.md
```

**Document Suite**:

| File                        | Purpose                        |
| --------------------------- | ------------------------------ |
| `07-documentation-index.md` | Master index with links        |
| `07-design-document.md`     | Technical design documentation |
| `07-operations-runbook.md`  | Day-2 operational procedures   |
| `07-resource-inventory.md`  | Complete resource listing      |
| `07-ab-cost-estimate.md`    | As-built cost analysis         |
| `07-compliance-matrix.md`   | Security control mapping       |
| `07-backup-dr-plan.md`      | Disaster recovery procedures   |

---

## Agents vs Skills

| Aspect          | Agents                                   | Skills                   |
| --------------- | ---------------------------------------- | ------------------------ |
| **Invocation**  | Manual (`Ctrl+Shift+A`) or via Conductor | Automatic or explicit    |
| **Interaction** | Conversational with handoffs             | Task-focused             |
| **State**       | Session context                          | Stateless                |
| **Output**      | Multiple artifacts                       | Specific outputs         |
| **When to use** | Core workflow steps                      | Specialized capabilities |

---

## Quick Reference

### Using the Conductor (Recommended)

```text
1. Ctrl+Shift+I → Select "InfraOps Conductor"
2. Describe your infrastructure project
3. Follow guided workflow through all 7 steps with approval gates
```

### Direct Agent Invocation

```text
1. Ctrl+Shift+A → Select specific agent
2. Provide context for that step
3. Agent produces artifacts and suggests next step
```

### Skill Invocation

**Automatic**: Skills activate based on prompt keywords:

```text
"Create an architecture diagram" → azure-diagrams skill
"Document the decision to use AKS" → azure-adr skill
```

**Explicit**: Reference the skill by name:

```text
"Use the azure-artifacts skill to generate documentation"
```

---

## Artifact Naming Convention

| Step           | Prefix    | Example                                                     |
| -------------- | --------- | ----------------------------------------------------------- |
| Requirements   | `01-`     | `01-requirements.md`                                        |
| Architecture   | `02-`     | `02-architecture-assessment.md`                             |
| Design         | `03-des-` | `03-des-diagram.py`, `03-des-adr-0001-*.md`                 |
| Planning       | `04-`     | `04-implementation-plan.md`, `04-governance-constraints.md` |
| Implementation | `05-`     | `05-implementation-reference.md`                            |
| Deployment     | `06-`     | `06-deployment-summary.md`                                  |
| As-Built       | `07-`     | `07-design-document.md`, `07-ab-diagram.py`                 |
| Diagnostics    | `08-`     | `08-resource-health-report.md`                              |

---

## Next Steps

- [Prompt Guide](prompt-guide/) — ready-to-use prompts for every agent and skill
- [Quickstart](quickstart.md) — 10-minute getting started walkthrough