agent-architecture-planner

# Agent Architecture Planner

Design autonomous agents using the "Shell Orchestrates, Claude Thinks" pattern. This skill takes a workflow description, selects the right architecture pattern, and produces a complete agent package: shell wrapper, system prompt, config, scheduling setup, and cost estimate.

The core principle: **the shell handles everything deterministic** (API calls, file I/O, scheduling, budget tracking), and **Claude handles everything that requires judgment** (scoring, filtering, writing, categorizing). This separation makes agents cheaper, more reliable, and easier to debug.

---

## Tools Used

| Tool | Purpose |
|---|---|
| `Read` | Check for existing agent docs, load reference files |
| `Write` | Output all agent architecture files |
| `Bash` | Make shell scripts executable, verify directory structure |
| `Glob` | Check for existing agents to avoid naming conflicts |

---

## Methodology

Follow these steps in order. Do not skip steps. Do not produce output files before completing the discovery interview and confirming the architecture with the user.

---

### Step 1 — Workflow Discovery (Interactive)

Present these questions to the user **all at once** in a numbered list. Tell the user they can answer inline or paste a block of text.

Ask exactly these questions:

```
I need to understand the workflow before designing the agent. Answer these 6 questions — be as specific as possible.

1. What task do you want to automate? (Describe the manual workflow as you do it today, step by step.)
2. How often should it run? (Every hour, daily, every 2 days, weekly, on-demand only?)
3. What data sources does it need? (APIs, websites to scrape, databases, local files, RSS feeds?)
4. What should it produce? (Report files, database entries, API calls, Slack messages, emails, CSV exports?)
5. What decisions does it need to make? (Scoring relevance, filtering noise, writing content, categorizing items, choosing actions?)
6. What's your budget constraint? (Max cost per run in dollars, or monthly ceiling. Include both API/data costs and LLM costs if you know them.)
```

**Rules for this step:**
- Wait for the user to respond before proceeding. Do NOT generate placeholder answers.
- If question 1 is vague (less than 3 concrete steps described), ask a focused follow-up: _"Walk me through the last time you did this manually. What did you open first? What did you check? What did you produce at the end?"_
- If question 3 mentions an API, ask: _"Does this API require authentication? What format does it return (JSON, XML, CSV)? Is there a rate limit?"_
- At most 2 follow-up rounds before proceeding.

---

### Step 2 — Architecture Pattern Selection

Based on the user's answers, recommend **one** of these four patterns. Present the recommended pattern and briefly explain why it fits. If two patterns are close, present both and let the user choose.

---

#### Pattern A: Simple Pipeline

```
Shell (acquire data) → JSON temp file → Claude (analyze + act) → Output
```

**Best for:** Single data source, single output. The most common pattern. Use this when the workflow is: get data, think about it, produce something.

**Examples:** Daily report generation, email draft writing from CRM data, log analysis, document summarization.

**When to use:**
- One data source (or multiple sources that can be merged trivially)
- No feedback loop needed
- Output is a single artifact (file, database push, message)

---

#### Pattern B: Dual-Layer Pipeline

```
Shell → Layer 1 (broad collection) → Layer 2 (targeted search) → Merge + Dedup → Claude (analyze + act) → Output
```

**Best for:** Monitoring and discovery workflows where comprehensive coverage matters. Layer 1 casts a wide net (e.g., scrape all new posts from 20 sources). Layer 2 does targeted searches for specific keywords or patterns. Results are merged and deduplicated before Claude sees them.

**Examples:** Social media monitoring, job posting tracking, competitor mention detection, market signal scanning.

**When to use:**
- You need to catch everything (missing a relevant item is costly)
- Data comes from overlapping sources that produce duplicates
- The volume of raw data is high but only 5-20% is relevant

---

#### Pattern C: Multi-Agent Decomposition

```
Orchestrator Shell → [Agent 1: Research] → [Agent 2: Analysis] → [Agent 3: Writing] → Merge → Output
```

**Best for:** Complex workflows where different steps need fundamentally different expertise or prompting strategies. Each sub-agent has its own system prompt optimized for its specific task.

**Examples:** Content production pipelines (research → outline → draft → edit), multi-step analysis (collect data → score → generate recommendations → format report), workflows where one step's output determines the next step's approach.

**When to use:**
- A single system prompt cannot cover all the judgment needed
- The workflow has 3+ distinct phases that require different thinking
- You need to be able to debug or improve each phase independently

---

#### Pattern D: Feedback Loop

```
Shell → Collect → Claude (score + filter) → Act → Log results → [wait] → Shell reads logs → Collect → Claude (score with history) → ...
```

**Best for:** Ongoing optimization workflows where each run should learn from previous runs. The shell maintains a log of past decisions and outcomes, and feeds them back to Claude as context on subsequent runs.

**Examples:** A/B testing content strategies, lead scoring with win/loss feedback, adaptive outreach sequences, quality improvement loops.

**When to use:**
- Performance should improve over time
- You have a feedback signal (open rates, conversion, engagement, human ratings)
- The agent runs repeatedly on similar data

---

**Present your recommendation to the user:**

_"Based on your workflow, I recommend **Pattern {X}: {Name}**. Here's why: {1-2 sentence justification}. Does this feel right, or should we look at an alternative?"_

Wait for confirmation before pro