claudeguide-engineer 1.14.8

package/.claude/commands/scout/ext.md

@@ -0,0 +1,35 @@
+---
+description: ⚡ Use external agentic tools to scout given directories
+argument-hint: [user-prompt] [scale]
+---
+
+## Purpose
+
+Utilize external agentic tools to scout given directories or explore the codebase for files needed to complete the task using a fast, token efficient agent.
+
+## Variables
+
+USER_PROMPT: $1
+SCALE: $2 (defaults to 3)
+RELEVANT_FILE_OUTPUT_DIR: `plans/<plan-name>/reports/`
+
+## Workflow:
+- Write a prompt for 'SCALE' number of agents to the `Task` tool that will immediately call the `Bash` tool to run these commands to kick off your agents to conduct the search:
+  - `gemini -p "[prompt]" --model gemini-2.5-flash-preview-09-2025` (if count <= 3)
+  - `opencode run "[prompt]" --model opencode/grok-code` (if count > 3 and count < 6)
+  - if count >= 6, spawn `Explore` subagents to search the codebase in parallel
+
+**Why use external agentic tools?**
+- External agentic tools are faster and more efficient when using LLMs with large context windows (1M+ tokens).
+
+**How to prompt the agents:**
+- If `gemini` or `opencode` is not available, ask the user if they want to install it:
+  - If **yes**, install it (if there are permission issues, instruct the user to install it manually, including authentication steps)
+  - If **no**, use the default `Explore` subagents.
+- IMPORTANT: Kick these agents off in parallel using the `Task` tool, analyze and divide folders for each agent to scout intelligently and quickly.
+- IMPORTANT: These agents are calling OTHER agentic coding tools to search the codebase. DO NOT call any search tools yourself.
+- IMPORTANT: That means with the `Task` tool, you'll immediately call the Bash tool to run the respective agentic coding tool (gemini, opencode, claude, etc.)
+- IMPORTANT: Instruct the agents to quickly search the codebase for files needed to complete the task. This isn't about a full blown search, just a quick search to find the files needed to complete the task.
+- Instruct the subagent to use a timeout of 3 minutes for each agent's bash call. Skip any agents that don't return within the timeout, don't restart them.
+- **IMPORTANT:** Sacrifice grammar for the sake of concision when writing reports.
+- **IMPORTANT:** In reports, list any unresolved questions at the end, if any.

package/.claude/commands/scout.md

@@ -0,0 +1,28 @@
+---
+description: ⚡⚡ Scout given directories to respond to the user's requests
+argument-hint: [user-prompt] [scale]
+---
+
+## Purpose
+
+Search the codebase for files needed to complete the task using a fast, token efficient agent.
+
+## Variables
+
+USER_PROMPT: $1
+SCALE: $2 (defaults to 3)
+REPORT_OUTPUT_DIR: `plans/<plan-name>/reports/scout-report.md`
+
+## Workflow:
+
+- Write a prompt for 'SCALE' number of agents to the `Task` tool that will immediately call the `Bash` tool to run these commands to kick off your agents to conduct the search: spawn many `Explore` subagents to search the codebase in parallel based on the user's prompt.
+
+**How to prompt the agents:**
+- IMPORTANT: Kick these agents off in parallel using the `Task` tool, analyze and divide folders for each agent to scout intelligently and quickly.
+- IMPORTANT: Instruct the agents to quickly search the codebase for files needed to complete the task. This isn't about a full blown search, just a quick search to find the files needed to complete the task.
+- Instruct the subagent to use a timeout of 3 minutes for each agent's bash call. Skip any agents that don't return within the timeout, don't restart them.
+
+**How to write reports:**
+
+- **IMPORTANT:** Sacrifice grammar for the sake of concision when writing reports.
+- **IMPORTANT:** In reports, list any unresolved questions at the end, if any.

package/.claude/commands/skill/add.md

