brain-clone

name

brain-clone

description

Use when a domain expert wants to clone their professional brain into an Agent2 agent — interactive multi-phase interview that extracts identity, Chain-of-Thought, tools, knowledge, examples, and output format, then generates a complete production agent with a Sachbearbeiter-style Chain-of-Thought prompt, Pydantic schemas, tools, knowledge collections, and Docker config. Triggers on "brain clone", "clone expert", "new domain agent", "extract expertise".

Brain Clone

Overview

Turn a domain expert's brain into a production Agent2 agent through structured interview. The skill extracts tacit professional knowledge — not just facts, but the expert's Chain-of-Thought — and generates a complete agent following the proven Sachbearbeiter architecture: 5-layer Chain-of-Thought prompt, tool metaphors, knowledge collections, memory, sandbox tools, and structured output with outcome consistency validation.

Canonical references in this repo:

• docs/brain-clone-pattern.md explains the Agent2 Brain Clone pattern.
• docs/reference-agents/sachbearbeiter-pattern.md explains the production reference architecture.
• agents/procurement-compliance-officer is the full public flagship example to study before generating a serious domain agent.

Core insight: Domain expertise is not a list of rules. It is a Sachbearbeiter-style Chain-of-Thought: a professional mental loop of intake, lookup, checking, clarification, decision, and memory update. Facts go into knowledge books. The expert's Chain-of-Thought goes into the prompt.

Important: In Agent2, "Chain-of-Thought" means the domain professional's explicit work-thinking pattern, not a request to expose private model internals. The prompt should make the agent run the expert's mental chain; the output should expose concise reasoning and review_steps[] as the observable trace of that work.

When to Use

• Domain expert wants to "clone" their professional decision-making into an AI agent
• User says "brain clone", "clone my brain", "create domain expert", "extract my expertise"
• Building an agent for a regulated/specialized domain (accounting, legal, medical, compliance, procurement, HR, insurance)
• Need to go beyond simple "You are an expert in X" prompts to Sachbearbeiter-level Chain-of-Thought prompts

Do NOT use for: Generic chatbots, simple CRUD agents, or agents that don't need domain expertise. Use creating-agents skill instead.

The 5-Layer Prompt Architecture

Every brain-clone agent produces a prompt with these layers (derived from the Sachbearbeiter pattern):

Layer 1: IDENTITY + MINDSET
  "You are a senior [role] with [N] years of experience..."
  → WHO the agent is, HOW they approach work

Layer 2: WORKSPACE (Tool Metaphors)
  "You sit at your desk and have everything you need:"
  - Reference books → search(), get_passage()
  - Internet → web_search()
  - Client file → get_{context}_info()
  - Database/registry → lookup_{entity}(), list_{entities}()
  - Notepad → update_{context}_memory()
  → Every tool gets a HUMAN metaphor the LLM understands

Layer 3: SACHBEARBEITER CHAIN OF THOUGHT
  "When you process a [case], you work through it step by step:"
  - "What do I have here?" (intake/classification)
  - "What do I know about this context?" (context lookup)
  - "Is this formally correct?" (validation)
  - "Is anything unclear?" (clarification check)
  - "How do I process this?" (core domain logic)
  - "What did I learn?" (memory update)
  → The professional reasoning chain extracted from the expert's actual work

Layer 4: EXAMPLE CHAINS OF THOUGHT
  3-5 real cases showing different outcomes and edge cases
  → NOT rules, but demonstrations of the expert's thinking chain

Layer 5: THREE OUTCOMES (Decision Tree)
  Every case ends with exactly one of three results:
  - complete — work product delivered
  - needs_clarification — expert needs human input
  - rejected — input is defective/unusable
  → Clear, mutually exclusive outcomes

The Interview: 8 Phases

Run each phase as a conversation. Do NOT skip phases. Do NOT generate code until Phase 7.

Phase 1: Identity

Goal: Understand WHO this expert is and their professional mindset.

Ask:

• "What's your professional role? What do you do day-to-day?"
• "How long have you been doing this?"
• "What separates you from a beginner in your field?"
• "How would you describe your work style — thorough, efficient, cautious?"

Extract: Role title, years of experience, core competency description, personality traits that affect work quality (e.g., "thorough when needed, efficient when possible — never guesses").

Map to Layer 1: The identity paragraph of the system prompt.

Phase 2: Thinking Process

Goal: Extract the expert's ACTUAL Chain-of-Thought when they handle a case.

Ask:

• "When a new [case/document/request] lands on your desk, what are your FIRST 3 thoughts?"
• "Walk me through a specific recent case from start to finish — every step, every decision."
• "At which points do you feel certain? At which points do you hesitate?"
• "When do you decide to look something up vs. trust your knowledge?"
• "When do you ask someone else for input? What triggers that?"
• "When do you reject something outright? What makes something unworkable?"

Extract: Ordered Chain-of-Thought with decision points. This becomes Layer 3.

Critical: Do NOT accept vague answers like "I analyze it". Push for specifics: "What exactly do you check first? Then what?"

Phase 3: Tools and Workspace

Goal: Map the expert's real-world tools to Agent2 tool categories.

Ask:

• "What's on your desk right now? What do you reach for?"
• "Which reference books/manuals/regulations do you consult?"
• "What databases or systems do you use?"
• "Do you keep personal notes about clients/cases? What's in them?"
• "When do you use the internet to look something up?"
• "Do you ever need to send messages/emails as part of your work?"
• "Do you look up history of past similar cases?"

Extract and map:

Expert says	Tool category	Implementation
"I check the regulation book"	Knowledge search	Knowledge MCP: search(), get_passage()
"I look up the client file"	Context lookup	get_{context}_info() → external DB
"I check my notes from last time"	Memory	get_{context}_info() (memory field)
"I update my notes"	Memory write	update_{context}_memory()
"I look up the supplier/vendor/entity"	Entity lookup	lookup_{entity}(), list_{entities}()
"I check past cases"	History	get_{domain}_history()
"I Google it when books don't help"	Web search	web_search() (Tavily/DuckDuckGo)
"I send an email to ask"	Communication	send_{action}_email() — SANDBOX tool
"I save a new record"	Data mutation	save_{entity}() — SANDBOX tool
"I scan/read the document"	OCR/intake	Docling MCP: convert + export

Workspace metaphor: For each tool, create a human-readable metaphor: "Your bookshelf with regulations" for knowledge, "Your notepad" for memory, "Your filing cabinet" for entity lookups.

Phase 4: Knowledge and Reference Material

Goal: Identify what goes into R2R knowledge collections.

Ask:

• "Which books, manuals, or regulations are ESSENTIAL for your work?"
• "If you could only keep 3 reference books on your desk, which ones?"
• "Do you have PDFs, tables, or documents you consult regularly?"
• "Are there different reference sets for different clients/contexts?"
• "How do you use these books — cover to cover or specific lookups?"
• "Can you share these files with me?" (collect file paths)

Extract:

• List of knowledge collections with descriptions
• Whether collections are universal or per-tenant scoped
• File paths for ingestion

Generate:

# knowledge/collections.yaml entry
collections:
  {domain}-standards:
    description: "Core regulations and standards for {domain}"
    books_dir: books/{domain}-standards/
    agents:
      - {agent-name}
  {domain}-reference:
    description: "Textbooks, commentaries, practical guides"
    books_dir: books/{domain}-reference/
    agents:
      - {agent-name}

Phase 5: Example Cases

Goal: Collect 3-5 diverse cases that demonstrate different thinking paths and outcomes.

Ask:

• "Give me a TYPICAL case and walk me through your reasoning."
• "Give me a case where you had to ask for clarification — what was unclear?"
• "Give me a case where you rejected the input — what was wrong with it?"
• "What's the most COMPLEX case you've handled recently?"
• "What are the most common MISTAKES beginners make?"

Extract: For each case, capture:

1. What the input looked like
2. What the expert thought at each step
3. What the outcome was and why
4. What made this case different from others

