go-modularization

Enforces flat hexagonal architecture and dependency direction for Go project layouts.

Updated May 5, 2026
One-click install
npx skills add https://github.com/trypanic/skills --skill go-modularization
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: go-modularization
Source: https://github.com/trypanic/skills/tree/main/go-modularization
Command: npx skills add https://github.com/trypanic/skills --skill go-modularization

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve?

Go monorepos and single-service repositories often suffer from inconsistent folder layouts, layering violations, and ambiguous file placement that slow down development and review. This Skill eliminates that ambiguity by providing opinionated, deterministic rules for where every type of Go source file, adapter, migration, and shared package belongs.

Core Features & Use Cases

  • Flat Hexagonal Architecture: Enforces dependency direction between inner layers (domain, interactor, ports, coordinator) and outer adapters (api, consumer, cli, data_repositories, external_services, producer, storage, grpc/ws/sse).
  • Promotion Thresholds & Naming: Governs when to promote suffixed files to subfolders (bounded contexts, API versions, middleware, external providers) and forbids combined-context or reserved folder names.
  • Validation & Migration: Includes an arch-checks gate script for CI, plus an incremental migration guide for adopting the convention in existing brownfield codebases.

Quick Start

Use the go-modularization skill to determine the correct destination folder and filename for a new Go source file in your service's internal directory.

Frequently Asked Questions about go-modularization

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I enforce a consistent Go monorepo folder layout across multiple services?

You can enforce a consistent Go monorepo folder layout by applying a flat hexagonal architecture with strict dependency direction rules. This approach governs where source files, adapters, and shared packages belong across bounded contexts and service boundaries.

What is the best way to organize Go source files using hexagonal architecture?

Organizing Go source files with hexagonal architecture involves separating inner layers like domain, interactor, ports, and coordinator from outer adapters such as api, consumer, cli, and data repositories. This enforces strict dependency direction between layers.

How do I validate Go project architecture rules in CI pipelines?

Validating Go project architecture rules in CI pipelines uses an arch-checks gate script to enforce module topology rules, promotion thresholds, and forbidden name validation. This prevents layering violations and ambiguous file placement from merging into the repository.

Can I apply strict architecture rules to an existing brownfield Go codebase?

Yes, you can apply strict architecture rules to an existing brownfield Go codebase by following an incremental migration guide. This helps adopt folder layout conventions and dependency direction rules without requiring a complete rewrite.

When do I need to promote Go source files into subfolders in a monorepo?

You need to promote Go source files into subfolders based on promotion threshold counting rules. This governs when to move suffixed files into bounded contexts, API versions, middleware, or external provider directories to maintain code organization.

Why does my Go monorepo have layering violations and ambiguous file placement?

Go monorepos suffer from layering violations and ambiguous file placement when lacking deterministic rules for source file, adapter, and migration locations. Applying opinionated folder layout conventions and CI-gated architecture validation eliminates this ambiguity.