@bcelep/capint 0.4.2 → 0.6.5

package/skills/dignified-python/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: dignified-python
+description:
+  Production Python coding standards with automatic version detection (3.10-3.13). Use when writing,
+  reviewing, or refactoring Python to ensure adherence to modern type syntax, LBYL exception
+  handling, pathlib operations, ABC-based interfaces, and production-tested patterns. Not
+  Dagster-specific - applies to any Python project.
+references:
+  - core-standards
+  - cli-patterns
+  - versions/python-3.10
+  - versions/python-3.11
+  - versions/python-3.12
+  - versions/python-3.13
+  - advanced/api-design
+  - advanced/exception-handling
+  - advanced/interfaces
+  - advanced/typing-advanced
+metadata:
+  version: '1.0.1'
+origin: verdent
+prismx_bundle: verdent
+prismx_imported_at: 2026-05-27
+---
+
+# Dignified Python Coding Standards Skill
+
+Production-quality Python coding standards for writing clean, maintainable, modern Python code
+(versions 3.10-3.13).
+
+## When to Use This Skill
+
+Auto-invoke when users ask about:
+
+- "make this pythonic" / "is this good python"
+- "type hints" / "type annotations" / "typing"
+- "LBYL vs EAFP" / "exception handling"
+- "pathlib vs os.path" / "path operations"
+- "CLI patterns" / "click usage"
+- "code review" / "improve this code"
+- Any Python code quality or standards question
+
+**Note**: This skill is **general Python standards**, not Dagster-specific. Use
+`/dagster-best-practices` for Dagster patterns.
+
+## When to Use This Skill vs. Others
+
+| User Need                    | Use This Skill              | Alternative Skill         |
+| ---------------------------- | --------------------------- | ------------------------- |
+| "make this pythonic"         | ✅ Yes - Python standards   |                           |
+| "is this good python"        | ✅ Yes - code quality       |                           |
+| "type hints"                 | ✅ Yes - typing guidance    |                           |
+| "LBYL vs EAFP"               | ✅ Yes - exception patterns |                           |
+| "pathlib vs os.path"         | ✅ Yes - path handling      |                           |
+| "best practices for dagster" | ❌ No                       | `/dagster-best-practices` |
+| "implement X pipeline"       | ❌ No                       | `/dg` for implementation  |
+| "which integration to use"   | ❌ No                       | `/dagster-expert`         |
+| "CLI argument parsing"       | ✅ Yes - CLI patterns       |                           |
+
+## Core Knowledge (ALWAYS Loaded)
+
+@dignified-python-core.md
+
+## Version Detection
+
+**Identify the project's minimum Python version** by checking (in order):
+
+1. `pyproject.toml` - Look for `requires-python` field (e.g., `requires-python = ">=3.12"`)
+2. `setup.py` or `setup.cfg` - Look for `python_requires`
+3. `.python-version` file - Contains version like `3.12` or `3.12.0`
+4. Default to Python 3.12 if no version specifier found
+
+**Once identified, load the appropriate version-specific file:**
+
+- Python 3.10: Load `versions/python-3.10.md`
+- Python 3.11: Load `versions/python-3.11.md`
+- Python 3.12: Load `versions/python-3.12.md`
+- Python 3.13: Load `versions/python-3.13.md`
+
+## Conditional Loading (Load Based on Task Patterns)
+
+Core files above cover 80%+ of Python code patterns. Only load these additional files when you
+detect specific patterns:
+
+Pattern detection examples:
+
+- If task mentions "click" or "CLI" -> Load `references/cli-patterns.md`
+- If task mentions "subprocess" -> Load subprocess patterns from core-standards
+
+## Reference Documentation Structure
+
+The `references/` directory contains detailed guidance organized by topic:
+
+### Core References
+
+- **`core-standards.md`** - Essential standards (always loaded)
+- **`cli-patterns.md`** - Command-line interface patterns (click, argparse)
+
+### Version-Specific References (`references/versions/`)
+
+- **`python-3.10.md`** - Features available in Python 3.10+
+- **`python-3.11.md`** - Features available in Python 3.11+
+- **`python-3.12.md`** - Features available in Python 3.12+
+- **`python-3.13.md`** - Features available in Python 3.13+
+
+### Advanced Topics (`references/advanced/`)
+
+- **`exception-handling.md`** - LBYL patterns, error boundaries
+- **`interfaces.md`** - ABC and Protocol patterns
+- **`typing-advanced.md`** - Advanced typing patterns
+- **`api-design.md`** - API design principles
+
+## When to Read Each Reference Document
+
+### `references/advanced/exception-handling.md`
+
+**Read when**:
+
+- Writing try/except blocks
+- Wrapping third-party APIs that may raise
+- Seeing or writing `from e` or `from None`
+- Unsure if LBYL alternative exists
+
+### `references/advanced/interfaces.md`
+
+**Read when**:
+
+- Creating ABC or Protocol classes
+- Writing @abstractmethod decorators
+- Designing gateway layer interfaces
+- Choosing between ABC and Protocol
+
+### `references/advanced/typing-advanced.md`
+
+**Read when**:
+
+- Using typing.cast()
+- Creating Literal type aliases
+- Narrowing types in conditional blocks
+
+### `references/module-design.md`
+
+**Read when**:
+
+- Creating new Python modules
+- Adding module-level code (beyond simple constants)
+- Using @cache decorator at module level
+- Seeing Path() or computation at module level
+- Considering inline imports
+
+### `references/api-design.md`
+
+**Read when**:
+
+- Adding default parameter values to functions
+- Defining functions with 5 or more parameters
+- Using ThreadPoolExecutor.submit()
+- Reviewing function signatures
+
+### `references/checklists.md`
+
+**Read when**:
+
+- Final review before committing Python code
+- Unsure if you've followed all rules
+- Need a quick lookup of requirements
+
+## How to Use This Skill
+
+1. **Core knowledge** is loaded automatically (LBYL, pathlib, basic imports, anti-patterns)
+2. **Version detection** happens once - identify the minimum Python version and load the appropriate
+   version file
+3. **Reference documents** are loaded on-demand based on the triggers above
+4. **Additional patterns** may require extra loading (CLI patterns, subprocess)
+5. **Each file is self-contained** with complete guidance for its domain

