novaforge-appkit 0.1.0

package/kit/skills/mobile-testing-and-visual-qa/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: mobile-testing-and-visual-qa
+description: Define and run testing and visual QA for Flutter apps. Use during Build, Verify and Fix for unit/widget/integration tests, deterministic seed data, the screenshot catalog and capture, golden comparison, the AI visual-review rubric, structured defect format, accessibility checks and release smoke testing.
+---
+
+# Mobile Testing & Visual QA
+
+Evidence is what makes an app "done". This skill defines the tests and the visual review.
+
+## Test pyramid (small-app sizing)
+- **Unit** — most tests. Business rules, validation, formatting, calculations, state
+  transitions, storage behavior, error handling, ad-eligibility/frequency logic.
+- **Widget** — important screens: input, validation errors, empty/populated/error states,
+  primary navigation, ad-container behavior, accessibility labels where practical.
+- **Integration** (`integration_test/`) — critical journeys only: first launch, main flow,
+  persistence across restart, settings change, error recovery, offline behavior, ad-unavailable
+  behavior, release-config smoke flow.
+
+## Conventions
+- Name tests after behavior: `create_screen_shows_error_on_empty_title`.
+- Aim for meaningful coverage of logic (not a number target); cover every acceptance criterion.
+- Make tests **deterministic**: inject a fixed clock, fixed ids, and a fake repository. No
+  network, no real ads, no wall-clock time.
+
+## Deterministic seed data
+Provide a `SeedData` helper used by integration and screenshot runs so every state is
+reproducible (e.g. exactly 3 items with fixed titles/dates). Screenshots must be byte-stable.
+
+## Screenshot catalog
+Defined in `app-spec.md`. Each entry: `id`, `screen`, `state`.
+```yaml
+screenshots:
+  - { id: home_empty,             screen: HOME,   state: empty }
+  - { id: home_populated,         screen: HOME,   state: populated }
+  - { id: create_validation_error, screen: CREATE, state: invalid_input }
+  - { id: settings,               screen: SETTINGS, state: default }
+```
+
+## Capture workflow
+1. Launch a deterministic build (`APP_ENV=dev`, seed data, test ads).
+2. Navigate automatically via the integration driver.
+3. Capture each catalog state to `.appkit/screenshots/qa/<id>.png` (stable names).
+4. Compare against `.appkit/screenshots/baselines/` when a baseline exists (golden compare).
+5. Submit images to AI visual review; write findings to `.appkit/screenshots/findings/`.
+
+Use Flutter's `integration_test` + `IntegrationTestWidgetsFlutterBinding.takeScreenshot`, or
+`flutter test --update-goldens` for widget goldens. Keep a single test device profile for v1.
+
+## AI visual-review rubric (inspect every screenshot for)
+clipped text · overflow · overlapping components · broken safe areas · wrong keyboard
+handling · inconsistent spacing · missing content · low contrast · weak hierarchy ·
+misaligned controls · unclear primary action · broken dark mode · ad obstruction ·
+accidental-click risk · empty unused ad space · debug info · placeholder content ·
+platform-inappropriate UI.
+
+## Structured defect format
+```yaml
+id: VQA-003
+category: visual            # visual | accessibility | functional | ...
+severity: major             # critical | major | minor | informational
+screen: CREATE
+state: keyboard_open
+requirement: AC-3
+evidence: .appkit/screenshots/qa/create_keyboard_open.png
+issue: Primary action is hidden behind the keyboard
+expected: Primary action remains reachable
+recommended_fix: Add keyboard-aware inset and scroll support
+status: open
+```
+
+## Accessibility basics (lean checklist)
+text scaling (up to ~200%) · contrast (WCAG AA) · touch targets ≥ 48dp · semantic labels on
+controls · meaningful button names · no color-only signaling · sane focus order · screen-reader
+reachability of the critical flow. Use the Flutter `meetsGuideline` semantics matchers.
+
+## Regression & smoke
+- Every fix adds a regression test reproducing the bug.
+- Release smoke: build release, install, launch, run the core flow, confirm no debug/test-ad
+  config — see `mobile-store-release`.

