updated readme

2026-01-26 20:19:36 +05:00
parent fe7725b47a
commit 4dc4aa7cb1
7 changed files with 161 additions and 59 deletions
@@ -9,6 +9,7 @@ Fetch the current temperature for Karachi, Pakistan and apply transformations.

 ## Workflow

+
 1. Use the AskUserQuestion tool to ask the user whether they want the temperature in Celsius or Fahrenheit
 2. Use the weather-fetcher agent to retrieve the current temperature from wttr.in API in the requested unit
 3. Use the weather-transformer agent to read transformation rules from input/input.md and apply them to the temperature
@@ -1,4 +1,23 @@
 {
+    "permissions": {
+    "allow": [
+      "Edit(*)",
+      "Write(*)",
+      "NotebookEdit(*)",
+      "Bash",
+      "WebFetch(domain:*)",
+      "WebSearch",
+      "mcp__*",
+      "mcp__ide__*",
+      "mcp__chrome-devtools__*",
+      "mcp__claude-in-chrome__*",
+      "mcp__playwright__*"
+    ],
+    "deny": [],
+    "ask": []
+  },
+  "plansDirectory": "./ralph-wiggum/plans",
+  "enableAllProjectMcpServers": true,
  "disableAllHooks": false,
  "hooks": {
    "PreToolUse": [
@@ -6,7 +25,19 @@
        "hooks": [
          {
            "type": "command",
-            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/run-hooks-py-os-wise.sh"
+            "command": "python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/hooks.py",
+            "timeout": 5000
+          }
+        ]
+      }
+    ],
+    "PermissionRequest": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/hooks.py",
+            "timeout": 5000
          }
        ]
      }
@@ -16,7 +47,8 @@
        "hooks": [
          {
            "type": "command",
-            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/run-hooks-py-os-wise.sh"
+            "command": "python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/hooks.py",
+            "timeout": 5000
          }
        ]
      }
@@ -26,7 +58,8 @@
        "hooks": [
          {
            "type": "command",
-            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/run-hooks-py-os-wise.sh"
+            "command": "python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/hooks.py",
+            "timeout": 5000
          }
        ]
      }
@@ -36,7 +69,8 @@
        "hooks": [
          {
            "type": "command",
-            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/run-hooks-py-os-wise.sh"
+            "command": "python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/hooks.py",
+            "timeout": 5000
          }
        ]
      }
@@ -46,7 +80,19 @@
        "hooks": [
          {
            "type": "command",
-            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/run-hooks-py-os-wise.sh"
+            "command": "python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/hooks.py",
+            "timeout": 5000
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/hooks.py",
+            "timeout": 5000
          }
        ]
      }
@@ -56,7 +102,8 @@
        "hooks": [
          {
            "type": "command",
-            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/run-hooks-py-os-wise.sh"
+            "command": "python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/hooks.py",
+            "timeout": 5000
          }
        ]
      }
@@ -66,7 +113,9 @@
        "hooks": [
          {
            "type": "command",
-            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/run-hooks-py-os-wise.sh"
+            "command": "python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/hooks.py",
+            "timeout": 5000,
+            "once": true
          }
        ]
      }
@@ -76,7 +125,9 @@
        "hooks": [
          {
            "type": "command",
-            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/run-hooks-py-os-wise.sh"
+            "command": "python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/hooks.py",
+            "timeout": 5000,
+            "once": true
          }
        ]
      }
@@ -86,10 +137,23 @@
        "hooks": [
          {
            "type": "command",
-            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/run-hooks-py-os-wise.sh"
+            "command": "python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/hooks.py",
+            "timeout": 5000,
+            "once": true
+          }
+        ]
+      }
+    ],
+    "Setup": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/hooks.py",
+            "timeout": 30000
          }
        ]
      }
    ]
  }
-}
+}
@@ -1,12 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "WebFetch(domain:wttr.in)",
-      "WebSearch",
-      "SlashCommand(/weather)",
-      "Bash(cat:*)"
-    ],
-    "deny": [],
-    "ask": []
-  }
-}
@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp"]
+    },
+    "reddit-mcp-server": {
+      "type": "http",
+      "url": "http://144.91.76.33:8080/mcp"
+    }
+  }
+}
@@ -0,0 +1,57 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Repository Overview
+
+This is a best practices repository for Claude Code configuration, demonstrating patterns for agents, commands, hooks, and skills. It serves as a reference implementation rather than an application codebase.
+
+## Key Components
+
+### Weather System (Example Workflow)
+A demonstration of agent orchestration:
+- `/weather` command delegates to `/weather-karachi`
+- `weather-fetcher` agent: fetches temperature from wttr.in API
+- `weather-transformer` agent: applies transformation rules from `input/input.md`, writes results to `output/output.md`
+
+Agents run sequentially, not in parallel, to maintain data dependencies.
+
+### Hooks System
+Cross-platform sound notification system in `.claude/hooks/`:
+- `scripts/hooks.py`: Main handler for all 9 Claude Code hooks
+- `config/hooks-config.json`: Shared team configuration
+- `config/hooks-config.local.json`: Personal overrides (git-ignored)
+- `sounds/`: Audio files organized by hook event
+
+Special handling: git commits trigger `pretooluse-git-committing` sound.
+
+## Critical Patterns
+
+### Agent Orchestration
+Agents **cannot** invoke other agents via bash commands. Use the Task tool:
+```
+Task(subagent_type="agent-name", description="...", prompt="...", model="haiku")
+```
+
+Be explicit about tool usage in agent definitions. Avoid vague terms like "launch" that could be misinterpreted as bash commands.
+
+### Agent Definition Structure
+Agents in `.claude/agents/*.md` use YAML frontmatter:
+- `name`: Agent identifier
+- `description`: When to invoke (use "PROACTIVELY" for auto-invocation)
+- `tools`: Comma-separated list of allowed tools
+- `model`: Typically "haiku" for efficiency
+- `color`: CLI output color for visual distinction
+
+### Configuration Hierarchy
+1. `.claude/settings.local.json`: Personal settings (git-ignored)
+2. `.claude/settings.json`: Team-shared settings
+3. `hooks-config.local.json` overrides `hooks-config.json`
+
+### Disable Hooks
+Set `"disableAllHooks": true` in `.claude/settings.local.json`, or disable individual hooks in `hooks-config.json`.
+
+## Documentation
+
+- `docs/AGENTS.md`: Agent orchestration troubleshooting
+- `docs/WEATHER.md`: Weather system flow diagram
@@ -3,17 +3,20 @@ your best ai assistant with the best practice

 ## CONCEPTS

