mbrucedogs/ai-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactored filesystem

Browse Source 
Signed-off-by: Matt Bruce <matt.bruce1@toyota.com>
This commit is contained in:
Matt Bruce 2026-02-12 16:33:53 -06:00
parent f3dd8d92bd
commit 8533890d2c
18 changed files with 512 additions and 366 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
docs/ai/android.md → docs/ai/android/android.md
View File

@ -1,6 +1,6 @@
# Android AI Setup # Android AI Setup
You are here: [AI Docs Home](index.md) > Android Setup You are here: [AI Docs Home](../index.md) > Android Setup
## Contents ## Contents
- Setup - Setup
@ -9,29 +9,10 @@ You are here: [AI Docs Home](index.md) > Android Setup
- Android Troubleshooting - Android Troubleshooting
- Next Steps - Next Steps
## Setup: VS Code + GitHub Copilot Extension ## Setup: VS Code + GitHub Copilot
### Prerequisites Before starting, complete the [VS Code Initial Setup](../vscode-setup.md) for Copilot and Copilot Chat. This covers installing VS Code, GitHub Copilot, signing in, and verifying suggestions.
- VS Code installed and up to date.
- GitHub account with Copilot Enterprise access.
### Install and Sign In (High-Level) Once Copilot is working, continue below for Android-specific guidance.
1. Install the GitHub Copilot extension.
2. Sign in with your GitHub account.
3. Confirm Copilot is enabled in VS Code.
4. Run a simple prompt to verify suggestions appear.
### Example Prompt (VS Code)
Open a Kotlin file and add:
Example prompt:
```text
// Create a Kotlin data class for a user profile with name and email.
```
### Verification Steps
- Open a Kotlin file and start a small function.
- Confirm inline suggestions appear.
- Open Copilot Chat and ask a short question.
## Android-Specific Guidance ## Android-Specific Guidance
- Ask for Kotlin/Java patterns with small, bounded tasks. - Ask for Kotlin/Java patterns with small, bounded tasks.
@ -45,7 +26,7 @@ Refactor this repository to reduce duplication. Keep the public API the same and
``` ```
## MCP For Android (High-Level) ## MCP For Android (High-Level)
MCP tools can automate Android tasks like builds, tests, and diagnostics. The exact tool depends on your team setup. MCP tools can automate Android tasks like builds, tests, and diagnostics. Complete the [VS Code Initial Setup](../vscode-setup.md) first, then follow your team’s approved Android MCP tool instructions here.
### What To Add Here ### What To Add Here
When you identify the approved Android MCP tool(s), add: When you identify the approved Android MCP tool(s), add:
@ -72,6 +53,6 @@ Refactor this file to reduce duplication without changing behavior.
- Multiple AI extensions competing for suggestions. - Multiple AI extensions competing for suggestions.
## Next Steps ## Next Steps
- For workflow patterns, read [Cross-Platform AI Usage](cross-platform.md). - For workflow patterns, read [Cross-Platform AI Usage](../cross-platform.md).
- For safety rules, read [Governance, Privacy, and Policy](governance.md). - For safety rules, read [Governance, Privacy, and Policy](../governance.md).
- For cost guidance, read [Usage and Token Budgeting](usage-tokens.md). - For cost guidance, read [Usage and Token Budgeting](../usage-tokens.md).

175
docs/ai/cross-platform.md
View File

