theinterneti/TTA.dev / .claude/skills/core-conventions
core-conventions
UnverifiedUse this skill when writing or reviewing Python code in TTA.dev. Covers package manager, type hints, primitives usage, and anti-patterns.
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 | NonenotOptional[str]dict[str, Any]notDict[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 |
from primitives.X | from ttadev.primitives.X |
State Management
Pass state via WorkflowContext, never global variables:
context = WorkflowContext(workflow_id="demo")
result = await workflow.execute(input_data, context)
LLM Provider Strategy
Always use get_llm_client() — never hardcode a model or base URL.
from ttadev.workflows.llm_provider import get_llm_client
cfg = get_llm_client()
# cfg.base_url, cfg.model, cfg.api_key, cfg.provider
Provider hierarchy for TTA.dev apps (automatic, zero config required):
- Ollama — default, always available, no API key needed (
qwen2.5:7b) - OpenRouter
:free— ifOPENROUTER_API_KEYis set - Paid models — if a paid key is configured
Never use nvidia/nemotron-3-super-120b-a12b:free — it is a reasoning-only
model that returns content: null. Any code reading response.content will crash.
Deep Reference
- Primitives API & patterns:
docs/agent-guides/primitives-patterns.md - Python standards:
docs/agent-guides/python-standards.md - LLM provider strategy:
docs/agent-guides/llm-provider-strategy.md - TODO management:
docs/agent-guides/todo-management.md
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 464k | Updated | Claude CodeCodex | Verified | Install |
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 464k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |