Skip to content

docs(stories): Maestro-adoption epic — 12 implementation stories#381

Merged
Lykhoyda merged 14 commits into
mainfrom
limestone-malpais
Jul 2, 2026
Merged

docs(stories): Maestro-adoption epic — 12 implementation stories#381
Lykhoyda merged 14 commits into
mainfrom
limestone-malpais

Conversation

@Lykhoyda

@Lykhoyda Lykhoyda commented Jul 1, 2026

Copy link
Copy Markdown
Owner

What

Adds docs/stories/ — an epic README + 12 implementation stories distilled from a code-level comparative deep-dive of mobile-dev-inc/maestro (iOS XCTest runner stack, core/Android orchestration engine, MCP server design) against this plugin's architecture.

Each story carries: problem with file:line evidence in both codebases, the Maestro reference mechanism, a concrete design, implementation steps, acceptance criteria, a test plan, and risks.

The stories

# Story Impact
01 Prebuilt runner artifacts 6-min cold xcodebuild → <30 s; CI smoke enabler
02 Runner wire-protocol versioning + /tmp state relocation Closes the bridge/runner skew bug class (observed live 2026-07-01)
03 Quiescence-bypass swizzle (FBQuiescence lineage) Kills the XCTest idle-wait flake class (Reanimated deadlocks, type timeouts) at the root
04 Shared two-tier settle engine + capability flags Replaces fixed sleeps with a "UI is stable" invariant on both platforms
05 Self-healing taps (attrs-minus-bounds re-resolution + retry-if-no-change) Most STALE_REF refusals become transparent in-tool repairs
06 Native-runner tests in CI + LLM-behavior evals Coverage for the currently-unexecuted riskiest layer
07 Native-first action replay (Maestro YAML stays the interchange) Resolves #317 fully; removes WDA from the replay critical path; adds x-rn: hybrid assertions
08 Token-efficient outputs (compact snapshot schema, screenshot downscale, deep-tree recovery) ≥60 % snapshot token reduction target
09 Android parity + shared client core (+ optional adb-stream transport) Tri-state liveness symmetry; deletes the duplicated arg-builder switches
10 Text-input reliability (iOS two-burst, Android ACTION_SET_TEXT) Dropped-keystroke / emoji flake class
11 Failure-evidence bundles + structured refusal reasons + agent-device debt ratchet Repair quality, telemetry integrity, retires misleading legacy errors
12 Tool-surface consolidation + 2 KB instructions test + first-result hint Agent ergonomics at 74 tools, eval-gated

Sequencing

Wave 1 (independent): 01, 02, 03, 08, 11 → Wave 2: 04, 06, 09 → Wave 3: 05, 10 → Wave 4: 07, 12.

Notes

  • Docs-only; no changeset needed (no shippable src changes).
  • Direction logged as D1289 in the workspace decisions ledger; ROADMAP entry appended (2026-07-02).
  • Follow-up after review: file each story as a GitHub issue with Kano/priority labels.

🤖 Generated with Claude Code

Lykhoyda and others added 11 commits July 1, 2026 17:44
…iewed + amended)

TDD plan for the in-runner live-tap keyboard-occlusion guard (iOS + Android),
amended per the Claude+Codex plan review: pure predicate in a dependency-free
file, guard at the command handler (not tapAt), Android FLAG_RETRIEVE_INTERACTIVE_WINDOWS,
containment predicate, destructive-back safety, off-device tests.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…ns for KeyboardGuard (#370)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Comparative deep-dive of mobile-dev-inc/maestro (iOS XCTest runner,
core/Android orchestration, MCP server design) vs this plugin,
distilled into an epic README + 12 stories with problem/evidence,
Maestro reference mechanics, design, implementation steps, acceptance
criteria, test plans, and risks:

01 prebuilt runner artifacts        07 native-first action replay (#317)
02 runner protocol versioning       08 token-efficient outputs
03 quiescence bypass                09 Android parity + shared core
04 two-tier settle engine           10 text-input reliability
05 self-healing taps                11 failure evidence + debt
06 native-runner CI + evals         12 tool-surface consolidation

Logged as D1289 in the workspace ledger.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c3520e5670

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

…— seamless maestro-runner (Go) integration (D1290)

Maintainer call: replay stays on the Go maestro-runner engine. Story 07
keeps the recorded effort assessment and becomes the documented
escalation path. Story 13 closes the integration seams instead:
version pinning + compat gate, proactive blind-probe (skip the 40s
doomed WDA attempt on iOS 26), wider CDP fallback grammar (absorbs
#334, incl. optional x-rn hybrid asserts), host-side keyboard seam
(B223), single-step iteration mode (absorbs #240).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c69b7971d4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

# Conflicts:
#	scripts/cdp-bridge/dist/runners/rn-android-runner-client.js
#	scripts/cdp-bridge/dist/runners/rn-fast-runner-client.js
#	scripts/cdp-bridge/src/runners/rn-android-runner-client.ts
#	scripts/cdp-bridge/src/runners/rn-fast-runner-client.ts
#	scripts/rn-android-runner/app/src/androidTest/java/dev/lykhoyda/rndevagent/androidrunner/CommandDispatcher.kt
#	scripts/rn-fast-runner/RnFastRunner/RnFastRunnerUITests/RnFastRunnerTests+CommandExecution.swift
#	scripts/rn-fast-runner/RnFastRunner/RnFastRunnerUITests/RnFastRunnerTests+Interaction.swift

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5187ad209a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread docs/stories/08-token-efficient-outputs.md
Comment thread docs/stories/02-runner-protocol-versioning.md

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 77443c95e5

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread docs/stories/06-native-runner-ci-and-evals.md
Comment thread docs/stories/11-failure-evidence-and-debt.md
@Lykhoyda Lykhoyda merged commit 2ef5ef9 into main Jul 2, 2026
11 checks passed
@Lykhoyda Lykhoyda deleted the limestone-malpais branch July 2, 2026 18:11
@Lykhoyda Lykhoyda restored the limestone-malpais branch July 2, 2026 18:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant