# Connect GitHub repositories to Composal (agent instructions)

You are a coding agent running on the user's machine. Follow these steps to connect the
user's GitHub repositories to their Composal organization using the Composal CLI without interactive prompts.
The user's message should name the Composal organization slug; if it does not, ask for it
before running anything.

## Rules

- Always run `com repo import` with `--yes --no-tui --format jsonl` so it never opens
  an interactive UI and prints machine-readable events, one JSON object per line.
- Never pass secrets or tokens as command-line flags. The CLI uses the stored login.
- Connecting creates repositories in the organization's Home repository on the Composal server.
  Confirm the organization slug and the repository selection with the user before starting.
- When a step needs the user's browser (sign-in, GitHub App authorization), show them the
  URL and wait. Do not try to automate the authorization page.

## 1. Check the Composal CLI installation

```sh
com version
```

If the command is missing, install it and check again:

```sh
curl -fsSL https://dl.composal.com/install.sh | sh
```

## 2. Check sign-in

```sh
com whoami
```

If not signed in, run `com login --no-browser`, give the user the verification URL it
prints, and wait for them to finish in their browser. Then confirm with `com whoami`.

## 3. Choose repositories

Prefer naming each repository explicitly with a repeatable `--github-repository` flag.
Use `--all` (connects every eligible App-visible repository) only when the user clearly
asked for everything.

## 4. Connect the repositories

```sh
com repo import --org <org-slug> \
  --github-repository <owner>/<repo> \
  --yes --no-tui --format jsonl
```

Or, with the user's explicit confirmation:

```sh
com repo import --org <org-slug> --all --yes --no-tui --format jsonl
```

## 5. Handle events

Each stdout line is a JSON event with an `event` field:

- `action_required` with a `url`: the GitHub App is not authorized yet. Show the URL
  to the user; the command keeps polling and continues automatically after they finish.
  (Without `--format jsonl` the same URL is printed as
  `GitHub App authorization required: <url>` on stderr.)
- `selected`: lists the repositories the session will connect.
- `phase` / `progress` / `log`: normal progress; no action needed.
- `completed`: one repository finished.
- `failed` with `"retryable": true`: note the `item_id` for a retry (step 6).
- `session_completed` and `stopped` with `exit_code`: the run is over. Exit code 0
  means every selected repository connected successfully.

## 6. Resume or retry when needed

Sessions are durable on the server. If the command is interrupted, resume the latest
session:

```sh
com repo import --resume --yes --no-tui --format jsonl
```

Retry a single failed item within a session:

```sh
com repo import --resume <session-id> --retry <item-id> --yes --no-tui --format jsonl
```

## 7. Report the outcome

Tell the user which repositories connected and which failed (with the failure messages).
Connected repositories appear at `https://vex.sc/<org-slug>/repos`, and future GitHub
sync runs in Composal cloud automatically. The local machine is needed only for this initial
connection. Suggest `vex clone <org-slug>/home` as the next step to start working.