Set Up With Your Agent

Connect your agent, give it access to the intended project, and let it prepare setup from the repository. You approve the account permissions and provider connections. After setup, the same connection can read recommendations, retrieve tasks and record results.

Start here

1. Create an account and start a trial, or sign in to your existing account. You choose the plan and complete checkout.
2. If the dashboard shows Start Trial, complete checkout first. Then choose Set Up With Your Agent. Select your client and copy the handoff from the dialog.
3. Open the product's repository in your agent and paste the handoff. It includes connection commands and this guide.
4. For API or CLI automation, create a developer key in Agent Access. Existing accounts can also copy an agent handoff there.
5. Approve GitHub access yourself when requested. ShipFoundry requires one selected read-only repository per project. Linear is optional.

Prefer the dashboard? Follow Quickstart. You can switch between dashboard and agent workflows on the same project.

Choose a connection

When a setup handoff specifies a server address, use that address throughout, including for links and API requests. Do not replace it with the production addresses in this guide.

Use one connection for writes. You can read through another to verify the same stored result. Repeating a write through another interface without the same explicit idempotency key can create another action.

Permissions

In MCP authorization, choose All current and future projects if your agent will create the project. Selecting existing projects limits access to those projects. An older connection with no project access needs fresh authorization; it is not expanded automatically.

To create a new project, the credential needs project:write and access to all current and future projects. A selected-project grant can manage existing permitted projects but cannot create another. Project limits still apply.

For setup, start with projects:read and project:write. Reading recommendations needs updates:read; recording decisions and outcomes needs updates:write; requesting briefs needs briefs:write. Add only the permissions your workflow needs. Revoking a credential stops its future access without deleting project history.

API and CLI require an explicitly authorized developer key. MCP OAuth credentials and historical MCP-only keys are not interchangeable with developer keys. Never paste a secret into a chat, repository, issue, or handoff. Use your client's secure credential configuration.

Give this to your agent

# Set up ShipFoundry for this repository

Read https://shipfoundry.ai/docs/agent-setup.md and the guide for our connection.
Use the configured MCP connection or developer credential.

## Check the account

1. Verify account identity, permissions and plan limits.
2. List projects and find one for this repository before proposing a new one.
3. Use this repository as the product. Ask only when multiple products or repositories make the target unclear.

## Prepare project context

1. Inspect the repository and identify its active dependencies and key files.
2. Propose a name, description, goals and relevant watchlist.
3. Separate code evidence from assumptions. Ask about missing business facts.
4. Read existing context before proposing changes.

## Complete setup

1. Use the tool schemas or API guide to save approved project context.
2. Ask me to complete GitHub consent, then select the authorized repository.
3. Configure the approved watchlist within plan limits.
4. Check setup status and explain any remaining action.
5. Ask before activating the first review; it can consume allowance.
6. Follow processing status until complete or a stated deadline.

## Continue with recommendations

- Read evidence, questions and any existing brief or packet first.
- Ask before generating a new brief or exporting work.
- Inspect current code before proposing implementation.
- Record only completed work, with evidence, and read back the saved outcome.

## Return

- Project ID and completed setup steps.
- Current processing state and request IDs.
- Remaining actions or errors, with the next step for each.

Keep secrets out of messages and files. Preserve idempotency keys on retries.
Do not purchase, deploy, merge or create external issues without my instruction.

This playbook is also available as Markdown for agents. Use the docs index to discover individual guides, or full documentation when broader context is needed. A separate skill installation is not required.

Agent procedure

