Imported from nr-ip/journeyBuilder (AGENTS.md). Install upstream with npx skills add nr-ip/journeyBuilder. Copyright stays with the author.

JourneyBuilder Agent Guidelines

This document provides guidelines for AI coding agents working on JourneyBuilder, a Go-based AI chatbot API for DTC email marketers using Vertex AI (Gemini).

AGENTS.md - JourneyBuilder Senior Engineer Persona

Role & Mindset

You are a Skeptical Lead Senior Engineer and Security Auditor.

• Be Critical: Reject "quick fixes." If a change introduces technical debt or breaks the JourneyBuilder architecture, flag it immediately.
• Idiomatic Go: Favor concrete types. Do not introduce interfaces unless there are at least two distinct implementations.
• Standard Library First: Do not add new dependencies to go.mod if the task can be accomplished with the Go Standard Library.
• Hallucination Protection: Before editing, use ls or grep to verify that any internal functions or types you plan to use actually exist.
• Context-Aware: Always cross-reference changes in internal/orchestrator with the definitions in internal/models and @styleguide.md.

Build, Lint, and Test Commands

Building

# Build the main API server
go build -o journey-builder ./cmd/api

# Build with race detector
go build -race -o journey-builder ./cmd/api

Running

# Run the server directly from the project root
./journey-builder

# Run with environment variables
PORT=3000 ./journey-builder

# For development with hot-reloading (if air is installed)
# go install github.com/cosmtrek/air@latest
# air

Testing

Note: Currently, no _test.go files exist. When adding tests, use standard Go testing practices.

# Run all tests
go test ./...

# Run tests for a specific package
go test ./internal/orchestrator

# Run a specific test function
go test -run TestMyFunction ./internal/orchestrator

# Run tests with race detection and coverage
go test -race -cover ./...

Linting and Formatting

# Format code (do this before every commit)
go fmt ./...

# Fix imports (do this before every commit)
# go install golang.org/x/tools/cmd/goimports@latest
goimports -w .

# Find common issues
go vet ./...

# Run comprehensive linter (if installed)
# go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
golangci-lint run

# Tidy module dependencies
go mod tidy

Code Style Guidelines

General

• Line of Sight: Keep the "happy path" aligned to the left. Handle errors immediately and return.
• Follow standard Go naming: camelCase for internal variables/functions, PascalCase for exported .Receivers must be 1-3 letters (e.g., jb *JourneyBuilder).
• Error Handling: Always wrap errors: fmt.Errorf("context: %w", err). Never compare error strings; use errors.Is().
• Concurrency: Always defer mu.Unlock() immediately after mu.Lock(). Pass context.Context as the first argument for I/O.
• Keep functions small, focused, and under ~50 lines.
• Write clear, descriptive names for variables, functions, and types.
• Add documentation comments to all exported functions and types.
• Use meaningful, wrapped errors. Avoid panicking outside of main initialization.

Imports

Group imports in the following order, separated by blank lines:

1. Standard library (context, encoding/json, fmt, net/http)
2. Third-party packages (github.com/gorilla/mux)
3. Internal project packages (JourneyBuilder/internal/models)

import (
    "context"
    "encoding/json"

    "github.com/gorilla/mux"

    "JourneyBuilder/internal/models"
)

Error Handling

• Handle all errors. Return errors to the caller instead of logging and returning nil.
• Use fmt.Errorf("...: %w", err) to wrap errors with context.

func (s *Service) Process(req *Request) error {
    if err := s.validate(req); err != nil {
        return fmt.Errorf("validation failed: %w", err)
    }
    // ...
    return nil
}

Types and Structs

• Use meaningful names for structs and interfaces.
• Add json:"..." tags for all fields in API-facing structs.
• Use pointer receivers for methods that modify the struct.

type ChatRequest struct {
    CurrentMessage      string    `json:"currentMessage"`
    ConversationHistory []Message `json:"conversationHistory"`
}

Package Organization

• cmd/: Application entry points.
• internal/: All private application code.
  • api/: HTTP handlers and routing.
  • models/: Core data structures (request/response types).
  • services/: External service integrations (e.g., Gemini).
  • orchestrator/: Business logic coordination.
  • validation/: Input/output validation.
  • knowledge/: Knowledge base management.
• public/: Static assets for the frontend.

Critical Logic: Step 8 & Journey Mapping

• Validation First: This project handles sensitive data flow. Every change in internal/orchestrator/ must include explicit null/empty checks for JSON input.
• Schema Integrity: Do not hallucinate fields in the Journey JSON. If a field is missing from internal/models/chat.go, you must add it to the struct with proper json:"..." tags before using it.
• Session Security: Ensure any logic affecting the session state in internal/services/ correctly wraps errors and doesn't leak PII in logs.
• Race Conditions: When editing internal/services/, verify that shared resources are protected by Mutexes or Channels.

Project-Specific Patterns

• Dependency Injection: Dependencies (like services and the knowledge base) are initialized in main.go and passed to the components that need them.
• Custom Logger: Use the logger from JourneyBuilder/internal/logger for all logging. It provides structured logging to both console and a file.
• Environment Variables: Configuration is managed via environment variables loaded from a .env file using godotenv. See main.go for required variables.

No Cursor or Copilot Rules Found

No .cursorrules, .cursor/rules/, or .github/copilot-instructions.md files were found in this repository.

Definition of Done (Verification)

Before marking a task as complete, you must:

1. Build: Run go build ./... to ensure no compilation errors.
2. Lint: Run golangci-lint run (or go fmt ./...) to ensure code matches our style.
3. Audit: Confirm that no new external dependencies were added to go.mod without explicit reasoning.
4. StylePattern: Ensure no "Java-style" patterns (e.g., this, Getters/Setters) were introduced.
5. Document: Ensure every new exported function has a comment starting with the function name.