mobile-ai-agents 1.0.33 → 1.0.35

package/AGENTS.md

@@ -101,7 +101,7 @@ Use the agent at agents/android/code-reviewer/agent.md to review this file:
 | Release Notes Generator | `agents/cross-platform/release-notes-generator/` | All | Git commits → user-facing release notes |
 | CI/CD Pipeline Generator | `agents/cross-platform/ci-cd-generator/` | All | Generates GitHub Actions / Bitrise / Fastlane configs |
 | Store Listing Writer | `agents/cross-platform/store-listing-writer/` | All | Play Store / App Store descriptions optimised for ASO |
-| Mobile Harness | `agents/cross-platform/mobile-harness/` | All | Build, test, verify UI, and run Mobile MCP QA for approved tasks |
+| Mobile Harness | `agents/cross-platform/mobile-harness/` | All | Guide beginners from idea and stack choice through one-task implementation, verification, device proof, and memory |
 
 ---
 

package/README.md

@@ -83,7 +83,7 @@ Mobile AI Agents turns AI coding from one-off prompts into a repeatable mobile e
 | 1. Start | Turn a raw idea into starter PRD, design, task, roadmap, and memory docs. | `npx mobile-ai-agents start` |
 | 2. Install | Add the agents, skills, and workflows to your AI coding tool. | `npx mobile-ai-agents install` |
 | 3. Open your app | Use it inside an Android, iOS, Flutter, React Native, KMP, Unity, or Unreal project. | Claude Code · Cursor · Windsurf · Copilot · Codex |
-| 4. Run the loop | Tell Mobile Harness to continue from the generated docs. It asks clarification questions before building. | `/mobile-harness` |
+| 4. Run the loop | Tell Mobile Harness to continue from the generated docs. New developers can use `BEGINNER_GUIDED` mode for stack advice and plain-language checkpoints. | `/mobile-harness` |
 | 5. Build with gates | The loop plans, implements, reviews architecture, checks security, audits performance, verifies UI, and runs QA. | `@MOBILE-HARNESS` |
 | 6. Continue later | Project context, decisions, reports, and next tasks are saved so work can continue across sessions. | Mobile Memory |
 
@@ -174,7 +174,9 @@ Not sure where to begin? Pick your situation:
 | Build, test, and verify a feature | `@MOBILE-HARNESS` + approved PRD/design/tasks |
 | Prepare a release | `/release-prep` |
 | Generate release notes | `@SCRIBE` + paste your git log |
-| Build an app from idea to store | `@APPFORGE` + answer the discovery questions |
+| Plan an app without implementing it | `@APPFORGE` + answer the discovery questions |
+| Build a first app with guided stack selection | `@MOBILE-HARNESS` in `BEGINNER_GUIDED` mode |
+| Build an approved app plan through device proof | `@MOBILE-HARNESS` |
 
 ---
 
@@ -316,7 +318,7 @@ Not sure where to begin? Pick your situation:
 | `/store-listing` | Conversation → ASO-optimized listing copy |
 | `/feature-slice` | Epic → independently shippable tickets |
 | `/release-prep` | Full release checklist from freeze to store |
-| `/accessibility-audit` | WCAG 2.1 AA + platform accessibility review |
+| `/accessibility-audit` | WCAG 2.1 AA, reskin contrast, and semantic color-token migration review |
 | `/api-versioning` | API deprecation strategy for mobile clients |
 | `/deeplink-debug` | Diagnoses broken deep links across Android and iOS |
 | `/mobile-mcp-qa` | Run AI-assisted QA on iOS/Android devices, simulators, and emulators |
@@ -431,20 +433,26 @@ Mobile Harness is the Loop Engineering orchestrator for Mobile AI Agents. It can
 
 Use it when you want to define the goal once and have the system keep moving through the app-building loop without repeating the same manual prompts at every stage.
 
+Use `BEGINNER_GUIDED` mode when this is your first mobile app or you are unsure about the platform or stack. Use APPFORGE alone when you only want planning documents; use Mobile Harness when you want implementation, verification, device proof, memory, and the next task too.
+
 ### What It Runs
 
 ```text
 Goal
--> clarify delivery profile and design direction
--> create or read PRD.md, DESIGN.md, TASKS.md, DEPENDENCIES.md, ROADMAP.md
--> implement one scoped task
--> run platform review
--> run tests
--> verify PRD and UI match
--> run device QA when available
--> run performance/security/accessibility checks when relevant
--> update MOBILE_MEMORY.md
--> produce MOBILE_HARNESS_REPORT.md
+-> PLAN: choose profile/stack and create or read PRD.md + ROADMAP.md
+-> DESIGN: approve DESIGN.md
+-> TASK: select one small item from TASKS.md
+-> IMPLEMENT: change only that task
+-> VERIFY: review, build, test, and check the PRD
+-> DEVICE PROOF: run Mobile MCP QA when available
+-> MEMORY: update MOBILE_MEMORY.md and the report
+-> NEXT ACTION: continue, fix, or stop at a human gate
+```
+
+Beginner prompt:
+
+```text
+Use MOBILE-HARNESS in BEGINNER_GUIDED mode. I have an app idea but I am not sure which platform or stack to use. Recommend one with reasons, create PRD.md, DESIGN.md, TASKS.md, DEPENDENCIES.md, ROADMAP.md, and MOBILE_MEMORY.md, then stop for approval before coding.
 ```
 
 ### First Questions It Should Ask

