Declarative

.claude/agents/code-flow-mapper.md

@@ -0,0 +1,17 @@
+---
+name: code-flow-mapper
+description: Expert code flow mapper that traces execution paths and file interconnections
+tools: Task, Bash, Glob, Grep, LS, ExitPlanMode, Read, Edit, MultiEdit, Write, NotebookRead, NotebookEdit, WebFetch, TodoWrite, mcp__context7__resolve-library-id, mcp__context7__get-library-docs, ListMcpResourcesTool, ReadMcpResourceTool, mcp__sequential-thinking__sequentialthinking, mcp__ide__executeCode, mcp__ide__getDiagnostics
+color: yellow
+---
+
+You must first read the "INVESTIGATION_REPORT.md" file from the investigator agent, then use ultrathink and sequential thinking to trace execution paths, 
+dependencies, and file interconnections based on the files identified in that report and after your analysis ends create a "FLOW_REPORT.md" inside the 
+task directory that gets automatically created for this task session.
+
+IMPORTANT: You MUST ALWAYS return the following response format and nothing else:
+
+```
+## Flow Report Location:
+The comprehensive flow analysis report has been saved to:
+`[full path to FLOW_REPORT.md file]`

.claude/agents/code-reviewer.md

@@ -0,0 +1,33 @@
+---
+name: code-reviewer
+description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use before commiting.
+tools: Read, Grep, Glob, Bash
+---
+
+You are a senior code reviewer ensuring high standards of code quality and security.
+
+When invoked:
+
+1. Run git diff to see recent changes
+2. Focus on modified files
+3. Begin review immediately
+
+Review checklist:
+
+- Code is simple and readable
+- Functions and variables are well-named
+- No duplicated code
+- Proper error handling
+- No exposed secrets or API keys
+- Input validation implemented
+- Good test coverage
+- Performance considerations addressed
+- No bandaid fixes
+
+Provide feedback organized by priority:
+
+- Critical issues (must fix)
+- Warnings (should fix)
+- Suggestions (consider improving)
+
+Include specific examples of how to fix issues.

.claude/agents/investigator.md

@@ -0,0 +1,17 @@
+---
+name: investigator
+description: Expert code investigator that tracks down related code to the problem
+tools: Task, Bash, Glob, Grep, LS, ExitPlanMode, Read, Edit, MultiEdit, Write, NotebookRead, NotebookEdit, WebFetch, TodoWrite, mcp__context7__resolve-library-id, mcp__context7__get-library-docs, ListMcpResourcesTool, ReadMcpResourceTool, mcp__sequential-thinking__sequentialthinking, mcp__ide__executeCode, mcp__ide__getDiagnostics
+color: cyan
+---
+
+You must ultrathink and use sequential thinking to investigate all codebase files and find the files related to the problem the user has and after 
+your investigation ends create a "INVESTIGATION_REPORT.md" inside the task directory that gets automatically created for this task session.
+
+IMPORTANT: You MUST ALWAYS return the following response format and nothing else:
+
+```
+## Report Location:
+The comprehensive investigation report has been saved to:
+`[full path to INVESTIGATION_REPORT.md file]`
+```

.claude/agents/planner.md

@@ -0,0 +1,20 @@
+---
+name: planner
+description: Expert planner that takes into account investigation and flow analysis reports to create a detailed plan that solves all problems
+tools: Task, Bash, Glob, Grep, LS, ExitPlanMode, Read, Edit, MultiEdit, Write, NotebookRead, NotebookEdit, WebFetch, TodoWrite, mcp__context7__resolve-library-id, mcp__context7__get-library-docs, ListMcpResourcesTool, ReadMcpResourceTool, mcp__sequential-thinking__sequentialthinking, mcp__ide__executeCode, mcp__ide__getDiagnostics
+color: green
+---
+
+You must read both the "INVESTIGATION_REPORT.md" and "FLOW_REPORT.md" files from the task directory, then use ultrathink and sequential thinking to 
+create a super detailed plan to solve the issues, taking into account every single piece of information. The plan should mention in detail 
+all the files that need adjustments for each part of it.
+
+Create a "PLAN.md" file inside the task directory.
+
+IMPORTANT: You MUST ALWAYS return the following response format and nothing else:
+
+```
+## Complete Plan Location:
+The plan has been saved to:
+`[full path to PLAN.md file]`
+```

.claude/commands/commit.md

@@ -0,0 +1,5 @@
+## Instructions
+
+1. Check diffs
+
+2. Commit and push. Avoid using co authored and generated by. Also follow https://www.conventionalcommits.org/en/v1.0.0/#specification guidelines

.claude/commands/task.md

@@ -0,0 +1,20 @@
+Use sequential-thinking mcp and all its tools that you will need about the problem and how to solve it. 
+You must ultrathink for the solution and use reasoning.
+
+You must consider edge cases and follow best coding practices for everything. Never do bandaid fixes.
+
+## Configuration
+
+STEP 1: You must use the investigator subagent (pass to it the full path of the created task-{id} 
+directory) that returns you a "INVESTIGATION_REPORT.md" file.
+
+STEP 2: You must use the code-flow-mapper subagent (pass to it the full path of the created task-{id} 
+directory) that returns you a "FLOW_REPORT.md" file.
+
+STEP 3: You must use the planner subagent (pass to it the full path of the task directory that 
+contains the 2 reports made by the 2 subagents) that reads both reports and creates a "PLAN.md".
+
+STEP 4: After all three subagents finish, enter plan mode and read the "PLAN.md" file and present the plan 
+to the user so that they can either accept or adjust it.
+
+Problem: $ARGUMENTS

.claude/hooks/task_prep_hook.py

@@ -0,0 +1,175 @@
+#!/usr/bin/env python3
+"""
+UserPromptSubmit hook for task directory preparation.
+Automatically creates task-{id} directories and git branches when users type /task.
+"""
+import json
+import os
+import sys
+import re
+import subprocess
+from pathlib import Path
+
+
+def get_next_task_id(base_dir: Path) -> int:
+    """Find the next available task ID by checking existing directories."""
+    if not base_dir.exists():
+        return 1
+
+    existing_dirs = [
+        d for d in base_dir.iterdir() 
+        if d.is_dir() and d.name.startswith('task-')
+    ]
+
+    if not existing_dirs:
+        return 1
+
+    # Extract numbers from directory names
+    numbers = []
+    for dir_path in existing_dirs:
+        match = re.search(r'task-(\d+)', dir_path.name)
+        if match:
+            numbers.append(int(match.group(1)))
+
+    return max(numbers) + 1 if numbers else 1
+
+
+def create_task_directory(base_dir: Path, task_id: int) -> tuple[bool, str]:
+    """Create the task directory and return success status and path."""
+    try:
+        task_dir = base_dir / f"task-{task_id}"
+
+        # Create directories with proper permissions
+        base_dir.mkdir(parents=True, exist_ok=True)
+        task_dir.mkdir(exist_ok=True)
+
+        return True, str(task_dir)
+    except Exception as e:
+        return False, str(e)
+
+
+def validate_git_environment(cwd: str) -> tuple[bool, str]:
+    """Validate git environment is clean before proceeding with task creation."""
+    try:
+        # Check if we're in a git repository
+        result = subprocess.run(
+            ["git", "rev-parse", "--git-dir"], 
+            cwd=cwd, 
+            capture_output=True, 
+            text=True
+        )
+        if result.returncode != 0:
+            return False, "Not in a git repository. Please initialize a git repository first."
+
+        # Check for uncommitted changes
+        result = subprocess.run(
+            ["git", "status", "--porcelain"], 
+            cwd=cwd, 
+            capture_output=True, 
+            text=True
+        )
+        if result.stdout.strip():
+            # Get more detailed status for user
+            status_result = subprocess.run(
+                ["git", "status", "--short"], 
+                cwd=cwd, 
+                capture_output=True, 
+                text=True
+            )
+            return False, f"Uncommitted changes detected. Please commit or stash your changes before starting a new task.\n\nCurrent git status:\n{status_result.stdout}"
+
+        return True, ""
+    except Exception as e:
+        return False, f"Failed to check git environment: {e}"
+
+
+def create_git_branch(branch_name: str, cwd: str) -> bool:
+    """Create and checkout a new git branch for the task."""
+    try:
+        # Check if branch already exists
+        result = subprocess.run(
+            ["git", "rev-parse", "--verify", f"refs/heads/{branch_name}"], 
+            cwd=cwd, 
+            capture_output=True, 
+            text=True
+        )
+        if result.returncode == 0:
+            # Branch exists, just checkout
+            subprocess.run(["git", "checkout", branch_name], cwd=cwd, capture_output=True)
+        else:
+            # Create and checkout new branch
+            subprocess.run(["git", "checkout", "-b", branch_name], cwd=cwd, capture_output=True)
+
+        return True
+    except Exception as e:
+        print(f"Warning: Failed to create git branch: {e}", file=sys.stderr)
+        return False
+
+
+def validate_prompt(prompt: str) -> bool:
+    """Check if prompt starts with /task and requires directory setup."""
+    # Strip whitespace and check for /task at the start
+    cleaned_prompt = prompt.strip()
+    return cleaned_prompt.startswith('/task')
+
+
+def main():
+    """Main hook execution logic."""
+    try:
+        # Read JSON input from stdin
+        input_data = json.load(sys.stdin)
+    except json.JSONDecodeError as e:
+        # Not a JSON input, exit silently
+        sys.exit(0)
+
+    # Extract required fields
+    prompt = input_data.get("prompt", "")
+    cwd = input_data.get("cwd", os.getcwd())
+
+    # Check if this is a task prompt
+    if not validate_prompt(prompt):
+        # Not a task prompt, exit silently to allow normal processing
+        sys.exit(0)
+
+    # Validate git environment before proceeding
+    git_valid, git_error = validate_git_environment(cwd)
+    if not git_valid:
+        print(f"ERROR: Cannot start new task - {git_error}", file=sys.stderr)
+        print("\nTo resolve this issue:", file=sys.stderr)
+        print("  - Commit your changes: git add . && git commit -m 'your message'", file=sys.stderr)
+        print("  - Or stash your changes: git stash", file=sys.stderr)
+        print("  - Or discard changes: git checkout .", file=sys.stderr)
+        sys.exit(2)  # Exit with error code to block the task
+
+    # Get next task ID
+    base_dir = Path(cwd) / "docs" / "plan" / "tasks"
+    task_id = get_next_task_id(base_dir)
+
+    # Create task directory
+    success, result = create_task_directory(base_dir, task_id)
+
+    if success:
+        # Create git branch for this task
+        branch_name = f"task-{task_id}"
+        branch_created = create_git_branch(branch_name, cwd)
+
+        # Extract the original problem from the prompt (after /task)
+        problem_text = prompt.replace('/task', '').strip()
+
+        # Output context message that will be added to the prompt
+        context_msg = f"Directory task-{task_id} has been automatically created for this task session. Git branch 'task-{task_id}' has been created and checked out. The subagents must create the INVESTIGATION_REPORT.md, FLOW_REPORT.md and PLAN.md files inside docs/plan/tasks/task-{task_id}/."
+        if not branch_created:
+            context_msg += " Note: Git branch creation encountered an issue, but task directory was created."
+        if problem_text:
+            context_msg += f" Problem to solve: {problem_text}"
+
+        print(context_msg)
+        sys.exit(0)
+    else:
+        # Output error but don't block processing
+        print(f"Warning: Failed to create task directory: {result}", file=sys.stderr)
+        sys.exit(2)
+
+
+if __name__ == "__main__":
+    main()

.claude/settings.json

@@ -0,0 +1,42 @@
+{
+  "permissions": {
+    "allow": [
+      "WebFetch(domain:docs.anthropic.com)",
+      "WebFetch(domain:github.com)",
+      "mcp__context7__resolve-library-id",
+      "mcp__context7__get-library-docs",
+      "Bash(grep:*)",
+      "Bash(git add:*)",
+      "Bash(sed:*)",
+      "Bash(git push:*)",
+      "Bash(find:*)",
+      "Bash(rg:*)",
+      "Bash(git commit:*)",
+      "Bash(git rm:*)",
+      "mcp__sequential-thinking__sequentialthinking",
+      "Bash(git checkout:*)",
+      "Bash(git pull:*)",
+      "Bash(diff:*)",
+      "Bash(git reset:*)"
+    ],
+    "deny": []
+  },
+  "enableAllProjectMcpServers": true,
+  "enabledMcpjsonServers": [
+    "context7",
+    "sequential-thinking"
+  ],
+  "hooks": {
+    "PreToolUse": [],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/task_prep_hook.py"
+          }
+        ]
+      }
+    ]
+  }
+}

.gitignore

@@ -30,3 +30,6 @@ kongctl
 .vscode/
 
 dist/
+
+# Local development context
+CLAUDE.local.md