aiwcli 0.9.0

package/dist/templates/_shared/lib/templates/README.md

@@ -0,0 +1,215 @@
+# Shared Templates Module
+
+Centralized templates and formatters for consistent context management output across discovery, handoff, and hooks.
+
+## Purpose
+
+This module eliminates duplication by providing a single source of truth for:
+- Mode displays (planning, implementing, etc.)
+- Status icons (pending, in_progress, completed)
+- Task rendering formatters
+- Context continuation headers
+- Plan context templates
+- Handoff reason formatting
+
+## Modules
+
+### `formatters.py`
+
+Core formatters and constants for context management output.
+
+#### Constants
+
+```python
+MODE_DISPLAY_MAP = {
+    "planning": "[Planning]",
+    "pending_implementation": "[Plan Ready]",
+    "implementing": "[Implementing]",
+    "handoff_pending": "[Handoff Pending]",
+    "none": "",
+}
+
+STATUS_ICON_MAP = {
+    "pending": "⬜",
+    "in_progress": "🔄",
+    "blocked": "🚫",
+    "completed": "✅",
+}
+
+REASON_MAP = {
+    "low_context": "Context window running low",
+    "user_requested": "User requested handoff",
+    "error_recovery": "Error recovery",
+    "session_end": "Session ending",
+}
+```
+
+#### Functions
+
+**`get_mode_display(mode: str) -> str`**
+
+Get display string for in-flight mode.
+
+```python
+>>> get_mode_display("planning")
+"[Planning]"
+>>> get_mode_display("none")
+""
+```
+
+**`get_status_icon(status: str) -> str`**
+
+Get emoji icon for task status.
+
+```python
+>>> get_status_icon("pending")
+"⬜"
+>>> get_status_icon("completed")
+"✅"
+```
+
+**`render_task_item(task, show_description=True, max_description_length=100) -> str`**
+
+Render single task with status icon and subject.
+
+```python
+task = {"status": "pending", "subject": "Fix bug", "description": "Details"}
+>>> render_task_item(task)
+"- ⬜ [PENDING] Fix bug\n  - Details"
+```
+
+**`render_task_list(tasks, header="Active Tasks", show_description=True) -> str`**
+
+Render list of tasks with header.
+
+```python
+tasks = [{"status": "pending", "subject": "Task 1", "description": "Details"}]
+>>> render_task_list(tasks, header="My Tasks")
+"### My Tasks\n\n- ⬜ [PENDING] Task 1\n  - Details\n"
+```
+
+**`format_continuation_header(header_type: str, context_id: str) -> str`**
+
+Format continuation header for various scenarios.
+
+```python
+>>> format_continuation_header("resuming", "my-context")
+"## RESUMING FROM HANDOFF: my-context"
+```
+
+Types: `context`, `resuming`, `implementing`, `handoff`
+
+**`format_reason(reason: str) -> str`**
+
+Format handoff reason code as human-readable string.
+
+```python
+>>> format_reason("low_context")
+"Context window running low"
+```
+
+### `plan_context.py`
+
+Plan context templates for the add_plan_context hook.
+
+**`get_evaluation_context_reminder() -> str`**
+
+Returns the evaluation context reminder template that prompts Claude to add evaluation context to plans.
+
+**`get_questions_offer_template() -> str`**
+
+Returns the clarifying questions offer template shown on first plan write.
+
+## Usage
+
+### In Discovery Functions
+
+```python
+from ..templates.formatters import (
+    get_mode_display,
+    get_status_icon,
+    format_continuation_header,
+)
+
+# Display mode status
+mode_display = get_mode_display(context.in_flight.mode)
+status = f"Context: {context.id} {mode_display}"
+
+# Render task with icon
+icon = get_status_icon(task.status)
+output = f"{icon} {task.subject}"
+
+# Create continuation header
+header = format_continuation_header("implementing", context.id)
+```
+
+### In Document Generator
+
+```python
+from ..templates.formatters import render_task_list, format_reason
+
+# Render task list section
+tasks_md = render_task_list(doc.active_tasks, header="Active Tasks")
+lines.append(tasks_md)
+
+# Format handoff reason
+reason_text = format_reason(doc.reason)
+```
+
+### In Hooks
+
+```python
+from templates.plan_context import (
+    get_evaluation_context_reminder,
+    get_questions_offer_template,
+)
+
+# Get plan context templates
+CONTEXT_REMINDER = get_evaluation_context_reminder()
+QUESTIONS_OFFER = get_questions_offer_template()
+```
+
+## Dependent Files
+
+Files that import from this module:
+
+- `.aiwcli/_shared/lib/context/discovery.py`
+  - Uses: `get_mode_display`, `get_status_icon`, `format_continuation_header`
+
+- `.aiwcli/_shared/lib/handoff/document_generator.py`
+  - Uses: `render_task_list`, `format_continuation_header`, `format_reason`
+
+- `.aiwcli/_cc-native/hooks/add_plan_context.py`
+  - Uses: `get_evaluation_context_reminder`, `get_questions_offer_template`
+
+## Design Principles
+
+1. **Single Source of Truth**: Each constant/function exists in one location only
+2. **Backward Compatible**: All functions preserve existing output formats
+3. **Type Flexible**: Functions handle both Task objects and dicts
+4. **Fail-Safe**: Use `.get()` with defaults for missing keys
+
+## Testing
+
+```bash
+# Test imports
+cd .aiwcli
+python -c "from _shared.lib.templates.formatters import get_mode_display; \
+           assert get_mode_display('planning') == '[Planning]'"
+
+# Test task rendering
+python -c "from _shared.lib.templates.formatters import get_status_icon; \
+           assert get_status_icon('pending') != ''"
+```
+
+## Synchronization
+
+Changes to this module must be synchronized to the template directory:
+
+```bash
+# After editing
+cp .aiwcli/_shared/lib/templates/*.py \
+   packages/cli/src/templates/_shared/lib/templates/
+```
+
+See `CLAUDE.md` for template synchronization requirements.