@ -1,175 +0,0 @@
# Cross-Platform AI Usage
You are here: [AI Docs Home](index.md) > Cross-Platform AI Usage
## Contents
- Instructions (Always-On Rules)
- Agents.md
- Agents vs Skills
- Prompting Patterns
- Prompting Anti-Patterns
- Plan-First Workflow
- Starter Prompts
- MCP Overview
- Next Steps
## Instructions (Always-On Rules)
Instructions are repo-scoped rules that auto-apply based on file patterns. They are always on and do not need to be invoked.
Where they live:
- Repo instructions directory (for example, [assets/instructions/](../../assets/instructions/))
- Editor or org-level instruction files when configured by your team
## Agents.md
### What It Is
Agents define a structured workflow so tasks are broken into clear steps, with explicit inputs and outputs.
### How to Use It
1. Read [Agents.md](../../Agents.md).
2. Choose a workflow that matches your task.
3. Provide the inputs in a short, bounded request.
### Example Request
Example prompt:
```text
Goal: Improve readability in this module
Inputs: src/foo/Bar.kt, keep behavior the same
Output: A small refactor and a short summary
Verification: No tests needed
```
### When to Use Agents vs Chat
- Use agents for multi-step tasks like refactors, doc audits, or migrations.
- Use chat for quick questions or one-off explanations.
## Agents vs Skills (Quick Compare)
- Agents are full modes/personas that control behavior end-to-end. They can be stored in a repo or a user-level folder.
- Skills are focused workflows you load for specific tasks. They are typically installed globally via the approved skills directory.
## Chat Modes In Copilot
Ask: Quick Q and A or summaries.
Edit: Targeted file edits with constraints.
Plan: Planning only, no edits yet.
Agent: Multi-step work across files or tools.
Example prompts:
```text
Ask: Explain this error message and list the top 3 likely fixes.
Edit: In this file, extract a helper function for validation and keep behavior the same.
Plan: Provide a 5-step plan to split this class into smaller components. Wait for approval.
Agent: Refactor the service layer, update tests, run the test task, and summarize results.
```
### Request Template
Use this structure to get consistent results:
```text
Goal: <one sentence>
Inputs: <files, constraints, context>
Output: <expected deliverable>
Verification: <tests or checks>
```
## Prompting Patterns
Example prompts:
```text
Refactors: Refactor this file to improve readability without changing behavior.
Tests: Add unit tests for this service. Keep the existing public API.
Debugging: Explain this error and list likely fixes in order.
Understanding code: Summarize what this module does and call out risks.
```
## Prompting Anti-Patterns (And Fixes)
Common mistakes and better alternatives:
Example prompts:
```text
Too broad: Fix everything in this project.
Better: Refactor this file to remove duplication. Do not change behavior.
Too vague: Make this code better.
Better: Improve naming and add comments only where logic is complex.
Missing inputs: Update the service to handle retries.
Better: Update ServiceA in src/service/ServiceA.kt to retry 2 times on 5xx. Keep API the same.
```
### Example: Too Broad vs Scoped
Example prompts:
```text
Too broad: Fix everything in this project.
Scoped: Refactor this file to remove duplication. Do not change behavior.
```
## Plan-First Workflow
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 prompt:
```text
Provide a 5-step plan to refactor this module. Wait for approval before edits.
```
## Starter Prompts (Copy/Paste)
Use these when you are not sure where to begin:
Example prompts:
```text
Summarize this file in 5 bullets and list 2 risks.
Refactor this function to remove duplication. Keep behavior the same.
List tests I should add for this change.
Explain this error and propose the top 3 fixes.
Create a 5-step plan to split this class into smaller components.
```
## Connecting Skills
- Use skills for tasks with known workflows.
- Combine multiple skills when a task spans domains.
- Pass concise context between steps to reduce repetition.
## Efficiency Tips
- Keep prompts small and scoped.
- Reuse context from earlier steps instead of repeating it.
- Ask for summaries before asking for edits.
### Example Summary Request
Example prompt:
```text
Summarize the decisions so far in 6 bullets so I can start a new chat.
```
## MCP (Model Context Protocol) - Cross-Platform Overview
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
Think of MCP as a set of safe, structured buttons the assistant can press. You ask a question, the assistant calls a tool, and it returns a clear result.
### Common MCP Use Cases (All Platforms)
- Run builds and tests
- Fetch logs or diagnostics
- Query project configuration
- Generate previews or reports
### Example Workflow
1. Ask the assistant to run a build.
2. The MCP tool runs it and returns the result.
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.md)
- Android examples: see [Android Setup](android.md)
## Next Steps
- If you need skills guidance, read [Skills Library](skills.md).
- For safety rules, read [Governance, Privacy, and Policy](governance.md).
- If setup is not working, follow [Troubleshooting and FAQ](troubleshooting.md).

23
docs/ai/crossplatform/cross-platform.md Normal file
View File

@ -0,0 +1,23 @@
# Cross-Platform AI Usage (Overview)
You are here: [AI Docs Home](../index.md) > Cross-Platform AI Usage
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
- [Prompting Patterns](prompting-patterns.md)
- [Prompting Anti-Patterns](prompting-antipatterns.md)
- [Plan-First Workflow](plan-first-workflow.md)
- [Starter Prompts](starter-prompts.md)
- [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/)).
## Agents and Skills
- Agents: Use for multi-step, structured tasks (see [Agents.md](../../Agents.md)).
- Skills: Use for focused, repeatable workflows (see [Skills Library](../skills.md)).
## Next Steps
- For safety rules, read [Governance, Privacy, and Policy](../governance.md)
- If setup is not working, follow [Troubleshooting and FAQ](../troubleshooting.md)

24
docs/ai/crossplatform/mcp-overview.md Normal file
View File

