Goca CLI — AI Agent Skill

Description

Specialized skill for AI agents using Goca (Go Clean Architecture Code Generator). Provides complete command reference, workflow patterns, error tracing, and architecture rules based on the actual codebase.

Activate when: user mentions goca, Clean Architecture code generation, Go project scaffolding, or any goca subcommand.

Clean Architecture — Layer Map

Dependencies point inward — each layer only knows the layer below it:

HTTP Handler → UseCase Interface → Repository Interface → Domain Entity
   adapter        business logic       persistence          pure logic

Generated directories:

Violations to prevent:

• ❌ Handler imports concrete usecase types (must use interfaces)
• ❌ UseCase imports Handler or Repository concretes
• ❌ Domain imports anything outside internal/domain/

Complete Command Reference

Global flags (apply to all commands):

--no-color, --no-interactive, -q / --quiet, -v / --verbose

Code Generation Commands

Diagnostic & Utility Commands

Common Workflows

1. Full feature from scratch (recommended)

goca init myproject --module github.com/user/myproject
cd myproject
goca feature User --fields "Name:string,Email:string,Age:int"

Generates: entity + usecase + handler + repository + messages + DI + routes + main.go update.

2. Modular build (fine-grained control)

goca init myproject --module github.com/user/myproject
goca entity Product --fields "Name:string,Price:float64" --validation --timestamps
goca usecase Product --entity Product --operations "create,read,update,delete,list"
goca repository Product --database postgres --transactions
goca handler Product --type http --validation --swagger
goca messages Product --all
goca di --features "Product" --database postgres

3. Add feature to existing project

goca feature Order --fields "CustomerID:uint,Total:float64,Status:string"
# or manually:
goca entity Order --fields "..."
goca usecase Order --entity Order
goca repository Order --database postgres
goca handler Order --type http
goca messages Order --all
goca integrate --all  # auto-wires everything

4. TDD-first approach

goca interfaces User --all
# Now write tests against interfaces before implementation
goca entity User --fields "..."
goca usecase User --entity User
goca repository User --database postgres
goca handler User --type http

5. Add middleware

goca middleware api --types "cors,logging,recovery,request-id,rate-limit"

6. CI/CD setup

goca ci --provider github-actions --with-docker --with-deploy

7. Diagnose issues

goca doctor        # quick health check
goca analyze       # deep analysis (arch, security, quality, deps)
goca doctor --fix  # auto-create missing directories

8. After updating Goca

goca upgrade            # check config compatibility
goca upgrade --update   # write new version to .goca.yaml

Field Syntax

All --fields flags use the same format:

--fields "FieldName:Type,FieldName2:Type2"

Supported types (20): string, int, int8-int64, uint, uint8-uint64, uintptr, byte, rune, float32, float64, bool, time.Time, []byte, interface{}

Naming rules:

• Name regex: ^[A-Za-z][A-Za-z0-9]*$
• PascalCase for fields (e.g., Email, CreatedAt)
• Length: 1-50 characters per field name

Auto-generated fields:

• ID (uint, primary key, auto-increment) — always added
• CreatedAt, UpdatedAt (time.Time) — with --timestamps
• DeletedAt (gorm.DeletedAt) — with --soft-delete

Error Tracing & Debugging

Common errors and solutions

Debug workflow

goca doctor              # 1. Check project health
goca doctor --fix        # 2. Auto-fix missing dirs
goca analyze             # 3. Deep analysis
goca analyze --quality   # or just quality checks
goca analyze --security  # or just security checks
goca analyze --output json  # machine-readable output

Safety first (always available on generation commands)

goca feature User --fields "..." --dry-run    # preview without creating
goca feature User --fields "..." --force       # overwrite existing
goca feature User --fields "..." --backup      # backup before overwrite
goca feature User --fields "..." --dry-run --force --backup  # combine safely

Flag Reference by Command

goca feature <name> — Full feature generation

goca entity <name> — Domain entity

goca usecase <name> — Business logic

goca handler <entity> — Protocol adapter

goca repository <entity> — Persistence

goca di — Dependency injection

goca middleware <name> — HTTP middleware

Template System

Built-in templates (in cmd/templates.go):

• entityTemplate — Entity struct + validation + methods
• useCaseTemplate — Interface + service + DTOs
• repositoryTemplate — Interface + DB implementation
• handlerTemplate — HTTP handler with CRUD

Custom templates:

goca template init   # creates .goca/templates/ with defaults
goca template list   # shows available custom templates

Custom .tmpl / .tpl files override built-in templates.

Template functions available:

title, lower, upper, camel / toCamelCase, pascal / toPascalCase, snake / toSnakeCase, kebab / toKebabCase, plural / toPlural, singular / toSingular, join, split, contains, hasPrefix, hasSuffix, trimSpace, replace, replaceAll

MCP Integration (AI Tool Calling)

Goca can run as an MCP server for AI assistants:

goca mcp-server --print-config vscode   # VS Code config snippet
goca mcp-server --print-config claude   # Claude Desktop config
goca mcp-server --print-config cursor   # Cursor config
goca mcp-server --print-config zed      # Zed config

Available MCP tools (5 core + 11 utility):

Core generation tools (auto-adds --no-interactive):

• goca_feature — name, fields, database, validation, business_rules, handlers, integration_tests, mocks, dry_run, force
• goca_entity — name, fields, validation, business_rules, timestamps, soft_delete, tests, dry_run, force
• goca_usecase — name, fields, validation, dry_run, force
• goca_repository — name, database, dry_run, force
• goca_handler — name, type, validation, dry_run, force

Utility tools: goca_di, goca_integrate, goca_interfaces, goca_messages, goca_mocks, goca_init, goca_doctor, goca_upgrade, goca_ci, goca_middleware, goca_analyze

Quick Reference Card

Most common command patterns

# New project
goca init <name> -m <module>

# Quick full feature
goca feature <Name> -f "field:type,field2:type2" -d <db>

# Add to existing
goca entity <Name> -f "..."
goca integrate --all

# Validate
goca doctor && goca analyze

# Safety
<command> --dry-run        # preview
<command> --dry-run --force --backup  # safe overwrite preview

Naming conventions

• Entities: PascalCase (User, ProductOrder)
• Files: snake_case (user.go, product_order.go)
• Packages: lowercase (domain, usecase)

Database types available

postgres, postgres-json, mysql, mongodb, sqlite, sqlserver, elasticsearch, dynamodb

Handler types available

http, grpc, cli, worker, soap

Operations for usecase

create, read, update, delete, list