paulasilvatech ASP Agentic SDLC Personas v1.0.0
EN PT ES
12 platform · Platform

Platform Architect

Golden paths and IDP.

Updated: 2026-04-24 14 sections Download .zip

The Platform Architect is the persona that designs the paved roads every team walks on. In an AI-native SDLC, the Platform Architect operates a stack of validated primitives, not a wiki full of aspirational diagrams.

Executive summary

The Platform Architect owns the Internal Developer Platform: the golden path templates, the capability matrix, and the architectural decision records that shape how every team builds. In an AI-native SDLC, the Platform Architect operates inside the Platform phase with a fixed set of primitives: one platform agent, four slash prompts, scoped instructions, schema-validated hooks, and a curated list of validated MCPs. The platform is delivered as a Backstage-style catalog backed by Azure DevOps and GitHub Enterprise, with Bicep-based service templates, GitHub reusable workflows, and Azure Policy initiatives. The primary outputs are template repositories, capability matrices, ADRs, and a measurable developer experience.

Role and responsibilities

Think of the Platform Architect like a city planner. The planner does not build the buildings; the planner defines the streets, utilities, zoning, and building codes that allow thousands of builders to work in parallel without the city collapsing. The planner’s success is measured not by the number of buildings they designed, but by the time it takes a new builder to break ground with confidence. In an AI-native SDLC, the city is the Internal Developer Platform, the streets are GitHub Actions reusable workflows, the utilities are Azure shared services, and the zoning is Azure Policy.

Primary responsibilities:

  • Define and maintain the golden path templates for every service archetype (API, worker, front-end, data pipeline)
  • Operate the Backstage-style catalog backed by Azure DevOps and GitHub Enterprise
  • Author and govern architectural decision records in a central ADR repo
  • Maintain the capability matrix that maps business domains to platform primitives
  • Set the policy initiative in Azure Policy that applies to every subscription in scope
  • Sponsor the validated MCP catalog and the agent governance model
  • Operate the Path Keeper agent and the /golden-path, /template-new, /adr-platform, /capability-matrix prompts

Jobs to be done

  1. As a Platform Architect, I want a new service repo created from a golden path template in minutes, so that teams start on the paved road.
  2. As a Platform Architect, I want every service to declare its capabilities in a machine-readable matrix, so that platform evolution is data-driven.
  3. As a Platform Architect, I want ADRs to be drafted from design conversations, so that the decision record is never skipped.
  4. As a Platform Architect, I want templates versioned and rolled forward via automated PRs, so that the paved road stays paved.
  5. As a Platform Architect, I want platform usage telemetry to flow into Application Insights, so that unused capabilities are retired, not accumulated.
  6. As a Platform Architect, I want the MCP catalog to be enforced at commit time, so that teams cannot install rogue MCPs.

Pain points before AI-native

  1. Templates rot. The scaffolding repo has not been updated in 14 months. New services start on the old road.
  2. ADRs are optional. Decisions are made in calls, documented later, or not at all. Context evaporates in six months.
  3. Capability matrix is a spreadsheet. Nobody updates it; nobody trusts it.
  4. Policy sprawl. Each subscription grows its own Azure Policy definitions. Compliance reports are contradictory.
  5. MCP free-for-all. Every team installs the MCP of the week. Supply-chain surface area explodes.

AI-native daily workflow

The Platform Architect operates a fixed loop each day. The loop uses GitHub Copilot primitives inside Visual Studio Code and Claude Code at the terminal, plus a small catalog of validated MCPs for external context.

