LMS Go - GitHub Workflow & Standards

Complete agentic workflow setup for production-ready Go backend development.

📋 Quick Start

Reference Agentic Workflow

Read agentic-workflow.md for complete pipeline overview.

Request a Feature

Describe your feature with execution mode:

**Feature**: Subscription with Invoice

**Execution Mode**: Full Autonomous

**Functional Requirements**:
- Users can subscribe to plans
- System generates invoices
- Invoice status tracked (pending, paid, overdue)

**Constraints**:
- Must support recurring billing (future)
- Must track payment history

The system will automatically:

1. Plan the implementation
2. Architect the design
3. Migrate the database
4. Implement the backend
5. Validate security
6. Generate tests (92%+ coverage)
7. Review code quality
8. Self-correct any issues

📁 Directory Structure

.github/
├── agentic-workflow.md      ← START HERE (phase definitions)
├── copilot-instructions.md  (core orchestration rules)
├── workflows/
│   └── ci.yml               (automated testing + security)
├── aw/                       (execution modes & workflows)
│   ├── execution-mode.md     (Plan/Generate/Autonomous)
│   ├── full-autonomous.md    (8-phase pipeline)
│   ├── self-correction.md    (validation loop)
│   └── ...
├── instructions/             (technical standards)
│   ├── architecture.md       (clean architecture rules)
│   ├── backend.md            (implementation patterns)
│   ├── database.md           (schema standards)
│   ├── security.md           (auth/validation/secrets)
│   ├── testing.md            (test requirements)
│   ├── go-standards.md       (Go conventions)
│   └── ...
├── agents/                   (agent role definitions)
│   ├── planner.md            (planning agent)
│   ├── architect.md          (architecture review)
│   ├── backend.md            (implementation)
│   ├── test.md               (test generation)
│   ├── security.md           (security validation)
│   ├── reviewer.md           (code quality)
│   └── ...
└── prompts/                  (request templates)
    ├── feature.md            (new features)
    ├── bugfix.md             (bug fixes)
    └── ...

🔄 Execution Modes

Plan Only

Scope definition without code generation.

• Use for: Requirements clarification, design decisions
• Output: Structured evolution plan
• Example: "What APIs needed for subscription?"

Plan + Generate

Design + full implementation (no tests/security review).

• Use for: Pre-approved features, low-risk additions
• Output: Ready-to-test code
• Example: "Add user profile endpoint"

Full Autonomous

Complete pipeline with security, tests, and review.

• Use for: Production features, critical systems
• Output: Production-ready implementation
• Guarantees: 92%+ test coverage, security validated, code reviewed

🧪 CI/CD Pipeline

Automatically enforces all standards:

Lint & Format      → Code Style Validation
    ↓
Tests & Coverage   → 92% Minimum Coverage Gate
    ↓
Architecture       → Clean Layer Validation
    ↓
Build              → Go Binary Compilation
    ↓
Security Scanning  → Gosec + SAST

Run locally:

make lint          # Run linters
make test          # Run tests with coverage
make coverage       # Generate coverage report
go build ./cmd/api-server  # Build binary

📐 Clean Architecture

Mandatory dependency flow:

Handler (HTTP) → Service (Logic) → Repository (Data) → Database

Violations detected in:

• Code review phase
• CI validation
• Self-correction loop

Layer Responsibilities

Handler:

• HTTP parsing only
• User authentication extraction
• Call service layer
• Return JSON responses

Service:

• Business logic & validation
• Orchestrate repositories
• Handle transactions
• Return structured responses

Repository:

• Database queries only
• Use parameterized statements
• Return domain models
• Handle not-found as nil

Domain:

• Pure data structures
• No framework imports
• Proper type tags (db, json)

🔒 Security Standards

All implementations must pass:

• Authentication: Proper JWT handling, context usage
• Authorization: RBAC middleware, ownership validation
• Input Validation: Service layer validation, no SQL injection
• Sensitive Data: No logs of passwords/tokens
• Error Handling: No internal details leaked to client

Enforced in Phase 5 (Security Agent).

✅ Testing Requirements

Minimum coverage: 92% (CI gate)

By Layer

Layer	Coverage	Type
Service	≥95%	Unit (mock repos)
Handler	≥90%	Integration (mock service)
Repository	≥80%	Unit (SQL validation)
Overall	≥92%	CI Gate

Test Files

internal/service/xyz_service_test.go       (unit tests)
internal/api/xyz_handler_test.go           (integration tests)

📝 Development Workflow

1. Develop Locally

# Start with feature request
# Include execution mode and requirements

# Implement according to plan
# Follow clean architecture
# Write tests as you code

make test          # Verify tests pass locally
make coverage      # Check coverage
make lint          # Check code style
go build ./cmd/api-server  # Ensure builds

2. Commit

git add .
git commit -m "feat|fix|refactor: description"

Pre-commit hooks validate:

• Code formatting
• Basic linting

3. Push & CI

git push origin feature-branch

CI automatically runs:

• Full linting & formatting
• Complete test suite (92% gate)
• Architecture validation
• Security scanning
• Build verification

4. Code Review

Human review validates:

• Architecture compliance
• Security review
• Performance assessment
• Test adequacy
• Documentation completeness

5. Merge

Merge to main only after:

• All CI checks pass
• Code review approved
• Coverage ≥92%
• No security issues

📚 Key Standards

Go Code

• Use int64 for IDs
• Use float64 for money
• Use time.Time for timestamps
• Use pointers for optional fields
• Accept context.Context as first parameter in service/repo

Database

• BIGSERIAL for PKs
• BIGINT with ON DELETE CASCADE for FKs
• Indexes on foreign keys and filters
• created_at / updated_at timestamps
• NOT NULL constraints where needed

APIs

• RESTful (POST create, GET read, PUT update, DELETE remove)
• Proper HTTP status codes (201, 400, 401, 403, 404, 500)
• Structured error responses
• Consistent request/response format

Error Handling

Use error package for domain errors:

return nil, errors.NewAppError("CODE", "message", 400)

Never:

• Return bare error strings
• Use http.StatusInternalServerError for validation
• Leak stack traces to client

🚀 Production Deployment

Code is production-ready when:

✓ All 8 phases complete (Full Autonomous) ✓ 92%+ test coverage ✓ 0 critical security issues
✓ Code review approved ✓ All CI checks passing

Then merge to main.

📖 Further Reading

• agentic-workflow.md - Complete phase definitions
• instructions/architecture.md - Clean architecture rules
• instructions/backend.md - Implementation patterns
• instructions/testing.md - Test standards
• instructions/security.md - Security requirements
• aw/execution-mode.md - Execution modes explained
• aw/self-correction.md - Validation loop details

❓ FAQ

Q: What if my PR fails CI?
A: Check the CI output. Usually: code formatting, test coverage, or lint issues. Fix and push again.

Q: How do I write tests first?
A: Good practice (TDD). Write test in xyz_test.go, implement service/handler to pass test, run make coverage.

Q: Can I skip security review?
A: Only in Plan + Generate mode. Full Autonomous always includes Phase 5 (Security Agent).

Q: What's the coverage gate?
A: 92% minimum. Check with make coverage. If below, add missing test cases.

Q: How do I run the full agentic pipeline?
A: Submit feature request with "Full Autonomous" mode. The system executes all 8 phases automatically.

---

Setup Date: February 18, 2026
Version: 1.0
Status: Production-Ready