mobile-ai-agents 1.0.23

package/workflows/mobile-memory-workflow.md

@@ -0,0 +1,243 @@
+# Workflow — Mobile Memory Context Loop
+
+**Type:** AI session continuity  
+**Agents Used:** Mobile Memory, AXIOM, CRASHER, SWIFT, DART, BRIDGE, SENTINEL, PERF
+**Skills Used:** /mobile-memory-save, /mobile-memory-graph, /mobile-memory-search, /grill-mobile, /crash-triage, /release-prep
+
+---
+
+## When to Use
+
+Use this workflow when a mobile project will span multiple AI sessions, multiple tools, or multiple teammates. It prevents context loss when tokens run out, a session resets, or a teammate needs to continue from the exact current state.
+
+---
+
+## Quick Reference
+
+```text
+Session Start
+    ↓
+mobile-ai-agents memory inject
+    ↓
+/mobile-memory restore
+    ↓
+/grill-mobile → decisions captured
+    ↓
+Build / refactor / debug
+    ↓
+AXIOM / CRASHER / DART / SWIFT findings captured
+    ↓
+mobile-ai-agents memory capture
+    ↓
+/mobile-memory save before context runs out
+    ↓
+Commit MOBILE_MEMORY.md for handoff
+    ↓
+Next AI tool reads MOBILE_MEMORY.md and continues from NEXT ACTION
+```
+
+---
+
+## Full Loop
+
+### 1. Initialize Local Memory
+
+Run once per project:
+
+```bash
+npx mobile-ai-agents memory init
+```
+
+Capture durable events during the project:
+
+```bash
+npx mobile-ai-agents memory capture --type decision --text "Use Room for offline persistence."
+npx mobile-ai-agents memory capture --type finding --text "PRD verification failed because restart persistence is missing."
+npx mobile-ai-agents memory capture --type next-action --text "Implement HabitDao and restart persistence test."
+```
+
+Raw events are stored in `.mobile-ai-agents/memory/events.jsonl` and ignored by git by default.
+
+### 2. Session Start
+
+Run:
+
+```bash
+npx mobile-ai-agents memory inject
+```
+
+Paste the output into the new AI session, or ask the AI to run it when the tool has terminal access.
+
+Then run:
+
+```text
+/mobile-memory restore
+```
+
+Then paste the existing `MOBILE_MEMORY.md`. Mobile Memory summarizes the project in five bullets, briefs the active agent state, and continues from `NEXT ACTION`.
+
+Output to expect:
+
+```text
+Mobile Memory loaded. Here is what I know:
+- Platform, stack, and architecture
+- Current task
+- Decisions already made
+- Health risks and active agent findings
+- The exact NEXT ACTION
+```
+
+### 3. During Development
+
+Run:
+
+```text
+/grill-mobile
+```
+
+Capture requirements and decisions directly into the next Mobile Memory update:
+
+- Target platform and OS constraints
+- Architecture decisions
+- State management choices
+- API, persistence, navigation, and test decisions
+- Rejected alternatives
+
+Also capture durable decisions into local memory:
+
+```bash
+npx mobile-ai-agents memory capture --type decision --title "State management" --text "Use StateFlow in ViewModels and collectAsStateWithLifecycle in Compose."
+```
+
+### 4. Code Review
+
+Run the platform agent:
+
+```text
+@AXIOM review CartViewModel.kt
+/flutter-review checkout_page.dart
+@SWIFT review ProfileViewModel.swift
+```
+
+Write findings into the `Agent State` and `Health Report` sections:
+
+```text
+AXIOM → CartViewModel → CRITICAL: direct repository construction → pending DI refactor
+```
+
+Capture the finding:
+
+```bash
+npx mobile-ai-agents memory capture --type finding --title "AXIOM CartViewModel" --text "CRITICAL: direct repository construction; pending DI refactor."
+```
+
+### 5. Crash Analysis
+
+Run:
+
+```text
+/crash-triage
+@CRASHER analyze crash.log
+```
+
+Mobile Memory stores:
+
+- Crash type and severity
+- Failure path
+- Root cause
+- Regression test
+- Pending fix
+
+Critical crash findings belong in `Health Report > CRITICAL`.
+
+### 6. Search Before Continuing
+
+When returning to a project after days or weeks, search local memory before re-reading the full codebase:
+
+```bash
+npx mobile-ai-agents memory search persistence
+npx mobile-ai-agents memory timeline --limit 20
+```
+
+Use `/mobile-memory-search` to turn search output into confirmed context, assumptions, files to read next, and one `NEXT ACTION`.
+
+### 7. Token Warning
+
+When the session covers several topics, writes large code, or produces agent findings, run:
+
+```text
+/mobile-memory save
+```
+
+This creates the full `MOBILE_MEMORY.md` checkpoint. A new session can load it and continue without reading the entire codebase again.
+
+You can also generate `MOBILE_MEMORY.md` from local memory:
+
+```bash
+npx mobile-ai-agents memory checkpoint
+```
+
+### 8. Feature Complete
+
+Run:
+
+```text
+/mobile-memory update
+```
+
+Update `MOBILE_MEMORY.md` with:
+
+- Completed files
+- Final decisions
+- Agent findings resolved
+- Remaining tech debt
+- Next release or review action
+
+Commit `MOBILE_MEMORY.md` with the feature branch when the session context is valuable for review or handoff.
+
+### 9. Team Handoff
+
+Commit or send `MOBILE_MEMORY.md`. The teammate opens any AI tool and says:
+
+```text
+Read MOBILE_MEMORY.md and continue from NEXT ACTION.
+```
+
+No re-explanation required. The teammate's AI sees the architecture, graph, decisions, health report, and exact next step.
+
+---
+
+## Integration Points
+
+| Moment | Tool | Memory Section Updated |
+|---|---|---|
+| Memory setup | `mobile-ai-agents memory init` | Local event store |
+| Session start | `mobile-ai-agents memory inject`, `/mobile-memory restore` | Instant Resume, Progress |
+| Requirements | `/grill-mobile` | Decisions Made, Open Questions |
+| Durable decision | `mobile-ai-agents memory capture` | `.mobile-ai-agents/memory/events.jsonl` |
+| Memory search | `mobile-ai-agents memory search`, `/mobile-memory-search` | Relevant context |
+| Architecture map | `/mobile-memory graph` | Knowledge Graph |
+| Android review | `AXIOM` | Agent State, Health Report |
+| Crash debug | `CRASHER` | Health Report, Current Task |
+| Token warning | `/mobile-memory save` | Full checkpoint |
+| Feature complete | `/mobile-memory update` | Progress, NEXT ACTION |
+| Team handoff | Committed `MOBILE_MEMORY.md` | Resume Instructions |
+
+---
+
+## Output
+
+- A portable `MOBILE_MEMORY.md`
+- A mobile architecture knowledge graph
+- A preserved list of decisions and rejected alternatives
+- Agent findings that survive session resets
+- One executable `NEXT ACTION`
+
+---
+
+## Failure Modes
+
+- If `NEXT ACTION` is vague, rewrite it before saving.
+- If a relationship is inferred from naming only, mark it `INFERRED`.
+- If a file is mid-edit, paste enough current code in `Code State` for a new AI to avoid guessing.
+- If a finding is resolved, move it from `CRITICAL` or `WARNING` to `Done` or `Tech Debt`.