package/kit/skills/small-app-product-design/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: small-app-product-design
+description: Generate, evaluate and shape small mobile app ideas. Use for idea scoring, MVP scope reduction, target-user and primary-outcome definition, screen inventory, user flows, acceptance criteria, monetization fit and policy-risk screening during the Idea and Shape phases.
+---
+
+# Small App Product Design
+
+Guidance for turning a vague request into a small, coherent, launchable product.
+
+## Selection criteria — a good small app
+- One clear user problem and one primary outcome.
+- Buildable in days, not months. 3–6 screens, 1–2 core flows.
+- Works **offline / local-first**; no login, no backend, no personal data.
+- Repeat usage (a reason to open it again) and a natural ad surface if monetized.
+- Low store-review risk (no sensitive category, no high-risk permission).
+
+## Idea scoring (rate each 1–5, then decide)
+Clarity of problem · usefulness · MVP size (smaller = better) · technical complexity
+(lower = better) · offline suitability · backend dependency (lower = better) · personal-data
+exposure (lower = better) · permission risk (lower = better) · AdMob suitability · repeat
+usage · differentiation · store-review risk (lower = better) · release speed.
+
+**Decision:** `GO` · `GO WITH REDUCED SCOPE` · `REVISE` · `HOLD` · `REJECT`.
+Reject ideas that need a backend, sensitive data, accounts, or a regulated category for the
+MVP — or steer them to a smaller adjacent idea.
+
+## MVP reduction rules
+- Cut any feature that does not serve the primary outcome.
+- Replace configuration with sensible defaults.
+- Defer: accounts, sync, sharing, theming, settings beyond the essentials, analytics.
+- One "delight" feature maximum. Everything else is post-launch.
+- If you cannot describe the app in one sentence, it is too big.
+
+## Defining the product
+- **Target user**: one concrete persona and the moment they reach for the app.
+- **Primary outcome**: the single thing the user accomplishes ("convert a recipe's servings").
+- **Core features**: 3–5 bullets, each tied to the outcome.
+- **Out of scope**: list explicitly — this is as important as the in-scope list.
+
+## Screen inventory (per screen)
+id · name · purpose · entry points · exit points · primary action · secondary actions ·
+displayed data · empty / error / loading / keyboard states · ad placement · accessibility
+notes · screenshot states. Every distinct visual **state** becomes a screenshot id.
+
+## User flows
+Describe the main flow as an ordered list of (screen → action → result). Cover first launch,
+the core flow, persistence across restart, and one error-recovery path.
+
+## Acceptance criteria
+Write them testable and observable, e.g.:
+> AC-3: When the user submits an empty title, the Create screen shows an inline error and
+> does not save. (verified by widget test `create_validation_error`)
+Each criterion should map to at least one test and, when visual, one screenshot.
+
+## Monetization fit
+Decide during shaping (see `admob-best-practices`). If ads do not fit the usage pattern
+(very short sessions, sensitive context, child-directed), recommend no ads or a one-time
+paid model rather than forcing placements.
+
+## Policy-risk screening (early)
+Flag any: children as audience, health/finance/legal claims, gambling, UGC, social comms,
+location tracking, high-risk permissions, content licensing. Any flag triggers a
+human-confirmation question (constitution §8) before shaping continues.
+
+## When to ask the human
+Ask only high-value questions: target audience, monetization intensity, Android-first vs
+simultaneous, paid vs free. Make safe assumptions for everything else and record them under
+"Assumptions" in `app-spec.md`.

package/kit/templates/app-spec.template.md