package/agents/cross-platform/mobile-harness/agent.md

@@ -29,8 +29,12 @@ Use MOBILE-HARNESS when the user wants one system to manage:
 - Performance and accessibility checks
 - Play Store launch preparation
 
+Use `BEGINNER_GUIDED` mode when the user has a rough idea, is new to mobile development, does not know which platform or stack to choose, or wants each step explained in plain language. This is a mode of Mobile Harness, not a separate agent, so the same evidence gates still apply.
+
 If product artifacts are missing, MOBILE-HARNESS invokes APPFORGE stages internally before allowing code implementation.
 
+Use APPFORGE by itself when the user only needs discovery, PRD, design, tasks, or roadmap output. Use Mobile Harness when the user wants those artifacts carried through implementation, verification, device proof, memory, and the next task.
+
 ---
 
 ## Autonomy Model
@@ -57,9 +61,64 @@ Ask the user only when:
 
 ---
 
+## Beginner-Guided Mode
+
+Beginner mode changes the explanation and defaults, not the engineering bar.
+
+Start with only the questions that cannot be inferred:
+
+```text
+1. What app do you want to build, and who is it for?
+2. Do you want iPhone, Android, or both? "Not sure" is valid.
+3. Is this your first mobile app, and which languages do you already know?
+4. Do you want the fastest learning prototype, a polished demo, or a production-ready app?
+```
+
+Inspect an existing repository before recommending anything. For a new app, recommend one stack and explain the reason in two plain-language sentences:
+
+| Situation | Default Recommendation | Reason |
+|---|---|---|
+| Android only | Kotlin + Jetpack Compose | Native Android tooling and direct platform access |
+| iPhone/iPad only | Swift + SwiftUI | Native Apple tooling and direct platform access |
+| Android + iOS, user knows TypeScript/JavaScript | React Native + Expo + TypeScript | Fast cross-platform start with familiar language and managed tooling |
+| Android + iOS, user accepts Dart and wants consistent custom UI | Flutter + Dart | One UI codebase with strong cross-platform rendering |
+| Existing app | Existing stack | Avoid an unnecessary rewrite and preserve project conventions |
+
+Document the recommendation, alternatives considered, and tradeoff in `PRD.md` and `ROADMAP.md`. Never imply there is one universally best stack.
+
+Create or refresh these artifacts before implementation:
+
+- `PRD.md`: user, problem, smallest useful outcome, requirements, edge cases, and open product decisions.
+- `DESIGN.md`: screen flow, states, navigation, visual direction, accessibility, and screenshot plan.
+- `TASKS.md`: small ordered tasks with acceptance criteria, verification command, and definition of done.
+- `DEPENDENCIES.md`: tools, libraries, services, environment variables, and setup blockers.
+- `ROADMAP.md`: milestones, task order, deferred scope, and release checkpoints.
+- `MOBILE_MEMORY.md`: decisions, completed work, current task, blockers, and one next action.
+
+Each artifact must start with a short `What this document means` paragraph and avoid unexplained acronyms. Each task should be finishable and verifiable independently; split tasks that mix setup, UI, data, and release work.
+
+Use this deterministic loop and show the current stage in every report:
+
+```text
+PLAN -> DESIGN -> TASK -> IMPLEMENT -> VERIFY -> DEVICE PROOF -> MEMORY -> NEXT ACTION
+```
+
+Human stop gates:
+
+- Stop after planning artifacts for approval before the first code change.
+- Stop when two product directions would materially change the MVP.
+- Stop for credentials, signing keys, API keys, account access, or private data.
+- Stop before destructive data/schema changes, irreversible migrations, or deleting user work.
+- Stop before enabling paid services, purchases, billing, or usage that may incur cost.
+- Stop before a public deployment, store submission, production rollout, or release approval.
+
+At a stop gate, explain `What is blocked`, `Why a decision is needed`, and `The smallest action the user must take`. Do not bury the request inside a long report.
+
+---
+
 ## First Message
 
-Start by asking:
+If `BEGINNER_GUIDED` applies, ask the four beginner questions above and infer the remaining details from the repository. Otherwise, collect only the missing fields from this advanced intake:
 
 ```text
 1. Are we starting from a new app idea or an existing codebase?
@@ -143,29 +202,21 @@ If the user does not choose, infer a practical default from the app category and
 ```text
 START
   ↓
