updated readme

.claude/commands/weather-karachi.md

@@ -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

.claude/settings.json

@@ -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,7 +137,20 @@
         "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
           }
         ]
       }

.claude/settings.local.json

@@ -1,12 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "WebFetch(domain:wttr.in)",
-      "WebSearch",
-      "SlashCommand(/weather)",
-      "Bash(cat:*)"
-    ],
-    "deny": [],
-    "ask": []
-  }
-}

.mcp.json

@@ -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"
+    }
+  }
+}

CLAUDE.md

@@ -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

README.md

@@ -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
+> **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.
-- **[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
+- **[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`
-- **[Hooks](https://docs.claude.com/en/docs/claude-code/hooks)** - Shell commands that execute in response to events like tool calls
+- **[Subagents](https://code.claude.com/docs/en/sub-agents)** - Isolated execution contexts that run their own loops and return summarized results
-- **[Skills](https://docs.claude.com/en/docs/claude-code/skills)** - Installable capabilities that add specialized functionality to Claude Code
+- **[Memory](https://code.claude.com/docs/en/memory)** - Persistent context via CLAUDE.md files and `@path` imports that Claude sees every session
-- **[Settings](https://docs.claude.com/en/docs/claude-code/settings)** - Hierarchical configuration system for Claude Code behavior
+- **[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
-- **[MCP Servers](https://docs.claude.com/en/docs/claude-code/mcp)** - Model Context Protocol for connecting to external tools, databases, and APIs
+- **[Hooks](https://code.claude.com/docs/en/hooks)** - Deterministic scripts that run outside the agentic loop on specific events
-- **[Plugins](https://docs.claude.com/en/docs/claude-code/plugins)** - Extensible packages that bundle commands, agents, skills, hooks, and MCP servers
+- **[MCP Servers](https://code.claude.com/docs/en/mcp)** - Model Context Protocol connections to external tools, databases, and APIs
-- **[Rules](https://docs.claude.com/en/docs/claude-code/memory#project-rules)** - Modular topic-specific instructions in `.claude/rules/*.md`
+- **[Plugins](https://code.claude.com/docs/en/plugins)** - Distributable packages that bundle skills, subagents, hooks, and MCP servers
-- **[Output Styles](https://docs.claude.com/en/docs/claude-code/output-styles)** - Custom system prompt modifications for different use cases
+- **[Marketplaces](https://code.claude.com/docs/en/discover-plugins)** - Host and discover plugin collections
-- **[Permissions](https://docs.claude.com/en/docs/claude-code/permissions)** - Fine-grained access control for tools and operations
+- **[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

output/output.md

@@ -1,26 +1,3 @@
-# Weather Transformation Results
+Original Temperature: 22°C
-
+Transformation Applied: add +10 in the result
-**Original Temperature:** 309.15 K (Kelvin)
+Final Result: 32°C
-
-**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)