Skip to content

feat: refine Copilot Studio harness guidance #15

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
Robert Standefer (RobStand) wants to merge 1 commit into from
Closed

feat: refine Copilot Studio harness guidance #15

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions .github/copilot-instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,8 @@ Documented in `docs/SCORING.md` and `docs/FLOWCHART.md`:
1. **Hard rules** zero out platforms for disqualifying answer combinations
2. **Raw scores** sum across 5 questions (max 15 per platform)
3. **Tiebreakers** in `apa.yaml` resolve equal scores using persona context
4. **Thresholds** map scores to fit labels: Strong (12–15), Good (8–11), Partial (4–7), Not recommended (0–3)
4. **Conditional runtime distinction** asks who should operate the runtime only when Copilot Studio and Foundry are the top two platforms within 2 points
5. **Thresholds** map scores to fit labels: Strong (12–15), Good (8–11), Partial (4–7), Not recommended (0–3)

`meta.platforms` lists four platforms, but `m365_copilot` is always zeroed in the scored wizard (`if (!fastTrack) zeroed['m365_copilot'] = true`), so only three can actually win. M365 Copilot is reached through the entry-point wizard, or via the legacy `?ft=1` / `?dt=copilot_chat` share links.

Expand All @@ -60,6 +61,7 @@ Result links are shared externally, so **old parameter shapes must keep resolvin
| Param | Meaning |
|---|---|
| `q1`, `q8`, `q2`, `q4`, `q3` | Scored-wizard answers (option IDs) |
| `q9=q9a|q9d` | Conditional runtime ownership tie-breaker |
| `dt=m365_copilot\|cowork\|scout\|both` | Entry-point destination |
| `st=chat\|agents` | Which M365 Copilot surface to feature |
| `r=<platform>` + `d=YYYYMMDD` | Original recommendation + date; drive the temporal-change banner |
Expand All @@ -81,8 +83,8 @@ Key constraints:

## Conventions

- Always update `docs/CHANGELOG.md` after making changes. Sections are dated by commit date (`## 2026-07-24`); work in progress sits under `## Unreleased` until it's committed.
- Always update `docs/CHANGELOG.md` after making changes. Sections are dated by commit date (`## 2026-07-24`).
- Always update `docs/FLOWCHART.md` and `docs/SCORING.md` after changes that affect user flow or scoring logic.
- Question IDs in `apa.yaml` are not sequential (e.g., `q1, q8, q2, q4, q3`) — they preserve identity across schema changes. Display order is the array order in `apa.yaml`, not the numeric ID.
- Question IDs in `apa.yaml` are not sequential (e.g., `q1, q8, q2, q4, q3`) — they preserve identity across schema changes. Display order is the array order in `apa.yaml`, not the numeric ID. `q9` is a conditional, non-scored runtime distinction.
- Entry-point cards (`ENTRY_POINT_PLATFORMS` in `apa.js`) render their accordions expanded; scored comparison cards stay collapsed.
- In tests, don't identify a recommendation card by a headline substring alone — several destinations share "Microsoft 365 Copilot" wording. Assert exact `.rec-platform-name` text plus something distinguishing.
12 changes: 8 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ The start page presents ways to use or build agents:
From **Get Started**, users choose one of three paths:

1. **Entry-point wizard** ("Help me find the right place to get work done") — asks how hands-on you want to be, then routes to Microsoft 365 Copilot (featuring either Copilot Chat or its built-in agents), Cowork, Scout, or a Cowork+Scout pair. Non-scored.
2. **Custom agent assessment** — runs the scored 5-question wizard for Agent Builder, Copilot Studio, and Foundry.
2. **Custom agent assessment** — runs the scored 5-question wizard for Agent Builder, Copilot Studio, and Foundry, with a conditional runtime tie-breaker when the two enterprise platforms remain close.
3. **Explore what's possible** — compares ways to use or build agents before deciding whether to take the assessment.

The custom agent assessment asks about:
Expand All @@ -40,9 +40,12 @@ The custom agent assessment asks about:
- What the agent should do: Q&A, multi-turn conversation, content/data analysis, multi-step action workflows, or complex orchestration
- What information it needs: Microsoft 365 content, connector-backed systems, Dataverse/custom APIs, public web/uploaded files, or custom retrieval architecture

