Skip to content

AGENTS.md

Latest commit

 

History

History
165 lines (125 loc) · 5.25 KB

AGENTS.md

File metadata and controls

165 lines (125 loc) · 5.25 KB
Raw

Cirrus AGENTS.md

This document complements the human-focused README by giving coding agents precise, actionable instructions: build steps, tests, structure, and conventions. Keep human docs concise; put agent-specific details here for predictable automation.

Project summary (for agents)

Repository layout

  • base/ — foundational styles (animations, defaults, grid, layout, spacing, etc.)
  • builds/ — build files for core and ext bundles
  • components/ — UI components (accordion, button, modal, tabs, tooltips, etc.)
  • internal/ — shared variables, mixins, functions, constants
  • utils/ — utility classes (absolute, display, flex, opacity, position, shadow, transitions, z-index, etc.)
  • dist/ — generated build artifacts (do not edit by hand)

Setup

Requirements: Node and yarn installed.

git clone git@github.com:Spiderpig86/Cirrus.git
cd Cirrus
yarn install

Scripts and commands (from package.json)

  • Build artifacts
    • Command: yarn build
    • Underlying: gulp minify
    • Output: dist/cirrus.css, dist/cirrus.min.css
  • Watch (rebuild on changes)
    • Command: yarn watch
    • Underlying: gulp watch
  • Test suite
    • Command: yarn test
    • Underlying: jest
    • Filter by name/pattern: yarn test -- -t "<name or pattern>"
  • Security policy (Snyk)
    • Command: yarn snyk-protect
    • Underlying: snyk-protect (applies Snyk patches/policies if configured)
  • Lifecycle hook
    • Command: yarn run prepare (rarely needed manually)
    • Underlying: npm run snyk-protect
    • Note: prepare runs automatically in npm/yarn lifecycles; invoke manually only to re-apply patches if needed.

Development guidance

  • Edit SCSS only in source dirs (base/, components/, internal/, utils/). Never edit dist/ directly.
  • For tight feedback, run yarn watch while making SCSS changes.
  • Keep specificity low and rely on utilities to avoid cascade conflicts.
  • Centralize tokens, mixins, and functions in internal/ rather than duplicating logic.
  • Component styles should not assume JavaScript for basic behavior; Cirrus is Sass-first.
  • Be conservative in base/; changes there ripple widely.

Testing instructions

  • Run all tests locally before committing: 
    yarn test
  • Target a specific test by name/pattern: 
    yarn test -- -t "<pattern>"
  • Add/update tests for:
    • Sass functions/mixins in internal/
    • Generated utilities in utils/
    • Component-specific SCSS logic in components/
  • After reorganizing imports, re-run the suite to catch path/resolution issues.

Build and artifacts

  • Validate builds locally: 
    yarn build
  • Artifacts are written to dist/:
    • dist/cirrus.css
    • dist/cirrus.min.css
  • Do not import from dist/ within source SCSS.
  • Do not hand-edit files in dist/; they are generated by the build.

CI expectations

  • CI lives at .github/workflows/ci.yml.
  • PRs should pass all required checks (tests and build).

Contributing scope guidelines

  • Components: Make localized changes in components/; avoid global overrides.
  • Utilities: Add or adjust utility scales in utils/ with consistent naming.
  • Base: Be conservative—changes propagate widely; ensure adequate tests.
  • Internal: Introduce or modify variables, functions, and mixins here for reuse.

PR instructions

  • Title format: [Cirrus] <Short, descriptive title>
  • Before opening:
    • yarn test passes locally
    • yarn build completes without errors
    • No hand edits to dist/
    • Tests added/updated for behavior changes
  • Include notes in the PR description for user-facing changes and link relevant docs pages if applicable.

User-facing docs and examples

If a change modifies usage (classes, utilities, or components), include example snippets in the PR description and reference:

Release and publishing

  • Versioning and publishing to npm (cirrus-ui) are handled by maintainers.
  • Do not change package.json version or publishConfig unless directed.

Gotchas

  • Don’t reference dist artifacts directly in docs/examples—prefer the published package/CDN guidance (see README).
  • Keep utilities composable and avoid introducing high-specificity selectors.
  • Validate responsive behavior if touching layout, grid, or spacing systems.

Quick reference

# Install deps
yarn install

# Watch
yarn watch

# Build
yarn build

# Test
yarn test

# Single test
yarn test -- -t "<pattern>"

# Apply Snyk patches
yarn snyk-protect

# (Lifecycle) Re-run prepare
yarn run prepare

Pointers

  • README.md: installation and usage examples
  • .github/CONTRIBUTING.md and .github/CONTRIBUTING.yml: contributor guidelines
  • CI logs: GitHub Actions tab if builds/tests fail

This AGENTS.md is intended to be a stable, predictable reference for coding agents and automation. It complements README.md without duplicating human-focused content.