@ -0,0 +1,24 @@
# MCP (Model Context Protocol) - Cross-Platform Overview
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
Think of MCP as a set of safe, structured buttons the assistant can press. You ask a question, the assistant calls a tool, and it returns a clear result.
## Common MCP Use Cases (All Platforms)
- Run builds and tests
- Fetch logs or diagnostics
- Query project configuration
- Generate previews or reports
## Example Workflow
1. Ask the assistant to run a build.
2. The MCP tool runs it and returns the result.
3. You ask for a summary and next steps.
## Example Prompt
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)

10
docs/ai/crossplatform/plan-first-workflow.md Normal file
View File

@ -0,0 +1,10 @@
# Plan-First Workflow
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
Provide a 5-step plan to refactor this module. Wait for approval before edits.

17
docs/ai/crossplatform/prompting-antipatterns.md Normal file
View File

@ -0,0 +1,17 @@
# Prompting Anti-Patterns (And Fixes)
Common mistakes and better alternatives:
**Too broad:** Fix everything in this project.
**Better:** Refactor this file to remove duplication. Do not change behavior.
**Too vague:** Make this code better.
**Better:** Improve naming and add comments only where logic is complex.
**Missing inputs:** Update the service to handle retries.
**Better:** Update ServiceA in src/service/ServiceA.kt to retry 2 times on 5xx. Keep API the same.
### Example: Too Broad vs Scoped
Too broad: Fix everything in this project.
Scoped: Refactor this file to remove duplication. Do not change behavior.

8
docs/ai/crossplatform/prompting-patterns.md Normal file
View File

@ -0,0 +1,8 @@
# Prompting Patterns
Example prompts:
- Refactor this file to improve readability without changing behavior.
- Add unit tests for this service. Keep the existing public API.
- Explain this error and list likely fixes in order.
- Summarize what this module does and call out risks.

9
docs/ai/crossplatform/starter-prompts.md Normal file
View File

@ -0,0 +1,9 @@
# Starter Prompts (Copy/Paste)
Use these when you are not sure where to begin:
- Summarize this file in 5 bullets and list 2 risks.
- Refactor this function to remove duplication. Keep behavior the same.
- List tests I should add for this change.
- Explain this error and propose the top 3 fixes.
- Create a 5-step plan to split this class into smaller components.

34
docs/ai/index.md
View File

@ -5,28 +5,25 @@ You are here: AI Docs Home
## Contents ## Contents
- Guided Paths - Guided Paths
- Start Here - Start Here
- Platform Setup
- [VS Code Initial Setup](vscode-setup.md)
- [iOS Setup](ios/ios.md)
- [Android Setup](android/android.md)
- Use AI Day-To-Day - Use AI Day-To-Day
- Safety And Cost - Safety And Cost
- iOS MCP Details
Welcome. This section is the entry point for AI enablement. It assumes no prior knowledge and is safe to follow step-by-step.
## Who This Is For
You can be an expert engineer and still be new to AI. This guide explains every step and includes examples to keep you from guessing.
## How To Use This Guide ## How To Use This Guide
Follow the steps in order. Do not skip ahead if this is your first time. Follow the steps in order. Do not skip ahead if this is your first time.
### Example Path (New iOS Engineer) ### Example Path (New iOS Engineer)
1. Read [AI Overview](overview.md) 1. Read [AI Overview](overview.md)
2. Follow [iOS Setup](ios.md) 2. Follow [iOS Setup](ios/ios.md)
3. Skim [Usage and Token Budgeting](usage-tokens.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](cross-platform.md)
## Guided Paths (Pick One) ## 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](cross-platform.md) -> [Usage and Token Budgeting](usage-tokens.md)
- iOS setup: [AI Overview](overview.md) -> [iOS Setup](ios.md) -> [XcodeBuildMCP (iOS)](ios-xcodebuildmcp.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.md) -> [Cross-Platform AI Usage](cross-platform.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) - Contributors: [AI Overview](overview.md) -> [Governance, Privacy, and Policy](governance.md) -> [Troubleshooting and FAQ](troubleshooting.md)
## If You Are New ## If You Are New
@ -40,20 +37,19 @@ If you will edit these docs, start with the "Key Repo Files" section in the over
## Start Here ## Start Here
- [AI Overview](overview.md) - [AI Overview](overview.md)
- [iOS Setup](ios.md) - [iOS Setup](ios/ios.md)
- [Android Setup](android.md) - [Android Setup](android/android.md)
## Use AI Day-To-Day ## Use AI Day-To-Day
- [Cross-Platform AI Usage](cross-platform.md) - Agents, instructions, prompting patterns, MCP overview, and workflow tips - [Cross-Platform AI Usage](crossplatform/cross-platform.md) - Overview, agent workflows, and navigation to:
- [Prompting Patterns](crossplatform/prompting-patterns.md)
- [Prompting Anti-Patterns](crossplatform/prompting-antipatterns.md)
- [Plan-First Workflow](crossplatform/plan-first-workflow.md)
- [Starter Prompts](crossplatform/starter-prompts.md)
- [MCP Overview](crossplatform/mcp-overview.md)
- [Skills Library](skills.md) - [Skills Library](skills.md)
## Safety And Cost ## Safety And Cost
- [Governance, Privacy, and Policy](governance.md) - [Governance, Privacy, and Policy](governance.md)
- [Usage and Token Budgeting](usage-tokens.md) - [Usage and Token Budgeting](usage-tokens.md)
- [Troubleshooting and FAQ](troubleshooting.md) - [Troubleshooting and FAQ](troubleshooting.md)
## iOS MCP Details
- [XcodeBuildMCP (iOS)](ios-xcodebuildmcp.md) - Full MCP setup and usage for Xcode workflows
## Confluence Mapping
This folder maps 1:1 to Confluence pages so content can be copied without rework.

