Skip to content

theinterneti/TTA.dev / .claude/skills/core-conventions

core-conventions

Unverified

Use 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 | 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 loopsRetryPrimitive
asyncio.wait_for()TimeoutPrimitive
Manual caching dictsCachePrimitive
Global variables for stateWorkflowContext
pip installuv add
Optional[str]`str
from primitives.Xfrom 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):

  1. Ollama — default, always available, no API key needed (qwen2.5:7b)
  2. OpenRouter :free — if OPENROUTER_API_KEY is set
  3. 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

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: 464kUpdated Claude CodeCodexVerifiedInstall
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: 464kUpdated Claude CodeCodexVerifiedInstall
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: 318kUpdated Claude CodeCodexUnverifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 318kUpdated Claude CodeCodexUnverifiedInstall