zhongwei/gh-slamb2k-agent-smith-agent-smith-plugin

Fork 0

Files

Zhongwei Li 8f952ee727 Initial commit

2025-11-30 08:57:54 +08:00

36 KiB

Raw Permalink Blame History

Agent Smith - Complete Design Specification

Design Date: 2025-11-20 Status: Approved Version: 1.0

Executive Summary

Agent Smith is an intelligent financial management skill for Claude Code that provides comprehensive PocketSmith API integration with advanced AI-powered analysis, rule management, tax intelligence, and scenario planning.

Name Origin: "Agent Smith" combines the PocketSmith platform reference with the Matrix's AI agent - a fitting metaphor for an intelligent assistant managing your financial matrix.

Key Value Proposition:

Transform PocketSmith from a passive tracking tool into an active financial intelligence system
Reduce manual financial admin time by 60-80% through intelligent automation
Provide proactive insights, alerts, and optimization recommendations
Ensure Australian tax compliance with ATO-aligned intelligence
Enable sophisticated financial scenario modeling and forecasting

Core Architecture
Directory Structure
Hybrid Rule Engine
Tax Intelligence Module
Scenario Analysis Engine
Subagent Orchestration
Slash Commands
Additional Features
Health Check System
Configuration
Implementation Roadmap

Core Architecture

Three-Tier System

1. API Integration Layer

Handles all PocketSmith API communication
Rate limiting and retry logic
Response caching (7-day TTL)
Error handling and fallback strategies
Automatic backup before mutations

2. Intelligence Engine

Hybrid Rule Engine: Platform-native + enhanced local rules
Tax Intelligence: 3-tier system (Reference, Smart, Full)
Scenario Analysis: Historical, projections, optimization, tax planning
AI Categorization: Tiered intelligence modes (Conservative, Smart, Aggressive)
Pattern Learning: Performance tracking and rule evolution

3. Orchestration Layer

Smart subagent conductor
Decision tree for delegation vs. direct handling
Parallel processing for bulk operations
Context preservation in main skill
Result aggregation and synthesis

Philosophy

Hybrid Approach:

Quick single-shot operations for simple tasks
Deep conversational sessions for complex workflows
User choice: always provide recommended mode but allow override
Context preservation through intelligent subagent orchestration

AI Intelligence Levels:

Conservative: User approval required for all actions
Smart: Auto-apply high-confidence (≥90%), ask for medium (70-89%)
Aggressive: Auto-apply ≥80% confidence, ask for 50-79%
User can override per operation

Directory Structure

