Skip to content

AGENTS.md

Latest commit

 

History

History
186 lines (151 loc) · 13.6 KB

AGENTS.md

File metadata and controls

186 lines (151 loc) · 13.6 KB
Raw

AGENTS.md

This file provides shared context for all Claude Code agents working in this repository. For the full project guide, see CLAUDE.md.

Project State

  • Site: xhverse.co — portfolio, blog, and interactive tools for Rujikorn Ngoensaard (XH / bossruji)
  • Role: Senior Data Engineer | Platform Architecture
  • Version: v3.9.7
  • Stack: Astro 6 (static only), Tailwind CSS v4, Bun, Cloudflare Pages, Supabase, Resend
  • Pages: 29 Astro route files; current release build generates 46 static HTML pages
  • Tests: 585 unit tests at 100% coverage + 84 E2E checks

Commands

bun run dev              # Dev server → localhost:4321
bun run build            # Production build → ./dist/
bun run typecheck        # Type checks
bun run test             # Unit tests (vitest)
bun run coverage         # Unit tests + 100% coverage enforcement
bun run test:e2e         # E2E tests (Playwright)
bun run check            # Full pipeline: typecheck + build + coverage + e2e

Kill dev server: lsof -ti :4321 | xargs kill -9 2>/dev/null

Architecture Overview