99
docs/ai/ios.md
View File

@ -1,99 +0,0 @@
# iOS AI Setup
You are here: [AI Docs Home](index.md) > iOS Setup
## Contents
- Setup Path A (Xcode)
- Setup Path B (VS Code)
- iOS-Specific Guidance
- MCP For iOS
- iOS Troubleshooting
- Next Steps
## Setup Path A: Xcode + GitHub Copilot for Xcode
### Prerequisites
- Xcode installed and up to date.
- GitHub account with Copilot Enterprise access.
### Install and Sign In (High-Level)
1. Install the GitHub Copilot for Xcode plugin.
2. Sign in with your GitHub account.
3. Confirm Copilot is enabled in Xcode.
4. Run a simple prompt to verify suggestions appear.
### Example Prompt (Xcode)
Type this in a Swift file comment, then wait for a suggestion:
Example prompt:
```text
// Create a function that validates an email string.
```
### Verification Steps
- Open a Swift file and start a small function.
- Confirm inline suggestions appear.
- Open the Copilot chat panel and ask a short question.
## Setup Path B: VS Code + GitHub Copilot Extension
### When to Use VS Code on iOS
- Editing shared docs or configs.
- Rapid refactors or explorations.
- Working on multi-platform files.
### Install and Sign In (High-Level)
1. Install VS Code and the GitHub Copilot extension.
2. Sign in with your GitHub account.
3. Confirm Copilot is enabled in VS Code.
4. Run a simple prompt to verify suggestions appear.
### Example Prompt (VS Code)
Open a Swift file and add:
Example prompt:
```text
// Create a Swift struct for a user profile with name and email.
```
### Verification Steps
- Open a Swift file and type a short function signature.
- Confirm inline suggestions appear.
- Open Copilot Chat and request a short summary.
## iOS-Specific Guidance
- Ask for Swift/SwiftUI patterns with small, bounded tasks.
- Request tests or sample usages for view models.
- Favor refactor or patch requests over full rewrites.
### Example Request
Example prompt:
```text
Refactor this SwiftUI view to reduce duplication. Do not change behavior. Provide a short diff summary.
```
### Starter Prompts
Example prompts:
```text
Create a SwiftUI view model for this screen and list its inputs and outputs.
Write unit tests for this view model using XCTest.
Refactor this view to reduce duplication without changing behavior.
```
## MCP For iOS
The detailed MCP setup and XcodeBuildMCP guidance is in a dedicated page:
- [XcodeBuildMCP (iOS)](ios-xcodebuildmcp.md)
## iOS Troubleshooting
- If suggestions are missing, confirm sign-in and access.
- If the plugin is not visible, verify extension compatibility.
- If responses are blocked, check network or policy constraints.
### Common Setup Gaps
- Copilot access not provisioned for the GitHub account.
- Xcode plugin disabled after update.
- Multiple AI plugins competing for suggestions.
## Next Steps
- For workflow patterns, read [Cross-Platform AI Usage](cross-platform.md).
- For MCP automation, read [XcodeBuildMCP (iOS)](ios-xcodebuildmcp.md).
- For safety rules, read [Governance, Privacy, and Policy](governance.md).

88
docs/ai/ios/ios-mcp-vscode.md Normal file
View File

