Launch Readiness

A library-agnostic launch readiness skill for Flutter, native iOS and Mac (Swift, SwiftUI), and native Android (Kotlin, Jetpack Compose) projects. Auto-detects project type and stack, runs tiered parallel quality checks, produces a scored go/no-go report, offers auto-fixes, and improves itself after each run.

Invocation

/launch-readiness              # Full 3-tier sweep, entire codebase
/launch-readiness --changed    # Full 3-tier sweep, changed files only
/launch-readiness --tier 1     # Only T1 (testing + security + store compliance)
/launch-readiness --tier 2     # T1 + T2
/launch-readiness --overlay X  # Use specific overlay file
/launch-readiness --fix        # Run + auto-fix without asking
/launch-readiness --auto       # Hook mode: condensed output, no prompts

Orchestrator Flow

1. DISCOVER  → Detect project type, read manifests (pubspec.yaml, project.yml, Package.swift, Gradle files), CLAUDE.md, overlay → emit stack profile
2. SCOPE     → Determine file scope (--changed or full)
3. DISPATCH  → Launch tier phases as parallel subagents
4. GATE      → Collect results, enforce tier gates
5. SCORECARD → Aggregate into unified report
6. FIX OFFER → "N issues auto-fixable. Fix now?"
7. LEARN     → Mine new patterns, propose phase updates

Step 1: Stack Discovery

Read these sources in parallel:

1-pre. Project type

Detect every project type present before reading manifests. One repository can hold several, for example a SwiftUI iPhone, Watch and Mac app next to a Kotlin Android app. Run each phase once per detected project and label findings with the project.

For Flutter, continue with 1a. For native projects, read references/native-projects.md for detection and the command map, then continue with 1a-native. Every phase file has a "Native Swift and Kotlin projects" section with the native equivalent of its Flutter checks.

1a. pubspec.yaml (Flutter)

Detect dependencies to build a stack profile:

See references/stack-detectors.md for detailed detection rules.

1a-native. Native Swift and Kotlin manifests

Detect the stack from these files instead of pubspec.yaml:

Zero third-party dependencies is a valid result. Record it in the profile and skip the checks that need an SDK.

1b. CLAUDE.md

If a CLAUDE.md exists at the project root (or any parent), extract:

• Banned imports (e.g., a banned UI package)
• Theme constant rules (e.g., "use spacing tokens, not raw values")
• Naming conventions
• Coverage thresholds
• Code quality rules

1c. Overlay

Resolve overlay using this priority:

1. --overlay <name> flag (explicit)
2. name field from pubspec.yaml (e.g., name: my_app matches overlays/my_app.md), or for native projects the top-level name: in project.yml or rootProject.name in settings.gradle.kts
3. Git repository root directory name
4. No overlay (generic checks only)

If multiple overlays could match, ask the user.

Stack Profile Output

Emit a profile object that every phase subagent receives:

Stack Profile:
- state: {detected state management}
- analytics: {detected analytics}
- crash: {detected crash reporting}
- subs: {detected subscriptions}
- ui: {detected UI framework}
- nav: {detected navigation}
- di: {detected DI}
- l10n: {detected localization}
- test_runner: {detected test runner}
- project_type: {flutter | apple-native | android-native, one entry per detected project}
- commands: {resolved build, test, lint and archive commands per project, see references/native-projects.md}
- rules: [extracted from CLAUDE.md]
- overlay: {matched overlay name or "none"}

Step 2: Scope Resolution

Determine which files to check:

• Full codebase (default, or --changed not specified): Flutter: all .dart files under lib/. Native Apple: all .swift files outside build/, .build/ and DerivedData. Native Android: all .kt files under src/main and src/test, plus AndroidManifest.xml and Gradle files
• Changed files (--changed or auto-hook mode): git diff --name-only $(git merge-base HEAD <target-branch>)..HEAD
• Target branch detection: From PR target (gh pr view), from branch naming (feature branches target the integration branch, hotfix branches target the production branch), or default to the integration branch. Branch roles are integration, release candidate, and production (for example develop, release, main).
• Import expansion (release-candidate and production targets only): For each changed file, resolve direct importers via grep to catch ripple effects

Step 3: Dispatch Tier Phases

Tier Structure

Launch all phases within a tier as parallel subagents using the Agent tool. Each subagent receives:

• The stack profile from Step 1
• The file scope from Step 2
• The phase instructions from phases/{phase}.md
• Any overlay additions from overlays/{overlay}.md for that phase

Phase File Location

Phase prompts live in phases/ directory relative to this skill file. Read the phase file and pass its content as the subagent prompt, prepending the stack profile and scope.

Subagent Error Handling

If a phase subagent fails (timeout, crash, malformed output):

1. Retry once with the same inputs
2. If retry fails: mark the phase as INCONCLUSIVE
3. Inconclusive in T1/T2 → treated as critical (fail-closed)
4. Inconclusive in T3 → treated as warning (advisory tier)
5. Include error details in the report

