claude-code-best-practice/docs/WEATHER.md

Weather Karachi System Flow

This document describes the complete flow of the weather data fetching and transformation system.

System Overview

The weather system consists of slash commands and specialized agents that work together to fetch and transform temperature data for Karachi, Pakistan.

Flow Diagram

┌─────────────────────────────────────────────────────────────────┐
│                        User Interaction                         │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
                    ┌──────────────────┐
                    │  /weather        │
                    │  Command         │
                    └──────────────────┘
                              │
                              │ calls
                              ▼
                    ┌──────────────────┐
                    │ /weather-karachi │
                    │  Command         │
                    └──────────────────┘
                              │
                              │ Step 1 (Sequential)
                              ▼
                  ┌────────────────────────┐
                  │  weather-fetcher       │
                  │  Agent                 │
                  │  (subagent_type)       │
                  └────────────────────────┘
                              │
                              ▼
                  ┌────────────────────────┐
                  │  wttr.in API           │
                  │  Fetch Temperature     │
                  │  for Karachi           │
                  └────────────────────────┘
                              │
                              │ Returns: 26°C
                              ▼
                              │
                              │ Step 2 (Sequential)
                              ▼
                  ┌─────────────────────────┐
                  │  weather-transformer    │
                  │  Agent                  │
                  │  (subagent_type)        │
                  └─────────────────────────┘
                              │
                              ▼
                  ┌─────────────────────────┐
                  │  input/input.md         │
                  │  Read Transform Rules   │
                  └─────────────────────────┘
                              │
                              │ Reads: "add +10"
                              ▼
                  ┌────────────────────────┐
                  │  Apply Transform       │
                  │  26 + 10 = 36°C        │
                  └────────────────────────┘
                              │
                              ▼
                  ┌────────────────────────┐
                  │  output/output.md      │
                  │  Write Results         │
                  └────────────────────────┘
                              │
                              ▼
                  ┌────────────────────────┐
                  │  Display Summary       │
                  │  to User               │
                  └────────────────────────┘

Component Details

1. Slash Commands

/weather

• Location: .claude/commands/weather.md
• Purpose: Entry point for weather operations
• Action: Calls /weather-karachi command
• Model: haiku

/weather-karachi

• Location: .claude/commands/weather-karachi.md
• Purpose: Orchestrates the weather fetching and transformation workflow
• Action: Launches two specialized agents sequentially
• Model: haiku

2. Specialized Agents

weather-fetcher

• Location: .claude/agents/weather-fetcher.md
• Purpose: Fetch real-time temperature data
• Data Source: wttr.in API for Karachi, Pakistan
• Output: Temperature in Celsius (numeric value)
• Tools Available: WebFetch

weather-transformer

• Location: .claude/agents/weather-transformer.md
• Purpose: Apply mathematical transformations to temperature data
• Input Source: input/input.md (transformation rules)
• Output Destination: output/output.md (formatted results)
• Tools Available: Read, Write

3. Data Files

input/input.md

• Purpose: Stores transformation rules
• Format: Natural language instructions (e.g., "add +10 in the result")
• Access: Read by weather-transformer agent

output/output.md

• Purpose: Stores formatted transformation results
• Format: Structured markdown with sections:
  • Original Temperature
  • Transformation Applied
  • Final Result
  • Calculation Details

Execution Flow

1. User Invocation: User runs /weather command
2. Command Delegation: /weather delegates to /weather-karachi
3. Sequential Agent Execution:
   • Step 1: weather-fetcher agent fetches current temperature from wttr.in
   • Step 2: weather-transformer agent:
     • Reads transformation rules from input/input.md
     • Applies rules to the fetched temperature
     • Formats and writes results to output/output.md
4. Result Display: Summary shown to user with:
   • Original temperature
   • Transformation rule applied
   • Final transformed result

Example Execution

Input: /weather
├─ Calls: /weather-karachi
│  ├─ Agent: weather-fetcher
│  │  └─ Result: 26°C
│  ├─ Agent: weather-transformer
│  │  ├─ Reads: input/input.md ("add +10")
│  │  ├─ Calculates: 26 + 10 = 36°C
│  │  └─ Writes: output/output.md
│  └─ Output:
│     ├─ Original: 26°C
│     ├─ Transform: Add +10
│     └─ Result: 36°C

Key Design Principles

1. Separation of Concerns: Each component has a single, clear responsibility
2. Sequential Execution: Agents run in order to ensure data dependencies are met
3. Specialized Agents: Task-specific agents with minimal tool access
4. Command Chaining: Simple commands can delegate to more complex workflows
5. Configurable Transformations: Rules stored externally in input files
6. Structured Output: Results formatted consistently in output files