pi-ape-speckit

A spec-driven platform engineering repository for designing and implementing Azure landing zone foundations with pi, checked-in specs, and Terraform/OpenTofu-compatible infrastructure code.

What this project is

This repository is a working starter for platform work that should be researched, reviewed, and built through a spec-first workflow rather than by jumping directly into code.

Today, the repository contains:

• a checked-in spec workflow scaffold under .specify/
• persona and workflow rules in AGENTS.md
• a first feature spec for Core Hub-and-Spoke Networking under specs/
• an initial Terraform/OpenTofu implementation skeleton under infra/terraform/
• checked-in Azure governance references, review checklists, and control matrices under governance/

This project is currently focused on Azure landing zone networking, but the repo structure and workflow are intended to support broader platform engineering work over time.

Current status

The repo currently reflects the following truths:

• The target architecture is a traditional hub-and-spoke Azure landing zone baseline.
• The implementation direction is Terraform/OpenTofu-compatible HCL, with remote state in Azure Blob Storage.
• The checked-in Terraform/OpenTofu code has been validated locally with:
  • terraform fmt -check -recursive infra/terraform
  • terraform -chdir=infra/terraform/bootstrap-state validate
  • terraform -chdir=infra/terraform/environments/dev validate
  • terraform -chdir=infra/terraform/environments/prod validate
• A GitHub Actions workflow is checked in for Terraform validation, TFLint, and advisory Checkov review, but this README does not assert that those checks have already run successfully in GitHub for a real PR.
• The repo now includes a subscription-level Azure Policy baseline module and example environment inputs, but the stack has not yet been fully planned or applied against a real Azure environment from this repo.
• The recommended first release posture is a starter / baseline scaffold until live Azure execution evidence is attached.
• The original Bicep-era validation gate az deployment sub validate is not the completion gate for this implementation anymore.

Repository layout

.
├── .github/
│   └── workflows/
├── AGENTS.md
├── README.md
├── .specify/
│   ├── README.md
│   ├── memory/
│   └── templates/
├── specs/
│   └── 2026-05-15-core-hub-and-spoke-networking/
│       ├── PRODUCT.md
│       ├── TECH.md
│       ├── MILESTONES.md
│       └── research/
├── governance/
│   ├── README.md
│   ├── azure-platform-review-checklist.md
│   ├── azure-control-matrix.md
│   ├── azure-policy-baseline.md
│   └── release-readiness-v0.1.0.md
├── docs/
│   ├── quickstart-dev.md
│   └── releases/
└── infra/
    └── terraform/
        ├── README.md
        ├── bootstrap-state/
        ├── modules/
        └── environments/
            ├── dev/
            └── prod/

Design choices

The current spec set makes the following design choices.

Platform architecture

• Traditional hub-and-spoke for v1, not Virtual WAN
• One platform-owned hub VNet for shared services
• Zero or more parameterized spokes for landing zones or environments
• No direct spoke-to-spoke peering
• Azure Firewall as the centralized routed security boundary
• Azure Bastion for operator access
• Centralized DNS with Azure Private DNS Resolver and curated Private DNS zones
• GatewaySubnet is reserved for future hybrid connectivity, but VPN/ExpressRoute gateways are not deployed in v1

IaC and repository design

• Infrastructure is authored in Terraform/OpenTofu-compatible HCL
• The repo uses environment root modules (dev, prod) plus reusable child modules
• Remote state is expected to live in Azure Blob Storage via the azurerm backend
• Backend bootstrap is separated into infra/terraform/bootstrap-state/
• Diagnostics are optional and parameter-driven
• Private DNS zones are curated and parameter-driven, not an exhaustive default catalog

Workflow design

• All non-trivial work should follow Spec -> Plan -> Implement -> Audit
• Every Azure resource must be represented in PRODUCT.md as a testable invariant
• TECH.md is the implementation plan, risk record, and Azure best-practice alignment record
• MILESTONES.md is the execution and decision log
• Build-time checks and runtime policy expectations should be defined before implementation begins

