48 lines
3 KiB
Markdown
48 lines
3 KiB
Markdown
---
|
|
brief: 4
|
|
convoy: repo-discovery-onboarding
|
|
role: role-implementer
|
|
title: Agent onboarding and repository bootstrap
|
|
status: ready
|
|
priority: P2
|
|
slice_dependencies: [2, 3]
|
|
recommended_model: qwen-coder
|
|
model_tier: local
|
|
workspace_id: global
|
|
---
|
|
|
|
# Brief 4 — Agent onboarding and repository bootstrap
|
|
|
|
## Goal
|
|
|
|
After connection/import, the operator receives accurate, client-specific instructions for connecting an agent to Echodo and can optionally open a bootstrap PR for repository-side convoy guidance.
|
|
|
|
Backlog task: `plans/Plan-automation-foundation/Epic-repo-discovery-onboarding/Task-agent-mcp-starter.md`.
|
|
|
|
## Product and security contract
|
|
|
|
- Do not generate snippets containing `DATABASE_URL` or other infrastructure secrets.
|
|
- Do not assume an `ECHODO_WORKSPACE_ID` environment variable is consumed unless the MCP transport/config actually supports it.
|
|
- Support the deployment's real MCP transport first. If this remains local stdio, show the command plus non-secret workspace slug used in tool arguments. If remote authenticated MCP is added separately, link to that setup rather than fabricating it here.
|
|
- Client formats differ. Render templates from typed server data for explicitly supported clients (OpenCode and Cursor first); label unsupported clients instead of presenting one generic JSON object as universal.
|
|
- Any repository bootstrap change is a commit on a branch followed by `createPullRequest`; `createPullRequest` alone cannot create files.
|
|
|
|
## Files
|
|
|
|
- Add a typed onboarding-config procedure returning only non-secret deployment and workspace/repo identifiers.
|
|
- Add an Agent setup panel to connected-repo settings with client tabs, copy controls, prerequisites, and verification steps.
|
|
- Add bootstrap service only if the forge adapter has branch/file/commit primitives; otherwise scope this brief to guidance and create a follow-up task rather than simulating a PR.
|
|
- Bootstrap content should reference the canonical `.convoys/README.md` contract and avoid overwriting an existing file without explicit confirmation.
|
|
|
|
## Acceptance
|
|
|
|
- OpenCode and Cursor examples are syntactically valid for their actual configuration formats and contain no database URL, PAT, access token, or API-key value.
|
|
- Instructions identify the selected workspace and repository and include a smoke test such as `query_manifest_status`.
|
|
- Copy controls provide success/error feedback and work over secure browser contexts.
|
|
- Bootstrap is idempotent: existing `.convoys/README.md` is detected, and any remote change is shown to the user through a PR URL.
|
|
- Authorization is workspace owner/admin for remote writes; read-only members may view non-secret setup guidance if allowed by workspace policy.
|
|
- Lint, type-check, and relevant UI/service tests pass.
|
|
|
|
## Prompt for implementer
|
|
|
|
Implement only Brief 4 after Briefs 2 and 3. First verify the MCP server's supported transport and environment contract in code. Never place infrastructure credentials in browser-rendered snippets. Do not claim a bootstrap PR is possible unless branch/file commit support is implemented and tested.
|