zhongwei/gh-slamb2k-agent-smith-agent-smith-plugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
gh-slamb2k-agent-smith-agen…/skills/agent-smith/references/onboarding-guide.md
Zhongwei Li 8f952ee727 Initial commit
2025-11-30 08:57:54 +08:00

8.6 KiB
Raw Permalink Blame History

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)
  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

# 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 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:

# 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)

    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)

    uv run python scripts/operations/batch_categorize.py --mode=apply --period=2025-09:2025-11

  3. Full Backfill (complete the archive)

    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:

/agent-smith-categorize --mode=smart --period=2025-11

Monthly:

/agent-smith-analyze spending --period=2025-11
/agent-smith-health --quick

Quarterly:

/agent-smith-tax deductions --period=2024-25

Annual (EOFY):

/agent-smith-tax eofy

Time: 2 minutes

Troubleshooting

Onboarding Interrupted

If onboarding is interrupted, your progress is saved in data/onboarding_state.json.

Resume:

/agent-smith-onboard

Claude will detect saved state and offer to resume from where you left off.

Start Over:

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:

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

Welcome to Agent Smith! Let's transform your PocketSmith into an intelligent financial system.

Reference in New Issue View Git Blame Copy Permalink