Product overview

What auto-swe is, who it is for, the value it delivers, the end-to-end use cases it covers, and what is deliberately out of scope. For the technical “how” see architecture.md and agents.md.

---

1. Product Thesis

auto-swe is a durable, governed multi-agent workflow platform for engineering and non-engineering teams. A workflow is a versioned JSON DAG executed on Temporal, with agents running inside isolated Docker workspaces, human approval gates wherever a team wants them, and cost, security, and observability applied to every run.

The flagship use case — and the one the default template ships for — is ticket in, reviewed and tested pull request out. That flow is not privileged runtime code: it is an ordinary workflow template composed of the same node types any team can author, so it is a starting point rather than the boundary of what the platform does. Other automations (dependency sweeps, release-note generation, scheduled audits, PRD decomposition) are the same engine with a different DAG.

The Slack channel teammate is both a headline capability and the platform’s conversational surface. It is a channel-resident assistant an engineering team talks to directly — and the same assistant starts, watches, and reports on the workflows above, so teams manage their automation from the channel they already work in rather than a separate console.

One constraint runs through everything the platform ships, as a product choice rather than a limitation: by default nothing merges. auto-swe operates as a contributor that opens PRs; a human merges them. The one exception is opt-in and per repository: in auto mode the platform asks GitHub to auto-merge a provably low-risk pull request once GitHub’s own branch rules are met, and never calls an immediate-merge API (pr-evaluation.md). That keeps it an amplifier of an engineering team rather than a replacement for it. (§7 states precisely how far that guarantee reaches.)

---

2. Target Users

Persona	What they get	Primary surfaces
Engineering teams	Autonomous implementation of well-specified tickets, with quality gates and review applied by default	Dashboard new-request flow, Slack teammate, Epics
Support / Ops, Product, Content, and other teams	Domain-specific workflows over Zendesk, Notion, Slack, Jira/Linear, and other integrations, governed by the same autonomy and approval controls	Dashboard new-request flow, Slack teammate, workflow library
Tech leads	Guaranteed human-governed outcomes, full visibility into what the agent did and why, HITL approval gates	Run viewer, HITL inbox, review network output
Platform / DevOps engineers	Run auto-swe as shared infrastructure for other teams: integrations, model config, RBAC, security policy	Admin console, team config, scanner patterns
Workflow authors	Automate team-specific processes as versioned DAGs — no code change, no redeploy	Visual template editor, NL authoring, CLI bundles
CI/CD pipeline authors	A scriptable pipeline step (PAT + CLI/REST) that fires on issue creation	CLI, REST API, scheduled work requests

The Slack teammate cuts across all of these: it answers questions in-channel with repo and run context, and it is also how a team kicks off a workflow, gets notified when one needs a decision, and answers a HITL gate without leaving Slack.

For the autonomous-implementation use case specifically, auto-swe deliberately does not target very early-stage codebases where the implementation surface is too undefined for an agent to work autonomously — that value depends on tickets being specified well enough to derive measurable success criteria.

---

3. Business Value & Goals

Value pillar	How it is delivered
Throughput amplification	Automates well-specified implementation work so a given headcount ships more
Quality by default	Lint, typecheck, tests, build, a three-agent review network, and security scanning all run on every change — none are opt-in
Institutional learning	An engineering run writes a semantic lesson (pgvector) from its evidence when it merges or its review or CI loop gives up; later implementation runs on the same repository get the closest lessons in their prompt — the system improves per-repo over time
Cost transparency	Per-call / per-run / per-team USD tracking, budget tiers with hard caps, and per-template A/B analytics
Operator control	Models, skills, tool access, workflow shape, and security policy are all DB-driven and overridable per team or per template — most changes need no restart
Operational safety	Temporal makes runs durable (survive crashes, wait days for signals, replay deterministically); humans govern the merge

---

4. Capability Map

