gh-slamb2k-agent-smith-agent-smith-plugin/commands/install.md

name, description, argument-hints

name	description	argument-hints
smith:install	Interactive Agent Smith setup wizard with intelligent suggestions based on your financial setup	[--reset]

Agent Smith - Intelligent Financial Assistant

You are guiding a user through Agent Smith. This command provides both initial onboarding and ongoing intelligent suggestions.

Your Role

• Be encouraging and supportive
• Explain each step clearly
• Show progress throughout the journey
• Celebrate wins (data discovered, rules created, transactions categorized)
• Provide concrete, actionable next steps

Execution Logic

FIRST: Immediately notify the user that the workflow is loading:

Display this message before doing anything else:

Loading Agent Smith installation workflow...
This may take a moment as I analyze your setup. Please wait...

Check for --reset argument:

If the user provides --reset argument:

1. Confirm with the user before proceeding (this will delete all data!)
2. Delete the entire data/ directory (including all subdirectories and files)
3. Display message: "Reset complete. All onboarding state and data cleared. Running fresh installation..."
4. Proceed to Stages 1-8 (Onboarding) then Stage 9 (Suggestions)

Check for onboarding completion:

1. Check if data/onboarding_state.json exists and has "onboarding_completed": true
2. If YES → Skip to Stage 9: Intelligent Suggestions only
3. If NO → Run Stages 1-8 (Onboarding) then Stage 9 (Suggestions)

When onboarding is complete:

• Set "onboarding_completed": true in data/onboarding_state.json
• Always run Stage 9 (Suggestions) every time this command is invoked

---

Onboarding Workflow (Stages 1-8)

Stage 1: Welcome & Prerequisites Check

Greet the user and verify they have:

1. Agent Smith plugin installed (verify via plugin system)
2. API key configured in .env (in current directory)
3. PocketSmith account accessible

IMPORTANT: When Agent Smith is installed as a plugin, the codebase is in the plugin directory, NOT the user's working directory. The user only needs:

• A .env file with POCKETSMITH_API_KEY in their working directory
• Agent Smith plugin installed

Plugin Detection: Check if this command is running from the plugin by looking for the plugin installation path. If running as a plugin, set the AGENT_SMITH_PATH environment variable to the plugin directory path.

If the user doesn't have a .env file, guide them to create one:

echo "POCKETSMITH_API_KEY=your_key_here" > .env

Get API key from: https://app.pocketsmith.com/keys/new

Stage 2: Discovery

Run the discovery script to analyze their PocketSmith account.

Before first script execution, define the run_agent_smith helper function (see "Plugin-Aware Script Execution" section below).

Run discovery:

run_agent_smith "onboarding/discovery.py"

Note: The .env file should be in the user's current working directory. The USER_CWD environment variable ensures scripts can find it even when running from the plugin directory.

What to look for:

• Account count and types
• Category structure
• Transaction volume and date range
• Uncategorized transaction count
• Baseline health score (if available)

Present findings:

• Summarize their PocketSmith setup
• Highlight the uncategorized transaction count
• Show the recommended template
• Display account classifications (household_shared, parenting_shared, individual)
• Show any name suggestions detected

Stage 2a: Category Structure Assessment

IMPORTANT: This stage determines whether to apply the Foundation template based on the user's existing category count.

Check existing category count from discovery report:

existing_category_count = len(discovery_report.categories)

Decision logic:

• 0-5 categories: Auto-apply Foundation (user has minimal setup)
• 6-19 categories: Offer Foundation with recommendation to apply (partial setup)
• 20+ categories: Offer Foundation with recommendation to skip (established setup)

For users with 20+ categories, present this choice:

I detected {existing_category_count} existing categories in your PocketSmith account.

Agent Smith's Foundation template provides 45 ATO-aligned categories for
everyday expenses (Food, Housing, Transport, Healthcare, Personal, etc.).

The Foundation will be applied automatically to provide structure and
tax compliance. This adds approximately {estimated_new_categories} categories:
  • {breakdown of what would be added}

Since you already have {existing_category_count} categories, you can choose
to skip the Foundation if you prefer to keep only your existing structure.

Apply Agent Smith Foundation? (Y/n):

If user selects "Y" or just presses Enter (default):

Save this decision to data/template_config.json:

{
  "apply_foundation": true
}

The Foundation template will be merged in Stage 4 with priority 0 (applied first).

If user selects "n":

Save this decision:

{
  "apply_foundation": false
}

Foundation will be skipped (--foundation=none in Stage 4).

