ns-langgraph-agents — скилл для Claude Code и Codex
Скилл ns-langgraph-agents для Claude Code, Codex, Cursor и других платформ, который ведёт разработку LangGraph.js agent-api от начального развёртывания до синхронизации graph-spec.
Apache-2.0 171 установок обновлён 2026-10-24
npx skills add nextstage-brasil/skills --skill ns-langgraph-agents -a claude-codeЧто делает ns-langgraph-agents
Скилл берёт на себя «runtime doctrine» — правила размещения файлов, инъекцию промптов и возможностей, синхронизацию graph-spec.md. Для нового agent-api запускается bootstrap-workflow из references/bootstrap-agent-runtime.md; для существующего (brownfield) — сначала чеклист восстановления из references/orphan-recovery-checklist.md, затем уже фичи.
Внутри скилл опирается на ns-harness как зависимость: сессионная загрузка, маршрутизация задач и code-skill-routing уходят туда. Сам ns-langgraph-agents держит справочники по MCP с множеством серверов (references/mcp-complex-access.md), токенам и контекстному окну, adversarial-охране, model-cascade и пользовательской памяти с роутами /memories.
Требуется Node 24+, TypeScript strict и пакет @langchain/langgraph. Для CrewAI, обычных веб-приложений или проектов без agent-api скилл не предназначен — маршрутизация переключит на ns-agent-architecture.
Какие задачи решает
- Развернуть новый LangGraph.js agent-api по bootstrap-workflow
- Подключить MCP-серверы и инструменты к StateGraph
- Восстановить структуру orphaned-рантайма по чеклисту
- Синхронизировать
graph-spec.mdпри изменении топологии или бюджетов - Добавить пользовательскую память с дедукцией и роутами
/memories
Примеры запросов агенту
- Создай новый agent-api на LangGraph.js, следуя bootstrap-workflow из скилла
- Подключи MCP-инструменты к графу и синхронизируй
graph-spec.md - Запусти восстановление orphaned-рантайма по
references/orphan-recovery-checklist.md
Как установить ns-langgraph-agents
1Через Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-langgraph-agents -a claude-code2Вручную: положить файлы
~/.claude/skills/ns-langgraph-agents/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/ns-langgraph-agents/
1Через Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-langgraph-agents -a codex2Вручную: положить файлы
.agents/skills/ns-langgraph-agents/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-langgraph-agents -a cursor2Вручную: положить файлы
.cursor/skills/ns-langgraph-agents/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install nextstage-brasil/skills skills/ns-langgraph-agents2Вручную: положить файлы
.github/skills/ns-langgraph-agents/SKILL.md1Через Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-langgraph-agents -a gemini-cli2Командой платформы
gemini skills install https://github.com/nextstage-brasil/skills --path skills/ns-langgraph-agentsВручную: положить файлы
.devin/skills/ns-langgraph-agents/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-langgraph-agents -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы о ns-langgraph-agents
Как установить ns-langgraph-agents в Claude Code?
Выполните в терминале: npx skills add nextstage-brasil/skills --skill ns-langgraph-agents -a claude-code. После этого скилл будет доступен по пути ~/.claude/skills/ns-langgraph-agents/SKILL.md.
Что делает скилл ns-langgraph-agents?
Скилл задаёт архитектурные правила для LangGraph.js-рантайма: размещение файлов, инъекцию промптов и возможностей, bootstrap нового agent-api, восстановление orphaned-структур и синхронизацию graph-spec.md.
Какие зависимости нужны для работы ns-langgraph-agents?
Node 24+, TypeScript strict, пакет @langchain/langgraph и скилл ns-harness — он подключается автоматически как зависимость через поле depends.
Исходный текст
SKILL.md · Apache-2.0
---
name: ns-langgraph-agents
description: "(NS) LangGraph.js agent-api — bootstrap-agent-runtime, StateGraph, MCP, skill bind/inject, checkpointers, user memory, HITL/SSE. Use for new agent-api, LangGraph graphs, MCP wiring, orphan layout, bind parity, graph-spec sync, or \"fix my LangGraph agent\" / \"wire MCP tools\" / \"translations in the graph\". Do NOT use for CrewAI, generic web apps, or SDD-only with no agent-api."
license: Apache-2.0
metadata:
author: nextstage-brasil
version: "1.20"
depends:
- ns-harness
---
# LangGraph Agents
Production-grade LangGraph.js (Node 24+, TypeScript strict, `@langchain/langgraph`).
Owns **runtime doctrine** — placement, prompt/capability injection, graph-spec sync. Diffs via `ns-coder` or `ns-autonomous`. Framework choice: `ns-agent-architecture`.
## Applicability
| Context | Doctrine strength |
| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Greenfield** agent-api (new LangGraph runtime) | **MUST** follow build workflow gates — dev-chat, budgets, normalize-before-truncate, separate skill cap. Topology: **suggest** `plan_execute` for most MCP/tool-heavy cases — lock in `graph-spec.md`; not a hard rule |
| **Brownfield** existing agent | **RECOMMENDED** migration toward same controls; orphan recovery does not Critical-fail missing topology |
| **Intentional MCP redesign** | Sync `graph-spec.md` + refs in same delivery — treat greenfield MUST for topology/budget/evidence sections touched |
Brownfield open ReAct valid until deliberate topology change. Greenfield MUST = new agent-api + intentional MCP redesign only.
## Routing (read first)
| Signal | Action |
| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| Conceptual design unlocked (agent vs RAG vs fine-tune) | **Stop** → `ns-agent-adaptation` |
| No framework lock / CrewAI requested | **Stop** → `ns-agent-architecture` |
| Orphan / lost structure / layout unclear | Run orphan checklist **before** features (`references/orphan-recovery-checklist.md`) |
| GitLab `ISSUE_URL` or SDD version scope | **Defer** to harness `../../ns-harness/references/code-skill-routing.md` — do not absorb |
| Approved placement/inject plan ready for diff | Hand off to `ns-coder` for implementation — except greenfield **bootstrap copy** (`references/bootstrap-agent-runtime.md`) |
## Boot (mandatory)
See `../../ns-harness/references/session-boot.md` — **complete Session boot (blocking)** there, then:
1. Confirm `{agent_api_root}` and `graph-spec.md` when touching runtime
2. Load placement/inject refs before path decisions (`references/placement-and-domains.md`, `references/prompt-and-capability-injection.md`)
3. Continue this skill
**Success:** placement + inject doctrine + project rules. **Failure:** invented folders or external frameworks.
## When to use
| Situation | Action |
| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Greenfield agent-api (no `{agent_api_root}/package.json`) | **Build workflow** Phase 0 then Phase 1 bootstrap — `references/bootstrap-agent-runtime.md` |
| Brownfield / orphaned runtime | Run **Orphan recovery** (`references/orphan-recovery-checklist.md`) before features |
| New file / unclear folder | **Placement Decision Block** + `references/placement-and-domains.md` |
| System prompt / skill inject / bind | **Prompt/Capability plan** + `references/prompt-and-capability-injection.md` |
| Topology / state / capabilities / `guard_fail_mode` change | **Spec Sync Gate** — update `graph-spec.md` in the same delivery |
| MCP with many servers/tools | Read `references/mcp-complex-access.md` + `references/capability-governance.md` |
| Token blow-up / slow turns | Read `references/context-window-and-tokens.md` |
| Agent must remember the user (preferences, terms, CRUD) | Read `references/user-memory.md` — per-user store, deduce-and-inform, `/memories` routes |
| Untrusted input / injection / claimed authority | Read `references/guardrail-and-adversarial.md` — scope classifier; scaffold fail-open ≠ doctrine |
| Cost-sensitive high volume / model tier / cache | Read `references/model-cascade-and-cache.md` |
| Provider message/reasoning quirks | Read `references/message-content-blocks.md` |
| HITL / streaming UX | Read `references/streaming-and-hitl.md` |
| JSON planner / analyst chooses tools | Operator-progress channel — `templates/contracts/planner-contract.md` + `references/streaming-and-hitl.md` |
| Prompt change / repeated hops / loop / "fixed" claim | Read `references/turn-flow-gates.md` — flow-first, terminal, repetition, evidence gates |
| Evals before merge | Read `references/evals-and-gates.md` |
## Core doctrine
LangGraph = control flow. MCP/local tools = capabilities under graph. Small graph state (refs, summaries). Checkpointer = full state; context window = LLM view — separate.
**Locale:** conversation-observed `turnLocale` (detection-first from human messages ± intent slots); `configurable.locale` weak hint only; Intl formatters in code — not fixed bootstrap locale. `references/evidence-and-fidelity.md`, `templates/snippets/conversation-locale.ts.snippet`.
**Operator progress (JSON planner hops):** greenfield `streaming_sse` with a planner/analyst that emits structured `executionPlan` (no `bindTools` on that hop) **MUST** persist `userFacingIntent` (or `analysis.userFacingIntent`) + `executionPlan` on `AgentState`. **`userFacingIntent` language MUST match the current user message** (last `HumanMessage`) — not English unless that message is English; not product default locale. Machine `intent` stays English for audit. Emit SSE `thinking` from that field at **node entry** of the next hop — not `response_streaming`, not in durable `messages`. Hop 0 uses generic copy from `conversation/presentation/` (or locale) in the **same operator language**. Open ReAct + `ToolNode` uses `tool_started` / `tool_finished` only. Details: `templates/contracts/planner-contract.md`, `references/streaming-and-hitl.md`.
Three capability kinds bind to the model:
| Kind | LLM wire name | Internal id |
| --------------- | ----------------------- | --------------------- |
| Local tool | `{name}` | `local:{name}` |
| MCP tool | `mcp__{server}__{tool}` | `mcp:{server}:{tool}` |
| Skill procedure | `use_skill__{id}` | `skill:{id}` |
Wire names must match `^[a-zA-Z0-9_-]{1,128}$` (use `__` separators; colons only in internal ids). Colon in a **new** wire name is Critical on review.
## Pre-change gates
Before new file or inject/bind change: complete all three. No code until posted.
### 1. Placement Decision Block
```markdown
### Placement Decision Block
- Artifact: …
- Type: …
- Target path: …
- Layer: …
- Refs: placement-and-domains.md
- do_not_create_under: […]
```
Full matrix: `references/placement-and-domains.md`.
### 2. Prompt / Capability plan
```markdown
### Prompt / Capability plan
- Compose: base_invariant + injected (rebuild per invoke; not in state/checkpointer/durable messages)
- Motor (`base_invariant`): [gather-no-Markdown / sole-writer / tool discipline / JSON planner userFacingIntent is SSE not Markdown / …]
- Product (`injected`): canonical path + persona/tone notes; mode-resolved: yes/no; modes: [...]; resolver: ...
- System layers touched: […]
- Canonical prompt path: …
- Session overlay: yes/no
- Bind list: […]
- Auto-inject skills: […] (exclusive of bind for same id)
- Truncate caps: tool vs skill body
- Bind parity: …
- Spec paths to sync: […]
```
Full doctrine: `references/prompt-and-capability-injection.md`. Plan/mode-resolve: `references/prompt-and-capability-injection-plan-execute.md`.
### 3. Spec Sync Gate
**Nodes, edges, state, capabilities, recursion_limit, wire names, or `guard_fail_mode`** change: update `graph-spec.md` **same** delivery. Stale archive ≠ SoT — sync spec to intended runtime; do not force-fit live code to stale archive.
## Reference map
Load on demand — do not memorize whole files.
| Reference | Read when |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `references/bootstrap-agent-runtime.md` | Greenfield copy of `templates/agent-runtime/` |
| `references/orphan-recovery-checklist.md` | Project structure unclear or agent "lost" |
| `references/runtime-layout.md` | Scaffolding, refactors, layer violations |
| `references/placement-and-domains.md` | Where to put files; domain vs graph vs config |
| `references/prompt-and-capability-injection.md` | System prompt layers, bind vs inject, bind parity |
| `references/prompt-and-capability-injection-plan-execute.md` | Prompt/Capability plan; `plan_execute` gather vs composer; mode-resolved `injected` |
| `references/message-content-blocks.md` | AIMessage/HumanMessage/ToolMessage across providers |
| `references/context-window-and-tokens.md` | trim, summarize, tool vs skill body caps, `context_manager` |
| `references/mcp-complex-access.md` | Multi-server MCP, discovery, transport, lifecycle |
| `references/capability-governance.md` | Allowlist, classification, rate limits, tool budgets |
| `references/evidence-and-fidelity.md` | State-backed evidence, fidelity gate, conversation-observed locale |
| `templates/snippets/conversation-locale.ts.snippet` | `resolveConversationLocale` + Intl `formatUserFacing` |
| `templates/snippets/tool-budget.ts.snippet` | Per-turn tool/MCP caps, arg fingerprint duplicate-skip |
| `templates/snippets/prepare-llm-messages.ts.snippet` | `context_manager` helper |
| `references/error-and-reliability.md` | Tool errors, circuit breaker, retries, compensation, parallel staleness, cost stop |
| `references/model-cascade-and-cache.md` | Cheap-first cascade, both signals OR-escalate, semantic/prompt cache; not LLM intent_classify hop |
| `references/observability.md` | Postgres audit, retention = tenant clock, query tenant+period+one decision, cost reservation |
| `references/architectures.md` | ReAct, plan_execute (suggested start for most MCP), Reflection levels, other topologies; **node id ≠ state channel** |
| `references/guardrail-and-adversarial.md` | Scope/safety classifier; fail-open scaffold ≠ `graph-spec` lock; not Gateway routing |
| `references/streaming-and-hitl.md` | SSE envelopes, operator `thinking`, `interrupted`, resume SSE, `interrupt()`, `Command` resume |
| `references/turn-flow-gates.md` | Prompt/loop incidents: flow-first, terminal, repetition, tool-error, DoD |
| `templates/contracts/planner-contract.md` | JSON planner hops: `executionPlan` + `userFacingIntent` |
| `references/user-memory.md` | Per-user long-term memory: kinds, deduce-and-inform write path, per-invoke read, `/memories` CRUD, LGPD |
| `references/evals-and-gates.md` | Architecture, tool-selection, memory evals; golden-set promotion |
| `references/anti-patterns.md` | Review gate before marking done — hot path |
| `references/anti-patterns-extended.md` | Dead prompt copies, state/memory, reliability, graph, MCP, LLM, ops, process |
Templates: `templates/agent-runtime/` (greenfield tree), `templates/graph-spec.md`, `templates/contracts/`, `templates/snippets/` (brownfield patches).
## Session inputs
| Variable | Required |
| ------------------ | ----------------------------- |
| `{agent_api_root}` | Default `agent-api` |
| `{task}` | What to build, fix, or review |
## Orphan recovery (brownfield first)
Runtime disorganized or team blocked:
1. Read `references/orphan-recovery-checklist.md`; score project.
2. Gap report: structure, placement, context window, inject/bind parity, MCP governance, HTTP, spec sync.
3. Ordered fix plan (one phase per message if large).
4. Implement via `ns-coder`.
No new graph nodes or MCP servers until layout + governance baselines pass.
## Build workflow (greenfield or post-recovery)
### Phase 0 — Spec gate
If `graph-spec.md` is missing, create it from `templates/graph-spec.md`. Minimum sections: locked header (`framework`, `architecture`, `interaction_mode`, `guard_fail_mode`), domain ownership, prompt composition, state schema, nodes table, edges, interrupts, memory, capability bind/inject table, recursion_limit, HTTP routes.
If the user has no architecture decision yet, stop and invoke `ns-agent-architecture` first.
### Phase 1 — Skeleton
If `{agent_api_root}/package.json` is missing, run `scripts/bootstrap-agent-runtime.mjs` (`references/bootstrap-agent-runtime.md`). Then `npm install && npm test` in `{agent_api_root}`.
Do **not** assemble the tree from `templates/snippets/`. Do **not** copy another product. After copy: align `src/graph/` with `graph-spec.md`; put domain in `conversation/` + `config/` via later phases / `ns-coder`.
Brownfield existing tree: align per `references/runtime-layout.md` — snippets for patches only.
### Phase 2 — State and persistence
After bootstrap, **verify** these exist; do not re-scaffold. Fill only gaps vs `graph-spec.md`.
- `AgentState` with `messages` reducer (`Annotation.Root` or Zod + `MessagesZodMeta`).
- `PostgresSaver` in dev/prod; `MemorySaver` only in `tests/setup.ts`.
- Long-term memory (when `graph-spec.md` locks it): per **user** (`tenant_id` + `user_id`), never per `thread_id` — `references/user-memory.md`.
- Every invoke/stream: `configurable.thread_id` via `buildRunConfig`.
- JSON planner/analyst (no `bindTools` on that hop): declare `executionPlan` + `userFacingIntent` (or nested on `analysis`) in `graph-spec.md` state schema — `templates/snippets/state.ts.snippet`.
### Phase 3 — LLM and messages
- Provider config in `src/llm/` (infra only — no domain prompts).
- **One env var per model role** (e.g. chat, summarize, embed) — **no hardcoded model id** in source.
- Embedding model change invalidates vector index → **full re-seed** required.
- Graph/node unit tests: **fake LLM** in default tier. Prompt/guardrail behavior needing a real model → **live tier** (Test tiers in `ns-harness` → `docker-and-testing.md`).
- Prefer JSON mode + Zod parse for structured turns; avoid `withStructuredOutput` on OpenAI-compatible local servers.
- Normalize provider output via `contentBlocks` / `content_blocks` — see `references/message-content-blocks.md`.
### Phase 4 — Context window (mandatory)
Implement per `references/context-window-and-tokens.md`:
- `trimMessagesForLlm` before every LLM call.
- `normalizeMcpToolResult` then `truncateToolOutput` before `ToolMessage` enters state.
- Separate `CONTEXT_SKILL_BODY_MAX_CHARS` for skill bodies (snippet `skillBodyMaxChars`).
- Summarize when used tokens exceed **80%** of `CONTEXT_MAX_TOKENS` (raw window). Ratios are constants: trigger `0.8`, compact to `0.5`, summary cap `0.1`. No summarize multiplier env.
- `summarizeOlderMessages` with **persisted compaction** (`RemoveMessage` + rewrite) in the same agent-node return.
Never pass raw `state.messages` to the model.
### Phase 5 — Capabilities
1. Local `StructuredTool`s in `src/tools/`.
2. MCP: governed client — discovery → local allowlist → wire names → singleton client lifecycle (`references/mcp-complex-access.md`).
3. Skills: `skills/*.md` auto-discovered → `use_skill__{id}` **or** auto-inject (exclusive per id).
Apply `references/capability-governance.md` and `references/prompt-and-capability-injection.md` before `bindTools`. Enforce **bind parity**. Wire per-turn tool/MCP budgets from `templates/snippets/tool-budget.ts.snippet` when MCP or external tools are bound.
### Phase 6 — HTTP and interaction mode
| Mode | Requirements |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sync_json` | `POST /threads`, `POST /threads/:id/message` |
| `streaming_sse` | SSE envelope per `references/streaming-and-hitl.md`; composer reply **MUST** `model.stream()` + cumulative `response_streaming` ticks (not invoke-dump); SSE flush leave-now; dev-chat `flushSync` per tick; **greenfield MUST** ship styled React `GET /dev-chat` (`DEV_CHAT_ENABLED`, local-only) + `GET /dev-chat/app.js`; JSON planner hops **MUST** emit operator `thinking`; Docker artifacts (Dockerfile, agent-only compose) shipped |
| HITL | `interrupt()` + `POST /threads/:id/resume` (SSE when Accept SSE) with `Command({ resume })`; always-escalate **MUST** send `approver_id` + `approver_role`; paused graph → terminal `interrupted` |
User memory enabled → caller-scoped `/memories` CRUD (`references/user-memory.md` §5); `user_id` from auth only.
Brownfield missing dev-chat: recommend add — not Critical. Postman synced with live routes.
### Phase 7 — Observability
Wire `references/observability.md`: `initDb`, `runStorage`, `logLlmCall`, `logToolExecution`, persist `turn_decisions`. LangSmith and OTel are opt-in.
### Phase 8 — Evals and review
- Add suites per `references/evals-and-gates.md`.
- Run `npm run build && npm test` in `{agent_api_root}`.
- Invoke `ns-reviewer` on the diff; ask it to verify placement, inject, wire-name, and bind-parity anti-patterns when the diff touches `agent-api`.
## Maintenance workflow
Ongoing work (not greenfield):
1. Three **Pre-change gates**
2. `graph-spec.md` matches intended graph after change
3. Layer: graph node, conversation, MCP, memory, HTTP
4. Read matching reference before edit
5. Minimal diff via `ns-coder` with placement/inject handoff
6. Postman on HTTP route change
7. Re-run orphan checklist items touched
## MCP complex access (quick rules)
Multiple MCP servers, overlapping or large catalogs:
- **Discovery filter** — allowlisted `tools/list` before bind
- **Local classify** — `read | write | destructive | admin`; never trust server read-only flags
- **Singleton client** — one `MultiServerMCPClient` per process; no per-request stdio in prod
- **Transport** — Streamable HTTP deployed; stdio local single-user dev only
- **Errors** — MCP `isError: true` = recoverable `ToolMessage` `status: "error"`; protocol fail may abort with HTTP/SSE `failed`
- **Secrets** — env or `configurable` / request payload only; never state or checkpointer
Full: `references/mcp-complex-access.md`.
## Handoff to ns-coder
When implementation is approved, delegate with:
```markdown
## LangGraph implementation task
- Root: {agent_api_root}
- Spec: path/to/graph-spec.md
- Phase: [number and name from this skill]
- target_paths: […]
- layer: […]
- do_not_create_under: […]
- injection_notes: [layers / bind vs auto-inject / caps]
- spec_paths_to_sync: […]
- References to apply: [list]
- Acceptance: build + test pass; orphan checklist items [n] resolved; placement + inject + bind parity verified
- Review: ns-reviewer after tests — must check placement, inject, wire names (`:`), bind parity (load ns-langgraph-agents anti-patterns when diff touches agent-api)
```
Stay here for diagnosis, spec, placement, governance design, and **greenfield bootstrap copy**. `ns-coder` for feature diffs. Version-scoped features: `ns-spec-driven`.
## Stop conditions
| Condition | Action |
| ---------------------------------------------------------- | ----------------------------------------------- |
| No `graph-spec.md` and user wants code now | Create spec or invoke architect |
| Greenfield assembled from snippets / another product tree | Stop; run `scripts/bootstrap-agent-runtime.mjs` |
| Path outside placement matrix / inventing folders | Stop; propose legal path |
| Domain / locale / copy landing in `graph/` or `llm/` | Stop; reroute to conversation/config |
| Bind without parity (dispatchable but unbound) | Stop; fix bind or document unbound + test |
| `:` in a new wire name | Stop; use `__` separators |
| Skill auto-inject + bind same id without explicit decision | Stop; choose one mode |
| CrewAI requested | Redirect to appropriate skill |
| Change spans >3 layers without plan | One-line phased plan, wait for approval |
| Critical security gap (secrets in state, ungoverned MCP) | Block feature work; fix governance first |
## Related skills (ownership)
| Skill | Owns |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `ns-langgraph-agents` | Doctrine, placement, inject plan, graph-spec, greenfield scaffold |
| `ns-coder` | Feature diffs + review loop (not initial scaffold copy) |
| `ns-reviewer` | Verdict; when diff touches `agent-api`, apply placement + inject + wire-name + bind-parity anti-patterns from this skill |
| `ns-agent-adaptation` | Conceptual adaptation design before architecture |
| `ns-agent-architecture` | Framework choice before Phase 0 when unlocked |
| `ns-spec-driven` | Version features after scaffold exists (or first task = bootstrap) |
| `ns-investigator` | Runtime debug |
## Forbidden
- Emitting planner `userFacingIntent` as `response_streaming` or as Markdown in `messages` (SSE `thinking` only; composer remains sole Markdown writer)
- Composer reply via `model.invoke` / single end-of-turn `response_streaming` dump; buffered SSE; client typewriter or delayed paint of ticks (`references/streaming-and-hitl.md`)
- Writing `userFacingIntent` in a language other than the current user message (e.g. English progress when the operator wrote Portuguese)
- Persisting composed system/persona prompt (`base_invariant + injected`) — or secrets/API keys — in graph state, checkpointer, or durable `messages` (rebuild system text per invoke)
- Keying long-term user memory by `thread_id`, storing company/tenant facts or secrets in user memory, persisting the rendered memory block in state/checkpointer, or asking the user to confirm each memory instead of informing (`references/user-memory.md`)
- Treating bootstrap / `.env` / `configurable.locale` as primary locale SoT, or persisting sticky thread locale (use conversation-observed `turnLocale` + Intl)
- Passing unbounded tool/MCP output into `state.messages`
- Applying tool/MCP truncate caps to skill bodies (use `CONTEXT_SKILL_BODY_MAX_CHARS`)
- Trusting MCP tool metadata for security classification
- Spawning stdio MCP subprocesses per HTTP request in production
- `memory/` compiling `StateGraph`
- Domain qualify/conversation prompts in `src/llm/`
- Locale/presentation under `graph/`
- Nudge as fake `HumanMessage`
- Tests under `src/`
- Greenfield tree from snippets or another product — use `templates/agent-runtime/` only
© nextstage-brasil · Apache-2.0 · nextstage-brasil/skills