shipmate 0.1.0__tar.gz

shipmate-0.1.0/PKG-INFO

@@ -0,0 +1,875 @@
+Metadata-Version: 2.4
+Name: shipmate
+Version: 0.1.0
+Summary: Autonomous AI dev agents as Docker containers — add to any project as a submodule
+Author-email: Paul R <paulr978@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/paulr978/shipmate
+Project-URL: Repository, https://github.com/paulr978/shipmate
+Project-URL: Issues, https://github.com/paulr978/shipmate/issues
+Keywords: ai,agents,docker,crewai,autonomous,dev-agents,ci
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: crewai>=0.108.0
+Requires-Dist: crewai-tools>=0.38.0
+Requires-Dist: anthropic>=0.52.0
+Requires-Dist: gitpython>=3.1.43
+Requires-Dist: PyGithub>=2.5.0
+Requires-Dist: click>=8.1.7
+Requires-Dist: docker>=7.1.0
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: rich>=13.7.0
+
+# Shipmate — Autonomous AI Development System
+
+A reusable, project-local framework that runs autonomous dev agents as Docker containers. Each agent clones the repo, creates a branch, implements a task, validates, pushes, and opens a PR. A persistent PR monitor watches for stale branches and re-spawns agents to rebase and self-heal.
+
+Project-agnostic. Configure for any repo via `shipmate.yml` + `.env` — no code changes needed.
+
+---
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Architecture Overview](#architecture-overview)
+- [Directory Structure](#directory-structure)
+- [CLI Reference](#cli-reference)
+- [Agent Lifecycle](#agent-lifecycle)
+- [PR Monitor](#pr-monitor)
+- [Tools Reference](#tools-reference)
+- [Configuration](#configuration)
+- [PR Metadata Format](#pr-metadata-format)
+- [Shared Services Policy](#shared-services-policy)
+- [Conflict & Self-Healing Model](#conflict--self-healing-model)
+- [Reusability Guide](#reusability-guide)
+- [Security Model](#security-model)
+- [Extending the System](#extending-the-system)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Quick Start
+
+### Prerequisites
+
+- Docker installed and running
+- Python 3.12+
+- `GITHUB_TOKEN` with repo + PR permissions (stored in `.env`)
+- `ANTHROPIC_API_KEY` for Claude API access (stored in `.env`)
+
+### The Easy Way — `launch.sh` / `launch.bat`
+
+The launcher handles everything: creates the venv, loads secrets from `.env`, builds Docker images, checks the network, and launches agents.
+
+**First time setup:**
+1. Copy `.env.example` to `.env` at the project root
+2. Add your `GITHUB_TOKEN` and `ANTHROPIC_API_KEY` to `.env`
+3. Make sure Docker is running and shared services are up (`make up`)
+
+**Then just run:**
+
+```bash
+# Linux/macOS/WSL
+bash shipmate/launch.sh agent "Add pagination to /api/products/"
+
+# Windows
+shipmate\launch.bat agent "Add pagination to /api/products/"
+```
+
+The launcher will automatically:
+- Create `shipmate/.venv` if it doesn't exist
+- Install all shipmate dependencies
+- Load secrets from `.env`
+- Validate tokens are present
+- Create the Docker network if needed
+- Build the agent image if needed
+- Launch the agent container
+
+**Other launcher commands:**
+
+```bash
+# Launch agent in foreground (watch output live)
+shipmate\launch.bat agent "Fix receipt parser bug" --no-detach
+
+# Start the PR monitor
+shipmate\launch.bat monitor
+
+# Check running containers
+shipmate\launch.bat status
+
+# Stop the monitor
+shipmate\launch.bat stop-monitor
+
+# Rebuild Docker images
+shipmate\launch.bat build
+
+# Show help
+shipmate\launch.bat help
+```
+
+### Manual Setup (Alternative)
+
+If you prefer to manage things yourself:
+
+```bash
+# 1. Set up shipmate's own venv
+cd shipmate
+setup_venv.bat            # Windows
+bash setup_venv.sh        # Linux/macOS/WSL
+.venv\Scripts\activate    # activate it
+
+# 2. Set secrets (or source from .env)
+export GITHUB_TOKEN=ghp_...
+export ANTHROPIC_API_KEY=sk-ant-...
+
+# 3. Build and run
+python -m shipmate build
+python -m shipmate run-agent --task "Add pagination to the /api/products/ endpoint"
+
+# 4. (Optional) PR monitor
+python -m shipmate build-monitor
+python -m shipmate monitor-start
+
+# 5. Check running agents
+python -m shipmate list-agents
+
+# Stop the monitor
+python -m shipmate monitor-stop
+```
+
+---
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  Your Machine (Host)                                    │
+│                                                         │
+│  python -m shipmate run-agent --task "..."               │
+│       │                                                 │
+│       ▼                                                 │
+│  ┌──────────────────┐    ┌──────────────────┐           │
+│  │  Agent Container  │    │  Agent Container  │  ...     │
+│  │  (fresh clone)    │    │  (fresh clone)    │          │
+│  │  shipmate/dev/task-A    │    │  shipmate/dev/task-B    │          │
+│  └────────┬─────────┘    └────────┬─────────┘           │
+│           │                       │                     │
+│           └───────┬───────────────┘                     │
+│                   ▼                                     │
+│  ┌────────────────────────────────────────┐              │
+│  │  project_backend_net (from shipmate.yml) │              │
+│  │  ┌──────┐ ┌───────┐ ┌───────┐         │              │
+│  │  │  db  │ │ redis │ │ minio │  ...    │              │
+│  │  └──────┘ └───────┘ └───────┘         │              │
+│  └────────────────────────────────────────┘              │
+│                                                         │
+│  ┌──────────────────┐                                   │
+│  │  PR Monitor       │  (always-on, polls GitHub)       │
+│  │  re-spawns stale  │                                  │
+│  │  agent containers │                                  │
+│  └──────────────────┘                                   │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Core Principles
+
+1. **One task = one container.** Full filesystem isolation. No agent can interfere with another.
+2. **Shared services are external.** Agents connect to the project's existing Docker network (db, redis, minio) but never own or mutate them destructively.
+3. **Each agent gets its own branch.** Branch naming: `shipmate/dev/<agent-id>-<task-slug>-<timestamp>`.
+4. **Each agent opens one PR.** PR body contains hidden metadata so the monitor can reconstruct the task later.
+5. **Self-healing via PR monitor.** When master advances, the monitor detects stale AI PRs and re-spawns the original agent in rebase mode.
+
+---
+
+## Directory Structure
+
+```
+shipmate/
+├── __init__.py
+├── __main__.py                  # `python -m shipmate` entry point
+├── main.py                      # Host-side CLI (click) — tasks, work, dashboard, agents
+├── task_manager.py              # Task queue CRUD (shipmate_tasks.yml backend)
+├── entrypoint.py                # Container lifecycle runner
+├── Dockerfile                   # Agent container image
+├── requirements.txt             # Python dependencies
+├── docker-compose.monitor.yml   # Compose file for the PR monitor
+├── setup_venv.sh                # Venv setup script (Linux/macOS/WSL)
+├── setup_venv.bat               # Venv setup script (Windows)
+├── .venv/                       # shipmate's own virtual environment (gitignored)
+│
+├── config/
+│   └── project.py               # Loads config from env + shipmate.yml (framework code, don't edit)
+│
+├── context/
+│   └── project_context.py       # Reads repo files → context string for the agent
+│
+├── agents/
+│   └── dev_agent.py             # CrewAI Agent definition (role, tools, instructions)
+│
+├── tasks/
+│   └── dev_task.py              # CrewAI Task builder (normal + rebase modes)
+│
+├── crews/
+│   └── dev_crew.py              # Crew assembly: 1 agent, 1 task, sequential
+│
+├── tools/
+│   ├── git_tools.py             # 12 git tools (branch, commit, rebase, push, diff...)
+│   ├── github_tools.py          # 6 GitHub tools (create PR, comment, list AI PRs...)
+│   ├── file_tools.py            # 5 file tools (read, write, list, search, patch)
+│   └── shell_tools.py           # 3 shell tools (constrained commands, ruff check/format)
+│
+├── monitor/
+│   ├── __init__.py
+│   ├── Dockerfile               # Monitor container image
+│   └── pr_monitor.py            # Polling service: detects stale PRs, re-spawns agents
+│
+└── docs/
+    └── README.md                # This file
+```
+
+---
+
+## CLI Reference
+
+All commands run on the host via `python -m shipmate <command>` or `launch.sh <command>`.
+
+### Task Management
+
+#### `task add`
+
+Add a task to the queue.
+
+```bash
+launch.sh task add "Add pagination to /api/products/" --priority high
+launch.sh task add "Fix receipt parser bug" --priority critical --id fix-parser
+launch.sh task add "Refactor analytics module"  # defaults to normal priority
+```
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--priority`, `-p` | `normal` | Priority: `critical`, `high`, `normal`, `low` |
+| `--id` | auto-generated | Custom task ID |
+
+#### `task list`
+
+Show tasks in the queue.
+
+```bash
+launch.sh task list              # pending + running only
+launch.sh task list --all        # include done/failed/cancelled
+launch.sh task list -s pending   # filter by status
+launch.sh task list -p high      # filter by priority
+```
+
+#### `task remove`
+
+Remove a task.
+
+```bash
+launch.sh task remove fix-parser
+```
+
+#### `task update`
+
+Change a task's priority, status, or description.
+
+```bash
+launch.sh task update fix-parser --priority critical
+launch.sh task update fix-parser --status cancelled
+launch.sh task update fix-parser --description "New description"
+```
+
+#### `work`
+
+Pick up pending tasks (by priority) and launch agents.
+
+```bash
+launch.sh work                # launch the next highest-priority task
+launch.sh work --all          # launch agents for ALL pending tasks
+launch.sh work -n 3           # launch the top 3 tasks
+launch.sh work --no-detach    # single task, foreground (watch output)
+```
+
+Tasks are picked in priority order: `critical > high > normal > low`, then FIFO within the same priority.
+
+#### `dashboard`
+
+Live overview of tasks, running agents, and results.
+
+```bash
+launch.sh dashboard            # show once
+launch.sh dashboard -w         # auto-refresh every 5 seconds
+```
+
+#### `logs`
+
+Shortcut to view agent container logs.
+
+```bash
+launch.sh logs dev-a1b2c3          # last 50 lines
+launch.sh logs dev-a1b2c3 -f       # follow (live)
+launch.sh logs dev-a1b2c3 -n 200   # last 200 lines
+```
+
+### Direct Agent Control
+
+#### `run-agent`
+
+Launch an agent directly, bypassing the task queue.
+
+```bash
+launch.sh agent "Add pagination to /api/products/" --no-detach
+launch.sh agent "Fix bug" --id my-fix --rebase
+```
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--task`, `-t` | (required) | Task description |
+| `--id` | auto | Agent identifier |
+| `--branch`, `-b` | auto | Git branch name |
+| `--rebase` | off | Rebase/conflict-resolution mode |
+| `--detach/--no-detach` | detach | Background or foreground |
+
+### Infrastructure
+
+#### `build`
+
+Build the agent Docker image.
+
+```bash
+launch.sh build [--no-cache]
+```
+
+#### `monitor` / `stop-monitor`
+
+Start/stop the PR monitor.
+
+```bash
+launch.sh monitor [--interval 60]
+launch.sh stop-monitor
+```
+
+#### `status`
+
+Show running containers.
+
+```bash
+launch.sh status
+```
+
+#### `list-agents`
+
+List running agent containers.
+
+```bash
+python -m shipmate list-agents
+```
+
+---
+
+## Agent Lifecycle
+
+When you run `python -m shipmate run-agent --task "..."`, this is what happens:
+
+```
+Host: main.py
+  │
+  ├── Generate agent ID, branch name
+  ├── Validate GITHUB_TOKEN and ANTHROPIC_API_KEY
+  ├── docker run shipmate-agent:latest with env vars
+  │
+  └── Container starts → entrypoint.py
+        │
+        ├── 1. Clone repo from GitHub (authenticated via GITHUB_TOKEN)
+        ├── 2. Configure git identity (shipmate-<agent-id>)
+        ├── 3. Create branch (or checkout existing for rebase)
+        ├── 4. Install backend requirements (pip install -r backend/requirements.txt)
+        ├── 5. Build project context (reads CLAUDE.md, decisions.md, etc.)
+        ├── 6. Run CrewAI dev crew
+        │     │
+        │     └── dev_agent.py executes the task:
+        │           ├── Read existing code (file_tools)
+        │           ├── Implement changes (file_tools)
+        │           ├── Run validation (shell_tools: ruff check, ruff format)
+        │           ├── Commit changes (git_tools)
+        │           ├── Push branch (git_tools)
+        │           └── Create PR with metadata (github_tools)
+        │
+        ├── 7. Log result
+        └── 8. Exit (container stops)
+```
+
+### Rebase Mode
+
+When `AGENT_REBASE=true` (set by the monitor or `--rebase` flag):
+
+1. Checkout existing branch
+2. Fetch latest from origin
+3. Rebase onto `origin/master`
+4. Resolve conflicts (simple ones automatically, complex ones flagged)
+5. Re-run validation
+6. Force-push the updated branch
+7. Comment on the PR with a summary
+
+---
+
+## PR Monitor
+
+The PR monitor (`monitor/pr_monitor.py`) is a simple polling service — not a CrewAI agent.
+
+### What It Does
+
+```
+Every N seconds:
+  │
+  ├── Get latest master SHA from GitHub
+  ├── If master hasn't changed → skip
+  ├── If master advanced:
+  │     ├── List all open PRs on shipmate/* branches
+  │     ├── For each PR:
+  │     │     ├── Compare branch HEAD to master
+  │     │     ├── If stale (behind master):
+  │     │     │     ├── Comment on PR: "Re-spawning agent to rebase"
+  │     │     │     ├── docker run agent container in rebase mode
+  │     │     │     └── Track as active respawn
+  │     │     └── If up-to-date → skip
+  │     └── Clean up finished respawns
+  └── Sleep N seconds
+```
+
+### Running the Monitor
+
+Option A — via CLI:
+```bash
+python -m shipmate monitor-start --interval 60
+```
+
+Option B — via docker-compose:
+```bash
+cd shipmate
+docker-compose -f docker-compose.monitor.yml up -d
+```
+
+The monitor container mounts `/var/run/docker.sock` so it can spawn sibling agent containers.
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `GITHUB_TOKEN` | (required) | GitHub PAT |
+| `ANTHROPIC_API_KEY` | (required) | Passed to spawned agents |
+| `GITHUB_REPO` | (required) | Repository to watch |
+| `BASE_BRANCH` | `master` | Branch to monitor |
+| `POLL_INTERVAL` | `60` | Seconds between polls |
+| `DOCKER_NETWORK` | (required) | Network agents join |
+| `AGENT_IMAGE` | `shipmate-agent:latest` | Image for spawned agents |
+
+---
+
+## Tools Reference
+
+### Git Tools (`tools/git_tools.py`)
+
+All tools operate on the local repo clone at `/workspace`.
+
+| Tool | Description |
+|------|-------------|
+| `create_branch` | Create and checkout a new branch |
+| `checkout_branch` | Checkout an existing branch |
+| `git_fetch` | Fetch from remote |
+| `git_rebase` | Rebase current branch onto another |
+| `git_rebase_continue` | Continue rebase after conflict resolution |
+| `git_rebase_abort` | Abort a rebase |
+| `git_commit` | Stage all changes and commit |
+| `git_push` | Push branch to origin (supports force-with-lease) |
+| `git_diff` | Show stat diff against a base branch |
+| `git_changed_files` | List files changed vs a base branch |
+| `git_status` | Show working tree status |
+| `git_log` | Show recent log entries |
+
+### GitHub Tools (`tools/github_tools.py`)
+
+| Tool | Description |
+|------|-------------|
+| `create_pull_request` | Create a PR with optional metadata block |
+| `update_pull_request` | Update PR title/body |
+| `comment_on_pr` | Add a comment to a PR |
+| `list_ai_pull_requests` | List all open PRs on `shipmate/*` branches |
+| `get_pr_metadata` | Extract shipmate metadata from a PR body |
+| `get_pr_changed_files` | List files changed in a PR |
+
+### File Tools (`tools/file_tools.py`)
+
+All paths are sandboxed to `/workspace`. Attempts to escape are rejected.
+
+| Tool | Description |
+|------|-------------|
+| `read_file` | Read file contents (truncated at 50K chars) |
+| `write_file` | Write/create a file |
+| `list_directory` | Recursive directory listing (configurable depth) |
+| `search_files` | Regex search across files (default: `*.py`) |
+| `patch_file` | Find-and-replace a specific text block in a file |
+
+### Shell Tools (`tools/shell_tools.py`)
+
+Shell access is **constrained by an allowlist**. The agent cannot run arbitrary commands.
+
+| Tool | Description |
+|------|-------------|
+| `run_shell_command` | Run an allowlisted command |
+| `run_ruff_check` | Run `ruff check` (with optional `--fix`) |
+| `run_ruff_format` | Run `ruff format` |
+
+**Built-in allowed prefixes:** `ruff `, `pytest `, `pip install`, `pip list`, `pip show`, `cat `, `head `, `tail `, `wc `, `diff `, `find `, `ls `
+
+**Built-in blocked patterns:** `rm -rf`, `rm -r /`, `DROP`, `DELETE FROM`, `TRUNCATE`, `FLUSHALL`, `FLUSHDB`
+
+**Project-specific additions** are configured in `shipmate.yml` under `shell.allowed_prefixes` and `shell.blocked_patterns`. These are merged with the built-in lists at runtime.
+
+---
+
+## Configuration
+
+shipmate is **project-agnostic**. All project-specific configuration comes from two sources:
+
+### 1. `shipmate.yml` (project root)
+
+This file lives at the root of your project (not inside `shipmate/`). It defines everything the agents need to know about your project: validation commands, context files, safety rules, shell allowlists, etc.
+
+```yaml
+github:
+  repo: your-org/your-repo
+  base_branch: main
+  branch_prefix: shipmate/dev
+  pr_title_prefix: "[AI]"
+
+docker:
+  network: your-project_backend_net
+
+context_files:
+  - README.md
+  - docs/architecture.md
+
+requirements_file: requirements.txt
+
+validation_commands:
+  - command: "npm run lint"
+    description: "Run linter"
+  - command: "npm test"
+    description: "Run tests"
+
+shared_service_rules:
+  - "Do NOT drop or truncate database tables."
+  - "Do NOT flush Redis."
+
+tech_stack:
+  - "Node.js 20"
+  - "PostgreSQL 16"
+
+shell:
+  allowed_prefixes:
+    - "npm "
+    - "npx "
+  blocked_patterns:
+    - "npm run db:reset"
+
+llm:
+  model: claude-sonnet-4-6
+  max_tokens: 8192
+```
+
+See the `shipmate.yml` at the root of this repo for a complete example.
+
+### 2. `.env` (secrets + overrides)
+
+Secrets and simple overrides go in your `.env` file (gitignored).
+
+**Required:**
+
+| Variable | Purpose |
+|----------|---------|
+| `GITHUB_TOKEN` | Clone, push, PR operations |
+| `ANTHROPIC_API_KEY` | LLM calls inside agent containers |
+
+**Optional overrides** (take precedence over `shipmate.yml`):
+
+| Variable | Overrides |
+|----------|-----------|
+| `SHIPMATE_GITHUB_REPO` | `github.repo` |
+| `SHIPMATE_BASE_BRANCH` | `github.base_branch` |
+| `SHIPMATE_DOCKER_NETWORK` | `docker.network` |
+| `SHIPMATE_BRANCH_PREFIX` | `github.branch_prefix` |
+| `SHIPMATE_LLM_MODEL` | `llm.model` |
+| `SHIPMATE_LLM_MAX_TOKENS` | `llm.max_tokens` |
+| `SHIPMATE_POLL_INTERVAL` | `monitor.poll_interval_seconds` |
+| `SHIPMATE_AGENT_IMAGE_NAME` | `agent.image_name` |
+| `SHIPMATE_AGENT_IMAGE_TAG` | `agent.image_tag` |
+
+### 3. `config/project.py` (framework code — do not edit)
+
+This file loads values from env vars and `shipmate.yml`. It has no hardcoded project values. You should never need to modify it.
+
+### Priority order
+
+```
+Environment variable  >  shipmate.yml  >  built-in default
+```
+
+---
+
+## PR Metadata Format
+
+Every AI-created PR contains a hidden metadata block in its body:
+
+```html
+<!-- SHIPMATE_META
+{
+  "task": "Add pagination to /api/products/",
+  "agent_id": "dev-a1b2c3",
+  "branch": "shipmate/dev/dev-a1b2c3-add-pagination-20260328-143022",
+  "created_at": "2026-03-28T14:30:22.000000+00:00",
+  "rebase_count": 0
+}
+SHIPMATE_META -->
+```
+
+This block is invisible when viewing the PR on GitHub but parseable by the monitor. It allows the monitor to:
+
+- Reconstruct the original task description
+- Re-spawn the exact same agent
+- Track how many times a branch has been rebased
+
+The `encode_pr_metadata()` and `decode_pr_metadata()` functions in `tools/github_tools.py` handle serialization.
+
+---
+
+## Shared Services Policy
+
+Agents attach to the project's Docker network and can reach shared services. Strict rules apply:
+
+### Allowed
+
+- Read from the running database (inspect schema, query data)
+- Read from Redis (check keys, inspect state)
+- Run targeted validation commands (`manage.py check`, `manage.py showmigrations`)
+- Run linting and formatting
+- Run isolated tests if safe (must use per-agent test DB: `test_agent_{agent_id}`)
+
+### Not Allowed
+
+- `manage.py migrate` — never migrate the shared development database
+- `manage.py flush` / `manage.py loaddata` / `manage.py dumpdata`
+- `FLUSHALL` / `FLUSHDB` on Redis
+- Delete or overwrite objects in MinIO
+- Any destructive operation on shared infrastructure
+
+These rules are enforced at two levels:
+1. **Shell allowlist** — blocked patterns in `shell_tools.py` prevent the commands from running
+2. **Agent instructions** — safety rules are injected into the agent's backstory so the LLM avoids attempting them
+
+---
+
+## Conflict & Self-Healing Model
+
+### Automatic Resolution (agent handles)
+
+- Simple merge conflicts in different parts of a file
+- Migration numbering conflicts (e.g., two agents both create `0005_...`)
+- Import ordering conflicts
+- Naming conflicts for newly added files/classes if detectable
+- Minor upstream refactors that don't change semantics
+
+### Escalation (agent marks PR for human review)
+
+- Semantic conflicts in the same function/method
+- Contradictory schema changes
+- Cases where the task intent is no longer valid after upstream changes
+- Risky shared-service changes
+
+When escalating, the agent:
+1. Updates the PR body with a warning section
+2. Comments on the PR explaining the conflict
+3. Leaves the branch in a clean state (rebase aborted if necessary)
+
+---
+
+## Reusability Guide
+
+shipmate is designed to be dropped into any project. The `shipmate/` directory contains zero project-specific values.
+
+### Step 1: Copy the directory
+
+```bash
+cp -r shipmate/ /path/to/other-project/shipmate/
+```
+
+### Step 2: Create `shipmate.yml` at your project root
+
+```yaml
+github:
+  repo: your-org/your-repo
+  base_branch: main
+
+docker:
+  network: your-project_backend_net
+
+context_files:
+  - README.md
+
+validation_commands:
+  - command: "npm run lint"
+    description: "Lint check"
+
+tech_stack:
+  - "Node.js 20"
+  - "Express"
+```
+
+### Step 3: Add secrets to `.env`
+
+```
+GITHUB_TOKEN=ghp_...
+ANTHROPIC_API_KEY=sk-ant-...
+```
+
+### Step 4: Update the Dockerfile (if needed)
+
+If your project uses a different language/runtime, update `shipmate/Dockerfile` to install the right system dependencies. The default image includes Python 3.12, git, and common build tools.
+
+### What you DON'T need to change
+
+- `config/project.py` — reads from env + `shipmate.yml` automatically
+- `tools/shell_tools.py` — shell allowlists/blocklists are configured in `shipmate.yml`
+- CLI, entrypoint, agent/task/crew wiring, git/github tools, PR monitor, metadata format
+
+### Files that are project-specific (live outside `shipmate/`)
+
+| File | Purpose |
+|------|---------|
+| `shipmate.yml` | Project config (repo, network, validation, rules) |
+| `.env` | Secrets and optional overrides |
+| `shipmate/Dockerfile` | System deps (only if your stack differs) |
+
+---
+
+## Security Model
+
+### Secrets
+
+- `GITHUB_TOKEN` and `ANTHROPIC_API_KEY` are passed as container env vars
+- Never baked into Docker images
+- Never committed to the repo
+
+### GitHub Token Scopes
+
+The token needs:
+- `repo` — clone, push branches
+- `pull_request` — create, update, comment on PRs
+
+### Container Isolation
+
+- Each agent runs in its own container with its own filesystem
+- Workspace is sandboxed — file tools reject paths outside `/workspace`
+- Shell access is allowlisted — only pre-approved commands run
+- Destructive patterns are explicitly blocked
+
+### Monitor Access
+
+The monitor container mounts the Docker socket (`/var/run/docker.sock`) to spawn sibling containers. This is a privileged operation — the monitor should only run in trusted environments.
+
+---
+
+## Extending the System
+
+### Adding a New Tool
+
+1. Create a function in the appropriate `tools/*.py` module
+2. Decorate with `@tool("tool_name")`
+3. Add it to the agent's tool list in `agents/dev_agent.py`
+
+Example:
+
+```python
+# tools/shell_tools.py
+@tool("run_mypy")
+def run_mypy(path: str = ".") -> str:
+    """Run mypy type checker."""
+    return _run_command(f"mypy {path}")
+```
+
+Then add `"mypy "` to `shell.allowed_prefixes` in `shipmate.yml` and add the tool import in `dev_agent.py`.
+
+### Adding a New Agent Type
+
+1. Create `agents/frontend_agent.py` (or similar)
+2. Create a corresponding task in `tasks/frontend_task.py`
+3. Optionally create a new crew in `crews/frontend_crew.py`
+4. Add a new CLI command in `main.py` (e.g., `run-frontend-agent`)
+
+### Adding New Validation Commands
+
+Update `shipmate.yml` at your project root:
+
+```yaml
+validation_commands:
+  - command: "ruff check --fix ."
+    description: "Lint check and auto-fix"
+  - command: "pytest backend/apps/myapp/tests/ -x"
+    description: "Run targeted tests"
+
+shell:
+  allowed_prefixes:
+    - "pytest "   # must be in the allowlist for validation to work
+```
+
+---
+
+## Troubleshooting
+
+### Agent container exits immediately
+
+Check logs:
+```bash
+docker logs shipmate-<agent-id>
+```
+
+Common causes:
+- Missing `GITHUB_TOKEN` or `ANTHROPIC_API_KEY`
+- GitHub token lacks push/PR permissions
+- Agent image not built (`python -m shipmate build`)
+
+### Agent can't reach shared services
+
+Make sure the project's Docker network exists and services are running:
+```bash
+docker network ls | grep backend_net
+make up  # from project root
+```
+
+### Monitor doesn't detect stale PRs
+
+- Check monitor logs: `docker logs -f shipmate-monitor`
+- Verify `GITHUB_REPO` and `BASE_BRANCH` are correct
+- PRs must be on `shipmate/*` branches to be detected
+
+### Clone fails inside container
+
+- Verify `GITHUB_TOKEN` has `repo` scope
+- For private repos, ensure the token has access
+
+### Rebase fails with complex conflicts
+
+The agent will attempt automatic resolution for simple conflicts. If it can't resolve, it will:
+1. Abort the rebase
+2. Comment on the PR explaining the conflict
+3. The PR remains open for human review
+
+Check the PR comments for details.