~/.claude/skills/agent-smith/
├── agent-smith.md               # Main skill file (invocation point)
├── .env.sample                  # API key configuration template
├── .gitignore                   # Protect sensitive data
├── README.md                    # Skill documentation
├── INDEX.md                     # Master directory index
│
├── ai_docs/                     # Documentation for Claude subagents
│   ├── INDEX.md                 # Document catalog with descriptions
│   ├── pocketsmith-api-documentation.md
│   ├── category-optimization-guide.md
│   ├── ato-tax-guidelines.md
│   ├── rule-engine-architecture.md
│   └── subagent-protocols.md
│
├── backups/                     # Recent backups (30-day retention)
│   ├── INDEX.md                 # Latest backups with descriptions
│   ├── YYYY-MM-DD_HHMMSS/       # Timestamped backup sets
│   └── archive/                 # Older backups (compressed)
│       ├── INDEX.md             # Archived backup catalog
│       └── YYYY-MM/             # Monthly archives (.tar.gz)
│
├── data/                        # Working data & persistent state
│   ├── INDEX.md                 # Current state files & purpose
│   ├── config.json              # User preferences, modes, tax level
│   ├── rule_metadata.json       # Rule tracking & performance metrics
│   ├── platform_rules.json      # PocketSmith native rules created
│   ├── local_rules.json         # Enhanced local rule engine
│   ├── session_state.json       # Current session context
│   ├── alerts/
│   │   ├── alert_rules.json
│   │   ├── alert_history.json
│   │   └── alert_templates.json
│   ├── tax/
│   │   ├── INDEX.md
│   │   ├── ato_category_mappings.json
│   │   ├── deduction_rules.json
│   │   ├── thresholds.json
│   │   ├── cgt_register.json
│   │   └── substantiation_tracking.json
│   ├── scenarios/
│   │   ├── INDEX.md
│   │   ├── saved_scenarios.json
│   │   ├── scenario_templates.json
│   │   └── scenario_results/
│   ├── merchants/
│   │   ├── INDEX.md
│   │   └── merchant_intelligence.json
│   ├── investments/
│   │   ├── INDEX.md
│   │   ├── portfolio.json
│   │   ├── transactions.json
│   │   └── performance.json
│   ├── goals/
│   │   ├── INDEX.md
│   │   └── financial_goals.json
│   ├── health/
│   │   ├── INDEX.md
│   │   ├── health_scores.json
│   │   ├── recommendations.json
│   │   └── health_history/
│   ├── audit/
│   │   ├── INDEX.md
│   │   ├── transaction_changes.log
│   │   ├── category_changes.log
│   │   ├── rule_changes.log
│   │   └── api_activity.log
│   └── cache/                   # API response cache (7-day TTL)
│       ├── INDEX.md             # Cache inventory & freshness
│       └── *.json               # Cached responses
│
├── docs/                        # Generated documentation
│   ├── INDEX.md                 # Recent docs & analyses
│   ├── operations/              # Recent operation logs (30 days)
│   │   ├── INDEX.md             # Operation summaries
│   │   └── YYYY-MM-DD_*.md
│   ├── analyses/                # Recent analysis reports (90 days)
│   │   ├── INDEX.md             # Analysis catalog
│   │   └── *.md
│   ├── guides/                  # User guides (persistent)
│   │   └── INDEX.md
│   └── archive/                 # Older docs (compressed)
│       ├── INDEX.md
│       └── YYYY-MM/
│
├── logs/                        # Execution logs (14 days active)
│   ├── INDEX.md                 # Recent log summary
│   ├── api_calls.log            # API interaction log
│   ├── operations.log           # High-level operations
│   ├── errors.log               # Error tracking
│   └── archive/                 # Compressed historical logs
│       ├── INDEX.md
│       └── YYYY-MM.tar.gz
│
├── reports/                     # Multi-format output (90 days)
│   ├── INDEX.md                 # Recent reports catalog
│   ├── markdown/
│   │   ├── INDEX.md
│   │   └── *.md
│   ├── data/                    # CSV/JSON exports
│   │   ├── INDEX.md
│   │   └── *.{csv,json}
│   ├── interactive/             # HTML dashboards
│   │   ├── INDEX.md
│   │   └── *.html
│   ├── tax/                     # Tax-ready formats (7-year retention)
│   │   ├── INDEX.md
│   │   └── YYYY-*.{pdf,xlsx}
│   └── archive/                 # Older reports
│       ├── INDEX.md
│       └── YYYY-MM/
│
└── scripts/                     # Python utilities & subagent tools
    ├── INDEX.md                 # Script catalog & usage
    ├── core/                    # Core libraries (reusable)
    │   ├── api_client.py        # PocketSmith API wrapper
    │   ├── rule_engine.py       # Hybrid rule system
    │   ├── tax_intelligence.py  # Tax analysis module
    │   ├── scenario_engine.py   # Financial scenarios
    │   └── archiver.py          # Smart archiving engine
    ├── operations/              # Specific operation scripts
    │   ├── INDEX.md
    │   ├── categorize.py
    │   ├── analyze.py
    │   ├── optimize_categories.py
    │   └── generate_reports.py
    ├── subagents/               # Subagent definitions
    │   ├── categorization-agent.md
    │   ├── analysis-agent.md
    │   ├── reporting-agent.md
    │   ├── tax-agent.md
    │   ├── optimization-agent.md
    │   └── scenario-agent.md
    └── utils/                   # Helper utilities
        ├── INDEX.md
        ├── backup.py
        ├── validation.py
        ├── formatters.py
        └── index_updater.py     # Auto-update INDEX.md files

Smart Archiving Strategy

Retention Policies:

Cache: 7 days, auto-purge
Logs: 14 days active, then compress to monthly archives
Backups: 30 days recent, then monthly compressed archives
Operations docs: 30 days, then archive
Analyses/Reports: 90 days, then archive
Tax reports: 7 years (ATO requirement)

Archiving Process:

Automatic after operations
Compresses old files into monthly .tar.gz archives
Updates INDEX.md in archive directories
Manual archive/restore commands available

INDEX.md Auto-Update:

Every file creation/modification triggers index update
Contains: filename, creation date, size, description, tags
Enables LLM to quickly scan without reading all files
Sorted by relevance (newest first, or by type)

Hybrid Rule Engine

Architecture

Two-Tier System:

Platform Rules - PocketSmith native (via API)
Local Rules - Enhanced engine with advanced features

Platform Rules (PocketSmith Native):

