Agent starter kit

This is the external quickstart for teams adopting Constellation as the coordination layer for their AI agents.

It covers two independent tracks. Most partners only need the first.

Track	What you get	What it costs
A — Connect	Your agent can read and write Project Tracker tasks, issues, and wiki pages (mcp__constellation__*)	One URL pasted into your client. No checkout, no repository access, no Node.js.
B — Scaffold	The pt-coordinator planning agent, portable skills, and an AGENTS.md, generated into your own repo (full set on Claude Code — see prerequisites)	The generator, which lives in our private repo — see its prerequisites

Track A stands alone: you can stop after it and have a working setup. Track B adds the conventions layer — the agent claims a task, implements it, the merge closes the task, and the coordinator answers "what next".

Prerequisites

For both tracks:

• A Constellation account on your tenant. Onboarding provisions the tenant and your access; you do not create either yourself.
• An agent client that can reach the connector: Claude, ChatGPT, Claude Code, or Codex CLI. (Cursor cannot use the OAuth flow — see the note in track A.)

For track B only:

• Your initiative and project details. Onboarding also provisions the initiative, its coordinator_profile, a wiki space and the synthetic agent users, and gives you the initiative ID and project prefixes. The generator needs those; connecting in track A does not.

• A repository-capable coding client. The hosted Claude and ChatGPT apps connect to the MCP perfectly well (track A), but cannot open your repository, so nothing in track B reaches them. For the rest, what the generator writes differs by client — this is a statement about the generator's output, not about what each client reads, which is its own documentation's to make:

  The generator writes	In
  AGENTS.md	the repo root, one file
  pt-coordinator under .claude/agents/	Claude Code's layout
  Skills under .claude/skills/	Claude Code's layout

  It writes no CLAUDE.md — that symlink is a manual step you run yourself in § 2 below.

  AGENTS.md is written once at the repo root, in no client-specific directory. The coordinator and the skills are emitted only under .claude/, which is Claude Code's documented location; no Cursor- or Codex-format equivalent is written. Which of these your client reads is its own documentation's to state — so if the coordinator is the reason you are running track B, check where your client loads agents and skills from and copy the emitted files there, or use Claude Code.

• The starter kit. The generator lives in the Constellation repository, which is private. During onboarding we either grant your team read access to it or send you the kit as a bundle — so the checkout in track B works. If you do not have access yet, ask your onboarding contact. (A public npx-installable package is planned; until then, access is a prerequisite for the generator — it is not needed to connect.)

• Node.js 20+ on your workstation (for the generator; it has zero dependencies).

Before you point an agent at your machine, read Secure agent workstation for the sandboxing and least-privilege advice — a couple of minutes now avoids an agent that can damage your dev station or LAN. On Windows, Windows setup (WSL2 + devcontainer) covers the distro and container setup.

Both guides predate the OAuth flow

Their credential sections still assume a static CONSTELLATION_API_KEY and the generator — including exporting the key from ~/.bashrc and forwarding it into a devcontainer. If you are connecting with OAuth (track A), skip those steps: a long-lived key in the shell environment is precisely what the warning below tells you to avoid. Their isolation and least-privilege guidance applies either way.

Track A — Connect your agent to Constellation

The MCP connector exposes Project Tracker and the Wiki as agent tools (mcp__constellation__*). It is a hosted HTTP endpoint — nothing is installed on your machine and nothing is checked out.

Connector URL — Planet B2B's shared hosted service: https://mcp.planetb2b.com/api/mcp

On a dedicated or self-hosted deployment, use your own URL

Every mcp.planetb2b.com address on this page belongs to the shared hosted service. If your tenant runs its own Constellation — dedicated cloud or on-prem — substitute your instance's connector, health and discovery URLs throughout, in this track and the next. Your onboarding contact has them.

Connecting to the wrong deployment does not fail loudly: you would authenticate against a Constellation that is not yours. Confirm the host before you sign in.

Authentication is OAuth 2.0 (authorization code + PKCE, with dynamic client registration): you paste the URL once, sign in with your normal Constellation account, and approve. There is no static key for you to copy, paste, or rotate. Your client still persists the resulting tokens — a coding client keeps them in its own credential store so the connection survives a restart — so this is not "nothing on disk"; it is nothing you manage. Access tokens are short-lived, grants are individually revocable, and every write is performed as you — the connector carries your own Constellation roles, so an assistant can only do what you can do, and the audit log attributes it to your account.

If a workstation is lost or compromised, treat those stored tokens as live: removing the connector stops the client using it, but ask a Constellation administrator to revoke the grant if you need certainty. The connector page covers this under "Disconnecting".

Cursor cannot use OAuth with this connector today

Cursor's dynamic client registration submits a custom-scheme callback (cursor://…) alongside its HTTPS and loopback ones, and this connector rejects non-http(s) schemes before any allowlist is consulted — then refuses the whole registration because one entry was disallowed. Desktop Cursor fails for the same reason as the cloud agents; no operator configuration changes it.

Cursor therefore needs a static API key. That setup is not covered in this guide — ask your onboarding contact for the currently supported process. Supporting Cursor OAuth properly is a product change, not a configuration one, and is tracked separately.

