aiwcli 0.9.7 → 0.10.0

package/bin/run.js

@@ -11,9 +11,12 @@ import {execute} from '@oclif/core'
 const args = process.argv.slice(2)
 const firstArg = args[0] ?? ''
 const hasCommand = args.length > 0 && !firstArg.startsWith('-')
-const isHelpOrVersion = firstArg === '--help' || firstArg === '-h' || firstArg === '--version'
+const isHelpOrVersion = firstArg === '--help' || firstArg === '-h' || firstArg === '--version' || firstArg === '-v'
+
+// Map -v to --version since oclif doesn't natively understand -v
+const resolvedArgs = firstArg === '-v' ? ['--version', ...args.slice(1)] : args
 
 await execute({
   dir: import.meta.url,
-  args: hasCommand || isHelpOrVersion ? args : ['launch', ...args],
+  args: hasCommand || isHelpOrVersion ? resolvedArgs : ['launch', ...resolvedArgs],
 })

package/dist/lib/claude-settings-types.d.ts

@@ -6,6 +6,8 @@
  * Hook command configuration
  */
 export interface HookCommand {
+    /** If true, runs in background without blocking */
+    async?: boolean;
     /** Command to execute */
     command: string;
     /** Optional timeout in seconds */

package/dist/templates/CLAUDE.md

@@ -17,24 +17,52 @@ Include `_output/{method}/` in template `.gitignore`.
 
 ## Directory Structure
 
+Each template installs into `.aiwcli/` (method files) and `.{ide}/` (IDE integration). The `_shared/` template provides cross-method infrastructure used by all methods.
+
 ```
-packages/cli/src/templates/{method}/
-├── _{method}/              # Method-specific shared files
-│   ├── templates/*.md.template
-│   └── workflows/*.md      # Canonical workflow definitions
-├── .{ide}/{ide-folder}/{method}/*.md  # IDE command stubs
-├── .gitignore              # Output ignore rules
-├── {METHOD}-README.md      # User documentation
-├── TEMPLATE-SCHEMA.md      # Schema reference
-└── MIGRATION.md            # Breaking changes
+packages/cli/src/templates/
+├── _shared/                          # Cross-method infrastructure (installed by all methods)
+│   ├── hooks/                        # Shared hook scripts (context, tasks, sessions)
+│   └── lib/                          # Shared Python libraries
+│       ├── base/                     #   Core: atomic_write, constants, inference, utils
+│       ├── context/                  #   Context CRUD, selection, formatting, plans, tasks
+│       ├── handoff/                  #   Session handoff document generation
+│       └── templates/                #   Output formatters, plan context templates
+│
+├── cc-native/                        # CC-Native method template
+│   ├── _cc-native/                   #   Method-specific hooks, lib, agents, workflows, scripts
+│   ├── .claude/                      #   Claude Code: settings.json, commands/, agents/
+│   ├── .windsurf/                    #   Windsurf: workflows/
+│   └── .gitignore
+│
+├── gsd/                              # GSD method template
+│   ├── .aiwcli/_gsd/                 #   Templates, workflows, hooks, config, docs
+│   ├── .claude/                      #   Claude Code: settings.json, commands/, agents/
+│   ├── .windsurf/                    #   Windsurf: workflows/
+│   ├── GSD-README.md
+│   ├── TEMPLATE-SCHEMA.md
+│   └── MIGRATION.md
+│
+├── bmad/                             # BMAD method template
+│   ├── .aiwcli/_bmad/               #   Agents, workflows, teams, testarch, config
+│   ├── .claude/                      #   Claude Code: settings.json, commands/
+│   └── ...
+│
+├── planning-with-files/              # Planning-with-Files method template
+│   ├── .claude/                      #   Claude Code: settings.json, skills/
+│   ├── .windsurf/                    #   Windsurf: workflows/, scripts/
+│   └── ...
+│
+└── CLAUDE.md                         # This file
 ```
 
 ### Tier Details
 
 | Tier | Location | Purpose |
 |------|----------|---------|
-| General | `_{method}/` | IDE-agnostic templates and canonical workflows |
-| IDE | `.{ide}/{folder}/{method}/` | Lightweight stubs that load canonical workflows |
+| Shared | `_shared/` | Cross-method hooks and libraries (context management, task tracking, sessions) |
+| Method | `_{method}/` or `.aiwcli/_{method}/` | Method-specific templates, workflows, hooks, config |
+| IDE | `.{ide}/` | IDE-specific command stubs, settings, workflow definitions |
 | Config | `.{ide}/settings.json` | Hooks, model prefs, method settings (merged on install) |
 
 ---
@@ -57,7 +85,7 @@ When multiple templates install, settings.json files merge:
 
 ## Hooks
 
-**Location:** `.claude/hooks/{method}-{hook-name}.{ext}`
+**Location:** Hooks live in `.aiwcli/_shared/hooks/` (cross-method) and `.aiwcli/_{method}/hooks/` (method-specific). They are configured in `.{ide}/settings.json`, not placed in IDE directories.
 
 **Configuration:**
 ```json
@@ -65,14 +93,14 @@ When multiple templates install, settings.json files merge:
   "hooks": {
     "PostToolUse": [{
       "matcher": "Write",
-      "hooks": [{ "type": "command", "command": "python .claude/hooks/gsd-plan-review.py", "timeout": 300000 }]
+      "hooks": [{ "type": "command", "command": "python .aiwcli/_cc-native/hooks/cc-native-plan-review.py", "timeout": 300000 }]
     }]
   }
 }
 ```
 
 **Requirements:**
-- Prefix with method name (e.g., `gsd-plan-review.py`)
+- Prefix method-specific hooks with method name (e.g., `cc-native-plan-review.py`)
 - Use relative paths from project root
 - Write outputs to `_output/{method}/`
 - Specify timeouts
@@ -119,8 +147,8 @@ Load and execute `_{method}/workflows/{name}.md`.
 | Reference Type | Pattern |
 |----------------|---------|
 | Templates | `_{method}/templates/FILE.md.template` |
-| Workflows (Claude) | `/gsd:other-workflow` |
-| Workflows (Windsurf) | `other-workflow` from GSD workflows |
+| Workflows (Claude) | `/gsd:workflow-name` (maps to `.claude/commands/gsd/workflow-name.md`) |
+| Workflows (Windsurf) | `workflow-name` from method workflows |
 | Outputs | `_output/{method}/{subdir}/FILE.md` |
 
 ---
@@ -143,8 +171,8 @@ Load and execute `_{method}/workflows/{name}.md`.
 
 **New Template:**
 - [ ] Create `_{method}/` with `templates/` and `workflows/`
-- [ ] Create `.claude/commands/{method}/` stubs
-- [ ] Create `.windsurf/workflows/{method}/` stubs
+- [ ] Create `.claude/commands/{method}/` stubs (Claude Code)
+- [ ] Create `.windsurf/workflows/{method}/` stubs (Windsurf)
 - [ ] Add `.gitignore` with `_output/{method}/`
 - [ ] Create `{METHOD}-README.md`, `TEMPLATE-SCHEMA.md`, `MIGRATION.md`
 - [ ] Configure method-namespaced settings in `.claude/settings.json`
@@ -165,6 +193,7 @@ Load and execute `_{method}/workflows/{name}.md`.
 - Keep canonical workflows in `_{method}/workflows/`
 - Use relative paths from project root
 - Document changes in TEMPLATE-SCHEMA.md
+- Place hooks in `.aiwcli/` directories, wire them in `.{ide}/settings.json`
 
 **Avoid:**
 - Outputs in project root
@@ -172,3 +201,5 @@ Load and execute `_{method}/workflows/{name}.md`.
 - Hooks without method prefix
 - Full workflows in IDE command files
 - Hardcoded paths without method namespace
+- Putting hook scripts directly in IDE directories (`.claude/hooks/`)
+- Creating `_shared/` directories inside method templates (e.g., `cc-native/_shared/`). All shared code lives in `packages/cli/src/templates/_shared/`. Method templates reference shared code via sys.path at runtime, not by copying.

package/dist/templates/_shared/.claude/settings.json

@@ -1,4 +1,8 @@
 {
+  "statusLine": {
+    "type": "command",
+    "command": "python .aiwcli/_shared/scripts/status_line.py"
+  },
   "fileSuggestion": {
     "type": "command",
     "command": "python .aiwcli/_shared/hooks/file-suggestion.py"

package/dist/templates/_shared/hooks/archive_plan.py

@@ -1,21 +1,20 @@
 #!/usr/bin/env python3
-"""Plan archival hook for ExitPlanMode PostToolUse event.
+"""Plan archival hook for ExitPlanMode PermissionRequest event.
 
-This hook runs when ExitPlanMode completes, extracting the plan path from
-the tool result and archiving it to the active context.
+This hook runs when ExitPlanMode is requested (BEFORE user accepts/rejects),
+extracting the plan path from the tool input and archiving it to the
+context's plans/ folder. It does NOT modify state.json plan fields or mode.
 
-Actions:
-1. Detect ExitPlanMode PostToolUse event
-2. Extract plan path from tool result
-3. Check if plan already archived (avoid duplicates)
-4. Determine active context
-5. Archive plan to context's plans folder
-6. Set context in_flight.mode = "pending_implementation"
+Separation of concerns:
+- archive_plan.py (PermissionRequest) -> archives file only, no state.json changes
+- plan_accepted.py (PostToolUse) -> assigns plan fields (hash/signature/path) to state.json
+- session_end.py (SessionEnd) -> transitions active -> has_plan when plan is assigned
+- context_selector.py -> matches plan content, transitions has_plan -> active
 
 Usage in .claude/settings.json:
 {
   "hooks": {
-    "PostToolUse": [{
+    "PermissionRequest": [{
       "matcher": "ExitPlanMode",
       "hooks": [{
         "type": "command",
@@ -26,7 +25,6 @@ Usage in .claude/settings.json:
   }
 }
 """
-import json
 import re
 import sys
 from pathlib import Path
@@ -37,12 +35,11 @@ SCRIPT_DIR = Path(__file__).resolve().parent
 SHARED_LIB = SCRIPT_DIR.parent / "lib"
 sys.path.insert(0, str(SHARED_LIB.parent))
 
-from lib.base.hook_utils import load_hook_input
-from lib.context.plan_archive import archive_plan_to_context
-from lib.context.context_manager import get_all_contexts
-from lib.context.context_extractor import extract_context_id_for_session
-from lib.base.utils import eprint, project_dir
+from lib.base.hook_utils import load_hook_input, log_debug, log_info, log_warn, log_error
+from lib.base.utils import project_dir
 from lib.base.constants import get_context_dir
+from lib.context.context_store import get_context_by_session_id
+from lib.context.plan_manager import archive_plan, extract_plan_path_from_result
 
 # Import debug cleanup function from cc-native lib
 _cc_native_lib = SCRIPT_DIR.parent / "_cc-native" / "lib"
@@ -51,210 +48,122 @@ try:
     from debug import cleanup_debug_folder
 except ImportError:
     def cleanup_debug_folder(context_path):
-        pass  # Fallback if debug module not available
+        pass
 
 
-def extract_plan_path_from_result(tool_result: str) -> Optional[str]:
-    """
-    Extract plan path from ExitPlanMode tool result.
-
-    Looks for pattern: "Your plan has been saved to: <path>"
-    """
-    match = re.search(r'Your plan has been saved to:\s*(.+\.md)', tool_result)
-    if match:
-        return match.group(1).strip()
-    return None
-
-
-def on_plan_archive():
-    """
-    Plan archival hook - archives plan when exiting plan mode.
-
-    Called from PostToolUse on ExitPlanMode - extracts plan path from result
-    and archives to the active context.
-    """
-    # Read hook input using shared utility
-    hook_input = load_hook_input()
-    if not hook_input:
-        eprint("[archive_plan] No valid JSON input")
-        return
-
-    hook_event = hook_input.get("hook_event_name", "unknown")
-    tool_name = hook_input.get("tool_name", "")
-    print(f"[archive_plan] Hook triggered: {hook_event}")
-    print(f"[archive_plan] Tool name: {tool_name}")
-    print(f"[archive_plan] Hook input keys: {list(hook_input.keys())}")
-
-    # Special handling for ExitPlanMode - don't check permission_mode
-    is_exit_plan_mode = (hook_event == "PostToolUse" and tool_name == "ExitPlanMode")
-
-    if is_exit_plan_mode:
-        print("[archive_plan] ExitPlanMode detected, proceeding with archival")
-    else:
-        # Check if we're in plan mode for other hooks
-        permission_mode = hook_input.get("permission_mode", "default")
-        print(f"[archive_plan] Permission mode: {permission_mode}")
-
-        if permission_mode != "plan":
-            print("[archive_plan] Not in plan mode, skipping archival")
-            return
-
-    # Prevent infinite loops from stop_hook_active
-    if hook_input.get("stop_hook_active", False):
-        print("[archive_plan] Stop hook already active, skipping to prevent loop")
-        return
-
-    print(f"[archive_plan] Proceeding with archival via {hook_event}")
-
-    # Get project root from hook input or environment
-    project_root = project_dir(hook_input)
-
-    # Get plan path from hook input
+def _find_plan_path(hook_input: dict, project_root: Path) -> Optional[str]:
+    """Find the plan file path from hook input or standard locations."""
     tool_input = hook_input.get("tool_input", {})
     tool_result = hook_input.get("tool_result", "")
+    hook_event = hook_input.get("hook_event_name", "")
+    tool_name = hook_input.get("tool_name", "")
 
-    # Try to find plan path in various locations
     plan_path = None
 
-    # For ExitPlanMode, extract plan path from tool result first
-    if is_exit_plan_mode and tool_result:
+    # For ExitPlanMode, extract from tool result
+    if tool_name == "ExitPlanMode" and tool_result:
         plan_path = extract_plan_path_from_result(tool_result)
         if plan_path:
-            print(f"[archive_plan] Extracted plan path from ExitPlanMode result: {plan_path}")
-
-    # Check if plan path is directly provided in tool_input
-    if not plan_path and "plan_path" in tool_input:
-        plan_path = tool_input["plan_path"]
-    elif not plan_path and "planPath" in tool_input:
-        plan_path = tool_input["planPath"]
+            log_info("archive_plan", f"Extracted plan path from result: {plan_path}")
 
-    # If not found yet, search standard locations
+    # Check tool_input for plan path
     if not plan_path:
-        print("[archive_plan] No plan_path found, searching standard locations...")
-        # Look for plan in common locations
-        possible_paths = []
+        plan_path = tool_input.get("plan_path") or tool_input.get("planPath")
 
-        # Check Claude Code plan directory first (~/.claude/plans/)
+    # Search standard locations
+    if not plan_path:
+        log_debug("archive_plan", "No plan_path found, searching standard locations...")
         claude_plans_dir = Path.home() / ".claude" / "plans"
-        print(f"[archive_plan] Checking Claude plans dir: {claude_plans_dir}")
         if claude_plans_dir.exists():
-            # Find any .md file in Claude plans directory
-            claude_plans = list(claude_plans_dir.glob("*.md"))
-            print(f"[archive_plan] Found {len(claude_plans)} .md files in Claude plans dir")
-            # Sort by modification time, newest first
+            claude_plans = sorted(
+                claude_plans_dir.glob("*.md"),
+                key=lambda p: p.stat().st_mtime,
+                reverse=True,
+            )
             if claude_plans:
-                claude_plans.sort(key=lambda p: p.stat().st_mtime, reverse=True)
-                possible_paths.extend(claude_plans)
-                for p in claude_plans[:3]:  # Show first 3
-                    print(f"[archive_plan]   - {p}")
+                plan_path = str(claude_plans[0])
 
-        # Existing fallback paths
-        possible_paths.extend([
+    if not plan_path:
+        for fallback in [
             project_root / "_output" / "cc-native" / "plans" / "current-plan.md",
             project_root / "_output" / "plans" / "current-plan.md",
             project_root / "plan.md",
-        ])
-
-        for path in possible_paths:
-            if path.exists():
-                plan_path = str(path)
+        ]:
+            if fallback.exists():
+                plan_path = str(fallback)
                 break
 
-    if not plan_path:
-        eprint("[archive_plan] Could not determine plan path")
-        # Don't block - let ExitPlanMode proceed
-        print("[archive_plan] Could not find plan file in any of these locations:")
-        print(f"  - ~/.claude/plans/*.md")
-        print(f"  - {project_root}/_output/cc-native/plans/current-plan.md")
-        print(f"  - {project_root}/_output/plans/current-plan.md")
-        print(f"  - {project_root}/plan.md")
-        print("Plan archival skipped: no plan path found")
+    return plan_path
+
+
+def on_plan_archive():
+    """Archive plan on PermissionRequest:ExitPlanMode — file archival only, no state.json changes."""
+    hook_input = load_hook_input()
+    if not hook_input:
+        log_warn("archive_plan", "No valid JSON input")
         return
 
-    print(f"[archive_plan] Found plan at: {plan_path}")
+    hook_event = hook_input.get("hook_event_name", "unknown")
+    tool_name = hook_input.get("tool_name", "")
+
+    log_info("archive_plan", f"Hook triggered: {hook_event}, tool: {tool_name}")
+
+    # Only handle PermissionRequest for ExitPlanMode
+    if not (hook_event == "PermissionRequest" and tool_name == "ExitPlanMode"):
+        log_debug("archive_plan", "Skipping: not PermissionRequest:ExitPlanMode")
+        return
 
-    # Resolve plan path relative to project root
+    if hook_input.get("stop_hook_active", False):
+        log_debug("archive_plan", "Stop hook active, skipping")
+        return
+
+    project_root = project_dir(hook_input)
+    plan_path = _find_plan_path(hook_input, project_root)
+
+    if not plan_path:
+        log_warn("archive_plan", "Could not find plan file, skipping archival")
+        return
+
+    # Resolve plan path
     plan_file = Path(plan_path)
     if not plan_file.is_absolute():
-        # Ensure we have a valid project_root
-        if project_root is None:
-            project_root = project_dir()
         plan_file = project_root / plan_path
-    else:
-        # On Windows, check if absolute path is on a different drive than project_root
-        # In that case, use the absolute path as-is
-        if sys.platform == 'win32':
-            try:
-                # Check if drives match (e.g., C: vs D:)
-                plan_drive = plan_file.drive.upper() if plan_file.drive else None
-                project_drive = project_root.drive.upper() if hasattr(project_root, 'drive') and project_root.drive else None
-                if plan_drive and project_drive and plan_drive != project_drive:
-                    # Different drives - use absolute path as-is
-                    pass  # plan_file is already set correctly
-            except Exception:
-                pass  # Fall through to use plan_file as-is
-
-    print(f"[archive_plan] Resolved plan file path: {plan_file}")
+
+    log_debug("archive_plan", f"Resolved plan file: {plan_file}")
 
     if not plan_file.exists():
-        eprint(f"[archive_plan] Plan file not found: {plan_file}")
-        print(f"[archive_plan] ERROR: File does not exist at resolved path")
-        print(f"Plan archival skipped: file not found ({plan_path})")
+        log_error("archive_plan", f"Plan file not found: {plan_file}")
         return
 
-    # Find context by session ID using shared extractor
+    # Find context by session ID
     session_id = hook_input.get("session_id", "unknown")
-    context_id = extract_context_id_for_session(session_id, project_root, "archive_plan")
+    state = get_context_by_session_id(session_id, project_root)
 
-    if not context_id:
-        eprint("[archive_plan] Could not determine context for session")
-        print("Plan archival failed: no context found for this session")
+    if not state:
+        log_warn("archive_plan", "Could not determine context for session")
         return
 
-    # Check if plan was already archived (avoid duplicates)
-    contexts = get_all_contexts(status="active", project_root=project_root)
-    for ctx in contexts:
-        if ctx.id == context_id:
-            if ctx.in_flight and ctx.in_flight.mode == "pending_implementation":
-                print(f"[archive_plan] Plan already archived for context '{context_id}', skipping")
-                return
-            break
-
-    # Archive the plan
-    archived_path, plan_hash = archive_plan_to_context(
-        str(plan_file),
-        context_id,
-        project_root
+    context_id = state.id
+
+    # Archive the plan file (returns path, hash, signature)
+    archived_path, plan_hash, plan_signature = archive_plan(
+        str(plan_file), context_id, project_root
     )
 
     if archived_path:
-        # Clean up debug logs before completing archive
+        # Clean up debug logs
         try:
             context_path = get_context_dir(context_id, project_root)
             cleanup_debug_folder(context_path)
-            print(f"[archive_plan] Cleaned up debug logs for context: {context_id}")
         except Exception as e:
-            print(f"[archive_plan] Warning: could not clean debug folder: {e}")
-
-        print(f"")
-        print(f"[archive_plan] SUCCESS!")
-        print(f"[archive_plan] Plan archived to context: {context_id}")
-        print(f"[archive_plan] Archived path: {archived_path}")
-        print(f"[archive_plan] Source path: {plan_file}")
-        print(f"[archive_plan] Hash: {plan_hash}")
-        print(f"")
-        print("After /clear, SessionStart will auto-continue this context for implementation.")
+            log_warn("archive_plan", f"could not clean debug folder: {e}")
+
+        log_info("archive_plan", f"SUCCESS: archived plan for {context_id}")
+        log_debug("archive_plan", f"Path: {archived_path}, hash: {plan_hash}")
     else:
-        print(f"[archive_plan] FAILED: Could not archive plan for context '{context_id}'")
+        log_error("archive_plan", f"Could not archive plan for '{context_id}'")
 
 
 if __name__ == "__main__":
-    try:
-        on_plan_archive()
-    except Exception as e:
-        # Log errors to stderr
-        eprint(f"[archive_plan] Error: {e}")
-        import traceback
-        eprint(traceback.format_exc())
-        # Exit cleanly so hook doesn't block
-        sys.exit(0)
+    from lib.base.hook_utils import run_hook
+    run_hook(on_plan_archive, "archive_plan")