TTA.dev — Agent Instructions

Universal entry point. All AI coding agents read this first. OpenCode users: this is your primary instruction file.

What is TTA.dev?

A Python library of composable workflow primitives, observability tooling, and multi-agent coordination infrastructure. The sole developer uses Claude Code, GitHub Copilot, and OpenCode.

Commands

uv sync --all-extras    # Install (uv only — never pip or poetry)
make watch              # TDD loop (fast, fail-fast, use during development)
make test               # Full run with coverage (use before committing)
uv run ruff format . && uv run ruff check . --fix   # Format + lint
uvx pyright ttadev/     # Type check
.github/copilot-hooks/post-generation.sh            # Full quality gate

# Running with 1Password secret injection:
op run --env-file=.env -- uv run python -m ttadev.observability
# First copy .env.template to .env and fill in your keys

Rules (non-negotiable)

• uv only — never pip or poetry
• Python 3.12+, str | None not Optional[str], dict[str, Any] not Dict
• Always use primitives for retry/timeout/circuit-breaker — never write manual loops
• Pass state via WorkflowContext — no globals
• 100% test coverage on new code; AAA pattern; MockPrimitive for mocking
• Conventional Commits format (feat:, fix:, docs:, etc.)
• Never edit ~/Repos/TTA directly — clone to /tmp/TTA-copilot, push, then delete

Routing: When working on…

Skills (on-demand HOW-TO workflows)

Skills live in .github/skills/. Invoke by name when relevant.

Before creating a new skill, search github/awesome-copilot first.

Agent-Specific Guides (docs/agent-guides/)

Deep-dive references for specific topics:

Custom Agents (.github/agents/)

Copilot Chat agents with specialized roles:

Copilot Instructions (.github/instructions/)

Auto-applied by file pattern — agents don't need to reference these directly:

L0 Directive

Agent coordination, task ownership, and leases live in ttadev/control_plane/ and ttadev/cli/control.py. Extend there — do not build parallel systems.

Maintenance

See docs/agents/MAINTENANCE.md — budget enforcement, how to update this tree, and cross-repo sync rules with the TTA repository.

GitNexus — Code Intelligence

This project is indexed by GitNexus as TTA.dev (0 symbols, 0 relationships, 0 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.

If any GitNexus tool warns the index is stale, run npx gitnexus analyze in terminal first.

Always Do

• MUST run impact analysis before editing any symbol. Before modifying a function, class, or method, run gitnexus_impact({target: "symbolName", direction: "upstream"}) and report the blast radius (direct callers, affected processes, risk level) to the user.
• MUST run gitnexus_detect_changes() before committing to verify your changes only affect expected symbols and execution flows.
• MUST warn the user if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
• When exploring unfamiliar code, use gitnexus_query({query: "concept"}) to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
• When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use gitnexus_context({name: "symbolName"}).

Never Do

• NEVER edit a function, class, or method without first running gitnexus_impact on it.
• NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
• NEVER rename symbols with find-and-replace — use gitnexus_rename which understands the call graph.
• NEVER commit changes without running gitnexus_detect_changes() to check affected scope.

Resources

CLI