Shayan Rais
168 lines
7.3 KiB
Markdown
168 lines
7.3 KiB
Markdown
# 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
|