Per-client steps — one copy-paste command each — are at mcp.planetb2b.com: Claude (claude.ai / Desktop), ChatGPT Developer Mode, Claude Code (claude mcp add --transport http), and Codex CLI (codex mcp add + codex mcp login). Cursor has a panel there too, but it is an unsupported-client notice rather than a setup command. The page also covers what the grant permits, how to disconnect, and what to check when a client will not connect.

Its snippets name the shared hosted service. They are not rewritten per deployment, so on a dedicated or self-hosted Constellation take the commands from that page and the host from your own instance — the page says so too.

Verify the service before you debug your client:

curl -s https://mcp.planetb2b.com/api/healthz

It returns {"status":"ok", … ,"wikiEnabled":true}. If wikiEnabled is false, the deployment has wiki access disabled and only the Project Tracker tools will appear. To confirm the authentication method a deployment offers, read its discovery document:

curl -s https://mcp.planetb2b.com/.well-known/oauth-authorization-server

Then, in your client, ask:

"Use the Constellation MCP to list my in-progress tasks across my projects."

The agent should establish the organisation (list_organisations) and call get_workspace_context without further prompting.

That is a complete setup. Stop here unless you also want the coordinator and the repo conventions.

CI, headless agents, and per-repo configuration

OAuth needs an interactive sign-in, so a CI job or headless agent uses a static tenant API key instead. Some teams also declare the server per repository rather than per user. Neither is covered in this guide — ask your onboarding contact for the currently supported process.

They are deliberately not summarised here. The credential handling has real sharp edges — an ignore rule does not untrack a file, an exported key is readable by any command the repository spawns, and a deployment enforcing OAuth audience rejects static keys outright — and a condensed version of that is worse than a pointer.

Track B — Scaffold the coordinator into your repo

This generates the conventions layer into your own codebase: the pt-coordinator planning agent, three portable skills, and an AGENTS.md. It needs the kit access and Node.js from the prerequisites above — and note the table there: the coordinator and skills are written only under .claude/, with no Cursor- or Codex-format equivalent emitted.

1. Collect your tenant details

From onboarding you have:

• Initiative ID — a UUID, e.g. 3f2b….
• Project prefixes — e.g. ENG, OPS.
• App URL — your Constellation instance, e.g. https://constellation.planetb2b.com.

2. Run the generator

With repo access granted, fetch just the kit with a sparse checkout — this pulls only tools/agent-starter-kit, not the whole platform — and run it. If you received a bundle instead, unpack it and run node <kit-dir>/tools/agent-starter-kit/index.mjs with the same flags.

# from the root of your (possibly empty) repo
git clone --depth 1 --filter=blob:none --sparse \
  https://github.com/B2B-Online/constellation.git .constellation-kit
git -C .constellation-kit sparse-checkout set tools/agent-starter-kit

node .constellation-kit/tools/agent-starter-kit/index.mjs \
  --out . \
  --initiative-id <YOUR-INITIATIVE-ID> \
  --initiative-name "Your Initiative" \
  --project-prefixes ENG,OPS \
  --agent-class claude-developer

rm -rf .constellation-kit

The command deliberately does not pass an app or MCP URL: those flags default to neutral placeholders, so what the generator emits stays host-neutral — it bakes no Constellation-hosted address into a tracked file. The endpoint reaches .mcp.json, which the generated .gitignore covers. Note an ignore rule does not untrack a file the repo already tracked; that case belongs to the static-key wiring, which this guide does not cover.

That is a property of the generator's output, not a rule about your repo: passing --app-base-url / --mcp-url (see below) deliberately writes the host into the emitted scaffold.

Self-hosted deployments

On a dedicated or self-hosted deployment, use your own instance's URLs. If you deliberately want your instance URL committed into the scaffold, pass --app-base-url / --mcp-url to the generator.

Only --out and --initiative-id are required. This writes:

Path	Purpose
.claude/agents/pt-coordinator.md	Planning agent, carrying your initiative ID
.claude/skills/*/SKILL.md	Worktree ritual, task lifecycle, spec authoring
AGENTS.md	Operational entry point
.mcp.json.example	MCP connector wiring
.devcontainer/devcontainer.json	Optional isolated dev environment
.gitignore (appended)	Adds .mcp.json / .cursor/mcp.json

AGENTS.md is the operational file, and it is the name Codex looks for. Claude Code looks for CLAUDE.md, so symlink one to the other and both names resolve to the same content — this repo does the same:

ln -s AGENTS.md CLAUDE.md

3. Verify

Start with the MCP and the guidance file, which do not depend on the .claude/ layout. Open the repo and ask:

"Read AGENTS.md, then use the Constellation MCP to list my in-progress tasks."

It should follow the conventions in AGENTS.md and return your tasks.

Then, if your client loads agents from .claude/agents/ — Claude Code does — ask the coordinator as well:

"What should I work on next?"

It returns a ranked recommendation. That is the wedge loop working on your repo. If your client uses a different layout, that prompt will not reach the coordinator until you copy the emitted files where your client expects them.

Nothing in track B registers the connector for you. If you scaffolded into a repository you will open from a different client or a different environment than the one you connected in — a devcontainer, WSL distro, or VM, none of which inherit a host registration — run track A again from inside that environment first, or the MCP tools will simply be absent.

Where to go next

• Secure agent workstation — run agents under least privilege, with sandbox/permission modes and container/VM isolation.
• Windows setup (WSL2 + devcontainer).
• MCP server reference — the full tool list and auth model.
• Working with AI agents — the conventions behind the scaffolding.