@vexdo/cli 0.1.0

package/.eslintrc.json

@@ -0,0 +1,23 @@
+{
+  "root": true,
+  "env": {
+    "node": true,
+    "es2022": true
+  },
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "project": "./tsconfig.json",
+    "sourceType": "module"
+  },
+  "plugins": ["@typescript-eslint"],
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/strict-type-checked",
+    "plugin:@typescript-eslint/stylistic-type-checked",
+    "prettier"
+  ],
+  "rules": {
+    "@typescript-eslint/consistent-type-imports": "error"
+  },
+  "ignorePatterns": ["dist", "bin/*.js"]
+}

package/.github/workflows/ci.yml

@@ -0,0 +1,84 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - '**'
+    tags:
+      - 'v*'
+  pull_request:
+
+jobs:
+  lint-typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18
+      - uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: npm-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
+          restore-keys: |
+            npm-${{ runner.os }}-
+      - run: npm ci
+      - run: npm run typecheck
+      - run: npm run lint
+
+  test:
+    runs-on: ubuntu-latest
+    needs: lint-typecheck
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18
+      - uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: npm-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
+          restore-keys: |
+            npm-${{ runner.os }}-
+      - run: npm ci
+      - run: npm run test:coverage
+
+  build:
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18
+      - uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: npm-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
+          restore-keys: |
+            npm-${{ runner.os }}-
+      - run: npm ci
+      - run: npm run build
+      - run: test -n "$(find dist -mindepth 1 -maxdepth 1 -print -quit)"
+
+  release:
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    needs: [lint-typecheck, test, build]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18
+          registry-url: https://registry.npmjs.org
+      - uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: npm-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
+          restore-keys: |
+            npm-${{ runner.os }}-
+      - run: npm ci
+      - run: npm run build
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.idea/copilot.data.migration.ask2agent.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="Ask2AgentMigrationStateService">
+    <option name="migrationStatus" value="COMPLETED" />
+  </component>
+</project>

package/.idea/go.imports.xml

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="GoImports">
+    <option name="excludedPackages">
+      <array>
+        <option value="github.com/pkg/errors" />
+        <option value="golang.org/x/net/context" />
+      </array>
+    </option>
+  </component>
+</project>

package/.idea/misc.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectRootManager" version="2" languageLevel="JDK_24" default="true" project-jdk-name="openjdk-24" project-jdk-type="JavaSDK">
+    <output url="file://$PROJECT_DIR$/out" />
+  </component>
+</project>

package/.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/vexdo-cli.iml" filepath="$PROJECT_DIR$/.idea/vexdo-cli.iml" />
+    </modules>
+  </component>
+</project>

package/.idea/vcs.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="" vcs="Git" />
+    <mapping directory="$PROJECT_DIR$" vcs="Git" />
+  </component>
+</project>

package/.idea/vexdo-cli.iml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="JAVA_MODULE" version="4">
+  <component name="NewModuleRootManager" inherit-compiler-output="true">
+    <exclude-output />
+    <content url="file://$MODULE_DIR$" />
+    <orderEntry type="inheritedJdk" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+</module>

package/.prettierrc

@@ -0,0 +1,5 @@
+{
+  "singleQuote": true,
+  "trailingComma": "all",
+  "printWidth": 100
+}

package/CLAUDE.md

