agent-smith

What this skill does

# Agent Smith

An intelligent financial management skill for Claude Code that transforms PocketSmith from a passive tracking tool into an active financial intelligence system.

## Core Capabilities

### 1. Hybrid Rule Engine
- **Platform Rules**: Simple keyword patterns synced to PocketSmith API
- **Local Rules**: Advanced regex, multi-condition logic, confidence scoring
- **Intelligence Modes**: Conservative (manual approval), Smart (auto-apply ≥90%), Aggressive (auto-apply ≥80%)
- **Performance Tracking**: Rule accuracy, matches, user overrides

### 2. 3-Tier Tax Intelligence (Australian ATO)
- **Level 1 (Reference)**: ATO category mappings, basic tax reports, GST tracking
- **Level 2 (Smart)**: Deduction detection, CGT tracking, confidence scoring, expense splitting
- **Level 3 (Full)**: BAS preparation, compliance checks, scenario planning, audit-ready documentation

### 3. Transaction Categorization
- **Batch Processing**: Categorize uncategorized transactions with AI assistance
- **Merchant Intelligence**: Automatic payee normalization and variation detection
- **AI Fallback**: LLM-powered categorization when rules don't match
- **Dry-Run Mode**: Preview categorization before applying

### 4. Financial Analysis & Reporting
- **Spending Analysis**: By category, merchant, time period
- **Trend Detection**: Increasing/decreasing categories, anomaly detection
- **Multi-Format Reports**: Markdown, CSV/JSON, HTML dashboards, Excel
- **Comparative Analysis**: YoY, QoQ, MoM comparisons

### 5. Scenario Analysis
- **Historical**: What-if replays ("What if I cut dining by 30% last year?")
- **Projections**: Spending forecasts, affordability analysis, goal modeling
- **Optimization**: Subscription analysis, expense rationalization, tax optimization
- **Tax Planning**: Purchase timing, income deferral, CGT scenarios

### 6. Health Check System
- **6 Health Dimensions**: Data Quality, Category Structure, Rule Engine, Tax Readiness, Automation, Budget Alignment
- **Automated Monitoring**: Weekly checks, EOFY prep, post-operation validation
- **Prioritized Recommendations**: Top 3 highest-impact improvements

### 7. Advanced Features
- **Smart Alerts**: Budget overruns, tax thresholds, pattern detection
- **Document Tracking**: Receipt requirements ($300 ATO threshold)
- **Multi-User**: Shared expense tracking and settlement
- **Audit Trail**: Complete activity log with undo capability

## Quick Start

### First-Time Setup

1. **Prerequisites**:
   - PocketSmith account with API access
   - Developer API key from PocketSmith (Settings > Security)
   - Python 3.9+ with uv package manager

2. **Configuration**:
   - Copy `.env.sample` to `.env`
   - Add `POCKETSMITH_API_KEY=<your_key>`
   - Set `TAX_INTELLIGENCE_LEVEL=smart` (reference|smart|full)
   - Set `DEFAULT_INTELLIGENCE_MODE=smart` (conservative|smart|aggressive)

3. **Installation**:
   ```bash
   # From the skill directory
   uv sync
   ```

4. **Guided Onboarding**:
   ```bash
   # Launch integrated onboarding (8 stages)
   /agent-smith:install
   ```

The onboarding process will:
- Discover your PocketSmith account structure
- Recommend and apply a rule template
- Help customize rules for your needs
- Configure intelligence modes
- Incrementally categorize transactions
- Show measurable improvement with health scores
- Provide ongoing usage guidance
- Generate intelligent suggestions

**Time required**: 30-60 minutes for first-time setup

### Daily Usage

**Two Usage Modes:**

1. **Guided Journey Mode** - When you start Claude Code, Agent Smith displays a status dashboard with:
   - Your health score
   - Uncategorized transaction count
   - Conflicts awaiting review
   - Suggested next steps with both natural language and command options

2. **Power User Mode** - Use slash commands directly for specific operations.

