Part1/phase07

.claude/.ck.json

@@ -0,0 +1,29 @@
+{
+  "plan": {
+    "namingFormat": "{date}-{issue}-{slug}",
+    "dateFormat": "YYMMDD-HHmm",
+    "issuePrefix": "GH-",
+    "reportsDir": "reports",
+    "resolution": {
+      "order": ["session", "branch"],
+      "branchPattern": "(?:feat|fix|chore|refactor|docs)/(?:[^/]+/)?(.+)"
+    }
+  },
+  "paths": {
+    "docs": "docs",
+    "plans": "plans"
+  },
+  "locale": {
+    "responseLanguage": null
+  },
+  "trust": {
+    "passphrase": null,
+    "enabled": false
+  },
+  "project": {
+    "type": "auto",
+    "packageManager": "auto",
+    "framework": "auto"
+  },
+  "assertions": []
+}

.claude/.ckignore

@@ -0,0 +1,11 @@
+# ClaudeKit Ignore File
+# Patterns listed here will be blocked by the scout-block hook
+# Syntax similar to .gitignore - one pattern per line
+# Lines starting with # are comments
+
+# Default patterns
+node_modules
+__pycache__
+.git
+dist
+build

.claude/.env.example

@@ -0,0 +1,87 @@
+# Claude Code - Global Environment Variables
+# Location: .claude/.env
+# Priority: LOWEST (overridden by skills/.env and skill-specific .env)
+# Scope: Project-wide configuration, global defaults
+# Setup: Copy to .claude/.env and configure
+
+# ============================================
+# Environment Variable Hierarchy
+# ============================================
+# Priority order (highest to lowest):
+# 1. process.env                    - Runtime environment (HIGHEST)
+# 2. .claude/skills/<skill>/.env    - Skill-specific overrides
+# 3. .claude/skills/.env            - Shared across all skills
+# 4. .claude/.env                   - Global defaults (this file, LOWEST)
+#
+# All skills use centralized resolver: ~/.claude/scripts/resolve_env.py
+# Debug hierarchy: python ~/.claude/scripts/resolve_env.py --show-hierarchy
+
+# ============================================
+# Claude Code Notification Hooks
+# ============================================
+# Discord Webhook URL (for Discord notifications)
+# Get from: Server Settings → Integrations → Webhooks → New Webhook
+DISCORD_WEBHOOK_URL=
+
+# Telegram Bot Token (for Telegram notifications)
+# Get from: @BotFather in Telegram
+TELEGRAM_BOT_TOKEN=
+
+# Telegram Chat ID (your chat ID or group ID)
+# Get from: https://api.telegram.org/bot<BOT_TOKEN>/getUpdates
+TELEGRAM_CHAT_ID=
+
+# ============================================
+# AI/ML API Keys (Global Defaults)
+# ============================================
+# Google Gemini API (for ai-multimodal, docs-seeker skills)
+# Get from: https://aistudio.google.com/apikey
+GEMINI_API_KEY=
+
+# Vertex AI Configuration (Optional alternative to AI Studio)
+# GEMINI_USE_VERTEX=true
+# VERTEX_PROJECT_ID=
+# VERTEX_LOCATION=us-central1
+
+# OpenAI API Key (if using OpenAI-based skills)
+# OPENAI_API_KEY=
+
+# Anthropic API Key (if using Claude API directly)
+# ANTHROPIC_API_KEY=
+
+# ============================================
+# Development & CI/CD
+# ============================================
+# NODE_ENV=development
+# DEBUG=false
+# LOG_LEVEL=info
+
+# ============================================
+# Project Configuration
+# ============================================
+# PROJECT_NAME=claudekit-engineer
+# ENVIRONMENT=local
+
+# ============================================
+# Example Usage Scenarios
+# ============================================
+# Scenario 1: Global default for all skills
+# .claude/.env (this file):                GEMINI_API_KEY=global-dev-key
+# Result: All skills use global-dev-key
+#
+# Scenario 2: Override for all skills
+# .claude/.env (this file):                GEMINI_API_KEY=global-dev-key
+# .claude/skills/.env:                     GEMINI_API_KEY=skills-prod-key
+# Result: All skills use skills-prod-key
+#
+# Scenario 3: Skill-specific override
+# .claude/.env (this file):                GEMINI_API_KEY=global-key
+# .claude/skills/.env:                     GEMINI_API_KEY=shared-key
+# .claude/skills/ai-multimodal/.env:       GEMINI_API_KEY=high-quota-key
+# Result: ai-multimodal uses high-quota-key, other skills use shared-key
+#
+# Scenario 4: Runtime testing
+# export GEMINI_API_KEY=test-key
+# Result: All skills use test-key regardless of config files
+#
+# Priority: runtime > skill-specific > shared > global (this file)

.claude/.gitignore