-SELECT DELIVERY PROFILE
+PLAN: SELECT DELIVERY PROFILE + STACK; CREATE/READ PRD + ROADMAP
   ↓
-SELECT DESIGN DIRECTION
+DESIGN: APPROVE DESIGN.md
   ↓
-LOAD MOBILE_MEMORY.md IF PRESENT
+TASK: SELECT ONE SMALL TASK FROM TASKS.md
   ↓
-IF PRODUCT ARTIFACTS MISSING → RUN APPFORGE
+IMPLEMENT: CHANGE ONLY THAT TASK
   ↓
-APPROVE PRD + DESIGN + TASKS
+VERIFY: REVIEW + BUILD + TEST + /prd-verification
   ↓
-SELECT ONE TASK
+DEVICE PROOF: /mobile-mcp-qa + EVIDENCE
   ↓
-IMPLEMENT ONLY THAT TASK
+MEMORY: UPDATE MOBILE_MEMORY.md + REPORT
   ↓
-RUN PLATFORM REVIEW + TESTS
-  ↓
-VERIFY PRD + UI + ACCESSIBILITY
-  ↓
-RUN MOBILE MCP DEVICE QA
-  ↓
-UPDATE MOBILE_MEMORY.md
-  ↓
-CONTINUE NEXT TASK OR LAUNCH PREP
+NEXT ACTION: CONTINUE, FIX, OR STOP AT HUMAN GATE
 ```
 
 ---
@@ -198,13 +249,16 @@ If an artifact is missing or stale, update it before implementing.
 - Work on one task only.
 - Do not modify unrelated files.
 - Read dependencies before implementation.
+- Route the task to the narrowest relevant agent or skill and record that choice in Orchestration State; MOBILE-HARNESS retains ownership of the result.
+- Use `/mobile-app-design` for new screens, redesigns, reskins, navigation changes, and design-system work; require approval of multi-screen reskin plans before editing.
 - Use the platform reviewer after code changes: AXIOM, SWIFT, DART, or BRIDGE.
-- Run tests if available.
+- Run the configured build, lint/static-analysis, and test checks after every task. If commands are missing, discover safe platform defaults; mark unavailable checks explicitly instead of silently skipping them.
 - Run `/prd-verification` to verify behavior against `PRD.md`, `DESIGN.md`, `TASKS.md`, tests, screenshots, and QA reports.
 - Verify UI against the design artifact, not memory.
 - Use Mobile MCP for device, emulator, or simulator evidence when available.
 - Capture screenshots, element lists, and failures in the report.
 - Update `MOBILE_MEMORY.md` after every approved stage, completed task, blocker, failed QA pass, and end-of-day checkpoint.
+- Run the `mobile-flight-recorder` workflow at the end of each session so changed files, commands, evidence, blockers, and the next action survive the handoff.
 - Run `npx mobile-ai-agents memory checkpoint` when local memory should produce or refresh `MOBILE_MEMORY.md`.
 - Mark task done only when acceptance criteria, tests, UI match, and device QA pass or accepted exceptions are documented.
 
@@ -218,8 +272,15 @@ MOBILE HARNESS REPORT
 Platform:
 Task:
 Status: PASS | FAIL | BLOCKED
-Mode: IDEA_TO_STORE | EXISTING_PROJECT | FEATURE_EXECUTION | QA_ONLY
+Mode: BEGINNER_GUIDED | IDEA_TO_STORE | EXISTING_PROJECT | FEATURE_EXECUTION | QA_ONLY
 Delivery Profile: SMALLEST_MVP | DEMO_GRADE_MVP | PRODUCTION_READY_MVP
+Current Loop Stage: PLAN | DESIGN | TASK | IMPLEMENT | VERIFY | DEVICE_PROOF | MEMORY | NEXT_ACTION
+
+Beginner Checkpoint:
+- What happened:
+- Why it matters:
+- Decision needed: <plain-language request or "None">
+- What happens next:
 
 Artifacts Read:
 | Artifact | Status | Notes |
@@ -277,18 +338,24 @@ NEXT ACTION:
 ## System Prompt
 
 ```text
-You are MOBILE-HARNESS, the autonomous top-level orchestrator for Mobile AI Agents. You can take a mobile app from rough idea to shipped release, or take an existing project through implementation, tests, UI verification, device QA, and launch readiness with minimal human effort.
+You are MOBILE-HARNESS, the autonomous top-level orchestrator for Mobile AI Agents. Take a mobile app from rough idea to release, or guide an existing project through implementation and evidence-based verification.
 
 Coordinate specialized systems:
 - APPFORGE for discovery, PRD, design plan, tasks, dependencies, roadmap, and store prep.
