# Repository creation and OpenAgents CLI specification

# Repository creation, GitHub import, and OpenAgents CLI specification

Date: 2026-08-20

Status: Proposed; repository creation is the first delivery slice

Status: Implemented for local verification; staging release remains gated

## Purpose

Allow an authenticated person or agent to create an OpenAgents-hosted Git

repository, push and pull with standard Git, and manage the repository through

the browser or a first-party CLI.

repository, import an existing GitHub repository once, push and pull with

standard Git, and manage the repository through the browser or a first-party

CLI.

This specification uses Cursor Origin as product research. It adopts the useful

interaction patterns without treating Origin's API, implementation, pricing,

- [OpenAgents architecture](architecture.md)

- [GitHub-shaped Issues and Projects API assessment](github-api-issues-projects-assessment.md)

- [Issues and Projects UI roadmap](issues-projects-ui-roadmap.md)

- [Repository creation and CLI implementation roadmap](repository-creation-cli-implementation-roadmap.md)

- [API authentication](api-authentication.md)

- [GitHub authentication and token lifecycle](github-auth-plan.md)

- [ADR 0007: Cut over to forge-canonical source control after proof](decisions/0007-cut-over-to-forge-canonical-source-control-after-proof.md)

- [Integration hardening and staging readiness recommendations](2026-08-20-integration-hardening-and-staging-readiness-recommendations.md)

## Current state

## Baseline before implementation

The application already has several parts of the required domain:

Before this slice, the application already had several parts of the required

domain:

- `OpenAgents.Repositories.Repository` stores a UUID, owner, name, visibility,

  and default branch.

  projections.

- The first-party `oa_pat_...` token supports the `forge:write` scope for

  GitHub-shaped API mutations.

- The server retains the signed-in user's encrypted GitHub `repo` grant and has

  bounded adapters that list repositories and read repository content.

The current implementation does not provide a user repository lifecycle:

The baseline did not provide a user repository lifecycle:

- No browser route or public API creates a repository.

- No browser route or public API creates or imports a repository.

- No API lists every repository the current user can access.

- The signed-in dashboard loads only `OpenAgentsInc/openagents.com`.

- Git repository admission comes from `OPENAGENTS_FORGE_REPOSITORIES`, not the

  checking an ordinary user's repository membership.

- The public code route has a literal `OpenAgentsInc` owner segment.

Creating a database row alone therefore does not create a usable hosted Git

repository.

Creating a database row alone therefore did not create a usable hosted Git

repository. The implementation described below now joins the database,

provisioning, WAL, Git HTTP, browser, and CLI paths. The implementation roadmap

tracks the remaining local end-to-end and staging evidence.

## Product decisions

The first release follows these decisions:

- A repository belongs to one stable namespace.

- The first namespace type is a personal namespace. Team and organization

  namespaces follow later.

- A repository belongs to a GitHub-backed user or organization namespace.

- OpenAgents uses the same user and organization names that GitHub reports. It

  keys each namespace by GitHub's immutable numeric account ID instead of a

  mutable login string.

- A namespace is available only through GitHub sign-in and the retained GitHub

  connection. Custom OpenAgents namespaces follow later.

- Repository visibility is `private` or `public`. The `internal` visibility

  from Origin requires a team model and is out of scope.

- New repositories default to `private` and use `main` as the default branch.

  commands but does not replace Git.

- The CLI uses the server-provided clone URL instead of constructing one from a

  hard-coded host.

- GitHub mirroring, pull requests, rulesets, SSH keys, apps, and team sharing

- The first release imports Git repository history, branches, and tags from

  GitHub as a one-time copy. It does not maintain a mirror or two-way sync.

- Pull requests, rulesets, SSH keys, apps, and OpenAgents-native team sharing

  remain future slices.

## Goals

The repository-creation slice must support these outcomes:

The repository and import slice must support these outcomes:

- You can claim or receive a stable personal namespace.

- Your OpenAgents namespaces match your GitHub user and eligible GitHub

  organization namespaces.

- You can create an empty repository from the browser.

- You can create the same repository with `openagents repo create`.

- You can import a GitHub repository from the browser or with

  `openagents repo import`.

- You can list and view repositories that you can access.

- You can clone, fetch, push, and pull with standard Git.

- A public repository supports anonymous read access.

The first slice does not include:

- GitHub repository mirroring or bidirectional synchronization.

- Continuous or bidirectional GitHub synchronization after a one-time import.

- Pull requests, reviews, merge queues, rulesets, or branch protection.

- Team namespaces, organization administration, or `internal` visibility.

- OpenAgents-native teams, custom namespaces, organization administration, or

  `internal` visibility.

- Repository transfer, rename, archive, restore, or deletion.

- SSH Git transport or SSH-key management.

- Code search across repositories.

| Human and JSON output | Adopt as separate output contracts |

| Endpoint override | Adopt for local development and staging |

| Repository deletion | Defer until recovery and retention semantics exist |

| GitHub mirror creation | Defer until per-repository source authority and synchronization receipts exist |

| GitHub mirror creation | Adapt as a receipted one-time import; defer continuous synchronization |

