For AI Assistants

This section is specifically designed for AI coding assistants (Claude, Kiro, Cursor, GitHub Copilot, etc.) working on the LLM Platform ecosystem.

🚨 CRITICAL - READ FIRST

Critical Warnings - Documented disasters from AI mistakes. Contains warnings about IRREVERSIBLE ACTIONS that have caused significant damage.

npm versions are PERMANENT - Once published, gone forever.
Issue closing requires verification - Read comments before closing.
Bulk operations need approval - Never assume state.

These warnings exist because of real disasters on 2025-11-30.

🚀 Start Here

If you're an AI assistant just starting to work on this codebase:

Read First: AI Instructions - Critical rules and constraints
Quick Reference: Command Reference - Essential commands at a glance
Workflows: Workflow Rules - Mandatory development workflows
Full Policies: Agent Policies - Complete policy documentation

📋 Quick Context

You're working on the LLM Ecosystem - an enterprise AI agent platform:

Component	Technology
Primary CMS	Drupal 11
Agent Standard	OSSA v0.2.4
CLI Tooling	BuildKit
Deployment	Kubernetes
Source Control	GitLab
CI/CD	GitLab CI with merge trains

🚨 Critical Rules Summary

DO NOT:

❌ Edit Composer-managed paths (llm-platform/web/*)
❌ Switch branches in main project directories
❌ Commit to protected branches (main, development)
❌ Create shell scripts (use BuildKit)
❌ Create local .md files (use GitLab Wiki)
❌ Create GitLab issues without user approval
❌ Release major versions (only patch/minor)

ALWAYS:

✅ Edit source directories (all_drupal_custom/*)
✅ Use git worktrees for feature work
✅ Create MRs from GitLab issues
✅ Write tests first (TDD)
✅ Run buildkit golden optimize before large tasks
✅ Assign MRs to milestones

📁 Key Paths

Purpose	Path
Working Directory (read-only)	`~/Sites/LLM/`
Feature Work (worktrees)	`~/Sites/LLM/worktrees/`
Drupal Custom Code	`~/Sites/LLM/all_drupal_custom/`
NPM Packages	`~/Sites/LLM/common_npm/`
This Documentation	`~/Sites/LLM/technical-documentation/`
API Schemas	`~/Sites/LLM/api-schema-registry/`
Tokens	`~/Sites/LLM/.env.local` or `~/.tokens/`

🔧 Essential Commands

# Before starting work
buildkit golden optimize         # Check if agents needed

# Testing
buildkit golden test             # Full test suite

# Drupal sync
buildkit drupal sync             # Sync custom code

# Quality
buildkit drupal phpcs PATH --fix # Fix PHP code style

# Git worktree
git worktree add ~/Sites/LLM/worktrees/<branch> <branch>

📚 Document Index

Document	Purpose
🚨 Critical Warnings	READ FIRST - Irreversible action safeguards
AI Instructions	Primary onboarding, critical rules
Quick Reference	Command cheatsheet
Workflow Rules	Issue-first, worktree, TDD, npm publishing workflows
Agent Policies	Complete policy documentation

OSSA Specification - Agent standard
BuildKit Architecture - CLI tooling
TDD Methodology - Testing approach
Worktree Workflow - Git workflow

Remember: When in doubt, ask the user. Don't assume, don't guess, don't create issues without approval.