flowchart TB
    subgraph Intake["Intake & Orchestration"]
        WR[Work requests\nWeb / CLI / REST / Slack]
        SCHED[Scheduled work requests\nTemporal Schedules]
        EPIC[Multi-repo epics\ndependency-graph fan-out]
        WF[Configurable workflow engine\n15 node types, versioned, A/B]
    end

    subgraph Agents["Agent Execution"]
        IMPL[Implementer\nDinD TDD loop]
        REVNET[Review network\nSecurity / Domain / Performance]
        GATES[Quality gates\nlint / typecheck / test / build / vuln / perf]
        CIHEAL[CI self-healing loop]
        MEM[Semantic memory\npgvector lessons]
    end

    subgraph Governance["Governance & Safety"]
        HITL[Human-in-the-loop\napproval / decision / input / review]
        SCAN[7 runtime security scanners]
        RBAC[RBAC + team multi-tenancy]
        COST[Cost tracking + budget tiers]
    end

    subgraph Platform["Platform & Operations"]
        CONFIG[DB-driven model + integration config]
        OBS[Observability\nAgentTracer + OTel + run viewer]
        INTEG[Integrations\nGitHub / Slack / trackers / S3]
    end

    Intake --> Agents --> Governance
    Platform -.cross-cutting.-> Intake
    Platform -.cross-cutting.-> Agents
    Platform -.cross-cutting.-> Governance

Domain	Capabilities
Agent system	33 seeded agents (19 model-backed + 14 sub-role personas); multi-agent review network; TDD implementation loop driven by the platform’s Mastra tool loop or, per template/team/organization or per agent, the Claude Code harness inside the workspace container or Pi’s agent loop in the worker (agents.md §3.7); channel-resident assistant with ambient, reactive, and persona modes. See agents.md.
Skills	36 built-in prompt-fragment skills; progressive disclosure (loadSkill) for the implementer; custom skills with content scanning + verification flag; scope cascade
Multi-model	DB-driven model selection per role per scope; Anthropic / OpenAI / Google + any OpenAI-compatible provider; AES-256-GCM encrypted credentials. See model-configuration.md.
Workflow engine	15 node types (incl. the declarative agent node and the eval node); versioned immutable template versions; visual React-Flow editor; deterministic A/B routing; per-template/team/global analytics; frozen spec snapshot per run
Orchestration	Temporal durable execution; budget tiers (STANDARD / LARGE / EPIC) with hard token caps and BUDGET_EXCEEDED enforcement
Memory	pgvector (HNSW) semantic lessons; per-repo cosine retrieval at run start; weekly consolidation (“dreaming”) of similar lessons
Security	7 runtime scanners (shell, sensitive-file, pre-write content, code-security, skill-content, LLM-output, memory-content); 68 built-in admin-extensible regex patterns (13 INJECTION, 11 EXFILTRATION, 18 SHELL_COMMAND, 15 CODE_SECURITY, 7 SENSITIVE_FILE, 4 PII); locked-down ephemeral shell containers
HITL	4 node types (approval / decision / input / review); sortable inbox with overdue and multi-approver progress; Slack buttons; idempotent atomic resolution, timeout routing, and cancellation cleanup. See hitl-workflows.md.
Governance	Global/team/template autonomy policies with fail-closed runtime validation; searchable autonomy-decision and lifecycle audit logs (filters live in the URL; the lifecycle log exports its current filter as CSV); analytics and security events over a UTC date range with a comparison to the window before; completed-vs-running analytics with truncation and sample-size disclosure; bounded configuration grants with effective-permission preview
Auth / RBAC	3 auth paths (JWT, PAT, better-auth sessions); 3 platform roles + team-scoped roles; per-page server guards; OAuth (GitHub/Google), Okta OIDC SSO, magic-link, account linking, new-user approval
Integrations	GitHub (PAT or GitHub App), Slack (slash command + interactive), issue trackers (Jira / Linear / GitHub Issues), S3-compatible object storage, email (SMTP/Resend) — all DB-configured, encrypted, with connection tests + audit log
Observability	AgentTracer (tool calls / LLM responses / events per attempt); OTel → Grafana LGTM; 3-mode run viewer (split / transcript / flight-recorder replay)
Surfaces	Web dashboard, full CLI, REST API, Slack

---

5. Primary Use Cases & Workflows

5.1 Standard single-repo work request (the flagship flow)

The canonical end-to-end journey, and what the default ticket-to-merge template encodes. It is a composition of ordinary node types, not a hard-coded pipeline. (Sequence diagram in architecture.md §3.)