- **[Agents](https://docs.claude.com/en/docs/claude-code/agents)** - Specialized subprocesses that autonomously handle complex, multi-step tasks
- **[Commands](https://docs.claude.com/en/docs/claude-code/slash-commands)** - Custom slash commands to extend Claude Code with reusable prompts
- **[Memory](https://docs.claude.com/en/docs/claude-code/memory)** - Persistent context that Claude remembers across conversations
- **[Hooks](https://docs.claude.com/en/docs/claude-code/hooks)** - Shell commands that execute in response to events like tool calls
- **[Skills](https://docs.claude.com/en/docs/claude-code/skills)** - Installable capabilities that add specialized functionality to Claude Code
- **[Settings](https://docs.claude.com/en/docs/claude-code/settings)** - Hierarchical configuration system for Claude Code behavior
- **[MCP Servers](https://docs.claude.com/en/docs/claude-code/mcp)** - Model Context Protocol for connecting to external tools, databases, and APIs
- **[Plugins](https://docs.claude.com/en/docs/claude-code/plugins)** - Extensible packages that bundle commands, agents, skills, hooks, and MCP servers
- **[Rules](https://docs.claude.com/en/docs/claude-code/memory#project-rules)** - Modular topic-specific instructions in `.claude/rules/*.md`
- **[Output Styles](https://docs.claude.com/en/docs/claude-code/output-styles)** - Custom system prompt modifications for different use cases
- **[Permissions](https://docs.claude.com/en/docs/claude-code/permissions)** - Fine-grained access control for tools and operations
+> **Note:** Custom slash commands have been merged into skills. Files in `.claude/commands/` still work, but skills (`.claude/skills/`) are recommended as they support additional features like supporting files, invocation control, and subagent execution.
+
+- **[Skills](https://code.claude.com/docs/en/skills)** - Reusable knowledge, workflows, and slash commands that Claude can load on-demand or you invoke with `/skill-name`
+- **[Subagents](https://code.claude.com/docs/en/sub-agents)** - Isolated execution contexts that run their own loops and return summarized results
+- **[Memory](https://code.claude.com/docs/en/memory)** - Persistent context via CLAUDE.md files and `@path` imports that Claude sees every session
+- **[Rules](https://code.claude.com/docs/en/memory#modular-rules-with-clauderules)** - Modular topic-specific instructions in `.claude/rules/*.md` with optional path-scoping via frontmatter
+- **[Hooks](https://code.claude.com/docs/en/hooks)** - Deterministic scripts that run outside the agentic loop on specific events
+- **[MCP Servers](https://code.claude.com/docs/en/mcp)** - Model Context Protocol connections to external tools, databases, and APIs
+- **[Plugins](https://code.claude.com/docs/en/plugins)** - Distributable packages that bundle skills, subagents, hooks, and MCP servers
+- **[Marketplaces](https://code.claude.com/docs/en/discover-plugins)** - Host and discover plugin collections
+- **[Settings](https://code.claude.com/docs/en/settings)** - Hierarchical configuration system for Claude Code behavior
+- **[Permissions](https://code.claude.com/docs/en/iam)** - Fine-grained access control for tools and operations
+
+**Extension Overview:** See [Extend Claude Code](https://code.claude.com/docs/en/features-overview) for when to use each feature and how they layer together.


 ## LESSON LEARNED
@@ -1,26 +1,3 @@
-# Weather Transformation Results
-
-**Original Temperature:** 309.15 K (Kelvin)
-
-**Conversion to Celsius:** 309.15 K - 273.15 = 36°C
-
-**Transformation Applied:** Add +10 to the result
-
-**Calculation:** 36°C + 10 = 46°C
-
-**Final Result in Celsius:** 46°C
-
-**Final Result in Kelvin:** 319.15 K
-
-## Detailed Summary
-
- Input: 309.15 K
- Intermediate (Celsius): 36°C
- After Transformation: 46°C
- Output: 319.15 K
-
-## Calculation Details
-
- Starting value: 309.15 K (equal to 36°C)
- Operation: Add +10
- Result: 36 + 10 = 46°C (equal to 319.15 K)
+Original Temperature: 22°C
+Transformation Applied: add +10 in the result
+Final Result: 32°C