# Integrations

This document shows recommended integration patterns for `smart-commit-host-agent` in agent skills and shell-first automation.

If you have not run the CLI manually yet, start with [`getting-started.md`](./getting-started.md) first. Integration is much easier after you have already verified `config resolve` and `bridge --review-only`.

## Principles

- Prefer `bridge` as the enforcement entrypoint for skills and scripts
- Prefer `bridge --review-only` until you explicitly want the CLI to own Git side effects
- Prefer `report generate` as the reporting entrypoint for scheduled or post-task automation
- Prefer `pull-request review` when the automation target is an existing GitHub PR or GitLab MR URL
- Parse JSON output instead of scraping stderr
- Gate logic on `status` and `error.code`
- When `status` is `needs_host_agent`, fill the turn response and resume with `--session`

## Host-Agent Skill Loop

This is the primary integration. Cursor, Codex, and similar agents already have a model, so the CLI does not call an LLM HTTP API.

Recommended skill behavior:

```text
loop:
  run smart-commit-host-agent <cmd> [--session …] --output json
  if status == needs_host_agent:
    read requestPath
    generate model text from messages / purpose / responseSchema
    write { "turnId", "content" } to the matching response file
    continue with --session <sessionPath>
  else:
    finish (passed | blocked | error | …)
```

Typical first skill command:

```bash
smart-commit-host-agent bridge --review-only --repo . --config ./smart-commit.host-agent.json \
  --session-base /tmp/scha --output json
```

Then resume:

```bash
smart-commit-host-agent bridge --review-only --repo . --session <sessionPath> --output json
```

Session progress for `bridge` is stored in `bridge-state.json`, so resumed runs skip completed steps. `my-pull-request batch-review` stores progress in `batch-review-state.json` and skips completed URLs.

Keep Git side effects disabled in skill config until you trust the workflow:

```json
{
  "smartCommitHostAgent": {
    "git": {
      "autoCommit": false,
      "autoPush": false
    }
  }
}
```

## Turn Files

Session layout:

```text
<sessionDir>/
  session.json
  turns/
    0001.request.json
    0001.response.json
```

The Host Agent must write a response whose `turnId` matches the request:

```json
{
  "turnId": "0001",
  "content": "model output as a string"
}
```

Request fields the skill should honor: `turnId`, `kind`, `purpose`, `messages`, `responseSchema`, and `attempt`.

## Cursor / Codex Skills

Recommended use:

- wrap `bridge --review-only` for local code review
- wrap `bridge` only after `autoCommit` / `autoPush` are understood
- wrap `pull-request review <url>` when the user already has a remote PR/MR
- wrap `my-pull-request batch-review` for inbox-style review
- wrap `report generate` for periodic summaries

Inspect `status`:

- `passed` / `ok` / `resolved` / `created` / `existing` / `ready` mean continue according to the command
- `needs_host_agent` means write the response and resume
- `blocked` means stop and surface the review reason
- `error` means stop and surface the runtime or config problem

Do not pass `--api-key`, `--base-url`, `--model`, or `--llm-provider`. Those flags are rejected.

## Shell Scripts

For custom agents, CI bots, or local automation runners:

- spawn `smart-commit-host-agent <command> --output json`
- parse stdout as JSON
- branch behavior on `status`
- persist `sessionPath` across resumes

Example review-only loop:

```bash
SESSION_BASE=/tmp/scha
OUT=$(smart-commit-host-agent bridge --review-only --repo . --config ./smart-commit.host-agent.json \
  --session-base "$SESSION_BASE" --output json)
STATUS=$(printf '%s' "$OUT" | python3 -c 'import json,sys; print(json.load(sys.stdin)["status"])')

# If STATUS is needs_host_agent, a Host Agent writes the response, then:
# smart-commit-host-agent bridge --review-only --repo . --session <sessionPath> --output json
```

`host-agent probe` is a diagnostic for this loop, not a user workflow:

```bash
smart-commit-host-agent host-agent probe --session-base /tmp/scha --output json
# write turns/NNNN.response.json, then:
smart-commit-host-agent host-agent probe --session <sessionPath> --output json
```

## Exit Codes

- `0`: success
- `2`: blocked business decision, such as review blocked
- `3`: config error
- `4`: runtime error
- `10`: `needs_host_agent` — write the turn response and resume with `--session`

JSON payloads should remain the primary contract. Exit codes are best used as a coarse first filter. Exit `10` is expected in a healthy skill loop; it is not a failure.

## Recommended Rollout

1. Start with `smart-commit-host-agent config resolve` in the skill or local scripts to verify merged config.
2. Wire `bridge --review-only` into the skill and complete one Host-Agent turn.
3. Enable `passHistory`.
4. Add `report generate` in scheduled automation or agent workflows.
5. Optionally enable AI reporting (`--report-ai`) after the local flow is already stable.
6. Only then consider `bridge` with commit, push, or PR/MR creation.