personal-projects/leo-claude-mktplace
Template
0
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(marketplace): command consolidation + 8 new plugins (v8.1.0 → v9.0.0) [BREAKING]

Browse Source 
Phase 1b: Rename all ~94 commands across 12 plugins to /<noun> <action>
sub-command pattern. Git-flow consolidated from 8→5 commands (commit
variants absorbed into --push/--merge/--sync flags). Dispatch files,
name: frontmatter, and cross-reference updates for all plugins.

Phase 2: Design documents for 8 new plugins in docs/designs/.

Phase 3: Scaffold 8 new plugins — saas-api-platform, saas-db-migrate,
saas-react-platform, saas-test-pilot, data-seed, ops-release-manager,
ops-deploy-pipeline, debug-mcp. Each with plugin.json, commands, agents,
skills, README, and claude-md-integration. Marketplace grows from 12→20.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Leo Miranda
2026-02-06 14:52:11 -05:00
parent 5098422858
commit 2d51df7a42
321 changed files with 13582 additions and 1019 deletions
Download Patch File Download Diff File Expand all files Collapse all files

119
plugins/saas-db-migrate/skills/migration-safety.md Normal file
View File

@@ -0,0 +1,119 @@
---
name: migration-safety
description: Rules for detecting destructive operations, data loss risks, and long-running locks
---
# Migration Safety
## Purpose
Defines safety rules for analyzing database migrations. This skill is loaded by both the `migration-planner` (during generation) and `migration-auditor` (during validation) agents to ensure migrations do not cause data loss or operational issues.
---
## Destructive Operations
### FAIL-Level (Block Migration)
| Operation | Risk | Detection Pattern |
|-----------|------|-------------------|
| `DROP TABLE` | Complete data loss | `DROP TABLE` without preceding backup/export |
| `DROP COLUMN` | Column data loss | `DROP COLUMN` without verification step |
| `ALTER COLUMN` type narrowing | Data truncation | VARCHAR(N) to smaller N, INTEGER to SMALLINT |
| `ALTER COLUMN` SET NOT NULL | Failure if NULLs exist | `SET NOT NULL` without DEFAULT or backfill |
| `TRUNCATE TABLE` | All rows deleted | `TRUNCATE` in migration file |
| `DELETE FROM` without WHERE | All rows deleted | `DELETE FROM table` without WHERE clause |
| Missing transaction | Partial migration risk | DDL statements outside BEGIN/COMMIT |
### WARN-Level (Report, Continue)
| Operation | Risk | Detection Pattern |
|-----------|------|-------------------|
| `RENAME TABLE` | App code must update | `ALTER TABLE ... RENAME TO` |
| `RENAME COLUMN` | App code must update | `ALTER TABLE ... RENAME COLUMN` |
| `ALTER COLUMN` type widening | Usually safe but verify | INTEGER to BIGINT, VARCHAR to TEXT |
| `CREATE INDEX` (non-concurrent) | Table lock during build | `CREATE INDEX` without `CONCURRENTLY` |
| Large table ALTER | Extended lock time | Any ALTER on tables with 100K+ rows |
| Mixed schema + data migration | Complex rollback | DML and DDL in same migration file |
| Missing downgrade/rollback | Cannot undo | No downgrade function or DOWN section |
### INFO-Level (Suggestions)
| Operation | Suggestion | Detection Pattern |
|-----------|-----------|-------------------|
| No-op migration | Remove or document why | Empty upgrade function |
| Missing IF EXISTS/IF NOT EXISTS | Add for idempotency | `CREATE TABLE` without `IF NOT EXISTS` |
| Non-concurrent index on PostgreSQL | Use CONCURRENTLY | `CREATE INDEX` could be `CREATE INDEX CONCURRENTLY` |
---
## Lock Duration Rules
### PostgreSQL
| Operation | Lock Type | Duration |
|-----------|-----------|----------|
| ADD COLUMN (no default) | ACCESS EXCLUSIVE | Instant (metadata only) |
| ADD COLUMN with DEFAULT | ACCESS EXCLUSIVE | Instant (PG 11+) |
| ALTER COLUMN TYPE | ACCESS EXCLUSIVE | Full table rewrite |
| DROP COLUMN | ACCESS EXCLUSIVE | Instant (metadata only) |
| CREATE INDEX | SHARE | Proportional to table size |
| CREATE INDEX CONCURRENTLY | SHARE UPDATE EXCLUSIVE | Longer but non-blocking |
| ADD CONSTRAINT (CHECK) | ACCESS EXCLUSIVE | Scans entire table |
| ADD CONSTRAINT NOT VALID + VALIDATE | Split: instant + non-blocking | Recommended for large tables |
### MySQL
| Operation | Lock Type | Duration |
|-----------|-----------|----------|
| Most ALTER TABLE | Table copy | Proportional to table size |
| ADD COLUMN (last position) | Instant (8.0+ some cases) | Depends on engine |
| CREATE INDEX | Table copy or instant | Engine-dependent |
---
## Recommended Patterns
### Safe Column Addition
```sql
-- Good: nullable column, no lock
ALTER TABLE users ADD COLUMN middle_name VARCHAR(100);
-- Then backfill in batches (separate migration):
UPDATE users SET middle_name = '' WHERE middle_name IS NULL;
-- Then add constraint (separate migration):
ALTER TABLE users ALTER COLUMN middle_name SET NOT NULL;
```
### Safe Column Removal
```sql
-- Step 1: Remove from application code first
-- Step 2: Verify column is unused (no queries reference it)
-- Step 3: Drop in migration
ALTER TABLE users DROP COLUMN IF EXISTS legacy_field;
```
### Safe Type Change
```sql
-- Step 1: Add new column
ALTER TABLE orders ADD COLUMN amount_new NUMERIC(10,2);
-- Step 2: Backfill (separate migration)
UPDATE orders SET amount_new = amount::NUMERIC(10,2);
-- Step 3: Swap columns (separate migration)
ALTER TABLE orders DROP COLUMN amount;
ALTER TABLE orders RENAME COLUMN amount_new TO amount;
```
---
## Pre-Migration Checklist
Before applying any migration in production:
1. Database backup completed and verified
2. Migration validated with `/db-migrate validate`
3. Execution plan reviewed with `/db-migrate plan`
4. Rollback strategy documented and tested
5. Maintenance window scheduled (if required by lock analysis)
6. Application deployment coordinated (if schema change affects code)

