AI coding agents

Start the demo stack (The demo application), open your agent in the repository, and describe what you want built. AGENTS.md is the contract it works to: it initializes Orbitron before anything else, so it works from this project’s installed Kinetis versions and verified layout rather than from recalled framework knowledge.

Getting a session ready

The agent can only initialize on a turn, never between turns, so it checks on every turn until the orbitron tools and resources are listed. Until then it answers questions about setup and these instructions, and nothing else.

  1. Complete the stack’s initial setup, docker compose up --build -d, so the app image exists and its vendor volume is populated. The MCP server runs in a disposable container built from that image. The launcher can do this part itself on a fresh clone (below), but its first launch then takes as long as the build and the install.

  2. Reload, restart or reconnect the client when the MCP configuration arrived or changed after the session started, or when an earlier launch failed before step 1 completed.

  3. Approve the project-local orbitron server under your client’s own policy (Trust and approval).

  4. The agent reads kinetis://orbitron/context and kinetis://docs/agent-workflow, calls orbitron_inspect, checks that the checkoutRoot it reports is this checkout’s pwd -P, and calls orbitron_verify.

  5. It reports readiness in one line, then gets on with your request:

    Orbitron ready — kinetis/framework <installed-version>, layout pass (App\, App\Tests\).

An agent with a shell does step 1 itself. Steps 2 and 3 are yours: it cannot reconnect the server it runs inside, or approve itself. When a step fails it stops, names the step, quotes the error and points you to Diagnostics. A refusal to start is the contract working.

What is checked in

  • AGENTS.md, the agent contract and the only place it is written. CLAUDE.md and GEMINI.md import it.

  • bin/orbitron-mcp, and one configuration per client: .mcp.json, .codex/config.toml and .gemini/settings.json. Each registers the stdio server orbitron, launched as ./bin/orbitron-mcp, plus the Nuxt, Vuetify and Vue documentation servers for frontend work.

bin/orbitron-mcp runs vendor/bin/kinetis-orbitron-mcp through docker compose --progress quiet run --rm -T --no-deps --entrypoint sh on the app service: a one-off container from app’s image, sharing its project and vendor mounts but not its lifetime. --entrypoint sh skips the entrypoint’s composer install on every launch, and --no-deps starts no other service. On a fresh clone the launcher sets itself up: it copies a missing backend/.env from backend/.env.example (set JWT_SECRET in it before the app itself boots), and when the vendor volume has never been populated it runs composer install under the entrypoint’s own vendor/.install.lock, with its output on stderr, so it never writes the tree while app does. Restarting, recreating or rebuilding app leaves a session connected. The container sees every checkout as /workspace/demo/backend, so the launcher passes the host path in KINETIS_ORBITRON_CHECKOUT_ROOT, which orbitron_inspect reports as checkoutRoot. The host needs no PHP and no Composer.

That one server is the whole registration. The Kinetis documentation arrives on the same connection, as kinetis://docs/* pages. Those pages describe Kinetis main, so orbitron_inspect and the installed-source tools stay the authority for anything version-sensitive. The tools read any installed package, kinetis/vector included; vendor/ is a Docker volume, so they are also the way to reach it from the host. See Orbitron for every tool.

Trust and approval

The checked-in files register a server and configure nothing else: no credential, no trust override, no preapproved tool. Your client’s own trust and approval policy applies, and it differs by client. Claude Code prompts about a project-scoped .mcp.json in an interactive session. Codex reads .codex/config.toml only for a trusted project. Gemini CLI may ignore workspace settings in an untrusted workspace, where a server without trust keeps its default, false.

Reload or restart the client when this configuration was added or changed after the current session started.

Client differences

Client

Reads instructions from

Project MCP configuration

Claude Code

CLAUDE.md (imports AGENTS.md)

.mcp.json, after its project-server prompt

Codex

AGENTS.md

.codex/config.toml, for a trusted project

Gemini CLI

GEMINI.md (imports AGENTS.md)

.gemini/settings.json, subject to workspace trust

Any other MCP client

AGENTS.md

Register ./bin/orbitron-mcp as a stdio server named orbitron.

Without MCP

The four Orbitron documents are commands too, for an agent that only has a shell, or for you:

docker compose exec app vendor/bin/kinetis orbitron:context
docker compose exec app vendor/bin/kinetis orbitron:inspect
docker compose exec app vendor/bin/kinetis orbitron:verify
docker compose exec app vendor/bin/kinetis orbitron:scaffold

orbitron:scaffold --apply is the only one that writes, and it writes two fixed files. Inside the container, orbitron:inspect reports /workspace/demo/backend as both roots: the container’s view, not the host checkout. See Appendix: Orbitron.

Diagnostics

The server fails to start on a fresh clone. Its first launch builds the app image when it is absent and installs the dependencies into an empty vendor volume, and a client whose server start-up timeout is shorter reports it as failed. Bring the stack up, then restart the client:

docker compose up --build -d
docker compose ps

An app restart, recreation or rebuild. It does not disconnect Orbitron, which runs in its own container. Nothing to do.

The server was there and is gone. Docker stopping, or the client ending its own process, removes the one-off container. Launch or connect the client again; the stack itself can still be healthy.

docker compose down fails with a network still in use. A live session keeps its container on the project network, so down removes app and then fails:

Network <project>_default Resource is still in use

End the client session, run down again, and relaunch the client once the stack is back up.

The server shows as disconnected. Run the launcher yourself. A working server answers a handshake on stdin:

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"manual","version":"0"}}}' \
    | ./bin/orbitron-mcp

A result naming kinetis-orbitron-mcp means the launcher and the server work, and what remains is the client: its trust policy, or a tool catalog that has not picked the server up yet.

A dependency change. It needs no restart. Orbitron reads the installed-package inventory on every call, so after a composer require the next orbitron_inspect already sees it.

orbitron_verify reports an error. The code of each failed check names the outcome. This project keeps the layout Orbitron admits, one autoload.psr-4 prefix mapped to src/ and one autoload-dev.psr-4 prefix mapped to tests/, so an error means demo/backend/composer.json moved away from it. See Appendix: Orbitron for every code.

See also