Created via API for simple keyword patterns
Advantages: Auto-apply to future transactions server-side
Limitations: Keyword-only matching, no modification/deletion via API
Tracking: Metadata stored in data/platform_rules.json

Local Rules (Enhanced Engine):

Stored in data/local_rules.json
Capabilities:
- Regex pattern matching
- Multi-condition logic (amount ranges, date patterns, account filters)
- Confidence scoring (0-100%)
- Priority/precedence management
- Rule chaining (conditional rules)
- Negative patterns (exclusions)
- Statistical learning (accuracy tracking)

Rule Schema (Local)

{
  "rule_id": "uuid",
  "name": "Woolworths Groceries",
  "type": "local|platform|session",
  "pattern": {
    "payee_regex": "WOOLWORTHS.*",
    "amount_range": {"min": null, "max": null},
    "account_ids": [],
    "date_range": null,
    "excludes": ["WOOLWORTHS PETROL"]
  },
  "action": {
    "category_id": 12345,
    "confidence": 95,
    "requires_approval": false
  },
  "metadata": {
    "created": "2025-11-20",
    "created_by": "user|ai",
    "last_modified": "2025-11-20",
    "priority": 100,
    "tags": ["groceries", "auto-categorize"]
  },
  "performance": {
    "matches": 150,
    "applied": 148,
    "user_overrides": 2,
    "accuracy": 98.67,
    "last_used": "2025-11-19"
  }
}

Intelligence Modes

1. Conservative Mode:

All rules require user approval before applying
Best for: Initial setup, learning phase, high-stakes categorization

2. Smart Mode (Default):

Auto-apply rules with confidence ≥ 90%
Ask for approval: 70-89% confidence
Skip: < 70% confidence
Best for: Most users, balanced automation

3. Aggressive Mode:

Auto-apply confidence ≥ 80%
Ask for approval: 50-79% confidence
Skip: < 50% confidence
Best for: Experienced users, trusted rule sets

Session Rules

Temporary rules for one-off bulk operations
Stored in session_state.json, not persisted by default
User prompted: "Keep this rule for future use?"
Useful for: Bulk categorization, experimentation

Rule Lifecycle

Creation: AI suggests or user defines
Validation: Test against historical transactions (dry-run)
Application: Apply with chosen intelligence mode
Tracking: Record performance metrics
Evolution: Suggest refinements based on override patterns
Archival: Move low-performing rules to review queue

Platform Sync Strategy

Decision Logic:

if rule.is_simple_keyword() and not rule.has_exclusions():
    # Create via PocketSmith API
    create_platform_rule(rule)
    track_in_platform_rules_json(rule)
else:
    # Keep local-only
    store_in_local_rules_json(rule)

Migration Tool:

Convert proven local rules to platform rules when possible
Audit which rules are platform vs. local
Bulk migration capability

Tax Intelligence Module

Three-Tier System

Configuration:

Environment variable: TAX_INTELLIGENCE_LEVEL=reference|smart|full
Runtime override: --tax-level=full
Interactive prompt when ambiguous

Level 1: Reference & Reporting

Capabilities:

Generate tax-ready expense summaries by category
Map PocketSmith categories to ATO expense categories
Basic GST tracking (GST paid on business purchases)
Flag potential deductible expenses based on category
Link to relevant ATO resources and guides
Simple reports: "You spent $X on deductible categories"

Output:

Factual reporting with resource links
No advice given
CSV exports mapped to ATO tax return categories

Use Case: Users who have accountants, just need organized data

Level 2: Smart Categorization Assistant

Everything from Level 1, PLUS:

Advanced Detection:

Flag transactions likely deductible based on payee patterns
Suggest expense splitting (mixed personal/business)
Identify missing documentation requirements
Track capital gains/losses events (asset purchases/sales)
Calculate vehicle logbook percentages from fuel/service patterns
Monitor common deduction thresholds ($300 receipt rule, etc.)
Detect home office expense patterns
Flag estimated tax obligations based on income patterns

Intelligent Suggestions:

"This $850 laptop purchase may be instantly deductible"
"Detected 15 Uber rides to/from work - likely NOT deductible"
"Mobile phone bill: consider 50/50 split for business deduction"

Capital Gains Tracking:

Detect asset purchase/sale pairs
Calculate holding periods
Flag CGT discount eligibility (> 12 months)
Track cost base adjustments

Output: Actionable insights with "consult your accountant" disclaimers

Use Case: Most users, proactive tax optimization

Level 3: Full Compliance Suite

Everything from Levels 1 & 2, PLUS:

Comprehensive Tax Management:

Deduction Optimization:

