Day 2: Infrastructure Setup & Plugin System Debug

Posted on Oct 29, 2025

Day 2: October 29, 2025

What We Worked On Today

Morning: Dependency Installation

Goal: Get all Python libraries ready for IAEMS platform

What We Did:

  1. Created comprehensive requirements.txt with 12 core library categories
  2. Built automated installation script
  3. Installed and verified all dependencies

Results:

  • ✅ 12/12 critical packages installed
  • ✅ All imports verified working
  • ✅ Minor version conflict (google-cloud-storage) but functional

Learnings:

  • Need --break-system-packages flag for pip on this system
  • firebase-admin requires newer google-cloud-storage than aiplatform expects
  • All core Google Cloud SDKs work together despite version warning

Mid-Day: API Client Boilerplate

Goal: Prepare integration patterns for third-party APIs

What We Built:

  1. Base Client Class (api-clients/base_client.py)

    • Secret Manager integration
    • Rate limiting decorator
    • Exponential backoff retry
    • Response caching with TTL
    • Consistent error handling

  2. Apollo.io Client (api-clients/apollo_client.py)

    • Complete implementation
    • Search people/companies
    • Contact enrichment
    • Credits tracking

  3. API Reference (api-clients/README.md)

    • 15+ service endpoints documented
    • Rate limits for each service
    • Cost estimates (~$332/month)
    • Authentication patterns

Key Code:

class BaseAPIClient(ABC):
    def __init__(self, project_id, base_url,
                 rate_limit_calls=100, rate_limit_period=60):
        # Secret Manager for API keys
        # Automatic rate limiting
        # Response caching
        # Retry logic

Why This Matters:

  • No hardcoded API keys (Secret Manager)
  • Automatic rate limiting prevents quota issues
  • Caching reduces API costs
  • Consistent pattern for all 15+ APIs

Afternoon: Claude Plugin System Deep Dive

Problem: Plugins not activating as expected

What We Discovered:

  1. Plugins ≠ Slash Commands ≠ Skills

    • Plugins: Containers with multiple components
    • Skills: Model-invoked (Claude decides when to use)
    • Commands: User-invoked (you type /command)

  2. Your Plugin Marketplace:

    • 227 plugins in claude-code-plugins-plus
    • 175 active Skills
    • 263 Skills in backups
    • All properly structured and GitHub-approved

  3. Discovery Issue:

    • Skills were 7 levels deep in directory structure
    • No symlinks to ~/.claude/skills/ directory
    • Plugin config.json was empty

Solution Attempted:

  • Created symlinks to personal skills directory
  • Problem: Too many (175 Skills) - could cause conflicts
  • Decision: Removed symlinks, use plugins as-is

Key Learning:

  • Skills activate based on description matching
  • Claude autonomously decides when to use them
  • Can’t “call” Skills directly - they’re not functions
  • Need clear, specific descriptions for activation

Your Google Cloud Agent SDK Skill:

  • 512 lines of comprehensive ADK mastery
  • Should activate when mentioning: ADK, multi-agent, Cloud Run, etc.
  • Located in your marketplace

Evening: Documentation Site Planning

Goal: Create living documentation on startaitools.com

Blueprint Created:

  • 9-section site structure
  • Daily journal format
  • All 34 docs organized logically
  • Mobile-friendly navigation
  • Search functionality planned

Structure:

/iaems/
├── journal/ (daily work log)
├── foundation/ (15 docs)
├── system/ (13 docs)
├── agents/ (6 docs)
├── progress/ (status)
├── infrastructure/ (setup)
├── reference/ (quick links)
└── challenges/ (debugging)

Challenges Hit Today

1. Plugin System Confusion

Problem: Expected plugins to work like traditional extensions Reality: Skills are model-invoked, not user-invoked Solution: Read official Claude Code documentation Learning: Always check docs first, don’t assume

2. Deep Directory Nesting

Problem: Skills buried in marketplaces/plugins/productivity/004.../skills/ Reality: This is correct structure for plugin marketplace Solution: Leave as-is, use properly Learning: Don’t “fix” what isn’t broken

Problem: Linked 175 Skills to personal directory Reality: Could cause conflicts and slow discovery Solution: Removed all symlinks Learning: More isn’t always better

Code We Wrote

1. Requirements Management

File: requirements.txt

# Core Google Cloud
google-cloud-aiplatform>=1.121.0
google-cloud-firestore>=2.19.0
firebase-admin>=6.7.0

# API Integrations
simple-salesforce>=1.12.6
# ...12 total categories