-- Mobile Memory for long-term project memory across days or weeks.
-- mobile-ai-agents memory commands for local event capture, search, context injection, and MOBILE_MEMORY.md checkpoint generation when terminal access is available.
+- Mobile Memory and mobile-ai-agents memory commands for durable context and checkpoints.
 - AXIOM, SWIFT, DART, or BRIDGE for platform-specific code review.
 - /prd-verification for evidence-based PRD, design, task, test, and UI match checks.
+- /mobile-app-design for screens, navigation changes, redesigns, and reskins.
 - /mobile-mcp-qa for emulator, simulator, or real-device QA evidence.
-- /accessibility-audit, PERF, /perf-audit, CRASHER, LAUNCHPAD, SCRIBE, and PIPELINE when the lifecycle requires them.
+- Relevant accessibility, performance, crash, release, and store specialists when required.
+
+Require approved PRD, design, task, and dependency context before coding. If missing, create it through APPFORGE and wait for approval. Choose a delivery profile and design direction first.
+
+Use BEGINNER_GUIDED mode for a rough idea, a new mobile developer, or an unknown platform/stack. Ask only what cannot be inferred. Recommend one stack with plain-language reasons and tradeoffs. Create beginner-readable PRD.md, DESIGN.md, TASKS.md, DEPENDENCIES.md, ROADMAP.md, and MOBILE_MEMORY.md. Show the current stage in this fixed loop: PLAN -> DESIGN -> TASK -> IMPLEMENT -> VERIFY -> DEVICE PROOF -> MEMORY -> NEXT ACTION. Explain what happened, why it matters, any decision needed, and what happens next.
+
+Stop for product approval, credentials, destructive or irreversible actions, paid services, and public release approval. For demos or marketing, default to Demo-grade MVP with seeded data, multiple visible states, screenshot planning, and UI polish.
 
-Before coding, require approved PRD/design/task/dependency context. If missing, create or update it through APPFORGE and wait for approval. Before creating those artifacts, choose or ask for a delivery profile: Smallest MVP, Demo-grade MVP, or Production-ready MVP. Also choose or ask for the design direction: clean utility, polished consumer, playful gamified, premium wellness, dense dashboard, enterprise/admin, or custom reference. If the user is recording a demo, marketing the repo, or showing Loop Engineering, default to Demo-grade MVP and require a visually complete app with seeded data, multiple visible screens/states, screenshot plan, and UI polish pass. Be autonomous by default: create artifacts, choose safe defaults, run tools, verify results, and proceed to the next safe step without asking the user to do routine work. Ask only for product decisions, credentials, unavailable external systems, paid or irreversible actions, destructive actions, or approval gates. Work one task at a time. Modify only files required for the current task. After changes, run available tests, invoke the relevant platform reviewer, compare UI against the approved design, run /prd-verification against PRD.md, DESIGN.md, TASKS.md, evidence, and reports, use Mobile MCP for device evidence when available, and update MOBILE_MEMORY.md.
+Work on one task at a time and modify only required files. Use /mobile-app-design for UI work. Then run tests, platform review, UI comparison, /prd-verification, and /mobile-mcp-qa when available. Update MOBILE_MEMORY.md and run mobile-flight-recorder at session end.
 
 Never mark done unless acceptance criteria are met or exceptions are explicitly documented. Always produce MOBILE HARNESS REPORT with orchestration state, implementation summary, code review, tests, PRD verification, UI match, Mobile MCP QA, acceptance criteria with source references, Mobile Memory update, remaining issues, and one NEXT ACTION.
 

package/docs/getting-started.md

@@ -16,6 +16,14 @@ npx mobile-ai-agents start
 
 This creates `PRD.md`, `DESIGN.md`, `TASKS.md`, `ROADMAP.md`, and `MOBILE_MEMORY.md`. After reviewing those files, install the agents and run `/mobile-harness` to continue from the approved plan.
 
+If this is your first mobile app or you do not know which stack to choose, start Mobile Harness like this:
+
+```text
+Use MOBILE-HARNESS in BEGINNER_GUIDED mode. I have a rough app idea and need a stack recommendation. Explain each checkpoint in plain language, create the planning documents, and stop for approval before coding.
+```
+
+APPFORGE is the planning specialist. Mobile Harness uses APPFORGE for planning, then continues through one-task implementation, verification, device proof, memory, and the next action.
+
 | I need to... | Start with this loop | Good first tool |
 |---|---|---|
 | Plan an app or feature | Planning | `@APPFORGE` |

package/docs/mobile-harness.md

@@ -4,6 +4,10 @@ Mobile Harness is the top-level orchestrator for Mobile AI Agents. It can start
 
 Use it when you want one AI system to manage the full mobile delivery loop with as little human effort as safely possible, while still using specialized agents and skills underneath.
 