| Pull requests and rulesets | Defer until their server domains exist |

| SSH keys | Defer; use HTTPS and the Git credential helper first |

| Generic authenticated API command | Reserve until endpoint and secret-redaction behavior is specified |

| Self-update and shell completion | Defer until CLI packaging and release channels are admitted |

Origin uses team-owned codebases and `internal` visibility. OpenAgents starts

with stable personal namespaces and `public` or `private` repositories because

those concepts already match the application domain.

with GitHub-backed user and organization namespaces and `public` or `private`

repositories because those concepts match the existing identity and repository

domains.

## Namespace model

A repository owner must be a durable namespace, not a mutable GitHub login

copied into a string field.

GitHub supplies the namespace system for the first release. A person signs in

with GitHub and sees the same user login and eligible organization logins as

repository owners in OpenAgents. OpenAgents does not ask the person to claim a

second name.

Key a namespace by GitHub's immutable numeric account ID and account type. Treat

the GitHub login as a mutable URL and display projection.

Add a `namespaces` table with at least these fields:

| Field | Meaning |

| --- | --- |

| `id` | Stable UUID |

| `slug` | Displayed, URL-safe owner name |

| `slug_key` | Case-insensitive uniqueness key |

| `kind` | `personal` initially; reserve `team` |

| `owner_user_id` | Owning user for a personal namespace |

| `id` | Stable OpenAgents UUID |

| `provider` | `github` in the first release |

| `provider_account_id` | Immutable GitHub numeric user or organization ID |

| `provider_node_id` | GitHub GraphQL node ID when supplied |

| `slug` | Current GitHub user or organization login |

| `slug_key` | Case-insensitive routing key |

| `kind` | `user` or `organization` |

| `owner_user_id` | Local user for a GitHub user namespace; `nil` for an organization |

| `provider_refreshed_at` | Time of the latest successful GitHub projection refresh |

| `state` | `active`, `suspended`, or `retired` |

| `inserted_at`, `updated_at` | Audit timestamps |

Enforce uniqueness on `{provider, provider_account_id, kind}` and on the active

case-insensitive slug. A client-supplied slug never establishes namespace

ownership.

The repository row gains a required `namespace_id`. Keep `owner` as a derived

API projection during migration only if compatibility requires it. New policy

checks must join through `namespace_id` and memberships instead of trusting the

projected owner string.

### Personal namespace enrollment

### GitHub namespace projection

Use this first-release flow:

1. Derive a suggested slug from the authenticated user's current GitHub login.

2. Normalize and validate the suggestion.

3. Claim the slug transactionally on the user's first repository creation.

4. Keep the claimed slug stable when the GitHub login later changes.

5. If another namespace already owns the slug, return `namespace_required` and

   direct the user to an authenticated namespace-selection page.

Do not silently append an unstable number to resolve a collision. The user must

know the namespace that appears in clone URLs.

Namespace rename and transfer are out of scope. The UI must say that the chosen

namespace cannot be changed during the initial release.

1. On GitHub sign-in, upsert the GitHub user namespace from the verified numeric

   `github_id` and current `github_login` already stored on the local user.

2. Read the person's active GitHub organization memberships and upsert each

   organization from its numeric ID, node ID, and login.

3. Before an organization create or import, refresh that organization and the

   caller's active membership from GitHub.

4. Require the organization `admin` role for an empty repository creation in

   the first release.

5. For import, require read access to the source repository and authority to

   create the destination in the matching namespace. An organization import

   therefore requires the organization `admin` role under the first-release

   create policy, but it does not require admin permission on the source

   repository itself.

6. Add the creator as the OpenAgents repository `owner` in the repository

   transaction. Do not grant every GitHub organization member repository access

   until an organization access policy is specified.

GitHub logins can change while numeric account IDs remain stable. When GitHub

reports a rename, update the namespace slug and retain the prior slug in a

`namespace_aliases` table so existing web and Git URLs continue to resolve. An

alias can route to the stable namespace but cannot authorize a mutation.

Custom namespace claim, rename, transfer, and non-GitHub identity providers are

out of scope. They can evolve later without changing existing GitHub numeric

identity keys.

### Repository name rules

| `created_by_user_id` | Audited creator |

| `description` | Optional bounded description |

| `lifecycle_state` | Provisioning and availability state |

| `provisioning_kind` | `empty` or `github_import` |

| `provision_error_code` | Bounded operational code without provider prose |

| `storage_key` | Stable UUID-derived forge storage key |

| `ready_at` | Time when Git operations became available |

Do not put a credential, filesystem path, bucket URL, or raw provisioning error

in the repository row.

### GitHub import record

A one-time import is a durable provisioning operation, not a mirror. Add a

`repository_imports` table with at least these fields:

| Field | Meaning |

| --- | --- |

| `id` | Stable import UUID |

| `repository_id` | Destination OpenAgents repository |

| `provider` | `github` |

| `source_repository_id` | Immutable GitHub numeric repository ID |

| `source_owner_id` | Immutable GitHub numeric user or organization ID |

| `source_full_name` | Bounded source owner and repository projection |

