Three ways to start

• Greenfield — describe a project with no repo; we scaffold a fresh GitHub repo and write the first sprint of tickets.
• Scoped build — pick a repo and name a module or path (e.g. /billing); we change just that part of the codebase.
• Brownfield analysis — pick a repo with no spec; we audit code health, surface tech debt, map the codebase into a knowledge graph, and suggest the first sprints.

The (?) toggle next to “What should we do?” opens an inline guide with the same patterns.

Click Sign in with GitHub on the login page. A consent screen explains exactly what SwarmBoard accesses:

• ✅Reads the code in repositories you select, so agents can understand your codebase.
• ✅Creates branches and pull requests your team reviews and merges — nothing is merged without your approval.
• ❌Never touches repositories you have not selected.
• 🔁Revoke access anytime from GitHub Settings → Installed Apps or Authorized OAuth Apps.

Click Continue to GitHub to authorize.

Go to Settings → Integrations and click Install SwarmBoard. You will be taken to GitHub to install the SwarmBoard App on a GitHub account you administer:

• Your personal account — for personal repositories.
• Any organization you admin — for org-owned repositories.

Choose which repositories SwarmBoard can access. The App acts as swarmboard[bot], touches only the repos you pick, and is revocable from GitHub Settings at any time.

You can install the SwarmBoard App on more than one GitHub account — for example, your personal account and one or more organizations. Each connected account shows up in Settings → Integrations, and you choose which repositories from each account SwarmBoard may access.

Connecting a repo for analysis needs only read access — anyone can do it. Git tracking (PRs, branches, and commits auto-updating your board) requires the SwarmBoard GitHub App installed on the repository’s owner/org — and only a GitHub org-owner or repository admin can install a GitHub App. If the person who onboarded isn’t that admin, they hand the final step to the admin inside SwarmBoard.

You’re here if the board banner shows “Install the SwarmBoard App” or “App installed — Connect this repository to finish.” (If it says “Git tracking on,” you’re done.)

Part A — Project Creator (not a GitHub admin)

1. Onboard the project and connect the repo as usual — analysis runs on read access.
2. The board shows the git-tracking banner — you can’t install the App yourself; that’s expected.
3. Invite the repo’s GitHub admin into the workspace: Settings → Members → Invite member, enter their email, and choose role Admin.
4. Send the invite — analysis keeps running while you wait.

Part B — Repository Admin (the invited GitHub org-owner/admin)

5. Accept the invitation email and sign in.
6. Select the workspace from the switcher (top-left).
7. Open the project → Settings → Integrations.
8. Click Connect to GitHub → on GitHub’s install screen, pick the org/account that owns the repo, choose the repo, and Install (only GitHub admin rights can complete this).
9. Back in SwarmBoard, click Connect this repository — the webhook registers automatically (no manual setup).
10. The banner flips to Git tracking on — PRs and commits now update tickets for everyone.

Tip: the admin should start the install from SwarmBoard’s Connect to GitHub button (so it links to the workspace), not from github.com directly.

What git tracking does

• Pull requests — a PR opened for a ticket’s branch is linked to that ticket, and merging it advances the ticket’s status on the board.
• Branches — agent and human branches that follow the ticket naming convention are matched to their ticket so you can see in-flight work at a glance.
• Commits — commits pushed to a linked branch surface on the ticket as real-time progress, with no manual updates needed.

Without the App, analysis still works (read-only access via your OAuth token), but these real-time board updates from git activity are disabled.

How to enable it

An org admin installs the SwarmBoard GitHub App from the project’s Settings → Integrations tab by clicking Connect to GitHub. Choose the account or organization that owns the repo and pick which repositories SwarmBoard may access. Once the App is installed, git tracking turns on automatically.

Not an admin? Installing the App requires admin rights on the target account or organization. Ask an org admin to install it, or submit the install request from the Connect to GitHub flow — GitHub notifies the org owner so they can approve it. See Logging in & connecting GitHub for the full walkthrough.

Where to find signals

• Recent Signals (board sidebar) — quick read-only peek at the last 20 signals on the project board. Click the “Recent Signals” button on the project page header.
• Blackboard Dashboard — full HITL surface at /dashboard/<projectId>/blackboard. Re-plan dispatch, run sprint retro, prune working memory, post directives, pin signals. Reachable via the project sidebar.
• Recent Activity (dashboard home) — different surface: a timeline of ticket lifecycle events (creations, status transitions, agent failures). Recent Activity is the system log of what happened; Signals are what agents said about it.

Signal types