+Choose `BEGINNER_GUIDED` mode if you have only an app idea, do not know the right mobile stack, or want each checkpoint explained in plain language. It uses the same rigorous build and QA gates as the standard harness.
+
+Use APPFORGE alone when you only want planning documents. Use Mobile Harness when you want the plan implemented, verified, tested on a device, saved to memory, and continued task by task.
+
 ---
 
 ## Mental Model
@@ -13,6 +17,7 @@ MOBILE-HARNESS
 ├── APPFORGE      → idea, PRD, design, tasks, roadmap
 ├── Mobile Memory → long-term memory across days/weeks
 ├── AXIOM/SWIFT/DART/BRIDGE → platform code review
+├── /mobile-app-design → screens, navigation, redesigns, and reskins
 ├── /mobile-mcp-qa → emulator/device UI verification
 ├── /accessibility-audit → accessibility verification
 ├── /perf-audit or PERF → performance verification
@@ -23,6 +28,42 @@ MOBILE-HARNESS
 ```
 
 APPFORGE plans. Mobile Memory remembers. Mobile Harness orchestrates execution and evidence.
+Mobile Flight Recorder records the end-of-session handoff so another session can resume from the exact next action.
+
+The fixed loop is:
+
+```text
+PLAN -> DESIGN -> TASK -> IMPLEMENT -> VERIFY -> DEVICE PROOF -> MEMORY -> NEXT ACTION
+```
+
+---
+
+## Beginner-Guided Start
+
+Mobile Harness asks four simple questions: what the app does and who it serves, whether it targets Android/iPhone/both, which languages you know, and whether you want a learning prototype, polished demo, or production app. It inspects an existing project before recommending a stack.
+
+For a new project, its defaults are native Compose for Android, native SwiftUI for Apple platforms, React Native with Expo for cross-platform TypeScript developers, and Flutter for teams that accept Dart and prioritize consistent custom UI. The recommendation includes reasons and tradeoffs; it is not treated as universally correct.
+
+Before coding it creates:
+
+- `PRD.md` for the user problem and requirements.
+- `DESIGN.md` for screens, states, navigation, accessibility, and screenshot proof.
+- `TASKS.md` for small independently verifiable work items.
+- `DEPENDENCIES.md` for tools, services, keys, and setup.
+- `ROADMAP.md` for milestones and deferred scope.
+- `MOBILE_MEMORY.md` for decisions, progress, blockers, and the next action.
+
+It stops for approval before the first code change and before credentials, destructive actions, paid services, irreversible migrations, public deployment, or store release.
+
+```text
+Use MOBILE-HARNESS in BEGINNER_GUIDED mode.
+App idea: A simple meal planner for busy parents.
+Target platform: Not sure.
+Experience: I know basic TypeScript and this is my first mobile app.
+Goal: A polished demo.
+
+Recommend the stack, explain why, create the planning documents, and stop for approval before coding.
+```
 
 ---
 
@@ -59,6 +100,7 @@ Mobile Harness verifies against docs, not memory:
 | `DESIGN.md` or design plan | Required before UI work | Layout, states, visual target |
 | `TASKS.md` | Required before implementation | Task scope and acceptance criteria |
 | `DEPENDENCIES.md` | Required before implementation | Libraries, APIs, env vars |
+| `ROADMAP.md` | Required for idea-to-app work | Milestones, sequence, deferred scope, release checkpoints |
 | `MOBILE_HARNESS_REPORT.md` | Required after each cycle | Evidence and pass/fail state |
 
 If these docs are missing, Mobile Harness routes to APPFORGE first.
@@ -112,6 +154,8 @@ Platform:
 Task:
 Status: PASS | FAIL | BLOCKED
 Mode:
+Current Loop Stage:
+Beginner Checkpoint:
 Artifacts Read:
 Orchestration State:
 Implementation Summary:

package/docs/wiki.md

@@ -384,6 +384,16 @@ Full guide: [`docs/vscode-copilot-integration.md`](vscode-copilot-integration.md
 
 **Specify the exact platform:** `Android-Compose`, `Android-XML`, `iOS-SwiftUI`, `iOS-UIKit`, `Flutter`, or `React-Native`. The fixes differ significantly between frameworks.
 
+For a reskin or theme migration, run `/accessibility-audit` with the supported themes, theme/token source, affected screens, and resolved foreground/background pairs. It maps by semantic role rather than old hex value, computes WCAG AA contrast for light and dark modes, and reports role collisions where one palette value was incorrectly reused for text, borders, fills, disabled content, or status states. Pair it with `/mobile-app-design` before implementation and `/mobile-mcp-qa` for device screenshots afterward.
+
+```text
+/accessibility-audit
+PLATFORM: React Native
+SUPPORTED_THEMES: light, dark
+Audit the Settings reskin and token migration. Report failed pairs with their ratio,
+required ratio, semantic role, theme/state, and recommended token.
+```
+
 ---
 
 ## 7. How Skills Work

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-ai-agents",
-  "version": "1.0.33",
+  "version": "1.0.35",
   "description": "AI agents, skills, and Loop Engineering workflows for building, testing, auditing, and releasing mobile apps.",
   "bin": {
     "mobile-ai-agents": "cli/index.js",

package/skills/cross-platform/accessibility-audit.md

@@ -7,7 +7,27 @@
 
 ## Purpose
 
-Reviews any mobile screen for WCAG 2.1 AA compliance and platform accessibility standards. Increasingly required by law (EU Accessibility Act 2025, ADA).
+Reviews mobile UI for WCAG 2.1 AA and platform accessibility requirements. It also verifies app reskins and color-token migrations by semantic role so palette replacements do not create invisible text, controls, or status states.
+
+## When to Use
+
+- Before releasing a new or redesigned mobile screen.
+- After `/mobile-app-design` changes themes, tokens, components, or navigation.
+- When a reskin replaces hardcoded colors or consolidates competing palettes.
+- When `/mobile-mcp-qa` finds unreadable content or a theme-specific regression.
+
+## Inputs
+
+Provide as much of this evidence as is available:
+
+```text
+PLATFORM: Android | iOS | Flutter | React Native
+SUPPORTED_THEMES: light, dark, or named themes
+UI_SOURCE: screen/component and theme/token source files
+COLOR_PAIRS: optional resolved foreground/background pairs by role, theme, and state
+SCREENSHOTS: optional device evidence; never a substitute for computed colors
+RESKIN_PLAN: optional /mobile-app-design screen inventory and token migration plan
+```
 
 ---
 
@@ -59,5 +79,135 @@ React Native:
 - accessibilityHint for non-obvious actions.
 - accessible={false} for decorative elements.
 
-For each issue: element, requirement violated, WCAG criterion, and concrete fix.
+RESKIN AND TOKEN MIGRATION:
+1. Build a usage inventory before changing or approving tokens. Inspect each occurrence as
+   body text, large text, muted/secondary text, icon, border, fill/surface, disabled content,
+   disabled fill, status content, status fill, or fixed-tone content/fill.
+2. Map colors by semantic role, never by old hex value. If one old hex is used for text,
+   borders, and fills, those usages require separate destination tokens. Flag a single
+   replacement token across different roles as ROLE_COLLISION.
+3. Resolve the actual foreground and background after aliases, theme selection, state layers,
+   opacity, and alpha compositing. Do not infer contrast from token names or visual judgment.
+4. Compute WCAG relative luminance and contrast ratio for every supported theme and relevant
+   state. Use (Llighter + 0.05) / (Ldarker + 0.05).
+5. Require at least 4.5:1 for body/normal text and 3:1 for large text, icons, borders,
+   focus indicators, and other meaningful non-text UI. Large text is at least 18pt regular
+   or 14pt bold. Decorative borders and inactive controls do not need 3:1, but enabled
+   control boundaries and state indicators do.
+6. Test these pairs separately in every theme:
+   - body text on each surface it appears on
+   - muted/secondary text on each surface it appears on
+   - icons and meaningful borders against adjacent colors
+   - status chips/badges: content on container and container against its surroundings when
+     the boundary communicates status
+   - disabled content on disabled fill and surrounding surface; disabled state must not rely
+     on low contrast or color alone
+   - error, success, warning, and info content/containers
+   - fixed-tone content on fixed-tone fills, without allowing system theme substitution
+7. Detect invisible-text risks: foreground and background resolving to the same token/value,
+   on-color paired with the wrong container, transparent content composited onto a matching
+   surface, fixed-tone content replaced by a theme-dependent token, or a missing dark token
+   falling back to a light-theme value.
+8. Screenshots may reveal where to inspect, but sampled pixels are not sufficient when text
+   has antialiasing, transparency, imagery, or gradients. Use resolved source/runtime colors
+   for the computed result and mark unavailable pairs UNVERIFIED.
+
+For each accessibility issue include the element, requirement, WCAG criterion, severity,
+evidence, and concrete fix. For color failures, recommend a semantic token, not only a hex.
+
+OUTPUT FORMAT:
+ACCESSIBILITY AUDIT
+===================
+Platform:
+Themes audited:
+Evidence:
+Result: PASS | FAIL | PARTIAL | BLOCKED
+
+Summary:
+- Critical:
+- High:
+- Medium:
+- Low:
+- Unverified:
+
+Role Collision Audit:
+| Old Color/Token | Source Usages | Incorrect Mapping | Required Role Tokens | Result |
+|---|---|---|---|---|
+
+Contrast Results:
+| Element/Pair | Role | Theme/State | Foreground | Background | Ratio | Required | Recommended Token | Result |
+|---|---|---|---|---|---:|---:|---|---|
+
+Other Findings:
+| Severity | Element | Requirement/WCAG | Evidence | Fix |
+|---|---|---|---|---|
+
+Unverified Evidence:
+- Pair or behavior, missing evidence, and exact verification needed.
+
+Decision:
+- PASS only when all in-scope themes and states have computed passing pairs and no blocking
+  semantic, focus, label, target-size, or announcement failures remain.
+- PARTIAL when available checks pass but required evidence is missing.
+- FAIL when any required pair or accessibility behavior fails.
+```
+
+## Example
+
+**Input:**
+
+```text
+PLATFORM: React Native
+SUPPORTED_THEMES: light, dark
+RESKIN_PLAN: Replace legacy #6B7280 usages with the new secondary token.
+UI_SOURCE:
+- Settings helper text used #6B7280.
+- Card borders used #6B7280.
+- Dark theme maps secondary to #334155 on surface #0F172A.
 ```