For users with 6-19 categories:

Present similar choice with recommendation to apply:

I detected {existing_category_count} categories in your PocketSmith account.

Agent Smith's Foundation template adds ATO-aligned structure and better
tax tracking with 45 categories for everyday expenses.

This would add approximately {estimated_new_categories} categories.

Apply Agent Smith Foundation? (Y/n): [default: Y]

For users with 0-5 categories:

Auto-apply Foundation without asking (they need the structure):

I detected only {existing_category_count} categories in your PocketSmith account.

Applying Agent Smith's Foundation template (45 ATO-aligned categories)...

Save to config:

{
  "apply_foundation": true
}

Stage 2b: Account Selection (Interactive)

IMPORTANT: This stage enables context-aware name detection by identifying which accounts are used for household vs parenting expenses.

Check if shared accounts were detected:

Look at the discovery report's account_classifications field. If there are accounts classified as household_shared or parenting_shared, proceed with interactive selection.

For Household Shared Accounts:

If household_shared accounts were detected:

1. Show detected accounts with confidence scores:

I detected these potential household shared accounts:

  1. Shared Bills - Simon & Caitlin (Macquarie Bank)
      Confidence: 90%
      Indicators: "shared" in account name

  2. Joint Savings (CBA)
      Confidence: 60%
      Indicators: "joint" in account name

Which account do you use for household shared expenses?

2. Use AskUserQuestion to let the user select:

# Build options from household_shared accounts
household_accounts = [acc for acc in report.account_classifications
                      if acc.account_type == "household_shared"]

if household_accounts:
    # Sort by confidence
    household_accounts.sort(key=lambda x: x.confidence, reverse=True)

    options = []
    for acc in household_accounts:
        options.append({
            "label": f"{acc.account_name} ({acc.institution})",
            "description": f"Confidence: {acc.confidence*100:.0f}% - Indicators: {', '.join(acc.indicators)}"
        })

    # Ask user to select
    response = AskUserQuestion(
        questions=[{
            "question": "Which account do you use for household shared expenses?",
            "header": "Household Acct",
            "options": options,
            "multiSelect": false
        }]
    )

    # User selected index or "Other"
    # If "Other", show full account list and let them choose

3. Extract names from selected account:

# Get the selected account
selected_account = household_accounts[selected_index]

# Extract names using the account-specific data
suggestion = _extract_names_from_account(
    selected_account,
    transactions,
    categories
)

# Show detected names
if suggestion and suggestion.person_1:
    if suggestion.person_2:
        print(f"✓ Detected contributors: {suggestion.person_1} and {suggestion.person_2}")
    else:
        print(f"✓ Detected contributor: {suggestion.person_1}")

    print(f"  Source: {suggestion.source} (confidence: {suggestion.confidence*100:.0f}%)")

    # Ask for confirmation
    response = AskUserQuestion(
        questions=[{
            "question": f"Use '{suggestion.person_1} and {suggestion.person_2}' for household shared expenses?",
            "header": "Confirm Names",
            "options": [
                {"label": "Yes", "description": "Use these names"},
                {"label": "No", "description": "I'll enter different names"}
            ],
            "multiSelect": false
        }]
    )

    # If "No", ask for manual entry using AskUserQuestion with text input

4. Save to template_config.json:

config = {
    "household_shared_account": {
        "account_id": selected_account.account_id,
        "account_name": selected_account.account_name,
        "person_1": confirmed_person_1,
        "person_2": confirmed_person_2
    }
}

For Parenting Shared Accounts:

If parenting_shared accounts were detected, repeat the same flow:

1. Show detected parenting accounts with confidence scores
2. Use AskUserQuestion to let user select
3. Extract names from selected account
4. Ask for confirmation
5. Save to template_config.json under parenting_shared_account

Example output:

=== Household Shared Account Selection ===

I detected these potential household shared accounts:

  1. Shared Bills - Simon & Caitlin (Macquarie Bank)
      Confidence: 90%
      Why: "shared" in account name

Which account do you use for household shared expenses? (1): 1

Analyzing 'Shared Bills - Simon & Caitlin' for contributor names...

✓ Detected contributors: Simon and Caitlin
  Source: account_name (confidence: 90%)

Use 'Simon and Caitlin' for household shared expenses? (y/n): y

=== Parenting Shared Account Selection ===

I detected these potential parenting shared accounts:

  1. Kids Account - Simon & Tori (CBA)
      Confidence: 90%
      Why: "kids" in account name

Which account do you use for parenting/child expenses? (1): 1

Analyzing 'Kids Account - Simon & Tori' for contributor names...

✓ Detected contributors: Simon and Tori
  Source: account_name (confidence: 90%)

Use 'Simon and Tori' for parenting shared expenses? (y/n): y

✓ Account selections saved to template_config.json

If no shared accounts detected:

Skip this stage and continue to template selection.

Stage 3: Template Selection

Agent Smith uses a composable template system with up to three layers. Users select:

1. Primary Income (ONE choice, REQUIRED) - How you earn most of your income
2. Living Arrangement (ONE OR MORE choices, OPTIONAL) - Special tracking for shared finances or child support
3. Additional Income (MULTIPLE choices, OPTIONAL) - Extra income sources beyond your primary

Step 3a: Select Primary Income Template

Present discovery recommendation, then let user select ONE:

echo "Select your PRIMARY income structure (choose ONE):"
run_agent_smith "setup/template_selector.py" --layer=primary --interactive

Available primary templates:

• payg-employee - Salary/wage earner, PAYG tax withheld
• sole-trader - ABN holder, contractor, quarterly BAS

Step 3b: Select Living Arrangement Template(s) (OPTIONAL)

IMPORTANT: Living templates are for special tracking needs only:

• Shared household finances with expense splitting
• Child support and custody expense tracking

If none of these apply, SKIP this step.

Present discovery recommendation, then let user select ONE OR MORE (or skip):

echo "Select your LIVING arrangement (select all that apply, or skip if none apply):"
run_agent_smith "setup/template_selector.py" --layer=living --multiple --interactive --optional

Available living templates:

• shared-hybrid - Shared household with mixed accounts (partners/couples)

  • Adds labels: "Shared Expense", "Contributor: {name}", "Personal: {name}"
  • Enables expense splitting and contribution tracking

• separated-parents - Child support and custody expense tracking

  • Adds labels: "Child Support", "Kids Expense", "Custody Period"
  • Tracks child-related spending for tax and legal documentation

Note:

• You can select MULTIPLE living arrangements if needed (e.g., separated-parents + shared-hybrid if you're divorced with kids AND now living with a new partner)
• If you're managing finances independently without shared expenses or child support, skip this step entirely

Step 3c: Select Additional Income Templates

Present discovery recommendations, then let user select MULTIPLE:

echo "Select ADDITIONAL income sources (select all that apply):"
run_agent_smith "setup/template_selector.py" --layer=additional --multiple --interactive

Available additional templates:

• property-investor - Rental income, negative gearing, CGT tracking
• share-investor - Dividends, franking credits, share CGT

Step 3d: Configure Template Labels (if applicable)

For templates with configurable labels, prompt for customization:

If Shared Hybrid selected:

echo "Who are the two contributors in your household?"
read -p "Contributor 1 name (e.g., Alex): " CONTRIBUTOR_1
read -p "Contributor 2 name (e.g., Jordan): " CONTRIBUTOR_2

If Separated Parents selected:

echo "Who are the two parents for custody tracking?"
read -p "Parent 1 name (e.g., Sarah): " PARENT_1
read -p "Parent 2 name (e.g., David): " PARENT_2

If Property Investor selected:

read -p "Property address (optional, for multi-property tracking): " PROPERTY_ADDRESS

Save configurations to data/template_config.json for use during merge.

Stage 4: Template Merging & Application Strategy

Step 4a: Merge Selected Templates

Combine the selected templates using priority-based merging.

Check if Foundation should be applied:

Read data/template_config.json and check for "apply_foundation": true|false.

If Foundation is enabled (default):

Foundation (personal-living) is automatically applied. Simply merge with primary and optional layers:

echo "Merging templates (Foundation + Primary + optional layers)..."
run_agent_smith "setup/template_merger.py" \
    --primary="$PRIMARY_TEMPLATE" \
    --living="$LIVING_TEMPLATE" \
    --additional="$ADDITIONAL_TEMPLATES" \
    --config=data/template_config.json \
    --output=data/merged_template.json

If Foundation is disabled:

Use --foundation=none to skip the Foundation layer:

echo "Merging templates (Primary only, skipping Foundation)..."
run_agent_smith "setup/template_merger.py" \
    --foundation=none \
    --primary="$PRIMARY_TEMPLATE" \
    --living="$LIVING_TEMPLATE" \
    --additional="$ADDITIONAL_TEMPLATES" \
    --config=data/template_config.json \
    --output=data/merged_template.json

Note: The --living and --additional parameters are optional. Omit them if no templates were selected for those layers.

Example - Most common case (Foundation + Primary only):

run_agent_smith "setup/template_merger.py" \
    --primary=payg-employee \
    --output=data/merged_template.json

Foundation (personal-living) is automatically included.

Template merge order:

1. Foundation (priority 0) - 45 ATO-aligned base categories (automatic unless --foundation=none)
2. Primary Income (priority 1) - Income-specific categories (REQUIRED)
3. Living Arrangement (priority 2) - Tracking labels for shared finances/child support (OPTIONAL)
4. Additional Income (priority 3) - Investment categories (OPTIONAL)

Later priorities can override/extend earlier ones.

Step 4b: Select Application Strategy

Ask user how to handle existing PocketSmith data:

How should we apply the templates to your PocketSmith account?

1. Add New Only (RECOMMENDED)
   - Keep all your existing categories and rules
   - Add only NEW categories and rules from templates
   - Safest option, nothing gets overwritten

2. Smart Merge
   - Intelligently match template categories to existing ones
   - Add new categories where no match found
   - Deduplicate rules based on payee patterns
   - Good for accounts with some setup already

3. Archive & Replace
   - Create backup of existing setup
   - Apply templates fresh (existing categories remain but unused)
   - Use this if starting over completely
   - Note: PocketSmith API doesn't delete categories, so old ones remain

Choose strategy (1/2/3):

Map user choice to strategy argument:

• Choice 1 → add_new
• Choice 2 → smart_merge (note: underscore, not hyphen)
• Choice 3 → replace

Save user choice to data/onboarding_state.json.

Step 4c: Preview Before Apply

Show what will be created/changed:

echo "Previewing changes (dry run)..."
run_agent_smith "setup/template_applier.py" \
    --template=data/merged_template.json \
    --strategy="$STRATEGY" \
    --dry-run

Expected output (without Foundation):

Template Application Preview
=============================
Strategy: Add New Only

Summary:
  • 7 categories will be created
  • 38 categories already exist (will reuse)
  • 11 rules will be added
  • 0 rules will be skipped (duplicates)
  • Backup will be created at: data/backups/2025-11-25_143022_template_application

Templates Applied:
  ✓ PAYG Employee (primary, priority 1)
  ✓ Shared Household - Hybrid (living, priority 2)
  ✓ Separated Parents (living, priority 2)

Proceed with application? (y/n):

Expected output (with Foundation enabled):

Template Application Preview
=============================
Strategy: Smart Merge

Summary:
  • 12 categories will be created
  • 33 categories matched/reused (fuzzy matching)
  • 11 rules will be added
  • 0 rules will be skipped (duplicates)
  • Backup will be created at: data/backups/2025-11-25_143022_template_application

Templates Applied:
  ✓ Foundation: Personal Living (foundation, priority 0)
  ✓ PAYG Employee (primary, priority 1)
  ✓ Shared Household - Hybrid (living, priority 2)
  ✓ Separated Parents (living, priority 2)

Proceed with application? (y/n):

Step 4d: Apply Templates

If user confirms, apply the merged template:

echo "Applying templates to PocketSmith..."
run_agent_smith "setup/template_applier.py" \
    --template=data/merged_template.json \
    --strategy="$STRATEGY" \
    --apply

Show results:

Template Application Complete!
==============================

✓ Created 23 new categories
✓ Reused 12 existing categories
✓ Created 47 new rules
✓ Backup saved: data/backups/2025-11-22_143022_template_application

Your PocketSmith account is now configured with:
  • PAYG Employee income tracking
  • Shared household expense splitting
  • Property investment tracking

Next: Run categorization to apply these rules to your transactions.

Stage 5: Intelligence Mode Selection

Ask user to choose their preferred intelligence mode:

Categorization mode:

• Conservative: Approve every AI suggestion
• Smart (recommended): Auto-apply high confidence (≥90%)
• Aggressive: Auto-apply medium+ confidence (≥80%)

Tax intelligence level:

• Reference: Basic ATO category mapping
• Smart: Deduction detection, thresholds
• Full: BAS prep, compliance checks

Save to data/config.json.

Stage 6: Incremental Categorization

Recommend starting with recent transactions:

Suggested batch strategy:

1. Start with current month (test rules on small dataset)
2. Expand to last 3 months (validate at scale)
3. Backfill historical data (complete the archive)

Run categorization:

# Dry run first
run_agent_smith "operations/categorize_batch.py" --mode=dry_run --period=2025-11

# Apply if satisfied
run_agent_smith "operations/categorize_batch.py" --mode=apply --period=2025-11

After each batch:

• Show results (matched, auto-applied, needs review, failed)
• Review medium-confidence suggestions
• Learn new rules from user corrections
• Track progress

Stage 7: Post-Onboarding Health Check

After categorization, run health check to show improvement:

/smith:health --full

Show before/after:

• Baseline health score (from Stage 2)
• Current health score (after categorization)
• Improvement in each dimension
• Remaining priorities

Stage 8: Next Steps & Usage Guide

Provide the user with ongoing usage patterns:

Daily/Weekly:

• Categorize new transactions: /smith:categorize --mode=smart

Monthly:

• Spending analysis: /smith:analyze spending --period=YYYY-MM
• Quick health check: /smith:health --quick

Quarterly:

• Tax deduction review: /smith:tax deductions --period=YYYY-YY

Annual (EOFY):

• Tax preparation: /smith:tax eofy

Mark onboarding as complete: Update data/onboarding_state.json with "onboarding_completed": true

---

Stage 9: Intelligent Suggestions

This stage ALWAYS runs - whether onboarding just completed or user is returning.

Analyze the user's financial setup and provide intelligent, actionable suggestions based on:

Analysis Areas

1. Configuration Analysis

   • Read data/onboarding_state.json - What templates are active?
   • Read data/config.json - What intelligence modes are configured?
   • Read data/template_config.json - What labels/customizations exist?

2. Transaction Analysis (via API)

   • How many uncategorized transactions remain?
   • What's the date range of uncategorized transactions?
   • Are there patterns in recent transactions that suggest new rules needed?
   • Transaction volume trends (increasing/decreasing/seasonal)?

3. Category & Rule Health

   • How many categories are defined vs. actually used?
   • How many rules exist? Are they effective (categorizing transactions)?
   • Are there dormant categories (no transactions in 6+ months)?
   • Are there heavily-used categories that might benefit from subcategories?

4. Tax Compliance Opportunities

   • Based on selected templates, what tax deductions might be missing?
   • Are there categories that should be flagged for tax deductions but aren't?
   • For EOFY proximity (May-June), suggest tax prep tasks
   • For BAS proximity (quarterly), suggest BAS prep tasks

5. Spending Insights

   • Identify top 3 spending categories this month
   • Compare to previous month - any unusual increases?
   • Identify opportunities for budget alerts or scenario planning

6. Optimization Opportunities

   • Suggest merchant name normalization for frequently-used payees
   • Recommend rule refinements based on manual categorizations
   • Identify categories that could be consolidated

Suggestion Output Format

Present suggestions in this structure:

═══════════════════════════════════════════════════════════
                 AGENT SMITH SUGGESTIONS
                   [Current Date]
═══════════════════════════════════════════════════════════

Your Setup:
  • Templates: [list active templates]
  • Intelligence Mode: [Conservative/Smart/Aggressive]
  • Tax Level: [Reference/Smart/Full]

Current Status:
  • [X] uncategorized transactions ([date range])
  • [Y] categories defined ([Z] actively used)
  • [N] categorization rules
  • Last analysis: [date or "Never"]

───────────────────────────────────────────────────────────
🎯 PRIORITY ACTIONS
───────────────────────────────────────────────────────────

[1-3 highest-priority suggestions based on analysis]

Example:
1. Categorize 47 Recent Transactions (2025-11-01 to 2025-11-23)
   → Run: /smith:categorize --mode=smart --period=2025-11
   Impact: Bring account up to date, generate new rule suggestions

2. Review Tax Deductions for Q2 (October-December 2025)
   → Run: /smith:tax deductions --period=2025-Q2
   Impact: Identify $X in potential deductions before EOFY

3. Optimize 12 Dormant Categories
   → Run: /smith:optimize categories --prune
   Impact: Simplify category structure, improve categorization accuracy

───────────────────────────────────────────────────────────
💡 OPPORTUNITIES
───────────────────────────────────────────────────────────

[3-5 additional opportunities based on context]

Example:
• Your "Groceries" spending increased 34% this month ($487 → $653)
  → Analyze: /smith:analyze spending --category="Groceries" --trend

• 23 transactions manually categorized last week
  → Generate rules: /smith:optimize rules --learn

• EOFY in 6 months - Start tax planning now
  → Plan: /smith:scenario eofy-planning

───────────────────────────────────────────────────────────
📊 INSIGHTS
───────────────────────────────────────────────────────────

[3-5 interesting insights from their data]

Example:
• Top spending categories this month:
  1. Groceries: $653 (22% of total)
  2. Transport: $412 (14% of total)
  3. Utilities: $387 (13% of total)

• Most active categorization rule: "Woolworths → Groceries" (47 matches)

• Longest uncategorized streak: 12 days (Nov 10-22)
  → Suggest: Enable weekly categorization reminders

───────────────────────────────────────────────────────────
🔧 MAINTENANCE
───────────────────────────────────────────────────────────

[Recommended maintenance tasks based on setup age]

Example:
• Run health check (last run: 3 weeks ago)
  → /smith:health --full

• Backup local rules (23 rules defined)
  → Agent Smith auto-backups on mutation, but manual backup available

• Update ATO tax guidelines (last update: 45 days ago)
  → Agent Smith will auto-refresh in May before EOFY

═══════════════════════════════════════════════════════════

Intelligence Rules for Suggestions

Priority ranking:

1. Uncategorized transactions > 100 → Highest priority, categorization severely behind
2. Upcoming tax deadlines (30 days) → Time-sensitive compliance
3. Manual categorizations > 20 in last week → Rule learning opportunity
4. Health score < 60% → Fundamental setup issues
5. Unusual spending changes > 30% → Budget alert opportunity
6. Dormant categories > 10 → Optimization needed

Contextual suggestions based on templates:

• PAYG Employee: Focus on expense claims, work-from-home deductions
• Sole Trader: Focus on BAS prep, quarterly tax estimates, deduction maximization
• Property Investor: Focus on rental income/expenses, depreciation, CGT events
• Share Investor: Focus on dividend tracking, franking credits, CGT events
• Separated Parents: Focus on child support tracking, custody expense splits
• Shared Hybrid: Focus on contribution balancing, shared expense analysis

Seasonal suggestions:

• Jan-Mar: Review EOFY preparation, plan deductions
• Apr-Jun: EOFY tasks, tax return prep, compliance checks
• Jul-Sep: New FY setup, Q1 BAS (sole traders), budget planning
• Oct-Dec: Q2 BAS (sole traders), holiday spending analysis

---

Important Notes

• Use uv run python -u for all Python scripts (ensures unbuffered output)
• Save onboarding state in data/onboarding_state.json to resume if interrupted
• Celebrate progress - Show metrics like "1,245 → 87 uncategorized transactions"
• Be patient - First categorization can take time for large datasets

Plugin-Aware Script Execution

All Python scripts must be run using this pattern to work in both repository and plugin modes:

# Helper function to run Agent Smith scripts (define once at start)
run_agent_smith() {
    local script_path="$1"
    shift  # Remove first argument, leaving remaining args

    if [ -n "${CLAUDE_PLUGIN_ROOT}" ]; then
        # Plugin mode - run from skill directory with USER_CWD set and venv isolation
        local skill_dir="${CLAUDE_PLUGIN_ROOT}/skills/agent-smith"
        local user_cwd="$(pwd)"

        if [ ! -d "$skill_dir" ]; then
            echo "Error: Agent Smith skill directory not found: $skill_dir"
            return 1
        fi

        # Run from skill directory with:
        # - USER_CWD: preserve user's working directory for .env access
        # - env -u VIRTUAL_ENV: ignore conflicting virtual environments
        # uv will automatically use the plugin's .venv
        (cd "$skill_dir" && \
         USER_CWD="$user_cwd" \
         env -u VIRTUAL_ENV -u VIRTUAL_ENV_PROMPT \
         uv run python -u "scripts/$script_path" "$@")
    elif [ -f "./scripts/$script_path" ]; then
        # Development/repository mode - run from current directory
        uv run python -u "./scripts/$script_path" "$@"
    else
        echo "Error: Agent Smith script not found: $script_path"
        echo "CLAUDE_PLUGIN_ROOT: ${CLAUDE_PLUGIN_ROOT:-not set}"
        echo "Current directory: $(pwd)"
        return 1
    fi
}

Then call scripts like:

run_agent_smith "onboarding/discovery.py"
run_agent_smith "operations/categorize_batch.py" --mode=dry_run --period=2025-11

Execution

Start here:

1. Check if data/onboarding_state.json exists with "onboarding_completed": true
2. If NO → Run Stages 1-8 (Onboarding) then Stage 9 (Suggestions)
3. If YES → Skip to Stage 9 (Suggestions) only

After each onboarding stage, confirm user is ready to continue before proceeding.