Developer Workflows
Start here when you know what kind of work you are doing but not which runbook or feature spec owns it.
Common Paths
Section titled “Common Paths”| Workflow | Start here | When to use it |
|---|---|---|
| Local setup | Local Dev Setup | First repo startup, prerequisite installation, env examples, health URLs, and local service checks. |
| Environment variables | Environment Variables | Understanding generated local env files, release/local categories, and which example file owns each env group. |
| Local troubleshooting | Local Troubleshooting | Recovering stuck auth, CMS, MongoDB, chat data, browser automation, Playwright, or MCP workflows after setup. |
| GitHub CI triage | GitHub CI Triage | Inspecting PR workflow runs, pulling failed logs with gh, and deciding what to reproduce locally. |
| Branching and initiative work | Branching And Initiative Work | Starting initiatives, branching from initiative branches, standalone bug fixes, and avoiding direct commits to dev or main. |
| Git worktrees for agent tasks | Git Worktrees For Agent Tasks | Creating isolated task worktrees from dev, provisioning env files, and configuring coding agents to run setup automatically. |
| Coding assistant collaboration | Coding Assistant Collaboration | Prompt templates, skills, terminal feedback, agent-browser checks, verification, and branch audits before PRs. |
| Canonical docs work | Canonical Docs Workflow | Adding or changing product behavior, initiative requirements, acceptance criteria, ADRs, or support-dev mirrors. |
| Verification | Verification + Evals | Choosing type-check, build, app tests, Mastra evals, or browser checks. |
| Release preparation | Release Workflow | Generating release-note previews, updating CHANGELOG.md, and bumping the root release version with Changelogen. |
| Local connector prompt packs | Local Connector Prompt Packs | Generating gitignored local prompt packs and running browser-backed checks against developer-local connectors. |
| Bruno API collections | Bruno API Collections | Installing Bruno and running manual local API smoke checks across auth, web proxy, API, and Mastra runtime boundaries. |
| PR readiness | PR Readiness | Final branch audit, diff review, Codex review handling, PR template drafting, and truthful skipped-gate notes. |
| Connector provider changes | Connector Provider Changes | Adding/changing connector registry, OAuth, runtime, sync, live query, or seed behavior. |
| Add a new connector | Add A New Connector | Starting a built-in connector with the repo connector prompt template and current registry/runtime onboarding path. |
| Auth and SSO changes | Workforce SSO Setup | Workforce provider setup or policy changes. |
| Feedback review and eval authoring | Feedback Review Handoff and Evals | Reviewing Jira feedback, deciding eval-worthiness, and authoring synthetic/redacted evals. |
| Mastra evals | Chat Evals And Regression Testing | Running deterministic or persisted chat eval lanes. |
| MCP server config | MCP Setup | Updating assistant MCP server config generated for local agents. |
Screenshot Placeholder
Developer workflow landing
Replace later with a screenshot of the support-dev workflow section or local service dashboard.
Practical Rule
Section titled “Practical Rule”If a change touches customer-cluster deployment, secrets, connector policy, auth, chat focus/retrieval, or review/eval privacy boundaries, read the canonical feature spec first. Support-dev pages are entry points, not approval sources.
Canonical Sources
Section titled “Canonical Sources”apps/support-dev/AGENTS.mddocs/AGENTS.mddocs/features/README.mddocs/features/*/spec.md