Skip to content

AGENTS.md

Latest commit

 

History

History
83 lines (56 loc) · 3.6 KB

AGENTS.md

File metadata and controls

83 lines (56 loc) · 3.6 KB

AGENTS.md

This file provides guidance to AI coding assistants when working with code in this repository.

Important: You must follow these rules and its language-specific rules referenced in that file.

Keeping This File Updated

When you make changes to the project that affect how AI agents should work with the codebase, update this file accordingly. This includes changes to:

  • Overall folder structure
  • Tech stack (frameworks, libraries, languages)
  • npm scripts and development commands
  • Testing approaches
  • Build and deployment processes

Important: Keep this file concise. Only include information that is relevant for most or all development tasks. Omit specific implementation details that don't affect how agents interact with the codebase.

Development Commands

This project uses npm scripts for all development tasks:

  • Test all: npm test - Runs all tests in parallel (format, lint, types, unit)
  • Unit tests: npm run test:unit - Run Vitest tests once
  • Watch tests: npm run vitest - Run Vitest in watch mode
  • Lint: npm run test:lint - ESLint with zero warnings allowed
  • Type check: npm run test:types - TypeScript compiler check
  • Format check: npm run test:format - Prettier format validation

Important: Use the typescript-lsp MCP to get diagnostics and type information Important: Use the vitest-server MCP to run individual tests. Important: Use the eslint MCP to check for linting errors.

Project Structure

  • Source: src/ - All source code and tests
  • Entry: src/index.ts; public API re-exported via src/exports/main.exports.ts, csv.exports.ts, mocks.exports.ts
  • Core: src/clockodo.ts (Clockodo client), src/lib/ (api, mappings, requests, etc.)
  • Models: src/models/ - TypeScript types and mocks for API entities (entry, customer, project, etc.)
  • Tests: Co-located with source using .test.ts suffix; integration test in src/integration.test.ts
  • Configuration: Uses @peerigon/configs for shared TypeScript, ESLint, and Prettier configs

Code Organization

  • SDK methods live on the Clockodo class in src/clockodo.ts; API calls go through src/lib/api.ts
  • Request/response keys are mapped to camelCase in src/lib/mappings.ts
  • Uses ES module syntax throughout (.ts extensions in imports)
  • Keep README.md API method documentation in sync whenever public SDK methods are added, removed, or renamed

Pulling Updates from Upstream

If user is asking you to pull in updates from the upstream repository, you can do so by following these steps:

Step 1: Merge Template Updates

git fetch upstream
git merge --strategy-option theirs --no-commit upstream/main

This will:

  • Prefer template files in conflicts (--strategy-option theirs)
  • Stage changes without committing (--no-commit)

Step 2: Restore Project Specific Files

Restore project-specific files and changes:

  • package.json: Restore original dependencies but keep the dependency updates from the upstream repository
  • README.md: Restore original project documentation
  • AGENTS.md: Restore project specific instructions and include changes from the upstream repository
  • src/: Restore project specific source code and include changes from the upstream repository

Step 3: Verify and Clean Up

  1. Run npm install to update lockfile
  2. Run npm test to verify everything works
  3. Review git status and git diff --staged for unexpected changes

Step 4: Stage Changes

IMPORTANT: Stage your changes, but do not commit. Ask the user to review the changes first.