initial skills

2025-12-30 15:18:48 +02:00
parent 258c4e0111
commit f654af9d8a
23 changed files with 10898 additions and 0 deletions
@@ -0,0 +1,288 @@
+# AmethystMultiplatform Skills Creation Plan
+
+## Overview
+Create 8 hybrid domain skills combining general expertise with AmethystMultiplatform-specific patterns.
+
+**Approach:** Each skill provides domain knowledge + project-specific implementation patterns from codebase.
+
+## Skills to Implement
+
+### 1. kotlin-multiplatform ✅ COMPLETED
+**Focus:** KMP architecture, jvmAndroid source set pattern, expect/actual
+
+**SKILL.md sections:**
+- Mental model: KMP hierarchy as dependency graph
+- Source set architecture: commonMain → jvmAndroid → {androidMain, jvmMain}
+- The jvmAndroid pattern (unique to this project, verified in quartz/build.gradle.kts:132-149)
+- expect/actual mechanics with 24+ examples from codebase
+- iOS framework setup for Quartz distribution
+
+**Bundled resources:**
+- `references/source-set-hierarchy.md` - Visual diagram + examples
+- `references/expect-actual-catalog.md` - All 24 expect/actual pairs with patterns
+- `scripts/validate-kmp-structure.sh` - Verify source set dependencies
+- `assets/kmp-hierarchy-diagram.png` - Visual graph
+
+**Differentiation:** Existing kotlin-multiplatform agent = general KMP. This skill = Amethyst's unique jvmAndroid pattern, concrete examples.
+
+**Status:** ✅ Skill created and packaged at `.claude/skills/kotlin-multiplatform/`
+
+---
+
+### 2. gradle-expert
+**Focus:** Build optimization, dependency resolution, multi-module KMP troubleshooting
+
+**SKILL.md sections:**
+- Build architecture: 4 modules, dependency flow
+- Version catalog mastery (libs.versions.toml)
+- Module dependency patterns (api vs implementation)
+- Android-specific: compileSdk, proguard
+- Desktop packaging: TargetFormat, distributions
+- Build performance: daemon, parallel, caching
+- Common errors: compose version conflicts, secp256k1 JNI variants
+
+**Bundled resources:**
+- `references/build-commands.md` - Common gradle tasks
+- `references/dependency-graph.md` - Module visualization
+- `scripts/analyze-build-time.sh` - Performance report
+- `scripts/fix-dependency-conflicts.sh` - Conflict patterns
+
+**Differentiation:** Focus on 4-module structure, KMP + Android + Desktop combo, specific issues (compose conflicts).
+
+---
+
+### 3. kotlin-expert ✅ DRAFT COMPLETE
+**Focus:** Flow state management, sealed hierarchies, immutability, DSL builders, inline/reified
+
+**SKILL.md sections:**
+- Flow state management: StateFlow/SharedFlow patterns (AccountManager, RelayConnectionManager)
+- Sealed hierarchies: sealed class vs sealed interface decision trees (AccountState, SignerResult)
+- Immutability: @Immutable for Compose performance (173+ event classes)
+- DSL builders: Type-safe fluent APIs (TagArrayBuilder, TlvBuilder)
+- Inline functions: reified generics, performance optimization (OptimizedJsonMapper)
+- Value classes: Zero-cost wrappers (optimization opportunity)
+
+**Bundled resources:**
+- `references/flow-patterns.md` - StateFlow/SharedFlow with AccountManager, RelayManager patterns
+- `references/sealed-class-catalog.md` - All 8 sealed types in quartz with usage patterns
+- `references/dsl-builder-examples.md` - TagArrayBuilder, PrivateTagArrayBuilder, TlvBuilder, custom DSL patterns
+- `references/immutability-patterns.md` - @Immutable annotation, data classes, ImmutableList/Map/Set
+
+**Differentiation:** Complements kotlin-coroutines agent (deep async). This skill = Amethyst Kotlin idioms (StateFlow state management, sealed for type safety, @Immutable for Compose, DSL builders).
+
+**Status:** ✅ SKILL.md (455 lines) + 4 references created at `.claude/skills/kotlin-expert/`
+
+**10-Step Progress:**
+1. ✅ UNDERSTAND - Defined scope (Flow/sealed/DSL/immutability/inline)
+2. ✅ EXPLORE - Found 173 @Immutable events, StateFlow in AccountManager/RelayManager, SignerResult generics, TagArrayBuilder
+3. ✅ RESEARCH - StateFlow vs SharedFlow, sealed class vs interface best practices 2025
+4. ✅ SYNTHESIZE - Extracted Amethyst patterns (hot flows for state, sealed for results, @Immutable for perf)
+5. ✅ DRAFT - Created SKILL.md + 4 reference files (flow, sealed, dsl, immutability)
+6. ✅ SELF-CRITIQUE - Reviewed against 4 Core Truths (all PASS)
+7. ✅ ITERATE - Draft complete (skipping deep iteration for now)
+8. ⏸️ TEST - Deferred to later (requires real usage scenarios)
+9. ⏸️ FINALIZE - Deferred to later
+10. ✅ DOCUMENT - Updated plan
+
+---
+
+### 4. compose-expert
+**Focus:** Shared composables, state management, animations, Material3
+
+**SKILL.md sections:**
+- Shared composables philosophy (100+ already shared in commons/commonMain)
+- State management: remember, derivedStateOf, produceState
+- Recomposition optimization: @Stable/@Immutable
+- Material3 conventions: theming
+- Custom icons: ImageVector builders (38+ icons)
+- Platform differences: Desktop vs Android UI
+- Performance: lazy lists, image loading
+
+**Bundled resources:**
+- `references/shared-composables-catalog.md` - 100+ composables
+- `references/state-patterns.md` - State hoisting examples
+- `references/icon-assets.md` - Custom icon catalog
+- `scripts/find-composables.sh` - Grep @Composable
+
+**Differentiation:** Multiplatform Compose patterns, shared vs platform UI philosophy, Amethyst conventions (robohash, custom icons).
+
+---
+
+### 5. ios-expert
+**Focus:** iosMain patterns, Swift/KMP interop, XCFramework generation
+
+**SKILL.md sections:**
+- iOS source sets: iosMain, iosX64Main, iosArm64Main
+- Swift interop: type mapping, nullability
+- expect/actual iOS: 10+ examples from quartz/iosMain
+- XCFramework setup: baseName = "quartz-kmpKit"
+- Platform APIs: platform.posix, CFNetwork, Security
+- CocoaPods integration
+- XCode project setup
+
+**Bundled resources:**
+- `references/ios-actual-implementations.md` - 10 iosMain actuals
+- `references/swift-interop-guide.md` - Type mapping
+- `references/xcode-integration.md` - XCode setup
+- `scripts/generate-xcframework.sh` - Build all iOS targets
+
+**Differentiation:** iOS platform specialization with Amethyst iosMain patterns, Quartz framework setup.
+
+---
+
+### 6. desktop-expert ✅ DRAFT COMPLETE
+**Focus:** Desktop UX, window management, Compose Desktop APIs, OS-specific conventions
+
+**SKILL.md sections:**
+- Desktop entry point: application {} DSL
+- Window management: WindowState, positioning, multi-window
+- Menu system: MenuBar, keyboard shortcuts (OS-aware)
+- System tray: minimize to tray
+- Desktop navigation: NavigationRail pattern (vs Android bottom nav)
+- File system: Desktop.getDesktop(), file pickers, drag-drop
+- Desktop UX principles: keyboard-first, native feel, tooltips
+- OS-specific behavior: macOS vs Windows vs Linux
+- Platform detection: PlatformDetector utility
+- Packaging: DMG, MSI, DEB distribution
+
+**Bundled resources:**
+- `references/desktop-compose-apis.md` - Complete Desktop API catalog (Window, Tray, MenuBar, Dialog, etc.)
+- `references/desktop-navigation.md` - NavigationRail vs BottomNav patterns
+- `references/keyboard-shortcuts.md` - Standard shortcuts by OS with DesktopShortcuts helper
+- `references/os-detection.md` - Platform detection, file paths, system integration
+
+**Differentiation:** Desktop-only APIs, OS conventions (Cmd vs Ctrl), NavigationRail, delegates build to gradle-expert and shared code to kotlin-multiplatform/compose-expert.
+
+**Status:** ✅ SKILL.md + 4 references created at `.claude/skills/desktop-expert/`
+
+**10-Step Progress:**
+1. ✅ UNDERSTAND - Defined desktop usage scenarios
+2. ✅ EXPLORE - Analyzed desktopApp/ module patterns (Main.kt, FeedScreen.kt, LoginScreen.kt)
+3. ✅ RESEARCH - Compose Desktop APIs, OS-specific UX conventions (JetBrains docs, HIG)
+4. ✅ SYNTHESIZE - Extracted desktop principles from codebase
+5. ✅ DRAFT - Created SKILL.md + 4 reference files
+6. ✅ SELF-CRITIQUE - Reviewed against 4 Core Truths (all PASS)
+7. ✅ ITERATE - Draft complete (skipping deep iteration for now)
+8. ⏸️ TEST - Deferred to later (requires real desktop scenarios)
+9. ⏸️ FINALIZE - Deferred to later
+10. ✅ DOCUMENT - Updated plan
+
+---
+
+### 7. android-expert ✅ DRAFT COMPLETE
+**Focus:** Android platform APIs, navigation, permissions, Material Design
+
+**SKILL.md sections:**
+- Android module structure: amethyst/ layout
+- Navigation: Navigation Compose, bottom nav
+- Permissions: runtime (camera, biometric)
+- Platform APIs: Intent, Context, ContentResolver
+- Lifecycle: Lifecycle-aware, ViewModel
+- Material Design: Android Material 3
+- Build config: Proguard, R8
+- Android UX: mobile-first patterns
+
+**Bundled resources:**
+- `references/android-navigation.md` - Navigation Compose
+- `references/android-permissions.md` - Permission handling
+- `references/proguard-rules.md` - Proguard explanation
+- `scripts/analyze-apk-size.sh` - APK optimization
+
+**Differentiation:** amethyst module structure, Android vs desktop patterns, Amethyst conventions.
+
+**Status:** ✅ SKILL.md + 3 references + 1 script created at `.claude/skills/android-expert/`
+
+**10-Step Progress:**
+1. ✅ UNDERSTAND - Defined Android usage scenarios
+2. ✅ EXPLORE - Analyzed amethyst/ module patterns
+3. ✅ RESEARCH - Android best practices + KMP Android patterns
+4. ✅ SYNTHESIZE - Extracted Android principles from codebase
+5. ✅ DRAFT - Initialized skill, created resources
+6. ✅ SELF-CRITIQUE - Reviewed against 4 Core Truths (all PASS)
+7. ✅ ITERATE - Draft complete (skipping deep iteration for now)
+8. ⏸️ TEST - Deferred to later
+9. ⏸️ FINALIZE - Deferred to later
+10. ✅ DOCUMENT - Updated plan
+
+---
+
+### 8. nostr-expert
+**Focus:** Nostr protocol, NIPs, Quartz architecture, event patterns
+
+**SKILL.md sections:**
+- Quartz architecture: package structure by NIP (57 NIPs implemented)
+- Event anatomy: IEvent, Event, kinds, tags (verified in TextNoteEvent.kt)
+- NIP implementation patterns: Event class, tags, builders
+- Common event types: TextNoteEvent, MetadataEvent, ReactionEvent
+- Tag patterns: aTag, eTag, pTag builders
+- Relay client: WebSocket, subscriptions
+- Cryptography: secp256k1, NIP-44 encryption
+- Event builders: TagArrayBuilder DSL
+
+**Bundled resources:**
+- `references/nip-catalog.md` - All 57 NIPs with code links
+- `references/event-hierarchy.md` - Event class diagram
+- `references/tag-patterns.md` - Tag builders from nip01Core/tags/
+- `scripts/nip-lookup.sh` - Find NIP implementation files
+
+**Differentiation:** nostr-protocol agent = NIP specs. This skill = Quartz implementation (57 NIPs), code patterns.
+
+---
+
+## Implementation Workflow
+
+Using skill-creator 10-step methodology per skill:
+
+**Overall Plan:**
+1. **UNDERSTAND** ✅ - 8 skills defined, user clarifications obtained
+2. **EXPLORE** ✅ - Codebase analyzed via Explore agent
+3. **RESEARCH** ✅ - Domain patterns identified via Plan agent
+4. **SYNTHESIZE** ✅ - Skills designed above
+
+**Per-Skill Implementation:**
+- kotlin-multiplatform: ✅ COMPLETED
+- android-expert: ✅ DRAFT COMPLETE
+- desktop-expert: ✅ DRAFT COMPLETE
+- kotlin-expert: ✅ DRAFT COMPLETE
+- Remaining 4 skills: Pending (gradle-expert, compose-expert, ios-expert, nostr-expert)
+
+## Critical Files Referenced
+
+**Build patterns:**
+- `/quartz/build.gradle.kts:132-149` - jvmAndroid source set
+- `/commons/build.gradle.kts` - Shared UI setup
+
+**Code patterns:**
+- `/quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip10Notes/TextNoteEvent.kt` - Event structure
+- `/commons/src/jvmAndroid/kotlin/com/vitorpamplona/amethyst/commons/account/AccountManager.kt` - StateFlow pattern
+- `/quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/utils/Platform.kt` - expect/actual
+
+**Documentation:**
+- `/docs/shared-ui-analysis.md` - UI migration strategy
+
+## Output Location
+`.claude/skills/<skill-name>/` for each skill
+
+## Next Steps
+
+1. ✅ Save this plan as `.claude/core-skills-plan.md` for reference
+2. ✅ Completed kotlin-multiplatform skill
+3. ✅ Completed android-expert skill (DRAFT)
+4. ✅ Completed desktop-expert skill (DRAFT)
+5. ⏳ **Next: Pick one of the remaining 5 skills:**
+   - gradle-expert - Build optimization, dependency resolution
+   - kotlin-expert - Coroutines, Flow, sealed classes
+   - compose-expert - Shared composables, state management
+   - ios-expert - iOS platform patterns, XCFramework
+   - nostr-expert - Nostr protocol, NIPs, Quartz
+
+## Current Focus: 3 skills completed
+
+**Completed:**
+- kotlin-multiplatform ✅
+- android-expert ✅
+- desktop-expert ✅
+
+**Remaining:** 5 skills
+
+Ready to start next skill when requested.