Agent Factory Build Decision Flow

glean-agent-factory-app / backend / engine — from PRD to buildable agent

How the Agent Factory engine decides what to build and how to build it. Every PRD enters at Phase 0 and exits as either a paste-ready brief (Auto Mode) or importable JSON (Workflow Mode). The decision flow spans three layers: build class selection (what kind of agent), build path routing (which phases to run), and architecture pattern selection (which structural template to use within Workflow Mode). Click any section below to drill into the decision logic.

Layer 1 Build Class Selection

Decision gate
Auto Mode
Workflow Mode
Rejected
Checkpoint
      graph TD
        PRD["PRD Submitted"]
        PM["Pattern Matcher
keyword scoring"]
        P0{"Phase 0
Fitness Check"}
        SCORE["Quick Scoring Model
8 dimensions, 0-2 each"]
        HARD{"Hard Gates
Check"}
        FAIL_N1["N1: Not Ready"]
        CLASS_A1["A1: Assistant"]
        CLASS_A2["A2: Assistant + Routing"]
        CLASS_G1["G1: Conversational Agent"]
        CLASS_G2["G2: Input Form Agent"]
        CLASS_G3["G3: Scheduled Agent"]
        CLASS_G4["G4: Content-Triggered"]
        GAP{"Phase 1
Gap Analysis
+ Class Validation"}
        HITL{"HITL Checkpoint"}
        AUTO["Auto Mode Path
Phase 2A + 3A"]
        WKFL["Workflow Mode Path
Phase 2 + 3 + 4"]

        PRD --> PM
        PM -->|"top 3 patterns"| P0
        P0 -->|"FAIL"| FAIL_N1
        P0 -->|"GO / CONDITIONAL"| SCORE
        SCORE --> HARD
        HARD -->|"0-4: broad Q&A"| CLASS_A1
        HARD -->|"14-16: multi-domain"| CLASS_A2
        HARD -->|"5-9: domain chat"| CLASS_G1
        HARD -->|"10-13: form+steps"| CLASS_G2
        HARD -->|"schedule trigger"| CLASS_G3
        HARD -->|"content trigger"| CLASS_G4
        CLASS_A1 --> GAP
        CLASS_A2 --> GAP
        CLASS_G1 --> GAP
        CLASS_G2 --> GAP
        CLASS_G3 --> GAP
        CLASS_G4 --> GAP
        GAP -->|"confirmed or
overridden"| HITL
        HITL -->|"BLOCK"| FAIL_N1
        HITL -->|"A1, A2, G1"| AUTO
        HITL -->|"G2, G3, G4"| WKFL

        classDef decision fill:#6366f122,stroke:#6366f1,stroke-width:2px
        classDef auto fill:#0891b222,stroke:#0891b2,stroke-width:2px
        classDef wkfl fill:#7c3aed22,stroke:#7c3aed,stroke-width:2px
        classDef fail fill:#dc262622,stroke:#dc2626,stroke-width:2px
        classDef gate fill:#d9770622,stroke:#d97706,stroke-width:2px
        classDef neutral fill:#64748b11,stroke:#64748b44,stroke-width:1px

        class P0,HARD,GAP decision
        class CLASS_A1,CLASS_A2,CLASS_G1,AUTO auto
        class CLASS_G2,CLASS_G3,CLASS_G4,WKFL wkfl
        class FAIL_N1 fail
        class HITL gate
        class PRD,PM,SCORE neutral
Pattern Matcher patterns.py
What it does: Keyword-scores the PRD against 10 built-in patterns, returns top 3 as hints.

How it works: Each pattern has a keyword list (8-10 terms). The matcher counts keyword hits in the lowercased PRD text. Score > 0 means a match. The top-scoring pattern is passed to Phase 0 as a suggestion, not a binding decision.

The 10 patterns:
  • 1. Q&A Bot - question, answer, knowledge base, search, FAQ
  • 2. Workflow Agent - form, workflow, collect, process, generate
  • 3. Scheduled Reporter - report, weekly, daily, digest, recurring
  • 4. Approval Workflow - approval, route, triage, classify, escalate
  • 5. Data Sync Agent - sync, migrate, transfer, ETL, pipeline
  • 6. Alert Monitor - monitor, alert, threshold, detect, anomaly
  • 7. Document Generator - document, template, memo, draft, compose
  • 8. Conversational Assistant - chat, conversation, multi-turn, coach
  • 9. Onboarding/Guided Flow - onboarding, walkthrough, checklist, training
  • 10. Decision Tree Agent - decision tree, evaluate, criteria, gate, eligibility
Limitation: Keyword matching is shallow. The LLM in Phase 0 makes the real decision. The matcher just primes it.
Phase 0 Fitness Check - FAIL Conditions mandatory stops
Any one of these triggers an automatic FAIL:
  • Required data source has no Glean connector AND no viable workaround (no Remote MCP template, no API-based custom action, no export-to-Drive path)
  • Core workflow requires storing/caching data outside Glean (agents are stateless)
  • Use case requires real-time bidirectional sync (Glean is read-search-respond, not sync)
  • Problem is better solved by process change, policy change, or non-AI tool
  • Problem-solution fit is MISALIGNED
CONDITIONAL_PASS is only appropriate when all required connectors exist and gaps are about PRD clarity, not platform capability.
Quick Scoring Model - 8 Dimensions 0-16 scale
Score each 0-2, then sum:
Dimension
0
1
2
Repeatability
rare
recurring
high-vol
Workflow clarity
unclear
partial
defined
Standard output
no
somewhat
yes
Branching / logic
none
limited
significant
Actions / integrations
none
future
required
Risk / governance
low
medium
high
Specialized KB
broad
mixed
narrow
Single entry point
no
maybe
yes
Score interpretation:
  • 0-4: A1 (Assistant)
  • 5-9: A1 or A2 (lean A1, consider routing if multi-domain)
  • 10-13: Agent (G1-G4 based on trigger type)
  • 14-16: A2 (Assistant + routing to specialized agents)
Hard Gates - Override the Score binding rules
These override the numeric score when triggered:

Force A1 (Assistant) if most are true
  • Primary value is broad Q&A / synthesis / drafting
  • No strict process needs to be followed
  • No action in another system required
  • User benefits from freeform conversation
  • Retrieval can remain dynamic
Force Agent (G1-G4) if ANY are true
  • Repeatable steps that can be written down
  • Deterministic inputs + structured outputs
  • Authoritative docs + system-specific logic
  • Must classify and respond differently by category
  • Must route to different paths / escalations
  • Requires system actions
  • Must be in Slack, scheduled, or triggered
Force A2 (Assistant + Routing) if ALL are true
  • Users shouldn't choose the specialist
  • 2+ domain-specific use cases
  • Meaningful quality gain from specialization
  • Single front door desired
PRD-prescribed structure override: If the PRD prescribes explicit workflow steps but the problem maps to Auto Mode, recommend Auto Mode and note the override. PRDs often carry forward legacy design decisions.
Phase 1 Gap Analysis - Build Class Validation (Category 12) can override Phase 0
Phase 1 re-evaluates the Phase 0 classification using 12 gap categories. Category 12 specifically validates the build class:

  • If A1 recommended: Do requirements actually need repeatable steps, deterministic outputs, or system actions? If yes, upgrade to G1 or G2.
  • If A2 recommended: Are there actually 2+ distinct domains that benefit from specialization? If not, downgrade to A1 or G1.
  • If G1 recommended: Do requirements need branching, quality gates, multi-step data flow, or >20 actions? If yes, upgrade to G2.
  • If G2/G3/G4 recommended: Is every step necessary, or could this be a single instruction block? If over-engineered, downgrade to G1 or A1.
Rule: Always choose the lowest complexity class that reliably solves the problem.
HITL Checkpoint - Human Override UI checkpoint
Three verdict types:
  • BLOCK - red UI, requires explicit checkbox override to continue. Indicates critical gaps that may result in a broken agent.
  • CAUTION - amber UI, standard approve/reject flow. Gaps exist but are manageable.
  • PROCEED - green UI, standard approve/reject. No significant gaps.
User can: approve and continue, reject and halt the build, or override the classification (change the build class before proceeding).

Layer 2 Build Path Routing 

      graph LR
        HITL2{"HITL Approved"}

        subgraph autopath ["Auto Mode Path (A1, A2, G1)"]
          direction TB
          P2A["Phase 2A
Instruction Design"]
          P3A["Phase 3A
Build Brief"]
          P2A --> P3A
        end

        subgraph wkflpath ["Workflow Mode Path (G2, G3, G4)"]
          direction TB
          P2["Phase 2
Workflow Design"]
          P3["Phase 3
Task Instructions"]
          P4["Phase 4
Generate Outputs"]
          P2 --> P3 --> P4
        end

        P5["Phase 5: Summary"]

        HITL2 -->|"A1, A2, G1"| P2A
        HITL2 -->|"G2, G3, G4"| P2
        P3A --> P5
        P4 --> P5

        classDef auto fill:#0891b222,stroke:#0891b2,stroke-width:2px
        classDef wkfl fill:#7c3aed22,stroke:#7c3aed,stroke-width:2px
        classDef gate fill:#d9770622,stroke:#d97706,stroke-width:2px
        classDef summary fill:#64748b11,stroke:#64748b44,stroke-width:1px

        class P2A,P3A auto
        class P2,P3,P4 wkfl
        class HITL2 gate
        class P5 summary
Auto Mode Path: Phase 2A + 3A A1, A2, G1
Phase 2A - Instruction Design:
  • Write the instruction block (scope, persona, knowledge sources, response format)
  • Action budget: max 20 actions per Auto Mode agent. MCP tools consume action slots. If exceeded, split or switch to Workflow Mode.
  • Don't over-specify edge cases - focus on core rules and structural decisions, leave room for adaptation through usage
  • Context health check: test for distraction (noise in KB), clash (conflicting instructions), confusion (ambiguous routing)
Phase 3A - Build Brief:
  • Paste-ready configuration for the Glean UI
  • Includes: instructions, knowledge sources, conversation starters, action selections, LLM config
  • For A2: also includes routing conditions and agent specs for each routed domain
  • Auto Mode agents cannot be imported via JSON - manual paste only
Workflow Mode Path: Phase 2 + 3 + 4 G2, G3, G4
Phase 2 - Workflow Design:
  • Select base architecture pattern (see Layer 3)
  • Apply hybrid modifiers if needed
  • Design branching architecture, sub-agent decisions, MCP integration
  • Context health check and skill/action detection scan
  • Output: step-by-step architecture with types, dependencies, tool assignments
Phase 3 - Task Instructions:
  • Write each step's instructionTemplate using Goal-Return Format-Warnings-Context framework
  • Target 4,000 chars per step (warn at 6K, hard limit 8K)
  • Wire variable references: [[step_id]] for prior outputs, [[field_name]] for form inputs
Phase 4 - Generate Outputs:
  • Produce importable JSON matching Glean's exact schema
  • UUIDs for each step, correct type field (BRANCH/TOOL/AGENT), memoryConfig: ALL_DEPENDENCIES
  • Post-build validation: schema checks, dependency integrity, variable syntax, budget audit
Knowledge Docs Per Phase system.py PHASE_KNOWLEDGE
Each phase gets only the docs it needs (token budget management). The PHASE_KNOWLEDGE dict in system.py controls filtering:

  • Phase 0: feasibility-rules, connector-registry, platform-ref-slim, prd-decision-framework, external-integrations
  • Phase 1: feasibility-rules, connector-registry, platform-ref-slim, community-patterns-slim
  • Phase 2: actions-catalog, connector-registry, platform-ref-slim, prompt-engineering, hybrid-patterns-slim, orchestration-decisions-slim, community-patterns-slim, tyler-best-practices
  • Phase 3: platform-ref (full), prompt-engineering, orchestration-decisions-slim
  • Phase 4: actions-catalog, json-schema, platform-ref (full), orchestration-decisions-slim
  • Phase 2A: actions-catalog, platform-ref-slim, prompt-engineering, orchestration-decisions-slim
  • Phase 3A: actions-catalog, platform-ref-slim, orchestration-decisions-slim
Phases 3 and 4 use the full platform reference (~45K chars) because they generate JSON and need complete action specs. All other phases use the slim version (~9K chars).

Layer 3 Architecture Pattern Selection (Workflow Mode)

During Phase 2, the engine selects a base pattern from 6 options, then optionally layers hybrid modifiers. The pattern matcher provides a keyword hint, but the LLM makes the final call using full PRD context. 

      graph TD
        P2S["Phase 2 Start"]
        PSEL{"Select Base Pattern"}

        PAT1["Cohesive Synthesis"]
        PAT2["Decision Tree Pipeline"]
        PAT3["Conditional Enterprise
Action Framework"]
        PAT4["Document Generator"]
        PAT5["Dynamic Research"]
        PAT6["Single-Step Agent"]

        HYB{"Hybrid Modifier?"}

        H1["Compute Bridge"]
        H2["Validation Gate"]
        H3["External Orchestration"]
        H4["Memory Isolation"]

        BR["Branching Design"]
        SA{"Sub-Agent?"}

        OUT["Workflow Architecture"]

        P2S --> PSEL

        PSEL -->|"prescriptive"| PAT1
        PSEL -->|"3+ stages"| PAT2
        PSEL -->|"type routing"| PAT3
        PSEL -->|"template+data"| PAT4
        PSEL -->|"exploratory"| PAT5
        PSEL -->|"trivial"| PAT6

        PAT1 --> HYB
        PAT2 --> HYB
        PAT3 --> HYB
        PAT4 --> HYB
        PAT5 --> HYB
        PAT6 --> HYB

        HYB -->|"compute"| H1
        HYB -->|"QA"| H2
        HYB -->|"webhook/MCP"| H3
        HYB -->|"isolation"| H4
        HYB -->|"none"| BR

        H1 --> BR
        H2 --> BR
        H3 --> BR
        H4 --> BR

        BR --> SA
        SA -->|"yes"| OUT
        SA -->|"no"| OUT

        classDef start fill:#7c3aed22,stroke:#7c3aed,stroke-width:2px
        classDef decision fill:#6366f122,stroke:#6366f1,stroke-width:2px
        classDef pattern fill:#05966922,stroke:#059669,stroke-width:2px
        classDef hybrid fill:#be185d22,stroke:#be185d,stroke-width:2px
        classDef branch fill:#d9770622,stroke:#d97706,stroke-width:2px
        classDef output fill:#64748b11,stroke:#64748b44,stroke-width:1px

        class P2S start
        class PSEL,HYB,SA decision
        class PAT1,PAT2,PAT3,PAT4,PAT5,PAT6 pattern
        class H1,H2,H3,H4 hybrid
        class BR branch
        class OUT output
Pattern 1: Cohesive Synthesis most common
Flow: Search + Think + Respond

When to use: Known inputs, defined outputs, standardized process. The vast majority of enterprise workflows are prescriptive - this is the default.

Key rules:
  • Think is the synthesis step. It reads dependency outputs via memory and compiles into structured result.
  • Think is deterministic and controllable.
  • Do NOT use Plan and Execute here - that is only for genuinely exploratory workflows.
Example: Job Description Generator
Trigger: Form (role title, level, department, location).
Flow: Search company JD templates and comp data -> Think synthesizes into standardized JD with sections (role summary, responsibilities, requirements, comp range) -> Respond delivers formatted output.
Why this pattern: Every input field is known, the output format is standardized, and the process is always search-then-synthesize. No branching, no exploration, no autonomy needed.
Example: Policy Compliance Checker
Trigger: Form (policy area, document to check).
Flow: Read submitted document -> Search relevant policy docs -> Think compares document against policies, outputs compliance report with pass/fail per section -> Respond delivers report.
Why this pattern: Clear inputs, authoritative source (policy docs), deterministic output structure. Think handles the comparison logic.
Pattern 2: Decision Tree Pipeline multi-stage gates
Flow: [Classify + Branch + Validate]* + Recommend

When to use: 3+ decision stages with STOP/REVIEW gates and terminal outcomes.

Architecture:
  • Each classification stage is a Think step
  • Each gate is a Branch step
  • Terminal outcomes get dedicated Respond steps
  • Final recommendation is a Think step consuming validated outputs from all prior stages
Critical rule: Gate enforcement must be structural (Branch steps), not behavioral (hoping the LLM follows "do not continue"). A decision tree PRD with 3+ stages MUST produce multiple steps - a single TOOL step containing all decision logic is always wrong.
Example: Technology Platform Selector
Trigger: Chat message describing a technology need.
Flow: Stage 1: Classify need (infra/app/data) -> Branch: STOP if out of scope -> Stage 2: Assess scale requirements -> Branch: REVIEW if enterprise-grade needed -> Stage 3: Check compliance/security -> Branch: STOP if non-compliant -> Final Think: produce recommendation with rationale from all validated stages -> Respond.
Why this pattern: Three decision stages, each with a gate that can halt the process. The recommendation must only proceed if all gates pass. A single step would let the LLM skip gates.
Example: Vendor Qualification Pipeline
Trigger: Form (vendor name, category, annual spend).
Flow: Search vendor docs -> Classify risk tier -> Branch: HIGH sends to manual review Respond -> MEDIUM continues -> Check insurance/compliance docs -> Branch: INCOMPLETE sends to request-docs Respond -> COMPLETE continues -> Score and rank -> Recommend.
Why this pattern: Multiple STOP conditions at different stages. Each gate must structurally prevent the next stage from running.
Pattern 3: Conditional Enterprise Action Framework type-based routing
Flow: Classify + Branch + Per-type processing steps

When to use: The request type determines entirely different processing paths, actions, output formats, or compliance rules.

Architecture:
  • First step classifies the request type
  • Branch step routes to type-specific sub-workflows
  • Each branch may have its own search, think, and action steps
  • Convergence step merges outputs from all branches
Example: HR Request Router
Trigger: Chat message or form (employee request description).
Flow: Classify request type (benefits / leave / employment verification / payroll) -> Branch on type -> Benefits path: search benefits docs, generate benefits response -> Leave path: search leave policies, check accrual data, generate leave guidance -> Verification path: collect required fields, generate verification letter -> Convergence: format final response with appropriate disclaimers per type.
Why this pattern: Each request type has completely different data sources, processing steps, and output formats. Benefits needs comp data; leave needs accrual lookups; verification needs legal templates. One workflow can't serve all types without branching.
Example: Separation Agreement Generator
Trigger: Form (employee name, jurisdiction, separation type).
Flow: Search employee data -> Classify by jurisdiction (US / EMEA / Australia) -> Branch -> US path: calculate WARN compliance, severance per US policy, generate US-format agreement -> EMEA path: check local labor law, consult Works Council requirements, generate EMEA-format agreement -> AU path: calculate notice period, generate AU-format agreement -> Convergence: QA check, deliver to legal reviewer.
Why this pattern: Jurisdiction determines entirely different legal frameworks, calculation methods, and output templates. Cannot be a single instruction block.
Pattern 4: Document Generator template-based
Flow: Gather data + Generate + Deliver

When to use: Template-based documents from gathered data. Output is a formatted deliverable.

Steps:
  • Gather: search for source data, read reference docs
  • Generate: Think step fills template sections from gathered data
  • Deliver: Respond or write action (create page, send email)
Example: Quarterly Business Review Generator
Trigger: Form (business unit, quarter, focus areas).
Flow: Search for quarterly metrics docs -> Read relevant dashboards/reports -> Think fills QBR template (executive summary, KPIs, highlights, risks, next quarter priorities) -> Create Confluence page with formatted output.
Why this pattern: The output is a standardized template. The "intelligence" is in gathering the right data and filling sections accurately - not in deciding what to do.
Example: New Hire Onboarding Packet
Trigger: Form (hire name, role, department, start date, manager).
Flow: Search role-specific onboarding checklist -> Search department resources and contacts -> Search IT provisioning requirements -> Think compiles into personalized onboarding document (week 1 schedule, key contacts, required trainings, system access) -> Respond with formatted packet.
Why this pattern: Multiple searches feed a single document with a known template. No branching, no decision logic - just gather and generate.
Pattern 5: Dynamic Research rare - exploratory only
Flow: Plan and Execute

When to use: The problem is genuinely open-ended with no known solution path. The agent needs to autonomously decide what to search, how to reason, and what to produce.

This is rare. Most enterprise workflows are prescriptive. Use Plan and Execute ONLY when:
  • Source material may be thin and the agent needs to autonomously re-query
  • The workflow is conversational and exploratory
  • No defined output format exists
NEVER use when: defined inputs + expected output format, prescriptive steps, standardized document output. These are Think (Pattern 1) workflows.
Example: Competitive Intelligence Researcher
Trigger: Chat message ("What is [competitor] doing in [market]?").
Flow: Plan and Execute autonomously decides: search internal competitive intel docs, search recent news, search product announcements, synthesize findings, identify gaps in knowledge, re-search if needed, produce analysis.
Why this pattern: The user doesn't know what sources are available. The agent must autonomously decide what to search, evaluate whether results are sufficient, and re-query if thin. No predefined output template.
Example: Root Cause Investigator
Trigger: Chat message (incident description).
Flow: Plan and Execute autonomously: search incident logs, search related past incidents, search runbooks, search architecture docs, trace the dependency chain, hypothesize root cause, search for confirming evidence, produce investigation report.
Why this pattern: Each investigation is unique. The agent must follow the evidence, not a script. Source material is unpredictable.
Pattern 6: Single-Step Agent minimal
Flow: One instruction block

When to use: Trivial 1-2 step workflows where full orchestration adds no value.

Note: If the workflow seems single-step but has decision logic or classification, it probably belongs in Pattern 1 or 2 instead. Don't collapse complexity into one step just because it fits in 8K characters.
Example: Meeting Summary Formatter
Trigger: Chat message with meeting transcript pasted.
Flow: Single instruction: extract attendees, key decisions, action items, and next steps from the transcript. Format as structured summary.
Why this pattern: One input (transcript), one output (summary), no search needed, no branching, no external data. The entire logic fits in one instruction block.
Example: Email Draft Helper
Trigger: Chat message ("Draft an email to [person] about [topic]").
Flow: Single instruction: draft email in company voice with appropriate tone for the recipient and topic.
Why this pattern: No search, no branching, no external systems. One instruction, one output. Adding orchestration would be over-engineering.
Hybrid Modifiers - Applied on Top of Base Patterns optional layer
Hybrid modifiers address the gap between deterministic and non-deterministic steps. Apply one or more when the base pattern doesn't fully cover the workflow's needs.

Compute Bridge
Insert: Custom Action step BEFORE a Branch step.
When: Branch needs exact computed values (dates, scores, thresholds, math). Never use Think to compute values for branch routing - Think output is non-deterministic.
Example: Contract Renewal Router
Custom Action calculates days-until-renewal from contract end date. Branch: if <30 days -> urgent renewal path, if 30-90 -> standard renewal path, if >90 -> no action. Without the Compute Bridge, Think might say "about a month" and misroute.
Example: Severance Package Calculator
Custom Action computes severance amount from tenure + salary + jurisdiction rules. Branch on result: if >$X threshold -> requires VP approval path, else -> standard approval. LLM arithmetic would be unreliable here.
Validation Gate
Insert: Think step (FACTUAL mode) between synthesis and delivery.
When: Output is externally visible, has required sections/format compliance, multiple upstream steps feed the final output, or PRD specifies success criteria.
Checks: completeness, consistency, compliance. Passes through or flags specific issues.
Example: JD Generator QA Step
After Think generates the job description, a Validation Gate Think step checks: all required sections present? Comp range within band? No prohibited language? Required EEO statement included? Either passes through or flags "Missing: requirements section" for the Respond step to surface.
External Orchestration Bridge
Insert: Webhook or MCP call between deterministic steps.
When: External system call needed mid-workflow (approval API, calculation service, notification).
Constraint: MCP tools only available in Plan and Execute and Auto Mode, not in explicit workflow steps. For Workflow Mode, use Custom Actions or webhooks.
Example: Purchase Order with Approval API
Agent gathers PO details and validates against budget -> Custom Action calls company approval API -> Branch on API response (approved/denied/pending) -> Approved path generates PO document, Denied path notifies requestor with reason. The external API call is deterministic and sits between workflow steps.
Memory Isolation Sandwich
Insert: Sub-agent (AGENT step) within parent workflow.
When: Batch processing (CSV Splitter loop), modular domain encapsulation, reusable component across parents.
Key constraint: Only the Respond step output returns to the parent. No native parent-to-child variable mapping - use implicit memory only.
Example: CSV Batch Processor
Parent agent receives a CSV upload -> CSV Splitter loops through rows -> Each row spawns a sub-agent that processes independently (e.g., validates address, enriches company data) -> Sub-agent Respond returns result to parent -> Parent aggregates all results into final report. Sub-agent memory doesn't pollute the parent's context.
Example: Multi-Region Compliance Check
Parent agent receives document -> Spawns US compliance sub-agent, EU compliance sub-agent, APAC compliance sub-agent in parallel -> Each sub-agent searches its region's policy docs independently -> Each Responds with findings -> Parent aggregates into unified compliance report. Updating US rules doesn't require touching the parent workflow.
Branching Design Rules critical constraints
Three binding rules for all branching:

Branch-First Routing (Tyler's rule)
Branch on raw search output, never on Think interpretation. Do not insert a Think step between Search and Branch. Think output is non-deterministic and may reclassify, soften, or alter the routing signal.

Correct: Search -> Branch -> [per-branch Think steps]
Wrong: Search -> Think -> Branch
Branching on Deterministic Computation
When a Branch depends on calculated values (dates, scores, thresholds), route the computation through a Custom Action BEFORE the Branch step. Never use Think to produce numeric values for branch conditions - LLM arithmetic is unreliable.

Correct: Custom Action (compute) -> Branch (on result)
Wrong: Think (compute and decide) -> Branch
Branch Depth and Convergence
Max 3 levels of nesting. If deeper, flatten the structure or delegate inner branches to a sub-agent.

Convergence steps must handle missing inputs from branches that didn't fire. Check each dependency's status with a sentinel value before including its output. Don't assume every branch ran.
Sub-Agent Decision Framework when to delegate
Use a sub-agent when:
  • Memory isolation is needed (sub-agent context doesn't pollute parent)
  • Batch processing pattern (CSV Splitter loop)
  • Modular domain encapsulation (updating sub-agent doesn't require rebuilding parent)
  • Reusable across multiple parent workflows
Do NOT use a sub-agent when:
  • Parent needs intermediate outputs (only Respond returns)
  • Task is 1-2 steps with tight coupling to parent context
  • The overhead of a separate agent exceeds the encapsulation benefit
Scoping rules: Single purpose, max 2 nesting levels, branch logic inside sub-agents to avoid duplication across parent branches. Start with "triage agent plus one or two specialists" - don't over-architect.

Review Key Anti-Patterns (Tyler + Community)

Top 5 anti-patterns to review with Tyler. These are the most common failures in Agent Factory output and represent the highest-value review items.
1. Plan and Execute for prescriptive workflows most common mistake
Wrong: Using Plan and Execute when the workflow has defined inputs, expected output format, and prescriptive steps.
Right: Use Search + Think + Respond (Cohesive Synthesis pattern).
Why it matters: Plan and Execute is non-deterministic. For prescriptive workflows, you want Think, which is controllable and reads dependency outputs via memory.
2. Think step between Search and Branch Tyler's rule
Wrong: Search -> Think (interpret) -> Branch
Right: Search -> Branch -> [per-branch Think steps]
Why it matters: Think may reclassify, soften, or alter the routing signal. Branch on raw search output to preserve deterministic routing.
3. Think for branch-routing computation unreliable
Wrong: Think step calculates a score/date/threshold, Branch reads that value.
Right: Custom Action computes the value, Branch reads the deterministic result.
Why it matters: LLM arithmetic is unreliable. A Custom Action is deterministic.
4. TEXT inputs for constrained fields UI problem
Wrong: TEXT input for locations, departments, job levels, or any field with a known set of valid values.
Right: SELECT dropdown with the valid options.
Why it matters: Free text introduces typos and variations that break downstream classification and branching.
5. Deep branch nesting without sub-agents complexity trap
Wrong: 4+ levels of nested branching in a single workflow.
Right: Max 3 levels. Delegate inner branches to sub-agents.
Why it matters: Deep nesting creates maintenance nightmares and makes convergence steps fragile. Sub-agents encapsulate complexity with memory isolation.
More anti-patterns from community practice community-patterns-slim.md
  • Silent context truncation: Glean auto-truncates tokens with no indicator. Design with progressive memory scoping.
  • Read Document token bloat: Full-doc reads exhaust context. Use snippet-based Company Search when possible.
  • Large PDF failure: ~1,000-page PDFs fail in agents. Split or extract sections first.
  • 8K character limit: Hard limit per instructionTemplate. Move stable conventions to reference docs, split behavior across steps.
  • OAuth switch breaks agents: Changing auth methods globally broke existing Google-connected agents.
  • Slack bot limitation: Agents do NOT respond to bot/workflow messages. Human must initiate, or use Agent API.

Reference Quick Reference Tables

Build Classes

Class Name Mode Trigger Build Output When to Use
A1 Assistant Auto Chat Paste-ready brief Broad Q&A, summarization, drafting
"Help me think through this PRD" - synthesis not execution, variable sources, follow-up questions matter
A2 Assistant + Routing Auto Chat Routing + agent specs Single front door, 2+ domains
Company-wide help desk: routes HR questions to benefits agent, IT questions to support agent, facilities to office agent
G1 Conversational Agent Auto Chat Paste-ready brief Domain chat, narrow KB, decision logic
Deal Desk booking policy Q&A - narrow domain, classification logic, different response paths by deal type
G2 Input Form Agent Workflow Form Importable JSON Structured inputs, sequential steps
JD Generator - user fills role/level/location form, agent searches policies, generates standardized job description
G3 Scheduled Agent Workflow Schedule JSON + schedule Time-triggered, no user initiation
Weekly compliance digest - every Monday, searches recent policy changes, generates summary, posts to Slack channel
G4 Content-Triggered Workflow Event JSON + trigger File/folder event triggers
Contract review agent - when new PDF lands in Contracts Drive folder, extracts terms, checks against policy, flags risks
S1 Skill Beta AI-routed SKILL.md Narrow reusable single-task
Severance calculator - fixed tool sequence (read agreement, calculate package, format output), reusable across HR agents
N1 Not Ready None -- Gap summary Missing sources, unresolved governance
"Automate the budget approval process" - but no budget data in Glean, no approval API, no defined process

Architecture Patterns

# Pattern Flow Selection Signal
1 Cohesive Synthesis Search + Think + Respond Prescriptive: known inputs, defined outputs
2 Decision Tree Pipeline [Classify+Branch+Validate]* 3+ decision stages with STOP/REVIEW gates
3 Conditional Enterprise Classify+Branch+Per-type Request type determines different paths
4 Document Generator Gather+Generate+Deliver Template-based output from gathered data
5 Dynamic Research Plan and Execute Genuinely exploratory (rare)
6 Single-Step One block Trivial, no orchestration needed

Orchestration Decision Matrix

Criterion Skill Custom Action Action Pack Sub-Agent
Reusable across agents? Yes (company-wide) Yes (global) Yes (system-wide) Yes (published)
External side effects? No Yes (API call) Yes (system write) Depends
Structured I/O? No (AI-routed) Yes (OpenAPI) Yes (fixed params) Yes (form/memory)
Memory isolation? N/A No No Yes
Token cost? Low (~100) Minimal Minimal High (full exec)
Deterministic? No Yes Yes Depends