Working with AI agents in Constellation

Constellation is built and operated primarily through AI agents (Claude Code, Codex CLI, Cursor, Aider, ChatGPT Custom Connectors, and the pt-coordinator subagent). The conventions that make this work — spec-first development, fragment-per-PR changelogs, mandatory CI gates, auto-derived release labels, the bracket-link webhook — are spread across half a dozen files in the repo. This page is the single entry point.

Where to start — decision tree

Open the file that answers your specific question; don't try to read everything.

If you are…	Open…
Starting any agent session	.ai/constitution.md — the unchanging architectural invariants (tenancy, schema-per-module, no cross-app imports, event contracts append-only, audit-critical, route wrapping, no any, spec-driven, pipeline-is-the-contract). Read once per session. Operational rules live in AGENTS.md; the constitution is the layer above.
Grounding before you write code on any non-trivial task	The KB retrieval docs (the consult-the-kb skill) — query the knowledge base (query_knowledge_base MCP / npx pt query-kb) for prior decisions / conventions / lessons, then cite the slugs you used. The KB is the canonical compounding grounding source (ADR-015); the flat files below are the zero-dependency bootstrap.
Doing module-local work in apps/directory/, apps/catalog/, apps/project-tracker/	The agentic/standalone-guide.md for that module: Directory, Catalog, Project Tracker — task-focused playbook (MUST/MUST NOT, layer call direction, worked example, common rookie mistakes)
Planning across modules ("what should we work on next?", "is this duplicating something in flight?")	The pt-coordinator subagent — read-only programme-wide planner. Ranks open work, checks for overlap, returns a recommendation
Looking for a shared rule (tenancy, RLS, audit, route wrapping)	docs.planetb2b.com/architecture/rules — every rule has a stable slug-anchor; cite by URL
Looking for the build / release / CI commands	Root CLAUDE.md — pre-push checklist, key commands, commit conventions, release flow
Looking for the binding repo-wide policy	Root AGENTS.md — invariants, task-router table, project status, tech stack
New to the codebase entirely	intro — onramp for humans + AI agents, with C4 L1 inline
Tracing one request end-to-end	Request lifecycle — annotated trace from browser to Postgres and back

Ecosystem map

The agent surfaces and what each one is for:

Surface	Purpose	Lives in
Claude Code	Primary development agent. Runs locally in a terminal; writes code, runs tests, opens PRs.	~/.claude/ (local config); .claude/agents/ for subagents
Codex CLI	OpenAI's terminal agent. Same auth model as Claude Code (.env.local autoload).	INF-29 wired up the setup; see tools
Cursor / Aider	IDE / inline-code agents. Use the same MCP stdio surface as Claude Code.	Per-IDE config — typically points at tools/mcp-server/
constellation MCP server	Exposes the Project Tracker REST API as MCP tools. Two transports: stdio (for desktop agents) and Streamable HTTP (for ChatGPT Custom Connectors)	tools/mcp-server/
knowledge-base wiki space (the KB)	The compounding, queryable agent memory — decisions, conventions, lessons. Read index-first via query_knowledge_base / npx pt query-kb and consulted first on every non-trivial task; written by the curation funnel. Canonical for what the team has learned (ADR-015).	The knowledge-base space in the Wiki module; read seam + tool in kb-retrieval
pt CLI	Shell wrapper around the same REST API the MCP server exposes. For agents that don't speak MCP.	npx pt <subcommand> — see CLI reference
pt-coordinator subagent	Read-only programme-wide planner. Inherits all PT MCP tools but cannot edit code.	.claude/agents/pt-coordinator.md
Spec lifecycle triad	spec-author drafts; spec-reviewer audits before implementation; post-impl-reviewer audits the diff before PR. All read-only except author.	Subagents page — files under .claude/agents/
Module developers (×6)	catalog- / directory- / project-tracker- / wiki- / platform- / infra-developer. Path-scoped to one module; refuse cross-module edits.	Subagents page
memory-curator subagent	Curates .ai/lessons.md on a weekly / per-release cadence. Only edits the lessons file.	Subagents page
General-purpose subagent	Standard Claude subagent for parallel research / implementation tasks.	Built into Claude Code

The runtime sequence one HTTP request takes inside Constellation is identical regardless of which agent surface invoked it — see Request lifecycle.

Document hierarchy — when each file wins

The repo has more than one source of truth on purpose. When two of them appear to disagree, the more specific one wins:

docs.planetb2b.com/architecture/rules     ← canonical, slug-stable, cite by URL
                ↑
       AGENTS.md  (binding policy + task router)
                ↑
       CLAUDE.md  (commands + conventions)
                ↑
   apps/<module>/CLAUDE.md  (module-local context)
                ↑
   apps/<module>/agentic/standalone-guide.md  (single-task playbook)
                ↑
       .ai/lessons.md  (append-only review corrections — newest first)

A correction in .ai/lessons.md overrides general guidance in CLAUDE.md, which overrides general policy in AGENTS.md, which is itself a citation of the rules pages. After receiving a code-review correction, append a new entry to .ai/lessons.md so the next agent doesn't repeat it.

Two knowledge layers — flat bootstrap vs. the KB

The stack above is the bootstrap layer: flat, git-tracked files readable on a clean checkout with no MCP, auth, or network, and partly CI-gated (check:agent-docs, the spec-format and AC-traceability gates). It is the cold-start entry point and the CI contract, and it does not retire.

Above it sits the knowledge base — the knowledge-base wiki space, the compounding, queryable, provenance-tracked synthesis of the team's decisions, conventions, and lessons. Per PLT-128 / ADR-015, the KB is canonical for what the team has learned and decided, and every agent consults it first — via the consult-the-kb skill (KB retrieval docs: query_knowledge_base / npx pt query-kb) — on every non-trivial task, citing what it used. The flat files stay canonical for how to bootstrap and what CI enforces.

Where a fact lives in both, the wiki-curator (the PLT-265 daily lint plus the per-release LLM judgement pass) flags contradictions as structured findings; the authored-source rule resolves each — the flat file wins for bootstrap / CI-gated content, the KB wins for compounding decisions and lessons. The retire-vs-mirror calls for the load-bearing flat files are flagged in ADR-015 for human ratification, not decided unilaterally.

The 4 mandatory pre-push gates

CI will not let a PR merge if any of these fail. Run them locally before pushing:

Gate	Command	What it catches
Format check	npx prettier --check "**/*.{ts,tsx,js,jsx,json,md}"	Inconsistent quotes, trailing commas, table alignment in markdown.
Turbo pipeline	npx turbo run lint typecheck build test	ESLint, TypeScript strict, every app builds, every test passes.
Route wrapping	npm run check:routes (scripts/check-route-wrapping.ts)	A withAuth not paired with withTenantAuth in apps/catalog/src/app/api or apps/directory/src/app/api.
SonarCloud quality gate	Runs in cloud — read the PR's SonarCloud check. Fix high + medium bugs, vulns, smells.	Maintainability + security regressions that ESLint doesn't catch.

The full pre-push checklist (with format-fix, route-wrap escape hatch, etc.) is in root CLAUDE.md.

See also

• Workflow — end-to-end worked example: spec → branch → changeset → PR → Copilot loop → release.
• Tools — pt CLI, MCP server (stdio + HTTP), pt-coordinator subagent, env-var checklist.
• Architecture rules — every binding rule with a stable slug-anchor.
• Request lifecycle — what one HTTP request goes through inside the platform.