Architecture Negotiation#

Before an agent writes a single file for a new feature, it negotiates the shape of the change with Mandu. The framework replies with a plan — files, layers, dependencies — and the user (or the agent) approves or rejects. On approval, mandu.negotiate.scaffold materializes the plan atomically.

This flips the usual "agent guesses structure → reviewer finds layer violations later" loop. From RFC-001.

The flow#

Intent: "Add user authentication with JWT + refresh tokens"
    ↓
mandu.negotiate({
  intent,
  requirements: ["JWT based", "Refresh tokens"],
  constraints: ["Use existing User model", "Redis sessions"],
})
    ↓
Framework checks:
  • Existing decisions (ADRs)
  • Guard preset layers
  • Current project structure
  • Related prior work
    ↓
Plan returned:
{
  approved: true,
  structure: [
    { path: "server/domain/auth/",       files: ["auth.service.ts", ...] },
    { path: "app/api/auth/login/",       files: ["route.ts"] },
    { path: "app/api/auth/refresh/",     files: ["route.ts"] },
    { path: "spec/contracts/",           files: ["auth.contract.ts"] },
  ],
  slots: [...],
  relatedDecisions: ["ADR-004: session storage"],
  warnings: [],
}
    ↓
User or agent approves
    ↓
mandu.negotiate.scaffold(plan.structure)
    ↓
Files created. Guard + ATE enforce going forward.

CLI#

mandu negotiate --intent "Add user authentication" \
  --category auth \
  --requirement "JWT based" --requirement "Refresh tokens" \
  --constraint "Use existing User model"

Programmatic API#

import { negotiate, generateScaffold } from "@mandujs/core/guard";

const plan = await negotiate({
  intent: "Add user authentication",
  category: "auth",
  requirements: ["JWT based", "Refresh tokens"],
  constraints: ["Use existing User model"],
}, projectRoot);

if (plan.approved) {
  await generateScaffold(plan.structure, projectRoot);
}

MCP#

From an agent:

• mandu.negotiate — returns the plan (read-only; no files touched)
• mandu.negotiate.analyze — reads the current project structure so the plan fits what already exists
• mandu.negotiate.scaffold — materializes an approved plan

What's in a plan#

Why negotiate#

• Structure consistency: every feature follows the same layer layout (no rogue src/utils/auth.ts buried in widgets).
• Decision reuse: plan consults Decision Memory; doesn't re-propose choices that already have ADRs.
• Atomic scaffold: files create together or not at all. No orphans.
• Agent alignment: agent and human both review the plan before code ships — one approval, not fifteen PR comments.

What the landing meant#

The hero says "100+ MCP 툴 · 실전 Skills 워크플로우 · 런타임 Guard" — this negotiation flow is the first step of every agent workflow. The plan is the Skills workflow; Guard is what enforces it afterward.

🤖 Agent Prompt#

Apply the guidance from the Mandu docs page at https://mandujs.com/docs/build-with-agents/negotiation to my project.

Summary of the page:
Mandu Negotiation is a pre-implementation dialog. Call mandu.negotiate with {intent, requirements, constraints} → framework returns a structured plan {files, layers, decisions} → if approved, mandu.negotiate.scaffold materializes it. RFC-001.

Required invariants — must hold after your changes:
- Every new feature an agent adds must pass `mandu.negotiate` before any files are written
- The scaffold step respects the Guard preset (layers, naming, imports)
- A rejected plan is NEVER partially applied

Then:
1. Make the change in my codebase consistent with the page.
2. Run `bun run guard` and `bun run check` to verify nothing
   in src/ or app/ breaks Mandu's invariants.
3. Show me the diff and any guard violations.

Related#

• Decision Memory — the ADR log plans consult
• Guard presets — the layer rules scaffolds must satisfy
• Change transactions — rolling back a bad scaffold