Skip to content

CLAUDE.md

Latest commit

 

History

History
149 lines (121 loc) · 5.89 KB

CLAUDE.md

File metadata and controls

149 lines (121 loc) · 5.89 KB

CLAUDE.md — Agent Instructions for Argus

This file tells AI coding agents how to work on the Argus codebase.

What is Argus?

Argus is a design intelligence runtime for AI agents. It gives coding agents the ability to see, judge, and learn from visual design quality. The codebase is a TypeScript monorepo using pnpm workspaces.

Repository structure

argus/
├── packages/           ← Core libraries (npm-publishable)
│   ├── protocol/       ← Shared types, constants, interfaces
│   ├── inspector/      ← DOM analysis, CSS extraction, a11y audit
│   ├── scorer/         ← Design quality scoring engine + rules
│   ├── memory/         ← Preference learning, taste profiles, export
│   ├── flux/           ← CSS interpolation engine
│   ├── typo/           ← Typography engine
│   ├── pulse/          ← Animation/visualization engine
│   └── lens/           ← Inline component tweaking
├── apps/               ← Runnable applications
│   ├── cli/            ← `argus` command line tool
│   ├── mcp-server/     ← MCP server for AI agent integration
│   ├── gateway/        ← Local WebSocket server
│   └── browser-ext/    ← Chrome extension
├── skills/             ← Design analysis skills (like plugins)
├── extensions/         ← Third-party tool integrations
├── test/               ← Integration tests, test fixtures
├── docs/               ← Documentation site
└── scripts/            ← Build and release scripts

Build commands

pnpm install              # Install all dependencies
pnpm build                # Build all packages
pnpm build:apps           # Build all apps
pnpm dev                  # Watch mode for packages
pnpm test                 # Run unit tests
pnpm test:integration     # Run integration tests
pnpm lint                 # Lint with oxlint
pnpm typecheck            # TypeScript type checking
pnpm argus <command>      # Run CLI in dev mode
pnpm gateway:watch        # Run gateway with auto-reload

Package dependency graph

protocol ← inspector ← scorer ← memory
                ↑          ↑        ↑
               flux      typo    pulse
                ↑          ↑        ↑
               lens ───────┘        │
                                    │
              cli ← mcp-server ← gateway

protocol is the leaf dependency. Everything depends on it. Nothing depends on cli, mcp-server, or gateway — they are entry points.

Code conventions

  • TypeScript strict mode. No any. No @ts-ignore. Use unknown and narrow.
  • Pure functions first. Side effects live at the edges (CLI, MCP server, gateway). Core packages are pure.
  • No classes in protocol. Shared types are interfaces and type aliases only.
  • Error handling. Use Result<T, E> pattern from @argus-design/protocol. No throwing in library code. Apps can throw.
  • Test co-location. Tests live next to source: foo.ts and foo.test.ts in the same directory.
  • No barrel re-exports in internal modules. Only index.ts at package root re-exports the public API.

Key types (from @argus-design/protocol)

  • ElementSnapshot — Complete state of a DOM element (selector, box, computed styles, a11y)
  • PageSnapshot — Array of ElementSnapshot + page-level metadata
  • ScoringRule — A function that takes inspection data and returns findings
  • Finding — A single scored observation (element, rule, severity, message, measured/expected values)
  • ScoreReport — Complete scoring output with findings grouped by category
  • DesignProfile — User's learned design preferences
  • Severity — "error" | "warning" | "info" | "pass"

Adding a new scoring rule

  1. Create packages/scorer/src/rules/your-rule.ts
  2. Export a ScoringRule function
  3. Register it in packages/scorer/src/rules/index.ts
  4. Add tests in packages/scorer/src/rules/your-rule.test.ts
  5. Document the rule in docs/tools/rules.md
import type { ScoringRule } from "@argus-design/protocol";

export const yourRule: ScoringRule = {
  id: "your-rule-id",
  name: "Your Rule Name",
  category: "spacing", // spacing | typography | color | hierarchy | accessibility | consistency
  description: "What this rule checks",
  evaluate: (snapshot) => {
    const findings = [];
    // ... analysis logic
    return findings;
  },
};

Adding a new skill

Skills live in skills/<skill-name>/SKILL.md. Each skill is a markdown file with structured metadata:

---
name: skill-name
description: What this skill checks
category: accessibility | spacing | typography | color | layout | responsive
rules: [rule-id-1, rule-id-2]
---

# Skill instructions for the agent
...

MCP tool naming

All MCP tools use the design. prefix:

  • design.inspect — Analyze a page or component
  • design.score — Score design quality
  • design.suggest — Get improvement suggestions
  • design.apply — Apply a design fix
  • design.compare — Before/after comparison
  • design.preferences — Read/write taste profile
  • design.audit — Full design + a11y audit
  • design.doctor — Check Argus configuration health

Important invariants

  1. No LLM calls in scoring. All rules are deterministic. Reproducible. Fast.
  2. Scores are 0–100. Every rule, every category, every aggregate.
  3. Every finding has provenance. Rule ID, element selector, measured value, expected range.
  4. Memory is file-based. JSON files in ~/.argus/. No database.
  5. Packages are tree-shakeable. Side-effect-free exports.
  6. Node 20+ required. We use native fetch, structuredClone, top-level await.

What not to change without discussion

  • The Result<T, E> pattern in protocol
  • The scoring scale (0–100)
  • The MCP tool names and schemas
  • The ~/.argus/ directory structure
  • The pnpm workspace layout