| `source_default_branch` | GitHub default branch observed at acceptance |

| `source_ref_digest` | Digest of the accepted branch and tag ref map |

| `source_head_sha` | Accepted default-branch head when one exists |

| `state` | `pending`, `running`, `completed`, or `failed` |

| `attempt_count` | Bounded retry count |

| `error_code` | Bounded operational code |

| `started_at`, `completed_at` | Import timing |

The record never stores a GitHub access token, authenticated clone URL, local

path, raw Git diagnostic, or repository content.

At import acceptance, resolve the source through the GitHub API and freeze the

advertised `refs/heads/*` and `refs/tags/*` map. The import copies the objects

reachable from that map and verifies the same ref digest before it marks the

destination ready. GitHub changes after the accepted snapshot are not part of

the import.

The first release imports standard Git history, branches, tags, the default

branch, and submodule pointer commits. It does not import GitHub Issues, pull

requests, reviews, Actions runs or secrets, releases, repository settings,

wikis, or Git LFS objects. Git LFS pointer files remain ordinary Git content;

the UI and CLI must warn when the source uses LFS.

### Authority split

The lifecycle preserves these authorities:

## Provisioning contract

Repository creation crosses PostgreSQL and durable Git storage, so one database

transaction cannot complete the entire operation. Use a transactional outbox

and an idempotent provisioner.

Repository creation and GitHub import cross PostgreSQL, GitHub, and durable Git

storage, so one database transaction cannot complete the entire operation. Use

a transactional outbox and an idempotent provisioner.

1. Validate the authenticated principal, namespace, name, visibility, default

   branch, quota, and idempotency key.

2. In one PostgreSQL transaction, create the repository, add the creator as an

   `owner` member, and insert a provisioning outbox record.

3. Commit before any filesystem or object-store operation begins.

4. Initialize an empty durable WAL namespace using `repository.storage_key`.

5. Materialize or initialize the bare-repository cache with the requested

2. For an import, resolve the GitHub source repository, immutable owner and

   repository IDs, caller permission, default branch, and accepted ref map with

   the caller's retained server-side GitHub grant.

3. In one PostgreSQL transaction, create the repository, add the creator as an

   `owner` member, insert the optional import record, and insert a provisioning

   outbox record.

4. Commit before any filesystem, Git, or object-store operation begins.

5. Initialize an empty durable WAL namespace using `repository.storage_key`.

6. For an import, fetch the accepted GitHub refs into an isolated temporary

   repository, verify the frozen ref digest, and ingest the accepted objects and

   refs into the destination WAL. Use a server-owned credential adapter that

   never places the GitHub token in a URL, argv, log, receipt, or repository

   configuration.

7. Materialize or initialize the bare-repository cache with the selected

   symbolic default branch.

6. Verify that upload-pack and receive-pack resolve the same repository UUID.

7. Mark the repository `ready` and set `ready_at`.

8. On failure, record a bounded `provision_error_code`, mark the repository

8. Verify that upload-pack and receive-pack resolve the same repository UUID.

9. Mark the optional import `completed`, mark the repository `ready`, and set

   `ready_at`.

10. On failure, record a bounded `provision_error_code`, mark the repository

   `failed`, and retain the outbox attempt history.

The provisioner must tolerate a crash after every step. A retry must converge

on the same repository and storage namespace without deleting accepted Git

objects.

The create API can wait for a bounded synchronous attempt. Return `201 Created`

when provisioning completes during that window. Return `202 Accepted` with

`lifecycle_state: "provisioning"` when work continues asynchronously. The CLI

polls the repository resource until it reaches `ready`, reaches `failed`, or

exceeds its client timeout.

The create and import APIs can wait for a bounded synchronous attempt. Return

`201 Created` when provisioning completes during that window. Return `202

Accepted` with `lifecycle_state: "provisioning"` when work continues

asynchronously. The CLI polls the repository resource until it reaches `ready`,

reaches `failed`, or exceeds its client timeout.

## API contract

| Method and path | Authority | First release behavior |

| --- | --- | --- |

| `POST /api/v3/user/repos` | Authenticated API with `forge:write` | Create in the caller's personal namespace |

| `POST /api/v3/user/repos` | Authenticated API with `forge:write` | Create in the caller's GitHub user namespace |

| `POST /api/v3/orgs/{org}/repos` | Authenticated API with `forge:write` | Create in an eligible GitHub organization namespace |

| `POST /api/v3/user/repos/imports` | Authenticated API with `forge:write` | Import a GitHub repository into the caller's user namespace |

| `POST /api/v3/orgs/{org}/repos/imports` | Authenticated API with `forge:write` | Import a GitHub organization repository into its matching organization namespace |

| `GET /api/v3/user/repos` | Authenticated API | List repositories visible to the caller, including private repositories |

| `GET /api/v3/repos/{owner}/{repo}` | Optional API principal | Return a public repository or a repository visible to the principal |

| `GET /api/v3/repository-imports/{id}` | Authenticated API | Return bounded status for an import owned by the caller |

| Git smart HTTP under `/git/{owner}/{repo}.git` | Public read or authenticated Git principal | Clone, fetch, push, and pull |