@ -0,0 +1,88 @@
# MCP for iOS in VS Code
You are here: [AI Docs Home](../index.md) > MCP for iOS in VS Code
## Contents
- Overview
- Prerequisites
- XcodeBuildMCP Setup
- Xcode Native MCP Setup
- Example Prompts
- Troubleshooting
- Next Steps
---
## Overview
This guide covers how to set up MCP (Model Context Protocol) automation for iOS development in VS Code. Complete the [VS Code Initial Setup](../vscode-setup.md) first.
---
## Prerequisites
- macOS with Xcode 26.3+ installed (for native MCP) or Xcode 13+ (for XcodeBuildMCP)
- VS Code with GitHub Copilot and Copilot Chat enabled ([see setup guide](../vscode-setup.md))
- Node.js 18+ (for XcodeBuildMCP)
- This repo opened in VS Code (workspace root)
---
## XcodeBuildMCP Setup (External Tool)
1. Install XcodeBuildMCP:
```bash
brew tap getsentry/xcodebuildmcp
brew install xcodebuildmcp
```
2. Ensure `.xcodebuildmcp/config.yaml` is present and configured for your workspace, scheme, and simulator.
3. Add or update `.vscode/mcp.json`:
```json
{
"servers": {
"XcodeBuildMCP": {
"command": "xcodebuildmcp",
"args": ["mcp"]
}
}
}
```
4. Restart VS Code. Copilot Chat will discover MCP tools.
---
## Xcode Native MCP Setup (Xcode 26.3+)
1. Open Xcode.
2. Go to Settings > Intelligence tab.
3. Enable Model Context Protocol (toggle on Xcode Tools or Allow external connections).
4. Add or update `.vscode/mcp.json`:
```json
{
"servers": {
"XcodeNative": {
"command": "xcrun",
"args": ["mcpbridge"]
}
}
}
```
5. Restart VS Code. Copilot Chat will discover the native MCP server.
---
## Example Prompts
- "Build and run ToyotaOneApp on the iPhone 17 Pro Max simulator."
- "Run all UI tests and summarize failures."
- "Take a screenshot of the home screen."
---
## Troubleshooting
- If MCP tools are not available, confirm `.vscode/mcp.json` is present and correct.
- For XcodeBuildMCP, check `.xcodebuildmcp/config.yaml` for correct paths and scheme.
- Simulator not found? Boot it in Xcode or Simulator.app first.
---
## Next Steps
- For general VS Code setup, see [VS Code Initial Setup](../vscode-setup.md).
- For iOS basics, see [iOS Setup](ios.md).

37
docs/ai/ios/ios-mcp.md Normal file
View File

@ -0,0 +1,37 @@
# iOS MCP Overview
You are here: [AI Docs Home](../index.md) > iOS MCP Overview
## What is MCP for iOS?
MCP (Model Context Protocol) enables automation and agent workflows for iOS development. It allows tools like Copilot Chat to build, test, run, and interact with Xcode projects programmatically.
## Why Use MCP?
- Automate builds, tests, and diagnostics
- Enable agentic workflows in Copilot Chat and other tools
- Standardize and speed up repetitive tasks
- Reduce context switching between tools
## MCP Options for iOS
There are two main ways to use MCP with iOS projects:
### 1. Xcode Native MCP (Xcode 26.3+)
- Built into Xcode 26.3 and later
- Official Apple support
- Best for seamless integration and live previews
- [Setup & details](ios-xcodebuildmcp-xcode.md)
### 2. XcodeBuildMCP (External Tool)
- Open-source bridge for Xcode 13+ (works with older versions)
- More configuration and CI/CD options
- Best for advanced automation or older Xcode setups
- [Setup & details](ios-xcodebuildmcp-vscode.md)
## When to Use Which?
- Use Xcode Native MCP for the simplest, most integrated experience (especially for new projects or live previews)
- Use XcodeBuildMCP if you need advanced automation, CI/CD, or support for older Xcode versions
- You can configure both and switch as needed in VS Code’s `.vscode/mcp.json`
## Next Steps
- [MCP for iOS in VS Code](ios-mcp-vscode.md)
- [XcodeBuildMCP (Xcode)](ios-xcodebuildmcp-xcode.md)
- [XcodeBuildMCP for iOS in VS Code](ios-xcodebuildmcp-vscode.md)

160
docs/ai/ios/ios-xcodebuildmcp-vscode.md Normal file
View File

