AI Assistant Instructions

This document is the FIRST thing AI assistants (Claude, Kiro, Cursor, etc.) should read before working on any BlueFly.io project.

Quick Context

You are working on the LLM Ecosystem - an enterprise AI agent platform built on: - Drupal 11 (primary CMS) - OSSA (Open Standard for Scalable AI Agents) - BuildKit (agent orchestration CLI) - Kubernetes (production deployment) - GitLab (source control, CI/CD)

🚨 MANDATORY RULES

1. Protected Paths - NEVER EDIT

These directories are Composer-managed. Editing them directly breaks the deployment pipeline.

PROTECTED (READ-ONLY):
/Users/flux423/Sites/LLM/llm-platform/web/modules/
/Users/flux423/Sites/LLM/llm-platform/web/themes/
/Users/flux423/Sites/LLM/llm-platform/web/recipes/
/Users/flux423/Sites/LLM/llm-platform/web/core/
/Users/flux423/Sites/LLM/llm-platform/web/profiles/
/Users/flux423/Sites/LLM/llm-platform/web/libraries/

2. Edit Source Directories Instead

SOURCE (EDIT HERE):
/Users/flux423/Sites/LLM/all_drupal_custom/modules/   → syncs to → web/modules/custom/
/Users/flux423/Sites/LLM/all_drupal_custom/themes/    → syncs to → web/themes/custom/
/Users/flux423/Sites/LLM/all_drupal_custom/recipes/   → syncs to → web/recipes/

After editing, run: buildkit drupal sync

3. Git Workflow - Issue-First, Worktree-Based

NEVER: - Commit directly to main, master, or development - Switch branches in main project directories - Create MRs via CLI

ALWAYS: 1. Create GitLab issue FIRST 2. Click "Create merge request" in GitLab UI 3. Use git worktree for feature work: bash git fetch origin git worktree add ../worktrees/<branch-name> <branch-name> cd ../worktrees/<branch-name> 4. Main directories ALWAYS stay on development branch

4. No Shell Scripts

NEVER create shell scripts (.sh files). Use BuildKit CLI instead:

# ❌ DON'T: Create deploy.sh
# ✅ DO: buildkit golden deploy --env dev

# ❌ DON'T: Create test.sh  
# ✅ DO: buildkit golden test

# ❌ DON'T: Create sync.sh
# ✅ DO: buildkit drupal sync

5. No Local Markdown Files

NEVER create local .md files for documentation. Use GitLab Wiki:

# ❌ DON'T: Create README.md, CHANGELOG.md, TODO.md locally
# ✅ DO: Update GitLab Wiki via git or API

🛠️ Essential Commands

BuildKit Golden Commands

buildkit golden test          # Run full test suite
buildkit golden deploy --env dev    # Deploy to development
buildkit golden audit         # Security + quality audit
buildkit golden sync          # Sync GitLab issues/wiki
buildkit golden optimize      # Check if agents needed

Drupal Commands

buildkit drupal sync          # Sync custom code to llm-platform
buildkit drupal cache:clear   # Clear Drupal cache
buildkit drupal config:export # Export config
buildkit drupal phpcs PATH --fix   # PHPCS with auto-fix

OSSA Commands

ossa validate agent.yml       # Validate OSSA manifest
ossa init <name> --type worker    # Create new agent
ossa migrate old/ --output new/   # Migrate manifest

Git Worktree Commands

# Create worktree for feature branch
git fetch origin
git worktree add ../worktrees/feature-123 feature-123
cd ../worktrees/feature-123

# After MR merges, cleanup
git worktree remove ../worktrees/feature-123
cd /path/to/main/project
git pull origin development

💡 Token Optimization

Before starting ANY task > 500 tokens or affecting 3+ files:

# Check if agent exists for this task
buildkit agents list
buildkit agents search --tag <keyword>

# Spawn agent for repetitive work
buildkit swarm spawn --type worker

Use agents for: - Multi-file refactoring - Test generation across modules - Documentation sync - Repetitive operations

📁 Key Project Locations

Project	Location
Main Platform	`/Users/flux423/Sites/LLM/llm-platform/`
Custom Drupal Code	`/Users/flux423/Sites/LLM/all_drupal_custom/`
NPM Packages	`/Users/flux423/Sites/LLM/common_npm/`
BuildKit CLI	`/Users/flux423/Sites/LLM/agent-buildkit/`
OpenAPI Specs	`/Users/flux423/Sites/LLM/technical-guide/`
Models	`/Users/flux423/Sites/LLM/models/`
This Wiki	`/Users/flux423/Sites/LLM/technical-documentation/`

🔑 Secrets Location

All tokens are in ~/.tokens/:

~/.tokens/gitlab      # GitLab token
~/.tokens/openai      # OpenAI API key
~/.tokens/anthropic   # Anthropic API key

NEVER ask the user for tokens - they're already configured.

📚 Documentation Structure

This wiki is organized:

getting-started/ - Installation and setup
standards/ - OSSA, OpenAPI, code standards
architecture/ - System design and components
developer-guides/ - NPM and Drupal development
api-reference/ - REST, GraphQL, gRPC APIs
deployment-and-operations/ - K8s, CI/CD
observability-and-analytics/ - Tracing, metrics
testing-and-quality/ - TDD, coverage
troubleshooting/ - Common issues

❌ Common Mistakes to Avoid

Editing protected paths - Always use source directories
Creating local .md files - Use GitLab Wiki
Creating shell scripts - Use BuildKit
Switching branches in main dirs - Use worktrees
Committing to development directly - Use MR workflow
Large changes without agents - Check optimization first
Creating GitLab issues without asking - Always ask user first
Mass-creating issues - Max 3 per request

🔗 Key Resources

Full Documentation: Home
OSSA Specification: standards/ossa/specification
BuildKit Architecture: architecture/buildkit
Worktree Workflow: standards/worktree-workflow
TDD Methodology: testing-and-quality/tdd/methodology
GitLab Group: https://gitlab.com/blueflyio/agent-platform

Last Updated: 2025-11-28 Version: 1.0.0