aiwcli 0.9.1 → 0.9.2

package/dist/templates/cc-native/.claude/agents/cc-native/CONTEXT-EXTRACTOR.md

@@ -3,7 +3,7 @@ name: context-extractor
 description: Extracts abstracted problem context from conversation for fresh perspective analysis. Strips implementation details, preserves problem essence.
 model: haiku
 focus: context abstraction
-enabled: true
+enabled: false
 categories:
   - code
   - infrastructure

package/dist/templates/cc-native/.claude/agents/cc-native/DEVILS-ADVOCATE.md

@@ -3,7 +3,7 @@ name: devils-advocate
 description: Takes the contrarian position and pushes logic to uncomfortable extremes. If a plan can't survive its antithesis, it's not robust. This agent asks "what if the exact opposite is true?"
 model: sonnet
 focus: contrarian analysis and reductio ad absurdum
-enabled: true
+enabled: false
 categories:
   - code
   - infrastructure

package/dist/templates/cc-native/.claude/agents/cc-native/FEASIBILITY-ANALYST.md

@@ -3,7 +3,7 @@ name: feasibility-analyst
 description: Evaluates whether plans are achievable given available resources, time, expertise, and technical constraints. Identifies gaps between what's planned and what's realistically possible.
 model: sonnet
 focus: resource constraints and technical viability
-enabled: true
+enabled: false
 categories:
   - code
   - infrastructure

package/dist/templates/cc-native/.claude/agents/cc-native/FRESH-PERSPECTIVE.md

@@ -3,7 +3,7 @@ name: fresh-perspective
 description: Provides unbiased problem-solving perspective without code context. Analyzes from first principles to combat code-anchored thinking.
 model: sonnet
 focus: first-principles problem analysis
-enabled: true
+enabled: false
 categories:
   - code
   - infrastructure

package/dist/templates/cc-native/.claude/agents/cc-native/HANDOFF-READINESS.md

@@ -3,7 +3,7 @@ name: handoff-readiness
 description: Tests whether plans contain sufficient context for execution by a fresh context window with zero prior knowledge. Simulates receiving the plan cold and identifies every point where clarification would be needed—because that question can never be answered. Detects undefined references, missing big-picture goals, implicit assumptions, and context-dependent gaps.
 model: sonnet
 focus: fresh context execution readiness
-enabled: true
+enabled: false
 categories:
   - code
   - infrastructure

package/dist/templates/cc-native/.claude/agents/cc-native/HIDDEN-COMPLEXITY-DETECTOR.md

@@ -3,7 +3,7 @@ name: hidden-complexity-detector
 description: Surfaces understated difficulty and implementation nightmares hiding behind simple-sounding requirements. Simple plans hide complex reality. This agent asks "what makes this harder than it sounds?"
 model: sonnet
 focus: understated complexity and hidden difficulty
-enabled: true
+enabled: false
 categories:
   - code
   - infrastructure

package/dist/templates/cc-native/.claude/agents/cc-native/INCENTIVE-MAPPER.md

@@ -3,7 +3,7 @@ name: incentive-mapper
 description: Examines who wins, who loses, and whether incentives align with desired outcomes. Plans fail when people's motivations don't match goals. This agent asks "who benefits from this being true?"
 model: sonnet
 focus: incentive alignment and motivation structures
-enabled: true
+enabled: false
 categories:
   - code
   - infrastructure

package/dist/templates/cc-native/.claude/agents/cc-native/PENETRATION-TESTER.md

@@ -3,7 +3,7 @@ name: penetration-tester
 description: Expert penetration tester specializing in ethical hacking, vulnerability assessment, and security testing. Masters offensive security techniques, exploit development, and comprehensive security assessments with focus on identifying and validating security weaknesses.
 model: sonnet
 focus: security vulnerabilities and attack vectors
-enabled: true
+enabled: false
 categories:
   - code
   - infrastructure

package/dist/templates/cc-native/.claude/agents/cc-native/PERFORMANCE-ENGINEER.md

