diff --git a/.github/skills/design-author/SKILL.md b/.github/skills/design-author/SKILL.md new file mode 100644 index 00000000..88f277fc --- /dev/null +++ b/.github/skills/design-author/SKILL.md @@ -0,0 +1,217 @@ +--- +name: design-author +description: Create detailed design specs for Android Auth features and open them as PRs in the AuthLibrariesApiReview ADO repo. Use this skill when a developer describes a feature at a high level and wants a detailed design document / implementation spec created before coding begins. Triggers include "design this feature", "create a design spec", "write a design doc", "create an implementation plan", "I need a design review for", or any request to produce a formal design document for team review before implementation. +--- + +# Design Author + +Create detailed design specs for Android Auth features, save them locally in `design-docs/`, +and open PRs in the `AuthLibrariesApiReview` ADO repo for team review. + +## Prerequisites + +- `design-docs/` repo cloned locally (run `git droidSetup` or clone manually from + `https://dev.azure.com/IdentityDivision/DevEx/_git/AuthLibrariesApiReview`) +- ADO MCP Server running with `repositories` domain enabled (configured in `.vscode/mcp.json`) + +## Design Docs Context + +The `design-docs/` folder contains ~150+ design specs for the Android Auth platform. + +**Important caveats about existing designs:** +- Designs on `main` may be outdated — last-minute PR discussions often cause code to deviate. + Always verify proposed patterns against the **current codebase**, not just existing designs. +- Some designs exist only as unmerged PRs. Check open PRs in the repo for in-progress thinking. +- Use existing designs as **style reference and historical context**, not as ground truth for current behavior. + +## Design Spec Template + +Follow the repo's template at `design-docs/Template/template.md`. Key sections: + +1. **Title** — Feature name +2. **Applicable to and priority** — Platform table (focus on Android column) +3. **Components** — Which repos/modules (MSAL, Common, Broker, etc.) +4. **Problem description** — User problem, business context, examples +5. **Requirements (Must)** — Key functional requirements +6. **System Qualities (Must)** — Performance, telemetry, security, supportability +7. **Goals & Principles (Desired)** — Aspirational design goals +8. **Solution options** — Multiple options with pseudo code, pros/cons +9. **Solution Decision** — Recommended option with reasoning + +For Android-specific designs, also include: +- **API surface** — Public/internal classes, methods, parameters +- **Data flow** — Request/response flow across repos (MSAL → Common → Broker → eSTS) +- **IPC contract changes** — Any AIDL/Bundle schema changes +- **Feature flag** — Flag name and gating strategy +- **Telemetry** — Span names, attributes, success/failure signals +- **Testing strategy** — Unit test approach, instrumented test needs, E2E coverage +- **Rollout plan** — Feature flag stages, ECS configuration +- **Cross-repo impact** — Which repos need changes and in what order + +## Workflow + +### Step 1: Understand the Feature + +Gather from the developer: +1. What the feature does and why it's needed +2. Which auth flows it affects +3. Scope boundaries (in/out) +4. Any existing designs to reference (check `design-docs/` for related specs) + +### Step 2: Research the Codebase + +Use the `codebase-researcher` skill to: +- Understand how related functionality currently works +- Identify which repos/files would be affected +- Find existing patterns to follow (feature flags, error handling, telemetry, IPC contracts) +- Check for any existing design docs in `design-docs/` on the same topic + +### Step 3: Research Existing Designs + +Search the `design-docs/` folder for related designs: +``` +# Look for related designs +ls design-docs/ | grep -i "" +# Read relevant designs for patterns and prior art +``` + +Android-specific designs are prefixed with `[Android]`. Pay attention to: +- Similar feature designs for structural patterns +- The level of detail expected +- How they handle cross-repo concerns + +### Step 4: Write the Design Spec + +Create the spec following the template. The file should be created at: +``` +design-docs/[Android] /.md +``` + +Use the standard template sections. For the **Solution options** section: +- Always provide at least 2 options +- Include pseudo code / API signatures for each +- List concrete pros/cons +- Make a clear recommendation in the Solution Decision section + +### Step 5: Present Design for Review + +After writing the spec, **STOP and present choices to the developer**. Do NOT auto-create +a PR or auto-proceed. Present the design summary and these explicit options: + +```markdown +## Design Spec Written: [Feature Name] + +**Local file**: `design-docs/[Android] /.md` + +### Summary +[2-3 sentence summary of the proposed design] + +### Recommended Solution +[Brief description of the recommended option and why] + +--- + +### What would you like to do? + +1. **Review locally first** — I'll open the spec in the editor for you. Use the **+ + icons in the gutter** to add review comments on specific lines, then click the + **status bar button** (bottom right) to submit them. + +2. **Approve and skip PR** — Move directly to PBI planning without creating a design PR. + Say: **"design approved, plan the PBIs"** + +3. **Approve and open draft PR** — Push to AuthLibrariesApiReview repo as a **draft** PR + for team review. + Say: **"open a draft PR"** + +4. **Approve and publish PR** — Push and open a **published** (non-draft) PR for team review. + Say: **"open and publish the PR"** + +5. **Request changes** — Tell me what to change and I'll update the spec. +``` + +**MANDATORY**: Wait for the developer to explicitly choose one of these options. +Do NOT auto-select any option. + +### Step 5a: Local Review Workflow (if developer chooses option 1) + +Open the spec file in the editor for the developer: +```powershell +code "design-docs/[Android] /.md" +``` + +Then tell the developer: +> "The spec is open in the editor. Here's how to review: +> 1. Click the **+ icon** in the gutter next to any line to add a comment +> 2. Type your comment and click **Add Comment** +> 3. Comments auto-collapse — click the line indicator to expand +> 4. When done, click the **status bar button** at the bottom right +> (it shows ‘💬 N Review Comments — Click to Submit’) +> 5. This sends your comments to chat and I'll address each one" + +When the developer submits review comments (via the status bar), the design-reviewer +skill will be triggered automatically. After addressing, return to Step 5 +(present choices again). + +### Step 5b: Push and Create PR (if developer chooses option 3 or 4) + +**Branch naming**: Use the developer's alias (discovered from `git config user.email` or +`.github/developer-local.json`) as the branch prefix: +```powershell +$alias = (git config user.email) -replace '@.*', '' +git checkout -b "$alias/design-" +``` + +```bash +cd design-docs/ +git add "[Android] " +git commit -m "Add design spec: " +git push origin $BRANCH_NAME +``` + +**Create PR via ADO MCP Server** (if `repositories` tools are available): +- Set `isDraft: true` for option 3 (draft), `isDraft: false` for option 4 (published) +- **PR description**: Use actual line breaks or HTML formatting, NOT literal `\n` escape sequences +- Target branch: `main` (or `dev` depending on the repo's default) + +Present the PR link and review instructions: +```markdown +### PR Created +**PR**: [link to PR] +**Status**: Draft / Published + +### How to Review +1. Open the PR link above +2. Use ADO's inline commenting to leave feedback +3. When done, say: **"address my design review comments"** +4. I'll read the PR comments via the ADO MCP server and update the spec + +When the team approves, say: **"design approved, plan the PBIs"** +``` + +### Step 6: Address PR Review Comments + +When the developer asks to address review comments (from ADO PR): + +1. Use the ADO MCP Server repository tools to read PR thread comments +2. For each comment: + - Understand the feedback + - Edit the local design spec to address it + - Reply to the PR thread confirming the resolution +3. Commit and push the updates to the same branch +4. Report a summary of changes made +5. Return to Step 5 (present choices again) + +### Step 7: Proceed to Implementation (on approval) + +When the developer confirms the design is approved: +1. The PR can be completed/merged in ADO +2. Hand off to the `feature-planner` skill for PBI decomposition + +## Integration with Feature Planner + +When the developer confirms the design is approved, the `feature-planner` skill should: +1. Read the approved design spec from `design-docs/` +2. Use it as the primary source for PBI decomposition +3. Reference the design doc PR link in each PBI description +4. Ensure PBI acceptance criteria align with the design's requirements diff --git a/.github/skills/design-reviewer/SKILL.md b/.github/skills/design-reviewer/SKILL.md new file mode 100644 index 00000000..21348aff --- /dev/null +++ b/.github/skills/design-reviewer/SKILL.md @@ -0,0 +1,109 @@ +--- +name: design-reviewer +description: Address review comments on design spec markdown files. Use this skill when a developer has added review comments (via the VS Code Comment API or manually) and wants the AI to address them. Triggers include "address review comments", "handle my review", "review comments on", or any request to process inline review feedback on a design spec. +--- + +# Design Reviewer + +Address review comments on design spec files. + +## How Comments Are Stored + +Comments are stored in a single well-known file: +``` +.github/design-reviews/reviews.json +``` + +The file is a JSON dictionary keyed by relative spec path: +```json +{ + "reviews": { + "design-docs/[Android] Feature Name/spec.md": [ + { "line": 30, "text": "Why is this needed?", "lineContent": "the line text" }, + { "line": 55, "text": "Is this backed by data?", "lineContent": "..." } + ], + "design-docs/[Android] Other Feature/spec.md": [ + { "line": 10, "text": "Clarify this", "lineContent": "..." } + ] + } +} +``` + +## Workflow + +### Step 1: Read Review Comments + +1. Read `.github/design-reviews/reviews.json` +2. If a specific spec path was mentioned in the prompt (e.g., "on `design-docs/.../spec.md`"), + only process comments for that spec. Otherwise process all specs in the file. +3. If the reviews file doesn't exist or has no comments, tell the user: + > "No review comments found. Add comments using the gutter icons in the editor." + +### Step 2: Read Spec Context + +For each comment, read ±5 lines around the comment's line number in the spec file. +This ensures you address the comment with full awareness of context. + +### Step 3: Evaluate Each Comment + +| Comment Type | How to Identify | Action | +|-------------|----------------|--------| +| **Genuine issue** | Points out a bug, inaccuracy, missing info | Update the spec | +| **Improvement** | Suggests better approach, more detail | Update if it improves clarity | +| **Question** | "why?", "what?", "how?" | Answer clearly. Update spec only if the answer should be documented | +| **Challenge** | "Are you sure?", "Is this correct?" | Verify against codebase. Update if wrong, explain if correct | +| **Acknowledgment** | "lol", "nice", "👍" | Acknowledge briefly, no change | + +### Step 4: Apply Changes + +For each comment requiring a spec update: +1. Read the current content around the target line +2. Make the edit using `replace_string_in_file` + +### Step 5: Clean Up reviews.json + +**IMPORTANT**: After addressing all comments for a spec, remove that spec's entry +from `reviews.json`. This prevents comments from being re-processed. + +Read the current `reviews.json`, delete the key for the addressed spec(s), and write +the file back. If no reviews remain, delete the file entirely. + +```python +# Pseudocode for cleanup: +reviews = read_json(".github/design-reviews/reviews.json") +del reviews["reviews"]["design-docs/.../spec.md"] # remove addressed spec +if len(reviews["reviews"]) == 0: + delete_file(".github/design-reviews/reviews.json") +else: + write_json(".github/design-reviews/reviews.json", reviews) +``` + +### Step 6: Present Summary + +Use this exact format: + +```markdown +## Review Comments Addressed + +--- + +### Comment 1: Line N — "[short quote]" + +**Type**: Question / Issue / Improvement / Acknowledgment + +**Action**: [What was done or why no change was needed] + +--- + +### Comment 2: Line N — "..." + +**Type**: ... + +**Action**: ... +``` + +**Rules:** +- Use `###` heading for EVERY comment — never a table +- Use `---` separators between comments +- If a comment was addressed by editing the spec, mention what changed +- If no change needed, explain why diff --git a/.github/skills/feature-planner/SKILL.md b/.github/skills/feature-planner/SKILL.md new file mode 100644 index 00000000..e933ac37 --- /dev/null +++ b/.github/skills/feature-planner/SKILL.md @@ -0,0 +1,225 @@ +--- +name: feature-planner +description: Decompose high-level feature requests into detailed, repo-targeted PBIs for the Android Auth multi-repo project. Use this skill when a developer describes a feature at a high level and wants it broken down into actionable work items. Triggers include "plan this feature", "break this down into PBIs", "decompose this into tasks", "plan implementation for", or any request to turn a feature idea into structured development work items. This skill produces a plan for developer review — actual ADO work item creation is handled by the `pbi-creator` skill. +--- + +# Feature Planner + +Decompose high-level feature descriptions into detailed, repo-targeted PBIs for the Android Auth +multi-repo codebase. Produce a structured plan for developer review. + +**This skill does NOT create ADO work items.** It produces a structured PBI plan that the +developer reviews and approves. Once approved, the `pbi-creator` skill handles ADO work item +creation, iteration/area path discovery, and dependency linking. + +## Prerequisites + +- Developer provides: feature description and priority +- No ADO MCP tools required — this skill is pure planning + +## Repository Routing + +Determine which repo(s) each PBI targets based on the architectural layer: + +| Module | GitHub Repo | When to Target | +|--------|-------------|----------------| +| common | `AzureAD/microsoft-authentication-library-common-for-android` | Shared utilities, IPC logic, data models, base classes, command architecture, token cache, crypto, telemetry primitives, AIDL contracts | +| common4j | (same repo as common) | Pure Java/Kotlin shared logic with no Android dependency | +| msal | `AzureAD/microsoft-authentication-library-for-android` | Client-facing API, AcquireToken/AcquireTokenSilent flows, MSAL-specific controllers, public configuration | +| broker | `identity-authnz-teams/ad-accounts-for-android` | Broker-side auth processing, PRT acquisition/rotation, device registration, eSTS communication, IPC entry points | +| broker4j | (same repo as broker) | Pure Java/Kotlin broker business logic, Protobuf schemas | +| adal | `AzureAD/azure-activedirectory-library-for-android` | Legacy ADAL changes only (rare — maintenance mode, bug fixes only) | + +**Routing heuristic:** +1. If it touches IPC contracts, shared data models, or command architecture → `common` +2. If it's a client-facing API change or MSAL configuration → `msal` +3. If it handles token processing on the broker side, PRT, device registration → `broker` +4. If it's a pure Java utility with no Android dependency → `common4j` or `broker4j` +5. Most features span `common` + one consumer (`msal` or `broker`) — create separate PBIs for each + +## Workflow + +### Step 1: Check for Approved Design + +Before decomposing into PBIs, check if an approved design spec exists: + +1. Check `design-docs/` for a matching design: `ls design-docs/ | grep -i ""` +2. If a design exists and is approved (merged PR), use it as the primary source for decomposition. +3. If no design exists, ask the developer: + > "No design spec found for this feature. Would you like me to create one first using the + > `design-author` skill? This is recommended for features that span multiple repos or + > introduce new APIs." +4. If the developer wants a design first, hand off to the `design-author` skill and stop. +5. For small, single-repo changes (bug fixes, minor enhancements), skip design and proceed directly. + +### Step 2: Understand the Feature + +Gather from the developer: +1. **What** the feature does (functional description) +2. **Why** it's needed (user problem, business reason) +3. **Which flows** it affects (AcquireToken, AcquireTokenSilent, PRT, device registration, etc.) +4. **Scope boundaries** (what's in/out) + +If the feature description is vague, use the `prompt-refiner` skill to structure it first. + +### Step 3: Research Current Implementation + +Use the `codebase-researcher` skill to understand: +- How related functionality currently works +- Which repos/files would need changes +- Existing patterns to follow (feature flags, error handling, telemetry) +- Test patterns in the affected areas + +### Step 4: Decompose into PBIs + +Break the feature into PBIs following these rules: + +1. **One PBI per repo** — never create a PBI that spans multiple repos +2. **Dependency ordering** — if PBI-B depends on PBI-A, document the dependency explicitly +3. **Right-sized** — each PBI should be implementable by a single Copilot coding agent session (roughly 1-3 files changed, <500 lines) +4. **Self-contained description** — the PBI description must contain everything the coding agent needs to implement it without additional context +5. **No local file paths** — never reference `design-docs/` or other local workspace paths in PBI descriptions. The Copilot coding agent runs in a cloud environment with only the target repo cloned — it cannot access the super-repo, design docs, or other sub-repos. Inline all necessary context directly into the PBI description. + +### Step 5: Write PBI Descriptions + +Each PBI description MUST follow the template in `references/pbi-template.md`. + +Key sections: +- **Objective**: What to implement and where +- **Target Repository**: Explicit repo URL + base branch +- **Context**: Why this change is needed, how it fits in the feature +- **Technical Requirements**: Specific implementation guidance +- **Acceptance Criteria**: Concrete, verifiable checklist +- **Dependencies**: Use PBI numbers like "PBI-1", not AB# IDs (those don't exist yet). + The `pbi-creator` skill resolves these to AB# IDs after creation. +- **Files to Modify/Create**: Specific file paths when known + +### Step 6: Present Plan for Review + +Present the full plan using the **exact output format below**. This format is designed to be: +- **Human-readable**: developers can scan the summary table and expand individual PBIs for detail +- **Handoff-ready**: the `pbi-creator` skill can extract all fields needed to create ADO work items + +**IMPORTANT**: Use this exact format — the `pbi-creator` skill depends on it. + +#### Output Format + +The output MUST contain these sections in this order: + +**1. Header with metadata:** + +```markdown +## Feature Plan: [Feature Name] + +**Feature flag**: `[flag_name]` (or "N/A") +**Design PR**: [link] (or "N/A") +**Total PBIs**: [N] +``` + +**2. Dependency graph** (ASCII art showing parallel/sequential relationships): + +```markdown +### Dependency Graph + +PBI-1 (common) → PBI-2 (broker) + PBI-3 (msal) [parallel after PBI-1] + PBI-2 → PBI-4 (broker) +``` + +**3. Summary table** (one row per PBI, for quick scanning): + +```markdown +### Summary Table + +| PBI | Title | Repo | Module | Priority | Depends On | +|-----|-------|------|--------|----------|------------| +| PBI-1 | [title] | common | common4j + common | P1 | None | +| PBI-2 | [title] | broker | broker4j | P1 | PBI-1 | +| PBI-3 | [title] | msal | msal | P2 | PBI-1 | +``` + +**4. Dispatch order** (sequenced for the `pbi-dispatcher` skill): + +```markdown +### Dispatch Order + +1. Dispatch **PBI-1** first (no blockers) +2. After PBI-1 merges → dispatch **PBI-2** and **PBI-3** in parallel +3. After PBI-2 merges → dispatch **PBI-4** +``` + +**5. PBI details** — one block per PBI with metadata header + full description: + +Each PBI detail block MUST have this structure: + +```markdown +--- + +#### PBI-1: [Title] + +| Field | Value | +|-------|-------| +| **Repo** | `[org/repo-name]` | +| **Module** | `[module]` | +| **Priority** | P[1-3] | +| **Depends on** | None / PBI-X | +| **Tags** | `ai-generated; copilot-agent-ready; [feature-tag]` | + +##### Description + +[Write the full PBI description here in PLAIN MARKDOWN — NOT HTML. +This section should contain: Objective, Context, Technical Requirements, +Acceptance Criteria, Files to Modify, Dependencies — per pbi-template.md. +The pbi-creator skill will convert this to HTML when creating ADO work items.] +``` + +**Why this structure?** +- The **metadata table** above the description lets the developer quickly scan each PBI. +- The **description in plain markdown** renders cleanly in VS Code chat (unlike HTML tags + like `
` or `

