Build Decision Flow

Keyword-scores the PRD against 10 built-in patterns and returns the top 3 as hints. Each pattern carries a keyword list (8–10 terms); the matcher counts hits in the lowercased PRD. Score > 0 is a match. Limitation: keyword matching is shallow — the LLM in Phase 0 makes the real decision; the matcher only primes it.

• 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

Any one of these triggers an automatic FAIL:

• Required data source has no connector AND no viable workaround (no remote template, API action, or export path)
• Core workflow requires storing or caching data outside the platform
• Use case requires real-time bidirectional sync
• Problem is better solved by process change, policy change, or a non-AI tool
• Problem-solution fit is misaligned

Conditional pass is appropriate only when all connectors exist and the gaps are about PRD clarity, not platform capability.

Score each 0–2, then sum.

Interpretation: 0–4 → A1. 5–9 → A1 or lean A2. 10–13 → agent (G1–G4 by trigger). 14–16 → A2.

These override the numeric score when triggered.

• Force A1 when mostly true: broad Q&A / synthesis is the value; no strict process; no action in another system; freeform conversation helps; retrieval can stay dynamic.
• Force agent (G1–G4) when any are true: repeatable steps; deterministic inputs + structured outputs; authoritative docs + system logic; must classify and respond differently; must route / escalate; requires system actions; must run in Slack, scheduled, or triggered.
• Force A2 when all are true: users shouldn’t pick the specialist; 2+ domain use cases; real quality gain from specialization; a single front door is wanted.

PRD-prescribed override: if the PRD prescribes 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 re-evaluates the Phase 0 classification using 12 gap categories; category 12 validates the class.

• A1 recommended? Do requirements need repeatable steps, deterministic outputs, or system actions? If yes, upgrade to G1/G2.
• A2 recommended? Are there really 2+ distinct domains? If not, downgrade to A1/G1.
• G1 recommended? Need branching, gates, multi-step data flow, or >20 actions? If yes, upgrade to G2.
• G2/G3/G4 recommended? Is every step necessary, or could it be a single instruction block? If over-engineered, downgrade to G1/A1.

Rule: always choose the lowest-complexity class that reliably solves the problem.

• Block — red UI, requires an explicit checkbox to continue. Critical gaps that may produce a broken agent.
• Caution — amber UI, standard approve / reject. Gaps exist but are manageable.
• Proceed — green UI. No significant gaps.

The user can approve and continue, reject and halt, or override the classification before proceeding.

Phase 2A — instruction design: write the instruction block (scope, persona, knowledge sources, response format). Action budget — max 20 actions per agent; MCP tools consume action slots, so split or switch to Workflow Mode if exceeded. Design for adoption — don’t over-specify behavior that should adapt through traces. Context health check for distraction, clash, confusion.

Phase 3A — build brief: a paste-ready configuration for the UI — instructions, knowledge sources, conversation starters, action selections, LLM config. For A2, adds routing conditions and agent specs per domain. Auto Mode agents cannot be imported via JSON — manual paste only.

Phase 2 — workflow design: select the base architecture pattern (Layer 3), apply hybrid modifiers if needed, design branching architecture, sub-agent decisions, MCP integration. Context health check and skill/action detection. Output: step-by-step architecture with types, dependencies, tool assignments.

Phase 3 — task instructions: write each step’s instruction template using the Goal–Return–Format–Warnings–Context framework. Target 4,000 chars per step (warn at 6K, hard limit 8K). Wire variable references [[step_id]] and [[field_name]].

Phase 4 — generate outputs: produce importable JSON matching the exact schema — UUIDs per step, correct type (BRANCH / TOOL / AGENT), memoryConfig: ALL_DEPENDENCIES. Post-build validation: schema checks, dependency integrity, variable syntax, budget audit.

Each phase gets only the docs it needs (token-budget management), controlled by the PHASE_KNOWLEDGE map. Phase 3 and 4 use the full platform reference (~45K chars) because they emit JSON; all others use the slim version (~9K chars).

• 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, platform-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

Flow: Search + Think + Respond. Use when: known inputs, defined outputs, standardized process. Think is the synthesis step — deterministic and controllable, it reads dependency outputs via memory and compiles a structured result. Do not use Plan and Execute here; that is only for genuinely exploratory work.

Flow: [Classify + Branch + Validate]* + Recommend. Use when: 3+ decision stages with STOP/REVIEW gates and terminal outcomes. Each classification is a Think step, each gate a Branch step, terminal outcomes get dedicated Respond steps, and the final recommendation is a Think step consuming validated outputs. Critical rule: gate enforcement must be structural (Branch steps), not behavioral. A decision-tree PRD with 3+ stages must produce multiple steps — a single TOOL step holding all the logic is always wrong.