package/skills/dignified-python/agents/verdent.yaml

@@ -0,0 +1,11 @@
+category: Backend
+interface:
+  display_name: Python Best Practices
+  short_description: Write production-grade Python with modern standards.
+  icon_dark: './assets/icon-dark.png'
+  icon_light: './assets/icon-light.png'
+  default_prompt: Help me write clean, modern Python code.
+  label:
+    - python
+    - backend
+    - code-quality

package/skills/dignified-python/cli-patterns.md

@@ -0,0 +1,156 @@
+---
+---
+
+# CLI Patterns - Click Best Practices
+
+## Core Rules
+
+1. **Use `click.echo()` for output, NEVER `print()`**
+2. **Exit with `raise SystemExit(1)` for CLI errors**
+3. **Error boundaries at command level**
+4. **Use `err=True` for error output**
+5. **Flush stderr before `click.confirm()`** (prevents buffering hangs)
+
+## Basic Click Patterns
+
+```python
+import click
+from pathlib import Path
+
+# ✅ CORRECT: Use click.echo for output
+@click.command()
+@click.argument("name")
+def greet(name: str) -> None:
+    """Greet the user."""
+    click.echo(f"Hello, {name}!")
+
+# ❌ WRONG: Using print()
+@click.command()
+def greet(name: str) -> None:
+    print(f"Hello, {name}!")  # NEVER use print in CLI
+```
+
+## Error Handling in CLI
+
+```python
+# ✅ CORRECT: CLI command error boundary
+@click.command("create")
+@click.argument("name")
+def create(name: str) -> None:
+    """Create a resource."""
+    try:
+        create_resource(name)
+    except subprocess.CalledProcessError as e:
+        click.echo(f"Error: Command failed: {e.stderr}", err=True)
+        raise SystemExit(1)
+    except ValueError as e:
+        click.echo(f"Error: {e}", err=True)
+        raise SystemExit(1)
+```
+
+## Output Patterns
+
+```python
+# Regular output to stdout
+click.echo("Processing complete")
+
+# Error output to stderr
+click.echo("Error: Operation failed", err=True)
+
+# Colored output
+click.echo(click.style("Success!", fg="green"))
+click.echo(click.style("Warning!", fg="yellow", bold=True))
+
+# Progress indication
+with click.progressbar(items) as bar:
+    for item in bar:
+        process(item)
+```
+
+## Command Structure
+
+```python
+@click.group()
+@click.pass_context
+def cli(ctx: click.Context) -> None:
+    """Main CLI entry point."""
+    ctx.ensure_object(dict)
+    ctx.obj["config"] = load_config()
+
+@cli.command()
+@click.option("--dry-run", is_flag=True, help="Perform dry run")
+@click.argument("path", type=click.Path(exists=True))
+@click.pass_obj
+def sync(obj: dict, path: str, dry_run: bool) -> None:
+    """Sync the repository."""
+    config = obj["config"]
+
+    if dry_run:
+        click.echo("DRY RUN: Would sync...")
+    else:
+        perform_sync(Path(path), config)
+        click.echo("✓ Sync complete")
+```
+
+## User Interaction
+
+```python
+import sys
+
+# ✅ CORRECT: Flush stderr before confirmation prompts
+# This prevents buffering hangs when mixing stderr output with stdin prompts
+click.echo("Warning: This operation is destructive!", err=True)
+sys.stderr.flush()  # Flush before prompting
+if click.confirm("Are you sure?"):
+    perform_dangerous_operation()
+
+# ❌ WRONG: click.confirm() after stderr output without flush
+# This can hang because stderr isn't flushed before the prompt
+click.echo("Warning: This operation is destructive!", err=True)
+if click.confirm("Are you sure?"):  # BAD: potential buffering hang
+    perform_dangerous_operation()
+
+# User input
+name = click.prompt("Enter your name", default="User")
+
+# Password input
+password = click.prompt("Password", hide_input=True)
+
+# Choice selection
+choice = click.prompt(
+    "Select option",
+    type=click.Choice(["option1", "option2"]),
+    default="option1"
+)
+```
+
+## Path Handling
+
+```python
+@click.command()
+@click.argument(
+    "input_file",
+    type=click.Path(exists=True, file_okay=True, dir_okay=False)
+)
+@click.argument(
+    "output_dir",
+    type=click.Path(exists=False, file_okay=False, dir_okay=True)
+)
+def process(input_file: str, output_dir: str) -> None:
+    """Process input file to output directory."""
+    input_path = Path(input_file)
+    output_path = Path(output_dir)
+
+    if not output_path.exists():
+        output_path.mkdir(parents=True)
+
+    click.echo(f"Processing {input_path} → {output_path}")
+```
+
+## Key Takeaways
+
+1. **Always click.echo()**: Never use print() in CLI code
+2. **Error to stderr**: Use `err=True` for error messages
+3. **Exit cleanly**: Use `raise SystemExit(1)` for errors
+4. **User-friendly**: Provide clear messages and confirmations
+5. **Type paths**: Use `click.Path()` for path arguments