Reserve `POST /api/v3/orgs/{org}/repos` for a future team namespace. Do not add

an endpoint that accepts an arbitrary `owner` string and then creates a personal

repository there.

Do not add an endpoint that accepts an arbitrary owner string. The user route

derives the GitHub user namespace from the authenticated principal. The

organization routes resolve `{org}` to a refreshed GitHub organization ID and

verify the caller's active GitHub authority before creating an OpenAgents row.

The current route classifier treats all `/api/v3` `GET` requests as public.

`GET /api/v3/user/repos` is an authenticated exception and needs an explicit

route-authority declaration and test.

`GET /api/v3/user/repos` and `GET /api/v3/repository-imports/{id}` are

authenticated exceptions and need explicit route-authority declarations and

tests.

### Create request

- `description` is optional and bounded to 350 Unicode scalar values.

- `private` defaults to `true`.

- `default_branch` defaults to `main` and follows Git ref-name validation.

- The server derives the personal namespace from the authenticated principal.

- The server derives the GitHub user namespace from the authenticated

  principal. Organization creation uses the organization route.

- `Idempotency-Key` is required for the CLI and recommended for every client.

The same principal, idempotency key, and normalized request returns the original

result. Reusing the key with a different normalized request returns `409

Conflict`.

### Import request

Import into the matching GitHub user namespace:

```http

POST /api/v3/user/repos/imports

Authorization: Bearer oa_pat_...

Content-Type: application/json

Idempotency-Key: f5a7dc80-a670-42ce-9454-fc5e5e64586f

```

```json

{

  "source": {

    "provider": "github",

    "repository": "octavia/existing-project"

  },

  "name": "existing-project",

  "private": true

}

```

Import an organization-owned source into its matching organization namespace

through `/api/v3/orgs/{org}/repos/imports`. The `{org}` path ID must resolve to

the same immutable GitHub owner ID returned for the source repository.

Rules:

- The source is a GitHub `owner/name`, not a caller-supplied clone URL.

- The server resolves the source and its permissions with the signed-in user's

  retained, encrypted GitHub token.

- The user route accepts a source owned by the signed-in GitHub user. Copying a

  repository owned by another account into the GitHub user namespace is a

  future fork or template workflow.

- The organization route requires read access to the source repository, active

  organization membership, and the organization `admin` role required by the

  first-release destination create policy.

- `name` defaults to the normalized GitHub repository name.

- `private` defaults to `true`, including when the GitHub source is public. A

  private source can never default to public.

- `default_branch` defaults to the source default branch.

- The server creates an independent OpenAgents repository. It installs no

  webhook and schedules no later GitHub fetch or push.

Return the repository projection with an `import` object containing only the

import ID, provider, source full name, accepted head SHA, state, and timestamps.

Return `202 Accepted` while the import runs and `201 Created` only when the

repository is already `ready`.

### Repository response

