commit 2500b54bcc2bd2be1c7a1dbd383a1fbe822021af Author: Matt Bruce Date: Tue Feb 10 13:55:42 2026 -0600 chore: initial docs diff --git a/AI-Docs-Plan.md b/AI-Docs-Plan.md new file mode 100644 index 0000000..0370f1e --- /dev/null +++ b/AI-Docs-Plan.md @@ -0,0 +1,138 @@ +# AI Documentation Plan + +## Purpose +Create a Confluence-ready hierarchy and an initial documentation set that assumes zero prior knowledge. This plan now maps directly to markdown files under a docs folder. + +## Proposed Folder Structure +- docs/ + - ai/ + - index.md + - overview.md + - ios.md + - android.md + - cross-platform.md + - skills.md + - usage-tokens.md + - troubleshooting.md + - governance.md + +## Top-Level Hierarchy (Confluence) +1. AI Overview +2. iOS (Xcode + optional VS Code) +3. Android (VS Code) +4. Cross-Platform AI Usage +5. Skills Library +6. Usage and Token Budgeting +7. Troubleshooting and FAQ +8. Governance, Privacy, and Policy + +## 1) AI Overview +- Start Here + - What AI is and is not (short definitions) + - What problems AI can help with (examples) + - What not to use AI for (guardrails) +- GitHub Copilot Enterprise + - What it is + - Access requirements + - Account setup steps +- Terminology + - Copilot + - Chat + - Agents + - Skills + - Tokens and usage +- Getting Help + - Who to contact + - Where to report issues + +## 2) iOS (Xcode + optional VS Code) +- Setup Path A: Xcode + GitHub Copilot for Xcode + - Prerequisites + - Install plugin + - Sign in and verify + - First-use walkthrough +- Setup Path B: VS Code + GitHub Copilot extension + - When to use VS Code on iOS + - Install extension + - Sign in and verify + - First-use walkthrough +- iOS-Specific Guidance + - Swift/SwiftUI tips + - Common prompt patterns for iOS +- iOS Troubleshooting + - Login issues + - Suggestions not appearing + - Network or policy blocks + +## 3) Android (VS Code) +- Setup: VS Code + GitHub Copilot extension + - Prerequisites + - Install extension + - Sign in and verify + - First-use walkthrough +- Android-Specific Guidance + - Kotlin/Java tips + - Common prompt patterns for Android +- Android Troubleshooting + - Login issues + - Suggestions not appearing + - Network or policy blocks + +## 4) Cross-Platform AI Usage +- Agents.md + - What it is + - How to use it (copy/paste examples) + - When to use agents vs chat +- Prompting Patterns + - Asking for refactors + - Writing tests + - Debugging errors + - Explaining unfamiliar code +- Connecting Skills + - When to use a skill + - How to chain multiple skills + - How to pass context between steps + +## 5) Skills Library +- What skills are +- How to download existing skills +- How to enable or configure skills +- Current Skills (add repo links) + - onboarding-cro (link) + - revenuecat-ios-integration (link) + - find-skills (link) + - swiftui-expert-skill (link) + - mcp-builder (link) + - pdf (link) + - skill-creator (link) + - template-skill (link) + - webapp-testing (link) + +## 6) Usage and Token Budgeting +- How tokens are spent (simple model) +- Best practices to reduce usage + - Use clear, bounded requests + - Prefer edits over full rewrites + - Reuse context instead of re-sending +- Daily and monthly budgeting tips +- Red flags that burn tokens quickly +- Quick checklist + +## 7) Troubleshooting and FAQ +- Setup and login errors +- Extension or plugin conflicts +- Company network restrictions +- Why suggestions are low quality +- When to escalate + +## 8) Governance, Privacy, and Policy +- What data is allowed +- What data is forbidden +- Safe prompts and examples +- Compliance and audit expectations + +## Next Steps +- Assign owners per section +- Link skills to their repos +- Add screenshots and short videos +- Set review cadence diff --git a/Agents.md b/Agents.md new file mode 100644 index 0000000..4a36e71 --- /dev/null +++ b/Agents.md @@ -0,0 +1,32 @@ +# Agents + +## Purpose +This file defines how to use agent-style workflows in this project so tasks are clear, scoped, and repeatable. + +## When to Use Agents +- Multi-step changes across files. +- Refactors with clear acceptance criteria. +- Audits or documentation updates. + +## Common Agent Use Cases +- Create or expand documentation sections. +- Plan a refactor before making edits. +- Summarize and assess risks across files. + +## How to Use Agents +1. Define the outcome in one sentence. +2. List inputs (files, context, constraints). +3. Ask for a plan, then approve before edits. +4. Ask for focused changes and verification steps. + +## Suggested Agent Request Template +- Goal: (one sentence) +- Inputs: (files, context, constraints) +- Output: (expected deliverable) +- Verification: (tests or checks) + +## Example +Goal: Add a troubleshooting section to the AI docs. +Inputs: docs/ai/troubleshooting.md, AI-Docs-Plan.md +Output: Updated troubleshooting section with 5 common issues. +Verification: Manual review. diff --git a/PRD.md b/PRD.md new file mode 100644 index 0000000..bf48310 --- /dev/null +++ b/PRD.md @@ -0,0 +1,64 @@ +# Product Requirements Document (PRD) + +## Product +AI Documentation for Mobile Development + +## Problem Statement +Teams need a clear, zero-knowledge onboarding path for AI tools, setup, and usage across iOS and Android. + +## Goals +- Provide a structured, searchable AI docs hierarchy. +- Enable fast setup for Copilot on Xcode and VS Code. +- Document agents, skills, and token budgeting. +- Set guardrails for safe AI usage. + +## Non-Goals +- Replacing official vendor documentation. +- Providing legal or security approvals. +- Enforcing policy compliance. + +## Target Audience +- Mobile engineers (iOS and Android). +- New hires and interns. +- Tech leads who onboard team members. + +## User Stories +- As a new engineer, I can set up Copilot in under 30 minutes. +- As a lead, I can point people to a single AI docs index. +- As a contributor, I can add or update skills guidance. + +## Success Metrics +- Time-to-setup under 30 minutes for new users. +- Reduced setup questions in chat or onboarding sessions. +- Consistent AI usage aligned with policy. + +## Scope +- Confluence-ready structure with markdown source. +- iOS and Android setup guides. +- Skills inventory and usage guidance. +- Token usage guidance and troubleshooting. + +## Assumptions +- The org has a Copilot Enterprise subscription. +- Editors are standard across teams (Xcode and VS Code). +- Policies for data handling are available elsewhere. + +## Dependencies +- GitHub Copilot Enterprise access and provisioning. +- Editor plugins and extensions are approved for use. +- A shared location for skills and updates. + +## Risks and Mitigations +- Outdated instructions: set a review cadence. +- Unclear ownership: assign section owners. +- Overly generic guidance: add platform-specific examples. + +## Milestones +- Draft structure and initial content. +- Review with iOS and Android leads. +- Publish to Confluence and iterate. + +## Open Questions +- Who owns each section and review cadence? +- Where should skill repo links be hosted? +- What screenshots and examples are required? diff --git a/README.md b/README.md new file mode 100644 index 0000000..b834bbc --- /dev/null +++ b/README.md @@ -0,0 +1,34 @@ +# AI Documentation Project + +This repo contains the source markdown for a Confluence-ready AI documentation set for mobile development. It is designed to be beginner-friendly and easy to keep current. + +## Structure +- [AI Docs Index](docs/ai/index.md) +- [Agents](Agents.md) +- [PRD](PRD.md) +- [AI Docs Plan](AI-Docs-Plan.md) + +## How to Use +1. Start at the [AI Docs Index](docs/ai/index.md). +2. Follow the iOS or Android setup guide. +3. Review skills and token usage guidance. + +## Local Workflow +- Edit files in docs/ai. +- Keep sections short and scannable. +- Avoid vendor-specific step details that change frequently. + +## Publish to Confluence +1. Copy the page content from each markdown file. +2. Preserve the hierarchy shown in docs/ai/index.md. +3. Add screenshots or short videos where helpful. + +## Contributing +- Keep content short, direct, and beginner-friendly. +- Add platform-specific examples when possible. +- Update the Skills Library with repo links. + +## Next Steps +- Add screenshots and short walkthrough videos. +- Assign owners per section. +- Publish to Confluence. diff --git a/docs/ai/android.md b/docs/ai/android.md new file mode 100644 index 0000000..1b9b76b --- /dev/null +++ b/docs/ai/android.md @@ -0,0 +1,37 @@ +# Android AI Setup + +## Setup: VS Code + GitHub Copilot Extension +### Prerequisites +- VS Code installed and up to date. +- GitHub account with Copilot Enterprise access. + +### Install and Sign In (High-Level) +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. + +### 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 +- Ask for Kotlin/Java patterns with small, bounded tasks. +- Request unit tests for services and view models. +- Prefer incremental changes over large rewrites. + +### Starter Prompts +- "Create a Kotlin data class and mapper for this API response." +- "Write unit tests for this repository using JUnit." +- "Refactor this file to reduce duplication without changing behavior." + +## Android Troubleshooting +- If suggestions are missing, confirm sign-in and access. +- If the extension is disabled, check extension settings. +- If responses are blocked, check network or policy constraints. + +### Common Setup Gaps +- Copilot access not provisioned for the GitHub account. +- VS Code extension disabled after an update. +- Multiple AI extensions competing for suggestions. diff --git a/docs/ai/cross-platform.md b/docs/ai/cross-platform.md new file mode 100644 index 0000000..e25e619 --- /dev/null +++ b/docs/ai/cross-platform.md @@ -0,0 +1,46 @@ +# Cross-Platform AI Usage + +## 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. + +### 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. + +### Request Template +Use this structure to get consistent results: + +```text +Goal: +Inputs: +Output: +Verification: +``` + +## Prompting Patterns +- 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." + +## 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. + +## 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. diff --git a/docs/ai/governance.md b/docs/ai/governance.md new file mode 100644 index 0000000..bb0f378 --- /dev/null +++ b/docs/ai/governance.md @@ -0,0 +1,30 @@ +# Governance, Privacy, and Policy + +## Allowed Data +- Public information or approved internal content. +- Code that is already in approved repos. + +## Handle With Care +- Customer data or identifiers. +- Security-sensitive configuration. +- Anything not explicitly approved by policy. + +## Forbidden Data +- Secrets, credentials, or personal data. +- Non-approved proprietary information. + +## Safe Prompt Examples +- "Summarize this public API and propose tests." +- "Refactor this function without changing behavior." + +## Redaction Tips +- Remove secrets before pasting. +- Replace real identifiers with placeholders. +- Use minimal context required for the task. + +## Compliance Expectations +- Follow org security policies and data handling rules. +- Use AI as assistance, not authority. + +## Ownership +If you are unsure about data classification, escalate before using AI. diff --git a/docs/ai/index.md b/docs/ai/index.md new file mode 100644 index 0000000..f059015 --- /dev/null +++ b/docs/ai/index.md @@ -0,0 +1,23 @@ +# AI Documentation + +Welcome. This section is the entry point for AI enablement. It assumes no prior knowledge and is safe to follow step-by-step. + +## If You Are New +1. Read the overview to understand terms and guardrails. +2. Follow the setup guide for your platform. +3. Skim skills and usage tips before your first session. + +## Start Here +- [AI Overview](overview.md) +- [iOS Setup](ios.md) +- [Android Setup](android.md) + +## Usage Guides +- [Cross-Platform AI Usage](cross-platform.md) +- [Skills Library](skills.md) +- [Usage and Token Budgeting](usage-tokens.md) +- [Troubleshooting and FAQ](troubleshooting.md) +- [Governance, Privacy, and Policy](governance.md) + +## Confluence Mapping +This folder maps 1:1 to Confluence pages so content can be copied without rework. diff --git a/docs/ai/ios.md b/docs/ai/ios.md new file mode 100644 index 0000000..f393df3 --- /dev/null +++ b/docs/ai/ios.md @@ -0,0 +1,54 @@ +# iOS AI Setup + +## 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. + +### 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. + +### 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. + +### Starter Prompts +- "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." + +## 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. diff --git a/docs/ai/overview.md b/docs/ai/overview.md new file mode 100644 index 0000000..a10ea06 --- /dev/null +++ b/docs/ai/overview.md @@ -0,0 +1,57 @@ +# AI Overview + +## Start Here +AI tools help with drafting, refactoring, explaining code, and accelerating routine tasks. They are not a replacement for engineering judgment, security review, or domain knowledge. + +## What To Expect In The First 30 Minutes +1. Confirm you have access to GitHub Copilot Enterprise. +2. Install the editor plugin for your platform. +3. Run a simple prompt to verify suggestions appear. +4. Read the usage and token guidance to avoid accidental overuse. + +## What AI Is and Is Not +- AI is a productivity assistant that can suggest code, summarize context, and propose solutions. +- AI is not a source of truth. Always validate outputs with tests, code review, and domain checks. + +## GitHub Copilot Enterprise +### What It Is +Copilot is an AI coding assistant that integrates with editors and chats to help you write and understand code. + +### Access Requirements +- You must be provisioned for Copilot Enterprise by the org. +- You must sign in with your GitHub account that has access. + +### Setup Steps (High-Level) +1. Confirm access with your team or admin. +2. Sign in to GitHub in your editor or plugin. +3. Verify Copilot is enabled in editor settings. +4. Run a quick prompt to validate it works. + +### Quick Access Checklist +- GitHub account is linked to the org. +- SSO or required auth flow is completed. +- Copilot is enabled in the editor or plugin settings. + +## Terminology +- Copilot: The AI assistant integrated into your editor. +- Chat: The conversational interface in your editor. +- Agents: Structured workflows that break work into steps. +- Skills: Reusable knowledge or workflows the assistant can apply. +- Tokens: The usage units that track AI consumption. + +## First Prompt (Safe) +Try a small, safe prompt to confirm everything is working: + +```text +Summarize what this file does in 3 bullet points. +``` + +## Guardrails And Good Habits +- Keep prompts scoped to a single task. +- Ask for a plan before large changes. +- Verify outputs with tests and review. +- Avoid sharing secrets or sensitive data. + +## Getting Help +- Ask your team lead or the AI docs owner. +- Use the escalation guidance in [Troubleshooting and FAQ](troubleshooting.md). diff --git a/docs/ai/skills.md b/docs/ai/skills.md new file mode 100644 index 0000000..25b33b0 --- /dev/null +++ b/docs/ai/skills.md @@ -0,0 +1,65 @@ +# Skills Library + +## What Skills Are +Skills are reusable instructions and workflows that guide the assistant through specialized tasks. + +## When To Use A Skill +- The task has a repeatable workflow. +- You want consistent structure and outputs. +- The task spans multiple files or steps. + +## Skills Directory +Store skills in the team-approved skills directory for your environment. If you do not know the location, ask your team lead or check your internal setup docs. + +## How to Download Existing Skills +1. Locate the skill in the team or org repository. +2. Add the skill to your local skills directory following team guidance. +3. Restart the editor or chat if required so the skill is recognized. + +## How to Enable or Configure Skills +- Follow the instructions provided in each skill's README or SKILL file. +- Some skills require additional setup, such as environment variables or tools. + +## How To Connect Skills +1. State the primary skill you want to use. +2. Provide the inputs that skill expects. +3. If needed, add a secondary skill and explain the handoff. + +## Current Skills (Add Repo Links) +Add a short summary and link for each skill below. + +### onboarding-cro +- Focus: New user onboarding and activation guidance. +- Repo: (link) + +### revenuecat-ios-integration +- Focus: RevenueCat setup for iOS and SwiftUI. +- Repo: (link) + +### find-skills +- Focus: Discovering and selecting skills for tasks. +- Repo: (link) + +### swiftui-expert-skill +- Focus: SwiftUI best practices and patterns. +- Repo: (link) + +### mcp-builder +- Focus: Building MCP servers and tool integrations. +- Repo: (link) + +### pdf +- Focus: PDF processing workflows. +- Repo: (link) + +### skill-creator +- Focus: Creating and maintaining new skills. +- Repo: (link) + +### template-skill +- Focus: Base template for new skills. +- Repo: (link) + +### webapp-testing +- Focus: Web app testing workflows. +- Repo: (link) diff --git a/docs/ai/troubleshooting.md b/docs/ai/troubleshooting.md new file mode 100644 index 0000000..3caf8ed --- /dev/null +++ b/docs/ai/troubleshooting.md @@ -0,0 +1,35 @@ +# Troubleshooting and FAQ + +## Common Setup Issues +- Cannot sign in: confirm GitHub access and SSO. +- No suggestions: verify Copilot is enabled in the editor. +- Plugin missing: confirm the plugin or extension is installed. + +## Quick Diagnostic Flow +1. Confirm account access and SSO. +2. Confirm plugin or extension is installed and enabled. +3. Restart the editor. +4. Test with a small prompt in a new file. +5. If still blocked, escalate. + +## Extension or Plugin Conflicts +- Disable overlapping AI extensions to avoid conflicts. +- Restart the editor after enabling Copilot. + +## Company Network Restrictions +- Check for blocked endpoints or proxy requirements. +- Escalate to IT if access appears restricted. + +## Low-Quality Suggestions +- Tighten the prompt with scope and context. +- Provide a small example or expected output. + +## What To Collect Before Escalation +- Editor version and plugin version. +- Error messages or screenshots. +- Whether the issue is reproducible in another editor. + +## When to Escalate +- Account access issues after setup. +- Consistent failures across multiple editors. +- Policy or security concerns. diff --git a/docs/ai/usage-tokens.md b/docs/ai/usage-tokens.md new file mode 100644 index 0000000..d53a879 --- /dev/null +++ b/docs/ai/usage-tokens.md @@ -0,0 +1,40 @@ +# Usage and Token Budgeting + +## How Tokens Are Spent +Tokens are consumed based on input length, output length, and tool usage. Long prompts and repeated context increase usage quickly. + +## Best Practices to Reduce Usage +- Use clear, bounded requests with specific goals. +- Prefer targeted edits over full rewrites. +- Reuse context by referencing earlier outputs instead of re-pasting. +- Ask for summaries before requesting changes. + +## Examples of Efficient Prompts +- "Summarize this file in 5 bullets. Then propose a refactor plan." +- "Update only the functions in this file that handle validation." +- "List risks in this change and suggest tests to add." + +## Daily and Monthly Budgeting Tips +- Batch related questions in a single prompt. +- Timebox explorations and stop when enough info is gathered. +- Avoid repeated retries without changing the prompt. + +## Budgeting Routine +- Start with a plan-first request for large tasks. +- Limit each request to one output type. +- End sessions with a short summary for easy follow-up. + +## Red Flags That Burn Tokens Quickly +- Large file pastes with no clear ask. +- Multiple full rewrites in one session. +- Repeated "start over" requests. + +## Team Habits That Help +- Capture reusable prompts in a shared doc. +- Standardize request templates. +- Agree on when to use agents vs chat. + +## Quick Checklist +- Is the request specific and scoped? +- Do I need the whole file or just a section? +- Can I ask for a plan first?