@datatamer.ai/agentdev 1.0.1

package/README.md

@@ -0,0 +1,283 @@
+# AgentDev CLI
+
+Distributed agent client for processing GitHub tickets autonomously. Agents poll a central server for work, claim tickets from a GitHub Projects board, execute them using Claude Code, and report results back.
+
+## Installation
+
+```bash
+cd packages/agentdev-client
+npm install
+npm link   # Makes `agentdev` available globally
+```
+
+**Prerequisites:** Node.js >= 18, Claude Code CLI (`claude`) installed and authenticated.
+
+## Quick Start
+
+```bash
+# 1. Register with the AgentDev platform
+agentdev register -u https://agentdev.datatamer.ai
+
+# 2. Start processing tickets (cron mode, 1-minute interval)
+agentdev cron --interval 1
+
+# 3. Or run as a continuous daemon
+agentdev start
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  AgentDev WebUI (agentdev-webui/)                       │
+│  ├── GitHub Projects board integration                  │
+│  ├── SSE real-time ticket/log streaming                 │
+│  └── REST API for agent communication                   │
+└────────────────────┬────────────────────────────────────┘
+                     │ HTTP (heartbeat, claim, logs, complete)
+┌────────────────────▼────────────────────────────────────┐
+│  AgentDev Client (packages/agentdev-client/)            │
+│  ├── Polls server for tickets to claim                  │
+│  ├── Spawns Claude Code with auto-ticket-workflow skill │
+│  ├── Streams logs back to server in real-time           │
+│  ├── Polls GitHub comments for live instruction updates │
+│  └── Reports completion status                          │
+└────────────────────┬────────────────────────────────────┘
+                     │ spawns
+┌────────────────────▼────────────────────────────────────┐
+│  Claude Code CLI                                        │
+│  ├── Reads ticket from GitHub                           │
+│  ├── Creates OpenSpec, implements, tests, deploys       │
+│  └── Moves ticket through board columns                 │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Commands
+
+### `agentdev register`
+
+Register this machine as an agent with the AgentDev platform.
+
+```bash
+agentdev register [-u, --url <url>] [-n, --name <name>]
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-u, --url` | `https://agentdev.datatamer.ai` | WebUI server URL |
+| `-n, --name` | system hostname | Agent display name |
+
+Performs OAuth device flow authentication, saves agent token and GitHub project board configuration to `~/.config/agentdev/config.json`.
+
+### `agentdev start`
+
+Run as a continuous daemon that polls for work every 10 seconds.
+
+```bash
+agentdev start [-c, --concurrent <number>]
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-c, --concurrent` | `1` | Max concurrent tickets (currently sequential) |
+
+On startup, scans the GitHub Projects board for leftover tickets (In Progress, test status) and resumes them before polling the server for new work.
+
+### `agentdev cron`
+
+Run in batch mode — process all available tickets per cycle, then sleep.
+
+```bash
+agentdev cron [-i, --interval <minutes>] [-m, --max-tickets <number>]
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-i, --interval` | `5` | Minutes between polling cycles |
+| `-m, --max-tickets` | `10` | Max tickets to process per cycle |
+
+Same leftover-ticket scan as `start` on startup. Preferred mode for running as a background process:
+
+```bash
+# Start as background process
+nohup agentdev cron --interval 1 > /tmp/agentdev-cron.log 2>&1 &
+
+# Monitor logs
+tail -f /tmp/agentdev-cron.log
+```
+
+### `agentdev status`
+
+Show agent registration status and configuration.
+
+```bash
+agentdev status
+```
+
+### `agentdev config`
+
+Read or write configuration values.
+
+```bash
+agentdev config get              # Show all config
+agentdev config get <key>        # Show specific key
+agentdev config set <key> <value>
+```
+
+Config is stored at `~/.config/agentdev/config.json`. Keys include:
+
+| Key | Description |
+|-----|-------------|
+| `api_url` | AgentDev server URL |
+| `agent_token` | Auth token (set by register) |
+| `agent_id` | Agent identifier (set by register) |
+| `agent_name` | Display name |
+| `github_org` | GitHub organization (`data-tamer`) |
+| `project_id` | GitHub Projects v2 node ID |
+| `project_number` | GitHub Projects board number |
+| `status_field_id` | Projects status field ID |
+| `status_options` | Map of status column option IDs (`TODO`, `IN_PROGRESS`, `TEST`, `DONE`) |
+
+### `agentdev ticket create`
+
+Create a GitHub issue and add it to the project board as Todo.
+
+```bash
+agentdev ticket create -R <repo> --title <title> [--body <body>] [--body-file <file>] [--no-claude] [--json]
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-R, --repo` | required | Repository name (under the configured org) |
+| `--title` | required | Issue title |
+| `--body` | `""` | Issue body text |
+| `--body-file` | — | Read body from file |
+| `--claude` | `true` | Append `@claude` tag to body |
+| `--no-claude` | — | Do not append `@claude` tag |
+| `--json` | — | Output as JSON |
+
+The `@claude` tag in the issue body is what triggers the agent to pick up the ticket.
+
+### `agentdev gh`
+
+GitHub CLI compatible commands. Drop-in replacement for `gh` so agent skills can use `agentdev gh` without requiring a separate `gh` installation.
+
+```bash
+# Issues
+agentdev gh issue view <number> -R <owner/repo> [--json <fields>]
+agentdev gh issue create -R <owner/repo> --title <title> [--body <body>]
+agentdev gh issue comment <number> -R <owner/repo> --body <body>
+agentdev gh issue reopen <number> -R <owner/repo>
+
+# Pull Requests
+agentdev gh pr create -R <owner/repo> --title <title> --head <branch> --base <branch> [--body <body>]
+agentdev gh pr view <number> -R <owner/repo> [--json <fields>]
+agentdev gh pr merge <number> -R <owner/repo> [--squash | --merge | --rebase]
+
+# Project Board
+agentdev gh project item-edit --id <id> --project-id <pid> --field-id <fid> --single-select-option-id <oid>
+
+# Workflow Runs
+agentdev gh run view <ref> -R <owner/repo>    # View CI status for a commit/branch
+agentdev gh run watch <ref> -R <owner/repo>   # Poll until CI completes
+
+# API (raw)
+agentdev gh api graphql -f query='...'
+agentdev gh api rest <path> [-X <method>] [--input <file>]
+```
+
+All `gh` commands require `GH_TOKEN` environment variable (automatically set from server OAuth tokens when running via `start`/`cron`).
+
+### `agentdev openspec`
+
+Wraps the `@fission-ai/openspec` CLI. Available subcommands:
+
+```bash
+agentdev openspec init [--tools <tools>] [--force]
+agentdev openspec list [--specs] [--sort <order>] [--json]
+agentdev openspec show [item] [--type <type>] [--json] [--deltas-only] [--requirements]
+agentdev openspec validate [item] [--all] [--changes] [--specs] [--strict] [--json]
+agentdev openspec status [--change <name>] [--json]
+agentdev openspec instructions <artifact> [--change <name>] [--json]
+agentdev openspec archive [change] [-y] [--skip-specs]
+agentdev openspec run [args...]   # Catch-all for any openspec subcommand
+```
+
+Resolves the `openspec` binary from agentdev's own `node_modules`, falling back to a global install.
+
+### `agentdev onboard`
+
+Interactive repo discovery and environment skill generation. Scans a workspace for git repos, detects languages/frameworks/databases, and generates Claude Code skill files.
+
+```bash
+agentdev onboard [-w, --workspace <path>] [--no-claude] [--force]
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-w, --workspace` | `cwd` | Workspace root to scan |
+| `--no-claude` | — | Use template generation instead of Claude |
+| `--force` | — | Overwrite existing skills |
+
+Generates `.claude/commands/env-<name>.md` skill files and `.claude/repo-spec.json` per repo.
+
+### `agentdev render`
+
+Render Remotion video compositions. Self-contained — uses Remotion from agentdev's own `node_modules`, no need for the target project to have Remotion installed.
+
+```bash
+agentdev render <name> [--output <path>]
+```
+
+| Argument | Composition ID | Output |
+|----------|---------------|--------|
+| `chat` | `ChatWithData` | `public/videos/chat-with-data.mp4` |
+| `topics` | `OrganizeTopics` | `public/videos/organize-topics.mp4` |
+| `artifacts` | `ManageArtifacts` | `public/videos/manage-artifacts.mp4` |
+| `all` | all three above | sequentially |
+
+| Option | Description |
+|--------|-------------|
+| `--output <path>` | Override output path (single composition only, not with `all`) |
+
+**Convention:** Run from the project root that contains `remotion/index.ts` as the entry point and `public/` for static assets. Outputs default to `public/videos/`.
+
+```bash
+cd /path/to/datatamer.ai/app
+agentdev render chat                        # Render single composition
+agentdev render all                         # Render all three
+agentdev render chat --output /tmp/test.mp4 # Custom output path
+```
+
+## Ticket Execution Flow
+
+When a ticket is claimed (via `start` or `cron`), the executor:
+
+1. **Configures environment** — sets `GH_TOKEN`, `TICKET_NUMBER`, `REPO`, `AGENT_ID`, `COMMENT_SIGNAL_FILE`
+2. **Loads the workflow skill** — reads `skills/auto-ticket-workflow.md` and injects it into the Claude prompt
+3. **Spawns Claude Code** — runs `claude -p --dangerously-skip-permissions --output-format stream-json --verbose` with the full prompt
+4. **Streams logs** — tails the output file, parses stream-json, uploads log batches to the server every 2 seconds
+5. **Polls for stop signals** — checks the server every 5 seconds for user-requested stops
+6. **Polls GitHub comments** — every 10 seconds, writes new comments to a signal file so Claude can read mid-execution instruction updates
+7. **Reports completion** — sends success/failure status to the server
+
+## Server API Endpoints
+
+The agent client communicates with the AgentDev WebUI server:
+
+| Method | Endpoint | Purpose |
+|--------|----------|---------|
+| `POST` | `/api/agent/heartbeat` | Send agent status (idle/busy) every 30s |
+| `GET` | `/api/agent/oauth` | Fetch GitHub OAuth tokens |
+| `GET` | `/api/agent/work` | Claim next available ticket |
+| `POST` | `/api/agent/logs` | Upload log batch |
+| `POST` | `/api/agent/complete` | Mark ticket as done |
+| `POST` | `/api/agent/ensure-ticket` | Upsert ticket in DB (for leftover resumption) |
+| `GET` | `/api/agent/should-stop` | Check if stop was requested |
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `CLAUDE_BIN` | Path to Claude Code CLI binary | `claude` |
+| `GH_TOKEN` | GitHub token (auto-configured from server OAuth) | — |