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)

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