Scenario: from an idea to a delivery backlog

A business user types an idea into a Copilot Studio agent. The product squad researches it, plans it, produces the stakeholder deliverables, and hands back a structured backlog — which the agent then creates as epics, stories, and tasks in Azure DevOps, Jira, or GitHub. This page is the whole path, end to end, so you can reproduce it.

What you will have at the end

1. A deployed MCP server in your own Azure tenant, with the product profile and the business tools enabled.
2. A Copilot Studio agent with two connectors: this server, and your native work-tracking connector.
3. A repeatable conversation: "turn this PRD into a backlog" → confirmation → work items created, correctly parented, with acceptance criteria intact.
4. A durable trail under .copilot-tracking/ in your own storage, read back automatically on the next run.

Part 0 — Prerequisites

• An Azure subscription you can deploy to, and permission to create an Entra app registration.
• An Azure OpenAI deployment. This is where the cost is.
• A Copilot Studio licence, and the ability to add a custom connector.
• Azure DevOps, Jira, or GitHub, with a licence that permits the native connector.
• The repository cloned, and npm ci && npm run build run once.

Part 1 — Deploy with the product path switched on

Follow host/RUNBOOK.md steps 1–7 for the base deployment. This scenario needs more than the default advisory posture, so set the following before Step 6 (they are main.bicepparam parameters as well as environment variables):

Part 2 — Decide where the history is saved

This is the decision people skip, and then discover after their first real run that a month of squad output lives somewhere nobody can open. Decide it now — it is one setting, and it is the same setting for everything the squad writes.

What actually gets written

With SQUAD_MCP_ENABLE_ARTIFACTS=true a run writes a browsable .copilot-tracking/ tree — the same tree the squad produces when it runs locally in VS Code:

squad/team.md                          the 13 seeded roles
squad/routing.md                       the rows those roles can serve
squad/state.json                       the ledger
squad/decisions.md                     append-only — incl. the Intake Readiness Verdict
squad/notifications.md                 append-only
squad/history/<agent>.md               per agent, with a measured Consumption block
squad/history/autopilot-run-<id>.md    per run
squad/consumption.md                   rebuilt from those blocks, so earlier turns are never dropped
plans/ · docs/ · outputs/ · ppt/<date>/<slug>/   the deliverables themselves

Pick a destination

One setting, SQUAD_MCP_MEMORY_BACKEND, chooses it for memory, the ledger, and the deliverables at once.

If you chose SharePoint

Each entry becomes one markdown file at:

<rootPath>/<tenantId>/<project>/<path>.md

versioned by SharePoint and subject to your existing retention, search, and DLP policy. Concurrency uses Graph's native eTag with If-Match, so a stale write loses the race rather than clobbering.

Two steps you must perform yourself:

1. Resolve the drive id of the library that will hold the history:

   SITE_ID=$(az rest --method GET \
     --url "https://graph.microsoft.com/v1.0/sites/<TENANT>.sharepoint.com:/sites/<SITE_PATH>" \
     --query id --output tsv)
   
   az rest --method GET \
     --url "https://graph.microsoft.com/v1.0/sites/$SITE_ID/drives" \
     --query "value[].{name:name,id:id}" --output table

2. Grant the app identity access to that one library, as an administrator:

   az deployment group create \
     --resource-group "$RG" \
     --template-file host/infra/graph-memory-permissions.bicep \
     --parameters host/infra/graph-memory-permissions.bicepparam

   This assigns Sites.Selected — which on its own grants access to no site — and then grants write on exactly the site you named. It is a separate deployment on purpose: it needs AppRoleAssignment.ReadWrite.All and Sites.FullControl.All, far above what deploying the Container App needs, so your routine deploys never require Graph admin rights. Re-running it is a no-op.

Large artifacts

A table entity has a size ceiling, and a PRD or a full backlog will exceed it. Enable overflow so the write does not fail:

