Skip to content

development-workflow.md

Latest commit

 

History

History
166 lines (120 loc) · 3.23 KB

development-workflow.md

File metadata and controls

166 lines (120 loc) · 3.23 KB

Development Workflow Guide

See Also:

This guide covers daily development workflows for making changes to Marcus code.

Quick Reference

Change Type Action Required Command
Python code changes Restart Marcus ./marcus stop && ./marcus start
Dependencies (requirements.txt) Reinstall pip install -r requirements.txt
Config file (config_marcus.json) Restart Marcus ./marcus stop && ./marcus start
Infrastructure (Planka/Postgres) Recreate containers docker compose up -d --force-recreate

Architecture

Marcus runs locally on your machine, not in Docker. Docker is only used for infrastructure (Planka + Postgres). This is because agents write to the local filesystem, and running Marcus in Docker would create path mismatches.

Docker:  Planka + Postgres (infrastructure)
Local:   Marcus + Cato + Agents (share the host filesystem)

Detailed Workflows

1. Python Code Changes (Most Common)

When you modify Python files in src/:

# Restart Marcus
./marcus stop
./marcus start

2. Dependency Changes

When you add/remove packages in requirements.txt:

pip install -r requirements.txt
./marcus stop
./marcus start

3. Configuration Changes

When you edit config_marcus.json:

# Config is read at startup, just restart
./marcus stop
./marcus start

4. Infrastructure Changes

When you need to reset Planka or Postgres:

# Restart infrastructure
docker compose restart

# Full reset (destroys data)
docker compose down -v
docker compose up -d

Testing Workflow

Run Tests

pytest tests/
pytest tests/unit/             # Unit tests only
pytest tests/integration/      # Integration tests only

Linting and Type Checking

black src/ tests/
isort src/ tests/
mypy src/
pre-commit run --all-files

Common Development Tasks

View Logs

# Marcus logs (timestamped files)
tail -f logs/marcus_*.log

# Planka/Postgres logs
docker compose logs -f planka
docker compose logs -f postgres

Reset Infrastructure

# Stop and remove containers + volumes
docker compose down -v

# Start fresh
docker compose up -d

Check Infrastructure Status

docker compose ps

Quick Decision Tree

Made a change?
|-- Python code only?
|   --> Restart Marcus
|
|-- Added/removed packages?
|   --> pip install, then restart Marcus
|
|-- Changed config file?
|   --> Restart Marcus
|
|-- Changed docker-compose.yml?
|   --> docker compose up -d --force-recreate
|
|-- Need fresh Planka data?
    --> docker compose down -v && docker compose up -d

Best Practices

1. Test Before Committing

pytest tests/
pre-commit run --all-files

2. Keep Docker Clean

docker image prune -a           # Remove unused images
docker volume prune             # Remove unused volumes

3. Document Changes

  1. Update relevant docs
  2. Add tests
  3. Update CHANGELOG.md

For configuration changes, update Configuration Reference