@yeongjaeyou/claude-code-config 0.14.0 → 0.16.0

package/.claude/commands/council.md

@@ -23,11 +23,53 @@ Inspired by Andrej Karpathy's LLM Council: query multiple AI models with the sam
 3. **Quick mode**: `/council --quick What's the best approach?`
 
 **Flags:**
-- `--quick`: Quick mode - reduced reasoning depth, faster convergence
+- `--quick`: Quick mode (see below)
 
 **Default behavior (no flags):**
-- Maximum reasoning depth (Codex: xhigh + gpt-5.1-codex-max)
+- Maximum reasoning depth (Codex: reasoningEffort=xhigh, model=gpt-5.1-codex-max)
 - Full multi-round deliberation (up to 3 rounds)
+- YAML schema enforced
+
+**Quick mode (`--quick`):**
+- All 4 models queried (Opus, Sonnet, Codex, Gemini)
+- Single round only (Round 1 -> direct Synthesis, no Round 1.5 analysis)
+- YAML schema not enforced (free-form responses accepted)
+- Codex: reasoningEffort=high (instead of xhigh)
+
+---
+
+## Pre-flight Check
+
+Before querying models, verify environment parity:
+
+**1. CLI Installation:**
+```bash
+command -v claude && echo "Claude Code: OK" || echo "Claude Code: Missing"
+command -v codex && echo "Codex CLI: OK" || echo "Codex CLI: Missing"
+command -v gemini && echo "Gemini CLI: OK" || echo "Gemini CLI: Missing"
+```
+
+**2. Guidelines Files:**
+```bash
+[ -f ./CLAUDE.md ] && echo "CLAUDE.md: OK" || echo "CLAUDE.md: Missing"
+[ -f ./AGENTS.md ] && echo "AGENTS.md: OK" || echo "AGENTS.md: Missing"
+[ -f ./GEMINI.md ] && echo "GEMINI.md: OK" || echo "GEMINI.md: Missing"
+```
+
+**3. MCP Configuration:**
+| CLI | Config Location | Check Command |
+|-----|-----------------|---------------|
+| Claude Code | `.mcp.json`, `~/.claude.json` | `claude mcp list` |
+| Codex CLI | `~/.codex/config.toml` | `codex mcp --help` |
+| Gemini CLI | `~/.gemini/settings.json`, `.gemini/settings.json` | `gemini mcp list` |
+
+**Warning conditions (proceed with caution):**
+- Guidelines file missing: model runs without project context
+- MCP not configured: model has limited tool access
+- CLI not installed: model excluded from council
+
+**If warnings detected:**
+Use AskUserQuestion to confirm whether to proceed or fix issues first.
 
 ---
 
@@ -41,15 +83,14 @@ council_member:
   response:
     summary: "1-2 sentence core answer"
     detailed_answer: "full response content"
-    confidence: 0.0-1.0
     key_points:
       - point: "key insight"
         evidence: "file:line or reasoning"
-    code_references:
+    code_references:  # optional
       - file: "/absolute/path/to/file.py"
         lines: "42-58"
         context: "why this is relevant"
-    caveats:
+    caveats:  # optional
       - "potential limitation or edge case"
   # Round 2+ additional fields
   gaps:
@@ -72,7 +113,6 @@ Before querying models, collect relevant context:
 ```
 - git status / git diff (current changes)
 - Directory structure (tree -L 2)
-- Files mentioned in conversation (Read/Edit history)
 
 Model-specific guidelines (project root):
 - ./CLAUDE.md (Claude Opus/Sonnet)
@@ -80,6 +120,38 @@ Model-specific guidelines (project root):
 - ./gemini.md (Gemini)
 ```
 
