zhongwei/gh-slamb2k-agent-smith-agent-smith-plugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:57:54 +08:00
commit 8f952ee727
50 changed files with 11199 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

327
skills/agent-smith/references/LESSONS_LEARNED.md Normal file
View File

@@ -0,0 +1,327 @@
# Lessons Learned from PocketSmith Migration
**Date:** 2025-11-23
**Source:** build/ directory reference materials (now archived)
This document captures key insights from a previous PocketSmith category migration project that informed Agent Smith's design.
---
## Table of Contents
1. [API Quirks and Workarounds](#api-quirks-and-workarounds)
2. [Category Hierarchy Best Practices](#category-hierarchy-best-practices)
3. [Transaction Categorization Patterns](#transaction-categorization-patterns)
4. [Merchant Name Normalization](#merchant-name-normalization)
5. [User Experience Lessons](#user-experience-lessons)
---
## API Quirks and Workarounds
### Category Rules API Limitations
**Issue:** PocketSmith API does not support updating or deleting category rules.
- GET `/categories/{id}/category_rules` works
- POST works (create only)
- PUT/PATCH/DELETE return 404 errors
**Impact:** Rules created via API cannot be modified programmatically.
**Agent Smith Solution:** Hybrid rule engine with local rules for complex logic, platform rules for simple keywords only.
### Transaction Migration 500 Errors
**Issue:** Bulk transaction updates sometimes fail with 500 Internal Server Errors.
**Root Cause:** Likely API rate limiting or server-side stability issues.
**Agent Smith Solution:**
- Implement rate limiting (0.1-0.5s delay between requests)
- Batch processing with progress tracking
- Retry logic with exponential backoff
- Always backup before bulk operations
### Special Characters in Category Names
**Issue:** Using "&" in category names causes 422 Unprocessable Entity errors.
**Workaround:** Replace "&" with "and" in all category names.
**Example:**
- ❌ "Takeaway & Food Delivery" → 422 error
- ✅ "Takeaway and Food Delivery" → Success
### Use PUT instead of PATCH
**Issue:** PATCH for transaction updates is unreliable in PocketSmith API.
**Solution:** Always use PUT for transaction updates.
```python
# ✅ Correct
response = requests.put(
f'https://api.pocketsmith.com/v2/transactions/{txn_id}',
headers=headers,
json={'category_id': category_id}
)
# ❌ Avoid (unreliable)
response = requests.patch(...)
```
---
## Category Hierarchy Best Practices
### Parent-Child Structure
**Recommendation:** Use 2-level hierarchy maximum.
- 12-15 parent categories for broad grouping
- 2-5 children per parent for specific tracking
- Avoid 3+ levels (PocketSmith UI gets cluttered)
**Example Structure:**
```
Food & Dining (parent)
├── Groceries
├── Restaurants
├── Takeaway and Food Delivery
└── Coffee Shops
```
### Duplicate Category Detection
**Problem:** Duplicate categories accumulate over time, causing confusion.
**Solution:** Before creating categories, check for existing matches:
1. Flatten nested category structure
2. Check both exact matches and case-insensitive matches
3. Check for variations (e.g., "Takeaway" vs "Takeaways")
**Agent Smith Implementation:** Category validation in health check system.
### Consolidation Strategy
**Insight:** Merging duplicate categories is risky:
- Requires migrating all associated transactions
- Transaction updates can fail (500 errors)
- Better to prevent duplicates than merge later
**Agent Smith Approach:** Template-based setup with validation prevents duplicates upfront.
---
## Transaction Categorization Patterns
### Pattern Matching Complexity
**Observation:** Transaction categorization evolved through multiple rounds:
- Round 1: Simple keyword matching (60% coverage)
- Round 2: Pattern matching with normalization (80% coverage)
- Round 3: User clarifications + edge cases (90% coverage)
- Round 4: Manual review of exceptions (95% coverage)
**Lesson:** Need both automated rules AND user override capability.
**Agent Smith Solution:** Tiered intelligence modes (Conservative/Smart/Aggressive) with confidence scoring.
### Confidence-Based Auto-Apply
**Insight:** Not all matches are equal:
- High confidence (95%+): Auto-apply safe (e.g., "WOOLWORTHS" → Groceries)
- Medium confidence (70-94%): Ask user (e.g., "LS DOLLI PL" → Coffee?)
- Low confidence (<70%): Always ask (e.g., "Purchase At Kac" → ???)
**Agent Smith Implementation:**
```python
if confidence >= 90: # Smart mode threshold
apply_automatically()
elif confidence >= 70:
ask_user_for_approval()
else:
skip_or_manual_review()
```
### Dry-Run Mode is Critical
**Lesson:** Always preview before bulk operations.
**Pattern from migration:**
```python
class BulkCategorizer:
def __init__(self, dry_run=True): # Default to dry-run!
self.dry_run = dry_run
def categorize_transactions(self):
if self.dry_run:
# Show what WOULD happen
return preview
else:
# Actually execute
return results
```
**Agent Smith Implementation:** All bulk operations support `--mode=dry_run` flag.
---
## Merchant Name Normalization
### Common Payee Patterns
**Observations from transaction data:**
1. **Location codes:** "WOOLWORTHS 1234" → "WOOLWORTHS"
2. **Legal suffixes:** "COLES PTY LTD" → "COLES"
3. **Country codes:** "UBER AU" → "UBER"
4. **Transaction codes:** "PURCHASE NSWxxx123" → "PURCHASE"
5. **Direct debit patterns:** "DIRECT DEBIT 12345" → "DIRECT DEBIT"
**Agent Smith Patterns:**
```python
LOCATION_CODE_PATTERN = r"\s+\d{4,}$"
SUFFIX_PATTERNS = [
r"\s+PTY\s+LTD$",
r"\s+LIMITED$",
r"\s+LTD$",
r"\s+AU$",
]
```
### Merchant Variation Grouping
**Problem:** Same merchant appears with multiple names:
- "woolworths"
- "WOOLWORTHS PTY LTD"
- "Woolworths 1234"
- "WOOLWORTHS SUPERMARKETS"
**Solution:** Learn canonical names from transaction history.
**Agent Smith Implementation:** `MerchantNormalizer.learn_from_transactions()` in scripts/utils/merchant_normalizer.py:101-130
---
## User Experience Lessons
### Backups are Non-Negotiable
**Critical Lesson:** ALWAYS backup before mutations.
**Migration practice:**
```python
def categorize_transactions(self):
# Step 1: Always backup first
self.backup_transactions()
# Step 2: Then execute
self.apply_changes()
```
**Agent Smith Policy:** Automatic backups before all mutation operations, tracked in backups/ directory.
### Progress Visibility Matters
**Problem:** Long-running operations feel broken without progress indicators.
**Solution:** Show progress every N iterations:
```python
for i, txn in enumerate(transactions, 1):
# Process transaction
if i % 100 == 0:
print(f"Progress: {i}/{total} ({i/total*100:.1f}%)")
```
**Agent Smith Implementation:** All batch operations show real-time progress.
### Manual Cleanup is Inevitable
**Reality Check:** Even after 5+ rounds of automated categorization, ~5% of transactions needed manual review.
**Reasons:**
- Genuinely ambiguous merchants ("Purchase At Kac" = gambling)
- One-off transactions (unique payees)
- Data quality issues (missing/incorrect payee names)
**Agent Smith Approach:** Make manual review easy with health check reports showing uncategorized transactions.
### Weekly Review Habit
**Post-migration recommendation:** Review recent transactions weekly for first month.
**Why:** Helps catch:
- Miscategorized transactions
- New merchants needing rules
- Changes in spending patterns
**Agent Smith Feature:** Smart alerts with weekly budget reviews (Phase 7).
---
## Implementation Timelines
### Migration Timeline (Reality vs Plan)
**Planned:** 35 minutes total
**Actual:** 3+ hours over multiple days
**Breakdown:**
- Category structure migration: 10 minutes (as planned)
- Rule recreation: 20 minutes (10 minutes planned - API limitations doubled time)
- Transaction categorization Round 1: 30 minutes
- Transaction categorization Round 2: 45 minutes
- Transaction categorization Round 3: 60 minutes
- Manual cleanup and verification: 90 minutes
**Lesson:** Budget 3-5x estimated time for data migration projects.
**Agent Smith Design:** Incremental onboarding (30-60 minutes initial setup, ongoing refinement).
---
## Key Takeaways for Agent Smith
### What We Built Better
1. **Hybrid Rule Engine:** Local + Platform rules overcome API limitations
2. **Confidence Scoring:** Tiered auto-apply based on pattern strength
3. **Merchant Intelligence:** Learned normalization from transaction history
4. **Health Checks:** Proactive detection of category/rule issues
5. **Template System:** Pre-built rule sets prevent common mistakes
### What We Avoided
1. **Manual rule migration** - Templates and import/export instead
2. **Duplicate categories** - Validation and health checks
3. **Bulk update failures** - Rate limiting, retry logic, batching
4. **Lost context** - Comprehensive backups with metadata
5. **User fatigue** - Incremental categorization, not all-at-once
### Core Principles
✅ **Backup before mutations**
✅ **Dry-run before execute**
✅ **Progress visibility**
✅ **Confidence-based automation**
✅ **User choice over forced automation**
✅ **Learn from transaction history**
✅ **Graceful degradation** (LLM fallback when rules don't match)
---
## Reference
**Original Materials:** Archived from `build/` directory (removed 2025-11-23)
**Full backup available at:** `../budget-smith-backup-20251120_093733/`
**See Also:**
- [Agent Smith Design](2025-11-20-agent-smith-design.md) - Complete system design
- [Unified Rules Guide](../guides/unified-rules-guide.md) - Rule engine documentation
- [Health Check Guide](../guides/health-check-guide.md) - Health scoring system
---
**Last Updated:** 2025-11-23

1324
skills/agent-smith/references/design.md Normal file
View File

File diff suppressed because it is too large Load Diff

408
skills/agent-smith/references/health-check-guide.md Normal file
View File

@@ -0,0 +1,408 @@
# Agent Smith Health Check Guide
## Introduction
The Agent Smith health check system provides a comprehensive assessment of your PocketSmith financial setup. It analyzes six key dimensions of your financial data management, identifies issues, and provides prioritized recommendations for improvement.
**Why use health checks?**
- **Proactive Issue Detection**: Catch problems before they affect your financial tracking
- **Continuous Improvement**: Track your setup quality over time with actionable metrics
- **Tax Readiness**: Ensure your categorization and data quality meet compliance requirements
- **Optimization Guidance**: Get specific recommendations to improve automation and accuracy
---
## The Six Health Dimensions
Agent Smith evaluates your PocketSmith setup across six weighted dimensions:
### 1. Data Quality (25% weight)
The foundation of accurate financial tracking. This dimension measures:
| Metric | Description | Target |
|--------|-------------|--------|
| Uncategorized Rate | Percentage of transactions without categories | < 5% |
| Duplicate Detection | Potential duplicate transactions identified | 0 |
| Data Gaps | Missing transaction periods | None |
| Description Quality | Transactions with meaningful descriptions | > 90% |
**Why it matters**: Poor data quality cascades into inaccurate reports, missed deductions, and unreliable budgets.
### 2. Category Structure (20% weight)
How well your category hierarchy is organized:
| Metric | Description | Target |
|--------|-------------|--------|
| Category Depth | Optimal nesting (2-4 levels) | Balanced |
| Unused Categories | Categories with no transactions | < 10% |
| Unclassified Amounts | Money in catch-all categories | < 3% |
| Category Distribution | Even spread across categories | No outliers |
**Why it matters**: A well-structured category system makes analysis meaningful and tax preparation straightforward.
### 3. Rule Engine (15% weight)
Effectiveness of your categorization rules:
| Metric | Description | Target |
|--------|-------------|--------|
| Rule Coverage | Transactions matched by rules | > 80% |
| Rule Efficiency | Rules that actively match transactions | > 70% |
| Conflict Detection | Rules with overlapping patterns | 0 |
| Pattern Quality | Specificity of rule patterns | High |
**Why it matters**: Strong rules reduce manual categorization work and ensure consistency.
### 4. Tax Readiness (15% weight)
Preparedness for tax reporting and compliance:
| Metric | Description | Target |
|--------|-------------|--------|
| Tax Category Coverage | Deductible expenses properly categorized | > 95% |
| Business/Personal Split | Clear separation where required | Complete |
| Receipt Documentation | Transactions over $82.50 with receipts | 100% |
| GST Tracking | GST amounts recorded where applicable | Complete |
**Why it matters**: Poor tax categorization means missed deductions and compliance risks.
### 5. Automation (10% weight)
Level of automated financial management:
| Metric | Description | Target |
|--------|-------------|--------|
| Savings Automation | Automated transfers to savings | Active |
| Bill Scheduling | Recurring bills tracked | > 90% |
| Account Sync Freshness | Time since last sync | < 24 hours |
| Auto-categorization Rate | Transactions auto-categorized | > 85% |
**Why it matters**: Automation reduces manual effort and prevents missed payments.
### 6. Budget Alignment (15% weight)
How well actual spending matches budgets:
| Metric | Description | Target |
|--------|-------------|--------|
| Budget Variance | Difference from planned amounts | < 10% |
| Overspending Categories | Categories over budget | < 20% |
| Budget Coverage | Expenses covered by budgets | > 80% |
| Forecast Accuracy | Predicted vs actual spending | > 85% |
**Why it matters**: Budget alignment indicates financial discipline and planning accuracy.
---
## How to Run Health Checks
### Using the Slash Command
Run a health check using the Agent Smith command:
```
/agent-smith-health
```
### Command Options
| Option | Description | Example |
|--------|-------------|---------|
| `full` | Complete analysis of all dimensions | `/agent-smith-health full` |
| `quick` | Fast check of critical metrics only | `/agent-smith-health quick` |
| `dimension` | Check specific dimension | `/agent-smith-health data-quality` |
| `compare` | Compare to previous check | `/agent-smith-health compare` |
### What Happens During a Health Check
1. **Data Collection**: Agent Smith queries your PocketSmith account
2. **Analysis**: Each dimension is evaluated against benchmarks
3. **Scoring**: Individual and overall scores are calculated
4. **Recommendations**: Prioritized action items are generated
5. **Report**: Results are displayed and optionally saved
---
## Interpreting Scores
### Score Ranges
| Range | Rating | Meaning |
|-------|--------|---------|
| 90-100 | Excellent | Your setup is optimized and well-maintained |
| 70-89 | Good | Solid foundation with minor improvements possible |
| 50-69 | Needs Attention | Several areas require improvement |
| 0-49 | Critical | Significant issues affecting financial tracking |
### Status Indicators
Throughout health check results, you will see these status indicators:
| Indicator | Meaning |
|-----------|---------|
| `[PASS]` | Metric meets or exceeds target |
| `[WARN]` | Metric is below target but not critical |
| `[FAIL]` | Metric requires immediate attention |
### Dimension Breakdown
Each dimension shows:
- **Score**: 0-100 for that dimension
- **Weight**: How much it contributes to overall score
- **Contribution**: Weighted points added to total
- **Status**: Overall health of that dimension
---
## Understanding Recommendations
Health checks generate prioritized recommendations to improve your score.
### Priority Levels
| Priority | Description | Action Timeframe |
|----------|-------------|------------------|
| **Critical** | Issues affecting data integrity or compliance | Immediate (today) |
| **High** | Significant impact on accuracy or efficiency | This week |
| **Medium** | Improvements for better organization | This month |
| **Low** | Nice-to-have optimizations | When convenient |
### Effort Estimates
Each recommendation includes an effort estimate:
| Effort | Typical Time | Examples |
|--------|--------------|----------|
| **Quick Win** | < 15 minutes | Enable a setting, create one rule |
| **Moderate** | 15-60 minutes | Reorganize categories, review duplicates |
| **Significant** | 1-4 hours | Major category restructure, bulk updates |
### Acting on Recommendations
Recommendations follow this format:
```
[PRIORITY] Recommendation Title
Issue: What the problem is
Impact: Why it matters
Action: Specific steps to fix it
Effort: Time estimate
```
**Best practice**: Start with critical/quick-win items for maximum impact with minimum effort.
---
## Automated Monitoring
### Weekly Health Checks
Agent Smith can run automated weekly health checks:
- **Schedule**: Every Sunday at midnight (configurable)
- **Storage**: Results saved to `data/health/weekly/`
- **Comparison**: Automatic comparison to previous week
### Score Drop Alerts
Get notified when your health score changes significantly:
| Alert Type | Trigger | Priority |
|------------|---------|----------|
| Critical Drop | Score falls below 50 | High |
| Significant Drop | Score drops > 15 points | Medium |
| Dimension Alert | Any dimension falls to Critical | High |
| Improvement | Score increases > 10 points | Info |
### Configuring Alerts
Set alert preferences in your environment or config:
```bash
# .env
HEALTH_CHECK_ALERTS=true
HEALTH_CHECK_THRESHOLD=15
```
Or in `data/config.json`:
```json
{
"healthCheck": {
"weeklyEnabled": true,
"alertOnDrop": true,
"dropThreshold": 15,
"notificationMethod": "summary"
}
}
```
---
## Example Output
Here is a sample health check result:
```
================================================================================
AGENT SMITH HEALTH CHECK
2025-01-15 09:30 AM
================================================================================
OVERALL SCORE: 74/100 [GOOD]
--------------------------------------------------------------------------------
DIMENSION BREAKDOWN
--------------------------------------------------------------------------------
Data Quality [################----] 80/100 (25%) = 20.0 pts
Category Structure [###############-----] 75/100 (20%) = 15.0 pts
Rule Engine [############--------] 60/100 (15%) = 9.0 pts [WARN]
Tax Readiness [################----] 82/100 (15%) = 12.3 pts
Automation [##############------] 70/100 (10%) = 7.0 pts
Budget Alignment [##############------] 72/100 (15%) = 10.8 pts
--------------------------------------------------------------------------------
KEY METRICS
--------------------------------------------------------------------------------
[PASS] Uncategorized transactions: 3.2% (target: <5%)
[PASS] Duplicate transactions: 0 found
[WARN] Rule coverage: 68% (target: >80%)
[PASS] Tax categories mapped: 94%
[WARN] Budget variance: 12% (target: <10%)
--------------------------------------------------------------------------------
RECOMMENDATIONS (5)
--------------------------------------------------------------------------------
[CRITICAL] Quick Win
Create rules for top 10 uncategorized merchants
Issue: 15 merchants account for 60% of uncategorized transactions
Impact: Could improve rule coverage by 12%
Action: Run `/agent-smith-categorize analyze` to generate rules
Effort: 15 minutes
[HIGH] Moderate
Review category "Other Expenses"
Issue: $2,340 in catch-all category this month
Impact: Affects reporting accuracy and tax deduction tracking
Action: Recategorize transactions or create more specific categories
Effort: 30 minutes
[MEDIUM] Quick Win
Enable automatic account sync
Issue: Manual sync causing 2-3 day delays
Impact: Budgets and forecasts using stale data
Action: Enable daily sync in PocketSmith settings
Effort: 5 minutes
[MEDIUM] Moderate
Reduce budget variance in "Dining Out"
Issue: Consistently 25% over budget
Impact: Unrealistic budget affecting financial planning
Action: Adjust budget or implement spending alerts
Effort: 15 minutes
[LOW] Quick Win
Archive unused categories
Issue: 8 categories with no transactions in 6+ months
Impact: Clutters category picker, minor UX issue
Action: Review and archive or delete unused categories
Effort: 10 minutes
--------------------------------------------------------------------------------
TREND (Last 4 Weeks)
--------------------------------------------------------------------------------
Week 1: 68 ████████████████░░░░
Week 2: 71 █████████████████░░░ (+3)
Week 3: 72 █████████████████░░░ (+1)
Week 4: 74 ██████████████████░░ (+2) <- Current
Trend: Improving (+6 over 4 weeks)
================================================================================
Next scheduled check: 2025-01-22 00:00
Run `/agent-smith-health compare` to see detailed changes
================================================================================
```
---
## Troubleshooting
### Common Issues
#### "Unable to connect to PocketSmith"
**Cause**: API key missing or invalid
**Solution**:
1. Check `.env` file contains `POCKETSMITH_API_KEY`
2. Verify the key is valid at PocketSmith Developer Settings
3. Ensure no extra whitespace around the key
#### "Health check taking too long"
**Cause**: Large transaction history or slow API response
**Solution**:
1. Use `/agent-smith-health quick` for faster results
2. Check your internet connection
3. Try again during off-peak hours
#### "Scores seem inaccurate"
**Cause**: Stale cached data or sync issues
**Solution**:
1. Force sync your PocketSmith accounts
2. Clear Agent Smith cache: check `data/cache/`
3. Run a full health check: `/agent-smith-health full`
#### "Recommendations don't apply to my situation"
**Cause**: Generic recommendations may not fit all users
**Solution**:
1. Adjust targets in `data/config.json`
2. Use `/agent-smith configure` to set your preferences
3. Dismiss inapplicable recommendations
#### "Missing dimension scores"
**Cause**: Insufficient data for analysis
**Solution**:
1. Ensure you have at least 30 days of transaction history
2. Verify all accounts are synced
3. Check that categories are set up in PocketSmith
### Getting Help
If issues persist:
1. Check `data/logs/` for error details
2. Run `/agent-smith-health --debug` for verbose output
3. Review the design documentation at `docs/design/`
---
## Quick Reference
| Task | Command |
|------|---------|
| Run full health check | `/agent-smith-health` |
| Quick check | `/agent-smith-health quick` |
| Check specific dimension | `/agent-smith-health data-quality` |
| Compare to last check | `/agent-smith-health compare` |
| View trends | `/agent-smith-health trends` |
| Configure alerts | `/agent-smith configure alerts` |
---
*For more information, see the complete [Agent Smith Design Document](../design/2025-11-20-agent-smith-design.md).*

344
skills/agent-smith/references/onboarding-guide.md Normal file
View File

@@ -0,0 +1,344 @@
# Agent Smith Onboarding Guide
Welcome to Agent Smith! This guide walks you through your first-time setup and helps you get the most out of your PocketSmith integration.
## Before You Begin
**Prerequisites:**
1. ✅ Agent Smith installed (see [INSTALL.md](../../INSTALL.md))
2. ✅ PocketSmith account with API access
3. ✅ API key configured in `.env` file
4. ✅ Python 3.9+ and `uv` installed
**Time Required:** 30-60 minutes (depending on transaction volume)
---
## The Onboarding Journey
Agent Smith's onboarding is an 8-stage interactive process that:
- Discovers your PocketSmith account structure
- Recommends and customizes rule templates
- Incrementally categorizes your transactions
- Shows measurable improvement with health scores
### Quick Start
```bash
# Launch the onboarding wizard
/agent-smith-onboard
```
Claude will guide you through each stage interactively.
---
## Stage 1: Prerequisites Check
**What happens:**
- Verifies Agent Smith installation
- Checks API key configuration
- Tests PocketSmith connection
**If something is missing:**
- Follow the prompts to complete installation
- Refer to [INSTALL.md](../../INSTALL.md) for detailed setup
**Time:** 2 minutes
---
## Stage 2: Discovery
**What happens:**
- Analyzes your PocketSmith account structure
- Counts accounts, categories, and transactions
- Identifies uncategorized transactions
- Calculates baseline health score
**What you'll see:**
```
✓ Connected as: your@email.com
✓ Accounts: 3 (Checking, Savings, Credit Card)
✓ Categories: 47
✓ Transactions: 2,387
✓ Uncategorized: 1,245 (52%)
✓ Date Range: Jan 2023 - Nov 2025
✓ Baseline Health Score: 45/100 (Critical)
✓ Recommended Template: shared-household
```
**Time:** 5-10 minutes (depends on data volume)
---
## Stage 3: Template Selection
**What happens:**
- Shows 4 template options
- Recommends best fit based on discovery
- Applies selected template to `data/rules.yaml`
**Templates:**
| Template | Best For | Includes |
|----------|----------|----------|
| **Simple** | Single person, basic tracking | Common categories, essential rules |
| **Separated Families** | Child support, shared custody | Kids expenses, contributor tracking |
| **Shared Household** | Couples, roommates | Shared expense tracking, approval workflows |
| **Advanced** | Business owners, investors | Tax optimization, investment tracking, CGT |
**What you'll do:**
- Review the recommendation
- Choose a template (or browse all)
- Confirm application
**Time:** 3-5 minutes
---
## Stage 4: Template Customization
**What happens:**
- Guides you to customize the template for your needs
**Customizations needed:**
1. **Account Mapping**
- Template uses generic names like "Shared Bills", "Personal"
- Update to match your actual account names
2. **Category Validation**
- Check if template categories exist in PocketSmith
- Create missing categories or map to existing ones
3. **Merchant Localization**
- Template has Australian merchants (WOOLWORTHS, COLES)
- Update for your region (SAFEWAY, KROGER, etc.)
**How to customize:**
- Edit `data/rules.yaml` manually (for now)
- Future versions will have interactive customization tool
**Example:**
```yaml
# Before (template)
- type: category
patterns: [WOOLWORTHS, COLES]
category: Food & Dining > Groceries
# After (customized for US)
- type: category
patterns: [SAFEWAY, KROGER, WHOLE FOODS]
category: Food & Dining > Groceries
```
**Time:** 10-20 minutes
---
## Stage 5: Intelligence Mode Selection
**What happens:**
- Configure AI categorization behavior
- Set tax intelligence level
**Categorization Mode:**
| Mode | Auto-Apply Threshold | Best For |
|------|---------------------|----------|
| Conservative | 100% (manual approval all) | First-time setup, learning |
| **Smart** (default) | ≥90% confidence | Most users, balanced |
| Aggressive | ≥80% confidence | High volume, trust AI |
**Tax Intelligence Level:**
| Level | Capabilities | Best For |
|-------|-------------|----------|
| Reference | ATO category mapping, basic reports | Users with accountants |
| **Smart** (default) | Deduction detection, thresholds | Most taxpayers |
| Full | BAS prep, compliance checks | Business owners, power users |
**Time:** 2 minutes
---
## Stage 6: Incremental Categorization
**What happens:**
- Categorize transactions in manageable batches
- Start recent, expand to historical
**Recommended Strategy:**
1. **Current Month** (test rules on small dataset)
```bash
uv run python scripts/operations/batch_categorize.py --mode=dry_run --period=2025-11
uv run python scripts/operations/batch_categorize.py --mode=apply --period=2025-11
```
2. **Last 3 Months** (validate at scale)
```bash
uv run python scripts/operations/batch_categorize.py --mode=apply --period=2025-09:2025-11
```
3. **Full Backfill** (complete the archive)
```bash
uv run python scripts/operations/batch_categorize.py --mode=apply --period=2023-01:2025-11
```
**After Each Batch:**
- Review results (matched, auto-applied, needs review)
- Approve medium-confidence suggestions
- Agent Smith learns new rules from your corrections
**Time:** 20-60 minutes (depends on volume and mode)
---
## Stage 7: Health Check & Progress
**What happens:**
- Run post-categorization health check
- Show before/after improvement
- Identify remaining priorities
**What you'll see:**
```
═══════════════════════════════════════════════
AGENT SMITH HEALTH CHECK - PROGRESS REPORT
═══════════════════════════════════════════════
Baseline (before): 45/100 (Critical)
Current: 78/100 (Good) ⬆ +33 points
Improvements:
• Data Quality: 42 → 88 (+46) ✅
• Rule Engine: 15 → 72 (+57) ✅
• Category Structure: 58 → 81 (+23) ✅
Remaining priorities:
1. Review tax category mappings
2. Add 3 more rules for recurring merchants
3. Create budgets for top 5 categories
```
**Time:** 5 minutes
---
## Stage 8: Ongoing Usage
**What happens:**
- Receive guidance on regular Agent Smith usage
- Get quick reference for common operations
**Daily/Weekly:**
```bash
/agent-smith-categorize --mode=smart --period=2025-11
```
**Monthly:**
```bash
/agent-smith-analyze spending --period=2025-11
/agent-smith-health --quick
```
**Quarterly:**
```bash
/agent-smith-tax deductions --period=2024-25
```
**Annual (EOFY):**
```bash
/agent-smith-tax eofy
```
**Time:** 2 minutes
---
## Troubleshooting
### Onboarding Interrupted
If onboarding is interrupted, your progress is saved in `data/onboarding_state.json`.
**Resume:**
```bash
/agent-smith-onboard
```
Claude will detect saved state and offer to resume from where you left off.
**Start Over:**
```bash
uv run python -c "from scripts.onboarding.state import OnboardingState; OnboardingState().reset()"
/agent-smith-onboard
```
### Discovery Fails
**Problem:** "Error during discovery: ..."
**Solutions:**
- Check `.env` has valid `POCKETSMITH_API_KEY`
- Verify PocketSmith account has API access enabled
- Check internet connection to api.pocketsmith.com
### Template Customization Unclear
**Problem:** Not sure how to customize `data/rules.yaml`
**Solutions:**
- Review [Unified Rules Guide](unified-rules-guide.md) for YAML syntax
- Check [Example Files](../examples/) for patterns
- Start with dry-run to test rules before applying
### Categorization Too Slow
**Problem:** Batch categorization taking too long
**Solutions:**
- Use smaller date ranges (1 month at a time)
- Switch to "Aggressive" mode for faster auto-apply
- Run in background with progress monitoring
---
## Next Steps
After completing onboarding:
1. **Set Up Alerts**
- Weekly budget reviews
- Monthly trend analysis
- Tax deadline reminders
2. **Create Budgets**
- Use health check recommendations
- Focus on top spending categories
- Track vs. budget monthly
3. **Optimize Rules**
- Review rule performance metrics
- Add rules for recurring merchants
- Refine confidence scores
4. **Explore Advanced Features**
- Scenario analysis
- Tax optimization
- Investment tracking
---
## Getting Help
- **Documentation:** [docs/](../INDEX.md)
- **API Reference:** [ai_docs/pocketsmith-api-documentation.md](../../ai_docs/pocketsmith-api-documentation.md)
- **Health Check Guide:** [health-check-guide.md](health-check-guide.md)
- **GitHub Issues:** [github.com/slamb2k/agent-smith/issues](https://github.com/slamb2k/agent-smith/issues)
---
**Welcome to Agent Smith! Let's transform your PocketSmith into an intelligent financial system.**

293
skills/agent-smith/references/pocketsmith-api.md Normal file
View File

@@ -0,0 +1,293 @@
# PocketSmith API Documentation (Offline Reference)
**API Version:** v2.0
**Base URL:** `https://api.pocketsmith.com/v2`
**Documentation Source:** https://developers.pocketsmith.com/
**Last Updated:** 2025-11-16
---
## Table of Contents
1. [Introduction](#introduction)
2. [Authentication](#authentication)
- [Developer Keys](#developer-keys-personal-tools)
- [OAuth 2.0](#oauth-20-multi-user-apps)
3. [API Reference](#api-reference)
- [Users](#users)
- [Institutions](#institutions)
- [Accounts](#accounts)
- [Transaction Accounts](#transaction-accounts)
- [Transactions](#transactions)
- [Categories](#categories)
- [Budgeting](#budgeting)
- [Supporting Resources](#supporting-resources)
4. [Common Topics](#common-topics)
- [Pagination](#pagination)
- [Error Handling](#error-handling)
5. [Changelog](#changelog)
6. [Support](#support)
---
## Introduction
The PocketSmith API is freely available to all developers without restrictions. The platform welcomes developers to build tools and integrations using their services.
**Developer Hub:** https://developers.pocketsmith.com/
---
## Authentication
PocketSmith provides two authentication methods depending on your use case.
### Developer Keys (Personal Tools)
For building personal tools like dashboard widgets or transaction importers, use developer keys.
**Configuration:**
- Manage keys in: Settings > Security within your PocketSmith account
- **Header:** `X-Developer-Key`
- **Access:** Persistent API access to your own account
**Example Request:**
```bash
curl --header "X-Developer-Key: YOUR_KEY_HERE" \
https://api.pocketsmith.com/v2/me
```
**Supported Languages:**
- Shell (curl)
- Node.js
- JavaScript
- PHP
- Python
### OAuth 2.0 (Multi-User Apps)
To create applications that other PocketSmith users can access, you'll need to use OAuth 2.0.
**Setup Process:**
1. **Register your application** by contacting the team at [email protected]
2. **Provide details** about yourself and your planned integration
3. **Receive credentials:** `client_id` and `client_secret` upon approval
4. **Implement authentication** using the OAuth integration guide
**OAuth Flow:**
- Standard OAuth 2.0 authorization code flow
- Detailed integration instructions available in the OAuth documentation section
---
## API Reference
The PocketSmith API v2.0 is organized around the following resource categories:
### Users
**Endpoints:**
- Get authorised user
- Get user by ID
- Update user information
**Example - Get the Authorised User:**
```
GET https://api.pocketsmith.com/v2/me
```
**Purpose:** Gets the user that corresponds to the access token used in the request.
**Authentication Required:** Yes (Header-based credentials)
---
### Institutions
Manage financial institutions connected to user accounts.
**Operations:**
- Create institution
- Read institution details
- Update institution information
- Delete institution
- List all institutions within a user account
---
### Accounts
Complete account management functionality.
**Operations:**
- Get account details
- Update account information
- Delete account
- Create new account
- Manage account ordering within users
- List accounts by institution
---
### Transaction Accounts
Transaction accounts are the specific accounts where transactions are recorded.
**Operations:**
- Get transaction account details
- Update transaction account
- List transaction accounts by user
---
### Transactions
Complete transaction lifecycle management with multi-context querying.
**Query Contexts:**
- By user
- By account
- By category
- By transaction account
**Operations:**
- Create transactions within transaction accounts
- Read transaction details
- Update transactions
- Delete transactions
- Query and filter transactions
---
### Categories
Manage and organize transaction categories.
**Operations:**
- Category management and organization
- List user-specific categories
- Create category rules
- Update categories
- Delete categories
---
### Budgeting
Budget management and analysis features.
**Features:**
- Budget retrieval and summaries
- Trend analysis
- Forecast cache management
---
### Supporting Resources
Additional resources for comprehensive financial data management:
- **Events** - Manage financial events
- **Attachments** - Attach files to transactions
- **Labels** - Label and tag transactions
- **Saved Searches** - Save frequently used search queries
- **Currencies** - Handle multi-currency support
- **Time Zones** - Manage timezone settings
---
## Common Topics
### Pagination
The API uses pagination for endpoints that return multiple records.
**Implementation Details:**
- Refer to the pagination documentation section for page size limits and navigation
- Response headers typically include pagination metadata
### Error Handling
The API returns standard HTTP status codes.
**Common Status Codes:**
- `200 OK` - Successful request
- `400 Bad Request` - Invalid request parameters
- `401 Unauthorized` - Authentication failure
- `403 Forbidden` - Insufficient permissions
- `404 Not Found` - Resource not found
- `500 Internal Server Error` - Server error
**Error Response Format:**
Detailed error handling documentation available at: https://developers.pocketsmith.com/docs
---
## Changelog
### v2.0 - Welcome to the new PocketSmith developer hub
**Posted:** Almost 7 years ago by Regan McEntyre
The development team announced an updated documentation portal: "We've given our developer documentation a bit of a spruce up. Come on in and check it out, and let us know what you think!"
**Current Status:**
- API Version 2.0 is the current stable version
- Interactive API documentation powered by OpenAPI 3 specification
---
## Support
**Contact the Development Team:**
- **Email:** [email protected]
**Resources:**
- **Interactive API Reference:** https://developers.pocketsmith.com/reference
- **Complete Guides:** https://developers.pocketsmith.com/docs
- **Changelog:** https://developers.pocketsmith.com/changelog
---
## Quick Start Guide
1. **For Personal Tools:**
```bash
# Get your developer key from Settings > Security
curl --header "X-Developer-Key: YOUR_KEY_HERE" \
https://api.pocketsmith.com/v2/me
```
2. **For Multi-User Applications:**
- Email [email protected] to register your app
- Implement OAuth 2.0 flow once approved
3. **Explore the API:**
- Start with the `/me` endpoint to verify authentication
- Review the resource categories that match your use case
- Test endpoints using the interactive reference
---
## Additional Notes
**OpenAPI Specification:**
The API documentation is built using OpenAPI 3, which means:
- Interactive testing tools available in the web interface
- Machine-readable API specifications
- Auto-generated client libraries possible
**Rate Limiting:**
Check the full documentation for any rate limiting policies.
**Best Practices:**
- Always handle errors gracefully
- Use pagination for large datasets
- Cache responses where appropriate
- Follow OAuth 2.0 best practices for multi-user apps
---
**End of Documentation**
For the most up-to-date information and interactive API testing, visit: https://developers.pocketsmith.com/

1810
skills/agent-smith/references/unified-rules-guide.md Normal file
View File

File diff suppressed because it is too large Load Diff