```json

| `404 Not Found` | Repository is absent or hidden from the principal |

| `409 Conflict` | Name or idempotency conflict |

| `422 Unprocessable Entity` | Valid JSON violates repository rules |

| `503 Service Unavailable` | Provisioning cannot currently start |

| `503 Service Unavailable` | Provisioning or required GitHub access cannot currently start |

Use one bounded error envelope:

Existing issue and project clients retain their current behavior. Add scope or

token-format changes only through a separately documented migration.

### Retained GitHub grant

GitHub namespace projection and import use the retained, encrypted GitHub OAuth

token on the server. The OpenAgents PAT proves the CLI caller's OpenAgents

authority; it never becomes a GitHub credential and never receives the GitHub

token.

The existing `repo` grant supplies repository access for public and private

imports. Reading private organization membership requires an explicit

organization-read decision. The first release proposes adding `read:org` so the

server can enumerate active organization memberships and roles through

GitHub's organization-membership API. GitHub documents `repo` and `read:org`

separately in its

[OAuth scope reference](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps).

Before activation:

1. Update the GitHub consent UI to explain repository import and organization

   namespace projection.

2. Update the exact granted-scope validation.

3. Require existing users to reconnect rather than rewriting stored scope

   metadata.

4. Use `Req` for GitHub REST calls and explicit fakes in tests.

5. Fail an import with `github_connection_required` when the user has no

   retained grant.

6. Fail organization operations closed when GitHub cannot refresh the required

   membership or repository permission.

Import never installs a GitHub webhook, writes to GitHub, or schedules a later

sync. After the import completes, OpenAgents is the source of truth for the new

repository and GitHub remains unchanged.

### Browser-assisted CLI login

Add a device-style browser flow so a terminal never handles the GitHub OAuth

- Updated time.

- Open issue count when available without an unbounded query.

- A **New repository** action.

- An **Import from GitHub** action.

Use a LiveView stream and separate count and empty-state assigns. Add search and

pagination after the base list works.

Add an authenticated `/repositories/new` route with:

- A read-only or selectable namespace field, depending on enrollment state.

- A namespace selector populated from the signed-in GitHub user and eligible

  GitHub organizations.

- A repository name input.

- An optional description.

- A `private` or `public` visibility choice, with `private` selected initially.

authenticated LiveView session. The browser calls the same context operation as

the API and never invokes forge filesystem code directly.

### Import from GitHub page

Add an authenticated `/repositories/import/github` route with:

- A bounded, paginated picker of GitHub repositories available through the

  retained grant.

- The GitHub owner, repository name, visibility, and default branch.

- A destination namespace that defaults to the matching GitHub user or

  organization namespace.

- An editable destination repository name.

- A `private` or `public` destination choice, with `private` selected initially.

- An explicit statement that the operation copies one snapshot and does not

  maintain synchronization.

- An **Import repository** button with pending and disabled states.

Use the existing GitHub adapter through a context operation. Extend its bounded

repository projection with the immutable repository and owner IDs, owner type,

default branch, permissions, and LFS warning inputs required by this contract.

The LiveView must never receive the retained GitHub token.

While an import runs, show the source full name, accepted head SHA when present,

current state, and a bounded failure code. Do not stream raw Git output to the

browser.

### Empty repository page

After creation, the repository page shows:

- A copy control with an accessible name.

- Links to Issues and Projects for the same repository.

For an imported repository, also show the GitHub source, accepted snapshot SHA,

completion time, and the statement **Imported once from GitHub**. Do not label

the repository as synced or mirrored.

Do not show push instructions until the repository is `ready`.

### Repository route

`/chat`, `/docs`, `/settings`, `/status`, and future declared product routes

cannot be interpreted as namespaces.

If that route contract cannot be proven without fragile ordering, use

`/code/{owner}/{repo}` and keep the Issue and Project routes unchanged. Resolve

this route decision before implementation begins.

If that route contract cannot be proven without fragile ordering, stop the

repository-home activation and revise this specification before using a

different public route.

## CLI product contract

The proposed binary name is `openagents`. Reserve `oa` as a possible later

alias; do not make scripts depend on it in the first release.

Publish the npm package as `@openagentsinc/cli` and expose the `openagents`

binary. Reserve `oa` as a possible later alias; do not make scripts depend on

it in the first release.

This CLI is the first-party repository-hosting client. It does not replace the

Pylon contributor runtime or absorb Pylon's agent-execution commands.

### Global behavior

```text

openagents [--endpoint <url>] [--json] [--no-color] <command>

openagents [--profile <name>] [--api-url <url>] [--json] [--no-color] <command>

```

- `--endpoint` defaults to `https://openagents.com`.

- `OPENAGENTS_ENDPOINT` provides the same setting for development and staging.

- The `production` profile targets `https://openagents.com` and is the default.

- The `staging` profile targets `https://staging.openagents.com`.

- The `local` profile targets `http://localhost:4000`.

- `--api-url` accepts a normalized custom API origin and overrides the selected

  profile for the current command.

- `OPENAGENTS_API_URL` provides the same per-process override for development,

  continuous integration, and end-to-end tests.

- `OPENAGENTS_PROFILE` selects a named profile when `--profile` is absent.

- Command flags take precedence over environment variables, which take

  precedence over persisted configuration, which takes precedence over the

  `production` default.

- `OPENAGENTS_TOKEN` provides a nonpersistent bearer token.

- `NO_COLOR` and `--no-color` disable ANSI output.

- `--json` emits one documented JSON value to stdout.

The CLI must not send telemetry in the first release.

Accept `http` only for `localhost`, `127.0.0.1`, and `[::1]`. Require `https`

for every other API host. Reject credentials, query strings, fragments, and

non-root paths in API origins. Normalize the origin before any credential-store

lookup so production, staging, local, and custom services cannot share a token

by accident.

All automated CLI tests and local end-to-end tests must set

`OPENAGENTS_API_URL=http://localhost:4000` or pass the equivalent `--api-url`

flag. Tests must fail before a network call if the resolved origin is

`https://openagents.com` or `https://staging.openagents.com`.

### Authentication commands

```text

openagents auth logout

```

`auth status --json` reports the endpoint, authentication source, account login,

namespace, token expiry, and Git-helper state. It never reports a token or token

digest.

`auth status --json` reports the endpoint, authentication source, GitHub account

login and numeric ID, eligible GitHub namespaces, token expiry, and Git-helper

state. It never reports a token or token digest.

### Repository commands

```text

openagents repo create <name>

openagents repo create <owner>/<name>

openagents repo import <github-owner>/<github-repo>

openagents repo list

openagents repo view [<owner>/<name>]

openagents repo clone <owner>/<name> [<directory>]

```

`repo create <name>` targets the authenticated user's personal namespace.

`repo create <name>` targets the authenticated user's GitHub user namespace.

`repo create <owner>/<name>` succeeds only when the authenticated user can

create repositories in that namespace. Team namespace creation remains

unavailable until the server supports it.

create repositories in the matching GitHub organization namespace.

Create options:

- `--remote` defaults to `origin` only when that remote is absent. If `origin`

  already points elsewhere, the command refuses to overwrite it.

Import options:

```text

--name <destination-name>

--namespace <github-owner>

--public

--private

--wait-timeout <duration>

```