@@ -0,0 +1,29 @@
+---
+description: Add new reference files or scripts to a skill
+argument-hint: [skill-name] [reference-or-script-prompt]
+---
+
+Think harder.
+Use `skill-creator` and `claude-code` skills.
+Use `docs-seeker` skills to search for documentation if needed.
+
+## Arguments
+$1: skill name (required, default: "")
+$2: reference or script prompt (required, default: "")
+If $1 or $2 is not provided, ask the user to provide it.
+
+## Your mission
+Add new reference files or scripts to a skill at `.claude/skills/$1` directory.
+
+## Requirements
+<reference-or-script-prompt>
+$2
+</reference-or-script-prompt>
+
+## Rules of Skill Creation:
+Base on the requirements:
+- Always keep in mind that `SKILL.md` and reference files should be token consumption efficient, so that **progressive disclosure** can be leveraged at best.
+- If you're given an URL, it's documentation page, use `Explore` subagent to explore every internal link and report back to main agent, don't skip any link.
+- If you receive a lot of URLs, use multiple `Explore` subagents to explore them in parallel, then report back to main agent.
+- If you receive a lot of files, use multiple `Explore` subagents to explore them in parallel, then report back to main agent.
+- If you're given a Github URL, use [`repomix`](https://repomix.com/guide/usage) command to summarize ([install it](https://repomix.com/guide/installation) if needed) and spawn multiple `Explore` subagents to explore it in parallel, then report back to main agent.

package/.claude/commands/skill/create.md

@@ -0,0 +1,22 @@
+---
+description: Create a new agent skill
+argument-hint: [prompt-or-llms-or-github-url]
+---
+
+Ultrathink.
+Use `skill-creator` and `claude-code` skills.
+Use `docs-seeker` skills to search for documentation if needed.
+
+## Your mission
+Create a new skill in `.claude/skills/` directory.
+
+## Requirements
+<user-prompt>$ARGUMENTS</user-prompt>
+
+## Rules of Skill Creation:
+Base on the requirements:
+- Always keep in mind that `SKILL.md` and reference files should be token consumption efficient, so that **progressive disclosure** can be leveraged at best.
+- If you're given an URL, it's documentation page, use `Explore` subagent to explore every internal link and report back to main agent, don't skip any link.
+- If you receive a lot of URLs, use multiple `Explore` subagents to explore them in parallel, then report back to main agent.
+- If you receive a lot of files, use multiple `Explore` subagents to explore them in parallel, then report back to main agent.
+- If you're given a Github URL, use [`repomix`](https://repomix.com/guide/usage) command to summarize ([install it](https://repomix.com/guide/installation) if needed) and spawn multiple `Explore` subagents to explore it in parallel, then report back to main agent.

package/.claude/commands/skill/fix-logs.md

@@ -0,0 +1,21 @@
+---
+description: Fix the agent skill based on `logs.txt` file.
+argument-hint: [prompt-or-path-to-skill]
+---
+
+Think harder.
+Use `skill-creator` and `claude-code` skills.
+Use `docs-seeker` skills to search for documentation if needed.
+
+## Your mission
+Fix the agent skill based on the current `logs.txt` file (in the project root directory).
+
+## Requirements
+<user-prompt>$ARGUMENTS</user-prompt>
+
+## Rules of Skill Fixing:
+Base on the requirements:
+- If you're given an URL, it's documentation page, use `Explorer` subagent to explore every internal link and report back to main agent, don't skip any link.
+- If you receive a lot of URLs, use multiple `Explorer` subagents to explore them in parallel, then report back to main agent.
+- If you receive a lot of files, use multiple `Explorer` subagents to explore them in parallel, then report back to main agent.
+- If you're given a Github URL, use [`repomix`](https://repomix.com/guide/usage) command to summarize ([install it](https://repomix.com/guide/installation) if needed) and spawn multiple `Explorer` subagents to explore it in parallel, then report back to main agent.

package/.claude/commands/skill/optimize.md

