Skip to content

CLAUDE.md

Latest commit

 

History

History
96 lines (80 loc) · 4.59 KB

CLAUDE.md

File metadata and controls

96 lines (80 loc) · 4.59 KB
Raw

Project SPEC

Project: vidveil Role: Efficient loader for AI.md

⚠️ THIS FILE IS AUTO-LOADED EVERY CONVERSATION. FOLLOW IT EXACTLY. ⚠️

Purpose:

  • This file is a short loader for the most important rules
  • AI.md is the full source of truth (READ-ONLY), IDEA.md is the project definition
  • For complete details, read the referenced PARTs in AI.md

Asking Questions

  • Default to continuing work - do not stop just to ask whether you should continue
  • Never guess - if the answer cannot be determined from AI.md, IDEA.md, the codebase, or repo state and the missing information materially changes behavior, scope, or safety, ASK the user
  • Do NOT ask for permission to keep going - continue until the task is complete, blocked, or the user asks to pause
  • Question mark = question - when the user ends with ?, answer/clarify, don't execute
  • Use AskUserQuestion wizard - one question at a time, with options plus "Other"

Ask only when at least one of these is true:

  1. A required business/product decision is missing
  2. Two or more reasonable implementations would produce materially different behavior
  3. The action is destructive, irreversible, or impacts production/user data
  4. The spec explicitly says to ask or confirm
  5. The user explicitly requested a plan, pause, or checkpoint before execution

Before ANY Code Change

  1. Have I read the relevant PART in AI.md? (If no → read it)
  2. Does this follow the spec EXACTLY? (If unsure → check spec)
  3. Am I guessing or do I KNOW from the spec? (If guessing → read spec)
  4. Would this pass the compliance checklist? (AI.md FINAL section)

WHEN IN DOUBT: READ THE SPEC. DO NOT GUESS.

Binary Terminology

  • server = vidveil (main binary, runs as service)
  • client = vidveil-cli (REQUIRED companion, CLI/TUI/GUI)

Key Placeholders

  • {project_name} = vidveil · {project_org} = apimgr
  • {internal_name} = vidveil (frozen forever) · {internal_org} = apimgr
  • {official_site} = https://x.scour.li · {api_version} = v1

NEVER Do (Top 19) - VIOLATIONS ARE BUGS

  1. Use bcrypt for config/backup passwords → Use Argon2id
  2. Put Dockerfile in root → docker/Dockerfile
  3. Use CGO → CGO_ENABLED=0 always
  4. Hardcode dev values → Detect at runtime
  5. Use external cron → Internal scheduler (PART 18)
  6. Store config/backup passwords plaintext → Argon2id (API tokens use SHA-256)
  7. Create premium tiers → All features free, no paywalls
  8. Use Makefile in CI/CD → Explicit commands only
  9. Guess values a command can produce → Run the command (date, git rev-parse --short=7 HEAD, uname -m, …); otherwise read spec or ask
  10. Skip platforms → Build all 8 (linux/darwin/windows/freebsd × amd64/arm64)
  11. Client-side rendering (React/Vue) → Server-side Go templates
  12. Add JavaScript for anything HTML5+CSS already does → JS is a LAST RESORT (PART 16)
  13. Let long strings break mobile → Use word-break CSS
  14. Skip validation → Server validates EVERYTHING
  15. Implement without reading spec → Read relevant PART first
  16. Modify AI.md → READ-ONLY SPEC. Project changes go in IDEA.md
  17. Edit ## Project variables in IDEA.md without confirming with the user
  18. Read an image larger than 1000×1000 directly → resize first (magick→convert→gm convert→vipsthumbnail→sips→ffmpeg)
  19. Use a non-conforming IDEA.md without migration → it must have ## Project description, ## Project variables, ## Business logic

ALWAYS Do - NON-NEGOTIABLE

  1. Read AI.md before implementing ANY feature
  2. Server-side processing (server does the work, client displays)
  3. Mobile-first responsive CSS
  4. All features work without JavaScript
  5. Tor hidden service support (auto-enabled if Tor found)
  6. Built-in scheduler, GeoIP, metrics, email, backup, update
  7. All settings configurable via API and config file
  8. Client binary for ALL projects
  9. Commit via gitcommit --dir {project_dir} all with a fresh accurate .git/COMMIT_MESS; subagents never commit

File Locations

  • Config: {config_dir}/server.yml
  • Data: {data_dir}/
  • Logs: {log_dir}/
  • Source: src/
  • Docker: docker/

Where to Find Details

  • AI behavior: .claude/rules/ai-rules.md (PART 0, 1)
  • Project structure: .claude/rules/project-rules.md (PART 2, 3, 4)
  • Frontend/WebUI: .claude/rules/frontend-rules.md (PART 16)
  • All 13 rule files: .claude/rules/
  • Full spec: AI.md (~49k lines) ← SOURCE OF TRUTH

Current Project State

[AI updates this section as work progresses]

  • Last read AI.md: 2026-09-03
  • Current task: compliance audit against AI.md PART 0, PART 1
  • Relevant PARTs: 0, 1