# SPEC.md — AI-Orchestrator

## Purpose

A Python service implementing the Symphony specification — it polls a task board (OrgMyLife) for agent-ready tasks, dispatches them to a coding agent (Codex CLI or alternative), manages isolated workspaces, and reports results back. Teams manage work; the orchestrator handles execution.

## Tech Stack

| Layer | Technology |
|-------|-----------|
| Language | Python 3.11+ (strict typing) |
| Package manager | Hatch (pyproject.toml) |
| Testing | pytest + pytest-asyncio + hypothesis (property-based) |
| Linting | ruff |
| Type checking | mypy (strict) |
| HTTP | httpx (client), starlette + uvicorn (server) |
| Templating | Jinja2 |
| Config format | YAML (WORKFLOW.md with front matter) |
| Deployment | Docker / systemd |

## Architecture

```
src/ai_orchestrator/
├── cli.py              # Entry point (ai-orchestrator command)
├── config.py           # Typed config from WORKFLOW.md front matter
├── workflow.py         # WORKFLOW.md parser (YAML + Jinja2 template)
├── models.py           # Data models (Issue, WorkspaceState, etc.)
├── orchestrator.py     # Poll loop, dispatch, concurrency, retries
├── tracker.py          # Abstract tracker interface
├── tracker_orgmylife.py # OrgMyLife adapter (REST API)
├── workspace.py        # Per-issue workspace lifecycle and hooks
├── agent_runner.py     # Codex subprocess integration
├── prompt.py           # Jinja2 prompt rendering
├── http_server.py      # Optional REST API + dashboard
└── watcher.py          # File system watcher for hot-reload

scripts/pat_manager/    # PAT lifecycle management (check, alert, rotate)
├── checker.py          # Token expiry checking
├── alerter.py          # Alert dispatch (OrgMyLife task creation)
├── rotator.py          # Token rotation logic
├── reporter.py         # Status reporting
├── registry.py         # pat-registry.json I/O
├── models.py           # PAT data models
└── errors.py           # Error types
```

## Components

### Orchestrator Core
- **Workflow Loader** — Parses `WORKFLOW.md` (YAML front matter + Jinja2 prompt template)
- **Config Layer** — Typed getters, defaults, env var resolution (`$VAR_NAME`), validation
- **Tracker Client** — OrgMyLife REST adapter with pagination and state mapping
- **Orchestrator** — Poll loop, task dispatch, concurrency limits, retry with backoff
- **Workspace Manager** — Per-issue workspace creation, hooks, cleanup
- **Agent Runner** — Codex app-server subprocess integration
- **HTTP Server** — REST API (`/api/v1/state`) and dashboard for observability

### PAT Manager
- **Checker** — Reads pat-registry.json, calculates days until expiry
- **Alerter** — Creates OrgMyLife tasks for expiring/expired tokens, deduplicates
- **Rotator** — Automated token rotation (where supported)
- **Reporter** — Generates status reports

## Configuration

The orchestrator reads `WORKFLOW.md` in the working directory. Format:

```yaml
---
tracker:
  kind: orgmylife
  endpoint: https://api.andreknie.de
  api_key: $ORGMYLIFE_API_SECRET
polling:
  interval_ms: 30000
workspace:
  root: ~/ai_orchestrator_workspaces
agent:
  max_concurrent_agents: 3
  max_turns: 15
codex:
  command: codex app-server
  approval_policy: auto-edit
---

<Jinja2 prompt template>
```

## Conventions

- All source in `src/ai_orchestrator/` (installed as package)
- Tests in `tests/` — mirror source structure with `test_` prefix
- Property-based tests use `_properties` suffix (e.g., `test_alerter_properties.py`)
- PAT manager scripts in `scripts/pat_manager/` (standalone, own requirements.txt)
- File naming: snake_case for Python modules
- Config via environment variables (prefixed as needed) or WORKFLOW.md

## Rules

1. Never store secrets in code — use env vars or `.secrets` file.
2. All tracker interactions go through the abstract `Tracker` interface.
3. Property-based tests (hypothesis) for all domain logic.
4. Async by default for I/O operations.
5. Typed models for all data transfer (no raw dicts at boundaries).
6. PAT manager must deduplicate alerts (check existing tasks before creating new ones).

## Current State

- Orchestrator core: implemented (poll, dispatch, workspace, agent runner)
- OrgMyLife tracker adapter: implemented
- PAT manager: fully implemented + tested (checker, alerter, rotator, reporter)
- HTTP server: implemented
- Deployment: Docker + docker-compose ready, systemd pending
- Blocked: needs Codex CLI or alternative agent installed on target server