Map to Layer 4: Write each as a brief Chain-of-Thought narrative (not a rule, but a demonstration of thinking). Keep them short — 2-3 sentences each, like the Sachbearbeiter examples.

Phase 6: Output Format

Goal: Design the Pydantic schema for the agent's structured output.

Ask:

• "When you finish a case, what does your work product look like?"
• "What fields/data points must ALWAYS be present?"
• "What fields are only present in certain outcomes?"
• "How do you express confidence — when are you 90% sure vs. 60%?"
• "What does a 'needs clarification' result look like?"
• "What does a 'rejected' result look like?"

Extract: Field list with types, required/optional status, and validation rules.

Generate schema following the Sachbearbeiter pattern:

class {Name}Result(BaseModel):
    status: Literal["complete", "needs_clarification", "rejected"]

    # Domain-specific output fields (only when complete)
    {domain_fields}: ...

    # Clarification path
    proposed_message: ClarificationRequest | None = None

    # Rejection path
    rejection_reason: str | None = None

    # Always present
    extracted_fields: Extracted{Domain}Fields
    confidence: float = Field(ge=0.0, le=1.0)
    reasoning: str  # Concise observable Chain-of-Thought summary for THIS case
    review_steps: list[str] = Field(default_factory=list)
    pending_actions: list[PendingAction] = Field(default_factory=list)

    @model_validator(mode="after")
    def _check_status_consistency(self) -> Self:
        """Enforce mutual exclusivity of outcomes."""
        # complete → domain output required, no rejection_reason
        # needs_clarification → proposed_message required
        # rejected → rejection_reason required, no domain output

Phase 7: Generation

Goal: Generate all Agent2 artefacts from the collected interview data.

Generate these files in agents/{name}/:

1. schemas.py — Pydantic models from Phase 6

• Include PendingAction, ClarificationRequest, extracted fields model
• Add @model_validator enforcing outcome consistency

2. agent.py — Full agent module:

• System prompt assembled from Layers 1-5 (Phases 1-5)
• create_agent() with instructions="" (prompt injected via before_run)
• Tool registrations from Phase 3 mapping
• before_run(): collection scoping, context injection into prompt, resume handling
• after_run(): persistence, low-confidence escalation
• mock_result(): schema-compliant mock for each outcome
• Tests and Promptfoo evals that prove behavior, not just JSON shape

3. tools.py — Tool implementations:

• Knowledge: via MCP toolsets (not in tools.py)
• Context/Memory/History/Lookup: async functions calling external DB
• Web search: Tavily with DuckDuckGo fallback
• Sandbox tools: return {"pending": True, "action": "...", "params": {...}}

4. config.yaml:

name: {agent-name}
description: "{one-line from Phase 1}"
model: ""  # Uses DEFAULT_MODEL
port: {next-available}
timeout_seconds: 300
max_retries: 3
collections:
  - {from Phase 4}
capabilities:
  - resume
  - approval_workflow
  - knowledge_mcp

5. main.py: from shared.api import create_app; app = create_app("{name}")

6. Dockerfile: Based on template, with agent-specific dependencies

7. docker-compose.yml entry: New service block with correct port and environment

8. knowledge/collections.yaml update: Add new collections from Phase 4

Phase 8: Review and Iteration

Goal: Validate the generated agent with the domain expert.

Present the generated system prompt to the expert and ask:

• "Read this carefully. Does this sound like how YOU think?"
• "Is any step missing from the Chain-of-Thought?"
• "Are the example cases accurate?"
• "Would you trust this agent to handle a real case?"
• "What would a beginner get wrong that I should add as a warning?"

Iterate until the expert says: "Yes, that's me."

After approval:

• Run uv run pytest tests/ -v to verify framework integrity
• Build Docker image: docker compose build {name}
• Test mock mode: POST /tasks?mode=sync with sample input
• If knowledge files were provided: add ingestion instructions

System Prompt Template

Use this template when assembling the prompt in Phase 7. Replace placeholders with interview data:

SYSTEM_PROMPT = """\
{layer_1_identity}

## Your Workspace

You sit at your desk and have everything you need:

{layer_2_workspace_tools}

Use these tools naturally — reach for them when you need them, not mechanically.

## Sachbearbeiter Chain of Thought

When you process a {case_type}, run the expert Chain-of-Thought step by step. \
Document the visible checkpoints in review_steps[] and summarize the decision \
chain in reasoning.

{layer_3_chain_of_thought_steps}

## Example Chains of Thought

These are typical cases. Your reality is much broader — use these as orientation, \
not as templates.

{layer_4_examples}

## {context_variable_section}

{dynamic_context_injection_placeholder}

## Three Outcomes

Every {case_type} ends with one of three results:

- **complete** — {complete_description}
- **needs_clarification** — {clarification_description}
- **rejected** — {rejection_description}

## Sandbox Tools

{sandbox_tools_description}

## Pause/Resume

If message_history is present: the case continues. Read the context, use the \
human's answer, complete the work — no re-processing needed.

## Output Format

{format_constraints}
"""

Tool Generation Patterns

Sandbox Tools (Side Effects)

Any tool that DOES something in the real world must be a sandbox tool:

async def save_{entity}(...) -> dict:
    """SANDBOX: Returns pending action for human approval."""
    return {
        "pending": True,
        "action": "save_{entity}",
        "params": {params},
        "description": f"Save new {entity} '{name}'",
    }

async def _execute_save_{entity}(...) -> dict:
    """REAL execution — called after human approval."""
    # Actual DB/API call here

Memory Tools

Every domain expert agent needs persistent memory:

async def get_{context}_info(context_id: str) -> dict:
    """Load context details and the expert's notes from previous sessions."""

async def update_{context}_memory(context_id: str, memory: str) -> dict:
    """Update persistent memory with learnings from this session.
    Read existing memory first, merge, then save. Max 10,000 chars."""

Chain-of-Thought Checkpoint Tool

For complex expert agents, add a no-op checkpoint tool that makes the model walk the Sachbearbeiter Chain-of-Thought before deciding. This tool does not persist anything and does not expose private model internals; it records the visible case checkpoint the professional would write on their scratchpad.

@agent.tool_plain
async def note_review_step(step: str, finding: str, next_action: str = "") -> dict:
    """Record a visible checkpoint in the expert Chain-of-Thought."""
    return {
        "recorded": True,
        "step": step,
        "finding": finding,
        "next_action": next_action,
    }

Use this when the real expert would pause and think: classify the case, choose a book to open, decide whether facts are missing, or decide between completion, clarification, and rejection.

Knowledge Scoping

Per-tenant or per-context knowledge collections:

_ACTIVE_COLLECTIONS: ContextVar[tuple[str, ...]] = ContextVar(
    "active_collections", default=DEFAULT_COLLECTIONS
)

def before_run(input_data: dict) -> dict:
    context = input_data.get("{context_key}", {})
    collections = context.get("knowledge_collections", [])
    if collections:
        _ACTIVE_COLLECTIONS.set(tuple(collections))
    # Inject dynamic prompt sections
    input_data["_instructions"] = SYSTEM_PROMPT.format(...)
    return input_data

before_run Pattern

Every brain-clone agent uses before_run() for:

1. Knowledge collection scoping — set active collections from input context
2. Dynamic prompt injection — inject context-specific sections into the system prompt (like SKR warning in Sachbearbeiter)
3. Langfuse prompt fallback — try Langfuse prompt management first (editable without redeploy), fall back to local SYSTEM_PROMPT
4. Resume detection — check for message_history and adjust instructions
5. Input guards — validate prerequisites (like OCR availability)
6. Per-run MCP toolsets — create fresh MCPServerStreamableHTTP instances per run to avoid cancel scope collisions when multiple async tasks run concurrently. Agent2 passes _toolsets into Agent.run(toolsets=...).