+
+**Output:**
+
+```text
+ACCESSIBILITY AUDIT
+===================
+Platform: React Native
+Themes audited: light, dark
+Evidence: resolved theme tokens and Settings source
+Result: FAIL
+
+Summary:
+- Critical: 0
+- High: 1
+- Medium: 1
+- Low: 0
+- Unverified: 0
+
+Role Collision Audit:
+| Old Color/Token | Source Usages | Incorrect Mapping | Required Role Tokens | Result |
+|---|---|---|---|---|
+| #6B7280 | helper text, card border | color.secondary | color.onSurfaceVariant, color.outline | ROLE_COLLISION |
+
+Contrast Results:
+| Element/Pair | Role | Theme/State | Foreground | Background | Ratio | Required | Recommended Token | Result |
+|---|---|---|---|---|---:|---:|---|---|
+| Settings helper/surface | muted text | dark/default | #334155 | #0F172A | 1.72:1 | 4.5:1 | color.onSurfaceVariant | FAIL |
+| Settings card edge/surface | meaningful border | dark/default | #334155 | #0F172A | 1.72:1 | 3:1 | color.outline | FAIL |
+
+Other Findings:
+| Severity | Element | Requirement/WCAG | Evidence | Fix |
+|---|---|---|---|---|
+| HIGH | Settings helper | 1.4.3 contrast | Dark token migration makes text nearly invisible | Map text to color.onSurfaceVariant and verify >= 4.5:1 |
+| MEDIUM | Settings card | 1.4.11 non-text contrast | Border no longer communicates grouping | Map border to color.outline and verify >= 3:1 |
+
+Unverified Evidence:
+- None.
+
+Decision:
+- FAIL. Split the legacy value by semantic role, recompute both dark-mode pairs, and rerun
+  `/mobile-mcp-qa` for Settings in light and dark themes.
+```
+
+## Composition
+
+Use `/mobile-app-design` to define the reskin and token plan, this skill to compute accessibility results, and `/mobile-mcp-qa` to capture device evidence in every supported theme.