@ -0,0 +1,160 @@
# XcodeBuildMCP for iOS in VS Code
You are here: [AI Docs Home](../index.md) > XcodeBuildMCP for iOS in VS Code
## Contents
- Overview
- Requirements
- One-time Repo Setup
- XcodeBuildMCP Installation & Configuration
- Using XcodeBuildMCP in Copilot Chat
- Common Actions & Prompts
- Troubleshooting
- References
- Next Steps
---
## Overview
XcodeBuildMCP lets you run Xcode build and test tasks from within VS Code, using agent workflows and Copilot Chat. This reduces context switching and makes iOS automation repeatable.
---
## Requirements
- macOS with Xcode installed (includes iOS Simulator)
- VS Code with GitHub Copilot Chat enabled
- MCP tools configured in VS Code (repo includes .vscode/mcp.json)
- Node.js 18+ (required by the MCP host)
- This repo opened in VS Code (workspace root)
Optional but commonly needed for successful builds:
- Ruby + Bundler
- CocoaPods
- Flutter + FVM (if working on the Flutter module)
---
## One-time Repo Setup
Run the standard project setup so builds succeed:
1. `./scripts/setup.sh`
2. `bundle exec pod install`
3. If using Flutter: `cd ../oneappmodule-2.0/apps/oneapp && fvm flutter pub get`
---
## XcodeBuildMCP Installation & Configuration
### 1. Install XcodeBuildMCP
```bash
brew tap getsentry/xcodebuildmcp
brew install xcodebuildmcp
```
### 2. Configure XcodeBuildMCP
- The repo should include `.xcodebuildmcp/config.yaml`. Make sure it points to the correct workspace, scheme, and simulator.
Example (Toyota):
```yaml
schemaVersion: 1
sessionDefaults:
workspacePath: ./OneApp.xcworkspace
scheme: ToyotaOneApp
configuration: Debug
simulatorName: iPhone 17 Pro Max
simulatorId: <SIMULATOR_UDID>
useLatestOS: true
```
Notes:
- Use either `simulatorName` or `simulatorId`. If both are set, `simulatorId` takes precedence.
- The simulator must be installed and booted before running build/run.
### 3. Configure MCP in VS Code
- Ensure `.vscode/mcp.json` exists:
```json
{
"servers": {
"XcodeBuildMCP": {
"command": "xcodebuildmcp",
"args": ["mcp"]
}
}
}
```
- Restart VS Code or reload the window. Copilot should discover the tools.
---
## Using XcodeBuildMCP in Copilot Chat
From Copilot Chat, you can ask to build and run via XcodeBuildMCP. Example prompts:
- "build and run ToyotaOneApp on the iPhone 17 Pro Max simulator"
- "launch ToyotaOneApp without building (use the existing build)"
- "take a screenshot of the home screen"
Common tool actions the agent will use:
- list_devices, list_schemes
- session_set_defaults
- build_run_sim
- launch_app_sim (no build)
- screenshot
---
## Common Actions & Prompts
- **Build:**
"Use XcodeBuildMCP to build the app for the iOS simulator and summarize errors in 5 bullets."
- **Unit Tests:**
"Run unit tests with XcodeBuildMCP and list failing tests with file names."
- **UI Tests:**
"Run UI tests with XcodeBuildMCP on iPhone 17 Pro Max (iOS 26.2) and list any failures."
- **Screenshots:**
"Run the UI test that captures screenshots and list the output paths."
- **Run without building:**
"launch ToyotaOneApp without building"
- **Home screen screenshot (example flow):**
1. "launch ToyotaOneApp without building"
2. Wait for the app to load the home screen
3. "take a screenshot of the home screen"
---
## Troubleshooting
- **Build DB locked:** another build is running. Stop it and retry.
- **Wrong scheme or workspace:** confirm in `.xcodebuildmcp/config.yaml`.
- **Simulator not found:** install/boot the simulator in Xcode or Simulator.app.
- If MCP tools are not available in VS Code, confirm `.vscode/mcp.json` is present and enabled.
---
## References
- https://github.com/getsentry/XcodeBuildMCP
- https://www.apple.com/newsroom/2026/02/xcode-26-point-3-unlocks-the-power-of-agentic-coding/
- https://code.visualstudio.com/docs/copilot/customization/mcp-servers
---
## Next Steps
- For iOS setup basics, read [iOS Setup](ios.md).
- For cross-platform usage patterns, read [Cross-Platform AI Usage](../cross-platform.md).

51
docs/ai/ios-xcodebuildmcp.md → docs/ai/ios/ios-xcodebuildmcp-xcode.md
View File