flowchart LR
    A[Submit ticket] --> B[Validate context\n+ retrieve lessons]
    B --> C[Implement\nTDD loop max 5]
    C --> D[Review network\nSec / Domain / Perf]
    D --> E[Quality gates]
    E --> F[Open PR]
    F --> G{CI}
    G -->|fail| H[CI self-heal\nread logs, push fix]
    H --> G
    G -->|pass| I[Await human merge\nup to 7 days]
    I --> J[Commit lesson\nto memory]

5.2 Multi-repo epic

A planner agent decomposes a brief spanning ≥2 repos into a per-repo dependency graph; EpicOrchestratorWorkflow fans out child runs in dependency order, each running the full standard flow, with auto merge-conflict resolution. Surfaced as a dependency graph at /epics/:id.

5.3 Human-in-the-loop approvals

Teams insert pause points anywhere in a workflow spec: humanApproval (binary gate before a PR), humanDecision (multi-option branch), humanInput (structured form into context), humanReview (annotated diff review). Workflows park inside Temporal until a signal arrives (inbox response or Slack button) or route to onTimeout.

5.4 CI self-healing loop

On a GitHub check_run failure webhook, the worker fetches the actual CI logs, runs a targeted fix activity, pushes, and re-awaits CI — repeating until green or a retry cap. No human intervention for fixable failures.

5.5 Semantic memory / learning loop

When an engineering run’s pull request is merged — or its review or CI loop runs out of attempts — the memory agent writes a structured lesson from the run’s evidence (the reviewers’ rejection, the failing CI output, the files changed): a MemoryItem with a failure type, rationale and 1536-dim embedding. The merge-conflict resolver and a shell step that pushes changes record lessons of their own without a model call. On later runs, executeImplementation does a per-repository similarity search and adds the closest lessons to the implementer’s system prompt, fenced as reference data. A weekly job merges near-duplicate lessons. Every lesson passes an injection gate on the way in and on the way out (see agents.md §6.4). Everyone can read the lessons of the repositories they can reach at /lessons; a lead of a repository’s team, or a platform admin, also deletes and consolidates them there. See memory.md.

5.6 Configurable + versioned workflow templates

Teams author their own workflow DAGs on a visual canvas without code changes, version them, diff versions, and A/B-test two versions by deterministic per-ticket split — with success-rate / duration / cost analytics per template.

5.7 Scheduled work requests

Admins configure standing automations backed by Temporal Schedules (nightly dependency checks, recurring lint sweeps, periodic doc generation) at /admin/schedules; every kind of automation, schedules included, is listed at /admin/automations (automations.md).

A schedule’s runs share one branch, so a fire is skipped while a retry of its request is running, and a retry is refused while a fire is running (work-views.md).

5.8 Team-scoped configuration

Each team overrides at TEAM scope (falling back to GLOBAL): model-per-role, provider credentials, assigned skills, enabled implementer tools, per-repo gate commands, shell-image and egress allowlists, and Slack notification channels.

5.9 Channel-resident teammate

A per-channel assistant with its own memory, persona, and budget. Two things at once: a capability a team uses directly — answering questions with repo and run context, summarising a thread, drafting a brief — and the conversational surface for everything above, so a workflow can be started, watched, and approved from the channel. See channel-assistant.md.

---

6. Differentiators

What sets auto-swe apart from simpler “AI coding” tools:

• Durable orchestration (Temporal): runs survive crashes, wait days for human/CI signals without polling, and replay deterministically — the foundation that makes multi-day merge waits and CI retry loops operationally safe.
• Multi-agent review network: three specialized reviewers (security, domain logic, performance) run in parallel against every diff, instead of one catch-all reviewer; all must approve.
• CI self-healing: the loop from CI failure → log analysis → automated fix → re-submit is fully automated.
• Semantic institutional memory: pgvector retrieval surfaces relevant past failures and decisions into agent context on relevant future runs; the system’s effective quality improves per-repo over time.
• First-class configurable workflow engine: the workflow DAG is a versioned JSON spec interpreted by a pure functional interpreter — editable, A/B-testable, and analyzable from the UI, not a YAML pipeline bolted onto an agent.
• Operational security stack: seven independent runtime scanners at distinct stages, six of them backed by admin-extensible DB patterns, plus locked-down ephemeral shell containers.
• The automation lives where the team does: the channel teammate is not a notification webhook — it is an agent with channel memory and a persona that also starts, watches, and gates the workflows, so the control surface and the conversation are the same place.

---

7. Non-Goals / Out of Scope

Most of these are architecturally enforced rather than policy; where a boundary rests on shipped content instead, it says so.

• Not a no-code automation tool, a BPM suite, an RPA tool, a chatbot platform, or a personal coding assistant. Templates, agents, and skills are authored, versioned, governed content — programmable rather than drag-and-drop. It augments execution with agents rather than modelling formal processes. It acts through APIs, connectors, and MCP servers, never by driving a third party’s UI. Slack is a control surface, not the product. And it is a team platform for repeatable workflows, not an editor assistant for one engineer.
• Nothing merges by default. No activity calls an immediate-merge API, and no seeded template merges. The SWE flow opens a PR and parks until a Temporal signal bridges the GitHub merge webhook to the waiting workflow. The only sanctioned merge path is opt-in and per repository: the auto mode of pull-request evaluation asks GitHub, through enablePullRequestAutoMerge, to merge a low-risk pull request later, when GitHub’s own branch rules are satisfied. This is a property of the activity catalog and the shipped templates — a team that allowlists the GitHub API host for a shell or containerStep node can author a DAG that merges (see architecture.md §10).
• Kubernetes workspaces cover agent runs only. Docker-in-Docker is the default workspace substrate and works inside Docker Compose. WORKSPACE_BACKEND=kubernetes runs agent workspaces as hardened pods, but shell steps, container steps and sidecars still need the Docker backend (architecture.md §10).
• No repo-admin actions. auto-swe acts as a contributor — no branch-protection bypass and no approval on target repos, and auto-merge only through the opt-in auto mode of pr-evaluation.md, which asks GitHub to merge once its own branch rules hold.
• No IP-level egress filtering for shell steps. DNS-based filtering only; IP-direct connections are out of scope (would require host iptables).
• No multi-arm A/B. Exactly two arms per template (active vs experiment).
• No cross-process scanner-cache invalidation. Gateway and worker are separate processes; pattern edits propagate via 60 s TTL.
• No localization. Interface copy is English only, across the dashboard, the CLI, and Slack and email notifications: there is no message catalog, no locale routing or negotiation, and the web root layout fixes lang="en". Formatting is the exception — dates, durations, token counts, costs, and percentages go through Intl with no locale pinned, so they follow the reader’s browser even though the surrounding words do not. Three further surfaces would each need their own mechanism rather than a message catalog: names and descriptions seeded into the database by syncBuiltins() and rendered as data, gateway error text that the dashboard displays verbatim (the { code, message } envelope makes the code the translatable unit, but Zod refinements carry prose and no code), and status pills, which derive their label by reformatting the raw enum instead of looking one up.

---

8. Maturity

The feature surface described above is built: the workflow engine, HITL, the security scanners, multi-repo epics, GitHub App auth, scheduled requests, Slack integration, evals, the distribution layer, the CLI, and analytics all exist in code, with the unit and workflow suites green.

Read that precisely. The unit suite runs against mocked Docker, mocked Temporal, and mocked LLM calls, so it establishes that the wiring is coherent — not that an agent given a real ticket and a real repository produces a pull request worth merging. Verifying the Temporal, Docker, and LLM paths end to end requires the full infrastructure stack, and the channel assistant in particular is newly built rather than validated under sustained real-world use.

A non-SWE workflow has its own way in. Two entry points take a generic payload validated against the template’s declared inputSchema, with no ticket ID and no repository required:

Entry point	Auth	Notes
POST /api/v1/workflow-templates/:id/runs	ENGINEER	Arbitrary payload; connectionId optional; externalTicketId auto-generated from the label
POST /api/v1/webhooks/:token	opaque per-template webhookToken, plus an optional or required X-AutoSwe-Signature (automations.md §5.1)	Same validation; for firing a template from an external system

A payload may name a baseBranch: the branch a repository run cuts its change from, diffs against, and opens its pull request into, in place of the repository’s default branch. It is a reserved key — every step that clones honours it, whatever the template, so a template that used an input of that name for something else now targets that branch — and it is checked before anything is written: an invalid branch name, or one of the platform’s own <branchPrefix>/… work branches, is 400 INVALID_BASE_BRANCH. It lives in the payload because the payload is what a retry and a re-run copy, so a later attempt targets the same branch. Agent runs take it as a body field (agent-runs.md); POST /api/v1/work-requests, Slack, schedules, epics and PRD runs do not accept one and always use the default branch.

