How should dependencies be managed?

Always use uv (uv add / uv sync); avoid pip or poetry.

How should retry logic and state be handled?

Use primitives like RetryPrimitive and TimeoutPrimitive, and pass state via WorkflowContext; avoid manual retry loops and global variables.

core-conventions

npx machina-cli add skill theinterneti/TTA.dev/core-conventions --openclaw

Files (1)

SKILL.md

1.7 KB

Core Conventions (TTA.dev)

Non-negotiable standards for all code in the TTA.dev repository.

Package Manager

Always use uv, never pip or poetry.

uv add package-name        # Add dependency
uv sync --all-extras       # Sync all dependencies
uv run pytest -v           # Run via uv

Python Version & Types

Python 3.11+ required
str | None not Optional[str]
dict[str, Any] not Dict[str, Any]
Google-style docstrings on all public functions

Primitives — Always Use Them

# ✅ Use primitives
workflow = RetryPrimitive(primitive=api_call, max_retries=3)

# ❌ Never write manual retry/timeout loops
for attempt in range(3):  # WRONG
    try: ...

Anti-Patterns

❌ Don't	✅ Do
`try/except` retry loops	`RetryPrimitive`
`asyncio.wait_for()`	`TimeoutPrimitive`
Manual caching dicts	`CachePrimitive`
Global variables for state	`WorkflowContext`
`pip install`	`uv add`
`Optional[str]`	`str

State Management

Pass state via WorkflowContext, never global variables:

context = WorkflowContext(workflow_id="demo")
result = await workflow.execute(input_data, context)

Deep Reference

Primitives API & patterns: docs/agent-guides/primitives-patterns.md
Python standards: docs/agent-guides/python-standards.md
TODO management: docs/agent-guides/todo-management.md

Source

git clone https://github.com/theinterneti/TTA.dev/blob/main/.claude/skills/core-conventions/SKILL.mdView on GitHub

Overview

TTA.dev's core-conventions establish non-negotiable Python coding standards for the repository. It covers the package manager, typing rules, primitive usage, and anti-patterns to keep codebases consistent and maintainable.

How This Skill Works

Developers apply these rules when writing or reviewing code in TTA.dev: use uv for dependency management, enforce Python 3.11+ and modern type hints, and prefer primitives over manual patterns. Anti-patterns like manual retry loops, global state, and pip installs are explicitly discouraged in favor of dedicated primitives and workflows.

When to Use It

When creating a new Python module in the TTA.dev repo and wanting to enforce standards from day one.
When reviewing pull requests to ensure dependencies, typing, and anti-patterns align with core conventions.
When upgrading Python version to 3.11+ or updating type hints across the codebase.
When implementing retry, timeout, or caching logic to avoid ad-hoc loops.
When refactoring code that uses global state or Optional[str] to use WorkflowContext and modern typing.

Quick Start

Step 1: Set up your environment to use uv (uv add, uv sync) and ensure Python 3.11+.
Step 2: Update typing to str | None and dict[str, Any], and add Google-style docstrings to public functions.
Step 3: Replace manual retry loops with RetryPrimitive, avoid global state, and run tests with uv run pytest -v.

Best Practices

Always use uv for dependency management (uv add / uv sync) instead of pip or poetry.
Target Python 3.11+ and use modern hints (str | None, dict[str, Any]); prefer Google-style docstrings for public functions.
Prefer primitives (RetryPrimitive, TimeoutPrimitive, CachePrimitive) over manual loops and ad-hoc patterns.
Keep state in WorkflowContext and pass it through workflow.execute instead of globals.
Avoid anti-patterns listed in the core-conventions and replace them with the recommended alternatives.

Example Use Cases

workflow = RetryPrimitive(primitive=api_call, max_retries=3)
context = WorkflowContext(workflow_id="demo"); result = await workflow.execute(input_data, context)
Use dict[str, Any] instead of Dict[str, Any] and str | None instead of Optional[str]
Replace asyncio.wait_for() with TimeoutPrimitive
Replace global state with a local WorkflowContext and Google-style docstrings for public functions

Frequently Asked Questions

Add this skill to your agents