package/skills/dignified-python/dignified-python-core.md

@@ -0,0 +1,345 @@
+---
+---
+
+# Dignified Python - Core Standards
+
+This document contains the core Python coding standards that apply to 80%+ of Python code. These
+principles are loaded with every skill invocation.
+
+For conditional loading of specialized patterns:
+
+- CLI development -> Load `cli-patterns.md`
+- Subprocess operations -> Load `subprocess.md`
+
+For detailed reference material, see the "When to Read Each Reference" section in SKILL.md.
+
+---
+
+## The Cornerstone: LBYL Over EAFP
+
+**Look Before You Leap: Check conditions proactively, NEVER use exceptions for control flow.**
+
+This is the single most important rule in dignified Python. Every pattern below flows from this
+principle.
+
+```python
+# CORRECT: Check first
+if key in mapping:
+    value = mapping[key]
+    process(value)
+
+# WRONG: Exception as control flow
+try:
+    value = mapping[key]
+    process(value)
+except KeyError:
+    pass
+```
+
+---
+
+## Exception Handling Basics
+
+### Core Principle
+
+**ALWAYS use LBYL, NEVER EAFP for control flow**
+
+LBYL means checking conditions before acting. EAFP (Easier to Ask for Forgiveness than Permission)
+means trying operations and catching exceptions. In dignified Python, we strongly prefer LBYL.
+
+### Dictionary Access Patterns
+
+```python
+# CORRECT: Membership testing
+if key in mapping:
+    value = mapping[key]
+    process(value)
+else:
+    handle_missing()
+
+# ALSO CORRECT: .get() with default
+value = mapping.get(key, default_value)
+process(value)
+
+# CORRECT: Check before nested access
+if "config" in data and "timeout" in data["config"]:
+    timeout = data["config"]["timeout"]
+
+# WRONG: KeyError as control flow
+try:
+    value = mapping[key]
+except KeyError:
+    handle_missing()
+```
+
+### When Exceptions ARE Acceptable
+
+Exceptions are ONLY acceptable at:
+
+1. **Error boundaries** (CLI/API level)
+2. **Third-party API compatibility** (when no alternative exists)
+3. **Adding context before re-raising**
+
+**Default: Let exceptions bubble up**
+
+For detailed exception handling patterns including B904 chaining, third-party API examples, and
+anti-patterns, see `references/exception-handling.md`.
+
+---
+
+## Path Operations
+
+### The Golden Rule
+
+**ALWAYS check `.exists()` BEFORE `.resolve()` or `.is_relative_to()`**
+
+### Why This Matters
+
+- `.resolve()` raises `OSError` for non-existent paths
+- `.is_relative_to()` raises `ValueError` for invalid comparisons
+- Checking `.exists()` first avoids exceptions entirely (LBYL!)
+
+### Correct Patterns
+
+```python
+from pathlib import Path
+
+# CORRECT: Check exists first
+for wt_path in worktree_paths:
+    if wt_path.exists():
+        wt_path_resolved = wt_path.resolve()
+        if current_dir.is_relative_to(wt_path_resolved):
+            current_worktree = wt_path_resolved
+            break
+
+# WRONG: Using exceptions for path validation
+try:
+    wt_path_resolved = wt_path.resolve()
+    if current_dir.is_relative_to(wt_path_resolved):
+        current_worktree = wt_path_resolved
+except (OSError, ValueError):
+    continue
+```
+
+### Pathlib Best Practices
+
+**Always Use Pathlib (Never os.path)**
+
+```python
+# CORRECT: Use pathlib.Path
+from pathlib import Path
+
+config_file = Path.home() / ".config" / "app.yml"
+if config_file.exists():
+    content = config_file.read_text(encoding="utf-8")
+
+# WRONG: Use os.path
+import os.path
+config_file = os.path.join(os.path.expanduser("~"), ".config", "app.yml")
+```
+
+**Always Specify Encoding**
+
+```python
+# CORRECT: Always specify encoding
+content = path.read_text(encoding="utf-8")
+path.write_text(data, encoding="utf-8")
+
+# WRONG: Default encoding
+content = path.read_text()  # Platform-dependent!
+```
+
+---
+
+## Import Organization
+
+### Core Rules
+
+1. **Default: ALWAYS place imports at module level**
+2. **Use absolute imports only** (no relative imports)
+3. **Inline imports only for specific exceptions** (circular deps, TYPE_CHECKING, conditional
+   features)
+
+```python
+# CORRECT: Module-level imports
+import json
+import click
+from pathlib import Path
+from erk.config import load_config
+
+def my_function() -> None:
+    data = json.loads(content)
+
+# CORRECT: Absolute import
+from erk.config import load_config
+
+# WRONG: Relative import
+from .config import load_config
+
+# WRONG: Inline imports without justification
+def my_function() -> None:
+    import json  # NEVER do this
+```
+
+For detailed inline import patterns and when they're legitimate, see `references/module-design.md`.
+
+---
+
+## Performance Guidelines
+
+### Properties Must Be O(1)
+
+```python
+# WRONG: Property doing I/O
+@property
+def size(self) -> int:
+    return self._fetch_from_db()
+
+# CORRECT: Explicit method name
+def fetch_size_from_db(self) -> int:
+    return self._fetch_from_db()
+
+# CORRECT: O(1) property
+@property
+def size(self) -> int:
+    return self._cached_size
+```
+
+### Magic Methods Must Be O(1)
+
+```python
+# WRONG: __len__ doing iteration
+def __len__(self) -> int:
+    return sum(1 for _ in self._items)
+
+# CORRECT: O(1) __len__
+def __len__(self) -> int:
+    return self._count
+```
+
+---
+
+## Anti-Patterns
+
+### No Backwards Compatibility Preservation (Default)
+
+```python
+# WRONG: Keeping old API unnecessarily
+def process_data(data: dict, legacy_format: bool = False) -> Result:
+    if legacy_format:
+        return legacy_process(data)
+    return new_process(data)
+
+# CORRECT: Break and migrate immediately
+def process_data(data: dict) -> Result:
+    return new_process(data)
+```
+
+### No Re-Exports: One Canonical Import Path
+
+**Core Principle:** Every symbol has exactly one import path. Never re-export.
+
+```python
+# WRONG: __all__ exports create duplicate import paths
+# myapp/__init__.py
+from myapp.core import Process
+__all__ = ["Process"]
+
+# CORRECT: Empty __init__.py, import from canonical location
+# from myapp.core import Process
+```
+
+**When re-exports ARE required** (plugin entry points): Use explicit `import X as X` syntax:
+
+```python
+# CORRECT: Explicit re-export syntax for required entry points
+from myapp.core.feature import my_function as my_function
+```
+
+### Declare Variables Close to Use
+
+```python
+# WRONG: Variable declared far from use
+def process_data(ctx, items):
+    result_path = compute_result_path(ctx)  # Declared here...
+    # 20+ lines of other logic...
+    save_to_path(transformed, result_path)  # ...used here
+
+# CORRECT: Inline at use site
+def process_data(ctx, items):
+    validate_items(items)
+    transformed = transform_items(items)
+    save_to_path(transformed, compute_result_path(ctx))
+```
+
+### Don't Destructure Objects Into Single-Use Locals
+
+```python
+# WRONG: Unnecessary field extraction
+result = fetch_user(user_id)
+name = result.name      # only used once below
+email = result.email    # only used once below
+send_notification(name, email, role)
+
+# CORRECT: Access fields directly
+user = fetch_user(user_id)
+send_notification(user.name, user.email, user.role)
+```
+
+### Indentation Depth Limit
+
+**Maximum indentation: 4 levels**
+
+```python
+# WRONG: Too deeply nested (5 levels)
+def process_items(items):
+    for item in items:
+        if item.valid:
+            for child in item.children:
+                if child.enabled:
+                    for grandchild in child.descendants:
+                        pass  # 5 levels deep!
+
+# CORRECT: Extract helper functions
+def process_items(items):
+    for item in items:
+        if item.valid:
+            process_children(item.children)
+
+def process_children(children):
+    for child in children:
+        if child.enabled:
+            process_descendants(child.descendants)
+```
+
+---
+
+## Backwards Compatibility Philosophy
+
+**Default stance: NO backwards compatibility preservation**
+
+Only preserve backwards compatibility when:
+
+- Code is clearly part of public API
+- User explicitly requests it
+- Migration cost is prohibitively high (rare)
+
+Benefits:
+
+- Cleaner, maintainable codebase
+- Faster iteration
+- No legacy code accumulation
+- Simpler mental models
+
+---
+
+## See Also
+
+For detailed guidance on specialized topics:
+
+- **Exception chaining (B904)**: `references/exception-handling.md`
+- **ABC vs Protocol**: `references/interfaces.md`
+- **typing.cast() assertions**: `references/typing-advanced.md`
+- **Import-time side effects, @cache**: `references/module-design.md`
+- **Default parameters, keyword-only args**: `references/api-design.md`
+- **All decision checklists**: `references/checklists.md`