+**Conditional Code Exploration:**
+
+When relevant files are unclear from the question, spawn Explore agents to discover them:
+
+```
+Trigger conditions:
+- Question mentions code/architecture/structure without specific files
+- Question asks about "this", "the code", "current implementation" ambiguously
+- UI/UX questions that need component/style file identification
+
+Skip exploration when:
+- User provides specific file paths or permalinks
+- Question is conceptual (no code context needed)
+- Files are obvious from recent git diff
+```
+
+```
+Task(subagent_type="Explore", run_in_background: true):
+  prompt: |
+    Find files related to: [USER_QUESTION]
+
+    Return results in this format:
+    - /absolute/path/file.ext:LINE-LINE (brief context)
+
+    Focus on:
+    - Direct implementation files
+    - Related tests
+    - Configuration if relevant
+```
+
+After exploration, use discovered paths in the File Path Inclusion format below.
+
 **File Path Inclusion (MANDATORY format):**
 ```
 Relevant files for this question:
@@ -95,7 +167,7 @@ Use your file access tools to READ these files directly.
 |-------|-------------------|
 | Claude Opus/Sonnet | Read tool (images supported) |
 | Codex | sandbox read-only file access |
-| Gemini | Include file content in prompt, or instruct to read |
+| Gemini | MCP tools or Bash file read (MCP supported since 2025) |
 
 **Sensitive Data Filtering (exclude from prompts):**
 ```
@@ -114,6 +186,41 @@ Directories: node_modules/, __pycache__/, .git/
 
 ---
 
+## Progress Tracking
+
+Use TodoWrite to show progress at each stage:
+
+**Round 1 start:**
+```yaml
+todos:
+  - content: "[Council] Query Opus"
+    status: "in_progress"
+    activeForm: "Querying Opus"
+  - content: "[Council] Query Sonnet"
+    status: "in_progress"
+    activeForm: "Querying Sonnet"
+  - content: "[Council] Query Codex"
+    status: "in_progress"
+    activeForm: "Querying Codex"
+  - content: "[Council] Query Gemini"
+    status: "in_progress"
+    activeForm: "Querying Gemini"
+  - content: "[Council] Analyze responses"
+    status: "pending"
+    activeForm: "Analyzing responses"
+  - content: "[Council] Synthesize"
+    status: "pending"
+    activeForm: "Synthesizing"
+```
+
+**Update rules:**
+- Model response received -> mark that model's todo as "completed"
+- All models done -> "[Council] Analyze responses" to "in_progress"
+- Round 2 needed -> add re-query todos for specific models
+- Analysis done -> "[Council] Synthesize" to "in_progress"
+
+---
+
 ## Execution
 
 ### Round 1: Collect Initial Responses
@@ -160,7 +267,7 @@ Task(subagent_type="general-purpose", run_in_background: true):
     You are participating in an LLM Council deliberation as Codex.
 
     ## Tool Usage
-    Use mcp__codex__codex tool with:
+    Use mcp__codex-cli__codex tool with:
     - sandbox: "read-only"
     - workingDirectory: "{PROJECT_ROOT}"
     - reasoningEffort: "xhigh"  (or "high" with --quick)
@@ -196,6 +303,8 @@ Task(subagent_type="general-purpose", run_in_background: true):
     [GEMINI_PROMPT_WITH_CONTEXT]
     EOF
     ```
+    Note: Gemini CLI supports MCP (since 2025). If MCP is configured,
+    Gemini can access project files directly via MCP tools.
 
     ## Guidelines
     Read and follow ./gemini.md project guidelines.
@@ -204,8 +313,8 @@ Task(subagent_type="general-purpose", run_in_background: true):
     ## Question
     [USER_QUESTION]
 
-    ## Context Files (include content since Gemini has limited file access)
-    [FILE_CONTENTS_WITH_LINE_NUMBERS]
+    ## Context Files (READ directly using exact paths)
+    [FILE_LIST_WITH_LINE_NUMBERS]
 
     ## Instructions
     Parse Gemini's response and return structured YAML following the schema.
@@ -232,15 +341,15 @@ Skipping Round 1.5 defeats the purpose of multi-round deliberation.
 
 **1. Anonymize Responses:**
 ```
-1. Shuffle response order randomly
-2. Assign labels: Response A, B, C, D
-3. Create internal mapping:
+1. Assign labels in response arrival order: Response A, B, C, D
+2. Create internal mapping:
    label_to_model = {
-     "Response A": "gemini",
-     "Response B": "opus",
-     "Response C": "sonnet",
-     "Response D": "codex"
+     "Response A": "[first arrived]",
+     "Response B": "[second arrived]",
+     "Response C": "[third arrived]",
+     "Response D": "[fourth arrived]"
    }
+3. Present responses by label only (hide model names until synthesis)
 ```
 
 **2. Gap Analysis:**
@@ -271,16 +380,17 @@ conflicts_detected:
 **4. Convergence Check (REQUIRED before synthesis):**
 ```yaml
 convergence_status:
-  confidence_average: 0.815
-  new_information_ratio: 0.15
+  agreement_count: 3  # models with same core conclusion
   gaps_remaining: 2
   conflicts_remaining: 1
   decision: "proceed_to_round_2" | "terminate_and_synthesize"
 ```
 
 **Decision logic:**
-- If `gaps_remaining > 0` AND `confidence_average < 0.9` → `proceed_to_round_2`
+- If `agreement_count >= 3` → `terminate_and_synthesize` (strong consensus)
+- If `gaps_remaining == 0` AND `conflicts_remaining == 0` → `terminate_and_synthesize`
 - If `conflicts_remaining > 0` AND round < 3 → `proceed_to_round_2`
+- If `gaps_remaining > 0` AND round < 3 → `proceed_to_round_2`
 - Otherwise → `terminate_and_synthesize`
 
 ### Round 2: Targeted Re-queries (Conditional)
@@ -292,11 +402,11 @@ If convergence criteria not met, re-query only models with gaps/conflicts:
 ## Previous Round Summary
 Round 1 produced the following positions:
 
-### Response A (Confidence: 0.92)
+### Response A
 - Position: [summary]
 - Key points: [list]
 
-### Response B (Confidence: 0.85)
+### Response B
 - Position: [summary]
 - Key points: [list]
 
@@ -317,7 +427,6 @@ Please address specifically:
 2. [specific gap or conflict to resolve]
 
 Provide evidence and reasoning for your position.
-Update your confidence score based on new information.
 
 ## Output (YAML format required)
 [COUNCIL_MEMBER_SCHEMA with gaps/conflicts fields]
@@ -362,10 +471,9 @@ After convergence or max rounds:
 ### Soft Limits (Convergence - any triggers termination)
 | Condition | Threshold |
 |-----------|-----------|
-| Average confidence | > 0.9 |
-| New information ratio | < 10% |
+| Strong consensus | 3+ models agree on core conclusion |
 | All gaps resolved | 0 remaining |
-| Strong consensus | 3+ models agree |
+| All conflicts resolved | 0 remaining |
 | Conflicts irreconcilable | Cannot be resolved with more queries |
 
 ---
@@ -387,29 +495,29 @@ After convergence or max rounds:
 
 ### Individual Responses (Anonymized)
 
-#### Response A (Confidence: 0.92)
+#### Response A
 [Content]
 
 **Key Points:**
 - [point 1] (evidence: file:line)
 - [point 2] (evidence: file:line)
 
-#### Response B (Confidence: 0.85)
+#### Response B
 [Content]
 
-#### Response C (Confidence: 0.78)
+#### Response C
 [Content]
 
-#### Response D (Confidence: 0.71)
+#### Response D
 [Content]
 
 ### Model Reveal
-| Label | Model | Final Confidence |
-|-------|-------|-----------------|
-| Response A | codex | 0.92 |
-| Response B | opus | 0.85 |
-| Response C | sonnet | 0.78 |
-| Response D | gemini | 0.71 |
+| Label | Model |
+|-------|-------|
+| Response A | codex |
+| Response B | opus |
+| Response C | sonnet |
+| Response D | gemini |
 
 ### Coordinator Analysis
 

package/.claude/skills/notion-md-uploader/SKILL.md

@@ -25,16 +25,22 @@ Before using this skill, ensure the following setup is complete:
 
 ### 2. Environment Configuration
 
-Set the API key in the environment:
+Set the API key in the environment. The script automatically loads `.env` files if `python-dotenv` is installed:
 
 ```bash
-# In .env file
+# In .env file (recommended - auto-loaded)
 NOTION_API_KEY=ntn_xxxxx
 
 # Or export directly
 export NOTION_API_KEY=ntn_xxxxx
 ```
 
+To install dotenv support:
+
+```bash
+uv add python-dotenv
+```
+
 ### 3. Page Access
 
 Share the target parent page with the integration:
@@ -65,6 +71,8 @@ uv run python .claude/skills/notion-md-uploader/scripts/upload_md.py \
 
 ### Dry Run (Preview)
 
+Preview parsing results and validate local images before uploading:
+
 ```bash
 uv run python .claude/skills/notion-md-uploader/scripts/upload_md.py \
     docs/analysis.md \
@@ -72,6 +80,11 @@ uv run python .claude/skills/notion-md-uploader/scripts/upload_md.py \
     --dry-run
 ```
 
+The dry run validates:
+- Markdown block parsing
+- Local image file existence
+- Conversion to Notion blocks
+
 ## Supported Markdown Elements
 
 | Element | Markdown Syntax | Notion Block |

package/.claude/skills/notion-md-uploader/scripts/upload_md.py

@@ -18,10 +18,17 @@ import sys
 from pathlib import Path
 from typing import Any
 
+# Load .env file if python-dotenv is available
+try:
+    from dotenv import load_dotenv
+    load_dotenv()
+except ImportError:
+    pass  # python-dotenv not installed, use env vars directly
+
 # Add scripts directory to path for imports
 sys.path.insert(0, str(Path(__file__).parent))
 
-from markdown_parser import MarkdownParser
+from markdown_parser import BlockType, MarkdownParser
 from notion_client import NotionClient, NotionAPIError, NotionConfig
 from notion_converter import NotionBlockConverter
 
@@ -236,8 +243,8 @@ Setup:
         print(f"Parsing: {args.md_file}")
         content = md_path.read_text(encoding="utf-8")
 
-        parser = MarkdownParser(base_path=str(md_path.parent))
-        blocks = parser.parse(content)
+        md_parser = MarkdownParser(base_path=str(md_path.parent))
+        blocks = md_parser.parse(content)
 
         print(f"Found {len(blocks)} blocks:")
         for i, block in enumerate(blocks[:10]):
@@ -251,6 +258,34 @@ Setup:
         if len(blocks) > 10:
             print(f"  ... and {len(blocks) - 10} more blocks")
 
+        # Validate image files
+        base_path = md_path.parent
+        image_blocks = [b for b in blocks if b.block_type == BlockType.IMAGE]
+        missing_images = []
+        found_images = []
+
+        for block in image_blocks:
+            img_src = block.metadata.get("url", "")
+            if img_src and not img_src.startswith(("http://", "https://")):
+                img_path = base_path / img_src
+                if img_path.exists():
+                    found_images.append(str(img_src))
+                else:
+                    missing_images.append(str(img_src))
+
+        if found_images:
+            print(f"\nLocal images ({len(found_images)}):")
+            for img in found_images[:5]:
+                print(f"  [OK] {img}")
+            if len(found_images) > 5:
+                print(f"  ... and {len(found_images) - 5} more")
+
+        if missing_images:
+            print(f"\nMissing images ({len(missing_images)}):")
+            for img in missing_images:
+                print(f"  [MISSING] {img}")
+            print("\nWarning: Missing images will cause upload to fail.")
+
         converter = NotionBlockConverter(base_path=str(md_path.parent))
         notion_blocks = converter.convert_blocks(blocks)
         print(f"\nConverted to {len(notion_blocks)} Notion blocks")
@@ -272,10 +307,13 @@ Setup:
 
         page_url = page.get("url", "")
         page_id = page.get("id", "")
+        image_count = len(uploader._uploaded_images)
 
         print(f"\nSuccess!")
         print(f"Page ID: {page_id}")
         print(f"URL: {page_url}")
+        if image_count > 0:
+            print(f"Images uploaded: {image_count}")
 
     except NotionAPIError as e:
         print(f"\nNotion API Error: {e}")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeongjaeyou/claude-code-config",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Claude Code CLI custom commands, agents, and skills",
   "bin": {
     "claude-code-config": "./bin/cli.js"