Broadcast types (blocker, halt, directive, stuck, agreement, debate_conclusion) fan out to all agent sessions; informational types (finding, decision) are scoped to the originating ticket.

Deduplication

Signals are deduplicated at two layers to prevent the panel from drowning in identical noise:

• Emit-time dedup (5-min window) — when a signal is posted via createSignalDeduped, the service checks for an existing signal with the same type + affectsTickets in the last 5 minutes. If found, no new row is created.
• Panel-level dedup — the Recent Signals panel collapses repeated identical signals into a single card with a count badge (e.g., “dev agent failed × 4”).

If you see hundreds of identical signals, that’s a regression — file a feedback report with the project ID.

Acting on signals

• Decisions — click Resolve in the Blackboard Dashboard. Three outcomes: Record as ADR (creates an Architecture Decision Record), Convert to Task (creates a backlog ticket), or Close (archives without persisting).
• Blockers / Stuck — open the affected ticket modal. Triage actions: Restart, Move to next sprint, or Override as done.
• Directives — post from Add Signal on the Blackboard Dashboard. Choose target role (Dev, Reviewer, Test, etc.), priority, and message. Lifecycle: pending → acknowledged → completed.
• Halt — broadcasts to every active agent session for the project. All in-flight agents check for a halt signal between turns and exit cleanly.
• Pin — pinned signals stay at the top of the blackboard regardless of age. Use for must-not-lose context.

Auto-prune & archival

A supervisor task runs every hour and archives signals older than 24 hours (status changes from active to archived). Archived signals stay queryable but no longer surface in the Recent Signals panel. Pinned signals are exempt. The Blackboard Dashboard’s Prune Working Memory button forces an immediate prune for the current sprint.

Real-time updates

The blackboard updates in real time via Server-Sent Events (SSE). Open the Recent Signals panel during an active sprint and you’ll see new signals appear as agents post them — no refresh required.

What auto-generate does

The PM agent reads your confirmed spec (greenfield) or analysis findings (brownfield) and breaks the work into implementable tickets — each sized for a single dev session (max 3 files, 150 lines, 1 endpoint). It sets acceptance criteria, assigns dependencies, and grooms every ticket before adding it to the backlog. No manual story-writing required.

When it fires

• Greenfield projects — triggers automatically after the spec is confirmed (status: spec_confirmed).
• Brownfield projects — triggers automatically after the health analysis completes (analysisStatus: complete).

How to disable auto-generate per project

Open the project, go to Settings → Generation. Toggle “Auto-generate tickets after spec confirm / analysis complete” OFF. A Generate Tickets button will appear on the project board instead — click it when you are ready to commit tokens to ticket generation.

How to set the user-level default

Go to Settings → Preferences (or visit /dashboard/settings/preferences). The toggle there controls the default for all new projects. Existing projects keep their own per-project setting.

Failure recovery

If ticket generation fails (PM agent error, timeout, or budget exhaustion) a Retry generation banner appears at the top of the project board. Click it to re-trigger the PM agent. Check the Signals panel for a blocker signal with the specific error detail.

What project defaults control

• Stack & Brownfield — default technology stack, analysis depth, and boundary mode applied to new projects.
• Quality & Standards — quality profile (speed / balanced / maximum), coding standards list, and architecture pattern selection.
• Agent Configuration — default number of dev agents and reviewers, and the AI model assigned to each role.

Architecture Patterns

Choose one of four primary patterns: Clean (dependency inversion), Layered MVC (traditional controller-service-model separation), Microservices (independently deployable bounded contexts), or Custom (define your own rules). Use the Advanced rules expander to fine-tune per-pattern rules and enable/disable individual requirements.

How to change defaults

Go to Settings → Defaults. Expand the section you want to change, make your selection, and click Save Defaults. New projects created after saving will inherit the updated values.

Three-role model

Invite flow

1. An Admin or Owner opens the Members page and clicks + Invite Member.
2. Enter the invitee’s email and choose their role (Admin / Member / Viewer).
3. An invite email is sent with a join link valid for 7 days.
4. The invitee clicks the link and accepts — their membership becomes active.

GitHub repository access — why it matters

SwarmBoard org membership controls access to the SwarmBoard UI. It does not automatically grant access to the underlying GitHub repository. When a Member or Admin’s agents try to push branches or open PRs, the GitHub API will reject them unless the user also has collaborator access on each project’s GitHub repo.

After inviting a non-viewer member, SwarmBoard shows a reminder card listing each configured project repo with a direct link to https://github.com/<org>/<repo>/settings/access — click Add to repo to add the collaborator in one click.

Auto-adding users to GitHub repos is intentionally NOT done — auto-modifying customer GitHub configurations would require members:write scope on their org, which carries significant security and audit risk. The manual reminder is by design.

Last-admin guard

You cannot remove or demote a member if they are the last admin in the org. The Remove button is replaced with a Last admin badge. To resolve: promote another member to admin first, then remove or demote the original admin.

Transferring admin

To hand over the admin role: open the Members page, change another member’s role to Admin using the role dropdown, then change your own role to Member or Viewer. Because the last-admin guard prevents you from demoting yourself while you are the only admin, the transfer must happen in that order.

How recovery works

• A heartbeat is written every 30 seconds while the worker is alive.
• If the heartbeat goes stale for 5+ minutes, a reconciler marks the run as “interrupted” (or “complete” if all three passes had already finished).
• The amber “still working” variant means the heartbeat just hasn’t ticked yet — usually self-resolves.
• The red “interrupted” variant means recovery already happened; click Resume Analysis to start a fresh run.

Sprint Controls

The sprint action buttons let you manage the lifecycle of a sprint. Start Sprint commits the selected tickets and dispatches agents to begin work. Add Tickets pulls backlog tickets into the running sprint without restarting it. Dispatch re-scans all pending tickets and sends agents to any that are waiting. Halt pauses all running agents gracefully — useful if you spot a problem mid-sprint. Close Sprint archives the sprint after reviewing the results. Reset Sprint returns active tickets to their previous state, which is helpful when a sprint went off-track.

Recent Signals

The Recent Signals panel shows a live feed of what agents are reporting during the current sprint: blockers, decisions, findings, and directives. Click the button to open the panel. The panel is read-only — to send a directive or resolve a decision, use the Blackboard from the project sidebar.

Repeated identical signals within a 5-minute window are collapsed into a single entry with a count badge so the feed stays readable.

Delivery Pipeline

The delivery pipeline shows which stage each ticket is at across six lanes:

• Context — the agent reads the spec and sets up its workspace.
• Breakdown — the architect agent defines the structure and approach.
• Execution — the developer agent builds the feature.
• Review — the reviewer agent checks the code for correctness and standards.
• Done — the code has been merged to the main branch.
• Blocked — the ticket is stuck and waiting for human triage.

Click any stage to filter the board to only the tickets at that point. Counts update live as agents make progress.

Active Sprint

The sticky bar at the top of the board shows the current sprint name, its status badge (planning, active, halted), and a progress counter showing how many tickets are done out of the total. A live count of running agents appears when work is in flight. While the sprint is active, a Halt button lets you pause all agents immediately. Once halted, the button changes to Resume to restart work. The progress bar turns green when every ticket in the sprint reaches Done.

Sprint Columns

The kanban columns show where each ticket stands in the current sprint. Tickets start in the leftmost column and move right as agents work through them:

• New — ticket just created, not yet sized.
• Groomed — spec confirmed, ready for sprint planning.
• Dev Ready — queued for a developer agent to pick up.
• In Dev — an agent is actively writing code.
• In Review — a reviewer agent is checking the code.
• Done — code merged to main branch.
• Blocked — stuck; click the ticket for triage options.

Empty columns are hidden by default to keep the board uncluttered. Click Show all to reveal them.

Hidden Columns

Empty columns are hidden by default to reduce visual noise during active sprints. The counter in the top-left of the board shows how many columns are currently hidden. Click Show all to reveal every column — useful when you want to confirm that nothing slipped into an unexpected state. Click Hide empty to return to the compact view. Columns that contain tickets are always visible regardless of this toggle.

Backlog

The backlog holds tickets that have not yet been assigned to a sprint. When the active sprint is running and backlog tickets exist, a Backlog (N) toggle appears at the top of the board — click it to show those tickets in the columns. Use Add Tickets in the sprint controls to move selected backlog tickets into the current sprint. Tickets created manually via Create Ticket land in the backlog first and can be edited or reprioritized before being committed to a sprint.

At Risk Files

Files flagged as at risk have a high concentration of recent changes, unresolved blockers, or dependency warnings. Agents prioritise these when planning refactors — review the list before each sprint to decide which risks need human attention.

Most Depended On

These files are imported by the highest number of other modules in your codebase. Changes here ripple widely — the graph helps you spot and protect these load-bearing files before an agent accidentally breaks a large surface area.

Unwired Files

Unwired files exist in your source tree but are not imported by any other module. They may be dead code, a feature built but never wired, or a draft. Review this list to prune stale files and avoid confusion during sprints.

