DevAgent Hub

Canonical workflow orchestrator for the DevAgent stack.

Maturity

Public alpha. Hub is the orchestrator and operator CLI for the validated DevAgent-only path.

Hub owns issue import, workflow state, task generation, approvals, persistence, operator CLI surfaces, and PR handoff. It does not launch executors directly. Hub resolves an ExecutorSpec, submits an SDK request to devagent-runner, ingests normalized events/results/artifacts, and drives the staged workflow around them.

Validated Path

The production-grade MVP path is:

devagent-hub -> devagent-runner -> devagent execute --request ... --artifact-dir ...

Current live-validated executor settings:

• executor: devagent
• provider: chatgpt
• model: gpt-5.4

Other runner adapters (codex, claude, opencode) are present and smoke-tested, but still experimental.

Canonical Flow

GitHub issue
  -> triage
  -> plan
  -> approval
  -> implement
  -> verify
  -> review
  -> repair loop (if review is not clean, up to repair.max_rounds)
  -> approval before PR
  -> PR handoff

Hub also enforces review blast-radius controls from WORKFLOW.md:

• review.max_changed_files
  • if exceeded after implement or repair, Hub pauses for manual approval
• review.run_max_changed_files
  • if exceeded, Hub stops automatic continuation and marks the workflow failed with an explicit reason
• review.max_patch_bytes
  • if exceeded after implement or repair, Hub pauses for manual approval
• review.run_max_patch_bytes
  • if exceeded, Hub stops automatic continuation and marks the workflow failed with an explicit reason

Bootstrap Local Development

Hub is the canonical bootstrap entrypoint for the four sibling repos.

Expected layout:

<workspace-root>/
  devagent-sdk/
  devagent-runner/
  devagent/
  devagent-hub/

Bootstrap from the devagent-hub repo root:

bun install
bun run bootstrap:local

That script:

• verifies the sibling checkout layout
• clones missing sibling repos from the pinned baseline manifest
• checks out main in all four repos
• runs install/build in dependency order
• links the local CLIs so these commands are ready:
  • devagent
  • devagent-runner
  • devagent-hub

The installed devagent-hub wrapper now boots through Node so the Hub CLI can safely use better-sqlite3 even when Bun is the package manager for the repo.

CLI

devagent-hub project add
devagent-hub issue sync
devagent-hub run start --issue 42
devagent-hub run resume <workflow-id>
devagent-hub run reject <workflow-id> --note "expand rollback notes"
devagent-hub run cancel <workflow-id>
devagent-hub pr open <workflow-id>
devagent-hub pr repair <workflow-id>
devagent-hub list
devagent-hub status <workflow-id>
devagent-hub status <workflow-id> --json

Hub state lives under ~/.config/devagent-hub by default. To isolate Hub state without changing auth discovery for gh or devagent, set DEVAGENT_HUB_CONFIG_DIR=/path/to/hub-state.

Review The Plan

When a workflow pauses after plan, you do not need to scrape logs. Use status.

Example:

devagent-hub run start --issue 42
devagent-hub status <workflow-id>

Default status output shows:

• workflow id
• current stage and status
• whether approval is pending
• latest artifact paths, including plan.md
• latest result or failure
• next recommended operator action

Typical output looks like:

Workflow: 123e4567-e89b-12d3-a456-426614174000
Issue: #42 Fix run detail header
Stage: plan
Status: waiting_approval
Approval pending: yes (plan)
Status reason: none
Latest result: plan: success
Artifacts:
  plan: .devagent-runner/artifacts/task-42/plan.md
Approvals:
  plan: pending
Next action: Review the plan artifact, then run: devagent-hub run resume 123e4567-e89b-12d3-a456-426614174000

If the workflow is paused after plan, review the artifact directly:

cat .devagent-runner/artifacts/<task-id>/plan.md

Or use the exact path printed by devagent-hub status <workflow-id>.

Then choose:

devagent-hub run resume <workflow-id>

or:

devagent-hub run reject <workflow-id> --note "expand rollback notes and split migration from implementation"

How feedback is used:

• a rejected plan note becomes input to the next plan attempt
• the rerun pauses again so a human can re-review the updated plan

Use status --json only for scripts or external tooling. The default text output is the intended operator view.

If the target repo does not contain WORKFLOW.md, Hub now infers safe defaults for Bun/Node and Python repos and prints the inferred verify commands into the early workflow context. If it cannot infer a safe profile, it fails fast and asks the operator to add WORKFLOW.md.

Review Before PR

After implement -> verify -> review completes cleanly, Hub pauses again before PR handoff.

Use:

devagent-hub status <workflow-id>

Review the latest:

• verification-report.md
• review-report.md
• implementation-summary.md

Then either open the PR:

devagent-hub pr open <workflow-id>

or reject and request more fixes:

devagent-hub run reject <workflow-id> --note "address security concerns before PR handoff"

How feedback is used:

• a rejected final approval note becomes input to the next repair
• Hub then reruns repair -> verify -> review and pauses again

When implement or repair reports success but produces no repository changes, Hub retries once with stronger instructions. For devagent, that retry resumes the previous session context so the follow-up run can continue from the earlier analysis instead of starting cold.

Post-PR Feedback

For an already-open PR, use:

devagent-hub pr repair <workflow-id>

Hub fetches:

• GitHub review comments
• file/line context when GitHub provides it
• failing CI logs

That feedback becomes the next repair request context, together with changed-file hints and the latest review-report / verification-report.

After repair succeeds, Hub reruns:

repair -> verify -> review

and pushes the updated branch.

Local Development Wiring

This repo currently consumes local packages through file dependencies:

• @devagent-sdk/* from ../devagent-sdk
• @devagent-runner/* from ../devagent-runner

That sibling layout is still MVP-only wiring, but the supported local path is now the bootstrap script above rather than ad hoc manual setup.

Development

bun install
bunx tsc --noEmit
bun run test
bun run build
bun run check:oss

Limitations

• the supported contributor path is the four-repo sibling checkout plus bootstrap flow
• only the DevAgent executor path is production-grade
• package publication and a simpler single-repo install story are still evolving

Additional baseline commands:

bun run baseline:check
bun run baseline:drift
bun run baseline:compat
bun run baseline:smoke

bun run test uses Node-backed Vitest through vitest.config.ts because the canonical store is built on better-sqlite3, and local validation output under .devagent-runner/ is excluded from discovery.

Validation

The pinned release-candidate baseline is recorded in baseline.json, the full operator checklist lives in BASELINE_VALIDATION.md, and the current 3-loop reliability bar is tracked in docs/validation-ledger.md.

See WORKFLOW.md for repo-local workflow configuration semantics, including review size limits and human approval behavior.