developer

Developer Instructions

Guidelines, patterns, and standards for GitHub Agentic Workflows.

---

Code Organization Patterns

1. Create Functions Pattern (create_*.go)

One file per GitHub entity. Examples: create_issue.go, create_pull_request.go, create_discussion.go, create_code_scanning_alert.go, create_agent_task.go.

2. Engine Separation Pattern

Each AI engine in its own file; shared helpers in engine_helpers.go. Examples: copilot_engine.go, claude_engine.go, codex_engine.go, custom_engine.go.

3. Test Organization Pattern

Tests alongside implementation:

• Feature: feature.go + feature_test.go
• Integration: feature_integration_test.go
• Scenario: feature_scenario_test.go

File Creation Decision Tree

graph TD
    A[Need New Functionality?] --> B{Size > 200 lines?}
    B -->|Yes| C[Create New File]
    B -->|No| D{Related to Existing File?}
    D -->|Yes| E[Add to Existing File]
    D -->|No| C
    C --> F{Multiple Related Operations?}
    F -->|Yes| G[Use Create Pattern: create_*.go]
    F -->|No| H[Use Domain Pattern]
    E --> I{File > 1000 lines?}
    I -->|Yes| J[Consider Splitting]
    I -->|No| K[Keep in Same File]

File Size Guidelines

• Small (50-200 lines): Utilities, helpers, simple features
• Medium (200-500 lines): Domain-specific logic, focused features
• Large (500-1000 lines): Complex features, comprehensive implementations
• Very Large (1000+ lines): Consider splitting if not cohesive

---

Validation Architecture

Validates workflow configs before compilation. Centralized in validation.go, or domain-specific in dedicated files.

Workflow YAML → parser → validation (centralized + domain-specific) → compiler on pass, error report on fail.

Centralized Validation: pkg/workflow/validation.go

• validateExpressionSizes() — GitHub Actions expression size limits
• validateContainerImages() — Docker images accessible
• validateRuntimePackages() — runtime package deps
• validateGitHubActionsSchema() — GitHub Actions YAML schema
• validateNoDuplicateCacheIDs() — unique cache IDs
• validateSecretReferences() — secret reference syntax
• validateRepositoryFeatures() — repo capabilities (issues, discussions)