Morning setup

  1. Open the platform monorepo in Visual Studio Code. GitHub Copilot Chat loads AGENTS.md and the scoped .github/instructions/*.instructions.md for templates and ADRs.
  2. In Claude Code, run a daily report that queries the GitHub MCP for template usage, template drift PRs, and ADR review queue.
  3. Review the capability matrix for any service that fell out of compliance overnight (driven by Azure Policy and GitHub Advanced Security).
  4. Triage the inbound template requests in Azure Boards.

Midday execution

Each midday cycle is a single platform change, typically 2 to 4 hours of focused work.

  1. Golden path. Invoke /golden-path with an archetype (API, worker, front-end, data). The Path Keeper agent composes the template from Bicep modules, GitHub reusable workflows, and the validated MCP catalog.
  2. Template change. Invoke /template-new to version the template, open a rollout PR fleet across consuming repos, and attach a migration guide.
  3. ADR. Invoke /adr-platform to draft an ADR from the design meeting transcript. The agent fills the EARS constraints, the options considered, and the decision rationale.
  4. Capability matrix. Invoke /capability-matrix to refresh the domain-to-primitive map from the service catalog index.
  5. Pull request. The PR description is composed from the ADR and the template diff. GitHub Copilot Code Review scans for policy drift.

Afternoon governance

  1. Run a weekly template drift report in Azure Monitor. Services more than two minor versions behind are flagged.
  2. Publish the capability matrix snapshot to the Microsoft 365 SharePoint site for the platform review meeting.
  3. Hand off infrastructure changes to the DevOps Engineer; hand off security posture changes to the InfoSec Officer.

Agents

AgentFilePurpose
path-keeper.github/agents/path-keeper.agent.mdAuthor golden paths, govern templates, draft ADRs, maintain the capability matrix

The Path Keeper agent uses claude-sonnet-4-6 by default. It holds tools read, edit, search, grep, glob, bash, and MCP bindings to GitHub MCP Server and Azure DevOps MCP Server for catalog traversal.

Prompts

CommandFilePurpose
/golden-path.github/prompts/golden-path.prompt.mdCompose a new golden path template for a service archetype
/template-new.github/prompts/template-new.prompt.mdVersion a template and open the rollout PR fleet
/adr-platform.github/prompts/adr-platform.prompt.mdDraft an ADR from a design meeting transcript or specification
/capability-matrix.github/prompts/capability-matrix.prompt.mdRefresh the domain-to-primitive capability matrix

Instructions

Scoped applyTo reduces token cost by approximately 68 percent compared to global instructions.

Scope (applyTo)FilePurpose
templates/**/*.github/instructions/templates.instructions.mdTemplate parameter schema, README structure, upgrade path
adr/**/*.md.github/instructions/adr.instructions.mdADR format: context, options, decision, consequences
catalog/**/*.yaml.github/instructions/catalog.instructions.mdCatalog schema, ownership, lifecycle

Skills

Skills are lazy-loaded, so the Platform Architect can install many and pay tokens only for the ones that trigger.

  • template-drift-scan: calls GitHub MCP to list consuming repos still on old template versions
  • mcp-catalog-enforcer: refuses PRs that add MCPs not present in the validated catalog

Hooks

Hooks cost zero LLM tokens. They are the strongest governance layer.

  • pre-commit: validate template parameter schema and ADR front matter
  • pre-merge: verify template version bump and migration guide on any template change
  • post-merge: open rollout PRs across consuming repos via the GitHub MCP

Validated MCPs

Every MCP below is registered in the MCP catalog. Do not reference any MCP that is not in the catalog.

MCPStatusUse in this persona
GitHub MCP ServerOfficialCatalog traversal, template rollout PRs, usage telemetry
Azure DevOps MCP ServerOfficial (Microsoft)Read intake tickets, update Azure Boards, manage pipeline templates
Azure MCP ServerOfficial (Microsoft)Query Azure Policy initiatives and resource group inventories
Microsoft Learn Docs MCPOfficialFetch Azure Well-Architected Framework and Azure reference guidance during ADR drafting
Microsoft 365 Agents SDK MCPOfficial (Microsoft)Publish capability matrix snapshots and ADR notifications into Teams and SharePoint
Playwright MCPOfficial (Microsoft)Validate that golden path templates bootstrap working end-to-end smoke tests

Real examples

Scenario A: launch a new API golden path

Input: The org decides that every new internal API must use Azure API Management, Entra ID auth, and a Bicep-deployed App Service. No other archetype is allowed for internal APIs.

Invocation: /golden-path with archetype internal-api.