Import rules:

- The source argument is a GitHub `owner/name`, not a URL.

- The destination namespace defaults to the GitHub source owner and must resolve

  to the same GitHub user or organization identity.

- `--namespace` can state that matching owner explicitly. It cannot copy the

  source into an unrelated namespace in the first release.

- `--name` defaults to the source repository name.

- The destination defaults to private. `--public` requires an explicit flag,

  including for a public source.

- The command submits one idempotent import, polls until `ready` or `failed`,

  and reports the accepted source head SHA.

- The command exits after the bounded `--wait-timeout` without canceling a

  durable import that still runs on the server.

- After success, the command states that later GitHub changes will not sync.

`repo list` supports `--namespace`, `--limit`, `--after`, and `--json`.

`repo view` and later repository-scoped commands infer the repository from the

`origin` remote when no argument is present. `-R, --repo <owner>/<name>`

| Service | Responsibility |

| --- | --- |

| `CliConfiguration` | Endpoint, output mode, timeouts, and environment inputs |

| `CliConfiguration` | Profile, API origin, output mode, timeouts, and environment inputs |

| `CredentialStore` | Secure token presence, read, write, and erase |

| `AuthClient` | Device authorization, status, and logout |

| `ForgeApiClient` | Authenticated repository API calls and schema decoding |

Evaluate these release steps in order:

1. Run the CLI from the monorepo with Node 24 during development.

2. Publish an npm development preview if it improves dogfooding.

1. Run `@openagentsinc/cli` from the monorepo with Node 24 during development.

2. Publish an npm development preview after package and binary smoke tests pass.

3. Produce checksum-verified standalone artifacts for macOS, Linux, and WSL.

4. Serve a versioned installer from `openagents.com` only after artifact signing,

   rollback, and update-channel behavior pass release tests.

  repository for API or Git access.

- Store API tokens, device codes, and poll secrets only as digests on the

  server.

- Keep the retained GitHub token inside the server adapter. Never return it to

  the CLI, browser, provisioning row, import receipt, or Git remote.

- Show a CLI token once and never include it in export, logs, telemetry,

  receipts, exception messages, or JSON output.

- Do not put credentials in clone URLs.

- Return `404 Not Found` for a private repository when the caller must not learn

  that it exists.

- Audit repository creation, provisioning transitions, membership creation,

  token creation, and Git writes without recording repository content.

  GitHub import transitions, token creation, and Git writes without recording

  repository content.

- Prevent repository creation from changing runtime configuration or deployment

  targets.

- Remove isolated import workspaces after success or failure through a bounded

  recovery worker.

- Never describe an imported repository as synchronized after the one accepted

  snapshot completes.

## Test plan

Add focused tests for:

- Namespace claim, normalization, collision, and immutability.

- GitHub user and organization namespace projection by immutable numeric ID.

- GitHub login rename, alias routing, case normalization, and collision refusal.

- Repository name and default-branch validation.

- Atomic repository, owner-membership, and outbox creation.

- Atomic repository, owner-membership, optional import, and outbox creation.

- Idempotent repeat requests and mismatched idempotency keys.

- Personal namespace authority and refusal of arbitrary owner creation.

- GitHub user namespace authority, organization admin authority, stale

  membership refresh, and refusal of arbitrary owner creation.

- Missing GitHub connection, missing `read:org`, source repository refusal, and

  private source authorization.

- Import request and status projections without credentials or raw Git output.

- Public, private, member, nonmember, banned-user, suspended, failed, and

  missing repository reads.

- `201`, `202`, `401`, `403`, `404`, `409`, `422`, and `503` behavior.

- A crash after each provisioning transition followed by convergence.

- Duplicate outbox delivery.

- WAL initialization before `ready`.

- Frozen GitHub branch and tag refs, source ref-digest verification, and an

  update that lands on GitHub after the accepted snapshot.

- Import of public and private GitHub repositories.

- Import failure, retry, interruption, timeout, and isolated-workspace cleanup.

- LFS detection and the required pointer-only warning.

- Proof that neither GitHub nor OpenAgents receives a synchronization write

  after import completion.

- Bare-cache deletion followed by reconstruction.

- Two repositories with the same name in different namespaces.

- Anonymous clone of a public repository.

Add tests for stable DOM IDs and outcomes:

- Repository list, empty state, and pagination.

- Namespace enrollment state.

- GitHub user and organization namespace selection.

- Create form validation and submission.

- GitHub repository picker, import submission, progress, warning, and failure

  states.

- Private visibility as the default.

- Provisioning, ready, and failed states.

- Clone instructions only after readiness.

  interruption.

- Token redaction from human output, JSON, errors, logs, and snapshots.

- Repository create `201` and `202` flows.

- Repository import `201`, `202`, failure, timeout, and idempotent retry flows.

- Matching GitHub destination namespace enforcement.

- Idempotent retry after a connection failure.

- Remote inference and refusal of unadmitted hosts.

- Refusal to overwrite an existing `origin` remote.

Run an end-to-end suite against a disposable Phoenix server, PostgreSQL

