Skip to content

Commit 7081be0

Browse files
thymikeethymikee
committed
feat: add agent-device dogfood skill package
1 parent 8123117 commit 7081be0

6 files changed

Lines changed: 321 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@ npx agent-device open SampleApp
3535
```
3636

3737
The skill is also accessible on [ClawHub](https://clawhub.ai/okwasniewski/agent-device).
38+
For structured exploratory QA workflows, use the dogfood skill at [skills/dogfood/SKILL.md](skills/dogfood/SKILL.md).
3839

3940
## Quick Start
4041

‎skills/agent-device/SKILL.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ description: Automates interactions for iOS simulators/devices and Android emula
66
# Mobile Automation with agent-device
77

88
For exploration, use snapshot refs. For deterministic replay, use selectors.
9+
For structured exploratory QA bug hunts and reporting, use [../dogfood/SKILL.md](../dogfood/SKILL.md).
910

1011
## Start Here (Read This First)
1112

‎skills/dogfood/SKILL.md‎

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
---
2+
name: dogfood
3+
description: Systematically explore and test a mobile app on iOS/Android with agent-device to find bugs, UX issues, and other problems. Use when asked to "dogfood", "QA", "exploratory test", "find issues", "bug hunt", or "test this app" on mobile. Produces a structured report with reproducible evidence: screenshots, optional repro videos, and detailed steps for every issue.
4+
allowed-tools: Bash(agent-device:*), Bash(npx agent-device:*)
5+
---
6+
7+
# Dogfood (agent-device)
8+
9+
Systematically explore a mobile app, find issues, and produce a report with full reproduction evidence for every finding.
10+
11+
## Setup
12+
13+
Only the **Target app** is required. Everything else has sensible defaults.
14+
15+
| Parameter | Default | Example override |
16+
|-----------|---------|-----------------|
17+
| **Target app** | _(required)_ | `Settings`, `com.example.app`, deep link URL |
18+
| **Platform** | Infer from user context; otherwise ask (`ios` or `android`) | `--platform ios` |
19+
| **Session name** | Slugified app/platform (for example `settings-ios`) | `--session my-session` |
20+
| **Output directory** | `./dogfood-output/` | `Output directory: /tmp/mobile-qa` |
21+
| **Scope** | Full app | `Focus on onboarding and profile` |
22+
| **Authentication** | None | `Sign in to user@example.com` |
23+
24+
If the user gives enough context to start, begin immediately with defaults. Ask follow-up only when a required detail is missing (for example platform or credentials).
25+
26+
Prefer direct `agent-device` binary when available.
27+
28+
## Workflow
29+
30+
```
31+
1. Initialize Set up session, output dirs, report file
32+
2. Launch/Auth Open app and sign in if needed
33+
3. Orient Capture initial snapshot and map navigation
34+
4. Explore Systematically test flows and states
35+
5. Document Record reproducible evidence per issue
36+
6. Wrap up Reconcile summary, close session
37+
```
38+
39+
### 1. Initialize
40+
41+
```bash
42+
mkdir -p {OUTPUT_DIR}/screenshots {OUTPUT_DIR}/videos
43+
cp {SKILL_DIR}/templates/dogfood-report-template.md {OUTPUT_DIR}/report.md
44+
```
45+
46+
### 2. Launch/Auth
47+
48+
Start a named session and launch target app:
49+
50+
```bash
51+
agent-device --session {SESSION} open {TARGET_APP} --platform {PLATFORM}
52+
agent-device --session {SESSION} snapshot -i
53+
```
54+
55+
If login is required:
56+
57+
```bash
58+
agent-device --session {SESSION} snapshot -i
59+
agent-device --session {SESSION} fill @e1 "{EMAIL}"
60+
agent-device --session {SESSION} fill @e2 "{PASSWORD}"
61+
agent-device --session {SESSION} press @e3
62+
agent-device --session {SESSION} wait 1000
63+
agent-device --session {SESSION} snapshot -i
64+
```
65+
66+
For OTP/email codes: ask the user, wait for input, then continue.
67+
68+
### 3. Orient
69+
70+
Capture initial evidence and navigation anchors:
71+
72+
```bash
73+
agent-device --session {SESSION} screenshot {OUTPUT_DIR}/screenshots/initial.png
74+
agent-device --session {SESSION} snapshot -i
75+
```
76+
77+
Map top-level navigation, tabs, and key workflows before deep testing.
78+
79+
### 4. Explore
80+
81+
Read [references/issue-taxonomy.md](references/issue-taxonomy.md) for severity/category calibration.
82+
83+
Strategy:
84+
85+
- Move through each major app area (tabs, drawers, settings pages).
86+
- Test core journeys end-to-end (create, edit, delete, submit, recover).
87+
- Validate edge states (empty/error/loading/offline/permissions denied).
88+
- Use `snapshot -i` after UI transitions to avoid stale refs.
89+
- Periodically capture `logs path` and inspect the app log when behavior looks suspicious.
90+
91+
Useful commands per screen:
92+
93+
```bash
94+
agent-device --session {SESSION} snapshot -i
95+
agent-device --session {SESSION} screenshot {OUTPUT_DIR}/screenshots/{screen-name}.png
96+
agent-device --session {SESSION} appstate
97+
agent-device --session {SESSION} logs path
98+
```
99+
100+
### 5. Document Issues (Repro-First)
101+
102+
Explore and document in one pass. When you find an issue, stop and fully capture evidence before continuing.
103+
104+
#### Interactive/behavioral issues
105+
106+
Use video + step screenshots:
107+
108+
1. Start recording:
109+
110+
```bash
111+
agent-device --session {SESSION} record start {OUTPUT_DIR}/videos/issue-{NNN}-repro.mp4
112+
```
113+
114+
2. Reproduce with visible pacing. Capture each step:
115+
116+
```bash
117+
agent-device --session {SESSION} screenshot {OUTPUT_DIR}/screenshots/issue-{NNN}-step-1.png
118+
sleep 1
119+
# perform action
120+
sleep 1
121+
agent-device --session {SESSION} screenshot {OUTPUT_DIR}/screenshots/issue-{NNN}-step-2.png
122+
```
123+
124+
3. Capture final broken state:
125+
126+
```bash
127+
sleep 2
128+
agent-device --session {SESSION} screenshot {OUTPUT_DIR}/screenshots/issue-{NNN}-result.png
129+
```
130+
131+
4. Stop recording:
132+
133+
```bash
134+
agent-device --session {SESSION} record stop
135+
```
136+
137+
5. Append issue immediately to report with numbered steps and screenshot references.
138+
139+
#### Static/on-load issues
140+
141+
Single screenshot is sufficient; no video required:
142+
143+
```bash
144+
agent-device --session {SESSION} screenshot {OUTPUT_DIR}/screenshots/issue-{NNN}.png
145+
```
146+
147+
Set **Repro Video** to `N/A` in the report.
148+
149+
### 6. Wrap Up
150+
151+
Target 5-10 well-evidenced issues, then finish:
152+
153+
1. Reconcile summary severity counts in `report.md`.
154+
2. Close session:
155+
156+
```bash
157+
agent-device --session {SESSION} close
158+
```
159+
160+
3. Report total issues, severity breakdown, and highest-risk findings.
161+
162+
## Guidance
163+
164+
- Repro quality matters more than issue count.
165+
- Use refs (`@eN`) for fast exploration, selectors for deterministic replay assertions when needed.
166+
- Re-snapshot after any mutation (navigation, modal, list update, form submit).
167+
- Use `fill` for clear-then-type semantics; use `type` for incremental typing behavior checks.
168+
- Keep logs optional and targeted: enable/read app logs only when useful for diagnosis.
169+
- Never read source code of the app under test; findings must come from observed runtime behavior.
170+
- Write each issue immediately to avoid losing evidence.
171+
- Never delete screenshots/videos/report artifacts during a session.
172+
173+
## References
174+
175+
| Reference | When to Read |
176+
|-----------|--------------|
177+
| [references/issue-taxonomy.md](references/issue-taxonomy.md) | Start of session; severity/categories/checklist |
178+
179+
## Templates
180+
181+
| Template | Purpose |
182+
|----------|---------|
183+
| [templates/dogfood-report-template.md](templates/dogfood-report-template.md) | Copy into output directory as the report file |

‎skills/dogfood/references/issue-taxonomy.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# Issue Taxonomy (Mobile)
2+
3+
Reference for categorizing issues found during mobile dogfooding.
4+
5+
## Severity Levels
6+
7+
| Severity | Definition |
8+
|----------|------------|
9+
| **critical** | Blocks a core workflow, causes data loss, or crashes/freeze loops the app |
10+
| **high** | Major feature broken or unusable, no practical workaround |
11+
| **medium** | Feature works with notable friction or partial failure; workaround exists |
12+
| **low** | Minor cosmetic or polish issue |
13+
14+
## Categories
15+
16+
### Visual / UI
17+
18+
- Layout broken, clipped, overlapped, or unreadable text
19+
- Safe-area/notch overlap issues
20+
- Incorrect dark/light appearance rendering
21+
- Missing assets/icons
22+
- Animation glitches or flicker
23+
24+
### Functional
25+
26+
- Buttons/controls do nothing or trigger wrong action
27+
- Flows fail (create/edit/delete/submit)
28+
- Navigation dead-ends or wrong destination
29+
- State loss after background/foreground transitions
30+
- Deep link opens wrong screen or fails
31+
32+
### UX
33+
34+
- Confusing hierarchy or navigation labels
35+
- Missing loading/progress feedback
36+
- Unclear error handling or no recovery affordance
37+
- Excessive steps for common tasks
38+
- Inconsistent behavior between similar screens
39+
40+
### Content
41+
42+
- Typos, incorrect copy, placeholder text
43+
- Wrong labels/help text
44+
- Truncated text with no affordance
45+
- Inconsistent terminology across screens
46+
47+
### Performance
48+
49+
- Slow startup or route transitions
50+
- Input lag or gesture jank
51+
- Scroll hitches/frame drops
52+
- Notable battery/thermal symptoms during basic usage
53+
54+
### Diagnostics / Logs
55+
56+
- Native crashes or repeated fatal exceptions
57+
- Repeated warnings correlated with broken behavior
58+
- Unhandled runtime errors visible during repro
59+
60+
### Permissions / Platform
61+
62+
- Permission prompt flow broken or loops forever
63+
- Denied permissions not handled gracefully
64+
- Platform-specific regressions (iOS-only or Android-only)
65+
- Background/foreground lifecycle regressions
66+
67+
### Accessibility
68+
69+
- Missing labels or incorrect accessibility names
70+
- Focus order/navigation issues for assistive tech
71+
- Low contrast or unreadable text scaling
72+
- Touch targets too small for reliable interaction
73+
74+
## Exploration Checklist
75+
76+
1. Visual scan: capture screenshot; verify layout/safe areas/text/icon rendering.
77+
2. Interactions: press controls, open menus/modals, validate expected response.
78+
3. Forms/input: test valid/invalid/empty/boundary input.
79+
4. Navigation: traverse all top-level sections and return paths.
80+
5. App states: loading/empty/error/offline/permission-denied/background-resume.
81+
6. Logs/diagnostics: inspect app logs when behavior is suspicious.
82+
7. Platform parity: verify critical flows on each requested platform.
83+
8. Accessibility basics: labels, touch target sizes, readability/contrast.

‎skills/dogfood/templates/dogfood-report-template.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Dogfood Report: {APP_NAME}
2+
3+
| Field | Value |
4+
|-------|-------|
5+
| **Date** | {DATE} |
6+
| **Platform** | {PLATFORM} |
7+
| **Target App** | {TARGET_APP} |
8+
| **Session** | {SESSION_NAME} |
9+
| **Scope** | {SCOPE} |
10+
11+
## Summary
12+
13+
| Severity | Count |
14+
|----------|-------|
15+
| Critical | 0 |
16+
| High | 0 |
17+
| Medium | 0 |
18+
| Low | 0 |
19+
| **Total** | **0** |
20+
21+
## Issues
22+
23+
<!-- Copy this block for each issue found. Interactive issues need video + step screenshots. Static issues can be screenshot-only (Repro Video = N/A). -->
24+
25+
### ISSUE-001: {Short title}
26+
27+
| Field | Value |
28+
|-------|-------|
29+
| **Severity** | critical / high / medium / low |
30+
| **Category** | visual / functional / ux / content / performance / diagnostics / permissions / accessibility |
31+
| **Screen / Route** | {screen where issue was found} |
32+
| **Repro Video** | {path to video, or N/A for static issues} |
33+
34+
**Description**
35+
36+
{What is wrong, what was expected, and what actually happened.}
37+
38+
**Repro Steps**
39+
40+
1. Open {screen/entry point}
41+
![Step 1](screenshots/issue-001-step-1.png)
42+
43+
2. {Action}
44+
![Step 2](screenshots/issue-001-step-2.png)
45+
46+
3. {Action}
47+
![Step 3](screenshots/issue-001-step-3.png)
48+
49+
4. **Observe:** {broken behavior}
50+
![Result](screenshots/issue-001-result.png)
51+
52+
---

‎website/docs/docs/introduction.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ title: Introduction
1111
- Session-aware workflows and replay
1212

1313
If you know `agent-browser`, this is the mobile-native counterpart for iOS/Android UI automation.
14+
For exploratory QA and bug-hunting workflows, see `skills/dogfood/SKILL.md` in this repository.
1415

1516
## What it’s good at
1617

0 commit comments

Comments
 (0)