AI Feature Orchestrator: Skills (1/6), Fixes AB#3534741

.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 "<keyword>"
+# 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] <Feature Name>/<spec-name>.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] <Feature Name>/<spec-name>.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] <Feature Name>/<spec-name>.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-<feature-name-kebab-case>"
+```
+
+```bash
+cd design-docs/
+git add "[Android] <Feature Name>"
+git commit -m "Add design spec: <Feature Name>"
+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

.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