104
plugins/saas-db-migrate/skills/naming-conventions.md Normal file
View File

@@ -0,0 +1,104 @@
---
name: naming-conventions
description: Migration file naming rules — timestamp prefixes, descriptive suffixes, ordering
---
# Naming Conventions
## Purpose
Defines standard naming patterns for migration files across all supported tools. This skill ensures consistent, descriptive, and correctly ordered migration files.
---
## General Rules
1. **Use lowercase with underscores** for descriptions (snake_case)
2. **Be descriptive but concise**: Describe WHAT changes, not WHY
3. **Use verb prefixes**: `add_`, `drop_`, `rename_`, `alter_`, `create_`, `remove_`
4. **Include the table name** when the migration affects a single table
5. **Never use generic names** like `migration_1`, `update`, `fix`
---
## Tool-Specific Patterns
### Alembic
**Format:** `{revision_hash}_{description}.py`
The revision hash is auto-generated by Alembic. The description is provided by the user.
| Example | Description |
|---------|-------------|
| `a1b2c3d4_create_users_table.py` | Initial table creation |
| `e5f6g7h8_add_email_to_users.py` | Add column |
| `i9j0k1l2_drop_legacy_users_columns.py` | Remove columns |
| `m3n4o5p6_rename_orders_total_to_amount.py` | Rename column |
| `q7r8s9t0_add_index_on_orders_user_id.py` | Add index |
**Description rules for Alembic:**
- Max 60 characters for the description portion
- No spaces (use underscores)
- Alembic auto-generates the revision hash
### Prisma
**Format:** `{YYYYMMDDHHMMSS}_{description}/migration.sql`
| Example | Description |
|---------|-------------|
| `20240115120000_create_users_table/migration.sql` | Initial table |
| `20240120093000_add_email_to_users/migration.sql` | Add column |
| `20240201110000_add_orders_table/migration.sql` | New table |
**Description rules for Prisma:**
- Prisma generates the timestamp automatically with `prisma migrate dev`
- Description is the `--name` argument
- Use snake_case, no spaces
### Raw SQL
**Format:** `{NNN}_{description}.sql`
Sequential numbering with zero-padded prefix:
| Example | Description |
|---------|-------------|
| `001_create_users_table.sql` | First migration |
| `002_add_email_to_users.sql` | Second migration |
| `003_create_orders_table.sql` | Third migration |
**Numbering rules:**
- Zero-pad to 3 digits minimum (001, 002, ..., 999)
- If project exceeds 999, use 4 digits (0001, 0002, ...)
- Never reuse numbers, even for deleted migrations
- Gaps in sequence are acceptable (001, 002, 005 is fine)
---
## Description Verb Prefixes
| Prefix | Use When |
|--------|----------|
| `create_` | New table |
| `add_` | New column, index, or constraint to existing table |
| `drop_` | Remove table |
| `remove_` | Remove column, index, or constraint |
| `rename_` | Rename table or column |
| `alter_` | Change column type or constraint |
| `backfill_` | Data-only migration (populate column values) |
| `merge_` | Combine tables or columns |
| `split_` | Separate table or column into multiple |
---
## Anti-Patterns
| Bad Name | Problem | Better Name |
|----------|---------|-------------|
| `migration_1.py` | Not descriptive | `create_users_table.py` |
| `update.sql` | Too vague | `add_status_to_orders.sql` |
| `fix_bug.py` | Describes why, not what | `alter_email_column_length.py` |
| `changes.sql` | Not descriptive | `add_index_on_users_email.sql` |
| `final_migration.py` | Nothing is ever final | `remove_deprecated_columns.py` |

