goplt/AGENTS.md

Agent Instructions for Go Platform Project

This document provides essential guidance for AI agents and developers working on the Go Platform project. Always consult the documentation before making changes or implementing features.

🚨 Critical Requirement

BEFORE making any code changes, architectural decisions, or implementing features, you MUST:

1. ✅ Review relevant documentation files
2. ✅ Check applicable architecture documents
3. ✅ Consult relevant Architecture Decision Records (ADRs)
4. ✅ Review the stories (epic-based implementation tasks)

Failure to follow these guidelines may result in code that doesn't align with the project's architecture, principles, or implementation plan.

---

📚 Documentation Structure

All documentation is located in /goplt/docs/content/. The project follows a structured documentation approach:

Core Documentation (/goplt/docs/content/)

• index.md: Main documentation index and navigation
• requirements.md: High-level architectural principles and requirements
• plan.md: Epic-based implementation plan with timelines and acceptance criteria
• playbook.md: Detailed implementation guide, best practices, and technical specifications

Architecture Documentation (/goplt/docs/content/architecture/)

• architecture.md: System architecture overview with diagrams
• architecture-modules.md: Module system design and integration patterns
• module-requirements.md: Detailed requirements for each module
• component-relationships.md: Component interactions and dependencies
• system-behavior.md: System behavior overview end-to-end
• service-orchestration.md: How services work together
• module-integration-patterns.md: How modules integrate with the platform
• operational-scenarios.md: Common operational flows and use cases
• data-flow-patterns.md: How data flows through the system

Architecture Decision Records (/goplt/docs/content/adr/)

All architectural decisions are documented in ADR files (ADR-0001 through ADR-0030+). These records explain:

• The context that led to the decision
• The decision itself
• The rationale and consequences
• Implementation notes

Key ADRs to review:

• ADR-0001: Go Module Path
• ADR-0003: Dependency Injection Framework
• ADR-0004: Configuration Management
• ADR-0005: Logging Framework
• ADR-0006: HTTP Framework
• ADR-0007: Project Directory Structure
• ADR-0008: Error Handling Strategy
• ADR-0013: Database ORM
• ADR-0016: OpenTelemetry Observability
• ADR-0017: JWT Token Strategy
• ADR-0021: Module Loading Strategy
• ADR-0022: Cache Implementation
• ADR-0023: Event Bus Implementation
• ADR-0025: Multitenancy Model
• ADR-0027: Rate Limiting Strategy
• ADR-0028: Testing Strategy
• ADR-0029: Microservices Architecture
• ADR-0030: Service Communication Strategy

Always check ADRs before making architectural decisions!

Implementation Stories (/goplt/docs/content/stories/)

The project is organized into 8 epics, each containing specific implementation stories:

• Epic 0: Project Setup & Foundation (epic0/)

  • 0.1: Project Initialization
  • 0.2: Configuration Management System
  • 0.3: Structured Logging System
  • 0.4: CI/CD Pipeline
  • 0.5: Dependency Injection and Bootstrap

• Epic 1: Core Kernel & Infrastructure (epic1/)

  • 1.1: Enhanced DI Container
  • 1.2: Database Layer
  • 1.3: Health & Metrics System
  • 1.4: Error Handling
  • 1.5: HTTP Server
  • 1.6: OpenTelemetry
  • 1.7: Service Abstraction Layer

• Epic 2: Authentication & Authorization (epic2/)

  • 2.1: JWT Authentication
  • 2.2: Identity Management
  • 2.3: RBAC System
  • 2.4: Role Management
  • 2.5: Audit Logging
  • 2.6: Database Seeding

• Epic 3: Module Framework (epic3/)

  • 3.1: Module System Interface
  • 3.2: Permission Code Generation
  • 3.3: Module Loader
  • 3.4: Module CLI
  • 3.5: Service Registry

• Epic 4: Sample Feature Module (epic4/)

  • 4.1: Blog Module

• Epic 5: Infrastructure Adapters (epic5/)

  • 5.1: Cache System
  • 5.2: Event Bus
  • 5.3: Blob Storage
  • 5.4: Email Notification
  • 5.5: Scheduler Jobs
  • 5.6: Secret Store
  • 5.7: gRPC Services

• Epic 6: Observability & Production Readiness (epic6/)

  • 6.1: Enhanced Observability
  • 6.2: Error Reporting
  • 6.3: Grafana Dashboards
  • 6.4: Rate Limiting
  • 6.5: Security Hardening
  • 6.6: Performance Optimization

• Epic 7: Testing, Documentation & CI/CD (epic7/)

  • 7.1: Testing Suite
  • 7.2: Documentation
  • 7.3: CI/CD Enhancement
  • 7.4: Docker Deployment

• Epic 8: Advanced Features & Polish (epic8/)

Each story file contains:

• Goal: What needs to be accomplished
• Deliverables: Specific items to be created
• Acceptance Criteria: How to verify completion
• Implementation Notes: Technical guidance

Always review the relevant story before implementing a feature!

---

🔍 Workflow for Agents

When working on this project, follow this workflow:

0. Git Workflow (MANDATORY)

• ALWAYS create a new branch when working on a new feature, bug fix, or enhancement
  • Use descriptive branch names (e.g., feature/epic1-http-server, bugfix/auth-token-expiry, enhancement/rate-limiting)
  • Branch names should follow the pattern: {type}/{epic}-{short-description} or {type}/{story-id}-{short-description}