@ -1,16 +1,16 @@
# XcodeBuildMCP (iOS) # XcodeBuildMCP (Xcode)
You are here: [AI Docs Home](index.md) > XcodeBuildMCP (iOS) You are here: [AI Docs Home](../index.md) > XcodeBuildMCP (Xcode)
## Contents ## Contents
- What XcodeBuildMCP Is - What XcodeBuildMCP Is
- What It Can Do - What It Can Do
- Xcode 26.3 MCP Setup - Xcode 26.3 MCP Setup (Xcode)
- Standardize The Simulator - Standardize The Simulator
- References - References
- Next Steps - Next Steps
This page focuses on MCP-based Xcode workflows and the XcodeBuildMCP setup. This page focuses on MCP-based Xcode workflows and the XcodeBuildMCP setup for Xcode users.
## What XcodeBuildMCP Is ## What XcodeBuildMCP Is
XcodeBuildMCP can run build and test tasks without you switching into Xcode for every step. This reduces context switching and makes workflows repeatable. XcodeBuildMCP can run build and test tasks without you switching into Xcode for every step. This reduces context switching and makes workflows repeatable.
@ -73,14 +73,10 @@ Example prompt:
Build with XcodeBuildMCP and extract the first error message only. Build with XcodeBuildMCP and extract the first error message only.
``` ```
## Xcode 26.3 MCP Setup (Detailed) ## Xcode 26.3 MCP Setup (Xcode)
These steps reflect a common setup as of February 2026. Wording may vary slightly in release candidates.
### Prerequisites ### Prerequisites
- Xcode 26.3 (RC or full release), opened at least once with your project - Xcode 26.3 (RC or full release), opened at least once with your project
- VS Code installed (stable or Insiders)
- GitHub Copilot extension installed and signed in
- Node.js and npm installed (for XcodeBuildMCP)
### Step 1: Enable Xcode MCP Server ### Step 1: Enable Xcode MCP Server
1. Open Xcode. 1. Open Xcode.
@ -89,29 +85,7 @@ These steps reflect a common setup as of February 2026. Wording may vary slightl
4. Find the Model Context Protocol section. 4. Find the Model Context Protocol section.
5. Toggle on Xcode Tools (or Allow external connections). 5. Toggle on Xcode Tools (or Allow external connections).
### Step 2: Install And Configure XcodeBuildMCP (Recommended Bridge) ### Step 2: Optional Native Xcode MCP Bridge
Install:
```bash
npm install -g xcodebuildmcp@latest
```
Add to VS Code (create or edit .vscode/mcp.json):
```json
{
"servers": {
"XcodeBuildMCP": {
"command": "npx",
"args": ["-y", "xcodebuildmcp@latest", "mcp"]
}
}
}
```
Restart VS Code or reload the window. Copilot should discover the tools.
### Step 3: Optional Native Xcode MCP Bridge
Xcode 26.3 includes a native MCP bridge. This exposes Xcode tools directly. Xcode 26.3 includes a native MCP bridge. This exposes Xcode tools directly.
Add to VS Code: Add to VS Code:
@ -127,20 +101,9 @@ Add to VS Code:
} }
``` ```
### Using MCP In VS Code With Copilot
1. Open your iOS project in VS Code.
2. Use Copilot Chat in agent mode for multi-step tasks.
3. MCP tools appear as slash commands once discovered.
Example prompt:
```text
Use XcodeBuildMCP to build and summarize errors. Then suggest fixes.
```
### Tips And Caveats ### Tips And Caveats
- Xcode must be running (or launchable) for MCP tools to respond. - Xcode must be running (or launchable) for MCP tools to respond.
- Native Xcode MCP is often best for previews. - Native Xcode MCP is often best for previews.
- XcodeBuildMCP is often best for heavy builds and automation.
## Standardize The Simulator (Avoid Back-And-Forth) ## Standardize The Simulator (Avoid Back-And-Forth)
Pin a simulator name and OS version in your project guidance so the assistant always uses the same target. Pin a simulator name and OS version in your project guidance so the assistant always uses the same target.
@ -183,4 +146,4 @@ https://www.apple.com/newsroom/2026/02/xcode-26-point-3-unlocks-the-power-of-age
## Next Steps ## Next Steps
- For iOS setup basics, read [iOS Setup](ios.md). - 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](../cross-platform.md).

47
docs/ai/ios/ios.md Normal file
View File

