Initial commit

commands/new-crud.md

@@ -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.

commands/new-feature.md

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

commands/new-project.md

@@ -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)

commands/update-feature.md

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