rstillwell/Submatter
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions
Submatter/plans/Plan-automation-foundation/Epic-repo-discovery-onboarding/Epic-repo-discovery-onboarding.md

3.8 KiB
Raw Permalink Blame History

kind slug title plan_slug status priority tenant_id cursor_epic_id updated_at
epic repo-discovery-onboarding Repository discovery, context import, and agent onboarding automation-foundation ready P1 global null 2026-09-25

Epic objective

Replace one-repository-at-a-time URL entry with a secure account/instance flow: discover repositories visible to the current operator, explicitly select repositories for the current workspace, import bounded repository context, and show accurate agent setup instructions.

Product decisions

  • Repositories are attached to the current workspace; discovery does not implicitly create workspaces.
  • GitHub uses the current user's linked Auth.js account. Access tokens remain server-side and users explicitly re-authorize when additional scope is required.
  • Forgejo/Gitea v1 uses an instance URL and a server-side token environment-variable reference. Plaintext PATs are not persisted in the application database.
  • Batch connection and context ingestion are separate operations. Connecting repos is fast and atomic; remote content import is retryable and reports per-repo progress.
  • V1 context import is bounded to root README.md, AGENTS.md, CONTRIBUTING.md, and .convoys/*.md. Recursive docs/** and plans/** import is deferred until source identity and conflict semantics are specified.
  • Agent setup instructions must match a transport the MCP server actually supports and must never expose DATABASE_URL, forge tokens, or provider API keys.

In scope

  • Paginated GitHub and Forgejo/Gitea repository discovery with normalized, zod-validated results.
  • Searchable multi-select picker and admin-only, idempotent batch connection.
  • Idempotent import of supported docs as document objects and existing convoy manifests with source provenance.
  • OpenCode and Cursor onboarding guidance for the deployed MCP transport.
  • Optional bootstrap PR only when branch/file commit support exists; otherwise a separate follow-up task is created.

Out of scope

  • Automatic workspace creation for each repository.
  • Unbounded recursive import or two-way synchronization of remote documentation.
  • Browser-visible forge credentials or direct database credentials in generated snippets.
  • Full git worktree management, which remains in apps/worker.

Dependencies

  • Epic connected-repos for the base schema, CRUD router, and forge adapters.
  • Auth.js account linking in apps/web/lib/auth.ts.
  • Convoy lifecycle schemas and local reconciliation behavior.
  • A configured workspace model route, Redis, and worker are runtime dependencies for executing the implementation convoy, not for using the finished repo picker.

Acceptance criteria

  • A GitHub-linked user or configured Forgejo/Gitea admin sees all accessible repositories through explicit pagination without receiving a token in the browser.
  • An admin selects multiple repos and connects them to the current workspace in an idempotent operation; manual URL connection still works.
  • Supported documentation imports as document objects with repo/path/revision provenance and no duplicates on retry.
  • Valid .convoys/*.md manifests reconcile into workspace-scoped convoy objects; malformed files are reported without aborting other imports.
  • OpenCode and Cursor setup instructions are syntactically accurate for the supported transport and contain no secrets.
  • Tenant isolation, credential redaction, pagination, idempotency, and partial-failure behavior have automated coverage.

Tasks

Execution convoy

.convoys/repo-discovery-onboarding.md