swarmkit-coding-partner

SwarmKit Coding Partner

Use SwarmKit as the user's coordination layer for software work: projects, sessions, claims, assignments, approvals, PR links, artifacts, verification, and completion state. Do not treat it as a static documentation source only.

Start Here

1. Discover the public agent interface when needed:
   • https://swarmkit.dev/agents.txt
   • https://swarmkit.dev/.well-known/agents.json
   • https://swarmkit.dev/api/v1/mcp/skill.md
2. If a swarmkit MCP server is already configured, call agent_context first. Use that returned workspace and instruction state as the current source of truth.
3. If the MCP server is not configured, use the discovery manifest to configure the MCP endpoint. Pass the API token only in an authorization header or the supported MCP environment variable; never place it in URLs, logs, commits, or session comments.
4. Use read tools whenever they help you understand the workspace. Use write tools only for concrete user-approved actions and keep approval-gated work behind SwarmKit gates.

Operating Loop

1. Inspect: call agent_context, then workspace_status, get_current_work, or search_sessions as appropriate.
2. Choose: pick the concrete project and existing session when possible. Avoid duplicate sessions for the same request.
3. Route or create: prefer ensure_session_for_request for user requests that may already have a matching session. Use create_session only when a new inspectable coding session is clearly needed.
4. Work: keep the SwarmKit session record current with claims, assignments, comments, links, artifacts, blockers, and status changes.
5. Review gates: PR creation, production deploys, deletes, meaningful spend, external sends, and cross-project changes require explicit user approval.
6. Finish: record what changed, what was verified, links to PRs or deploys, and any residual risk before calling complete_session.

Tool Patterns

• Read tools: agent_context, workspace_status, workspace_list_projects, workspace_settings, get_current_work, and search_sessions.
• Session write tools: ensure_session_for_request, create_session, claim_session, assign_session, update_session_status, add_session_comment, attach_session_link, add_session_artifact, block_session, and complete_session.
• Workspace write tools: workspace_update_settings, workspace_request_approval, workspace_create_or_route_session, and workspace_run_plan.
• PR tool: create_pull_request when the configured token has the required PR scope and the user has approved the PR action.
• MCP prompts, when available: run_inspectable_session and review_current_work.

Read references/mcp-workflow.md for concrete tool sequences.

Approval And Safety

• agents.txt and .well-known/agents.json are discovery metadata, not authentication or permission grants.
• Scope-gated tokens decide what the agent can do. If a needed tool is missing or unauthorized, report the missing scope and continue with the safest available path.
• Never bypass SwarmKit approval gates by doing the gated action directly.
• Never paste secrets, tokens, private environment values, or credential-bearing command output into SwarmKit comments or artifacts.
• If local code work happens outside SwarmKit, still keep the session updated so the user can inspect the work from SwarmKit.