package/workflows/new-project-setup.md

@@ -0,0 +1,93 @@
+# Workflow — New Project Setup
+
+**Type:** Project bootstrapping
+**Agents Used:** AXIOM / SWIFT / DART / BRIDGE, PIPELINE, SENTINEL, FIGMA
+**Skills Used:** /grill-mobile, /android-tdd or /ios-tdd or /flutter-tdd
+
+---
+
+## When to Use
+
+Starting a new mobile project from scratch. Do this once, do it right.
+
+---
+
+## Steps
+
+```
+1. DEFINE — /grill-mobile (full 20 questions)
+   ↓ All 20 questions. No shortcuts.
+   ↓ This conversation determines every architecture decision that follows.
+   ↓ Output: confirmed understanding of the app's purpose, audience, and constraints.
+
+2. ARCHITECTURE — AXIOM / SWIFT / DART / BRIDGE
+   ↓ Generate the project structure based on /grill-mobile answers:
+     - Package/module structure
+     - Layer breakdown (data / domain / presentation)
+     - State management choice and why
+     - Navigation approach
+     - Dependency injection setup
+   ↓ Output: folder structure + base classes for each layer.
+
+3. CI FROM DAY ONE — PIPELINE
+   ↓ Set up CI before writing any feature code.
+   ↓ PR check: lint + unit tests (< 5 min)
+   ↓ Merge to main: build + deploy to Firebase App Distribution
+   ↓ Output: working CI pipeline on first commit.
+
+4. SECURITY BASELINE — SENTINEL
+   ↓ Review the project template for default insecure configurations.
+   ↓ Network security config (no cleartext traffic).
+   ↓ Keychain / Keystore setup for credentials.
+   ↓ Certificate pinning setup for production API.
+
+5. TEST INFRASTRUCTURE — /android-tdd or /ios-tdd or /flutter-tdd
+   ↓ Set up the test structure before any feature tests are needed.
+   ↓ Base test class for ViewModel tests.
+   ↓ Test doubles / mock infrastructure.
+   ↓ First test: a trivial "project compiles and one test passes" smoke test.
+
+6. DESIGN HANDOFF — FIGMA (if Figma access available)
+   ↓ Set up design token mapping to code tokens.
+   ↓ Generate base theme from design system.
+   ↓ Typography and color system in code.
+
+7. READY TO BUILD
+   ↓ Clean architecture structure ✓
+   ↓ CI running on first PR ✓
+   ↓ Security baseline in place ✓
+   ↓ Test infrastructure ready ✓
+   ↓ Design tokens wired up ✓
+```
+
+---
+
+## Project Setup Checklist
+
+```
+[ ] Version control: .gitignore includes keystore, local.properties, .env files
+[ ] README: setup instructions that work on a fresh checkout
+[ ] Architecture: documented decision (why this pattern, not just what)
+[ ] CI: first pipeline run successful
+[ ] Signing: debug keystore committed, release keystore in CI secrets only
+[ ] API environment: dev/staging/prod configs separated (not hardcoded)
+[ ] Analytics: event tracking structure decided before first feature
+[ ] Crash reporting: Firebase Crashlytics or Sentry configured
+```
+
+---
+
+## Inputs
+
+- App concept and target audience (from /grill-mobile)
+- Platform and minimum OS version
+- Team size and development timeline
+
+---
+
+## Outputs
+
+- Complete project scaffold with architecture
+- Working CI pipeline
+- Security-baseline configuration
+- Test infrastructure ready for first feature

