# 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 with the non-interactive Composal CLI.
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. Ensure the Composal CLI is installed

```sh
com version
```

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

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

## 2. Ensure the user is signed 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 was only needed for this initial
connection. Suggest `com clone <org-slug>/home` as the next step to start working.