How to use this repo

1. Work from pi

This repository is intended to be worked on from a pi session with spec workflow support available. The repo contains both:

• @capyup/pi-specs conventions for PRODUCT.md / TECH.md style spec work
• @ifi/pi-spec conventions for .specify/ and /spec:*-style workflow scaffolding

In practice:

• use AGENTS.md as the repo-specific operating contract
• keep decisions in checked-in spec files, not only in chat history
• treat specs as implementation inputs, not documentation written after the fact

2. Understand the spec artifacts

For the active feature, look in:

• specs/<feature>/PRODUCT.md — what the platform capability provides
• specs/<feature>/TECH.md — how it will be implemented and how it aligns to Azure best practices
• specs/<feature>/research/ — evidence that shaped the design
• specs/<feature>/MILESTONES.md — design and implementation history

3. Use the governance baseline

The repo now includes checked-in governance support under governance/:

• governance/azure-platform-review-checklist.md — design, implementation, and release review checklist
• governance/azure-control-matrix.md — design/build/runtime control mapping with evidence expectations
• governance/azure-policy-baseline.md — initial Azure Policy initiative scope and exemption model
• governance/release-readiness-v0.1.0.md — current first-release readiness checklist and outstanding blockers

Use these artifacts to keep spec review, CI, runtime controls, and release posture aligned.

4. Use the quickstart and release docs

• docs/quickstart-dev.md — shortest honest path to a real dev plan/apply exercise
• docs/releases/v0.1.0.md — draft release notes for the first tag
• CHANGELOG.md — release history and known limitations

5. Work with the Terraform/OpenTofu modules

The current infrastructure layout is:

• infra/terraform/bootstrap-state/ — remote-state backend creation
• infra/terraform/modules/ — reusable Azure networking modules
• infra/terraform/environments/dev — example lower-environment root
• infra/terraform/environments/prod — example production root

The root modules compose:

• resource groups
• hub network
• firewall policy and firewall
• bastion
• DNS resolver and private DNS zones
• spoke networks
• peerings
• route tables
• optional diagnostics
• optional subscription-level Azure Policy baseline assignment

6. Choose your CLI

The technical design is OpenTofu-first in intent, but the checked-in configuration is intentionally Terraform-compatible.

Important truth for this repository environment:

• the checked-in examples and local validation in this repo were run with Terraform
• the checked-in CI workflow also uses Terraform today
• if your team standardizes on OpenTofu, you can generally substitute tofu for terraform, but you should prove that in your own environment before treating it as operationally equivalent

7. Configure backend and variables

Before planning or applying an environment:

1. bootstrap the remote state backend
2. replace the placeholder values in backend.hcl
3. replace example values in terraform.tfvars
4. authenticate to Azure using your team-approved method

How to operate the spec-kit driven flow

Use the workflow below for any substantial platform change.

Recommended lifecycle

1. Start with intent
   • define the platform capability or change you want
2. Research before committing to a design
   • use /specs-research when evidence could change direction
3. Write or refine PRODUCT.md
   • define the platform behavior as numbered, testable invariants
4. Write or refine TECH.md
   • define implementation structure, Azure WAF alignment, risks, validation, and rollout
5. Review and approve the spec
   • do not implement from an unreviewed technical direction
6. Implement from the approved spec
   • keep code, spec, and milestones aligned
7. Validate
   • for this Terraform/OpenTofu stack, the completion gate is formatting, init, validation, plan review, and static analysis
8. Audit
   • use audit-oriented review plus Azure Policy compliance checks to catch drift between behavior, design, and implementation

Useful pi commands

If your pi session has the packages loaded, these are the main workflows to use.

@capyup/pi-specs

• /specs <feature>
• /specs-research <topic>
• /specs-product <feature>
• /specs-tech <feature>
• /specs-implement <spec-dir>
• /specs-audit [area]
• /specs-grill-me [focus]

@ifi/pi-spec

