Skip to main content

open source first

Prefer Open Source First (MANDATORY)

Moved from CLAUDE.md to reduce context size. Rules are mandatory.

Limit custom code; use open source tools. In Drupal: use api_normalization (OpenAPI import, gateway, Tools), ECA (flows), drupal/tool, key, http_client_manager, migrate_plus, ai/ai_agents. Do not build custom GitLab clients, validators, or ORMs. See AGENTS.md "Limit custom code, use open source tools (mandatory)".

Before building ANY custom solution:

  1. Search for existing solutions - GitHub/GitLab, npm, Packagist, Drupal.org
  2. Use official SDKs - Anthropic SDK, OpenAI SDK, GitLab SDK, Tailscale SDK
  3. Evaluate using scoring system - See wiki: policies/tool-evaluation-checklist.md (80-point system)
  4. NEVER build custom without approval - Lead Architect approval + GitLab issue required

Absolute Prohibitions (Zero Tolerance)

NEVER build custom implementations of:

  • HTTP clients (use axios, got, node-fetch)
  • Validation libraries (use zod, joi, yup)
  • Auth/JWT handlers (use jsonwebtoken, passport, official OAuth SDKs)
  • CLI frameworks (use commander, yargs, oclif)
  • Testing frameworks (use vitest, jest, playwright)
  • Logging libraries (use winston, pino, bunyan)
  • Date/time libraries (use date-fns, luxon, dayjs)
  • UUID generators (use uuid package)
  • Crypto utilities (use Node.js crypto, bcrypt)
  • File upload handlers (use multer, formidable)
  • Email clients (use nodemailer, sendgrid)
  • Database ORMs (use prisma, drizzle, typeorm)
  • Cache clients (use ioredis, node-cache)

Quick Reference: Use These, Don't Build Custom

NeedOfficial Tool/SDKInstall Command
HTTP Clientaxios, gotnpm install axios
ValidationZod (already in use)npm install zod
Auth/JWTjsonwebtokennpm install jsonwebtoken
CLI Frameworkcommandernpm install commander
TestingVitest, Playwrightnpm install vitest
Loggingwinston, pinonpm install winston
LLM - Anthropic@anthropic-ai/sdknpm install @anthropic-ai/sdk
LLM - OpenAIopenainpm install openai
GitLab API@gitbeaker/restnpm install @gitbeaker/rest
Tailscale APItailscale-api (official)npm install tailscale-api
MCP@modelcontextprotocol/sdknpm install @modelcontextprotocol/sdk
Dockerdockerodenpm install dockerode
Kubernetes@kubernetes/client-nodenpm install @kubernetes/client-node

Decision Framework

Ask these questions BEFORE writing custom code:

  1. Search Phase (MANDATORY):

    • Searched npm registry for relevant packages
    • Searched GitHub for existing implementations
    • Checked official SDK availability
    • Reviewed Drupal.org contrib (for Drupal)
    • Checked @bluefly/* packages (for platform services)

  2. Evaluation Phase (MANDATORY):

    • Scored using tool-evaluation-checklist.md (80-point system)
    • Tool scores <60 points? → STOP, do NOT use
    • Tool scores 60-79? → Requires justification
    • Tool scores 80+? → Approved for use

  3. Approval Phase (if custom code needed):

    • Created GitLab issue with justification
    • Documented why existing tools don't work
    • Lead Architect approved custom implementation
    • Added justification docblock to custom code

AI Assistant Enforcement

AI assistants (Claude, Cursor, etc.) MUST:

  1. Suggest open source FIRST - Always search for existing solutions before suggesting custom code
  2. Provide reasoning - Explain why suggested tool is better than custom implementation
  3. Block custom code - Refuse to write custom implementations without GitLab issue + approval
  4. Use scoring system - Evaluate tools using 80-point checklist before suggesting

Drupal-Specific: Configuration > Code

CRITICAL for Drupal development:

  1. Configuration FIRST - Use YAML config files (config/install/*.yml)
  2. Contrib modules SECOND - Search Drupal.org for existing modules
  3. Recipes THIRD - Use Drupal recipes for reusable config patterns
  4. Custom PHP LAST RESORT - Only if above options don't work + approval

Enforcement Mechanisms

  1. Pre-commit Hooks - .lefthook.yml blocks:

    • Custom HTTP clients (detects class.*HttpClient, function.*fetch)
    • Custom validators (detects class.*Validator without Zod import)
    • Custom auth (detects class.*Auth without official SDK)
    • Drupal PHP without justification docblock

  2. CI Pipeline Gate - gitlab_components/templates/compliance-check.yml:

    • Runs @bluefly/compliance-engine check-open-source-policy
    • Fails build if violations found
    • Requires Lead Architect override to merge

  3. Code Review Checklist:

    • No custom HTTP clients (use axios/got)
    • No custom validation (use Zod)
    • No custom auth (use official SDKs)
    • All Drupal code justified (see drupal/README.md)
    • All custom code has GitLab issue + approval

See Wiki:

  • policies/prefer-open-source-first.md - Complete policy
  • policies/build-vs-buy-decision-tree.md - Decision flowchart
  • policies/tool-evaluation-checklist.md - 80-point scoring system
  • policies/drupal-config-first-code-last.md - Drupal-specific rules