94
plugins/saas-db-migrate/skills/orm-detection.md Normal file
View File

@@ -0,0 +1,94 @@
---
name: orm-detection
description: Detect Alembic, Prisma, or raw SQL migration tools and locate configuration files
---
# ORM Detection
## Purpose
Identify the database migration tool in use and map its configuration. This skill is loaded by the `migration-planner` agent during setup and migration generation to ensure tool-appropriate output.
---
## Detection Rules
### Alembic Detection
| Indicator | Location | Confidence |
|-----------|----------|------------|
| `alembic.ini` file | Project root | High |
| `alembic/` directory with `env.py` | Project root | High |
| `alembic/versions/` directory | Within alembic dir | High |
| `sqlalchemy` + `alembic` in requirements | `requirements.txt`, `pyproject.toml` | Medium |
| `from alembic import op` in Python files | `*.py` in versions dir | High |
**Alembic Configuration Files:**
- `alembic.ini` — Main config (database URL, migration directory)
- `alembic/env.py` — Migration environment (model imports, target metadata)
- `alembic/versions/` — Migration files directory
**Model Location:**
- Look for `Base = declarative_base()` or `class Base(DeclarativeBase)` in Python files
- Check `target_metadata` in `env.py` to find the models module
- Common locations: `app/models/`, `models/`, `src/models/`
### Prisma Detection
| Indicator | Location | Confidence |
|-----------|----------|------------|
| `prisma/schema.prisma` file | Project root | High |
| `@prisma/client` in package.json | `package.json` | High |
| `prisma/migrations/` directory | Within prisma dir | High |
| `npx prisma` in scripts | `package.json` scripts | Medium |
**Prisma Configuration Files:**
- `prisma/schema.prisma` — Schema definition (models, datasource, generator)
- `prisma/migrations/` — Migration directories (timestamp-named)
- `.env` — `DATABASE_URL` connection string
### Raw SQL Detection
| Indicator | Location | Confidence |
|-----------|----------|------------|
| `migrations/` dir with numbered `.sql` files | Project root | Medium |
| `flyway.conf` | Project root | High (Flyway) |
| `knexfile.js` or `knexfile.ts` | Project root | High (Knex) |
| `db/migrate/` directory | Project root | Medium (Rails-style) |
**Raw SQL Configuration:**
- Migration directory location
- Naming pattern (sequential numbers, timestamps)
- Tracking table name (if database-tracked)
---
## Database Connection Detection
Look for connection strings in this order:
1. `DATABASE_URL` environment variable
2. `.env` file in project root
3. `alembic.ini` `sqlalchemy.url` setting
4. `prisma/schema.prisma` `datasource` block
5. Application config files (`config.py`, `config.js`, `settings.py`)
**Database Type Detection:**
- `postgresql://` or `postgres://` — PostgreSQL
- `mysql://` — MySQL
- `sqlite:///` — SQLite
- `mongodb://` — MongoDB (not supported for SQL migrations)
---
## Version Detection
**Alembic**: Parse from `pip show alembic` or `requirements.txt` pin
**Prisma**: Parse from `package.json` `@prisma/client` version
**SQLAlchemy**: Parse from requirements; important for feature compatibility (1.4 vs 2.0 API)
---
## Ambiguous Projects
If multiple migration tools are detected (e.g., Alembic for backend + Prisma for a separate service), ask the user which one to target. Store selection in `.db-migrate.json`.

