ara.engineer

End-to-end validate a `text.ara.so/backend` (website-agent) fix against a real Railway preview environment BEFORE merging to main. Pushes the current branch, deploys the SHA to the long-lived `preview` Railway env, confirms the new `git_sha` is live via `/healthz`, then sends a focused signed webhook replay (single-turn or short multi-turn) to a reserved 555-01XX test phone, and polls Braintrust for the root span's `outcome` / rounds / tools / reply. Use whenever you change anything in `backend/src/` (tool handlers, system prompt, builder loop, etc.) and want production-fidelity proof — not just unit tests — before opening the PR. Invoked as `/replay-railway-preview` or `/replay railway preview`.

Ara's secrets convention — all runtime credentials live in Infisical (project "Ara-passwords"), one folder per active GitHub repo (`/ara-engineer`, `/text-ara-so`). The old megarepo lives at `/legacy-ara-megarepo` tagged `legacy` — reference only. Never ask the user to paste keys; never commit .env; never build a custom vault.

Align the website-agent (system prompt + routing) with successful on-Ara website building; analyze Braintrust traces for derailment (wrong phase, local-dev tutoring, missing deploy, paywall/connect confusion), patch `text.ara.so/backend` (primarily `system-prompt.ts`), then verify in a tight loop—`bt` / Braintrust evals / `bun run e2e` (replay + live)—and report a before vs after fit table. Invoked as `/align`, `/align <trace url>`, `/align users …` (pair with `/trace` to gather traces). Companion to `/trace`.

Ara agent-trace debugging — inspect Braintrust traces for the website-agent (TS/Bun, Cerebras, Vercel AI SDK v6). Invoked as `/trace recent`, `/trace turn <turn_id>`, `/trace convo <chat_id>`, `/trace user <phone>`, `/trace top users` (aggregate: who messaged most in a time window — one latest-turn link per sender, table below), `/trace tool <name>`, `/trace span <id>`, `/trace <url>`, `/trace test` (run canonical e2e via `text.ara.so/backend/scripts/e2e.ts` (`bun run e2e --target=local --scenarios=<name>`)), `/trace score`, `/trace online`, or `/trace grow`. **Use `/align`** to align system prompt and gates to traces and report before/after tables (`skills/align/SKILL.md`). **When the user asks for users’ traces / links:** give **one permalink per user** — the **latest** `webhook.inbound` root only. **When they ask for top / busiest users over a time range:** use the **top users table** format (Msgs, User, single review link) — no per-thread “all turns” column unless they ask.

Deeply research a technology already in the stack. Pulls latest official docs, changelogs, release notes, production recipes, and pitfalls via heavy web search — then maps findings onto the exact usage pattern in this repo to surface underused features and confirm best practices. Use whenever someone asks "are we using X right?", "what's the best way to use X for Y?", or "what did X ship recently that we should adopt?"

Braintrust `bt` CLI for Ara — every agent-facing service emits spans to the `Ara` project (org `Aradotso`). Use for inspecting logs/traces/prompts/evals, authenticating, SQL over spans, and wrapping new code with tracing. For the Ara-specific span shape and debug recipes (`/trace recent`, `/trace turn`, `/trace user`, etc.) see the companion `/trace` skill.

Meta-guide to the aracli CLI (formerly `ae`) and its skill-sharing pipeline. Covers how aracli ships Claude Code skills to every teammate automatically — first-run bootstrap, live symlinks, PreToolUse/Skill hook, SessionStart hook. Use whenever you need to author a new skill, edit an existing skill, or reason about why a skill change did (or didn't) reach another user.

Self-improving skill loop. Analyzes the current conversation — what worked, what didn't — and patches ae skills accordingly. Run at the end of a session.

Ara observability — query logs across api, web, and app. Primary dataset is "logs". Filter by service, environment, user_id, or runtime_session_id.

End-user control of cmux topology and routing (windows, workspaces, panes/surfaces, focus, moves, reorder, identify, trigger flash). Use when automation needs deterministic placement and navigation in a multi-pane cmux layout.

Linear issue tracking — create issues when features are discussed, assign on start, move through In Progress → Done. Always active during coding sessions.

Find best-in-class tech for any problem. Runs parallel searches across GitHub, startups, research, and community — ranks and saves winners to a sauce list.

Smart test runner — auto-detects what changed vs main, runs relevant tests (health, browser smoke, go tests). Writes a gate file so /push knows tests passed.