AGENTS.md · diff

git:20260125.c366932 to git:20260204.6094bc5

109 added, 50 removed. Audit A to A.

- # Agent Instructions

+ # AGENTS.md

- This repository contains skills for AI coding agents working with Capacitor mobile development.

+ This file provides guidance to AI agents and contributors working on this Capacitor plugin.

- ## How to Use These Skills

+ ## Quick Start

- 1. **Identify the task** - Determine which skill applies

- 2. **Read the skill** - Load the relevant SKILL.md file

- 3. **Apply the knowledge** - Use the guidelines and examples

- 4. **Cite sources** - Reference the skill when providing information

+ ```bash

+ # Install dependencies

+ bun install

- ## Skill Triggers

+ # Build the plugin (TypeScript + Rollup + docgen)

+ bun run build

- ### Plugin Selection

- - "which plugin for X" → capacitor-plugins

- - "add biometric/camera/audio/etc" → capacitor-plugins

- - "native functionality" → capacitor-plugins

+ # Full verification (iOS, Android, Web)

+ bun run verify

- ### Live Updates

- - "live updates" → capgo-live-updates

- - "OTA updates" → capgo-live-updates

- - "skip app store" → capgo-live-updates

- - "capgo" → capgo-live-updates

- - "deploy instantly" → capgo-live-updates

+ # Format code (ESLint + Prettier + SwiftLint)

+ bun run fmt

- ### Code Quality

- - "best practices" → capacitor-best-practices

- - "optimize" → capacitor-best-practices

- - "review code" → capacitor-best-practices

+ # Lint without fixing

+ bun run lint

+ ```

- ### Debugging

- - "debug" → debugging-capacitor

- - "crash" → debugging-capacitor

- - "not working" → debugging-capacitor

- - "logs" → ios-android-logs

- - "logcat" → ios-android-logs

+ ## Development Workflow

- ### UI/Design

- - "Ionic" → ionic-design

- - "Konsta" → konsta-ui

- - "Tailwind mobile" → tailwind-capacitor

- - "notch/safe area" → safe-area-handling

+ 1. **Install** - `bun install` (never use npm)

+ 2. **Build** - `bun run build` compiles TypeScript, generates docs, and bundles with Rollup

+ 3. **Verify** - `bun run verify` builds for iOS, Android, and Web. Always run this before submitting work

+ 4. **Format** - `bun run fmt` auto-fixes ESLint, Prettier, and SwiftLint issues

+ 5. **Lint** - `bun run lint` checks code quality without modifying files

- ### iOS

- - "CocoaPods to SPM" → cocoapods-to-spm

- - "Swift Package Manager" → cocoapods-to-spm

+ ### Individual Platform Verification

- ### Automation

- - "MCP" → capacitor-mcp

- - "automate" → capacitor-mcp

+ ```bash

+ bun run verify:ios

+ bun run verify:android

+ bun run verify:web

+ ```

- ## Priority Order

+ ### Example App

- When multiple skills apply:

- 1. Most specific skill first

- 2. Then general best practices

- 3. Reference additional skills as needed

+ If an `example-app/` directory exists, you can test the plugin locally:

- ## Example

+ ```bash

+ cd example-app

+ bun install

+ bun run start

+ ```

- User: "Add biometric login to my app"

+ The example app references the plugin via `file:..`. Use `bunx cap sync <platform>` to sync native platforms.

- Agent should:

- 1. Use `capacitor-plugins` to recommend `@capgo/capacitor-native-biometric`

- 2. Use `capacitor-best-practices` for implementation patterns

- 3. Use `debugging-capacitor` if issues arise

+ ## Project Structure

+ - `src/definitions.ts` - TypeScript interfaces and types (source of truth for API docs)

+ - `src/index.ts` - Plugin registration

+ - `src/web.ts` - Web implementation

+ - `ios/Sources/` - iOS native code (Swift)

+ - `android/src/main/` - Android native code (Java/Kotlin)

+ - `dist/` - Generated output (do not edit manually)

+ - `Package.swift` - SwiftPM definition

+ - `*.podspec` - CocoaPods spec

+ ## iOS Package Management

+ We always support both **CocoaPods** and **Swift Package Manager (SPM)**. Every plugin must ship a valid `*.podspec` and `Package.swift`. Do not remove or break either integration — users depend on both.

+ ## API Documentation

+ API docs in the README are auto-generated from JSDoc in `src/definitions.ts`. **Never edit the `<docgen-index>` or `<docgen-api>` sections in README.md directly.** Instead, update `src/definitions.ts` and run `bun run docgen` (also runs as part of `bun run build`).

+ ## Versioning

+ The plugin major version follows the Capacitor major version (e.g., plugin v8 for Capacitor 8). **We only ship breaking changes when a new Capacitor native major version is released.** All other changes must be backward compatible.

+ ## Changelog

+ `CHANGELOG.md` is managed automatically by CI/CD. Do not edit it manually.

+ ## Pull Request Guidelines

+ We welcome contributions, including AI-generated pull requests. Every PR must include:

+ ### Required Sections

+ 1. **What** - What does this PR change?

+ 2. **Why** - What is the reason for this change?

+ 3. **How** - How did you approach the implementation?

+ 4. **Testing** - What did you test? How did you verify it works?

+ 5. **Not Tested** - What is not yet tested or needs further validation?

+ ### Rules

+ - **No breaking changes** unless aligned with a new Capacitor major release.

+ - Run `bun run verify` and `bun run fmt` before opening a PR. CI will catch failures, but catching them locally saves time.

+ - If you are an AI agent, that is perfectly fine. Just be transparent about it. We care that the code is correct and helpful, not who wrote it.

+ - We review PRs on a best-effort basis. We may request changes — you are expected to address them for the PR to be merged.

+ - We use automated code review tools (CodeRabbit, and others). You will need to respond to their feedback and resolve any issues they raise.

+ - We have automatic releases. Once merged, your change will ship in the next release cycle.

+ ### PR Template

+ ```

+ ## What

+ - [Brief description of the change]

+ ## Why

+ - [Motivation for this change]

+ ## How

+ - [Implementation approach]

+ ## Testing

+ - [What was tested and how]

+ ## Not Tested

+ - [What still needs testing, if anything]

+ ```

+ ## Common Pitfalls

+ - Always rename Swift/Java classes and package IDs when creating a new plugin from a template — leftover names cause registration conflicts.

+ - We only use Java 21 for Android builds.

+ - Keep temporary files clean: delete or mark with `deleteOnExit` after use.

+ - `dist/` is fully regenerated on every build — never edit generated files.

+ - Use Bun for everything. Do not use npm or npx. Use `bunx` if you need to run a package binary.