roboco/usage.md

RoboCo Usage Guide

Operating the AI company after deployment.

The Organization

22 AI agents organized as a company:

CEO (You)
├── Intake (on-demand interviewer: chats only with you to draft a task)
└── Board
    ├── Product Owner
    ├── Head of Marketing
    └── Auditor
        └── Main PM
            ├── Backend Cell (PM, 2 Devs, QA, Documenter)
            ├── Frontend Cell (PM, 2 Devs, QA, Documenter)
            └── UX/UI Cell (PM, 2 Devs, QA, Documenter)

Agent IDs

ID	Role	Team
main-pm	Main PM	Management
be-pm	Cell PM	Backend
be-dev-1, be-dev-2	Developers	Backend
be-qa	QA	Backend
be-doc	Documenter	Backend
fe-pm	Cell PM	Frontend
fe-dev-1, fe-dev-2	Developers	Frontend
fe-qa	QA	Frontend
fe-doc	Documenter	Frontend
ux-pm	Cell PM	UX/UI
ux-dev-1, ux-dev-2	Developers	UX/UI
ux-qa	QA	UX/UI
ux-doc	Documenter	UX/UI
product-owner	Product Owner	Board
head-marketing	Head of Marketing	Board
auditor	Auditor	Board
intake-1	Intake (interviewer)	Board

Spawning Agents

# Start with minimal team
uv run python -m roboco.cli --spawn main-pm be-dev-1 be-qa

# Add more agents
uv run python -m roboco.cli --spawn main-pm be-pm be-dev-1 be-dev-2 be-qa

# Full organization
uv run python -m roboco.cli --spawn \
  main-pm \
  be-pm be-dev-1 be-dev-2 be-qa be-doc \
  fe-pm fe-dev-1 fe-dev-2 fe-qa fe-doc \
  ux-pm ux-dev-1 ux-dev-2 ux-qa ux-doc \
  product-owner head-marketing auditor

Monitoring Agents

Check Status

# Via API
curl http://localhost:8000/api/orchestrator/status | jq

# Via Docker
docker ps --filter "name=roboco-agent"

View Agent Logs

# Follow specific agent's output
docker logs -f roboco-agent-be-dev-1

# All agent containers
docker ps --filter "name=roboco-agent" --format "{{.Names}}"

Container Management

# Stop one agent
docker stop roboco-agent-be-dev-1

# Restart an agent
docker restart roboco-agent-be-dev-1

# Stop all agents
docker ps --filter "name=roboco-agent" -q | xargs docker stop

Creating Tasks

POST /api/tasks has no silent defaults — title, description (min 20 chars), acceptance_criteria (at least one), team, task_type, nature, and estimated_complexity are all required, plus exactly one of project_id (the repo this task targets) or product_id (a cell→project map for a fan-out task). See the TaskCreate schema in roboco/models/task.py (or the Swagger UI at /docs) for the full field list and enum values.

curl -X POST http://localhost:8000/api/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Implement user authentication",
    "description": "Add JWT-based auth to the API endpoints",
    "team": "backend",
    "task_type": "code",
    "nature": "technical",
    "estimated_complexity": "medium",
    "project_id": "<project-uuid>",
    "acceptance_criteria": [
      "Users can register",
      "Users can login",
      "Protected routes require valid JWT"
    ]
  }'

Enum values: task_type ∈ {code, documentation, research, planning, design, administrative}; nature ∈ {technical, non_technical}; estimated_complexity ∈ {low, medium, high}.

Task Lifecycle

pending → claimed → in_progress → verifying → awaiting_qa → awaiting_documentation → completed
                         ↓
                    blocked/paused

Agents automatically:

1. Pull pending work via the gateway verb give_me_work()
2. Claim it with i_will_work_on(task_id) (auto-creates the feature branch)
3. Follow the workflow: UNDERSTAND → PLAN → EXECUTE → VERIFY → NOTES
4. Open a PR and submit for QA when done (open_pr / i_am_done)
5. Move to next task

API Endpoints

Endpoint	Description
GET /health	Health check
GET /docs	Swagger UI
GET /api/orchestrator/status	Agent states
GET /api/tasks	List tasks
POST /api/tasks	Create task
GET /api/tasks/{id}	Task details

Viewing the API

Open http://localhost:8000/docs in your browser for the Swagger UI.

Common Workflows

Start a Development Session

# 1. Start infrastructure
docker compose up -d

# 2. Run migrations (if needed)
uv run alembic upgrade head

# 3. Start with a small team
uv run python -m roboco.cli --spawn main-pm be-dev-1 be-qa

Create and Monitor a Task

# Create task (all fields below are required — see POST /api/tasks schema)
curl -X POST http://localhost:8000/api/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Fix login bug",
    "description": "Login fails on expired-token refresh path",
    "team": "backend",
    "task_type": "code",
    "nature": "technical",
    "estimated_complexity": "low",
    "project_id": "<project-uuid>",
    "acceptance_criteria": ["Expired token refreshes without 500"]
  }'

# Watch agent pick it up
docker logs -f roboco-agent-be-dev-1

Shutdown

# Stop orchestrator (Ctrl+C in terminal)

# Stop agent containers
docker ps --filter "name=roboco-agent" -q | xargs docker stop

# Stop infrastructure
docker compose down

Tips

Start Small

Don't spawn the whole fleet at once. Start with:

1. main-pm alone - verify spawning works
2. Add be-dev-1 - verify task claiming
3. Add be-qa - verify full workflow

Check Agent Health

# Quick status
curl -s http://localhost:8000/api/orchestrator/status | jq '.agents'

# Detailed container info
docker inspect roboco-agent-be-dev-1

Debug an Agent

# View full logs
docker logs roboco-agent-be-dev-1

# Attach to container (read-only)
docker logs -f roboco-agent-be-dev-1

Resource Usage

RAM is modest. Agent containers are spawned on demand and torn down when their work is done, so you rarely have more than a handful live at once — and the on-demand Intake and Secretary only run while you're interacting with them. Steady-state memory is dominated by the standing services (Postgres, Redis, and especially Ollama with its models loaded), not by the agents.

Storage is the larger footprint: the built (or pulled) image set. The agent images all share a common base layer, so on disk they cost far less than their nominal sizes added together. docker system prune reclaims old image versions and stopped agent containers.

Monitor with:

docker stats        # live RAM / CPU per running container
docker system df    # image / container / build-cache disk usage