mobile-ai-agents 1.0.23

package/docs/agent-guide.md

@@ -0,0 +1,138 @@
+# Agent Guide
+
+How agents in this repository are structured, why they are structured that way, and how to get the most out of them.
+
+---
+
+## What Is an Agent?
+
+In this repo, an **agent** is a self-contained Markdown file that specifies:
+
+1. A **system prompt** — the LLM instructions
+2. An **input format** — the exact schema the developer fills in
+3. An **output format** — the exact schema the LLM must produce
+4. A **worked example** — real input → real output, tested
+
+Agents are LLM-agnostic. They work with Claude, GPT-4, Gemini, and any instruction-following model. The quality of output scales with the quality of the model.
+
+---
+
+## Why Structured Input/Output?
+
+Unstructured prompts produce inconsistent output. A structured input format means:
+- The developer knows exactly what to provide
+- The LLM has all the context it needs
+- The output is predictable and parseable
+
+Structured output means:
+- You can pipe output into scripts
+- You can track issues in a spreadsheet
+- You can compare reviews across multiple files consistently
+
+---
+
+## Agent Anatomy
+
+```
+## Purpose         — one sentence, answers "what does this do?"
+## Input Format    — the schema with field descriptions
+## Output Format   — the exact output template
+## System Prompt   — the LLM instructions (paste this into your session)
+## Example         — a real, tested input/output pair
+## Notes           — limitations and compatibility
+```
+
+Every section is required. Agents with empty or placeholder sections are rejected in review.
+
+---
+
+## Input Format Conventions
+
+- Field names are UPPER_SNAKE_CASE
+- Multi-line content fields (CODE, CRASH_LOG, GIT_LOG) always go last
+- Boolean fields use `true | false`
+- Enum fields show all valid values separated by `|`
+- Optional fields are marked in the Fields table
+
+---
+
+## Output Format Conventions
+
+- Section headings use `===` (level 1) or `---` (level 2)
+- Verdict/summary lines are capitalized: `OVERALL VERDICT: PASS`
+- Findings use `[CRITICAL]`, `[WARNING]`, `[INFO]` prefixes
+- Line references: `Line N` (not `line N` or `L.N`)
+- Code snippets in output use triple backtick blocks
+
+---
+
+## Severity Levels
+
+| Level | When to Use |
+|---|---|
+| CRITICAL | Bug, crash, data loss, security issue, or performance problem that will affect users |
+| WARNING | Bad practice, technical debt, anti-pattern, or scalability issue |
+| INFO | Style, minor improvement, or optional suggestion |
+
+---
+
+## Choosing Between Agent, Skill, and Prompt
+
+| Use | When... |
+|---|---|
+| **Agent** | You want a full structured analysis with typed fields, a complete output format, and a verdict |
+| **Skill** | You want to add a focused capability to a session without the full agent structure |
+| **Prompt** | You want a quick, one-shot result for a narrow task with minimal setup |
+
+---
+
+## Running Multiple Agents on the Same File
+
+To review a file from multiple angles:
+
+1. Run Agent 01 (Android Code Reviewer) for quality issues
+2. Run Agent 05 (RN Performance Optimizer) equivalent for perf — or combine:
+3. Prepend multiple skill prompts before a single session
+
+Or use Claude Code's multi-turn sessions: apply one agent, fix the issues, then apply the next.
+
+---
+
+## Automation
+
+Agents can be run programmatically using the Anthropic API:
+
+```python
+import anthropic
+
+client = anthropic.Anthropic()
+
+system_prompt = open("agents/android/code-reviewer/agent.md").read()
+# Extract just the ## System Prompt section
+
+user_input = f"""
+PLATFORM: Android
+KOTLIN_VERSION: 2.0
+COMPOSE_VERSION: none
+FILE_PATH: {file_path}
+CODE:
+{code_content}
+"""
+
+message = client.messages.create(
+    model="claude-sonnet-4-6",
+    max_tokens=4096,
+    system=system_prompt,
+    messages=[{"role": "user", "content": user_input}]
+)
+
+print(message.content[0].text)
+```
+
+---
+
+## Contributing a New Agent
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md) and use [templates/agent-template.md](../templates/agent-template.md).
+
+The most common rejection reason: the example output is placeholder text, not a real tested result. Always test your agent on your example input before submitting.

package/docs/chatgpt-integration.md