def before_run(input_data: dict) -> dict:
    # 1. Scope knowledge collections
    context = input_data.get("{context_key}", {})
    collections = context.get("knowledge_collections", [])
    if collections:
        _ACTIVE_COLLECTIONS.set(tuple(collections))

    # 2. Build dynamic prompt sections from context
    dynamic_section = _build_dynamic_section(context)

    # 3. Try Langfuse prompt first, fall back to local
    from shared.config import Settings
    from shared.runtime import get_prompt
    langfuse_prompt = get_prompt(
        "{agent-name}-system-prompt", Settings.from_env(),
        dynamic_section=dynamic_section,
    )
    input_data["_instructions"] = langfuse_prompt or SYSTEM_PROMPT.format(
        dynamic_section=dynamic_section,
    )

    # 4. Resume detection
    if input_data.get("message_history"):
        pass  # _instructions already set; framework handles history

    # 5. Input guards
    if not docling_mcp_url and input_data.get("requires_ocr"):
        raise ValueError("OCR tool not available")

    # 6. Fresh MCP toolsets per run
    input_data["_toolsets"] = _create_mcp_toolsets()
    return input_data

after_run Pattern

Every brain-clone agent uses after_run() for:

1. Persist results to external DB/API
2. Low-confidence escalation — flag results below threshold for human review
3. Message threading — append to existing conversation threads
4. Error recovery — set error status if persistence fails

async def after_run(input_data: dict, output: dict) -> None:
    job_id = input_data.get("{job_id_field}")
    if not job_id:
        return
    # Persist
    # Escalate if confidence < 0.85
    if output.get("confidence", 0) < 0.85:
        output["needs_review"] = True

Common Mistakes

Mistake	Fix
Skipping Phase 2 (Chain-of-Thought)	This IS the skill. Without it you get "You are an expert" — worthless. Push for step-by-step specifics.
Encoding domain knowledge in the prompt	Knowledge goes in R2R collections. The prompt teaches HOW TO THINK, not WHAT TO KNOW.
Generic tool names	Use domain language: "lookup_lieferant" not "search_entity". The LLM performs better with domain-specific naming.
Skipping the review loop (Phase 8)	The expert MUST validate. "Does this sound like how you think?" is the only real test.
Making all tools execute immediately	Side-effect tools MUST be sandboxed with pending_actions. Always.
Single knowledge collection	Split by purpose: standards vs. reference material vs. per-tenant packages.
No model_validator on schema	Without it, the LLM can return contradictory state (e.g., complete + rejection_reason). PydanticAI retries on validation errors.
Hardcoding prompt without before_run	Dynamic sections (like context-specific rules) must be injected per-run via _instructions.
Forgetting mock_result	Without it, the API is untestable in dev mode. Generate schema-compliant mocks for each outcome.
Ignoring the flagship example	Study agents/procurement-compliance-officer before generating a full domain expert.

Anti-Sycophancy Rules

The interviewer must behave like a rigorous YC partner, not a polite note-taker. The first answer to any question is usually the polished version. The real answer comes after the second or third push.

Never say these during the interview (Phases 1-6):

• "That's an interesting approach" — take a position instead
• "I see, that makes sense" — probe whether it actually makes sense in production
• "There are many ways to think about this" — pick one and state what evidence would change your mind
• "You might want to consider..." — say "This is wrong because..." or "This works because..."
• "Got it" — restate what you understood and ask if that matches reality

Always do:

• Take a position on every answer. State your position AND what evidence would change it.
• Push once, then push again. The first answer is aspirational. The second is real.
• Challenge the strongest version of the expert's claim, not a strawman.
• Name common failure patterns: "sounds like you're describing how you WISH you worked, not how you ACTUALLY work — is that fair?"

Forcing Questions & Pushback Patterns

Every phase has forcing-quality questions. Do NOT accept abstract or generic answers. Push until you hear specifics: a field name, a regulation section, a concrete threshold, a real case.

Phase 1 Pushback Patterns

