agentboard-harness

name	agentboard-harness
description	Use when the user asks Codex to operate AgentBoard, run AgentBoard slash-command-like workflows, use AgentBoard as a Codex/Claude/OpenCode harness, or move product docs through analyze, clarify, design, plan, run, QA, and change stages with the local AgentBoard CLI.

AgentBoard Harness

Use this skill to drive the local agentboard CLI from Codex. Treat AgentBoard as the source of workflow state: projects, sources, artifacts, approvals, issues, run logs, QA, and change requests live under .agentboard/.

First Steps

1. Locate the repo root. Prefer the current workspace if it contains cmd/agentboard/main.go or an executable ./agentboard.
2. Use plugins/agentboard-harness/scripts/agentboard.sh as the CLI wrapper when possible. It uses AGENTBOARD_BIN, ./agentboard, or go run ./cmd/agentboard.
3. Run agentboard status or agentboard project create depending on whether a project already exists.
4. Ask the user only when the project slug or source path cannot be inferred safely.

Slash-Style Command Map

Codex does not need native slash command registration to run these. Interpret user text like /agentboard:plan rfq-platform as the matching CLI action.

• /agentboard:init -> agentboard init
• /agentboard:create "Name" -> agentboard project create "Name"
• /agentboard:source <path> --project <slug> -> agentboard source add <path> --project <slug>
• /agentboard:analyze <slug> -> agentboard analyze <slug>
• /agentboard:clarify <slug> -> agentboard clarify <slug>
• /agentboard:design <slug> -> agentboard design <slug>
• /agentboard:plan <slug> -> agentboard plan <slug>
• /agentboard:issues <slug> -> agentboard issue list --project <slug>
• /agentboard:ready <issue> -> agentboard issue ready <issue>
• /agentboard:run <issue> -> agentboard run --issue <issue>
• /agentboard:qa <issue> -> agentboard qa review <issue>
• /agentboard:preview <slug> -> agentboard preview --project <slug> --addr 127.0.0.1:0
• /agentboard:change <slug> "<summary>" -> agentboard change create --project <slug> --summary "<summary>"
• /agentboard:regenerate <change-id> -> agentboard change regenerate <change-id>
• /agentboard:serve -> agentboard serve --addr 127.0.0.1:8787

Stage Agent Setup

For product/design/planning stages, configure AgentBoard to use CLI agents:

agentboard config set-stage-provider cli
agentboard config set-stage-agent product "plugins/agentboard-harness/scripts/codex-stage-agent.sh"
agentboard config set-stage-agent clarify "plugins/agentboard-harness/scripts/codex-stage-agent.sh"
agentboard config set-stage-agent design "plugins/agentboard-harness/scripts/codex-stage-agent.sh"
agentboard config set-stage-agent planner "plugins/agentboard-harness/scripts/codex-stage-agent.sh"
agentboard config set-stage-agent qa "plugins/agentboard-harness/scripts/codex-stage-agent.sh"
agentboard config set-stage-agent change "plugins/agentboard-harness/scripts/codex-stage-agent.sh"

Use claude-stage-agent.sh or opencode-stage-agent.sh instead when the user wants those agents.

AgentBoard writes the generated stage prompt to AGENTBOARD_STAGE_PROMPT and expects the stage command to write the artifact body to stdout. Do not pipe long prompts through ad hoc shell quoting if a wrapper script is available.

Stage agents also receive:

AGENTBOARD_PREVIEW_HOST=127.0.0.1
AGENTBOARD_PREVIEW_PORT=<free-port>
AGENTBOARD_PREVIEW_URL=http://127.0.0.1:<free-port>

Use those variables when a spec, design, or planning agent needs to show temporary HTML prototype options for a human decision. Do not use hard-coded shared ports.

Implementation Runs

Implementation runs are separate from stage generation. Configure the default implementation runner with:

agentboard config set-default codex
agentboard config set-runner codex "codex exec"
agentboard config set-runner claude "claude"
agentboard config set-runner opencode "opencode run"

Then use agentboard run --issue ISS-0001. Check agentboard logs ISS-0001 after each run.

Operating Rules

• Prefer AgentBoard commands over manual edits to .agentboard/ state.
• After changes, inspect artifacts or issues with artifact list/show, issue list, logs, and qa review.
• If a command fails because a binary is missing, report the missing binary and use local template mode only when the user accepts that fallback.
• Keep stage output focused on the artifact requested by AgentBoard; avoid conversational prefaces because stdout becomes the stored artifact.