More refactoring

Signed-off-by: Matt Bruce <matt.bruce1@toyota.com>

docs/ai/android/android.md

@@ -53,6 +53,6 @@ Refactor this file to reduce duplication without changing behavior.
 - Multiple AI extensions competing for suggestions.
 
 ## Next Steps
-- For workflow patterns, read [Cross-Platform AI Usage](../cross-platform.md).
+- For workflow patterns, read [Cross-Platform AI Usage](../crossplatform/cross-platform.md).
 - For safety rules, read [Governance, Privacy, and Policy](../governance.md).
 - For cost guidance, read [Usage and Token Budgeting](../usage-tokens.md).

docs/ai/crossplatform/cross-platform.md

@@ -2,6 +2,15 @@
 
 You are here: [AI Docs Home](../index.md) > Cross-Platform AI Usage
 
+## Contents
+- What This Section Covers
+- Quick Links
+- Repo Instructions (Always-On Rules)
+- Agents and Skills
+- Example Starting Prompt
+- Next Steps
+
+## What This Section Covers
 This page gives a high-level overview of cross-platform AI usage, agent workflows, and prompting patterns. For detailed patterns, anti-patterns, and workflows, see the linked guides below.
 
 ## Quick Links
@@ -12,12 +21,18 @@ This page gives a high-level overview of cross-platform AI usage, agent workflow
 - [MCP Overview](mcp-overview.md)
 
 ## Repo Instructions (Always-On Rules)
-Instructions are repo-scoped rules that auto-apply based on file patterns. See your repo’s instructions directory (e.g., [assets/instructions/](../../assets/instructions/)).
+Instructions are repo-scoped rules that auto-apply based on file patterns. See your repo’s instructions directory (e.g., [assets/instructions/](../../../assets/instructions/)).
 
 ## Agents and Skills
-- Agents: Use for multi-step, structured tasks (see [Agents.md](../../Agents.md)).
+- Agents: Use for multi-step, structured tasks (see [Agents.md](../../../Agents.md)).
 - Skills: Use for focused, repeatable workflows (see [Skills Library](../skills.md)).
 
+## Example Starting Prompt
+Example prompt:
+```text
+I need to refactor this file safely. First, provide a 5-step plan. Wait for approval before editing.
+```
+
 ## Next Steps
 - For safety rules, read [Governance, Privacy, and Policy](../governance.md)
 - If setup is not working, follow [Troubleshooting and FAQ](../troubleshooting.md)

docs/ai/crossplatform/mcp-overview.md

@@ -1,5 +1,15 @@
 # MCP (Model Context Protocol) - Cross-Platform Overview
 
+You are here: [AI Docs Home](../index.md) > [Cross-Platform AI Usage](cross-platform.md) > MCP Overview
+
+## Contents
+- What MCP Is
+- How MCP Helps In A Workflow
+- Common MCP Use Cases
+- Example Workflow
+- Example Prompt
+- Where To Learn More
+
 MCP is an open standard that lets tools and agents interact with real systems. In plain language, MCP lets the assistant "do" things (like run builds or fetch logs) instead of just talking about them.
 
 ## How MCP Helps In A Workflow
@@ -17,8 +27,15 @@ Think of MCP as a set of safe, structured buttons the assistant can press. You a
 3. You ask for a summary and next steps.
 
 ## Example Prompt
+Example prompt:
+```text
 Use the build MCP tool to run the build and summarize any errors.
+```
 
 ## Where To Learn More
 - iOS examples: see [iOS Setup](../ios/ios.md)
 - Android examples: see [Android Setup](../android/android.md)
+
+## Next Steps
+- Return to [Cross-Platform AI Usage](cross-platform.md).
+- Continue to [Plan-First Workflow](plan-first-workflow.md) for safer multi-step changes.

docs/ai/crossplatform/plan-first-workflow.md

@@ -1,10 +1,35 @@
 # Plan-First Workflow
 
+You are here: [AI Docs Home](../index.md) > [Cross-Platform AI Usage](cross-platform.md) > Plan-First Workflow
+
+## Contents
+- When To Use Plan-First
+- Workflow Steps
+- Example Plan Request
+- Example Follow-Up Request
+- Next Steps
+
+## When To Use Plan-First
+Use this workflow when a task is multi-step, risky, or touches more than one file.
+
+## Workflow Steps
 1. Ask for a short plan.
 2. Approve or adjust the plan.
 3. Ask for targeted changes.
 4. Verify with tests or review.
 
