Skip to content

AGENTS.md

Latest commit

 

History

History
20 lines (15 loc) · 2.93 KB

AGENTS.md

File metadata and controls

20 lines (15 loc) · 2.93 KB

Repository Guidelines

Project Structure and Module Organization

Paula uses pnpm workspaces, with core code distributed across packages/core and packages/cli. TypeScript source files for each package reside in src/, while compiled artifacts are written to dist/ and should not be modified directly. Core domain logic, Docker and GitHub adapters, and shared utilities are located in packages/core/src/{services,agent,utils,types}, with corresponding tests placed alongside source files following the *.test.ts pattern. Command-line entry points are in packages/cli/src/{commands,components,controllers}, responsible for wrapping core services to provide the paula executable. The root directory contains workspace configuration (such as tsconfig.json, pnpm-workspace.yaml) and installation scripts, with user-specific customizations written to .paula/ after initialization.

Build, Test, and Development Commands

  • pnpm install: Install workspace dependencies.
  • pnpm build: Run tsc compilation for all packages, generating the latest dist/ output.
  • pnpm dev: Start tsc in watch mode, suitable for continuous development.
  • pnpm lint, pnpm type-check: Execute ESLint and type checking to ensure consistent style.
  • pnpm test, pnpm test:watch, pnpm test:coverage: Run tests with Vitest, watch for changes, or generate coverage reports.

Code Style and Naming Conventions

Consistently use ES Module TypeScript, targeting Node 20+ runtime, with four-space indentation. Prefer named exports and follow directory naming patterns (such as *Service.ts, *Controller.ts). Standalone utility files use kebab-case naming (e.g., docker-labels.ts), while class-oriented modules maintain PascalCase. Always run pnpm lint before committing to fix style issues, and use Prettier when necessary to maintain automated formatting.

Testing Guidelines

Vitest is the default testing framework, following the *.test.ts layout co-located with source code. Describe blocks focus on business behavior (e.g., "ConfigService loadConfig"). Logic involving Docker or GitHub should preferably have integration-level tests. New features require test cases covering error branches and service combinations, ensuring pnpm test:coverage shows no coverage regression. When mocking external dependencies, prioritize reusing existing helper functions from packages/core/src/utils.

Commit and Pull Request Guidelines

The project history follows Conventional Commits (such as feat, chore, or scoped like chore(cli)). Keep commits concise in present tense, with subject lines under 70 characters. Reference related GitHub Issues in the commit body to maintain traceability. Pull Requests should explain the changes and list verification steps (e.g., pnpm build, pnpm test). When CLI output is involved, include screenshots or logs. PR labels must follow Paula's workflow (paula-todo → paula-done), ensuring automated workers respond correctly.