Topic Manager v2 Skill

Version: 2.0.0
Author: OpenClaw
Type: Context Management
Dependencies: python3, jq

Overview

The Topic Manager v2 skill provides context isolation and topic switching to prevent context rot. It distinguishes between simple topics (lightweight Q&A/discussions) and projects (multi-iteration work that spawn War Rooms).

Features

✅ Context Isolation - Zero context pollution between topics
✅ Simple Topics - Lightweight discussions and Q&A
✅ Projects - Multi-iteration work with War Room integration
✅ Memory Management - Current status + historical archives
✅ Topic Switching - Clean context transitions
✅ Telegram Integration - Full /topic command suite
✅ War Room Integration - Automatic War Room spawning for projects

Philosophy

• Prevent context rot through topic isolation
• Simple vs Projects: Different tools for different needs
• Memory hierarchy: Current status (always loaded) vs archives (loaded on demand)
• Fast switching: Minimal context loading for rapid topic changes

Data Structure

JSON State (topics/topics.json)

{
  "active": "topic-name",
  "topics": {
    "simple-topic": {
      "type": "simple",
      "created": "2024-01-15T10:30:00Z",
      "status": "in-progress",
      "notes": ["Initial discussion about feature X", "Need to research API options"]
    },
    "project-name": {
      "type": "project",
      "created": "2024-01-15T09:00:00Z",
      "status": "planning",
      "notes": ["Project kickoff", "Requirements gathering"],
      "warRoomId": "war-room-001",
      "projectDir": "projects/project-name/",
      "repos": ["https://github.com/user/repo"],
      "sessions": ["session-001", "session-002"]
    }
  }
}

Memory Structure

• memory/topic-{name}.md — Current status (always loaded on switch)
• memory/topic-{name}-session-{timestamp}.md — Historical archives

Commands

Core Operations

# Create simple topic
./handler.py new simple-discussion

# Create project (spawns War Room)
./handler.py project api-redesign

# Switch topics (archives current, loads target)
./handler.py switch simple-discussion

# List all topics
./handler.py list

# Show status (current or named)
./handler.py status [topic-name]

# Add note to active topic
./handler.py note "Updated the requirements"

# Convert simple topic to project
./handler.py promote simple-discussion

# Close topic (archive)
./handler.py close simple-discussion

# Delete topic (archive first)
./handler.py delete simple-discussion

Telegram Integration

/topic new <name>          # Create simple topic
/topic project <name>      # Create project + War Room
/topic switch <name>       # Switch active topic
/topic list                # Show all topics
/topic status [name]       # Show details
/topic note <text>         # Add note
/topic promote <name>      # Simple → Project
/topic close <name>        # Mark complete
/topic delete <name>       # Remove

Topic Switching Process

When switching topics, the system:

1. Archive Current Topic

   • Summarize recent work (decisions, blockers, next steps)
   • Update memory/topic-{current}.md
   • Create memory/topic-{current}-session-{timestamp}.md
   • Clear working context

2. Load Target Topic

   • Load memory/topic-{target}.md (current status)
   • Set as active topic
   • Ready for work with clean context

War Room Integration

For project topics:

• Automatic War Room creation on topic project <name>
• War Room sessions tracked in sessions array
• Project directory created at projects/<name>/
• Git repos can be associated

Installation

# Install the skill
cp -r skills/topic-manager-v2 skills/topic-manager-v2

# Make handler executable
chmod +x skills/topic-manager-v2/handler.py

# Initialize directory structure
./skills/topic-manager-v2/handler.py init

Configuration

Gateway Integration

Add to your gateway configuration:

{
  "commands": {
    "topic": {
      "command": ["python3", "skills/topic-manager-v2/handler.py"],
      "description": "Topic management",
      "telegram": true
    }
  }
}

Telegram Commands

All /topic commands are automatically routed to the handler.

Best Practices

Topic Creation

• Use descriptive names (kebab-case)
• Start with simple topics for exploration
• Promote to projects when multi-session work begins

Memory Management

• Keep status files concise (current state only)
• Historical sessions preserve full context
• Regular topic switching keeps context clean

Project Management

• Use projects for deliverables requiring multiple sessions
• Link relevant git repositories
• Track War Room sessions for historical reference

Error Handling

The system handles:

• Missing topics gracefully
• Invalid JSON recovery
• Directory creation
• Context switching failures

Development

Testing

# Run tests
python3 -m pytest tests/

# Test topic creation
./handler.py new test-topic
./handler.py status test-topic

Schema Validation

The JSON state is validated against config/schema.json on every operation.

Migration from v1

If upgrading from the directory-based v1 system:

# Backup existing topics
cp -r topics topics-v1-backup

# Initialize new system
./handler.py init

# Manual migration (topic by topic)
# Extract information from old META.md files

Troubleshooting

Common Issues

"No active topic"

• Create a topic first: ./handler.py new my-first-topic
• Switch to existing topic: ./handler.py switch topic-name

"JSON parse error"

• Backup and reinitialize: cp topics/topics.json topics.json.bak && ./handler.py init

"Memory file not found"

• Normal for new topics - status file created on first switch

Debug Mode

# Run with debug output
DEBUG=1 ./handler.py status

Performance

• Fast topic switching (< 100ms)
• Minimal memory footprint
• JSON operations optimized for frequent access
• Memory files loaded on-demand only

Running Tests

The Topic Manager v2 includes a comprehensive test suite covering all functionality, edge cases, and error handling.

Local Testing

# Run full test suite (self-contained)
cd skills/topic-manager-v2
python3 test.py

# Run with help
python3 test.py --help

Test Coverage:

• ✅ All 9 commands (init, new, project, switch, list, status, note, promote, close, delete)
• ✅ Edge cases (special characters, long names, boundary conditions)
• ✅ Error handling (invalid commands, non-existent topics)
• ✅ JSON state persistence
• ✅ Memory file creation and archiving
• ✅ Performance validation (< 5 second execution)

GitHub Actions CI/CD

Automated testing runs on every push to main and PRs:

# .github/workflows/test.yml
- Triggers: push to main, pull requests
- Python versions: 3.11, 3.12
- Platforms: Ubuntu latest
- Timeout: 10 minutes max
- Validation: test coverage, code quality, documentation

CI Pipeline:

1. Test Suite - Run comprehensive tests
2. Code Quality - Syntax validation, executable permissions
3. Documentation - Validate required sections exist
4. Integration - Direct handler.py testing
5. Performance - Ensure fast execution

Test Requirements

• Self-contained: No external dependencies
• Fast execution: Complete in < 5 seconds
• Clear output: Pass/fail with detailed reporting
• Isolated: Uses temporary directories
• Comprehensive: 80%+ functional coverage

Adding New Tests

When adding new functionality:

1. Add test method to test.py following naming convention test_<feature>
2. Test edge cases - invalid inputs, boundary conditions
3. Verify state - JSON persistence, file creation
4. Test errors - proper error handling and messages
5. Update CI if new dependencies or validation needed

Future Enhancements

• [ ] Topic templates
• [ ] Batch operations
• [ ] Search across topics
• [ ] Export/import functionality
• [ ] Integration with calendar/reminders