package/dist/templates/_shared/lib/templates/__init__.py

@@ -0,0 +1,40 @@
+"""Shared templates and formatters for context management output.
+
+This module provides centralized templates for:
+- Mode displays (planning, implementing, etc.)
+- Status icons (pending, in_progress, completed)
+- Task rendering
+- Context continuation headers
+
+Used by discovery.py, document_generator.py, and hooks.
+"""
+
+from .formatters import (
+    MODE_DISPLAY_MAP,
+    STATUS_ICON_MAP,
+    REASON_MAP,
+    get_mode_display,
+    get_status_icon,
+    render_task_item,
+    render_task_list,
+    format_continuation_header,
+    format_reason,
+)
+from .plan_context import (
+    get_evaluation_context_reminder,
+    get_questions_offer_template,
+)
+
+__all__ = [
+    "MODE_DISPLAY_MAP",
+    "STATUS_ICON_MAP",
+    "REASON_MAP",
+    "get_mode_display",
+    "get_status_icon",
+    "render_task_item",
+    "render_task_list",
+    "format_continuation_header",
+    "format_reason",
+    "get_evaluation_context_reminder",
+    "get_questions_offer_template",
+]

package/dist/templates/_shared/lib/templates/formatters.py

@@ -0,0 +1,147 @@
+"""Formatters for context management templates.
+
+Provides constants and helper functions for consistent formatting
+across discovery, handoff, and hook output.
+"""
+
+from typing import Any, Dict, List, Optional, Union
+
+# Mode display mapping for in-flight work states
+MODE_DISPLAY_MAP = {
+    "planning": "[Planning]",
+    "pending_implementation": "[Plan Ready]",
+    "implementing": "[Implementing]",
+    "handoff_pending": "[Handoff Pending]",
+    "none": "",
+}
+
+# Status icon mapping for task states
+STATUS_ICON_MAP = {
+    "pending": "⬜",
+    "in_progress": "🔄",
+    "blocked": "🚫",
+    "completed": "✅",
+}
+
+
+def get_mode_display(mode: str) -> str:
+    """Get display string for in-flight mode.
+
+    Args:
+        mode: In-flight mode string (planning, implementing, etc.)
+
+    Returns:
+        Display string like "[Planning]" or empty string for "none"
+    """
+    return MODE_DISPLAY_MAP.get(mode, "")
+
+
+def get_status_icon(status: str) -> str:
+    """Get emoji icon for task status.
+
+    Args:
+        status: Task status (pending, in_progress, blocked, completed)
+
+    Returns:
+        Emoji icon like "⬜" or "✅"
+    """
+    return STATUS_ICON_MAP.get(status, "⬜")
+
+
+def render_task_item(
+    task: Union["Task", Dict[str, Any]],
+    show_description: bool = True,
+    max_description_length: int = 100
+) -> str:
+    """Render single task with status icon and subject.
+
+    Args:
+        task: Task object or dict with status, subject, description
+        show_description: Whether to include description
+        max_description_length: Maximum length for description before truncating
+
+    Returns:
+        Formatted string: "- {icon} [{STATUS}] {subject}"
+    """
+    # Handle both Task objects and dicts
+    status = task.get("status") if isinstance(task, dict) else task.status
+    subject = task.get("subject") if isinstance(task, dict) else task.subject
+    description = task.get("description") if isinstance(task, dict) else task.description
+
+    icon = get_status_icon(status)
+    status_text = f"[{status.upper()}]"
+    line = f"- {icon} {status_text} {subject}"
+
+    if show_description and description:
+        truncated = description[:max_description_length]
+        if len(description) > max_description_length:
+            truncated += "..."
+        return f"{line}\n  - {truncated}"
+    return line
+
+
+def render_task_list(
+    tasks: List[Union["Task", Dict[str, Any]]],
+    header: Optional[str] = "Active Tasks",
+    show_description: bool = True
+) -> str:
+    """Render list of tasks with header.
+
+    Args:
+        tasks: List of Task objects or dicts
+        header: Section header text
+        show_description: Whether to show task descriptions
+
+    Returns:
+        Formatted markdown section with task list
+    """
+    lines = [f"### {header}", ""]
+
+    if not tasks:
+        lines.append("No active tasks.")
+    else:
+        for task in tasks:
+            lines.append(render_task_item(task, show_description))
+
+    lines.append("")
+    return "\n".join(lines)
+
+
+def format_continuation_header(header_type: str, context_id: str) -> str:
+    """Format continuation header for various scenarios.
+
+    Args:
+        header_type: Type of continuation (context, resuming, implementing, handoff)
+        context_id: Context identifier
+
+    Returns:
+        Formatted markdown header
+    """
+    headers = {
+        "context": f"## CONTINUING CONTEXT: {context_id}",
+        "resuming": f"## RESUMING FROM HANDOFF: {context_id}",
+        "implementing": f"## CONTINUING IMPLEMENTATION: {context_id}",
+        "handoff": f"# Session Handoff: {context_id}",
+    }
+    return headers.get(header_type, f"## {context_id}")
+
+
+# Handoff reason display mapping
+REASON_MAP = {
+    "low_context": "Context window running low",
+    "user_requested": "User requested handoff",
+    "error_recovery": "Error recovery",
+    "session_end": "Session ending",
+}
+
+
+def format_reason(reason: str) -> str:
+    """Format handoff reason code as human-readable string.
+
+    Args:
+        reason: Reason code (low_context, user_requested, etc.)
+
+    Returns:
+        Human-readable reason string
+    """
+    return REASON_MAP.get(reason, reason)