**Slash Commands** (7 specialized commands):
- `/smith:install` - Installation and onboarding wizard
- `/smith:categorize [--mode] [--period]` - Transaction categorization
- `/smith:review-conflicts` - Review transactions flagged for review
- `/smith:health [--full|--quick]` - Health check and recommendations
- `/smith:insights <spending|trends|scenario|report>` - Financial analysis and reports
- `/smith:tax <deductions|cgt|bas|eofy>` - Tax intelligence (ATO)
- `/smith:schedule [--setup|--status|--remove]` - Automated categorization scheduling

## Python Scripts

All Python scripts are in `scripts/` directory. **Always run with `uv run python -u`** for proper dependency resolution and unbuffered output.

### Core Operations

```bash
# Categorize transactions
uv run python -u scripts/operations/batch_categorize.py --mode=smart --period=2025-11

# Run health check
uv run python -u scripts/health/check.py --full

# Generate spending report
uv run python -u scripts/reporting/generate.py --period=2025 --format=all

# Tax deduction analysis
uv run python -u scripts/tax/deduction_detector.py --period=2024-25
```

### Script Organization

- **`scripts/core/`** - API client, rule engine, unified rules
- **`scripts/operations/`** - Categorization, batch processing, transaction updates
- **`scripts/analysis/`** - Spending analysis, trend detection
- **`scripts/reporting/`** - Multi-format report generation
- **`scripts/tax/`** - ATO mappings, deductions, CGT, BAS preparation
- **`scripts/scenarios/`** - Historical, projections, optimization, tax scenarios
- **`scripts/status/`** - Status dashboard for SessionStart hook
- **`scripts/scheduled/`** - Automated scheduled tasks (cron/launchd)
- **`scripts/health/`** - Health check engine, recommendations, monitoring
- **`scripts/workflows/`** - Interactive categorization workflows
- **`scripts/utils/`** - Backup, validation, logging, merchant normalization

## Unified Rule System

Agent Smith uses a YAML-based unified rule system for transaction categorization and labeling.

### Quick Start with Rules

```bash
# 1. Choose a template for your household type
uv run python scripts/setup/template_selector.py

# 2. Customize rules in data/rules.yaml

# 3. Test with dry run
uv run python scripts/operations/batch_categorize.py --mode=dry_run --period=2025-11

# 4. Apply to transactions
uv run python scripts/operations/batch_categorize.py --mode=apply --period=2025-11
```

### Example Rule

```yaml
rules:
  # Category rule - categorize transactions
  - type: category
    name: WOOLWORTHS → Groceries
    patterns: [WOOLWORTHS, COLES, ALDI]
    category: Food & Dining > Groceries
    confidence: 95

  # Label rule - apply labels based on context
  - type: label
    name: Shared Groceries
    when:
      categories: [Groceries]
      accounts: [Shared Bills]
    labels: [Shared Expense, Essential]
```

### Key Features
- **Two-phase execution**: Categories first, then labels
- **Pattern matching**: Regex patterns with exclusions
- **Confidence scoring**: 0-100% for auto-apply logic
- **LLM fallback**: AI categorization when rules don't match
- **Intelligence modes**: Conservative/Smart/Aggressive
- **Template system**: Pre-built rules for common household types
- **Operational modes**: DRY_RUN/VALIDATE/APPLY for safe testing

See [references/unified-rules-guide.md](references/unified-rules-guide.md) for complete documentation.

## Tax Intelligence

### ATO Compliance (Australian Tax Office)

**Three Levels**:

1. **Reference (Level 1)**:
   - ATO category mappings
   - Basic tax reports
   - GST tracking
   - Resource links

2. **Smart (Level 2)** - Recommended:
   - Deduction detection (14 pattern-based rules)
   - CGT tracking with FIFO matching
   - Confidence scoring
   - Substantiation threshold checking ($300, $75 taxi/Uber)
   - Time-based commuting detection
   - Instant asset write-off tracking

3. **Full (Level 3)** - Power Users:
   - BAS preparation with GST calculations
   - Compliance checks
   - Scenario planning
   - Audit-ready documentation
   - Professional advice disclaimers

**Configure Tax Level**:
```bash
# In .env file
TAX_INTELLIGENCE_