package/workflows/new-screen.md

@@ -0,0 +1,68 @@
+# Workflow — New Screen
+
+**Type:** UI implementation
+**Agents Used:** FIGMA, AXIOM / SWIFT / DART / BRIDGE, PERF
+**Skills Used:** /grill-mobile, /compose-review or /swiftui-review or /flutter-review, /android-tdd or /ios-tdd
+
+---
+
+## When to Use
+
+Implementing a new screen from a Figma or design spec.
+
+---
+
+## Steps
+
+```
+1. DESIGN HANDOFF — FIGMA
+   ↓ Translate Figma spec into component spec:
+     - Layout dimensions and spacing
+     - Typography tokens
+     - Color tokens
+     - States: default, loading, empty, error
+     - Interactions and animations
+   ↓ Output: detailed component spec for implementation.
+
+2. ALIGNMENT — /grill-mobile (5 key questions for a screen)
+   ↓ What data does this screen load? From where?
+   ↓ What are the loading, empty, and error states?
+   ↓ What happens on tapping each interactive element?
+   ↓ Does this screen need to be deep-linkable?
+   ↓ What accessibility requirements apply?
+
+3. IMPLEMENTATION — AXIOM / SWIFT / DART / BRIDGE
+   ↓ Data/domain layer first (repository, use case, ViewModel/state).
+   ↓ UI scaffold: structure without real data.
+   ↓ Wire up real data with loading + error states.
+   ↓ Animations and interactions.
+
+4. REVIEW — /compose-review or /swiftui-review or /flutter-review
+   ↓ Recomposition / rebuild audit.
+   ↓ Accessibility check (touch targets, content descriptions).
+
+5. PERFORMANCE — PERF
+   ↓ Is the screen 60fps on a mid-range device?
+   ↓ Any list without virtualization?
+   ↓ Any main thread work during transition?
+
+6. TESTS
+   ↓ UI test: happy path loads and displays data correctly.
+   ↓ Unit test: ViewModel handles loading, success, and error states.
+```
+
+---
+
+## Inputs
+
+- Figma design file or detailed design description
+- API contract for data this screen consumes
+- Platform context (SDK version, design system in use)
+
+---
+
+## Outputs
+
+- Pixel-perfect, accessible, 60fps screen implementation
+- Unit test for ViewModel
+- UI test for happy path

package/workflows/perf-sprint.md