package/dist/templates/_shared/lib/templates/plan_context.py

@@ -0,0 +1,119 @@
+"""Plan context templates for add_plan_context hook.
+
+Provides standardized templates for:
+- Evaluation context reminder
+- Clarifying questions offer
+"""
+
+
+def get_evaluation_context_reminder() -> str:
+    """Get the plan evaluation context reminder template.
+
+    Returns:
+        Formatted markdown reminder about adding evaluation context
+    """
+    return """
+## IMPORTANT: This Plan Will Be Executed in a Fresh Context
+
+Your plan will be:
+1. **Reviewed** by agents who have NO access to this conversation
+2. **Executed** by a Claude agent starting with a completely fresh context
+
+The implementing agent won't have access to your research, file explorations, or any conversation history. Your plan must be **self-contained** and provide everything needed to execute it successfully.
+
+### Required Plan Elements
+
+1. **A title line** at the very top: `# Plan: <descriptive title>`
+
+2. **Context Section** near the top with:
+   - **Background**: The bigger picture - why this change is needed and what problem it solves
+   - **Task**: What is being built/changed (specific and actionable)
+   - **Goal**: The underlying problem the user wants solved
+   - **Constraints**: Technical requirements, preferences, or limitations mentioned
+
+3. **Relevant Files** section listing:
+   - Files that will be modified (with brief description of what changes)
+   - Files to reference for patterns/context (with why they're relevant)
+   - Any configuration files that matter
+
+4. **Implementation Details** that are explicit enough for someone unfamiliar with your research:
+   - Don't assume the implementer knows what you discovered
+   - Include specific function names, patterns, or approaches to use
+   - Reference line numbers or code snippets if helpful
+
+### Example
+
+```markdown
+# Plan: Add OAuth2 Authentication
+
+## Context
+**Background**: The app currently only supports username/password auth. Users have requested social login to reduce friction during signup.
+**Task**: Implement OAuth2 flow for user authentication
+**Goal**: Enable secure third-party authentication via Google and GitHub
+**Constraints**: Must integrate with existing session management; no new dependencies preferred
+
+## Relevant Files
+**Modify:**
+- `src/auth/middleware.ts` - Add OAuth callback handlers
+- `src/routes/auth.ts` - Add OAuth routes
+
+**Reference for patterns:**
+- `src/auth/password.ts` - Shows existing auth flow pattern
+- `src/config/index.ts` - Where to add OAuth credentials
+
+## Implementation Steps
+[Detailed steps here...]
+```
+
+This context allows reviewers to assess whether your plan addresses the user's needs, AND enables the implementing agent to execute it without needing to re-discover your research.
+""".strip()
+
+
+def get_questions_offer_template() -> str:
+    """Get the clarifying questions offer template.
+
+    Returns:
+        Formatted markdown prompt for offering clarifying questions
+    """
+    return """
+## First Plan Write - Optional Clarifying Questions
+
+Your initial plan has been saved. Before finalizing, ask the user if they'd like to answer clarifying questions to refine it.
+
+**Use AskUserQuestion now with this question:**
+
+Header: "Questions?"
+Question: "I've drafted an initial plan. Would you like to answer a few clarifying questions so I can refine it?"
+Options:
+- "Yes, ask me questions" (description: "I'll interview you about technical details, constraints, and preferences, then update the plan")
+- "No, proceed as-is" (description: "Skip questions and proceed with the current plan")
+
+### If user chooses YES - Interview them about:
+
+1. **Technical Implementation**
+   - Preferred approaches or patterns?
+   - Technologies/libraries to use or avoid?
+   - Performance or scalability requirements?
+
+2. **Constraints & Requirements**
+   - Hard constraints that must be respected?
+   - Deadlines or scope limitations?
+   - Dependencies on other systems?
+
+3. **Edge Cases & Concerns**
+   - Known edge cases to handle?
+   - Security or privacy considerations?
+   - Error handling preferences?
+
+4. **Tradeoffs**
+   - Speed vs. quality preferences?
+   - Simplicity vs. flexibility?
+   - What's acceptable to defer to later?
+
+Ask focused, **non-obvious** questions using AskUserQuestion (max 12). Questions should surface hidden constraints, unstated assumptions, or preferences that aren't evident from the original request - things that would meaningfully change the plan.
+
+After gathering answers, **update the plan file** with the refined content before calling ExitPlanMode.
+
+### If user chooses NO:
+Proceed directly to ExitPlanMode with the current plan.
+""".strip()