Product Spine

AI-powered product delivery for existing codebases. Enables PM, Architect, Dev, Reviewer, and Test agents. Includes brownfield repository analysis, sprint planning, and quality gates. Designed for teams with an existing product codebase who want to accelerate delivery.

Swarm Build

Everything in Product Spine plus automated code generation, greenfield project scaffolding, and the ability to create new GitHub repositories from scratch. Designed for teams starting new projects or wanting full autonomous code generation.

What guardrails protect against

Guardrails intercept actions in six categories: network (unexpected outbound calls), destructive (mass deletions, force-pushes to protected branches), privilege (unexpected permission escalations), exfiltration (writing secrets to logs or disk), injection (prompt injection via untrusted content), and pii (personal data written to repositories).

Guardrail Metrics Dashboard

Admins can view aggregate guardrail activity in the Guardrail Metrics Dashboard. Summary cards show total blocks, warnings, and redactions for the selected time window. The category breakdown identifies which guardrail types trigger most often, and the timeline shows daily event volume to help tune false-positive rates.

What the blackboard does

Every blocker, decision, finding, directive, and handoff during a sprint appears as a signal on the blackboard. Agents read and post signals automatically — you can observe the live feed without doing anything. Use the Blackboard Dashboard for interactive controls: re-plan dispatch, run sprint retro, prune working memory, and post directives.

Blackboard Dashboard vs Recent Signals panel

The Recent Signals panel (project sidebar) is a quick read-only view of the last 20 signals. The Blackboard Dashboard is the full HITL surface with interactive controls, pinned signals, and signal resolution. Both update in real time via SSE.

Model assignment

Each agent role has a model dropdown: Claude (Sonnet / Opus / Haiku), GPT-4o, or Gemini. A common setup is Claude Sonnet for Dev (best code generation), GPT-4o for Reviewer (different training data catches different bugs), and Gemini for Verifier (independent validation). To enable non-Anthropic models, set the OPENAI_API_KEY or GOOGLE_AI_API_KEY environment variables.

Instance counts

More dev instances run more tickets in parallel — useful for large sprints. Each dev needs its own worktree, so token cost scales linearly. 1-4 Dev instances are supported. For PM and Architect, 1 is enough — multiple instances create conflicting plans.

How claiming works

Claiming a ticket creates a feature branch on your project’s repository and pins the ticket to you as the human contributor. Once claimed, the ticket moves to “In Dev” and AI agents will not auto-dispatch to it. You’ll see the branch name and a one-click checkout snippet — run it in your terminal to start coding.

Finishing and releasing

Push commits to the branch and open a pull request to finish. To release a claim without completing the work, click Release claim — the ticket returns to Dev Ready and the branch remains on GitHub.

What webhooks enable

GitHub webhooks allow SwarmBoard to auto-link commits and PRs to tickets, update branch protection rules, and trigger smart notifications when code is pushed. The health indicator in the webhook panel turns green within 30 seconds of the first successful delivery.

Setup options

Auto-register — click the button in Settings → Integrations and SwarmBoard calls the GitHub Hooks API automatically using your OAuth token (requires admin:repo_hook scope). Manual setup — copy the webhook URL and secret, paste them in your repo’s Settings → Webhooks → Add webhook, set Content-Type to application/json, and select the recommended events.

Feature Branch Detection

When you create a Git branch with the ticket id in the name (feat/T-123-add-login, T-123/refactor, bugfix/T-99), SwarmBoard’s webhook handler reads the branch name, finds the ticket, and moves it to In Dev. The branch must follow the convention exactly — case-insensitive T-XXX somewhere in the branch name.

PR Tracking

When you open a pull request from a tracked branch, SwarmBoard moves the ticket to Review Ready. Approvals move it to Merge Ready (when all required reviews are in). Merging the PR moves it to Done. All driven by GitHub webhooks — no need to manually update the ticket.

Manual State Override

If a ticket’s state was set automatically by SwarmBoard (from a branch or PR event) and you change it manually in the board UI, you’ll be asked to justify the override. The justification is recorded in the ticket history alongside the original automatic transition. Helps the team understand why state moved.

Product Spine vs Swarm Build

Product Spine is the human-led package: developers write code, SwarmBoard observes Git activity and updates ticket state. Swarm Build adds AI dev/test agents that generate code automatically — agents create branches, open PRs, and merge them. Your org’s package determines which flow applies. Switch packages in Org Settings → Package.

Sprint Curation

