Jean Claude Development Guide

Overview

This skill provides guidance for developing Jean Claude itself - the AI-driven workflow orchestration framework. It captures institutional knowledge, testing patterns, common pitfalls, and active experiments that evolve as the project grows.

When to use this skill:

• Making changes to src/jean_claude/ source code
• Writing or updating tests in tests/
• Modifying architecture or core patterns
• Working on new features or experiments
• Conducting retrospectives after development sessions

Do NOT use when:

• Users are simply using jc CLI commands
• Working on user-facing documentation only
• Answering general questions about Jean Claude usage

Current Architecture Focus

Active Areas (as of 2026-01-04):

• Agent note-taking system (branch: claude/agent-note-taking-system-Ly16E)
• Event-sourced architecture with SQLite event store
• Mailbox communication between agents and coordinator
• Dashboard memory leak fixes (SSE streaming)
• Version 0.9.0 release cycle

Core Architectural Patterns:

1. Two-Agent Workflow - Opus (planning) + Sonnet (implementation)
2. Event Sourcing - SQLite as single source of truth
3. Coordinator Pattern - Agent-to-human escalation via ntfy.sh
4. Git Worktree Isolation - Separate filesystems per workflow
5. Mailbox Communication - Async agent-to-agent messaging

Critical Files:

• src/jean_claude/orchestration/two_agent.py - Two-agent pattern implementation
• src/jean_claude/core/state.py - WorkflowState persistence
• src/jean_claude/core/event_store.py - Event logging to SQLite
• src/jean_claude/core/sdk_executor.py - Claude Agent SDK wrapper
• src/jean_claude/tools/mailbox_tools.py - Agent communication tools

Testing Patterns

Core Principle: Test OUR Code, Not External Dependencies

What to Mock:

• ✅ Beads CLI (bd commands) - external tool
• ✅ Claude Agent SDK responses
• ✅ Subprocess calls (subprocess.run)
• ✅ File system operations (when appropriate)

What NOT to Mock:

• ❌ Pydantic validation - test real models
• ❌ Click command parsing - trust the framework
• ❌ Our own business logic - test real implementations

Critical Mock Patching Rule

Always patch where an object is USED, not where it's DEFINED.

# If edit_and_revalidate.py imports:
# from jean_claude.core.beads import fetch_beads_task

# ✅ CORRECT - patch in the importing module
@patch('jean_claude.core.edit_and_revalidate.fetch_beads_task')
def test_something(mock_fetch):
    pass

# ❌ WRONG - patching in source module won't work
@patch('jean_claude.core.beads.fetch_beads_task')
def test_something(mock_fetch):
    pass

Fixture Hierarchy

Three-tier structure:

1. tests/conftest.py - Root fixtures (cli_runner, mock_beads_task, work_command_mocks)
2. tests/core/conftest.py - Core module fixtures (sample_beads_task, subprocess mocks)
3. tests/orchestration/conftest.py - Workflow fixtures (workflow_state, execution_result)

Before creating a new fixture:

# Search existing fixtures
grep -r "@pytest.fixture" tests/conftest.py tests/*/conftest.py

Mock Patterns

# ✅ GOOD - Use @patch decorators (bottom-up order)
@patch('module.function_c')
@patch('module.function_b')
@patch('module.function_a')
def test_thing(mock_a, mock_b, mock_c):
    pass

# ❌ BAD - Nested with patch() blocks
def test_thing():
    with patch('a'):
        with patch('b'):
            pass  # DON'T NEST

# ✅ GOOD - Use AsyncMock for async functions
@patch('module.async_function', new_callable=AsyncMock)
def test_async(mock_async):
    pass

# ❌ BAD - Regular Mock for async functions
@patch('module.async_function')  # Will cause errors
def test_async(mock_async):
    pass

Test Organization

File Mapping:

• src/jean_claude/core/foo.py → tests/core/test_foo.py
• src/jean_claude/cli/commands/bar.py → tests/test_bar.py

Test Consolidation: Prefer comprehensive tests over many narrow tests:

# ✅ GOOD - Comprehensive test
@pytest.mark.parametrize("priority", [MessagePriority.LOW, MessagePriority.NORMAL, MessagePriority.URGENT])
def test_read_messages_all_priorities(priority):
    # Single test covering all priority levels
    pass

# ❌ BAD - Separate test per priority
def test_read_low_priority(): pass
def test_read_normal_priority(): pass
def test_read_urgent_priority(): pass

Running Tests

# All tests (parallel, 4 workers)
uv run pytest

# Specific module
uv run pytest tests/core/test_state.py

# Filter by name
uv run pytest -k "mailbox"

# With coverage
uv run pytest --cov=jean_claude

# Single-threaded (for debugging)
uv run pytest -n 0

Common Pitfalls

1. AsyncMock vs Mock

Problem: Using regular Mock for async functions causes errors. Solution: Always use new_callable=AsyncMock for async functions.

2. Patch Location

Problem: Patching where defined instead of where used. Solution: Patch in the module that imports the function, not the source module.

3. Fixture Duplication

Problem: Creating fixtures that already exist in conftest.py files. Solution: Search all conftest.py files before creating new fixtures.

4. Testing External Tools

Problem: Testing Beads/SDK behavior instead of our integration. Solution: Mock external tools and test only our wrapper code.

5. Nested Mocking

Problem: Using nested with patch() blocks instead of decorators. Solution: Use @patch decorators in bottom-up order.

6. Parallel Test State

Problem: Tests failing intermittently due to shared state. Solution: Avoid shared state; use temporary directories and unique identifiers.

7. ABOUTME Comments

Problem: Forgetting to add ABOUTME comments to new files. Solution: Every file needs 2-line ABOUTME comment at the top.

Active Experiments

Agent Note-Taking System

Status: In development (branch: claude/agent-note-taking-system-Ly16E) Purpose: Allow agents to take notes during execution that other agents can read Key Files:

• src/jean_claude/core/notes.py
• src/jean_claude/core/notes_api.py
• src/jean_claude/tools/notes_tools.py

Design Questions:

• How should notes be categorized? (OBSERVATION, LEARNING, DECISION)
• Should notes persist across workflows or be workflow-specific?
• How do we prevent note bloat?

Dashboard Memory Optimization

Status: Recently fixed (v0.9.0) Problem: SSE streaming endpoint had memory leaks Solution: Proper cleanup of background tasks and event listeners Lesson: Always test long-running streams for memory leaks

Skill-Based Documentation

Status: Experimenting (this skill!) Purpose: Capture project-specific knowledge in skills vs CLAUDE.md Hypothesis: Living skills updated via /retrospective will maintain better context than static docs

Retrospective Insights

Session: 2026-01-04 - Dashboard Memory Leak Fix

What we learned:

• SSE streaming requires careful cleanup of background tasks
• Memory leaks manifest slowly in long-running processes
• Dashboard testing should include stress tests

Code patterns discovered:

# ✅ GOOD - Proper SSE cleanup
async def event_stream():
    try:
        async for event in event_source:
            yield event
    finally:
        await event_source.cleanup()

Session: Testing Pattern Consolidation

What we learned:

• Mock patching location matters more than we thought
• Fixture hierarchy prevents duplication but requires discovery
• Comprehensive tests > many narrow tests

Changes made:

• Added fixture search guidance to CLAUDE.md
• Consolidated duplicate test fixtures
• Documented patch location rule

Development Workflows

Adding a New CLI Command

1. Create command module: src/jean_claude/cli/commands/my_command.py
2. Define Click command:

   import click
   
   @click.command()
   @click.argument('arg_name')
   def my_command(arg_name: str):
       """Brief description."""
       pass
   

3. Register in main.py: Add to cli.add_command(my_command)
4. Write tests: tests/test_my_command.py using cli_runner fixture
5. Update CLAUDE.md: Add to Quick Reference table

Adding a New Agent Tool

1. Define tool in: src/jean_claude/tools/my_tools.py
2. Follow MCP tool pattern:

   @server.tool()
   def my_tool(param: str) -> str:
       """Tool description."""
       return result
   

3. Register in SDK executor: Update get_mcp_servers() in sdk_executor.py
4. Write tests: Mock the tool execution, test integration
5. Update skill: Add tool documentation to jean-claude-cli skill

Updating Event Store Schema

1. Review: src/jean_claude/core/event_store.py
2. Add new event type: Update EventType enum
3. Update schema: Modify initialize_event_store() if needed
4. Migration: Consider if existing events need migration
5. Test: Add tests in tests/core/test_event_store.py

Working with Beads Integration

1. Beads models: src/jean_claude/core/beads.py
2. Mock in tests: Use mock_beads_task or sample_beads_task fixtures
3. Spec generation: Specs auto-created in specs/beads-{task_id}.md
4. State linking: WorkflowState includes beads_task_id field

Resources

This skill includes:

references/

• testing_patterns.md - Detailed testing examples and fixture catalog
• retrospectives/ - Session-by-session learnings (created via /retrospective)

scripts/

• retrospective_helper.py - Analyzes recent commits to suggest skill updates

Note: Assets directory not needed for this skill and has been removed.

Updating This Skill

This skill should evolve as Jean Claude develops. To update:

1. Use /retrospective command - Reflect on recent work and update skill
2. Manual updates - Edit this SKILL.md directly when discovering new patterns
3. Reference files - Add detailed examples to references/ to keep SKILL.md lean
4. Commit changes - This skill is part of the project repository

Meta-learning loop:

Development → Retrospective → Skill Update → Better Development