romantic-companion-ai/
├── CLAUDE.md # Main instruction document for Claude Code
├── setting.json # Configuration and personality settings
├── README.md # Project overview and setup guide
├── requirements.txt # Python dependencies
├── .env.example # Environment variables template
├── _doc/ # Implementation documentation
│ ├── TEMPLATE_LOG.md # Template for implementation logs
│ ├── TEMPLATE_EVAL.md # Template for self-evaluation
│ ├── TEMPLATE_PLAN.md # Template for action planning
│ ├── logs/ # Implementation logs with timestamps
│ ├── evaluations/ # Self-evaluation reports
│ └── plans/ # Action plans for sessions
├── src/
│ ├── __init__.py
│ ├── main.py # Entry point
│ ├── core/
│ │ ├── __init__.py
│ │ ├── affinity_engine.py # Enhanced affinity system
│ │ ├── emotion_processor.py # Emotional state management
│ │ ├── memory_system.py # Long-term memory
│ │ ├── personality_core.py # Dynamic personality
│ │ └── response_generator.py # Advanced response generation
│ ├── ai/
│ │ ├── __init__.py
│ │ ├── sentiment_analyzer.py # Multi-layer sentiment analysis
│ │ ├── context_manager.py # Conversation context
│ │ ├── language_model.py # Natural language processing
│ │ └── learning_engine.py # Adaptive learning system
│ ├── personality/
│ │ ├── __init__.py
│ │ ├── traits.py # Personality trait definitions
│ │ ├── moods.py # Mood state management
│ │ ├── interests.py # Interest tracking
│ │ └── relationship_model.py # Relationship dynamics
│ ├── data/
│ │ ├── __init__.py
│ │ ├── storage.py # Persistent data management
│ │ ├── encryption.py # Data security
│ │ └── models.py # Data models
│ ├── interface/
│ │ ├── __init__.py
│ │ ├── cli.py # Command line interface
│ │ ├── commands.py # Command handlers
│ │ └── display.py # UI formatting
│ └── utils/
│ ├── __init__.py
│ ├── validators.py # Input validation
│ ├── decorators.py # Utility decorators
│ └── helpers.py # Helper functions
├── tests/
│ ├── __init__.py
│ ├── unit/
│ ├── integration/
│ └── fixtures/
├── data/
│ ├── templates/ # Response templates
│ ├── personalities/ # Personality presets
│ └── knowledge/ # Knowledge base
└── logs/ # Runtime logs
-
Create Project Directory
mkdir romantic-companion-ai cd romantic-companion-ai -
Initialize Git Repository
git init echo "# Romantic Companion AI" > README.md git add README.md git commit -m "Initial commit"
-
Create Directory Structure
# Create all directories mkdir -p src/{core,ai,personality,data,interface,utils} mkdir -p tests/{unit,integration,fixtures} mkdir -p data/{templates,personalities,knowledge} mkdir -p _doc/{logs,evaluations,plans} mkdir logs # Create __init__.py files touch src/__init__.py touch src/core/__init__.py touch src/ai/__init__.py touch src/personality/__init__.py touch src/data/__init__.py touch src/interface/__init__.py touch src/utils/__init__.py touch tests/__init__.py
-
Copy Configuration Files
- Place
CLAUDE.mdin the root directory - Place
setting.jsonin the root directory - Copy all template files to
_doc/directory
- Place
-
Create Python Environment
python -m venv venv # Activate virtual environment # On macOS/Linux: source venv/bin/activate # On Windows: venv\Scripts\activate # Upgrade pip pip install --upgrade pip
-
Install Initial Dependencies
pip install python-dotenv pip install typing-extensions pip install pydantic pip install rich # For beautiful CLI output pip install pytest pytest-cov # For testing pip install cryptography # For data encryption pip install aiofiles # For async file operations pip freeze > requirements.txt
-
Create Environment Files
# Create .env.example cat > .env.example << EOF # Application Settings APP_NAME=Romantic Companion AI APP_VERSION=2.0.0 # Security ENCRYPTION_KEY=your-encryption-key-here # Development DEBUG=false LOG_LEVEL=INFO # Data Storage DATA_PATH=./data USER_DATA_PATH=./data/users EOF # Create actual .env (don't commit this) cp .env.example .env # Edit .env with your actual values
-
Initialize Documentation
# Copy templates to _doc directory # Create first planning document cp _doc/TEMPLATE_PLAN.md "_doc/plans/$(date +%Y%m%d-%H%M%S)-initial-plan.md" # Edit the plan with your initial session goals
-
Before Each Session:
- Read all previous documents in
_doc/logs/,_doc/evaluations/, and_doc/plans/ - Create new action plan using
TEMPLATE_PLAN.md - Review
CLAUDE.mdfor implementation guidelines - Check current project status
- Read all previous documents in
-
During Development:
- Follow the implementation strategy in your action plan
- Commit changes frequently with descriptive messages
- Run tests continuously
- Update documentation as you go
- Take notes for your implementation log
-
After Each Session:
- Create implementation log using
TEMPLATE_LOG.mdwith timestamp - Complete self-evaluation using
TEMPLATE_EVAL.md - Draft next action plan while insights are fresh
- Commit all documentation to git
- Backup your work
- Create implementation log using
# Run all tests
pytest
# Run with coverage report
pytest --cov=src tests/ --cov-report=html
# Run specific test file
pytest tests/unit/test_affinity_engine.py
# Run with verbose output
pytest -v
# Run only marked tests
pytest -m "unit"
# Watch mode (requires pytest-watch)
pip install pytest-watch
ptw# Install code quality tools
pip install black flake8 mypy isort
# Format code
black src/
# Check code style
flake8 src/
# Type checking
mypy src/
# Sort imports
isort src/# Feature branch workflow
git checkout -b feature/emotional-state-machine
# ... make changes ...
git add .
git commit -m "feat: implement emotional state machine with mood persistence"
git push origin feature/emotional-state-machine
# Commit message format
# feat: new feature
# fix: bug fix
# docs: documentation update
# style: code style update
# refactor: code refactoring
# test: test updates
# chore: build/config updates-
Documentation is Mandatory: Every coding session MUST include:
- Implementation log in
_doc/logs/ - Self-evaluation in
_doc/evaluations/ - Next action plan in
_doc/plans/
- Implementation log in
-
Read Previous Work: Always start by reading all previous documentation to understand context and learn from past sessions.
-
Quality Over Speed: Focus on creating a genuine, emotionally intelligent AI rather than rushing features.
-
User Privacy: All user data must be encrypted and stored locally only.
-
Continuous Learning: Each session should build upon previous learnings and improvements.