From 253364405b2f0c12181e834d457568c77b5add4f Mon Sep 17 00:00:00 2001 From: bryantgillespie Date: Wed, 18 Feb 2026 13:39:38 -0500 Subject: [PATCH 1/6] first pass --- .docs/claude-code-guide.md | 118 +++++++++++++++++++++++++++ .github/pull_request_template.md | 15 ++++ .github/workflows/build.yaml | 30 +++++++ .github/workflows/claude-review.yaml | 62 ++++++++++++++ AGENTS.md | 106 ++++++++++++++++++++++++ CLAUDE.md | 1 + 6 files changed, 332 insertions(+) create mode 100644 .docs/claude-code-guide.md create mode 100644 .github/pull_request_template.md create mode 100644 .github/workflows/build.yaml create mode 100644 .github/workflows/claude-review.yaml create mode 100644 AGENTS.md create mode 120000 CLAUDE.md diff --git a/.docs/claude-code-guide.md b/.docs/claude-code-guide.md new file mode 100644 index 00000000..5bd5348d --- /dev/null +++ b/.docs/claude-code-guide.md @@ -0,0 +1,118 @@ +# Claude Code Guide for the Website Team + +A guide for using Claude Code to make changes to the Directus marketing website. + +## What is Claude Code? + +Claude Code is an AI-powered coding assistant that runs in your terminal. It can read your codebase, write code, run commands, and help you submit pull requests — all through natural language conversation. + +## Getting Started + +### 1. Install Claude Code + +```bash +npm install -g @anthropic-ai/claude-code +``` + +You'll need to authenticate with your team account. Ask a team lead for access if you don't have it. + +### 2. Clone the repo and open it + +```bash +git clone https://github.com/directus/website.git +cd website +claude +``` + +This drops you into an interactive session where you can ask Claude to make changes. + +### 3. Install dependencies (first time only) + +```bash +pnpm install +``` + +## Submitting Your First PR + +Here's the typical workflow: + +### Step 1: Create a branch + +Tell Claude what you want to do. It'll create a branch and start working: + +``` +> Create a branch and update the CTA block to support a secondary variant +``` + +Or create one yourself first: + +```bash +git checkout -b your-name/description-of-change +``` + +### Step 2: Make your changes + +Describe what you want in plain language: + +``` +> Add a new "compact" size option to the Header block +> Update the testimonial slider to show 3 cards on desktop instead of 2 +> Fix the spacing on the pricing tier cards +``` + +Claude will read the relevant files, make changes, and run lint/typecheck to verify. + +### Step 3: Review what changed + +Ask Claude to show you what it did: + +``` +> What files did you change? Show me a summary. +``` + +Or check git directly: + +```bash +git diff +``` + +### Step 4: Commit and push + +``` +> Commit these changes and push +``` + +Or use `/commit` in Claude Code for an interactive commit flow. + +### Step 5: Open a PR + +``` +> Open a pull request for this change +``` + +Claude will create the PR on GitHub with a description of the changes. + +### Step 6: Get a review + +Add the `claude` label to your PR on GitHub. This triggers an automated code review that will post comments on your PR. A team dev will also review and approve before merge. + +## What Happens After You Push + +1. **CI Checks** run automatically (lint, typecheck, build) — all must pass +2. **Deploy Preview** — Netlify creates a preview URL so you can see your changes live +3. **Claude Review** — add the `claude` label for an automated code review +4. **Human Review** — a dev reviews and merges your PR + +## Tips + +- **Be specific.** "Make the header bigger" is vague. "Increase the header font size on desktop from 3rem to 3.5rem" is better. +- **Ask Claude to explain.** If you don't understand something, ask: "What does this component do?" or "How does the block system work?" +- **Don't worry about breaking things.** CI checks catch most issues, deploy previews let you verify visually, and a dev reviews before merge. +- **Use existing components.** Before asking Claude to build something new, ask: "Is there an existing component for X?" The `Base/` directory has reusable primitives. +- **Run checks locally.** `pnpm lint` and `pnpm typecheck` catch issues before you push. + +## Common Gotchas + +- **Content vs. code changes.** If you're updating text, images, or page content — that's done in the Directus CMS admin, not in this repo. This repo is for layout, styling, and functionality changes. +- **Environment variables.** You'll need a `.env` file for local development. Ask a dev for the values. +- **Node version.** This project uses Node 20. Use `nvm use 20` if you have nvm installed. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 00000000..bcfce194 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,15 @@ +## What Changed + + + +## How to Test + + + +- Deploy preview: + +## Checklist + +- [ ] `pnpm lint` passes +- [ ] `pnpm typecheck` passes +- [ ] Verified changes in deploy preview diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml new file mode 100644 index 00000000..ff4431b5 --- /dev/null +++ b/.github/workflows/build.yaml @@ -0,0 +1,30 @@ +name: Build + +on: + push: + branches: + - main + pull_request: + branches: + - main + +concurrency: + group: build-${{ github.ref }} + cancel-in-progress: true + +env: + NODE_OPTIONS: --max_old_space_size=6144 + +jobs: + build: + name: Build + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Prepare + uses: ./.github/actions/prepare + + - name: Run Build + run: pnpm build diff --git a/.github/workflows/claude-review.yaml b/.github/workflows/claude-review.yaml new file mode 100644 index 00000000..861a326f --- /dev/null +++ b/.github/workflows/claude-review.yaml @@ -0,0 +1,62 @@ +name: Claude Code Review + +on: + pull_request_target: + types: [labeled] + +jobs: + review: + if: github.event.label.name == 'claude' + runs-on: ubuntu-latest + permissions: + contents: read + pull-requests: write + id-token: write + steps: + - name: Checkout repository + uses: actions/checkout@v6 + with: + fetch-depth: 1 + + - name: PR Review + uses: anthropics/claude-code-action@v1 + with: + claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + track_progress: true + prompt: | + REPO: ${{ github.repository }} + PR NUMBER: ${{ github.event.pull_request.number }} + + Be extremely concise. Sacrifice grammar for brevity. + + ## Step 1: Risk Assessment + + Evaluate the PR and apply exactly one label — `low-risk` or `high-risk`. + + **low-risk:** styling, CSS, copy, Base component changes, docs, assets + **high-risk:** server routes, nuxt config, modules, type definitions, CI/CD, package deps, composables used broadly, layouts, middleware, plugins + + Use judgment — a one-line style fix in a composable is still low-risk. Consider blast radius, not just file path. + + Apply the label to the PR using `gh pr edit` with `--add-label`. Remove the other risk label if present. Post a one-line comment with your risk assessment and reasoning. + + ## Step 2: Code Review + + Review with focus on: + + 1. **Code Quality** — Vue/Nuxt best practices, reuse of existing Base/Block components, readability + 2. **Styling** — scoped SCSS, CSS custom properties, responsive breakpoints (50rem/68rem), no hardcoded values + 3. **TypeScript** — proper prop typing, minimal `any` + 4. **Security** — no exposed secrets/internal URLs, safe data handling + 5. **Performance** — no unnecessary re-renders/watchers, efficient data fetching + + Inline comments for specific issues. Top-level comment for general observations. Keep it short. + + claude_args: | + --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr edit:*),Bash(gh issue edit:*)" + + - name: Remove claude label + if: always() + env: + GH_TOKEN: ${{ github.token }} + run: gh pr edit ${{ github.event.pull_request.number }} --remove-label claude --repo ${{ github.repository }} diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..1ebc94c0 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,106 @@ +# Directus Website + +## Overview + +Marketing website for [directus.io](https://directus.io) built with Nuxt 4 and Directus CMS. Pages are composed of reusable block components that render content from the Directus API. + +## Tech Stack + +- **Framework:** Nuxt 4 (app/ directory convention) +- **CMS:** Directus (headless, all content via API) +- **Styling:** Scoped SCSS with CSS custom properties (no Tailwind) +- **Hosting:** Netlify (deploy previews on PRs) +- **CI:** GitHub Actions (lint, typecheck, build) + +## Project Structure + +``` +app/ +├── components/ +│ ├── Base/ # Reusable UI primitives (Button, Card, Container, etc.) +│ ├── Block/ # CMS block components (Header, RichText, CardGroup, etc.) +│ ├── Nav/ # Navigation components +│ └── ... +├── composables/ # Vue composables +├── layouts/ # Page layouts +├── pages/ # File-based routing +├── plugins/ +└── utils/ +server/ # Nitro server routes +types/ # TypeScript type definitions +``` + +## Architecture: Block System + +Pages are built from **sections** containing **blocks**. Content editors compose pages in Directus; the app renders them: + +1. `PageBuilder.vue` receives sections from the CMS +2. Each section renders via `PageSection.vue` (handles background, spacing) +3. Blocks render via `BaseBlock.vue` which maps `block_*` collection types to `Block*.vue` components + +**To add a new block:** +1. Create `app/components/Block/YourBlock.vue` +2. Register it in `app/components/Base/Block.vue` in the `components` map +3. Add the corresponding `block_*` type to `types/schema.ts` `BlockType` +4. The block receives a `uuid` prop and fetches its own data from Directus + +## Conventions + +### Components +- Use ` + + + + +``` + +## Props + +Use `defineProps()` with TypeScript interfaces. Use `withDefaults()` when defaults are needed. + +```vue + +``` + +## Styling + +- Always use `