Repo Architecture Reference

Repo Architecture Reference

For use by the docs-writer skill. Last verified: 2026-02-26.

Workspace Root Structure

azure-agentic-infraops/
├── .github/
││   ├── agents/              # 13 agent definitions + 9 subagents
││   │   └── _subagents/      # Validation subagents (lint, what-if, review)
││   ├── skills/              # 14 skill definitions (incl. docs-writer)
││   │   └── azure-artifacts/templates/ # 16 artifact templates
││   ├── instructions/        # 25 file-type instruction files
├── agent-output/{project}/  # Agent-generated artifacts (01-07)
├── docs/                    # User-facing documentation
│   ├── exec-plans/          # Execution plans and tech debt tracker
│   ├── prompt-guide/        # Agent & skill prompt examples
│   ├── presenter/           # Presentation materials
│   └── testing/             # Test checklists
├── infra/bicep/             # Bicep module library
├── mcp/azure-pricing-mcp/   # Azure Pricing MCP server
├── scripts/                 # Validation and automation scripts
└── temp/                    # Scratch space (gitignored for outputs)

Agent Inventory (13 Primary + 9 Subagents)

Primary Agents

Validation Subagents (in _subagents/)

Shared Knowledge (via Skills)

All shared context previously in _shared/ is now consolidated into skills:

Skill Catalog (14 Skills)

Template Inventory (16 Templates)

All in .github/skills/azure-artifacts/templates/. Naming: {step}-{name}.template.md.

Instruction File Map (25 Files)

Artifact Flow (7-Step Workflow)

Step 1          Step 2            Step 3         Step 4
Requirements → Architecture →  Design       → Planning
(01-*.md)     (02-*.md)       (03-des-*)     (04-*.md)
                                  │
                                  ├─ Diagrams (03-des-diagram.py/png)
                                  ├─ ADRs (03-des-adr-*.md)
                                  └─ Cost Estimate (03-des-cost-estimate.md)

Step 5            Step 6          Step 7
Implementation → Deploy       → Documentation
(infra/bicep/)  (06-*.md)      (07-*.md × 7 types)
(05-*.md)

Key Files for Documentation Maintenance

These files contain counts, tables, or version references that need updating when agents or skills change:

docs/ Folder Contents

Skill Discovery & Auto-Invocation

Skills are discovered by VS Code Copilot via description keyword matching in the SKILL.md frontmatter — not through tools: arrays in agent definitions.

Agent-Referenced Skills

These skills are explicitly referenced in agent body text via mandatory "Read skills FIRST" instructions:

General-Purpose Skills

Discovered purely by prompt keyword matching — no agent explicitly references them:

• git-commit — Triggered by "commit", "git commit" prompts
• docs-writer — Triggered by "update docs", "check staleness" prompts
• make-skill-template — Triggered by "create skill", "new skill" prompts

Instruction Files (Separate Mechanism)

Instruction files (.github/instructions/*.instructions.md) load automatically via .gitattributes applyTo globs — this is a distinct mechanism from skill discovery. Instructions are file-type-scoped rules, not invokable skills.