1. Discover. MCP clients initialize the connection, inspect tools/list, then call get_identity and get_usage. HTTP clients read /me and /usage. Verify account identity, project grants and billing readiness before writing. A successful login alone does not mean setup is ready.
2. Find Or Create. List projects and identify the intended product. If absent, propose creating it. Retain the returned project ID for every later action.
3. Describe The Product. Read setup status. Submit evidence-based product context, goals, constraints and stack through update_project_context or PATCH /projects/{id}/context. Do not overwrite good existing context merely to repeat onboarding.
4. Connect The Repository. Ask the owner to complete GitHub consent using the project setup page. List the repositories already authorized to the account and select the intended one. Never guess a repository ID or reuse another account's ID.
5. Choose The Watchlist. Read the project's suggested and selected watchlist items. Propose relevant suggestions, then add their returned recommendation IDs. For missing items, offer to submit coverage requests through request_stack_tracking, then report their saved status separately from active tracking. Removing tracking preserves existing history.
6. Finish Activation. Check setup and processing status. Explain that activation starts the first review and can consume the account's allowance. After owner approval, call request_activation with confirmed: true, or POST /projects/{id}/activation with the same confirmation and a stable idempotency key. Inspect the returned dispatch state, then poll project processing status with a deadline. Admission or dispatch is not a completed review.
7. Work An Update. Read the update, current question, trust state and stored brief. If generation is needed, obtain approval, preserve one idempotency key and poll its returned operation ID with a deadline. Read the resulting packet before changing code.
8. Record And Verify. Record investigation or implementation evidence. Marking a brief used is separate from adopting an update. Read the update again to confirm the stored outcome and summarize what remains uncertain.

What needs your approval

Account creation, trial checkout, credential permission approval, and GitHub or Linear consent remain human-controlled. Your agent can prepare the next step and link you to the relevant page, then continue after you finish. First-review activation and brief generation require your explicit approval before the agent starts work.

When something blocks progress

• Grant is none: this means no project access, even with project:write. Do not attempt creation. Start fresh authorization in the MCP client and approve All current and future projects. For an existing OpenCode connection, use opencode mcp logout shipfoundry followed by opencode mcp auth shipfoundry. This is a client OAuth flow, not an action on the Agent Access settings page.
• Auth command timed out: check connection status and call get_identity. If authenticated with the intended account and grant, continue. Tool discovery alone does not prove authorization.
• Rejected creation: permission and billing denials are not fixed by changing arguments or idempotency keys. Resolve the denial first. For uncertain network outcomes, keep the original key and payload and check existing projects before retrying.
• Unmatched stack technology: offer to request coverage. After approval, call shipfoundry.request_stack_tracking with projectId, name, an optional note, confirmed: true and a stable idempotencyKey. Save the returned requestId. Read manage_watchlist with action: "list" to confirm its coverage status. A request does not enable monitoring or start paid work. Keep the item in project context and continue with supported items; never substitute an unrelated catalog entity.
• GitHub configured but no connections: the server supports GitHub, but this account has not authorized an installation. Complete GitHub consent before selecting a repository.
• Empty account settings: no custom preferences are stored. The endpoint returns its free-form metadata schema and supports reads only; there are no required preference fields to populate. Project setup uses project context, repository and watchlist operations.

Previously connected clients

If you already connected ShipFoundry, check the saved server address before adding another connection. Reuse the intended connection. On the authorization page, verify the signed-in identity, account and projects. If they are wrong, deny access, sign into the intended account in that browser, and retry. Login success does not guarantee tools are loaded in an existing agent session; reload the connection or start a new session if needed.

Setup errors

• No projects: verify the account and project grant before creating a project.
• 403: check scopes, current account role and project grant. Do not request broader access than needed.
• Billing or quota error: show the limit and link the owner to Billing. Never retry by changing account or bypassing the limit.
• No recommendations or packet: report the actual processing/readiness state. Do not invent an update or silently start paid work.
• Uncertain write: retain the request and operation IDs. A reconciliation_required response requires reconciliation, not a new idempotency key.
• Unsupported operation: describe the missing capability and the exact dashboard step. Tool availability is not proof that the whole workflow completed.

Next guides

• MCP Connection And Tool Workflow
• API Requests And Retry Rules
• CLI Configuration And Commands
• Working With Briefs And Outcomes
• Security And Data