oh-my-customcode 0.44.4 → 0.44.6

package/README.md

@@ -13,7 +13,7 @@
 
 **[한국어 문서 (Korean)](./README_ko.md)**
 
-44 agents. 76 skills. 21 rules. One command.
+45 agents. 77 skills. 21 rules. One command.
 
 ```bash
 npm install -g oh-my-customcode && cd your-project && omcustom init
@@ -117,7 +117,7 @@ Agent(arch-documenter):haiku      ┘
 
 ---
 
-### Agents (44)
+### Agents (45)
 
 | Category | Count | Agents |
 |----------|-------|--------|
@@ -125,7 +125,7 @@ Agent(arch-documenter):haiku      ┘
 | Backend | 6 | be-fastapi, be-springboot, be-go-backend, be-express, be-nestjs, be-django |
 | Frontend | 4 | fe-vercel, fe-vuejs, fe-svelte, fe-flutter |
 | Data Engineering | 6 | de-airflow, de-dbt, de-spark, de-kafka, de-snowflake, de-pipeline |
-| Database | 3 | db-supabase, db-postgres, db-redis |
+| Database | 4 | db-supabase, db-postgres, db-redis, db-alembic |
 | Tooling | 3 | tool-npm, tool-optimizer, tool-bun |
 | Architecture | 2 | arch-documenter, arch-speckit |
 | Infrastructure | 2 | infra-docker, infra-aws |
@@ -138,11 +138,11 @@ Each agent declares its tools, model, memory scope, and limitations in YAML fron
 
 ---
 
-### Skills (76)
+### Skills (77)
 
 | Category | Count | Includes |
 |----------|-------|----------|
-| Best Practices | 23 | Go, Python, TypeScript, Kotlin, Rust, React, FastAPI, Spring Boot, Django, Flutter, Docker, AWS, Postgres, Redis, Kafka, dbt, Spark, Snowflake, Airflow, pipeline-architecture-patterns, and more |
+| Best Practices | 24 | Go, Python, TypeScript, Kotlin, Rust, React, FastAPI, Spring Boot, Django, Flutter, Docker, AWS, Postgres, Redis, Kafka, dbt, Spark, Snowflake, Airflow, pipeline-architecture-patterns, alembic, and more |
 | Routing | 4 | secretary, dev-lead, de-lead, qa-lead |
 | Workflow | 12 | structured-dev-cycle, deep-plan, research, evaluator-optimizer, dag-orchestration, worker-reviewer-pipeline, reasoning-sandwich, and more |
 | Development | 7 | dev-review, dev-refactor, analysis, create-agent, intent-detection, web-design-guidelines, omcustom-takeover |
@@ -215,7 +215,7 @@ Key rules: R010 (orchestrator never writes files), R009 (parallel execution mand
 
 ---
 
-### Guides (25)
+### Guides (26)
 
 Reference documentation covering best practices, architecture decisions, and integration patterns. Located in `guides/` at project root, covering topics from agent design to CI/CD to observability.
 
@@ -256,15 +256,15 @@ omcustom security              # Scan for security issues
 your-project/
 ├── CLAUDE.md                   # Entry point
 ├── .claude/
-│   ├── agents/                 # 44 agent definitions
-│   ├── skills/                 # 75 skill modules
+│   ├── agents/                 # 45 agent definitions
+│   ├── skills/                 # 77 skill modules
 │   ├── rules/                  # 21 governance rules (R000-R021)
 │   ├── hooks/                  # 15 lifecycle hook scripts
 │   ├── schemas/                # Tool input validation schemas
 │   ├── specs/                  # Extracted canonical specs
 │   ├── contexts/               # 4 shared context files
 │   └── ontology/               # Knowledge graph for RAG
-└── guides/                     # 25 reference documents
+└── guides/                     # 26 reference documents
 ```
 
 ---

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "oh-my-customcode",
   "workspaces": ["packages/*"],
