orchestrator-agent
8ddae78551
Co-authored-by: orchestrator-agent <orchestrator@cubecraftlabs.com> Co-committed-by: orchestrator-agent <orchestrator@cubecraftlabs.com>
75 lines
4.2 KiB
Markdown
75 lines
4.2 KiB
Markdown
# NestQuest controller
|
|
|
|
OpenCode 1.18.31 loads the three named agents from `.opencode/agents/`. Their
|
|
models match the current NestQuest CTXD prompt: DeepSeek V4.1
|
|
Flash for controller and approver, GLM 5.3 Flash for development. The
|
|
controller runs one OpenCode turn at a time, then starts a fresh turn based on
|
|
Maestro, CTXD, Git, and pull-request state. Its state file is
|
|
`~/.local/state/nestquest-controller/last-run.json` (mode 0600). A lock allows
|
|
only one controller process. It waits while an interactive OpenCode session is
|
|
open for the NestQuest checkout.
|
|
|
|
`scripts/nq-agent` launches developer and approver sessions with fixed agent
|
|
definitions and no `--auto` flag. Headless OpenCode runs use `--pure` so the
|
|
global idle-notification plugin does not notify on every controller tick.
|
|
The approver's shell permission permits only the installed
|
|
`nq-approve-merge` broker for Gitea. That broker requires exact-head
|
|
Claude approval evidence, an exact-head Gitea approval by `review_agent`,
|
|
the `dev` target, a mergeable PR, and passing configured checks before it
|
|
requests a squash merge with Gitea's atomic `head_commit_id` guard.
|
|
`scripts/nq-review` launches the independent
|
|
Claude review in a noninteractive read-only session in the task worktree,
|
|
checks the head again afterward, saves
|
|
the output under `/tmp/opencode`, and posts the Gitea approval.
|
|
The approver verifies the reviewed head again before a merge.
|
|
|
|
The production service uses a stable copy of this configuration and scripts
|
|
at `/home/overseer/.local/share/nestquest-controller`; it does not depend on
|
|
which task branch is checked out in the primary NestQuest directory. Install
|
|
that copy, run `scripts/nq-controller --check`, and verify all four OpenCode
|
|
agents (orchestrator, developer, approver, cycle-control)
|
|
with `opencode debug agent <name>` while `OPENCODE_CONFIG_DIR` points at the
|
|
installed `.opencode` directory. Install `deploy/nestquest-controller.service`
|
|
under `~/.config/systemd/user/` and reload the user manager. Its lack of an
|
|
`[Install]` section makes it a manual-only unit; development starts only
|
|
when requested. Copy `deploy/opencode-global-commands/*.md` into
|
|
`~/.config/opencode/commands/` and `.opencode/agents/cycle-control.md` into
|
|
`~/.config/opencode/agents/` for the commands to work from older branches.
|
|
The host has lingering
|
|
enabled for the `overseer` user. The service waits for an open interactive
|
|
NestQuest session to close before starting work.
|
|
|
|
In NestQuest's OpenCode session, use `/start-development`,
|
|
`/stop-development`, or `/development-status`. The matching global
|
|
`/start-nestquest-development`, `/stop-nestquest-development`, and
|
|
`/nestquest-development-status` commands work even while an older branch is
|
|
checked out. Starting the unit in an interactive NestQuest session puts it
|
|
in a waiting state; close that session to let the first controller tick run.
|
|
The commands call `scripts/nq-cycle`; they do not run a developer inside
|
|
the interactive chat.
|
|
|
|
`templates/ORCHESTRATOR-PROMPT.template.md` and
|
|
`templates/nestquest.profile.json` make the current CTXD cycle prompt
|
|
adaptable to another project. See `templates/README.md` before publishing a
|
|
rendered prompt for a new project.
|
|
|
|
The CTXD preflight reads the configured HTTP/MCP server's NestQuest prompt.
|
|
It deliberately does not inspect `/home/overseer/.ctx/ctxd.db`, which belongs
|
|
to a different local store and lacks this project.
|
|
|
|
All four agent credentials are currently readable by the same Unix account.
|
|
The Gitea review and merge gates enforce normal workflow sequencing, but
|
|
they are not a hard isolation boundary against a process running as that
|
|
account. Strong isolation requires separate OS identities and protected
|
|
credentials for the controller, reviewer, and approver.
|
|
|
|
A tick has an explicit six-hour timeout. On timeout or an OpenCode error, the
|
|
next tick must reconcile external state before acting. Three consecutive
|
|
failed ticks stop the service. A BLOCKED verdict also stops it. QUIESCENT
|
|
causes a five-minute poll. Neither a feature merge nor a progress report
|
|
stops the controller while eligible work remains.
|
|
|
|
Do not put tokens in this repository or in unit files. Existing OpenCode MCP
|
|
connections supply CTXD and Maestro. Rotate those MCP tokens as a coordinated
|
|
operation across every consumer before revoking the old values.
|