src/data/*.ts     → Static typed content (profile, cv, site, services, gallery; blog fallback/seed)
src/lib/          → Business logic + tests (17 domain folders, 100% coverage)
src/pages/*.astro → Routes → generated static HTML (29 route files, 46 current build pages)
src/components/   → Shared Astro components (10)
src/layouts/      → BaseLayout (SEO/CSP) + AdminLayout (admin panel)
dist/             → Deployed to Cloudflare CDN

Interactive Tools (15 live)

All tools are fully client-side. Each follows:

src/lib/<tool-name>/   → Data + logic + tests
src/pages/tools/<slug>.astro → Page with <script> block

The five practitioner assessment tools share src/lib/practitioner-tools/ and are generated through guided decision journeys in src/pages/tools/[slug].astro.

Tool Type
SCD Design Lab Education (dimension modeling practice)
Data Platform Maturity Checker Assessment (form → score + benchmark)
Governance Readiness Scorecard Assessment (form → score + action plan)
Architecture Decision Roulette Game (10 scenarios, agreement tracking)
Data Stack Roast Generator (6 dropdowns → 3-paragraph roast)
SQL Deathmatch Challenge (15 SQL rounds, tier ranking)
Lakehouse Cost Calculator Calculator (cluster config → USD + optimizations)
Cloud Egress Pricing Calculator Calculator (AWS/GCP/Azure Thailand/Singapore egress → USD + source links)
Spark Explained Visualizer (pipeline stages, animated partitions)
Data Product Contract Builder Guided contract journey (clauses → copyable brief)
Access Model Simulator Guided governance journey (policy gates → risk/actions)
Lakehouse Table Layout Advisor Guided architecture journey (layout signals → maintenance plan)
Power BI Semantic Model Doctor Guided semantic journey (metric diagnosis → actions)
Pipeline Recovery Planner Guided recovery journey (drill checkpoints → runbook brief)
Workload Placement Simulator Guided architecture journey (Databricks/Fabric/Power BI placement → review brief)

Key Systems

  • CV Gate: Email capture → admin review → PDF sent via Resend
  • Admin Panel: /admin/* behind Cloudflare Access (Zero Trust)
  • Blog CMS: Supabase posts is the editorial source of truth; Astro publishes static HTML from Supabase at build time
  • CSP: Dual-layer (edge _headers + HTML meta tag) — must stay synced
  • Theme: Dark default, light via html.light. Anti-FOUC inline script.

Agent Knowledge Surfaces

  • AGENTS.md: Compact operating contract for all agents
  • CLAUDE.md: Full repo onboarding and implementation guide
  • .cursor/rules/*.mdc: Cursor rule surfaces for project, git, testing, Cloudflare, code quality, and agent-surface maintenance
  • .agents/skills/*/SKILL.md: Repo skills; frontmatter must be valid YAML
  • .codex/agents/*.toml: Repo-local sub-agent role definitions
  • .codex/config.toml: Codex runtime config only. Do not add [instructions] or developer_instructions tables here; put repo guidance in AGENTS.md, CLAUDE.md, skills, or rules.
  • Memory updates: Only when explicitly requested. Add small notes under /Users/bossruji/.codex/memories/extensions/ad_hoc/notes/; do not edit generated memory files directly.
  • Repo-scoped MCPs/plugins: Declare only project-relevant MCPs/connectors in .codex/config.toml. Store env var names, never token values. Keep unrelated global plugins disabled here so skill-description context budget stays focused. Do not add Notion for this repo.

Codex + Cursor Flow

  • Default split: Codex owns planning, scope control, review, QA, security gate, and release evidence. Cursor owns bounded implementation when explicitly used.
  • Implementation lane: Default code implementation to codex-spark for bounded build/edit work. Codex still owns the plan, review, QA evidence, and final acceptance.
  • Escalation: If codex-spark produces too many bugs, misses repo rules, cannot reach production-grade quality, or the task is high-risk/complex, switch back to the smarter Codex lane for implementation and say why.
  • Handoff surface: Use repo files, usually .tmp/*-handoff.md, as the shared instruction channel. Include allowed files, forbidden files, acceptance criteria, verification commands for Cursor to run, and a .tmp/*-cursor-result.md result note for Cursor to write back.
  • Cursor Agent use: Codex does not operate Cursor through Computer Use for this repo. Codex prepares the handoff; the user runs Cursor Agent locally, preferably with --worktree <task-name> --worktree-base development, then returns the worktree path/branch and Cursor's result note for Codex review.
  • Cursor run request: Only ask the user to run Cursor when it is materially useful. Provide a short reason, the exact terminal command, the handoff path, the expected result note path, and what to send back to Codex.
  • Mode choice: Use Cursor normal agent for one focused implementation. Use Cursor multi-agent/multitask mode only when the work can be split into non-overlapping file ownership.
  • Result handback: Cursor should leave all changes on disk and write .tmp/<task>-cursor-result.md with worktree path, changed files, commands run with exit status, key output lines, deviations from the handoff, and unresolved risks.
  • Review gate: After Cursor edits, Codex must inspect the actual worktree with git status, git diff, changed files, and Cursor's result/test evidence. For Cursor-assisted work, ask Cursor to run the relevant checks, including bun run check when full confidence is needed; Codex reruns tests directly only if Cursor cannot run them, evidence is incomplete, or the user asks.
  • Handoff cleanup: After Cursor-assisted implementation is accepted and any needed evidence has been captured in the final response or durable docs, remove the temporary .tmp/*-handoff.md and .tmp/*-cursor-result.md files before final cleanup.
  • Edit discipline: One tool edits a file at a time. If Cursor is implementing, Codex stays review/QA-only unless explicitly asked to patch findings.
  • Chat hygiene: If the Cursor chat gets long or confused, start a new Cursor conversation and point it at the current handoff file, worktree path, branch state, allowed file list, and latest .tmp/*-cursor-result.md.

Engineering Skill Defaults

  • debug-mantra: Use for bug reports, failing checks, regressions, stack traces, or broken behavior before proposing a fix.
  • scrutinize: Use as the default review lens for plans, PRs, diffs, architecture choices, and code-change sanity checks.
  • post-mortem: Use after a bug fix has a reliable repro, known root cause, implemented fix, and validation evidence, especially when a writeup or RCA is requested.
  • These defaults apply to both Codex and Cursor when the relevant skill is available. Codex-authored Cursor handoffs should name the expected skill lens when debugging, review, or post-fix writeup work is in scope.

Content Writing Defaults

  • technical-writer: Use the repo-local technical_writer sub-agent when starting, outlining, drafting, or reviewing public content: blog posts, technical docs, release notes, page copy, article metadata, references, or related-tool CTAs.
  • Pair technical_writer with blog-content-strategy and document-writer for xhverse blog work. Use it before body drafting and again for pre-publish review.
  • For content strategy, use product-manager first to choose the topic and technical_writer next to sharpen reader goal, thesis, outline, references, SEO metadata, disclosure, and CTA fit.
  • When asked to make a blog post, draft the article package for the Supabase Blog Writer/admin workflow; do not implement a src/data/blog.ts code change unless explicitly requested.
  • After content and cover approval, Codex should publish Supabase-backed posts directly when credentials/MCP access are available: upload or register the cover, insert/update posts, trigger the Cloudflare Pages rebuild, and verify /blog plus /blog/<slug> in production. Keep /admin/blog behavior unchanged as the manual fallback.
  • Generated blog covers should match the existing xhverse cover series: dark isometric data-architecture visuals, glass panels, teal glow, restrained amber accents, abstract platform objects, and no people/logos/screenshots or readable text unless explicitly requested.
  • seo-metadata-check: Use for branded-query SEO work, metadata review, canonical/robots/sitemap checks, structured data, and Search Console follow-up planning. Preserve Rujikorn Ngoensaard, bossruji, XH, and xhverse without keyword stuffing or ranking promises.

Branch & Release Rules

  1. NEVER edit on development or main — create a feature branch first
  2. ALWAYS branch from development — never from main
  3. ALL PRs target development — release PRs are development → main
  4. ALWAYS create an annotated release tag with a useful message after main promotion
  5. ALWAYS show user in browser before push — no exceptions
  6. QA + Security gate every release — both must PASS

Non-Negotiable Constraints

  • 100% test coverage on src/lib/** and src/data/** (statements, branches, functions, lines)
  • No any types
  • No onclick or inline event handlers (Cloudflare Rocket Loader breaks them)
  • data-cfasync="false" on all <script is:inline> tags
  • No external runtime dependencies for tools (all client-side compute)
  • Site must build without Supabase env vars (graceful degradation)
  • When Supabase build credentials are configured, Supabase posts is authoritative; do not merge deleted or stale local fallback posts into public builds
  • Preserve SEO signals: "Rujikorn Ngoensaard", "bossruji", "XH", "xhverse"
  • Branded search improvements must be evidence-backed: inspect current page source or built HTML, keep production canonical URLs on https://xhverse.co, keep preview deployments noindex, and list external Search Console/profile actions separately from repo changes.

Agent Responsibilities

Agent Owns Key Rules
engineering-lead Architecture, coordination, code review, agent-surface governance Plans first, delegates to specialists
site-planner Read-heavy planning, file-level implementation scopes No edits; define owners, risks, and checks
astro-builder Production Astro page/component implementation Follow existing page patterns and visual system
frontend-engineer Pages, components, layouts, styling, a11y addEventListener only, mobile-first, both themes
backend-engineer src/data/, src/lib/, tests, types, Supabase 100% coverage, no any, mock externals
platform-engineer CI, CSP, headers, Cloudflare, build pipeline, repo MCP config Dual-layer CSP sync, generate-headers.ts, no secrets in config
product-manager Feature strategy, roadmap, UX decisions Business case for every recommendation
technical-writer Blog posts, technical docs, article briefs, metadata, references, content QA xhverse voice, primary sources, useful CTAs, no invented claims
qa-reviewer Read-only regression, a11y, security, release readiness Findings first; verify with real commands

Repo-Scoped MCP Policy

  • Cloudflare: Default repo MCP because xhverse runs on Cloudflare Pages and uses Access, Turnstile, security headers, and deployment checks.
  • Supabase: Allowed only for explicit backend/data/RLS/storage/auth/admin work.
  • Notion: Not used by xhverse; keep it out of repo config.
  • Secrets: Never commit bearer tokens, service-role keys, or .env files. Use env var references only.

Content & Identity

  • Title: Senior Data Engineer | Platform Architecture
  • Positioning: Data platform craftsman — practical, production-focused
  • Tech focus: Azure, Databricks, Fabric, Spark, Power BI, lakehouse, governance
  • Industries: Retail, Real Estate, E-Commerce, Manufacturing, Loyalty
  • Current role: Central Pattana (Oct 2024–Present) — enterprise platform delivery
  • Contact: contact@xhverse.co (no phone number on site)
  • Advisory: Available alongside full-time enterprise delivery

Done When

  • Requested change is implemented
  • bun run check passes (typecheck + build + coverage + e2e)
  • User has verified in browser (both themes, mobile viewport)
  • Final summary includes: changed files, risks, verification status

For docs, rule, skill, or Codex-config-only changes, validate the relevant Markdown/YAML/TOML surfaces and state clearly that app runtime tests were not run.