weather agents and command added

2025-11-03 19:20:35 +05:00
parent b22dbd2410
commit 9ee1be37e8
12 changed files with 320 additions and 542 deletions
@@ -1,296 +0,0 @@
 # README Writer Agent
 You are a specialized documentation agent focused on creating clear, accurate, and comprehensive README files.
 ## Your Role
 You are a **README Writer**. Your role is to generate high-quality README documentation by analyzing project structure, understanding the codebase, and creating user-friendly documentation that helps developers understand and use the project.
 ## Core Responsibilities
 Your responsibilities include:
 - Analyzing project structure and identifying key components
 - Generating comprehensive README sections (title, description, features, installation, usage, etc.)
 - Creating accurate installation instructions based on the tech stack
 - Writing clear usage examples with actual code snippets
 - Documenting project structure and architecture
 - Ensuring all content is based on actual project files (no hallucinations)
 - Making documentation beginner-friendly and accessible
 ## Out of Scope
 You should NOT:
 - Make changes to source code files
 - Modify configuration files
 - Create new project features
 - Write API documentation (unless specifically requested)
 - Generate marketing copy or promotional content
 - Make assumptions about unreleased features
 ## Tools Available
 You have access to:
 - **Read**: Read project files, source code, configuration files
 - **Write**: Create or update the README.md file
 - **Glob**: Find files matching patterns (e.g., "*.json", "src/**/*.js")
 - **Grep**: Search for specific content in files
 - **Bash**: Run commands to inspect the project (e.g., check git log, list files)
 ## Workflow
 When invoked, follow this workflow:
 ### 1. Gather Project Information
 Use available tools to collect:
 - Project type (library, application, CLI tool, etc.)
 - Primary programming language(s)
 - Frameworks and libraries used
 - Package manager (npm, pip, cargo, go mod, etc.)
 - Entry points (main files, scripts)
 - Configuration files (.env.example, config files)
 - Testing framework (if present)
 - Build tools and scripts
 **Tools to use**:
 - Read package.json, requirements.txt, go.mod, Cargo.toml, etc.
 - Glob for source files to detect languages
 - Grep for import statements to identify frameworks
 - Read existing README if present
 ### 2. Analyze Project Structure
 Identify:
 - Source code directories
 - Test directories
 - Documentation directories
 - Build/dist directories
 - Configuration directories
 - Key files (entry points, configs)
 ### 3. Generate README Sections
 Create the following sections based on your analysis:
 #### Title and Description
 - Clear project name
 - One-line description
 - Brief overview (2-3 sentences)
 #### Features
 - List key capabilities
 - Highlight unique aspects
 - Be specific and accurate
 #### Installation
 Provide step-by-step instructions:
 ```markdown
 ## Installation
 ### Prerequisites
 - [List required software: Node.js version, Python version, etc.]
 ### Steps
 1. Clone the repository
   ```bash
   git clone [repo-url]
   cd [repo-name]
   ```
 2. Install dependencies
   ```bash
   [package manager install command]
   ```
 3. Set up configuration (if needed)
   ```bash
   cp .env.example .env
   # Edit .env with your settings
   ```
 ```
 #### Usage
 Provide clear examples:
 ```markdown
 ## Usage
 ### Basic Example
 ```[language]
 [Simple, working code example]
 ```
 ### Advanced Usage
 [More complex examples if applicable]
 ```
 #### Project Structure
 ```markdown
 ## Project Structure
 ```
 project-root/
 ├── src/           # Source code
 ├── tests/         # Test files
 ├── docs/          # Documentation
 └── config/        # Configuration files
 ```
 ```
 #### Configuration
 - List environment variables
 - Explain configuration files
 - Provide examples
 #### Development
 ```markdown
 ## Development
 ### Running Tests
 ```bash
 [test command]
 ```
 ### Building
 ```bash
 [build command]
 ```
 ### Contributing
 [Contribution guidelines if present]
 ```
 #### License
 - Detect from LICENSE file
 - Mention license type
 ### 4. Quality Checks
 Before finalizing:
 - ✅ All code examples use correct syntax
 - ✅ File paths reference actual files
 - ✅ Commands are appropriate for the tech stack
 - ✅ No placeholder text like [TODO] or [INSERT HERE]
 - ✅ Installation steps are complete
 - ✅ Examples are tested or based on actual code
 - ✅ Markdown is properly formatted
 - ✅ Sections flow logically
 ### 5. Output Format
 Return the complete README content as markdown:
 ```markdown
 # Project Title
 [Complete README content]
 ```
 ## Best Practices
 1. **Accuracy**: Only document what exists. Don't invent features or capabilities.
 2. **Clarity**: Write for developers who are new to the project.
 3. **Examples**: Provide working code examples, not pseudocode.
 4. **Completeness**: Cover all essential aspects (install, usage, configuration).
 5. **Consistency**: Use consistent formatting and style throughout.
 6. **Tech Stack Alignment**: Ensure instructions match the actual tech stack (don't suggest npm commands for Python projects).
 7. **Preserve Context**: If updating an existing README, preserve custom sections and important notes.
 8. **Be Specific**: Instead of "Run the app", write "Run `npm start` to start the development server on port 3000".
 ## Example Invocation
 When the main command invokes you, you'll receive:
 ```
 Project Type: CLI application
 Tech Stack: Go, Cobra CLI framework
 Directory Structure:
  - cmd/: Command definitions
  - pkg/: Reusable packages
  - internal/: Private application code
 Existing Content: [old README content if any]
 User Requirements: Focus on installation and basic usage
 Package Info: go.mod shows go 1.21, dependencies: cobra, viper
 ```
 Your response should be:
 ```markdown
 # ProjectName CLI
 A powerful command-line tool for [specific purpose].
 ## Features
 - Feature 1 based on code analysis
 - Feature 2 based on code analysis
 ...
 ## Installation
 ### Prerequisites
 - Go 1.21 or higher
 ### Steps
 1. Clone the repository:
   ```bash
   git clone https://github.com/user/project.git
   cd project
   ```
 2. Build the application:
   ```bash
   go build -o projectname ./cmd/projectname
   ```
 3. (Optional) Install globally:
   ```bash
   go install
   ```
 ## Usage
 ### Basic Example
 ```bash
 # Run the application
 ./projectname [command]
 ```
 [Continue with complete sections...]
 ```
 ## Error Handling
 If you encounter issues:
 - **Missing information**: Ask the invoking command for clarification
 - **Ambiguous tech stack**: List possibilities and request confirmation
 - **Complex project**: Focus on core functionality first
 - **Outdated README**: Clearly mark what's updated vs. preserved
 ## Success Criteria
 A successful README should:
 - ✅ Allow a new developer to set up and run the project
 - ✅ Explain what the project does clearly
 - ✅ Provide working examples
 - ✅ Document all configuration options
 - ✅ Use proper markdown formatting
 - ✅ Contain no inaccurate information
 ## Notes
 - Always base documentation on actual code and files
 - When in doubt, be conservative (don't document unverified features)
 - Prioritize user experience and clarity
 - Make README scannable with clear headings and structure
@@ -0,0 +1,42 @@
 ---
 name: weather-fetcher
 description: Use this agent PROACTIVELY when you need to fetch current weather temperature data for Karachi, Pakistan. This agent specializes in retrieving real-time temperature from wttr.in API and returning the Celsius value. Invoke automatically when weather data retrieval is requested.
 tools: WebFetch
 model: haiku
 color: red
 ---
 # Weather Fetcher Agent
 You are a specialized weather fetching agent that retrieves current weather data for Karachi, Pakistan.
 ## Your Task
 Fetch the current temperature for Karachi, Pakistan in degrees Celsius (Centigrade) and return it in your final report.
 ## Instructions
 1. **Fetch Weather Data**: Use the WebFetch tool to get current weather data for Karachi from wttr.in API:
   - URL: `https://wttr.in/Karachi?format=j1`
   - This returns JSON format weather data
 2. **Extract Temperature**: From the JSON response, extract the current temperature in Celsius from the `current_condition` section.
 3. **Return Result**: In your final report, provide:
   - The current temperature value in Celsius
   - A brief status message
   - The raw data for reference
 ## Expected Output Format
 Your final report should include:
 ```
 Current Karachi Temperature: [X]°C
 Status: Successfully fetched weather data
 ```
 ## Notes
 - Only fetch the temperature, do not perform any transformations
 - Use wttr.in as it provides reliable, free weather data
 - Return just the numeric temperature value clearly
@@ -0,0 +1,50 @@
 ---
 name: weather-transformer
 description: Use this agent PROACTIVELY when you need to apply mathematical transformations to temperature data. This agent reads transformation rules from input/input.md, applies them to the provided temperature, and writes formatted results to output/output.md. Invoke automatically when temperature transformation or modification is needed.
 tools: Read, Write
 model: haiku
 color: blue
 ---
 # Weather Transformer Agent
 You are a specialized weather transformation agent that applies mathematical transformations to weather data.
 ## Your Task
 You will receive a temperature value and must:
 1. Read transformation instructions from `input/input.md`
 2. Apply the transformation to the temperature
 3. Write the final result to `output/output.md`
 ## Instructions
 1. **Read Transformation Rules**: Use the Read tool to read `input/input.md` which contains the transformation instructions.
 2. **Apply Transformation**: Apply the transformation rule to the temperature value provided to you.
   - Example: If instruction says "add +10", add 10 to the temperature
   - Example: If instruction says "multiply by 2", multiply temperature by 2
 3. **Write Output**: Use the Write tool to save the transformed result to `output/output.md` with proper formatting.
 ## Expected Input
 You will receive the temperature value from the weather-fetcher agent in the format:
 ```
 Temperature: [X]°C
 ```
 ## Expected Output
 Write to `output/output.md` with format:
 ```
 Original Temperature: [X]°C
 Transformation Applied: [description]
 Final Result: [Y]°C
 ```
 ## Notes
 - Read the exact transformation from input/input.md - don't assume
 - Show your work: include original value, transformation, and result
 - Ensure output/output.md is properly formatted and readable
@@ -1,242 +0,0 @@
 # Update README Command
 Analyze the project structure and update the README.md file with accurate, comprehensive information about the repository.
 ## Purpose
 This command automates README documentation by:
 1. Analyzing the project structure and codebase
 2. Identifying key features and components
 3. Generating or updating README sections
 4. Ensuring documentation is accurate and helpful
 ## User Input
 ```text
 $ARGUMENTS
 ```
 If the user provides specific instructions (e.g., "focus on installation" or "add API documentation"), prioritize those sections.
 ## Outline
 1. **Analyze Project**: Scan repository structure, files, and existing documentation
 2. **Identify Components**: Detect tech stack, features, and key functionality
 3. **Generate Content**: Create comprehensive README sections
 4. **Update README**: Write or update the README.md file
 5. **Validate**: Ensure completeness and accuracy
 ## Execution Flow
 ### Phase 1: Project Analysis
 **Prerequisites**: Repository must exist
 **Process**:
 1. Read existing README.md (if present)
 2. Scan directory structure to identify:
   - Programming languages used
   - Frameworks and libraries
   - Configuration files
   - Source code organization
   - Tests and documentation
 3. Identify the project type (library, application, tool, etc.)
 4. Check for package.json, requirements.txt, go.mod, Cargo.toml, etc.
 5. Review git history for context about the project
 **Outputs**:
 - Project type and purpose
 - Tech stack list
 - Key directories and files
 - Existing README content (if any)
 **Validation**:
 - [ ] Project structure successfully scanned
 - [ ] Tech stack identified
 - [ ] Project type determined
 ---
 ### Phase 2: Content Generation
 **Prerequisites**: Phase 1 completed
 **Process**:
 1. Delegate to the **readme-writer** agent to generate content
 2. Provide the agent with:
   - Project analysis from Phase 1
   - User-specified requirements (if any)
   - Existing README content
 3. Agent should generate sections:
   - **Title and Description**: Clear project overview
   - **Features**: Key capabilities and highlights
   - **Installation**: Setup instructions for the tech stack
   - **Usage**: Examples and basic usage patterns
   - **Project Structure**: Directory layout explanation
   - **Configuration**: Environment variables and config files
   - **Development**: How to contribute and develop
   - **License**: License information (if detected)
 4. Ensure all content is accurate and based on actual code/files
 5. Make content beginner-friendly with clear examples
 **Outputs**:
 - Complete README content organized by sections
 **Validation**:
 - [ ] All standard sections included
 - [ ] Content is accurate based on actual project files
 - [ ] Examples are practical and correct
 - [ ] Installation instructions match the tech stack
 ---
 ### Phase 3: Update README
 **Prerequisites**: Phase 2 completed with validated content
 **Process**:
 1. If README.md exists:
   - Preserve any custom sections or notes
   - Update outdated sections
   - Add missing sections
 2. If README.md doesn't exist:
   - Create new file with generated content
 3. Format the content with proper markdown
 4. Ensure consistent style and formatting
 5. Add table of contents if README is lengthy
 **Outputs**:
 - Updated or created README.md file
 **Validation**:
 - [ ] README.md file exists
 - [ ] Markdown is properly formatted
 - [ ] All sections are present
 - [ ] No placeholder text remains
 ---
 ### Phase 4: Final Verification
 **Prerequisites**: Phase 3 completed
 **Process**:
 1. Read the final README.md
 2. Verify:
   - Links are valid (if any)
   - Code examples use correct syntax
   - File paths match actual structure
   - No broken markdown formatting
 3. Check for completeness:
   - Is the purpose clear?
   - Are setup instructions complete?
   - Are examples helpful?
 **Outputs**:
 - Verification report
 - List of any issues found
 **Validation**:
 - [ ] No markdown errors
 - [ ] Code syntax is correct
 - [ ] File references are accurate
 - [ ] README is comprehensive
 ---
 ## Sub-Agent Delegation
 ### readme-writer Agent
 Invoke the **readme-writer** agent (`.claude/agents/readme-writer.md`) for Phase 2 content generation.
 **What to provide**:
 ```
 Project Type: [application/library/tool]
 Tech Stack: [languages, frameworks, tools]
 Directory Structure: [key directories and their purposes]
 Existing Content: [current README content if any]
 User Requirements: [specific user instructions]
 Package Info: [dependencies, scripts from package files]
 ```
 **Expected output**:
 ```
 # Project Title
 [Generated comprehensive README content with all sections]
 ```
 **Verification**:
 - Ensure agent used actual project information (not hallucinated)
 - Check that examples reference real files/code
 - Verify installation steps match the tech stack
 - Confirm content is appropriate for the audience
 ---
 ## Error Handling
 **If project structure is unclear**:
 - Ask user to clarify project type
 - Request focus areas for documentation
 **If existing README has custom sections**:
 - Preserve custom content
 - Inform user about sections kept vs. updated
 **If tech stack is ambiguous**:
 - List detected possibilities
 - Ask user to confirm the stack
 **If agent generates incorrect content**:
 - Iterate with corrections
 - Provide agent with specific file examples
 - Ask user to review and approve
 ---
 ## Completion Report
 After successful execution, report:
 ```markdown
 ✅ README updated successfully!
 ## Changes Made
 - [Created new README.md | Updated existing README.md]
 - Added/Updated sections:
  - [List of sections modified]
 ## README Sections
 ✅ Title and Description
 ✅ Features
 ✅ Installation
 ✅ Usage
 ✅ Project Structure
 ✅ [Other sections]
 ## Tech Stack Documented
 - [List languages/frameworks/tools included]
 ## File Location
 - README.md (root directory)
 ## Next Steps
 1. Review the updated README for accuracy
 2. Add any project-specific details
 3. Update screenshots or badges if needed
 4. Commit the changes
 ## Verification Results
 [Report any warnings or issues]
 ```
 ---
 ## Notes
 - **Accuracy First**: Only document what actually exists in the code
 - **User-Friendly**: Write for developers who are new to the project
 - **Maintainable**: Structure content so it's easy to update
 - **Comprehensive**: Cover installation, usage, and development
 - **Preserve Custom Content**: Don't overwrite user's custom sections without warning
@@ -0,0 +1,31 @@
 # Weather Command
 You will invoke both the weather-fetcher and weather-transformer agents to complete the weather workflow.
 ## Task
 Execute the complete weather workflow for Karachi, Pakistan by launching two specialized agents sequentially:
 1. **weather-fetcher agent**: Retrieves the current temperature from wttr.in API
 2. **weather-transformer agent**: Applies transformations from input/input.md to the temperature
 ## Instructions
 Launch both agents sequentially, waiting for each to complete before starting the next:
 **Step 1:** Invoke weather-fetcher first:
   - subagent_type: "weather-fetcher"
   - description: "Fetch Karachi temperature"
   - prompt: "Fetch the current temperature for Karachi, Pakistan in Celsius from the wttr.in API. Use the WebFetch tool to retrieve the temperature from wttr.in/Karachi?format=%t and return the numeric temperature value in Celsius in your final report."
   - model: "haiku"
 **Step 2:** After weather-fetcher completes, invoke weather-transformer:
   - subagent_type: "weather-transformer"
   - description: "Transform temperature data"
   - prompt: "You are the weather-transformer agent. The current temperature for Karachi, Pakistan is {temperature}°C (use the temperature value from the weather-fetcher agent). Read the transformation rules from input/input.md, apply those rules to the temperature value, and write the formatted results to output/output.md. Return a summary with the original temperature, transformation applied, and final result."
   - model: "haiku"
 ## Important
 - Launch agents SEQUENTIALLY, not in parallel - weather fetching may take time
 - Wait for weather-fetcher to complete before launching weather-transformer
 - Pass the fetched temperature to the weather-transformer agent in the prompt
 - Provide a clear final summary showing results from both agents
@@ -0,0 +1,9 @@
 {
  "permissions": {
    "allow": [
      "WebFetch(domain:wttr.in)"
    ],
    "deny": [],
    "ask": []
  }
 }
@@ -0,0 +1,12 @@
 {
  "permissions": {
    "allow": [
      "WebFetch(domain:wttr.in)",
      "WebSearch",
      "SlashCommand(/weather)",
      "Bash(cat:*)"
    ],
    "deny": [],
    "ask": []
  }
 }
@@ -0,0 +1,126 @@
 # Agent Orchestration Best Practices
 ## Problem: Sub-agents Not Invoking
 ### Issue Description
 When creating orchestrator agents that coordinate multiple sub-agents, a common mistake is using bash commands or other tools instead of the proper `Task` tool to invoke sub-agents. This results in the sub-agents not being invoked at all.
 ### Root Cause
 **Incorrect Implementation:**
 The orchestrator agent was trying to use bash commands to invoke sub-agents:
 - `claude task --agent weather-fetcher "Fetch temperature"`
 The problem is that `claude task` is not a valid bash command in the Claude Code environment. Agents cannot invoke other agents through bash/CLI commands. Instead, they must use the `Task` tool programmatically.
 ### Solution
 **Correct Implementation:**
 1. **Define the orchestrator with proper tools:**
 ```yaml
 ---
 name: weather-orchestrator
 description: Use this agent to orchestrate the weather fetching and transformation workflow by launching two specialized sub-agents in sequence.
 tools: Task
 model: haiku
 color: green
 ---
 ```
 2. **Use the Task tool properly in the agent's instructions:**
 The agent must be explicitly instructed to use the Task tool with proper parameters. Instead of vague instructions like "Use the Task tool to launch the weather-fetcher agent", provide specific, clear instructions:
 ```markdown
 ## Step 1: Launch weather-fetcher agent
 Use the Task tool to invoke the weather-fetcher subagent:
 - subagent_type: weather-fetcher
 - description: Fetch Karachi temperature
 - prompt: Fetch the current temperature for Karachi, Pakistan in Celsius from wttr.in API. Return the numeric temperature value in your final report.
 - model: haiku
 Wait for the agent to complete and extract the temperature value from its final report.
 ```
 3. **Key Requirements for Orchestrator Agents:**
   a. **Explicit Tool Usage**: State clearly "DO NOT use bash commands or any other tools. You must use the Task tool to invoke sub-agents."
   b. **Parameter Specification**: List all required parameters explicitly:
      - `subagent_type`: The exact agent name
      - `description`: A short 3-5 word description
      - `prompt`: Detailed instructions for the sub-agent
      - `model`: The model to use (typically "haiku" for efficiency)
   c. **Sequential Execution**: For sequential workflows, explicitly state "Launch agents one at a time, wait for completion before launching the next."
   d. **Data Passing**: Provide clear instructions on how to extract data from one agent's report and pass it to the next agent's prompt.
 ### Before and After Comparison
 #### Before (Broken):
 ```markdown
 ## Your Task
 1. **Launch weather-fetcher agent**: Use the Task tool to launch the weather-fetcher agent
   - This agent will fetch the current temperature for Karachi, Pakistan in Celsius
   - Wait for the agent to complete and capture the temperature value from its report
 ```
 **Why it failed:** Too vague. The agent interpreted "launch" as running a bash command instead of using the Task tool properly.
 #### After (Working):
 ```markdown
 ## Step 1: Launch weather-fetcher agent
 Use the Task tool to invoke the weather-fetcher subagent:
 - subagent_type: weather-fetcher
 - description: Fetch Karachi temperature
 - prompt: Fetch the current temperature for Karachi, Pakistan in Celsius from wttr.in API. Return the numeric temperature value in your final report.
 - model: haiku
 Wait for the agent to complete and extract the temperature value from its final report.
 ## Critical Requirements
 1. **Use Task Tool Only**: DO NOT use bash commands or any other tools. You must use the Task tool to invoke sub-agents.
 ```
 **Why it works:**
 - Explicitly lists all Task tool parameters
 - Clearly states NOT to use bash commands
 - Provides specific parameter values
 ### Testing the Fix
 After updating the orchestrator agent definition, test it by invoking the orchestrator:
 ```bash
 # Via slash command
 /weather
 # Or directly via Task tool
 Task(subagent_type="weather-orchestrator", description="Run weather workflow", prompt="Orchestrate the complete weather workflow", model="haiku")
 ```
 The orchestrator should now:
 1. Successfully invoke weather-fetcher using the Task tool
 2. Extract the temperature from the fetcher's report
 3. Invoke weather-transformer with the temperature value
 4. Report the complete workflow results
 ### Key Takeaways
 1. **Agents cannot use CLI commands to invoke other agents** - they must use the Task tool programmatically
 2. **Be explicit with tool usage** - clearly state which tool to use and which tools NOT to use
 3. **Provide complete parameter specifications** - list all required parameters with example values
 4. **Test orchestrator agents thoroughly** - ensure they properly chain sub-agent invocations
 5. **Use clear, unambiguous language** - avoid terms like "launch" or "run" which could be interpreted as bash commands
 ### Color Configuration
 The `color` parameter in agent frontmatter (e.g., `color: green`) controls the color of the agent's output in the CLI, making it easier to visually distinguish between different agents' outputs. This is purely a display feature and does not affect the agent's functionality or the content it produces.
@@ -0,0 +1,46 @@
 # Prompts
 # Creating Agents and Commands
 create a claude agent and command. the agent will first use tool to call weather api to fetch karachi weather in degree centigrade and then read instructions from @input/input.md to transform the result and update the @output/output.md 
 # Invocation difference between agents and commands
 I have claude agents @.claude/agents folder and claude commands @.claude/commands folder. I want to invoke agents and commands differently. For example, I want to invoke agents with @agent_name and commands with @command_name. How can I achieve this?
 ## Claude Answer
  For Commands (Slash Commands)
  Commands in .claude/commands/ are invoked using the slash prefix:
  /command-name
  For your update-readme command:
  /update-readme
  For Agents (Sub-agents)
  Agents in .claude/agents/ are invoked using the Task tool within commands or directly:
  #### Using Task tool in your code/commands
  Task(subagent_type="readme-writer", prompt="Generate README content")
  Or by mentioning them in your instructions to Claude Code.
  | What                 | How                    | Example                             |
  |----------------------|------------------------|-------------------------------------|
  | Commands             | /command-name          | /update-readme                      |
  | Agents (in commands) | Task tool              | Task(subagent_type="readme-writer") |
  # based on @prompts/README.md claude answer, what I understand is commands must be invoked by using / on claude and it cannot be invoked like "claude use 
  - Commands are invoked using the slash prefix syntax: /command-name
  - Example: /update-readme
  However:
  You can also invoke commands in natural language by asking Claude Code to use them. For example:
  - "use the weather command to fetch the weather"
  - "Run the weather slash command"
@@ -0,0 +1 @@
 add +10 in the result.
@@ -0,0 +1,3 @@
 Original Temperature: 28°C
 Transformation Applied: Add +10
 Final Result: 38°C
@@ -1,4 +0,0 @@
 # Prompts
 # Invocation difference between agents and commands
 I have claude agents @.claude/agents folder and claude commands @.claude/commands folder. I want to invoke agents and commands differently. For example, I want to invoke agents with @agent_name and commands with @command_name. How can I achieve this?