feat: add mobile API integration skill and command (#23)

Author: Wreos

CHANGELOG.md

@@ -33,6 +33,9 @@
   - explicit truthfulness policy (`planned/not executed` wording when no command evidence exists)
   - required missing-inputs/assumptions notes for partial context
   - required next steps and confidence/residual risk coverage in output contracts
+- Added external backend API integration workflow:
+  - command: `commands/integrate-mobile-api.md`
+  - skill: `skills/integrate-mobile-api/SKILL.md`
 
 ## 1.10.0
 

README.md

@@ -98,6 +98,7 @@ Reference project layout:
   - `prepare-mobile-release`
   - `setup-mobile-github-pipeline`
   - `setup-flutter-environment`
+  - `integrate-mobile-api`
   - `integrate-firebase`
   - `security-review`
   - `sync-official-flutter-ai-rules`
@@ -113,6 +114,7 @@ Reference project layout:
   - `skills/build-flutter-features/`
   - `skills/scaffold-flutter-architecture/`
   - `skills/release-mobile-apps/`
+  - `skills/integrate-mobile-api/`
   - `skills/integrate-firebase/`
   - `skills/write-flutter-tests/`
   - `skills/review-flutter-code/`
@@ -172,24 +174,26 @@ Reference project layout:
 7. For Firebase integration use:
    - `integrate-firebase`
    - `docs/firebase-integration-checklist.md`
-8. For security audit and secrets scanning use:
+8. For external backend API integration use:
+   - `integrate-mobile-api`
+9. For security audit and secrets scanning use:
    - `security-review`
    - `docs/security-audit-checklist.md`
    - `docs/security-posture.md`
-9. Keep generated output aligned with plugin rules.
-10. For dependency upgrades, also follow:
+10. Keep generated output aligned with plugin rules.
+11. For dependency upgrades, also follow:
    - `docs/dependency-upgrade-checklist.md`
-11. For monorepo/workspace setups, follow:
+12. For monorepo/workspace setups, follow:
    - `docs/monorepo-workspace-guide.md`
-12. To sync official Flutter AI rules profiles (`10k`/`4k`/`1k`), use:
+13. To sync official Flutter AI rules profiles (`10k`/`4k`/`1k`), use:
    - `sync-official-flutter-ai-rules`
    - `docs/flutter-ai-rules-sync.md`
-13. For automated release cut (version/changelog/tag/release), use:
+14. For automated release cut (version/changelog/tag/release), use:
    - `.github/workflows/release-automation.yml`
    - `docs/release-automation.md`
-14. For command namespacing/aliases (`flutter:*`), see:
+15. For command namespacing/aliases (`flutter:*`), see:
    - `docs/command-namespacing.md`
-15. For deterministic local setup and SDK/MCP readiness, use:
+16. For deterministic local setup and SDK/MCP readiness, use:
    - `setup-flutter-environment`
 
 Note: every code review flow includes mandatory security checks (OWASP MASVS-oriented).
@@ -207,3 +211,4 @@ Note: every code review flow includes mandatory security checks (OWASP MASVS-ori
 9. Security audit and secrets scanner workflow via `/security-review`.
 10. Safe Flutter/Dart dependency upgrades with deterministic validation and rollback.
 11. Deterministic environment bootstrapping for Flutter SDK, MCP, and baseline checks.
+12. External backend API integration with robust auth/error/retry patterns.

commands/flutter-integrate-mobile-api.md

@@ -0,0 +1,10 @@
+---
+name: flutter:integrate-mobile-api
+description: Alias for `integrate-mobile-api`. Integrate backend REST/GraphQL APIs into Flutter app with safe auth, error handling, and layered architecture.
+---
+
+Namespaced alias for `integrate-mobile-api`.
+
+1. Run the canonical command with the same intent.
+2. Follow `./integrate-mobile-api.md`.
+3. Keep output and checks identical to the canonical command.

commands/integrate-mobile-api.md

@@ -0,0 +1,11 @@
+---
+name: integrate-mobile-api
+description: Integrate backend REST/GraphQL APIs into Flutter app with safe auth, error handling, and layered architecture.
+---
+
+Integrate external API into the target Flutter app.
+
+1. Follow `../skills/integrate-mobile-api/SKILL.md`.
+2. Keep networking logic in data layer and map to domain models/failures.
+3. Add/update tests for happy and error paths.
+4. Provide validation evidence and explicit follow-up risks.

scripts/validate_prompt_semantics.sh

@@ -29,6 +29,7 @@ canonical_commands=(
   "commands/update-flutter-dependencies.md"
   "commands/resolve-flutter-build-error.md"
   "commands/prepare-mobile-release.md"
+  "commands/integrate-mobile-api.md"
   "commands/integrate-firebase.md"
   "commands/migrate-flutter-code.md"
   "commands/scaffold-flutter-feature.md"

skills/integrate-mobile-api/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: integrate-mobile-api
+description: Integrate external REST/GraphQL APIs into Flutter apps with production-safe networking, auth, error handling, and test coverage.
+---
+
+# Integrate Mobile API
+
+Use this skill for integrating backend APIs into Flutter applications.
+
+## Workflow
+
+1. Confirm API scope and constraints:
+   - protocol (`REST` or `GraphQL`)
+   - authentication model (JWT, OAuth, API key, session)
+   - required endpoints/operations
+2. Define architecture boundaries:
+   - data layer for client/datasource
+   - domain layer for repository contracts and use cases
+   - presentation layer for state updates
+3. Implement API client with safe defaults:
+   - timeouts
+   - retry/backoff policy where appropriate
+   - request/response logging with redaction
+4. Add auth handling:
+   - token attach/refresh strategy
+   - unauthorized flow (`401/403`) and sign-out fallback
+5. Add DTO mapping and error normalization:
+   - map API payloads to domain entities
+   - map transport/server failures to typed domain failures
+6. Add tests:
+   - unit tests for mapping and repository behavior
+   - integration tests for happy/error paths (mock server/client)
+7. Validate with analysis and impacted tests.
+
+## Guardrails
+
+- Do not expose secrets/tokens in logs or source files.
+- Keep API client concerns in data layer; avoid direct networking in widgets.
+- Do not claim API integration is complete without naming changed files and validation evidence.
+- In simulation/planning mode, use `planned/not executed` wording.
+
+## Required output
+
+1. API scope and auth model selected.
+2. Files changed by layer (presentation/domain/data).
+3. Validation commands and results.
+4. Error handling and retry strategy summary.
+5. Remaining risks/follow-up tasks.
+
+## Required references
+
+- `../../rules/flutter-development-best-practices.mdc`
+- `../../rules/dart-effective-dart.mdc`
+- `../../rules/flutter-test-best-practices.mdc`