mobile-ai-agents 1.0.23

package/docs/mobile-memory.md

@@ -0,0 +1,349 @@
+# Mobile Memory
+
+Mobile Memory is a mobile-specific AI memory and knowledge graph system for Mobile AI Agents. It captures project architecture, session decisions, agent findings, health risks, code state, and the next executable action into local project memory and a portable `MOBILE_MEMORY.md` handoff file.
+
+The goal is simple: when tokens run out or a developer switches tools, the next AI session can continue without asking for the same explanation again.
+
+---
+
+## Why It Exists
+
+Generic AI coding sessions lose context:
+
+- Architecture decisions vanish between sessions.
+- Agent findings from AXIOM, CRASHER, DART, SWIFT, and BRIDGE are forgotten.
+- Mid-edit files become risky because the next AI cannot see what was already decided.
+- Large codebases cost too many tokens to reload from scratch.
+
+Mobile Memory preserves the mobile-specific parts of context that matter most:
+
+- ViewModels, repositories, use cases, widgets, screens, services, APIs, databases, tests
+- Edges like `OBSERVES`, `CALLS`, `INJECTS`, `EMITS`, `NAVIGATES_TO`, and `VIOLATES`
+- CRITICAL/WARNING/DEBT health nodes
+- The exact `NEXT ACTION`
+
+---
+
+## Token Reduction Math
+
+Mobile Memory reduces tokens by replacing raw files with a graph and a session state summary.
+
+Typical Android feature:
+
+| Source | Files | Avg tokens | Total |
+|---|---:|---:|---:|
+| Compose screens | 4 | 2,500 | 10,000 |
+| ViewModels | 3 | 2,000 | 6,000 |
+| Use cases | 5 | 700 | 3,500 |
+| Repositories | 3 | 1,800 | 5,400 |
+| API/DAO/models | 12 | 600 | 7,200 |
+| Tests | 8 | 1,200 | 9,600 |
+| Prior chat context | 1 | 18,000 | 18,000 |
+| Total raw context | 36 | - | 59,700 |
+
+A high-quality Mobile Memory checkpoint for the same feature is usually 700-1,200 tokens:
+
+```text
+59,700 raw tokens / 750 Mobile Memory tokens = 79.6x reduction
+```
+
+That is where the "up to 80x" claim comes from. Smaller snippets reduce less. Large mobile features reduce more because repeated code bodies collapse into graph nodes, edges, health findings, and decisions.
+
+---
+
+## How It Differs From Generic Memory Tools
+
+Tools like Recallium, mem0, and agentmemory are useful generic memory layers. Mobile Memory is different because it understands mobile architecture.
+
+| Generic memory tools | Mobile Memory |
+|---|---|
+| Store arbitrary facts | Stores mobile architecture state |
+| Remember text snippets | Builds UI/VM/Domain/Data/Net/DB graphs |
+| Need manual meaning | Knows ViewModel, ObservableObject, StateNotifier, Context, MonoBehaviour |
+| Generic links | Mobile edge types: OBSERVES, EMITS, NAVIGATES_TO, VIOLATES |
+| Generic risk | Flags GlobalScope, force unwraps, exposed MutableStateFlow, bridge hot paths, Update() abuse |
+| Session recall | Session recall plus executable NEXT ACTION |
+
+Mobile Memory has two layers:
+
+| Layer | Storage | Purpose |
+|---|---|---|
+| Local memory | `.mobile-ai-agents/memory/events.jsonl` | Persistent project event history for search, timeline, and context injection |
+| Portable checkpoint | `MOBILE_MEMORY.md` | Tool-agnostic handoff file that any AI can read |
+
+Raw local memory stays out of git by default. Commit `MOBILE_MEMORY.md` only when the context is useful for review, handoff, or long-running work.
+
+---
+
+## Local Memory Store
+
+Initialize memory inside any app project:
+
+```bash
+npx mobile-ai-agents memory init
+```
+
+This creates:
+
+```text
+.mobile-ai-agents/
+├── .gitignore
+└── memory/
+    ├── config.json
+    ├── events.jsonl
+    └── index.md
+```
+
+Capture memory events:
+
+```bash
+npx mobile-ai-agents memory capture --type decision --title "Use Room" --text "Persist habits locally with Room."
+npx mobile-ai-agents memory capture --type finding --title "PRD gap" --text "Restart persistence is missing."
+npx mobile-ai-agents memory capture --type next-action --text "Implement HabitDao and restart persistence test."
+```
+
+You can also pipe content:
+
+```bash
+git diff | npx mobile-ai-agents memory capture --type code-state --title "Current diff"
+```
+
+Search and inject context:
+
+```bash
+npx mobile-ai-agents memory search persistence
+npx mobile-ai-agents memory timeline --limit 20
+npx mobile-ai-agents memory inject
+```
+
+Generate the portable checkpoint:
+
+```bash
+npx mobile-ai-agents memory checkpoint
+```
+
+This writes `MOBILE_MEMORY.md` from the captured memory events. Review it before committing.
+
+Privacy rule: do not capture secrets, customer data, private logs, tokens, credentials, or proprietary crash payloads. Text inside `<private>...</private>` is removed during capture.
+
+---
+
+## Quick Save Slash Command
+
+Use `/mobile-memory-save` when you are inside Claude Code and need a fast checkpoint without setting up the full local memory store.
+
+```text
+/mobile-memory-save
+```
+
+Recommended input:
+
+```text
+PROJECT: Habit Pulse
+PLATFORM: Android
+CURRENT TASK:
+Building habit tracker MVP with list, add habit, streak tracking.
+
+DECISIONS:
+- Use Room for offline storage.
+- Use MVVM with StateFlow.
+- Keep UI simple for demo.
+
+PROGRESS:
+- Done: habit list screen and add habit dialog.
+- In progress: persistence and restart test.
+- Blocked: none.
+
+CODE STATE:
+MainActivity.kt has current UI. Habit data is still in memory.
+
+NEXT ACTION:
+Add Room HabitEntity, HabitDao, and repository, then persist created habits across app restart.
+```
+
+The skill returns a compact `MOBILE_MEMORY.md`. Save it in the project root when the handoff should travel with the app. A future session can continue with:
+
+```text
+Read MOBILE_MEMORY.md and continue from NEXT ACTION.
+```
+
+| Need | Use |
+|---|---|
+| Fast one-time checkpoint inside chat | `/mobile-memory-save` |
+| Searchable project memory over days/weeks | `npx mobile-ai-agents memory init/capture/search/checkpoint` |
+| Resume a new session from saved context | `/mobile-memory` or `Read MOBILE_MEMORY.md and continue` |
+
+---
+
+## Graphify Integration
+
+Graphify can be used first to create a general graph of a project. Mobile Memory enhances that output with mobile semantics:
+
+1. Run Graphify to discover broad dependency structure.
+2. Run `/mobile-memory graph` on the relevant mobile files.
+3. Merge Graphify's broad nodes with Mobile Memory's mobile-specific node types and health labels.
+4. Save the result in `MOBILE_MEMORY.md`.
+
+Mobile Memory uses confidence tags similar to graph-first tools:
+
+- `EXTRACTED`: direct code evidence exists
+- `INFERRED`: relationship is strongly implied
+- `AMBIGUOUS`: relationship may exist but needs more code
+
+---
+
+## Portable Checkpoint Format
+
+```markdown
+---
+# Mobile Memory
+**Project:** [name]
+**Platform:** [Android/iOS/Flutter/RN/Unity/Unreal]
+**Stack:** [language, framework, key libraries]
+**Architecture:** [pattern]
+**Saved:** [date]
+**Compatible:** Claude Code · Cursor · Windsurf · ChatGPT · Gemini · Copilot
+**Token reduction:** [X× vs reading raw files]
+
+---
+
+## ⚡ INSTANT RESUME
+[2-4 sentences. Fully self-contained. No assumed knowledge. What project, what task, what decisions, what to do next.]
+
+---
+
+## 🗺️ Knowledge Graph
+
+### Nodes
+| Node | Type | Layer | Health |
+|---|---|---|---|
+| [ClassName] | [VM/REPO/UI/etc] | [UI/Domain/Data] | [OK/CRITICAL/WARNING] |
+
+### Key Edges
+| From | Edge | To | Note |
+|---|---|---|---|
+| [Node] | OBSERVES | [Node] | [why this matters] |
+
+### God Nodes
+| Node | Connections | Platform Risk | Recommendation |
+|---|---|---|---|
+
+### Architecture Violations
+- [Class] VIOLATES [rule] — [explanation] → [fix]
+
+---
+
+## 🏥 Health Report
+### 🚨 CRITICAL
+- [Node]: [issue] → [fix]
+
+### ⚠️ WARNING
+- [Node]: [issue] → [fix]
+
+### 🏦 Tech Debt
+- [Node]: [debt] → [migration path]
+
+---
+
+## 🎯 Session Context
+
+### Current Task
+[Exact task in one paragraph]
+
+### Decisions Made
+| Decision | Reason | Rejected |
+|---|---|---|
+
+### Progress
+✅ Done: [list]
+🔄 In Progress: [exact state of anything mid-edit]
+⏭️ NEXT ACTION: [specific, executable, no assumed context]
+🚧 Blocked: [list or "Nothing"]
+
+### Open Questions
+- [question 1]
+- [question 2]
+
+---
+
+## 🤖 Agent State
+| Agent | Last Action | Finding | Pending |
+|---|---|---|---|
+| AXIOM | [what it reviewed] | [what it found] | [what remains] |
+
+---
+
+## 📄 Code State
+[For any file mid-edit, paste current state here]
+
+---
+
+## 🔄 Resume Instructions
+
+**Claude Code:**
+Start new session → paste INSTANT RESUME → paste full MOBILE_MEMORY.md → say "Continue"
+
+**Cursor/Windsurf:**
+Save as MOBILE_MEMORY.md in project root → next prompt: "Read MOBILE_MEMORY.md and continue"
+
+**ChatGPT/Gemini:**
+Paste full file as first message → "Resume from NEXT ACTION"
+
+**Same tool, new session:**
+Paste full file → /mobile-memory restore
+---
+```
+
+---
+
+## Commands
+
+Preferred CLI:
+
+| Command | Use |
+|---|---|
+| `mobile-ai-agents memory init` | Create local project memory |
+| `mobile-ai-agents memory capture` | Save decisions, findings, progress, and next actions |
+| `mobile-ai-agents memory search` | Search local project memory |
+| `mobile-ai-agents memory timeline` | Show recent memory events |
+| `mobile-ai-agents memory inject` | Print compact context for a new AI session |
+| `mobile-ai-agents memory checkpoint` | Generate `MOBILE_MEMORY.md` |
+
+Legacy slash aliases:
+
+| Command | Use |
+|---|---|
+| `/mobile-memory save` | Produce full `MOBILE_MEMORY.md` |
+| `/mobile-memory restore` | Load a pasted `MOBILE_MEMORY.md` and continue |
+| `/mobile-memory graph` | Build the knowledge graph from code files |
+| `/mobile-memory-search` | Search local `.mobile-ai-agents/memory/` output and continue from relevant context |
+| `/mobile-memory update` | Update an existing checkpoint |
+| `/mobile-memory status` | Print only progress state |
+| `/mobile-memory health` | Print CRITICAL and WARNING nodes |
+| `/mobile-memory next` | Print only NEXT ACTION |
+| `/mobile-memory decisions` | Print decisions from the session |
+| `/mobile-memory diff` | Show changes since last save |
+
+---
+
+## FAQ
+
+### Is Mobile Memory a replacement for reading code?
+
+No. It is a resume layer. Use it to restore context quickly, then read the exact files needed for the next action.
+
+### Should MOBILE_MEMORY.md be committed?
+
+Commit `MOBILE_MEMORY.md` when the context is useful for handoff, review, or long-lived work. Do not commit `.mobile-ai-agents/memory/events.jsonl` unless your team explicitly wants raw local event history in source control. Do not commit secrets, private logs, customer data, or proprietary crash payloads.
+
+### How often should I capture memory?
+
+Capture memory after major architectural decisions, after agent findings, before switching tools, and when the session is long enough that re-explaining would be expensive.
+
+### Why does it include health nodes?
+
+Mobile projects fail at boundaries: lifecycle, state ownership, navigation, threading, persistence, and platform APIs. Health nodes preserve those risks so the next AI does not repeat unsafe work.
+
+### Can ChatGPT or Gemini use it?
+
+Yes. Paste the full file as the first message and say: "Resume from NEXT ACTION." Mobile Memory checkpoints are plain Markdown and do not depend on a specific AI tool.

