Development Rules

Relevant source files

The following files were used as context for generating this wiki page:

• AGENTS.md
• CLAUDE.md
• biome.json
• package.json
• src/agent/setup.ts
• src/log.ts

Development Rules for the pi-digby project encompass the standards, workflows, and technical constraints required to maintain a consistent and high-quality codebase. These rules cover everything from code style and linting to commit conventions and execution safety, ensuring that the Slack bot assistant remains reliable and maintainable.

The project is built using TypeScript in strict mode, utilizing ESM with explicit .js extensions for imports. It relies on Biome for linting and formatting, and follows specific patterns for asynchronous operations and external API interactions.

Code Quality and Style

The project enforces strict TypeScript usage and automated formatting to ensure code readability and minimize runtime errors.

Core Principles

• Strict Typing: The use of any types is prohibited unless absolutely necessary. Developers must check node_modules for external API type definitions rather than guessing.
• Formatting: Biome handles all code formatting with a specific configuration: tabs for indentation, an indentation width of 3, and a maximum line width of 120 characters.
• Import Syntax: All imports must use ESM syntax with explicit .js extensions.

Sources: AGENTS.md:4-5, AGENTS.md:16-17, biome.json:15-18

Linting Rules

The project uses Biome's recommended ruleset with specific overrides to balance strictness and practicality.

Rule Category	Setting	Description
style.noNonNullAssertion	off	Allows non-null assertions where type safety is handled manually.
style.useConst	error	Enforces const for variables that are never reassigned.
suspicious.noExplicitAny	off	While discouraged in docs, the linter allows it for edge cases.
recommended	true	Enables Biome's standard recommended linting suite.

Sources: biome.json:4-13

Workflow and Commands

Developers are expected to follow a specific sequence of commands to validate changes. Local builds are discouraged as the CI environment handles production builds.

Essential Commands

• Validation: npm run check runs both Biome linting (with auto-fix) and TypeScript type-checking via tsgo. This must be run after any code changes.
• Quick Check: npx tsgo --noEmit provides a fast type-check without running the linter.
• Builds: Developers should NEVER run npm run build locally; this is reserved for CI environments.

Sources: AGENTS.md:9-11, package.json:11-12, CLAUDE.md:25-28

Commit and Contribution Rules

To maintain a clean project history and prevent regression, the project employs automated hooks and standardized messaging.

• Conventional Commits: Commit messages must follow the conventional format, such as feat(scope):, fix(scope):, or docs:.
• Functionality Removal: Always ask before removing code or functionality that appears intentional.
• Pre-commit Hooks: A pre-commit hook (managed by Husky) enforces that npm run check passes before a commit is allowed.

Sources: AGENTS.md:6, AGENTS.md:14, package.json:15

Logging and Monitoring

System activity and agent execution must be logged through the centralized logging module to ensure consistency in output format.

Log Levels and Formatting

All logs include a timestamp in ISOString format (truncated to HH:MM:SS) and specific markers for different event types.

Function	Output Prefix	Purpose
info(msg)	[HH:MM:SS]	General system information.
warn(msg)	[HH:MM:SS] ⚠	Recoverable issues or API retries.
error(msg)	[HH:MM:SS] ✗	Critical failures.
toolStart()	[HH:MM:SS] [channel] →	Indicates the start of a tool execution.
toolEnd()	[HH:MM:SS] [channel] ✓/✗	Indicates completion or failure of a tool.

Sources: src/log.ts:5-28

Execution Telemetry

The project tracks execution costs and token usage, which is logged at the end of runs to monitor resource consumption.
Sources: src/log.ts:31-38, src/agent/setup.ts:223-230

Infrastructure and Security

Development must respect the AWS-based architecture and security model.

• Bedrock Authentication: Local development requires AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. In production, the bot uses the ECS Task Role (pi-digby-task), and IAM user credentials should not be used.
• Secrets Management: Secrets are stored in AWS Secrets Manager (pi-digby/env) and are managed via CLI. They should not be added directly to CloudFormation templates.
• Persistence: Persistent data (logs, memory, skills) is stored in EFS at /data. Ephemeral code resides in /app.

Sources: src/agent/setup.ts:46-56, CLAUDE.md:10-14, deploy/cloudformation.yml:181-185

Summary

The development rules for pi-digby establish a "verify-first" culture where automated tools (Biome, tsgo, Husky) ensure code health before it reaches the repository. By adhering to conventional commits, ESM standards, and strict logging patterns, the team maintains a high-velocity environment that remains secure within the AWS ecosystem.