Artisan — Multi-Agent Software Engineering Lifecycle

Inspiration

Engineering workflows are increasingly accelerated by coding agents, yet developers spend hours every day paying an invisible "context tax":

Ticket → Agent: Manually translating Jira tickets, user bug reports, and product specs into prompts that coding agents can understand.
Agent → Ticket: Babysitting coding outputs, checking test suites, opening PRs, and manually shuttling statuses, comments, and links back to Jira.

When agents hallucinate, loop infinitely on broken tests, or attempt unverified merges, developer trust breaks down.

We built Artisan to be an autonomous, expert co-developer that closes this loop completely. Given a raw GitHub issue, Artisan autonomously assesses context, detects duplicate issues, writes and verifies code inside secure, ephemeral sandboxes, and opens a review-ready PR — keeping Jira perfectly in sync end-to-end without a single human context-switch.

What It Does & Core Architecture

Artisan operates on a strict 3-Gate Safety Architecture powered by Google's Agent Development Kit (ADK) and Gemini 3.7 Flash, enforcing the invariant that Artisan acts with confidence or escalates with clarity — it never guesses on user intent.

Pipeline overview:

GitHub Issue/PR Event
      │
      ▼
Webhook (GitHub App)
      │
      ▼
Pub/Sub Queue
      │
      ▼
Orchestrator (Cloud Run)
      │
      ▼
Gate 1: Intake & Clarification
      │  (context verified)
      ▼
Gate 2: Plan → Execute → Verify 
      │                    │
      ▼                    ▼
Gate 3: Conflict Triage  Pull Request Opened
      │                    │
      │                    ▼
      └─────► Human Maintainer Review & Merge

Orchestrator also syncs with:
  • Jira Cloud (ticket status/comments)
  • Firestore (state machine)
  • Live Next.js Dashboard (real-time view)

Gate 1: Duplicate-Aware Intake & Clarification

Duplicate Detection: Scans open issues using semantic overlap scoring. Candidates are flagged with links, asking the reporter for confirmation. Artisan never auto-closes tickets without reporter consent.
Context Sufficiency: An Intake Agent evaluates if requirements are actionable. If ambiguous (e.g., "Login broken"), it posts a single targeted question to the thread ($ R_{\text{clarify}} \le 3 $) rather than guessing implementation details. Once sufficient, Jira transitions to In Progress.

Gate 2: Plan → Execute → Verify → PR Pipeline

Routing & Domain Experts: Routes the issue to specialized persona prompts (Backend, Frontend, Infrastructure).
Planning Agent: Produces a structured implementation plan covering modified files, new tests, and documentation.
Isolated Cloud Run Sandbox: The Execution Agent runs in an ephemeral, bounded Cloud Run Job. It clones the repo, modifies files, and executes the project's actual test suite.
Verification Agent: Validates the test run and diff against both the plan and the original issue. If tests fail, it loops back with structured feedback up to a deterministic retry ceiling ($ R_{\text{retry}} \le 3 $).
Safe PR Creation: On passing verification, a clean PR is opened, Jira is updated with diff summaries and PR links, and the ticket enters review.

Gate 3: Authoritative Merge-Conflict Triage

Executes an authoritative trial merge in an isolated scratch worktree.
Trivial Conflicts: Auto-resolved only if the full test suite passes.
Semantic Conflicts: If both sides modify core business logic differently, Artisan generates a side-by-side comparison and escalates to human maintainers.

Security Invariants

$$\text{MergeAuthority} \in {\text{Human Maintainer}}, \quad \text{SelfMerge} = \emptyset, \quad \text{ForcePush} = \emptyset$$

Isolated Compute: Code execution never touches shared host environments.
No Self-Merge: A human merge is the sole path to ticket completion (Done).

How We Built It

Artisan is built as a cloud-native monorepo orchestrated with Google Cloud services:

Reasoning & Agent Orchestration: Built using the Google Agent Development Kit (ADK) and Gemini 3.7 Flash on Vertex AI.
Microservices & Compute:
- Orchestrator Service: Python 3.13 FastAPI app running on Cloud Run, managing gate logic and webhooks.
- Execution Sandbox: Cloud Run Jobs providing isolated, on-demand container runtimes with bounded tools (read_file, write_file, run_shell_command).
Resilient Ingestion: Google Cloud Pub/Sub with push subscriptions, OIDC signature validation, and Dead-Letter Queues (DLQ).
State Management: Cloud Firestore (Native Mode) for atomic transactional state transitions and idempotency token leases.
Observability: OpenTelemetry (OTel) tracing export to Google Cloud Trace and Cloud Logging for transparent gate audit trails.
Real-time Monitoring Dashboard: Next.js 15 (App Router), TypeScript, TailwindCSS, and Auth.js v5 (GitHub OAuth) with Server-Sent Events (SSE) for live status streams.
Infrastructure as Code: Declarative Terraform and multi-stage Docker builds.

Challenges We Ran Into

Pub/Sub At-Least-Once Delivery vs. Long-Running Agent Workflows: Gate 2 pipelines (planning, multi-round execution, running test suites) take minutes. Standard ack deadlines caused duplicate redelivery storms. We designed a transactional distributed claim-based idempotency pattern in Firestore (claim_delivery → in_progress → completed) with time-bounded lease expiries and dead-letter queues.
Unattended Sandboxing with Google ADK: Standard agent toolkits often expect interactive human confirmation for shell commands. In an unattended Cloud Run Job, this caused jobs to stall. We built custom bounded FunctionTool abstractions equipped with step caps ($ N_{\text{max}} = 40 $) and timeout protections.
Vertex AI Global Endpoint Routing: Connecting Gemini 3.7 Flash through Vertex AI required GOOGLE_CLOUD_LOCATION=global rather than regional endpoints (us-central1), which surfaced initially as silent 404s. Identifying this allowed us to establish deterministic client bootstrap patterns.
Stale Git Merge States: GitHub's mergeable_state API is asynchronous and prone to stale cache reads. We solved this by executing explicit trial merges inside isolated scratch git worktrees to guarantee authoritative conflict classification.

Accomplishments We're Proud Of

147+ Automated Tests: Comprehensive unit, integration, and E2E test coverage across all Python agents, execution sandboxes, and Next.js frontend components.
True End-to-End Autonomy: Successfully filing an issue on a live GitHub repo, watching Artisan clarify missing details, write working code, execute pytest suites in Cloud Run Jobs, and open a verified PR with real-time Jira updates.
Zero Guessing Guardrails: A verifiable gate architecture that prioritizes developer safety and transparency above blind autonomy.

What We Learned

Agentic Systems Need Classical Engineering Rigor: LLMs provide incredible semantic reasoning, but production reliability comes from traditional distributed systems concepts: idempotency keys, state machines, bounded retries, and sandboxed virtualization.
Observability is Trust: Developers will not adopt autonomous coding agents unless they can inspect a verifiable audit trail answering "Why did the agent make this decision?"

What's Next for Artisan

Multi-Repo & Monorepo Fleet Support: Cross-repository dependency analysis and coordinated multi-PR rollouts.
Custom Domain Persona Plugins: Letting teams define repository-specific coding personas and linter policies via markdown configuration files.
Interactive Maintenance Slack/Discord Bot: Allowing engineers to approve escalations or answer clarification questions directly from team chat.