Expert says	BAD follow-up (avoid)	FORCING follow-up (aim for)
"I'm thorough and careful"	"Great, tell me more about your style"	"Give me an example where being thorough cost you 30 minutes but saved the client money. What did a beginner miss that you caught?"
"I have 20 years of experience"	"That's impressive, what's your specialty?"	"What do you know today that you got wrong in year 5? What's the most expensive mistake you stopped making?"
"I handle invoices"	"What kind of invoices?"	"Pick the last invoice that made you pause. Not routine — the tricky one. What was on it?"

Phase 2 Pushback Patterns (THE critical phase)

Expert says	BAD follow-up (avoid)	FORCING follow-up (aim for)
"First I analyze the document"	"What do you analyze?"	"'Analyze' is too vague for a production agent. When the PDF opens, where do your eyes go FIRST — top-right for the amount? Bottom for the tax line? What tells you in the first 3 seconds whether this is routine or trouble?"
"I check if everything is correct"	"What counts as correct?"	"Name the last invoice you rejected. What SPECIFIC field was wrong? Was it missing entirely, or present but wrong? How did you know it was wrong — from memory, from a regulation, or from the client file?"
"I look things up when needed"	"What do you look up?"	"Last week — what did you look up and what did you already know? What's the threshold where you stop trusting your memory and open the book?"
"It depends on the situation"	"Can you give me examples?"	"'It depends' means there's a decision tree in your head. Let's map it. What are the 2-3 things it depends ON? For each one, what do you do differently?"
"I use my experience"	"How does experience help?"	"Experience means you have mental shortcuts a beginner doesn't. Name one. What does a beginner check that you skip because you already know the answer? What does a beginner miss that you catch without thinking?"

Phase 3 Pushback Patterns

Expert says	BAD follow-up (avoid)	FORCING follow-up (aim for)
"I use various databases"	"Which ones?"	"Open your browser right now. What tabs are open? What bookmarks do you use weekly? Name the 3 systems you'd be paralyzed without."
"I check regulations"	"Which regulations?"	"You have a client's invoice for EUR 2,380 consulting. Which EXACT section do you open? Do you search by keyword or flip to a known page? What's the search term?"

Phase 5 Pushback Patterns

Expert says	BAD follow-up (avoid)	FORCING follow-up (aim for)
"I usually approve these"	"What makes you approve?"	"Walk me through the LAST one you approved. What was the amount? Who was the vendor? What made it a clear approve versus needing a second look?"
"Sometimes I need to ask"	"What do you ask about?"	"Show me the last email or message you sent to a client asking for clarification. What EXACTLY was unclear? What would have happened if you'd guessed instead of asking?"
"I reject bad invoices"	"What makes them bad?"	"Name the last rejection. What was wrong? Was it fixable (send corrected invoice) or unfixable (fraudulent)? How did you communicate the rejection?"

Phase 2.5: Premise Challenge (NEW — insert between Phase 2 and Phase 3)

Goal: Validate that the extracted Chain-of-Thought matches reality, not aspiration. Experts describe how they WISH they worked, not how they ACTUALLY work. This phase catches the gap.

Before moving to Phase 3 (Tools), synthesize the thinking chain from Phase 2 and present it as explicit premises:

Based on what you described, here are the premises I'm building the agent on.
If any of these are wrong, the agent will be wrong in production.

PREMISES:
1. [You always check X before Y] — true in every case, or only when Z?
2. [You reach for the book when the amount exceeds threshold T] — is T a hard
   number or a gut feeling?
3. [You never reject without attempting clarification first] — even when the
   document is clearly fraudulent?
4. [Your first step is always intake/classification] — or do you sometimes
   skip straight to booking for known recurring vendors?
5. [You update your notes at the end of every session] — really every time,
   or only when something surprising happened?

Rules:

• Extract 4-6 premises from the Phase 2 answers.
• Each premise must be specific enough that the expert can say "yes exactly" or "no, actually..."
• Frame premises as potentially wrong — make it easy to correct them.
• If the expert corrects a premise, UPDATE the Chain-of-Thought from Phase 2.
• Do NOT proceed to Phase 3 until all premises are confirmed or corrected.

Pushback pattern:

• Expert says "Yes, that's right" to everything → "I'm suspicious. Nobody's process is this clean. Tell me about the last time you DIDN'T follow this process. What made you skip a step?"

Phase 6.5: Scope Decision (NEW — insert between Phase 6 and Phase 7)

Goal: Make deliberate architectural decisions before generating code.

Present via structured questions:

Scope Question 1: Agent Boundary

"Is this one agent or should some responsibilities be separate? For example: should OCR intake be a preprocessing step before the agent runs? Should knowledge search be shared infrastructure used by multiple agents?"

Options:

• A) Single agent handles everything (simpler, recommended for first version)
• B) Split: [describe the split based on interview data]

Scope Question 2: Knowledge Sharing

"Should the knowledge collections be exclusive to this agent or shared with others in your organization?"

Options:

• A) Exclusive — this agent owns its books
• B) Shared — other agents may search the same collections

Scope Question 3: Execution Model

"When this agent decides to take action (send email, save record), should it:"

Options:

• A) Propose and wait for human approval (sandbox mode — recommended for regulated domains)
• B) Execute directly (autonomous mode — for low-risk domains)

Scope Question 4: Minimal Viable Agent

"What's the smallest version of this agent that would be useful in production THIS WEEK? Not the full vision — the wedge."

Push for a concrete answer. The wedge becomes the Phase 7 generation target. The full vision goes into config.yaml as future capabilities.

Phase 7.5: Architecture Review by Fresh Eyes (NEW — insert between Phase 7 and Phase 8)

Goal: Independent validation of the generated agent before the expert reviews.

After Phase 7 generates all files, dispatch a review of the generated code. The reviewer sees ONLY the generated files, NOT the interview context. This ensures genuine independence.

Review dimensions:

1. Completeness — Does every tool referenced in the prompt exist in tools.py? Does every outcome in the prompt have a matching schema path? Does mock_result() cover all three outcomes?

2. Consistency — Do the schema field names match what the prompt tells the agent to produce? Does the model_validator catch all contradictory states? Do the tool function signatures match what the prompt describes?

3. Clarity — Could a developer with zero interview context read agent.py and understand what this agent does? Are the tool docstrings in domain language?

4. Domain Fit — Do tool names sound like domain vocabulary ("lookup_lieferant") or generic abstractions ("search_entity")? Does the prompt read like a professional talking or like a requirements document?

5. Production Readiness — Does before_run() scope knowledge collections? Does after_run() handle persistence failures? Is there a mock_result()? Are MCP toolsets created per-run?

Output: A numbered list of issues with severity (CRITICAL / IMPORTANT / NICE). Fix CRITICAL issues before proceeding to Phase 8. Present IMPORTANT issues to the expert during Phase 8. Log NICE issues as TODOs in the generated code.

Agent Quality Rating (run after Phase 8)

After the expert approves, rate the generated agent on these dimensions. This makes quality visible and specific.

Dimension	Score	What a 10 looks like for THIS agent
Chain-of-Thought Depth	?/10	The thinking chain is specific enough that a junior in the domain could use it as a processing checklist
Tool Coverage	?/10	Every physical tool on the expert's desk has a corresponding agent tool with domain-language naming
Knowledge Completeness	?/10	All books, regulations, and reference materials are specified as collections with real source documents
Example Diversity	?/10	Examples cover complete, clarification, rejection, AND at least one complex edge case with split logic
Schema Strictness	?/10	model_validator prevents every contradictory state; no valid JSON can represent an impossible outcome
Workspace Metaphor Quality	?/10	Reading the prompt feels like sitting at the expert's desk, not reading a requirements spec
Production Readiness	?/10	before_run, after_run, mock_result, per-run toolsets, knowledge scoping, resume detection all present
Eval Coverage	?/10	Promptfoo evals test real domain behavior (correct outcome, correct reasoning) not just JSON shape

Scoring rules:

• Below 6 on any dimension → the agent is not ready for production. Fix before deploying.
• Below 8 on Chain-of-Thought Depth → the interview was too shallow. Go back to Phase 2.
• Below 7 on Example Diversity → go back to Phase 5 and collect more cases.
• Report the total score (out of 80) and the weakest dimension.

