agentic-cli 0.3.3__tar.gz → 0.4.0__tar.gz

{agentic_cli-0.3.3 → agentic_cli-0.4.0}/.gitignore

@@ -41,7 +41,7 @@ Thumbs.db
 # Logs
 *.log
 
-CLAUDE.md
+#CLAUDE.md
 .claude/
 plans/
 docs/

{agentic_cli-0.3.3 → agentic_cli-0.4.0}/CHANGELOG.md

@@ -5,6 +5,36 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2026-02-07
+
+### Added
+
+- **Task Management System**: `save_tasks`/`get_tasks` tools backed by `TaskStore` with flat JSON and atomic writes (`src/agentic_cli/tools/task_tools.py`)
+- **Integration Tests**: Comprehensive ADK and LangGraph workflow pipeline tests (`tests/integration/`)
+- **PDF Text Extraction**: arXiv PDF extraction in `web_fetch` tool, arXiv specialist sub-agent
+- **Prompt Caching**: Claude model prompt caching and LLM usage tracking in LangGraph
+- **Graceful 429 Handling**: Rate limit detection with user retry prompt and configurable delay
+
+### Changed
+
+- **Simplified Memory**: 5 tools → 2 (`save_memory`/`search_memory`), following Claude Code pattern
+- **Simplified Planning**: 7 tools → 2 (`save_plan`/`get_plan`), backed by `PlanStore` (flat markdown)
+- **Simplified HITL**: 5 tools → 2 (`request_approval`/`create_checkpoint`), async/blocking via workflow manager
+- **Store Consolidation**: Merged store packages into corresponding tool files
+- **Tools Review**: Standardized error handling (`{"success": bool}` dicts), improved descriptions, removed deprecated `ToolCategory` values
+- **HITL Deadlock Fix**: Direct async callback instead of Future-based pattern for user input
+- **Choice Dialog**: Switched from horizontal buttons to vertical radio list (`dropdown_dialog`)
+- **Unified Tool Registration**: All 34 tools registered through consistent pattern
+- **ContextVar Fix**: Fixed reset bug, deduplicated `_workflow_context`, removed dead modules
+- **Task Progress Display**: Fixed stale display, auto-cleanup between messages, plan checkboxes from PlanStore
+- **Research Demo**: Updated with task tools, removed app-specific tools, fixed Gemini API compatibility
+
+### Fixed
+
+- `ask_clarification` deadlock when prompting user during workflow
+- Stale task progress display between messages
+- ContextVar reset bug in workflow context
+
 ## [0.3.3] - 2026-02-04
 
 ### Added

agentic_cli-0.4.0/CLAUDE.md