package/docs/release-process.md

@@ -0,0 +1,85 @@
+# Release Process
+
+Mobile AI Agents npm releases are published by GitHub Actions from git tags.
+
+Do not run `npm publish` manually. Manual publishing can race with the tag workflow and cause npm to reject the workflow with:
+
+```text
+403 Forbidden - You cannot publish over the previously published versions
+```
+
+---
+
+## Release Steps
+
+1. Update `package.json`:
+
+```json
+{
+  "version": "1.0.19"
+}
+```
+
+2. Run local checks:
+
+```bash
+git diff --check
+node --check cli/index.js
+bash -n install.sh
+node cli/index.js list
+npm pack --dry-run
+```
+
+3. Commit the version bump:
+
+```bash
+git add package.json
+git commit -m "Release v1.0.19"
+```
+
+If the release also changes docs, CLI, agents, skills, or workflows, include those files in the same release commit.
+
+4. Create the tag locally:
+
+```bash
+git tag v1.0.19
+```
+
+5. Push the branch and tag:
+
+```bash
+git push origin main
+git push origin v1.0.19
+```
+
+6. Let GitHub Actions publish npm.
+
+The workflow is `.github/workflows/publish.yml`. It runs on tags matching `v*`, verifies the tag version matches `package.json`, checks whether the version already exists on npm, and publishes only when the version is new.
+
+---
+
+## Verification
+
+After the workflow finishes:
+
+```bash
+npm view mobile-ai-agents version dist-tags.latest
+npm view mobile-ai-agents@1.0.19 version dist.tarball dist.shasum
+git ls-remote origin refs/heads/main refs/tags/v1.0.19
+```
+
+Expected:
+
+- npm latest equals the released version.
+- GitHub `main` points to the release commit.
+- GitHub tag `v1.0.19` points to the same release commit.
+- GitHub Actions publish workflow is green.
+
+---
+
+## Important Rules
+
+- Never run `npm publish` manually for normal releases.
+- Never push a tag before `package.json` is updated and committed.
+- The tag must match the package version exactly: `package.json` `1.0.19` uses tag `v1.0.19`.
+- If a workflow is rerun for an already-published version, it should skip publishing instead of failing.