@@ -3,7 +3,7 @@ name: performance-engineer
 description: Expert performance engineer specializing in system optimization, bottleneck identification, and scalability engineering. Masters performance testing, profiling, and tuning across applications, databases, and infrastructure with focus on achieving optimal response times and resource efficiency.
 model: sonnet
 focus: performance bottlenecks and optimization
-enabled: true
+enabled: false
 categories:
   - code
   - infrastructure

package/dist/templates/cc-native/.claude/agents/cc-native/PLAN-ORCHESTRATOR.md

@@ -3,7 +3,7 @@ name: plan-orchestrator
 description: Intelligent plan analyzer that determines complexity and routes to appropriate reviewers. Uses fast inference to minimize latency while maximizing review accuracy through targeted agent selection.
 model: haiku
 focus: plan complexity analysis and agent routing
-enabled: true
+enabled: false
 categories:
   - orchestration
 tools: Read, Glob, Grep

package/dist/templates/cc-native/.claude/agents/cc-native/PRECEDENT-FINDER.md

@@ -3,7 +3,7 @@ name: precedent-finder
 description: Pattern-matches to historical precedents and their results. History predicts plan outcomes. This agent asks "when has this been tried before, and what happened?"
 model: sonnet
 focus: historical patterns and precedent analysis
-enabled: true
+enabled: false
 categories:
   - code
   - infrastructure

package/dist/templates/cc-native/.claude/agents/cc-native/REVERSIBILITY-ANALYST.md

@@ -3,7 +3,7 @@ name: reversibility-analyst
 description: Identifies one-way doors, lock-in, and path dependencies that foreclose future options. Some decisions close doors permanently. This agent asks "can you undo this if you're wrong?"
 model: sonnet
 focus: one-way doors and irreversible decisions
-enabled: true
+enabled: false
 categories:
   - code
   - infrastructure

package/dist/templates/cc-native/.claude/agents/cc-native/RISK-ASSESSOR.md

@@ -3,7 +3,7 @@ name: risk-assessor
 description: Identifies potential failure modes, external dependencies, reversibility concerns, and mitigation strategies. Focuses on what could go wrong and how to prepare for it.
 model: sonnet
 focus: failure modes and mitigation strategies
-enabled: true
+enabled: false
 categories:
   - code
   - infrastructure

package/dist/templates/cc-native/.claude/agents/cc-native/SECOND-ORDER-ANALYST.md

@@ -3,7 +3,7 @@ name: second-order-analyst
 description: Traces consequences 2-3 steps beyond immediate effects. Plans that look safe in isolation often trigger cascading failures. This agent maps the domino chain and asks "what breaks downstream?"
 model: sonnet
 focus: cascading effects and downstream consequences
-enabled: true
+enabled: false
 categories:
   - code
   - infrastructure

package/dist/templates/cc-native/.claude/agents/cc-native/SIMPLICITY-GUARDIAN.md

@@ -3,7 +3,7 @@ name: simplicity-guardian
 description: Detects over-engineering, unnecessary complexity, scope creep, premature abstraction, and YAGNI violations. Advocates for the simplest solution that meets requirements.
 model: sonnet
 focus: complexity reduction and scope control
-enabled: true
+enabled: false
 categories:
   - code
   - infrastructure

package/dist/templates/cc-native/.claude/agents/cc-native/SKEPTIC.md

@@ -3,7 +3,7 @@ name: skeptic
 description: Adversarial reviewer specializing in problem-solution alignment and assumption validation. Questions whether the plan solves the right problem, challenges hidden assumptions, and identifies over-engineering. Uses Socratic questioning to surface fundamental flaws.
 model: sonnet
 focus: problem-solution alignment and assumption validation
-enabled: true
+enabled: false
 categories:
   - code
   - infrastructure

package/dist/templates/cc-native/.claude/agents/cc-native/STAKEHOLDER-ADVOCATE.md

@@ -3,7 +3,7 @@ name: stakeholder-advocate
 description: Ensures plans actually serve user and business needs, not just technical elegance. Evaluates who benefits, who bears costs, and whether the plan aligns with stakeholder priorities.
 model: sonnet
 focus: user value and business alignment