-  "version": "0.44.4",
+  "version": "0.44.6",
   "description": "Batteries-included agent harness for Claude Code",
   "type": "module",
   "bin": {

package/templates/.claude/agents/db-alembic-expert.md

@@ -0,0 +1,72 @@
+---
+name: db-alembic-expert
+description: Alembic migration specialist for generating, reviewing, fixing, and advising on SQLAlchemy database migrations
+model: sonnet
+domain: backend
+memory: project
+effort: high
+tools:
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - Bash
+skills:
+  - alembic-best-practices
+  - postgres-best-practices
+escalation:
+  enabled: true
+  path: sonnet → opus
+  threshold: 2
+limitations:
+  - "cannot apply migrations directly to production databases"
+  - "cannot resolve application-level data backfill logic without domain context"
+  - "cannot detect rename intent without git diff context or explicit user instruction"
+---
+
+# db-alembic-expert
+
+Alembic migration lifecycle specialist. Generates, reviews, fixes, and advises on SQLAlchemy database migrations with a focus on safety, zero-downtime deployment, and PostgreSQL best practices.
+
+## Purpose
+
+Manage the complete Alembic migration lifecycle: autogenerate from SQLAlchemy models, review generated scripts for dangerous patterns, enforce naming conventions, configure env.py for async and multi-tenant setups, and integrate migrations into CI pipelines.
+
+## Key Capabilities
+
+1. **Migration Generation** — Run `alembic revision --autogenerate` and perform a post-generation safety review before any migration is committed
+2. **Dangerous Pattern Detection** — Identify rename-as-drop+add sequences, anonymous constraints, lock-risky operations (non-concurrent index creation, NOT NULL without server default on large tables), and missing downgrade paths
+3. **Expand-Contract Pattern** — Design and implement zero-downtime migrations across three phases: Expand (add nullable column), Migrate (backfill data), Contract (enforce NOT NULL, drop old column)
+4. **env.py Configuration** — Set up sync, async (asyncpg/asyncio), multi-tenant, and multi-database environments with proper connection URL handling and credential sourcing from environment variables
+5. **pytest-alembic Testing** — Configure built-in tests (single_head_revision, upgrade, model_match, up_down_consistency) and custom pre/post migration data checks
+6. **alembic-utils Integration** — Manage PostgreSQL-specific objects (views, functions, triggers, row-level security policies) as Replaceable Objects with proper dependency ordering
+7. **CI Integration** — Configure `alembic check` for pending-migration detection and Squawk linter for lock-risk DDL analysis in GitHub Actions or similar pipelines
+
+## Workflow
+
+```
+1. Read SQLAlchemy models and existing migration history
+2. Run autogenerate (or inspect provided migration script)
+3. Review generated ops against dangerous pattern checklist (alembic-best-practices)
+4. Flag any CRITICAL risks with explanation and safer alternatives
+5. Fix naming conventions, add missing downgrade logic, restructure if needed
+6. Advise on expand-contract phasing for breaking schema changes
+7. Recommend test coverage via pytest-alembic
+```
+
+## Safety Rules
+
+- **Never auto-fix column renames** without explicit user confirmation — autogenerate cannot distinguish rename from drop+add
+- **Always flag downgrade gaps** — `pass` in `downgrade()` is acceptable only when explicitly justified
+- **Never embed credentials** in `alembic.ini` or `env.py` — always source from `os.environ`
+- **Require CONCURRENTLY** for index operations on large tables to avoid table-level locks
+- **Validate naming_convention** is set on MetaData before generating constraint-related migrations
+
+## Collaboration
+
+| Agent | When to involve |
+|-------|----------------|
+| db-postgres-expert | PostgreSQL-specific DDL nuances, partitioning, JSONB patterns |
+| be-fastapi-expert | Async engine configuration, lifespan integration, dependency injection |
+| qa-engineer | Migration test strategy, rollback testing, data integrity checks |

package/templates/.claude/skills/alembic-best-practices/SKILL.md

@@ -0,0 +1,294 @@
+---
+name: alembic-best-practices
+description: Alembic migration patterns for naming conventions, safety checks, expand-contract, env.py configuration, and CI integration
+scope: core
+version: 1.0.0
+---
+
+# Alembic Best Practices
+
+Reference patterns for safe, maintainable Alembic database migrations.
+
+## 1. Naming Convention
+
+Always set `naming_convention` on `MetaData` before autogenerate runs. Without it, constraint names are database-generated and differ across engines, causing migration drift.
+
+```python
+from sqlalchemy import MetaData
+
+convention = {
+    "ix": "ix_%(column_0_label)s",
+    "uq": "uq_%(table_name)s_%(column_0_N_name)s",
+    "ck": "ck_%(table_name)s_%(constraint_name)s",
+    "fk": "fk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s",
+    "pk": "pk_%(table_name)s",
+}
+
+metadata = MetaData(naming_convention=convention)
+```
+
+Set `file_template` in `alembic.ini` for timestamp-prefixed filenames:
+
+```ini
+file_template = %%(year)d%%(month).2d%%(day).2d_%%(hour).2d%%(minute).2d_%%(rev)s_%%(slug)s
+```
+
+## 2. Credential Management
+
+**NEVER** store database credentials in `alembic.ini` or commit them to version control.
+
+Override `sqlalchemy.url` in `env.py` from environment variables:
+
+```python
+# env.py — override alembic.ini URL with environment variable
+import os
+from alembic import context
+
+config = context.config
+db_url = os.environ.get("DATABASE_URL")
+if db_url:
+    config.set_main_option("sqlalchemy.url", db_url)
+```
+
+For PostgreSQL + asyncpg, ensure the sync URL uses `postgresql+psycopg2` (or `postgresql`) for offline/sync contexts and `postgresql+asyncpg` only for async contexts.
+
+## 3. Autogenerate Trust Matrix
+
+Autogenerate is a starting point, not a final answer. Always review generated scripts.
+
+| Object / Change | Autogenerate Detects | Notes |
+|-----------------|----------------------|-------|
+| Table add/drop | Yes | Reliable |
+| Column add/drop | Yes | Reliable |
+| Column type change | Partial | Type equivalence varies by backend |
+| Column rename | **Never** | Generates drop+add — will destroy data |
+| Index add/drop | Yes | Only if reflected or declared |
+| Named constraint add/drop | Yes | Requires `naming_convention` on MetaData |
+| Anonymous constraint | **No** | No name = no detection |
+| Default value change | Partial | Server defaults vs client defaults differ |
+| PostgreSQL views / functions | **No** | Use alembic-utils |
+| PostgreSQL enum add value | Partial | Requires `alembic-postgresql-enum` |
+| Sequence changes | No | Manual op required |
+
+## 4. Dangerous Pattern Detection
+
+Review every generated migration against this checklist before committing:
+
+**CRITICAL — Review Required:**
+
+- [ ] `op.drop_column` + `op.add_column` on the same column name → likely unintended rename; confirm with user
+- [ ] `op.create_foreign_key(None, ...)` → anonymous FK; must have an explicit name
+- [ ] `op.add_column` with `nullable=False` and no `server_default` on a non-empty table → full-table rewrite, lock risk
+- [ ] `op.create_index` without `postgresql_concurrently=True` on a large table → table-level lock
+- [ ] `op.drop_table` or `op.drop_column` → confirm there are no application references
+- [ ] Empty `def downgrade(): pass` → document justification or implement rollback
+- [ ] `op.alter_column` type change across incompatible types (e.g., `VARCHAR` → `INTEGER`) → data loss risk
+
+**WARNING — Verify Intent:**
+
+- [ ] Multiple heads detected (`alembic heads` shows 2+) → merge before deploying
+- [ ] `batch_alter_table` missing for SQLite → required for constraint modifications on SQLite
+- [ ] `render_as_batch=True` not set in `env.py` for SQLite projects
+
+## 5. Expand-Contract Pattern
+
+For zero-downtime schema changes on live tables, use three separate migration phases:
+
+**Phase 1 — Expand** (deploy without application changes):
+```python
+def upgrade():
+    op.add_column("users", sa.Column("email_new", sa.String(255), nullable=True))
+
+def downgrade():
+    op.drop_column("users", "email_new")
+```
+
+**Phase 2 — Migrate** (data backfill, can run during deploy):
+```python
+def upgrade():
+    op.execute("""
+        UPDATE users SET email_new = email WHERE email_new IS NULL
+    """)
+
+def downgrade():
+    pass  # Data loss acceptable; backfill was additive
+```
+
+**Phase 3 — Contract** (after all application nodes use new column):
+```python
+def upgrade():
+    with op.batch_alter_table("users") as batch_op:
+        batch_op.alter_column("email_new", nullable=False)
+    op.drop_column("users", "email")
+    op.alter_column("users", "email_new", new_column_name="email")
+
+def downgrade():
+    op.add_column("users", sa.Column("email", sa.String(255), nullable=True))
+    op.execute("UPDATE users SET email = email_new WHERE email IS NULL")
+    op.drop_column("users", "email_new")
+```
+
+## 6. Async env.py
+
+Canonical pattern for async SQLAlchemy (asyncpg) with Alembic:
+
+```python
+# env.py — async configuration
+import asyncio
+from logging.config import fileConfig
+
+from sqlalchemy import pool
+from sqlalchemy.ext.asyncio import async_engine_from_config
+
+from alembic import context
+from myapp.models import Base  # Import all models here
+
+config = context.config
+fileConfig(config.config_file_name)
+target_metadata = Base.metadata
+
+
+def run_migrations_offline() -> None:
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def do_run_migrations(connection):
+    context.configure(connection=connection, target_metadata=target_metadata)
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+async def run_migrations_online() -> None:
+    connectable = async_engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,  # Required: avoids pool issues during migration
+    )
+    async with connectable.connect() as connection:
+        await connection.run_sync(do_run_migrations)
+    await connectable.dispose()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    asyncio.run(run_migrations_online())
+```
+
+Key points:
+- Use `NullPool` — migration scripts are one-shot; pooling causes connection leaks
+- Import ALL models in `env.py` (directly or via a central `models/__init__.py`) so autogenerate sees every table
+- `run_sync` bridges the async connection back to Alembic's sync API
+
+## 7. Testing with pytest-alembic
+
+Install: `pip install pytest-alembic`
+
+Built-in tests (all enabled by default):
+
+```python
+# conftest.py
+import pytest
+from sqlalchemy import create_engine
+from alembic.config import Config
+
+@pytest.fixture
+def alembic_config():
+    return Config("alembic.ini")
+
+@pytest.fixture
+def alembic_engine():
+    return create_engine("postgresql://test_user:test_pass@localhost/test_db")
+```
+
+Built-in test assertions:
+- `test_single_head_revision` — exactly one head revision exists
+- `test_upgrade` — all upgrades apply without error
+- `test_model_definitions_match_ddl` — SQLAlchemy models match the migrated schema
+- `test_up_down_consistency` — every upgrade can be cleanly downgraded
+
+Custom data migration test:
+```python
+@pytest.mark.alembic
+def test_user_email_backfill(alembic_runner):
+    # Insert data before migration
+    alembic_runner.migrate_up_before("abc123def456")
+    alembic_runner.insert_into("users", [{"id": 1, "email": "test@example.com"}])
+
+    # Apply the migration
+    alembic_runner.migrate_up_one()
+
+    # Assert post-migration state
+    result = alembic_runner.execute("SELECT email_new FROM users WHERE id = 1")
+    assert result.scalar() == "test@example.com"
+```
+
+## 8. CI Integration
+
+**Detect uncommitted migrations** — fail CI if models changed but no migration was generated:
+
+```yaml
+# .github/workflows/migrations.yml
+- name: Check for pending migrations
+  run: alembic check
+  env:
+    DATABASE_URL: ${{ secrets.TEST_DATABASE_URL }}
+```
+
+**Squawk** — static analysis for lock-risk DDL (no live DB required):
+
+```yaml
+- name: Install Squawk
+  run: pip install squawk-cli  # or: brew install squawk
+
+- name: Lint migrations for lock risks
+  run: |
+    alembic upgrade head --sql > migration.sql
+    squawk migration.sql
+```
+
+Squawk detects: non-concurrent index creation, adding NOT NULL without default, renaming columns, dropping constraints without cascade, and other patterns that cause long locks.
+
+## 9. Extensions
+
+| Package | Purpose | Install |
+|---------|---------|---------|
+| `alembic-utils` | Replaceable PG objects: views, functions, triggers, RLS policies | `pip install alembic-utils` |
+| `alembic-postgresql-enum` | Safe enum value additions without full table rewrites | `pip install alembic-postgresql-enum` |
+| `audit-alembic` | Attach migration metadata to audit log tables | `pip install audit-alembic` |
+| `sqla-utils` | Additional SQLAlchemy model utilities complementing alembic-utils | `pip install sqla-utils` |
+
+### alembic-utils example (PostgreSQL view):
+
+```python
+from alembic_utils.pg_view import PGView
+
+user_summary_view = PGView(
+    schema="public",
+    signature="user_summary",
+    definition="SELECT id, email, created_at FROM users WHERE active = true",
+)
+
+# In env.py — register with autogenerate
+from alembic_utils.replaceable_entity import register_entities
+register_entities([user_summary_view])
+```
+
+## 10. Common Pitfalls
+
+| Pitfall | Symptom | Fix |
+|---------|---------|-----|
+| Empty `target_metadata` | Autogenerate produces empty migration | Import all models in `env.py` before `Base.metadata` is referenced |
+| Multiple heads | `alembic upgrade head` fails with merge conflict error | Run `alembic merge heads -m "merge"` |
+| SQLite constraint modification | `NotImplementedError` on `op.alter_column` | Use `op.batch_alter_table` context manager |
+| asyncpg URL in offline mode | `Can't load plugin: sqlalchemy.dialects:postgresql+asyncpg` | Use sync URL (`postgresql://`) for offline mode; override only for async online mode |
+| Missing model imports | Tables not detected by autogenerate | Add `from myapp import models` to `env.py` (not just `Base`) |
+| `server_default` vs `default` | `server_default` needed for NOT NULL on existing rows | Use `server_default=sa.text("''")`; remove it in the Contract phase |

package/templates/guides/alembic/README.md

@@ -0,0 +1,438 @@
+# Alembic Guide
+
+Database migration framework for SQLAlchemy. Current stable: **1.18.x** (2025).
+
+## Overview
+
+Alembic is the de-facto migration tool for SQLAlchemy projects. It manages the evolution of a relational database schema over time through versioned migration scripts organized as a directed acyclic graph (DAG). Each migration is a Python file with `upgrade()` and `downgrade()` functions that emit SQLAlchemy Core operations or raw SQL.
+
+**Relationship to SQLAlchemy**: Alembic depends on SQLAlchemy but operates at the DDL (schema) level, not the DML (data query) level. It uses SQLAlchemy's introspection API to compare the current database state against declared models, then generates the difference as migration ops.
+
+**Philosophy**: Unlike Rails migrations or Django migrations, Alembic generates migration code that developers are expected to review and edit. Autogenerate is a starting point, not a final answer.
+
+---
+
+## Core Concepts
+
+### Revision Chain (DAG)
+
+Each migration file has:
+- `revision`: unique identifier (e.g., `a1b2c3d4e5f6`)
+- `down_revision`: parent revision(s) — `None` for the first migration, a tuple for merge points
+
+The chain forms a DAG. `alembic upgrade head` walks the graph from the current DB revision to the tip(s). Branches can exist and are resolved with merge migrations.
+
+```
+None → a1b2 → c3d4 → e5f6 (head)
+                   ↘ g7h8 → merge(e5f6, g7h8) (merged head)
+```
+
+### env.py
+
+The bridge between Alembic and the application. Responsibilities:
+1. Configure the SQLAlchemy engine/connection URL
+2. Set `target_metadata` (SQLAlchemy `MetaData` with all models imported)
+3. Define `run_migrations_offline()` and `run_migrations_online()` functions
+4. Optionally override `alembic.ini` settings (e.g., inject `DATABASE_URL` from env vars)
+
+### alembic.ini
+
+Main configuration file. Key settings:
+- `script_location` — path to `alembic/` directory
+- `sqlalchemy.url` — database URL (should be overridden in `env.py` from env vars)
+- `file_template` — naming pattern for generated migration files
+- `prepend_sys_path` — adds project root to `sys.path` so `env.py` can import models
+
+### script.py.mako
+
+Mako template used to generate new migration files. Default template includes the `revision`, `down_revision`, `branch_labels`, `depends_on` header and empty `upgrade()`/`downgrade()` stubs.
+
+---
+
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `alembic init <dir>` | Initialize a new Alembic environment in `<dir>` |
+| `alembic revision -m "message"` | Create a new empty migration |
+| `alembic revision --autogenerate -m "message"` | Generate migration from model diff |
+| `alembic upgrade head` | Apply all pending migrations |
+| `alembic upgrade +1` | Apply the next one migration |
+| `alembic upgrade <rev>` | Apply migrations up to `<rev>` |
+| `alembic downgrade -1` | Revert the most recent migration |
+| `alembic downgrade base` | Revert all migrations |
+| `alembic downgrade <rev>` | Revert to `<rev>` |
+| `alembic current` | Show current revision(s) applied to the DB |
+| `alembic history` | Show full revision history |
+| `alembic heads` | Show all head revisions (should be 1 in linear projects) |
+| `alembic branches` | Show branch points |
+| `alembic merge <rev1> <rev2> -m "merge"` | Create a merge migration |
+| `alembic check` | Exit non-zero if models have changes not yet reflected in migrations |
+| `alembic upgrade head --sql` | Print SQL statements without executing (offline mode) |
+
+---
+
+## Operations Reference
+
+### Table Operations
+| Op | Description |
+|----|-------------|
+| `op.create_table(name, *cols)` | Create table |
+| `op.drop_table(name)` | Drop table |
+| `op.rename_table(old, new)` | Rename table |
+
+### Column Operations
+| Op | Description |
+|----|-------------|
+| `op.add_column(table, column)` | Add column |
+| `op.drop_column(table, col_name)` | Drop column |
+| `op.alter_column(table, col_name, ...)` | Change type, nullable, default, name |
+
+### Index Operations
+| Op | Description |
+|----|-------------|
+| `op.create_index(name, table, cols)` | Create index |
+| `op.drop_index(name, table)` | Drop index |
+| `op.create_index(..., postgresql_concurrently=True)` | Non-locking index (PG only) |
+
+### Constraint Operations
+| Op | Description |
+|----|-------------|
+| `op.create_unique_constraint(name, table, cols)` | Unique constraint |
+| `op.drop_constraint(name, table)` | Drop constraint |
+| `op.create_foreign_key(name, src_table, ref_table, lcols, rcols)` | FK constraint |
+| `op.create_check_constraint(name, table, condition)` | Check constraint |
+
+### Data & Raw SQL
+| Op | Description |
+|----|-------------|
+| `op.execute(sql)` | Run raw SQL string or `text()` |
+| `op.bulk_insert(table, rows)` | Insert list of dicts |
+| `op.get_bind()` | Get the active connection for custom queries |
+
+### Batch (SQLite / locked tables)
+```python
+with op.batch_alter_table("users") as batch_op:
+    batch_op.add_column(sa.Column("age", sa.Integer()))
+    batch_op.alter_column("name", nullable=False)
+```
+
+---
+
+## Configuration Patterns
+
+### Sync (Default)
+
+```python
+# env.py
+import os
+from sqlalchemy import engine_from_config, pool
+from alembic import context
+from myapp.models import Base
+
+config = context.config
+config.set_main_option("sqlalchemy.url", os.environ["DATABASE_URL"])
+target_metadata = Base.metadata
+
+def run_migrations_online():
+    connectable = engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+    with connectable.connect() as connection:
+        context.configure(connection=connection, target_metadata=target_metadata)
+        with context.begin_transaction():
+            context.run_migrations()
+```
+
+### Async (asyncpg)
+
+```python
+# env.py — async pattern
+import asyncio, os
+from sqlalchemy import pool
+from sqlalchemy.ext.asyncio import async_engine_from_config
+from alembic import context
+from myapp.models import Base
+
+config = context.config
+config.set_main_option("sqlalchemy.url", os.environ["DATABASE_URL"])
+target_metadata = Base.metadata
+
+async def run_migrations_online():
+    connectable = async_engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+    async with connectable.connect() as connection:
+        await connection.run_sync(
+            lambda conn: context.configure(conn, target_metadata=target_metadata)
+        )
+        async with connectable.begin() as trans:
+            await connection.run_sync(lambda _: context.run_migrations())
+    await connectable.dispose()
+
+asyncio.run(run_migrations_online())
+```
+
+### Multi-Tenant (Schema Per Tenant)
+
+```python
+# env.py — schema-per-tenant pattern
+import os
+from alembic import context
+
+TENANT_SCHEMAS = os.environ.get("TENANT_SCHEMAS", "public").split(",")
+
+def run_migrations_online():
+    connectable = engine_from_config(...)
+    with connectable.connect() as connection:
+        for schema in TENANT_SCHEMAS:
+            connection.execute(text(f"SET search_path TO {schema}"))
+            context.configure(
+                connection=connection,
+                target_metadata=target_metadata,
+                version_table_schema=schema,
+                include_schemas=True,
+            )
+            with context.begin_transaction():
+                context.run_migrations()
+```
+
+### Multi-Database
+
+Use separate `alembic/` directories (one per database), each with its own `alembic.ini` and `env.py`. Invoke as:
+
+```bash
+alembic -c alembic_orders.ini upgrade head
+alembic -c alembic_users.ini upgrade head
+```
+
+---
+
+## Integration
+
+### FastAPI
+
+Use lifespan events to run migrations on startup in development:
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from alembic.config import Config
+from alembic import command
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Run migrations on startup (dev/test only — use CI in production)
+    alembic_cfg = Config("alembic.ini")
+    command.upgrade(alembic_cfg, "head")
+    yield
+
+app = FastAPI(lifespan=lifespan)
+```
+
+For production, run migrations as a separate step before the application starts (init container, pre-deploy hook, or CI step).
+
+### Flask-Migrate
+
+Flask-Migrate wraps Alembic for Flask applications. It adds `flask db init`, `flask db migrate`, `flask db upgrade` commands. Under the hood it calls the same Alembic Python API. Alembic knowledge transfers directly; only the CLI surface differs.
+
+### Docker / Kubernetes
+
+Run migrations as a Kubernetes init container or Docker Compose `depends_on` service:
+
+```yaml
+# docker-compose.yml
+services:
+  migrate:
+    image: myapp:latest
+    command: alembic upgrade head
+    environment:
+      DATABASE_URL: postgresql://user:pass@db:5432/mydb
+    depends_on:
+      db:
+        condition: service_healthy
+
+  app:
+    image: myapp:latest
+    depends_on:
+      migrate:
+        condition: service_completed_successfully
+```
+
+### pytest-alembic
+
+```bash
+pip install pytest-alembic
+```
+
+Provides fixtures (`alembic_config`, `alembic_engine`, `alembic_runner`) and built-in tests. Add `--test-alembic` flag or run `pytest tests/test_migrations.py`. See `alembic-best-practices` skill for full setup.
+
+---
+
+## Comparison
+
+| Feature | Alembic | Atlas (HashiCorp) | Django Migrations | Flyway | Liquibase |
+|---------|---------|-------------------|-------------------|--------|-----------|
+| Language | Python | Go / HCL | Python | Java | Java / XML |
+| Migration format | Python scripts | HCL / SQL | Python auto-generated | SQL files | XML / YAML / SQL |
+| Autogenerate | Yes (SQLAlchemy) | Yes (schema diff) | Yes (ORM diff) | No | No |
+| Downgrade support | Yes | Partial | Yes | Yes (Undo) | Yes (Rollback) |
+| Multi-DB | Manual | Built-in | Manual | Built-in | Built-in |
+| Async support | Yes (v1.11+) | N/A | No | N/A | N/A |
+| PG objects (views, etc.) | Via alembic-utils | Native HCL | No | SQL only | SQL only |
+| Lock analysis | Via Squawk | Built-in lint | None | None | None |
+| Best for | SQLAlchemy / Python projects | Infra-as-code DB schemas | Django projects | JVM projects | Enterprise / multi-engine |
+
+---
+
+## Security
+
+### Credential Management
+
+Never embed database credentials in `alembic.ini`. Always source from environment variables in `env.py`:
+
+```python
+import os
+config.set_main_option("sqlalchemy.url", os.environ["DATABASE_URL"])
+```
+
+Use secret management (AWS Secrets Manager, HashiCorp Vault, Kubernetes Secrets) to inject `DATABASE_URL` at runtime.
+
+### Migration Script Integrity
+
+- Commit migration files to version control — do not generate them on the fly in CI
+- Use `alembic check` in CI to verify no uncommitted model changes exist
+- Review all autogenerated migrations before merging — they are code, not config
+
+### Database Permission Separation
+
+| Role | Permissions | Used by |
+|------|------------|---------|
+| Migration role | `CREATE`, `ALTER`, `DROP`, `INSERT`, `UPDATE`, `DELETE` on schema | Alembic only |
+| Application role | `SELECT`, `INSERT`, `UPDATE`, `DELETE` on tables | Application at runtime |
+| Read-only role | `SELECT` only | Reporting, analytics |
+
+Run `alembic upgrade head` with the migration role, not the application role. The application should never have `DROP TABLE` or `ALTER TABLE` permissions.
+
+---
+
+## Advanced Topics
+
+### Batch Operations (SQLite)
+
+SQLite does not support `ALTER TABLE` for most operations. Use `batch_alter_table` which recreates the table:
+
+```python
+with op.batch_alter_table("users", schema=None) as batch_op:
+    batch_op.alter_column("email", nullable=False)
+    batch_op.drop_constraint("uq_users_username", type_="unique")
+```
+
+Set `render_as_batch=True` in `env.py` to make autogenerate always emit batch operations for SQLite projects.
+
+### Offline Mode
+
+Generate SQL without a live database:
+
+```bash
+alembic upgrade head --sql > migration.sql
+```
+
+Useful for: production deployments (run SQL through DBA review), Squawk lint analysis, audit trails.
+
+### Branching and Merging
+
+When two developers create migrations from the same base revision, a branch forms. Resolve with:
+
+```bash
+alembic merge <rev1> <rev2> -m "merge parallel migrations"
+```
+
+The merge migration has both revisions in `down_revision` as a tuple:
+
+```python
+down_revision = ("a1b2c3d4", "e5f6g7h8")
+```
+
+### Custom Operations
+
+Extend Alembic with project-specific ops:
+
+```python
+# migrations/ops.py
+from alembic.operations import Operations, MigrateOperation
+
+@Operations.register_operation("create_sequence")
+class CreateSequenceOp(MigrateOperation):
+    def __init__(self, sequence_name, schema=None):
+        self.sequence_name = sequence_name
+        self.schema = schema
+
+    @classmethod
+    def create_sequence(cls, operations, sequence_name, **kw):
+        op = CreateSequenceOp(sequence_name, **kw)
+        return operations.invoke(op)
+
+@Operations.implementation_for(CreateSequenceOp)
+def create_sequence(operations, operation):
+    operations.execute(f"CREATE SEQUENCE {operation.sequence_name}")
+```
+
+### Replaceable Objects (alembic-utils)
+
+For PostgreSQL objects that are replaced entirely on change (views, functions, triggers, RLS policies), use `alembic-utils` to manage them as Replaceable Objects. Register with autogenerate so diffs are automatically detected:
+
+```python
+# env.py
+from alembic_utils.replaceable_entity import register_entities
+from myapp.db.views import user_summary_view, active_orders_view
+
+register_entities([user_summary_view, active_orders_view])
+```
+
+---
+
+## Ecosystem
+
+| Package | Purpose | Maturity |
+|---------|---------|---------|
+| `alembic-utils` | PostgreSQL Replaceable Objects: views, functions, triggers, RLS | Stable |
+| `alembic-postgresql-enum` | Add enum values without full table recreate | Stable |
+| `pytest-alembic` | Migration test fixtures and built-in test cases | Stable |
+| `audit-alembic` | Attach migration context to audit log | Beta |
+| `Squawk` | Static DDL linter for lock-risk patterns | Stable |
+| `pgai Vectorizer` | AI-enabled column vectorization via migrations | Experimental |
+| `Atlas` | Alternative migration engine with HCL-based schema | Stable (separate tool) |
+
+---
+
+## Quick Reference
+
+```bash
+# Initial setup
+pip install alembic sqlalchemy
+alembic init alembic
+
+# Daily workflow
+alembic revision --autogenerate -m "add user preferences table"
+# → Review generated file in alembic/versions/
+alembic upgrade head
+
+# Check / verify
+alembic current
+alembic history --verbose
+alembic check  # fails if models have unmigrated changes
+
+# Rollback
+alembic downgrade -1
+
+# Branching
+alembic merge rev1 rev2 -m "merge branches"
+
+# Offline SQL
+alembic upgrade head --sql | squawk  # lint before applying
+```

package/templates/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.44.4",
+  "version": "0.44.6",
   "lastUpdated": "2026-03-16T00:00:00.000Z",
   "components": [
     {
@@ -12,19 +12,19 @@
       "name": "agents",
       "path": ".claude/agents",
       "description": "AI agent definitions (flat .md files with prefixes)",
-      "files": 44
+      "files": 45
     },
     {
       "name": "skills",
       "path": ".claude/skills",
       "description": "Reusable skill modules (includes slash commands)",
-      "files": 76
+      "files": 77
     },
     {
       "name": "guides",
       "path": "guides",
       "description": "Reference documentation",
-      "files": 25
+      "files": 26
     },
     {
       "name": "hooks",