> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vinmake.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Implementation Tiers

> When to build a skill, when to build a workflow, when to build a full agent

# Implementation Tiers

Brain uses three implementation tiers. The tier choice for each feature is
deliberate. It's about matching the tool to the problem — using a full agent for a
deterministic task wastes tokens and adds hallucination risk; using a skill for
multi-step reasoning produces inconsistent results.

## Tier 1 — Simple LLM + skill

A `skill.md` file with a clear prompt and small input/output contract. Stateless,
deterministic-leaning, fast to iterate.

**Use for:**

* Generate a quotation with a fixed markup
* Ask for missing client fields
* Draft a quotation email
* Summarize a single email
* Classify an email topic

**Pros:** fast to build, easy to iterate, low engineering complexity, ideal for MVP.

**Cons:** not suited for long-running tasks; limited state management; harder to
coordinate multiple steps.

## Tier 2 — LangGraph workflow

A multi-step state machine with explicit nodes for AI steps, tool calls, and human
approval gates. Each transition is observable and resumable.

**Use for:**

* Email-to-style creation (intake → classify → extract → duplicate-check → approve → write)
* Client creation approval flow
* Duplicate check workflow
* Quotation generation workflow
* Any human-in-the-loop pipeline

**Pros:** clear states, good for human-in-the-loop, easy to debug, supports
branching logic, strong observability.

**Cons:** more engineering setup; requires workflow design up front; less flexible
than full agent autonomy.

## Tier 3 — Full agent with tools and environment

A reasoning loop with multiple tools, document access, image analysis, and the
ability to plan multi-step actions. Used when the task can't be reduced to a
deterministic flow.

**Use for:**

* Tech pack → BOM (parse PDFs, parse Excel, vision analysis, garment template
  matching)
* Manager lifecycle queries (multi-source retrieval, structured output)
* Pricing intelligence (external search + internal history + client profile)
* End-to-end oversight agent (continuous monitoring, risk classification, alerting)

**Pros:** handles complex analysis, multi-tool, multimodal; more autonomous.

**Cons:** higher hallucination risk, requires stricter guardrails, needs strong
observability, needs source attribution, more expensive to run.

## Tier recommendation by feature

| Feature                        | Tier                                  |
| ------------------------------ | ------------------------------------- |
| Fixed markup quotation         | Tier 1 — Skill                        |
| Draft quotation email          | Tier 1 — Skill                        |
| Missing field prompts          | Tier 1 — Skill                        |
| Email topic classification     | Tier 1 — Skill                        |
| Client creation                | Tier 2 — Workflow                     |
| Manual style creation          | Tier 2 — Workflow                     |
| Email-triggered style creation | Tier 2 — Workflow                     |
| Duplicate style check          | Tier 2 + DB tool                      |
| True cost first draft          | Tier 2 / Tier 3 hybrid                |
| Tech pack → BOM                | **Tier 3 — Agent**                    |
| Material matching              | Tier 3 — Agent                        |
| Pricing intelligence           | Tier 3 — Agent                        |
| Manager style lifecycle query  | Tier 3 — Agent                        |
| Pipeline oversight             | Tier 3 — Agent + scheduled monitoring |
| Approval inbox                 | Tier 2 workflow infrastructure        |

## How tiers interact

A high-level workflow (Tier 2) often calls lower-level skills (Tier 1) as steps and
delegates complex sub-problems to agents (Tier 3). For example:

```text theme={null}
Email-to-Style (Tier 2 workflow)
  ├── Classify email topic (Tier 1 skill)
  ├── Extract style fields (Tier 1 skill)
  ├── Duplicate check (Tier 2 with DB tool)
  ├── Show draft for approval (human gate)
  └── Write to CutMake (tool call)

After approval, next-step suggestion may chain to:

Tech Pack → BOM (Tier 3 agent)
  ├── PDF parse tool
  ├── Excel parse tool
  ├── Vision tool
  ├── Category template lookup
  └── BOM draft write
```

Each tier is the right tool for a different shape of problem.

## Related

* [Runtime](/brain/staging/architecture/runtime) — what hosts all three tiers
* [Workflows](/brain/staging/workflows/index) — see each feature's tier choice in
  context