AI Assistant Quick Reference

One-page command reference for AI assistants working on LLM Ecosystem projects.

BuildKit Commands

Golden Workflow (Most Common)

# Testing
buildkit golden test              # Full test suite
buildkit golden test --unit       # Unit tests only
buildkit golden test --coverage   # With coverage report

# Deployment
buildkit golden deploy --env dev        # Deploy to dev
buildkit golden deploy --env staging    # Deploy to staging
buildkit golden deploy --env prod       # Deploy to production

# Quality
buildkit golden audit             # Security + compliance audit
buildkit golden review PATH --fix # Code review with auto-fix
buildkit golden optimize          # Check if agents should be used

# Sync
buildkit golden sync              # Sync GitLab issues + wiki
buildkit golden sync --all        # Full sync

Drupal Operations

# Sync custom code
buildkit drupal sync              # Sync all
buildkit drupal sync --modules    # Sync modules only
buildkit drupal sync --dry-run    # Preview changes

# Drupal commands
buildkit drupal cache:clear       # drush cr
buildkit drupal config:export     # drush cex
buildkit drupal config:import     # drush cim
buildkit drupal database:update   # drush updb

# Code quality
buildkit drupal phpcs PATH        # Check PHP code style
buildkit drupal phpcs PATH --fix  # Auto-fix violations
buildkit drupal taste PATH        # Validate design principles

Agent Management

# List and search
buildkit agents list              # List all agents
buildkit agents search --tag TDD  # Search by tag

# Create and spawn
buildkit agents create --type worker --name my-agent
buildkit swarm spawn --type worker
buildkit swarm spawn --tasks tasks.json --runtime local

# Deploy and monitor
buildkit agents deploy --manifest agent.yml
buildkit agents status agent-id
buildkit agents logs agent-id --follow

OSSA Operations

buildkit ossa validate manifest.json    # Validate OSSA manifest
buildkit ossa generate worker --name x  # Generate agent scaffold
buildkit ossa register --agent-id x     # Register with mesh

Git Worktree Workflow

Create Feature Worktree

# From main project directory
cd /path/to/project
git fetch origin
git worktree add ../worktrees/<branch> <branch>
cd ../worktrees/<branch>

Work and Push

# Make changes
git add .
git commit -m "feat: description"
git push origin <branch>

Cleanup After MR Merges

# Remove worktree
git worktree remove ../worktrees/<branch>

# Update main directory
cd /path/to/project
git pull origin development

Path Mappings

Remember: Edit source, run buildkit drupal sync, test in destination.

Environment Variables

# Check current environment
echo $GITLAB_HOST
echo $DRUPAL_ENV

# Common vars
GITLAB_HOST=gitlab.com
DRUPAL_ENV=development
NODE_ENV=development

Quick Diagnostics

# System status
docker ps                         # Check running containers
ddev status                       # DDEV environment status
kubectl get pods -n llm-platform  # K8s pod status

# Git status
git branch --show-current         # Current branch (should be development)
git status                        # Working tree status
git worktree list                 # List worktrees

# Drupal status
drush status                      # Drupal status
drush pm:list --status=enabled    # Enabled modules

Decision Tree: Agent vs Direct Work

Task involves > 500 tokens?
├── YES → Use agents
│   └── buildkit agents search --description "task"
└── NO → Continue below

Task affects > 3 files?
├── YES → Use agents
│   └── buildkit swarm spawn --type worker
└── NO → Continue below

Task is repetitive?
├── YES → Use agents
│   └── buildkit swarm create-tasks --files "pattern" --output tasks.json
└── NO → Work directly

Error Resolution

PHPCS Violations

# Auto-fix
buildkit drupal phpcs PATH --fix

# If violations remain, fix manually then rerun

Composer Conflicts

# In llm-platform directory
ddev composer update --lock
ddev composer install

Git Worktree Issues

# Force remove stuck worktree
git worktree remove --force ../worktrees/<branch>

# Prune deleted worktrees
git worktree prune

DDEV Issues

ddev restart
ddev composer install
ddev drush cr

Links

• Full AI Instructions
• BuildKit Architecture
• OSSA Specification
• TDD Methodology