Coding Assistant Collaboration

Use this page when you are asking a coding assistant to plan, implement, review, or debug work in this repo. The best results come when the assistant has the same working context a human developer would use: repo rules, the right prompt template, terminal output, and permission to verify its own changes.

Start With Repo Context

Point the assistant at AGENTS.md and the app-level AGENTS.md files for the area being changed.
Use PROMPT_TEMPLATES.md when the task matches an existing template. Connector work should usually start with Connector Implementation Intake, then move to New Connector Implementation once the scope is clear.
Mention relevant canonical docs under docs/features/ and the matching support-dev page.
Describe the outcome and affected workflow, not only the smallest file change. Overly narrow prompts can make the assistant miss adjacent contracts, docs, tests, or user-facing regressions.
Keep secrets out of prompts. Ask the assistant to use repo-owned helpers, .env.example files, and safe commands instead of reading real .env files directly.
For new independent tasks where you want isolation, ask the assistant to use Git Worktrees For Agent Tasks or run bun run worktree:create <task-slug>. If you want the assistant to work in the current checkout, say that explicitly.

Let Skills Guide The Work

Skills under .agents/skills/ encode repo-specific and framework-specific workflows. Usually it is enough to ask the assistant to use the relevant repo skills before planning or coding.

Mention a specific skill only when it helps disambiguate the task, such as connector-providers for connector work, meltano for indexed sync/tap work, mastra for API-side Mastra work, or pre-pr-readiness before PR handoff.

Repo-owned editable skills are listed in CUSTOM_SKILLS.md. Do not ask the assistant to edit lock-managed skills unless the task is explicitly skill maintenance and the writing-skills workflow applies.

Let The Assistant See Runtime Truth

Assistants perform better when they can inspect real command output instead of working from summarized failures.

Let the assistant run targeted tests, type checks, builds, and eval lanes that match the changed surface.
Paste or expose the full terminal error when a command fails. Truncated or paraphrased errors often hide the useful frame.
For UI behavior, let the assistant use Agent Browser when a real browser check can catch layout, auth, state, or interaction problems faster than code inspection.
For chat, retrieval, connector, and model-policy changes, include the relevant eval or smoke lane so the assistant can judge answer quality and grounding, not just whether the UI rendered.

Agent Browser is especially useful for authenticated local UI checks, screenshots, accessibility-tree snapshots, hover/open/closed states, and visual regression hunting. Set it up through Local Dev Setup and use Local Troubleshooting for stale sessions.

Manual testing is still highly recommended. Assistant-run tests, evals, and browser checks provide strong evidence, but a human should still exercise the important workflow before PR handoff when the change affects product behavior, connector accuracy, or user trust.

Ask For A Branch Audit Before PR

Before moving to PR readiness, ask the assistant to audit the current branch against the branch the PR will target. The target might be an initiative branch, dev, or another human-selected base.

Audit the current branch against <target-branch> one more time for regressions, missing docs/tests, security/privacy issues, and stale support-dev guidance before we prepare the PR.

This often finds one more issue worth fixing. If the audit finds several issues, fix them and run another focused audit before drafting the PR. Use PR Readiness after the audit and verification are clean enough for handoff.

Useful Prompts

Use the relevant repo context and skills, then inspect the changed files, nearby call sites, and canonical docs before proposing edits.

Run verification that gives meaningful evidence for this change, read the output, and fix failures before summarizing.

Use agent-browser when browser-visible behavior matters, and verify the changed flow in the real local app rather than relying only on code inspection.

Compare this branch against <target-branch> and look for regressions, missing tests, stale docs, auth/privacy issues, or code paths that drift from the accepted spec.

Canonical Sources

AGENTS.md
PROMPT_TEMPLATES.md
CUSTOM_SKILLS.md
.agents/skills/
apps/web/README.agent-browser.md
apps/support-dev/src/content/docs/getting-started/local-dev-setup.mdx
apps/support-dev/src/content/docs/workflows/git-worktrees.md
apps/support-dev/src/content/docs/workflows/verification.md
apps/support-dev/src/content/docs/workflows/pr-readiness.md