Flow: Classify + Branch + per-type processing. Use when: the request type determines entirely different paths, actions, output formats, or compliance rules. First step classifies type; a branch routes to type-specific sub-workflows; a convergence step merges outputs.

Flow: Gather data + Generate + Deliver. Use when: output is a formatted deliverable built from a template. The intelligence is in gathering the right data and filling sections accurately, not in deciding what to do.

Flow: Plan and Execute. Use only when the problem is genuinely open-ended with no known path — source material may be thin and the agent must autonomously re-query, the workflow is conversational and exploratory, and no defined output format exists. Never for defined inputs plus expected output, prescriptive steps, or standardized documents — those are Think (Pattern 1) workflows.

Flow: one instruction block. Use when: trivial 1–2 step workflows where orchestration adds no value. Note: if a workflow seems single-step but has decision logic or classification, it belongs in Pattern 1 or 2. Don’t collapse complexity into one step just because it fits in 8K characters.

Hybrid modifiers close the gap between deterministic and non-deterministic steps. Apply one or more when the base pattern doesn’t fully cover the workflow.

• Compute Bridge — a Custom Action step before a Branch step, when the branch needs exact computed values. Never use Think to compute routing values (non-deterministic). Example: days-until-renewal computed by a Custom Action; Think might say “about a month” and misroute.
• Validation Gate — a Think step (FACTUAL) between synthesis and delivery when output is externally visible or multi-step. Checks completeness, consistency, compliance. Example: a QA step after the JD generator confirms sections, comp range, and EEO statement.
• External Orchestration Bridge — a webhook or MCP call between deterministic steps. Constraint: MCP tools only exist in Plan and Execute and Auto Mode, not explicit workflow steps — use Custom Actions or webhooks in Workflow Mode. Example: a PO that calls an approval API, then branches on approved / denied / pending.
• Memory Isolation Sandwich — a sub-agent within the parent workflow for batch processing or modular encapsulation. Only the Respond step returns to the parent; no native parent-to-child variable mapping. Example: a CSV Splitter spawns per-row sub-agents that enrich data; or parallel US/EU/APAC compliance sub-agents aggregate into one report.

Branch-first routing — branch on raw search output, never on Think interpretation. Think may reclassify, soften, or alter the routing signal.

Correct: Search → Branch → per-branch Think.  Wrong: Search → Think → Branch.

Deterministic computation — route calculated values through a Custom Action before the Branch. LLM arithmetic is unreliable.

Correct: Custom Action (compute) → Branch.  Wrong: Think (compute and decide) → Branch.

Depth and convergence — max 3 levels of nesting; deeper means flatten 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 before including its output.

Use a sub-agent when: memory isolation matters (no context pollution); batch processing (CSV Splitter); modular domain encapsulation (updating it doesn’t rebuild the parent); reusable across parents.

Don’t use one when: the parent needs intermediate outputs (only Respond returns); the task is 1–2 steps tightly coupled to parent context; the overhead exceeds the encapsulation benefit.

Scoping: single purpose, max 2 nesting levels, branch logic inside sub-agents to avoid duplication. Start with “triage agent plus one or two specialists.” Don’t over-architect.

Wrong: Plan and Execute with defined inputs, expected output, prescriptive steps. Right: Search + Think + Respond. Plan and Execute is non-deterministic; Think is controllable and reads dependencies via memory.

Wrong: Search → Think (interpret) → Branch. Right: Search → Branch → per-branch Think. Think may reclassify or soften the routing signal; branch on raw output.

Wrong: Think computes a score / date / threshold that Branch reads. Right: a Custom Action computes it; Branch reads the deterministic result.

Wrong: free text for locations, departments, job levels. Right: a SELECT with the valid options. Typos and variations break downstream classification and branching.

Wrong: 4+ nested branch levels in one workflow. Right: max 3; delegate inner branches to sub-agents. Deep nesting makes convergence fragile.

• Silent context truncation — the platform auto-truncates tokens with no indicator. Design with progressive memory scoping.
• Read-document token bloat — full-doc reads exhaust context; use snippet-based search.
• Large-PDF failure — ~1,000-page PDFs fail in agents; split or extract sections first.
• 8K character limit — hard limit per instruction template. Move stable conventions to reference docs.
• OAuth switches break agents — changing auth methods globally broke existing connected agents.
• Slack bot limitation — agents don’t respond to bot / workflow messages. A human initiates, or use the Agent API.