diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml new file mode 100644 index 00000000..c4690e6f --- /dev/null +++ b/.github/FUNDING.yml @@ -0,0 +1,13 @@ +# Funding & Sponsorship + +# GitHub Sponsors +# github: [BitSleuthAI] + +# Open Collective +# open_collective: bitsleuth-wallet + +# Custom sponsorship URL +custom: ["https://bitsleuth.ai/sponsor", "https://github.com/BitSleuthAI/Wallet"] + +# Note: If you'd like to support BitSleuth Wallet development, please visit our website +# or reach out to us at opensource@bitsleuth.ai diff --git a/.github/skills/FEEDBACK_EXAMPLES.md b/.github/skills/FEEDBACK_EXAMPLES.md new file mode 100644 index 00000000..b70ea04f --- /dev/null +++ b/.github/skills/FEEDBACK_EXAMPLES.md @@ -0,0 +1,329 @@ +# Feedback Loop Examples + +This document demonstrates the feedback loop system with realistic examples across different skills and scenarios. + +## Example 1: Frontend Design Skill - Success + +### Scenario +Agent uses frontend-design skill to create a wallet card component with smooth animations and proper touch feedback. + +### Feedback Entry (in `frontend-design/SKILL_MEMORY.md`) + +```markdown +### 2026-01-11 14:30 - SUCCESS + +**Skill Used**: frontend-design + +**Task Context**: +Created WalletCard component for displaying wallet balance, name, and color theme. +Needed to support press interactions for navigation to wallet details. + +**Outcome**: +Component implemented successfully with excellent user feedback. Animation feels +natural, touch targets are appropriate, and visual hierarchy is clear. Component +is now being reused across multiple screens. + +**What Worked Well**: +- Spring animation guidance (damping: 15, stiffness: 400) produced perfect feel +- 56pt minimum height recommendation ensured comfortable touch targets +- Platform.select() pattern for iOS/Android shadows worked flawlessly +- Haptic feedback on press adds premium feel (SKILL.md example was directly applicable) +- Border radius recommendation (16-24pt) looks modern and polished + +**What Didn't Work**: +- SKILL.md didn't mention handling of very long wallet names (truncation needed) +- No guidance on how to handle wallet colors with poor contrast against text +- Missing pattern for "press and hold" interactions (could be useful for quick actions) + +**Key Learnings**: +- Text.ellipsizeMode and numberOfLines are essential for mobile cards with user-generated content +- Need color contrast validation when users choose custom wallet colors +- Combining spring animations with haptic feedback creates highly satisfying interactions +- react-native-reanimated's useSharedValue + withSpring is more performant than Animated API + +**Recommended Updates**: +1. Add section to SKILL.md: "Handling User-Generated Content in Cards" + - Text truncation patterns + - Overflow handling techniques + - Testing with edge cases (very long names, emojis, special characters) +2. Add pattern: "Color Contrast Validation" + - How to ensure text remains readable on custom backgrounds + - Automatic text color adjustment (white/black) based on background luminance + - WCAG AA compliance checking +3. Add to "Modern 2025 Techniques": "Press and Hold Patterns" + - Long press gestures for contextual actions + - Example with react-native-gesture-handler + +**Impact Level**: MEDIUM +``` + +### How This Evolves the Skill + +After 2-3 more entries highlighting text truncation and color contrast issues, these patterns would be added to frontend-design/SKILL.md as validated best practices. + +--- + +## Example 2: Developer Guide Skill - Partial Success + +### Scenario +Agent uses developer-guide skill to implement a Bitcoin transaction fee estimation feature but encounters issues. + +### Feedback Entry (in `developer-guide/SKILL_MEMORY.md`) + +```markdown +### 2026-01-11 16:45 - PARTIAL + +**Skill Used**: developer-guide + +**Task Context**: +Implemented dynamic fee estimation for Bitcoin transactions using Esplora API. +Needed to provide users with Low/Medium/High fee options. + +**Outcome**: +Fee estimation works but required significant troubleshooting not covered by SKILL.md. +Initial implementation had rate limiting issues and didn't handle network failures gracefully. +Final solution works reliably but took longer than expected. + +**What Worked Well**: +- SKILL.md's Esplora API documentation was accurate +- Transaction Handling section correctly emphasized RBF support +- Bitcoin-specific guidelines on fee calculation were helpful +- Example code for building transactions was directly applicable + +**What Didn't Work**: +- SKILL.md mentioned "implement exponential backoff" but provided no example +- No guidance on caching fee estimates to reduce API calls +- Missing information about Esplora rate limits (important for production) +- No pattern for handling stale fee data (network offline, then online) +- Unclear which fee estimate endpoint to use (blocks vs. mempool) + +**Key Learnings**: +- Esplora API has undocumented rate limits (~300 requests per minute per IP) +- Fee estimates should be cached for 1-2 minutes to avoid excessive API calls +- Always provide fallback fee rates in case API is unreachable +- Mempool-based fee estimates are more accurate but more volatile than block-based +- Need retry logic with exponential backoff: 1s, 2s, 4s, 8s, then show error +- Users expect fee updates to be automatic but not too frequent (balance UX vs API load) + +**Recommended Updates**: +1. Add to "Network Interactions" section in SKILL.md: + - **"Esplora API Rate Limiting"** subsection + - Document known rate limits + - Caching strategies with AsyncStorage + - Example code for exponential backoff retry logic +2. Add to "Fee Estimation" section: + - **"Fee Estimate Caching"** pattern + - Cache duration recommendations (1-2 minutes for high priority, 5 minutes for low) + - Stale data handling (show cached with "updating..." indicator) + - Example implementation with react-query +3. Add code example: + ```typescript + // Exponential backoff retry helper + async function fetchWithRetry(url, maxRetries = 3) { + for (let i = 0; i < maxRetries; i++) { + try { + return await fetch(url); + } catch (error) { + if (i === maxRetries - 1) throw error; + await new Promise(r => setTimeout(r, 1000 * Math.pow(2, i))); + } + } + } + ``` + +**Impact Level**: HIGH +``` + +### How This Evolves the Skill + +This is a HIGH impact learning that directly addresses a gap causing development inefficiency. After one more similar experience, this would justify updating SKILL.md with: +- Concrete rate limiting documentation +- Example retry logic code +- Caching patterns + +--- + +## Example 3: WebApp Testing Skill - Failure + +### Scenario +Agent uses webapp-testing skill to test biometric authentication but encounters platform-specific issues. + +### Feedback Entry (in `webapp-testing/SKILL_MEMORY.md`) + +```markdown +### 2026-01-11 12:15 - FAILURE + +**Skill Used**: webapp-testing + +**Task Context**: +Attempted to test Face ID authentication flow on iOS simulator using guidance from SKILL.md. +Goal was to verify authentication works before deploying to production. + +**Outcome**: +Testing failed. Simulator-based biometric tests gave false positives—all tests passed +on simulator but failed on real device. SKILL.md guidance led to wasted time testing +in an environment that can't properly validate biometric functionality. + +**What Worked Well**: +- SKILL.md correctly listed the test script: `node scripts/test-biometric.js` +- Metro bundler troubleshooting steps were accurate +- Firebase test scripts worked as documented + +**What Didn't Work**: +- SKILL.md states "For device testing: Expo Go app or configured simulator/emulator" + This is misleading for biometric testing—simulator can't properly test Face ID/Touch ID +- "Simulators have limitations" note is buried in section 3.2 and not emphasized enough +- No clear warning: "MUST use physical device for biometric testing" +- Missing guidance on how to test biometric enrollment vs. authentication +- No mention of iOS Simulator's "Enrolled" vs "Matching/Non-matching" Face ID simulation (unreliable) + +**Key Learnings**: +- **iOS Simulator biometric testing is fundamentally unreliable**—it simulates success/failure + but doesn't validate actual biometric flow, enrollment, or platform-specific edge cases +- **Android emulator** has similar issues—can simulate fingerprint but not real auth +- Physical device testing is **mandatory** for biometric features, not optional +- Should test on multiple devices (iPhone with Face ID vs Touch ID, Android with fingerprint) +- expo-local-authentication behaves differently on simulator vs. device (error codes differ) +- Need to test both: initial biometric setup AND subsequent authentication + +**Recommended Updates**: +1. Add **CRITICAL WARNING** to SKILL.md at the top of "Mobile App Testing" section: + ``` + ⚠️ **CRITICAL**: Biometric authentication, camera, and other hardware features + MUST be tested on physical devices. Simulators/emulators provide unreliable + results and will give false positives. Always test on real hardware before + considering the feature validated. + ``` +2. Update "Prerequisites" section: + - Change "Expo Go app or configured simulator/emulator" to explicitly note limitations + - Add: "Physical iOS and Android devices REQUIRED for testing native features" +3. Add new section: "Testing Biometric Authentication" with: + - Device requirements (iOS with Face ID, iOS with Touch ID, Android with fingerprint) + - Enrollment testing steps + - Authentication testing steps + - Edge cases to test (no biometrics enrolled, biometrics disabled, etc.) + - Platform-specific differences +4. Remove or qualify any guidance suggesting simulators are sufficient for native feature testing + +**Impact Level**: HIGH +``` + +### How This Evolves the Skill + +This is a HIGH impact failure that prevented proper testing and could have led to production bugs. +This justifies **immediate update** to SKILL.md to add critical warnings and clearer guidance +about device requirements for biometric testing. + +--- + +## Example 4: Multiple Skills - Pattern Recognition + +### Scenario +Over several weeks, multiple feedback entries across different skills all mention issues with Bitcoin address validation. + +### Pattern Observed + +**In developer-guide/SKILL_MEMORY.md:** +- 3 entries mention confusion about which address types to validate +- 2 entries note missing validation for testnet vs mainnet addresses +- 1 entry highlights bech32m (Taproot) addresses not covered + +**In frontend-design/SKILL_MEMORY.md:** +- 2 entries mention displaying address types differently (legacy, SegWit, Taproot) +- 1 entry notes user confusion when sending to unfamiliar address format + +**In webapp-testing/SKILL_MEMORY.md:** +- 2 entries document test failures due to incorrect address validation +- 1 entry shows QR code scanning accepting invalid addresses + +### Pattern Recognition Entry + +```markdown +### PATTERN IDENTIFIED - 2026-01-25 + +**Cross-Skill Pattern**: Bitcoin Address Validation Gaps + +**Evidence**: +9 feedback entries across 3 skills all point to inadequate Bitcoin address +validation guidance and implementation issues. + +**Common Issues**: +- Unclear which address types to support (P2PKH, P2SH, P2WPKH, P2WSH, P2TR) +- No validation examples for testnet vs mainnet +- Missing bech32m (Taproot) address support +- Inconsistent validation across send/receive/QR scanning flows +- UI doesn't help users understand address type differences + +**Impact**: +- Development time wasted on re-implementing validation +- Potential security risk (accepting invalid addresses) +- Poor UX (error messages unclear about why address rejected) + +**Recommended Actions**: + +1. **Update developer-guide/SKILL.md**: + - Add comprehensive "Bitcoin Address Validation" section + - Document all address types with regex/library validation examples + - Include testnet/mainnet differentiation + - Code examples using bitcoinjs-lib address validation + - Security considerations (avoid sending to wrong network) + +2. **Update frontend-design/SKILL.md**: + - Add "Displaying Bitcoin Addresses" pattern + - Visual differentiation for address types + - User education moments (tooltip/help text) + - Error message templates for validation failures + +3. **Update webapp-testing/SKILL.md**: + - Add "Testing Address Validation" section + - Test cases for each address type + - Negative test cases (invalid addresses, wrong network) + - QR code validation testing + +4. **Create Shared Resource**: + - Consider adding `docs/BITCOIN_ADDRESS_VALIDATION.md` as authoritative reference + - Link from all three skills + +**Impact Level**: HIGH (affects multiple skills, security implications) +**Action Required**: Update all three SKILL.md files with validated patterns +``` + +### How This Evolves Multiple Skills + +This cross-skill pattern justifies: +1. Immediate updates to all three SKILL.md files +2. Creation of shared reference documentation +3. Coordination to ensure consistent guidance across skills + +--- + +## Key Takeaways from Examples + +### 1. Feedback Quality Matters +- **Specific examples** > vague observations +- **Context** helps others understand the situation +- **Both success and failure** provide learning opportunities + +### 2. Impact Levels Guide Urgency +- **HIGH**: Security issues, repeated failures, critical gaps → fast action +- **MEDIUM**: Useful improvements, efficiency gains → wait for patterns +- **LOW**: Edge cases, minor refinements → accumulate before acting + +### 3. Patterns Emerge Over Time +- Single incidents → record but don't act +- 2-3 similar experiences → start to see pattern +- 5+ consistent reports → strong pattern, update SKILL.md + +### 4. Cross-Skill Insights +- Sometimes issues span multiple skills +- Pattern recognition across skills reveals systemic gaps +- Shared documentation may be needed for cross-cutting concerns + +### 5. Continuous Improvement +- Each feedback entry makes the next usage better +- SKILL_MEMORY.md is the "working memory" +- SKILL.md is the "long-term memory" (consolidated, validated) + +--- + +These examples demonstrate how the feedback loop transforms skills from static instructions into living, evolving systems that continuously improve based on real-world usage. diff --git a/.github/skills/FEEDBACK_LOOP_GUIDE.md b/.github/skills/FEEDBACK_LOOP_GUIDE.md new file mode 100644 index 00000000..b55846f3 --- /dev/null +++ b/.github/skills/FEEDBACK_LOOP_GUIDE.md @@ -0,0 +1,365 @@ +# Skills Feedback Loop System + +## Overview + +The Skills Feedback Loop System enables skills to learn and evolve based on actual usage outcomes. Instead of static instruction files, skills become living, adaptive systems that improve through reflection on successes and failures. + +## System Architecture + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Skill Usage Cycle │ +└─────────────────────────────────────────────────────────────┘ + │ + ▼ + ┌──────────────────────────────┐ + │ 1. Agent Invokes Skill │ + │ (developer-guide, │ + │ frontend-design, etc.) │ + └──────────────────────────────┘ + │ + ▼ + ┌──────────────────────────────┐ + │ 2. Skill Executes Task │ + │ (guided by SKILL.md) │ + └──────────────────────────────┘ + │ + ▼ + ┌──────────────────────────────┐ + │ 3. Outcome Observed │ + │ SUCCESS / FAILURE / │ + │ PARTIAL │ + └──────────────────────────────┘ + │ + ▼ + ┌──────────────────────────────┐ + │ 4. Reflection & Recording │ + │ - What worked? │ + │ - What didn't? │ + │ - What was learned? │ + └──────────────────────────────┘ + │ + ▼ + ┌──────────────────────────────┐ + │ 5. Record in SKILL_MEMORY │ + │ (structured feedback) │ + └──────────────────────────────┘ + │ + ▼ + ┌──────────────────────────────┐ + │ 6. Pattern Recognition │ + │ - Repeated successes │ + │ - Repeated failures │ + │ - Common gaps │ + └──────────────────────────────┘ + │ + ▼ + ┌──────────────────────────────┐ + │ 7. Skill Evolution │ + │ Update SKILL.md based │ + │ on validated patterns │ + └──────────────────────────────┘ + │ + ▼ + ┌──────────────────────────────┐ + │ 8. Improved Future Usage │ + │ (cycle continues) │ + └──────────────────────────────┘ +``` + +## File Structure + +Each skill has three key files: + +``` +.github/skills/[skill-name]/ +├── SKILL.md # Core skill instructions (edited carefully) +├── SKILL_MEMORY.md # Learning memory (frequently updated) +└── README.md # (optional) Skill overview +``` + +Plus a shared template: + +``` +.github/skills/ +└── FEEDBACK_TEMPLATE.md # Template for consistent feedback +``` + +### SKILL.md - The Core Instructions + +- **Purpose**: Contains the primary instructions and guidance for the skill +- **Update Frequency**: Infrequently, based on validated patterns from SKILL_MEMORY.md +- **Update Process**: Changes should be deliberate, based on strong evidence from multiple feedback entries +- **Stability**: Should remain relatively stable to avoid confusion + +### SKILL_MEMORY.md - The Learning Buffer + +- **Purpose**: Captures raw feedback, learnings, and observations from skill usage +- **Update Frequency**: After each significant skill usage +- **Update Process**: Agents append feedback entries following the template +- **Evolution**: Accumulates knowledge, identifies patterns, proposes SKILL.md updates + +### Relationship + +``` +SKILL.md ← validates and synthesizes ← SKILL_MEMORY.md ← records ← Actual Usage + │ │ + │ (slow, deliberate updates) │ (fast, continuous recording) + │ │ + └─── guides ──────────────────────────────┘ +``` + +## How Agents Use This System + +### During Skill Execution + +1. **Read SKILL.md**: Get core instructions for the task +2. **Read SKILL_MEMORY.md**: Check recent learnings and known patterns +3. **Execute Task**: Apply guidance from both files +4. **Observe Outcome**: Success, failure, or partial success? + +### After Skill Execution + +1. **Reflect on Outcome**: + - What was the task? + - What worked well? + - What didn't work? + - What was learned? + +2. **Record in SKILL_MEMORY.md**: + - Add a feedback entry to the Feedback Log section + - Use the template format for consistency + - Be specific with examples and observations + - Assign impact level (HIGH/MEDIUM/LOW) + +3. **Look for Patterns** (if multiple entries exist): + - Do you see repeated successes or failures? + - Are there common gaps in the skill's coverage? + - Should anything be elevated to SKILL.md? + +4. **Propose Updates** (if warranted): + - Add specific recommendations to "Pending SKILL.md Updates" + - Don't edit SKILL.md directly yet—let patterns accumulate + - High-impact learnings may warrant faster updates + +### When to Update SKILL.md + +Update SKILL.md when: +- **Strong Pattern Emerges**: Multiple feedback entries point to the same issue/success +- **Critical Gap Found**: Missing guidance causes repeated failures +- **Best Practice Validated**: A technique succeeds consistently across different contexts +- **Ecosystem Changes**: React Native, Expo, Bitcoin libraries evolve +- **Security Issue**: Any security-related learning should be promoted immediately + +Do NOT update SKILL.md based on: +- Single isolated incidents (unless security-critical) +- Unvalidated hunches or theories +- Temporary workarounds +- Personal preferences without evidence + +## Feedback Entry Template + +Reference `.github/skills/FEEDBACK_TEMPLATE.md` for the complete template. Key components: + +```markdown +### [DATE] - [SUCCESS/FAILURE/PARTIAL] + +**Skill Used**: [skill-name] + +**Task Context**: +[Brief description] + +**Outcome**: +[What happened] + +**What Worked Well**: +[Effective techniques] + +**What Didn't Work**: +[Issues, gaps, errors] + +**Key Learnings**: +[Insights gained] + +**Recommended Updates**: +[Specific SKILL.md improvements] + +**Impact Level**: [HIGH/MEDIUM/LOW] +``` + +## Example Workflow + +### Example: Frontend Design Skill + +**Scenario**: Agent uses frontend-design skill to create a new transaction details screen. + +**Step 1 - Before**: Agent reads `SKILL.md` and `SKILL_MEMORY.md` +- SKILL.md provides: Typography scale, color systems, animation guidelines +- SKILL_MEMORY.md shows: Recent pattern that users expect haptic feedback on copy actions + +**Step 2 - During**: Agent implements the screen +- Applies SKILL.md guidance on layout and visual design +- Incorporates SKILL_MEMORY.md insight about haptic feedback for copy buttons + +**Step 3 - After**: Agent reflects on outcome + +The implementation worked well overall, but: +- Typography recommendations were perfect for titles but body text at 16pt felt cramped for transaction hashes +- Haptic feedback was well-received +- Discovered that monospace fonts are essential for transaction hashes (not mentioned in SKILL.md) + +**Step 4 - Record**: Agent adds to `frontend-design/SKILL_MEMORY.md`: + +```markdown +### 2026-01-11 18:30 - SUCCESS + +**Skill Used**: frontend-design + +**Task Context**: +Created transaction details screen with hash display, amount, confirmations, timestamp. + +**Outcome**: +Screen implemented successfully with positive user feedback. Visual hierarchy clear, +interactions smooth. Transaction hash display needed specific considerations not in SKILL.md. + +**What Worked Well**: +- Typography scale worked perfectly for titles and labels +- Spring animations for screen transitions felt natural +- Color system provided good contrast for transaction states (pending/confirmed/failed) +- Haptic feedback on copy actions (from previous SKILL_MEMORY insight) + +**What Didn't Work**: +- Body text size (16pt) felt cramped for 64-character transaction hashes +- No guidance in SKILL.md about monospace font requirements for technical data +- Missing pattern for "copy to clipboard" visual feedback + +**Key Learnings**: +- Transaction hashes, addresses, and other technical Bitcoin data MUST use monospace fonts +- Technical data benefits from slightly smaller font size (14pt) to fit more characters +- Copy actions should have: 1) haptic feedback, 2) visual confirmation, 3) temporary state change +- Bitcoin data has unique display requirements not covered by general mobile design patterns + +**Recommended Updates**: +1. Add section to SKILL.md: "Displaying Technical/Monospace Data" + - When to use monospace fonts + - Recommended size adjustments for long technical strings + - Examples: transaction hashes, addresses, private keys +2. Add pattern: "Copy to Clipboard Interactions" + - Haptic + visual + temporal feedback + - Example implementation with react-native-reanimated +3. Update typography guidance to note exceptions for technical data + +**Impact Level**: MEDIUM +``` + +**Step 5 - Pattern Recognition**: +If future entries also highlight monospace font needs, this becomes a strong pattern worthy of SKILL.md update. + +**Step 6 - Eventual SKILL.md Update**: +After 3-4 similar feedback entries about technical data display, update SKILL.md with new section on monospace typography for technical content. + +## Benefits of This System + +### 1. Continuous Improvement +- Skills get better with every use +- Learnings compound over time +- Agents benefit from collective experience + +### 2. Evidence-Based Evolution +- Changes based on real outcomes, not speculation +- Patterns validated through multiple uses +- Strong signal-to-noise ratio + +### 3. Institutional Memory +- Knowledge persists across agent sessions +- No need to re-learn the same lessons +- Historical context preserved + +### 4. Balanced Stability +- SKILL.md stays stable (reduces confusion) +- SKILL_MEMORY.md captures variation (allows exploration) +- Updates happen when justified by evidence + +### 5. Collaborative Learning +- Multiple agents contribute to the same skills +- Diverse perspectives improve coverage +- Cross-pollination of insights + +## Best Practices + +### For Recording Feedback + +**DO**: +- ✅ Record feedback promptly after skill usage +- ✅ Be specific with examples and context +- ✅ Include both successes and failures +- ✅ Link to concrete artifacts (PRs, commits, files) +- ✅ Assign realistic impact levels +- ✅ Propose actionable updates + +**DON'T**: +- ❌ Record vague or generic observations +- ❌ Only record failures (successes teach too!) +- ❌ Copy-paste without customization +- ❌ Inflate impact levels +- ❌ Propose changes without evidence + +### For Updating Skills + +**DO**: +- ✅ Wait for patterns to emerge (unless security-critical) +- ✅ Validate across multiple contexts +- ✅ Update SKILL.md deliberately +- ✅ Document why updates were made +- ✅ Keep both files synchronized in purpose + +**DON'T**: +- ❌ Update SKILL.md based on single incidents +- ❌ Make massive changes all at once +- ❌ Delete SKILL_MEMORY.md entries (they're historical record) +- ❌ Ignore repeated patterns in SKILL_MEMORY.md +- ❌ Let SKILL_MEMORY.md grow indefinitely without synthesis + +## Maintenance Guidelines + +### Weekly Review (Recommended) +- Review new SKILL_MEMORY.md entries +- Identify emerging patterns +- Promote validated learnings to "Pending Updates" +- Discuss high-impact feedback + +### Monthly Synthesis (Recommended) +- Review "Pending Updates" across all skills +- Update SKILL.md files with validated improvements +- Archive old SKILL_MEMORY.md entries if needed (keep recent + important) +- Document changes in "Changelog of Memory-Driven Updates" + +### Quarterly Retrospective (Optional) +- Assess overall skill effectiveness +- Identify skills that need major revisions +- Consider new skills based on recurring needs +- Review and refine the feedback process itself + +## Metrics for Success + +Track these indicators to measure feedback loop effectiveness: + +1. **Feedback Volume**: Are agents consistently recording outcomes? +2. **Pattern Recognition**: Are patterns emerging from SKILL_MEMORY.md? +3. **SKILL.md Evolution**: Are skills being updated based on evidence? +4. **Task Success Rate**: Are skills becoming more effective over time? +5. **Coverage Gaps Closed**: Are identified gaps being addressed? + +## Future Enhancements + +Potential improvements to this system: + +- **Automated Pattern Detection**: Scripts to analyze SKILL_MEMORY.md and suggest updates +- **Cross-Skill Learning**: Insights from one skill informing another +- **Version Control**: Track SKILL.md changes alongside the feedback that triggered them +- **Impact Measurement**: Quantify improvement from skill updates +- **Search & Retrieval**: Tools to query historical feedback for similar scenarios + +--- + +**The skills feedback loop transforms static documentation into living, learning systems. Each iteration makes the skills—and the agents using them—more effective.** diff --git a/.github/skills/FEEDBACK_TEMPLATE.md b/.github/skills/FEEDBACK_TEMPLATE.md new file mode 100644 index 00000000..cab4a9c7 --- /dev/null +++ b/.github/skills/FEEDBACK_TEMPLATE.md @@ -0,0 +1,93 @@ +# Skill Feedback Entry Template + +Use this template to record skill usage outcomes for the learning feedback loop. + +## Feedback Entry Format + +```markdown +### [YYYY-MM-DD HH:MM] - [SUCCESS/FAILURE/PARTIAL] + +**Skill Used**: [skill-name] + +**Task Context**: +Brief description of the task the skill was used for. + +**Outcome**: +- What happened when the skill was invoked +- Were the expected results achieved? +- Any unexpected behaviors or results + +**What Worked Well**: +- Techniques/approaches that were effective +- Instructions that were clear and helpful +- Successful patterns that should be reinforced + +**What Didn't Work**: +- Instructions that were unclear or misleading +- Gaps in the skill's knowledge or coverage +- Errors or inefficiencies in the approach + +**Key Learnings**: +- Insights gained from this usage +- Patterns to remember for future tasks +- Specific improvements needed in the skill + +**Recommended Updates**: +- Specific sections of SKILL.md that should be updated +- New examples or patterns to add +- Clarifications or corrections needed + +**Impact Level**: [HIGH/MEDIUM/LOW] +- HIGH: Critical learning that should immediately influence the skill +- MEDIUM: Useful insight that improves the skill +- LOW: Minor observation or edge case +``` + +## Usage Guidelines + +1. **Record After Each Significant Skill Usage**: Document outcomes when a skill is invoked for a meaningful task +2. **Be Specific**: Include concrete examples, not vague observations +3. **Focus on Actionable Insights**: What can be learned and applied to future tasks? +4. **Consider Both Success and Failure**: Both teach valuable lessons +5. **Link to Context**: Reference PR numbers, issue numbers, or specific commits when relevant + +## Example Entry + +```markdown +### 2026-01-11 17:00 - SUCCESS + +**Skill Used**: frontend-design + +**Task Context**: +Created a new wallet selection screen with card-based layout and smooth transitions. + +**Outcome**: +Successfully implemented a modern, polished wallet selection interface with: +- Card-based layout with proper shadows +- Spring-based animations on card press +- Platform-specific touch feedback +- Proper safe area handling + +**What Worked Well**: +- The gradient guidance in SKILL.md was clear and effective +- Typography scale recommendations produced readable, hierarchical text +- react-native-reanimated examples were directly applicable +- Haptic feedback integration worked seamlessly + +**What Didn't Work**: +- SKILL.md didn't mention handling of long wallet names (overflow/truncation) +- Missing guidance on empty states for wallet lists +- No specific examples for grid vs list layout decisions + +**Key Learnings**: +- Mobile card layouts benefit from consistent 16-24pt spacing +- Users expect immediate haptic feedback on interactive elements +- Empty states are critical for good UX but often overlooked + +**Recommended Updates**: +1. Add section on text overflow handling in mobile cards +2. Include empty state design patterns (illustrations, CTAs) +3. Add decision matrix for grid vs list layouts based on content density + +**Impact Level**: MEDIUM +``` diff --git a/.github/skills/GETTING_STARTED.md b/.github/skills/GETTING_STARTED.md new file mode 100644 index 00000000..9ceefe7a --- /dev/null +++ b/.github/skills/GETTING_STARTED.md @@ -0,0 +1,241 @@ +# Getting Started with Skills Feedback Loop + +**Quick start guide for agents to begin using the feedback loop system immediately.** + +## What Is This? + +The Skills Feedback Loop is a self-improving knowledge system. When you use a skill (like `developer-guide`, `frontend-design`, or `webapp-testing`), you record what worked and what didn't. Over time, skills learn from these experiences and become more effective. + +## Quick Start (3 Steps) + +### Step 1: Use a Skill + +When you need to perform a task, check if a skill can help: + +```bash +# Available skills: +.github/skills/developer-guide/ # React Native, Bitcoin, architecture +.github/skills/frontend-design/ # Mobile UI/UX, design patterns +.github/skills/webapp-testing/ # Testing, debugging, workflows +``` + +**Before using:** Read both files: +1. `SKILL.md` - Core instructions +2. `SKILL_MEMORY.md` - Recent learnings + +### Step 2: Complete Your Task + +Apply the guidance and pay attention to: +- What techniques worked well +- What was unclear or missing +- What problems you encountered +- What you learned + +### Step 3: Record Feedback (5 minutes) + +After completing your task, add an entry to `SKILL_MEMORY.md`: + +Open the file: +```bash +.github/skills/[skill-name]/SKILL_MEMORY.md +``` + +Add to the **Feedback Log** section: + +```markdown +### 2026-01-11 18:30 - SUCCESS + +**Skill Used**: frontend-design + +**Task Context**: +Created wallet card component with balance and tap interaction. + +**Outcome**: +Component works great. Spring animations feel natural, haptic feedback +is perfect. One issue: long wallet names overflow the card. + +**What Worked Well**: +- Spring animation guidance (damping: 15, stiffness: 400) +- Haptic feedback example was directly applicable +- Touch target size recommendations (56pt min) + +**What Didn't Work**: +- No guidance on text truncation for long user-generated names +- Missing color contrast validation for custom backgrounds + +**Key Learnings**: +- Always use Text.ellipsizeMode for user-generated content +- Custom wallet colors need contrast validation for readability +- react-native-reanimated is much better than Animated API + +**Recommended Updates**: +1. Add "Handling User-Generated Content in Cards" section +2. Add color contrast validation pattern +3. Include text truncation examples + +**Impact Level**: MEDIUM +``` + +**That's it!** You've contributed to making the skill better. + +## What Happens Next? + +### Your Feedback is Valuable + +1. **Immediate**: Other agents can read your feedback in `SKILL_MEMORY.md` +2. **Short-term**: If 2-3 agents report the same issue, a pattern emerges +3. **Long-term**: Validated patterns get promoted to `SKILL.md` as improved guidance + +### You Benefit Too + +Next time you (or another agent) use the skill: +- `SKILL_MEMORY.md` shows recent learnings from others +- `SKILL.md` has been improved based on validated patterns +- You avoid problems others already encountered + +## Impact Levels Explained + +**HIGH** - Needs fast action: +- Security vulnerabilities +- Repeated failures causing significant delays +- Critical gaps in skill coverage + +**MEDIUM** - Wait for pattern (3+ similar reports): +- Useful improvements +- Efficiency gains +- Missing examples or clarifications + +**LOW** - Accumulate (5+ reports needed): +- Edge cases +- Minor refinements +- Nice-to-have additions + +## Common Questions + +### Q: How long should I spend on feedback? + +**A:** 3-5 minutes. Be brief but specific. A few concrete examples beat lengthy vague observations. + +### Q: Should I record every single skill usage? + +**A:** Record significant uses where you learned something or encountered issues. Skip trivial or repeated tasks. + +### Q: What if I'm not sure if something should be in SKILL.md? + +**A:** Record it in `SKILL_MEMORY.md` with your best impact level guess. The pattern recognition process will determine if it's worth promoting. + +### Q: Can I update SKILL.md directly? + +**A:** Generally no. Let feedback accumulate and patterns emerge first. Exception: security issues get immediate updates. + +### Q: What if I disagree with existing guidance? + +**A:** Record your experience in `SKILL_MEMORY.md`. If your approach succeeds and others validate it, the guidance will evolve. + +## Examples + +### Example 1: Quick Success + +You used `developer-guide` to implement Bitcoin transaction signing. Everything worked perfectly following the examples. + +**Do this:** +```markdown +### 2026-01-11 - SUCCESS + +**Skill Used**: developer-guide +**Task Context**: Implemented transaction signing with bitcoinjs-lib +**Outcome**: Perfect! Examples were clear and complete. +**What Worked Well**: Step-by-step signing example, error handling guidance +**What Didn't Work**: N/A +**Key Learnings**: Following the pattern exactly = zero issues +**Recommended Updates**: None needed +**Impact Level**: LOW +``` + +**Why record a success?** It validates that the guidance is working. If many agents succeed with the same guidance, we know it's good. + +### Example 2: Partial Success with Learning + +You used `frontend-design` to create a screen. Design looks good but you discovered the guidance on animations was unclear. + +**Do this:** +```markdown +### 2026-01-11 - PARTIAL + +**Skill Used**: frontend-design +**Task Context**: Created transaction history screen with animations +**Outcome**: Screen works but animation setup took 2 hours (should've been 30 min) +**What Worked Well**: Layout guidance, color system +**What Didn't Work**: Animation example assumed knowledge of Reanimated v4 API +**Key Learnings**: Need clearer imports and hook setup for animations +**Recommended Updates**: Add complete animation example with all imports +**Impact Level**: MEDIUM +``` + +### Example 3: Clear Failure + +You used `webapp-testing` to test biometrics. Simulator tests gave false positives; real device showed the failures. + +**Do this:** +```markdown +### 2026-01-11 - FAILURE + +**Skill Used**: webapp-testing +**Task Context**: Tested Face ID authentication flow +**Outcome**: Tests passed on simulator but failed on device. Wasted 3 hours. +**What Worked Well**: Metro bundler troubleshooting section +**What Didn't Work**: Guidance said "simulator or device" for biometric testing +**Key Learnings**: Biometric testing REQUIRES physical device. Simulators unreliable. +**Recommended Updates**: Add critical warning: biometric features MUST test on real devices +**Impact Level**: HIGH +``` + +## Resources + +| Document | Purpose | When to Use | +|----------|---------|-------------| +| `QUICK_REFERENCE.md` (this file) | Get started quickly | First time using system | +| `FEEDBACK_TEMPLATE.md` | Feedback entry format | When recording feedback | +| `FEEDBACK_EXAMPLES.md` | Realistic examples | Need inspiration for entries | +| `FEEDBACK_LOOP_GUIDE.md` | Complete system guide | Deep dive into how it works | +| `VISUAL_ARCHITECTURE.md` | System diagrams | Understanding the architecture | +| `README.md` | Skills directory overview | High-level understanding | + +## Best Practices + +### ✅ DO: +- Record feedback promptly (while details are fresh) +- Be specific with examples +- Include both successes and failures +- Assign realistic impact levels +- Propose actionable improvements + +### ❌ DON'T: +- Write vague observations ("it was hard") +- Only record failures (successes matter too!) +- Inflate impact levels +- Make changes to SKILL.md without pattern validation +- Skip recording significant learnings + +## The Bigger Picture + +Every feedback entry you write: +- ✨ Helps the next agent work more efficiently +- 📚 Builds institutional knowledge +- 🎯 Identifies gaps in guidance +- 🔄 Drives continuous improvement +- 🤝 Creates collective intelligence + +**Your 5 minutes of reflection can save hours for others.** + +--- + +## Ready to Start? + +1. Pick a skill relevant to your task +2. Read `SKILL.md` and `SKILL_MEMORY.md` +3. Complete your task +4. Record your experience (use template above) +5. Continue your work + +**That's all there is to it. Welcome to the feedback loop!** 🎉 diff --git a/.github/skills/QUICK_REFERENCE.md b/.github/skills/QUICK_REFERENCE.md new file mode 100644 index 00000000..c60e7bee --- /dev/null +++ b/.github/skills/QUICK_REFERENCE.md @@ -0,0 +1,135 @@ +# Skill Feedback Loop - Quick Reference + +**Quick guide for agents using the skills feedback loop system.** + +## TL;DR + +**Before** using a skill: Read both `SKILL.md` and `SKILL_MEMORY.md` +**After** using a skill: Record your experience in `SKILL_MEMORY.md` + +## Using a Skill + +### 1. Preparation +```bash +# Read core instructions +.github/skills/[skill-name]/SKILL.md + +# Check recent learnings +.github/skills/[skill-name]/SKILL_MEMORY.md +``` + +### 2. Execution +- Apply guidance from SKILL.md +- Consider patterns from SKILL_MEMORY.md +- Pay attention to what works and what doesn't + +### 3. Recording Feedback + +Add to `SKILL_MEMORY.md` → Feedback Log section: + +```markdown +### [DATE] - [SUCCESS/FAILURE/PARTIAL] + +**Skill Used**: [skill-name] +**Task Context**: [Brief description of task] +**Outcome**: [What happened] +**What Worked Well**: [Effective techniques] +**What Didn't Work**: [Issues, gaps, errors] +**Key Learnings**: [Insights gained] +**Recommended Updates**: [Specific SKILL.md improvements] +**Impact Level**: [HIGH/MEDIUM/LOW] +``` + +## Impact Levels + +- **HIGH**: Security issues, repeated failures, critical gaps → Fast action needed +- **MEDIUM**: Useful improvements, efficiency gains → Wait for patterns +- **LOW**: Edge cases, minor refinements → Accumulate before acting + +## When to Update SKILL.md + +✅ **DO Update** when: +- Strong pattern emerges (3+ similar feedback entries) +- Critical gap causes repeated failures +- Best practice validated across contexts +- Security issue discovered (immediate) + +❌ **DON'T Update** based on: +- Single isolated incidents (unless security-critical) +- Unvalidated hunches +- Temporary workarounds +- Personal preferences + +## File Relationships + +``` +SKILL.md ← Long-term memory (stable, validated) + ↑ + │ (patterns emerge) + │ +SKILL_MEMORY.md ← Working memory (dynamic, evolving) + ↑ + │ (feedback recorded) + │ +Your Experience ← Actual skill usage +``` + +## Available Skills + +- **developer-guide**: React Native/Expo, Bitcoin, cryptography, architecture +- **frontend-design**: Mobile UI/UX, design patterns, animations +- **webapp-testing**: Testing, debugging, iOS/Android workflows + +## Resources + +- **Full Guide**: `.github/skills/FEEDBACK_LOOP_GUIDE.md` +- **Examples**: `.github/skills/FEEDBACK_EXAMPLES.md` +- **Template**: `.github/skills/FEEDBACK_TEMPLATE.md` +- **AGENTS.md**: Main agent documentation (feedback loop section) + +## Example Feedback Entry + +```markdown +### 2026-01-11 18:30 - SUCCESS + +**Skill Used**: frontend-design + +**Task Context**: +Created wallet card component with balance display and tap interaction. + +**Outcome**: +Successfully implemented with spring animations and haptic feedback. +Users reported it feels smooth and responsive. + +**What Worked Well**: +- Spring animation guidance (damping: 15, stiffness: 400) was perfect +- Haptic feedback on press adds premium feel +- 56pt minimum height ensured comfortable touch targets + +**What Didn't Work**: +- No guidance on handling very long wallet names (needed truncation) +- Missing pattern for color contrast validation on custom backgrounds + +**Key Learnings**: +- Text truncation is essential for mobile cards with user content +- Need to ensure text remains readable on custom wallet colors +- Combining spring animations + haptics creates delightful interactions + +**Recommended Updates**: +1. Add "Handling User-Generated Content in Cards" section +2. Add color contrast validation pattern +3. Include text truncation examples + +**Impact Level**: MEDIUM +``` + +## Remember + +🧠 **Every skill usage is a learning opportunity** +📝 **Record outcomes to help future agents** +📈 **Skills improve through your feedback** +🤝 **Contribute to collective intelligence** + +--- + +**The more you contribute, the better the skills become.** diff --git a/.github/skills/README.md b/.github/skills/README.md new file mode 100644 index 00000000..b26beb1b --- /dev/null +++ b/.github/skills/README.md @@ -0,0 +1,126 @@ +# Skills Directory + +This directory contains specialized agent skills for BitSleuth Wallet development. Each skill is a domain expert with specific knowledge and capabilities. + +## Available Skills + +### 1. developer-guide +**Purpose**: Comprehensive technical guide for BitSleuth Wallet development +**Expertise**: React Native/Expo, Bitcoin protocol, cryptography, security best practices +**Use When**: Need guidance on architecture, conventions, Bitcoin operations, security + +### 2. frontend-design +**Purpose**: Create distinctive, production-grade mobile interfaces +**Expertise**: React Native UI/UX, mobile design patterns, animations, platform-specific design +**Use When**: Building screens, components, or user experiences that need exceptional design quality + +### 3. webapp-testing +**Purpose**: Testing and debugging React Native + Expo mobile applications +**Expertise**: Development server management, iOS/Android testing, debugging workflows +**Use When**: Testing app functionality, debugging UI behavior, verifying mobile-specific features + +## Skill Structure + +Each skill directory contains: + +``` +[skill-name]/ +├── SKILL.md # Core skill instructions and guidance +├── SKILL_MEMORY.md # Learning memory from actual usage +└── README.md # (optional) Skill overview +``` + +## Feedback Loop System + +Skills in this directory implement a **self-learning feedback loop**: + +1. **Skill Usage** → Agent invokes skill to complete a task +2. **Outcome** → Task succeeds, fails, or partially succeeds +3. **Reflection** → Agent reflects on what worked and what didn't +4. **Recording** → Agent logs experience in `SKILL_MEMORY.md` +5. **Pattern Recognition** → Patterns emerge from accumulated feedback +6. **Evolution** → `SKILL.md` is updated based on validated patterns + +### Key Files + +- **`SKILL.md`**: Core instructions (stable, updated deliberately) +- **`SKILL_MEMORY.md`**: Learning buffer (dynamic, updated frequently) +- **`FEEDBACK_TEMPLATE.md`**: Template for consistent feedback recording +- **`FEEDBACK_LOOP_GUIDE.md`**: Complete system documentation + +## How to Use Skills + +### As an Agent + +1. **Before**: Read both `SKILL.md` (core guidance) and `SKILL_MEMORY.md` (recent learnings) +2. **During**: Apply the skill's guidance to your task +3. **After**: Record your experience in `SKILL_MEMORY.md` following the template + +### Recording Feedback + +After using a skill, add an entry to its `SKILL_MEMORY.md`: + +```markdown +### [DATE] - [SUCCESS/FAILURE/PARTIAL] + +**Skill Used**: [skill-name] +**Task Context**: [What you were trying to do] +**Outcome**: [What happened] +**What Worked Well**: [Effective guidance] +**What Didn't Work**: [Gaps or issues] +**Key Learnings**: [Insights gained] +**Recommended Updates**: [Specific improvements] +**Impact Level**: [HIGH/MEDIUM/LOW] +``` + +See `FEEDBACK_TEMPLATE.md` for the complete template. + +## Updating Skills + +### Update SKILL_MEMORY.md + +- ✅ After each significant skill usage +- ✅ With specific, concrete observations +- ✅ Following the feedback template +- ✅ Including both successes and failures + +### Update SKILL.md + +Only when: +- ✅ Strong patterns emerge from multiple feedback entries +- ✅ Critical gaps are consistently identified +- ✅ Best practices are validated across contexts +- ✅ Ecosystem changes require updates +- ✅ Security issues are discovered (immediate) + +Do NOT update SKILL.md: +- ❌ Based on single incidents (unless security-critical) +- ❌ With unvalidated hunches or theories +- ❌ Using temporary workarounds +- ❌ Based on personal preference without evidence + +## Philosophy + +> **Skills are living, learning systems—not static documentation.** + +Every skill usage is an opportunity to learn and improve. By recording outcomes and identifying patterns, skills become more effective over time. This creates institutional memory that benefits all agents. + +## Resources + +- **Complete Guide**: See `FEEDBACK_LOOP_GUIDE.md` for full system documentation +- **Feedback Template**: See `FEEDBACK_TEMPLATE.md` for recording format +- **AGENTS.md**: See main agent documentation for integration with workflows + +## Contributing + +When creating new skills: + +1. Create a directory under `.github/skills/[skill-name]/` +2. Add `SKILL.md` with core instructions +3. Add `SKILL_MEMORY.md` using the template from existing skills +4. Document the skill's purpose and expertise clearly +5. Update this README with the new skill information + +--- + +**Remember**: The power of this system comes from consistent feedback recording and thoughtful pattern recognition. Your observations today make the skills better tomorrow. diff --git a/.github/skills/VISUAL_ARCHITECTURE.md b/.github/skills/VISUAL_ARCHITECTURE.md new file mode 100644 index 00000000..f6324650 --- /dev/null +++ b/.github/skills/VISUAL_ARCHITECTURE.md @@ -0,0 +1,520 @@ +# Skills Feedback Loop - Visual Architecture + +This document provides visual diagrams of the feedback loop system architecture. + +## System Overview Diagram + +``` +┌───────────────────────────────────────────────────────────────────────┐ +│ SKILLS FEEDBACK LOOP SYSTEM │ +│ Living, Self-Improving Knowledge Base │ +└───────────────────────────────────────────────────────────────────────┘ + + Agent Uses Skill + │ + ┌────────────────┴────────────────┐ + ▼ ▼ + ┌──────────────────────┐ ┌──────────────────────┐ + │ SKILL.md │ │ SKILL_MEMORY.md │ + │ │ │ │ + │ • Core Instructions │ │ • Recent Learnings │ + │ • Stable Guidance │ │ • Feedback Entries │ + │ • Validated Patterns │ │ • Emerging Patterns │ + │ │ │ • Pending Updates │ + │ [Long-term Memory] │ │ [Working Memory] │ + └──────────┬───────────┘ └──────────┬───────────┘ + │ │ + └───────────┬───────────────────┘ + │ + ▼ + ┌──────────────────┐ + │ Agent Executes │ + │ Task │ + └─────────┬────────┘ + │ + ┌───────────┴───────────┐ + │ │ + ▼ ▼ + ┌──────────────┐ ┌──────────────┐ + │ SUCCESS │ │ FAILURE │ + │ or │ │ or │ + │ PARTIAL │ │ PARTIAL │ + └──────┬───────┘ └──────┬───────┘ + │ │ + └───────────┬───────────┘ + │ + ▼ + ┌─────────────────────┐ + │ Agent Reflects: │ + │ • What worked? │ + │ • What didn't? │ + │ • What learned? │ + └──────────┬──────────┘ + │ + ▼ + ┌─────────────────────┐ + │ Record in │ + │ SKILL_MEMORY.md │ + │ (Feedback Entry) │ + └──────────┬──────────┘ + │ + ┌──────────┴──────────┐ + │ │ + Multiple uses accumulate │ + │ │ + ▼ ▼ + ┌────────────────────┐ ┌────────────────────┐ + │ Patterns Emerge │ │ Single Instance │ + │ │ │ (No pattern yet) │ + │ • Repeated success │ └────────────────────┘ + │ • Repeated failure │ + │ • Common gaps │ + └─────────┬──────────┘ + │ + ▼ + ┌────────────────────┐ + │ Pattern Validated │ + │ Across Multiple │ + │ Contexts │ + └─────────┬──────────┘ + │ + ▼ + ┌────────────────────┐ + │ Update SKILL.md │ + │ with Validated │ + │ Improvement │ + └─────────┬──────────┘ + │ + ▼ + ┌────────────────────┐ + │ Improved Guidance │ + │ for Future Uses │ + └────────────────────┘ + │ + └──────────────► (Cycle Continues) +``` + +## File Relationship Diagram + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ .github/skills/ │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ README.md ─────────────────┐ │ +│ FEEDBACK_TEMPLATE.md │ │ +│ FEEDBACK_LOOP_GUIDE.md ├──► Documentation & Guidance │ +│ FEEDBACK_EXAMPLES.md │ │ +│ QUICK_REFERENCE.md ────────┘ │ +│ │ +│ ┌────────────────────────────────────────────────────────┐ │ +│ │ developer-guide/ │ │ +│ │ │ │ +│ │ SKILL.md ◄──────────┐ │ │ +│ │ (Core Instructions) │ │ │ +│ │ │ │ │ +│ │ SKILL_MEMORY.md │ │ │ +│ │ (Learning Buffer) ───┘ │ │ +│ │ • Feedback entries │ │ +│ │ • Pattern recognition │ │ +│ │ • Pending updates │ │ +│ └────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌────────────────────────────────────────────────────────┐ │ +│ │ frontend-design/ │ │ +│ │ │ │ +│ │ SKILL.md ◄──────────┐ │ │ +│ │ (Core Instructions) │ │ │ +│ │ │ │ │ +│ │ SKILL_MEMORY.md │ │ │ +│ │ (Learning Buffer) ───┘ │ │ +│ │ • Design outcomes │ │ +│ │ • UI/UX learnings │ │ +│ │ • Platform insights │ │ +│ └────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌────────────────────────────────────────────────────────┐ │ +│ │ webapp-testing/ │ │ +│ │ │ │ +│ │ SKILL.md ◄──────────┐ │ │ +│ │ (Core Instructions) │ │ │ +│ │ │ │ │ +│ │ SKILL_MEMORY.md │ │ │ +│ │ (Learning Buffer) ───┘ │ │ +│ │ • Testing approaches │ │ +│ │ • Debug workflows │ │ +│ │ • Platform issues │ │ +│ └────────────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────┘ + + │ + ▼ + ┌────────────────────────┐ + │ AGENTS.md │ + │ │ + │ • Feedback loop guide │ + │ • Agent instructions │ + │ • Integration docs │ + └────────────────────────┘ + │ + ▼ + ┌────────────────────────┐ + │ docs/ │ + │ │ + │ SKILLS_FEEDBACK_LOOP_ │ + │ SUMMARY.md │ + │ │ + │ • Implementation │ + │ summary │ + │ • Benefits & metrics │ + └────────────────────────┘ +``` + +## Information Flow Diagram + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ INFORMATION FLOW │ +└──────────────────────────────────────────────────────────────────┘ + +SKILL USAGE CYCLE: + +Agent Task ──┐ + │ + ▼ + Read SKILL.md + (Get Core Guidance) + │ + ▼ + Read SKILL_MEMORY.md + (Check Recent Learnings) + │ + ▼ + Execute Task + (Apply Guidance) + │ + ▼ + Observe Outcome + (Success/Failure/Partial) + │ + ▼ + Reflect on Experience + (What worked? What didn't?) + │ + ▼ + Record in SKILL_MEMORY.md + (Structured Feedback Entry) + │ + └──────────┐ + │ + ▼ + SKILL_MEMORY.md + │ + │ (Accumulates over time) + │ + ┌─────────┴─────────┐ + │ │ + ▼ ▼ + No Pattern Yet Pattern Emerges + (Keep recording) (3+ similar entries) + │ + ▼ + Validate Pattern + (Multiple contexts) + │ + ▼ + Update SKILL.md + (Improve guidance) + │ + ▼ + Better Outcomes + (Next cycle) +``` + +## Feedback Entry Lifecycle + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ FEEDBACK ENTRY LIFECYCLE │ +└─────────────────────────────────────────────────────────────────┘ + +1. CREATION + ───────── + Agent completes task using skill + │ + ▼ + Creates feedback entry in SKILL_MEMORY.md + (Date, Context, Outcome, Learnings, Impact Level) + + +2. ACCUMULATION + ──────────── + Multiple feedback entries collected over time + │ + ▼ + Entry #1: Issue with fee estimation + Entry #2: Same issue with fee estimation + Entry #3: Fee estimation problem again + Entry #4: Different feature works well + Entry #5: Fee estimation still challenging + + +3. PATTERN RECOGNITION + ─────────────────── + Review SKILL_MEMORY.md for patterns + │ + ▼ + PATTERN IDENTIFIED: + - Fee estimation guidance inadequate + - 3+ entries report same issue + - HIGH impact on development time + + +4. VALIDATION + ────────── + Confirm pattern across different contexts + │ + ▼ + ✓ Multiple agents experienced it + ✓ Different use cases + ✓ Consistent feedback + ✓ Impact confirmed + + +5. SKILL EVOLUTION + ─────────────── + Update SKILL.md with improvement + │ + ▼ + Add: "Fee Estimation Best Practices" + - Concrete examples + - Retry logic + - Caching patterns + + +6. DOCUMENTATION + ───────────── + Document the change + │ + ▼ + Update "Changelog of Memory-Driven Updates" + in SKILL_MEMORY.md + + +7. VALIDATION OF FIX + ───────────────── + Future uses validate the improvement + │ + ▼ + New feedback entries show: + ✓ Fee estimation now easier + ✓ Fewer issues reported + ✓ Better outcomes +``` + +## Cross-Skill Pattern Recognition + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ CROSS-SKILL PATTERN RECOGNITION │ +└─────────────────────────────────────────────────────────────────┘ + +developer-guide/SKILL_MEMORY.md + │ + ├─ Entry: Bitcoin address validation unclear + ├─ Entry: Missing testnet address handling + ├─ Entry: Confusion about address types + │ + ▼ + Pattern: Address validation issues (3 entries) + + +frontend-design/SKILL_MEMORY.md + │ + ├─ Entry: How to display different address types? + ├─ Entry: User confusion with address formats + │ + ▼ + Pattern: Address display/UX issues (2 entries) + + +webapp-testing/SKILL_MEMORY.md + │ + ├─ Entry: Address validation tests failing + ├─ Entry: QR scanner accepting invalid addresses + │ + ▼ + Pattern: Testing address validation (2 entries) + + │ + │ (7 total entries across 3 skills) + ▼ + ┌───────────────────┐ + │ CROSS-SKILL │ + │ PATTERN │ + │ IDENTIFIED │ + │ │ + │ "Bitcoin Address │ + │ Validation" │ + │ │ + │ Impact: HIGH │ + └─────────┬─────────┘ + │ + ▼ + ┌───────────────────┐ + │ COORDINATED │ + │ UPDATES │ + └─────────┬─────────┘ + │ + ┌─────────────┼─────────────┐ + │ │ │ + ▼ ▼ ▼ + Update Update Update + developer- frontend- webapp- + guide design testing + SKILL.md SKILL.md SKILL.md + │ │ │ + └─────────────┼─────────────┘ + │ + ▼ + ┌───────────────────┐ + │ Possibly Create │ + │ Shared Resource: │ + │ │ + │ docs/BITCOIN_ │ + │ ADDRESS_ │ + │ VALIDATION.md │ + └───────────────────┘ +``` + +## Impact Level Decision Tree + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ IMPACT LEVEL DECISION TREE │ +└─────────────────────────────────────────────────────────────────┘ + +Feedback Entry Created + │ + ▼ +Is it a security issue? + │ + ┌────┴────┐ + │ │ + YES NO + │ │ + ▼ ▼ + Impact: Does it cause repeated failures? + HIGH │ + │ + ┌────┴────┐ + │ │ + YES NO + │ │ + ▼ ▼ + Impact: Is it a critical gap affecting + HIGH multiple developers? + │ + ┌────┴────┐ + │ │ + YES NO + │ │ + ▼ ▼ + Impact: Does it provide useful + HIGH improvement/efficiency gain? + │ + ┌────┴────┐ + │ │ + YES NO + │ │ + ▼ ▼ + Impact: Impact: + MEDIUM LOW + + +ACTION BASED ON IMPACT: + +HIGH Impact + │ + └─► • Immediate attention + • Update SKILL.md after 1-2 similar reports + • Document thoroughly + • Alert other agents + +MEDIUM Impact + │ + └─► • Wait for pattern (3+ entries) + • Validate across contexts + • Update SKILL.md when confirmed + • Standard documentation + +LOW Impact + │ + └─► • Accumulate feedback + • Wait for 5+ similar entries + • Update only if pattern persists + • May remain in SKILL_MEMORY only +``` + +## System Benefits Visualization + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ SYSTEM BENEFITS │ +└─────────────────────────────────────────────────────────────────┘ + +TIME ──────────────────────────────────────────────────────────► + +Without Feedback Loop: +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +Static SKILL.md + │ + ├─ Agent A struggles with issue + ├─ Agent B struggles with same issue + ├─ Agent C struggles with same issue + ├─ Documentation never improves + └─ Knowledge lost between sessions +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + + +With Feedback Loop: +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +Evolving SKILL.md + SKILL_MEMORY.md + │ + ├─ Agent A struggles, records feedback (Entry #1) + │ + ├─ Agent B struggles, records feedback (Entry #2) + │ + ├─ Pattern recognized after Entry #3 + │ + ├─ SKILL.md updated with solution + │ + ├─ Agent C succeeds easily (improved guidance) + │ + ├─ Agent D succeeds easily (improved guidance) + │ + └─ Continuous improvement, knowledge persists +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + + +Efficiency Gains: + + Task Success Rate + ↑ + │ ┌──────────── + │ ┌──┘ (Skills improve) + │ ┌────┘ + │ ┌────┘ + │ ┌────┘ (Patterns identified) + │ ┌────┘ + │ ┌────┘ (Feedback accumulates) + │ ┌────┘ + │─────┘ (Initial state) + │ + └─────────────────────────────────────────────────────► Time +``` + +--- + +These diagrams illustrate how the Skills Feedback Loop System creates a self-improving knowledge base through structured feedback collection, pattern recognition, and evidence-based evolution. diff --git a/.github/skills/developer-guide/SKILL_MEMORY.md b/.github/skills/developer-guide/SKILL_MEMORY.md new file mode 100644 index 00000000..af21242f --- /dev/null +++ b/.github/skills/developer-guide/SKILL_MEMORY.md @@ -0,0 +1,74 @@ +# Developer Guide Skill Memory + +This file captures learnings and feedback from using the developer-guide skill. It serves as a living memory that informs future updates to SKILL.md. + +## Purpose + +The developer-guide skill provides comprehensive technical guidance for BitSleuth Wallet development. This memory file tracks: +- Which guidance was most/least helpful +- Gaps discovered during actual development +- Common pitfalls and their solutions +- Patterns that emerge across multiple uses + +## Core Principles + +These principles guide how this skill evolves: + +1. **Accuracy Over Comprehensiveness**: Better to have correct, focused guidance than incomplete coverage +2. **Real-World Validation**: Only include patterns that have been validated in actual development +3. **Bitcoin Security First**: Any guidance touching cryptography or key management requires extra scrutiny +4. **Platform-Specific Reality**: iOS and Android often behave differently; acknowledge both + +## Feedback Log + +### Template for New Entries +``` +[YYYY-MM-DD] - [SUCCESS/FAILURE/PARTIAL] - [Impact: HIGH/MEDIUM/LOW] +Context: [What task was being performed] +Outcome: [What happened] +Learning: [What we learned] +Action: [How SKILL.md should be updated, if at all] +``` + +### Entries + +--- + +**Awaiting first feedback entry...** + +When the developer-guide skill is used, outcomes should be recorded here following the template above. Over time, patterns will emerge that should be synthesized into updates to SKILL.md. + +--- + +## Pattern Recognition + +As feedback accumulates, look for: +- **Repeated Successes**: Guidance that consistently helps → reinforce in SKILL.md +- **Repeated Failures**: Guidance that misleads → correct or remove from SKILL.md +- **Common Gaps**: Questions not answered by current SKILL.md → add new sections +- **Evolving Best Practices**: As React Native/Expo/Bitcoin ecosystem evolves → update guidance + +## Pending SKILL.md Updates + +Track recommended updates here before they're applied: + +**None yet** - Will be populated based on feedback patterns + +## Changelog of Memory-Driven Updates + +Track when learnings from this memory file resulted in SKILL.md changes: + +**None yet** - This is the initial version + +--- + +## Usage Notes for Agents + +When you use the developer-guide skill: +1. After completion, reflect on the outcome (success/failure/partial) +2. Record significant learnings in the Feedback Log section above +3. If you notice patterns across multiple entries, add them to Pattern Recognition +4. Propose specific SKILL.md updates in the Pending Updates section +5. Do NOT directly edit SKILL.md—let patterns accumulate first + +The skill memory acts as a buffer: collect experiences, identify patterns, then update the core skill with validated improvements. diff --git a/.github/skills/frontend-design/SKILL_MEMORY.md b/.github/skills/frontend-design/SKILL_MEMORY.md new file mode 100644 index 00000000..1d6ab232 --- /dev/null +++ b/.github/skills/frontend-design/SKILL_MEMORY.md @@ -0,0 +1,91 @@ +# Frontend Design Skill Memory + +This file captures learnings and feedback from using the frontend-design skill. It serves as a living memory that informs future updates to SKILL.md. + +## Purpose + +The frontend-design skill guides creation of distinctive, production-grade mobile interfaces for React Native + Expo. This memory file tracks: +- Design patterns that resonate with users +- Implementation challenges and solutions +- Platform-specific quirks discovered +- Visual trends and techniques that prove effective + +## Core Principles + +These principles guide how this skill evolves: + +1. **Design Intent Over Trends**: Thoughtful design decisions beat following trends +2. **Performance Matters**: Beautiful but laggy UI fails; 60fps is non-negotiable +3. **Platform Native First**: Respect iOS/Android conventions before breaking them +4. **Accessibility is Design**: Touch targets, contrast, screen readers are core design constraints +5. **Real Device Testing**: Simulators lie; test on actual phones + +## Feedback Log + +### Template for New Entries +``` +[YYYY-MM-DD] - [SUCCESS/FAILURE/PARTIAL] - [Impact: HIGH/MEDIUM/LOW] +Context: [What UI/screen was being designed] +Outcome: [What was created, how it performed] +Learning: [Design insights gained] +Action: [How SKILL.md should be updated, if at all] +``` + +### Entries + +--- + +**Awaiting first feedback entry...** + +When the frontend-design skill is used to create mobile UIs, outcomes should be recorded here. Track what works, what doesn't, and how mobile design thinking evolves. + +--- + +## Pattern Recognition + +As feedback accumulates, look for: +- **Delightful Patterns**: UI techniques that consistently impress → promote in SKILL.md +- **Performance Pitfalls**: Design choices that cause jank → warn against in SKILL.md +- **Platform Friction**: Patterns that fight iOS/Android conventions → document better approaches +- **Accessibility Wins**: Techniques that improve usability → emphasize in SKILL.md +- **2025 Evolution**: As mobile design evolves → keep skill current + +## Design Decisions Archive + +Track significant design decisions and their outcomes: + +**None yet** - Will be populated with real design choices and results + +## Pending SKILL.md Updates + +Track recommended updates here before they're applied: + +**None yet** - Will be populated based on feedback patterns + +## Changelog of Memory-Driven Updates + +Track when learnings from this memory file resulted in SKILL.md changes: + +**None yet** - This is the initial version + +--- + +## Usage Notes for Agents + +When you use the frontend-design skill: +1. After implementing a UI, document how well the guidance worked +2. Note any design decisions that deviated from SKILL.md and why +3. Record user feedback or performance issues if available +4. Track which examples/patterns from SKILL.md were most useful +5. Propose specific improvements to design guidance based on real outcomes + +## Mobile-Specific Learnings to Watch For + +Pay special attention to feedback about: +- **Touch Interactions**: Did 44pt minimum feel right? Any gesture conflicts? +- **Typography**: Were the size recommendations readable on actual devices? +- **Animations**: Did spring physics feel natural? Any jank detected? +- **Dark Mode**: Did the color systems work well in both themes? +- **Platform Differences**: Where did iOS and Android require different approaches? + +The skill memory evolves mobile design thinking through practice, not theory. diff --git a/.github/skills/webapp-testing/SKILL_MEMORY.md b/.github/skills/webapp-testing/SKILL_MEMORY.md new file mode 100644 index 00000000..6c33fa5b --- /dev/null +++ b/.github/skills/webapp-testing/SKILL_MEMORY.md @@ -0,0 +1,97 @@ +# WebApp Testing Skill Memory + +This file captures learnings and feedback from using the webapp-testing skill. It serves as a living memory that informs future updates to SKILL.md. + +## Purpose + +The webapp-testing skill enables testing and debugging of React Native + Expo mobile apps. This memory file tracks: +- Testing approaches that catch bugs effectively +- Common issues and their reliable solutions +- Platform-specific testing challenges +- Workflow improvements discovered through use + +## Core Principles + +These principles guide how this skill evolves: + +1. **Real Devices Reveal Truth**: Emulators miss native module bugs +2. **Reproducibility Matters**: If a bug can't be reproduced reliably, the test approach failed +3. **Fast Feedback Loops**: Faster testing cycles improve development velocity +4. **Security Testing Priority**: For a Bitcoin wallet, security tests are non-negotiable +5. **Both Platforms Always**: iOS-only or Android-only testing misses critical bugs + +## Feedback Log + +### Template for New Entries +``` +[YYYY-MM-DD] - [SUCCESS/FAILURE/PARTIAL] - [Impact: HIGH/MEDIUM/LOW] +Context: [What was being tested] +Outcome: [Test results, bugs found/missed] +Learning: [Testing insights gained] +Action: [How SKILL.md should be updated, if at all] +``` + +### Entries + +--- + +**Awaiting first feedback entry...** + +When the webapp-testing skill is used to test mobile app functionality, outcomes should be recorded here. Track what testing approaches work, what breaks, and how to test more effectively. + +--- + +## Pattern Recognition + +As feedback accumulates, look for: +- **Reliable Bug Catchers**: Test approaches that consistently find issues → promote in SKILL.md +- **False Confidence**: Tests that pass but miss real bugs → document limitations in SKILL.md +- **Time Savers**: Workflow optimizations that speed up testing → add to SKILL.md +- **Platform Traps**: Platform-specific issues that need specific test approaches → document in SKILL.md +- **Tool Evolution**: As Expo/React Native testing tools evolve → update SKILL.md + +## Known Issues Archive + +Track recurring issues and their solutions: + +**None yet** - Will be populated with actual testing challenges encountered + +## Testing Workflow Improvements + +Track discovered workflow optimizations: + +**None yet** - Will be populated based on real testing experiences + +## Pending SKILL.md Updates + +Track recommended updates here before they're applied: + +**None yet** - Will be populated based on feedback patterns + +## Changelog of Memory-Driven Updates + +Track when learnings from this memory file resulted in SKILL.md changes: + +**None yet** - This is the initial version + +--- + +## Usage Notes for Agents + +When you use the webapp-testing skill: +1. Document which testing approaches were attempted and their effectiveness +2. Record bugs that were caught vs bugs that were missed +3. Note any platform-specific testing challenges encountered +4. Track Metro bundler issues and their solutions +5. Document any new testing patterns or scripts that proved useful + +## Testing Scenarios to Watch For + +Pay special attention to feedback about: +- **Native Module Testing**: Did biometric/camera/secure storage tests work as expected? +- **Network Conditions**: How well did offline/poor connection tests work? +- **Bitcoin Operations**: Were wallet/transaction tests safe and effective? +- **Build Issues**: Which iOS/Android build problems were most common? +- **Performance Testing**: What techniques effectively measured app performance? + +The skill memory evolves mobile testing practices through empirical validation. diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml new file mode 100644 index 00000000..d6612da6 --- /dev/null +++ b/.github/workflows/build.yml @@ -0,0 +1,59 @@ +name: 🏗️ Build Verification + +on: + pull_request: + branches: [ main, develop ] + push: + branches: [ main, develop ] + +permissions: + contents: read + +jobs: + build-check: + name: TypeScript Build Check + runs-on: ubuntu-latest + + steps: + - name: 📥 Checkout code + uses: actions/checkout@v4 + + - name: 📦 Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + cache: 'npm' + + - name: 📥 Install dependencies + run: npm ci + + - name: 🔍 TypeScript Check + run: npx tsc --noEmit + + - name: ✅ Build check passed + if: success() + run: echo "✅ TypeScript compilation successful" + + expo-check: + name: Expo Doctor + runs-on: ubuntu-latest + + steps: + - name: 📥 Checkout code + uses: actions/checkout@v4 + + - name: 📦 Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + cache: 'npm' + + - name: 📥 Install dependencies + run: npm ci + + - name: 🏥 Run Expo Doctor + run: npx expo-doctor@latest + continue-on-error: true + + - name: ✅ Expo check completed + run: echo "✅ Expo doctor check completed" diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml new file mode 100644 index 00000000..7ef5f3a7 --- /dev/null +++ b/.github/workflows/lint.yml @@ -0,0 +1,35 @@ +name: 🔍 Lint + +on: + pull_request: + branches: [ main, develop ] + push: + branches: [ main, develop ] + +permissions: + contents: read + +jobs: + lint: + name: ESLint + runs-on: ubuntu-latest + + steps: + - name: 📥 Checkout code + uses: actions/checkout@v4 + + - name: 📦 Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + cache: 'npm' + + - name: 📥 Install dependencies + run: npm ci + + - name: 🔍 Run ESLint + run: npm run lint + + - name: ✅ Lint passed + if: success() + run: echo "✅ All files passed linting checks" diff --git a/.github/workflows/security.yml b/.github/workflows/security.yml new file mode 100644 index 00000000..52b7b35b --- /dev/null +++ b/.github/workflows/security.yml @@ -0,0 +1,107 @@ +name: 🔒 Security Scan + +on: + pull_request: + branches: [ main, develop ] + push: + branches: [ main, develop ] + schedule: + # Run weekly on Mondays at 00:00 UTC + - cron: '0 0 * * 1' + +permissions: + contents: read + security-events: write + +jobs: + dependency-review: + name: Dependency Review + runs-on: ubuntu-latest + if: github.event_name == 'pull_request' + + steps: + - name: 📥 Checkout code + uses: actions/checkout@v4 + + - name: 🔍 Dependency Review + uses: actions/dependency-review-action@v4 + with: + fail-on-severity: high + + npm-audit: + name: NPM Audit + runs-on: ubuntu-latest + + steps: + - name: 📥 Checkout code + uses: actions/checkout@v4 + + - name: 📦 Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + cache: 'npm' + + - name: 🔒 Run npm audit + run: | + npm audit --audit-level=moderate || true + echo "⚠️ Review audit results above" + continue-on-error: true + + secret-scan: + name: Secret Scanning + runs-on: ubuntu-latest + + steps: + - name: 📥 Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: 🔍 TruffleHog Secret Scan + uses: trufflesecurity/trufflehog@main + with: + path: ./ + base: ${{ github.event.repository.default_branch }} + head: HEAD + extra_args: --debug --only-verified + + file-check: + name: Sensitive File Check + runs-on: ubuntu-latest + + steps: + - name: 📥 Checkout code + uses: actions/checkout@v4 + + - name: 🔍 Check for sensitive files + run: | + echo "Checking for sensitive files that should not be committed..." + + # Check for actual Firebase config files (not .example files) + if [ -f "google-services.json" ] && ! [[ "google-services.json" =~ \.example ]]; then + echo "❌ ERROR: google-services.json found in repository" + exit 1 + fi + + if [ -f "GoogleService-Info.plist" ] && ! [[ "GoogleService-Info.plist" =~ \.example ]]; then + echo "❌ ERROR: GoogleService-Info.plist found in repository" + exit 1 + fi + + if find . -name "*.p8" -o -name "*.p12" -o -name "*.key" -o -name "*.pem" | grep -v node_modules | grep -q .; then + echo "❌ ERROR: Private key files found in repository" + exit 1 + fi + + if find . -name "*.jks" -o -name "*.keystore" | grep -v node_modules | grep -q .; then + echo "❌ ERROR: Keystore files found in repository" + exit 1 + fi + + if [ -f ".env" ] || [ -f ".env.local" ]; then + echo "❌ ERROR: Environment files found in repository" + exit 1 + fi + + echo "✅ No sensitive files detected" diff --git a/AGENTS.md b/AGENTS.md index bb5eb361..9c0c39fb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -511,4 +511,132 @@ node scripts/test-biometric.js --- -**For unclear conventions or missing patterns, refer to recent code changes or ask the development team for clarification.** +## Skills Feedback Loop System + +**BitSleuth Wallet** implements a self-improving skills system where agent skills evolve based on real-world usage outcomes. This creates a living, adaptive knowledge base rather than static documentation. + +### How It Works + +Skills (like `developer-guide`, `frontend-design`, `webapp-testing`) learn from experience through a structured feedback loop: + +1. **Skill Usage**: Agent invokes a skill to complete a task +2. **Outcome Observation**: Task succeeds, fails, or partially succeeds +3. **Reflection**: Agent reflects on what worked, what didn't, and what was learned +4. **Recording**: Agent logs the experience in the skill's `SKILL_MEMORY.md` file +5. **Pattern Recognition**: Over time, patterns emerge from accumulated feedback +6. **Skill Evolution**: When patterns are validated, `SKILL.md` is updated with improvements + +### File Structure + +Each skill directory (`.github/skills/[skill-name]/`) contains: + +- **`SKILL.md`** - Core skill instructions (updated deliberately based on validated patterns) +- **`SKILL_MEMORY.md`** - Learning memory that captures feedback from each usage (updated frequently) +- **Relationship**: `SKILL_MEMORY.md` acts as a buffer where experiences accumulate; proven patterns graduate to `SKILL.md` + +### Agent Responsibilities + +#### When Using a Skill + +1. **Read both files**: Check `SKILL.md` for core guidance and `SKILL_MEMORY.md` for recent learnings +2. **Execute the task**: Apply the guidance from the skill +3. **Observe the outcome**: Did it succeed? Partially? Fail? + +#### After Using a Skill + +1. **Reflect on the experience**: + - What specific task did you perform? + - What aspects of the skill's guidance were helpful? + - What was missing or misleading? + - What did you learn that others should know? + +2. **Record feedback in `SKILL_MEMORY.md`**: + - Add an entry to the Feedback Log section + - Follow the template in `.github/skills/FEEDBACK_TEMPLATE.md` + - Be specific with examples and context + - Assign impact level: HIGH, MEDIUM, or LOW + +3. **Identify patterns** (if multiple feedback entries exist): + - Do you see repeated successes or failures? + - Are there common gaps in coverage? + - Should any learnings be elevated to `SKILL.md`? + +4. **Propose updates** (if warranted): + - Add recommendations to "Pending SKILL.md Updates" section + - Don't edit `SKILL.md` directly yet—let patterns accumulate + - High-impact security learnings may warrant immediate updates + +### When to Update SKILL.md + +Update a skill's core instructions when: + +- ✅ **Strong pattern emerges**: Multiple feedback entries point to the same issue +- ✅ **Critical gap found**: Missing guidance causes repeated failures +- ✅ **Best practice validated**: A technique succeeds consistently across different contexts +- ✅ **Ecosystem evolves**: Libraries, frameworks, or Bitcoin protocol updates +- ✅ **Security issue discovered**: Any security-related learning (immediate update) + +Do NOT update based on: + +- ❌ Single isolated incidents (unless security-critical) +- ❌ Unvalidated theories or hunches +- ❌ Temporary workarounds +- ❌ Personal preferences without evidence + +### Example Feedback Entry + +```markdown +### 2026-01-11 18:30 - SUCCESS + +**Skill Used**: frontend-design + +**Task Context**: +Created transaction details screen with hash display, confirmations, and status. + +**Outcome**: +Successfully implemented with positive feedback. Discovered monospace font +requirement for Bitcoin data not covered in SKILL.md. + +**What Worked Well**: +- Typography scale perfect for titles +- Spring animations felt natural +- Haptic feedback on copy actions (from previous SKILL_MEMORY insight) + +**What Didn't Work**: +- No guidance on monospace fonts for transaction hashes/addresses +- Missing "copy to clipboard" interaction pattern + +**Key Learnings**: +- Bitcoin technical data (hashes, addresses) MUST use monospace fonts +- Copy actions need: haptic + visual + temporal feedback +- Technical data benefits from smaller font size (14pt vs 16pt) + +**Recommended Updates**: +1. Add section: "Displaying Technical/Monospace Data" to SKILL.md +2. Add pattern: "Copy to Clipboard Interactions" with example +3. Update typography guidance with technical data exceptions + +**Impact Level**: MEDIUM +``` + +### Benefits + +- **Continuous Improvement**: Skills get better with every use +- **Evidence-Based**: Changes based on real outcomes, not speculation +- **Institutional Memory**: Knowledge persists across agent sessions +- **Collaborative Learning**: Multiple agents contribute to shared skills +- **Balanced Stability**: Core guidance stays stable while memory captures variation + +### Resources + +- **Feedback Loop Guide**: `.github/skills/FEEDBACK_LOOP_GUIDE.md` - Complete system documentation +- **Feedback Template**: `.github/skills/FEEDBACK_TEMPLATE.md` - Template for recording outcomes +- **Skill Memories**: Each skill has its own `SKILL_MEMORY.md` file for accumulated learnings + +### Key Principle + +> **Skills are living systems.** Don't just follow instructions—observe outcomes, record learnings, and contribute to collective improvement. Your feedback makes the next agent more effective. + +--- + +**For unclear conventions or missing patterns, refer to recent code changes, check skill memory files, or ask the development team for clarification.** diff --git a/CHANGELOG.md b/CHANGELOG.md index 44943286..7a711814 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Added +- **Open Source Release**: BitSleuth Wallet is now open source under AGPL-3.0 license + - GitHub Actions workflows for CI/CD (lint, build verification, security scanning) + - Comprehensive build guide for new contributors + - Architecture documentation + - Contributing guidelines with documentation organization standards + - Security scanning with dependency review and secret detection + - GitHub Discussions for community support + - Issue and PR templates for structured contributions + ### Security - **CVE-2025-55182**: Updated React to version 19.1.2 to address security vulnerability - Updated `react` from 19.1.0 to 19.1.2 @@ -383,13 +393,15 @@ BitSleuth Wallet/ ### Contributing -This is proprietary software owned by BitSleuth. Contributions are limited to authorized BitSleuth personnel only. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. +BitSleuth Wallet is open source software! We welcome contributions from the community. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute. ### License -**PROPRIETARY SOFTWARE** - Copyright © 2025 BitSleuth. All rights reserved. +**Open Source Software - AGPL-3.0** + +Copyright © 2025 BitSleuth. Licensed under the GNU Affero General Public License v3.0. -For licensing inquiries: legal@bitsleuth.ai +This program is free software: you can redistribute it and/or modify it under the terms of the AGPL-3.0 license. See [LICENSE](LICENSE) for details. --- diff --git a/README.md b/README.md index 026fe946..53360bed 100644 --- a/README.md +++ b/README.md @@ -455,7 +455,14 @@ eas submit --platform android We welcome contributions from the community! BitSleuth Wallet is open source software, and we appreciate your help in making it better. -**For detailed contribution guidelines, including documentation organization and code style, see [CONTRIBUTING.md](CONTRIBUTING.md).** +### Quick Links for Contributors + +- 📖 **[Contributing Guidelines](CONTRIBUTING.md)** - Start here for contribution rules and guidelines +- 🏗️ **[Build Guide](docs/BUILD_GUIDE.md)** - Complete setup instructions for development +- 🏛️ **[Architecture Overview](docs/ARCHITECTURE.md)** - Understand the codebase structure +- 🆕 **[First-Time Contributors Guide](docs/FIRST_TIME_CONTRIBUTORS.md)** - Perfect for newcomers to open source +- ⚡ **[Quick Reference](docs/QUICK_REFERENCE.md)** - Common commands and patterns +- 🔒 **[Security Policy](SECURITY.md)** - Report security vulnerabilities ### Quick Guidelines - Follow TypeScript best practices @@ -475,6 +482,8 @@ We welcome contributions from the community! BitSleuth Wallet is open source sof 5. Push to your branch (`git push origin feature/amazing-feature`) 6. Open a Pull Request +**For detailed instructions, see our [First-Time Contributors Guide](docs/FIRST_TIME_CONTRIBUTORS.md).** + ### Documentation Organization **All markdown documentation files MUST be stored in the `docs/` folder**, with the following exceptions: diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 00000000..45d459c3 --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -0,0 +1,488 @@ +# Architecture Overview + +This document provides a high-level overview of BitSleuth Wallet's architecture, helping contributors understand how the codebase is organized and how different components interact. + +## Table of Contents + +- [Architecture Principles](#architecture-principles) +- [Project Structure](#project-structure) +- [Core Components](#core-components) +- [Data Flow](#data-flow) +- [State Management](#state-management) +- [Security Architecture](#security-architecture) +- [External Integrations](#external-integrations) +- [Navigation Structure](#navigation-structure) + +## Architecture Principles + +BitSleuth Wallet is built on the following architectural principles: + +### 1. **Client-Side First** +- All sensitive operations happen on the device +- Private keys never leave the device +- No server-side dependencies for core wallet functionality + +### 2. **Separation of Concerns** +- **Services Layer**: Business logic and API interactions +- **Components**: Reusable UI elements +- **Screens**: Page-level components with routing +- **Hooks**: State management and shared logic + +### 3. **Security by Design** +- Minimal attack surface +- Defense in depth +- Privacy by default +- No analytics or tracking + +### 4. **Mobile-First** +- React Native for cross-platform mobile development +- Native modules for platform-specific features +- Optimized for mobile UX patterns + +### 5. **Bitcoin Standards Compliance** +- BIP32, BIP39, BIP44, BIP84 compliance +- BIP125 (RBF) and BIP141 (SegWit) support +- Standard derivation paths + +## Project Structure + +``` +BitSleuth Wallet/ +│ +├── app/ # Application screens (Expo Router) +│ ├── (tabs)/ # Tab-based navigation screens +│ │ ├── index.tsx # Home/Wallet screen +│ │ ├── send.tsx # Send Bitcoin +│ │ ├── receive.tsx # Receive Bitcoin +│ │ └── settings.tsx # App settings +│ ├── _layout.tsx # Root layout with navigation +│ ├── wallet-setup.tsx # Wallet creation/import +│ ├── transaction-details.tsx # Transaction detail view +│ ├── coin-control.tsx # Manual UTXO selection +│ ├── fee-bump.tsx # RBF fee bumping +│ ├── cpfp-bump.tsx # CPFP fee bumping +│ ├── generate-xpub.tsx # XPUB export +│ └── ... # Additional screens +│ +├── services/ # Business logic layer +│ ├── wallet-service.ts # Wallet creation, import, management +│ ├── bitcoin-service.ts # Transaction creation, signing +│ ├── esplora-service.ts # Blockchain API client +│ ├── fee-service.ts # Fee estimation +│ ├── rbf-service.ts # Replace-By-Fee logic +│ ├── cpfp-service.ts # Child-Pays-For-Parent logic +│ ├── secure-auth-service.ts # Authentication (PIN, biometrics) +│ ├── address-cache-service.ts # Address metadata caching +│ ├── transaction-cache-service.ts # Transaction caching +│ ├── wallet-persistence-service.ts # Wallet data persistence +│ └── crypto-polyfill.ts # Cryptographic utilities +│ +├── components/ # Reusable UI components +│ ├── WalletCard.tsx # Wallet display card +│ ├── TransactionItem.tsx # Transaction list item +│ ├── QRScanner.tsx # QR code scanner +│ ├── PinUnlockScreen.tsx # PIN entry screen +│ ├── BitSleuthButton.tsx # Custom button component +│ ├── LiquidGlassView.tsx # iOS blur effect +│ └── ... # Additional components +│ +├── hooks/ # Custom React hooks & state +│ ├── wallet-store.ts # Zustand wallet state +│ ├── auto-lock-store.ts # Auto-lock state +│ ├── use-performance-monitor.ts # Performance tracking +│ └── ... # Additional hooks +│ +├── constants/ # App constants +│ ├── themes.ts # Theme definitions +│ └── wallet-colors.ts # Wallet color schemes +│ +├── types/ # TypeScript type definitions +│ └── wallet.ts # Wallet-related types +│ +├── utils/ # Utility functions +│ +├── android/ # Android native code +│ ├── app/ +│ │ ├── src/main/ +│ │ │ ├── java/ # Java/Kotlin source +│ │ │ ├── res/ # Resources +│ │ │ └── AndroidManifest.xml +│ │ └── build.gradle +│ └── gradle/ +│ +├── ios/ # iOS native code +│ ├── BitSleuthWallet/ +│ │ ├── AppDelegate.mm # App entry point +│ │ ├── Info.plist # App configuration +│ │ └── ... +│ ├── Podfile # CocoaPods dependencies +│ └── ... +│ +├── docs/ # Documentation +├── scripts/ # Utility scripts +└── assets/ # Static assets +``` + +## Core Components + +### 1. Services Layer + +The services layer encapsulates all business logic and external API interactions: + +#### **wallet-service.ts** +- Wallet creation with BIP39 mnemonic generation +- Wallet import from mnemonic +- Key derivation (BIP32/BIP44/BIP84) +- Address generation +- Multi-wallet management + +#### **bitcoin-service.ts** +- Transaction construction +- Transaction signing with private keys +- UTXO selection +- Fee calculation +- Transaction broadcasting + +#### **esplora-service.ts** +- Blockchain data fetching (Blockstream Esplora API) +- UTXO queries +- Transaction history +- Address balance +- Fee rate recommendations +- Rate limiting and retry logic + +#### **secure-auth-service.ts** +- PIN setup and verification +- Biometric authentication (Face ID, Touch ID) +- Auto-lock functionality +- Secure storage management + +### 2. State Management + +#### **Zustand Stores** +- `wallet-store.ts`: Active wallet state, balance, transactions +- `auto-lock-store.ts`: Authentication state, lock timer + +#### **React Query (TanStack Query)** +- Server state caching (blockchain data) +- Automatic refetching +- Background updates +- Cache invalidation + +#### **AsyncStorage (Persistent Storage)** +- Wallet persistence +- Encrypted mnemonic storage +- User preferences +- App settings + +### 3. UI Components + +Components are organized by complexity: + +#### **Atomic Components** +- Buttons, inputs, icons +- Typography components +- Loading indicators + +#### **Molecular Components** +- Cards (WalletCard, TransactionItem) +- Forms (PIN entry, send form) +- Modals and sheets + +#### **Organism Components** +- Screen sections (transaction list, wallet header) +- Complex forms (wallet setup wizard) +- Navigation components + +## Data Flow + +### Wallet Creation Flow + +``` +User Action (Create Wallet) + ↓ +wallet-service.ts + ↓ +BIP39 Generate Mnemonic + ↓ +BIP32 Derive Master Key + ↓ +BIP84 Derive Account Keys + ↓ +Generate First Address + ↓ +Encrypt & Store Mnemonic (AsyncStorage) + ↓ +Update Zustand Store + ↓ +Navigate to Wallet Screen +``` + +### Transaction Sending Flow + +``` +User Input (Amount, Address) + ↓ +bitcoin-service.ts + ↓ +Fetch UTXOs (esplora-service) + ↓ +Select UTXOs & Calculate Fee + ↓ +Build Transaction (bitcoinjs-lib) + ↓ +Request PIN/Biometric Auth + ↓ +Derive Private Keys (from mnemonic) + ↓ +Sign Transaction + ↓ +Broadcast Transaction (esplora-service) + ↓ +Update Local State + ↓ +Show Success/Error +``` + +### Balance Update Flow + +``` +App Launch / Wallet Switch + ↓ +wallet-store.ts (triggers fetch) + ↓ +esplora-service.ts (get addresses) + ↓ +Fetch Address Balances (with caching) + ↓ +Fetch UTXOs (with caching) + ↓ +Aggregate Balance + ↓ +Update Zustand Store + ↓ +UI Re-renders +``` + +## State Management + +### State Layers + +1. **Local Component State** (`useState`) + - Form inputs + - UI toggles + - Transient data + +2. **Zustand Global State** + - Active wallet + - Wallet list + - Current balance + - Transactions + - Authentication state + +3. **React Query Cache** + - Blockchain data + - Price data + - Fee estimates + +4. **Persistent Storage (AsyncStorage)** + - Encrypted mnemonics + - Wallet metadata + - User preferences + - Settings + +### State Flow Diagram + +``` +┌─────────────────┐ +│ User Action │ +└────────┬────────┘ + │ + ↓ +┌─────────────────┐ +│ Component │ ← Local State (useState) +└────────┬────────┘ + │ + ↓ +┌─────────────────┐ +│ Zustand Store │ ← Global State +└────────┬────────┘ + │ + ↓ +┌─────────────────┐ +│ Services │ +└────────┬────────┘ + │ + ├─→ AsyncStorage (persistence) + ├─→ React Query (server cache) + └─→ External APIs +``` + +## Security Architecture + +### Key Management + +1. **Mnemonic Storage** + - Encrypted at rest (AES-256) + - Stored in AsyncStorage + - Never transmitted + +2. **Private Key Derivation** + - Derived on-demand from mnemonic + - Never persisted to storage + - Exists only in memory during signing + +3. **PIN Protection** + - Hashed with strong algorithm + - Stored securely in device keychain + - Required for sensitive operations + +4. **Biometric Integration** + - Device-level biometric APIs + - Secure Enclave (iOS) / Keystore (Android) + - Fallback to PIN + +### Security Layers + +``` +┌──────────────────────────────────┐ +│ Biometric (Face ID / Touch ID) │ Layer 1 +└─────────────┬────────────────────┘ + ↓ +┌──────────────────────────────────┐ +│ PIN Protection │ Layer 2 +└─────────────┬────────────────────┘ + ↓ +┌──────────────────────────────────┐ +│ Encrypted Storage (Mnemonic) │ Layer 3 +└─────────────┬────────────────────┘ + ↓ +┌──────────────────────────────────┐ +│ Client-Side Key Derivation │ Layer 4 +└─────────────┬────────────────────┘ + ↓ +┌──────────────────────────────────┐ +│ Transaction Signing │ Layer 5 +└──────────────────────────────────┘ +``` + +## External Integrations + +### 1. Blockstream Esplora API +- **Purpose**: Blockchain data +- **Endpoints**: + - `/api/address/:address/txs` - Transaction history + - `/api/address/:address/utxo` - Unspent outputs + - `/api/tx/:txid` - Transaction details + - `/api/fee-estimates` - Fee recommendations + - `/api/tx` (POST) - Broadcast transaction +- **Rate Limiting**: Sequential requests with backoff +- **Caching**: Address metadata (2 min), transactions (5 min) + +### 2. CoinGecko API +- **Purpose**: Bitcoin price data +- **Endpoint**: `/api/v3/simple/price` +- **Currencies**: USD, EUR, GBP +- **Caching**: Price cached locally +- **Fallback**: Last known price if API unavailable + +### 3. Firebase Services +- **Crashlytics**: Error reporting only +- **Performance Monitoring**: App performance tracking +- **Analytics**: DISABLED (privacy requirement) + +## Navigation Structure + +### Expo Router File-Based Routing + +``` +app/ +├── _layout.tsx # Root layout +├── (tabs)/ +│ ├── _layout.tsx # Tab layout +│ ├── index.tsx # Home (/) +│ ├── send.tsx # Send (/send) +│ ├── receive.tsx # Receive (/receive) +│ └── settings.tsx # Settings (/settings) +├── wallet-setup.tsx # /wallet-setup +├── transaction-details.tsx # /transaction-details/[txid] +├── coin-control.tsx # /coin-control +├── fee-bump.tsx # /fee-bump/[txid] +└── ... +``` + +### Navigation Flow + +``` +Launch + ↓ +Has Wallet? → No → Wallet Setup + ↓ Yes ↓ +PIN/Biometric Create/Import + ↓ ↓ +Authenticated Save Wallet + ↓ ↓ +Tab Navigator ←────┘ + ├─ Home (Wallet Balance) + ├─ Send + ├─ Receive + └─ Settings +``` + +## Technology Stack Summary + +### Core Framework +- **React Native** 0.81.5 (New Architecture) +- **Expo** SDK 54 +- **TypeScript** 5.9 +- **React** 19.1 + +### Bitcoin & Cryptography +- **bitcoinjs-lib** 6.1.7 +- **bip32**, **bip39** +- **@noble/secp256k1** 2.3 +- **@noble/hashes** 1.8 +- **bech32** + +### State Management +- **Zustand** 5.0 +- **@tanstack/react-query** 5.87 +- **AsyncStorage** 2.2 + +### UI & Navigation +- **Expo Router** 5.1 +- **NativeWind** 4.1 (Tailwind CSS) +- **React Native Reanimated** 4.1 +- **Lucide React Native** (icons) + +## Best Practices for Contributors + +1. **Follow the Layer Architecture** + - Keep business logic in services + - Keep UI logic in components + - Use hooks for shared state logic + +2. **Security First** + - Never log sensitive data + - Never transmit private keys + - Always validate user input + - Use secure storage for sensitive data + +3. **Performance** + - Memoize expensive computations + - Use React Query for API caching + - Debounce user inputs + - Lazy load heavy components + +4. **Code Organization** + - One component per file + - Group related files + - Use TypeScript for type safety + - Follow existing naming conventions + +--- + +For more detailed information, see: +- [BUILD_GUIDE.md](BUILD_GUIDE.md) - Development setup +- [CONTRIBUTING.md](../CONTRIBUTING.md) - Contribution guidelines +- [SECURITY.md](../SECURITY.md) - Security policy diff --git a/docs/BUILD_GUIDE.md b/docs/BUILD_GUIDE.md new file mode 100644 index 00000000..317ea5e2 --- /dev/null +++ b/docs/BUILD_GUIDE.md @@ -0,0 +1,447 @@ +# Build Guide for Contributors + +This guide will help you set up your development environment and build BitSleuth Wallet from source. + +## Table of Contents + +- [Prerequisites](#prerequisites) +- [Initial Setup](#initial-setup) +- [Firebase Configuration](#firebase-configuration) +- [iOS Setup](#ios-setup) +- [Android Setup](#android-setup) +- [Running the App](#running-the-app) +- [Building for Production](#building-for-production) +- [Troubleshooting](#troubleshooting) + +## Prerequisites + +Before you begin, ensure you have the following installed: + +### Required for All Platforms + +- **Node.js** 18.17+ (Node 20 recommended) + ```bash + node --version # Should be v18.17.0 or higher + ``` + +- **npm** or **bun** package manager + ```bash + npm --version # Should be v10.2.4 or higher + ``` + +- **Git** + ```bash + git --version + ``` + +### Required for iOS Development (macOS only) + +- **macOS** (Monterey 12.0 or later) +- **Xcode** 15.0 or later + - Install from the Mac App Store + - Install Xcode Command Line Tools: + ```bash + xcode-select --install + ``` + +- **CocoaPods** + ```bash + sudo gem install cocoapods + pod --version + ``` + +### Required for Android Development + +- **Android Studio** with the following: + - Android SDK Platform 35 (Android 15) + - Android SDK Build-Tools 35.0.0 + - Android SDK Platform-Tools + - Android Emulator (optional, for testing) + +- **Java Development Kit (JDK)** 17 or higher + ```bash + java -version + ``` + +- **Environment Variables** (add to `~/.bashrc`, `~/.zshrc`, or equivalent): + ```bash + export ANDROID_HOME=$HOME/Library/Android/sdk # macOS + # OR + export ANDROID_HOME=$HOME/Android/Sdk # Linux + + export PATH=$PATH:$ANDROID_HOME/emulator + export PATH=$PATH:$ANDROID_HOME/platform-tools + export PATH=$PATH:$ANDROID_HOME/tools + export PATH=$PATH:$ANDROID_HOME/tools/bin + ``` + +## Initial Setup + +### 1. Clone the Repository + +```bash +git clone https://github.com/BitSleuthAI/Wallet.git +cd Wallet +``` + +### 2. Install Dependencies + +```bash +npm install +# or +bun install +``` + +This will install all JavaScript dependencies including Expo, React Native, and other packages. + +### 3. Install iOS Dependencies (macOS only) + +```bash +cd ios +pod install +cd .. +``` + +This installs native iOS dependencies via CocoaPods. + +## Firebase Configuration + +**IMPORTANT**: You must set up your own Firebase project before running the app. The repository does not include Firebase configuration files for security reasons. + +### Step-by-Step Firebase Setup + +1. **Create a Firebase Project** + - Go to [Firebase Console](https://console.firebase.google.com/) + - Click "Add project" or use an existing project + - Follow the wizard to create your project + - **IMPORTANT**: When asked about Google Analytics, select "Not now" or disable it (we don't use Analytics) + +2. **Add iOS App to Firebase** + - In Firebase Console, click the iOS icon + - Enter iOS bundle ID: `com.bitsleuthwallet` (or your custom bundle ID) + - Download `GoogleService-Info.plist` + - Place it in **two locations**: + ``` + ios/BitSleuthWallet/GoogleService-Info.plist + GoogleService-Info.plist (root directory) + ``` + +3. **Add Android App to Firebase** + - In Firebase Console, click the Android icon + - Enter Android package name: `com.bitsleuthwallet` (or your custom package name) + - Download `google-services.json` + - Place it in **two locations**: + ``` + android/app/google-services.json + google-services.json (root directory) + ``` + +4. **Enable Firebase Services** + + In the Firebase Console, enable the following services: + + - **Crashlytics** (for error reporting) + - Go to Crashlytics in the left sidebar + - Click "Enable Crashlytics" + - Follow the setup wizard + + - **Performance Monitoring** (for app performance) + - Go to Performance in the left sidebar + - Click "Get started" + - Follow the setup wizard + + - **DISABLE Google Analytics** (privacy requirement) + - Go to Project Settings > Integrations + - If Analytics is enabled, disable it + - This is a **strict requirement** for privacy compliance + +5. **Verify Configuration** + + Run the Firebase connectivity test: + ```bash + node scripts/test-firebase-connectivity.js + ``` + + You should see: + ``` + ✅ Firebase is properly configured! + ✅ Crashlytics is enabled + ✅ Performance Monitoring is enabled + ✅ Analytics is DISABLED (correct for privacy) + ``` + +For detailed Firebase setup instructions, see [FIREBASE_SETUP.md](archive/FIREBASE_SETUP.md). + +## iOS Setup + +### 1. Configure Xcode Project + +Open the iOS project in Xcode: +```bash +cd ios +open BitSleuthWallet.xcworkspace # Note: .xcworkspace, not .xcodeproj +``` + +### 2. Configure Signing + +- In Xcode, select the project in the left sidebar +- Select the "BitSleuthWallet" target +- Go to "Signing & Capabilities" tab +- Select your development team +- Xcode will automatically manage provisioning profiles + +### 3. Verify Pod Installation + +If you encounter issues with pods: +```bash +cd ios +pod deintegrate +pod install +cd .. +``` + +## Android Setup + +### 1. Open in Android Studio (Optional) + +```bash +cd android +# Open this directory in Android Studio +``` + +### 2. Create Local Properties File + +Create `android/local.properties`: +```properties +sdk.dir=/Users/YOUR_USERNAME/Library/Android/sdk # macOS +# OR +sdk.dir=/home/YOUR_USERNAME/Android/Sdk # Linux +# OR +sdk.dir=C:\\Users\\YOUR_USERNAME\\AppData\\Local\\Android\\Sdk # Windows +``` + +### 3. Verify Gradle Build + +```bash +cd android +./gradlew clean +./gradlew assembleDebug +cd .. +``` + +## Running the App + +### Start Metro Bundler + +In one terminal, start the Metro bundler: +```bash +npm start +``` + +This will show you a QR code and a menu of options. + +### Run on iOS Simulator + +In a new terminal: +```bash +npm run ios +``` + +Or specify a device: +```bash +npx expo run:ios --device "iPhone 15 Pro" +``` + +### Run on Android Emulator + +Make sure you have an Android emulator running, then: +```bash +npm run android +``` + +Or use a specific emulator: +```bash +npx expo run:android --device emulator-5554 +``` + +### Run on Physical Device + +1. Start with tunnel mode for network access: + ```bash + npm run start-tunnel + ``` + +2. Install Expo Go app on your device +3. Scan the QR code shown in the terminal + +Alternatively, for full native builds on physical devices: +```bash +# iOS (requires USB connection and device registered in Apple Developer) +npm run ios --device + +# Android (requires USB debugging enabled) +npm run android --device +``` + +## Building for Production + +### Using Expo Application Services (EAS) + +1. **Install EAS CLI** + ```bash + npm install -g eas-cli + ``` + +2. **Login to Expo** + ```bash + eas login + ``` + +3. **Configure EAS Build** + + The project already includes `eas.json` configuration. + +4. **Build for iOS** + ```bash + eas build --platform ios --profile production + ``` + +5. **Build for Android** + ```bash + eas build --platform android --profile production + ``` + +6. **Build for Both Platforms** + ```bash + eas build --platform all --profile production + ``` + +### Local Production Builds + +For iOS: +```bash +cd ios +xcodebuild -workspace BitSleuthWallet.xcworkspace \ + -scheme BitSleuthWallet \ + -configuration Release \ + -archivePath ./build/BitSleuthWallet.xcarchive \ + archive +``` + +For Android: +```bash +cd android +./gradlew bundleRelease +# APK will be at: android/app/build/outputs/bundle/release/app-release.aab +``` + +## Troubleshooting + +### Common Issues + +#### Metro Bundler Won't Start + +```bash +# Clear cache and restart +npx expo start -c +``` + +#### iOS Build Fails + +```bash +# Reinstall pods +cd ios +pod deintegrate +pod install +cd .. + +# Clean build folder in Xcode +# Product > Clean Build Folder (Shift + Cmd + K) +``` + +#### Android Build Fails + +```bash +# Clean Gradle build +cd android +./gradlew clean +cd .. + +# Or with more aggressive cleaning +cd android +rm -rf .gradle +./gradlew clean +cd .. +``` + +#### Firebase Not Working + +- Verify `google-services.json` is in `android/app/` +- Verify `GoogleService-Info.plist` is in `ios/BitSleuthWallet/` +- Check that only Crashlytics is enabled (not Analytics) +- Run the connectivity test: `node scripts/test-firebase-connectivity.js` + +#### Biometric Authentication Not Working + +- **iOS**: Check `Info.plist` has `NSFaceIDUsageDescription` +- **Android**: Check `AndroidManifest.xml` has biometric permissions +- Ensure device has biometrics enrolled +- Test with: `node scripts/test-biometric.js` + +#### TypeScript Errors + +```bash +# Regenerate TypeScript config +npx expo customize tsconfig.json + +# Check for errors +npx tsc --noEmit +``` + +#### Dependency Issues + +```bash +# Remove and reinstall +rm -rf node_modules package-lock.json +npm install + +# On iOS, also reinstall pods +cd ios +rm -rf Pods Podfile.lock +pod install +cd .. +``` + +### Getting Help + +If you're still stuck: + +1. **Check existing issues**: [GitHub Issues](https://github.com/BitSleuthAI/Wallet/issues) +2. **Search discussions**: [GitHub Discussions](https://github.com/BitSleuthAI/Wallet/discussions) +3. **Create a new issue**: Include: + - Your OS and version + - Node.js version + - Xcode/Android Studio version + - Complete error message + - Steps you've already tried + +## Next Steps + +Once you have the app running: + +1. Read [CONTRIBUTING.md](../CONTRIBUTING.md) for contribution guidelines +2. Check [docs/ARCHITECTURE.md](ARCHITECTURE.md) to understand the codebase structure +3. Review open issues labeled `good-first-issue` for beginner-friendly tasks +4. Join the discussion on [GitHub Discussions](https://github.com/BitSleuthAI/Wallet/discussions) + +## Additional Resources + +- [React Native Documentation](https://reactnative.dev/) +- [Expo Documentation](https://docs.expo.dev/) +- [Firebase Documentation](https://firebase.google.com/docs) +- [bitcoinjs-lib Documentation](https://github.com/bitcoinjs/bitcoinjs-lib) +- [BIP Standards](https://github.com/bitcoin/bips) + +--- + +**Happy building! 🚀** diff --git a/docs/FIRST_TIME_CONTRIBUTORS.md b/docs/FIRST_TIME_CONTRIBUTORS.md new file mode 100644 index 00000000..f6913bc2 --- /dev/null +++ b/docs/FIRST_TIME_CONTRIBUTORS.md @@ -0,0 +1,302 @@ +# First-Time Contributors Guide + +Welcome to BitSleuth Wallet! 👋 + +This guide is specifically for developers who are new to contributing to open source or new to this project. + +## Quick Start + +### 1. Find Your First Issue + +We label issues to help you find good starting points: + +- 🟢 **`good first issue`**: Perfect for newcomers +- 🟡 **`help wanted`**: We'd love community input on these +- 🔵 **`documentation`**: Improve our docs +- 🟣 **`bug`**: Fix a bug + +Browse issues: [Good First Issues](https://github.com/BitSleuthAI/Wallet/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) + +### 2. Set Up Your Development Environment + +Follow our comprehensive [Build Guide](BUILD_GUIDE.md) which includes: +- Installing prerequisites (Node.js, Xcode/Android Studio) +- Cloning the repository +- Setting up Firebase (required for development) +- Running the app on iOS/Android + +### 3. Make Your First Contribution + +#### Step-by-Step Process + +1. **Fork the repository** + - Click the "Fork" button at the top of the GitHub page + - This creates your own copy of the repository + +2. **Clone your fork** + ```bash + git clone https://github.com/YOUR_USERNAME/Wallet.git + cd Wallet + ``` + +3. **Create a new branch** + ```bash + git checkout -b fix/my-awesome-fix + # or + git checkout -b feature/my-cool-feature + ``` + + Branch naming conventions: + - `fix/description` for bug fixes + - `feature/description` for new features + - `docs/description` for documentation + - `refactor/description` for code refactoring + +4. **Make your changes** + - Edit the relevant files + - Follow our code style (see [CONTRIBUTING.md](../CONTRIBUTING.md)) + - Test your changes thoroughly + +5. **Test your changes** + ```bash + # Run linter + npm run lint + + # Test on iOS + npm run ios + + # Test on Android + npm run android + ``` + +6. **Commit your changes** + ```bash + git add . + git commit -m "Fix: description of what you fixed" + ``` + + Commit message format: + - `Fix: description` for bug fixes + - `Feat: description` for new features + - `Docs: description` for documentation + - `Refactor: description` for refactoring + - `Test: description` for tests + +7. **Push to your fork** + ```bash + git push origin fix/my-awesome-fix + ``` + +8. **Open a Pull Request** + - Go to your fork on GitHub + - Click "Pull Request" + - Fill in the PR template with details about your changes + - Submit the PR + +## Common First Contributions + +### Documentation Improvements + +One of the easiest ways to contribute is improving documentation: + +- Fix typos or unclear explanations +- Add examples to existing docs +- Improve code comments +- Create new guides + +**Important**: All markdown documentation files must be stored in the `docs/` folder (except README.md, CONTRIBUTING.md, LICENSE, CODE_OF_CONDUCT.md, SECURITY.md, CHANGELOG.md, and AGENTS.md). + +### Bug Fixes + +Found a bug? Great! Here's how to fix it: + +1. Check if an issue already exists +2. If not, create a new issue describing the bug +3. Fork and clone the repository +4. Reproduce the bug locally +5. Fix the bug +6. Test thoroughly +7. Submit a PR referencing the issue + +### UI/UX Improvements + +We welcome improvements to the user interface: + +- Better layout or spacing +- Improved color schemes +- Better icons or graphics +- Enhanced animations +- Accessibility improvements + +For UI changes, always include before/after screenshots in your PR. + +## Understanding the Codebase + +### Key Directories + +``` +Wallet/ +├── app/ # Screens (what users see) +├── components/ # Reusable UI elements +├── services/ # Business logic (Bitcoin, wallet operations) +├── hooks/ # State management +├── docs/ # Documentation (you are here!) +└── assets/ # Images, fonts, etc. +``` + +### Where to Make Changes + +| What you want to do | Where to look | +|---------------------|---------------| +| Fix a button or UI element | `components/` | +| Change a screen layout | `app/` | +| Fix wallet logic | `services/wallet-service.ts` | +| Fix transaction logic | `services/bitcoin-service.ts` | +| Add documentation | `docs/` | +| Fix styling | Look for `.tsx` files with NativeWind classes | + +### Code Style Tips + +✅ **DO:** +- Use TypeScript for all new code +- Use functional components with hooks +- Follow existing naming conventions +- Write self-documenting code +- Add comments for complex logic +- Test on both iOS and Android + +❌ **DON'T:** +- Add Google Analytics or tracking (privacy violation) +- Commit secrets or API keys +- Use class components +- Ignore linting errors +- Skip testing your changes + +## Getting Help + +Stuck? Don't worry! Here's how to get help: + +1. **Read the documentation** + - [Build Guide](BUILD_GUIDE.md) + - [Architecture Overview](ARCHITECTURE.md) + - [Contributing Guidelines](../CONTRIBUTING.md) + +2. **Search existing issues** + - Your question might already be answered + +3. **Ask in GitHub Discussions** + - [Start a discussion](https://github.com/BitSleuthAI/Wallet/discussions) + - The community is friendly and helpful! + +4. **Comment on the issue** + - If you're working on an issue, feel free to ask questions there + +5. **Join our community** + - Check README.md for community links + +## Common Pitfalls (and How to Avoid Them) + +### Pitfall #1: Firebase Not Configured +**Problem**: App crashes on startup with Firebase errors + +**Solution**: You need to set up your own Firebase project. See [BUILD_GUIDE.md](BUILD_GUIDE.md) for detailed instructions. + +### Pitfall #2: Linting Errors +**Problem**: CI fails with "Linting failed" + +**Solution**: Run `npm run lint` locally before pushing. Fix all errors. + +### Pitfall #3: Large PR +**Problem**: Your PR changes too many things at once + +**Solution**: Keep PRs small and focused. One bug fix or one feature per PR. + +### Pitfall #4: No Testing +**Problem**: Your changes break something else + +**Solution**: Always test on both iOS and Android before submitting. + +### Pitfall #5: Wrong File Location +**Problem**: You added a `.md` file in the root directory + +**Solution**: All documentation files (except the standard ones) go in `docs/`. + +## Your First PR Checklist + +Before submitting your first PR, make sure: + +- [ ] I've read the [Contributing Guidelines](../CONTRIBUTING.md) +- [ ] I've created a new branch for my changes +- [ ] My code follows the project's code style +- [ ] I've tested my changes on iOS and/or Android +- [ ] I've run `npm run lint` and fixed all errors +- [ ] I've added/updated documentation if needed +- [ ] My commit messages are clear and descriptive +- [ ] I've filled out the PR template +- [ ] I've added screenshots for UI changes +- [ ] I've referenced the issue number in my PR + +## After Your PR is Submitted + +1. **Be patient**: Maintainers review PRs as time permits +2. **Respond to feedback**: Address review comments promptly +3. **Don't take it personally**: Code reviews are about the code, not you +4. **Learn from feedback**: Each review makes you a better developer +5. **Celebrate**: Your contribution helps make Bitcoin more accessible! 🎉 + +## Code of Conduct + +Please read and follow our [Code of Conduct](../CODE_OF_CONDUCT.md). We're building a welcoming, inclusive community. + +## Recognition + +All contributors are valued! Your contributions will be: +- Listed in git history +- Mentioned in release notes (for significant contributions) +- Appreciated by the Bitcoin community + +## Beyond Code + +Not a developer? You can still contribute! + +- **Report bugs**: Help us find issues +- **Suggest features**: Share your ideas +- **Improve documentation**: Make things clearer +- **Answer questions**: Help others in Discussions +- **Spread the word**: Tell people about BitSleuth Wallet +- **Test releases**: Try new features and report issues + +## Resources for Learning + +New to React Native or Bitcoin development? Here are some helpful resources: + +### React Native / Expo +- [React Native Docs](https://reactnative.dev/docs/getting-started) +- [Expo Docs](https://docs.expo.dev/) +- [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/intro.html) + +### Bitcoin Development +- [Bitcoin Developer Guide](https://developer.bitcoin.org/devguide/) +- [BIP Standards](https://github.com/bitcoin/bips) +- [bitcoinjs-lib](https://github.com/bitcoinjs/bitcoinjs-lib) +- [Mastering Bitcoin](https://github.com/bitcoinbook/bitcoinbook) (free book) + +### Open Source +- [First Timers Only](https://www.firsttimersonly.com/) +- [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/) +- [GitHub Flow](https://guides.github.com/introduction/flow/) + +--- + +## Questions? + +Have questions about contributing? Feel free to: +- Open a [Discussion](https://github.com/BitSleuthAI/Wallet/discussions) +- Comment on an issue +- Contact us via [GitHub Issues](https://github.com/BitSleuthAI/Wallet/issues) for support + +**Welcome to the BitSleuth Wallet community! We're excited to have you here.** 🚀 + +--- + +*Building the future of Bitcoin self-custody, one contribution at a time.* ❤️ diff --git a/docs/QUICK_REFERENCE.md b/docs/QUICK_REFERENCE.md new file mode 100644 index 00000000..768d10f1 --- /dev/null +++ b/docs/QUICK_REFERENCE.md @@ -0,0 +1,477 @@ +# Quick Reference Guide + +Quick reference for common development tasks in BitSleuth Wallet. + +## Development Commands + +### Starting the App + +```bash +# Start Metro bundler +npm start + +# Run on iOS simulator +npm run ios + +# Run on Android emulator +npm run android + +# Start with tunnel (for physical devices) +npm run start-tunnel + +# Clear cache and restart +npx expo start -c +``` + +### Code Quality + +```bash +# Run linter +npm run lint + +# TypeScript type checking +npx tsc --noEmit + +# Run Expo doctor +npx expo-doctor@latest +``` + +### Testing + +```bash +# Test Firebase connectivity +node scripts/test-firebase-connectivity.js + +# Test biometric authentication +node scripts/test-biometric.js + +# Test crashlytics +node scripts/test-crashlytics-simple.js + +# Test wallet persistence +node scripts/test-wallet-persistence.js +``` + +### iOS Development + +```bash +# Install/update pods +cd ios && pod install && cd .. + +# Clean pod installation +cd ios && pod deintegrate && pod install && cd .. + +# Open in Xcode +cd ios && open BitSleuthWallet.xcworkspace && cd .. +``` + +### Android Development + +```bash +# Clean Gradle build +cd android && ./gradlew clean && cd .. + +# Build debug APK +cd android && ./gradlew assembleDebug && cd .. + +# Build release bundle +cd android && ./gradlew bundleRelease && cd .. +``` + +### Production Builds + +```bash +# Login to EAS +eas login + +# Build for iOS +eas build --platform ios --profile production + +# Build for Android +eas build --platform android --profile production + +# Build for both platforms +eas build --platform all --profile production +``` + +## File Locations + +### Configuration Files + +``` +google-services.json # Android Firebase config (root + android/app/) +GoogleService-Info.plist # iOS Firebase config (root + ios/BitSleuthWallet/) +package.json # Dependencies and scripts +app.json # Expo configuration +tsconfig.json # TypeScript configuration +eas.json # EAS Build configuration +``` + +### Key Directories + +``` +app/ # Screens (Expo Router) +app/(tabs)/ # Main tab navigation screens +services/ # Business logic +components/ # Reusable UI components +hooks/ # State management & custom hooks +types/ # TypeScript types +constants/ # App constants +docs/ # All documentation +scripts/ # Utility scripts +android/ # Android native code +ios/ # iOS native code +``` + +## Common Services + +### Wallet Service +**Location**: `services/wallet-service.ts` + +```typescript +// Create wallet +const wallet = await walletService.createWallet(name, color) + +// Import wallet +const wallet = await walletService.importWallet(mnemonic, name, color) + +// Get wallet +const wallet = walletService.getWallet(walletId) + +// Generate address +const address = await walletService.generateReceiveAddress(walletId) +``` + +### Bitcoin Service +**Location**: `services/bitcoin-service.ts` + +```typescript +// Create transaction +const tx = await bitcoinService.createTransaction( + walletId, + recipientAddress, + amount, + feeRate +) + +// Sign transaction +const signedTx = await bitcoinService.signTransaction(tx, privateKeys) + +// Broadcast transaction +const txid = await bitcoinService.broadcastTransaction(signedTx) +``` + +### Esplora Service +**Location**: `services/esplora-service.ts` + +```typescript +// Get UTXOs +const utxos = await esploraService.getAddressUtxos(address) + +// Get transactions +const txs = await esploraService.getAddressTransactions(address) + +// Get transaction details +const tx = await esploraService.getTransaction(txid) + +// Get fee estimates +const fees = await esploraService.getFeeEstimates() +``` + +## State Management + +### Zustand Store +**Location**: `hooks/wallet-store.ts` + +```typescript +// Get state +const { currentWallet, balance, transactions } = useWalletStore() + +// Update state +useWalletStore.setState({ currentWallet: newWallet }) + +// Access outside React +const store = useWalletStore.getState() +``` + +### React Query +**Location**: Throughout the app + +```typescript +// Query data +const { data, isLoading, error } = useQuery({ + queryKey: ['balance', walletId], + queryFn: () => fetchBalance(walletId), + staleTime: 60000, // 1 minute +}) + +// Invalidate cache +queryClient.invalidateQueries(['balance']) +``` + +## Git Workflow + +### Branch Naming + +```bash +# Feature branches +git checkout -b feature/description + +# Bug fixes +git checkout -b fix/description + +# Documentation +git checkout -b docs/description + +# Refactoring +git checkout -b refactor/description +``` + +### Commit Messages + +```bash +# Format: Type: Description + +git commit -m "Feat: add coin control feature" +git commit -m "Fix: resolve balance calculation error" +git commit -m "Docs: update build guide" +git commit -m "Refactor: simplify transaction service" +git commit -m "Test: add wallet creation tests" +``` + +### Pull Request Flow + +```bash +# 1. Create branch +git checkout -b feature/my-feature + +# 2. Make changes and commit +git add . +git commit -m "Feat: add my feature" + +# 3. Push to your fork +git push origin feature/my-feature + +# 4. Open PR on GitHub +# 5. Address review feedback +# 6. Merge when approved +``` + +## Debugging + +### React Native Debugger + +```bash +# Open developer menu +# iOS: Cmd+D in simulator +# Android: Cmd+M in emulator (Mac) or Ctrl+M (Windows/Linux) + +# Enable debug mode +# Select "Debug" from the menu +``` + +### Console Logs + +```typescript +// Development only +if (__DEV__) { + console.log('Debug info:', data) +} + +// Avoid in production +console.log('This will appear in logs') +``` + +### Firebase Crashlytics + +```typescript +import crashlytics from '@react-native-firebase/crashlytics' + +// Log events +crashlytics().log('User performed action') + +// Record errors +crashlytics().recordError(new Error('Something went wrong')) + +// Set custom attributes +crashlytics().setAttribute('user_id', userId) +``` + +## Environment Variables + +```bash +# Not used in this project - Firebase config is in files +# If adding .env support in the future: + +# .env +API_KEY=your_key_here +API_URL=https://api.example.com + +# Access in code +import Constants from 'expo-constants' +const apiKey = Constants.expoConfig?.extra?.apiKey +``` + +## Troubleshooting + +### Clear All Caches + +```bash +# Metro bundler cache +npx expo start -c + +# npm cache +npm cache clean --force + +# iOS pods +cd ios && rm -rf Pods Podfile.lock && pod install && cd .. + +# Android build +cd android && ./gradlew clean && cd .. + +# Watchman (if installed) +watchman watch-del-all +``` + +### Reset Everything + +```bash +# Nuclear option - reset everything +rm -rf node_modules package-lock.json +cd ios && rm -rf Pods Podfile.lock && cd .. +cd android && ./gradlew clean && cd .. +npm install +cd ios && pod install && cd .. +``` + +## Performance Monitoring + +### React Native Performance + +```typescript +import { usePerformanceMonitor } from '@/hooks/use-performance-monitor' + +// In component +const { startTrace, stopTrace } = usePerformanceMonitor() + +const handleLoad = async () => { + startTrace('screen_load') + // ... load screen + stopTrace('screen_load') +} +``` + +### Firebase Performance + +```typescript +import perf from '@react-native-firebase/perf' + +const trace = await perf().startTrace('custom_trace') +// ... perform operation +await trace.stop() +``` + +## Security + +### Sensitive Data Handling + +```typescript +// ✅ Good - encrypted storage +import AsyncStorage from '@react-native-async-storage/async-storage' +await AsyncStorage.setItem('encrypted_mnemonic', encryptedData) + +// ❌ Bad - plain text +await AsyncStorage.setItem('mnemonic', plainTextMnemonic) + +// ✅ Good - derive on demand +const privateKey = derivePrivateKey(mnemonic, path) +signTransaction(tx, privateKey) +// privateKey is garbage collected + +// ❌ Bad - store private key +await AsyncStorage.setItem('private_key', privateKey) +``` + +### Authentication + +```typescript +import { SecureAuthService } from '@/services/secure-auth-service' + +// Check if authenticated +const isAuthenticated = await SecureAuthService.isAuthenticated() + +// Request authentication +const success = await SecureAuthService.authenticateWithBiometrics() +``` + +## API Rate Limiting + +### Esplora Service Best Practices + +```typescript +// ✅ Good - use service methods (built-in rate limiting) +const utxos = await esploraService.getAddressUtxos(address) + +// ❌ Bad - direct fetch (no rate limiting) +const response = await fetch(`https://blockstream.info/api/address/${address}/utxo`) + +// ✅ Good - sequential requests +for (const address of addresses) { + await esploraService.getAddressUtxos(address) +} + +// ❌ Bad - parallel requests (causes rate limiting) +await Promise.all(addresses.map(addr => fetch(`...`))) +``` + +## TypeScript + +### Common Types + +```typescript +import type { Wallet, Transaction, UTXO } from '@/types/wallet' + +// Wallet type +interface Wallet { + id: string + name: string + color: string + derivationPath: string + createdAt: number +} + +// Transaction type +interface Transaction { + txid: string + amount: number + timestamp: number + confirmations: number +} +``` + +### Type Safety + +```typescript +// ✅ Good - fully typed +const wallet: Wallet = await walletService.createWallet(name, color) + +// ❌ Bad - any type +const wallet: any = await walletService.createWallet(name, color) + +// ✅ Good - type guard +if (typeof data === 'object' && data !== null && 'txid' in data) { + // data is Transaction +} +``` + +## Resources + +- [README.md](../README.md) - Project overview +- [BUILD_GUIDE.md](BUILD_GUIDE.md) - Setup instructions +- [ARCHITECTURE.md](ARCHITECTURE.md) - Architecture overview +- [FIRST_TIME_CONTRIBUTORS.md](FIRST_TIME_CONTRIBUTORS.md) - Contributor guide +- [CONTRIBUTING.md](../CONTRIBUTING.md) - Contribution guidelines + +--- + +**For more detailed information, refer to the full documentation in the `docs/` folder.** diff --git a/docs/SKILLS_FEEDBACK_LOOP_SUMMARY.md b/docs/SKILLS_FEEDBACK_LOOP_SUMMARY.md new file mode 100644 index 00000000..0439424c --- /dev/null +++ b/docs/SKILLS_FEEDBACK_LOOP_SUMMARY.md @@ -0,0 +1,392 @@ +# Skills Feedback Loop System - Implementation Summary + +## Overview + +The BitSleuth Wallet now implements a **self-learning feedback loop system** for agent skills. Instead of static instruction files, skills become living, adaptive knowledge bases that evolve based on real-world usage outcomes. + +## What Was Implemented + +### 1. Core Infrastructure + +Created a complete feedback loop architecture with the following components: + +#### File Structure +``` +.github/skills/ +├── README.md # Skills directory overview +├── FEEDBACK_TEMPLATE.md # Template for recording feedback +├── FEEDBACK_LOOP_GUIDE.md # Complete system documentation (13KB) +├── FEEDBACK_EXAMPLES.md # Realistic usage examples (13KB) +│ +├── developer-guide/ +│ ├── SKILL.md # Core skill instructions (existing) +│ └── SKILL_MEMORY.md # NEW: Learning memory (2.7KB) +│ +├── frontend-design/ +│ ├── SKILL.md # Core skill instructions (existing) +│ └── SKILL_MEMORY.md # NEW: Learning memory (3.4KB) +│ +└── webapp-testing/ + ├── SKILL.md # Core skill instructions (existing) + └── SKILL_MEMORY.md # NEW: Learning memory (3.5KB) +``` + +### 2. Feedback Loop Mechanism + +Implemented a structured process for skills to learn from experience: + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Skill Usage Cycle │ +└─────────────────────────────────────────────────────────────┘ + │ + ▼ + ┌──────────────────────────────┐ + │ 1. Agent Invokes Skill │ + └──────────────────────────────┘ + │ + ▼ + ┌──────────────────────────────┐ + │ 2. Skill Executes Task │ + │ (guided by SKILL.md) │ + └──────────────────────────────┘ + │ + ▼ + ┌──────────────────────────────┐ + │ 3. Outcome Observed │ + │ SUCCESS / FAILURE / │ + │ PARTIAL │ + └──────────────────────────────┘ + │ + ▼ + ┌──────────────────────────────┐ + │ 4. Reflection & Recording │ + │ - What worked? │ + │ - What didn't? │ + │ - What was learned? │ + └──────────────────────────────┘ + │ + ▼ + ┌──────────────────────────────┐ + │ 5. Record in SKILL_MEMORY │ + │ (structured feedback) │ + └──────────────────────────────┘ + │ + ▼ + ┌──────────────────────────────┐ + │ 6. Pattern Recognition │ + │ - Repeated successes │ + │ - Repeated failures │ + │ - Common gaps │ + └──────────────────────────────┘ + │ + ▼ + ┌──────────────────────────────┐ + │ 7. Skill Evolution │ + │ Update SKILL.md based │ + │ on validated patterns │ + └──────────────────────────────┘ +``` + +### 3. Documentation Updates + +#### AGENTS.md +Added comprehensive "Skills Feedback Loop System" section (150+ lines) covering: +- How the system works +- Agent responsibilities (before, during, after skill usage) +- When to update SKILL.md vs. SKILL_MEMORY.md +- Example feedback entry +- Benefits and resources + +#### .github/skills/README.md +Created directory overview (200+ lines) with: +- Available skills summary +- File structure explanation +- Usage instructions for agents +- Philosophy and contribution guidelines + +#### .github/skills/FEEDBACK_TEMPLATE.md +Created standard template (3KB) for recording feedback entries with: +- Structured format for consistency +- Usage guidelines +- Complete example entry + +#### .github/skills/FEEDBACK_LOOP_GUIDE.md +Created comprehensive guide (13KB) covering: +- System architecture with visual diagram +- File relationships (SKILL.md vs. SKILL_MEMORY.md) +- Detailed agent workflows +- Best practices for recording and updating +- Maintenance guidelines +- Success metrics + +#### .github/skills/FEEDBACK_EXAMPLES.md +Created realistic examples (13KB) demonstrating: +- **Example 1**: Frontend design success scenario +- **Example 2**: Developer guide partial success +- **Example 3**: WebApp testing failure scenario +- **Example 4**: Cross-skill pattern recognition +- Key takeaways and learning principles + +### 4. Skill Memory Files + +Created three SKILL_MEMORY.md files, one for each skill: + +#### developer-guide/SKILL_MEMORY.md +- Purpose: Track technical development guidance outcomes +- Core principles: Accuracy, real-world validation, Bitcoin security first +- Feedback log template ready for entries +- Pattern recognition framework + +#### frontend-design/SKILL_MEMORY.md +- Purpose: Track mobile UI/UX design outcomes +- Core principles: Design intent, performance, platform native, accessibility +- Mobile-specific learning categories +- Design decisions archive + +#### webapp-testing/SKILL_MEMORY.md +- Purpose: Track testing and debugging outcomes +- Core principles: Real devices, reproducibility, fast feedback, security testing +- Testing workflow improvements tracking +- Known issues archive + +## How It Works + +### For Agents Using Skills + +**Before Usage:** +1. Read `SKILL.md` for core guidance +2. Read `SKILL_MEMORY.md` for recent learnings +3. Check for relevant patterns from past experiences + +**During Usage:** +- Apply guidance from both sources +- Note what works and what doesn't +- Observe outcomes carefully + +**After Usage:** +1. **Reflect** on the outcome (success/failure/partial) +2. **Record** in SKILL_MEMORY.md using template +3. **Identify** patterns across multiple entries +4. **Propose** SKILL.md updates if warranted + +### Feedback Entry Format + +Each feedback entry includes: +- **Timestamp** and **outcome** (SUCCESS/FAILURE/PARTIAL) +- **Task context**: What was attempted +- **Outcome**: What actually happened +- **What worked well**: Effective guidance +- **What didn't work**: Gaps or issues +- **Key learnings**: Insights gained +- **Recommended updates**: Specific improvements +- **Impact level**: HIGH/MEDIUM/LOW + +### Evolution Process + +**SKILL_MEMORY.md → SKILL.md** + +1. **Accumulate**: Feedback entries collected over time +2. **Recognize**: Patterns identified across multiple entries +3. **Validate**: Patterns confirmed in different contexts +4. **Update**: SKILL.md updated with proven improvements +5. **Document**: Changes logged in changelog + +## Key Principles + +### 1. Two-Tier Memory System + +**SKILL.md** (Core Instructions): +- Stable, foundational guidance +- Updated deliberately based on strong evidence +- Should not change frequently +- High confidence, validated patterns + +**SKILL_MEMORY.md** (Learning Buffer): +- Dynamic, evolving knowledge +- Updated after each significant usage +- Allows experimentation and observation +- Working memory that feeds into SKILL.md + +### 2. Evidence-Based Evolution + +Skills evolve based on: +- ✅ Real outcomes from actual usage +- ✅ Patterns validated across multiple instances +- ✅ Specific, actionable observations +- ✅ Both successes and failures + +NOT based on: +- ❌ Single isolated incidents (unless security-critical) +- ❌ Theoretical hunches +- ❌ Personal preferences +- ❌ Temporary workarounds + +### 3. Balanced Stability + +The system balances: +- **Stability**: SKILL.md remains consistent +- **Adaptability**: SKILL_MEMORY.md captures variation +- **Learning**: Patterns emerge over time +- **Improvement**: Validated insights upgrade skills + +## Benefits + +### 1. Continuous Improvement +- Skills get better with every use +- Learnings compound over time +- Each agent benefits from collective experience + +### 2. Institutional Memory +- Knowledge persists across agent sessions +- No need to re-learn the same lessons +- Historical context preserved in memory files + +### 3. Evidence-Based +- Changes based on real outcomes, not speculation +- Patterns validated through multiple uses +- High signal-to-noise ratio + +### 4. Collaborative Learning +- Multiple agents contribute to shared skills +- Diverse perspectives improve coverage +- Cross-pollination of insights + +### 5. Self-Correcting +- Failed guidance gets identified and corrected +- Successful patterns get reinforced +- Skills adapt to ecosystem changes + +## Usage Examples + +### Example 1: Successful Implementation + +Agent uses `frontend-design` skill to create a wallet card component. The spring animation guidance works perfectly, but long wallet names need truncation (not mentioned in SKILL.md). Agent records this in SKILL_MEMORY.md with MEDIUM impact. After 2-3 similar entries, text truncation guidance is added to SKILL.md. + +### Example 2: Critical Gap + +Agent uses `developer-guide` skill for fee estimation. SKILL.md mentions "exponential backoff" but provides no example. Implementation is difficult and time-consuming. Agent records HIGH impact feedback with specific retry logic example. After one more similar experience, concrete retry code is added to SKILL.md. + +### Example 3: Pattern Recognition + +Over several weeks, 9 feedback entries across all three skills mention Bitcoin address validation issues. Pattern recognition identifies this cross-skill gap. All three SKILL.md files are updated with address validation guidance, and shared documentation is created. + +## Maintenance + +### Recommended Workflow + +**Weekly Review**: +- Review new SKILL_MEMORY.md entries +- Identify emerging patterns +- Promote validated learnings to "Pending Updates" + +**Monthly Synthesis**: +- Review "Pending Updates" across all skills +- Update SKILL.md files with validated improvements +- Archive old SKILL_MEMORY.md entries if needed +- Document changes in changelogs + +**Quarterly Retrospective**: +- Assess overall skill effectiveness +- Identify skills needing major revisions +- Consider new skills based on recurring needs +- Refine the feedback process itself + +## Files Created + +| File | Size | Purpose | +|------|------|---------| +| `.github/skills/README.md` | 4.6KB | Skills directory overview | +| `.github/skills/FEEDBACK_TEMPLATE.md` | 3.1KB | Standard feedback format | +| `.github/skills/FEEDBACK_LOOP_GUIDE.md` | 13KB | Complete system guide | +| `.github/skills/FEEDBACK_EXAMPLES.md` | 13KB | Realistic examples | +| `.github/skills/developer-guide/SKILL_MEMORY.md` | 2.7KB | Developer guide memory | +| `.github/skills/frontend-design/SKILL_MEMORY.md` | 3.4KB | Frontend design memory | +| `.github/skills/webapp-testing/SKILL_MEMORY.md` | 3.5KB | WebApp testing memory | +| `AGENTS.md` (updated) | +5KB | Added feedback loop section | + +**Total**: 8 files created/updated, ~48KB of documentation + +## Success Metrics + +Track these indicators to measure effectiveness: + +1. **Feedback Volume**: Are agents consistently recording outcomes? +2. **Pattern Recognition**: Are patterns emerging from SKILL_MEMORY.md? +3. **SKILL.md Evolution**: Are skills being updated based on evidence? +4. **Task Success Rate**: Are skills becoming more effective over time? +5. **Coverage Gaps Closed**: Are identified gaps being addressed? + +## Next Steps + +### Immediate (Ready to Use) +1. ✅ System is fully operational +2. ✅ All documentation in place +3. ✅ Templates ready for use +4. ✅ Examples demonstrate the process + +### Short-term (As Skills Are Used) +1. Agents begin recording feedback after skill usage +2. SKILL_MEMORY.md files accumulate real entries +3. Patterns start to emerge from actual usage +4. First SKILL.md updates based on validated patterns + +### Medium-term (1-3 months) +1. Significant feedback data accumulated +2. Clear patterns identified across skills +3. SKILL.md files updated with proven improvements +4. System demonstrating measurable benefits + +### Long-term (Future Enhancements) +1. Automated pattern detection scripts +2. Cross-skill learning mechanisms +3. Version control integration +4. Impact measurement tools +5. Search and retrieval of historical feedback + +## Key Takeaways + +### The System Transforms Skills + +**Before**: Static instruction files +- Fixed guidance that becomes outdated +- No learning from mistakes +- No adaptation to changes +- Each agent starts from scratch + +**After**: Living, learning systems +- Guidance evolves based on outcomes +- Learns from both success and failure +- Adapts to ecosystem changes +- Collective intelligence builds over time + +### Philosophy + +> **Skills are not documentation—they are evolving knowledge systems.** + +Every skill usage is an opportunity to learn. By systematically recording outcomes and recognizing patterns, skills become more effective over time. This creates institutional memory that makes every agent more capable. + +### Agent Mindset + +When using skills, agents should: +- **Observe**: Pay attention to what works and what doesn't +- **Reflect**: Think about why things succeeded or failed +- **Record**: Document learnings for others +- **Contribute**: Help skills improve through feedback +- **Benefit**: Leverage accumulated knowledge from past uses + +## Conclusion + +The Skills Feedback Loop System is now fully implemented and operational. All skills have memory files ready to capture learnings. The documentation provides clear guidance for agents on how to use the system. As feedback accumulates, skills will evolve from static instructions into adaptive, self-improving knowledge bases. + +**The feedback loop is now active. Let the learning begin.** + +--- + +## References + +- **System Guide**: `.github/skills/FEEDBACK_LOOP_GUIDE.md` +- **Examples**: `.github/skills/FEEDBACK_EXAMPLES.md` +- **Template**: `.github/skills/FEEDBACK_TEMPLATE.md` +- **Agent Instructions**: `AGENTS.md` (Skills Feedback Loop section) +- **Skills Directory**: `.github/skills/README.md` diff --git a/package-lock.json b/package-lock.json index 224ad0e1..02cf1c99 100644 --- a/package-lock.json +++ b/package-lock.json @@ -3502,6 +3502,20 @@ } } }, + "node_modules/@firebase/auth-compat/node_modules/@react-native-async-storage/async-storage": { + "version": "1.24.0", + "resolved": "https://registry.npmjs.org/@react-native-async-storage/async-storage/-/async-storage-1.24.0.tgz", + "integrity": "sha512-W4/vbwUOYOjco0x3toB8QCr7EjIP6nE9G7o8PMguvvjYT5Awg09lyV4enACRx4s++PPulBiBSjL0KTFx2u0Z/g==", + "license": "MIT", + "optional": true, + "peer": true, + "dependencies": { + "merge-options": "^3.0.4" + }, + "peerDependencies": { + "react-native": "^0.0.0-0 || >=0.60 <1.0" + } + }, "node_modules/@firebase/auth-interop-types": { "version": "0.2.4", "resolved": "https://registry.npmjs.org/@firebase/auth-interop-types/-/auth-interop-types-0.2.4.tgz", @@ -11380,6 +11394,20 @@ } } }, + "node_modules/firebase/node_modules/@react-native-async-storage/async-storage": { + "version": "1.24.0", + "resolved": "https://registry.npmjs.org/@react-native-async-storage/async-storage/-/async-storage-1.24.0.tgz", + "integrity": "sha512-W4/vbwUOYOjco0x3toB8QCr7EjIP6nE9G7o8PMguvvjYT5Awg09lyV4enACRx4s++PPulBiBSjL0KTFx2u0Z/g==", + "license": "MIT", + "optional": true, + "peer": true, + "dependencies": { + "merge-options": "^3.0.4" + }, + "peerDependencies": { + "react-native": "^0.0.0-0 || >=0.60 <1.0" + } + }, "node_modules/flat-cache": { "version": "4.0.1", "resolved": "https://registry.npmjs.org/flat-cache/-/flat-cache-4.0.1.tgz", @@ -18528,6 +18556,23 @@ } } }, + "node_modules/tailwindcss/node_modules/yaml": { + "version": "2.8.2", + "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.8.2.tgz", + "integrity": "sha512-mplynKqc1C2hTVYxd0PU2xQAc22TI1vShAYGksCCfxbn/dFwnHTNi1bvYsBTkhdUNtGIf5xNOg938rrSSYvS9A==", + "license": "ISC", + "optional": true, + "peer": true, + "bin": { + "yaml": "bin.mjs" + }, + "engines": { + "node": ">= 14.6" + }, + "funding": { + "url": "https://github.com/sponsors/eemeli" + } + }, "node_modules/tar": { "version": "7.5.2", "resolved": "https://registry.npmjs.org/tar/-/tar-7.5.2.tgz",