AGENTS.md · thedaviddias/Front-End-Checklist

Sections

1. Project Overview
2. Work Tracking
3. MCP Usage
4. Monorepo Structure
5. Rule MDX Frontmatter Spec
6. Canonical Rule Shape
7. Category Taxonomy
8. Quality Scoring Rubric
9. Adding or Updating a Rule
10. Scripts Reference
11. MCP Tool Development
12. Workspace Architecture Notes
13. Learned User Preferences
14. Learned Workspace Facts

First lines (shown under the repo's MIT license)

# AGENTS.md — Front-End Checklist

Repository rules and conventions for contributors and automation tools.

## Project Overview

**Front-End Checklist** is an open-source monorepo providing 385 quality-gated frontend best practice rules with an MCP server for structured review workflows.

- **MCP Server**: `https://mcp.frontendchecklist.io` (11 tools)
- **Rules**: `packages/content/rules/en/<category>/<slug>.mdx`
- **Web App**: `apps/web/` (Next.js App Router)
- **MCP Package**: `packages/mcp/` (TypeScript)
- **Package Manager**: pnpm (workspaces + Turborepo)

## Work Tracking

Work in this repo is tracked in Paperclip project **FEC** (Front-End Checklist, id `c5edfe8f-731b-43e8-b805-c52999831084`). New tickets get the `DAV-` prefix.

## MCP Usage

When working on frontend implementation, review, debugging, or audit tasks, use the Front-End Checklist MCP server when available so recommendations stay grounded in the project rule corpus.

- Use `review_code` first for pasted or inspected HTML, CSS, JavaScript, TypeScript, React, or Next.js code.
- Use `search_rules` before making accessibility, performance, SEO, security, image, privacy, i18n, or testing recommendations.
- Use `get_rule`, `check_rule`, `fix_rule`, or `explain_rule` for rule-specific guidance and remediation.
- Use `get_workflow` or `get_checklist_rules` for broad launch, accessibility, SEO, security, performance, and testing audits.
- Use `audit_url` for public `https://` pages.

Some clients lazy-load installed MCP tools. If the tools are not initially visible, search for or explicitly request the Front-End Checklist MCP before proceeding with frontend work.

## Monorepo Structure

```
apps/
  web/                    # Next.js app (App Router)
packages/
  mcp/                    # MCP server implementation
  content/                # Rules MDX content + content-collections config
  auth/                   # Better-Auth + Prisma + Supabase
  design-system/          # Shared UI components
  types/                  # Shared TypeScript types
  data-layer/             # Data access layer
  schemas/                # Zod v4 schemas
```

## Rule MDX Frontmatter Spec

Rules live at `packages/content/rules/en/<category>/<slug>.mdx`.

### Required Fields

```yaml
---
title: "Human-readable rule title (string, use quotes)"
description: "One-sentence description of what to do"
categories: ['html']           # Array; first item = primaryCategory
priority: 'high'               # 'critical' | 'high' | 'medium' | 'low'
difficulty: 'beginner'         # 'beginner' | 'intermediate' | 'advanced' | 'expert'
estimatedTime: 15              # Minutes as integer
prompts:
  check: "Prompt for checking whether the implementation follows this rule"
  fix: "Prompt for fixing the issue"
  explain: "Prompt for explaining why this rule matters"
---
```

### Recommended Fields

These fields are not required by the parser, but they materially improve rule quality, MCP usefulness, and generated skills.

```yaml
subcategory: 'keyboard'        # Sub-grouping within category
tldr:                          # Array of bullet points (used in llms.txt)
  - "Key point one"
  - "Key point two"
whyItMatters: "Paragraph explaining the business/user impact"
sources:
  - title: "MDN or spec page title"
    url: "https://..."
    type: "mdn|spec|guide|wcag|google"
    id: "stable-source-id"
    role: "standard|reference|implementation|compatibility|regulation|search|research"
    authority: "primary|secondary"
resources:
  - name: "Supplementary tool or article"
    url: "https://..."
    type: "tool|article|reference"
relatedRules:
  - slug: other-rule-slug
    reason: "Why these rules relate"
tools:
  - name: "Tool Name"
    url: "https://..."         # or null
tags: ['wcag', 'performance']
prompts:
  codeReview: "Recommended prompt for systematic code review context"
aiContext: "Additional context for automated review about when this rule applies"
```

Authoring placement rules:

- Put authoritative citations in `sources`, not in body prose like `Reference: ...`
- `sources` are proof metadata, not generic further reading. Every rule needs at least 2 sources, 2 source roles, and 1 `authority: primary`.
- `resources` are for further reading or tools only. Do not map evidence claims to `resources`.
- The system may infer or normalize `id`, `role`, and `authority` for sources at build time; authors should focus on strong, relevant sources rather than maintaining claim-by-claim proof objects.
- Put cross-rule navigation in `relatedRules`, not in body prose like `See also ...`
- Keep intro paragraphs focused on the rule itself; metadata should render from frontmatter-driven UI

Inline link contract:

- Natural inline links inside body prose are allowed when they support a specific claim, comparison, or implementation recommendation.
- Prefer light-touch density: usually `2-5` inline links per rule, with `0-1` in the intro and `1-3` across the main guidance sections.
- Prefer external links over internal ones; internal rule links should usually stay at `0-1`, with `2` only for unusually interconnected rules.
- Keep standalone metadata lines out of the body. Do not add paragraphs that start with `See also ...` or `Reference: ...`.
- Keep evergreen proof in `sources`, and use newer inline external articles only when they add practical or recent context that the primary sources do not cover alone.
- When a named tool is mentioned in prose for the first meaningful time (for example `Screaming Frog` or `Google Search Console`), link that first mention if the tool materially helps the reader and already exists in `resources` or `tools`.
- Approved secondary inline links should stay curated. Prefer strong platforms such as `CSS-Tricks`, `Smashing Magazine`, `Nielsen Norman Group`, `WebAIM`, `Screaming Frog`, `Sitebulb`, `Moz`, or `Yoast` when they add practical implementation context.
- Use descriptive anchor text tied to the sentence claim, not generic labels like “read more”.

`impact`, `standards`, and `automation` are intentionally not part of the active rule-writing contract right now. The current corpus and tooling do not consume them consistently enough to justify treating them as standard authoring fields.

## Canonical Rule Shape

New and refreshed rules should follow this structure unless there is a strong reason not to:

1. Short intro paragraph explaining the rule in plain language
2. `## Code Example` or `## Code Examples`
3. `## Why It Matters`
4. Optional implementation or guidance sections
5. `## Verification`

Canonical ordering rules:

- `## Code Example` or `## Code Examples` must appear before `## Why It Matters`
- `## Why It Matters` must appear before `## Verification`
- `## Verification` must be the final H2 in the rule body
- Optional H2 sections belong between `## Why It Matters` and `## Verification`

Preferred optional H2 taxonomy:

- `## Best Practices`
- `## Common Mistakes`
- `## Framework Examples`
- `## Tools & Validation`
- `## Thresholds`
- `## Exceptions`
- `## Browser Support`
- `## Support Notes`
- `## Standards`
- `## Implementation Notes`

The validator reports headings outside this preferred taxonomy so section sprawl stays visible over time.

Rule Contract V2 adds three conditional concepts:

- `## Exceptions` for nuanced rules, false positives, or valid caveats
- `### Automated Checks` and `### Manual Checks` inside `## Verification` when both matter
- a short visible standards/support note for compatibility-sensitive or compliance-sensitive rules

Apply these conditionally, not universally.