oh-my-customcodex 0.1.0

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

@@ -0,0 +1,94 @@
+---
+name: airflow-best-practices
+description: Apache Airflow best practices for DAG authoring, testing, and production deployment
+scope: core
+user-invocable: false
+---
+
+# Apache Airflow Best Practices (3.1.8)
+
+## DAG Authoring
+
+### Imports (Airflow 3.x)
+- Use `from airflow.sdk import DAG, task, Asset` — the stable public API
+- Legacy `from airflow.models import DAG` and `from airflow.decorators import task` are deprecated
+
+### Top-Level Code (CRITICAL)
+- Avoid heavy computation at module level (executed on every DAG parse)
+- Minimize imports at module level — lazy-load inside `@task` functions
+- Never call APIs, query databases, or access Variables at top level
+- If Variables needed at top level, enable experimental cache with TTL
+
+### TaskFlow API (Default Pattern)
+- Use `@task` decorator for all Python tasks (preferred over classic operators)
+- XCom serialization is automatic — return values become XCom
+- Use `@task.branch` for branching logic
+- Use `@task.sensor` for sensor tasks
+
+### Dynamic Task Mapping
+- Use `task.expand()` for runtime-determined task instances
+- Combine with `.partial()` for fixed kwargs
+- Map over lists, dicts, or XCom outputs from upstream tasks
+
+### Scheduling
+- Use cron expressions or timetables for `schedule` parameter
+- Set `catchup=False` for most DAGs
+- Use data-aware scheduling with `Asset` (replaces `Dataset`) for dependencies
+- Configure SLA monitoring
+
+### Task Dependencies
+- Use `>>` / `<<` operators for clarity
+- Group related tasks with `TaskGroup`
+- Avoid deep nesting (max 3 levels)
+
+## Testing
+
+### Local Testing
+- Use `dag.test()` in `if __name__ == "__main__":` block for IDE debugging
+- Runs all tasks in single serialized process without executor
+
+### Unit Tests
+- Test DAG import without errors
+- Detect cycles in dependencies
+- Mock external connections
+- Test task logic independently
+
+### Integration Tests
+- Use Airflow test mode
+- Validate end-to-end workflows
+- Test with sample data
+
+## Production Deployment
+
+### Performance
+- Lazy-load heavy libraries inside `@task` functions
+- Use connection pooling
+- Minimize DAG parse time (target < 30s for all DAGs)
+- Enable parallelism appropriately
+
+### Reliability
+- Set appropriate `retries` and `retry_delay`
+- Use SLA callbacks for monitoring
+- Implement proper error handling with `on_failure_callback`
+- Log important events
+
+## Migration: 2.x → 3.x
+
+### Deprecated (Remove or Replace)
+| Deprecated | Replacement |
+|-----------|-------------|
+| `from airflow.models import DAG` | `from airflow.sdk import DAG` |
+| `from airflow.decorators import task` | `from airflow.sdk import task` |
+| `Dataset` | `Asset` |
+| `execution_date` in context | `dag_run.logical_date` |
+| `conf` in task context | Removed — use Variables or params |
+
+### Architecture Changes
+- **AIP-72**: Task Execution Interface — tasks run in isolated subprocesses via Execution API Server
+- **AIP-44**: Internal API — components communicate via API, not direct DB access
+- **New UI**: React-based web interface (replaces Flask-based UI)
+
+## References
+- [Airflow 3.1.8 Best Practices](https://airflow.apache.org/docs/apache-airflow/3.1.8/best-practices.html)
+- [Airflow SDK (Task SDK)](https://airflow.apache.org/docs/apache-airflow/3.1.8/authoring-and-scheduling/index.html)
+- [Migration Guide 2.x → 3.x](https://airflow.apache.org/docs/apache-airflow/3.1.8/migration-guide.html)

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

@@ -0,0 +1,295 @@
+---
+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
+user-invocable: false
+---
+
+# 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/.claude/skills/ambiguity-gate/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: ambiguity-gate
+description: Pre-routing ambiguity analysis — scores request clarity and asks clarifying questions when needed (inspired by ouroboros)
+scope: core
+user-invocable: true
+argument-hint: "[request to analyze for ambiguity]"
+---
+
+# Ambiguity Gate
+
+## Purpose
+
+Analyze a user request for ambiguity before routing to implementation. Inspired by the [ouroboros](https://github.com/Q00/ouroboros) Socratic interviewer pattern, this skill measures request clarity on a 0.0–1.0 scale and asks targeted clarifying questions when needed.
+
+## Ambiguity Scoring
+
+| Score Range | Verdict | Action |
+|-------------|---------|--------|
+| ≤ 0.2 | Clear | Proceed with implementation |
+| 0.2–0.5 | Moderate | Suggest clarifications but allow proceeding |
+| > 0.5 | High | Require clarification before proceeding |
+
+## Scoring Factors
+
+| Factor | Weight | Description |
+|--------|--------|-------------|
+| Scope clarity | 30% | Is the scope of work well-defined? |
+| Technical specificity | 25% | Are technical requirements clear? |
+| Acceptance criteria | 20% | Can we determine when the task is done? |
+| Constraint clarity | 15% | Are constraints and limitations specified? |
+| Context sufficiency | 10% | Is there enough context to proceed? |
+
+**Composite score** = weighted sum of individual factor scores (each 0.0–1.0, inverted: 0.0 = clear, 1.0 = ambiguous).
+
+## Output Format
+
+```
+[Ambiguity Analysis]
+├── Score: {0.0-1.0}
+├── Verdict: {Clear | Moderate | High}
+├── Breakdown:
+│   ├── Scope: {score} — {reason}
+│   ├── Technical: {score} — {reason}
+│   ├── Acceptance: {score} — {reason}
+│   ├── Constraints: {score} — {reason}
+│   └── Context: {score} — {reason}
+└── Suggestions: {clarifying questions if score > 0.2}
+```
+
+## Workflow
+
+1. Receive the request to analyze (from `$ARGUMENTS` or conversation context)
+2. Score each factor independently
+3. Compute weighted composite score
+4. Determine verdict based on threshold
+5. If score > 0.2: generate targeted clarifying questions (max 3, prioritized by highest-weight ambiguous factors)
+6. If score > 0.5: do NOT proceed to implementation; present analysis and wait for clarification
+7. If score ≤ 0.2: output analysis and proceed
+
+## Clarifying Question Guidelines
+
+- Ask **one question per ambiguous factor** (max 3 total)
+- Order by factor weight (scope → technical → acceptance criteria)
+- Make questions specific and answerable
+- Avoid yes/no questions; prefer open-ended with examples
+
+**Example questions:**
+- Scope: "Should this change affect all environments or only development?"
+- Technical: "What language/framework should this be implemented in?"
+- Acceptance: "What would a passing test look like for this feature?"
+- Constraints: "Are there performance or memory constraints to consider?"
+- Context: "Is this a new feature or modifying existing behavior?"
+
+## Integration
+
+This skill can be:
+- **Invoked manually**: `/ambiguity-gate [request]` — analyze a specific request
+- **Integrated into routing skills**: Insert as a pre-check step before agent delegation when request complexity warrants it
+
+Routing skill integration example:
+```
+1. Run ambiguity-gate on user request
+2. If score > 0.5: surface questions, wait for response, re-run gate
+3. If score ≤ 0.5: proceed with normal routing
+```
+
+## When NOT to Use
+
+Skip this skill for:
+- Simple, one-line questions ("What does X do?")
+- One-line fixes with clear scope ("Fix the typo in line 42")
+- Well-defined bug reports with reproduction steps and expected behavior
+- Requests with explicit acceptance criteria already stated
+- Follow-up requests that clarify a previous ambiguous request