Metadata-Version: 2.4
Name: devage
Version: 0.1.10
Summary: Local human-in-the-loop multi-agent development environment
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: alembic>=1.13
Requires-Dist: typer[all]>=0.12
Requires-Dist: litellm>=1.0
Requires-Dist: docker>=7.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: mypy>=1.9; extra == "dev"
Requires-Dist: pydantic[mypy]; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: pyinstaller>=6.0; extra == "dev"

# devage — Developer Agency

> Local, human-in-the-loop multi-agent development environment.

A developer orchestrates a team of autonomous AI agents. Each agent runs as a long-lived Docker container daemon, creates a per-task Git branch, commits progress after every workflow step, and picks up tasks from a shared Kanban board backed by SQLite. Tasks are authored as Markdown files — the files are the source of truth, the database is a queryable index. Agents execute YAML-defined workflows entirely inside the container — calling `claude -p` for LLM steps, running bash validation, and auto-committing completed work — while the human reviews and approves from a VS Code dashboard.

## Repository Layout

```
devage/
├── .devage/                  # Local project config and runtime state
│   ├── agents/               #   Per-agent Dockerfiles + devage.whl build artefact
│   ├── milestones/           #   MILESTONE-NNN_<slug>.md files from the roadmap builder
│   ├── state/                #   Wizard state (roadmap cursor, resume support)
│   ├── tasks/                #   Task .md files (TASK-NNN_slug.md) — source of truth
│   ├── team.yaml             #   Agent definitions
│   ├── worktrees/            #   Per-agent git worktrees
│   └── *.db                  #   SQLite database (queryable task/agent index)
├── cli/                      # Python orchestrator (compiled to standalone binary)
│   └── devage/
│       ├── cli/              #   CLI entry point, command modules (init/agent/task), ProjectContext
│       ├── engine/           #   Workflow engine, workers, task/milestone managers
│       ├── database/         #   SQLAlchemy ORM models, agent repository, session management
│       ├── models/           #   Pydantic config validation
│       └── orchestrator/     #   Docker container + Git worktree lifecycle
├── vscode-extension/         # TypeScript/React VS Code extension (dashboard UI)
└── docs/                     # Architecture and reference documentation
```

## Quickstart

### Python CLI

```bash
cd cli
pip install -e ".[dev]"

# Set your LLM API key
export ANTHROPIC_API_KEY=sk-ant-...

# First-time setup (interactive wizard)
devage init
# Phase 1 — Workspace scan:    if the project dir has existing code, claude -p
#                               summarises it and seeds the goal interview.
# Phase 2 — Goal interview:    short Q&A → .devage/project_goal.md
# Phase 3 — Team setup:        validates team.yaml, registers agents in the DB
# Phase 4 — Roadmap builder:   proposes milestones (epics) one at a time;
#                               accept / edit / pause / done
#                               → .devage/milestones/MILESTONE-NNN_<slug>.md
# Phase 5 — DB init:           creates .devage/<project>.db

# Resume a paused roadmap session
devage init --resume-roadmap

# View the Kanban board
devage status
```

**Scripted / CI usage** (skip all wizard prompts):

```bash
devage init --team-yaml .devage/team.yaml
```

### Working with tasks

Tasks live as Markdown files in `.devage/tasks/`. The CLI creates them and keeps the database in sync.

```bash
# Create a task (prints path of the created .md file)
devage create-task --title "Implement login endpoint" --assignee "backend_dev"
# → .devage/tasks/TASK-001_implement_login_endpoint.md

# Edit the task file directly — add acceptance criteria, adjust assignee, etc.
# Then re-sync the database:
devage sync
# Synced 1 tasks (0 errors)
```

### Starting agents and running tasks

```bash
# Build the agent's Docker image and start it as a detached container daemon.
# The container runs the internal poll loop automatically — no second command needed.
devage start-agent tech_lead
# Builds image devage-tech_lead:latest (first run: 1–3 min)
# Starts container: devage-tech_lead
# Agent tech_lead started. Container: devage-tech_lead

# Watch the agent work (optional)
docker logs devage-tech_lead --follow

# Stop the agent
devage stop-agent tech_lead
```

The container polls every 10 seconds. It resumes its own `IN_PROGRESS` tasks first (crash recovery), then claims `APPROVED` tasks. Each AI/bash step is committed to the task's dedicated git branch (`git add . && git commit`). When the workflow reaches a `human_review` step the task moves to `IN_REVIEW`; the human sets the status back to `approved` in the task's `.md` file and runs `devage sync` to resume from where it paused. Task status updates flow back through the shared SQLite database so the VS Code dashboard updates in real time.

### Opening a shell in an agent's container

```bash
devage shell backend_dev
# Opens: docker exec -it -w /workspace devage-backend_dev /bin/bash
# Type exit or Ctrl+D to return.
```

### Hiring agents

```bash
# Fully interactive interview (wizard asks about role, model, workflows, and tools)
devage create-agent

# Pre-fill the role description
devage create-agent --role-hint "A Python backend dev who writes tests first"
```

The wizard asks which CLI tools and runtimes the agent needs (e.g. `nodejs`, `python3`, `go`, `rust`, `make`). It generates a per-agent Dockerfile at `.devage/agents/Dockerfile.<agent_id>` and writes a `team.yaml` entry with a `tools` field. The Dockerfile is built automatically the first time you run `devage start-agent`.

### Build standalone binary

```bash
cd cli
./build.sh
./dist/devage --version
```

### VS Code Extension

1. Open the project root in VS Code
2. Run `npm install` inside `vscode-extension/`
3. Press **F5** to open an Extension Development Host
4. Press `Ctrl+Shift+P` → **devage: Open Dashboard**

The dashboard shows the Team Roster and Kanban board. You can:
- Start/stop agents with the **▶ Start** and **⏹ Stop** buttons
- Open a shell in a running agent's container with **>_ Jump In**
- Click any task card to open its `.md` file in the editor
- Add a task with the **+** button in the Backlog column header
- Hire a new agent with **+ Hire Agent**

Agent cards show real-time status: `creating` while the Docker image is being built, `stopping` during shutdown, and the current workflow step (e.g. `↳ ai:gen`, `↳ validation:tests`) while a task is in progress.

## Architecture

| Document | Description |
|----------|-------------|
| [docs/architecture.md](docs/architecture.md) | System overview, component map, IPC contracts |
| [docs/workflow-engine.md](docs/workflow-engine.md) | Workflow YAML schema, execution flow, retry logic |
| [docs/task-files.md](docs/task-files.md) | Markdown task files, frontmatter schema, sync engine |
| [docs/cli-reference.md](docs/cli-reference.md) | Full command and flag reference |
| [docs/configuration.md](docs/configuration.md) | team.yaml schema, config cascade, init wizard |

## License

MIT