@ -0,0 +1,47 @@
# iOS AI Setup (Quick Start)
You are here: [AI Docs Home](../index.md) > iOS Setup
## Which Path Should I Choose?
- **Use Xcode** if you want the most integrated Apple experience for Swift/SwiftUI and UI design.
- **Use VS Code** if you want automation, Copilot Chat agent workflows, or work on cross-platform code.
- You can use both! Many developers do.
---
## Xcode: Copilot Setup Steps
1. Install Xcode from the Mac App Store and open it once.
2. Install the [GitHub Copilot for Xcode plugin](https://github.com/github/copilot-xcode) and enable it in Xcode’s Extensions.
3. Sign in with your GitHub account (Copilot access required).
4. Open a Swift file and type `//` to trigger a suggestion.
5. Open Copilot Chat and try a simple prompt (e.g., “Write a Swift function to reverse a string”).
## VS Code: Copilot Setup Steps
1. Follow the [VS Code Initial Setup](../vscode-setup.md) to install VS Code, Copilot, and sign in.
2. Open a Swift file and type `//` to trigger a suggestion.
3. Open Copilot Chat and try a simple prompt.
---
## Add MCP Automation (Optional, Advanced)
- For general MCP usage in VS Code: See [MCP for iOS in VS Code](ios-mcp-vscode.md)
- For Xcode’s built-in MCP: See [XcodeBuildMCP (Xcode)](ios-xcodebuildmcp-xcode.md)
- For XcodeBuildMCP in VS Code: See [XcodeBuildMCP for iOS in VS Code](ios-xcodebuildmcp-vscode.md)
---
## Troubleshooting
- If suggestions are missing, confirm you’re signed in and Copilot is enabled.
- If the plugin/extension is not visible, check compatibility and restart the app.
- If responses are blocked, check your network or company policy.
- If you have multiple AI plugins, disable all but Copilot.
---
## Next Steps
- For cross-platform patterns, read [Cross-Platform AI Usage](../cross-platform.md)
- For automation, see the MCP guides above
- For safety rules, read [Governance, Privacy, and Policy](../governance.md)

2
docs/ai/overview.md
View File

@ -211,7 +211,7 @@ Refactor only the validation logic in this file. Keep behavior the same and list
``` ```
## Next Steps ## Next Steps
- If you have not set up an editor yet, go to [iOS Setup](ios.md) or [Android Setup](android.md). - 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](cross-platform.md).
- For safety and cost guidance, read [Governance, Privacy, and Policy](governance.md) and [Usage and Token Budgeting](usage-tokens.md). - For safety and cost guidance, read [Governance, Privacy, and Policy](governance.md) and [Usage and Token Budgeting](usage-tokens.md).

57
docs/ai/vscode-setup.md Normal file
View File

@ -0,0 +1,57 @@
# VS Code Initial Setup (All Platforms)
You are here: [AI Docs Home](index.md) > VS Code Initial Setup
## Contents
- Overview
- Install VS Code
- Install GitHub Copilot
- Sign In and Verify
- Try Copilot Suggestions
- Next Steps
---
## Overview
This guide covers the basic setup for Visual Studio Code and GitHub Copilot. It applies to all platforms (iOS, Android, cross-platform). Complete these steps before any platform-specific automation or MCP setup.
---
## Install VS Code
1. Download Visual Studio Code from [code.visualstudio.com](https://code.visualstudio.com/).
2. Open the installer and follow the prompts to install.
3. Launch VS Code.
---
## Install GitHub Copilot
1. In VS Code, open the Extensions sidebar (⇧⌘X).
2. Search for "GitHub Copilot" and click Install.
3. (Optional) Search for and install "GitHub Copilot Chat" for chat-based workflows.
---
## Sign In and Verify
1. After installing, you’ll be prompted to sign in with your GitHub account.
2. Complete the sign-in flow in your browser.
3. You must have Copilot access (Copilot Individual, Business, or Enterprise).
4. Open a code file (e.g., Swift, Kotlin, Java, JS) and type `//` or start a function to trigger a suggestion.
5. You should see Copilot suggestions inline.
---
## Try Copilot Suggestions
- Open a file for your platform (Swift for iOS, Kotlin for Android, etc.).
- Type a comment or function signature, e.g.:
- `// Create a function to validate an email address.`
- `fun main() {` (for Kotlin)
- Accept a suggestion with Tab or Enter.
- Open the Copilot Chat sidebar and try a prompt, e.g.:
- "Write a function to reverse a string in Kotlin."
---
## Next Steps
- For iOS automation, see [MCP for iOS in VS Code](ios/ios-mcp-vscode.md).
- For Android automation, see [Android Setup](android/android.md).

2
docs/planning/AI-Docs-Plan.md
View File

@ -33,7 +33,7 @@ The docs under docs/ai map 1:1 to Confluence pages.
- overview.md - overview.md
- ios.md - ios.md
- ios-xcodebuildmcp.md - ios-xcodebuildmcp.md
- android.md - android/android.md
- cross-platform.md - cross-platform.md
- skills.md - skills.md
- usage-tokens.md - usage-tokens.md