Expected output:

  1. A template repo template-internal-api with Bicep module, GitHub Actions reusable workflow, Entra ID app registration skeleton, and OpenAPI scaffold.
  2. An Azure Policy initiative that denies any App Service created outside this template.
  3. An ADR adr/0042-internal-api-golden-path.md recording the decision, options considered, and consequences.
  4. A capability matrix update linking the internal-api archetype to the shared APIM instance.

Scenario B: roll forward a breaking template change

Input: The org upgrades the standard .NET runtime from 8 to 9. Every service using the API golden path must upgrade.

Invocation: /template-new with the template version bump.

Expected output:

  1. A new template version template-internal-api@2.0.0 with the runtime bumped and a migration guide.
  2. A fleet of PRs opened by the Path Keeper agent across every consuming repo, each with the migration diff and a link to the ADR.
  3. A drift dashboard in Application Insights that shows adoption over time, published to the platform review meeting.

Anti-patterns

  1. Template as wiki page. A markdown page that describes the golden path without a scaffolding engine. Mitigation: every golden path is a real template repo with parameters and tests.
  2. ADRs written after the fact. Decisions are documented months later, if at all. Mitigation: /adr-platform drafts from the design meeting transcript during the meeting.
  3. Manual capability matrix. A spreadsheet that nobody updates. Mitigation: /capability-matrix regenerates from the catalog YAML.
  4. MCP free-for-all. Teams install any MCP they find. Mitigation: mcp-catalog-enforcer skill refuses PRs that reference uncatalogued MCPs.
  5. Policy per subscription. Each subscription grows its own Azure Policy tree. Mitigation: a single initiative owned by the Platform Architect, assigned at the management group.

KPIs and impact metrics

The Platform Architect persona is evaluated with a mix of platform engineering and developer experience metrics.

MetricBaseline (manual)Target (agentic)Measurement
Time to first commit for a new service2 weeks< 1 dayTime from intake to first merged PR
Template adoption rate40 percent> 90 percentPercent of services on the latest golden path
ADR coverage20 percent> 95 percentPercent of architecture decisions with a linked ADR
Capability matrix freshnessQuarterlyWeeklyDays since last refresh
Platform NPS from developersUnknown> 40Quarterly survey
Policy compliance70 percent> 98 percentAzure Policy compliance score
MCP catalog driftUnmeasured0 uncatalogued MCPsRepo scan
Token efficiencyN/A< 300k tokens per template versionCopilot usage report

Maturity in four levels

LevelNameMarkers
L1ManualScaffolding is a wiki page, ADRs optional, policies per subscription
L2AssistedTemplate repo exists but drifts, GitHub Copilot helps draft ADRs occasionally
L3AugmentedOne Path Keeper agent, four slash prompts, scoped instructions, two MCPs, template rollout automated
L4AgenticFull primitives kit, hooks enforced, MCP catalog enforced, capability matrix refreshed weekly, ADR coverage > 95 percent

Integration with other personas

Handoffs:

  • From Enterprise Architect: target architecture, reference patterns, investment themes
  • From Software Architect: service-level ADRs that bubble up to platform decisions
  • To DevOps Engineer: reusable workflows, Bicep modules, policy initiatives
  • To Developer: scaffolded repo, scoped instructions, validated MCP catalog
  • To InfoSec Officer: policy initiative, MCP catalog, Entra ID app registration skeleton

Glossary

  • Agent: a configured LLM role with tools, instructions, and a defined output shape.
  • Prompt: a reusable slash command that invokes an agent with a specific task.
  • Instructions: scoped guidance applied by pattern match on file paths via applyTo.
  • Skill: a lazy-loaded capability that activates on keyword match.
  • Hook: a zero-token rule enforced at a specific lifecycle event.
  • MCP: Model Context Protocol server that exposes external systems to the agent.
  • Golden path: the paved road every team is expected to use; deviation requires an ADR.
  • IDP: Internal Developer Platform; the system that makes the golden path easy to follow.
  • ADR: Architectural Decision Record; a dated markdown file that captures context, options, decision, consequences.
  • Capability matrix: a machine-readable map from business domain to platform primitive.

References