zhongwei/gh-venturo-id-venturo-claude-plugins-venturo-planner
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:43 +08:00
commit 88bb1197e0
7 changed files with 543 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,12 @@
{
"name": "venturo-planner",
"description": "Database design and API contract planning tool - Generate ERD, DBML, and API contracts following audit standards",
"version": "1.0.0",
"author": {
"name": "Venturo",
"email": "dev@venturo.id"
},
"commands": [
"./commands"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# venturo-planner
Database design and API contract planning tool - Generate ERD, DBML, and API contracts following audit standards

115
commands/new-crud.md Normal file
View File

@@ -0,0 +1,115 @@
---
description: Quick CRUD entity design (simplified version of new-feature)
---
# New CRUD Entity Creation
You will guide the user through creating a simple CRUD entity with ERD, DBML, PostgreSQL migration, and standard API contract.
## Workflow
This command uses an **incremental 3-phase workflow** for quick CRUD entity creation.
### Interactive Discovery
Ask the user these questions first:
1. **Entity name** (singular, snake_case, e.g., `product`, `category`, `tag`)
2. **Attributes** with types:
- Attribute name
- Data type (VARCHAR, INT, DECIMAL, TEXT, TIMESTAMP, etc.)
- Length (for VARCHAR)
- Required or optional
- Unique constraint needed?
- Default value (if any)
3. **Soft delete needed?** (yes/no, default: yes)
4. **Common filters** (e.g., search by name, filter by status)
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. **Schema Generation** - `phases/new-crud/01-crud-schema.md` (ERD + DBML)
2. **PostgreSQL Migration** - `phases/new-crud/02-crud-migrations.md`
3. **API Contract** - `phases/new-crud/03-crud-api-contract.md` (Standard CRUD)
After each phase:
- Stop and report what was created
- Ask user to review
- Wait for "continue" before next phase
## Key Implementation Rules
**Database Standards:**
- Read `DATABASE_STANDARDS.md` before starting
- Apply all audit standards automatically
- UUID primary key (VARCHAR 40)
- 6 audit trail columns
- Standard indexes (deleted_at, unique constraints)
- NO foreign key constraints
**Standard CRUD Endpoints:**
```
GET /api/v1/{entity_plural} - List with pagination
GET /api/v1/{entity_plural}/{id} - Get by ID
POST /api/v1/{entity_plural} - Create
PUT /api/v1/{entity_plural}/{id} - Update
DELETE /api/v1/{entity_plural}/{id} - Soft delete
```
**File Naming:**
- ERD: `docs/database/erd/{entity_name}.mmd`
- DBML: `docs/database/dbml/{entity_name}.dbml`
- Migration: `docs/database/migrations/{timestamp}_add_{entity_name}.sql`
- API: `docs/api/contracts/{entity_name}.md`
## Example Usage
```
User: /venturo-planner:new-crud
Claude: I'll help you create a simple CRUD entity.
Let me ask some questions:
1. What is the entity name? (singular, snake_case)
User: tag
Claude: 2. What attributes should this entity have?
Please provide: name, type, length (if VARCHAR), required/optional, unique
User:
- name: VARCHAR(100), required, unique
- color: VARCHAR(7), optional (hex color code)
- description: TEXT, optional
Claude: 3. Should this entity support soft delete?
User: yes
Claude: 4. What filters should be available?
User: search by name
[Presents plan, executes phases]
```
## Output Files
- `docs/database/erd/{entity_name}.mmd` - Mermaid ERD
- `docs/database/dbml/{entity_name}.dbml` - DBML schema
- `docs/database/migrations/{timestamp}_add_{entity_name}.sql` - PostgreSQL migration
- `docs/api/contracts/{entity_name}.md` - Standard CRUD API contract
## Use Cases
Perfect for:
- Simple lookup tables (tags, categories, statuses)
- Reference data (countries, currencies)
- Configuration entities
- Small entities without complex relationships
For complex entities with multiple relationships, use `/venturo-planner:new-feature` instead.

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

@@ -0,0 +1,99 @@
---
description: Design a single feature with database schema and API endpoints
---
# New Feature Creation
You will guide the user through creating a complete feature design with ERD, DBML, PostgreSQL migration, and API contract.
## Workflow
This command uses an **incremental 4-phase workflow** to create feature documentation step-by-step.
### Interactive Discovery
Ask the user these questions first:
1. **Feature name** (snake_case, e.g., `product_catalog`, `order_management`)
2. **Entities in this feature** (e.g., products, categories, reviews)
3. **For each entity, ask:**
- Attributes with data types
- Required vs optional fields
- Unique constraints
- Relationships to other entities
4. **API endpoints needed** (CRUD, custom actions like approve, cancel, etc.)
5. **Filter/search requirements** (search by name, filter by status, etc.)
6. **Pagination needed?** (yes/no, default page size)
7. **Permissions required** (who can create, read, update, delete)
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. **ERD Generation** - `phases/new-feature/01-feature-erd.md`
2. **DBML Generation** - `phases/new-feature/02-feature-dbml.md`
3. **PostgreSQL Migration** - `phases/new-feature/03-feature-migrations.md`
4. **API Contract** - `phases/new-feature/04-feature-api-contract.md`
After each phase:
- Stop and report what was created
- Ask user to review
- Wait for "continue" before next phase
## Key Implementation Rules
**Database Standards:**
- Read `DATABASE_STANDARDS.md` before starting
- Validate table names (plural, snake_case, no prefixes)
- Validate column names (snake_case, proper foreign key format)
- Ensure all audit trail columns present
- UUID primary keys (VARCHAR 40)
- NO foreign key constraints (only indexes)
**File Naming:**
- ERD: `docs/database/erd/{feature_name}.mmd`
- DBML: `docs/database/dbml/{feature_name}.dbml`
- Migration: `docs/database/migrations/{timestamp}_{feature_name}.sql`
- API: `docs/api/contracts/{feature_name}.md`
## Example Usage
```
User: /venturo-planner:new-feature
Claude: I'll help you design a new feature with database schema and API endpoints.
Let me ask some questions first:
1. What is the name of the feature? (use snake_case)
User: product_catalog
Claude: 2. What entities will this feature contain?
User: products, categories, product_images
Claude: 3. Let's define the 'products' entity.
What attributes should it have?
User: name (required), description (optional), price (required), stock (required), category_id (required), is_active (required)
[Continues through all questions, presents plan, executes phases]
```
## Output Files
- `docs/database/erd/{feature_name}.mmd` - Mermaid ERD
- `docs/database/dbml/{feature_name}.dbml` - DBML schema
- `docs/database/migrations/{timestamp}_{feature_name}.sql` - PostgreSQL migration
- `docs/api/contracts/{feature_name}.md` - API contract
## Integration
After completion:
1. Use DBML and API contract as reference
2. Run `/venturo-go:new-feature` to generate backend
3. Backend generates OpenAPI YAML
4. Run `/venturo-react:new-feature` with OpenAPI to generate frontend

94
commands/new-project.md Normal file
View File

@@ -0,0 +1,94 @@
---
description: Initialize a new project with complete database design and API planning
---
# New Project Creation
You will guide the user through creating a complete project plan with database design (ERD, DBML, PostgreSQL) and API contracts for all features.
## Workflow
This command uses an **incremental 5-phase workflow** to create project documentation step-by-step.
### Interactive Discovery
Ask the user these questions first:
1. **Project name** (e.g., "E-Commerce Platform", "Inventory Management System")
2. **Project description** (brief business purpose)
3. **List of features/modules** (e.g., user_management, product_catalog, order_management, inventory)
4. **Authentication requirements** (JWT, OAuth, session-based, etc.)
5. **Common entities** (users, roles, permissions, etc.)
6. **Database type** (PostgreSQL recommended)
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. **Project Planning** - `phases/new-project/01-project-planning.md`
2. **ERD Generation** - `phases/new-project/02-project-erd.md`
3. **DBML Generation** - `phases/new-project/03-project-dbml.md`
4. **PostgreSQL Migrations** - `phases/new-project/04-project-migrations.md`
5. **API Contracts** - `phases/new-project/05-project-api-contract.md`
After each phase:
- Stop and report what was created
- Ask user to review
- Wait for "continue" before next phase
## Key Implementation Rules
**Database Standards:**
- Read `DATABASE_STANDARDS.md` before starting
- Enforce all audit standards
- UUID primary keys (VARCHAR 40)
- 6 audit trail columns required
- NO foreign key constraints
- Proper indexing
**File Naming:**
- ERD: `docs/database/erd/project-overview.mmd`
- DBML: `docs/database/dbml/project-schema.dbml`
- Migrations: `docs/database/migrations/{timestamp}_initial_schema.sql`
- API: `docs/api/contracts/project-api.md`
## Example Usage
```
User: /venturo-planner:new-project
Claude: I'll help you create a new project plan with complete database design and API contracts.
Let me ask some questions first:
1. What is the name of your project?
User: E-Commerce Platform
Claude: 2. What is the business purpose of this project?
User: Online marketplace for selling products with inventory management
Claude: 3. What features/modules will this project have?
(e.g., user_management, product_catalog, order_management)
User: user_management, product_catalog, order_management, inventory, payments
[Continues through all questions, presents plan, executes phases]
```
## Output Files
- `docs/database/erd/project-overview.mmd` - Complete project ERD
- `docs/database/dbml/project-schema.dbml` - Complete DBML schema
- `docs/database/migrations/{timestamp}_initial_schema.sql` - PostgreSQL migration
- `docs/api/contracts/project-api.md` - Complete API contract
- Individual files per feature
## Integration
After completion, the generated documentation can be used with:
- `venturo-go` - For backend implementation
- `venturo-react` - For frontend implementation (via OpenAPI from backend)

163
commands/update-feature.md Normal file
View File

@@ -0,0 +1,163 @@
---
description: Update an existing feature design with schema and API changes
---
# Update Feature
You will guide the user through updating an existing feature design, regenerating ERD, DBML, PostgreSQL migration, and API contract with changes.
## Workflow
This command uses an **incremental 5-phase workflow** to update feature documentation.
### Interactive Discovery
Ask the user these questions first:
1. **Feature name** to update (snake_case, e.g., `product_catalog`)
2. **What needs to be updated?**
- Add new entities
- Modify existing entities (add/remove/change columns)
- Add/remove relationships
- Update API endpoints
- Change validation rules
3. **For entity changes, ask:**
- Which entity to modify?
- What columns to add/remove/modify?
- New relationships?
- Index changes?
4. **For API changes, ask:**
- New endpoints needed?
- Modified request/response schemas?
- New filters or parameters?
- Permission changes?
Present a complete change plan and ask for confirmation before proceeding.
### Implementation Phases
After confirmation, execute these phases sequentially (read each phase file when needed):
1. **Load Existing Design** - `phases/update-feature/01-load-existing.md`
2. **Update ERD** - `phases/update-feature/02-update-erd.md`
3. **Update DBML** - `phases/update-feature/03-update-dbml.md`
4. **Generate Migration** - `phases/update-feature/04-generate-migration.md`
5. **Update API Contract** - `phases/update-feature/05-update-api-contract.md`
After each phase:
- Stop and report what was updated
- Ask user to review
- Wait for "continue" before next phase
## Key Implementation Rules
**Database Standards:**
- Read `DATABASE_STANDARDS.md` before starting
- Maintain all audit standards
- UUID primary keys (VARCHAR 40)
- 6 audit trail columns required
- NO foreign key constraints
- Proper indexing
**Migration Strategy:**
- Create **new migration file** (don't modify existing)
- Use ALTER TABLE for schema changes
- Add new indexes as needed
- Include rollback instructions in comments
**File Naming:**
- ERD: `docs/database/erd/{feature_name}.mmd` (overwrite)
- DBML: `docs/database/dbml/{feature_name}.dbml` (overwrite)
- Migration: `docs/database/migrations/{timestamp}_update_{feature_name}.sql` (new file)
- API: `docs/api/contracts/{feature_name}.md` (overwrite)
## Example Usage
```
User: /venturo-planner:update-feature
Claude: I'll help you update an existing feature design.
1. Which feature do you want to update?
User: product_catalog
Claude: 2. What changes do you need to make?
- Add new entities
- Modify existing entities
- Update API endpoints
- Other
User: Add a new entity "product_reviews" and add a "rating" column to products
Claude: Let me confirm the changes:
**New Entity:**
- product_reviews (id, product_id, user_id, rating, comment, ...)
**Modified Entity:**
- products: add "average_rating" column (DECIMAL 3,2)
**New Relationships:**
- products ||--o{ product_reviews
- users ||--o{ product_reviews
Proceed with these changes?
[Continues through all phases]
```
## Output Files
- `docs/database/erd/{feature_name}.mmd` - **Updated** ERD
- `docs/database/dbml/{feature_name}.dbml` - **Updated** DBML
- `docs/database/migrations/{timestamp}_update_{feature_name}.sql` - **New** migration
- `docs/api/contracts/{feature_name}.md` - **Updated** API contract
## Important Notes
### Migration Strategy
**DO NOT modify existing migration files!** Always create a new migration:
```sql
-- Migration: 20250123170000_update_product_catalog.sql
-- Description: Add product_reviews table and average_rating to products
-- Add new table
CREATE TABLE IF NOT EXISTS product_reviews (...);
-- Modify existing table
ALTER TABLE products ADD COLUMN average_rating DECIMAL(3,2);
-- Add new indexes
CREATE INDEX idx_product_reviews_product_id ON product_reviews(product_id);
-- Rollback instructions (commented)
-- DROP TABLE product_reviews;
-- ALTER TABLE products DROP COLUMN average_rating;
```
### Backward Compatibility
Consider backward compatibility:
- Adding columns: Use NULL or DEFAULT values
- Removing columns: Mark as deprecated first
- Changing types: May require data migration
- API changes: Version endpoints if breaking changes
### Team Communication
After updating:
- Notify backend team of schema changes
- Notify frontend team of API changes
- Update both teams if breaking changes
- Frontend may need to re-verify against new OpenAPI
## Integration
After completion:
1. Backend team: Create new migration with `/venturo-go:new-migration`
2. Frontend team: Review API contract changes
3. Both teams: Test integration with updated schemas
4. Frontend: Re-verify against updated OpenAPI when backend completes

57
plugin.lock.json Normal file
View File

@@ -0,0 +1,57 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:venturo-id/venturo-claude:plugins/venturo-planner",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "57b405b0fd1ad2f4aed66669c70d77b8d11554eb",
"treeHash": "c207b38fec290781fffa56eccce2952a569f6ddfdfd2f2ef74f981d816f92c43",
"generatedAt": "2025-11-28T10:28:55.444870Z",
"toolVersion": "publish_plugins.py@0.2.0"
},
"origin": {
"remote": "git@github.com:zhongweili/42plugin-data.git",
"branch": "master",
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
},
"manifest": {
"name": "venturo-planner",
"description": "Database design and API contract planning tool - Generate ERD, DBML, and API contracts following audit standards",
"version": "1.0.0"
},
"content": {
"files": [
{
"path": "README.md",
"sha256": "f2b6ff9fe715a854edc6bd36054378da54226fd74360415d6a3d47549e3d3f0c"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "6e339614c3f4d4c519fa4698f23e32b6a662df27da710371eefca19bd1035ee3"
},
{
"path": "commands/new-feature.md",
"sha256": "d3085cac9ba692131aa4466db39b997afdf8e7ff35b854a7f87fe576335dcad1"
},
{
"path": "commands/new-crud.md",
"sha256": "60f72236ad7707a6d9f6d2d6176d5ebe123c60a2321991931b02c3e50d7e0ce3"
},
{
"path": "commands/new-project.md",
"sha256": "9873ed96f03b5fa51e47ba8a1bdf2eefc3cf57f43da901cc3bfa8a349b0833f4"
},
{
"path": "commands/update-feature.md",
"sha256": "2882b3a7ba97eef8c0ed0fb49db8f3ba71ed5b8a32c6e66b34abd935328af936"
}
],
"dirSha256": "c207b38fec290781fffa56eccce2952a569f6ddfdfd2f2ef74f981d816f92c43"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}