• /spec:init
• /spec:constitution <principles>
• /spec:specify <feature description>
• /spec:clarify
• /spec:plan
• /spec:tasks
• /spec:analyze
• /spec:implement
• /spec:status
• /spec:next

What “done” means for the current Terraform/OpenTofu implementation

Treat completion as layered, not as a single command.

Local configuration gate

At minimum, the checked-in Terraform/OpenTofu configuration should pass:

terraform fmt -check -recursive infra/terraform
terraform -chdir=infra/terraform/environments/<env> init -backend-config=backend.hcl
terraform -chdir=infra/terraform/environments/<env> validate
terraform -chdir=infra/terraform/environments/<env> plan -var-file=terraform.tfvars -out=core-hub-spoke.tfplan

If using OpenTofu, replace terraform with tofu.

Governance gate

Before you treat an environment change as ready for approval, also expect:

• CI checks for formatting, initialization, validation, and lint/static analysis
• reviewed plan output
• checked-in spec and milestone alignment
• documented exceptions, if any

Live Azure gate

This repo does not yet claim that the stack or policy baseline has passed a real Azure plan/apply cycle from these checked-in environment roots. For rollout confidence, you still need environment-specific plan review, apply approval, and Azure-side smoke checks/policy compliance review.

Example operating commands

Bootstrap remote state

terraform -chdir=infra/terraform/bootstrap-state init
terraform -chdir=infra/terraform/bootstrap-state plan
terraform -chdir=infra/terraform/bootstrap-state apply

Validate an environment root

terraform fmt -check -recursive infra/terraform
terraform -chdir=infra/terraform/environments/dev init -backend-config=backend.hcl
terraform -chdir=infra/terraform/environments/dev validate
terraform -chdir=infra/terraform/environments/dev plan -var-file=terraform.tfvars -out=core-hub-spoke.tfplan

Sample pi prompts for generic platform engineering tasks

These are example prompts you can give pi when working in this repo or a similar platform repo.

Spec and architecture prompts

• Use /specs to research and design a shared observability baseline for our Azure landing zone.
• Create a PRODUCT.md and TECH.md for a platform-managed private DNS service for spoke subscriptions.
• Research the trade-offs between Azure Firewall Standard and Premium for a regulated environment.
• Grill the current hub-and-spoke spec and identify the weakest design assumptions.
• Draft a rollout plan for moving existing spokes to centralized egress with minimum disruption.

Terraform/OpenTofu prompts

• Implement a reusable Terraform module for Azure Private DNS zones linked to the hub and optional spokes.
• Add environment validation and safer variable checks for hub and spoke address planning.
• Design a remote-state bootstrap pattern for Terraform in Azure with Entra ID-based access.
• Refactor the networking root modules so prod and dev share the same child modules with different inputs.
• Audit the Terraform modules for naming, tagging, and optional diagnostics consistency.

Platform operations prompts

• Create a spec for standardizing Azure tags, diagnostics, and RBAC on shared platform resources.
• Research whether we should split connectivity, management, identity, and security into separate subscriptions.
• Design a safe process for onboarding a new spoke landing zone into the hub without replacing existing peerings.
• Propose a staged migration from local Terraform state to Azure Blob remote state with locking.
• Audit our spec and implementation drift before we approve a production rollout.

Attribution

This repository and workflow are built on top of, and informed by, the following projects and references:

• @capyup/pi-specs for the checked-in PRODUCT.md / TECH.md spec workflow used in this repo
• @ifi/pi-spec for the native pi /spec:* workflow, .specify/ scaffold, and spec-kit-inspired lifecycle support
• GitHub spec-kit as an upstream conceptual influence on spec-first workflow structure
• Microsoft Learn, Azure Architecture Center, and Azure Cloud Adoption Framework guidance for Azure landing zone and hub-and-spoke design decisions
• Terraform / OpenTofu language, backend, and AzureRM provider documentation for the current IaC layout

Please retain attribution when reusing this repository structure or adapting the workflow in derivative projects.