The skill now leads with a programmatic overlap-and-overflow check
that runs in under a second and catches the failures that the
eyeball pass kept missing: text bleeding past a card, two cards
intersecting, an arrow label sitting on top of a card title or zone
subtitle, two texts colliding.
The checker loads the SVG in headless Chrome and uses real getBBox()
measurements via puppeteer-core, so the verdict matches what readers
see at render time. Exit code 0 means clean; non-zero lists each
finding with element coordinates and the rule it violated, which is
what you need to fix it without screenshotting.
Updated SKILL.md to put the programmatic check first in the test
loop, with the eyeball pass as the backup. Added the checker to the
pre-commit checklist and the Related files section.
Captures the conventions learned while iterating on the Claude Code
self-hosted runners diagrams:
* viewBox sizing for the ~657 CSS-pixel docs prose column, with a
table mapping viewBox font sizes to on-page font sizes.
* The 'paint-order: stroke' white halo pattern for arrow labels so
they stay readable over zone-tinted backgrounds.
* Card title wrapping rules so titles don't overflow a 144 px card.
* Locked-to-one-user badge and per-instance suffix conventions for
surfacing the things readers most need to see.
* A reproducible test loop: render the docs page (not the raw SVG)
with a copy-pastable headless Chrome script, then verify the
click-through full-size view with a computer_use subagent.
* Pitfalls: subagents reusing stale screenshots, Next.js asset
caching, and headless Chrome rendering SVGs at sub-natural width
when the file is opened directly.
Ships with two reference files: 'render-diagram.sh' (a cache-busting
docs-page screenshot script) and 'template.svg' (a starter SVG with
all conventions baked in).
This follows up on
https://github.com/coder/coder/actions/runs/25684936801/job/75406131184?pr=25139
by replacing the large raw Go test JSON artifact with inline structured
summaries and a compact failures-only artifact.
## What changed
- Added `scripts/gotestsummary`, a streaming Go tool that reads
gotestsum JSON and renders failed tests as Markdown.
- Updated the three Go test jobs to publish per-test `<details>`
sections in the job summary.
- Removed upload of the raw `go-test.json` artifact.
- Added upload of `go-test-failures-*.ndjson` with compact failure
records for deeper inspection.
- Deleted the old bash and `jq` summary script.
## Why
- The previous raw artifact was about 35 MB compressed and 445 MB raw in
the linked run.
- Passing-test output made the artifact noisy and slow to inspect.
- The old summary truncated output to 600 characters.
- The new path keeps streaming, bounded output and writes structured
diagnostics for only final failed tests.
## Validation
- `gofmt -w scripts/gotestsummary`
- `gofmt -l scripts/gotestsummary`
- `go test ./scripts/gotestsummary/...`
- `go vet ./scripts/gotestsummary/...`
- `grep -rn 'go-test-failure-summary.sh' . || true`
- `grep -rn 'go-test-failure-summary.sh\|go-test.json\|go-test-json-'
.claude .agents docs AGENTS.md || true`
- `make lint/agents`
- `make lint/emdash`
- `make lint/markdown`
- `make lint/shellcheck`
- `git diff --check origin/main..HEAD`
> This PR was prepared by Mux working on Mike's behalf.
This PR adds an opinionated harness-engineering layer for agent-driven
workflows: a small set of agent-readable docs, mechanical structure
checks, structured CI failure summaries, an architecture-lint umbrella,
and per-worktree dev-server isolation. The goal is to make local dev,
tests, and CI mechanically inspectable by agents without changing app
runtime behavior.
## What landed
**Agent docs and navigation**
- `.claude/docs/OBSERVABILITY.md`, `.claude/docs/DEV_ISOLATION.md`,
`.claude/docs/AGENT_FAILURES.md`: task-oriented guides for logs,
tracing, Prometheus, dev-server isolation, and a seeded failure catalog.
- `AGENTS.md`: added an `Agent navigation` block, then trimmed the file
from 375 to 229 lines by migrating duplicated detail into
`WORKFLOWS.md`, `GO.md`, `TESTING.md`, and `DATABASE.md`. The
user-managed custom-instructions block is preserved.
- `.agents/docs`: symlink mirror of `.claude/docs` for agent runtimes
that look under `.agents`.
**Mechanical checks**
- `scripts/check_agents_structure.sh`: validates `@...` references in
tracked `AGENTS.md` files and warns when root grows past 600 lines.
Wired as `make lint/agents` and into `make lint`.
- `scripts/audit-agent-readiness.sh`: report-first audit of harness
readiness. Currently `10 ok, 0 warn, 0 fail`.
- `scripts/check_architecture.sh` / `make lint/architecture`: umbrella
architecture-lint target. Consolidates the existing
`check_enterprise_imports.sh` and `check_codersdk_imports.sh` so they
run exactly once via the umbrella. Slot is open for new high-confidence
rules.
**Structured CI failure summaries**
- `scripts/playwright-failure-summary.sh`: parses
`site/test-results/results.json` and writes Markdown to
`$GITHUB_STEP_SUMMARY` on failure. Wired into the `test-e2e` matrix job.
- `scripts/go-test-failure-summary.sh`: parses `go test -json`
line-delimited output the same way. Wired into `test-go-pg`,
`test-go-pg-17`, and `test-go-race-pg` by injecting `gotestsum
--jsonfile` in the workflow without touching `Makefile`. JSON also
uploaded as a CI artifact on failure.
- `site/e2e/playwright.config.ts`: enables `screenshot:
only-on-failure`, `trace: retain-on-failure`, JSON reporter, and HTML
reporter alongside existing reporters.
- `.github/workflows/ci.yaml`: failure artifact uploads for Playwright
now use `if: failure()` and predictable names
(`playwright-artifacts-<variant>-<sha>`).
**Per-worktree dev-server isolation** (`scripts/develop/main.go`)
- Deterministic FNV-64a hash of the worktree path produces a port offset
in `[0, 1000)` (50 buckets, step 20 to avoid API/proxy overlap across
adjacent buckets).
- Offset is applied only to defaults; both env vars (`CODER_DEV_PORT`,
`CODER_DEV_WEB_PORT`, `CODER_DEV_PROXY_PORT`,
`CODER_DEV_PROMETHEUS_PORT`) and CLI flags retain priority.
- Hardcoded ports `9090` (embedded Prometheus UI) and `12345` (Delve)
are unchanged by design.
- Startup banner shows each port's source: `default`, `offset`, or
`explicit`.
- Unit tests in `scripts/develop/main_test.go` cover determinism,
bounds, no-overlap across the four ports, and explicit-skip behavior.
- State (`.coderv2/`) was already worktree-isolated via `os.Getwd()`, so
no state-dir changes were needed.
## Validation
`make lint/agents`, `make lint/architecture`, `make lint/emdash`, `bash
scripts/audit-agent-readiness.sh` (10 ok, 0 warn, 0 fail), `shellcheck`
on all 5 new scripts, `go test ./scripts/develop/...`, and `js-yaml`
parse of `ci.yaml` all pass. Synthetic fixtures verify both
failure-summary scripts handle empty/missing input (silent exit 0),
ANSI-stripped output, and parent/subtest formatting.
## Known follow-ups (deferred)
- Frontend Storybook/Vitest failure summary: lowest-leverage slice of
the failure-summary work. Skipping until observed pain.
- Architecture lint currently only delegates to existing import checks;
new rules (`InTx` outer-store detection, swagger-annotation lint) plug
in as needed.
- 50 port-offset buckets means two worktree paths can occasionally
collide. The DEV_ISOLATION doc tells users to set the relevant env var
when this happens.
> Mux opened this PR on Mike's behalf.
Use typed atomics (atomic.Int64, atomic.Int32, etc.) in test files to prevent
mixing atomic and non-atomic access on the same value, guarantee 64-bit
alignment on 32-bit platforms, and provide a cleaner API.
> Mux working on behalf of Mike.
## Summary
Clarifies that GitHub PR body prose should rely on soft wrapping instead
of manual fixed-width hard wraps. Updates the examples and key
principles to match that guidance.
## Validation
- `pnpm exec markdownlint-cli2 .claude/docs/PR_STYLE_GUIDE.md`
- `make lint/emdash`
- `make pre-commit-light`
Add a lint check that prevents introduction of Unicode emdash (U+2014)
and endash (U+2013) characters. These are almost exclusively introduced
by AI agents and conflict with the project writing style.
The lint script (scripts/check_emdash.sh) checks only added lines in
the current diff by default, so existing violations do not block CI.
Pass --all to scan the entire repo for auditing.
Agent instructions in AGENTS.md, site/AGENTS.md, and the docs style
guide now explicitly ban emdash, endash, and " -- " as punctuation,
with guidance to use commas, semicolons, or periods instead.
The attribution footer in the PR style guide assumed all AI-generated
PRs come from Claude Code using Claude Sonnet 4.5. PRs can be generated
through different tools and models (e.g. Coder Agents), so a hardcoded
template is misleading.
Co-authored-by: Michael Suchacz <ibetitsmike@users.noreply.github.com>
Restore PR title validation that was removed in 828f33a when
cdr-bot was expected to handle it. That bot has since been disabled.
The new title job in contrib.yaml validates:
- Conventional commit format (type(scope): description)
- Type from the same set used by release notes generation
- Scope validity derived from the changed files in the PR diff
- All changed files fall under the declared scope
Uses actions/github-script (no third-party marketplace actions).
Also fixes feat(api) examples across docs (no api folder exists)
and consolidates commit rules into CONTRIBUTING.md as the single
source of truth.
The `test-postgres` Makefile rule was redundant — CI never used it (it
runs `test-postgres-docker` + `make test` via the `test-go-pg` action),
and `make test` auto-starts a Postgres Docker container when needed via
`dbtestutil`.
- Remove the `test-postgres` rule from Makefile
- Update `pre-push` to run `test-postgres-docker` in the first phase
(alongside gen/fmt) and `make test` in the second phase
- Fix stale comments in CI workflows referencing `make test-postgres`
- Remove redundant "Test Postgres" entries from docs since `make test`
handles Postgres automatically
This pull request adds a new documentation file that defines the
"code-review" skill for use in the project. The document outlines a
standard workflow, severity levels, key areas to focus on during code
reviews, and Coder-specific review guidelines. This aims to standardize
and improve the quality and consistency of code reviews across the team.
Documentation and process standardization:
* Added `.claude/skills/code-review/SKILL.md`, which describes the
code-review skill, including workflow steps, severity levels, what to
look for in reviews, and what not to comment on. It also provides
Coder-specific patterns and best practices for authorization, error
handling, and shell scripting.
## Summary
Updates our existing doc-check workflow to utilize new claude-skills
that exist in the repository for better contextual behavior with less
prompting requirements in the workflow
## Changes
### New: Claude Skill (`.claude/skills/doc-check/SKILL.md`)
Defines the doc-check workflow for Claude:
- Check PR title first to skip irrelevant reviews (refactors, tests,
chores)
- Read code changes and search existing docs for related content
- Post structured comments with specific recommendations
### Updated: GitHub Workflow (`.github/workflows/doc-check.yaml`)
- **Triggers**: PR opened, updated (synchronize), `doc-check` label
added, or manual dispatch
- **Task lifecycle**: Creates task → monitors completion → fetches logs
→ cleans up
- **Context-aware prompts**: Tells Claude if this is a new PR, update,
or manual request
- Uses `coder-username` parameter to run as `doc-check-bot` service
account
When working on PRs, Claude Code was sometimes force pushing to
branches. This adds simple git workflow guidelines that emphasize proper
branch checkout and avoiding force pushes.
## Changes
Added git workflow section to `CLAUDE.md`, `AGENTS.md`, and
`.claude/docs/WORKFLOWS.md` with:
- Instructions to fetch, checkout, and pull before working on PR
branches
- Note to avoid `git push --force` unless explicitly requested
## Examples of force push behavior
Observed in recent PRs:
- PR #21148: 7 commits including merge commit from iterative changes
- PR #21150: 9 commits with multiple documentation iterations
- PR #21182: 4 commits with iterative fixes
- Force update on `feat/add-tasks-template-flag` branch:
`9bf7980b9...f98cf44f7`
The guidelines now make it clear to check out branches properly and push
normally.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
The _redirects file format is used by Netlify and Cloudflare Pages, but
coder.com runs on Vercel with Next.js. Redirects for coder.com/docs must
be configured in the coder/coder.com repository redirects.json file.
This file was never functional and caused confusion when renaming docs.
Co-authored-by: blink-so[bot] <211532188+blink-so[bot]@users.noreply.github.com>
## Summary
This PR addresses David's review comments from PR #21153 to improve the
Documentation Style Guide.
## Changes
- **Research section**: Updated to focus on reading "recent
documentation" instead of "10+ similar pages" - more practical guidance
- **Premium Feature Callout**: Clarified that the manifest.json badge
addition should happen in `docs/manifest.json`
- **Screenshot Guidelines**: Added context that this is for when
screenshots "don't exist yet", making it clearer this is a temporary
measure
- **Tabs documentation**: Expanded explanation to clarify when tabs are
appropriate (parallel content paths)
- **Coder registry**: Added mention of referencing Coder registry URLs
for cross-linking to external Coder resources
All changes maintain the existing documentation structure while
improving clarity and specificity based on review feedback.
Refs #21153🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
Adds a style guide documenting PR description patterns observed in the
Coder repository. This guide is intended for AI agents to reference when
creating PRs, ensuring consistency with project conventions.
The guide covers title format (Conventional Commits), description
structure (default concise vs. complex structured), what to include
(links, performance context, warnings), and what to avoid (test plans,
benefits sections). Includes examples from recent merged PRs
demonstrating each pattern.
Placed in `.claude/docs/` alongside other agent-specific documentation
(WORKFLOWS.md, ARCHITECTURE.md, etc.) rather than in the main
contributing docs, as this is primarily for automated tooling reference.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
Adds a comprehensive documentation style guide in
`.claude/docs/DOCS_STYLE_GUIDE.md` documenting patterns observed across
Coder's existing documentation. This guide is intended for AI agents to
reference when writing documentation, ensuring consistency with project
conventions.
The guide covers research requirements (code verification, permissions
model, UI thresholds), document structure (titles, premium callouts,
overview sections), image usage (placement, captions, screenshot-driven
organization), content organization, writing style, code examples,
accuracy standards (specific numbers, permission actions, API
endpoints), manifest requirements, and proactive documentation
approaches.
Placed in `.claude/docs/` alongside other agent-specific documentation
(WORKFLOWS.md, ARCHITECTURE.md, etc.) and imported in CLAUDE.md to
ensure it's automatically loaded into context for documentation work.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
Replace `.cursorrules` with symlink to `AGENTS.md` to establish a single
authoritative document for AI agent guidelines.
Extract architectural documentation from `.cursorrules` into
`.claude/docs/ARCHITECTURE.md` for reference material.
This ensures all AI agents (Claude, Cursor, etc.) use the same
guidelines without duplication.
---
🤖 This change was written by Claude Sonnet 4.5 Thinking using
[mux](https://github.com/coder/mux) and reviewed by a human 🏂
## Problem
Users were being automatically logged out when deleting OAuth2
applications.
## Root Cause
1. User deletes OAuth2 app successfully
2. React Query automatically refetches the app data
3. Management API incorrectly returned **401 Unauthorized** for the
missing app
4. Frontend axios interceptor sees 401 and calls `signOut()`
5. User gets logged out unexpectedly
## Solution
- Change management API to return **404 Not Found** for missing OAuth2
apps
- OAuth2 protocol endpoints continue returning 401 per RFC 6749
- Rename `writeInvalidClient` to `writeClientNotFound` for clarity
## Additional Changes
- Add conditional OAuth2 navigation when experiment is enabled or in dev
builds
- Add `isDevBuild()` utility and `buildInfo` to dashboard context
- Minor improvements to format script and warning dialogs
Signed-off-by: Thomas Kosiewski <tk@coder.com>
# Organize Development Documentation into Separate Files
This PR reorganizes the development documentation by splitting the monolithic CLAUDE.md file into multiple focused documents. The main file now provides a concise overview with essential commands and critical patterns, while importing detailed content from specialized guides.
Key improvements:
- Created separate documentation files for specific domains:
- Database development patterns
- OAuth2 implementation guidelines
- Testing best practices
- Troubleshooting common issues
- Development workflows and guidelines
- Restructured the main CLAUDE.md to be more scannable with improved formatting
- Added quick-reference tables for common commands
- Maintained all existing content while making it more accessible
- Highlighted critical patterns that must be followed
This organization makes the documentation more maintainable and easier to navigate, allowing developers to quickly find relevant information for their specific tasks.
Ben Potter