@@ -0,0 +1,28 @@
+---
+description: Optimize an existing agent skill
+argument-hint: [skill-name] [prompt]
+---
+
+Think harder.
+Use `skill-creator` and `claude-code` skills.
+Use `docs-seeker` skills to search for documentation if needed.
+
+## Arguments
+SKILL: $1 (default: `*`)
+PROMPT: $2 (default: empty)
+
+## Your mission
+Propose a plan to optimize an existing skill in `.claude/skills/${SKILL}` directory. 
+When you finish, ask user to review your plan:
+- If the user approve: Write down a plan follow "Output Requirements", then ask user if they want to start implementing.
+- If the user reject: Revise the plan or ask more questions to clarify more about the user's request (ask one question at the time), then repeat the review process.
+
+## Additional instructions
+<additional-instructions>$PROMPT</additional-instructions>
+
+## Output Requirements
+An output implementation plan must also follow the progressive disclosure structure:
+- Always keep in mind that `SKILL.md` and reference files should be token consumption efficient, so that **progressive disclosure** can be leveraged at best.
+- Create a directory `plans/YYYYMMDD-HHmm-plan-name` (example: `plans/20251101-1505-authentication-and-profile-implementation`).
+- Save the overview access point at `plan.md`, keep it generic, under 80 lines, and list each phase with status/progress and links.
+- For each phase, add `phase-XX-phase-name.md` files containing sections (Context links, Overview with date/priority/statuses, Key Insights, Requirements, Architecture, Related code files, Implementation Steps, Todo list, Success Criteria, Risk Assessment, Security Considerations, Next steps).

package/.claude/commands/test.md

@@ -0,0 +1,8 @@
+---
+description: ⚡ Run tests locally and analyze the summary report.
+---
+
+Use the `tester` subagent to run tests locally and analyze the summary report.
+
+**IMPORTANT**: **Do not** start implementing.
+**IMPORTANT:** Analyze the skills catalog and activate the skills that are needed for the task during the process.

package/.claude/commands/use-mcp.md

@@ -0,0 +1,34 @@
+---
+description: Utilize tools of Model Context Protocol (MCP) servers
+argument-hint: [task]
+---
+Execute MCP operations via **Gemini CLI** to preserve context budget.
+
+## Execution Steps
+
+1. **Execute task via Gemini CLI** (using stdin pipe for MCP support):
+   ```bash
+   # IMPORTANT: Use stdin piping, NOT -p flag (deprecated, skips MCP init)
+   echo "$ARGUMENTS. Return JSON only per GEMINI.md instructions." | gemini -y -m gemini-2.5-flash
+   ```
+
+2. **Fallback to mcp-manager subagent** (if Gemini CLI unavailable):
+   - Use `mcp-manager` subagent to discover and execute tools
+   - If the subagent got issues with the scripts of `mcp-management` skill, use `mcp-builder` skill to fix them
+   - **DO NOT** create ANY new scripts
+   - The subagent can only use MCP tools if any to achieve this task
+   - If the subagent can't find any suitable tools, just report it back to the main agent to move on to the next step
+
+## Important Notes
+
+- **MUST use stdin piping** - the deprecated `-p` flag skips MCP initialization
+- Use `-y` flag to auto-approve tool execution
+- **GEMINI.md auto-loaded**: Gemini CLI automatically loads `GEMINI.md` from project root, enforcing JSON-only response format
+- **Parseable output**: Responses are structured JSON: `{"server":"name","tool":"name","success":true,"result":<data>,"error":null}`
+
+## Anti-Pattern (DO NOT USE)
+
+```bash
+# BROKEN - deprecated -p flag skips MCP server connections!
+gemini -y -m gemini-2.5-flash -p "..."
+```

package/.claude/commands/watzup.md

@@ -0,0 +1,8 @@
+---
+description: ⚡ Review recent changes and wrap up the work
+---
+Review my current branch and the most recent commits. 
+Provide a detailed summary of all changes, including what was modified, added, or removed. 
+Analyze the overall impact and quality of the changes.
+
+**IMPORTANT**: **Do not** start implementing.

package/.claude/hooks/.env.example