package/dist/templates/_shared/scripts/save_handoff.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+"""Save a handoff document and set context status to handoff_pending.
+
+Usage:
+    python .aiwcli/_shared/scripts/save_handoff.py <context_id> <<'EOF'
+    # Your handoff markdown content here
+    EOF
+
+Or with a file:
+    python .aiwcli/_shared/scripts/save_handoff.py <context_id> < handoff.md
+
+This script:
+1. Reads handoff markdown content from stdin
+2. Saves it to _output/contexts/{context_id}/handoffs/HANDOFF-{HHMM}.md
+3. Sets in_flight.mode = "handoff_pending"
+4. Records the event in events.jsonl
+
+The handoff will be automatically picked up by the next session.
+"""
+import sys
+from datetime import datetime
+from pathlib import Path
+
+# Add parent directories to path for imports
+SCRIPT_DIR = Path(__file__).resolve().parent
+SHARED_ROOT = SCRIPT_DIR.parent
+sys.path.insert(0, str(SHARED_ROOT))
+
+from lib.context.context_manager import update_handoff_status, get_context
+from lib.base.utils import eprint, atomic_write
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: python save_handoff.py <context_id> < content.md", file=sys.stderr)
+        print("       python save_handoff.py <context_id> <<'EOF'", file=sys.stderr)
+        print("       ... markdown content ...", file=sys.stderr)
+        print("       EOF", file=sys.stderr)
+        sys.exit(1)
+
+    context_id = sys.argv[1]
+
+    # Read content from stdin
+    content = sys.stdin.read()
+    if not content.strip():
+        print("Error: No content provided via stdin", file=sys.stderr)
+        sys.exit(1)
+
+    # Project root is the parent of .aiwcli
+    project_root = SHARED_ROOT.parent.parent
+
+    # Verify context exists
+    context = get_context(context_id, project_root)
+    if not context:
+        print(f"Error: Context not found: {context_id}", file=sys.stderr)
+        sys.exit(1)
+
+    # Create handoffs directory
+    handoffs_dir = project_root / "_output" / "contexts" / context_id / "handoffs"
+    handoffs_dir.mkdir(parents=True, exist_ok=True)
+
+    # Generate filename with timestamp
+    timestamp = datetime.now().strftime("%H%M")
+    filename = f"HANDOFF-{timestamp}.md"
+    file_path = handoffs_dir / filename
+
+    # Handle filename collision (add suffix if file exists)
+    counter = 1
+    while file_path.exists():
+        filename = f"HANDOFF-{timestamp}-{counter}.md"
+        file_path = handoffs_dir / filename
+        counter += 1
+
+    # Save the handoff document
+    try:
+        success, error = atomic_write(file_path, content)
+        if not success:
+            print(f"Error: Failed to write handoff: {error}", file=sys.stderr)
+            sys.exit(1)
+    except Exception as e:
+        print(f"Error: Failed to write handoff: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    # Update context status
+    try:
+        update_handoff_status(context_id, str(file_path), project_root)
+    except Exception as e:
+        eprint(f"[save_handoff] Warning: Status update failed: {e}")
+        # Don't exit - file was saved successfully
+
+    # Output success message
+    print(f"✓ Saved handoff: {file_path}")
+    print(f"✓ Set status to handoff_pending for context: {context_id}")
+    print()
+    print("The next session will automatically offer to resume from this handoff.")
+
+
+if __name__ == "__main__":
+    main()