-### Example Plan Request
+## Example Plan Request
-
+Example prompt:
+```text
 Provide a 5-step plan to refactor this module. Wait for approval before edits.
+```
+
+## Example Follow-Up Request
+Example prompt:
+```text
+Proceed with steps 1 and 2 only. Show changed files and test results.
+```
+
+## Next Steps
+- Use [Starter Prompts](starter-prompts.md) for copy/paste prompt options.
+- Review [Prompting Patterns](prompting-patterns.md) for prompt structure.

docs/ai/crossplatform/prompting-antipatterns.md

@@ -1,17 +1,52 @@
 # Prompting Anti-Patterns (And Fixes)
 
-Common mistakes and better alternatives:
+You are here: [AI Docs Home](../index.md) > [Cross-Platform AI Usage](cross-platform.md) > Prompting Anti-Patterns
 
-**Too broad:** Fix everything in this project.
+## Contents
-**Better:** Refactor this file to remove duplication. Do not change behavior.
+- Why Anti-Patterns Cause Rework
+- Common Anti-Patterns and Fixes
+- Quick Self-Check Before Sending
+- Next Steps
 
-**Too vague:** Make this code better.
+## Why Anti-Patterns Cause Rework
-**Better:** Improve naming and add comments only where logic is complex.
+Anti-patterns are prompt styles that are too broad or ambiguous. They usually produce low-quality output, extra retries, and higher token use.
 
-**Missing inputs:** Update the service to handle retries.
+## Common Anti-Patterns and Fixes
-**Better:** Update ServiceA in src/service/ServiceA.kt to retry 2 times on 5xx. Keep API the same.
+Too broad:
+```text
+Fix everything in this project.
+```
+Better:
+Example prompt:
+```text
+Refactor this file to remove duplication. Do not change behavior.
+```
 
-### Example: Too Broad vs Scoped
+Too vague:
+```text
+Make this code better.
+```
+Better:
+Example prompt:
+```text
+Improve naming and add comments only where logic is complex.
+```
 
-Too broad: Fix everything in this project.
+Missing inputs:
-Scoped: Refactor this file to remove duplication. Do not change behavior.
+```text
+Update the service to handle retries.
+```
+Better:
+Example prompt:
+```text
+Update ServiceA in src/service/ServiceA.kt to retry 2 times on 5xx. Keep API the same.
+```
+
+## Quick Self-Check Before Sending
+1. Did I name the exact file or function?
+2. Did I say what must not change?
+3. Did I ask for one clear output type?
+
+## Next Steps
+- Read [Prompting Patterns](prompting-patterns.md) for reusable templates.
+- Use [Plan-First Workflow](plan-first-workflow.md) for larger changes.

docs/ai/crossplatform/prompting-patterns.md

@@ -1,8 +1,53 @@
 # Prompting Patterns
 
-Example prompts:
+You are here: [AI Docs Home](../index.md) > [Cross-Platform AI Usage](cross-platform.md) > Prompting Patterns
 
-- Refactor this file to improve readability without changing behavior.
+## Contents
-- Add unit tests for this service. Keep the existing public API.
+- Why Prompt Patterns Matter
-- Explain this error and list likely fixes in order.
+- Prompt Template
-- Summarize what this module does and call out risks.
+- Common Prompt Patterns
+- Next Steps
+
+## Why Prompt Patterns Matter
+Good prompt patterns reduce rework. They tell the assistant exactly what to change, what not to change, and what output you expect.
+
+## Prompt Template
+Use this structure for most requests:
+1. Goal: The specific outcome you want.
+2. Scope: The file or function to change.
+3. Constraints: What must stay the same.
+4. Output: What you want returned (code only, bullets, tests, and so on).
+
+Example prompt:
+```text
+Goal: Refactor validation logic for readability.
+Scope: Only ValidationService.swift.
+Constraints: Keep behavior and public API unchanged.
+Output: Return code changes and a short list of tests to update.
+```
+
+## Common Prompt Patterns
+- Refactor safely:
+Example prompt:
+```text
+Refactor this file to improve readability without changing behavior.
+```
+- Add tests:
+Example prompt:
+```text
+Add unit tests for this service. Keep the existing public API.
+```
+- Debug:
+Example prompt:
+```text
+Explain this error and list likely fixes in priority order.
+```
+- Understand code:
+Example prompt:
+```text
+Summarize what this module does and call out the top 3 risks.
+```
+
+## Next Steps
+- Read [Prompting Anti-Patterns](prompting-antipatterns.md) to avoid common mistakes.
+- Use [Starter Prompts](starter-prompts.md) when you need copy/paste examples.