@@ -0,0 +1,89 @@
+# Application Specification
+
+> Lean spec for a small app. Keep it proportional — delete sections that don't apply.
+
+## 1. Product Summary
+## 2. Product Objective
+## 3. Target Users
+## 4. Primary User Outcome
+## 5. Core Features
+<!-- 3–5, each tied to the outcome. -->
+## 6. Out of Scope
+<!-- Explicit. As important as in-scope. -->
+## 7. Main User Flow
+<!-- Ordered screen → action → result. -->
+
+## 8. Screen Inventory
+| ID | Name | Purpose | States |
+|----|------|---------|--------|
+| HOME | Home |  | empty, populated, error |
+
+## 9. Screen Specifications
+<!-- Per screen: -->
+```yaml
+screen_id: HOME
+name: Home
+purpose:
+entry_points: []
+exit_points: []
+primary_action:
+secondary_actions: []
+displayed_data: []
+states: [empty, populated, error, loading, keyboard]
+ads:
+  placement_id: home_bottom_banner
+  format: anchored_adaptive_banner
+accessibility_notes:
+screenshots: [home_empty, home_populated]
+```
+
+## 10. Data Model
+## 11. Local Storage
+<!-- Tech + repository interface + migration/version. -->
+## 12. Permissions
+| Permission | Feature | User benefit | Runtime explanation | Store declaration |
+|---|---|---|---|---|
+<!-- An unjustified permission is a release blocker. -->
+
+## 13. Third-Party SDKs
+| SDK | Category | Data collected | Privacy manifest? |
+|---|---|---|---|
+
+## 14. AdMob Plan
+<!-- Per placement: -->
+```yaml
+placement_id: home_bottom_banner
+format: anchored_adaptive_banner
+screen: HOME
+trigger: screen_visible
+frequency: sdk_managed
+critical_interaction_conflict: false
+accidental_click_risk: low
+loading_behavior: preserve_layout
+failure_behavior: collapse_or_preserve_clean_space
+development_ad_id: test
+production_ad_id_source: environment_configuration
+```
+
+## 15. Privacy Plan
+<!-- Data inventory + Data Safety / App Privacy mapping + policy URL placeholder. -->
+## 16. Technical Approach
+<!-- Profile, structure, state mgmt, navigation, env config. -->
+## 17. Testing Strategy
+<!-- Unit / widget / integration coverage + screenshot catalog. -->
+
+## Screenshot Catalog
+```yaml
+screenshots:
+  - { id: home_empty, screen: HOME, state: empty }
+  - { id: home_populated, screen: HOME, state: populated }
+```
+
+## 18. Accessibility Requirements
+## 19. Acceptance Criteria
+<!-- AC-n: observable + testable, mapped to a test/screenshot. -->
+## 20. Store Risks
+## 21. Release Targets
+<!-- platforms, stores, OS targets, version. -->
+## 22. Assumptions
+<!-- Every safe default chosen automatically. -->

package/kit/templates/idea.template.md

@@ -0,0 +1,60 @@
+# App Idea
+
+## Working Title
+
+## Problem
+<!-- The one concrete problem this app solves. -->
+
+## Target User
+<!-- One persona and the moment they reach for the app. -->
+
+## Core Value / Primary Outcome
+<!-- The single thing the user accomplishes. -->
+
+## Primary Use Case
+
+## Proposed MVP
+<!-- 3–6 bullets, each tied to the outcome. -->
+
+## Main Screens
+<!-- Rough list; full inventory comes in Shape. -->
+
+## Why It Fits The Kit
+<!-- Small, local-first, low-permission, low-policy-risk, launchable fast. -->
+
+## Monetization Concept
+<!-- Ads? Which format? Or none / paid. -->
+
+## Privacy Considerations
+<!-- Data touched, ideally none beyond on-device. -->
+
+## Permission Considerations
+
+## Store Risks
+<!-- Any policy-sensitive aspects. -->
+
+## Recommended Platforms
+<!-- android | ios | both, with reasoning. -->
+
+## Complexity Estimate
+<!-- size, screens, days. -->
+
+## Idea Scores (1–5)
+| Dimension | Score |
+|---|---|
+| Problem clarity |  |
+| Usefulness |  |
+| MVP size (smaller=better) |  |
+| Technical complexity (lower=better) |  |
+| Offline suitability |  |
+| Backend dependency (lower=better) |  |
+| Personal-data exposure (lower=better) |  |
+| Permission risk (lower=better) |  |
+| AdMob suitability |  |
+| Repeat usage |  |
+| Differentiation |  |
+| Store-review risk (lower=better) |  |
+| Release speed |  |
+
+## Decision
+<!-- GO | GO WITH REDUCED SCOPE | REVISE | HOLD | REJECT  + one-line rationale. -->

package/kit/templates/privacy-policy.template.md