package/docs/releases/release-v1.0.0.md

@@ -0,0 +1,165 @@
+# Release v0.1.0 — Foundation
+
+**Released:** 2026-05-29  
+**Tag:** `v0.1.0`  
+**Type:** Initial public release
+
+---
+
+## Overview
+
+v0.1.0 is the foundation release of **Mobile Dev Skill Agents** — an open-source AI productivity toolkit for mobile and game developers.
+
+This release ships 14 production-ready agents, 10+ skills, 22 prompts, and tool integration files for Claude Code, Cursor, ChatGPT, and GitHub Copilot. Every agent includes a structured input format, typed output format, and a real worked example verified against at least one major LLM.
+
+---
+
+## What's Included
+
+### Agents (14)
+
+#### Android
+| Agent | Description |
+|---|---|
+| Android Code Reviewer | Kotlin/Compose Clean Architecture, coroutines, anti-patterns — CRITICAL/WARNING/INFO findings |
+| Android Crash Analyzer | 9-section crash report: root cause, fix, edge cases, test checklist, prevention tips |
+| Android Compose UI Reviewer | Recomposition scope, `remember`/`derivedStateOf`, `LazyColumn` keys, side effects |
+| Android Compose Screen Builder | Full screen generation: ViewModel, StateFlow, Material 3, Navigation, Hilt |
+| Android BLoC-compatible crash debugging | Detailed coroutine, lifecycle, and RecyclerView crash analysis |
+
+#### iOS
+| Agent | Description |
+|---|---|
+| Swift Code Reviewer | ARC, retain cycles, `@MainActor`, async/await, force-unwrap audit |
+| iOS Crash Analyzer | Symbolicated crash reports → 9-section analysis (EXC_BAD_ACCESS, SIGSEGV, watchdog) |
+
+#### Flutter
+| Agent | Description |
+|---|---|
+| Flutter Widget Generator | Production Dart widget from plain-English description |
+| Flutter BLoC Feature Builder | Complete layered feature: Cubit/BLoC, Repository, Dio, domain entities, test stubs |
+
+#### React Native
+| Agent | Description |
+|---|---|
+| RN Performance Optimizer | Re-renders, `useCallback`/`useMemo`, FlatList config, bridge overhead |
+
+#### Game Development
+| Agent | Description |
+|---|---|
+| Unity Shader Generator | Full `.shader` file from visual description (URP, HDRP, Built-in) |
+| Unreal Blueprint Advisor | Blueprint analysis, tick optimization, C++ migration candidates |
+
+#### Cross-Platform
+| Agent | Description |
+|---|---|
+| Release Notes Generator | `git log` → App Store copy + developer changelog + QA notes |
+| CI/CD Pipeline Generator | GitHub Actions / Fastlane for Android, iOS, Flutter, React Native |
+| Store Listing Writer | ASO-optimized App Store + Play Store listings with character counts |
+| Mobile Security Scanner | OWASP Mobile Top 10 — exploitability analysis + concrete fix per finding |
+| Accessibility Auditor | WCAG 2.2 audit across Compose, SwiftUI, Flutter, React Native |
+
+---
+
+### Skills (16 composable prompt modules)
+
+| Platform | Skills |
+|---|---|
+| Android | Code review (coroutines, Clean Architecture, Compose) |
+| iOS | Swift review, SwiftUI state, Networking, Unit testing, Performance, Data persistence |
+| Flutter | Widget generation rules |
+| React Native | Performance, Bridge audit |
+| Unity | Shader review |
+| Shared | Crash analysis, Accessibility audit, Security scan |
+
+---
+
+### Prompts (22)
+
+| Platform | Prompts |
+|---|---|
+| Android | Unit test generation, Migration guide, Compose layout, Gradle dependency audit, Flow explainer |
+| iOS | Swift concurrency explainer, Unit test generation, SwiftUI accessibility audit, Combine → async/await |
+| Flutter | Widget from design, Riverpod migration, Golden test, Performance audit |
+| React Native | Component audit, New Architecture migration, Navigation setup, Detox E2E test |
+| Game Dev | Shader from reference, Blueprint to C++, Game object architecture, Game balance table, Level design review |
+
+---
+
+### Tool Integrations
+
+| Tool | File | How |
+|---|---|---|
+| Claude Code | `CLAUDE.md` | Loaded automatically on repo open |
+| Cursor | `.cursorrules` | Loaded automatically — full agent index + platform rules |
+| ChatGPT | `docs/chatgpt-integration.md` | Paste-ready Custom GPT system prompt |
+| GitHub Copilot | `.github/copilot-instructions.md` | Loaded via `@workspace` |
+
+---
+
+### Examples
+
+Real code examples paired with agents:
+- `examples/android/ProfileViewModel.kt` — paired with Android Code Reviewer
+- `examples/android/sample-crash-log.txt` — paired with Android Crash Analyzer
+- `examples/ios/ProfileViewModel.swift` — paired with Swift Code Reviewer
+- `examples/flutter/expandable_card.dart` — paired with Flutter Widget Generator
+- `examples/react-native/FeedScreen.tsx` — paired with RN Performance Optimizer
+- `examples/game-dev/HolographicScanline.shader` — paired with Unity Shader Generator
+
+---
+
+## Metrics
+
+| Metric | Value |
+|---|---|
+| Agents | 14 |
+| Skills | 16 |
+| Standalone prompts | 22 |
+| Example files | 6 |
+| Lines of markdown / code | ~12,000+ |
+| Platforms covered | 7 (Android, iOS, Flutter, React Native, Unity, Unreal, Cross-Platform) |
+| LLM compatibility | Claude Sonnet 4.6, GPT-4o, Gemini 1.5 Pro |
+| Tool integrations | 4 (Claude Code, Cursor, ChatGPT, GitHub Copilot) |
+
+---
+
+## Known Limitations
+
+- Agents are prompt-based — output quality scales with the model. GPT-3.5 and smaller models produce weaker structured output.
+- The iOS Crash Analyzer requires symbolicated crash reports. Unsymbolicated `.crash` files return limited analysis.
+- The CI/CD Pipeline Generator produces starter configs. Secrets management and advanced signing workflows may require manual adaptation.
+- Game Dev agents (Unity, Unreal) are marked `Beta` — coverage for HDRP, Niagara, and GAS is limited in v0.1.0.
+
+---
+
+## Upgrade Notes
+
+This is the first public release — no migration needed.
+
+---
+
+## What's Next
+
+See [`docs/roadmap/github-issues.md`](../roadmap/github-issues.md) for the full v0.2.0 roadmap.
+
+Top priorities for v0.2.0:
+- Android APK/AAB size analyzer agent
+- iOS App Store Review Guidelines compliance checker
+- Flutter state architecture advisor (when to use Riverpod vs BLoC vs setState)
+- Windsurf and VS Code extension integration guides
+- Multi-file review workflow (review entire feature folder, not one file at a time)
+
+---
+
+## Contributors
+
+This release was authored by [Salman Ashraf](https://github.com/salmanashraf).
+
+Want to contribute? See [CONTRIBUTING.md](../../CONTRIBUTING.md) and open an issue before starting large work.
+
+---
+
+## License
+
+[MIT](../../LICENSE) — free to use, modify, and distribute. Attribution appreciated.