Sdd

In each phase a lead does the work, a fresh-context reviewer reruns the checks, and fixers get up to maxFixLoops rounds. Only the reviewer’s verdict passes a gate. Implement runs disjoint workstreams in parallel.

Phases reconcile existing artifacts instead of starting over, so reruns are safe. Lessons go to docs/LOOP.md. Each run writes a flight record to .agentic-loop/runs/<runId>.json, with status running, awaiting-approval, blocked, deployed, verified (or specified/implemented when to ends it early) or error, saved at the start, at the first step after a resume, at each gate and checkpoint, and at the end. A record that cannot be written pauses the run at blocked-record-<step>. One run is active per workspace: .agentic-loop/active-run.json holds its lease, and a second run refuses to start while that lease is under 30 minutes old.

Start a run

1. Check for a run. List runs with dynamic_workflows_manage (runs) and match them to this workspace’s .agentic-loop/runs/ records. If one is running or paused, report it and offer to resume it instead of starting a second run.

2. Preflight in Chat (read-only): az account show, azd auth login --check-status, azd ai agent --help (azd Foundry extension), microsoft-foundry and the bootstrap. Report all gaps at once, and ask before installing or upgrading tools.

3. Clarify once. Ask, with choices, only the questions whose answers change the spec: users, data, tools, UX or compliance. Take the subscription, region and azd environment from the canvas prompt. Otherwise confirm the current az default subscription, leave the region to Specify’s placement check, and derive a short environment name such as claims-triage-dev.

4. Lock the mode. Upsert the SDD section of the root AGENTS.md (lock-in). The workflow also writes it and refuses a workspace locked to rapid prototyping.

5. Start with run_dynamic_workflow, name: "foundry-agentic-loop-workflow", and these args:

   Arg	Purpose
   brief	Required. Self-contained, with the user’s answers and decisions
   subscriptionId, location, environmentName	Azure target when known
   scenarioId	Canvas prompt template
   autonomy	gated (default) pauses for spec approval; auto skips it
   maxFixLoops	Fix rounds per phase gate, 0–5 (default 2)
   skipDeploy	Stop after Verify
   from	Rerun from this phase; refused unless the latest record passed every earlier phase
   to	Last phase to run (default Deploy); from and to set to one phase run it alone

   Pass limits only when the user sets them; defaults are 250 subagents, 4 concurrent and 12 hours of active time.

6. Report the run ID and the checkpoints ahead. The run continues in the background, posting phase and gate lines in Chat; the Foundry Agentic Loop canvas Build tab shows live agents. No input is needed until a checkpoint. Do not poll; the run notifies when it pauses or ends.

Checkpoints and recovery

Live status first. For status, approve, resume or deploy requests, read the run with dynamic_workflows_manage (runs, then inspect-run) before its flight record. The run status is authoritative: a cancelled run keeps its last saved record status.

A pause posts a Needs you: line. Answer it in one message: what paused and why, the files to review, then the options as ask_user choices (approve or resume, change or fix first, leave paused).

• Resume with run_dynamic_workflow and resumeFromRunId only when the user asks. When a canvas prompt says “Do not resume the run”, don’t: the canvas resumes it.
• Liveness. Workflow subagents don’t appear in list_agents or read_agent, and one Implement step can run for over an hour without a record change. The canvas Build tab shows live subagent activity. Never cancel, pause or restart a run to unstick it; only the user decides that.
• Provider errors. A subagent that ends without a report is retried once with instructions to continue from the current state; a second miss blocks the phase, except for a workstream worker, which integration finishes. Check the session log, then resume.
• Effort. Subagents inherit the session’s model and reasoning effort. Prefer medium or high: maximum effort multiplies step time.
• A run that ends in error with workflow_limit_reached resumes with only that limit raised, after approval. For other errors, read the run with dynamic_workflows_manage (inspect-run), fix the cause and start a new run.
• Never weaken a gate, skip a phase or report unverified checks as passed.
• For a single named phase, start the workflow with from and to both set to it; from alone also runs every later phase. Without the workflow, follow the phase guides yourself in order, checking each gate and pausing at the same approvals: ask before azd provision, azd deploy or azd up.

SDD defaults

• Placement: a new resource group in the chosen subscription. Model gpt-5.4-mini unless the spec needs otherwise. Preferred region eastus2 (swedencentral for EU data residency) unless the user chose one. The joint placement check decides before AZURE_LOCATION is persisted; record the preferred and deployed regions in the deployment plan.
• Naming: azd environment <solution>-<stage> in at most 20 characters; resource group rg-<environment>, set with azd env set AZURE_RESOURCE_GROUP right after scaffolding to replace the salted default. Check az group exists and add a short suffix on collision.
• Skills first: reusable agent behavior goes into Foundry skills authored at skills/<name>/SKILL.md and declared as host: azure.ai.skill services, so azd deploy versions them. Agents load them from the toolbox at runtime, so the image never copies skills/. Agents that use skills run on the Copilot SDK; basic agents and graph workflows use MAF.
• Toolbox: one host: azure.ai.toolbox service carries the skills, MCP tools (each through a host: azure.ai.connection service) and grounding. Agents list it in uses and map its TOOLBOX_<NAME>_MCP_ENDPOINT to TOOLBOX_ENDPOINT (toolbox guide). Older azd extensions without upgrade approval fall back to ordered postprovision hooks.
• Infra: scaffold the Basic sample with azd ai agent init . in an empty .scaffold folder, then move it into place (scaffold); never azd init -t <template> followed by agent init (it rewrites the provider). azure.yaml then uses two infra.layers: foundry (provider: microsoft.foundry: account, project and the model deployments in services.ai-project) and app (Bicep with AVM, dependsOn: [foundry]) for user-assigned identities, Log Analytics and Application Insights connected to the project, one ACR pulled by managed identity, the Container Apps environment and apps, and every RBAC row. Agents use host: azure.ai.agent; MCP servers, backend and frontend use host: containerapp with docker.remoteBuild: true. Cosmos DB for NoSQL only when state is needed. No private networking unless required. Layout: azd-layout.md.
• Identity: user-assigned managed identities. Bicep creates the RBAC contract rows at provision; an idempotent postdeploy hook creates the runtime instance rows and the MCP Easy Auth allow-lists. The RBAC preflight runs in Specify; BLOCKED stops the run and hands the owner a ready-to-run grant block.
• Repository: .gitignore covers .azure/* with !.azure/deployment-plan.md, .env and build output. Python dependencies follow the dependency contract and are locked with uv.lock or pinned requirements. .gitattributes sets * text=auto eol=lf.
• Evaluations: Verify always runs a small agent evaluation on spec scenarios (task adherence, intent resolution, and groundedness when grounded); content safety comes from Foundry guardrails. Add recurring or CI evaluations only on request.

Teardown

Only on request and with explicit approval for the named environment and subscription: run azd down --purge --force from the workspace. It deletes the resource group and purges soft-deleted Foundry resources. Entra app registrations live outside the resource group: with the same approval, delete those recorded in docs/implementation.md with az ad app delete --id <appId>.