@@ -0,0 +1,78 @@
+# Workflow — Performance Sprint
+
+**Type:** Performance optimization
+**Agents Used:** PERF, AXIOM / DART / BRIDGE
+**Skills Used:** /perf-audit, /compose-review or /flutter-review
+
+---
+
+## When to Use
+
+When users are reporting slow performance, or before a major release as a performance gate.
+
+---
+
+## Steps
+
+```
+1. BASELINE — PERF
+   ↓ Measure before touching anything:
+     - App cold start time
+     - Hot start time (from background)
+     - 3 most-used screens: frame rate during scroll/interaction
+     - Memory footprint on target device
+     - Battery drain over 10 minutes of active use
+   ↓ Document numbers. This is your benchmark.
+
+2. PROFILE — /perf-audit
+   ↓ Run screen-by-screen profiling.
+   ↓ Use platform profiler (Systrace / Instruments / DevTools / Flipper).
+   ↓ Identify top 3 bottlenecks by frame time cost.
+
+3. FIX — AXIOM / DART / BRIDGE (platform-specific)
+   ↓ Fix the highest-impact bottleneck first.
+   ↓ Fix one thing at a time and re-measure after each fix.
+   ↓ Do NOT batch fixes — you won't know which one helped.
+
+4. REVIEW — /compose-review or /flutter-review (UI layer)
+   ↓ Check for unnecessary rebuilds introduced by the fix.
+   ↓ Ensure the optimization didn't create new jank.
+
+5. VALIDATE — PERF
+   ↓ Re-measure all baselines from step 1.
+   ↓ Target: each bottleneck shows measurable improvement.
+   ↓ Document: before numbers, after numbers, what changed.
+
+6. DOCUMENT
+   ↓ Add before/after screenshots to PR description.
+   ↓ Link to profiler traces in the PR.
+   ↓ Add a performance test or threshold to CI so it doesn't regress.
+```
+
+---
+
+## Performance Targets (Mobile)
+
+| Metric | Target |
+|---|---|
+| Cold start (time to interactive) | < 2 seconds |
+| Hot start | < 500ms |
+| Scroll frame rate | Consistent 60fps (< 16.7ms/frame) |
+| Memory (mid-range device) | < 150MB active |
+| Crash-free rate | > 99.5% |
+
+---
+
+## Inputs
+
+- Platform and device target (flagship / mid-range / low-end)
+- List of screens or features reported as slow
+- Profiler traces if available
+
+---
+
+## Outputs
+
+- Measured baseline vs. improved numbers
+- Code changes with documented performance rationale
+- Performance CI gate to prevent regression

package/workflows/release-cycle.md

@@ -0,0 +1,71 @@
+# Workflow — Release Cycle
+
+**Type:** Release management
+**Agents Used:** CRASHER, SENTINEL, SCRIBE, LAUNCHPAD, PIPELINE
+**Skills Used:** /release-prep
+
+---
+
+## When to Use
+
+Every release, from feature freeze to store submission.
+
+---
+
+## Steps
+
+```
+1. FEATURE FREEZE
+   ↓ Cut release branch: git checkout -b release/vX.Y.Z
+   ↓ No new features merged after this point. Only bug fixes.
+
+2. CRASH REVIEW — CRASHER
+   ↓ Pull last 7 days of crash data from Crashlytics/Sentry.
+   ↓ Any P0/P1 crashes must be fixed before this release ships.
+   ↓ Document crash-free rate baseline for comparison post-launch.
+
+3. SECURITY PASS — SENTINEL
+   ↓ Scan release branch for any new CRITICAL or HIGH vulnerabilities.
+   ↓ Focus on any new third-party dependencies added in this cycle.
+   ↓ Block release on any new CRITICAL finding.
+
+4. RELEASE NOTES — SCRIBE
+   ↓ git log <last-tag>..HEAD --oneline → paste into SCRIBE.
+   ↓ Generate store listing notes + internal changelog + stakeholder summary.
+   ↓ Human review before publishing.
+
+5. STORE LISTING — LAUNCHPAD (if features changed)
+   ↓ Update Play Store / App Store listing if new features warrant it.
+   ↓ New screenshots if UI changed significantly.
+
+6. CHECKLIST — /release-prep
+   ↓ Work through the full release checklist.
+   ↓ Every item checked before proceeding.
+
+7. BUILD & UPLOAD — PIPELINE
+   ↓ Trigger release build workflow.
+   ↓ AAB uploaded to Play Store internal track.
+   ↓ IPA uploaded to TestFlight.
+
+8. STAGED ROLLOUT
+   ↓ Play Store: 1% → 5% → 20% → 100% (monitor 24h at each stage).
+   ↓ App Store: release after review approval.
+   ↓ Monitor: crash rate, ANR rate, user ratings.
+```
+
+---
+
+## Inputs
+
+- Last release tag for git log diff
+- Crash reports from current version
+- Store developer account access
+
+---
+
+## Outputs
+
+- Release branch with all fixes
+- Store listing updated
+- Build uploaded to stores
+- Post-release monitoring active