Step 4: Gate Enforcement

After all phases in a tier complete:

• If any critical findings → STOP. Present findings, offer to fix. Do NOT proceed to next tier.

• If high findings in T2 → present each and ask for acknowledgment:

  [phase] file:line — description
  Acknowledge? (y = accept risk / n = will fix) [y/n]:

  • y: marked acknowledged, doesn't count toward HOLD
  • n: remains unacknowledged, counts toward HOLD
• If --auto mode: all highs are unacknowledged (no interactive prompt)
• If tier clears → proceed to next tier

Auto-Hook Gate by Branch

Step 5: Scorecard Generation

After all tiers complete (or short-circuit), generate the report.

Verdict Logic

Severity Definitions

Report Template

Use the template in references/scorecard-template.md. Write the report to docs/launch-readiness-report.md in the project root.

Step 6: Fix Offer

After presenting the scorecard:

1. Count auto-fixable issues (those with fix_action in phase output)
2. Present: "N issues can be fixed automatically. Fix now?"
3. If --fix flag: skip prompt, fix immediately
4. On approval: apply fixes grouped by phase
5. After fixing: re-run only affected phases to verify
6. Present updated scorecard with delta

Step 7: Self-Improvement

After every run, perform learning extraction.

Pattern Mining

Scan findings for recurring patterns not already in phase check lists:

• New code patterns that should be checked
• Check refinements (broader scope than current check)
• Project-specific discoveries

Learning Persistence

Append to references/learnings.md:

## {date} — {project} run
- NEW CHECK ({phase}): {description}
- REFINEMENT ({phase}): {description}

Pruning

On each run, scan learnings.md and:

• Remove entries older than 90 days not promoted to a phase/overlay
• Deduplicate identical check descriptions
• Cap at 100 entries (oldest unpromoted pruned first)

Phase Update Proposals

Present at end of report:

"I discovered N patterns not covered by current checks. Update phase files?"

On approval:

• Generic patterns → update phases/{phase}.md
• Project-specific patterns → update overlays/{project}.md

Auto-Hook Mode

When invoked with --auto (from a UserPromptSubmit hook):

• Run T1 only, scoped to changed files

• Condensed output:

  Launch Readiness (T1):
    Testing:  PASS (N tests, 0 failures)
    Security: PASS (0 criticals)
    Store Compliance: PASS (0 criticals)
    → Proceeding.

• No interactive prompts (highs are unacknowledged)
• On failure: print findings and block

Hook Setup

See hooks/pre-push.md for configuration instructions.

Sources

• https://developer.apple.com/documentation/metrickit
• https://developer.apple.com/documentation/storekit/in-app-purchase
• https://developer.android.com/build/building-cmdline
• https://api.flutter.dev/flutter/widgets/MediaQuery/textScalerOf.html
• https://docs.flutter.dev/ui/accessibility/accessibility-testing
• https://riverpod.dev/docs/whats_new
• https://www.w3.org/TR/WCAG22/
• https://posthog.com/docs/libraries/flutter
• https://firebase.google.com/docs/analytics/flutter/events
• https://amplitude.com/docs/sdks/analytics/flutter/flutter-sdk-4
• https://developer.apple.com/app-store/review/guidelines/
• https://developer.apple.com/app-store/user-privacy-and-data-use/
• https://developer.apple.com/news/upcoming-requirements/
• https://developer.apple.com/support/third-party-SDK-requirements/
• https://developer.apple.com/documentation/bundleresources/privacy-manifest-files
• https://developer.apple.com/help/app-store-connect/reference/app-information/screenshot-specifications
• https://developer.apple.com/help/app-store-connect/reference/app-information/age-ratings-values-and-definitions
• https://developer.apple.com/documentation/xcode/configuring-your-app-icon
• https://support.google.com/googleplay/android-developer/answer/11926878
• https://support.google.com/googleplay/android-developer/answer/10787469
• https://support.google.com/googleplay/android-developer/answer/9888076
• https://support.google.com/googleplay/android-developer/answer/13327111
• https://support.google.com/googleplay/android-developer/answer/14115180
• https://support.google.com/googleplay/android-developer/answer/9866151
• https://developer.android.com/guide/practices/page-sizes
• https://developer.android.com/about/versions/13/behavior-changes-13#granular-media-permissions
• https://developers.google.com/android-publisher/api-ref/rest/v3/applications/dataSafety
• https://docs.sentry.io/concepts/key-terms/dsn-explainer/
• https://firebase.google.com/docs/projects/api-keys
• https://pub.dev/packages/mixpanel_flutter
• https://firebase.google.com/docs/crashlytics/flutter/customize-crash-reports
• https://docs.flutter.dev/ui/internationalization
• https://code.claude.com/docs/en/hooks
• https://cli.vgv.dev/docs/commands/test