2. Base API Client

File: api-clients/base_client.py Lines: 300+ Features:

  • Secret Manager integration
  • Rate limiting with decorators
  • Automatic retry with backoff
  • Response caching
  • Error handling

Why: Consistent pattern for all 15+ third-party APIs

3. Installation Automation

File: install-dependencies.sh Purpose: One-command setup

pip install --break-system-packages \
    google-cloud-aiplatform \
    google-cloud-firestore \
    # ...all dependencies

Decisions Made

1. Secret Management Strategy

Decision: Use Google Secret Manager for ALL API keys Rationale:

  • No secrets in code/env files
  • Centralized rotation
  • Audit logging
  • IAM controls Impact: All API clients inherit from BaseAPIClient

2. Plugin Usage Approach

Decision: Use marketplace as-is, don’t force-link Skills Rationale:

  • Plugins are properly structured
  • Skills activate autonomously
  • Too many symlinks create confusion Impact: Cleaner ~/.claude directory

3. Documentation Site Structure

Decision: Organize by strategic grouping + chronology Rationale:

  • Easy to navigate by topic
  • Shows progression of work
  • Both teaching tool and study guide Impact: 9-section hierarchy created

What We Learned

Technical

  1. PEP 668: System Python needs --break-system-packages
  2. Claude Skills: Model-invoked, not user-invoked
  3. Rate Limiting: Decorator pattern works beautifully
  4. Secret Manager: Best practice for all credentials

Process

  1. Read docs first: Saved hours of confusion
  2. Understand before fixing: Don’t break what works
  3. Documentation matters: Blueprint before building
  4. Simple is better: Don’t over-engineer

Collaboration

  1. Transparent debugging: Show mistakes and fixes
  2. Ask clarifying questions: “Is this marketing?” critical question
  3. Iterate quickly: Blueprint → Build → Test → Learn
  4. Trust the process: Good architecture takes time

Tomorrow’s Plan

Phase 1: Build Documentation Site

  1. Create home dashboard
  2. Add first journal entry (this one!)
  3. Convert foundation docs (001-012)
  4. Deploy to startaitools.com
  5. Test navigation and search

Phase 2: First Agent Deployment

  1. Set up Firebase Functions locally
  2. Create Hello World agent
  3. Deploy to Cloud Run
  4. Test end-to-end
  5. Document the process

Phase 3: API Integrations

  1. Test Apollo client with real API
  2. Implement Salesforce integration
  3. Create workflow orchestration
  4. Add error handling
  5. Monitor costs

Files Created Today

Documentation

  • INSTALLATION-SUMMARY.md - Complete setup status
  • DEPENDENCY-STATUS.md - Audit report
  • QUICK-START.md - Fast reference
  • PLUGIN-DEBUG-REPORT.md - Debugging findings
  • CLAUDE-PLUGIN-SYSTEM-DEBUG.md - System analysis
  • IAEMS-LEARNING-JOURNAL.md - Learning notes
  • IAEMS-SITE-MAP-BLUEPRINT.md - Site structure

Infrastructure

  • requirements.txt - All Python dependencies
  • install-dependencies.sh - Automated installer
  • api-clients/base_client.py - Base API class
  • api-clients/apollo_client.py - Apollo integration
  • api-clients/README.md - API reference
  • fix-skills-discovery.sh - Plugin linking script

Hugo Site

  • content/iaems/_index.md - Site home
  • content/iaems/journal/2025-10-29.md - This entry!

Metrics

Time Spent: ~6 hours Documents Created: 13 new files Lines of Code: ~800 lines Dependencies Installed: 12 packages APIs Documented: 15 services Bugs Fixed: 3 major issues

  • [018] Complete Implementation Blueprint
  • [020] Technical Deep Dive
  • [033] SDR + Manager Workflows
  • Tool-Enabled Implementation Guide

Links & Resources

Official Documentation

Our Code

  • IAEMS Repository: /home/jeremy/000-projects/iaems/
  • Documentation: /000-docs/
  • Infrastructure: /000-docs/infrastructure-templates/

External

Reflections

Today was about foundations. We installed dependencies, created boilerplate, debugged the plugin system, and planned our documentation site.

The biggest learning: Skills are not commands. They’re autonomous. Claude decides when to use them based on context. This changes everything about how we think about plugins.

Tomorrow we build the actual site and deploy our first agent.

Progress Status: 🟢 On Track Next Session: Build Phase 1 of documentation site

This is a real journal of real work. No marketing. No fluff. Just Claude Code + Jeremy building Google A2A systems together.