opencode-skills-collection 3.0.47 → 3.0.48

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
- "updatedAt": "2026-06-15T02:32:44.805Z",
3
+ "updatedAt": "2026-06-16T02:36:05.454Z",
4
4
  "entries": [
5
5
  "00-andruia-consultant",
6
6
  "007",
@@ -14,6 +14,7 @@
14
14
  "accesslint-audit",
15
15
  "accesslint-diff",
16
16
  "accesslint-scan",
17
+ "accint-solve",
17
18
  "active-directory-attacks",
18
19
  "activecampaign-automation",
19
20
  "ad-creative",
@@ -74,6 +75,7 @@
74
75
  "analytics-tracking",
75
76
  "analyze-project",
76
77
  "andrej-karpathy",
78
+ "android-cli",
77
79
  "android-dev",
78
80
  "android-jetpack-compose-expert",
79
81
  "android_ui_verification",
@@ -389,6 +391,7 @@
389
391
  "codebase-cleanup-refactor-clean",
390
392
  "codebase-cleanup-tech-debt",
391
393
  "codebase-to-wordpress-converter",
394
+ "codex-fable5",
392
395
  "codex-review",
393
396
  "cold-email",
394
397
  "comfyui-gateway",
@@ -533,6 +536,7 @@
533
536
  "e2e-testing-patterns",
534
537
  "earllm-build",
535
538
  "ecl-harness-engineer",
539
+ "efficient-web-research",
536
540
  "ejentum-reasoning-harness",
537
541
  "electron-development",
538
542
  "elixir-pro",
@@ -1270,6 +1274,7 @@
1270
1274
  "sexual-health-analyzer",
1271
1275
  "shadcn",
1272
1276
  "shader-programming-glsl",
1277
+ "sharp-coder",
1273
1278
  "sharp-edges",
1274
1279
  "shellcheck-configuration",
1275
1280
  "shodan-reconnaissance",
@@ -0,0 +1,205 @@
1
+ ---
2
+ name: accint-solve
3
+ description: "Route agent work through AccInt's MCP memory loop: retrieve prior outcomes, resolve frames, and close commitments with evidence."
4
+ category: ai-agents
5
+ risk: safe
6
+ source: community
7
+ source_repo: maxbaluev/accreted-intelligence
8
+ source_type: community
9
+ date_added: "2026-06-15"
10
+ author: maxbaluev
11
+ tags: [mcp, memory, ai-agents, coding-agents, workflow]
12
+ tools: [claude, codex, cursor, gemini, opencode]
13
+ license: "Apache-2.0"
14
+ license_source: "https://github.com/maxbaluev/accreted-intelligence/blob/main/LICENSE-APACHE-2.0.txt"
15
+ ---
16
+
17
+ # AccInt Solve
18
+
19
+ ## Overview
20
+
21
+ AccInt is a local-first MCP memory server for coding agents. It keeps a scored
22
+ record of retrieved experience, open commitments, continuation frames, and
23
+ outcome feedback so the next agent run can build on what actually worked.
24
+
25
+ Use this skill when AccInt is already configured in the host as an MCP server.
26
+ The skill adapts AccInt's public `solve` Claude skill into a host-agnostic
27
+ workflow for Claude Code, Codex CLI, Cursor, Gemini CLI, OpenCode, and other
28
+ agent runtimes that can call MCP tools.
29
+
30
+ ## When to Use This Skill
31
+
32
+ - Use when starting non-trivial coding-agent work where prior decisions,
33
+ debugging history, repo-specific habits, or maintainer feedback may matter.
34
+ - Use when a task may require multiple attempts and you want an explicit
35
+ commitment ID that can later receive a real outcome.
36
+ - Use when AccInt returns a continuation frame and the agent must reason locally
37
+ before submitting a proposal back to the memory loop.
38
+ - Use after verification, merge, deployment, maintainer response, or other
39
+ reality signal to close the commitment with an honest outcome.
40
+ - Do not use when the host has no AccInt MCP tools configured; first install or
41
+ configure AccInt, then rerun the workflow.
42
+
43
+ ## How It Works
44
+
45
+ ### Step 1: Confirm the AccInt MCP tools exist
46
+
47
+ Use the host's available MCP/tool list to confirm an AccInt server exposes the
48
+ two verbs:
49
+
50
+ ```text
51
+ acc_retrieve(query)
52
+ acc_act(runtime, input)
53
+ ```
54
+
55
+ If the host names the tools with a namespace prefix, use the equivalent
56
+ AccInt MCP verbs. If neither verb is available, stop and ask the user to
57
+ configure AccInt rather than inventing memory results.
58
+
59
+ ### Step 2: Retrieve before planning
60
+
61
+ Before a non-trivial step, retrieve relevant prior work:
62
+
63
+ ```json
64
+ {"query": "the concrete task or subtask you are about to perform"}
65
+ ```
66
+
67
+ Read the returned memories and cite the `[ids]` you actually build on. Treat
68
+ retrieved memories as evidence to consider, not as a substitute for inspecting
69
+ the current repository, running tests, or checking live external state.
70
+
71
+ ### Step 3: Route the goal through `solve`
72
+
73
+ Open an AccInt commitment for the concrete goal:
74
+
75
+ ```json
76
+ {"runtime": "solve", "input": "the concrete goal to accomplish"}
77
+ ```
78
+
79
+ If the response is final, use the answer, commitment ID, and cited memory IDs.
80
+ If the response is a `brain_frame`, keep the reasoning in the current session:
81
+ inspect the frame, resolve the missing judgment or knowledge from the workspace,
82
+ then submit a concise proposal through `continue`.
83
+
84
+ ### Step 4: Resolve continuation frames
85
+
86
+ For a returned frame, submit only the frame ID and your proposal text unless the
87
+ host explicitly manages tokens for you:
88
+
89
+ ```json
90
+ {
91
+ "runtime": "continue",
92
+ "input": {
93
+ "frame_id": "bf_...",
94
+ "proposal_text": "reasoned answer, plan, or decision grounded in the current evidence"
95
+ }
96
+ }
97
+ ```
98
+
99
+ Do not leave a received frame unresolved. If the frame expires, close or rerun
100
+ the bound commitment rather than pretending the continuation succeeded.
101
+
102
+ ### Step 5: Execute and verify outside AccInt
103
+
104
+ Do the actual work in the repository, browser, shell, issue tracker, or other
105
+ real environment. Verify with the strongest relevant evidence available: tests,
106
+ builds, linters, link checks, PR state, screenshots, maintainer replies, or
107
+ production telemetry.
108
+
109
+ AccInt stores the learning loop; it does not replace the work or the evidence.
110
+
111
+ ### Step 6: Close the commitment with an outcome
112
+
113
+ When reality answers, record the result:
114
+
115
+ ```json
116
+ {
117
+ "runtime": "outcome",
118
+ "input": {
119
+ "ref": "solved:...",
120
+ "good": true,
121
+ "note": "brief evidence: tests passed, PR merged, deploy succeeded, reviewer accepted, or exact failure reason"
122
+ }
123
+ }
124
+ ```
125
+
126
+ Use `good: false` when the approach failed. Do not tag an outcome as external
127
+ or owner-validated unless a real external system or the owner actually supplied
128
+ that verdict.
129
+
130
+ ## Examples
131
+
132
+ ### Example 1: Start a repository fix with memory
133
+
134
+ ```text
135
+ 1. acc_retrieve({"query":"fix failing parser tests in this repo"})
136
+ 2. Read the returned memories; cite only the relevant [ids].
137
+ 3. acc_act(runtime="solve", input="Fix the failing parser tests and verify them")
138
+ 4. Inspect the repo, edit files, run the parser tests.
139
+ 5. acc_act(runtime="outcome", input={"ref":"solved:...", "good":true, "note":"parser test command passed"})
140
+ ```
141
+
142
+ ### Example 2: Handle a continuation frame
143
+
144
+ ```text
145
+ AccInt returns frame bf_123 asking for a judgment about whether to patch the
146
+ schema or the caller.
147
+
148
+ 1. Inspect the schema and caller in the current repo.
149
+ 2. Decide from code evidence, not memory alone.
150
+ 3. acc_act(runtime="continue", input={"frame_id":"bf_123", "proposal_text":"Patch the caller because..."})
151
+ 4. Continue implementation and verification.
152
+ ```
153
+
154
+ ## Best Practices
155
+
156
+ - Cite retrieved `[ids]` whenever they shape your plan or answer.
157
+ - Keep owner-held facts owner-held: ask instead of fabricating preferences,
158
+ credentials, identity, or history the repository cannot prove.
159
+ - Use small, concrete solve goals; open a new solve for materially different
160
+ subproblems instead of overloading one commitment.
161
+ - Close commitments promptly when reality answers, including failures.
162
+ - Record evidence in outcome notes, not confidence.
163
+ - Preserve privacy: do not store secrets, raw credentials, or unnecessary
164
+ sensitive user data in outcome notes.
165
+
166
+ ## Limitations
167
+
168
+ - Requires an installed and configured AccInt MCP server exposing
169
+ `acc_retrieve` and `acc_act`.
170
+ - Does not replace repository inspection, tests, review, or live-state checks.
171
+ - Retrieved memory can be stale or wrong; current evidence wins.
172
+ - Outcome credit is only as strong as the evidence tier. Self-graded outcomes
173
+ are weaker than runtime, external, or owner-validated outcomes.
174
+ - AccInt is local-first; a different machine or database may not have the same
175
+ memories unless the user intentionally shares the AccInt database.
176
+
177
+ ## Security & Safety Notes
178
+
179
+ - This skill does not require shell commands, network fetches, or credentials.
180
+ - AccInt MCP calls can write to the configured local AccInt database by opening
181
+ commitments, continuations, and outcomes. Treat those writes as project
182
+ memory, and avoid recording sensitive data that does not need to persist.
183
+ - If a task involves production systems, payments, private accounts, legal or
184
+ medical facts, or secrets, get the required authorization and verify against
185
+ the appropriate external source before recording an outcome.
186
+
187
+ ## Common Pitfalls
188
+
189
+ - **Problem:** Using retrieved memory as if it were guaranteed current.
190
+ **Solution:** Use it to guide investigation, then verify in the current
191
+ workspace or live system.
192
+ - **Problem:** Leaving a `brain_frame` open because implementation work started.
193
+ **Solution:** Submit a `continue` proposal first, or close/rerun the bound
194
+ commitment if the frame expires.
195
+ - **Problem:** Marking an outcome good before tests, checks, or external state
196
+ prove it.
197
+ **Solution:** Wait for real evidence, then record the outcome with the exact
198
+ command, PR state, deploy state, or reviewer signal.
199
+
200
+ ## Related Skills
201
+
202
+ - `@agent-memory-mcp` - Use when you need a broader overview of MCP-backed
203
+ agent memory systems.
204
+ - `@verification-before-completion` - Use before claiming work is complete.
205
+ - `@lint-and-validate` - Use to select and run repository validation commands.
@@ -0,0 +1,239 @@
1
+ ---
2
+ name: android-cli
3
+ description: Orchestrates Android development tasks including project creation, deployment, SDK management, and environment diagnostics using the `android` command-line tool.
4
+ category: tools
5
+ risk: safe
6
+ source: self
7
+ source_type: self
8
+ date_added: "2026-06-15"
9
+ author: Owais
10
+ tags: [android, cli, adb, mobile, build, emulator]
11
+ tools: [claude, cursor, gemini, antigravity]
12
+ ---
13
+
14
+ <!-- security-allowlist: curl-pipe-bash -->
15
+
16
+ # Android CLI Specialist
17
+
18
+ This skill provides instructions for using the `android` CLI tool. The tool includes various commands for creating projects, running applications, interacting with devices, and managing the CLI environment.
19
+
20
+ ## When to Use
21
+
22
+ - Use when you need to create, configure, or analyze Android projects from the command line.
23
+ - Use when interacting with, deploying to, or taking screenshots of running Android devices.
24
+ - Use when managing Android SDK components, versions, or virtual devices (emulators).
25
+ - Use when inspecting UI layouts or running XML-specified journey tests.
26
+
27
+ ## Installation
28
+
29
+ If the `android` tool is not in the path, install it. To install, run the following command:
30
+
31
+ - **Linux:** `curl -fsSL https://dl.google.com/android/cli/latest/linux_x86_64/install.sh | bash`
32
+ - **macOS:** `curl -fsSL https://dl.google.com/android/cli/latest/darwin_arm64/install.sh | bash`
33
+ - **Windows:** `curl.exe -fsSL https://dl.google.com/android/cli/latest/windows_x86_64/install.cmd -o "%TEMP%\i.cmd" && "%TEMP%\i.cmd"`
34
+
35
+ ## SDK Management
36
+
37
+ To manage the installation of Android SDKs and tools, use the `sdk` command. For example:
38
+
39
+ - `android sdk install <package>[@<version>]...`: Install specific packages. Multiple packages can be specified, separated by spaces. `<version>` defaults to latest. For example: `android sdk install platforms/android-30@2 platforms/android-34`
40
+ - `android sdk update [<pkg-name>]`: Update a specific package or all packages to the latest version.
41
+ - `android sdk remove <pkg-name>`: Remove a package from the local SDK.
42
+ - `android sdk list --all`: List installed and available SDK packages.
43
+
44
+ ## Project Creation
45
+
46
+ Create projects from templates using the `create` command.
47
+
48
+ For example:
49
+ ```bash
50
+ android create empty-activity --name="My App" --output=./my-app
51
+ ```
52
+
53
+ ## Interacting with Devices
54
+
55
+ For more information on interacting with running devices, see [here](references/interact.md).
56
+
57
+ ## Running Journey Tests
58
+
59
+ For more information on running journeys, see [here](references/journeys.md).
60
+
61
+ ## Doc Searching
62
+
63
+ The `docs` command searches authoritative, high-quality Android developer documentation in the Android Knowledge Base.
64
+ By providing a few keywords, this tool will return high quality articles that contain examples or guidance on how to use Android APIs or libraries.
65
+ Use this tool to obtain additional information on how to achieve Android-specific tasks or to know more about Android APIs, surfaces, libraries, or devices.
66
+
67
+ Always use this tool to get the most up-to-date information about Android concepts. Typical good use cases are:
68
+ - Finding migration guides for APIs.
69
+ - Finding examples for APIs.
70
+ - Finding up-to-date information about Android APIs.
71
+ - Finding best practices for Android concepts.
72
+
73
+ ## Running APKs
74
+
75
+ Use the `run` command to run Android apps.
76
+
77
+ ## Managing Emulators
78
+
79
+ Manage Android Virtual Devices (AVDs) using the `android emulator` command.
80
+
81
+ ## Capturing Screenshots
82
+
83
+ Capture an image of the current screen of a connected Android device and output it to a file using the `android screen capture -o <file path>` command.
84
+
85
+ ## Managing Skills
86
+
87
+ Manage antigravity agent skills for Android using the `android skills` command.
88
+
89
+ ## Inspecting UI Layouts
90
+
91
+ Use the `android layout` command to inspect the UI layout of an Android application. It returns the layout tree of an Android application in JSON format. When debugging UI errors, this is often a much faster approach than taking a screenshot.
92
+
93
+ ## Updating the CLI
94
+
95
+ Update the Android CLI using the `android update` command.
96
+
97
+ ## Limitations
98
+
99
+ - The `android` CLI must be installed and available on `PATH`; otherwise install it first or use the platform-specific setup guidance above.
100
+ - Device, emulator, SDK, and documentation commands can depend on local Android SDK state, network access, and attached hardware.
101
+ - Treat generated commands as environment-sensitive: inspect paths, package names, device serials, and install/update targets before running them.
102
+
103
+ ## Android Help Output
104
+
105
+ ```text
106
+ Usage: android [-hV] [--sdk=PARAM] [COMMAND]
107
+ -h, --help Show this help message and exit.
108
+ --sdk=PARAM Path to the Android SDK
109
+ -V, --version Print version information and exit.
110
+ Commands:
111
+ create Create a new Android project
112
+ describe Analyzes an Android project to generate descriptive metadata.
113
+ docs Android documentation commands
114
+ emulator Emulator commands
115
+ help Shows the help of all commands
116
+ info Print environment information (SDK Location, etc.)
117
+ init Initializes the environment (eg. skills) for Android CLI.
118
+ layout Returns the layout tree of an application
119
+ run Deploy an Android Application
120
+ screen Commands to view the device
121
+ sdk Download and list SDK packages
122
+ skills Manage skills
123
+ update Update the Android CLI
124
+
125
+ create
126
+ Usage: android create [-h] [--verbose] [--list] [--minSdk=api]
127
+ --name=applicationName [-o=dest-path] [template-name]
128
+ Create a new Android project
129
+ [template-name] The template name
130
+ -h, --help Show this help message and exit.
131
+ --minSdk=api The 'minSdk' supported by the application (default
132
+ is defined in the template)
133
+ --name=applicationName
134
+ The name of the application (e.g. 'My Application')
135
+ -o, --output=dest-path The destination project directory path (default is
136
+ '.')
137
+ --verbose Enables verbose output
138
+ --list List all available templates
139
+
140
+ describe
141
+ Usage: android describe [-hV] [--project_dir=PARAM]
142
+ Analyzes an Android project to generate descriptive metadata.
143
+ This command identifies and outputs the paths to JSON files that detail the
144
+ project's structure, including build targets and their corresponding output
145
+ artifact locations (e.g., APKs). This information enables other tools and
146
+ commands to locate build artifacts efficiently.
147
+ -h, --help Show this help message and exit.
148
+ --project_dir=PARAM The project directory to describe
149
+ -V, --version Print version information and exit.
150
+
151
+ docs
152
+ Usage: android docs [-h] [COMMAND]
153
+ Android documentation commands
154
+ -h, --help Show this help message and exit.
155
+ Commands:
156
+ search Search Android documentation
157
+ fetch Fetch Android documentation
158
+
159
+ emulator
160
+ Usage: android emulator [-h] [COMMAND]
161
+ Emulator commands
162
+ -h, --help Show this help message and exit.
163
+ Commands:
164
+ create Creates a virtual device
165
+ start Launches the specified virtual device. This command will return when
166
+ the emulator is fully started and ready to use.
167
+ stop Stops the specified virtual device
168
+ list Lists available virtual devices
169
+ remove Delete a virtual device
170
+
171
+ help
172
+ Usage: android help [COMMAND]
173
+ Shows the help of all commands
174
+ [COMMAND] The command to show help for
175
+
176
+ info
177
+ Usage: android info <field>
178
+ Print environment information (SDK Location, etc.)
179
+ <field> The specific field to print the value of. If omitted print all.
180
+
181
+ init
182
+ Usage: android init
183
+ Initializes the environment (eg. skills) for Android CLI.
184
+
185
+ layout
186
+ Usage: android layout [-dhp] [--device=PARAM] [-o=PARAM]
187
+ Returns the layout tree of an application
188
+ -d, --diff Returns a flat list of the layout elements that have
189
+ changed since the last invocation of ui-dump
190
+ --device=PARAM The device serial number
191
+ -h, --help Show this help message and exit.
192
+ -o, --output=PARAM Writes the layout tree to the specified file or
193
+ directory. If omitted, prints the tree to standard
194
+ output
195
+ -p, --pretty Pretty-prints the returned JSON
196
+
197
+ run
198
+ Usage: android run [-h] [--debug] [--activity=PARAM] [--device=PARAM]
199
+ [--type=PARAM] [--apks=PARAM[,PARAM...]]...
200
+ Deploy an Android Application
201
+ --activity=PARAM The activity name
202
+ --apks=PARAM[,PARAM...]
203
+ The paths to the APKs
204
+ --debug Run in debug mode
205
+ --device=PARAM The device serial number
206
+ -h, --help Show this help message and exit.
207
+ --type=PARAM The component type (ACTIVITY, SERVICE, etc.)
208
+
209
+ screen
210
+ Usage: android screen [-h] [COMMAND]
211
+ Commands to view the device
212
+ -h, --help Show this help message and exit.
213
+ Commands:
214
+ capture Outputs the device screen to a PNG
215
+ resolve Target UI elements visually
216
+
217
+ sdk
218
+ Usage: android sdk [COMMAND]
219
+ Download and list SDK packages
220
+ Commands:
221
+ install Install SDK packages
222
+ update Update one or all packages to the latest version
223
+ remove Remove a package from the SDK
224
+ list List installed and available SDK packages
225
+
226
+ skills
227
+ Usage: android skills [COMMAND]
228
+ Manage skills
229
+ Commands:
230
+ add Install a skill
231
+ remove Remove a skill
232
+ list List available skills
233
+ find Find skills by keyword
234
+
235
+ update
236
+ Usage: android update [--url=PARAM]
237
+ Update the Android CLI
238
+ --url=PARAM The URL to download the update from
239
+ ```
@@ -0,0 +1,83 @@
1
+ # Tools
2
+ Run `android layout --help` and `android screen --help`.
3
+
4
+ ## UI Dump
5
+ `android layout` returns a flat JSON list of the UI elements on screen.
6
+ `android layout --diff` returns a flat JSON list of the UI elements that have changed since the last call to `layout` or `layout --diff`
7
+
8
+ Each JSON object represents a UI element in the Android app. The following properties may be present:
9
+ - `text` - any literal text the element contains
10
+ - `resourceId` - the Android resource id used to refer to the element
11
+ - `contentDesc` - a description of a UI element for use by accessibility tools
12
+ - `interactions` - the set of user interactions the element supports. May contain one or more of: `checkable`, `clickable`, `focusable`, `scrollable`, `long-clickable`, `password`
13
+ - `state` - the set of states the element is in. May contain one or more of `checked`, `focused`, `selected`
14
+ - `bounds` - the screen coordinates of the bounding rectangle of the element, in the format `[min X,min Y][max X, max Y]`
15
+ - `center` - the screen coordinates of the center of the element, in the format `[x,y]`
16
+ - `off-screen` - if true, the element is in the UI hierarchy but not visible; it may require scrolling to view.
17
+
18
+ Use `layout` as a primary means of examining an Android app. Use `layout --diff` to focus on changes and to keep your context small.
19
+ Example: When entering digits into a calculator, use `layout --diff` to output only the digit readout element.
20
+
21
+ `layout` may fail due to the app displaying a WebView or animation; in these cases, use `android screen --annotate` to inspect the app.
22
+ This failure will likely resolve after navigating away from the current screen.
23
+
24
+ ## Screenshot
25
+ `android screen capture -o <file path>` saves a PNG of the current device screen to `<file path>`
26
+
27
+ Use `screen capture` as a secondary means of examining an Android app
28
+ Examples:
29
+ - Understanding the content of an on-screen image
30
+ - Looking at a `WebView` (web content does not always appear in the ui dump)
31
+ - Trying to find a UI element by its visual appearance
32
+
33
+ **IMPORTANT**: Always *VISUALLY* examine the PNG image returned from `android screen` BEFORE doing anything else.
34
+
35
+ ## Annotated Screenshot
36
+ `android screen capture --annotate -o <file path>`
37
+ `android screen resolve --screen <path> --string <string>`
38
+
39
+ The `--annotate` command adds numerical labels and bounding boxes around UI elements. Use this command to locate UI elements that cannot
40
+ be located in the `layout` output.
41
+
42
+ **IMPORTANT**: When using `android –-annotate`, always *VISUALLY* examine the resulting PNG file.
43
+
44
+ To refer to these labels in input commands, use `screen resolve` to convert labels into coordinates:
45
+
46
+ `android screen resolve --screen <file path> --string "#3"` returns `<x coord of region 3> <y coord of region 3>`
47
+
48
+ To save turns, you can combine shell commands:
49
+
50
+ `adb shell input $(android screen resolve --screen screen.png --string "tap #34")`
51
+
52
+ This command taps on region #34 from `screen.png`
53
+
54
+ ## Input
55
+ Use `adb shell input` for interacting with Android devices.
56
+ Refer to the `"interactions"` property of an element for what interactions can be performed on a particular element.
57
+
58
+ Interact with UI elements with their `center` coordinate or their `bounds` coordinates:
59
+ ```json
60
+ {
61
+ "key": -248568265,
62
+ "class": "android.widget.Button",
63
+ "bounds": "[138,9][167,38]",
64
+ "center": "[152,23]"
65
+ }
66
+ ```
67
+ To tap on this button, you would execute `adb shell input tap 152 23`. This taps the center.
68
+
69
+ ```json
70
+ {
71
+ "key": 12487234,
72
+ "class": "com.example.ui.ScrollableList",
73
+ "bounds": "[100,200][400,600]",
74
+ "center": "[250,400]"
75
+ }
76
+ ```
77
+ To scroll down on this list, you would execute `adb shell input swipe 250 400 250 200 500`. This swipes from the center to the top over 500ms.
78
+
79
+ # Android Interaction Rules
80
+ 1. Always ensure text input fields have `"focused"` in their `"state"` list before entering text
81
+ 2. If an element has `"scrollable"` in its `"interactions"` list, try scrolling it when looking for missing UI elements
82
+ 3. Always scroll slowly when executing scroll inputs. In `adb shell input swipe <x1> <y1> <x2> <y2> [duration(ms)]`, the duration is the optional 5th parameter after `swipe` (the 6th argument to the `input` utility).
83
+ 4. Content may take time to load; if a `layout` is missing information after you take an action, wait a few seconds, then perform `layout --diff` to see if anything changes.
@@ -0,0 +1,105 @@
1
+ A journey is an XML-specified test of an Android app's behavior. It consists of a list of `<action>` elements. For example:
2
+ ```xml
3
+ <journey name="My Journey">
4
+ <description>
5
+ A sample journey to illustrate the format
6
+ </description>
7
+ <actions>
8
+ <action>
9
+ Tap the "Home" icon
10
+ </action>
11
+ <action>
12
+ Verify that the app is on its Home screen
13
+ </action>
14
+ </actions>
15
+ </journey>
16
+ ```
17
+
18
+ Evaluate a journey by proceeding through the `<actions>` list in sequential order. Evaluate each `<action>` block individually.
19
+ A journey succeeds if all elements in the `<actions>` list succeed.
20
+
21
+ A journey is a test case for an app. The journey XML is the source of truth; if the app disagrees with the journey, the app has failed.
22
+ Additionally, if the app exits, crashes, or freezes, journey evaluation stops and the journey fails.
23
+
24
+ **IMPORTANT** - Execute each step EXACTLY as written, and independently of other steps! If an action says to `"tap the first search result"`,
25
+ you MUST find the search results and tap the first one. Do this even if you believe you know the intent behind the action.
26
+
27
+ ## Taking Actions
28
+ Some `<action>` elements specify UI interactions to perform on the running Android app. Perform the interaction and verify that the app does
29
+ not crash or behave in an unexpected manner. This is the *only* verification you should perform for an `<action>`.
30
+
31
+ If the interaction cannot be performed as specified, the journey fails.
32
+ Example:
33
+ ```xml
34
+ <action>Click the red button</action>
35
+ ```
36
+ If you determine a red button is not present in the UI, the journey fails.
37
+
38
+ If the text of an `<action>` specifies a list of actions, break it into sub-actions and evaluate them individually:
39
+ Example:
40
+ ```xml
41
+ <action>Search for soda and add the first result to the cart</action>
42
+ ```
43
+ This should be evaluated as:
44
+ ```xml
45
+ <action>Search for soda</action>
46
+ <action>Add the first result to the cart</action>
47
+ ```
48
+
49
+ If an `<action>` contains something that is not a specification for a UI interaction, alert the user that the journey is malformed and exit
50
+ early, specifying the error in question.
51
+
52
+ ## Verifying Expectations
53
+ `<action>` elements that begin with "check" or "verify" specify expectations for the current state of the Android app. Determine the current
54
+ state of the app and check if the expectations are met.
55
+
56
+ Determine the current state of the app by inspecting the current screen of the device without interacting with it.
57
+ Example:
58
+ ```xml
59
+ <action>Check if "Switch 2" is visible on the screen</action>
60
+ ```
61
+ This requires only inspecting the current screen, not scrolling or interacting. If "Switch 2" is not currently visible, the action fails.
62
+
63
+ If the expectations are not met, mark the `<action>` as a failure and the journey evaluation ends. A single `<action>` may contain
64
+ multiple expectations.
65
+ Example:
66
+ ```xml
67
+ <action>Verify that the app is on the Home screen, the Home icon is blue, and the temperature is displayed</action>
68
+ ```
69
+ This `<action>` fails if ANY of the following are false:
70
+ - The app is on the Home screen
71
+ - There is a Home icon, and it is blue
72
+ - A temperature is displayed
73
+
74
+ ## Handling Failure
75
+ When running a journey, evaluate it as a test. Failure is acceptable, and often expected. Proper reporting of failures is the priority.
76
+
77
+ Keep debugging and troubleshooting to a minimum; assume that tools are showing you the correct output every time. The goal is to determine
78
+ if the *current* Android app can correctly handle the *current* steps outlined in the journey. Suggestions for bug fixes, clarification, or
79
+ other improvements should be kept to journey evaluation summary at the end.
80
+
81
+ ## Summarizing
82
+ For each `<action>` you evaluated, output JSON describing the results.
83
+
84
+ ```json
85
+ {
86
+ "journey": "The name of the journey",
87
+ "results": [
88
+ {
89
+ // A string containing the full text of the <action>
90
+ "action": "Click the blue button",
91
+ // "PASSED" if the instruction was evaluated, "FAILED" if the instruction could not be evaluated, or "SKIPPED" if journey evaluation ended early because an instruction failed
92
+ "status": "PASSED",
93
+ // A list of the ADB commands executed while evaluating the instruction
94
+ "commands": [ "adb input swipe 490 200 500 500 500", "adb input tap 45 920" ],
95
+ // Failure reasons, feedback, or other useful information
96
+ "comment": "The journey step doesn't specify that the button requires scrolling to see"
97
+ },
98
+ {
99
+ "action": "The home screen is shown",
100
+ "status": "FAILED",
101
+ "comment": "The settings page was shown"
102
+ }
103
+ ]
104
+ }
105
+ ```