• ALWAYS create a commit after successfully implementing a feature that:
  • ✅ Builds successfully (make build passes)
  • ✅ Tests pass (make test passes)
  • ✅ Lint pass (make lint passes)
  • ✅ fmt-check pass (make fmt-check passes)
  • ✅ Meets all acceptance criteria from the story
• Commit messages should be clear and descriptive, referencing the story/epic when applicable
• Never commit directly to main branch

1. Understand the Task

• Read the user's request carefully
• Identify which epic/story the task relates to
• Determine if it's a new feature, bug fix, or enhancement

2. Consult Documentation (MANDATORY)

• Start with index.md to get oriented
• Read the relevant story from /goplt/docs/content/stories/epicX/
• Review architecture documents that relate to the feature
• Check ADRs for any architectural decisions that apply
• Review playbook.md for implementation patterns and best practices

3. Understand the Architecture

• Review the architecture overview (architecture/architecture.md)
• Check component relationships if integrating with existing systems
• Review module integration patterns if working on modules
• Understand data flow patterns if working on data processing

4. Check ADRs

• Search for ADRs related to your task
• Ensure your implementation aligns with documented decisions
• If you need to make a new architectural decision, document it in a new ADR

5. Implement According to Stories

• Follow the deliverables specified in the story
• Meet the acceptance criteria
• Use the implementation notes as guidance
• Follow the patterns established in playbook.md
• Implement tests

6. Verify Alignment

• Ensure code follows Clean/Hexagonal Architecture principles
• Verify it aligns with microservices architecture
• Check that it follows plugin-first design
• Confirm security-by-design principles are followed
• Validate observability is properly implemented

7. Commit Changes

• ALWAYS commit after successful implementation
• Ensure the code builds (go build)
• Ensure all tests pass (go test)
• Ensure there are no linter issues (make lint)
• Ensure there are no fmt issues (make fmt-check)
• Verify all acceptance criteria are met
• Write a clear, descriptive commit message

---

🏗️ Key Architectural Principles

The project follows these core principles (documented in requirements.md and playbook.md):

1. Clean/Hexagonal Architecture

   • Clear separation between pkg/ (interfaces) and internal/ (implementations)
   • Domain code in internal/domain
   • Only interfaces exported from pkg/

2. Microservices Architecture

   • Each module is an independent service from day one
   • Services communicate via gRPC/HTTP
   • Service discovery via service registry

3. Plugin-First Design

   • Extensible architecture supporting static and dynamic modules
   • Modules implement the IModule interface
   • Module loader discovers and loads modules

4. Security-by-Design

   • JWT authentication
   • RBAC/ABAC authorization
   • Audit logging
   • Context-based user propagation

5. Observability

   • OpenTelemetry integration
   • Structured logging (Zap)
   • Prometheus metrics
   • Request correlation IDs

6. Dependency Injection

   • Using uber-go/fx for lifecycle management
   • Constructor injection preferred
   • Service registry pattern

---

📋 Quick Reference Checklist

Before implementing any feature, verify:

• Created a new branch for the feature/bugfix/enhancement
• Read the relevant story from /goplt/docs/content/stories/epicX/
• Reviewed architecture documents in /goplt/docs/content/architecture/
• Checked applicable ADRs in /goplt/docs/content/adr/
• Consulted playbook.md for implementation patterns
• Understood the epic context and dependencies
• Verified acceptance criteria are clear
• Confirmed architectural alignment

After implementing a feature, verify:

• Code builds successfully (go build)
• All tests pass (go test)
• All acceptance criteria are met
• Created a commit with a clear, descriptive message

---

🚫 Common Mistakes to Avoid

1. Working directly on main branch - Always create a feature branch before making changes
2. Committing without verification - Never commit code that doesn't build, has failing tests, or doesn't meet acceptance criteria
3. Implementing without checking stories - Stories contain specific deliverables and acceptance criteria
4. Ignoring ADRs - ADRs document why decisions were made; don't reinvent the wheel
5. Violating architecture principles - Code must follow Clean/Hexagonal Architecture
6. Missing acceptance criteria - All stories have specific criteria that must be met
7. Not following module patterns - Modules must implement the IModule interface correctly
8. Skipping observability - All features must include proper logging, metrics, and tracing
9. Breaking microservices boundaries - Services must communicate via defined interfaces

---

📖 Additional Resources

• MkDocs Configuration: /goplt/docs/mkdocs.yml - Documentation site configuration
• Docker Setup: /goplt/docs/Dockerfile and docker-compose.yml - Development environment
• Makefile: /goplt/Makefile - Build and development commands
• Story Generator: /goplt/docs/content/stories/generate_tasks.py - Tool for generating story templates

---

💡 Tips for Agents

1. Use semantic search to find relevant documentation when you're unsure
2. Read multiple related files to get complete context
3. Check the epic README files (epicX/README.md) for epic-level overviews
4. Review COMPLETE_TASK_LIST.md for a comprehensive task overview
5. When in doubt, ask for clarification rather than making assumptions

---

📝 Documentation Updates

If you make architectural decisions or significant changes:

1. Update relevant ADRs or create new ones
2. Update architecture documents if structure changes
3. Update stories if implementation details change
4. Keep documentation in sync with code
5. Do not use any emojis

---

Remember: Documentation is the source of truth. Always consult it before making changes!