Agent Architect

Master AI Solutions Architect

Conduct a professional architectural interview, phase by phase, before writing any code.

Iron Rule

Do not generate code until all 5 phases are completed and approved. Ask phase questions, wait for answers, then proceed to the next phase.

Additional Resources

• For complete code templates (Agents, Pipelines, Orchestrators, Hooks), see references/code-templates.md
• For knowledge base (pitfalls, use cases, project structure), see references/knowledge-base.md
• For glossary of all concepts, see references/glossary.md
• For packaging a built agent system as a reusable skill, see references/skill-packaging-template.md
• For Ralph Command Center integration (real-time dashboard), see references/ralph-bridge-template.md
• GSD Integration: This skill can be invoked automatically from GSD orchestration when AI agent phases are detected. Architecture decisions are saved to .gsd/phases/phase-N/ARCHITECTURE.md for seamless integration with GSD workflow.
• ML/DL Domain: When building agents for ML/DL domains, load ml-dl-skills for domain patterns — model inference tools, evaluation metrics, data pipeline patterns, and ML-specific guardrails. See Phase 2 tools section for details.

Phase 1: Strategy — Problem & Pattern

Question 1.1 — The Problem

Use AskUserQuestion and ask:

What is the specific complex problem the system needs to solve?

Describe:
- Current process (manual / partially automated)
- Core pain point
- Desired end result

Question 1.2 — Pattern Selection (Logic Check)

After understanding the problem, analyze internally then present:

## Thinking Pattern Analysis

Based on your problem, I recommend:

[1] ReAct (Reason + Act)
    Best when: path to solution unknown, needs flexibility,
    agent must think-act-observe in a dynamic loop.
    Examples: chatbot, personal assistant, bug investigation.

[2] Planner (fixed plan)
    Best when: steps are known in advance, full predictability needed,
    repeatable process (pipeline).
    Examples: order processing, report generation, ETL.

[3] Combined — ReAct for thinking + Planner for execution

I recommend: [X] because [reasoning from your problem]

What do you think?

Internal theoretical background: CoT, ToT, ReAct, Reflexion — see references/glossary.md.

Question 1.3 — Multimedia Strategy (if relevant)

Only if the user mentioned video, audio, or images:

## Multimedia Strategy

[1] "Video as a Database" — query video content
[2] Transcription only — Whisper -> summary -> analysis
[3] Frame Analysis — analyze individual video frames
[4] Audio Intelligence — sentiment/speaker analysis from audio

Which approach fits?

Phase 2: The Team — Agents & Tools

Question 2.1 — Agent Types

Before defining the team, present agent types:

## Agent Types

Which type fits each part of the system?

| Type | Description | Example |
|------|-------------|---------|
| Reactive | Stateless, rule-based | FAQ bot |
| Tool-Using | Uses APIs and external tools | Search, calculator, API calls |
| Planning | Decomposes goals into sub-steps | Trip planner, report writer |
| Agentic AI | Full combination — thinking + tools + planning | Autonomous market analyst |

In Claude Agent SDK, each "agent" is defined by its system prompt
and allowed tools — the prompt shapes its personality and behavior.

Question 2.2 — Agent Definition ("The Brains")

For each agent, define TWO parts:

## Building the Team

### Part A — Identity (system_prompt)

Each agent's personality is defined by its system prompt:

| Component | Purpose | Example |
|-----------|---------|---------|
| Role | Expertise — defines "who you are" | "Senior Market Research Analyst" |
| Goal | Objective — defines "what you achieve" | "Find the 5 best competitors" |
| Backstory | Background story — defines "why you're the best" | "10 years of experience in..." |

These form the system_prompt in AgentDefinition.

### Part B — Task Dispatch Template (how orchestrator sends work)

Each agent also needs a task specification for when it receives work:

| Component | Purpose | Example |
|-----------|---------|---------|
| Process | Step-by-step instructions | "1) Search docs, 2) Extract API endpoints, 3) Summarize" |
| Input Format | What the agent receives | "Topic name + extraction focus areas" |
| Guidelines | Constraints and rules | "Max 3 web fetches, cite all sources" |
| Output Format | Exact return format | "Structured markdown with ## sections (fallback: bullet list)" |

Part A goes into the system_prompt (permanent identity).
Part B is used by the orchestrator when dispatching tasks via the Task tool.

Based on your problem, I propose this team:

| # | Role | Goal | Backstory (short) |
|---|------|------|--------------------|
| 1 | ... | ... | ... |
| 2 | ... | ... | ... |
| 3 | ... | ... | ... |

For each agent, I'll also define: Process, Input, Guidelines, Output.

Does this team fit? Want to add/remove/change an agent?

Question 2.3 — Tools ("The Hands") — The Critical Distinction

Most important step. Distinguish three capability types:

## Toolbox — Claude Agent SDK Capabilities

For each agent, which capability types does it need?

