journal_organizer/.kiro/steering/structure.md

# Project Structure

## Directory Organization

```
journal_organizer/
├── __init__.py              # Package initialization
├── __main__.py              # Entry point for python -m execution
├── main.py                  # v1.0 CLI entry and Agent initialization
├── chat_main.py             # v2.0 conversational interface entry
├── agent_core.py            # Core Agent framework (Command + Skill)
├── config.py                # Configuration management utilities
├── server.py                # Optional server interface
├── config.example.yaml      # Configuration template
├── requirements.txt         # Python dependencies
├── README.md               # v1.0 documentation
├── README_V2.md            # v2.0 documentation
├── DEVELOPER_GUIDE.md      # Development guidelines
├── OBSIDIAN_INTEGRATION.md # Obsidian integration guide
├── commands/               # Command implementations
│   ├── __init__.py
│   └── organize_command.py # Main journal organization command
├── skills/                 # Skill implementations
│   ├── __init__.py
│   ├── obsidian_skill.py   # Obsidian API integration skills
│   └── claude_skill.py     # Claude AI integration skills
└── conversation/           # v2.0 conversational layer
    ├── __init__.py
    ├── conversational_agent.py    # Main conversational agent
    ├── conversation_state.py      # State management
    ├── intent_understanding.py    # Natural language understanding
    └── response_generator.py      # Response generation
```

## Core Components

### Agent Core (`agent_core.py`)
- **Agent**: Main orchestrator class
- **Command**: Abstract base for high-level operations
- **Skill**: Abstract base for atomic operations
- **SkillChain**: Sequential skill execution
- **SkillResult**: Standardized result format
- **CommandContext**: Execution context container

### Entry Points
- **`__main__.py`**: Package entry point (`python -m journal_organizer`)
- **`main.py`**: v1.0 CLI with argparse-based command handling
- **`chat_main.py`**: v2.0 conversational interface with natural language processing

### Command Layer (`commands/`)
Commands orchestrate multiple Skills to accomplish complex tasks:
- **OrganizeCommand**: Main journal analysis and organization workflow
- Commands inherit from `Command` base class
- Commands register and coordinate Skills
- Commands handle parameter validation and error recovery

### Skill Layer (`skills/`)
Skills perform atomic operations:
- **ObsidianReadSkill**: Read notes from Obsidian vault
- **ObsidianWriteSkill**: Create/update notes in Obsidian
- **ObsidianAppendSkill**: Append content to existing notes
- **ObsidianListFilesSkill**: List files in vault directories
- **ClaudeAnalyzeSkill**: Analyze journal content with Claude
- **ClaudeTransformSkill**: Transform content formats with Claude

### Conversational Layer (`conversation/`)
v2.0 natural language interface:
- **ConversationalAgent**: Main conversation coordinator
- **IntentUnderstanding**: Maps natural language to commands/parameters
- **ConversationState**: Manages chat history and context
- **ResponseGenerator**: Generates natural language responses

## Naming Conventions

### Files and Modules
- Snake_case for Python files: `organize_command.py`
- Package names match directory structure
- Skills end with `_skill.py`
- Commands end with `_command.py`

### Classes
- PascalCase for class names: `OrganizeCommand`, `ClaudeAnalyzeSkill`
- Skills inherit from `Skill` base class
- Commands inherit from `Command` base class
- Result objects use `Result` suffix: `SkillResult`

### Methods and Variables
- Snake_case for methods and variables: `execute_command`, `api_key`
- Async methods use `async def` prefix
- Private methods start with underscore: `_parse_response`

### Constants and Enums
- UPPER_CASE for constants: `MAX_RETRIES`
- PascalCase for Enums: `SkillType`, `TaskStatus`

## Configuration Structure

### YAML Configuration (`config.yaml`)
```yaml
obsidian:
  vault_path: "/path/to/vault"
  rest_api:
    url: "https://localhost:27123"
    api_key: "your-key"
    verify_ssl: false

claude:
  api_key: "${ANTHROPIC_API_KEY}"
  model: "claude-3-5-sonnet-20241022"
  max_tokens: 4096

journal:
  daily_notes_folder: "Daily"
  date_format: "YYYY-MM-DD"

output:
  experiences_folder: "Knowledge/Experiences"
  lessons_folder: "Knowledge/Lessons"
  # ... other output folders
```

## Extension Patterns

### Adding New Skills
1. Create new file in `skills/` directory
2. Inherit from `Skill` base class
3. Implement `execute()` method returning `SkillResult`
4. Register skill in relevant commands

### Adding New Commands
1. Create new file in `commands/` directory
2. Inherit from `Command` base class
3. Register required skills in `__init__()`
4. Implement `execute()` method with skill orchestration
5. Register command in `main.py` or `chat_main.py`

### Extending Conversational Capabilities
1. Add new intent patterns in `intent_understanding.py`
2. Update command keyword mappings
3. Extend parameter extraction patterns
4. Add response templates in `response_generator.py`