When PM finishes generating tickets, the sprint enters Planning. On Spine projects, the sprint does not auto-start — you stay in control. Pick which tickets you want in this sprint, then click Start Sprint. The board switches to active tracking, and ticket state moves automatically as you push code.

GitHub Activity Tracking

SwarmBoard reads three GitHub webhook event types: branch creation (start tracking), push to a tracked branch (work-in-progress signal), and pull request lifecycle (state transitions). Connect a webhook in Project Settings → Integrations. Without a webhook, ticket state stays manual.

Invite flow

1. An Admin or Founder opens the Members page and clicks + Invite Member.
2. Enter the invitee’s email and choose their role (Admin / Architect / Contributor).
3. An invite email is sent with a join link valid for 7 days.
4. The invitee clicks the link and accepts — their membership becomes active.

Joining without an invite

Every approved SwarmBoard user gets their own workspace auto-created on admin approval. The join page at /orgs/<orgId>/join is only reachable via an invite link — if you arrived without one, your personal workspace is already set up on the dashboard.

Settings sections

• Health — composite org health score and critical findings.
• Members — invite, remove, and change roles for org members.
• Settings — org identity (name, slug), package tier, repo quota, scan retention, capability gate, agent auth, notifications, security, and danger zone.
• Audit Log — every privileged action recorded with actor, timestamp, and change details.

Founder-only actions

Some actions are restricted to the org Founder: deleting the organization, changing the package tier, and managing billing. These actions are flagged inline with a crown icon in the Settings UI. The Founder role cannot be transferred — it stays with the account that created the org.

Three-pass analysis

SwarmBoard clones your repo and runs three passes: a structural pass (module map, imports, routes), a heuristic pass (Haiku — dead code and module types), and a deep pass (Opus — per-module findings and top issues). The resulting analysis feeds directly into ticket generation.

Brownfield vs greenfield

Brownfield means analysing an existing codebase — the PM agent reads the findings to generate improvement tickets. Greenfield means building from a spec with no existing code. You choose the mode during onboarding; it cannot be changed after project creation.

Auto-handoff

For brownfield projects, ticket generation triggers automatically once the analysis status reaches complete. The PM agent reads the module findings and top issues to produce improvement tickets — each sized for a single dev session.

If auto-handoff didn’t fire

On older projects (created before the auto-handoff fix) or when the PM agent’s WIP slot was busy at the moment analysis finished, a recovery banner appears. Click Generate Tickets Now to dispatch the PM agent manually.

Greenfield

You provide a spec; the PM agent breaks it into tickets; agents build from scratch. Optionally connect a GitHub URL as architecture reference (locked mode) — the URL is treated as inspiration and will NOT be cloned or analysed.

Brownfield

Connect an existing repo; SwarmBoard analyses it and generates improvement tickets. The analysis results — module map, findings, health score — guide agent work. Brownfield mode is the basis of Product Spine.

Metrics shown

The Cycle Time view shows average, median, and 95th-percentile time-in-column over the last 30 days. It also shows reviewer responsiveness (PR open to first review) and approval-count progress over time — helping you identify where work stalls in the pipeline.

Access

Cycle Time is visible to org owners and architects. Contributors see only their own PR state. Find it on the project board under the Quality tab.

How the debate works

A Proposer (Claude) suggests an architecture. A Challenger (GPT-4o) critiques it. A Rebutter (Claude) defends or adjusts. An Arbitrator (Gemini) synthesises the final recommendation, produces a convergence score, and lists unresolved points.

Output

The debate produces an Architecture Decision Record (ADR) that is injected into every subsequent agent prompt. The debate result is visible on the project’s Architecture tab.

Reading the graph

Each dot is a module; colour shows health; dot size shows how many other modules depend on it; lines show imports, calls, and data flow. The swimlane layout (UI → Routes → Services → Data) makes dependency flow read left-to-right. Glowing dots are the most-depended-on modules — changes there ripple furthest.

Insights rail

The right-hand Insights rail highlights At Risk modules (high coupling, low test coverage), Most Depended On (high blast radius), and Unwired files (built but not integrated). Use these lists to guide sprint priorities.

Importing transcripts

Go to the Meetings page and click Upload Transcript. Paste text directly or upload a file (.vtt, .srt, .txt, .json, or .md). Add a title and date, then click Import. The transcript is normalised and stored.

How agents use transcripts

The Analyst agent uses meeting context during project onboarding to extract requirements. KPI tiles on the Meetings page show meeting count, specs extracted, action items, and link coverage. You can filter by platform (Zoom, Teams, Meet, Otter, Fireflies), date range, status, and project link.