Track deductions against ATO category limits and guidelines
Suggest timing optimizations (prepay expenses before EOFY)
Identify bundling opportunities
Compare deduction methods (actual vs. standard rates)
Monitor substantiation requirements by category

BAS & GST Management:

BAS-ready reports (quarterly/monthly)
GST paid vs. collected tracking
Input tax credit calculations
PAYG installment tracking
BAS reconciliation reports

Threshold Monitoring:

$300 substantiation threshold
$75 taxi/Uber receipt requirements
FBT thresholds
Small business entity thresholds ($10M turnover)
Instant asset write-off limits (currently $20,000)

Investment & CGT Intelligence:

Comprehensive CGT register
Cost base tracking (purchase price + incidental costs)
Dividend tracking (franked/unfranked)
Foreign income detection
Cryptocurrency transaction tracking
Wash sale detection

Scenario Planning:

"Sell investment now vs. after 12 months - tax impact?"
"Prepay insurance before EOFY - savings?"
"You're approaching threshold X - implications"

Compliance Checks:

Cross-reference expenses against ATO audit triggers
Identify unusual patterns
Verify substantiation completeness
Generate audit-ready documentation

Reports Generated:

Tax return schedule summaries (D1-D15)
BAS worksheets
CGT schedule
Depreciation schedules
Home office calculation worksheets
Vehicle logbook summaries

Disclaimers:

All Level 3 outputs include: "This analysis is for informational purposes. Consult a registered tax agent for advice."
Flags complex situations requiring professional review

Use Case: Power users, small business owners, serious tax optimization

ATO Documentation Caching

Smart Documentation Strategy:

Local Cache Structure:

ai_docs/tax/
├── INDEX.md
├── cache_metadata.json
├── ato_guidelines/
│   ├── motor_vehicle_expenses_2025.md
│   ├── home_office_deductions_2025.md
│   ├── capital_gains_tax_2025.md
│   └── instant_asset_writeoff_2025.md
├── legislation/
│   ├── income_tax_rates_2024-25.json
│   ├── gst_rules.md
│   └── substantiation_requirements.md
└── archived/
    └── YYYY/

Cache Metadata:

{
  "document_id": "motor_vehicle_expenses_2025",
  "source_url": "https://www.ato.gov.au/...",
  "cached_date": "2025-11-01",
  "last_verified": "2025-11-20",
  "content_hash": "abc123...",
  "refresh_policy": "monthly",
  "expiry_date": "2025-12-01",
  "version": "v2.1",
  "change_log": [
    {
      "date": "2025-11-15",
      "change": "Updated instant asset write-off threshold to $20,000"
    }
  ]
}

Smart Refresh Strategy:

Automatic Checks:
- Monthly refresh of all cached docs
- Pre-EOFY force refresh (May-June)
- Post-Budget alert (October)
On-Demand Verification:
- Before generating tax reports: check for doc updates
- Compare cached vs. online versions
- Highlight changes to user
Integration with Tax Levels:
- Level 1: Use cached docs, verify monthly
- Level 2: Verify before recommendations
- Level 3: Always verify freshness before compliance operations

Commands:

refresh-tax-cache - Force refresh
verify-tax-cache - Check for updates
diff-tax-changes - Show changes since last cache

Scenario Analysis Engine

Four Scenario Types

1. Historical Analysis

What-If Replays:

"What if I had cut dining out by 30% in 2024?"
"Show impact of eliminating subscription X"
"What if I had sold investment Y in June vs. December?"

Trend Analysis:

Compare spending across periods (YoY, QoQ, MoM)
Identify trending categories
Seasonal pattern detection
Anomaly detection

Comparative Scenarios:

Actual vs. Budget variance
Category spending comparisons
Account-level analysis

2. Future Projections

Spending Forecasts:

Project based on historical patterns
Seasonal adjustments
Account for known upcoming changes
Confidence intervals (optimistic/pessimistic/realistic)

Affordability Analysis:

"Can I afford a $500/month car payment?"
"Impact of $15k annual expense on cash flow?"
Cash flow projections (monthly surplus/deficit)

Goal Modeling:

"Save $20k by Dec 2026 - required monthly savings?"
"Retire at 60 - monthly savings needed?"
Investment growth projections

Algorithm:

Analyze historical patterns (12-24 months)
Detect trends (increasing/decreasing categories)
Apply seasonal adjustments
Factor in inflation (configurable %)
Account for known future changes
Generate 3 scenarios: conservative/realistic/optimistic
Project forward 3/6/12/24 months

3. Optimization Engine

AI-Suggested Opportunities:

Subscription Analysis:

Detect recurring payments
Identify unused/underutilized subscriptions
Calculate consolidation savings
Suggest alternatives

Category Trend Alerts:

Flag categories trending up >10%
Identify unusual spending patterns
Compare to peer benchmarks (optional)
Suggest budget adjustments

Expense Rationalization:

Duplicate service detection
Identify optimization opportunities
Bundle opportunities

Tax Optimization:

Prepayment opportunities before EOFY
Timing of asset sales (CGT optimization)
Salary sacrifice recommendations
Deduction maximization strategies

4. Tax Scenario Planning

Pre-Purchase Analysis:

"Buy $25k equipment now vs. next FY - tax impact?"
"Instant asset write-off vs. depreciation?"
"Salary sacrifice $10k to super - net benefit?"

Income Timing:

"Defer $20k invoice to next FY - tax savings?"
"Bonus timing optimization"
"Capital gain timing (< or > 12 months)"

Deduction Optimization:

"Prepay 12 months insurance before EOFY - deductible?"
"Extra super contribution - tax benefit?"
"Bring forward expenses - impact?"

CGT Scenarios:

"Sell now (8 months held) vs. wait 4 months (CGT discount)"
"Offset gains with losses - which assets?"
"Distribute gains across financial years"

Subagent Orchestration

Orchestration Decision Tree

def should_delegate(operation):
    """Decide if operation should use subagent"""

    # Always delegate
    if operation.type in ['bulk_processing', 'deep_analysis', 'multi_period']:
        return True

    # Check complexity
    if operation.transaction_count > 100:
        return True

    if operation.estimated_tokens > 5000:
        return True

    # Check parallelization opportunity
    if operation.can_parallelize:
        return True

    # Simple queries stay in main context
    return False

Subagent Types

Specialized Workers:

categorization-agent.md - Transaction categorization
analysis-agent.md - Financial analysis
reporting-agent.md - Report generation
tax-agent.md - Tax intelligence operations
optimization-agent.md - Category/rule optimization
scenario-agent.md - Scenario modeling

Processing Patterns

1. Parallel Processing:

Multi-period analysis (12 months → 12 parallel agents)
Category-wise deep dives (top 5 categories → 5 agents)
Bulk categorization (500 transactions → 5 batches → 5 agents)

2. Sequential Delegation:

Complex workflows requiring user approval between steps
Each step's output feeds next step
Main skill orchestrates and presents results

3. Smart Context Management:

Main Skill Handles:

User preferences and configuration
Session state
High-level decision making
User interaction and approvals
Result aggregation

Subagents Handle:

Large data processing
API-intensive operations
Detailed analysis
Report generation
Rule application
Complex calculations

Communication Protocol

Delegation Message Format:

You are a specialized {operation_type} agent for Agent Smith.

CONTEXT:
- User: {user_id}
- Operation: {operation_description}
- Intelligence Mode: {conservative|smart|aggressive}
- Tax Level: {reference|smart|full}

DATA:
{relevant_data_subset}

REFERENCES:
- API Documentation: ai_docs/pocketsmith-api-documentation.md
- {operation_specific_docs}

TASK:
{specific_instructions}

OUTPUT FORMAT:
{expected_output_schema}

CONSTRAINTS:
- Dry-run mode: {true|false}
- Maximum API calls: {limit}
- Backup before mutations: {true|false}

Response Format:

{
  "status": "success|error|partial",
  "operation": "categorization",
  "summary": "Categorized 95/100 transactions",
  "results": {
    "categorized": 95,
    "skipped": 5,
    "rules_applied": 12,
    "new_rules_suggested": 3
  },
  "details": {},
  "errors": [],
  "recommendations": [],
  "next_steps": []
}

Slash Commands

Command Structure

.claude/commands/
├── agent-smith.md                      # Installation and onboarding
├── agent-smith-categorize.md           # Transaction categorization
├── agent-smith-analyze.md              # Financial analysis
├── agent-smith-report.md               # Report generation
├── agent-smith-scenario.md             # Scenario modeling
├── agent-smith-optimize.md             # Optimization operations
├── agent-smith-tax.md                  # Tax intelligence
└── agent-smith-health.md               # Health check

Command Definitions

1. /agent-smith - Main Conversational Skill

Start a conversational Agent Smith session for complex multi-step operations.
Use for workflows involving multiple operations or guided assistance.

2. /agent-smith-categorize [--mode] [--period]

Categorize uncategorized transactions with AI assistance.