package/workflows/mobile-harness.md

@@ -2,7 +2,7 @@
 
 **Type:** Top-level mobile delivery orchestration  
 **Agents Used:** MOBILE-HARNESS, APPFORGE, Mobile Memory, AXIOM / SWIFT / DART / BRIDGE, CRASHER, PERF, LAUNCHPAD, SCRIBE, PIPELINE
-**Skills Used:** /mobile-mcp-qa, /accessibility-audit, /perf-audit, /mobile-memory-save, /release-prep, /store-listing
+**Skills Used:** /mobile-app-design, /prd-verification, /mobile-mcp-qa, /accessibility-audit, /perf-audit, /mobile-memory-save, /release-prep, /store-listing
 
 ---
 
@@ -10,6 +10,10 @@
 
 Use this workflow when a user wants one orchestrator that can manage the complete mobile app lifecycle: idea, planning, implementation, verification, multi-session memory, device QA, and launch preparation.
 
+Use `BEGINNER_GUIDED` mode when the user is new to mobile development, has only a rough idea, or does not know which platform or stack to choose. Do not create a separate beginner agent: Mobile Harness already owns the full lifecycle and can route planning work to APPFORGE.
+
+Use APPFORGE alone when the requested deliverable stops at discovery, PRD, design, tasks, or roadmap. Use Mobile Harness when the user wants the plan executed and proved on an emulator, simulator, or device.
+
 This workflow is intentionally strict. It prevents the common AI failure mode of building code without proving it matches the product plan, design, and real-device behavior.
 
 The goal is near-zero human effort. MOBILE-HARNESS should do routine product, engineering, QA, documentation, and release-prep work itself. The user should mainly provide the initial goal, approve major gates, and supply credentials or business decisions that cannot be inferred safely.
@@ -44,38 +48,47 @@ Ask the user only for:
 ## Lifecycle Map
 
 ```text
-0. START
-   ↓ New idea or existing codebase?
+PLAN -> DESIGN -> TASK -> IMPLEMENT -> VERIFY -> DEVICE PROOF -> MEMORY -> NEXT ACTION
+```
 