@@ -0,0 +1,41 @@
+# Privacy Policy — <APP_NAME>
+
+> DRAFT. Every `<PLACEHOLDER>` must be reviewed and completed by a human before publishing.
+> This is not legal advice. Host this at a stable URL and reference it in both stores.
+
+**Effective date:** <DATE>
+**Developer:** <DEVELOPER_NAME / ENTITY>
+**Contact:** <SUPPORT_EMAIL>
+
+## Summary
+<APP_NAME> is a local-first mobile app. <STATE_WHETHER_ANY_DATA_LEAVES_THE_DEVICE.>
+
+## Data We Collect
+<!-- From the data inventory. For a pure local app this may be "none". -->
+| Data | Purpose | Stored | Shared | Retention |
+|---|---|---|---|---|
+| <e.g. app content> | <app function> | on device | no | until user deletes |
+
+## Data We Do Not Collect
+<!-- Be specific to build trust: no account, no precise location, no contacts, etc. -->
+
+## Third-Party Services
+<!-- List each SDK and link its policy. e.g. Google AdMob. -->
+- **Google AdMob** (if ads enabled): may collect device/advertising identifiers to serve ads.
+  See Google's policy: https://policies.google.com/privacy. Personalized ads are gated on
+  consent where required (EEA/UK/CCPA). <STATE_PERSONALIZED_OR_NON_PERSONALIZED.>
+
+## Advertising & Consent
+<DESCRIBE_UMP_CONSENT_FLOW_AND_AD_PERSONALIZATION.>
+
+## Children
+<STATE_WHETHER_DIRECTED_TO_CHILDREN_AND_RELEVANT_PROTECTIONS, or "not directed to children".>
+
+## Your Rights
+<DATA_ACCESS_DELETION_MECHANISM — e.g. uninstalling removes all local data.>
+
+## Changes
+We may update this policy; changes will be posted at <HOSTED_URL>.
+
+## Contact
+<SUPPORT_EMAIL>

package/kit/templates/release-manifest.template.yaml

@@ -0,0 +1,46 @@
+# Release Manifest — generated by /appkit.release
+app:
+  name: <APP_NAME>
+  android_application_id: <com.example.app>
+  ios_bundle_id: <com.example.app>
+version:
+  name: <1.0.0>
+  android_version_code: <1>
+  ios_build: <1>
+verification:
+  status: <ready | ready_with_warnings_approved>
+  report: .appkit/verification-report.md
+  unresolved_blockers: 0
+targets: [android, ios]
+stores: [google_play, apple_app_store]
+monetization:
+  admob: <true|false>
+  ad_ids_source: environment_configuration
+artifacts:
+  android_aab: release/builds/android/<app>-release.aab
+  ios_archive: release/builds/ios/<app>.xcarchive   # or instructions
+metadata:
+  google_play: release/metadata/google-play.md
+  app_store: release/metadata/app-store.md
+  release_notes: release/metadata/release-notes.md
+  review_notes: release/metadata/review-notes.md
+privacy:
+  policy: release/privacy/privacy-policy.md
+  google_data_safety: release/privacy/google-data-safety.md
+  apple_app_privacy: release/privacy/apple-app-privacy.md
+compliance:
+  google_play: release/compliance/google-play-review.md
+  apple_app_store: release/compliance/apple-app-store-review.md
+  admob: release/compliance/admob-review.md
+  privacy: release/compliance/privacy-review.md
+checklists:
+  android: release/checklists/android-release.md
+  ios: release/checklists/ios-release.md
+signing:
+  android: { play_app_signing: true, secrets_in_repo: false }
+  ios: { provisioning_ready: <true|false>, secrets_in_repo: false }
+human_approval:
+  required: true
+  granted: false        # human sets true before submission
+placeholders_remaining: []   # must be empty before submission
+generated_at: <DATE>

package/kit/templates/store-listing.template.md

@@ -0,0 +1,37 @@
+# Store Listing — <APP_NAME>
+
+> Draft metadata. Mark every `<PLACEHOLDER>`. No misleading claims; do not show unavailable
+> features. Keep within each store's length limits.
+
+## Common
+- **App name:** <APP_NAME>
+- **Category:** <CATEGORY>
+- **Privacy policy URL:** <HOSTED_URL>
+- **Support URL:** <SUPPORT_URL>
+- **Marketing URL:** <OPTIONAL>
+
+## Google Play
+- **Short description (≤80 chars):**
+- **Full description (≤4000 chars):**
+- **Release notes:**
+- **Content rating:** <IARC_QUESTIONNAIRE_RESULT>
+- **Target audience & content:** <AGE_GROUPS>
+- **Ads declaration:** <CONTAINS_ADS: yes/no>
+- **Data Safety:** see `privacy/google-data-safety.md`
+
+## Apple App Store
+- **Subtitle (≤30 chars):**
+- **Promotional text (≤170 chars):**
+- **Description:**
+- **Keywords (≤100 chars, comma-separated):**
+- **What's New (release notes):**
+- **Age rating:** <RATING>
+- **App Privacy:** see `privacy/apple-app-privacy.md`
+- **Export compliance:** <USUALLY "No" for standard HTTPS>
+
+## Reviewer Notes (both stores)
+<!-- Explain non-obvious behavior, how to reach ad-bearing screens, demo/login if any. -->
+
+## Screenshots
+- Source: `release/screenshots/store-final/`
+- Required sizes: <PER_PLATFORM_DEVICE_SIZES>

