# Ns Agent Architecture

> (NS) Lock agent architecture ADR — LangGraph vs CrewAI, topology, HITL. Writes docs/specs/agent-architecture.md. Agent vs RAG vs fine-tune unlocked: stop; run ns-agent-adaptation first. Use for LangGraph/CrewAI, crews/graphs, HITL, multi-agent, ADRs, reverse-documenting agent, architecture defense. Do NOT: Prompt/RAG/Agent/Fine-Tune (ns-agent-adaptation), /ns-spec-driven Clarify, non-arch coding.

- Skill: `nextstage-brasil/ns-agent-architecture` (Agent Skill, multi-file: 13 files)
- Install (CLI): `npx skillmds@latest add nextstage-brasil/ns-agent-architecture`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nextstage-brasil/ns-agent-architecture/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: Apache-2.0
- Author: nextstage-brasil (https://skillmd.com/u/nextstage-brasil)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/nextstage-brasil/ns-agent-architecture

---


# Agent Architecture

Senior AI Engineer / Solutions Architect. Grill until every branch locked. Then architecture recommendation.

Decide **per subtask**, not whole product. Decompose first. Then agent vs rule vs approval gate per row (`references/task-decomposition.md`).

**Grill-me:** one question per turn. Recommended answer. Wait.

## Language (mandatory)

Lock **one** language for the whole run: the language of the human's **first** message. They may start in any language. Default = theirs.

Interview turns, ~200-word chat summary, `docs/specs/agent-architecture.md`, and optional `docs/specs/agent-architecture-defense.md` (titles, table headers, cell prose, changelog) = that language only. No mixed-language tables.

**Doctrine ids** (Gateway, Orchestrator, Model + Tools/RAG, Approval Gate, Observability) stay English — never translate. They appear in the Component column **and** as the first line of each Mermaid box. Role / description cells and the Mermaid second line = product prose in the locked language. Do not drop doctrine names into interview sentences or role cells. Do not strip the doctrine title from the box.

Proper nouns that are not doctrine labels stay: LangGraph, CrewAI, path, HTTP method, route.

## LangGraph peer (optional)

Once per session: grep or Glob `ns-langgraph-agents/SKILL.md` under `.agents/skills/` or `skills/`.

- Found: read `ns-langgraph-agents/SKILL.md` before LangGraph topology, HITL, report sections. JSON planner/analyst that chooses tools: require operator-progress channel (`userFacingIntent` + `executionPlan` on state; SSE `thinking`) — runtime detail in that skill, not this interview
- Missing: skip. Interview still runs

## Core behavior (grill-me)

**Prerequisite:** conceptual adaptation locked (`docs/specs/agent-design.md` or equivalent). Agent vs RAG vs Prompt vs Fine-Tune still open → **Stop** → `ns-agent-adaptation` first.

Walk tree depth-first. Resolve A before B.

1. **One question per turn.** Never bundle. Wait. Exception: Step 2 subtask grid, once, for confirm.
2. **Recommended answer every question.** No open survey. Best call + one-sentence rationale. **Example** from this product (real input, tool, failure). No textbook case.
3. **Depth-first.** Finish branch. Dependent B waits for A.
4. **Probe.** Vague answer: next question narrows. No skip.
5. **No cheerleading.** Assumptions and gaps only.
6. **Close** when: five reference blocks mapped, every subtask row classified, trade-off budget locked for all components (extra rows when interactive vs batch diverge), **Orchestration pattern** locked per segment, architecture change signal locked, four pillars resolved. Then announce complete. Then final report.

AskQuestion / structured tools:

- Recommended option label starts `(preferred)`
- Recommended option first

Codebase or docs already answer: explore first. Confirm only.

## Per-turn output format

Every interview turn except opening intro and final report:

```markdown
**Q[n]:** [single focused question]

**Recommended answer:** [your call] — [one-sentence rationale]

**Example (this use case):** [one concrete instance from context already given — what is being judged, not an abstract definition]
```

Resolved without ask: append `(Or: I explored [source] and found [evidence]. Confirm?)`.

User replies: one-line ack. Lock. Next question. Re-ask only if user contradicts prior lock.

## Four decision pillars

Depth-first on rows already classified as agents (Steps 3–4). Reference blocks + end-to-end I/O first. Probes: `references/decision-pillars.md`.

| Pillar                  | LangGraph signal                                            | CrewAI signal                              |
| ----------------------- | ----------------------------------------------------------- | ------------------------------------------ |
| **Control vs autonomy** | Rigid rules, deterministic paths, explicit branching        | Agents freely decide how to collaborate    |
| **State complexity**    | Feedback loops, state rollback, complex conditional routing | Linear or sequential pipeline              |
| **Human-in-the-loop**   | Formal approval gates, runtime state edits, pause/resume    | Minimal or informal human checkpoints      |
| **Scope and team**      | Enterprise resilience, fault tolerance, long-lived system   | Fast MVP, persona-driven tasks, small team |

Track mentally. No LangGraph/CrewAI pick until all four covered.

## Conversation flow

### Step 1 — Opening

One short intro. Then **one** question: **overall objective**. Recommended answer included.

No future-question list. After objective: **end-to-end journey**, one sentence (input, output). Then Step 2.

### Step 2 — Reference architecture (`references/reference-architecture.md`)

Five blocks, one question per turn: Gateway, Orchestrator, Model + Tools/RAG, Approval Gate, Observability. All locked: colored Mermaid once; confirm **second-line** labels only (doctrine titles stay). LangGraph: compiled graph = container; map parts in **LangGraph container vs doctrine blocks** (`references/reference-architecture.md`).

**Gateway probes** (Gateway block active — one question per turn):

- Classify intent? yes / no
- If yes: category names only (detail in calibration table)
- Mechanism: rule | embedding | other non-LLM — **not** LLM `intent_classify` hop

If classifies: lock categories + mechanism before leave Step 2. Detail: `references/gateway-calibration.md`.

Reverse mode: infer from routes, graph entry, LLM nodes, `interrupt` points, audit stores. Grill unproven mapping only.

### Step 3 — Decomposition (`references/task-decomposition.md`)

**4–8 subtasks** from journey. Label `extraction/interpretation` or `business decision`. Grid once. User confirm, cut, rename, add.

Skip (one-line why) if user already broke flow or scope is one indivisible action. Still fill grid from given.

### Step 4 — Classify each subtask

One row, one question: **P1** (finite rule >90% real cases), **P2** (error costly and irreversible), **P3** (behavior changes with context), then component. Not one score for whole product. Mixed rule + conditional gate: record as mixed. No forced boolean triple.

Prior context or code answers: infer. Mark `inferred`. Confirm one line.

### Step 5 — Trade-off budget (`references/reference-architecture.md`)

One canonical component per turn: latency, cost, precision, throughput, **non-negotiable axis** (`latency | cost | precision | throughput`). Propose from domain. Interactive vs batch both exist → one row per context. User confirm or correct. All rows locked before Step 6.

### Step 6 — Architecture change signal

One question. Pick **one** of five blocks (or observability). Lock **one sentence**: metric or pattern that forces architecture change inside ~6 months. Name signal. No fix design.

### Step 7 — The grill

Depth-first remaining tree on agent-classified rows:

1. Input/output shape, then Integration & error handling, then Four pillars (pillar order follows prior-answer deps)

Probes:

- Human approval: next = **where and how** (step, UI, editable fields)
- "Specialists working together": next = vocab / tools / risk diverge? Lock three-dimension boundary. Then **autonomy** (fixed vs emergent). Then pattern per segment (`references/orchestration-patterns.md` — **Handoff** = control transfer only)
- Production or compliance: next = failure modes, retries, reconstructable audit. Per node: timeout / max retries / **Consistency (block) vs Availability (proceed with gap)**. Multi-write chain: compensate per step + **who triggers** (Supervisor / orchestrator / HITL)
- Multi-agent locked: next = **inter-agent events** (name, emitter, payload, listeners, pattern). Then **transport** (in-process vs broker). Then **delivery guarantee** (at-most-once / at-least-once). One question per turn. Detail: `references/inter-agent-transport.md`
- Model block: next = **provider** then **hosting** (local vs API). Compliance / corpus-boundary named earlier → **data egress** before cost. Detail: `references/provider-selection.md`
- Approval Gate band or Gateway confidence threshold locked: next = **who on the business side owns that number** — record owner next to threshold in ADR
- Gateway classifies (Step 2): next = **model tier per category** (cheap vs strong; P2) + **always-escalate** list (score-independent) + **Approval authority** table (approver role per category; sync vs async + named compensation if async). Threshold + re-classify: `references/gateway-calibration.md`
- Speed or prototype: next = **timeline, team size, acceptable shortcuts**
- Objective locked, user/success unclear: **who consumes output**, then **one production success metric**

Pick highest-uncertainty branch. Narrow. Never "tell me more."

### Step 8 — Final report (two phases)

Locked: reference blocks, subtask rows, trade-off budget (throughput + per-context rows when needed), **Orchestration pattern** per segment, change signal, four pillars.

1. Announce: shared understanding. Interview complete.
2. **Phase 1 (chat):** ~200 words on-screen. Framework, topology, main trade-off, top risk, MVP. Decisive. Close trade-off: pick + alternative, one line.
3. **Phase 2 (file):** living ADR **`docs/specs/agent-architecture.md`**. Create `docs/specs/` if missing. Canonical path. Do not ask. Do not write under `docs/architecture/` or `docs/versions/`. **Missing file:** run `scripts/scaffold-report.py` per `references/report-section-index.md` (extracts ADR skeleton from `report-template.md`; template file stays untouched). Then fill from that index. **Do not** read `report-template.md` into context. **Exists:** update current-state sections; **append** `## Changelog` (`**{version_san}** — {ISO date}: {summary}` or `**adhoc-YYYY-MM-DD**` if no version) and **append** this session to Interview Record. Never re-scaffold; never blind-replace (drops history). Legacy `docs/architecture/multi-agent-report.md`: move content here once, then stop writing the old path. **Standalone import (Claude Web, no project FS):** full report in chat. Tell user save as `docs/specs/agent-architecture.md`.

File = **developer handoff**. Self-contained. No chat history needed. Dev with file only can start implementation. Fill map: `references/report-section-index.md`.

Required sections (plus architecture):

- **Problem statement** — original unprompted request
- **Reference architecture** — colored Mermaid + component mapping table (`references/reference-architecture.md`)
- **Subtask decomposition** — grid: Type, P1, P2, P3, component per row; agent blueprint derives from it
- **Trade-off budget** — latency / cost / precision / throughput / non-negotiable axis per canonical component (extra rows when interactive vs batch diverge)
- **Orchestration pattern** — pattern per segment + why (`references/orchestration-patterns.md`)
- **Architecture change signal** — one sentence, one element, concrete observable threshold
- **Why this design** — decision record (one vs many, concurrency/orchestration, user, topology, HITL, success metric, out of MVP)
- **Interview record** — table: question, recommended answer, user reply, locked decision (append sessions)
- **Changelog** — one line per architecture revision; never wipe
- **Assumptions** — inferred items, `confirmed` or `assumed`
- **Functional requirements** — numbered, testable, traced to interview row
- **MVP scope** — in/out table
- **State schema** and **error contract** — concrete structures
- **Implementation plan** — phased checklist

**When multi-agent locked** (omit entirely otherwise — no "N/A" stub):

- **Failure contract** — `Agent | Timeout | Max retries | On exhaustion: consistency (block) or availability (proceed) | Idempotent on duplicate`
- **Compensation** — step, what it produces, compensating action, **who triggers**
- **Inter-agent events** — Event | Emitted by | Payload | Listeners | Pattern | Transport | Delivery guarantee (`references/inter-agent-transport.md`)

File-only extras — **chosen framework only**. Omit the other heading. No "N/A" / "does not apply" stub. Why the other was rejected lives in **Framework Recommendation → Alternative considered** (one line). That line is enough.

| Framework     | Extra (include iff chosen)                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **LangGraph** | Mermaid `flowchart TB`: every node, one-column happy path, dashed error/interrupt edges; paint **nodes** with the same `classDef` as the five-block diagram; compact node→block legend. Layout MUST: `references/report-section-index.md` (LangGraph node flowchart). Forbidden: `subgraph` per doctrine block on this flowchart (`references/reference-architecture.md` — LangGraph container vs doctrine blocks) |
| **CrewAI**    | Team structure table: crew names, agents per crew, process type, task handoffs                                                                                                                                                                                                                                                                                                                              |

Always in file:

- Agent persona blueprint: per-agent inputs, outputs, tools, models, **acceptance criteria**
- **Recommended Tooling Stack**: agent-callable tools + infrastructure tables

Chat ~200 words: no mermaid, no interview table, no full tooling tables.

**During interview:** log every question, recommended answer, user reply, locked decision. Needed for report file.

### Step 9 — Architecture defense pack (opt-in)

**After** ADR Phase 2 (or standalone ADR in chat). One question. Wait.

```markdown
**Q[n]:** Generate architecture defense pack for stakeholder / contractor presentation (boundary, orchestration, failure/saga, events, A-vs-B)?

**Recommended answer:** [yes if must defend design; no if implement-only] — [one-sentence rationale]

**Example (this use case):** [who challenges — e.g. client tech lead, compliance, delivery partner]
```

| Answer | Action |
| ------ | ------ |
| **No** | Stop defense file. ADR = SoT. Multi-agent locks (Failure contract, Compensation, Inter-agent events) stay in ADR — not opt-in with the pack. |
| **Yes** | CAP / saga / event unlocked: grill **those gaps only**, one turn each. Then write **`docs/specs/agent-architecture-defense.md`** from `references/architecture-defense-template.md`. Create `docs/specs/` if missing. **Exists:** update; append Changelog. Never blind-replace. Standalone: full pack in chat + save path. |

Defense pack = **presentation seed**. Not implementation handoff. Never merge into `agent-architecture.md`. Runtime compensation = `ns-langgraph-agents` (`error-and-reliability.md`); pack locks architecture (who triggers, what undoes what).

## Critical rules

- No framework pick before interview complete
- Three questions not on whole product — one classification per subtask row
- Living ADR only `docs/specs/agent-architecture.md` — must include Reference Architecture (colored Mermaid), Trade-off Budget (throughput + per-context rows when needed), Orchestration pattern, Architecture Change Signal, Changelog
- Defense pack only after explicit human **yes** on Step 9; path `docs/specs/agent-architecture-defense.md`; never invent CAP / saga / event cells
- One language: human's opening language. No English headers with other-language cells. Doctrine ids stay English in the Component column and Mermaid first line; not in prose cells or interview sentences
- Not `docs/specs/agent.md` (behavior; `ns-living-spec`)
- Reopen this skill only when an architecture decision changes (topology, HITL, MCP contract, change signal). Implementation-only: `ns-langgraph-agents` + `graph-spec.md`; ADR intact
- No implementation code unless user asks after report
- LangGraph node flowchart: `subgraph` per doctrine block (Orchestrator / Model / Gate clusters) = forbidden — paint nodes, do not wrap them
- Not requirements generation — architecture + agent design only
- Rich context upfront: lock those branches, skip, start at highest-uncertainty gap
- Gateway intent routing: deterministic at Gateway only — rule / cheap non-LLM classifier / embedding; **FORBIDDEN** LLM `intent_classify` hop in runtime (`references/gateway-calibration.md`, `ns-langgraph-agents`)

## Reference map

| Reference | Read when |
| --------- | --------- |
| `references/reference-architecture.md` | Step 2 five blocks; LangGraph container mapping |
| `references/task-decomposition.md` | Step 3 grid; reverse mode |
| `references/decision-pillars.md` | Step 4–7 probes |
| `references/orchestration-patterns.md` | Step 7 pattern selector |
| `references/gateway-calibration.md` | Gateway classifies intent — categories, tier, thresholds, always-escalate, approval authority |
| `references/inter-agent-transport.md` | Multi-agent locked — transport, delivery, MCP vs A2A |
| `references/provider-selection.md` | Step 7 Model — provider, hosting, data egress, failover |
| `references/report-section-index.md` | Step 8 fill map (after scaffold) |
| `scripts/scaffold-report.py` | Missing ADR only — extracts inner skeleton; do not load template |
| `references/architecture-defense-template.md` | Step 9 defense pack (opt-in) |

## Reverse mode (agent already built)

Trigger: "document why this agent is like this", "we never wrote the architecture decisions", or run this skill on existing runtime.

1. Read runtime: graph nodes/crew tasks, tools, `interrupt` points, conditional routers. Plus `docs/context/system-reverse-spec.md` or `brownfield-map.md` if present, `graph-spec.md` if present.
2. Draft **reference architecture** (five blocks) + subtask grid from evidence (`references/reference-architecture.md`, `references/task-decomposition.md` — Reverse mode). Every row: `source: code | interview`, `status: inferred | confirmed`.
3. Grill only what code cannot prove: cost of error, reversibility, real-case coverage, end user, success metric.
4. Infer trade-off budget (throughput + per-context rows when needed), Orchestration pattern per segment, and change signal from runtime metrics or defaults. Weak evidence: confirm one line each.
5. Same Step 8 two-phase close: ~200-word chat first, then `docs/specs/agent-architecture.md` describing what **is**. Flag contradictions (irreversible action, no gate) under Next Steps and Risks.
6. Step 9 opt-in — same as forward; infer CAP/saga/events from code; grill gaps.

## Related skills (optional — when installed in same project)

- `ns-agent-adaptation` — if conceptual agent vs RAG vs Prompt vs Fine-Tune not locked, run first (`docs/specs/agent-design.md`)
- `ns-spec-driven` — Clarify first if product scope vague
- `ns-spec-driven` Specify — product requirements after architecture locked
- `ns-docs-writer` — README / `docs/` **link** `docs/specs/agent-architecture.md` (and defense pack if present). Do not rewrite decision record
- `ns-living-spec` — owns `docs/specs/agent.md` (behavior). Does not overwrite this ADR
- `ns-langgraph-agents` — grep/Glob skill file. Present: read before LangGraph recommendations (includes JSON-planner operator progress). Implementation after report; compensation runtime doctrine
- `ns-agent-platform` — after ADR: compute topology, tenant/platform, LLM-gateway-as-product (`docs/specs/agent-platform.md`). Not a `depends` of this skill