-1. DELIVERY PROFILE
-   ↓ Smallest MVP, Demo-grade MVP, or Production-ready MVP
+The eight stages are deterministic. Full QA and launch preparation happen as tasks inside the same loop rather than bypassing it.
 
-2. DESIGN DIRECTION
-   ↓ Clean utility, polished consumer, playful gamified, premium wellness, dense dashboard, enterprise/admin, or custom reference
+---
 
-3. MEMORY
-   ↓ Load or create MOBILE_MEMORY.md
+## Beginner-Guided Defaults
 
-4. PRODUCT PLAN
-   ↓ APPFORGE discovery, PRD.md, design plan, TASKS.md, DEPENDENCIES.md
+Ask only what cannot be discovered from the repository: app idea and audience, target platform, existing language experience, and delivery goal. `Not sure` is a valid answer.
 
-5. TASK LOOP
-   ↓ Select exactly one task
-   ↓ Implement only that task
-   ↓ Platform review
-   ↓ Tests
-   ↓ PRD verification
-   ↓ UI match review
-   ↓ Mobile MCP QA
-   ↓ Update MOBILE_MEMORY.md
+Recommend one stack with a plain-language explanation and record the tradeoff:
 
-6. FULL QA
-   ↓ Accessibility, performance, crash risk, edge cases
+| Need | Recommended Stack |
+|---|---|
+| Android only | Kotlin + Jetpack Compose |
+| iPhone/iPad only | Swift + SwiftUI |
+| Android + iOS with TypeScript/JavaScript experience | React Native + Expo + TypeScript |
+| Android + iOS with highly consistent custom UI | Flutter + Dart |
+| Existing app | Keep the existing stack |
 
-7. LAUNCH
-   ↓ Store listing, release notes, checklist, pipeline
+Before implementation, create beginner-readable `PRD.md`, `DESIGN.md`, `TASKS.md`, `DEPENDENCIES.md`, `ROADMAP.md`, and `MOBILE_MEMORY.md`. Explain each document's purpose, keep tasks independently shippable, and give every task acceptance criteria plus a verification command.
+
+At the end of every stage, state:
+
+```text
+What happened:
+Why it matters:
+Decision needed: None | <one explicit request>
+What happens next:
 ```
 
+Stop at these human gates:
+
+- Approval of PRD, design, and task order before the first implementation.
+- Product choices that materially change the MVP.
+- Credentials, keys, certificates, account access, or private data.
+- Destructive operations, irreversible migrations, or deletion of user data/work.
+- Paid services, purchases, billing changes, or cost-incurring usage.
+- Public deployment, store submission, production rollout, or release approval.
+
 ---
 
 ## Delivery Profiles
@@ -203,15 +216,17 @@ For each task:
 4. Read `TASKS.md`.
 5. Read `DEPENDENCIES.md`.
 6. Select exactly one task.
-7. Implement only that task.
-8. Run platform reviewer.
-9. Run tests.
-10. Verify behavior against `PRD.md`.
-11. Verify UI against design.
-12. Run `/mobile-mcp-qa` if device automation is available.
-13. Produce `DEVICE_QA_REPORT.md` with the `device-proof-report` workflow when screenshots or device proof are required.
-14. Write `MOBILE_HARNESS_REPORT.md`.
-15. Update `MOBILE_MEMORY.md`.
+7. Select the narrowest specialist agent or skill and record why it fits the task.
+8. Use `/mobile-app-design` first when the task creates or changes screens, navigation, visual identity, or a reskin; then implement only that task.
+9. Run platform reviewer.
+10. Run the configured build, lint/static-analysis, and test commands. Discover safe platform defaults when commands are missing and record any unavailable check.
+11. Verify behavior against `PRD.md`.
+12. Verify UI against design.
+13. Run `/mobile-mcp-qa` if device automation is available.
+14. Produce `DEVICE_QA_REPORT.md` with the `device-proof-report` workflow when screenshots or device proof are required.
+15. Write `MOBILE_HARNESS_REPORT.md`.
+16. Update `MOBILE_MEMORY.md`.
+17. At session end, run `mobile-flight-recorder` to preserve changed files, commands, evidence, blockers, and the next action.
 
 After a task passes, continue to the next safe task automatically when the user has approved autonomous execution for the project. Stop only at human gates defined in the Autonomy Contract.
 
@@ -307,6 +322,12 @@ Start from scratch:
 Use MOBILE-HARNESS. Start from a new app idea and orchestrate APPFORGE, Mobile Memory, implementation, QA, and launch prep.
 ```
 
+Beginner-guided start:
+
+```text
+Use MOBILE-HARNESS in BEGINNER_GUIDED mode. I have an app idea but need help choosing the platform and stack. Explain each checkpoint in plain language, create the planning documents, and stop for approval before the first code change.
+```
+
 Resume multi-day feature:
 
 ```text