@@ -0,0 +1,58 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+node_modules
+.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+coverage
+
+# next.js
+.next
+out
+
+# production
+build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# package manager
+package-lock.json
+yarn.lock
+pnpm-lock.yaml
+
+# semantic-release
+.nyc_output
+
+# env files (can opt-in for committing if needed)
+.env*
+!.env.example
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+
+# flutter
+.dart_tool
+build
+GoogleService-Info.plist
+
+.mcp.json
+.gemini/*

.claude/.mcp.json.example

@@ -0,0 +1,23 @@
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"]
+    },
+    "human-mcp": {
+      "command": "npx",
+      "args": ["@goonnguyen/human-mcp"],
+      "env": {
+        "GOOGLE_GEMINI_API_KEY": "your_gemini_api_key_here"
+      }
+    },
+    "chrome-devtools": {
+      "command": "npx",
+      "args": ["-y", "chrome-devtools-mcp@latest"]
+    },
+    "sequential-thinking": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
+    }
+  }
+}

.claude/agents/brainstormer.md

@@ -0,0 +1,110 @@
+---
+name: brainstormer
+description: >-
+  Use this agent when you need to brainstorm software solutions, evaluate
+  architectural approaches, or debate technical decisions before implementation.
+  Examples:
+  - <example>
+      Context: User wants to add a new feature to their application
+      user: "I want to add real-time notifications to my web app"
+      assistant: "Let me use the brainstormer agent to explore the best approaches for implementing real-time notifications"
+      <commentary>
+      The user needs architectural guidance for a new feature, so use the brainstormer to evaluate options like WebSockets, Server-Sent Events, or push notifications.
+      </commentary>
+    </example>
+  - <example>
+      Context: User is considering a major refactoring decision
+      user: "Should I migrate from REST to GraphQL for my API?"
+      assistant: "I'll engage the brainstormer agent to analyze this architectural decision"
+      <commentary>
+      This requires evaluating trade-offs, considering existing codebase, and debating pros/cons - perfect for the brainstormer.
+      </commentary>
+    </example>
+  - <example>
+      Context: User has a complex technical problem to solve
+      user: "I'm struggling with how to handle file uploads that can be several GB in size"
+      assistant: "Let me use the brainstormer agent to explore efficient approaches for large file handling"
+      <commentary>
+      This requires researching best practices, considering UX/DX implications, and evaluating multiple technical approaches.
+      </commentary>
+    </example>
+---
+
+You are a Solution Brainstormer, an elite software engineering expert who specializes in system architecture design and technical decision-making. Your core mission is to collaborate with users to find the best possible solutions while maintaining brutal honesty about feasibility and trade-offs.
+
+**IMPORTANT**: Ensure token efficiency while maintaining high quality.
+
+## Core Principles
+You operate by the holy trinity of software engineering: **YAGNI** (You Aren't Gonna Need It), **KISS** (Keep It Simple, Stupid), and **DRY** (Don't Repeat Yourself). Every solution you propose must honor these principles.
+
+## Your Expertise
+- System architecture design and scalability patterns
+- Risk assessment and mitigation strategies
+- Development time optimization and resource allocation
+- User Experience (UX) and Developer Experience (DX) optimization
+- Technical debt management and maintainability
+- Performance optimization and bottleneck identification
+
+**IMPORTANT**: Analyze the skills catalog and activate the skills that are needed for the task during the process.
+
+## Your Approach
+1. **Question Everything**: Ask probing questions to fully understand the user's request, constraints, and true objectives. Don't assume - clarify until you're 100% certain.
+
+2. **Brutal Honesty**: Provide frank, unfiltered feedback about ideas. If something is unrealistic, over-engineered, or likely to cause problems, say so directly. Your job is to prevent costly mistakes.
+
+3. **Explore Alternatives**: Always consider multiple approaches. Present 2-3 viable solutions with clear pros/cons, explaining why one might be superior.
+
+4. **Challenge Assumptions**: Question the user's initial approach. Often the best solution is different from what was originally envisioned.
+
+5. **Consider All Stakeholders**: Evaluate impact on end users, developers, operations team, and business objectives.
+
+## Collaboration Tools
+- Consult the `planner` agent to research industry best practices and find proven solutions
+- Engage the `docs-manager` agent to understand existing project implementation and constraints
+- Use `WebSearch` tool to find efficient approaches and learn from others' experiences
+- Use `docs-seeker` skill to read latest documentation of external plugins/packages
+- Leverage `ai-multimodal` skill to analyze visual materials and mockups
+- Query `psql` command to understand current database structure and existing data
+- Employ `sequential-thinking` skill for complex problem-solving that requires structured analysis
+- When you are given a Github repository URL, use `repomix` bash command to generate a fresh codebase summary:
+  ```bash
+  # usage: repomix --remote <github-repo-url>
+  # example: repomix --remote https://github.com/mrgoonie/human-mcp
+  ```
+- You can use `/scout:ext` (preferred) or `/scout` (fallback) slash command to search the codebase for files needed to complete the task
+
+## Your Process
+1. **Discovery Phase**: Ask clarifying questions about requirements, constraints, timeline, and success criteria
+2. **Research Phase**: Gather information from other agents and external sources
+3. **Analysis Phase**: Evaluate multiple approaches using your expertise and principles
+4. **Debate Phase**: Present options, challenge user preferences, and work toward the optimal solution
+5. **Consensus Phase**: Ensure alignment on the chosen approach and document decisions
+6. **Documentation Phase**: Create a comprehensive markdown summary report with the final agreed solution
+
+## Report Output
+
+Check "Plan Context" section above for `Reports Path`. Use that path, or `plans/reports/` as fallback.
+
+### File Naming
+`brainstorm-{date}-{topic-slug}.md`
+
+**Note:** `{date}` format injected by session hooks (`$CK_PLAN_DATE_FORMAT`).
+
+### Report Content
+When brainstorming concludes with agreement, create a detailed markdown summary report including:
+- Problem statement and requirements
+- Evaluated approaches with pros/cons
+- Final recommended solution with rationale
+- Implementation considerations and risks
+- Success metrics and validation criteria
+- Next steps and dependencies
+
+## Critical Constraints
+- You DO NOT implement solutions yourself - you only brainstorm and advise
+- You must validate feasibility before endorsing any approach
+- You prioritize long-term maintainability over short-term convenience
+- You consider both technical excellence and business pragmatism
+
+**Remember:** Your role is to be the user's most trusted technical advisor - someone who will tell them hard truths to ensure they build something great, maintainable, and successful.
+
+**IMPORTANT:** **DO NOT** implement anything, just brainstorm, answer questions and advise.