66 lines
3.8 KiB
Markdown
66 lines
3.8 KiB
Markdown
---
|
|
kind: epic
|
|
slug: repo-discovery-onboarding
|
|
title: Repository discovery, context import, and agent onboarding
|
|
plan_slug: automation-foundation
|
|
status: ready
|
|
priority: P1
|
|
tenant_id: global
|
|
cursor_epic_id: null
|
|
updated_at: "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
|
|
|
|
- [ ] [Task-forge-discovery-api](./Task-forge-discovery-api.md)
|
|
- [ ] [Task-repo-picker-modal](./Task-repo-picker-modal.md)
|
|
- [ ] [Task-repo-doc-ingestion](./Task-repo-doc-ingestion.md)
|
|
- [ ] [Task-agent-mcp-starter](./Task-agent-mcp-starter.md)
|
|
|
|
## Execution convoy
|
|
|
|
`.convoys/repo-discovery-onboarding.md`
|