From d75f05fb7751470b128310c3c4aae5d1aa50bd43 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 19 Aug 2026 19:11:33 +0000 Subject: [PATCH 1/3] Replace CONTRIBUTING.md with a pointer index MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The old guide described conventions the repo doesn't follow and a stack it no longer has: - It routed backend reviews to "someone who works with Python/FastAPI". There is no FastAPI here; backend/ is TypeScript/Hono. - It mandated feat//fix//chore/ branches and `type:` commit subjects. Actual branches are claude/*, ux/*, mindmap-main; actual subjects are plain imperative sentences. Nothing linked to the file, so the stale conventions had no counterweight — anyone who did read it got bad information. Replaced with a short index pointing at the docs that are maintained because they sit next to their code (backend/README.md, frontend/CLAUDE.md, frontend/TESTING.md, VISUAL_REGRESSION.md, docs/). Keeps the two genuinely non-obvious gotchas: CI-only Playwright baselines, and the pre-push hook that typechecks experiment/ on main pushes. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01EVaiHqHvxameg9j8JPRWBC --- CONTRIBUTING.md | 275 +++++++----------------------------------------- 1 file changed, 39 insertions(+), 236 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c7d05127..5c0f97db 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,250 +1,53 @@ -# GitHub Conventions Guide +# Contributing ---- +Most of what you need is documented next to the code it describes. This file is the index. -## Typical Workflow +## Which app are you changing? -**Day-to-day process:** +This monorepo holds two independent applications: -1. **Pick a task** - Look at open issues, assign one to yourself -2. **Ensure clean state** - Commit or stash any uncommitted changes -3. **Create branch** - `git checkout -b feature/task-name` (or use VS Code Source Control UI) -4. **Work and commit** - Make changes, commit with proper messages -5. **Push and PR** - Publish branch, open pull request -6. **Review** - Get teammate approval -7. **Merge** - Merge PR, delete branch -8. **Close issue** - Issue closes automatically if you used `Closes #X` +- **Production add-in** — `frontend/` (TypeScript/React Office Add-in) plus `backend/` + (TypeScript [Hono](https://hono.dev) server: OpenAI proxy + JSONL study logging). + They are separate apps in source, but ship as a single container built from the + repo-root `Dockerfile`, with the backend serving the built frontend in production. +- **Experiment app** — `experiment/`, a separate Next.js app for the user study. It does + not use `frontend/` or `backend/`. -**Example:** -```bash -# Start new work -git checkout main -git pull -git checkout -b feat/add-user-dashboard +If it's ambiguous which one a task belongs to, ask rather than guessing. -# Make changes and commit -git add . -git commit -m "feat: add user dashboard layout" +There are also standalone prototypes — `prototype-mindmap/`, `prototype-word-bank/`, +`google-docs-addon/` — each with its own README, plus `sandbox/` for loose +experiments and prompt drafts. -# Push and create PR -git push -u origin feat/add-user-dashboard -# Then open PR on GitHub linking to issue -``` +## Where things are documented ---- +| Topic | See | +| --- | --- | +| Running the backend, its endpoints, env vars, deploy | [backend/README.md](backend/README.md) | +| Frontend build, dev server, entry points | [frontend/CLAUDE.md](frontend/CLAUDE.md) | +| Frontend build-output contract tests | [frontend/TESTING.md](frontend/TESTING.md) | +| Visual regression tests and baselines | [VISUAL_REGRESSION.md](VISUAL_REGRESSION.md) | +| Experiment app | [experiment/README.md](experiment/README.md) | +| Architecture and design notes | [docs/](docs/) | +| CI workflows | [.github/workflows/](.github/workflows/) | -## Branch Naming +## Two things that surprise people -**Format:** `/` +**Playwright baselines are CI-only.** They're pixel-stable only in CI's pinned container, +so don't regenerate them on your machine. Run the **Frontend Tests** workflow with +**Regenerate Playwright visual snapshots** checked and it commits fresh baselines to your +branch. See [VISUAL_REGRESSION.md](VISUAL_REGRESSION.md). -**Types:** -- `feat/` - New features -- `fix/` - Bug fixes -- `test/` - Adding tests to existing code -- `chore/` - Maintenance (includes refactoring, dependency updates, docs, config) - -**Examples:** -``` -feat/add-user-login -fix/correct-password-validation -test/add-authentication-tests -chore/update-readme -chore/upgrade-dependencies -chore/refactor-auth-logic -``` - -**Rules:** -- Use lowercase and hyphens (kebab-case) -- Keep names clear and concise -- Delete branches after merging - -**Note on Testing:** -- Use `test/` branches when adding tests to existing untested code -- For new features, include tests in the same `feat/` branch -- For bug fixes, include tests in the same `fix/` branch - ---- - -## Commit Messages - -**Format:** `type: brief description` - -**Common Types:** -- `feat:` - New feature -- `fix:` - Bug fix -- `refactor:` - Code cleanup -- `test:` - Adding tests -- `chore:` - Maintenance (docs, dependencies, config, etc.) - -**Examples:** -``` -feat: add user registration -fix: correct login validation error -chore: update README installation steps -refactor: simplify database connection logic -chore: upgrade React to v18 -``` - -**Best Practices:** -- Keep first line under 50 characters -- Use imperative mood: "add" not "added" -- Reference issues when relevant: `fix: login error (closes #12)` -- Add detailed explanation in body if needed (optional) - -**Template:** -``` -: - -[Optional body: detailed explanation of what and why] - -[Optional footer: issue references] -``` - -**Full Example:** -``` -feat: add password reset functionality - -Implemented email-based password reset flow. -Users receive a reset link valid for 1 hour. - -Closes #25 -``` - ---- - -## Pull Requests - -**Title Format:** Same as commits: `type: description` -- Example: `feat: add user profile page` - -**Required in Description:** -```markdown -## What This Does -Brief explanation (2-3 sentences) - -## Related Issue -Closes #[number] - -## Testing -- [ ] Tested locally and works -- [ ] All tests pass -``` -*Note: Check boxes by replacing `[ ]` with `[x]`* - -**PR Workflow:** -1. Push your branch to GitHub -2. Open PR with clear title and description -3. Link the related issue using `Closes #123` -4. Request review from at least one teammate -5. Address feedback if any -6. Merge after approval - -**Rules:** -- Get **at least 1 approval** before merging -- Resolve all merge conflicts -- Ensure tests pass -- Keep PRs focused (one feature/fix per PR) - -**Choosing a Reviewer:** -- **Frontend changes** → Request review from someone familiar with React/TypeScript -- **Backend changes** → Request review from someone who works with Python/FastAPI -- **Full-stack changes** → Consider requesting 2 reviewers (one for each side) -- **Documentation/config** → Any active team member can review -- **When unsure** → Ask in team chat or request review from the most active contributor -- **Small teams** → Rotate reviewers to share knowledge across the team - ---- - -## Issues - -**Create Issues For:** -- New features -- Bugs -- Documentation tasks -- Questions or discussions - -**Title Guidelines:** -- ✅ "Add user login form" -- ✅ "Fix password validation error" -- ❌ "Login stuff" -- ❌ "Bug" - -**Simple Template:** - -**For tasks/bugs:** -```markdown -## Description -What needs to be done or what's broken? - -## Details (for bugs) -Steps to reproduce: -1. Do this -2. Then this -3. See error - -Expected: [what should happen] -Actual: [what actually happens] - -## Additional Context -Screenshots, ideas, or relevant info -``` - -**For questions/discussions:** -```markdown -## Question/Discussion -What needs to be discussed or decided? - -## Context -Why is this question coming up? - -## Options (if applicable) -1. Option A - pros and cons -2. Option B - pros and cons - -## Impact -Who/what does this affect? - -## Additional Info -Links, screenshots, or relevant context -``` - -**Best Practices:** -- Assign issues when you start working on them -- Reference issue numbers in commits: `closes #12` -- Close issues when work is merged - ---- - -## Quick Reference - -### Before Committing -- [ ] Code works and is tested -- [ ] Commit message follows format -- [ ] No sensitive data (passwords, API keys) - -### Before Creating PR -- [ ] Branch is up to date with main -- [ ] PR title and description are complete -- [ ] Linked to issue with `Closes #X` - -### Before Merging -- [ ] At least 1 approval -- [ ] Tests passing -- [ ] Feedback addressed -- [ ] No merge conflicts - ---- - -## Further Reading - -This guide covers our team's common patterns. For deeper understanding: - -- **Git workflow fundamentals**: [GitHub Flow](https://docs.github.com/en/get-started/quickstart/github-flow) -- **Branch naming conventions**: [Conventional Branch](https://conventional-branch.github.io/) -- **Commit message best practices**: [Conventional Commits](https://www.conventionalcommits.org/) -- **Pull request reviews**: [How to review code](https://google.github.io/eng-practices/review/reviewer/) - Google's engineering practices - ---- +**Pushing to `main` runs a typecheck.** A Husky `pre-push` hook typechecks `experiment/` +whenever the target ref is `main`, and *rejects the push* if it fails — even when your +change never touched `experiment/`. Fix the errors, or `git push --no-verify` to skip. +## Pull requests +- Keep each PR to one feature or fix, and link its issue (`Closes #123`). +- Get a teammate's review before merging, and let CI go green first. +- No branch-name or commit-message prefix scheme is enforced. Write a clear imperative + subject line and don't worry beyond that. +Task tracking is GitHub Issues. The `backlog/` folder is a legacy system kept for +reference; it's worth a grep for context, but new work goes in Issues. From d3c6197fd87a82edbb5936741c121cd628f82e61 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 19 Aug 2026 19:23:42 +0000 Subject: [PATCH 2/3] Move dev gotchas into the auto-loaded CLAUDE.md files The pointer index still restated root CLAUDE.md: same two-app orientation, same Issues/backlog note. Half of it was duplication, and the half that wasn't sat in a file nothing auto-loads. So put each note where it fires: - frontend/CLAUDE.md said "Run with `npx playwright test`" and nothing about baselines. Added the CI-only regeneration note right there. - The pre-push hook was documented in no CLAUDE.md at all; noted in the root Workflow section. CONTRIBUTING.md drops to a 15-line stub: what the repo is, where conventions actually live, and the PR norms. It exists for GitHub's Contribute UI, so it points rather than repeats. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01EVaiHqHvxameg9j8JPRWBC --- CLAUDE.md | 3 +++ CONTRIBUTING.md | 52 +++++++--------------------------------------- frontend/CLAUDE.md | 5 +++++ 3 files changed, 15 insertions(+), 45 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 78b6b5d7..c5a26331 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -20,4 +20,7 @@ This monorepo has two separate applications. If it's ambiguous which one to use, Use GitHub Issues for task management. Note that this project once used `backlog.md` (the `backlog` folder), so it may be worth a quick grep through `/backlog` to see if there are any relevant tasks. - Check for issues that may be relevant to the current task. +- A Husky `pre-push` hook typechecks `experiment/` when the push target is `main`, + and rejects the push if it fails — even for changes that don't touch `experiment`. + It does not run when pushing a feature branch. - Keep `/docs` up to date. (grep for relevant existing docs; create new docs as needed; don't worry about keeping style consistent across documents though.) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5c0f97db..e424f429 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,53 +1,15 @@ # Contributing -Most of what you need is documented next to the code it describes. This file is the index. +Research code from the [Thoughtful AI Lab](https://thoughtful-ai.com/) at Calvin +University. See [README.md](README.md) for what this repo is and how to run it. -## Which app are you changing? - -This monorepo holds two independent applications: - -- **Production add-in** — `frontend/` (TypeScript/React Office Add-in) plus `backend/` - (TypeScript [Hono](https://hono.dev) server: OpenAI proxy + JSONL study logging). - They are separate apps in source, but ship as a single container built from the - repo-root `Dockerfile`, with the backend serving the built frontend in production. -- **Experiment app** — `experiment/`, a separate Next.js app for the user study. It does - not use `frontend/` or `backend/`. - -If it's ambiguous which one a task belongs to, ask rather than guessing. - -There are also standalone prototypes — `prototype-mindmap/`, `prototype-word-bank/`, -`google-docs-addon/` — each with its own README, plus `sandbox/` for loose -experiments and prompt drafts. - -## Where things are documented - -| Topic | See | -| --- | --- | -| Running the backend, its endpoints, env vars, deploy | [backend/README.md](backend/README.md) | -| Frontend build, dev server, entry points | [frontend/CLAUDE.md](frontend/CLAUDE.md) | -| Frontend build-output contract tests | [frontend/TESTING.md](frontend/TESTING.md) | -| Visual regression tests and baselines | [VISUAL_REGRESSION.md](VISUAL_REGRESSION.md) | -| Experiment app | [experiment/README.md](experiment/README.md) | -| Architecture and design notes | [docs/](docs/) | -| CI workflows | [.github/workflows/](.github/workflows/) | - -## Two things that surprise people - -**Playwright baselines are CI-only.** They're pixel-stable only in CI's pinned container, -so don't regenerate them on your machine. Run the **Frontend Tests** workflow with -**Regenerate Playwright visual snapshots** checked and it commits fresh baselines to your -branch. See [VISUAL_REGRESSION.md](VISUAL_REGRESSION.md). - -**Pushing to `main` runs a typecheck.** A Husky `pre-push` hook typechecks `experiment/` -whenever the target ref is `main`, and *rejects the push* if it fails — even when your -change never touched `experiment/`. Fix the errors, or `git push --no-verify` to skip. +Development conventions live next to the code they describe: [CLAUDE.md](CLAUDE.md) +for repo layout and workflow, then the `CLAUDE.md` / `README.md` in `frontend/`, +`backend/`, and `experiment/`. Architecture and design notes are in [docs/](docs/). ## Pull requests - Keep each PR to one feature or fix, and link its issue (`Closes #123`). - Get a teammate's review before merging, and let CI go green first. -- No branch-name or commit-message prefix scheme is enforced. Write a clear imperative - subject line and don't worry beyond that. - -Task tracking is GitHub Issues. The `backlog/` folder is a legacy system kept for -reference; it's worth a grep for context, but new work goes in Issues. +- No branch-name or commit-message prefix scheme is enforced. Write a clear + imperative subject line and don't worry beyond that. diff --git a/frontend/CLAUDE.md b/frontend/CLAUDE.md index 8cbd40a0..8f6d501b 100644 --- a/frontend/CLAUDE.md +++ b/frontend/CLAUDE.md @@ -118,6 +118,11 @@ Two runners own two disjoint directories — never mix them: `src/api/__tests__/generate.test.ts`, including how to stream an `error` part. - **Playwright** (E2E/visual) — `tests/`, files named `*.spec.ts`. Scoped via `testDir` in `playwright.config.ts`. Run with `npx playwright test`. + - Visual baselines are only pixel-stable in CI's pinned container, so don't + commit ones generated locally (`--update-snapshots`). Regenerate by running + the **Frontend Tests** workflow with `update-snapshots=true`; its + `update-snapshots` job commits fresh baselines to your branch. See + [../VISUAL_REGRESSION.md](../VISUAL_REGRESSION.md). Keep unit tests in `src/` and E2E specs in `tests/`. If a unit runner's globs reach into `tests/`, Playwright specs fail with "test.describe() did not expect to be called From 070eef5058c7c456294fcc0c3a365843b8940475 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 19 Aug 2026 19:35:32 +0000 Subject: [PATCH 3/3] Drop the pre-push hook note The hook is being removed in favor of a CI typecheck for experiment/, so documenting it here would land a note about a hook that no longer exists. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01EVaiHqHvxameg9j8JPRWBC --- CLAUDE.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index c5a26331..78b6b5d7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -20,7 +20,4 @@ This monorepo has two separate applications. If it's ambiguous which one to use, Use GitHub Issues for task management. Note that this project once used `backlog.md` (the `backlog` folder), so it may be worth a quick grep through `/backlog` to see if there are any relevant tasks. - Check for issues that may be relevant to the current task. -- A Husky `pre-push` hook typechecks `experiment/` when the push target is `main`, - and rejects the push if it fails — even for changes that don't touch `experiment`. - It does not run when pushing a feature branch. - Keep `/docs` up to date. (grep for relevant existing docs; create new docs as needed; don't worry about keeping style consistent across documents though.)