@@ -0,0 +1,219 @@
+# Using Mobile Dev Skill Agents with ChatGPT
+
+This guide covers three ways to use this toolkit with ChatGPT: manual paste, a Custom GPT that routes to the right agent automatically, and the Assistants API for programmatic use.
+
+---
+
+## Method 1 — Manual Paste (Quickest)
+
+Works in any ChatGPT tier, no setup required.
+
+1. Open the agent file for your task. Example: `agents/android/code-reviewer/agent.md`
+2. Find the `## System Prompt` section and copy the text inside the code block.
+3. Start a new ChatGPT chat.
+4. Paste the system prompt as your **first message** and send it. ChatGPT will acknowledge the role.
+5. In your next message, use the agent's **Input Format** to send your code.
+
+**Tip:** For GPT-4o and above, you can paste the entire `agent.md` file and say:
+> "Use the system prompt and output format defined in this file to review the code I'll paste next."
+
+---
+
+## Method 2 — Custom GPT (Recommended for Teams)
+
+Build one Custom GPT that covers all platforms. It reads the right agent based on what you describe.
+
+### Step 1 — Open GPT Builder
+
+Go to [chatgpt.com](https://chatgpt.com) → your profile → **My GPTs** → **Create a GPT** → **Configure** tab.
+
+### Step 2 — Paste this as the System Prompt
+
+```
+You are a Mobile Dev Skill Agent — an AI productivity assistant for Android, iOS,
+Flutter, React Native, Unity, and Unreal Engine developers.
+
+When the developer describes their task, identify which agent applies and apply
+that agent's system prompt and output format automatically.
+
+AGENT ROUTING TABLE:
+
+| Task | Platform | Agent to Apply |
+|---|---|---|
+| Review Kotlin/Compose code, Clean Architecture | Android | Android Code Reviewer |
+| Analyze Android crash log, stack trace, ANR | Android | Android Crash Analyzer |
+| Review Swift/SwiftUI code | iOS | Swift Code Reviewer |
+| Analyze iOS crash log | iOS | iOS Crash Analyzer |
+| Generate Flutter widget from description | Flutter | Flutter Widget Generator |
+| React Native performance, re-renders | React Native | RN Performance Optimizer |
+| Generate Unity shader | Unity | Unity Shader Generator |
+| Review Unreal Blueprint, C++ migration | Unreal | Unreal Blueprint Advisor |
+| Release notes from git commits | Any | Release Notes Generator |
+| CI/CD pipeline config | Any | CI/CD Pipeline Generator |
+| App Store / Play Store listing | Any | Store Listing Writer |
+| Security vulnerabilities in mobile code | Any | Security Scanner |
+| Accessibility audit of UI code | Any | Accessibility Auditor |
+
+AGENT SYSTEM PROMPTS:
+
+--- ANDROID CODE REVIEWER ---
+You are a senior Android engineer with deep expertise in Kotlin, Jetpack Compose,
+Clean Architecture, and Android performance. Review Android Kotlin source files for:
+1. Clean Architecture violations (layer boundary crossing, Android imports in domain)
+2. Kotlin idioms (prefer StateFlow over LiveData, sealed class for state, avoid !!)
+3. Coroutine safety (no GlobalScope, viewModelScope usage, exception handling)
+4. Jetpack Compose misuse (remember, LaunchedEffect, derivedStateOf, recomposition)
+5. Dependency injection (no direct instantiation of repositories in ViewModels)
+6. Testability (injectable dependencies, no hardcoded singletons)
+For each finding: [CRITICAL/WARNING/INFO] Line N — Title / Problem / Fix
+End with: COROUTINE SAFETY, CLEAN ARCHITECTURE ASSESSMENT, TESTABILITY SCORE 1-10, OVERALL VERDICT.
+
+--- ANDROID CRASH ANALYZER ---
+You are a senior Android crash debugging expert. Analyze crash logs and related code.
+Return exactly these sections:
+## Crash Summary | ## Root Cause | ## Why This Happens | ## Risk Level (Critical/High/Medium/Low) |
+## Recommended Fix | ## Updated Code | ## Edge Cases | ## Testing Checklist | ## Prevention Tips
+Rules: Prefer lifecycle-aware solutions. For Fragment/ViewModel issues, consider lifecycle
+owner, repeated observers, configuration changes. For coroutines, check scope, dispatcher,
+cancellation, exception handling. For RecyclerView, check adapter state and async updates.
+
+--- SWIFT CODE REVIEWER ---
+You are a senior iOS engineer. Review Swift/SwiftUI source for:
+1. Memory safety (retain cycles, [weak self], unowned misuse)
+2. Concurrency (@MainActor, async/await, Sendable, actor isolation)
+3. SwiftUI state (@State/@StateObject/@ObservedObject misuse, expensive body)
+4. Force unwrap (!) removal, safe alternatives
+5. Testability (protocol-based dependencies, no singletons)
+For each finding: [CRITICAL/WARNING/INFO] Line N — Title / Problem / Fix
+End with: MEMORY SAFETY, CONCURRENCY, TESTABILITY SCORE 1-10, OVERALL VERDICT.
+
+--- FLUTTER WIDGET GENERATOR ---
+You are a senior Flutter engineer. Generate production-ready Flutter/Dart widget code.
+Rules: null-safe Dart 3.x, const constructors, Theme.of(context) for all colors/styles,
+Semantics for accessibility, responsive layout (no hardcoded widths), dispose all controllers.
+Output: widget code + usage example + accessibility notes + theming notes + limitations.
+
+--- RN PERFORMANCE OPTIMIZER ---
+You are a senior React Native performance engineer. Analyze components for:
+re-renders (missing useCallback/useMemo/React.memo), FlatList config (keyExtractor,
+getItemLayout, windowSize), inline objects in JSX, bridge overhead, animation thread.
+For each finding: [HIGH/MEDIUM/LOW] impact + problem + refactored code snippet.
+End with: BRIDGE OVERHEAD, ANIMATION SAFETY, FLATLIST AUDIT, ESTIMATED IMPROVEMENT.
+
+--- UNITY SHADER GENERATOR ---
+You are a senior Unity graphics engineer. Generate complete .shader files (not snippets).
+Match the pipeline (Built-in: CGPROGRAM, URP: HLSLPROGRAM with URP includes, HDRP: HDRP includes).
+Mobile: ≤2 texture samples, half precision, no dynamic branching.
+Output: full ShaderLab file + properties reference + material setup guide + performance notes.
+
+--- UNREAL BLUEPRINT ADVISOR ---
+You are a senior Unreal Engine engineer. Analyze Blueprint logic for:
+Tick misuse (move to timers/events), Cast chains in hot paths, polling vs event-driven,
+interface usage, component responsibility, replication issues.
+Output: findings + TICK AUDIT + C++ MIGRATION CANDIDATES + C++ equivalent for HIGH items.
+
+--- RELEASE NOTES GENERATOR ---
+You are a technical writer for mobile teams. Convert git commit logs to release notes.
+Filter noise (merge commits, CI, typo fixes). Group by: Features, Fixes, Performance, Internal.
+Output three sections: USER-FACING (App Store copy ≤4000 chars), DEVELOPER CHANGELOG, QA NOTES.
+
+--- CI/CD PIPELINE GENERATOR ---
+You are a mobile DevOps engineer. Generate complete, working pipeline YAML or Ruby.
+Use env vars for all secrets. Add caching. PR check: lint+test only. Staging: build+sign+distribute.
+Production: full pipeline + GitHub Release + store upload.
+
+--- STORE LISTING WRITER ---
+You are an ASO specialist. Write App Store (title 30, subtitle 30, description 4000, keywords 100)
+and Play Store (title 30, short desc 80, full desc 4000) listings. No superlatives.
+Lead with strongest benefit. Keyword in title if natural. Report character counts.
+
+--- SECURITY SCANNER ---
+You are a mobile security engineer. Review code for OWASP Mobile Top 10:
+hardcoded secrets, insecure storage, unvalidated deep links, missing certificate pinning,
+excessive permissions, insecure network config, weak cryptography.
+Severity: CRITICAL (exploitable now), HIGH (exploitable with effort), MEDIUM, LOW.
+
+--- ACCESSIBILITY AUDITOR ---
+You are a mobile accessibility specialist. Review UI code for:
+missing content descriptions/labels, touch targets <48dp, color contrast via theme tokens,
+missing screen reader announcements, focus order, keyboard navigation.
+Severity: CRITICAL (blocks access), HIGH (degrades access), MEDIUM, LOW.
+
+ROUTING INSTRUCTIONS:
+1. Read the developer's message. Identify platform and task type.
+2. Silently select the matching agent from the routing table.
+3. Apply that agent's system prompt to produce structured output.
+4. If the task is ambiguous, ask ONE clarifying question before proceeding.
+5. Never tell the developer which agent you're using — just apply it and output the result.
+```
+
+### Step 3 — Configure GPT Settings
+
+- **Name:** Mobile Dev Agent
+- **Description:** AI productivity toolkit for Android, iOS, Flutter, React Native, Unity, and Unreal developers
+- **Instructions:** (the system prompt above)
+- **Capabilities:** Enable Code Interpreter if you want file upload support for crash logs
+
+### Step 4 — Example Session
+
+After saving the GPT, a developer can just say:
+
+> "Review this Android ViewModel for me: [paste code]"
+
+The GPT automatically applies the Android Code Reviewer agent and returns a structured CRITICAL/WARNING/INFO report.
+
+---
+
+## Method 3 — OpenAI Assistants API
+
+Use any agent's system prompt directly as an Assistant's instructions.
+
+```python
+import openai
+
+client = openai.OpenAI()
+
+# Read the system prompt from the agent file (the ## System Prompt section content)
+system_prompt = """
+You are a senior Android engineer with deep expertise in Kotlin, Jetpack Compose...
+[paste full system prompt here]
+"""
+
+assistant = client.beta.assistants.create(
+    name="Android Code Reviewer",
+    instructions=system_prompt,
+    model="gpt-4o",
+)
+
+thread = client.beta.threads.create()
+
+client.beta.threads.messages.create(
+    thread_id=thread.id,
+    role="user",
+    content="""
+PLATFORM: Android
+KOTLIN_VERSION: 2.0
+COMPOSE_VERSION: 1.7
+FILE_PATH: app/src/main/java/com/example/ProfileViewModel.kt
+CODE:
+[your Kotlin code here]
+    """
+)
+
+run = client.beta.threads.runs.create_and_poll(
+    thread_id=thread.id,
+    assistant_id=assistant.id,
+)
+
+messages = client.beta.threads.messages.list(thread_id=thread.id)
+print(messages.data[0].content[0].text.value)
+```
+
+---
+
+## Tips for Best Results
+
+- **GPT-4o** gives the best structured output; GPT-4o-mini works for simpler agents.
+- For crash analysis, paste the **full** stack trace — truncated traces miss the first app frame.
+- For code review, paste the **complete** class, not a snippet — missing context leads to false positives.
+- The Custom GPT method scales well for teams: one shared GPT, all agents available.

package/docs/core-loops.md

@@ -0,0 +1,143 @@
+# Core Loops and Platform Plugins
+
+Mobile AI Agents is organized as a mobile engineering system, not a prompt list.
+
+The simple model:
+
+```text
+Mobile AI Agents
+
+Core Loops
+- Planning
+- Architecture
+- Development
+- Performance
+- Security
+- Testing
+- Release
+- Growth
+- Maintenance
+
+Platform Plugins
+- Android
+- iOS
+- Flutter
+- React Native
+- Kotlin Multiplatform
+- Unity
+- Unreal
+```
+
+Core loops describe the repeatable work every mobile team has to do. Platform plugins add the exact Android, iOS, Flutter, React Native, Kotlin Multiplatform, Unity, or Unreal expertise needed for that loop.
+
+## Why This Matters
+
+Most AI coding resources start with prompts. Mobile teams start with outcomes:
+
+- What are we building?
+- Is the architecture same?
+- Does it perform on real devices?
+- Is it secure enough to ship?
+- Does the UI match the design?
+- Did tests and device QA prove it works?
+- Can another session continue the work later?
+
+Mobile AI Agents turns those questions into loops that can be run, audited, and repeated.
+
+## Loop Engineering
+
+Loop Engineering means defining the goal once, then letting the system move through the next engineering steps with evidence:
+
+```text
+Goal
+-> Plan
+-> Build
+-> Audit
+-> Test
+-> Verify on device
+-> Report
+-> Save context
+-> Continue
+```
+
+The user should not have to manually prompt every stage. The system should stop only for product decisions, credentials, destructive actions, paid services, legal/store ownership, release approval, or blockers it cannot safely resolve.
+
+## Core Loops
+
+| Loop | Purpose | Agents and Skills |
+|---|---|---|
+| Planning | Turn rough ideas into PRDs, roadmaps, and task slices. | `@APPFORGE`, `/grill-mobile`, `/feature-slice` |
+| Architecture | Review system design, module boundaries, model separation, and clean code. | `@AXIOM`, `/clean-code-audit`, platform reviewers |
+| Development | Implement one feature slice at a time and keep code scoped. | `@MOBILE-HARNESS`, `@FIGMA`, screen builders, code reviewers |
+| Performance | Find and fix startup, ANR, memory, frame, battery, network, and size issues. | `@PERF`, `@FREEZE`, `@RETAINER`, `/perf-audit`, `/anr-investigation` |
+| Security | Audit OWASP risks, secrets, auth, storage, deep links, WebViews, permissions, logs, and release hardening. | `@SENTINEL`, `security-scanner`, `/security-audit`, `/security-scan` |
+| Testing | Add unit/UI tests, run device QA, check accessibility, and verify PRD/design match. | TDD skills, `/prd-verification`, `/mobile-mcp-qa`, `/accessibility-audit` |
+| Release | Prepare CI/CD, signing, release notes, rollout, and store submission. | `@PIPELINE`, `@SCRIBE`, `/release-prep` |
+| Growth | Improve store listing, ASO, screenshots, conversion, and monetization copy. | `@LAUNCHPAD`, `/store-listing` |
+| Maintenance | Triage crashes, preserve context, plan issue work, and prevent regressions. | `@CRASHER`, Mobile Memory, crash triage, issue-to-agent workflow |
+
+## Platform Plugins
+
+| Plugin | Current Coverage |
+|---|---|
+| Android | Kotlin, Java, Compose, Navigation, ANR, memory leaks, crash analysis, TDD, performance, security, release |
+| iOS | Swift, SwiftUI, concurrency, networking, persistence, performance, testing, crash analysis |
+| Flutter | Dart, widgets, Bloc feature building, review, TDD, modernization |
+| React Native | Bridge performance, New Architecture, Expo optimization, review, TDD |
+| Kotlin Multiplatform | Target platform plugin for shared Kotlin architecture, model boundaries, persistence, and API strategy |
+| Unity | C#, shaders, frame budget, test loop, game performance |
+| Unreal | Blueprint advice, C++ migration, performance, game architecture |
+
+## How To Choose
+
+Choose by stage first:
+
+| If You Need To... | Start With |
+|---|---|
+| Figure out what to build | Planning |
+| Decide how the app should be structured | Architecture |
+| Build a feature | Development |
+| Fix slowness, jank, ANRs, memory leaks, or app size | Performance |
+| Prepare for production risk review | Security |
+| Prove the app works | Testing |
+| Ship to stores | Release |
+| Improve downloads or conversion | Growth |
+| Resume work later or handle production issues | Maintenance |
+
+Then choose the platform plugin that matches the app.
+
+Example:
+
+```text
+Problem: Android app freezes during startup
+Loop: Performance
+Plugin: Android
+Agents/skills: @FREEZE, @PERF, /anr-investigation
+Evidence: Play Console ANR trace, startup code, device reproduction
+Output: root cause, fix, verification plan, regression check
+```
+
+## Marketing Position
+
+Use this sentence when explaining the repo:
+
+> Mobile AI Agents gives every mobile team a repeatable loop for planning, building, auditing, testing, releasing, and maintaining apps, with security and performance checks built in.
+
+Short version:
+
+```text
+Core Loops: Plan -> Build -> Audit -> Test -> Release -> Monitor
+Platform Plugins: Android · iOS · Flutter · React Native · Kotlin Multiplatform · Unity · Unreal
+```
+
+## Current Gaps
+
+The model is intentionally ahead of the full implementation. The strongest next builds are:
+
+- Loop Engineering automation to reduce manual prompting
+- `/prd-verification` rollout into Mobile Harness and APPFORGE evidence gates
+- Mobile Flight Recorder
+- Device Proof Reports
+- dedicated Performance Loop reports
+- dedicated Security Audit Loop reports
+- Kotlin Multiplatform plugin assets

package/docs/cursor-integration.md

@@ -0,0 +1,143 @@
+# Using Mobile Dev Skill Agents with Cursor
+
+Cursor reads `.cursorrules` from the repo root automatically. When you open this repo in Cursor, the AI already knows the agent index, platform conventions, and severity levels — no setup needed.
+
+---
+
+## How `.cursorrules` Is Loaded
+
+Cursor loads `.cursorrules` at the start of every session in the workspace. It acts as a persistent system prompt for Cursor Chat and Composer. You can verify it's active by asking:
+
+> "What agents are available in this repo?"
+
+Cursor should list all agents from the agent index in `.cursorrules`.
+
+---
+
+## Workflow 1 — Cursor Chat (Single File Review)
+
+**Use when:** You want to review or improve one file.
+
+1. Open the file you want to review (e.g., `ProfileViewModel.kt`)
+2. Open Cursor Chat (Cmd+L)
+3. Type:
+
+```
+Review this file using the Android Code Reviewer agent at
+agents/android/code-reviewer/agent.md
+```
+
+Or more naturally:
+
+```
+Review this ViewModel for Clean Architecture violations and coroutine safety.
+```
+
+Cursor will read the agent rules from `.cursorrules` and produce a structured CRITICAL/WARNING/INFO report.
+
+**With file reference:**
+
+```
+@ProfileViewModel.kt
+Review for Clean Architecture violations, GlobalScope usage, and Compose best practices.
+```
+
+---
+
+## Workflow 2 — Cursor Composer (Multi-File or Apply Fixes)
+
+**Use when:** You want to review AND automatically apply fixes across one or more files.
+
+1. Open Composer (Cmd+I or Cmd+Shift+I)
+2. Reference the file(s) and the agent:
+
+```
+@agents/android/code-reviewer/agent.md @ProfileViewModel.kt
+
+Review ProfileViewModel.kt, then apply the CRITICAL and WARNING fixes directly to the file.
+```
+
+Composer will:
+- Run the agent review
+- Show you a diff of every proposed change
+- Let you accept or reject each change individually
+
+**Multi-file example:**
+
+```
+@agents/react-native/performance-optimizer/agent.md
+
+Review every file in src/screens/ for performance issues and apply the HIGH-impact fixes.
+```
+
+---
+
+## Workflow 3 — Crash Log Analysis
+
+1. Open or paste the crash log into a new file (e.g., `crash.txt`)
+2. In Cursor Chat:
+
+```
+@crash.txt @agents/android/crash-analyzer/agent.md
+
+Analyze this crash log. The user was on Android 14 / Pixel 8 Pro.
+```
+
+Cursor will return the full 9-section crash analysis: Summary, Root Cause, Why It Happens, Risk Level, Recommended Fix, Updated Code, Edge Cases, Testing Checklist, Prevention Tips.
+
+---
+
+## Workflow 4 — Generate Code from Description
+
+**Flutter widget:**
+
+```
+@agents/flutter/widget-generator/agent.md
+
+Generate a Flutter widget for a swipeable onboarding screen with 3 pages,
+a dot indicator, skip button, and a Get Started button on the last page.
+Flutter 3.27, Dart 3.6, no state management package.
+```
+
+**Unity shader:**
+
+```
+@agents/unity/shader-generator/agent.md
+
+Generate a URP unlit shader for a dissolve effect using a noise texture.
+The dissolve threshold should be a tweakable property. Mobile-friendly.
+```
+
+---
+
+## Workflow 5 — CI/CD Pipeline Generation
+
+```
+@agents/cross-platform/ci-cd-generator/agent.md
+
+Generate a GitHub Actions pipeline for my Flutter app.
+Platforms: Android + iOS.
+Distribution: Firebase App Distribution (Android) + TestFlight (iOS).
+Tests: flutter test.
+Notify Slack on success/failure.
+```
+
+---
+
+## Tips
+
+- **@codebase** in Cursor Chat gives the agent awareness of your entire project structure — useful for architecture-level questions.
+- **Cursor Tab** (autocomplete) uses `.cursorrules` implicitly — it will suggest Kotlin idioms, avoid `!!`, and prefer `StateFlow` in Android files automatically.
+- For agents with long output (CI/CD Generator, Store Listing Writer), use **Composer** rather than Chat — Composer handles long outputs better and can write directly to files.
+- Combine multiple `@file` references to give the agent cross-file context:
+
+```
+@ProfileViewModel.kt @ProfileRepository.kt @ProfileUseCase.kt
+Review the full data flow for Clean Architecture violations.
+```
+
+---
+
+## Updating `.cursorrules`
+
+When new agents are added to the repo, update the Agent Index table in `.cursorrules` so Cursor Chat can reference them. The table is at the top of the file.