package/kit/templates/tasks.template.md

@@ -0,0 +1,46 @@
+# Tasks
+
+## Status Legend
+- [ ] Not started
+- [~] In progress
+- [x] Complete
+- [!] Blocked
+
+> Group by vertical slice. Each task links feature, screen, acceptance criteria, test
+> expectation, and policy consideration.
+
+## Slice 1: Application shell
+### TASK-001
+- **Feature:** project setup
+- **Screen:** —
+- **Description:** Initialize project, package ids, navigation, theme, initial tests.
+- **Acceptance:** AC-? · **Tests:** smoke test passes · **Policy:** —
+- **Status:** [ ]
+
+## Slice 2: Core flow
+### TASK-002
+- **Feature:** · **Screen:** HOME
+- **Description:**
+- **Acceptance:** AC-? · **Tests:** unit + widget · **Policy:** —
+- **Status:** [ ]
+
+## Slice 3: Persistence
+### TASK-003
+- **Feature:** local storage · **Screen:** —
+- **Description:** Repository + migration + persistence tests.
+- **Acceptance:** AC-? · **Tests:** unit (storage) · **Policy:** data inventory updated
+- **Status:** [ ]
+
+## Slice 4: Advertising
+### TASK-004
+- **Feature:** AdMob · **Screen:** HOME
+- **Description:** Ad adapter, test ad config, banner placement, failure-state handling.
+- **Acceptance:** AC-? · **Tests:** widget (ad container, failure) · **Policy:** AdMob placement rules
+- **Status:** [ ]
+
+## Slice 5: Verification readiness
+### TASK-005
+- **Feature:** QA · **Screen:** all
+- **Description:** Deterministic seed data, screenshot scenarios, critical integration test.
+- **Acceptance:** screenshot catalog reachable · **Tests:** integration · **Policy:** —
+- **Status:** [ ]

package/kit/templates/verification-report.template.md

@@ -0,0 +1,58 @@
+# Verification Report
+
+**Overall Status:** <!-- READY | READY WITH WARNINGS | NOT READY | HUMAN CONFIRMATION REQUIRED -->
+**Date:** · **Mode:** <!-- full | changed | android | ios | visual | policy -->
+
+## Build Information
+<!-- profile, app id/bundle id, version, env, flutter/dart versions -->
+
+## Test Summary
+| Suite | Result | Notes |
+|---|---|---|
+| Static analysis |  |  |
+| Unit |  |  |
+| Widget |  |  |
+| Integration |  |  |
+
+## Unit Test Results
+## Component (Widget) Test Results
+## Integration Test Results
+
+## Screenshot Coverage
+| Catalog id | Captured | Golden | Result |
+|---|---|---|---|
+
+## Findings
+> One block per finding.
+```yaml
+id: VQA-001
+category: visual
+severity: major          # critical | major | minor | informational
+status: open             # open | fixed | accepted
+screen:
+state:
+requirement:
+evidence:
+issue:
+expected:
+recommended_fix:
+```
+
+## Visual QA Findings
+## Accessibility Findings
+## Permission Findings
+## SDK & Privacy Findings
+## AdMob Findings
+## Google Play Findings
+## Apple App Store Findings
+## Release Build Findings
+
+## Blocking Issues
+<!-- critical + unresolved major -->
+## Warnings
+<!-- minor -->
+## Recommended Fixes
+<!-- ordered, minimal -->
+
+## Final Decision
+<!-- verdict + the next command -->

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "novaforge-appkit",
+  "version": "0.1.0",
+  "description": "Lean Mobile App Launch Kit — take a small mobile app from idea to a store-ready release with Claude Code or Codex.",
+  "bin": {
+    "appkit": "bin/appkit.js"
+  },
+  "type": "commonjs",
+  "engines": {
+    "node": ">=16"
+  },
+  "files": [
+    "bin/",
+    "kit/",
+    "adapters/",
+    "install.sh",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node bin/appkit.js --help"
+  },
+  "keywords": [
+    "appkit",
+    "mobile",
+    "flutter",
+    "claude-code",
+    "codex",
+    "spec-kit",
+    "admob",
+    "app-store",
+    "google-play",
+    "ai-agents"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/NovaForgeOrg/appkit.git"
+  },
+  "homepage": "https://github.com/NovaForgeOrg/appkit#readme",
+  "bugs": {
+    "url": "https://github.com/NovaForgeOrg/appkit/issues"
+  },
+  "license": "MIT"
+}