zhongwei/gh-venturo-id-venturo-claude-plugins-venturo-go
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 09:04:41 +08:00
commit 4896c607da
9 changed files with 806 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

100
commands/add-adapter-impl.md Normal file
View File

@@ -0,0 +1,100 @@
---
description: Add new provider to existing service adapter
---
# Add Adapter Implementation
Add a new provider/implementation to an **existing service port** (e.g., add SendGrid to email service).
## When to Use
**Use this when:**
- A port interface already exists (e.g., `internal/domains/ports/email.go`)
- You want to add another provider option
**Don't use when:**
- Creating brand new service type → Use `/venturo-go:new-adapter`
## Workflow
### Phase 1: Auto-Discovery
Automatically scan `internal/domains/ports/` to show available services:
```
Found existing service ports:
1. email
- Interface: EmailAdapter
- Existing providers: gomail, async
Which service do you want to add a provider to?
```
### Phase 2: Provider Selection
Suggest common providers based on service type:
**Email**: SendGrid, AWS SES, Mailgun, Postmark, Resend, Brevo
**Storage**: AWS S3, GCS, Azure Blob, MinIO
**Payment**: Stripe, PayPal, Square, Razorpay
### Phase 3: Implementation
Execute these phases in order:
1. **Scan & Analyze** - `phases/add-adapter/01-scan-and-analyze.md`
2. **Create Adapter** - `phases/add-adapter/02-create-adapter.md`
3. **Update Initialization** - `phases/add-adapter/03-update-initialization.md`
4. **Update Configuration** - `phases/add-adapter/04-update-configuration.md`
5. **Code Quality** - `phases/shared/code-quality.md`
### Files Created
```
pkg/{service}/{provider}/
├── config.go
├── {provider}.adapter.go
├── errors.go
├── {provider}.adapter_test.go
└── README.md
```
### Files Updated
- `pkg/{service}/main.{service}.go` - Add provider case
- `internal/config/config.go` - Add config struct
- `.env.example` - Add environment variables
## Example
```
User: /venturo-go:add-adapter-impl
Claude: Scanning internal/domains/ports/...
Found: email (gomail, async), payment (stripe)
Which service?
User: email
Claude: Common email providers:
- SendGrid
- AWS SES
...
Which provider?
User: sendgrid
[Proceeds with implementation]
```
## Tips
- Always scan for existing ports first
- Implement ALL port interface methods
- Validate configuration in constructor
- Never log sensitive data (API keys)
- Keep adapters thin (no business logic)

146
commands/add-amqp.md Normal file
View File