These and POST /api/v1/prd-runs accept an optional Idempotency-Key header. With one, the run’s workflow ID is a deterministic function of the key, so a retried request or a redelivered webhook collapses onto the original run (409) instead of starting a second one. Without one, each request is a fresh run — idempotency is opt-in, because a schedule or a manual retry often wants to run the same payload again.

POST /api/v1/work-requests takes the same header but does not derive its workflow ID from it: a work request already has a ticket-derived ID, and the in-flight guard on it (one running execution per ticket and repository, 409) must keep holding whatever key arrives. The key is stored on the RunInput and is unique per submitter, so a retry with the same key, ticket, repository, description and budget tier, made after the run started, answers 200 with the workRequestId and the single workflowIds entry the original 201 returned (never a later re-run’s) and deduplicated: true. The caller must still be able to launch against the repository: a replay by someone since removed from the team is refused like a fresh submission. The org’s monthly cap is not re-applied, because a replay starts nothing. The same key with different values is 422 IDEMPOTENCY_KEY_MISMATCH; while the original request is still starting its run the key answers 409 IDEMPOTENCY_KEY_IN_PROGRESS with Retry-After; and a key whose launch failed to start is free to reuse. Two different keys for one ticket that is still running get the ordinary 409.

What is still SWE-shaped is the plumbing behind them, not the door. Both marshal the payload into a RepoWorkRequest — the ticket→PR struct — passing a null repoId when there is no connection, and RunInput.externalTicketId remains non-nullable in the schema (auto-filled rather than demanded of the caller). Event→input mappings for external triggers are configuration rather than a persisted Trigger table.

The non-engineering verticals are seeded content, not proven flows. The horizontal abstractions exist — workspace providers (git_repo, document, issue_tracker, record, api_only), outcome publishers, connection types (git_repo, issue_tracker, notion, confluence, zendesk, hubspot, slack_workspace, http_api, mcp), autonomy policies, and the support, product, and content skill and agent packs — but only the engineering flow has a complete, exercised end-to-end path. Where the platform stops today:

• The document provider is backed by Notion and Confluence, reading and writing through the connector API per step; there is no local document cache and no headless editor. A Confluence write reads a page or creates one, or replaces an existing page’s whole body; there is no block-level edit. The Confluence request and response shapes follow the documented v2 and legacy REST contracts, but no Confluence instance was reachable from this environment, so they are unexercised against a live service.
• Salesforce, Workday, Google Docs and Intercom are not connection types; they are reachable only through a generic http_api connection or an mcp server, and http_api is itself still a placeholder, so a generic step over one reports success without making a request. There is no connector marketplace — bundles install from a file or a URL against trust anchors set in the environment.
• The run viewer is built around a code diff and CI status. A document, record change, or message produced by a non-code workflow is shown as raw step output, not rendered.
• estimatedHumanTimeSaved is self-reported per template (estimatedHumanTimeSavedMinutes) and multiplied out per run; it is not measured.
• Execution is a DAG only; there is no linear or case-management mode.
• Enterprise controls stop at Okta SSO and org/team RBAC: no per-org SSO scoping, no data-residency controls, and no retention policy beyond template deletion (which removes its shell audit rows) and manual memory_items deletion.

Two limitations in §7 are deliberate rather than pending: shell-step egress filtering is DNS-based, so IP-direct connections are unfiltered and wildcard entries are informational only. Both would require an in-path egress proxy or resolver.

Tenant isolation is enforced in the application layer — org and team membership checks on the routes — not by database row-level policies.

Both the read-only run/diff DAG viewer and the interactive template editor support keyboard navigation: arrow-key edge traversal, Home-to-entry, Enter-to-open, and per-node screen-reader labels (the editor also keeps Delete-to-remove). The editor’s traversal is bound in the capture phase so it takes precedence over React Flow’s native arrow-key node nudge (node positions are session-only, so nothing is lost).

---

9. Where to Go Next

To understand…	Read
System context, package map, lifecycle, data model, infra	architecture.md
Agent roles, review network, skills, scanners, observability	agents.md
HITL node types, signal flow, inbox	hitl-workflows.md
Model + credential configuration	model-configuration.md
Production deployment	deployment.md
Conventions, tech stack, model defaults	AGENTS.md
Design rationale behind decisions already made	history/