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 proceeding.

Step 3 — Component Design

For the confirmed pattern, design each of the four components below. Present the designs to the user as you go. Do not write files yet — this step is about design, not output.

3A: Shell Wrapper Design

The shell wrapper is the backbone. It handles everything deterministic. Design it with these sections:

Environment Setup

• Source API keys from environment variables (never hardcode secrets)
• Define paths (log directory, temp directory, prompt file, config file)
• Create directories if they don't exist
• Set timestamp for the current run

Gate Check (prevents double-runs)

GATE_FILE="logs/${AGENT_NAME}_last_run.txt"
MIN_HOURS_BETWEEN_RUNS=44  # adjust per agent

if [ -f "$GATE_FILE" ]; then
    last_run=$(cat "$GATE_FILE")
    now=$(date +%s)
    hours_since=$(( (now - last_run) / 3600 ))
    if [ "$hours_since" -lt "$MIN_HOURS_BETWEEN_RUNS" ]; then
        echo "Gate check: only ${hours_since}h since last run (min: ${MIN_HOURS_BETWEEN_RUNS}h). Skipping."
        exit 0
    fi
fi

Data Acquisition

• API calls using curl with error handling
• Write raw responses to temp files (NEVER store API responses in shell variables — they often contain unescaped control characters that break the shell)
• Validate that the response is not empty or an error

Data Preprocessing

• Strip JSON to essential fields before sending to Claude. This is the single biggest cost optimization. Example: a raw API response might be 12KB per item. After stripping to the 8-10 fields Claude actually needs, it drops to ~750 bytes per item — a 94% reduction in input tokens.
• Use a small Python or jq script to do the stripping. Write the stripped data to a new temp file.

Claude Invocation

• Pipe the prompt file to Claude: cat "$PROMPT_FILE" | claude -p --model {model} --max-turns {turns} --allowedTools {tools}
• NEVER use claude -p "$(cat ...)" — this hits shell ARG_MAX limits with large prompts (150+ items)