@@ -0,0 +1,151 @@
+# Agentic CLI - Shared Framework for Agentic Applications
+
+## Project Overview
+
+Agentic CLI is a shared library providing the core infrastructure for building domain-specific CLI applications powered by LLM agents.
+
+## Tech Stack
+
+- **Language**: Python 3.12+
+- **CLI UI**: `thinking_prompt` - enhanced CLI with thinking boxes and markdown
+- **Workflow**: Google ADK + LangGraph - dual orchestration backends (selectable via settings)
+- **Config**: `pydantic-settings` - type-safe configuration
+- **Logging**: `structlog` - structured logging
+
+## Project Structure
+
+```
+agentic-cli/
+├── src/agentic_cli/
+│   ├── __init__.py           # Package exports, lazy imports
+│   ├── config.py             # BaseSettings (pydantic-settings)
+│   ├── constants.py          # Shared constants, truncate()
+│   ├── resolvers.py          # ModelResolver, PathResolver
+│   ├── settings_persistence.py
+│   ├── logging.py
+│   ├── cli/
+│   │   ├── app.py            # BaseCLIApp
+│   │   ├── commands.py       # Command, CommandRegistry
+│   │   ├── builtin_commands.py
+│   │   ├── workflow_controller.py  # WorkflowController, factory
+│   │   ├── message_processor.py
+│   │   └── settings*.py      # Settings UI (introspection, dialog)
+│   ├── workflow/
+│   │   ├── base_manager.py   # BaseWorkflowManager (abstract)
+│   │   ├── adk_manager.py    # GoogleADKWorkflowManager
+│   │   ├── events.py         # WorkflowEvent, EventType
+│   │   ├── thinking.py       # ThinkingDetector
+│   │   ├── config.py         # AgentConfig
+│   │   ├── context.py        # ContextVars for tool access (get_context_*())
+│   │   ├── adk/              # ADK-specific (llm_event_logger)
+│   │   └── langgraph/        # LangGraph orchestrator
+│   │       ├── manager.py    # LangGraphWorkflowManager
+│   │       ├── state.py
+│   │       ├── persistence/  # Checkpointers, stores
+│   │       └── tools/        # LangChain-compatible wrappers
+│   ├── tools/
+│   │   ├── registry.py       # ToolRegistry, @register_tool, ToolCategory, PermissionLevel
+│   │   ├── executor.py       # SafePythonExecutor
+│   │   ├── standard.py       # search_knowledge_base, execute_python, ask_clarification
+│   │   ├── file_read.py      # read_file, diff_compare
+│   │   ├── file_write.py     # write_file, edit_file
+│   │   ├── glob_tool.py      # glob
+│   │   ├── grep_tool.py      # grep
+│   │   ├── search.py         # web_search (Tavily/Brave backends)
+│   │   ├── webfetch_tool.py  # web_fetch (orchestrator)
+│   │   ├── memory_tools.py   # save_memory, search_memory + MemoryStore
+│   │   ├── planning_tools.py # save_plan, get_plan + PlanStore
+│   │   ├── task_tools.py     # save_tasks, get_tasks + TaskStore
+│   │   ├── hitl_tools.py     # request_approval, create_checkpoint
+│   │   ├── shell/            # 8-layer shell security
+│   │   └── webfetch/         # Fetcher, converter, validator, robots
+│   ├── hitl/
+│   │   ├── config.py         # ApprovalRule, HITLConfig
+│   │   ├── approval.py       # ApprovalManager
+│   │   └── checkpoints.py    # CheckpointManager
+│   ├── knowledge_base/
+│   │   ├── models.py         # Document, SearchResult
+│   │   ├── embeddings.py     # EmbeddingService
+│   │   ├── vector_store.py   # VectorStore (FAISS)
+│   │   └── manager.py        # KnowledgeBaseManager
+│   └── persistence/
+│       ├── session.py        # SessionPersistence
+│       ├── artifacts.py      # ArtifactManager
+│       └── _utils.py         # Atomic write utilities
+├── tests/
+│   ├── conftest.py           # MockContext, MockVectorStore, MockEmbeddingService
+│   ├── test_*.py             # Unit tests
+│   ├── tools/                # Tool-specific tests
+│   └── integration/          # ADK & LangGraph pipeline tests
+└── examples/                 # Demo scripts
+```
+
+## Running Commands
+
+**IMPORTANT**: Always use `conda run -n agenticcli` prefix for running commands:
+
+```bash
+# Create the environment (first time only)
+conda env create -f environment.yml
+
+# Install package
+conda run -n agenticcli pip install -e .
+
+# Run tests
+conda run -n agenticcli python -m pytest tests/ -v
+
+# Run Python
+conda run -n agenticcli python -c "from agentic_cli import BaseCLIApp; print(BaseCLIApp)"
+```
+
+## Branching Strategy
+
+- **main**: Stable branch, matches latest release. Only updated via merges from `develop` when releasing.
+- **develop**: Integration branch for ongoing work. Small fixes can be committed directly here.
+- **feature/\***: Feature branches for larger changes. Branch from `develop`, merge back to `develop`.
+
+Workflow:
+1. For small fixes: commit directly to `develop`
+2. For features: create `feature/<name>` from `develop`, work there, merge back to `develop`
+3. When ready to release: merge `develop` → `main` and tag the release
+
+## Development Principles
+
+### Code Style
+- Follow PEP 8 style guidelines
+- Use type hints throughout
+- Prefer descriptive variable names
+
+### Key Design Decisions
+- **Abstract base classes**: BaseCLIApp and BaseWorkflowManager for domain extension
+- **Dual orchestrator**: ADK and LangGraph backends, selectable via settings
+- **Lazy initialization**: Defer heavy imports until needed
+- **Event-based streaming**: Real-time updates via AsyncGenerator
+- **UI-agnostic workflow**: WorkflowEvent objects can be consumed by any UI
+
+### Key Design Patterns
+- **Tool error handling**: All tools return `{"success": bool, ...}` dicts. Never raise `ToolError`.
+- **Tool registration**: Use `@register_tool(category=..., permission_level=..., description=...)` decorator. Tools are auto-discovered via the global `ToolRegistry`.
+- **Store consolidation**: Stores (MemoryStore, PlanStore, TaskStore) live inside their tool files (e.g. `memory_tools.py`), not in separate packages.
+- **Context access**: Tools use `get_context_*()` functions from `workflow.context` to access managers and stores via ContextVars.
+- **Atomic writes**: Use `atomic_write_json`/`atomic_write_text` from `persistence/_utils.py` for file persistence.
+
+### Console Output
+All console output must go through `ThinkingPromptSession` methods. Never use `rich.Console` or `print()` directly.
+
+Available session methods:
+- `session.add_response(text, markdown=True)` - Display text/markdown response
+- `session.add_rich(renderable)` - Display Rich renderables (Panel, Table, etc.)
+- `session.add_message(role, content)` - Add message to history
+- `session.add_error(content)` - Display error message
+- `session.add_warning(content)` - Display warning message
+- `session.add_success(content)` - Display success message
+- `session.clear()` - Clear the terminal screen
+
+## Testing
+
+- **Framework**: pytest with `asyncio_mode = "auto"`
+- **MockContext**: From `tests/conftest.py` — provides isolated settings and temp dirs for all tests
+- **MockVectorStore** and **MockEmbeddingService**: In-tree mocks for testing without ML dependencies
+- **FAISS tests**: Guard with `pytest.importorskip("faiss")` since FAISS is not installed in dev env
+- **Integration tests**: `tests/integration/` covers ADK and LangGraph pipeline tests