Arguments:
  --mode=conservative|smart|aggressive  Intelligence level (default: smart)
  --period=YYYY-MM                      Target specific month/year
  --account=ID                          Limit to specific account
  --dry-run                             Preview without applying

Examples:
  /agent-smith-categorize
  /agent-smith-categorize --mode=aggressive --period=2025-11

3. /agent-smith-analyze [type] [--period]

Run financial analysis on PocketSmith data.

Arguments:
  type: spending|trends|category|tax|insights
  --period=YYYY-MM or YYYY
  --category=ID
  --compare=YYYY-MM
  --tax-level=reference|smart|full

Examples:
  /agent-smith-analyze spending --period=2025
  /agent-smith-analyze trends --compare=2024

4. /agent-smith-scenario [type] [description]

Model financial scenarios: what-if, projections, optimization, tax planning.

Arguments:
  type: historical|projection|optimization|tax
  description: Natural language scenario description

Examples:
  /agent-smith-scenario historical "What if I cut dining by 25% last year?"
  /agent-smith-scenario projection "Can I afford $600/month car payment?"
  /agent-smith-scenario tax "Buy $25k equipment before or after EOFY?"

5. /agent-smith-report [format] [--period]

Generate comprehensive reports in various formats.

Arguments:
  format: summary|detailed|tax|custom
  --period=YYYY-MM or YYYY
  --output=markdown|csv|json|html|excel|all
  --tax-level=reference|smart|full

Examples:
  /agent-smith-report summary --period=2025-Q4
  /agent-smith-report tax --period=2024-25 --tax-level=full

6. /agent-smith-optimize [target]

AI-assisted optimization for categories, rules, or spending.

Arguments:
  target: categories|rules|spending|subscriptions

Examples:
  /agent-smith-optimize categories
  /agent-smith-optimize rules

7. /agent-smith-tax [operation] [--period]

Tax-focused analysis, deduction tracking, compliance reporting.

Arguments:
  operation: deductions|cgt|bas|eofy|scenario
  --period=YYYY-YY
  --level=reference|smart|full

Examples:
  /agent-smith-tax deductions --period=2024-25
  /agent-smith-tax eofy

8. /agent-smith-health [--full]

Evaluate PocketSmith setup and get optimization recommendations.

Arguments:
  --full                    Complete deep analysis
  --quick                   Fast essential checks
  --category=area           Specific area: categories|rules|tax|data

Examples:
  /agent-smith-health
  /agent-smith-health --full

Additional Features

1. Smart Alerts & Notifications

Alert Types:

Budget alerts (overspending, trending)
Tax alerts (thresholds, EOFY deadlines, CGT timing)
Pattern alerts (new recurring charges, duplicates, unusual transactions)
Optimization alerts (unused subscriptions, fee increases)

Scheduling:

Weekly spending summary
Monthly budget review
Quarterly trend analysis
EOFY tax prep reminder (May)
Post-budget cache refresh (October)

2. Merchant Intelligence

Automated Payee Enrichment:

Detect payee variations automatically
Group similar transactions
Learn from user corrections
Suggest canonical names

Merchant Insights:

Spending patterns by merchant
Price trend tracking
Optimization suggestions

3. Receipt & Document Management

Integration with PocketSmith Attachments:

Flag transactions requiring receipts (>$300)
Track missing documentation
Generate substantiation reports
OCR receipt data
Auto-link receipts to transactions

4. Multi-User & Shared Expense Tracking

Household Finance:

Track shared expenses
Calculate settlement amounts
Split transactions by custom ratios
Generate "who owes whom" reports

5. Investment Tracking

Portfolio Integration:

Link transactions to investment events
Track cost basis
Calculate unrealized gains/losses
CGT optimization
Dividend tracking
Performance vs. benchmarks

6. Cash Flow Forecasting

Intelligent Liquidity Management:

Predict future account balances
Identify potential shortfalls
Optimize payment timing
Track recurring payments
Model major purchase impact

7. Goal Tracking

Financial Goals:

Emergency fund
House deposit
Debt payoff
Investment targets
Retirement savings

Progress Tracking:

Automatic updates
On-track vs. behind alerts
Required contribution adjustments
Milestone celebrations

8. Comparative Benchmarking

Anonymous Peer Comparison (Opt-In):

Compare spending to similar households
Privacy-first (aggregated, anonymized)
Configurable peer criteria

9. Audit Trail

Complete Activity Log:

Every transaction modification
Category structure changes
Rule creation/updates
Bulk operations
Report generation

Benefits:

"Undo" capability
Compliance tracking
Troubleshooting
Accountability

10. Smart Backup & Recovery

Automated Protection:

Before every bulk operation
Daily automatic backups (if changes made)
Pre-migration snapshots
Configurable retention

Recovery Tools:

List backups
Preview backup contents
Selective restore
Full restore
Diff between backup and current

Health Check System

Six Health Scores

1. Data Quality (0-100)

Categorization coverage
Data completeness
Data consistency

2. Category Structure (0-100)

Hierarchy optimization
Category usage
Tax alignment

3. Rule Engine (0-100)

Rule coverage
Rule quality
Rule completeness

4. Tax Readiness (0-100)

ATO compliance
Tax category mapping
EOFY preparation

5. Automation & Efficiency (0-100)

Agent Smith utilization
PocketSmith feature usage
Data entry efficiency

6. Overall Health

Composite of all scores
Top 3 priorities identified
Impact projections

Health Check Output

🏥 AGENT SMITH HEALTH CHECK - OVERALL
════════════════════════════════════════

Overall Score: 59/100 (Fair)

Individual Scores:
├─ Data Quality:        72/100  ✅ Good
├─ Category Structure:  58/100  ⚠️ Needs Work
├─ Rule Engine:         45/100  ⚠️ Needs Improvement
├─ Tax Readiness:       68/100  ⚠️ Fair
└─ Automation:          52/100  ⚠️ Moderate

🎯 TOP 3 PRIORITIES:
1. CREATE CATEGORY HIERARCHY (Highest Impact)
2. EXPAND RULE COVERAGE (Quick Win)
3. TAX COMPLIANCE FIXES (Risk Reduction)

After completing: Projected score 96/100

Automated Health Monitoring

Periodic Checks:

Weekly quick health check
Monthly full health analysis
Pre-EOFY comprehensive check
Post-major-operation validation

Proactive Alerts:

Health score changes
New recommendations
Declining tax readiness

Configuration

.env.sample

# PocketSmith API Authentication
POCKETSMITH_API_KEY=<Your Developer API Key>

# Agent Smith Configuration
TAX_INTELLIGENCE_LEVEL=smart          # reference|smart|full
DEFAULT_INTELLIGENCE_MODE=smart       # conservative|smart|aggressive
AUTO_BACKUP=true
AUTO_ARCHIVE=true
ALERT_NOTIFICATIONS=true

# Tax Configuration (Australia)
TAX_JURISDICTION=AU
FINANCIAL_YEAR_END=06-30             # June 30
GST_REGISTERED=false

# Reporting Preferences
DEFAULT_REPORT_FORMAT=all            # markdown|csv|json|html|excel|all
CURRENCY=AUD

# Advanced
API_RATE_LIMIT_DELAY=100             # ms between calls
CACHE_TTL_DAYS=7
SUBAGENT_MAX_PARALLEL=5

User Preferences (data/config.json)

{
  "user_id": 217031,
  "tax_level": "smart",
  "intelligence_mode": "smart",
  "alerts_enabled": true,
  "alert_preferences": {
    "budget": true,
    "tax": true,
    "patterns": true,
    "optimization": true,
    "frequency": "weekly"
  },
  "backup_before_mutations": true,
  "auto_archive": true,
  "default_report_formats": ["markdown", "csv", "html"],
  "household": {
    "enabled": false,
    "members": [],
    "split_method": "proportional"
  },
  "benchmarking": {
    "enabled": false,
    "criteria": {}
  }
}

Implementation Roadmap

Phase 1: Foundation (Weeks 1-2)

Core Infrastructure:

✅ Directory structure creation
✅ .env.sample and configuration files
✅ INDEX.md templates for all directories
✅ Python core libraries:
- api_client.py (PocketSmith API wrapper)
- archiver.py (smart archiving engine)
- index_updater.py (INDEX.md automation)
- backup.py (backup/restore utilities)
- validation.py (data validation)

Basic Functionality:

✅ API authentication and basic queries
✅ Backup/restore system
✅ Archiving automation
✅ Logging infrastructure

Phase 2: Rule Engine (Weeks 3-4)

Hybrid Rule System:

✅ Local rule engine implementation
✅ Platform rule tracking
✅ Rule performance metrics
✅ Intelligence mode implementation
✅ Session rules
✅ Rule validation and testing

Categorization:

✅ Basic categorization workflow
✅ Batch categorization
✅ Rule suggestion engine
✅ Merchant normalization

Phase 3: Analysis & Reporting (Weeks 5-6)

Analysis Engine:

✅ Spending analysis
✅ Trend detection
✅ Category analysis
✅ Pattern recognition

Multi-Format Reporting:

✅ Markdown reports
✅ CSV/JSON exports
✅ HTML dashboards (interactive)
✅ Excel generation

Phase 4: Tax Intelligence (Weeks 7-8)

3-Tier Tax System:

✅ Level 1: Reference & Reporting
✅ Level 2: Smart Categorization Assistant
✅ Level 3: Full Compliance Suite

ATO Integration:

✅ Documentation caching
✅ Category mappings
✅ Deduction rules
✅ CGT register
✅ BAS preparation

Phase 5: Scenario Analysis (Weeks 9-10)

Scenario Engine:

✅ Historical analysis
✅ Future projections
✅ Optimization engine
✅ Tax scenario planning

Advanced Analytics:

✅ Cash flow forecasting
✅ Goal tracking
✅ Investment tracking

Phase 6: Orchestration & UX (Weeks 11-12)

Subagent System:

✅ Subagent definitions
✅ Orchestration logic
✅ Parallel processing
✅ Result aggregation

Slash Commands:

✅ All 8 slash commands
✅ Argument parsing
✅ Natural language integration
✅ Interactive workflows

Phase 7: Advanced Features (Weeks 13-14)

Additional Capabilities:

✅ Smart alerts & notifications
✅ Merchant intelligence
✅ Document management
✅ Multi-user support
✅ Comparative benchmarking
✅ Audit trail

Phase 8: Health Check & Polish (Weeks 15-16)

Health Check System:

✅ 6 health scores
✅ Recommendation engine
✅ Automated monitoring
✅ Guided setup workflow

Polish & Testing:

✅ End-to-end testing
✅ Documentation completion
✅ Performance optimization
✅ User guides

Success Metrics

Efficiency Gains:

Reduce manual categorization time by 60-80%
Auto-categorization rate: 70%+ (from ~5%)
Financial admin time: 45 min/week → 10 min/week

Quality Improvements:

Health score: 95/100 average
Categorization accuracy: 95%+
Tax compliance score: 90%+

User Satisfaction:

All essential tax documents generated automatically
Proactive optimization suggestions implemented
Financial insights delivered weekly
Zero missed tax deadlines/thresholds

Future Enhancements

v2.0 Potential Features:

Machine learning for transaction categorization
Integration with other financial platforms
Mobile app companion
Real-time alerts via notifications
Advanced visualizations and dashboards
Multi-currency support enhancements
Business expense separation automation
Integration with accounting software (Xero, MYOB)
Predictive budget adjustments
AI financial advisor capabilities

End of Design Document

Status: Ready for implementation Next Steps:

Review and approve design
Set up git worktree for isolated development
Create detailed implementation plan
Begin Phase 1: Foundation

Document Version: 1.0 Last Updated: 2025-11-20 Approved By: [Pending]

36 KiB Raw Permalink Blame History

Agent Smith - Complete Design Specification

Executive Summary

Table of Contents

Core Architecture

Three-Tier System

Philosophy

Directory Structure

Smart Archiving Strategy

Hybrid Rule Engine

Architecture

Rule Schema (Local)

Intelligence Modes

Session Rules

Rule Lifecycle

Platform Sync Strategy

Tax Intelligence Module

Three-Tier System

Level 1: Reference & Reporting

Level 2: Smart Categorization Assistant

Level 3: Full Compliance Suite

ATO Documentation Caching

Scenario Analysis Engine

Four Scenario Types

Subagent Orchestration

Orchestration Decision Tree

Subagent Types

Processing Patterns

Communication Protocol

Slash Commands

Command Structure

Command Definitions

Additional Features

1. Smart Alerts & Notifications

2. Merchant Intelligence

3. Receipt & Document Management

4. Multi-User & Shared Expense Tracking

5. Investment Tracking

6. Cash Flow Forecasting

7. Goal Tracking

8. Comparative Benchmarking

9. Audit Trail

10. Smart Backup & Recovery

Health Check System

Six Health Scores

Health Check Output

Automated Health Monitoring

Configuration

.env.sample

User Preferences (data/config.json)

Implementation Roadmap

Phase 1: Foundation (Weeks 1-2)

Phase 2: Rule Engine (Weeks 3-4)

Phase 3: Analysis & Reporting (Weeks 5-6)

Phase 4: Tax Intelligence (Weeks 7-8)

Phase 5: Scenario Analysis (Weeks 9-10)

Phase 6: Orchestration & UX (Weeks 11-12)

Phase 7: Advanced Features (Weeks 13-14)

Phase 8: Health Check & Polish (Weeks 15-16)

Success Metrics

Future Enhancements

36 KiB

Raw Permalink Blame History