@@ -0,0 +1,93 @@
+# CLAUDE.md
+
+## 1) Project overview
+
+`vexdo` is a task orchestrator CLI for multi-service repositories. The core flow is: load task + config, run Codex for each step, run Claude reviewer + arbiter loop, then submit PRs or escalate.
+
+## 2) Architecture
+
+Dependency direction should stay:
+
+```text
+types  ←  lib  ←  commands  ←  index.ts
+```
+
+Key invariants:
+- `commands/` may exit process; `lib/` should generally return errors.
+- `lib/` is reusable orchestration/integration logic.
+- `types/` stays free of runtime dependencies.
+- Reviewer and arbiter must run with isolated contexts/data.
+
+## 3) Key files and roles
+
+```text
+src/
+  index.ts                  # commander bootstrap, global flags, command wiring
+  commands/
+    init.ts                 # interactive bootstrap (`vexdo init`)
+    start.ts                # primary task execution flow
+    review.ts               # rerun review loop on active step
+    fix.ts                  # feed corrective prompt to Codex then review
+    submit.ts               # PR creation and state completion
+    abort.ts                # cancel task, preserve branches
+    status.ts               # print active state
+    logs.ts                 # print iteration logs
+  lib/
+    config.ts               # .vexdo.yml discovery + validation
+    tasks.ts                # task loading/validation and lane moves
+    state.ts                # active state persistence
+    review-loop.ts          # reviewer/arbiter loop control
+    claude.ts               # Anthropic SDK wrapper
+    codex.ts                # codex CLI wrapper
+    gh.ts                   # gh CLI wrapper for PRs
+    git.ts                  # git operations
+    logger.ts               # output formatting
+    requirements.ts         # env/runtime checks
+  prompts/
+    reviewer.ts             # reviewer prompt construction
+    arbiter.ts              # arbiter prompt construction
+  types/index.ts            # shared type contracts
+```
+
+## 4) Common tasks
+
+### Add a command
+1. Add `src/commands/<name>.ts` with `register<Name>Command`.
+2. Keep parsing and CLI concerns in command file.
+3. Put reusable logic in `lib/`.
+4. Register in `src/index.ts`.
+5. Add tests and README docs.
+
+### Add a lib function
+1. Add function to the nearest `lib/*` module.
+2. Keep signature typed and avoid `any`.
+3. Return errors; avoid process termination.
+4. Add focused unit tests.
+
+### Add a test
+1. Unit tests in `test/unit` or `tests/unit` for isolated behavior.
+2. Integration tests in `test/integration` or `tests/integration` for flow.
+3. Use `vi.mock` for `child_process`, SDKs, and external CLIs.
+
+## 5) Constraints to always enforce
+
+- No `any` in new code.
+- Keep ESM `.js` import specifiers in TS source.
+- No `process.exit` inside `lib/` modules.
+- Do not add `chalk`; use `picocolors` for output styling.
+- Reviewer and arbiter contexts must remain isolated.
+
+## 6) Test conventions
+
+- Prefer mocking at module boundary.
+- `child_process` calls should be mocked with `vi.mock('node:child_process', ...)`.
+- Anthropic SDK behavior should be mocked through `lib/claude.ts` dependencies.
+- Use temp directories for filesystem side effects.
+
+## 7) What not to do
+
+- Do not embed orchestration logic directly in `index.ts`.
+- Do not tightly couple command handlers to specific prompt text.
+- Do not bypass task/config validation.
+- Do not mutate state without persisting through `state.ts` helpers.
+- Do not mix reviewer and arbiter outputs in a single decision context.

package/CONTRIBUTING.md