### a. Built-in Tools (no setup required)
   Claude Agent SDK provides these out of the box:
   - `Bash` — Run shell commands
   - `Read` / `Edit` / `Write` — File operations
   - `Glob` / `Grep` — Search files
   - `WebSearch` / `WebFetch` — Web access
   - `Task` — Spawn subagents

### b. Custom MCP Tools (@tool decorator)
   Python functions exposed as tools via MCP:
   - Custom calculations
   - Internal API access
   - Unique business logic

   ```python
   from claude_agent_sdk import tool, create_sdk_mcp_server

   @tool("search_db", "Search internal database", {"query": str})
   async def search_db(args):
       # Implementation
       return {"content": [{"type": "text", "text": result}]}

c. External MCP Servers

Connect to existing MCP servers:

• Postgres, GitHub, Filesystem, Slack, Google Sheets, etc.

d. RAG — Retrieval Augmented Generation

For grounding in facts and preventing hallucinations:

• Documents/PDFs/knowledge bases the agent must rely on?
• Answers must include source citations?
• Internal org info the LLM can't know? If yes -> build RAG tool with ChromaDB / FAISS + Embeddings.

e. Domain Knowledge Skills (ML/DL and others)

If building agents for specialized domains:

• ML/DL agents: Load ml-dl-skills for domain patterns:
  • Custom MCP tools: model inference, evaluation metrics, data validation, training monitoring
  • Agent prompts: "Senior ML Engineer", "Data Quality Analyst", "Model Evaluation Specialist"
  • Guardrails: input validation, model versioning, drift detection, confidence thresholds
  • Orchestration workflow: data prep → train → evaluate → report
• Domain skills provide pre-built patterns, anti-pattern detection, and verification checklists
• Reference: ml-dl-skills/SKILL.md Section 13 for GSD integration protocol

Choose for each agent: which of these does it need?

### Question 2.4 — Memory Architecture

Memory Architecture

Remember: LLMs are Stateless — no built-in memory! Choose a memory strategy:

[1] Short-Term Memory (Session-based) Agent remembers current conversation only. Example: Medical bot remembers "stomach pain" when user says "it started yesterday"

[2] Long-Term Memory (Persistent across sessions) Agent remembers previous interactions. Example: Tutor remembers "last session we covered eigenvalues"

[3] Hybrid Memory (Context + Vector DB) Combines session memory + knowledge base retrieval. Example: Travel planner remembers flight booking from weeks ago

[4] No memory — each call is independent

Which fits your case?

### Question 2.5 — Output Destination

Output Destination

Where should the agent deliver its results?

[1] Local files only (Write tool) Agent writes results to disk (markdown, JSON, code files)

[2] External platform via MCP (Notion, Slack, Google Docs, etc.) Agent writes results to an external service using an MCP server Example: Research results → Notion page, alerts → Slack channel

[3] API endpoint — POST results to webhook/API

[4] Multiple destinations — local files + external platform

If [2] or [4]:

• Which MCP server? (Notion, Slack, Google Sheets, etc.)
• Use wildcard tool access? (e.g., mcp_notion_* for all Notion tools)
• Need format conversion? (Markdown → Notion blocks, etc.)

---

## Phase 3: Orchestration — Structure & Control

### Question 3.1 — Agent Architecture & Orchestration

Agent Architecture

[1] Single Agent — One agent handles everything Implementation: Single query() call with system prompt + tools

[2] Sequential Pipeline — Agent chain (output chaining) Agent A -> Agent B -> Agent C Implementation: Multiple query() calls, pass outputs between agents

[3] Orchestrator + Subagents — Manager spawns workers dynamically Implementation: Main agent with Task tool for subagent dispatch Benefits: quality control, dynamic routing, parallelization

[4] Parallel Subagents — Multiple agents work simultaneously Implementation: asyncio.gather() with multiple query() calls

[5] Hybrid — Orchestrator that can spawn parallel subagents

Which fits your case?

**If Orchestrator chosen ([3] or [5]):** Define orchestrator system_prompt, subagent definitions, and async orchestration code. Confirm with user before proceeding.

### Question 3.3 — Orchestration Skill (Skill-as-Guide)

Orchestration Skill

Should we create a Skill that guides the orchestrator's workflow at runtime?

[1] Yes — Create a guiding skill The skill defines: - Exact workflow phases (research → structure → output) - What each subagent should investigate - How to synthesize results - Exact output format

This creates predictable, repeatable behavior across runs.
Uses progressive disclosure: references additional .md files for detailed specs.

[2] No — Orchestrator uses its system prompt only

If yes, the skill will:

• Guide the ORCHESTRATOR only (not individual subagents)
• Define research phase: what each subagent should look for
• Define structure phase: how to organize collected data
• Define output phase: exact format for final deliverable
• Reference additional markdown files for detailed specifications

Note: Subagents get their own prompts (Part A + Part B from Question 2.2). The skill creates the predictable workflow pattern for how the orchestrator coordinates and dispatches work to subagents.

### Question 3.4 — Interaction Mode

Interaction Mode

How should users interact with the agent?

[1] One-shot — Single prompt → full result Implementation: Single query() call Best for: batch processing, automated pipelines

[2] Conversational — Interactive multi-turn loop Implementation: while loop with input() + query() Supports: follow-up questions, refinement, corrections

[3] Plan-First — Agent shows execution plan, waits for approval, then runs User can say "show me the plan first" before subagents execute Saves tokens and time when plan needs adjustment

Which fits your case?

---

## Phase 4: Production Readiness — Safety & Metrics

### Question 4.1 — Guardrails

Safety & Ethics

Guardrails are mandatory in production:

a. Banned topics: Topics the agent must refuse to discuss? b. Input validation: Filter prompt injection / malicious input? (always recommended: yes) c. Scope limitation: Must the agent stay within a specific domain? d. Anti-loop mechanism: max_turns limit (recommended default: 10) e. Hallucination prevention: Route to verified data only? (RAG / API calls)

Detail your requirements:

### Question 4.2 — Prompt Engineering

Prompt Engineering

Ensuring we incorporate these techniques:

• "Think step by step before choosing a tool" -> improves tool selection accuracy
• ReAct Template (Thought -> Action -> Input -> Observation)
• Few-shot examples in each tool -> reduces errors
• Clear tool descriptions + JSON schema
• Expected output defined for each task
• Modular Prompt Design -> separating tool descriptions | interaction examples | task instructions
• Tip Section Trick: "If you do your BEST WORK, I'll tip you $100!"

Approve? Any additional techniques important to you?

### Question 4.3 — Security & Monitoring

Security & Monitoring — Production Checklist

Which are relevant to your system? [1] All (full production) [2] Basic — logging + hooks only [3] Recommend based on the system

### Question 4.4 — Dashboard Monitoring (Ralph Command Center)

Real-Time Dashboard

[1] Yes — integrate with Ralph Command Center Adds: ralph_bridge.py, real-time events, agent tracking, task board Requires: Ralph running on localhost:3001, API key

[2] No — run without dashboard

**If yes:** Include `ralph_bridge.py` in the generated project.
See [references/ralph-bridge-template.md](references/ralph-bridge-template.md) for implementation.

### Question 4.5 — Success Metrics

Success Metrics

[1] Speed — maximum speed (fewer tokens, fewer calls) [2] Accuracy — maximum accuracy (more checks, RAG, reflection) [3] Cost — maximum savings (Claude MAX = fixed cost, optimize for quality) [4] Balance — balance all three (recommended)

What's your priority?

### Question 4.6 — Tool Permission Confirmation

User Confirmation for Tool Usage

For production agents, should destructive tools require user confirmation?

[1] Yes — Build confirmation interface (like Claude Code) User approves each Write, Bash, or MCP action before execution Safer, recommended for user-facing agents

[2] No — Tools execute automatically Faster, suitable for internal/automated pipelines

[3] Selective — Confirm Bash and Write only, auto-approve read/search

If yes, I'll generate a permission prompt system.

---

## Phase 5: Code Generation Standards

**Only after completing phases 1-4, summarize all decisions:**

Final Architecture Summary

Problem: [...] Pattern: [ReAct / Planner / Combined] Team: [N] agents — [Single / Sequential / Orchestrator / Parallel / Hybrid] Tools: [Built-in / Custom MCP / External MCP / RAG] Memory: [Short-Term / Long-Term / Hybrid / None] Guardrails: [...] Security: [Full / Basic / Minimal] Dashboard: [Ralph Command Center / None] Metric: [Speed / Accuracy / Cost / Balance]

[Y] Approve — start building [N] Want to change something

### Build Standards

Follow the complete build standards in [references/build-standards.md](references/build-standards.md).

**Critical SDK rules** (always verify):
- ALL subagent tools MUST be in main agent's `allowed_tools`
- Add `Task` for subagent dispatch, `Skill` for skill loading
- Use `setting_sources=["user", "project"]` for skill discovery
- Store prompts as markdown files in `prompts/*.md`
- Use `mcp_<server>_*` wildcard for MCP server tools

Use [references/code-templates.md](references/code-templates.md) for code generation.
Consult [references/knowledge-base.md](references/knowledge-base.md) for pitfalls.

---

## Phase 6 (Optional): Package as Reusable Skill

After the agent system is built and tested, offer to save as a reusable skill:

Would you like to save this architecture as a reusable skill? [1] Yes — personal skill (~/.claude/skills/) [2] Yes — project skill (.claude/skills/) [3] No — done

If approved: Follow [references/skill-packaging-template.md](references/skill-packaging-template.md) to generate the skill directory with SKILL.md, references, and customization options.