Agent starter kit

This is the external quickstart for teams adopting Constellation as the coordination layer for their AI agents. It takes you from an empty repo to a working pt-coordinator + task-lifecycle setup — the agent claims a Project Tracker (PT) task, implements it, the merge closes the task, and the coordinator answers "what next" — in under 15 minutes, on your own codebase.

You will:

Collect your tenant details and mint an API key.
Scaffold .claude/ + AGENTS.md + MCP wiring with the generator.
Connect the Constellation MCP from Claude Code / Cursor / Codex.
Verify with the coordinator.

Prerequisites

A Constellation tenant. During onboarding we provision your tenant, org, initiative, coordinator_profile, wiki space, and synthetic agent users, and give you your initiative ID and project prefixes. You do not create these yourself.
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 below 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.)
Node.js 20+ on your workstation (for the generator; it has zero dependencies).
An agent client: Claude Code, Cursor, or Codex CLI.

Before you point an agent at your machine, read Secure agent workstation — a couple of minutes now avoids an agent that can damage your dev station or LAN. On Windows, start with Windows setup (WSL2 + devcontainer).

1. Get your tenant details and an API key

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.

Mint a tenant API key: in the Constellation app open Settings → API Keys, create a key labelled for this machine, and copy it once. Export it into your shell (keep it out of the repo — never commit it):

export CONSTELLATION_API_KEY="<paste the key>"

2. Scaffold your repo

With repo access granted (see Prerequisites), 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: the app/MCP URL flags default to neutral placeholders, so the scaffold committed into your repo stays host-neutral — no Constellation-hosted address is baked into a tracked file. You supply the hosted endpoint in the next step, inside .mcp.json, which the generated .gitignore keeps out of version control.

Hosted endpoints

MCP URL: https://mcp.planetb2b.com/api/mcp — goes into your gitignored .mcp.json in step 3. Don't put it in a tracked file. (The legacy https://constellation-pt-mcp.vercel.app/api/mcp host still works as an alias during a grace period, but use the branded URL for new setups.)
App URL: https://constellation.planetb2b.com — only where the Settings → API Keys page lives (step 1); it isn't written into any file.

On a dedicated or self-hosted deployment, use your own instance's URLs. If you deliberately want your instance URL committed into the scaffold (e.g. a self-hosted team), pass --app-base-url / --mcp-url to the generator — that is the only path that writes a host into a tracked file.

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)	Keeps `.mcp.json` out of git

Symlink CLAUDE.md to AGENTS.md so every client picks it up:

ln -s AGENTS.md CLAUDE.md

3. Connect the Constellation MCP

The MCP connector exposes Project Tracker (and the Wiki) as agent tools (mcp__constellation__*). All three clients talk to the same hosted endpoint with your tenant API key; the token is read from CONSTELLATION_API_KEY so it never lands in a file, and the endpoint URL lives only in .mcp.json (gitignored) — so neither the URL nor the token is ever committed.

Claude Code

cp .mcp.json.example .mcp.json

The example ships with a neutral placeholder URL. Edit .mcp.json and set url to the hosted MCP endpoint from the "Hosted endpoints" note above (https://mcp.planetb2b.com/api/mcp). It uses the HTTP transport with an env-var reference for the token:

{
  "mcpServers": {
    "constellation": {
      "type": "http",
      "url": "https://mcp.planetb2b.com/api/mcp",
      "headers": { "Authorization": "Bearer ${CONSTELLATION_API_KEY}" }
    }
  }
}

Cursor

Cursor reads .cursor/mcp.json (already covered by the generated .gitignore). Use the same shape:

{
  "mcpServers": {
    "constellation": {
      "url": "https://mcp.planetb2b.com/api/mcp",
      "headers": { "Authorization": "Bearer ${CONSTELLATION_API_KEY}" }
    }
  }
}

Codex CLI

Codex speaks streamable-HTTP MCP natively, so point ~/.codex/config.toml at the hosted endpoint and have it read your tenant API key from the CONSTELLATION_API_KEY environment variable (the one you exported in step 1) via bearer_token_env_var — so, like the other clients, the token never lands in a file:

# ~/.codex/config.toml
[mcp_servers.constellation]
url = "https://mcp.planetb2b.com/api/mcp"
bearer_token_env_var = "CONSTELLATION_API_KEY"

Restart any running Codex session after editing. (To connect to a local dev instance instead of the hosted endpoint, see the MCP server reference.)

4. Verify

Open the repo in your client and ask:

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

The agent should call get_workspace_context without further prompting. Then ask the coordinator:

"What should I work on next?"

It returns a ranked recommendation. That is the wedge loop working on your repo.

One-click connector (coming)

The steps above use a pasted tenant API key. A one-click OAuth connector — add "Constellation" as a custom connector in Claude.ai / ChatGPT and click Connect, no token paste — is being rolled out (tracked as INF-164). When it is live for your tenant, prefer it: it supports per-grant revocation and keeps no long-lived key on disk. Until then, the API-key path above is the supported flow.

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.

Prerequisites​

1. Get your tenant details and an API key​

2. Scaffold your repo​

3. Connect the Constellation MCP​

Claude Code​

Cursor​

Codex CLI​

4. Verify​

One-click connector (coming)​

Where to go next​