Skip to content

quickstart.md

Latest commit

 

History

History
256 lines (197 loc) · 7.41 KB

quickstart.md

File metadata and controls

256 lines (197 loc) · 7.41 KB

Quickstart

This is the fastest way to run Siegclaw with OpenCode as the coding engine.

1. Prerequisites

Install:

  • Rust (stable)
  • git
  • python3
  • node + npm
  • github-mcp-server (for real GitHub MCP runs outside Docker):
    • go install github.com/github/github-mcp-server/cmd/github-mcp-server@latest

Build:

cargo build

2. Smoke Test with Mock Jira

cargo run -- --init-prompt "read jira ticket TEST-1 and do the work" --mcp-config mcp.mock-jira.json --flow flows/jira-flow

This validates:

  • Jira MCP connectivity
  • request parsing and repo extraction
  • local OpenCode server spawn + health check
  • default OpenCode config creation (permission: "allow") when no config is provided
  • supervision flow

Validate a flow pack without running OpenCode:

cargo run -- doctor --flow flows/jira-flow --mcp-config mcp.mock-jira.json

3. Real Run (Jira + GitHub MCP)

  1. Prepare MCP config:
cp mcp.example.json mcp.json
# edit mcp.json with real Jira/GitHub MCP settings

Note:

  • Jira/GitHub MCP tools are owned and called directly by OpenCode.
  • You do not need Siegclaw-side GitHub MCP orchestration for the standard flow.
  • For fine-grained GitHub PAT, use:
    • Contents: Read and write
    • Pull requests: Read and write
    • Metadata: Read-only
  1. Provide OpenCode auth/config (choose one approach):
export OPENCODE_AUTH_JSON_PATH=/path/to/auth.json
export OPENCODE_CONFIG_JSON_PATH=/path/to/opencode.json

or:

export OPENCODE_AUTH_JSON='{"...":"..."}'
export OPENCODE_CONFIG_JSON='{"...":"..."}'
  1. Run:
./target/debug/siegclaw --init-prompt "read jira ticket YOUR-123 and do the work" --mcp-config mcp.json --flow flows/jira-flow

4. Docker Run

Build image:

docker build -t siegclaw:dev .

Run:

docker run --rm -it \
  -v "$PWD":/workspace \
  -w /workspace \
  -e OPENCODE_URL=http://127.0.0.1:4096 \
  -e OPENCODE_AUTH_JSON_PATH=/workspace/secret/auth.json \
  -e OPENCODE_CONFIG_JSON_PATH=/workspace/secret/opencode.json \
  siegclaw:dev --init-prompt "read jira ticket YOUR-123 and do the work" --mcp-config /workspace/mcp.json --flow /workspace/flows/jira-flow

Alternative: transient workspace (recommended for clean reruns)

docker run --rm -it \
  -v "$PWD/mcp.json":/run/config/mcp.json:ro \
  -v "$PWD/flows":/run/flows:ro \
  -v "$PWD/mock":/run/mock:ro \
  -v "$HOME/.local/share/opencode/auth.json":/run/secret/auth.json:ro \
  -v "$HOME/.config/opencode/opencode.json":/run/secret/opencode.json:ro \
  -w /run \
  -e OPENCODE_AUTH_JSON_PATH=/run/secret/auth.json \
  -e OPENCODE_CONFIG_JSON_PATH=/run/secret/opencode.json \
  siegclaw:dev --init-prompt "read jira ticket YOUR-123 and do the work" --workdir /workspace --mcp-config /run/config/mcp.json --flow /run/flows/jira-flow

Why:

  • Avoids stale workspace state across runs.
  • Keeps each run isolated.
  • Relative paths in mcp.json are resolved against mcp.json parent directory when the paths exist.

5. Useful Flags