docs/ai/crossplatform/starter-prompts.md

@@ -1,9 +1,51 @@
 # Starter Prompts (Copy/Paste)
 
-Use these when you are not sure where to begin:
+You are here: [AI Docs Home](../index.md) > [Cross-Platform AI Usage](cross-platform.md) > Starter Prompts
 
-- Summarize this file in 5 bullets and list 2 risks.
+## Contents
-- Refactor this function to remove duplication. Keep behavior the same.
+- How To Use Starter Prompts
-- List tests I should add for this change.
+- Understand Existing Code
-- Explain this error and propose the top 3 fixes.
+- Safe Refactoring
-- Create a 5-step plan to split this class into smaller components.
+- Testing
+- Planning
+- Debugging
+- Next Steps
+
+## How To Use Starter Prompts
+1. Copy one prompt that matches your task.
+2. Replace placeholders (file names, functions, constraints).
+3. Keep the request focused on one outcome.
+
+## Understand Existing Code
+Example prompt:
+```text
+Summarize this file in 5 bullets and list 2 risks.
+```
+
+## Safe Refactoring
+Example prompt:
+```text
+Refactor this function to remove duplication. Keep behavior the same.
+```
+
+## Testing
+Example prompt:
+```text
+List tests I should add for this change.
+```
+
+## Planning
+Example prompt:
+```text
+Create a 5-step plan to split this class into smaller components. Wait for approval before edits.
+```
+
+## Debugging
+Example prompt:
+```text
+Explain this error and propose the top 3 fixes in priority order.
+```
+
+## Next Steps
+- Learn stronger prompt structure in [Prompting Patterns](prompting-patterns.md).
+- Avoid common mistakes in [Prompting Anti-Patterns](prompting-antipatterns.md).

docs/ai/governance.md

