TTA.dev — Claude Code (Main Agent)

Claude Code is the primary agent for this repository. Other agents defer to Claude Code's decisions on architecture and standards. The owner is the sole developer.

SDD Mandate

No implementation code before a signed-off spec. Follow the sdd-workflow skill for the 4-phase process (/specify → /plan → /tasks → /implement). Full constitution: docs/agent-guides/sdd-constitution.md.

Session Start Protocol

Every session begins with /session-start (or the session-start skill steps manually).

1. mcp__hindsight__recall — query adam-global for durable directives/preferences, then query the current derived project-* or workspace-* bank for repository-specific mental models and context
2. mcp__codegraphcontext__get_repository_stats — confirm graph is current
3. Acknowledge what was loaded before any task work begins

Every significant task ends with mcp__hindsight__retain to the right bank:

• retain cross-project preferences and reusable workflow patterns in adam-global
• retain repository-specific decisions, commands, patterns, and failures in the current derived project-* or workspace-* bank

Repo Layout

ttadev/             # Main package
├── primitives/     # Core workflow primitives (retry, cache, timeout, etc.)
├── agents/         # Role-based agent system (specs, registry, router)
├── observability/  # OpenTelemetry integration
├── integrations/   # LLM integrations (Anthropic, OpenAI, Groq, etc.)
├── cli/            # `tta` CLI subcommands
├── skills/         # Agent skills
└── ui/             # UI components
docs/               # Architecture, guides, agent docs
tests/              # Test suite

Agent Skills (Tier 2)

Agent Guides (Tier 3)

Non-Negotiable Standards (Quick Reference)

• Package manager: uv always (never pip/poetry)
• Python: 3.12+ with str | None (not Optional[str])
• Linting: Ruff — line length 88, strict mode (uv run ruff check . --fix)
• Type checking: Pyright basic mode (uvx pyright ttadev/)
• Testing: pytest AAA pattern, 100% coverage for new code — use make watch during development, make test for the full run
• Commits: Conventional Commits (feat:, fix:, docs:, etc.)
• Primitives: Always use for workflows (never manual retry/timeout loops)
• State: Pass via WorkflowContext (never globals)
• LLM providers: Groq openai/gpt-oss-20b for the live Hindsight runtime by default; keep Gemini 3.1 Flash Lite Preview and local Ollama as fallbacks — see llm-provider-strategy
• Orient before edit: Run CGC (find_code + analyze_code_relationships) on any non-trivial target before touching it — enforced by hook (.claude/settings.json)
• Retain after task: Store cross-project signal in adam-global and repo-specific signal in the current derived project-* or workspace-* Hindsight bank
• TTA cross-repo edits: ~/Repos/TTA is owned by the local TTA agent — never edit it directly. Clone to /tmp/TTA-copilot, commit + push, then rm -rf /tmp/TTA-copilot.

Tool Selection: Symbol Lookup

Prefer semantic tools over raw file reads for symbol-level work:

When to use Serena vs CGC:

• Use Serena for precise, symbol-level edits (you know the function, you want to read/replace it)
• Use CGC for orientation (you need to understand relationships and impact before touching anything)

Key References

• AGENTS.md — Universal agent guidance
• PRIMITIVES_CATALOG.md — Full API reference
• GETTING_STARTED.md — Quick start
• MCP_TOOL_REGISTRY.md — Available MCP tools

Multi-Agent Context

Cross-agent memory: .hindsight/ — see Hindsight Memory.

L0 Continuation Directive

TTA.dev now contains the first implemented L0 developer control-plane slice:

• ttadev/control_plane/
• ttadev/cli/control.py
• ttadev/primitives/mcp_server/server.py

If a task is about coordinating coding agents, task ownership, approvals, leases, or developer work orchestration, continue from that L0 surface rather than building a second orchestration system somewhere else.

Immediate L0 Priorities

1. use the current L0 surface to prove one documented, repeatable multi-agent workflow
2. deepen approval/policy/review workflows only where that workflow needs richer coordination
3. strengthen ownership and telemetry attribution so active workflow steps can be explained clearly
4. connect additional agent-facing surfaces to the existing L0 state instead of creating parallel coordination systems

When implementing these, keep the design additive, local-first, and compatible with the existing .tta session/project model.

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