Agent Slop Detection

After generation, scan for these anti-patterns that indicate a generic agent rather than a genuine brain clone. Each detected pattern is a generation failure that must be fixed before Phase 8 review.

Pattern	What it looks like	Fix
Identity slop	"You are an expert in X" or "You are a helpful X assistant"	Rewrite with specific years, style traits, and what separates this expert from a beginner
Tool name slop	search_entity(), process_input(), get_data()	Rename to domain language: lookup_lieferant(), get_mandant_info(), search_kontenrahmen()
Missing workspace	Tools listed without desk metaphor	Add "You sit at your desk and have:" with human-readable metaphors for each tool
Uniform examples	All examples end with "complete" or all follow the same structure	Ensure examples cover different outcomes, different complexity levels, and at least one surprise
Abstract Chain-of-Thought	"Analyze the input" / "Check for correctness" / "Process the request"	Replace with specific checks: "What field is missing?" / "Is the tax ID in the right format?" / "Does the amount match the line items?"
Missing clarification triggers	No guidance on WHEN to ask vs. decide	Add explicit triggers: "Ask when X is ambiguous. Decide when Y is clear. Never guess about Z."
Hardcoded domain knowledge	Lookup tables, account mappings, or rules embedded in the prompt	Move to knowledge collections. The prompt teaches HOW to think, books contain WHAT to know.
Missing memory structure	No guidance on what to remember between sessions	Add memory template with sections relevant to the domain
Single-outcome mock	mock_result() only returns "complete"	Generate mocks for all three outcomes with realistic field values
No resume handling	Missing message_history detection in before_run	Add resume detection: if message_history present, continue case without re-processing

Rule: If 3+ slop patterns are detected, the generation failed. Go back to the interview phase that produced the weak output (usually Phase 2 or Phase 5).

Interview Session Persistence

Brain Clone interviews can span multiple sessions. Persist interview state so the conversation can resume.

After each completed phase, write state to disk:

mkdir -p ~/.agent2/brain-clone-sessions

{
  "agent_name": "my-agent",
  "started_at": "2026-04-30T10:00:00Z",
  "current_phase": 3,
  "completed_phases": {
    "phase_1": {"identity": "...", "completed_at": "..."},
    "phase_2": {"chain_of_thought": "...", "completed_at": "..."},
    "phase_2_5": {"premises": [...], "corrections": [...], "completed_at": "..."}
  },
  "pending_phase": 3,
  "expert_name": "...",
  "domain": "..."
}

On skill start, check for existing sessions:

ls ~/.agent2/brain-clone-sessions/*.json 2>/dev/null

If a session exists for the current agent name, offer to resume:

"Found an in-progress brain clone session for '{agent_name}' (Phase {N} of 8, started {date}). Resume where you left off?"

Options:

• A) Resume from Phase {N}
• B) Start fresh (overwrites previous session)

Completion Status Protocol

When completing the Brain Clone workflow, report status using one of:

• DONE — Agent generated, reviewed, and approved by expert. Report the Agent Quality Rating score.
• DONE_WITH_CONCERNS — Agent generated and approved, but some dimensions scored below 7. List the weak dimensions and recommended follow-ups.
• BLOCKED — Cannot proceed. State the blocker (e.g., expert unavailable for Phase 8 review, knowledge documents not provided, OCR dependency missing).
• NEEDS_CONTEXT — Missing information. State exactly what is needed (e.g., "Need 2 more example cases covering rejection outcomes for Phase 5").

Format: STATUS, SCORE (total /80), WEAKEST_DIMENSION, NEXT_ACTION.

Cross-References

• REQUIRED: creating-agents skill for file scaffolding and Docker wiring
• REQUIRED: building-domain-experts skill for the domain expert pattern reference
• REQUIRED: adding-knowledge skill for R2R collection setup and ingestion
• OPTIONAL: adding-capabilities skill for pause/resume and approval workflow details