Skip to content

AGENTS.md

Latest commit

 

History

History
106 lines (76 loc) · 4.17 KB

AGENTS.md

File metadata and controls

106 lines (76 loc) · 4.17 KB

AGENTS.md — node-slack-sdk

Instructions for AI coding agents working on this repository.

Project Overview

Package Architecture

Package Folder Description
@slack/web-api packages/web-api Core Web API client (most complex package)
@slack/types packages/types Shared Slack platform TypeScript types (Block Kit, events, etc.)
@slack/logger packages/logger Logging utility used by other packages
@slack/webhook packages/webhook Incoming webhook client
@slack/oauth packages/oauth OAuth flow handling and token management
@slack/socket-mode packages/socket-mode WebSocket-based real-time event client
@slack/cli-hooks packages/cli-hooks CLI integration hooks for Slack CLI

Additional internal packages: cli-test (test utilities), rtm-api (legacy RTM client).

Dependency Graph (Build Order)

Independent (no internal deps): cli-hooks, cli-test
Base:                           logger, types
Depends on base:                web-api, webhook
Depends on web-api:             oauth, rtm-api, socket-mode

Build packages in this order — a package can only be built after its dependencies.

Build System

# Install all dependencies from the repo root
npm install

# Lint all packages (Biome)
npm run lint
npm run lint:fix

# Build a specific package
npm run build --workspace=packages/web-api

# Test a specific package
npm test --workspace=packages/web-api

Full Build Order (from CI)

# 1. No internal dependencies
npm run build --workspace=@slack/cli-hooks
npm run build --workspace=@slack/cli-test

# 2. Base dependencies
npm run build --workspace=@slack/logger
npm run build --workspace=@slack/types

# 3. Packages requiring base dependencies
npm run build --workspace=@slack/web-api
npm run build --workspace=@slack/webhook

# 4. Packages depending on web-api
npm run build --workspace=@slack/oauth
npm run build --workspace=@slack/rtm-api
npm run build --workspace=@slack/socket-mode

Critical Rules

  1. Never manually edit packages/web-api/src/types/response/*.ts — these files are auto-generated by scripts/generate-web-api-types.sh. They contain a "DO NOT EDIT" banner.
  2. Request types ARE manually maintained — packages/web-api/src/types/request/ is hand-written code; edit these responsibly.
  3. Build packages in dependency order — see the dependency graph above.
  4. Use Biome, not ESLint or Prettier — config is in biome.json at repo root.
  5. TypeScript 5.9.3, Node 18+ (tested on Node 18, 20, 22, 24).

Code Conventions

  • Formatting: configured in biome.json
  • Test files: *.test.{ts,js} using node:test + node:assert/strict; coverage via --experimental-test-coverage
  • Type tests: *.test-d.ts using tsd
  • CI matrix: Node 18.x, 20.x, 22.x, 24.x on Ubuntu + Windows

Package-Level AGENTS.md

Individual packages have their own AGENTS.md with package-specific guidance:

  • packages/types/AGENTS.md — shared type definitions, Block Kit types, event types
  • packages/web-api/AGENTS.md — adding API methods, code generation, client architecture

Development Philosophy

  • Follow existing patterns exactly — when adding or modifying code, match the style of adjacent code.
  • Reuse mixins and shared types rather than duplicating field definitions across packages.
  • PascalCase for types, camelCase for methods.
  • JSDoc on public APIs: Always include @description and @see with a link to the API reference.

Common Pitfalls

  • Build in dependency order — see the dependency graph above.