157
plugins/saas-db-migrate/skills/rollback-patterns.md Normal file
View File

@@ -0,0 +1,157 @@
---
name: rollback-patterns
description: Standard rollback generation patterns, reverse operations, and data backup strategies
---
# Rollback Patterns
## Purpose
Defines patterns for generating safe rollback migrations. This skill is loaded by the `migration-planner` agent when generating migrations (to include downgrade sections) and when creating explicit rollback plans.
---
## Reverse Operation Map
| Forward Operation | Reverse Operation | Data Preserved |
|-------------------|-------------------|----------------|
| CREATE TABLE | DROP TABLE | No (all data lost) |
| DROP TABLE | CREATE TABLE (empty) | No (must restore from backup) |
| ADD COLUMN | DROP COLUMN | No (column data lost) |
| DROP COLUMN | ADD COLUMN (nullable) | No (must restore from backup) |
| RENAME TABLE | RENAME TABLE (back) | Yes |
| RENAME COLUMN | RENAME COLUMN (back) | Yes |
| ADD INDEX | DROP INDEX | Yes (data unaffected) |
| DROP INDEX | CREATE INDEX | Yes (data unaffected) |
| ADD CONSTRAINT | DROP CONSTRAINT | Yes |
| DROP CONSTRAINT | ADD CONSTRAINT | Yes (if data still valid) |
| ALTER COLUMN TYPE | ALTER COLUMN TYPE (back) | Depends on conversion |
| INSERT rows | DELETE matching rows | Yes (if identifiable) |
| UPDATE rows | UPDATE with original values | Only if originals saved |
| DELETE rows | INSERT saved rows | Only if backed up |
---
## Rollback Classification
### Fully Reversible (Green)
Operations that can be undone with no data loss:
- RENAME operations (table, column)
- ADD/DROP INDEX
- ADD/DROP CONSTRAINT (when data satisfies constraint)
- ADD COLUMN (drop it in rollback)
### Partially Reversible (Yellow)
Operations where structure is restored but data is lost:
- CREATE TABLE (rollback = DROP TABLE; data lost)
- DROP COLUMN (rollback = ADD COLUMN; column data gone)
- ALTER COLUMN TYPE narrowing then widening (precision lost)
### Irreversible (Red)
Operations that cannot be meaningfully undone:
- DROP TABLE without backup (data permanently gone)
- TRUNCATE TABLE without backup
- DELETE without WHERE without backup
- Data transformation that loses information (e.g., hash, round)
---
## Backup Strategies
### Pre-Migration Table Backup
For migrations that will cause data loss, generate backup commands:
**PostgreSQL:**
```sql
-- Full table backup
CREATE TABLE _backup_users_20240115 AS SELECT * FROM users;
-- Column-only backup
CREATE TABLE _backup_users_email_20240115 AS
SELECT id, legacy_email FROM users;
```
**Export to file:**
```bash
pg_dump --table=users --column-inserts dbname > users_backup_20240115.sql
```
### Restoration Commands
Include restoration commands in rollback section:
```sql
-- Restore from backup table
INSERT INTO users (id, legacy_email)
SELECT id, legacy_email FROM _backup_users_email_20240115;
-- Clean up backup
DROP TABLE IF EXISTS _backup_users_email_20240115;
```
---
## Alembic Downgrade Patterns
```python
def downgrade():
# Reverse of upgrade, in opposite order
op.drop_index('ix_orders_user_id', table_name='orders')
op.drop_table('orders')
```
For complex downgrades with data restoration:
```python
def downgrade():
# Re-create dropped column
op.add_column('users', sa.Column('legacy_email', sa.String(255), nullable=True))
# Note: Data cannot be restored automatically
# Restore from backup: _backup_users_email_YYYYMMDD
```
---
## Prisma Rollback Patterns
Prisma does not have native downgrade support. Generate a new migration that reverses the operations:
```sql
-- Rollback: undo add_orders_table
DROP TABLE IF EXISTS "order_items";
DROP TABLE IF EXISTS "orders";
```
---
## Raw SQL Rollback Patterns
Always include DOWN section in migration files:
```sql
-- UP
CREATE TABLE orders (
id SERIAL PRIMARY KEY,
user_id INTEGER REFERENCES users(id),
total DECIMAL(10,2) NOT NULL
);
-- DOWN
DROP TABLE IF EXISTS orders;
```
---
## Point-of-No-Return Identification
Flag migrations that cross the point of no return:
1. **Data deletion without backup step**: Mark as irreversible
2. **Type narrowing that truncates data**: Data is permanently altered
3. **Hash/encrypt transformations**: Original values unrecoverable
4. **Aggregate/merge operations**: Individual records lost
When a migration includes irreversible operations, the rollback section must clearly state: "This migration cannot be fully rolled back. Data backup is required before applying."

