Skip to content

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

core-conventions

Verified

Use this skill when writing or reviewing Python code in TTA.dev. Covers package manager, type hints, primitives usage, and anti-patterns.

FileKindSize
SKILL.mdskill md2.6 KB
---
name: core-conventions
description: 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`.**

```bash
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

```python
# ✅ 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 | None` |
| `from primitives.X` | `from ttadev.primitives.X` |

#### State Management

Pass state via `WorkflowContext`, never global variables:

```python
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.**

```python
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

- Primitives API & patterns: [`docs/agent-guides/primitives-patterns.md`](../../docs/agent-guides/primitives-patterns.md)
- Python standards: [`docs/agent-guides/python-standards.md`](../../docs/agent-guides/python-standards.md)
- LLM provider strategy: [`docs/agent-guides/llm-provider-strategy.md`](../../docs/agent-guides/llm-provider-strategy.md)
- TODO management: [`docs/agent-guides/todo-management.md`](../../docs/agent-guides/todo-management.md)
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: 471kUpdated 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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall