refactor: replace debug mode with extensible hook-based system

CLAUDE.md

@@ -1,15 +1,19 @@
 ## Pre-Commit Requirements
 **CRITICAL**: Always run from project root before ANY commit:
 1. `dart analyze` (check for code errors)
-2. `ktlint -F .`
-3. `find . -name "*.dart" ! -name "*.g.dart" ! -path "*/.*" -print0 | xargs -0 dart format --set-exit-if-changed`
-4. `flutter test` (all Dart tests)
-5. `cd example/android && ./gradlew :workmanager_android:test` (Android native tests)
+2. `ktlint -F .` (format Kotlin code)
+3. `swiftlint --fix` (format Swift code)
+4. `find . -name "*.dart" ! -name "*.g.dart" ! -path "*/.*" -print0 | xargs -0 dart format --set-exit-if-changed`
+5. `flutter test` (all Dart tests)
+6. `cd example/android && ./gradlew :workmanager_android:test` (Android native tests)
+7. `cd example && flutter build apk --debug` (build Android example app)
+8. `cd example && flutter build ios --debug --no-codesign` (build iOS example app)
 
 ## Code Generation
 - Regenerate Pigeon files: `melos run generate:pigeon`
 - Regenerate Dart files (including mocks): `melos run generate:dart`
 - Do not manually edit *.g.* files
+- Never manually modify mocks or generated files. Always modify the source, then run the generator tasks via melos.
 
 ## Running Tests
 - Use melos to run all tests: `melos run test`
@@ -32,4 +36,31 @@
 - **No AI agent progress**: Don't document debugging steps, build fixes, or internal development process
 - **What matters to users**: Breaking changes, new features, bug fixes that affect their code
 - **Example of bad changelog entry**: "Fixed Kotlin null safety issues with androidx.work 2.10.2 type system improvements"
-- **Example of good changelog entry**: "Fixed periodic tasks not respecting frequency changes"
+- **Example of good changelog entry**: "Fixed periodic tasks not respecting frequency changes"
+
+## Documentation Components (docs.page)
+- **Component reference**: https://use.docs.page/ contains the full reference for available components
+- **Tabs component syntax**:
+  ```jsx
+  <Tabs>
+    <TabItem label="Tab Name" value="unique-value">
+      Content here
+    </TabItem>
+  </Tabs>
+  ```
+- Use `<TabItem>` not `<Tab>` - this is a common mistake that causes JavaScript errors
+- Always include both `label` and `value` props on TabItem components
+
+## Pull Request Description Guidelines
+
+Template:
+```markdown
+## Summary
+- Brief change description
+
+Fixes #123
+
+## Breaking Changes (if applicable)
+**Before:** `old code`
+**After:** `new code`
+```

docs.json

@@ -29,6 +29,10 @@
           "title": "Task Customization",
           "href": "/customization"
         },