@@ -0,0 +1,62 @@
+# Contributing to vexdo
+
+## 1) Development setup
+
+```bash
+git clone <repo-url>
+cd vexdo-cli
+npm install
+npm link
+npm test
+```
+
+Useful checks:
+- `npm run typecheck`
+- `npm run lint`
+- `npm run build`
+
+## 2) Project structure
+
+```text
+src/
+  index.ts            # CLI entrypoint and command registration
+  commands/           # User-facing command handlers
+  lib/                # Core orchestration, integrations, and helpers
+  prompts/            # Claude reviewer/arbiter prompt templates
+  types/              # Shared TypeScript types
+test/ + tests/        # Unit and integration tests
+```
+
+## 3) Adding a new command
+
+1. Create `src/commands/<name>.ts`.
+2. Export `register<Name>Command(program: Command)`.
+3. Implement `run<Name>` function and keep side effects inside command layer.
+4. Add registration in `src/index.ts`.
+5. Add unit tests for parsing/behavior and integration tests if command touches git/fs/process.
+6. Update README command docs.
+
+## 4) Testing conventions
+
+- **Unit tests**: isolated logic, heavy mocking (`child_process`, SDK clients, filesystem helpers).
+- **Integration tests**: flow-level behavior and state transitions.
+- Prefer deterministic fixtures and temporary directories.
+- External dependencies (Anthropic, gh, codex) must be mocked in unit tests.
+
+## 5) Commit conventions
+
+- Follow Conventional Commits, e.g.:
+  - `feat: add init command`
+  - `fix: prevent duplicate gitignore entry`
+  - `docs: expand README`
+- PRs should include:
+  - clear summary
+  - tests run
+  - any breaking changes
+
+## 6) Release process
+
+1. Bump version and update changelog/release notes.
+2. Push tag `vX.Y.Z`.
+3. GitHub Actions CI runs lint/typecheck/test/build.
+4. Release job publishes to npm using `NPM_TOKEN`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vexdo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,206 @@
+# vexdo
+
+Automated implementation + review loop for multi-service tasks, powered by Codex and Claude.
+
+![CI](https://github.com/vexdo/vexdo-cli/actions/workflows/ci.yml/badge.svg)
+![npm](https://img.shields.io/npm/v/vexdo)
+![license](https://img.shields.io/npm/l/vexdo)
+![node](https://img.shields.io/node/v/vexdo)
+
+## 1) What is vexdo
+
+`vexdo` is a CLI that turns a task spec into a controlled execution pipeline across one or more services. It applies changes with Codex, reviews with Claude, loops until quality gates are met, and then opens PRs (or escalates when needed).
+
+Real-world example: you need to add a new billing field in API, web, and worker repos. Instead of running separate ad-hoc sessions, you define one `task.yml` with ordered steps and let `vexdo` orchestrate execution + review with traceable state.
+
+## 2) How it works
+
+```text
+task.yml
+   ↓
+vexdo start
+   ↓
+codex exec
+   ↓
+git diff
+   ↓
+claude reviewer
+   ↓
+claude arbiter
+   ↓
+fix loop (max N)
+   ↓
+PR or escalate
+```
+
+## 3) Requirements
+
+- Node.js >= 18
+- `ANTHROPIC_API_KEY` environment variable
+- Codex CLI installed globally:
+  - `npm install -g @openai/codex`
+- GitHub CLI installed:
+  - https://cli.github.com
+
+## 4) Quick start (5 minutes)
+
+```bash
+npm install -g vexdo
+cd my-project
+vexdo init
+# create tasks/backlog/my-task.yml
+vexdo start tasks/backlog/my-task.yml
+```
+
+## 5) Commands
+
+| Command | Description |
+|---|---|
+| `vexdo init` | Initialize `.vexdo.yml`, folders, and `.gitignore` entry. |
+| `vexdo start <task-file> [--resume]` | Start a task and run implementation/review orchestration. |
+| `vexdo review` | Re-run review loop for the current step. |
+| `vexdo fix <feedback>` | Send targeted feedback to Codex, then review again. |
+| `vexdo submit` | Create PRs for active task branches. |
+| `vexdo status` | Show current task state. |
+| `vexdo logs [task-id] [--full]` | Inspect iteration logs. |
+| `vexdo abort [--force]` | Abort active task and move task file back to backlog. |
+
+### Global flags
+
+- `--verbose`: Print debug logs.
+- `--dry-run`: Show actions without making changes.
+
+### Command details
+
+#### `vexdo init`
+Interactive bootstrap wizard:
+- asks service names/paths
+- asks review and model defaults
+- writes `.vexdo.yml`
+- creates `tasks/*` lanes and `.vexdo/logs/`
+- adds `.vexdo/` to `.gitignore` once
+
+#### `vexdo start <task-file>`
+Flags:
+- `--resume`: resume from existing state if present
+
+Behavior:
+- validates config and task
+- creates/checks service branches
+- runs Codex then review loop per step
+- moves task files across lanes (`backlog → in_progress → review/done/blocked`)
+
+#### `vexdo review`
+Runs review + arbiter flow against current step without restarting full task.
+
+#### `vexdo fix <feedback>`
+Runs Codex with your corrective feedback, then re-enters review loop.
+
+#### `vexdo submit`
+Creates PRs for each service branch in the active task and marks task as done.
+
+#### `vexdo status`
+Prints a concise summary of active task id/title/step statuses.
+
+#### `vexdo logs [task-id]`
+Flags:
+- `--full`: include full diffs and complete comment payloads
+
+#### `vexdo abort`
+Flags:
+- `--force`: skip confirmation prompt
+
+## 6) Task YAML format
+
+```yaml
+id: billing-vat-001
+title: "Add VAT ID support"
+depends_on: [] # optional task-level dependencies
+
+steps:
+  - service: api
+    spec: |
+      Add vat_id to organization model, migration, and create/update APIs.
+      Ensure validation rules and API docs are updated.
+
+  - service: web
+    depends_on: [api] # optional per-step ordering dependency
+    spec: |
+      Add VAT ID input to organization settings screen.
+      Integrate with updated API and show validation errors.
+```
+
+Field reference:
+- `id` *(string, required)*: stable slug used for branches and state.
+- `title` *(string, required)*: human-readable name.
+- `depends_on` *(string[], optional)*: coarse dependency marker at task level.
+- `steps` *(array, required)*: ordered units of work.
+  - `service` *(string, required)*: must match `.vexdo.yml` service name.
+  - `spec` *(string, required)*: concrete implementation request for Codex.
+  - `depends_on` *(string[], optional)*: service dependencies before this step starts.
+
+## 7) `.vexdo.yml` format
+
+```yaml
+version: 1
+services:
+  - name: api
+    path: ./api
+  - name: web
+    path: ./web
+
+review:
+  model: claude-haiku-4-5-20251001
+  max_iterations: 3
+  auto_submit: false
+
+codex:
+  model: gpt-4o
+```
+
+Field reference:
+- `version`: config schema version (currently `1`).
+- `services`: list of service roots used by task steps.
+- `review.model`: Claude model for reviewer + arbiter.
+- `review.max_iterations`: hard cap for fix/review loop.
+- `review.auto_submit`: auto-run `submit` after successful review.
+- `codex.model`: model passed to Codex execution.
+
+## 8) Spec format guide
+
+Good specs are:
+- **specific**: list exact files, behaviors, and edge cases.
+- **testable**: include acceptance checks.
+- **constrained**: mention prohibited changes and compatibility limits.
+
+Recommended template:
+
+```text
+Goal:
+Constraints:
+Acceptance criteria:
+- ...
+- ...
+Non-goals:
+```
+
+## 9) Troubleshooting
+
+- **"Not inside a vexdo project"**
+  - Run from a directory containing `.vexdo.yml` (or use `vexdo init`).
+- **Anthropic key errors**
+  - Ensure `ANTHROPIC_API_KEY` is exported in shell/CI.
+- **Codex not found**
+  - Install with `npm install -g @openai/codex` and verify PATH.
+- **`vexdo submit` fails with GitHub auth issues**
+  - Run `gh auth login` and confirm repo access.
+- **Task escalated**
+  - Review `.vexdo/logs/*` and rerun with `vexdo fix "..."`.
+
+## 10) Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## 11) License
+
+MIT.

package/bin/vexdo.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/index.js';

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@vexdo/cli",
+  "version": "0.1.0",
+  "type": "module",
+  "bin": {
+    "vexdo": "./bin/vexdo.js"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:coverage": "vitest run"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.39.0",
+    "@types/js-yaml": "^4.0.9",
+    "commander": "^12.1.0",
+    "js-yaml": "^4.1.1",
+    "ora": "^8.1.1",
+    "picocolors": "^1.1.1",
+    "yaml": "^2.6.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "@typescript-eslint/eslint-plugin": "^8.25.0",
+    "@typescript-eslint/parser": "^8.25.0",
+    "eslint": "^8.57.1",
+    "eslint-config-prettier": "^10.1.1",
+    "prettier": "^3.5.2",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.2",
+    "vitest": "^3.0.8"
+  }
+}

package/src/commands/abort.ts

@@ -0,0 +1,66 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline/promises';
+
+import type { Command } from 'commander';
+
+import { findProjectRoot } from '../lib/config.js';
+import * as logger from '../lib/logger.js';
+import { clearState, loadState } from '../lib/state.js';
+import { ensureTaskDirectory, moveTaskFileAtomically } from '../lib/tasks.js';
+
+export interface AbortOptions { force?: boolean }
+
+function fatalAndExit(message: string): never {
+  logger.fatal(message);
+  process.exit(1);
+}
+
+async function promptConfirmation(taskId: string): Promise<boolean> {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await rl.question(`Abort task ${taskId}? Branches will be kept. [y/N] `);
+    return answer.trim().toLowerCase() === 'y';
+  } finally {
+    rl.close();
+  }
+}
+
+export async function runAbort(options: AbortOptions): Promise<void> {
+  const projectRoot = findProjectRoot();
+  if (!projectRoot) {
+    fatalAndExit('Not inside a vexdo project.');
+  }
+
+  const state = loadState(projectRoot);
+  if (!state) {
+    fatalAndExit('No active task.');
+  }
+
+  if (!options.force) {
+    const confirmed = await promptConfirmation(state.taskId);
+    if (!confirmed) {
+      logger.info('Abort cancelled.');
+      return;
+    }
+  }
+
+  const inProgressDir = path.join(projectRoot, 'tasks', 'in_progress');
+  if (state.taskPath.startsWith(inProgressDir) && fs.existsSync(state.taskPath)) {
+    const backlogDir = ensureTaskDirectory(projectRoot, 'backlog');
+    moveTaskFileAtomically(state.taskPath, backlogDir);
+  }
+
+  clearState(projectRoot);
+  logger.info('Task aborted. Branches preserved for manual review.');
+}
+
+export function registerAbortCommand(program: Command): void {
+  program
+    .command('abort')
+    .description('Abort active task')
+    .option('--force', 'Skip confirmation prompt')
+    .action(async (options: AbortOptions) => {
+      await runAbort(options);
+    });
+}