goca-helper-skill

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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:

| Layer | Path | Depends On |
|-------|------|------------|
| Domain | `internal/domain/` | Nothing (pure Go) |
| UseCase | `internal/usecase/` | Domain + Repository interfaces |
| Repository | `internal/repository/` | Domain |
| Handler | `internal/handler/` | UseCase interfaces |
| DI | `internal/di/` | All layers (wires concretes) |
| Messages | `internal/messages/` | Nothing |
| Interfaces | `internal/interfaces/` | Nothing (contracts only) |
| Middleware | `internal/middleware/` | Nothing |

**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

| Command | Args | Required Flags | When to Use |
|---------|------|----------------|-------------|
| `goca init <name>` | 0-1 | `--module` | **Scaffold new project** from scratch. Creates full Clean Architecture structure. |
| `goca feature <name>` | Exactly 1 | `--fields "field:type"` | **Generate ALL layers at once** (entity + usecase + handler + repository + messages + DI). Fastest path to a working feature. |
| `goca entity <name>` | Exactly 1 | `--fields "field:type"` | **Generate only the domain entity** with validation, business rules, seeds, tests. Use when you already have other layers or want fine-grained control. |
| `goca usecase <name>` | Exactly 1 | `--entity <name>` | **Generate business logic** (DTOs + service + interface). Requires existing entity. |
| `goca handler <entity>` | Exactly 1 | (none) | **Generate protocol adapter** (HTTP, gRPC, CLI, Worker). Requires existing usecase. |
| `goca repository <entity>` | Exactly 1 | (none) | **Generate persistence layer** (interface + DB-specific impl). Choose from 8 databases. |
| `goca messages <entity>` | Exactly 1 | (none) | **Generate error + response constants** per feature. |
| `goca di` | None | `--features` | **Generate or update DI container** (manual or Google Wire). |
| `goca interfaces <entity>` | Exactly 1 | (none) | **Generate layer contracts only** — ideal for TDD approach. |
| `goca middleware <name>` | Exactly 1 | (none) | **Generate HTTP middleware** (cors, logging, auth, rate-limit, recovery, request-id, timeout). |

### Diagnostic & Utility Commands

| Command | Args | When to Use |
|---------|------|-------------|
| `goca doctor` | None | **Health check** — verifies go.mod, .goca.yaml, dirs, go build, go vet, DI container. Always run first when something is wrong. |
| `goca analyze` | None | **Deep self-analysis** — checks architecture, quality, security (OWASP), standards, tests, deps. Use after `doctor` passes. |
| `goca integrate` | None | **Auto-wire existing features** into DI + main.go. Use after manually creating entities/layers. |
| `goca upgrade` | None | **Check config version** against installed Goca. Use after updating goca binary. |
| `goca ci` | None | **Generate GitHub Actions** CI/CD pipeline. Use when setting up automation. |
| `goca template init\|list` | Varies | **Manage custom templates** — init creates template dir, list shows available. |
| `goca mcp-server` | None | **Start MCP server** for AI tools integration. Use `--print-config vscode\|claude\|cursor\|zed` to get client config. |
| `goca version` | None | **Show version** + build info. `--short` for just the number. |

---

## Common Workflows

### 1. Full feature from scratch (recommended)
```bash
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)
```bash
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
```bash
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
```bash
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
```bash
goca middleware api --types "cors,logging,recovery,request-id,rate-limit"
```

From sazardev/goca, MIT.

More from sazardev/goca