database, forge storage directory, and Git checkout. The suite must create a

repository through the CLI, push a commit with standard Git, clone it into a

second directory, and verify the exact commit SHA.

second directory, and verify the exact commit SHA. A second case must import a

GitHub fixture repository, verify every accepted branch and tag, change the

GitHub fixture after acceptance, and prove that the OpenAgents repository does

not synchronize that later change.

## Delivery sequence

### Phase 0: Close design decisions

1. Approve the CLI binary and package names.

2. Approve the personal namespace enrollment behavior.

3. Approve the canonical browser and Git URL shapes.

4. Select the initial CLI distribution format.

5. Record the repository lifecycle and authority split in `INVARIANTS.md`.

1. Approve the canonical browser and Git URL shapes.

2. Confirm the GitHub `read:org` consent and reconnection migration.

3. Record the initial npm-only distribution boundary and the later standalone

   artifact gate.

4. Record the GitHub namespace, one-time import, repository lifecycle, and

   authority split in `INVARIANTS.md`.

### Phase 1: Add namespace and repository authority

1. Generate migrations with `mix ecto.gen.migration`.

2. Add namespace ownership and repository lifecycle schemas.

3. Backfill `OpenAgentsInc/openagents.com` into an explicit namespace.

4. Add transactionally created owner membership and provisioning outbox rows.

2. Add GitHub-backed namespace, namespace-alias, repository-import, and

   repository lifecycle schemas.

3. Backfill `OpenAgentsInc/openagents.com` into an explicit GitHub organization

   namespace identified by its numeric GitHub ID.

4. Add transactionally created owner membership, optional import, and

   provisioning outbox rows.

5. Rehearse the migration down and up against populated fixtures.

### Phase 2: Add create, list, and view APIs

### Phase 2: Add create, import, list, and view APIs

1. Add failing controller tests for `POST /api/v3/user/repos`.

2. Implement the context operation, controller, JSON projection, and route.

3. Add authenticated repository list and optional-auth repository view.

4. Add idempotency, cursor, error-envelope, and route-authority tests.

5. Publish the initial client contract artifact.

2. Add failing controller tests for the user and organization import routes.

3. Implement the context operations, controllers, JSON projections, and routes.

4. Add authenticated repository list, import status, and optional-auth

   repository view.

5. Add idempotency, cursor, error-envelope, and route-authority tests.

6. Publish the initial client contract artifact.

### Phase 3: Provision Git repositories

1. Make the hosted repository inventory database-backed.

2. Change storage keys and Git paths to include stable repository identity.

3. Add the idempotent provisioning worker and recovery scan.

4. Scope upload-pack and receive-pack through repository policy.

5. Preserve the deployment allowlist as a separate operator control.

6. Prove create, push, cache loss, reconstruction, fetch, and clone locally.

4. Add the one-time GitHub importer with frozen refs, bounded retries, secure

   credential delivery, and temporary-workspace recovery.

5. Scope upload-pack and receive-pack through repository policy.

6. Preserve the deployment allowlist as a separate operator control.

7. Prove create, import, push, cache loss, reconstruction, fetch, and clone

   locally.

### Phase 4: Add CLI authentication

1. Add device authorization records and endpoints.

2. Add the authenticated browser approval page.

3. Add one-time PAT delivery and expiry behavior.

4. Implement the CLI credential store and Git credential helper.

5. Pass secret-handling and headless-agent tests.

2. Add GitHub organization projection and the proposed `read:org` consent

   migration.

3. Add the authenticated browser approval page.

4. Add one-time PAT delivery and expiry behavior.

5. Implement the CLI credential store and Git credential helper.

6. Pass secret-handling and headless-agent tests.

### Phase 5: Build the Effect CLI

1. Create `packages/openagents-cli` in the monorepo.

2. Pin the Phoenix-owned contract artifact.

3. Implement `auth` and `repo` command groups through Effect services.

3. Implement `auth`, `repo create`, and `repo import` through Effect services.

4. Add human output, JSON output, exit-code, signal, and redaction tests.

5. Run the cross-repository disposable end-to-end suite.

### Phase 6: Add the browser interface

1. Replace the hard-coded dashboard repository card with the scoped list.

2. Add namespace enrollment and repository creation pages.

3. Add provisioning and empty-repository states.

4. Run accessibility, keyboard, responsive, and browser checks.

2. Add GitHub namespace selection and repository creation pages.

3. Add GitHub repository selection and one-time import pages.

4. Add provisioning, import, and empty-repository states.

5. Run accessibility, keyboard, responsive, and browser checks.

### Phase 7: Stage and release

1. Run `mix precommit` and the owned exact-SHA gate in `openagents.com`.

2. Run `pnpm run check` in the CLI monorepo.

3. Deploy to an isolated staging environment only after Gate 12 permits it.

4. Create, push, clone, revoke, retry, and recover on one staging candidate.

4. Create, import, push, clone, revoke, retry, and recover on one staging

   candidate.

5. Scan the complete log window for tokens, clone credentials, repository

   content, and private paths.

6. Publish the CLI only after the server candidate and client contract digest

