🔄 Project Context & Architecture

Always read
PLANNING.md
at the start of new conversations to understand WitsV3's LLM wrapper architecture and goals
Check
TASK.md
before starting work. Add tasks if not listed with date
WitsV3 is an LLM orchestration system with CLI-first approach, ReAct pattern, and tool registry
Core components: agents/, core/, tools/ - maintain this structure

🐍 Python & Async Best Practices

Use Python 3.10+ with type hints throughout
All agent/tool methods must be async - WitsV3 is fully async
Follow PEP8 and format with black
Use Pydantic models for data validation (already in core/schemas.py)
Import style: Use relative imports within packages, absolute for cross-package

🧱 Code Structure & Modularity

Max 500 lines per file - split into modules when approaching limit
Maintain existing structure:
- ```
agents/
```
  - Agent implementations (BaseAgent, Orchestrators, Control Center)
- ```
core/
```
  - Core functionality (config, LLM interface, memory, schemas)
- ```
tools/
```
  - Tool implementations extending BaseTool
New tools go in tools/ and must extend BaseTool
New agents go in agents/ and must extend BaseAgent

🧪 Testing Requirements

Create pytest tests for all new features in
```
/tests
```
mirroring structure
Test async functions with pytest-asyncio
Mock external services (Ollama, file system) in tests
Minimum coverage per feature:
- Happy path test
- Error handling test
- Edge case test
Run existing test functions at bottom of modules when updating

✅ Task Management

Update TASK.md after completing tasks
Add discovered work to TASK.md under "Discovered During Work"
Log progress in task descriptions with dates
When committing, summarize the actual changes (e.g., "Remove historical scripts and ignore log directory")
Follow repository guidelines for commit style and include details in the PR description

📚 WitsV3-Specific Conventions

StreamData for agent communication - use stream_thinking(), stream_action(), etc.
Tool Registry pattern - all tools must register with get_llm_description()
Memory Manager integration - use store_memory() and search_memory() in agents
Config-driven - use WitsV3Config for all settings
Logging pattern: Use self.logger in all classes

🧠 LLM Integration Rules

Ollama is primary LLM - ensure compatibility
Support streaming responses via AsyncGenerator
Parse LLM responses robustly using ResponseParser
Handle tool calls through proper ToolCall/ToolResult schemas

📝 Documentation Standards

Update README.md when adding features or changing setup

Google-style docstrings for all functions:

async def method_name(self, param: str) -> StreamData:
    """
    Brief description of method.

    Args:
        param: Description of parameter

    Yields:
        StreamData objects for streaming responses
    """

Comment non-obvious logic with # Reason: explanations

⚠️ Critical WitsV3 Rules

Never break async patterns - all I/O operations must be async
Preserve ReAct loop in orchestrators (Reason-Act-Observe)
Maintain backward compatibility with existing tools/agents
Test with Ollama running - many features require active Ollama connection
Unicode handling is important - project emphasizes clean text output
Memory persistence - ensure MemorySegment serialization works

🚫 Don't Do

Don't use synchronous I/O operations
Don't create circular imports between packages
Don't modify core schemas without updating all dependent code
Don't hardcode configuration values - use config.yaml
Don't forget to handle LLM connection failures gracefully

async def method_name(self, param: str) -> StreamData:
    """
    Brief description of method.

    Args:
        param: Description of parameter

    Yields:
        StreamData objects for streaming responses
    """

🔄 Project Context & Architecture

🔄 Project Context & Architecture

🐍 Python & Async Best Practices

🧱 Code Structure & Modularity

🧪 Testing Requirements

✅ Task Management

📚 WitsV3-Specific Conventions

🧠 LLM Integration Rules

📝 Documentation Standards

⚠️ Critical WitsV3 Rules

🚫 Don't Do

Related Skills

Repo rules

.cursorrules

This is an Elixir library that recompiles Elixir code in its AST form.

🔄 Project Context & Architecture

🐍 Python & Async Best Practices

🧱 Code Structure & Modularity

🧪 Testing Requirements

✅ Task Management

📚 WitsV3-Specific Conventions

🧠 LLM Integration Rules

📝 Documentation Standards

⚠️ Critical WitsV3 Rules

🚫 Don't Do