Aso audit

ASO Audit — Full Listing Analysis

Comprehensive app listing audit that spawns 7 core specialist agents in parallel, adds localization when relevant, and finishes with a compliance gate.

Modes

Mode	Trigger	Data Source
Local	/aso audit (no args)	Fastlane metadata, Xcode project, Gradle project
Remote	/aso audit <app-id>	Live App Store / Google Play listing
Compare	/aso audit --compare <app-id>	Both local + remote, shows diff

Process

Step 1: Get Metadata (sequential)

If no app ID provided (local mode):

uv run python scripts/detect_project.py --json

This scans the working directory for Fastlane metadata (fastlane/metadata/), Xcode project (.xcodeproj), or Gradle project (app/build.gradle). If Fastlane metadata is found, all store fields are available. If only Xcode/Gradle is found, extract the app/bundle ID and offer to fetch the live listing.

If app ID provided (remote mode):

uv run python scripts/fetch_listing.py <app-id> --country us --json

For Android, also pipe through parse_listing.py.

If --compare flag (compare mode): Run both detect_project.py AND fetch_listing.py, then diff the results.

Step 2: Platform & Category Detection (sequential)

• Detect iOS vs Android from project type or app ID format
• Classify category from listing metadata (Gaming, SaaS, Health, E-commerce, Social, Fintech, Other)
• Load category-specific benchmarks

Step 3: Parallel Subagent Dispatch

IMPORTANT: Run ALL agents in FOREGROUND (not background). Launch them all in a single message with multiple Agent tool calls so they run in parallel, but do NOT use run_in_background. This ensures you have all results before proceeding to Step 4. Do NOT output anything to the user between launching agents and presenting the final report.

Spawn ALL of these agents simultaneously using the Agent tool:

Agent	Input	Focus
aso-keywords	listing JSON	Keyword coverage in title, subtitle/short desc, keywords field, description
aso-metadata	listing JSON	Field quality, character limits, utilization, keyword placement
aso-visuals	listing JSON	Screenshot count, narrative flow, icon, preview video
aso-reviews	listing JSON	Rating, sentiment distribution, themes, response rate
aso-competitors	listing JSON + category	Top 5 competitors, keyword gaps, metadata comparison
aso-technical	listing JSON	App size, update recency, stability, category fit
aso-conversion	listing JSON	First-impression elements, screenshot narrative, CRO

Conditional agents (spawn if relevant): | aso-localization | listing JSON | If app supports >1 locale |

Each agent returns: { score: 0-100, findings: [...], recommendations: [...] }

Step 4: Score Aggregation (sequential)

Step 3.5: Compliance Validation (sequential — runs AFTER all agents return)

Once all parallel agents have returned, run the aso-compliance agent. Pass it:

1. The original listing metadata
2. ALL recommendations from the other agents (title rewrites, keyword suggestions, description changes)

The compliance agent validates everything against references/store-policies.md and returns:

• Violations in the CURRENT metadata (include in audit report)
• Violations in RECOMMENDED changes (remove from action plan, replace with compliant alternatives)

Any recommendation that violates a store policy MUST be removed from the final action plan. The compliance agent suggests compliant alternatives where possible.

Step 4: Score Aggregation (sequential)

Calculate the weighted score:

Category	Weight	Source Agent
Keyword Optimization	20%	aso-keywords
Metadata Quality	15%	aso-metadata
Visual Assets	15%	aso-visuals
Reviews & Ratings	15%	aso-reviews
Competitive Position	10%	aso-competitors
Technical Health	10%	aso-technical
Conversion Signals	10%	aso-conversion
Policy Compliance	5%	aso-compliance

ASO Health Score = weighted average, rounded to integer.

Note: Compliance has only 5% weight in the score but has VETO power — any VIOLATION-level finding gets escalated to Critical in the action plan regardless of score.

Step 5: Report Generation (sequential)

Generate two files in the current directory:

ASO-AUDIT-REPORT.md — detailed findings per category (including a Policy Compliance section).

ASO-ACTION-PLAN.md — prioritized checklist (Critical > High > Medium > Low).

Step 6: Final Summary (CRITICAL — this is what the user sees)

After writing both report files, output a clean, well-formatted summary to the user. This is the most important part of the audit — it must be the LAST thing shown and must be visually clear.

Format the final output EXACTLY like this:

## ASO Audit: [App Name]

**Score: XX/100** | Platform: [iOS/Android] | Category: [category]

### Score Breakdown

| Category           | Score | Status |
|--------------------|-------|--------|
| Keywords           | XX    | [emoji-free status word] |
| Metadata           | XX    | ... |
| Visual Assets      | XX    | ... |
| Reviews & Ratings  | XX    | ... |
| Competitive        | XX    | ... |
| Technical          | XX    | ... |
| Conversion         | XX    | ... |

### Top Issues

1. **[Issue title]** — [one-line description with specific fix]
2. **[Issue title]** — [one-line description with specific fix]
3. **[Issue title]** — [one-line description with specific fix]

### Quick Wins (< 30 min)

- [Action] — [expected impact]
- [Action] — [expected impact]
- [Action] — [expected impact]

Full report: `ASO-AUDIT-REPORT.md` | Action plan: `ASO-ACTION-PLAN.md`

Rules for the final summary:

• Keep it SHORT — max 40 lines. The detail is in the files.
• Top Issues: exactly 3, the most impactful ones.
• Quick Wins: 3-5 items, things achievable in under 30 minutes each.
• Status words: use "Excellent", "Good", "Needs Work", "Poor", "Critical" (no emojis).
• End with file paths so the user knows where to find the full detail.
• Do NOT repeat the full findings — that's what the report files are for.

Available Tools

Read, Bash, Write, Glob, Grep, WebFetch, Agent

Error Handling

• App not found → report error, suggest checking ID format
• Partial data → run available agents, note missing data in report
• Agent timeout → report partial results, mark category as "incomplete"