+        {
+          "title": "Task Status Tracking",
+          "href": "/task-status"
+        },
         {
           "title": "Debugging",
           "href": "/debugging"

docs/debugging.mdx

@@ -5,18 +5,128 @@ description: Debug and troubleshoot background tasks on Android and iOS
 
 Background tasks can be tricky to debug since they run when your app is closed. Here's how to effectively debug and troubleshoot them on both platforms.
 
-## Enable Debug Mode
+## Hook-Based Debug System
 
-Always start by enabling debug notifications:
+The Workmanager plugin uses a hook-based debug system that allows you to customize how debug information is handled.
+
+### Quick Setup
+
+Initialize Workmanager without any debug parameters:
 
 ```dart
-Workmanager().initialize(
-  callbackDispatcher,
-  isInDebugMode: true, // Shows notifications when tasks execute
-);
+await Workmanager().initialize(callbackDispatcher);
 ```
 
-This shows system notifications whenever background tasks run, making it easy to verify execution.
+Then set up platform-specific debug handlers as needed.
+
+## Android Debug Handlers
+
+### Logging Debug Handler (Recommended)
+
+Shows debug information in Android's Log system (visible in `adb logcat`):
+
+```kotlin
+// In your Application class
+import dev.fluttercommunity.workmanager.WorkmanagerDebug
+import dev.fluttercommunity.workmanager.LoggingDebugHandler
+
+class MyApplication : Application() {
+    override fun onCreate() {
+        super.onCreate()
+        WorkmanagerDebug.setCurrent(LoggingDebugHandler())
+    }
+}
+```
+
+### Notification Debug Handler
+
+Shows debug information as notifications (requires notification permissions):
+
+```kotlin
+import dev.fluttercommunity.workmanager.NotificationDebugHandler
+
+class MyApplication : Application() {
+    override fun onCreate() {
+        super.onCreate()
+        WorkmanagerDebug.setCurrent(NotificationDebugHandler())
+    }
+}
+```
+
+## iOS Debug Handlers
+
+### Logging Debug Handler (Recommended)
+
+Shows debug information in iOS's unified logging system:
+
+```swift
+// In your AppDelegate.swift
+import workmanager_apple
+
+@main
+class AppDelegate: FlutterAppDelegate {
+    override func application(
+        _ application: UIApplication,
+        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
+    ) -> Bool {
+        WorkmanagerDebug.setCurrent(LoggingDebugHandler())
+        return super.application(application, didFinishLaunchingWithOptions: launchOptions)
+    }
+}
+```
+
+### Notification Debug Handler
+
+Shows debug information as notifications:
+
+```swift
+WorkmanagerDebug.setCurrent(NotificationDebugHandler())
+```
+
+## Custom Debug Handlers
+
+Create your own debug handler for custom logging needs:
+
+<Tabs>
+  <TabItem label="Android" value="android">
+
+```kotlin
+class CustomDebugHandler : WorkmanagerDebug() {
+    override fun onTaskStatusUpdate(context: Context, taskInfo: TaskDebugInfo, status: TaskStatus, result: TaskResult?) {
+        // Custom status handling logic
+        // See Task Status documentation for detailed status information
+    }
+
+    override fun onExceptionEncountered(context: Context, taskInfo: TaskDebugInfo?, exception: Throwable) {
+        // Handle exceptions
+    }
+}
+
+WorkmanagerDebug.setCurrent(CustomDebugHandler())
+```
+
+  </TabItem>
+  <TabItem label="iOS" value="ios">
+
+```swift
+class CustomDebugHandler: WorkmanagerDebug {
+    override func onTaskStatusUpdate(taskInfo: TaskDebugInfo, status: TaskStatus, result: TaskResult?) {
+        // Custom status handling logic  
+        // See Task Status documentation for detailed status information
+    }
+
+    override func onExceptionEncountered(taskInfo: TaskDebugInfo?, exception: Error) {
+        // Handle exceptions
+    }
+}
+
+WorkmanagerDebug.setCurrent(CustomDebugHandler())
+```
+
+  </TabItem>
+</Tabs>
+
+For detailed information about task statuses, lifecycle, and notification formats, see the [Task Status Tracking](task-status) guide.
 
 ## Android Debugging
 
@@ -243,7 +353,7 @@ Future<bool> isTaskHealthy(String taskName, Duration maxAge) async {
 - [ ] Workmanager initialized in main()
 - [ ] Task names are unique
 - [ ] Platform setup completed ([iOS setup guide](quickstart#ios))
-- [ ] Debug notifications enabled (`isInDebugMode: kDebugMode`)
+- [ ] Debug handler configured (see [Debug Handlers](#debug-handlers))
 
 **Performance & Reliability:**
 - [ ] Task logic optimized for background execution

docs/quickstart.mdx

@@ -145,10 +145,7 @@ void callbackDispatcher() {
 import 'package:flutter/foundation.dart';
 
 void main() {
-  Workmanager().initialize(
-    callbackDispatcher,
-    isInDebugMode: kDebugMode,
-  );
+  Workmanager().initialize(callbackDispatcher);
 
   runApp(MyApp());
 }