` which show as raw text in chat). +- The `pbi-creator` skill converts the markdown description to HTML when creating ADO work items. +- The **Summary Table** gives the developer a bird's eye view to approve the breakdown before + seeing any details. + +**IMPORTANT**: Do NOT use HTML tags (`
`, ``, `

`, `

`, `

    `, etc.) +in the plan output. VS Code chat renders markdown only — HTML tags appear as raw text and +make the output unreadable. Use standard markdown formatting instead. + +**6. Notes** (cross-repo coordination, external team notifications, etc.): + +```markdown +### Notes + +- [Cross-repo coordination needed] +- [OneAuth team notification if applicable] +``` + +**7. Handoff prompt** — always end with: + +```markdown +### Next Step + +> Plan approved? Say **"create the PBIs"** to trigger the `pbi-creator` skill, +> which will discover your ADO area path and iteration, then create all work items. +``` + +## Common Patterns + +### Single-Repo Feature +Most bug fixes and small features only touch one repo. Create a single PBI. + +### Two-Repo Feature (Common + Consumer) +The most common multi-repo pattern: +1. PBI-1: Add shared logic/contract in `common` +2. PBI-2: Consume from `msal` or `broker` + +### Three-Repo Feature (Common + Broker + MSAL) +For end-to-end features affecting the full auth flow: +1. PBI-1: Add shared contract/data model in `common` +2. PBI-2: Implement broker-side processing (depends on PBI-1) +3. PBI-3: Implement MSAL client-side API (depends on PBI-1) +4. PBI-4: (optional) Integration test PBI + +### Feature Flag Convention +All PBIs for a feature should use the **same feature flag name** across repos: +- Flag name format: `ExperimentationFeatureFlag.` +- Include the flag name in each PBI description diff --git a/.github/skills/feature-planner/references/dispatch-workflow.md b/.github/skills/feature-planner/references/dispatch-workflow.md new file mode 100644 index 00000000..bdd8fd52 --- /dev/null +++ b/.github/skills/feature-planner/references/dispatch-workflow.md @@ -0,0 +1,154 @@ +--- +name: pbi-dispatcher +description: > + Dispatch Azure DevOps PBIs to GitHub Copilot coding agent for autonomous implementation. + Use this skill when PBIs have been created (by the feature-planner or manually) and you + want to send them to Copilot coding agent to generate PRs. Triggers include "dispatch PBIs + to agent", "assign to Copilot", "send work items to coding agent", "kick off agent + implementation", or any request to have Copilot coding agent pick up and implement + Azure DevOps work items. +--- + +# PBI Dispatcher + +Dispatch Azure DevOps PBIs to GitHub Copilot coding agent by creating GitHub Issues +and assigning them to `copilot-swe-agent[bot]`. + +## Prerequisites + +- **ADO MCP Server** must be running (for reading PBI details) +- **GitHub CLI** (`gh`) must be authenticated with access to target repos +- PBIs must exist in ADO with tag `copilot-agent-ready` +- Target repos must have Copilot coding agent enabled + +## Dispatch Workflow + +### Step 1: Identify PBIs to Dispatch + +Query ADO for PBIs ready for dispatch. Use the ADO MCP Server to: +1. List work items tagged `copilot-agent-ready` in `IdentityDivision/Engineering` +2. Filter by iteration/sprint if specified +3. Sort by dependency order (PBIs with no dependencies first) + +### Step 2: Parse Target Repository + +Extract the target repository from the PBI description. The PBI template includes a +"Target Repository" section with the format: +- `AzureAD/microsoft-authentication-library-common-for-android` → common +- `AzureAD/microsoft-authentication-library-for-android` → msal +- `identity-authnz-teams/ad-accounts-for-android` → broker +- `AzureAD/azure-activedirectory-library-for-android` → adal + +### Step 3: Check Dependencies + +Before dispatching a PBI: +1. Check if it has dependencies listed (other AB# IDs) +2. If dependencies exist, verify their PRs have been merged +3. If dependencies are not yet merged, skip and flag for later dispatch + +### Step 4: Create GitHub Issue + +For each ready PBI, create a GitHub Issue in the target repo: + +**Issue Title**: Same as PBI title + +**Issue Body** (template): +```markdown +## Auto-dispatched from Azure DevOps + +**Work Item**: Fixes AB# +**Priority**: +**Iteration**: + +--- + + + +--- + +> This issue was auto-created from ADO PBI AB# for Copilot coding agent dispatch. +> Do not modify this issue directly — it is managed by the dispatch pipeline. +``` + +### Step 5: Assign to Copilot Coding Agent + +After creating the issue, assign it to Copilot coding agent. + +**Method A — GitHub CLI** (recommended for interactive use): +```bash +# Create the issue and assign to Copilot in one step +gh issue create \ + --repo "OWNER/REPO" \ + --title "PBI Title" \ + --body "Issue body with Fixes AB#12345" \ + --assignee "copilot-swe-agent[bot]" +``` + +**Method B — GitHub REST API** (recommended for scripted automation): +```bash +# Step 1: Create issue +gh api /repos/OWNER/REPO/issues \ + --method POST \ + -f title="PBI Title" \ + -f body="Issue body" \ + | jq '.number' + +# Step 2: Assign to Copilot +gh api /repos/OWNER/REPO/issues/ISSUE_NUMBER/assignees \ + --method POST \ + --input - <<< '{ + "assignees": ["copilot-swe-agent[bot]"], + "agent_assignment": { + "target_repo": "OWNER/REPO", + "base_branch": "dev", + "custom_instructions": "Follow the repo copilot-instructions.md. PR title must include Fixes AB#." + } + }' +``` + +### Step 6: Update ADO Work Item + +After dispatching, update the ADO work item: +- State: `Active` (or `In Progress`) +- Add tag: `agent-dispatched` +- Add comment: `Dispatched to Copilot coding agent via GitHub Issue # in ` + +### Step 7: Report Dispatch Summary + +```markdown +## Dispatch Summary + +| AB# | Title | Repo | GitHub Issue | Agent Status | +|-----|-------|------|-------------|--------------| +| AB#12345 | [title] | common | #42 | Dispatched | +| AB#12346 | [title] | broker | — | Blocked (depends on AB#12345) | +| AB#12347 | [title] | msal | #18 | Dispatched | + +### Next Steps +- Monitor agent sessions at https://github.com/copilot/agents +- After AB#12345 PR merges, re-run dispatch for blocked PBIs +- Review generated PRs and use `@copilot` for feedback +``` + +## Batch Dispatch (Overnight Mode) + +For the "developer leaves, everything is done by morning" workflow: + +1. Run the orchestration script (`scripts/agent-pipeline/orchestrate.py`) +2. It dispatches all independent PBIs in parallel +3. Set up a cron job or scheduled GitHub Action to re-check dependencies every 2 hours +4. When a dependency PR merges, the next wave of PBIs is dispatched automatically + +## Review Feedback Loop + +After agent PRs are created, reviewers can iterate: +1. Leave review comments on the PR +2. Mention `@copilot` with specific feedback +3. Copilot coding agent picks up the feedback and pushes fixes +4. Repeat until the PR is approved + +Example feedback comment: +``` +@copilot This method should use the Logger class instead of android.util.Log. +Also please add unit tests for the error case when the IPC call throws DeadObjectException. +``` diff --git a/.github/skills/feature-planner/references/pbi-template.md b/.github/skills/feature-planner/references/pbi-template.md new file mode 100644 index 00000000..f1aea927 --- /dev/null +++ b/.github/skills/feature-planner/references/pbi-template.md @@ -0,0 +1,142 @@ +# PBI Description Template + +Use this template for every PBI created by the feature-planner skill. The description must be +self-contained — a Copilot coding agent should be able to implement the PBI using only this +description and the repo's `copilot-instructions.md`. + +--- + +## Template + +```html +

    Objective

    +

    Implement [what] in [which module] that [does what] for [purpose].

    + +

    Target Repository

    + + + + +
    Repo[org/repo-name]
    Base Branchdev
    Module[common | common4j | msal | AADAuthenticator | broker4j | adal]
    + +

    Context

    +

    [Why this change is needed. How it fits into the larger feature. What user problem it solves.]

    + +

    Feature Flag

    +

    Wrap all new behavior behind ExperimentationFeatureFlag.[FLAG_NAME].

    + +

    Technical Requirements

    +
      +
    • [Specific implementation detail 1]
      • +
    • [Specific implementation detail 2]
      • +
    • [Pattern to follow — reference existing class/method if applicable]
      • +
    • [Error handling requirements]
      • +
    • [Telemetry/logging requirements]
      • +
    + +

    Scope

    +

    In scope:

    +
      +
    • [What to implement]
      • +
    +

    Out of scope:

    +
      +
    • [What NOT to implement — important for constraining the agent]
      • +
    + +

    Files to Modify/Create

    +
      +
    • [path/to/existing/File.kt] — [what to change]
      • +
    • [path/to/new/File.kt] — [new file, what it contains]
      • +
    + +

    Acceptance Criteria

    +
      +
    • [ ] [Functional criterion 1]
      • +
    • [ ] [Functional criterion 2]
      • +
    • [ ] Feature flag integration: behavior is off when flag is disabled
      • +
    • [ ] Unit tests added for new/modified logic
      • +
    • [ ] No new lint warnings introduced
      • +
    • [ ] Compile check passes: ./gradlew :[module]:compile[Variant]Kotlin
      • +
    • [ ] Unit tests pass: ./gradlew :[module]:test[Variant]UnitTest
      • +
    + +

    Dependencies

    +

    [List any PBIs that must be completed before this one, with AB# IDs]

    +

    Or: "None — this PBI can be implemented independently."

    + +

    Additional Context

    +

    [Links to design docs, related PRs, or existing patterns to follow]

    +``` + +--- + +## Example: Adding Retry Logic to IPC Token Request + +```html +

    Objective

    +

    Add automatic retry with exponential backoff for failed IPC token requests in the Common +module to improve reliability when the Broker process is temporarily unavailable.

    + +

    Target Repository

    + + + + +
    RepoAzureAD/microsoft-authentication-library-common-for-android
    Base Branchdev
    Modulecommon
    + +

    Context

    +

    Users experience intermittent IPC failures when the Broker process is starting up or under +heavy load. Adding retry logic at the IPC layer in Common will transparently improve +reliability for all consumers (MSAL, OneAuth) without requiring changes in each client.

    + +

    Feature Flag

    +

    Wrap all new behavior behind ExperimentationFeatureFlag.IPC_RETRY_ENABLED.

    + +

    Technical Requirements

    +
      +
    • Add retry logic in the IPC strategy classes (BrokerAccountManagerStrategy or similar)
      • +
    • Use exponential backoff: 500ms, 1s, 2s (3 attempts max)
      • +
    • Only retry on transient IPC errors (DeadObjectException, RemoteException), not on auth errors
      • +
    • Log each retry attempt using the Logger class with correlation ID
      • +
    • Add telemetry span attribute for retry count
      • +
    • Follow existing error handling patterns in the IPC layer
      • +
    + +

    Scope

    +

    In scope:

    +
      +
    • Retry logic with exponential backoff
      • +
    • Logging and telemetry for retries
      • +
    • Feature flag gating
      • +
    +

    Out of scope:

    +
      +
    • UI-level retry indication
      • +
    • Per-operation retry configuration
      • +
    • Changes in MSAL or Broker repos
      • +
    + +

    Files to Modify/Create

    +
      +
    • common/src/main/java/com/microsoft/identity/common/internal/broker/ipc/IpcRetryPolicy.kt — New file: retry policy with exponential backoff
      • +
    • common/src/main/java/com/microsoft/identity/common/internal/broker/ipc/BrokerAccountManagerStrategy.java — Wrap IPC calls with retry policy
      • +
    • common/src/test/java/com/microsoft/identity/common/internal/broker/ipc/IpcRetryPolicyTest.kt — New file: unit tests
      • +
    + +

    Acceptance Criteria

    +
      +
    • [ ] Retries on DeadObjectException and RemoteException
      • +
    • [ ] Does not retry on AuthenticationException or other auth errors
      • +
    • [ ] Respects max retry count of 3
      • +
    • [ ] Backoff timing: 500ms, 1s, 2s
      • +
    • [ ] Feature flag disables all retry behavior when off
      • +
    • [ ] Logger output includes correlation ID and retry attempt number
      • +
    • [ ] Unit tests cover: success first try, retry-then-success, max-retries-exceeded
      • +
    • [ ] Compile check passes: ./gradlew :common:compileDebugKotlin
      • +
    • [ ] Unit tests pass: ./gradlew :common:testDebugUnitTest
      • +
    + +

    Dependencies

    +

    None — this PBI can be implemented independently.

    +``` diff --git a/.github/skills/pbi-creator/SKILL.md b/.github/skills/pbi-creator/SKILL.md new file mode 100644 index 00000000..aec6cdde --- /dev/null +++ b/.github/skills/pbi-creator/SKILL.md @@ -0,0 +1,295 @@ +--- +name: pbi-creator +description: Create Azure DevOps work items from a feature plan produced by the `feature-planner` skill. Handles ADO metadata discovery (area path, iteration, assignee), work item creation, and dependency linking. Use this skill when PBIs have been planned and approved, and you need to create them in ADO. Triggers include "create the PBIs", "create work items", "push PBIs to ADO", or approval of a feature plan. +--- + +# PBI Creator + +Create Azure DevOps work items from a feature plan produced by the `feature-planner` skill. +Handles ADO metadata discovery, work item creation, and dependency linking. + +## Prerequisites + +- **ADO MCP Server** must be running (configured in `.vscode/mcp.json`) with `work-items` domain +- A **feature plan** must exist in the current chat context (produced by the `feature-planner` skill) + — the plan follows the structured output format with Summary Table, PBI Details, etc. + +## Workflow + +### Step 1: Parse the Feature Plan + +Read the feature plan from the chat context. Extract for each PBI: +- **Title** — from the `#### PBI-N: [Title]` header +- **Repo** — from the metadata table `Repo` field +- **Module** — from the metadata table `Module` field +- **Priority** — from the metadata table `Priority` field (P1→1, P2→2, P3→3) +- **Depends on** — from the metadata table `Depends on` field (PBI-N references) +- **Tags** — from the metadata table `Tags` field +- **Description** — from the `##### Description` section (in plain markdown). + **Convert to HTML** before setting as `System.Description` in ADO: + - `## Heading` → `

    Heading

    ` + - `**bold**` → `bold` + - `- item` → `
    • item
    ` + - `` `code` `` → `code` + - Paragraphs → `

    text

    ` + - Or use a simple approach: wrap the entire markdown in `
    ` tags if conversion is complex.
+
+If a feature plan is not found in context, ask the developer:
+> "I don't see a feature plan in our conversation. Either:
+> 1. Run the `feature-planner` skill first (say 'plan this feature')
+> 2. Or paste the PBI details and I'll create the work items"
+
+### Step 2: Discover ADO Defaults
+
+**Do this BEFORE asking the developer for preferences.** This ensures you present valid
+options and avoid path errors.
+
+**Discovery sequence:**
+1. Call `mcp_ado_wit_my_work_items` to get the developer's recent work items.
+2. Call `mcp_ado_wit_get_work_items_batch_by_ids` on 3-5 recent items.
+3. Extract from the responses:
+   - `System.AreaPath` → collect **all unique area paths** with frequency counts
+   - `System.IterationPath` → note the format pattern
+   - `System.AssignedTo` → use as default assignee
+4. Call `mcp_ado_work_list_iterations` with **`depth: 6`** (monthly sprints are at depth 6;
+   `depth: 4` will miss them).
+5. Filter iterations to **current month or future only** — discard any iteration whose end date
+   is in the past. Compare iteration dates against today's date. For monthly iterations with
+   names like `CY26Q1_M2_Feb`, parse the month/year and exclude months before the current one.
+   **Never suggest past iterations as options.**
+
+### Step 3: Present Options for Confirmation
+
+**MANDATORY**: You MUST present options and wait for the developer to confirm before proceeding.
+Do NOT make assumptions. Do NOT auto-select defaults. Always ask.
+**Use the `askQuestion` tool** to present clickable MCQ-style options whenever possible.
+
+**Batch ALL questions into a SINGLE `askQuestion` call** with multiple questions.
+This gives the user a smooth flow where answering one immediately shows the next.
+Do NOT make separate `askQuestion` calls for each question — combine them all into one call
+with 4 questions (Area Path, Iteration, Assignee, Parent). Example:
+
+```
+askQuestion({
+  questions: [
+    {
+      header: "Area Path",
+      question: "Which area path for these PBIs?",
+      options: [
+        { label: "Engineering\\Auth Client\\Broker\\Android", description: "Your most recent work items use this path", recommended: true },
+        { label: "Engineering\\Auth Client\\MSAL\\Android" }
+      ],
+      allowFreeformInput: true
+    },
+    {
+      header: "Iteration",
+      question: "Which iteration? (Current date: )",
+      options: [
+        { label: "CY26Q2_M4_Apr (next month)", description: "Engineering\\CY26\\CY26H1\\CY26Q2\\Monthly\\CY26Q2_M4_Apr", recommended: true },
+        { label: "CY26Q2_M5_May", description: "Engineering\\CY26\\CY26H1\\CY26Q2\\Monthly\\CY26Q2_M5_May" }
+      ],
+      allowFreeformInput: true
+    },
+    {
+      header: "Assignee",
+      question: "Who should be assigned?",
+      options: [
+        { label: "shjameel@microsoft.com", description: "Discovered from recent work items", recommended: true }
+      ],
+      allowFreeformInput: true
+    },
+    {
+      header: "Parent",
+      question: "Link PBIs to a parent Feature work item?",
+      options: [
+        { label: "Create new Feature", description: "Create a new Feature work item titled ''" },
+        { label: "No parent", description: "No parent Feature — standalone PBIs" }
+      ],
+      allowFreeformInput: true
+    }
+  ]
+})
+```
+
+### Question details:
+
+**Area Path** (ALWAYS ask, even if only one found):
+- Show all unique area paths discovered from recent work items with frequency counts
+- Mark the most common one as `recommended: true`
+
+**Iteration** (ALWAYS present a list — never assume):
+Only show iterations for the **current month or later**. Never include past months.
+- Mark the current/next month as `recommended: true`
+
+**Assignee** (confirm):
+- Show the discovered assignee as `recommended: true`
+
+**Parent Feature**:
+- Offer to create a new Feature, link to an existing one, or no parent
+
+Wait for all answers before proceeding to Step 4.
+
+**If creating a new Feature:**
+Use `mcp_ado_wit_create_work_item` with:
+```json
+{
+  "project": "Engineering",
+  "workItemType": "Feature",
+  "fields": [
+    {"name": "System.Title", "value": "[Feature Name from plan header]"},
+    {"name": "System.Description", "value": "
    [Brief feature description from plan]
    ", "format": "Html"},
+    {"name": "System.AreaPath", "value": "[developer-confirmed area path]"},
+    {"name": "System.IterationPath", "value": "[developer-confirmed iteration]"},
+    {"name": "System.AssignedTo", "value": "[developer-confirmed assignee]"},
+    {"name": "System.Tags", "value": "ai-generated"}
+  ]
+}
+```
+Record the Feature ID for use in Step 4.
+
+**If linking to existing Feature:**
+Verify the Feature exists by calling `mcp_ado_wit_get_work_item` with the provided ID.
+Record the Feature ID for use in Step 4.
+
+### Step 4: Create Work Items in ADO
+
+Use `mcp_ado_wit_create_work_item` for each PBI. Create them in **dependency order**
+(PBIs with no dependencies first).
+
+**CRITICAL tool parameters:**
+- `project`: `"Engineering"`
+- `workItemType`: `"Product Backlog Item"`
+- `fields`: An array of `{name, value}` objects
+
+**Field format:**
+```json
+{
+  "project": "Engineering",
+  "workItemType": "Product Backlog Item",
+  "fields": [
+    {"name": "System.Title", "value": "[title from plan]"},
+    {"name": "System.Description", "value": "[HTML from 
     block]", "format": "Html"},
+    {"name": "System.AreaPath", "value": "[developer-confirmed area path]"},
+    {"name": "System.IterationPath", "value": "[developer-confirmed iteration]"},
+    {"name": "System.AssignedTo", "value": "[developer-confirmed assignee]"},
+    {"name": "Microsoft.VSTS.Common.Priority", "value": "[priority number]"},
+    {"name": "System.Tags", "value": "[tags from plan]"}
+  ]
+}
+```
+
+**Common mistakes to avoid:**
+- Do NOT use top-level params like `title`, `description`, `areaPath` — they don't exist
+- Do NOT use `type` — the param is called `workItemType`
+- The `description` field value must be **HTML** (not Markdown), with `"format": "Html"`
+- Tags are semicolon-separated: `"ai-generated; copilot-agent-ready"`
+- Area/iteration paths use backslashes: `"Engineering\\Auth Client\\Broker\\Android"`
+- **Never hardcode paths** — always use values confirmed by the developer in Step 3
+
+**After each PBI is created:**
+- Record the returned `id` (AB# number)
+- Map `PBI-N` → `AB#[id]` for dependency resolution
+
+### Step 5: Resolve Dependencies + Parent Links
+
+After all PBIs are created and you have the PBI-N → AB# mapping:
+
+1. **Update descriptions**: For each PBI whose description references `PBI-N` in the
+   Dependencies section, update the description to use the actual `AB#[id]`.
+   Use `mcp_ado_wit_update_work_item` to patch the description.
+
+2. **Link dependencies**: Use `mcp_ado_wit_work_items_link` to create predecessor links:
+   ```json
+   {
+     "updates": [
+       {"id": [dependent_id], "linkToId": [dependency_id], "type": "predecessor",
+        "comment": "[Dependent title] depends on [Dependency title]"}
+     ]
+   }
+   ```
+
+3. **Parent to Feature** (if Feature ID was recorded in Step 3.5):
+   Use `mcp_ado_wit_add_child_work_items` to parent all PBIs to the Feature:
+   ```json
+   {
+     "parentId": [feature_id],
+     "childWorkItemIds": [pbi_id_1, pbi_id_2, pbi_id_3]
+   }
+   ```
+   If this tool is unavailable, use `mcp_ado_wit_work_items_link` with `type: "child"` instead.
+
+### Step 5.5: Mark PBIs as Committed
+
+After all PBIs are created, linked, and parented, update their state to **Committed**
+so they appear in sprint planning.
+
+Use `mcp_ado_wit_update_work_items_batch` (if available) or `mcp_ado_wit_update_work_item`
+for each PBI:
+```json
+{
+  "id": [pbi_id],
+  "fields": [
+    {"name": "System.State", "value": "Committed"}
+  ]
+}
+```
+
+Also update the Feature work item (if created) to Committed state.
+
+### Step 6: Report Summary
+
+Present the results:
+
+```markdown
+## PBIs Created: [Feature Name]
+
+### Work Items
+
+| PBI | AB# | Title | Repo | Depends On | State | Link |
+|-----|-----|-------|------|------------|-------|------|
+| PBI-1 | AB#12345 | [title] | common | — | Committed | [link] |
+| PBI-2 | AB#12346 | [title] | broker | AB#12345 | Committed | [link] |
+| PBI-3 | AB#12347 | [title] | msal | AB#12345 | Committed | [link] |
+
+### ADO Settings Used
+
+- **Parent Feature**: AB#12340 `[Feature title]` (or "None")
+- **Area Path**: `[confirmed path]`
+- **Iteration**: `[confirmed path]`
+- **Assigned to**: `[confirmed assignee]`
+- **State**: Committed
+
+### Dispatch Order
+
+1. Dispatch **AB#12345** first (no blockers)
+2. After AB#12345 merges → dispatch **AB#12346** and **AB#12347** in parallel
+
+### Next Step
+
+> Say **"dispatch"** to send PBI-1 to Copilot coding agent via the `pbi-dispatcher` skill.
+```
+
+## MCP Server Failure Recovery
+
+If ADO MCP tools become unavailable mid-workflow:
+1. Ask the developer to restart the MCP server:
+   Command Palette → `MCP: Restart Server` → `ado`
+2. If tools still don't load, recommend starting a **new chat session** — MCP tools sometimes
+   don't reconnect to existing sessions after a restart.
+3. **Preserve progress**: Note which PBIs were already created (with AB# IDs) so the new
+   session can continue from where it left off without duplicating work items.
+4. In the new session, the developer can say:
+   > "Continue creating PBIs for [feature]. PBI-1 already created as AB#12345. Create PBI-2 onwards."
+
+## Edge Cases
+
+### Plan has a single PBI
+Skip dependency linking. Create one work item and report.
+
+### Developer wants different area paths per PBI
+If PBIs target different teams (e.g., one in Common, one in MSAL), ask if they want different
+area paths. Present the discovered options for each PBI individually.
+
+### Developer modifies the plan before approving
+If the developer asks for changes to the plan (add/remove PBIs, change descriptions), defer back
+to the `feature-planner` skill to regenerate the plan, then return here for creation.
diff --git a/.github/skills/pbi-dispatcher/SKILL.md b/.github/skills/pbi-dispatcher/SKILL.md
new file mode 100644
index 00000000..fdc4bc0c
--- /dev/null
+++ b/.github/skills/pbi-dispatcher/SKILL.md
@@ -0,0 +1,186 @@
+---
+name: pbi-dispatcher
+description: Dispatch Azure DevOps PBIs to GitHub Copilot coding agent for autonomous implementation. Use this skill when PBIs have been created (by the `pbi-creator` skill or manually) and you want to send them to Copilot coding agent to generate PRs. Triggers include "dispatch PBIs to agent", "assign to Copilot", "send work items to coding agent", "kick off agent implementation", "dispatch these work items", or any request to have Copilot coding agent implement ADO work items.
+---
+
+# PBI Dispatcher
+
+Dispatch Azure DevOps PBIs to GitHub Copilot coding agent by creating GitHub Issues in the
+target repos and assigning them to `copilot-swe-agent[bot]`.
+
+## Prerequisites
+
+- **ADO MCP Server** running (for reading PBI details)
+- **GitHub CLI** (`gh`) authenticated with accounts for target repos
+- PBIs in ADO with tag `copilot-agent-ready`
+- Copilot coding agent enabled on target repos
+
+## GitHub Account Discovery
+
+**CRITICAL**: Before dispatching, you must determine which `gh` CLI accounts to use.
+**Never hardcode GitHub usernames** — they vary per developer.
+
+### Discovery Sequence
+
+Follow these steps **in order**. Stop at the first one that succeeds:
+
+**Step 0: Verify `gh` CLI is installed:**
+```powershell
+gh --version
+```
+If this fails (command not found), offer to install it for the developer:
+> "GitHub CLI (`gh`) is not installed. Want me to install it for you?"
+> 1. **Yes, install it** (recommended)
+> 2. **No, I'll install it myself**
+
+If the developer agrees, run the appropriate install command:
+- **Windows**: `winget install --id GitHub.cli -e --accept-source-agreements --accept-package-agreements`
+- **macOS**: `brew install gh`
+
+After installation completes, verify with `gh --version`, then prompt authentication:
+> "gh CLI installed! Now you need to sign in:
+> ```
+> gh auth login --hostname github.com
+> ```
+> Run this, complete the auth flow, then say 'continue'."
+
+**Step 1: Check `.github/developer-local.json`** (fastest — developer already configured):
+```powershell
+$config = Get-Content ".github/developer-local.json" -Raw -ErrorAction SilentlyContinue | ConvertFrom-Json
+$publicUser = $config.github_accounts.AzureAD
+$emuUser = $config.github_accounts.'identity-authnz-teams'
+```
+
+**Step 2: Discover from `gh auth status`** (zero-config if logged in):
+```powershell
+$ghStatus = gh auth status 2>&1
+# Parse output for logged-in accounts on each host
+# Look for lines like: "Logged in to github.com account "
+```
+Map accounts to orgs:
+- Non-EMU account (no `_` suffix) → `AzureAD/*` repos
+- EMU account (ends with `_microsoft` or similar) → `identity-authnz-teams/*` repos
+
+**Step 3: Prompt the developer** (fallback — save for next time):
+If neither Step 1 nor Step 2 yields both accounts, ask:
+> "I need your GitHub usernames for dispatching:
+> 1. **Public GitHub** (for AzureAD/* repos like common, msal, adal): ___
+> 2. **GitHub Enterprise / EMU** (for identity-authnz-teams/* repos like broker): ___"
+
+After receiving the answer, offer to save:
+> "Save these to `.github/developer-local.json` so you don't have to enter them again? (Y/n)"
+
+If yes, write the config file:
+```json
+{
+  "github_accounts": {
+    "AzureAD": "",
+    "identity-authnz-teams": ""
+  }
+}
+```
+
+**Step 4: Not signed in at all** — if `gh auth status` shows no accounts:
+> "You're not signed in to GitHub CLI. Please run:
+> ```
+> gh auth login --hostname github.com
+> ```
+> Then try dispatching again."
+
+Do NOT attempt to proceed without valid accounts — fail fast with clear instructions.
+
+## Repo Routing
+
+| Target in PBI | GitHub Repo | Account Type |
+|---------------|-------------|--------------|
+| common / common4j | `AzureAD/microsoft-authentication-library-common-for-android` | Public (AzureAD) |
+| msal | `AzureAD/microsoft-authentication-library-for-android` | Public (AzureAD) |
+| broker / broker4j / AADAuthenticator | `identity-authnz-teams/ad-accounts-for-android` | EMU (identity-authnz-teams) |
+| adal | `AzureAD/azure-activedirectory-library-for-android` | Public (AzureAD) |
+
+## Workflow
+
+### 1. Read PBIs from ADO
+Use ADO MCP Server tools to list/get work items tagged `copilot-agent-ready`. Read the full
+PBI description — it will be needed for the dispatch prompt.
+
+### 2. Check Dependencies
+For each PBI, check if its dependencies (other AB# IDs) have merged PRs. Skip blocked PBIs.
+
+### 3. Switch gh Account + Dispatch to Copilot Agent
+
+For each ready PBI:
+
+**Step 1: Switch to the correct gh account** (using the discovered username from above):
+```bash
+# For AzureAD/* repos (common, msal, adal):
+gh auth switch --user 
+
+# For identity-authnz-teams/* repos (broker):
+gh auth switch --user 
+```
+
+**Step 2: Dispatch using `gh agent-task create` (PREFERRED — requires gh v2.80+):**
+
+Write the full PBI description to a temp file and pipe it as the prompt. This avoids
+shell escaping issues and ensures the full context reaches the agent:
+
+```bash
+# Write PBI description to temp file
+echo "" > /tmp/pbi-prompt.txt
+
+# Create agent task with full PBI content
+gh agent-task create "$(cat /tmp/pbi-prompt.txt)" \
+  --repo "OWNER/REPO" \
+  --base dev
+```
+
+On Windows PowerShell:
+```powershell
+$prompt = @"
+
+"@
+$prompt | Set-Content -Path "$env:TEMP\pbi-prompt.txt"
+gh agent-task create (Get-Content "$env:TEMP\pbi-prompt.txt" -Raw) --repo "OWNER/REPO" --base dev
+```
+
+**IMPORTANT for prompt content:**
+- Include the FULL PBI description (Objective, Context, Technical Requirements, Acceptance Criteria)
+- Include `Fixes AB#` so the PR links to the ADO work item
+- Include `Follow .github/copilot-instructions.md strictly` as a reminder
+- Do NOT include local file paths (design-docs/, etc.) — the agent can't access them
+- Do NOT truncate — the full description IS the implementation spec
+
+**Step 3 (FALLBACK — if `gh agent-task create` fails):**
+
+Create a GitHub Issue and assign to Copilot:
+```bash
+gh issue create \
+  --repo "OWNER/REPO" \
+  --title "[PBI Title]" \
+  --body "[Full PBI description with 'Fixes AB#ID']"
+```
+Then assign via API (extract issue number from the URL output):
+```bash
+echo '{"assignees":["copilot-swe-agent[bot]"],"agent_assignment":{"target_repo":"OWNER/REPO","base_branch":"dev","custom_instructions":"Follow copilot-instructions.md. PR title must include Fixes AB#ID."}}' | gh api /repos/OWNER/REPO/issues/ISSUE_NUMBER/assignees --method POST --input -
+```
+
+### 4. Update ADO State
+Mark the ADO work item as `Active`, add tag `agent-dispatched`.
+
+### 5. Report Summary
+Output a dispatch summary table with AB#, repo, dispatch method, and status.
+
+## Batch Dispatch Script
+
+For overnight automation, use [`scripts/agent-pipeline/orchestrate.py`](../../../scripts/agent-pipeline/orchestrate.py).
+This script handles dependency ordering, parallel dispatch, and ADO state updates.
+
+## Review Feedback Loop
+
+After PRs are created, use `@copilot` in PR comments to iterate:
+```
+@copilot Please use the Logger class instead of android.util.Log.
+Add unit tests for the error case.
+```