-enabled: true
+enabled: false
 categories:
   - code
   - design

package/dist/templates/cc-native/.claude/agents/cc-native/TRADE-OFF-ILLUMINATOR.md

@@ -3,7 +3,7 @@ name: trade-off-illuminator
 description: Forces explicit acknowledgment of what's being sacrificed. Every decision has a price. Plans hide their costs. This agent drags hidden trade-offs into the light and asks "what are you giving up?"
 model: sonnet
 focus: hidden costs and sacrificed alternatives
-enabled: true
+enabled: false
 categories:
   - code
   - infrastructure

package/dist/templates/cc-native/.claude/settings.json

@@ -18,6 +18,17 @@
     }
   },
   "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python .aiwcli/_shared/hooks/session_start.py",
+            "timeout": 5000
+          }
+        ]
+      }
+    ],
     "UserPromptSubmit": [
       {
         "hooks": [
@@ -94,6 +105,16 @@
       }
     ],
     "PreToolUse": [
+      {
+        "matcher": "TaskCreate",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python .aiwcli/_shared/hooks/task_create_atomicity.py",
+            "timeout": 15000
+          }
+        ]
+      },
       {
         "matcher": "Write",
         "hooks": [

package/dist/templates/cc-native/_cc-native/hooks/CLAUDE.md

@@ -0,0 +1,211 @@
+# CC-Native Hooks Development Guide
+
+> **Keep this document updated.** When you solve an issue related to hooks, add the solution to the relevant section and log it in the Changelog. This document should grow with discovered patterns and fixes—don't wait to be asked.
+
+---
+
+## Quick Reference
+
+| Hook | Trigger | Purpose |
+|------|---------|---------|
+| `cc-native-plan-review.py` | PreToolUse: ExitPlanMode | Review plans before user approval |
+| `add_plan_context.py` | PostToolUse: EnterPlanMode | Add context when entering plan mode |
+| `suggest-fresh-perspective.py` | PostToolUse | Suggest fresh perspective workflow |
+
+---
+
+## Import Pattern
+
+Hooks run from arbitrary working directories. Always set up sys.path explicitly.
+
+```python
+# CORRECT - works in hook context
+from pathlib import Path
+import sys
+
+_lib = Path(__file__).parent.parent / "lib"
+sys.path.insert(0, str(_lib))
+
+# For shared library access
+_shared = Path(__file__).parent.parent.parent / "_shared"
+sys.path.insert(0, str(_shared))
+
+from utils import eprint, ReviewerResult
+from lib.base.subprocess_utils import is_internal_call
+```
+
+```python
+# WRONG - relative imports fail in hook context
+from ..lib import utils  # ModuleNotFoundError
+```
+
+---
+
+## Internal Call Detection
+
+Hooks can be invoked recursively when spawning subprocesses (agents, orchestrator). Always check and skip:
+
+```python
+def main() -> int:
+    # FIRST LINE of main - before any other logic
+    if is_internal_call():
+        return 0  # Skip for subprocess calls
+
+    # Rest of hook logic...
+```
+
+Without this check, the hook runs multiple times per plan review, causing duplicate reviews and state corruption.
+
+---
+
+## Hook Output Format
+
+Claude Code hooks return JSON to stdout. The format is specific to each hook type.
+
+### PreToolUse Output
+
+```python
+# CORRECT - current API format
+import json
+
+out = {
+    "hookSpecificOutput": {
+        "hookEventName": "PreToolUse",
+        "additionalContext": "Information for Claude to see...",
+    }
+}
+
+# To block the tool call:
+out["hookSpecificOutput"]["permissionDecision"] = "deny"
+out["hookSpecificOutput"]["permissionDecisionReason"] = "Reason shown to Claude"
+
+print(json.dumps(out, ensure_ascii=False))
+```
+
+```python
+# WRONG - old format, silently ignored
+{"decision": "block", "reason": "..."}  # Does nothing
+{"continue": False, "message": "..."}   # Does nothing
+```
+
+**Key insight:** The old `decision`/`reason` format fails silently. If your hook isn't affecting Claude's behavior, check the output format first.
+
+---
+
+## Debugging Output
+
+Hooks communicate via stdout (JSON) and stderr (logs). Use them correctly:
+
+```python
+# CORRECT - logs go to stderr, visible in terminal
+def eprint(*args):
+    print(*args, file=sys.stderr)
+
+eprint("[hook-name] Starting hook...")
+eprint(f"[hook-name] Found {len(items)} items")
+```
+
+```python
+# WRONG - print() goes to stdout, corrupts JSON output
+print("Debug info")  # Breaks JSON parsing
+print(json.dumps(output))  # Now invalid because of previous print
+```
+
+---
+
+## Context System Integration
+
+Plan review hooks integrate with the shared context system for state management:
+
+```python
+from lib.context.context_manager import (
+    get_context_by_session_id,
+    get_all_in_flight_contexts,
+)
+from lib.base.constants import get_context_reviews_dir
+
+# Find active context
+context = get_context_by_session_id(session_id, project_root)
+if not context:
+    # Fallback: find single planning context
+    in_flight = get_all_in_flight_contexts(project_root)
+    planning = [c for c in in_flight if c.in_flight and c.in_flight.mode == "planning"]
+    if len(planning) == 1:
+        context = planning[0]
+
+# Get reviews directory for this context
+reviews_dir = get_context_reviews_dir(context.id, project_root)
+```
+
+If context isn't found, add diagnostic logging:
+
+```python
+eprint(f"[hook] Session ID: {session_id}")
+eprint(f"[hook] In-flight contexts: {len(in_flight)}")
+eprint(f"[hook] Modes: {[c.in_flight.mode for c in in_flight]}")
+```
+
+---
+
+## Error Handling
+
+Hooks should fail gracefully - a broken hook shouldn't break the user's workflow:
+
+```python
+def main() -> int:
+    try:
+        # Hook logic...
+        return 0
+    except Exception as e:
+        eprint(f"[hook-name] Error: {e}")
+        # Return 0 to not block the user
+        return 0
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main())
+    except Exception as e:
+        import traceback
+        eprint(f"[hook-name] FATAL: {e}")
+        traceback.print_exc(file=sys.stderr)
+        # Still exit 0 to not block - or exit 1 if blocking is intentional
+        raise SystemExit(0)
+```
+
+Use `sys.exit(1)` only for intentional blocking (e.g., `blockOnFail: true` configured).
+
+---
+
+## DO NOT
+
+These are reminders based on past issues. Not enforcement rules.
+
+- **Don't modify hook output format** without verifying the current Claude Code hook API (it changes between versions)
+- **Don't use `sys.exit(1)`** for non-fatal errors - it blocks the user's workflow
+- **Don't forget template sync** after modifying hooks in `.aiwcli/` - changes should also go to `packages/cli/src/templates/cc-native/`
+- **Don't use `print()`** for anything except the final JSON output
+- **Don't assume session_id format** - it can be UUID, path-like, or other formats
+- **Don't skip `is_internal_call()` check** - recursive hook execution causes state corruption
+- **Don't hardcode paths** - use `Path(__file__)` and environment variables
+
+---
+
+## Verification After Changes
+
+Always validate Python syntax after editing hooks:
+
+```bash
+python -m py_compile packages/cli/src/templates/cc-native/_cc-native/hooks/cc-native-plan-review.py
+```
+
+Hooks fail silently on syntax errors - this catches them before they reach production.
+
+---
+
+## Changelog
+
+<!-- Add dated entries as new issues are discovered -->
+
+| Date | Change |
+|------|--------|
+| 2026-02-03 | Initial creation |

package/dist/templates/cc-native/_cc-native/hooks/cc-native-plan-review.py

@@ -29,6 +29,7 @@ Output: _output/cc-native/plans/{YYYY-MM-DD}/{slug}/reviews/
 
 import json
 import os
+import random
 import sys
 from concurrent.futures import ThreadPoolExecutor, as_completed
 from datetime import datetime
@@ -522,7 +523,9 @@ def main() -> int:
     gemini_enabled = plan_review_enabled and reviewers_config.get("gemini", {}).get("enabled", False)
 
     agent_library = load_agent_library(base, agent_settings) if agent_review_enabled else []
-    enabled_agents = [a for a in agent_library if a.enabled]
+    # Load all agents regardless of enabled status - enabled:false only prevents
+    # Claude Code auto-suggestion, not plan-review usage
+    enabled_agents = agent_library
     timeout = agent_settings.get("timeout", 120)
     legacy_mode = agent_settings.get("legacyMode", False)
 
@@ -585,19 +588,42 @@ def main() -> int:
 
         selected_agents: List[AgentConfig] = []
 
+        # Load mandatory and fallback config
+        mandatory_names = set(agent_settings.get("mandatoryAgents", [
+            "handoff-readiness", "clarity-auditor", "skeptic"
+        ]))
+        fallback_by_complexity = agent_settings.get("fallbackByComplexity", {
+            "simple": 0, "medium": 5, "high": 9
+        })
+
         if enabled_agents:
+            # Split into mandatory and non-mandatory pools
+            mandatory_agents = [a for a in enabled_agents if a.name in mandatory_names]
+            non_mandatory = [a for a in enabled_agents if a.name not in mandatory_names]
+
+            eprint(f"[cc-native-plan-review] Mandatory agents: {[a.name for a in mandatory_agents]}")
+            eprint(f"[cc-native-plan-review] Non-mandatory pool: {len(non_mandatory)} agents")
+
             if orch_result and not legacy_mode:
-                # Use orchestrator result from phase 1
                 detected_complexity = orch_result.complexity
 
-                selected_names = set(orch_result.selected_agents)
-                selected_agents = [a for a in enabled_agents if a.name in selected_names]
+                # Get orchestrator's additional selections (excluding mandatory since they always run)
+                orch_selected_names = set(orch_result.selected_agents) - mandatory_names
+                orch_selected = [a for a in non_mandatory if a.name in orch_selected_names]
 
-                    if not selected_agents and selected_names:
-                        eprint(f"[cc-native-plan-review] Warning: orchestrator selected unknown agents: {selected_names}")
-                        selected_agents = [a for a in enabled_agents if orch_result.category in a.categories]
+                eprint(f"[cc-native-plan-review] Orchestrator selected (non-mandatory): {[a.name for a in orch_selected]}")
 
-                    eprint(f"[cc-native-plan-review] Orchestrator selected: {[a.name for a in selected_agents]}")
+                # Random fallback if orchestrator selected zero additional agents
+                if not orch_selected and non_mandatory:
+                    fallback_count = fallback_by_complexity.get(detected_complexity, 5)
+                    fallback_count = min(fallback_count, len(non_mandatory))
+                    if fallback_count > 0:
+                        orch_selected = random.sample(non_mandatory, fallback_count)
+                        eprint(f"[cc-native-plan-review] Random fallback ({detected_complexity}): {[a.name for a in orch_selected]}")
+
+                # Combine: mandatory + orchestrator/fallback selection
+                selected_agents = mandatory_agents + orch_selected
+                eprint(f"[cc-native-plan-review] Final selection: {len(selected_agents)} agents ({len(mandatory_agents)} mandatory + {len(orch_selected)} additional)")
             else:
                 eprint("[cc-native-plan-review] Running in legacy mode (all enabled agents)")
                 selected_agents = enabled_agents
@@ -764,4 +790,17 @@ def main() -> int:
 
 
 if __name__ == "__main__":
-    raise SystemExit(main())
+    try:
+        raise SystemExit(main())
+    except Exception as e:
+        import traceback
+        print(f"[cc-native-plan-review] FATAL ERROR: {e}", file=sys.stderr)
+        traceback.print_exc(file=sys.stderr)
+        # Output error to Claude via hook format so it's visible
+        print(json.dumps({
+            "hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "additionalContext": f"**CC-Native Plan Review Hook Error**\n\nThe hook encountered an error:\n```\n{traceback.format_exc()}\n```\n\nPlease report this issue.",
+            }
+        }))
+        raise SystemExit(1)