56
plugins/saas-db-migrate/skills/visual-header.md Normal file
View File

@@ -0,0 +1,56 @@
---
name: visual-header
description: Standard header format for db-migrate commands and agents
---
# Visual Header
## Standard Format
Display at the start of every command execution:
```
+----------------------------------------------------------------------+
| DB-MIGRATE - [Command Name] |
+----------------------------------------------------------------------+
```
## Command Headers
| Command | Header Text |
|---------|-------------|
| db-migrate-setup | Setup Wizard |
| db-migrate-generate | Generate |
| db-migrate-validate | Validate |
| db-migrate-plan | Plan |
| db-migrate-history | History |
| db-migrate-rollback | Rollback |
## Summary Box Format
For completion summaries:
```
+============================================================+
| DB-MIGRATE [OPERATION] COMPLETE |
+============================================================+
| Component: [Status] |
| Component: [Status] |
+============================================================+
```
## Status Indicators
- Success: `[check]` or `Ready`
- Warning: `[!]` or `Partial`
- Failure: `[X]` or `Failed`
- New file: `[+]`
- Modified file: `[~]`
- Deleted file: `[-]`
## Risk Level Indicators
- LOW: Safe operation, no data loss risk
- MEDIUM: Reversible but requires attention
- HIGH: Potential data loss, backup required
- CRITICAL: Irreversible data loss, explicit approval required