Anything past the threshold spills to blob with a pointer left in the entity. Reads are transparent.

Offering a choice to different teams

If one deployment serves several teams that must not share a destination, declare an allow-list instead of a single backend:

SQUAD_MCP_MEMORY_TARGETS=[
  { "name": "azure",      "backend": "table", "tableName": "squadmemory" },
  { "name": "sharepoint", "backend": "graph", "driveId": "<DRIVE_ID>", "rootPath": "squad-memory" }
]
SQUAD_MCP_MEMORY_DEFAULT_TARGET=azure

The caller then passes an opaque target name. You own every credential-bearing field; an undeclared name is rejected before any I/O and never falls back to the default.

Reading it back

There are two paths, and for this scenario the first one is the one that matters:

• Automatic. With SQUAD_MCP_MEMORY_AUTO_ENABLED=true the server reads the project's state and decisions before every dispatch and injects them as delimited data — never authority. Nobody has to remember to ask for it. This is why the squad_backlog call in Part 7 does not need the run's artifact pasted back in.
• On demand. squad_history browses the tree — op=index to summarize, op=list to enumerate, op=read to open one file. It needs the Squad.Memory scope.

What is true regardless of destination

• The validated token's tenantId is always the first path segment, so tenant isolation holds on Azure Table, SharePoint, and disk alike.
• The partition is derived from a pinned sub-squad or SQUAD_MCP_MEMORY_DEFAULT_PROJECT — it is never taken from caller free text.
• With SQUAD_MCP_RUN_ENCRYPTION_KEY_B64 set, stage artifacts, the Council Verdict, and caller request/context are AES-256-GCM encrypted at rest.
• Writes are compare-and-swap, so two concurrent runs in one project cannot clobber each other.

Part 3 — Expose the scopes this scenario uses

In the Entra app registration from Step 2 of the runbook, expose and consent to:

Every scope is fail-closed: a missing one returns 403 with no work performed and nothing billed.

Part 4 — Import the connector into Copilot Studio

1. Regenerate the connector so it reflects your build, then fill in the placeholders in generated/copilot-studio-connector/apiDefinition.swagger.json and apiProperties.json:

   npm run generate:connector

   Placeholder	Replace with
   <SQUAD_MCP_HOST>	your Container App FQDN, host only, no scheme
   <ENTRA_TENANT_ID>	your tenant id
   <ENTRA_CLIENT_ID>	the app id from Step 2
   <SQUAD_MCP_AUDIENCE>	api://<ENTRA_CLIENT_ID>

2. Add a custom connector in Copilot Studio from the OpenAPI file. It advertises the x-ms-agentic-protocol: mcp-streamable-1.0 /mcp operation.
3. Complete the Entra OAuth 2.0 connection, consenting to the scopes in Part 3.
4. Enable generative orchestration on the agent. Without it the agent cannot call MCP tools at all — this is the single most common reason "nothing happens".
5. Add your work-tracking connector to the same agent: the certified Azure DevOps, Jira, or GitHub connector, authenticated as the end user.
6. Paste the generated agent instructions from generated/copilot-studio-connector/agent-instructions.md into the agent's Instructions field. It already contains the create-work-items protocol, the confirmation requirement, and the parenting rules. Delete the memory section — you enabled automatic memory in Part 1, so the agent must not call the memory tools.

Part 5 — What the product profile actually runs

profile: "product" seeds 13 roles, and that seeding is what makes this scenario different from a generic squad_run. Resolved against the bundled cast, a product run sequences:

Two behaviours here are worth understanding before you run it:

• The intake gate can stop the run. Because the product profile seeds intake-validator, a run grounded in a requirements document is validated first. The validator records Ready, Ready-With-Gaps, or Not-Ready. On Not-Ready the pipeline halts with reason: "intake_not_ready" rather than letting seven specialists build on inputs it just rejected. That is the gate working — fix the document and re-run.
• There is no separate backlog-handoff stage. The product profile carries product-owner inside the fan-out, so the handoff is stage 4. A profile without it gets a backlog stage appended instead.

