diff --git a/README.md b/README.md index 28f5422..8ee378e 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,21 @@ This plugin work in progress and supported by Github Issues only at this time, w /plugin install mcs-assistant@copilot-studio-plugin ``` +## Commands + +| Command | Description | +|---|---| +| `/create` | Create and push a new CLI-authored Copilot Studio agent from instructions or a business scenario, with optional guided component design. | +| `/migrate` | Migrate a classic Copilot Studio agent to the new agentic-loop architecture. | +| `/add-knowledge` | Add public website, SharePoint, OneDrive, or uploaded-file knowledge to a local agent. | +| `/chat` | Chat with and test a locally cloned CLI-authored agent. | + +## Skills + +| Skill | Description | +|---|---| +| `create-copilot-studio-agent` | Reusable procedure for instructions-only creation or optional guided design across skills, tools and workflows, instructions, data and knowledge, and settings. It is also the implementation behind `/create`. | + ## Trademarks This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft diff --git a/agents/copilot-studio-architect.md b/agents/copilot-studio-architect.md index 55f52c0..e2affba 100644 --- a/agents/copilot-studio-architect.md +++ b/agents/copilot-studio-architect.md @@ -1,14 +1,16 @@ --- name: Copilot Studio Architect description: > - This agent accepts a detailed behavior description plus an initialized Copilot Studio CLI target project, reasons about the right agentic-loop architecture, and writes the modern YAML files that implement it. It can also migrate agents from the previous architecture to the new agentic loop. + This agent accepts a behavior description plus an initialized Copilot Studio CLI target project, reasons about the right agentic-loop architecture, and writes the modern YAML files that implement it. It supports both new agents and migrations from the previous architecture. --- # Guide: Turning a natural-language idea into an agentic-loop agent ## 1. What the mechanism does -The mechanism receives a very detailed natural-language description and transforms that idea into a working Copilot Studio CLI project: +The mechanism receives a natural-language business problem, scenario, or set of instructions and +transforms it into a working Copilot Studio CLI project. The description may be minimal for a basic +instructions-only agent or detailed for a richer design: ```text Agent @@ -88,15 +90,47 @@ The mechanism’s job is to separate these concerns. ## Required inputs -You need these inputs before implementing a migrated agent: +For every implementation, require: -1. Target agent project directory, already initialized by `pac copilot init`. -2. Detailed behavior report from the Copilot Studio Describer. -3. Target migrated agent display name. -4. Source agent path, when available, for reading source-local knowledge references or copying uploaded knowledge files that are present locally. -5. Tool/action migration result, including which tools were already converted into `capabilities\tools`, which legacy actions were intentionally excluded by the approved plan, and which selected legacy actions were skipped as unsupported or invalid. +1. Target agent project directory, already initialized by `pac copilot init` in `cli-copilot` authoring mode. +2. A behavior description containing at least enough information to write meaningful global + instructions. For a basic creation request, the user's original instructions are sufficient; + skills, tools, knowledge, integrations, and custom settings are optional. -If the target project directory or describer report is missing, ask for the missing value and stop. If source files or unsupported action details are missing, continue with reasonable assumptions and list the gap in the final response. +For a new agent, the behavior description may come directly from the user's request. A Copilot Studio Describer report is not required. + +For a migration, also require: + +1. Detailed behavior report from the Copilot Studio Describer. +2. Target migrated agent display name. +3. Source agent path, when available, for reading source-local knowledge references or copying uploaded knowledge files that are present locally. +4. Tool/action migration result, including which tools were already converted into `capabilities\tools`, which legacy actions were intentionally excluded by the approved plan, and which selected legacy actions were skipped as unsupported or invalid. + +If the target directory has not been initialized, stop and route initialization to the Copilot Studio Init agent. Do not imitate initialization by creating `settings.mcs.yml`, `agent.sync.yaml`, or `.mcs\` manually. + +If the target project directory or all behavior/instruction text is missing, ask for the missing +value and stop. Do not require a detailed component specification for a new agent. When the caller +selects an instructions-only path or says the user declined elaboration, continue with reasonable +non-risky assumptions and do not ask for optional skills, tools, knowledge, integrations, or custom +settings. For a migration, also stop when the describer report is missing. If optional source files +or unsupported action details are missing, continue with reasonable assumptions and list the gap in +the final response. + +## Project preflight + +Before writing YAML: + +1. Confirm that the target directory contains `settings.mcs.yml` and `agent.sync.yaml`. +2. Read `settings.mcs.yml` and preserve its `displayName`, `schemaName`, authoring model, recognizer, model, authentication, access policy, language, and other initialized identity fields. +3. Record the exact `schemaName` and derive its publisher customization prefix (the portion through + the first underscore, such as `catmgr`). Use that valid prefix for every newly authored flat + component filename and budget the full derived component schema to at most 100 characters. +4. Confirm that `.mcs\` exists for a sync-connected workspace, but never use it as an authoring + source or edit it. The create workflow may inspect `.mcs\conn.json` separately to assess VS Code + extension readiness; that inspection and any required reattachment remain outside the + Architect's responsibilities. +5. Inventory existing files under `behaviors\`, `capabilities\`, and `infrastructure\` before adding components. Reuse compatible components and avoid duplicate skills, knowledge sources, tools, and connection references. +6. Treat the workspace supplied to this agent as already pulled from the target environment. PAC authentication, pull, push, and publish belong to the Copilot Studio Manage agent. The required lifecycle is: initialize -> pull -> architect edits -> push. Publishing remains a separate, explicitly confirmed action. ## Edit scope @@ -104,6 +138,7 @@ If the target project directory or describer report is missing, ask for the miss - Never modify the source agent folder. - Do not hand-edit files under `.mcs\`; they are CLI-managed state. - Preserve initialized identity fields such as `schemaName`, environment binding, connection references, template, language, and generated IDs unless the user explicitly asks for an identity change. +- Do not create or replace `agent.sync.yaml`; it is a CLI workspace marker. - Preserve any already migrated files under `capabilities\tools`. Read them so instructions and skills can reference the available tools correctly. Do not overwrite connector or MCP tool YAML unless you have complete, concrete YAML fields and the change is required by the migration. Treat actions intentionally excluded by the approved migration plan as out of scope, not as missing tools to recreate. - Do not create design notes, migration plans, or JSON meta-description files in the project. The final implementation artifact is the YAML component set. @@ -134,7 +169,35 @@ mcs.metadata: kind: ``` -Use descriptive, orchestration-friendly metadata. Component files should use a slugified component name plus a short unique suffix, for example `answer-refund-questions_a1B2c3.mcs.yml`. Keep existing generated suffixes when editing existing files. +Use descriptive, orchestration-friendly metadata. + +Every newly authored bot-component filename must start with the valid Dataverse customization prefix +derived from the agent `schemaName`: + +```text +__.mcs.yml +``` + +For example, when `schemaName` is `catmgr_WeatherInformationAssistant`: + +```text +catmgr_getweather_a1B2c3.mcs.yml +``` + +Do not create an unprefixed file such as `get-weather_a1B2c3.mcs.yml`. Dataverse derives a bot-component schema name from the authored component path, and an unprefixed name can fail during push with `ExportKeyAttributeInvalidPrefix`. + +Also enforce Dataverse's 100-character maximum for `botcomponent.schemaname`. Before writing a flat +component, conservatively require: + +```text +length( + "." + ) <= 100 +``` + +Shorten the descriptive slug when necessary. Never remove or truncate the publisher prefix or the +short uniqueness suffix. Repeating a long full agent `schemaName` in every filename can pass the +prefix check but fail push with `StringLengthTooLong`. + +Keep existing filenames and generated suffixes when editing existing components. After a push and pull, PAC may normalize an inline skill into a directory such as `behaviors\\skill.mcs.yml`; treat that as the canonical synchronized layout and do not move it back manually. ## Settings YAML @@ -193,6 +256,16 @@ toolInputs: Only create or substantially modify tool YAML when the describer report or migrated action output provides complete connector/MCP details such as connector ID, operation ID, auth mode, inputs, outputs, and connection reference. Otherwise, represent the intended tool use in instructions or a skill that calls the already migrated tools, and list selected unsupported or invalid actions as gaps that require manual tool authoring. Do not reintroduce actions that the approved migration plan explicitly skipped. +For new agents, apply the same rule: do not invent a `connectionReference`, connector ID, operation ID, input shape, or output shape. A connector-backed tool is usable only when the target environment has the required connection and the project has a valid connection reference. + +Capabilities that promise current or live data should normally use a tool. A public website knowledge source may be used only as a best-effort grounding fallback when the URL is a valid Copilot Studio public-website source and the requested experience does not require API-level reliability. When using that fallback: + +- state the limitation in the final response +- instruct the agent to search the source before answering +- instruct the agent never to fabricate current data +- instruct the agent to report retrieval failure clearly +- do not describe the website source as equivalent to an authenticated connector or API + ## Skill YAML Skill components live in `behaviors\`. Create focused skills there for reusable multi-step @@ -301,13 +374,29 @@ Does this need to manipulate data or execute logic in a complex way? --- -# 7. Extraction process +# 7. Extraction and implementation process The mechanism should run through these phases. +## Phase 0: Preflight the initialized workspace + +Apply the project preflight above. Read the exact `schemaName`, inventory existing components, and verify that the workspace has the modern CLI layout before designing or writing files. + ## Phase 1: Normalize the idea -Normalize into intents, extract constraints, reason about edge cases, identify user stories, and ask clarifying questions if needed. +Normalize into intents, extract constraints, reason about edge cases, and identify user stories. +Reuse every relevant detail already present in the request. When guided scenario design is desired, +ask targeted questions only for material gaps in: + +- Skills +- Tools and workflows +- Instructions +- Data and knowledge, including concrete SharePoint locations, URLs, or files +- Settings + +Do not repeat answered questions or make every category mandatory. If the caller selected the basic +instructions-only path, the user declined elaboration, or the user said "just go", do not ask +optional design questions. ## Phase 2: Classify each intent @@ -321,6 +410,19 @@ The mechanism should infer or ask about integrations. Then it should think what Write or update the components stated above, with detailed descriptions, metadata, and instructions. Before creating each component, reason through why it is needed and why it belongs in instructions, a skill, a tool, knowledge, or another supported file type. Do not put reasoning notes in project files. +Always implement meaningful global instructions. Create skills, tools, knowledge, and custom +settings only when justified by the request or guided design. Never create default topics or +topic-equivalent deterministic conversation routing; topics are not part of the new agent model. + +For every new component: + +1. Choose the correct component directory. +2. Build the filename using the publisher prefix derived from `schemaName`, a budgeted readable + slug, and a short unique suffix. +3. Add the required `mcs.metadata` block and component `kind`. +4. Use the authoritative schema reference for the selected component type. +5. Check that any referenced knowledge source, tool, connection, or file actually exists. + ## Phase 5: Check for overlap Before finalizing, detect ambiguous components. @@ -341,11 +443,27 @@ Skill: explain-insurance-coverage The skill uses the knowledge, but the knowledge is the source of facts. +## Phase 6: Run structural checks + +Before returning control to the caller: + +1. Confirm that `settings.mcs.yml` remains present and retains initialized identity fields. +2. Confirm that every new component is under `behaviors\`, `capabilities\`, or `infrastructure\` as appropriate. +3. Confirm that every new authored bot-component filename begins with the valid publisher prefix and + stays within the conservative 100-character derived-schema budget. +4. Confirm that every authored component except `settings.mcs.yml` has `mcs.metadata` and `kind`. +5. Confirm that no `.mcs\` file or `agent.sync.yaml` was edited. +6. Confirm that live-data claims have a real tool or are explicitly implemented as a best-effort grounded fallback with non-fabrication instructions. +7. Report the exact files changed so the Manage agent can push them. + --- # 8. How to handle ambiguous natural language -Natural-language specs are often vague. The mechanism should ask clarifying questions, and/or make reasonable assumptions (surfacing them). +Natural-language specs are often vague. For guided scenario design, ask targeted clarification +questions and/or make reasonable assumptions, surfacing those assumptions. Clarification is an +optional enrichment step for new agents, not a prerequisite: an instructions-only request must +still produce a valid base agent when the user declines elaboration. Example input: @@ -451,6 +569,11 @@ Before reporting completion, the mechanism should check the generated YAML imple | Overlap | Are similar skills/tools clearly distinguished? | | Missing integrations | Are unknown systems listed as open questions? | | Evals | Are there realistic prompts for the core behaviors? | +| Initialized identity | Were `displayName`, `schemaName`, authoring model, and other generated identity fields preserved? | +| Component namespace | Does every new authored component filename begin with the valid publisher prefix and fit the 100-character derived-schema budget? | +| Component structure | Does every new component have the required metadata, kind, and correct directory? | +| CLI state safety | Were `.mcs\` and `agent.sync.yaml` left untouched? | +| Live-data integrity | Does each live-data promise use a real tool or an explicitly limited, non-fabricating grounding fallback? | --- @@ -460,8 +583,9 @@ Keep the final answer short and factual. Include: 1. The target project directory. 2. The target YAML files or component areas changed. -3. Migrated tools that were preserved and referenced. -4. Assumptions made and unresolved gaps, especially selected unsupported legacy actions, invalid selected actions, or missing knowledge sources. +3. For migrations, migrated tools that were preserved and referenced. +4. For new agents, any required connector, connection reference, or external integration that was unavailable. +5. Assumptions made and unresolved gaps, especially selected unsupported legacy actions, invalid selected actions, missing knowledge sources, or best-effort live-data fallbacks. Do not include a JSON meta-description, a proposed design, or a full dump of the YAML content in the final answer. diff --git a/agents/copilot-studio-init.md b/agents/copilot-studio-init.md index 36c586b..4f3b8e9 100644 --- a/agents/copilot-studio-init.md +++ b/agents/copilot-studio-init.md @@ -1,17 +1,17 @@ --- name: Copilot Studio Init description: > - Deterministic setup agent for Copilot Studio migrations. Runs the single `pac copilot init` command that creates an empty CLI-authoring Copilot Studio agent project in the target environment. Use only for initializing migration target files. + Deterministic setup agent for new and migrated Copilot Studio projects. Runs the single `pac copilot init` command that creates an empty CLI-authoring Copilot Studio agent project in the target environment. --- # Copilot Studio Init Agent -You are a deterministic setup specialist for Copilot Studio migration targets. +You are a deterministic setup specialist for new and migrated Copilot Studio projects. Your only responsibility is to create the empty target agent project that later agents will fill. ## Scope boundaries -- You only initialize a new migration target. Do not describe, design, migrate, edit, rewrite, validate, test, publish, or improve agent behavior. +- You only initialize a new target project. Do not describe, design, migrate, edit, rewrite, validate, test, publish, or improve agent behavior. - Do not modify the source agent. - Do not modify the newly initialized target agent after creation. - Do not invent environment IDs, display names, publisher prefixes, authoring modes, or output folders. Derive them exactly as specified below. @@ -20,13 +20,13 @@ Your only responsibility is to create the empty target agent project that later You need these inputs before doing any setup: -1. Target migrated agent display name. +1. Target agent display name. 2. Target project directory. 3. Target environment ID. You may also receive a publisher prefix for the solution and components (the caller-approved customization prefix, e.g. `zava`). If the caller does not provide one, fall back to the default `catmgr`. -The caller should provide the target display name explicitly. In migration workflows, the new target display name is usually derived from the source agent display name by appending ` (migrated)` to it. For example, if the source agent display name is `MyAgent`, the target display name should be `MyAgent (migrated)`. +The caller should provide the target display name explicitly. For a migration, the display name is usually derived from the source agent display name by appending ` (migrated)`. For a new project, the create workflow derives or collects the display name before invoking this agent. If the target display name, target project directory, or target environment ID is still missing, ask for the missing value and stop until it is provided. @@ -38,7 +38,7 @@ Use these constants exactly unless the user explicitly gives different values: |---|---| | Publisher prefix | Provided by caller; defaults to `catmgr` when not supplied | | Authoring mode | `cli-copilot` | -| Target display name | Provided by caller, usually ` (migrated)` | +| Target display name | Provided by caller | | Target project directory | Provided by caller | | Target environment ID | Provided by caller | @@ -47,7 +47,7 @@ Use these constants exactly unless the user explicitly gives different values: 1. Set the shell to fail on errors before running the command. 2. Run exactly one creation command: `pac copilot init`. 3. Before running the command, confirm that the target project directory does not already exist. -4. If the target project directory already exists, stop and report the error, asking for the user intervention to delete such folder. Tell the user that the migration might already have been performed. In such case, the user either needs to delete the previous migrated agent or modify it (without running the /migrate command). Do not overwrite or delete the folder by yourself. +4. If the target project directory already exists, stop and report the error. Do not overwrite or delete the folder. Tell the caller to inspect it and either resume the existing sync-connected project, choose another target directory, or explicitly clean up an incomplete directory before retrying. 5. After the command completes, confirm that the target project directory exists and contains `settings.mcs.yml`. 6. If the expected `settings.mcs.yml` is missing, stop immediately and report what was missing. 7. This operation is not idempotent: each successful run creates a new empty Copilot Studio agent project. @@ -60,7 +60,7 @@ Below is the authoritative PowerShell sequence. Preserve the command arguments e ```powershell $ErrorActionPreference = "Stop" -$TARGET_DISPLAY_NAME = "" +$TARGET_DISPLAY_NAME = "" $TARGET_PROJECT_DIR = "" $ENVIRONMENT_ID = "" $PUBLISHER_PREFIX = "" @@ -105,4 +105,4 @@ Keep the final answer short and factual. Include: 4. The publisher prefix used. 5. Confirmation that `pac copilot init` completed. -Do not include migration design, source-agent analysis, or recommendations. +Do not include agent design, source-agent analysis, or recommendations. diff --git a/commands/create.md b/commands/create.md new file mode 100644 index 0000000..77c2178 --- /dev/null +++ b/commands/create.md @@ -0,0 +1,14 @@ +--- +description: Create a new Copilot Studio CLI agent project with the reusable create-copilot-studio-agent skill. +argument-hint: Business problem, scenario, or agent instructions; optionally include project identity and component details +allowed-tools: Skill, Bash(pac), Read, Write, Glob, Grep, Task +--- + +# Create a Copilot Studio Agent + +Initial request: $ARGUMENTS + +Load and follow the **`create-copilot-studio-agent`** skill. Pass the complete initial request above +as the creation request. The skill is the authoritative workflow; do not duplicate, abbreviate, or +replace its initialization, structural validation, synchronization, error-handling, or publication +rules. diff --git a/skills/create-copilot-studio-agent/SKILL.md b/skills/create-copilot-studio-agent/SKILL.md new file mode 100644 index 0000000..b8446f6 --- /dev/null +++ b/skills/create-copilot-studio-agent/SKILL.md @@ -0,0 +1,287 @@ +--- +name: create-copilot-studio-agent +description: Create a new Microsoft Copilot Studio CLI-authored agent project from a natural-language description, using the proper settings, behaviors, capabilities, infrastructure, and PAC synchronization structure. Use when the user asks to create, scaffold, initialize, or build a new MCS or Copilot Studio agent/project. +--- + +# Create a Copilot Studio Agent + +Create a new **Copilot Studio CLI-authored agent** from a natural-language business problem, +scenario, or set of instructions. Reuse details from the initial request, offer optional guided +design, collect the required project identity, initialize a sync-connected workspace, implement the +agent with the modern YAML structure, validate it, and push it to Copilot Studio. + +This skill creates and pushes the agent, but does not publish it unless the user explicitly requests +publication and confirms the publication warning. + +## Required collaborators + +Use these plugin agents in this order: + +1. **Copilot Studio Init** — creates the empty sync-connected project. +2. **Copilot Studio Manage** — pulls before editing, pushes afterward, and performs the final pull. +3. **Copilot Studio Architect** — implements the requested behavior in the initialized project. + +Do not replace their responsibilities with improvised PAC commands or hand-created workspace files. + +## Process + +### 1. Parse the request + +Extract any values already supplied by the user: + +- Business problem, scenario, or agent instructions. +- Agent display name. +- Target project directory. +- Target environment ID or absolute Dataverse HTTPS URL. +- Publisher customization prefix. + +Treat behavioral text in the initial request as the initial agent instructions. Do not ask the user +to repeat or rephrase information they already supplied. + +Extract available design details into these areas: + +- **Skills** — reusable procedures or expert workflows. +- **Tools and workflows** — external actions, live data, APIs, connectors, agent flows, or other + integrations. +- **Instructions** — role, primary jobs, intended users, tone, clarification and confirmation + behavior, safety, privacy, and escalation constraints. +- **Data and knowledge** — public websites, SharePoint, OneDrive, uploaded files, or other grounding + sources. +- **Settings** — authentication, access, language, model, Work IQ, and other agent-level settings. + +Do not require the user to name YAML components. The Architect decides whether each requirement +belongs in instructions, knowledge, tools, or skills. + +### 2. Choose the creation depth + +Support both of these paths: + +1. **Basic instructions-only path.** This is the minimum valid creation path. Use the instructions + already present in the request, make reasonable non-risky assumptions, and create the base agent + without requiring skills, tools, workflows, knowledge sources, or custom settings. Use this path + when the user says "just go", asks to skip questions, declines elaboration, or otherwise requests + immediate creation. +2. **Guided scenario-design path.** Prefer this path when the user wants help shaping the agent or + when targeted clarification would materially improve the result. Ask one concise, grouped set of + questions only for important missing details across Skills, Tools and workflows, Instructions, + Data and knowledge, and Settings. In particular, clarify concrete data sources such as + SharePoint locations, public URLs, or local files when grounding is requested. + +The guided path is optional, not a prerequisite for creation. Do not force the user to answer every +category, ask again for details already present in the initial request, or block an +instructions-only agent because richer components were not specified. Operational values required +to initialize the project, such as the environment, may still need to be collected. + +Record which path is being used and any assumptions. Never create default topics: topics are not +part of the new agent model. Translate relevant requirements into instructions, skills, tools, +knowledge, or supported settings instead. + +### 3. Resolve project identity + +Resolve these values before initialization: + +1. **Display name.** Use an explicit user-provided name when present. Otherwise derive a concise, + human-readable name from the behavior description and show it with the other resolved values. +2. **Project directory.** Use an explicit path when present. Otherwise derive a slugified directory + under the current working directory. Resolve it to an absolute path. +3. **Environment.** Require an environment ID or absolute Dataverse HTTPS URL. If the request + contains a Copilot Studio URL with `/environments//`, extract the environment ID. + Do not silently select an environment when several are plausible. +4. **Publisher prefix.** Use an explicit value when present. Otherwise default to `catmgr`. Validate + it: 2-8 alphanumeric characters, starts with a letter, and does not start with `mscrm` + case-insensitively. Preserve the user's casing. + +Ask only for values that cannot be safely derived. Before initialization, state the resolved display +name, absolute project directory, environment, and publisher prefix. + +### 4. Protect the destination + +Check the target project directory: + +- If it does not exist, continue. +- If it contains `settings.mcs.yml`, `agent.sync.yaml`, and `.mcs\`, treat it as an existing + sync-connected CLI workspace. Do not initialize over it. Ask whether to resume or use another + directory. +- If it exists but is incomplete or is not a Copilot Studio workspace, stop. Do not delete, + overwrite, or merge into it. Ask the user to choose another directory or explicitly clean up the + existing path themselves. + +### 5. Initialize the workspace + +Delegate to **Copilot Studio Init** with exactly: + +- display name +- absolute target project directory +- environment ID or URL +- validated publisher prefix + +The Init agent must run one `pac copilot init` command with `--authoring-mode cli-copilot`. + +After it completes, verify: + +- `\settings.mcs.yml` exists +- `\agent.sync.yaml` exists +- `\.mcs\` exists +- `settings.mcs.yml` contains the expected display name and a nonempty `schemaName` +- `configuration.recognizer.kind` is `CLICopilotRecognizer` or `CLIAgentRecognizer` +- `configuration.authoringModel` is `CliCopilot` + +If initialization fails or a marker is missing, stop and report the exact failure. Never create the +missing workspace files manually. + +Read `.mcs\conn.json` only to assess client compatibility; never edit it. Record whether +`AgentManagementEndpoint` is a nonempty URL. + +- A PAC-initialized or PAC-cloned workspace can have `AgentManagementEndpoint: null`. PAC pull and + push may still work because PAC uses its external auth profile, but the Copilot Studio VS Code + extension rejects that workspace as having incomplete connection settings. +- Do not repair the field manually and do not repeatedly clone with PAC; PAC can reproduce the same + null endpoint. +- Mark the workspace as requiring extension reattachment. Tell the user to update or reload the + Copilot Studio extension and run **Copilot Studio: Reattach Agent** from the VS Code Command + Palette, selecting the same environment and agent. Current extension builds can also attempt an + on-demand endpoint repair for PAC-cloned workspaces. +- If reattachment is unavailable or fails, use the extension's Clone Agent workflow to clone the + already-pushed remote agent into a new folder, then open that extension-created workspace. + +Missing `AgentManagementEndpoint` is a VS Code extension-readiness warning, not proof that the PAC +workspace or remote agent is invalid. Continue the PAC-based creation workflow, but do not report +the project as extension-ready until reattachment or an extension clone supplies complete metadata. + +### 6. Pull before implementation + +Delegate a pull to **Copilot Studio Manage** for the initialized project. Do not start implementation +until pull completes successfully. + +### 7. Build the implementation brief + +Turn the request into a concrete brief for the Architect. Include: + +- exact target project directory +- new-agent mode, not migration mode +- selected creation depth: basic instructions-only or guided scenario design +- resolved display name and `schemaName` +- the original instructions, preserving all useful details from the initial request +- requested Skills +- requested Tools and workflows, including live-data and external-action requirements +- Instructions covering role, users, capabilities, tone, clarification rules, and safety constraints +- Data and knowledge, including concrete SharePoint locations, URLs, or local files +- requested Settings +- existing tools, knowledge, skills, and connections in the workspace +- assumptions and unresolved integration details + +For the basic path, require meaningful global instructions but do not invent skills, tools, +knowledge sources, custom settings, connections, or topics merely to make the project look more +complete. + +For current or live data, require a real tool when API-level reliability is expected. Do not claim a +connector-backed capability is implemented unless the environment has the required connection and +the project has a valid connection reference. A public website knowledge source is only a +best-effort fallback and must be identified as such. + +### 8. Implement with the Architect + +Delegate the brief to **Copilot Studio Architect**. Require it to write the complete YAML +implementation into the initialized project, not merely return a design. + +The Architect must: + +- preserve initialized identity and synchronization fields +- always write meaningful global behavior into `settings.mcs.yml`, including for the basic + instructions-only path +- place reusable procedures under `behaviors\` +- place knowledge under `capabilities\knowledge\` +- place tools under `capabilities\tools\` only when complete tool and connection metadata exists +- create only components justified by the request or guided design; do not create default topics or + speculative skills, tools, knowledge, or settings +- use the publisher customization prefix from `schemaName` for every newly authored flat component + filename and keep the complete derived component schema within Dataverse's 100-character limit +- leave `.mcs\` and `agent.sync.yaml` untouched +- report exact files changed and unresolved gaps + +If the Architect returns only a proposal or makes no concrete file changes, creation is incomplete. + +### 9. Run the structural gate + +Before push, inspect the resulting workspace and block on any failure: + +1. `settings.mcs.yml`, `agent.sync.yaml`, and `.mcs\` still exist. +2. Initialized `displayName`, `schemaName`, recognizer, and authoring model are preserved. +3. `settings.mcs.yml` contains meaningful instructions derived from the user's request. +4. No default topic or topic-equivalent routing components were created. +5. Every new component is under `behaviors\`, `capabilities\`, or `infrastructure\`. +6. Every authored `*.mcs.yml` component except `settings.mcs.yml` contains `mcs.metadata` and + `kind`. +7. Every new flat bot-component filename starts with the publisher customization prefix derived from + `schemaName`, followed by `_` or `.`. For example, a `catmgr_...` agent uses + `catmgr_getweather_a1B2c3.mcs.yml`. Do not repeat a long full agent `schemaName` in every filename + when that would make the derived Dataverse component schema too long. +8. For each new flat component, conservatively calculate + ` + "." + ` and require at most 100 characters. + Shorten the slug, never the publisher prefix or uniqueness suffix, when over budget. +9. Knowledge components follow `reference/knowledge-schema.md`, including its filename budget. +10. No connector tool contains an invented or placeholder `connectionReference`, connector ID, + operation ID, input, or output. +11. Live-data behavior uses a real tool or is explicitly described as a best-effort grounded + fallback that must not fabricate results. +12. `.mcs\` and `agent.sync.yaml` were not authored or modified by the Architect. +13. `.mcs\conn.json` was inspected without modification. If `AgentManagementEndpoint` is null or + empty, record that VS Code extension reattachment is required; do not block PAC push solely for + this reason. + +If a filename lacks the required namespace, rename it before push: + +```text +__.mcs.yml +``` + +Never wait for Dataverse to discover a predictable prefix error. + +### 10. Push and verify + +Delegate push to **Copilot Studio Manage**. It must follow its normal pull-before-push rules and +surface conflicts rather than overwrite remote changes. + +After a successful push, delegate one final pull: + +- Zero applied changes confirms local and remote synchronization. +- If remote changes are applied, inspect them and confirm that the authored components still exist + in PAC's canonical layout. + +Do not publish unless explicitly requested. Publication requires the Manage agent's standard warning +and explicit confirmation. + +### 11. Report + +Report: + +- display name +- project directory +- environment +- agent ID and schema name when available +- creation depth used and assumptions made +- component areas and principal files created +- push result +- final synchronization result +- unresolved connectors, knowledge, or live-data limitations +- VS Code extension readiness, including whether **Copilot Studio: Reattach Agent** is required +- publication status + +Do not claim an unavailable integration works. Do not dump complete YAML unless requested. + +## Resumability and errors + +- Preserve a successfully initialized workspace when a later phase fails. +- Resume an existing sync-connected workspace only after the user chooses to resume it. +- If files already exist, inspect and continue from the first incomplete phase rather than creating + duplicate components. +- On `ExportKeyAttributeInvalidPrefix`, correct new component paths to start with the valid + publisher customization prefix before retrying. +- On `StringLengthTooLong` for `botcomponent.schemaname`, shorten component filename slugs until the + conservative derived-name calculation is at most 100 characters. +- On push conflicts, use the Manage agent's pull-and-resolve workflow. +- If a connector connection is unavailable, do not invent it. Report the gap and either omit that + capability or use a clearly disclosed best-effort knowledge fallback when appropriate. +- If VS Code reports incomplete `.mcs\conn.json` settings and `AgentManagementEndpoint` is null, + direct the user to **Copilot Studio: Reattach Agent** or the extension's Clone Agent workflow. + Never hand-edit `.mcs\conn.json`.