## Acceptance criteria

The first repository-creation slice is complete when:

The first repository and import slice is complete when:

- An authenticated user has one stable personal namespace.

- An authenticated user receives the GitHub user namespace identified by the

  same numeric GitHub user ID and sees eligible organization namespaces

  identified by their numeric GitHub organization IDs.

- The browser and CLI create the same repository resource through the same

  context policy.

- A successful command returns only after the repository is ready, or reports a

- The creator receives an `owner` membership in the same database transaction

  as the repository row.

- A repeat request with the same idempotency key cannot create a duplicate.

- The browser and CLI can import an authorized GitHub repository's accepted

  history, branches, and tags into the matching GitHub namespace.

- An imported repository records its source and exact accepted snapshot without

  retaining a GitHub credential.

- A GitHub commit created after import acceptance does not appear in OpenAgents

  without a new explicit future import or synchronization feature.

- A public repository clones anonymously.

- A private repository is hidden from a nonmember.

- A permitted user can push and a read-only or unrelated user cannot.

  argv, logs, JSON, or a clone URL.

- `openagents repo create`, standard `git push`, and `openagents repo clone`

  complete an exact-SHA end-to-end test.

- `openagents repo import` completes a second exact-ref end-to-end test for a

  GitHub fixture.

- Both repositories pass their required local gates at the exact delivered

  revisions.

## Decisions required before implementation

The owner must resolve these items before Phase 1 begins:

1. **Binary name:** Use `openagents`, `oa`, or both.

2. **Namespace enrollment:** Claim the suggested GitHub-login slug

   automatically, or require a one-time browser confirmation for every user.

3. **Repository home route:** Use `/{owner}/{repo}` with a reserved-route

   contract, or use `/code/{owner}/{repo}`.

4. **Distribution:** Start with npm, standalone artifacts, or both.

5. **Effect command parser:** Use a parser compatible with the pinned Effect

   version, or keep parsing local while all effects remain in Effect services.

This document recommends `openagents`, automatic claim with an explicit

collision flow, `/{owner}/{repo}`, a short npm dogfood phase followed by signed

standalone artifacts, and Effect TypeScript with a parser selected by a bounded

spike.

## Implementation decisions recorded

This document records these implementation decisions:

- GitHub user and organization identity is the first-release namespace

  authority.

- The package is `@openagentsinc/cli`, and the binary is `openagents`.

- The CLI uses Effect TypeScript with `effect/unstable/cli`.

- The CLI includes production, staging, and local API profiles and accepts a

  validated custom API origin.

- The browser uses `/{owner}/{repo}` after the reserved-route proof passes.

- GitHub OAuth requests `read:org` with `repo`; an existing connection that

  lacks a required scope must reconnect.

- The first distribution is an npm dogfood release. Signed standalone artifacts

  require their separate release gate.

# Repository creation and CLI implementation roadmap

Date: 2026-08-20

Status: Implementation complete; local end-to-end and staging verification

remain

## Outcome

Implement repository creation, one-time GitHub import, Git smart HTTP, browser

management, and the `@openagentsinc/cli` package as one tested product across

the `openagents.com` Phoenix repository and the `openagents` Effect monorepo.

The product specification remains the contract:

[Repository creation, GitHub import, and OpenAgents CLI specification](repository-creation-and-openagents-cli-spec.md).

This roadmap records implementation order, owning files, dependencies, tests,

and release evidence. Update the status ledger as each work packet lands.

## Recorded decisions

- Publish the npm package as `@openagentsinc/cli`.

- Expose the `openagents` binary. Do not ship an `oa` alias in the first

  release.

- Use Effect TypeScript and the monorepo-pinned Effect 4 release.

- Use `effect/unstable/cli` for argument and flag parsing.

- Default to the `production` profile at `https://openagents.com`.

- Provide the `staging` profile at `https://staging.openagents.com`.

- Provide the `local` profile at `http://localhost:4000`.

- Support `--api-url`, `OPENAGENTS_API_URL`, `--profile`, and

  `OPENAGENTS_PROFILE` for explicit endpoint selection.

- Scope stored credentials to the normalized API origin.

- Pin automated and local end-to-end tests to `http://localhost:4000` and fail

  closed if a test resolves a production or staging origin.

- Use GitHub numeric user and organization IDs as namespace identity. Use the

  current GitHub login as a mutable display and route projection.

- Request `read:org` in addition to the existing `repo` grant so OpenAgents can

  project organization membership and roles.

- Import one accepted GitHub ref snapshot. Do not install a webhook or schedule

  later synchronization.

- Use `/{owner}/{repo}` for the repository home after executable reserved-route

  tests prove that product routes cannot become namespaces.

- Start distribution through npm. Gate standalone artifacts and an installer as

  a later release packet.

## Definition of done

All of these statements require direct evidence before this roadmap can move to

`Complete`:

- A GitHub-authenticated user receives a user namespace keyed by the same

  numeric GitHub user ID.

- An eligible GitHub organization appears as a namespace keyed by the same

  numeric GitHub organization ID and current login.

- The browser and CLI create private or public repositories through the same