@@ -58,5 +58,5 @@ Is it ok to share this log snippet with user IDs in Copilot?
 ```
 
 ## Next Steps
-- For day-to-day workflows, read [Cross-Platform AI Usage](cross-platform.md).
+- For day-to-day workflows, read [Cross-Platform AI Usage](crossplatform/cross-platform.md).
 - For cost guidance, read [Usage and Token Budgeting](usage-tokens.md).

docs/ai/index.md

@@ -18,10 +18,10 @@ Follow the steps in order. Do not skip ahead if this is your first time.
 1. Read [AI Overview](overview.md)
 2. Follow [iOS Setup](ios/ios.md)
 3. Skim [Usage and Token Budgeting](usage-tokens.md)
-4. Return to [Cross-Platform AI Usage](cross-platform.md)
+4. Return to [Cross-Platform AI Usage](crossplatform/cross-platform.md)
 
 ## Guided Paths (Pick One)
-- New to AI: [AI Overview](overview.md) -> [Cross-Platform AI Usage](cross-platform.md) -> [Usage and Token Budgeting](usage-tokens.md)
+- New to AI: [AI Overview](overview.md) -> [Cross-Platform AI Usage](crossplatform/cross-platform.md) -> [Usage and Token Budgeting](usage-tokens.md)
 - iOS setup: [AI Overview](overview.md) -> [iOS Setup](ios/ios.md) -> [MCP](ios/ios-mcp.md)
 - Android setup: [AI Overview](overview.md) -> [Android Setup](android/android.md) 
 - Contributors: [AI Overview](overview.md) -> [Governance, Privacy, and Policy](governance.md) -> [Troubleshooting and FAQ](troubleshooting.md)

docs/ai/ios/ios-xcodebuildmcp-vscode.md

@@ -142,4 +142,4 @@ Common tool actions the agent will use:
 ## Next Steps
 
 - For iOS setup basics, read [iOS Setup](ios.md).
-- For cross-platform usage patterns, read [Cross-Platform AI Usage](../cross-platform.md).
+- For cross-platform usage patterns, read [Cross-Platform AI Usage](../crossplatform/cross-platform.md).

docs/ai/ios/ios-xcodebuildmcp-xcode.md

@@ -146,4 +146,4 @@ https://www.apple.com/newsroom/2026/02/xcode-26-point-3-unlocks-the-power-of-age
 
 ## Next Steps
 - For iOS setup basics, read [iOS Setup](ios.md).
-- For cross-platform usage patterns, read [Cross-Platform AI Usage](../cross-platform.md).
+- For cross-platform usage patterns, read [Cross-Platform AI Usage](../crossplatform/cross-platform.md).

docs/ai/ios/ios.md

@@ -42,6 +42,6 @@ You are here: [AI Docs Home](../index.md) > iOS Setup
 ---
 
 ## Next Steps
-- For cross-platform patterns, read [Cross-Platform AI Usage](../cross-platform.md)
+- For cross-platform patterns, read [Cross-Platform AI Usage](../crossplatform/cross-platform.md)
 - For automation, see the MCP guides above
 - For safety rules, read [Governance, Privacy, and Policy](../governance.md)

docs/ai/overview.md

@@ -212,7 +212,7 @@ Refactor only the validation logic in this file. Keep behavior the same and list
 
 ## Next Steps
 - If you have not set up an editor yet, go to [iOS Setup](ios/ios.md) or [Android Setup](android/android.md).
-- For day-to-day usage patterns, read [Cross-Platform AI Usage](cross-platform.md).
+- For day-to-day usage patterns, read [Cross-Platform AI Usage](crossplatform/cross-platform.md).
 - For safety and cost guidance, read [Governance, Privacy, and Policy](governance.md) and [Usage and Token Budgeting](usage-tokens.md).
 
 ## Getting Help

docs/ai/skills.md

@@ -173,9 +173,8 @@ Everything is installable with one command:
 - Curated skill lists (for example, ios-skills.txt, android-skills.txt)
 
 ### Link To The Assets Repo
-- Repo: (link)
+- Repo (current project source): [assets/](../../assets/)
 
 ## Next Steps
-- For day-to-day workflows, read [Cross-Platform AI Usage](cross-platform.md).
+- For day-to-day workflows, read [Cross-Platform AI Usage](crossplatform/cross-platform.md).
 - For setup issues, follow [Troubleshooting and FAQ](troubleshooting.md).
-

docs/ai/usage-tokens.md

@@ -210,5 +210,5 @@ Agent: Refactor these two files, update tests, and summarize results.
 - Can I ask for a plan first?
 
 ## Next Steps
-- For workflow patterns, read [Cross-Platform AI Usage](cross-platform.md).
+- For workflow patterns, read [Cross-Platform AI Usage](crossplatform/cross-platform.md).
 - For troubleshooting, read [Troubleshooting and FAQ](troubleshooting.md).

docs/planning/AI-Docs-Plan.md

@@ -21,20 +21,33 @@ The docs under docs/ai map 1:1 to Confluence pages.
 3. Android (VS Code)
 4. Cross-Platform AI Usage
 5. iOS MCP (XcodeBuildMCP)
-5. Skills Library
+6. Skills Library
-6. Usage and Token Budgeting
+7. Usage and Token Budgeting
-7. Troubleshooting and FAQ
+8. Troubleshooting and FAQ
-8. Governance, Privacy, and Policy
+9. Governance, Privacy, and Policy
 
 ## Folder Structure (Current)
 - docs/
   - ai/
     - index.md
     - overview.md
-    - ios.md
+    - vscode-setup.md
-    - ios-xcodebuildmcp.md
+    - android/
-    - android/android.md
+      - android.md
-    - cross-platform.md
+    - ios/
+      - ios.md
+      - ios-mcp.md
+      - ios-mcp-vscode.md
+      - ios-xcodebuildmcp-xcode.md
+      - ios-xcodebuildmcp-vscode.md
+      - xcodebuildmcp-config.yaml.md
+    - crossplatform/
+      - cross-platform.md
+      - prompting-patterns.md
+      - prompting-antipatterns.md
+      - plan-first-workflow.md
+      - starter-prompts.md
+      - mcp-overview.md
     - skills.md
     - usage-tokens.md
     - troubleshooting.md