When Copilot Studio and Foundry are the top two platforms within 2 points, the wizard asks one final non-scored distinction: whether Microsoft or the user's engineering team should operate the agent runtime.

After completing a path, users get:

- A primary recommendation with fit badge, key factors, and platform-specific guidance
- A "Start with this harness" callout when Copilot Studio wins
- A "Start Here" callout on entry-point results naming the surface to open first
- A secondary "Also Consider" card when another option is close or complementary
- A score comparison panel for the scored wizard
Expand Down Expand Up @@ -88,6 +91,7 @@ There are two recommendation modes:
- Hard rules zero out platforms for disqualifying combinations before scoring.
- Raw scores sum across 5 questions, with a maximum of 15 points per platform.
- Persona preferences and tiebreakers adjust ranking when scores are tied or misleading for the selected builder persona.
- A conditional runtime distinction resolves close Copilot Studio/Foundry cases without changing their scores.
- Thresholds map scores to fit labels: Strong fit (12-15), Good fit (8-11), Partial fit (4-7), Not recommended (0-3).

Microsoft 365 Copilot, Cowork, and Scout are not part of the 0-15 scored wizard. They are reached only through the entry-point wizard.
Expand All @@ -97,7 +101,7 @@ Microsoft 365 Copilot, Cowork, and Scout are not part of the 0-15 scored wizard.
The advisor reflects the current split between Microsoft agent options:

- **Agent Builder** has expanded beyond SharePoint/OneDrive-only scenarios. It now covers no-code agents grounded in Microsoft 365 content, scoped web, uploaded files, and admin-enabled Microsoft 365 Copilot connectors, including lightweight content and data-analysis helpers.
- **Copilot Studio** is the default governed low-code path for enterprise agents that need actions, workflows, triggers, connectors, MCP tools, computer use, connected agents, evaluation, monitoring, and multi-channel deployment.
- **Copilot Studio** is the managed enterprise agent platform spanning GitHub Copilot harness agents for adaptive work, standard harness agents for predictable conversations, Copilot chat harness agents for Microsoft 365 knowledge extensions, and deterministic workflows.
- **Microsoft Foundry** is the developer-controlled production runtime for prompt agents, hosted code agents, custom retrieval, managed endpoints, toolboxes, MCP, identity, private networking, tracing, evaluation, monitoring, and custom app/service integration.
- **Microsoft 365 Copilot** is treated as the built-in productivity layer, and as one product rather than several: Copilot Chat, Copilot Search, app-native Copilot, Pages, Notebooks, and Microsoft-built agents are all surfaces within it.
- **Copilot Cowork** and **Microsoft Scout** are personal agents you delegate work to, not platforms in the scored build assessment.
Expand All @@ -106,7 +110,7 @@ The advisor reflects the current split between Microsoft agent options:

Share links encode the recommendation path:

- Wizard results include selected answers, the recommended platform, and the recommendation date.
- Wizard results include selected scored answers (`q1`, `q8`, `q2`, `q4`, and `q3`), the optional runtime distinction (`q9`) when asked, the recommended platform, and the recommendation date.
- Entry-point results include `dt=m365_copilot`, `dt=cowork`, `dt=scout`, or `dt=both`, plus `st=chat` or `st=agents` for the Microsoft 365 Copilot starting surface.
- Older links keep working: `ft=1` and `dt=copilot_chat` both resolve to the Microsoft 365 Copilot card.
- Recipients can view the recommendation directly or retake the assessment with answers pre-filled.
Expand All @@ -123,7 +127,7 @@ npm test # headless
npm run test:headed # with browser visible
```

There are 39 tests across 6 spec files covering wizard completion, shared link loading, temporal change detection, legacy fast-track links, entry-point wizard routing, and share button behavior. To run a single file or test: `npx playwright test tests/e2e/delegate-path.spec.js` or `npx playwright test -g "completes full wizard"`. CI runs automatically on push and pull request via GitHub Actions.
There are 48 tests across 7 spec files covering wizard completion, the conditional runtime distinction, Copilot Studio harness guidance, shared link loading, temporal change detection, legacy fast-track links, entry-point wizard routing, and share button behavior. To run a single file or test: `npx playwright test tests/e2e/delegate-path.spec.js` or `npx playwright test -g "completes full wizard"`. CI runs automatically on push and pull request via GitHub Actions.

## Contributing

Expand Down
Loading
Loading