{agentic_cli-0.3.3 → agentic_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-cli
-Version: 0.3.3
+Version: 0.4.0
 Summary: A framework for building domain-specific agentic CLI applications
 Project-URL: Homepage, https://github.com/shoom1/agentic-cli
 Project-URL: Repository, https://github.com/shoom1/agentic-cli
@@ -21,6 +21,7 @@ Requires-Dist: numpy>=1.26.0
 Requires-Dist: prompt-toolkit>=3.0.0
 Requires-Dist: pydantic-settings>=2.0.0
 Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pypdf>=4.0.0
 Requires-Dist: rich>=13.0.0
 Requires-Dist: structlog>=24.0.0
 Requires-Dist: thinking-prompt>=0.2.0
@@ -572,21 +573,23 @@ async for event in manager.process(message, user_id="user1"):
 
 ### Task Progress Display
 
-When using a task graph for planning, the CLI thinking box dynamically shows task progress:
+When using plan checkboxes or task tools, the CLI thinking box dynamically shows task progress:
 
 ```
-Calling: search_web
-─── Tasks: 2/5 ───
-◐ Researching topic
-☐ Analyzing results
-☐ Writing summary
+Calling: web_search
+--- Tasks: 1/3 ---
+Research:
+  [x] Gather data
+  [ ] Analyze results
+Writing:
+  [ ] Draft report
 ```
 
-Status icons:
-- `◐` In progress
-- `☐` Pending
-- `✓` Completed
-- `✗` Failed
+Status icons (task tools):
+- `[x]` Completed
+- `[>]` In progress
+- `[ ]` Pending
+- `[-]` Cancelled
 
 ## Examples
 
@@ -648,20 +651,27 @@ agentic-cli/
 ├── src/agentic_cli/
 │   ├── __init__.py           # Package exports
 │   ├── config.py             # BaseSettings, SettingsContext
+│   ├── constants.py          # Shared constants (truncation, limits)
+│   ├── logging.py            # Structlog configuration
 │   ├── cli/
 │   │   ├── app.py            # BaseCLIApp
 │   │   ├── commands.py       # Command, CommandRegistry
+│   │   ├── builtin_commands.py
 │   │   ├── workflow_controller.py  # Workflow orchestration
 │   │   └── message_processor.py    # Event stream processing
 │   ├── workflow/
+│   │   ├── base_manager.py   # BaseWorkflowManager (abstract)
 │   │   ├── events.py         # WorkflowEvent, EventType
 │   │   ├── config.py         # AgentConfig
+│   │   ├── context.py        # Context variables for tools
+│   │   ├── thinking.py       # ThinkingDetector
 │   │   ├── adk_manager.py    # GoogleADKWorkflowManager
 │   │   └── langgraph/        # LangGraph submodule
 │   │       ├── manager.py    # LangGraphWorkflowManager
 │   │       ├── state.py      # AgentState, CheckpointData
 │   │       └── persistence/  # Checkpointers and stores
 │   ├── tools/
+│   │   ├── registry.py       # ToolRegistry, ToolCategory, PermissionLevel
 │   │   ├── executor.py       # SafePythonExecutor
 │   │   ├── file_read.py      # read_file, diff_compare
 │   │   ├── file_write.py     # write_file, edit_file
@@ -669,14 +679,31 @@ agentic-cli/
 │   │   ├── glob_tool.py      # glob, list_dir (file discovery)
 │   │   ├── search.py         # Web search (Tavily, Brave)
 │   │   ├── webfetch_tool.py  # Web content fetching
+│   │   ├── memory_tools.py   # MemoryStore, save/search_memory
+│   │   ├── planning_tools.py # PlanStore, save/get_plan
+│   │   ├── task_tools.py     # TaskStore, save/get_tasks
+│   │   ├── hitl_tools.py     # request_approval, create_checkpoint
+│   │   ├── standard.py       # ArXiv tools, ask_clarification
 │   │   └── shell/            # Shell executor with security
 │   │       ├── executor.py   # Main entry point (disabled by default)
 │   │       ├── tokenizer.py  # Command parsing
 │   │       ├── classifier.py # Risk classification
 │   │       ├── sandbox.py    # Execution sandboxing
 │   │       └── audit.py      # Security logging
-│   └── knowledge_base/
-│       └── manager.py        # KnowledgeBaseManager
+│   ├── knowledge_base/
+│   │   ├── manager.py        # KnowledgeBaseManager
+│   │   ├── models.py         # Document, SearchResult
+│   │   ├── embeddings.py     # EmbeddingService
+│   │   ├── vector_store.py   # VectorStore
+│   │   └── sources.py        # ArxivSearchSource, SearchSourceRegistry
+│   ├── persistence/
+│   │   ├── session.py        # SessionPersistence
+│   │   ├── artifacts.py      # ArtifactManager
+│   │   └── _utils.py         # Atomic write utilities
+│   └── hitl/
+│       ├── approval.py       # ApprovalManager
+│       ├── checkpoints.py    # CheckpointManager
+│       └── config.py         # HITLConfig
 ├── examples/
 │   ├── hello_agent.py        # Basic ADK example
 │   ├── hello_langgraph.py    # Basic LangGraph example

{agentic_cli-0.3.3 → agentic_cli-0.4.0}/README.md

@@ -533,21 +533,23 @@ async for event in manager.process(message, user_id="user1"):
 
 ### Task Progress Display
 
-When using a task graph for planning, the CLI thinking box dynamically shows task progress:
+When using plan checkboxes or task tools, the CLI thinking box dynamically shows task progress:
 
 ```
-Calling: search_web
-─── Tasks: 2/5 ───
-◐ Researching topic
-☐ Analyzing results
-☐ Writing summary
+Calling: web_search
+--- Tasks: 1/3 ---
+Research:
+  [x] Gather data
+  [ ] Analyze results
+Writing:
+  [ ] Draft report
 ```
 
-Status icons:
-- `◐` In progress
-- `☐` Pending
-- `✓` Completed
-- `✗` Failed
+Status icons (task tools):
+- `[x]` Completed
+- `[>]` In progress
+- `[ ]` Pending
+- `[-]` Cancelled
 
 ## Examples
 
@@ -609,20 +611,27 @@ agentic-cli/
 ├── src/agentic_cli/
 │   ├── __init__.py           # Package exports
 │   ├── config.py             # BaseSettings, SettingsContext
+│   ├── constants.py          # Shared constants (truncation, limits)
+│   ├── logging.py            # Structlog configuration
 │   ├── cli/
 │   │   ├── app.py            # BaseCLIApp
 │   │   ├── commands.py       # Command, CommandRegistry
+│   │   ├── builtin_commands.py
 │   │   ├── workflow_controller.py  # Workflow orchestration
 │   │   └── message_processor.py    # Event stream processing
 │   ├── workflow/
+│   │   ├── base_manager.py   # BaseWorkflowManager (abstract)
 │   │   ├── events.py         # WorkflowEvent, EventType
 │   │   ├── config.py         # AgentConfig
+│   │   ├── context.py        # Context variables for tools
+│   │   ├── thinking.py       # ThinkingDetector
 │   │   ├── adk_manager.py    # GoogleADKWorkflowManager
 │   │   └── langgraph/        # LangGraph submodule
 │   │       ├── manager.py    # LangGraphWorkflowManager
 │   │       ├── state.py      # AgentState, CheckpointData
 │   │       └── persistence/  # Checkpointers and stores
 │   ├── tools/
+│   │   ├── registry.py       # ToolRegistry, ToolCategory, PermissionLevel
 │   │   ├── executor.py       # SafePythonExecutor
 │   │   ├── file_read.py      # read_file, diff_compare
 │   │   ├── file_write.py     # write_file, edit_file
@@ -630,14 +639,31 @@ agentic-cli/
 │   │   ├── glob_tool.py      # glob, list_dir (file discovery)
 │   │   ├── search.py         # Web search (Tavily, Brave)
 │   │   ├── webfetch_tool.py  # Web content fetching
+│   │   ├── memory_tools.py   # MemoryStore, save/search_memory
+│   │   ├── planning_tools.py # PlanStore, save/get_plan
+│   │   ├── task_tools.py     # TaskStore, save/get_tasks
+│   │   ├── hitl_tools.py     # request_approval, create_checkpoint
+│   │   ├── standard.py       # ArXiv tools, ask_clarification
 │   │   └── shell/            # Shell executor with security
 │   │       ├── executor.py   # Main entry point (disabled by default)
 │   │       ├── tokenizer.py  # Command parsing
 │   │       ├── classifier.py # Risk classification
 │   │       ├── sandbox.py    # Execution sandboxing
 │   │       └── audit.py      # Security logging
-│   └── knowledge_base/
-│       └── manager.py        # KnowledgeBaseManager
+│   ├── knowledge_base/
+│   │   ├── manager.py        # KnowledgeBaseManager
+│   │   ├── models.py         # Document, SearchResult
+│   │   ├── embeddings.py     # EmbeddingService
+│   │   ├── vector_store.py   # VectorStore
+│   │   └── sources.py        # ArxivSearchSource, SearchSourceRegistry
+│   ├── persistence/
+│   │   ├── session.py        # SessionPersistence
+│   │   ├── artifacts.py      # ArtifactManager
+│   │   └── _utils.py         # Atomic write utilities
+│   └── hitl/
+│       ├── approval.py       # ApprovalManager
+│       ├── checkpoints.py    # CheckpointManager
+│       └── config.py         # HITLConfig
 ├── examples/
 │   ├── hello_agent.py        # Basic ADK example
 │   ├── hello_langgraph.py    # Basic LangGraph example

{agentic_cli-0.3.3 → agentic_cli-0.4.0}/environment.yml

@@ -7,5 +7,6 @@ dependencies:
   - pip
   - html2text
   - pip:
+    - pypdf>=4.0.0
     - -e .
     - -e .[dev]

agentic_cli-0.4.0/examples/memory_demo.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python
+"""Standalone demo for the simplified memory system.
+
+Demonstrates:
+1. Storing memories with optional tags
+2. Searching memories by substring
+3. Loading all memories for system prompt injection
+4. Persistence across instances
+
+Usage:
+    conda run -n agenticcli python examples/memory_demo.py
+"""
+
+import tempfile
+from pathlib import Path
+
+from agentic_cli.tools.memory_tools import MemoryStore, MemoryItem
+from agentic_cli.config import BaseSettings
+
+
+class DemoSettings(BaseSettings):
+    """Settings for demo with temp directory."""
+
+    workspace_dir: Path = Path(".")
+
+    def __init__(self, temp_dir: Path, **kwargs):
+        super().__init__(workspace_dir=temp_dir, **kwargs)
+
+
+def main():
+    print("\n" + "#" * 60)
+    print("#  Memory System Demo (Simplified)")
+    print("#" * 60)
+
+    with tempfile.TemporaryDirectory() as temp_dir:
+        temp_path = Path(temp_dir)
+        settings = DemoSettings(temp_path)
+
+        # --- Store memories ---
+        print("\n  Storing memories:")
+        store = MemoryStore(settings)
+
+        id1 = store.store("User prefers markdown output", tags=["preference"])
+        print(f"    Stored: {id1[:8]}... [preference]")
+
+        id2 = store.store("Basel III requires 99% VaR confidence", tags=["fact", "finance"])
+        print(f"    Stored: {id2[:8]}... [fact, finance]")
+
+        id3 = store.store("Python 3.12 is the project runtime")
+        print(f"    Stored: {id3[:8]}... (no tags)")
+
+        # --- Search ---
+        print("\n  Search for 'Basel':")
+        for item in store.search("Basel"):
+            print(f"    - {item.content}")
+
+        print("\n  Search for 'Python':")
+        for item in store.search("Python"):
+            print(f"    - {item.content}")
+
+        # --- Load all (system prompt injection) ---
+        print("\n  All memories (for system prompt):")
+        print(store.load_all())
+
+        # --- Persistence ---
+        print("\n  Persistence test:")
+        store2 = MemoryStore(settings)
+        results = store2.search("")
+        print(f"    New instance loaded {len(results)} memories")
+        assert len(results) == 3
+
+    print("\n" + "#" * 60)
+    print("#  Demo Complete!")
+    print("#" * 60 + "\n")
+
+
+if __name__ == "__main__":
+    main()

agentic_cli-0.4.0/examples/planning_demo.py

@@ -0,0 +1,149 @@
+#!/usr/bin/env python
+"""Standalone demo for the PlanStore planning system.
+
+This demo shows the simplified flat-markdown planning pattern:
+1. Agent creates a plan with markdown checkboxes
+2. Agent updates the plan as tasks complete
+3. Framework just stores the string
+
+Usage:
+    conda run -n agenticcli python examples/planning_demo.py
+"""
+
+from agentic_cli.tools.planning_tools import PlanStore
+
+
+def demo_basic_plan():
+    """Demo creating and retrieving a plan."""
+    print("\n" + "=" * 60)
+    print("Basic Plan Demo")
+    print("=" * 60)
+
+    store = PlanStore()
+
+    # Agent creates a plan
+    plan = (
+        "## Research Plan: Python History\n"
+        "\n"
+        "- [ ] Search for key milestones in Python development\n"
+        "- [ ] Identify major version releases and their features\n"
+        "- [ ] Find notable Python community events\n"
+        "- [ ] Write summary document\n"
+    )
+    store.save(plan)
+
+    print("  Created plan:")
+    print(store.get())
+    print()
+
+
+def demo_progress_tracking():
+    """Demo updating plan with progress."""
+    print("\n" + "=" * 60)
+    print("Progress Tracking Demo")
+    print("=" * 60)
+
+    store = PlanStore()
+
+    # Initial plan
+    store.save(
+        "## ML Pipeline\n"
+        "- [ ] Prepare dataset\n"
+        "- [ ] Train model\n"
+        "- [ ] Evaluate performance\n"
+        "- [ ] Deploy to production\n"
+    )
+    print("  Initial plan:")
+    print(store.get())
+
+    # Agent completes first two tasks
+    store.save(
+        "## ML Pipeline\n"
+        "- [x] Prepare dataset\n"
+        "- [x] Train model (accuracy: 94.2%)\n"
+        "- [ ] Evaluate performance\n"
+        "- [ ] Deploy to production\n"
+    )
+    print("\n  After completing 2 tasks:")
+    print(store.get())
+
+    # Agent adds notes and completes more
+    store.save(
+        "## ML Pipeline\n"
+        "- [x] Prepare dataset\n"
+        "- [x] Train model (accuracy: 94.2%)\n"
+        "- [x] Evaluate performance\n"
+        "  - Precision: 0.93, Recall: 0.95\n"
+        "  - Exceeds baseline by 12%\n"
+        "- [ ] Deploy to production\n"
+    )
+    print("\n  After evaluation with notes:")
+    print(store.get())
+    print()
+
+
+def demo_plan_revision():
+    """Demo revising a plan mid-execution."""
+    print("\n" + "=" * 60)
+    print("Plan Revision Demo")
+    print("=" * 60)
+
+    store = PlanStore()
+
+    # Original plan
+    store.save(
+        "## API Integration\n"
+        "- [x] Design API schema\n"
+        "- [ ] Implement endpoints\n"
+        "- [ ] Write tests\n"
+    )
+    print("  Original plan:")
+    print(store.get())
+
+    # Agent discovers need for auth — revises plan
+    store.save(
+        "## API Integration\n"
+        "- [x] Design API schema\n"
+        "- [x] Implement endpoints\n"
+        "- [ ] Add authentication (discovered requirement)\n"
+        "- [ ] Write tests\n"
+        "- [ ] Update documentation\n"
+    )
+    print("\n  Revised plan (added auth + docs):")
+    print(store.get())
+    print()
+
+
+def demo_clear():
+    """Demo clearing the plan."""
+    print("\n" + "=" * 60)
+    print("Clear Plan Demo")
+    print("=" * 60)
+
+    store = PlanStore()
+    store.save("- [ ] Some task")
+    print(f"  Has plan: {not store.is_empty()}")
+
+    store.clear()
+    print(f"  After clear, is empty: {store.is_empty()}")
+    print()
+
+
+def main():
+    """Run all demos."""
+    print("\n" + "#" * 60)
+    print("#  PlanStore Planning System Demo")
+    print("#" * 60)
+
+    demo_basic_plan()
+    demo_progress_tracking()
+    demo_plan_revision()
+    demo_clear()
+
+    print("\n" + "#" * 60)
+    print("#  Demo Complete!")
+    print("#" * 60 + "\n")
+
+
+if __name__ == "__main__":
+    main()