@@ -0,0 +1,146 @@
---
description: Set up RabbitMQ async processing
---
# AMQP/Async Integration
Set up RabbitMQ asynchronous processing for background jobs and event-driven architecture.
## When to Use
**Use this when:**
- Async email sending (queue email operations)
- Event processing (handle domain events asynchronously)
- Background jobs (report generation, data import, long-running tasks)
- Webhooks (process incoming webhooks asynchronously)
- Notifications (push notifications, SMS in background)
- Data sync (synchronize data between services)
## Workflow
### Interactive Discovery
Ask these questions:
1. **Use case?** (Async Email, Event Processing, Background Jobs, Webhooks, Notifications, Data Sync, Other)
2. **Publisher feature?** (Which feature produces messages?)
3. **Consumer feature?**
- Same feature consumes own messages
- Different feature (specify)
- New dedicated worker feature (specify name)
4. **Operations to queue?** (operation name, trigger event, payload structure)
5. **Failure handling?** (retry count, dead letter queue, custom handling)
6. **Queue configuration?** (one queue or multiple queues per operation/priority)
7. **Performance requirements?** (messages per minute, max delay, concurrent consumers)
8. **RabbitMQ already configured?** (Check `pkg/queue/`, `.env`, `docker-compose.yml`)
Present complete plan before proceeding.
### Implementation Phases
Execute these 5 phases in order:
1. **Infrastructure Setup** - `phases/amqp/01-infrastructure.md`
2. **Publisher Implementation** - `phases/amqp/02-publisher.md`
3. **Consumer Implementation** - `phases/amqp/03-consumer.md`
4. **Application Integration** - `phases/amqp/04-integration.md`
5. **Code Quality** - `phases/shared/code-quality.md`
### Components Created
**Infrastructure:**
- `pkg/queue/rabbitmq.go` - Queue service package
- `internal/handler/amqp/consumers.go` - AMQP handler
- `docker-compose.yml` - RabbitMQ container
- `.env` - RabbitMQ configuration
**Publisher:**
- `features/{feature}/domain/dto/event.{entity}.go` - Event structs
- Service method integration for publishing
**Consumer:**
- `features/{consumer_feature}/amqp/consumer.{entity}.go` - Message consumer
- `features/{consumer_feature}/service/service.{entity}.go` - Processing logic
- `features/{consumer_feature}/main.{consumer_feature}.go` - Consumer module
## Common Queue Patterns
**One Queue Per Operation:**
```
Queue: user_welcome_email
Queue: order_confirmation_email
```
Use when: Different processing logic per operation
**One Queue With Event Types:**
```
Queue: email_queue
Events: user.welcome, order.confirmation
```
Use when: Shared processing infrastructure
**Priority Queues:**
```
Queue: high_priority_emails
Queue: low_priority_emails
```
Use when: Different SLAs for operations
**Fanout Pattern:**
```
Exchange: user_events (fanout)
Queues: email_queue, analytics_queue, audit_queue
```
Use when: Multiple consumers need same event
## Example
```
User: /venturo-go:add-amqp
Claude: What use case? (Async Email, Events, Jobs, Webhooks, Notifications...)
User: Async Email Sending
Claude: Which feature publishes messages?
User: user_management
Claude: Which feature consumes?
A) Same (user_management)
B) Different (specify)
C) New worker (specify name)
User: C) email_sender
Claude: What operations to queue?
User: Welcome email, password reset email, verification email
[Presents plan with queue names, events, error handling]
Claude: Checking RabbitMQ infrastructure... Not found.
I'll set up:
1. pkg/queue/ (RabbitMQ service)
2. Docker container
3. Publisher in user_management
4. Consumer in email_sender feature
Proceed?
[Executes phases]
```
## Tips
- Start simple (one queue, one consumer)
- Test locally with Docker
- Monitor queues via RabbitMQ Management UI (http://localhost:15672)
- Implement dead letter queue for failed messages
- Make consumers idempotent (handle duplicates)
- Log message processing
- Graceful shutdown (finish processing before exit)
- Keep messages small (reference data by ID)
- Version message schemas
- Use TLS in production

141
commands/add-endpoint.md Normal file
View File

@@ -0,0 +1,141 @@
---
description: Add lightweight endpoint without full entity infrastructure
---
# Add Endpoint/Handler
Add new HTTP endpoints to an existing feature **without creating full entity infrastructure**.
## When to Use
**Use this when:**
- Adding report/analytics endpoints (statistics, dashboards)
- Adding search/filter endpoints (advanced search, autocomplete)
- Adding action endpoints (approve, cancel, activate)
- Adding aggregation endpoints (totals, counts, summaries)
- Adding small entities without full CRUD (comments, tags, notes)
- Adding utility endpoints (export, import, validate)
**Don't use when:**
- Creating new feature → Use `/venturo-go:new-feature`
- Adding full entity with CRUD → Use `/venturo-go:add-entity`
## Workflow
### Interactive Discovery
Ask these questions:
1. **Which feature?** (List from `features/`)
2. **Endpoint type?** (Report, Search, Action, Aggregation, Utility, Small Entity, Custom)
3. **Specific endpoint?** (HTTP method + path, e.g., `GET /users/statistics`)
4. **Related to entity or feature-general?**
- Entity-specific (user statistics) → Add to existing handler
- Feature-general (dashboard) → Create new handler
- Operation-specific (bulk import) → Dedicated handler
5. **Operation/handler name?**
6. **Purpose?** (What data/action?)
7. **Input required?** (URL params, query params, body, headers)
8. **Return type?** (Single object, array, paginated list, success message, file)
9. **Business logic?** (queries, calculations, external calls)
10. **External services?** (email, storage, queue, cache)
11. **Authorization?** (public, authenticated, role-based, permission-based)
12. **New repository methods?** (queries, aggregations)
13. **Modifies data?** (read-only vs write operations)
Present plan and confirm before implementation.
### Implementation Phases
Execute these 8 phases:
1. **Create DTOs** - `phases/add-endpoint/01-create-dtos.md`
2. **Repository Methods** - `phases/add-endpoint/02-repository-methods.md`
3. **Service Methods** - `phases/add-endpoint/03-service-methods.md`
4. **HTTP Handlers** - `phases/add-endpoint/04-http-handlers.md`
5. **Register Routes** - `phases/add-endpoint/05-register-routes.md`
6. **Testing** - `phases/add-endpoint/06-testing.md`
7. **Code Quality** - `phases/shared/code-quality.md`
8. **Documentation** - `phases/shared/documentation.md`
## Common Endpoint Patterns
**Report/Analytics:**
```
GET /users/statistics?from_date=...&to_date=...
GET /dashboard/summary
```
- Query parameters for filters
- Aggregated data response
- Read-only, often cached
**Search/Filter:**
```
GET /products/search?q=keyword&category=...
POST /orders/advanced-filter
```
- Search criteria in query or body
- Paginated results
**Action/Command:**
```
POST /orders/:id/cancel
POST /users/:id/activate
```
- URL parameter for resource ID
- Body for action parameters
- Modifies state, idempotent
**Aggregation:**
```
GET /sales/totals?group_by=month
GET /inventory/summary
```
- Computed/derived data
- Grouping and filtering
**Utility:**
```
POST /users/export (returns file)
POST /products/import (accepts file)
```
- File upload/download
- Batch operations
## Example
```
User: /venturo-go:add-endpoint
Claude: Which feature?
User: user_management
Claude: Endpoint type?
User: Report/Analytics
Claude: Specific endpoint?
User: GET /users/statistics
Claude: Related to user entity or feature-general?
User: Entity-specific (user)
Claude: What data should statistics return?
User: Total users, active users, new registrations this month, users by role
[Presents plan, proceeds with phases]
```
## Tips
- Keep it focused (one endpoint = one responsibility)
- Reuse existing repository/service methods
- Validate input with binding tags
- Consider caching for expensive operations
- Think about performance and scale
- Apply proper authentication
- Test edge cases

128
commands/add-entity.md Normal file
View File

@@ -0,0 +1,128 @@
---
description: Add new entity with full CRUD to existing feature
---
# Add Entity and Routes
Add a new entity with complete CRUD operations to an **existing feature**.
## When to Use
**Use this when:**
- Adding new data entity to existing feature
- Need full CRUD infrastructure (Create, Read, Update, Delete, List)
- Example: Add `profile` entity to `user_management` feature
**Don't use when:**
- Creating new feature → Use `/venturo-go:new-feature`
- Adding lightweight endpoint only → Use `/venturo-go:add-endpoint`
## Workflow
### Interactive Discovery
Ask these questions:
1. **Which feature?** (List from `features/` directory)
2. **Entity name?** (singular, e.g., `product`, `order`, `profile`)
3. **Database table name?** (usually plural)
4. **Table exists?** (Yes = generate from schema, No = design schema)
5. **Entity fields?** (if designing new schema)
6. **Relationships?** (foreign keys, joins)
7. **HTTP operations?** (CRUD, batch, custom actions)
8. **Base URL path?** (e.g., `/products`, `/orders`)
9. **Authentication?** (public, authenticated, role-based, permission-based)
10. **Business rules?** (validation, state transitions, side effects)
11. **External services?** (email, storage, notifications)
Present plan and ask for confirmation.
### Implementation Phases
Execute these 9 phases in order:
1. **Migration** - `phases/new-entity/01-migration.md`
2. **Domain Entity** - `phases/new-entity/02-domain-entity.md`
3. **DTOs** - `phases/new-entity/03-dtos.md`
4. **Repository** - `phases/new-entity/04-repository.md`
5. **Service** - `phases/new-entity/05-service.md`
6. **HTTP Handler** - `phases/new-entity/06-handler.md`
7. **Routes & Errors** - `phases/new-entity/07-routes.md`
8. **Code Quality** - `phases/shared/code-quality.md`
9. **Documentation** - `phases/shared/documentation.md`
## Common Patterns
**Simple CRUD Entity:**
- Basic create, read, update, delete
- Example: Product, Category, Tag
**Entity with Relationships:**
- References other entities
- Example: Order (belongs to User)
**Entity with State Machine:**
- Status transitions + business rules
- Example: Order (draft → pending → confirmed → shipped)
**Entity with Soft Delete:**
- Uses GORM `DeletedAt` field
- Never permanently deleted
**Entity with Audit Trail:**
- Tracks `CreatedBy`, `UpdatedBy`
- Populated from auth context
## File Naming Conventions
- Entities: `entity.{entity}.go` (singular)
- DTOs: `request.{entity}.go`, `response.{entity}.go`
- Handlers: `http.{entity}.go`
- Repositories: `repo.{entity}.go`
- Services: `service.{entity}.go`
- Errors: `errors.{feature}.go` (shared)
## Example
```
User: /venturo-go:add-entity
Claude: Which feature?
- user_management
- email_sender
User: user_management
Claude: Entity name? (singular)
User: profile
Claude: Database table name?
User: user_profiles
Claude: Does table exist?
User: No
Claude: What fields?
User:
- bio: text
- avatar_url: string
- phone: string, unique
- user_id: uuid, foreign key
[Presents plan, proceeds with phases]
```
## Tips
- Start with database schema design
- Use code generation for standard CRUD: `make gen-crud`
- Follow naming conventions strictly
- Add validation tags to DTOs
- Use feature-specific errors
- Test incrementally
- Add database indexes for performance
- Apply proper authentication

119
commands/new-adapter.md Normal file
View File

@@ -0,0 +1,119 @@
---
description: Create new adapter/service type with port interface
---
# New Adapter Creation
Create a **brand new service type** with port interface and first adapter implementation.
## When to Use
**Use this when:**
- Creating first adapter for a service (e.g., first payment adapter with Stripe)
- No port interface exists yet in `internal/domains/ports/`
- Need complete service infrastructure (port + adapter + config + init)
**Already have port?** → Use `/venturo-go:add-adapter-impl`
## Workflow
### Interactive Discovery
Ask these questions:
1. **Adapter type** (Email, Storage, Queue, Cache, Search, Payment, Notification, Other)
2. **Specific provider** (e.g., "SendGrid", "AWS S3", "Stripe")
3. **Port interface exists?** (Check `internal/domains/ports/`)
4. **Core operations** (methods to implement)
5. **Configuration needed** (API keys, endpoints, regions)
6. **Async processing?** (RabbitMQ integration)
Present complete plan before implementation.
### Implementation Steps
1. **Create Port Interface** (if needed) - `internal/domains/ports/{service}.go`
2. **Create Adapter Package** - `pkg/{service}/{provider}/`
3. **Adapter Configuration** - `config.go`
4. **Implement Adapter** - `adapter.go`
5. **Error Handling** - `errors.go`
6. **Main Config Update** - `internal/config/config.go`
7. **Environment Variables** - `.env.example`
8. **Initialization Function** - `pkg/{service}/main.{service}.go`
9. **Application Integration** - `cmd/api/main.go`
10. **Write Tests** - `adapter_test.go`, `integration_test.go`
11. **Documentation** - `README.md`
12. **Optional Async** - AMQP wrapper (see `/venturo-go:add-amqp`)
### Common Port Patterns
**Email Port:**
```go
type EmailService interface {
SendEmail(to, subject, body string) error
SendHTMLEmail(to, subject, htmlBody string) error
}
```
**Storage Port:**
```go
type StorageService interface {
UploadFile(ctx context.Context, path string, data io.Reader) (string, error)
DownloadFile(ctx context.Context, path string) (io.ReadCloser, error)
DeleteFile(ctx context.Context, path string) error
}
```
**Payment Port:**
```go
type PaymentService interface {
CreatePayment(ctx context.Context, amount int64, currency string) (*PaymentResult, error)
RefundPayment(ctx context.Context, paymentID string) error
}
```
## Adapter Patterns
**HTTP API-Based** (SendGrid, Mailgun, Stripe):
- Use `http.Client`
- Build requests with authentication headers
**SDK-Based** (AWS, Google Cloud):
- Use provider's official SDK client
- Initialize with credentials
**Connection Pool** (Redis, Database):
- Maintain connection pool
- Implement `Close()` method
## Example
```
User: /venturo-go:new-adapter
Claude: What type of adapter? (Email, Storage, Payment...)
User: Payment
Claude: Specific provider?
User: Stripe
Claude: Checking for payment port... Not found.
I'll create:
1. internal/domains/ports/payment.go (interface)
2. pkg/payment/stripe/ (adapter)
3. pkg/payment/main.payment.go (init)
[Proceeds with implementation]
```
## Tips
- Study existing adapters (`pkg/email/gomail/`)
- Follow port interface strictly
- Validate config early, fail fast
- Wrap provider errors with context
- Keep adapters thin
- Never log sensitive data

92
commands/new-feature.md Normal file
View File

@@ -0,0 +1,92 @@
---
description: Create complete feature with modular clean architecture
---
# New Feature Creation
You will guide the user through creating a complete Go backend feature using the Venturo skeleton's clean architecture pattern.
## Workflow
This command uses an **incremental 6-phase workflow** to create features step-by-step.
### Interactive Discovery
Ask the user these questions first:
1. **Feature name** (snake_case, e.g., `order_management`)
2. **Entities/sub-features** (e.g., orders, payments, shipments)
3. **Business purpose** (brief description)
4. **Database schema** (existing tables or design help needed?)
5. **External services** (email, storage, payment, etc.)
6. **Async processing needed?** (RabbitMQ integration?)
7. **HTTP endpoints** (CRUD operations, custom actions)
Present a complete plan and ask for confirmation before proceeding.
### Implementation Phases
After confirmation, execute these phases sequentially (read each phase file when needed):
1. **Planning & Migration** - `phases/new-feature/01-planning-and-migration.md`
2. **Domain Layer** - `phases/new-feature/02-domain-layer.md`
3. **Repository Layer** - `phases/new-feature/03-repository-layer.md`
4. **Service Layer** - `phases/new-feature/04-service-layer.md`
5. **HTTP Handler & Routes** - `phases/new-feature/05-handler-and-routes.md`
6. **Documentation** - `phases/new-feature/06-documentation.md`
After each phase:
- Stop and report what was created
- Ask user to review
- Wait for "continue" before next phase
## Key Implementation Rules
**Error Handling:**
```go
// ✅ Correct
utils.ErrorResponse(c, http.StatusBadRequest, "Invalid request", err.Error())
// ❌ Wrong
utils.ErrorResponse(c, http.StatusBadRequest, "Invalid request", err)
```
**Middleware:**
```go
// ✅ Correct
{entity}Group.Use(middleware.JWTMiddleware(cfg))
```
**File Naming:**
- Entities: `entity.{entity}.go`
- DTOs: `request.{entity}.go`, `response.{entity}.go`
- Handlers: `http.{entity}.go`
- Repositories: `repo.{entity}.go`
- Services: `service.{entity}.go`
- Errors: `errors.{feature_name}.go`
## Frontend Integration
After completion, the generated OpenAPI YAML can be used with Claude AI to:
- Generate TypeScript interfaces
- Create API client functions
- Generate React hooks
- Create validation schemas
## Example Usage
```
User: /venturo-go:new-feature
Claude: I'll help you create a new feature. Let me ask some questions first:
1. What is the name of the feature you want to create?
User: product_catalog
Claude: 2. What entities/sub-features will this feature contain?
User: products, categories, reviews
[Continues through all questions, presents plan, executes phases]
```