aiwcli 0.9.7 → 0.9.8

package/dist/templates/CLAUDE.md

@@ -17,24 +17,53 @@ 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 management, event sourcing, discovery
+│       ├── 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
+│   ├── _shared/                      #   Copy of shared infrastructure (installed together)
+│   ├── .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 sync, 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 +86,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 +94,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 +148,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 +172,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 +194,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 +202,4 @@ 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/`)

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

@@ -373,7 +373,7 @@ def determine_context(
             return (
                 session_context.id,
                 "session_match",
-                format_active_context_reminder(session_context)
+                format_active_context_reminder(session_context, project_root)
             )
 
     # 2. Check for bare "^" - show context picker
@@ -433,11 +433,11 @@ def determine_context(
 
         # Use mode-specific formatter for better continuation context
         if mode == "pending_implementation":
-            output = format_pending_plan_continuation(ctx)
+            output = format_pending_plan_continuation(ctx, project_root)
         elif mode == "implementing":
-            output = format_implementation_continuation(ctx)
+            output = format_implementation_continuation(ctx, project_root)
         else:
-            output = format_active_context_reminder(ctx)
+            output = format_active_context_reminder(ctx, project_root, include_restore=True)
 
         return (ctx.id, "auto_selected", output)
 

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

@@ -62,8 +62,15 @@ from lib.context.context_manager import (
     get_context_by_session_id,
     update_plan_status,
 )
+from lib.context.auto_state import save_auto_state
+from lib.context.event_log import EVENT_AUTO_STATE_SAVED, append_event
+
+# Module-level flag: only save auto-state once per process lifetime
+# Since hooks are separate processes per invocation, we use a file marker instead
+_PROGRESSIVE_SAVE_MARKER = ".progressive-save-done"
 
 # Configuration
+SAVE_STATE_THRESHOLD = 60  # Silently save auto-state at 60% remaining
 LOW_CONTEXT_THRESHOLD = 40  # Warn when below 40% remaining
 CRITICAL_CONTEXT_THRESHOLD = 25  # Urgent warning below 25%
 
@@ -242,6 +249,71 @@ def check_and_transition_mode(hook_input: dict) -> None:
         update_plan_status(context.id, "implementing", project_root=project_root)
 
 
+def _try_progressive_save(hook_input: dict, percent_remaining: int) -> None:
+    """
+    Silently save auto-state at SAVE_STATE_THRESHOLD (60%).
+
+    Uses a marker file in the context folder to ensure this fires only
+    once per session. The marker is the session_id written to a file.
+
+    Args:
+        hook_input: Hook input data from Claude Code
+        percent_remaining: Current context percentage remaining
+    """
+    try:
+        session_id = hook_input.get("session_id", "")
+        if not session_id:
+            return
+
+        project_root = project_dir(hook_input)
+        context = get_context_by_session_id(session_id, project_root)
+        if not context:
+            return
+
+        from lib.base.constants import get_context_dir
+        marker_path = get_context_dir(context.id, project_root) / _PROGRESSIVE_SAVE_MARKER
+        # Check if already saved for this session
+        if marker_path.exists():
+            try:
+                saved_session = marker_path.read_text(encoding="utf-8").strip()
+                if saved_session == session_id:
+                    return  # Already saved this session
+            except OSError:
+                pass
+
+        eprint(f"[context_monitor] Progressive save at {percent_remaining}% remaining")
+
+        in_flight_mode = context.in_flight.mode if context.in_flight else "none"
+        plan_path = context.in_flight.artifact_path if context.in_flight else None
+        handoff_path = context.in_flight.handoff_path if context.in_flight else None
+        transcript_path = hook_input.get("transcript_path")
+
+        saved = save_auto_state(
+            context_id=context.id,
+            session_id=session_id,
+            save_reason="progressive",
+            project_root=project_root,
+            in_flight_mode=in_flight_mode,
+            plan_path=plan_path,
+            handoff_path=handoff_path,
+            transcript_path=transcript_path,
+        )
+
+        if saved:
+            append_event(
+                context.id, EVENT_AUTO_STATE_SAVED, project_root,
+                session_id=session_id, save_reason="progressive",
+            )
+            # Write marker so we don't save again this session
+            try:
+                marker_path.write_text(session_id, encoding="utf-8")
+            except OSError:
+                pass
+
+    except Exception as e:
+        eprint(f"[context_monitor] Progressive save error (non-fatal): {e}")
+
+
 def check_context_level(hook_input: dict) -> Optional[str]:
     """
     Check context level and return warning if low.
@@ -270,7 +342,13 @@ def check_context_level(hook_input: dict) -> Optional[str]:
     percent_remaining = max(0, min(100, int((remaining / max_tokens) * 100)))
 
     # 4. Most common case: context is fine, exit early
+    if percent_remaining > SAVE_STATE_THRESHOLD:
+        return None
+
+    # === PROGRESSIVE SAVE: At 60% remaining, silently save auto-state ===
     if percent_remaining > LOW_CONTEXT_THRESHOLD:
+        # Only save once per session (check marker file)
+        _try_progressive_save(hook_input, percent_remaining)
         return None
 
     # === SLOW PATH: Only reached when context is low (rare) ===
@@ -320,7 +398,6 @@ def main():
             # Plain stdout from PostToolUse only goes to verbose mode, not Claude's context
             output = {
                 "hookSpecificOutput": {
-                    "hookEventName": "PostToolUse",
                     "additionalContext": warning
                 }
             }

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

@@ -0,0 +1,89 @@
+#!/usr/bin/env python3
+"""PreCompact hook - saves auto-state before context compaction.
+
+Critical: saves state before context compaction destroys token history.
+After compaction, SessionStart fires with source="compact" and the
+restored auto-state provides continuity context.
+
+Hook input (from Claude Code):
+{
+    "hook_event_name": "PreCompact",
+    "session_id": "abc123",
+    "transcript_path": "/path/to/transcript.jsonl",
+    "cwd": "/path/to/project",
+    ...
+}
+
+Hook output:
+- Silent (no stdout output needed)
+- Logs to stderr for debugging
+"""
+import sys
+from pathlib import Path
+
+# Add parent directories to path for imports
+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.base.utils import eprint, project_dir
+from lib.context.context_manager import get_context_by_session_id
+from lib.context.event_log import EVENT_AUTO_STATE_SAVED, append_event
+from lib.context.auto_state import save_auto_state
+
+
+def main():
+    """Save auto-state before compaction."""
+    try:
+        hook_input = load_hook_input()
+        if not hook_input:
+            return
+
+        session_id = hook_input.get("session_id", "")
+        transcript_path = hook_input.get("transcript_path")
+        project_root = project_dir(hook_input)
+
+        if not session_id:
+            eprint("[pre_compact] No session_id, skipping")
+            return
+
+        eprint(f"[pre_compact] Saving state before compaction: {session_id[:8]}...")
+
+        # Find context bound to this session
+        context = get_context_by_session_id(session_id, project_root)
+        if not context:
+            eprint("[pre_compact] No context bound to this session, skipping")
+            return
+
+        context_id = context.id
+        in_flight_mode = context.in_flight.mode if context.in_flight else "none"
+        plan_path = context.in_flight.artifact_path if context.in_flight else None
+        handoff_path = context.in_flight.handoff_path if context.in_flight else None
+
+        saved = save_auto_state(
+            context_id=context_id,
+            session_id=session_id,
+            save_reason="pre_compact",
+            project_root=project_root,
+            in_flight_mode=in_flight_mode,
+            plan_path=plan_path,
+            handoff_path=handoff_path,
+            transcript_path=transcript_path,
+        )
+
+        if saved:
+            append_event(
+                context_id, EVENT_AUTO_STATE_SAVED, project_root,
+                session_id=session_id, save_reason="pre_compact",
+            )
+            eprint(f"[pre_compact] Auto-state saved for {context_id}")
+
+    except Exception as e:
+        eprint(f"[pre_compact] ERROR: {e}")
+        import traceback
+        eprint(traceback.format_exc())
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+"""SessionEnd hook - records session boundary and saves auto-state.
+
+Fires when session terminates (quit, /clear, logout). Creates a session
+boundary marker in events.jsonl and writes auto-state.json for restoration.
+
+Hook input (from Claude Code):
+{
+    "hook_event_name": "SessionEnd",
+    "session_id": "abc123",
+    "source": "prompt_input_exit",  # or "clear", "logout", "compact"
+    "transcript_path": "/path/to/transcript.jsonl",
+    "cwd": "/path/to/project",
+    ...
+}
+
+Hook output:
+- Silent (no stdout output needed for SessionEnd)
+- Logs to stderr for debugging
+"""
+import sys
+from pathlib import Path
+
+# Add parent directories to path for imports
+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.base.utils import eprint, project_dir
+from lib.context.context_manager import get_context_by_session_id
+from lib.context.event_log import get_current_state, EVENT_AUTO_STATE_SAVED, append_event
+from lib.context.task_sync import record_session_ended
+from lib.context.auto_state import save_auto_state
+
+
+def main():
+    """Record session boundary and save auto-state."""
+    try:
+        hook_input = load_hook_input()
+        if not hook_input:
+            return
+
+        session_id = hook_input.get("session_id", "")
+        source = hook_input.get("source", "other")
+        transcript_path = hook_input.get("transcript_path")
+        project_root = project_dir(hook_input)
+
+        if not session_id:
+            eprint("[session_end] No session_id, skipping")
+            return
+
+        eprint(f"[session_end] Session ending: {session_id[:8]}... reason={source}")
+
+        # Find context bound to this session
+        context = get_context_by_session_id(session_id, project_root)
+        if not context:
+            eprint("[session_end] No context bound to this session, skipping")
+            return
+
+        context_id = context.id
+        eprint(f"[session_end] Found context: {context_id}")
+
+        # Get current task state for the session boundary marker
+        state = get_current_state(context_id, project_root)
+        active_tasks = [t.id for t in state.tasks if t.status == "in_progress"]
+        pending_tasks = [t.id for t in state.tasks if t.status == "pending"]
+
+        # Record session_ended event in events.jsonl
+        record_session_ended(
+            context_id=context_id,
+            session_id=session_id,
+            reason=source,
+            active_tasks=active_tasks,
+            pending_tasks=pending_tasks,
+            project_root=project_root,
+        )
+        eprint(f"[session_end] Recorded session_ended: active={len(active_tasks)}, pending={len(pending_tasks)}")
+
+        # Save auto-state.json
+        in_flight_mode = context.in_flight.mode if context.in_flight else "none"
+        plan_path = context.in_flight.artifact_path if context.in_flight else None
+        handoff_path = context.in_flight.handoff_path if context.in_flight else None
+
+        saved = save_auto_state(
+            context_id=context_id,
+            session_id=session_id,
+            save_reason=source,
+            project_root=project_root,
+            in_flight_mode=in_flight_mode,
+            plan_path=plan_path,
+            handoff_path=handoff_path,
+            transcript_path=transcript_path,
+        )
+
+        if saved:
+            # Record auto_state_saved event
+            append_event(
+                context_id, EVENT_AUTO_STATE_SAVED, project_root,
+                session_id=session_id, save_reason=source,
+            )
+            eprint(f"[session_end] Auto-state saved for {context_id}")
+
+    except Exception as e:
+        eprint(f"[session_end] ERROR: {e}")
+        import traceback
+        eprint(traceback.format_exc())
+
+
+if __name__ == "__main__":
+    main()

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

@@ -1,18 +1,14 @@
 #!/usr/bin/env python3
-"""SessionStart hook for mode transitions after /clear.
+"""SessionStart hook for mode transitions and post-compaction restore.
 
-This hook fires when a new session starts. It handles the critical transition
-from `pending_implementation` to `implementing` when a session starts after
-/clear with bypass permissions.
+This hook fires when a new session starts. It handles:
 
-The flow is:
-1. User approves plan (ExitPlanMode) -> mode = pending_implementation
-2. User clicks "yes and clear and bypass permissions"
-3. SessionStart fires with source="clear" and permission_mode="bypassPermissions"
-4. This hook transitions mode to "implementing"
+1. Mode transition from `pending_implementation` to `implementing` when
+   a session starts after /clear with bypass permissions.
 
-Without this hook, the mode stays stuck at pending_implementation because
-UserPromptSubmit may not receive the correct permission_mode after /clear.
+2. Post-compaction restore: when source="compact", the session is already
+   bound to a context. Load auto-state and inject rich restoration context
+   so Claude can continue seamlessly after compaction.
 
 Hook input:
 {
@@ -24,6 +20,7 @@ Hook input:
     ...
 }
 """
+import json
 import sys
 from pathlib import Path
 
@@ -36,22 +33,106 @@ from lib.base.hook_utils import load_hook_input
 from lib.base.utils import eprint, project_dir
 from lib.context.context_manager import (
     get_all_in_flight_contexts,
+    get_context_by_session_id,
     update_plan_status,
     update_context_session_id,
 )
+from lib.context.auto_state import load_auto_state
+from lib.context.discovery import (
+    _build_restore_sections,
+    find_plan_path,
+    format_relative_time,
+)
+from lib.context.task_sync import generate_task_summary
 
 
-def main():
+def _handle_clear_transition(hook_input, session_id, project_root):
+    """Handle /clear mode transitions (existing behavior)."""
+    permission_mode = hook_input.get("permission_mode", "default")
+
+    if permission_mode == "plan":
+        eprint("[session_start] Skipping: permission_mode is 'plan' (in planning mode)")
+        return
+
+    in_flight_contexts = get_all_in_flight_contexts(project_root)
+    if not in_flight_contexts:
+        eprint("[session_start] No in-flight contexts found")
+        return
+
+    pending_contexts = [
+        ctx for ctx in in_flight_contexts
+        if ctx.in_flight and ctx.in_flight.mode == "pending_implementation"
+    ]
+    for ctx in pending_contexts:
+        eprint(f"[session_start] Transitioning {ctx.id} from pending_implementation to implementing")
+        update_plan_status(ctx.id, "implementing", project_root=project_root)
+        update_context_session_id(ctx.id, session_id, project_root)
+        eprint(f"[session_start] Bound session {session_id[:8]}... to context {ctx.id}")
+
+    if pending_contexts:
+        eprint(f"[session_start] Transitioned {len(pending_contexts)} context(s) to implementing")
+
+
+def _handle_compact_restore(hook_input, session_id, project_root):
+    """
+    Handle post-compaction restore.
+
+    After compaction, the session is already bound to a context.
+    Load auto-state and inject rich restoration context via additionalContext.
     """
-    Handle mode transitions on session start.
+    context = get_context_by_session_id(session_id, project_root)
+    if not context:
+        eprint("[session_start] No context bound to session after compact")
+        return
+
+    context_id = context.id
+    eprint(f"[session_start] Post-compaction restore for context: {context_id}")
+
+    # Build restoration context
+    mode_display = "Active"
+    if context.in_flight and context.in_flight.mode != "none":
+        mode_display = context.in_flight.mode.replace("_", " ").title()
+
+    lines = [
+        f"## Resuming Context After Compaction: {context_id}",
+        "",
+        f"**Summary:** {context.summary}",
+        f"**Mode:** {mode_display}",
+    ]
+
+    # Add restore sections (auto-state, tasks, git)
+    restore = _build_restore_sections(context, project_root)
+    if restore:
+        lines.append(restore)
+
+    lines.extend([
+        "",
+        "---",
+        "",
+        "**Instructions:**",
+        "Context was compacted to free memory. Your previous conversation has been summarized.",
+        "1. Review the previous work above",
+        "2. Continue from where you left off",
+    ])
+
+    restore_context = "\n".join(lines)
+
+    # Output as additionalContext so Claude sees it
+    output = {
+        "hookSpecificOutput": {
+            "additionalContext": restore_context
+        }
+    }
+    print(json.dumps(output, ensure_ascii=False))
+    eprint(f"[session_start] Injected post-compaction restore context for {context_id}")
+
 
-    When source is "clear" and permission_mode is "bypassPermissions" or "acceptEdits",
-    transition any pending_implementation context to implementing.
+def main():
+    """
+    Handle mode transitions and post-compaction restore on session start.
     """
     try:
-        # Read hook input using shared utility
         hook_input = load_hook_input()
-
         if not hook_input:
             return
 
@@ -62,36 +143,12 @@ def main():
 
         eprint(f"[session_start] source={source}, permission_mode={permission_mode}, session={session_id[:8]}...")
 
-        # Only handle /clear with bypass/accept permissions
-        if source != "clear":
-            eprint(f"[session_start] Skipping: source is '{source}', not 'clear'")
-            return
-
-        if permission_mode == "plan":
-            eprint(f"[session_start] Skipping: permission_mode is 'plan' (in planning mode)")
-            return
-
-        # Find contexts in pending_implementation mode
-        in_flight_contexts = get_all_in_flight_contexts(project_root)
-        pending_contexts = [
-            ctx for ctx in in_flight_contexts
-            if ctx.in_flight and ctx.in_flight.mode == "pending_implementation"
-        ]
-
-        if not pending_contexts:
-            eprint("[session_start] No pending_implementation contexts found")
-            return
-
-        # Transition each pending context to implementing
-        for ctx in pending_contexts:
-            eprint(f"[session_start] Transitioning {ctx.id} from pending_implementation to implementing")
-            update_plan_status(ctx.id, "implementing", project_root=project_root)
-
-            # Also bind this session to the context
-            update_context_session_id(ctx.id, session_id, project_root)
-            eprint(f"[session_start] Bound session {session_id[:8]}... to context {ctx.id}")
-
-        eprint(f"[session_start] Transitioned {len(pending_contexts)} context(s) to implementing")
+        if source == "clear":
+            _handle_clear_transition(hook_input, session_id, project_root)
+        elif source == "compact":
+            _handle_compact_restore(hook_input, session_id, project_root)
+        else:
+            eprint(f"[session_start] No action for source='{source}'")
 
     except Exception as e:
         eprint(f"[session_start] ERROR: {e}")