Skip to content

AGENTS.md

Latest commit

 

History

History
121 lines (95 loc) · 7.06 KB

AGENTS.md

File metadata and controls

121 lines (95 loc) · 7.06 KB

Contracts Spec Governance

Treat @contractspec/lib.contracts-spec as a compatibility surface, not an implementation detail.

Every meaningful change must:

  1. update the contract source first
  2. classify compatibility intent
  3. pass through ContractSpec Connect before risky edits or shell execution
  4. preserve policy/workflow integrity
  5. leave behind review and replay evidence when escalation is required
  6. keep package docs, website docs, and release capsules aligned when the public contract surface or workflow changes

ContractSpec Codebase

Mission: ContractSpec is the open spec system for AI-native software: explicit contracts, aligned surfaces, safe regeneration, and an operating layer on top when teams need it.

Quick Reference

Concern Rule File Key Points
Contracts contracts-first.md Spec before implementation
Mission & Context contractspec-mission.md Why we exist, who we serve
Architecture package-architecture.md libs → integrations/modules → bundles → apps
Code Quality code-quality-practices.md Testing, naming, standards
File Organization code-splitting.md Max 250 lines, domain grouping
Type Safety type-safety-dependencies.md No any, latest deps
Frontend frontend.md Atomic design, state handling
Backend backend.md Hexagonal, DDD
Design System design-system-usage.md No raw HTML
Delivery Lifecycle lifecycle-loop.md Ideation → plan → ship → review → observe → document
Cursor Marketplace cursor-marketplace-readiness.md Plugin metadata, artifact safety, publish readiness
AI Governance ai-agent.md Traceability, composability
Documentation docs.md DocBlocks first

Core Principles

  1. Spec-First: Contracts define behavior before implementation
  2. Multi-Surface Consistency: One spec → API, DB, UI, events
  3. Safe Regeneration: Code can be regenerated without breaking invariants
  4. Standard Tech: TypeScript, Zod, no magic abstractions
  5. Incremental Adoption: Stabilize one module at a time

Repository Layout

  • packages/libs/: Foundational contracts, runtimes, agent systems, design system primitives, and shared utilities.
  • packages/integrations/: Runtime, provider, and environment bridges that connect core libs to concrete execution targets.
  • packages/modules/: Domain and feature modules that compose libs and integrations into reusable product surfaces.
  • packages/bundles/: Higher-level product composition for docs, workspace, marketing, and other cross-feature surfaces.
  • packages/examples/: Runnable or importable reference implementations that demonstrate the package stack in practice.
  • packages/apps/ and packages/apps-registry/: Deployable shells such as CLIs, MCP servers, APIs, websites, mobile apps, and registry surfaces.
  • packages/tools/: Build, lint, docs, config, and agentpacks tooling used across the repository and downstream workspaces.

AGENTS.md Routing

  • The root AGENTS.md is generated from this overview rule and gives repository-wide guidance.
  • Package-level AGENTS.md files are the authoritative local guides for touched packages; always prefer the nearest one when editing code.
  • When the root guide and a package guide differ, follow the more specific package guidance unless it conflicts with higher-priority safety or security rules.

Docs And Release Sync

  • Treat root README.md, the nearest package README.md, the nearest package AGENTS.md, the website docs, and /llms* guidance as one public documentation surface.
  • When contributor or user workflows change, use the paired .changeset/*.md and .changeset/*.release.yaml files as the canonical release-facing source of truth for what must be reflected in docs.
  • Update the source rule files that generate root guidance instead of hand-editing generated root AGENTS.md.
  • If a website or changelog surface depends on generated release artifacts, run contractspec release build before treating that surface as current.

Code Style (Enforced)

  • Language: TypeScript (strict mode)
  • Formatting: 2 spaces, semicolons, double quotes, trailing commas
  • Types: Explicit, no any, proper type guards
  • Files: Max 250 lines (components: 150, utilities: 100)

Before You Code

  1. Read relevant rules for your change type
  2. Check the nearest package README.md and AGENTS.md before changing behavior
  3. If the change affects public behavior or operator workflow, inspect the related .changeset/*.md and .release.yaml files before updating docs
  4. Check existing patterns in the codebase
  5. Plan with DocBlocks if adding new features
  6. Run /ai-audit to verify decisions

AI Agent Guidelines

When working with AI assistants:

  • Rules are applied contextually based on file type
  • Treat package.json, src/, local README.md, and local AGENTS.md as the source of truth for package behavior
  • MCP schemas, exported subpaths, CLI signatures, and generated artifacts are compatibility surfaces and should be changed deliberately
  • Keep generated docs, /llms*, and release-manifest-backed website surfaces aligned with the same underlying source docs and release capsules
  • Conflicts resolved by: Security > Compliance > Safety > Quality > UX > Performance
  • All decisions should be traceable and reversible
  • Use /ai-audit to verify governance compliance

Commands Available

  • /commit - Create conventional commit
  • /test - Run tests with analysis
  • /lint - Check and fix lint issues
  • /fix - Auto-fix common issues
  • /explain - Understand code
  • /ideate - Shape idea into a scoped brief
  • /analyze-codebase - Audit architecture/contracts/quality hotspots
  • /impact - Analyze change impact before build/PR
  • /review-plan - Review plan before coding
  • /refactor - Guided refactoring
  • /ship - Run release-readiness checks
  • /draft-pr - Create draft PR with checklist
  • /review-pr - Code review
  • /audit-health - File/layer/reuse health audit
  • /audit-observability - Logging/metrics/analytics audit
  • /document - Sync docs with implementation
  • /cursor-plugin - Build Cursor plugin artifacts
  • /ai-audit - Governance check

Getting Help

  • Check the specific rule file for detailed guidance
  • Use /explain <concept> for architecture questions
  • Run /ai-audit to verify your approach