Each specialist writes to its own root, which is where you go looking afterwards:

Part 6 — Run it

In the Copilot Studio agent, the user says something like:

Run the full product squad on our customer onboarding PRD and turn it into a delivery backlog.

The agent calls squad_run. Make sure your instructions pass the profile:

{
  "name": "squad_run",
  "arguments": {
    "request": "Turn our customer onboarding PRD into a delivery backlog",
    "profile": "product",
    "mode": "autopilot",
    "squad": "onboarding",
    "context": "<the PRD text, or the constraints the user gave>"
  }
}

What comes back depends on your Part 1 choice:

curl -sS -X POST "https://$FQDN/admin/approve" \
  -H "Authorization: Bearer $OPERATOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"runId":"<run-id>"}'

Part 7 — Turn the result into work items

The compiled artifact is prose — good for a human, wrong for a connector. squad_backlog is the converter:

{
  "name": "squad_backlog",
  "arguments": {
    "request": "Break the approved onboarding plan into epics, stories, and tasks",
    "squad": "onboarding"
  }
}

With automatic memory on you do not have to paste the run's output back in — the pre-read merges the project's prior state into context as data, so passing the same squad is enough. Pass context explicitly only to add something the run never saw, such as an existing backlog or a definition of done.

The contract you get back

{
  "summary": "Plain-language summary for the business user.",
  "epics": [ { "title": "...", "description": "...",
               "acceptanceCriteria": ["..."],
               "stories": [ { "title": "...", "tasks": [ ... ] } ] } ],
  "workItems": [
    { "ref": "E1",       "type": "Epic",       "title": "...", "acceptanceCriteria": ["..."] },
    { "ref": "E1-S1",    "type": "User Story", "parentRef": "E1",    "estimate": "M", "...": "..." },
    { "ref": "E1-S1-T1", "type": "Task",       "parentRef": "E1-S1", "...": "..." }
  ]
}

workItems is a depth-first flattening of epics, so parents always precede their children. Iterating it in order and creating as you go means a parent id always exists by the time a child needs it. ref and parentRef are assigned by the server, not the model — which is the point: the agent links by id it recorded, never by matching titles, because titles are not unique and a model will rephrase them.

The server validates and normalizes the model's JSON and fails cleanly if it cannot, so the agent never receives half-parsed output. Hard caps apply — 30 epics, 30 stories per epic, 30 tasks per story, 20 acceptance criteria, 4000 characters per text field — so one call can never emit an unbounded backlog.

The agent's create loop

This is already in the generated instructions; it is repeated here so you can verify the behaviour you see:

1. Show the user the summary and the epic/story list. Ask for confirmation. Never bulk-create unconfirmed.
2. On confirmation, iterate workItems in order, one connector call per element: type from type, title from title, description from description, and the acceptanceCriteria lines joined as a list.
3. Record the created id against the element's ref. When an element has a parentRef, link it to the id recorded for that ref.
4. On a failure, report which ref failed, continue with the rest, then offer to retry only the failures.
5. Pace the calls. The connectors are rate limited per connection — create one epic and its stories at a time rather than firing the whole array at once.

Part 8 — Mapping to your tracker

The contract uses the Azure DevOps type names. That is a naming choice, not a lock-in — the mapping happens in your agent's instructions, and the server is unaware of which tracker you use.

Part 9 — Verify it worked

Troubleshooting

What this scenario deliberately does not do

• It does not write to Azure DevOps, Jira, or GitHub from the server. Every write is the agent, on the user's own connection, under that connector's auth, DLP, and throttles.
• It does not execute code, open a pull request, or deploy anything.
• It does not let the model or the caller release a Human Gate. Only Squad.Operate does, out of band.
• It does not treat the PRD as instructions. Caller content is data; only a persona charter carries authority.