--workdir /workspace
--init-prompt "read jira ticket TEST-1 and do the work"
--mcp-config mcp.json
--flow /path/to/flow/dir
--soul /path/to/soul.md
--skills-dir /path/to/skills
--max-iterations 6
--opencode-url http://127.0.0.1:4096
--opencode-session-id SESSION_ID
--opencode-agent AGENT
--opencode-model MODEL
--opencode-stream-events
--opencode-stream-heartbeat
--log-prompts
--opencode-home /path/to/opencode/home
--opencode-auth-json '{...}'
--opencode-auth-json-path /path/to/auth.json
--opencode-config-json '{...}'
--opencode-config-json-path /path/to/opencode.json

Soul Prompt Customization

--soul points to the global cross-flow system prompt file. Siegclaw supports template variables in this file:

  • {{REQUEST_ID}}
  • {{REQUEST_SUMMARY}}
  • {{REQUEST_DESCRIPTION}}
  • {{WORKDIR}}

Example:

Validation policy:
- Never mark compile/tests as passed unless actually observed.

Flow Packs

--flow is required.

--flow /path/to/flow/dir

Example in this repo:

Flow packs can now scope step capabilities directly in flow.json:

  • flow-wide default agent
  • flow-wide / step-local skills
  • optional flow-defined agents for specialist nested-agent definitions
  • flow-wide / step-local allowed_subagents
  • step-local bind exports into controller state
  • step-local controller verification

Example shipped packs:

  • flows/jira-flow for ticket -> code -> PR workflows
  • flows/deploy-flow for SSH-backed deployment workflows with controller probes
  • flows/k8s-deploy-flow for Kubernetes rollout workflows with kubectl + HTTP postcondition checks

Verification can now be composed with all, any, and when, so flows can describe success as controller-observable postconditions instead of fixed Rust logic.

This lets a flow choose the main OpenCode agent per step while keeping skill and delegation guidance close to the workflow definition. Flow-local skills can live under <flow>/skills. Flow-defined specialist agents can live under <flow>/agents.

--flow /workspace/flows/jira-flow

Validate a flow pack without running OpenCode:

siegclaw doctor --flow /workspace/flows/k8s-deploy-flow --mcp-config mcp.json

Schema reference:

Flow pack contents:

  • flow.json (canonical JSON flow definition)
  • optional policy.md (referenced via policy_prompt)
  • prompt files referenced by flow.json
  • optional skills/ directory for flow-local skill definitions
  • optional agents/ directory for flow-defined specialist agent definitions
  • reference flow in this repo: flows/jira-flow/flow.json

Flow wiring in flow.json:

  • steps: ordered dynamic step list (you can use any step names)
  • each step block supports:
    • system (optional)
    • first (required)
    • retry (optional)
    • response_marker (optional)
    • response_json_template (optional)
  • max_attempts controls retries per step (if omitted, --max-iterations is used)

Prompt layering:

  1. soul.md for global cross-flow invariants
  2. policy.md for flow-wide rules (including PR title + repository target policy for this flow)
  3. prompt files referenced by each step block in flow.json

6. Success/Failure

  • Exit 0: completed (validation + workflow criteria satisfied)
  • Exit non-zero: workflow failed

Validation used by controller loop:

  • if a step defines response_json_template, Siegclaw enforces it.
  • if a step defines verification, Siegclaw must also prove those postconditions before advancing.
  • if a step omits response_json_template, Siegclaw does not require structured JSON for that step.
  • marker/template instructions are auto-injected into the step prompt.

Log source tags to watch:

  • OPENCODE, MCP, AGENT, CORE

OpenCode live activity is emitted as:

  • OPENCODE with event=stream_activity
  • OPENCODE with event=session_usage_summary (final aggregate token usage right before OpenCode server shutdown)

Default behavior:

  • no OpenCode stream event logs
  • no heartbeat spam (session.idle, session.busy, session.diff)
  • no rendered prompt dumps

If you want OpenCode stream activity logs, add:

  • --opencode-stream-events

If you want heartbeat activity too, add both:

  • --opencode-stream-events
  • --opencode-stream-heartbeat

If you want to dump full rendered prompts per step attempt, add:

  • --log-prompts

Common note:

  • OpenCode now performs Jira/GitHub MCP actions directly; Siegclaw only supervises loop and local validation criteria.