Gaunt Sloth Assistant project guidelines

This file provides guidance to any AI coding agent (Claude Code, Cursor, etc.) working with this repository.

IMPORTANT: Always read and follow .gsloth.guidelines.md first for development principles, testing patterns, and workflow.

Tool Use

Precedence for your tool use:

Your built-in tools (e.g. Read, Edit, Write, Glob, Grep, etc.)
Bash commands that are documented in this file and in README.md
Other bash commands

Examples of what to avoid:

❌
```
cat file.txt
```
→ ✅ Use Read tool
❌
```
grep pattern file.txt
```
→ ✅ Use Grep tool
❌
```
echo content > file.txt
```
→ ✅ Use Write tool
❌
```
find . -name "*.js"
```
→ ✅ Use Glob tool

Abstain from using bash commands when you already have a built-in tool, every time you use a bash command that is not in allow-list, it needs approval and slows down the process.

Integration tests

Running all integration tests (takes ~10 minutes):

npm run it vertexai

Command accepts another argument which is a partial file name to filter tests,

for example

npm run it vertexai review

will run all tests that contain

review

in the file name.

Faster integration tests have

simple

suffix, which allows running a subset of tests quickly, this also helps with less intelligent models:

npm run it vertexai simple

Run multiple integration test patterns:

npm run it vertexai prCommand reviewCommand

Building and Testing

# Build the project
npm run build

# Run tests
npm test

# Run linting
npm run lint

# Auto-fix simple lint issues
npm run lint-n-fix

# Format code
npm run format

# Install globally for development
npm install -g ./

Release Notes

Release notes are stored in

assets/release-notes/

and follow a consistent format.

Writing Release Notes

When creating release notes for a new version:

File naming: Use the pattern
```
v{major}_{minor}_{patch}.md
```
(e.g.,
```
v1_1_0.md
```
)

Title format:

# v{major}.{minor}.{patch} {Brief Description}

Style: Keep language dry and factual, not excited or marketing-oriented

Structure

Release notes should include relevant sections:

New Features: Major functionality additions
Potentially Breaking Changes: Changes that might require user action
Bug Fixes: Resolved issues
Improvements: Refactoring, performance, architecture improvements
Maintenance: Dependency updates, minor fixes

Guidelines

Focus on user-facing changes and impacts
Omit internal implementation details like specific test counts or documentation updates unless relevant
Use concrete examples where helpful
For breaking changes, explain what users need to do
Reference examples:
```
v1_0_0.md
```
,
```
v1_0_2.md
```
,
```
v1_0_4.md
```
,
```
v1_0_5.md
```

Example Structure

# v1.1.0 Custom Tools

## New Features
- **Custom Tools Configuration:** Description of the feature...

## Potentially Breaking Changes
- Removed unused configuration property...

## Improvements
- Architectural changes that benefit users...

Codebase Architecture

Gaunt Sloth Assistant is a command line AI assistant for software developers, primarily focused on code reviews and question answering.

High-Level Structure

Commands: The CLI exposes dedicated commands for each workflow:
- ```
askCommand
```
  : Q&A against supplied files, diffs, or providers
- ```
reviewCommand
```
  : General diff reviews (stdin, files, providers)
- ```
prCommand
```
  : Review GitHub pull requests with optional requirements ingestion
- ```
chatCommand
```
  : Starts an interactive chat session (default command)
- ```
codeCommand
```
  : Interactive coding session with full workspace FS access
- ```
initCommand
```
  : Bootstraps
```
.gsloth.config.*
```
  for a chosen provider
Modules:
- ```
questionAnsweringModule
```
  : Builds prompts and orchestrates Q&A runs
- ```
reviewModule
```
  : Handles diff/pr reviews and requirement stitching
- ```
interactiveSessionModule
```
  : Powers chat/code sessions via
```
createInteractiveSession
```
LLM Providers: Via LangChain the tool works with:
- Anthropic (Claude), Google Vertex AI (Gemini), Google AI Studio, Groq
- DeepSeek, OpenAI & OpenAI-compatible (e.g., Inception, OpenRouter)
- xAI and any other provider configured through JS configs
Content Providers / Inputs:
- ```
file
```
  : Reads local project files
- ```
text
```
  : Passes literal strings/stdin
- ```
ghPrDiffProvider
```
  : Uses GitHub CLI to fetch PR diffs
- ```
ghIssueProvider
```
  : Pulls GitHub issue descriptions
- ```
jiraIssueProvider
```
  : Jira REST API (PAT)
- ```
jiraIssueLegacyProvider
```
  : Jira REST API v2 with legacy tokens

Configuration System

Configurations are stored in

.gsloth.config.js

.gsloth.config.json

, or

.gsloth.config.mjs

Guidelines are in
```
.gsloth.guidelines.md
```
Output files are saved to project root or
```
.gsloth/
```
directory if it exists
Environment variables can be used for API keys (e.g.,
```
ANTHROPIC_API_KEY
```
,
```
GROQ_API_KEY
```
)

Important Architectural Concepts

Command Pattern: Commands are separated into module and handler code
Provider Pattern: Abstract interfaces for fetching content
Configuration-driven: Heavy use of configuration files
Output Persistence: All outputs are saved to local files
Integration: GitHub CLI and Jira integration for PR reviews

Note: For development workflow, testing patterns, imports, and other development principles, refer to .gsloth.guidelines.md

Gaunt Sloth Assistant project guidelines

This file provides guidance to any AI coding agent (Claude Code, Cursor, etc.) working with this repository.

IMPORTANT: Always read and follow .gsloth.guidelines.md first for development principles, testing patterns, and workflow.

Tool Use

Precedence for your tool use:

Your built-in tools (e.g. Read, Edit, Write, Glob, Grep, etc.)
Bash commands that are documented in this file and in README.md
Other bash commands

Examples of what to avoid:

❌
```
cat file.txt
```
→ ✅ Use Read tool
❌
```
grep pattern file.txt
```
→ ✅ Use Grep tool
❌
```
echo content > file.txt
```
→ ✅ Use Write tool
❌
```
find . -name "*.js"
```
→ ✅ Use Glob tool

Abstain from using bash commands when you already have a built-in tool, every time you use a bash command that is not in allow-list, it needs approval and slows down the process.

Integration tests

Running all integration tests (takes ~10 minutes):

npm run it vertexai

Command accepts another argument which is a partial file name to filter tests,

for example

npm run it vertexai review

will run all tests that contain

review

in the file name.

Faster integration tests have

simple

suffix, which allows running a subset of tests quickly, this also helps with less intelligent models:

npm run it vertexai simple

Run multiple integration test patterns:

npm run it vertexai prCommand reviewCommand

Building and Testing

# Build the project
npm run build

# Run tests
npm test

# Run linting
npm run lint

# Auto-fix simple lint issues
npm run lint-n-fix

# Format code
npm run format

# Install globally for development
npm install -g ./

Release Notes

Release notes are stored in

assets/release-notes/

and follow a consistent format.

Writing Release Notes

When creating release notes for a new version:

File naming: Use the pattern
```
v{major}_{minor}_{patch}.md
```
(e.g.,
```
v1_1_0.md
```
)

Title format:

# v{major}.{minor}.{patch} {Brief Description}

Style: Keep language dry and factual, not excited or marketing-oriented

Structure

Release notes should include relevant sections:

New Features: Major functionality additions
Potentially Breaking Changes: Changes that might require user action
Bug Fixes: Resolved issues
Improvements: Refactoring, performance, architecture improvements
Maintenance: Dependency updates, minor fixes

Guidelines

Focus on user-facing changes and impacts
Omit internal implementation details like specific test counts or documentation updates unless relevant
Use concrete examples where helpful
For breaking changes, explain what users need to do
Reference examples:
```
v1_0_0.md
```
,
```
v1_0_2.md
```
,
```
v1_0_4.md
```
,
```
v1_0_5.md
```

Example Structure

# v1.1.0 Custom Tools

## New Features
- **Custom Tools Configuration:** Description of the feature...

## Potentially Breaking Changes
- Removed unused configuration property...

## Improvements
- Architectural changes that benefit users...

Codebase Architecture

Gaunt Sloth Assistant is a command line AI assistant for software developers, primarily focused on code reviews and question answering.

High-Level Structure

Commands: The CLI exposes dedicated commands for each workflow:
- ```
askCommand
```
  : Q&A against supplied files, diffs, or providers
- ```
reviewCommand
```
  : General diff reviews (stdin, files, providers)
- ```
prCommand
```
  : Review GitHub pull requests with optional requirements ingestion
- ```
chatCommand
```
  : Starts an interactive chat session (default command)
- ```
codeCommand
```
  : Interactive coding session with full workspace FS access
- ```
initCommand
```
  : Bootstraps
```
.gsloth.config.*
```
  for a chosen provider
Modules:
- ```
questionAnsweringModule
```
  : Builds prompts and orchestrates Q&A runs
- ```
reviewModule
```
  : Handles diff/pr reviews and requirement stitching
- ```
interactiveSessionModule
```
  : Powers chat/code sessions via
```
createInteractiveSession
```
LLM Providers: Via LangChain the tool works with:
- Anthropic (Claude), Google Vertex AI (Gemini), Google AI Studio, Groq
- DeepSeek, OpenAI & OpenAI-compatible (e.g., Inception, OpenRouter)
- xAI and any other provider configured through JS configs
Content Providers / Inputs:
- ```
file
```
  : Reads local project files
- ```
text
```
  : Passes literal strings/stdin
- ```
ghPrDiffProvider
```
  : Uses GitHub CLI to fetch PR diffs
- ```
ghIssueProvider
```
  : Pulls GitHub issue descriptions
- ```
jiraIssueProvider
```
  : Jira REST API (PAT)
- ```
jiraIssueLegacyProvider
```
  : Jira REST API v2 with legacy tokens

Configuration System

Configurations are stored in

.gsloth.config.js

.gsloth.config.json

, or

.gsloth.config.mjs

Guidelines are in
```
.gsloth.guidelines.md
```
Output files are saved to project root or
```
.gsloth/
```
directory if it exists
Environment variables can be used for API keys (e.g.,
```
ANTHROPIC_API_KEY
```
,
```
GROQ_API_KEY
```
)

Important Architectural Concepts

Command Pattern: Commands are separated into module and handler code
Provider Pattern: Abstract interfaces for fetching content
Configuration-driven: Heavy use of configuration files
Output Persistence: All outputs are saved to local files
Integration: GitHub CLI and Jira integration for PR reviews

Note: For development workflow, testing patterns, imports, and other development principles, refer to .gsloth.guidelines.md

Gaunt Sloth Assistant project guidelines

Gaunt Sloth Assistant project guidelines

Tool Use

Integration tests

Building and Testing

Release Notes

Writing Release Notes

Structure

Guidelines

Example Structure

Codebase Architecture

High-Level Structure

Configuration System

Important Architectural Concepts

Related Skills

Markdown Converter

Nano Banana Pro

1password

Gaunt Sloth Assistant project guidelines

Tool Use

Integration tests

Building and Testing

Release Notes

Writing Release Notes

Structure

Guidelines

Example Structure

Codebase Architecture

High-Level Structure

Configuration System

Important Architectural Concepts