@@ -0,0 +1,15 @@
+# Claude Code Hooks - Local Environment Variables
+# This file is for hook-specific environment variables (lowest priority)
+# Priority: process.env > .claude/.env > .claude/hooks/.env
+# Copy this file to .env and fill in your actual values
+
+# ============================================
+# Discord Notifications
+# ============================================
+DISCORD_WEBHOOK_URL=
+
+# ============================================
+# Telegram Notifications
+# ============================================
+TELEGRAM_BOT_TOKEN=
+TELEGRAM_CHAT_ID=

package/.claude/hooks/README.md

@@ -0,0 +1,339 @@
+# Claude Code Notification Hooks
+
+This directory contains notification hooks for Claude Code sessions. These hooks send real-time notifications to Discord and Telegram when Claude completes tasks.
+
+## Overview
+
+Claude Code hooks automate notifications and actions at specific points in your development workflow. This project includes notification systems for Discord and Telegram:
+
+| Hook | File | Type | Description |
+|------|------|------|-------------|
+| **Scout Block** | `scout-block.js` | Automated | Cross-platform hook blocking heavy directories (node_modules, .git, etc.) |
+| **Modularization** | `modularization-hook.js` | Automated | Non-blocking suggestions for files >200 LOC to encourage code modularization |
+| **Discord (Auto)** | `discord_notify.sh` | Automated | Auto-sends rich embeds on session/subagent completion |
+| **Discord (Manual)** | `send-discord.sh` | Manual | Sends custom messages to Discord channel |
+| **Telegram** | `telegram_notify.sh` | Automated | Auto-sends detailed notifications on session/subagent completion |
+
+### Cross-Platform Support
+
+**Scout Block Hook** now supports both Windows and Unix systems:
+- **Windows**: Uses PowerShell (`scout-block.ps1`)
+- **Linux/macOS/WSL**: Uses Bash (`scout-block.sh`)
+- **Automatic detection**: `scout-block.js` dispatcher selects the correct implementation
+
+No manual configuration needed - the Node.js dispatcher handles platform detection automatically.
+
+## Quick Start
+
+### Current Setup
+Check **[SETUP-SUMMARY.md](./SETUP-SUMMARY.md)** for current configuration and quick reference.
+
+### Scout Block Hook (Cross-Platform)
+Automatically blocks Claude Code from accessing heavy directories to improve performance.
+
+**Configuration:** Already enabled in `.claude/settings.json`
+
+**Blocked Patterns:**
+- `node_modules/` - NPM dependencies
+- `__pycache__/` - Python cache
+- `.git/` - Git internal files
+- `dist/` - Distribution builds
+- `build/` - Build artifacts
+
+**Testing:**
+```bash
+# Linux/macOS/WSL
+bash tests/test-scout-block.sh
+
+# Windows PowerShell
+pwsh tests/test-scout-block.ps1
+```
+
+**Requirements:**
+- Node.js >=18.0.0 (already required by project)
+
+### Modularization Hook (Automated)
+Automatically analyzes files after Write/Edit operations and suggests modularization for large files.
+
+**Configuration:** Already enabled in `.claude/settings.json`
+
+**Behavior:**
+- Triggers on Write/Edit tool usage
+- Analyzes file line count (LOC)
+- Suggests modularization if >200 LOC
+- **Non-blocking**: Claude continues main task automatically
+- Provides context-aware guidance using `additionalContext`
+
+**Testing:**
+```bash
+# Create test file with 205 lines
+for i in {1..205}; do echo "console.log('Line $i');"; done > /tmp/test-large.js
+
+# Test hook (should output modularization suggestion)
+echo '{"tool_input":{"file_path":"/tmp/test-large.js"}}' | node .claude/hooks/modularization-hook.js
+
+# Test with small file (should be silent)
+echo "console.log('test');" > /tmp/test-small.js
+echo '{"tool_input":{"file_path":"/tmp/test-small.js"}}' | node .claude/hooks/modularization-hook.js
+```
+
+**Requirements:**
+- Node.js >=18.0.0 (already required by project)
+
+**How It Works:**
+1. Hook receives file path from Write/Edit tool
+2. Counts lines in modified file
+3. If >200 LOC, injects suggestion into Claude's context
+4. Claude receives guidance but continues without blocking
+5. Exit code 0 ensures non-blocking behavior
+
+### Discord Hook (Automated)
+Automatic notifications on Claude Code session events with rich embeds.
+
+**Setup:** [discord-hook-setup.md](./discord-hook-setup.md)
+
+**Quick Test:**
+```bash
+echo '{"hookType":"Stop","projectDir":"'$(pwd)'","sessionId":"test","toolsUsed":[{"tool":"Read","parameters":{"file_path":"test.ts"}}]}' | ./.claude/hooks/discord_notify.sh
+```
+
+### Discord Hook (Manual)
+Send custom notifications to Discord with your own messages.
+
+**Quick Test:**
+```bash
+./.claude/hooks/send-discord.sh 'Test notification'
+```
+
+### Telegram Hook
+Automatic notifications on Claude Code session events.
+
+**Setup:** [telegram-hook-setup.md](./telegram-hook-setup.md)
+
+**Quick Test:**
+```bash
+echo '{"hookType":"Stop","projectDir":"'$(pwd)'","sessionId":"test","toolsUsed":[]}' | ./.claude/hooks/telegram_notify.sh
+```
+
+## Documentation
+
+### Quick Reference
+- **[Setup Summary](./SETUP-SUMMARY.md)** - Current configuration, testing, and troubleshooting
+
+### Detailed Setup Guides
+
+- **[Discord Hook Setup](./discord-hook-setup.md)** - Complete Discord webhook configuration
+- **[Telegram Hook Setup](./telegram-hook-setup.md)** - Complete Telegram bot configuration
+
+### What's Included in Each Guide
+
+**Discord Hook Guide:**
+- Discord webhook creation
+- Environment configuration
+- Manual & automated usage
+- Message formatting
+- Troubleshooting
+- Advanced customization
+
+**Telegram Hook Guide:**
+- Telegram bot creation
+- Chat ID retrieval
+- Global vs project config
+- Hook event configuration
+- Testing procedures
+- Security best practices
+
+## Features Comparison
+
+| Feature | Discord (Auto) | Discord (Manual) | Telegram |
+|---------|----------------|------------------|----------|
+| **Trigger Type** | Automatic on events | Manual invocation | Automatic on events |
+| **Message Style** | Rich embeds | Rich embeds | Markdown formatted |
+| **Setup Complexity** | Simple (webhook only) | Simple (webhook only) | Medium (bot + chat ID) |
+| **Use Case** | Session monitoring | Custom messages | Session monitoring |
+| **Events** | Stop, SubagentStop | On-demand | Stop, SubagentStop |
+| **Tool Tracking** | Yes | No | Yes |
+| **File Tracking** | Yes | No | Yes |
+
+## Scripts
+
+### modularization-hook.js
+PostToolUse hook for automated code modularization suggestions.
+
+**Triggers:**
+- `Write` - File creation
+- `Edit` - File modification
+
+**Required:** None (standalone Node.js script)
+
+**Features:**
+- LOC (Lines of Code) analysis
+- Non-blocking execution (exit code 0)
+- Context injection via `additionalContext`
+- Kebab-case naming guidance
+- Automatic continuation after suggestion
+
+### discord_notify.sh
+Automated Discord notification hook for Claude Code events with rich embeds.
+
+**Triggers:**
+- `Stop` - Main session completion
+- `SubagentStop` - Subagent task completion
+
+**Required:** `DISCORD_WEBHOOK_URL` environment variable
+
+**Features:**
+- Rich embeds with session details
+- Tool usage statistics (with counts)
+- File modification tracking
+- Session ID and timestamps
+- Color-coded by event type
+
+### send-discord.sh
+Manual Discord notification script with rich embed formatting.
+
+**Usage:**
+```bash
+./.claude/hooks/send-discord.sh 'Your message here'
+```
+
+**Required:** `DISCORD_WEBHOOK_URL` environment variable
+
+### telegram_notify.sh
+Automated Telegram notification hook for Claude Code events.
+
+**Triggers:**
+- `Stop` - Main session completion
+- `SubagentStop` - Subagent task completion
+
+**Required:** `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` environment variables
+
+## Configuration
+
+### Environment Variables
+
+Environment variables are loaded with the following priority (highest to lowest):
+1. **process.env** - System/shell environment variables
+2. **.claude/.env** - Project-level Claude configuration
+3. **.claude/hooks/.env** - Hook-specific configuration
+
+Create environment files based on your needs:
+
+**Project Root `.env`** (recommended for general use):
+```bash
+# Discord
+DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/YOUR_WEBHOOK_ID/YOUR_TOKEN
+
+# Telegram
+TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz
+TELEGRAM_CHAT_ID=987654321
+```
+
+**OR `.claude/.env`** (for project-specific overrides):
+```bash
+# Same variables as above
+```
+
+**OR `.claude/hooks/.env`** (for hook-only configuration):
+```bash
+# Same variables as above
+```
+
+See `.env.example` files in each location for templates.
+
+### Claude Code Hooks Config
+
+Hooks are configured in `.claude/settings.local.json`:
+
+```json
+{
+  "hooks": {
+    "Stop": [{
+      "hooks": [{
+        "type": "command",
+        "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/telegram_notify.sh"
+      }]
+    }],
+    "SubagentStop": [{
+      "hooks": [{
+        "type": "command",
+        "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/telegram_notify.sh"
+      }]
+    }]
+  }
+}
+```
+
+## Security
+
+**⚠️ Important Security Practices:**
+
+1. **Never commit tokens/webhooks:**
+   ```bash
+   # Add to .gitignore
+   .env
+   .env.*
+   ```
+
+2. **Use environment variables** - Never hardcode credentials
+
+3. **Rotate tokens regularly** - Regenerate periodically
+
+4. **Limit permissions** - Minimum required access only
+
+5. **Monitor usage** - Check for unauthorized activity
+
+See individual setup guides for detailed security recommendations.
+
+## Troubleshooting
+
+### Scout Block Hook
+
+**"Node.js not found"**
+- Install Node.js >=18.0.0 from [nodejs.org](https://nodejs.org)
+- Verify installation: `node --version`
+
+**Hook not blocking directories**
+- Verify `.claude/settings.json` uses `node .claude/hooks/scout-block.js`
+- Test manually: `echo '{"tool_input":{"command":"ls node_modules"}}' | node .claude/hooks/scout-block.js`
+- Should exit with code 2 and error message
+
+**Windows PowerShell execution policy errors**
+- Run: `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`
+- Or use bypass flag (already included in dispatcher)
+
+**Testing the hook**
+- Linux/macOS/WSL: `bash tests/test-scout-block.sh`
+- Windows: `pwsh tests/test-scout-block.ps1`
+
+### Notification Hooks
+
+**"Environment variable not set"**
+- Verify `.env` file exists and is properly formatted
+- Reload shell after updating profile files (`source ~/.bashrc`)
+
+**"jq: command not found"** (Legacy - no longer needed)
+- All hooks now use Node.js for JSON parsing
+- No jq dependency required
+
+**No messages received**
+- Verify tokens/webhooks are valid
+- Check network connectivity
+- Ensure proper permissions
+
+### Getting Help
+
+- Check individual setup guides for detailed troubleshooting
+- Review [Claude Code Documentation](https://docs.claude.com/claude-code)
+- Report issues at [Claude Code GitHub](https://github.com/anthropics/claude-code/issues)
+
+## Additional Resources
+
+- [Claude Code Documentation](https://docs.claude.com/claude-code)
+- [Claude Code Hooks Reference](https://docs.claude.com/claude-code/hooks)
+- [Discord Webhooks Guide](https://discord.com/developers/docs/resources/webhook)
+- [Telegram Bot API](https://core.telegram.org/bots/api)
+
+---
+
+**Last Updated:** 2025-11-04