bitty-mcp: Instructions file for Codex

Bitty MCP repository guidance

Repository and authority

• This is the independent bitty-mcp repository. Its canonical remote is https://github.com/bitty-terminal/bitty-mcp.
• The Bitty umbrella directory and bitty-plugins directory are grouping only; neither owns this repository's Git or CarryCtx state.
• Enter this repository before running Git, CarryCtx, validation, or toolchain commands.
• bitty-docs is the canonical source for product architecture, security, interface, protocol, and public-behavior contracts.
• The project is pre-implementation. Do not describe an empty repository, configuration file, example, or design proposal as working product behavior.

Current scope

• Documentation and repository governance may be initialized when the active CarryCtx task permits it.
• Do not add product code until a separately authorized task has accepted protocol, security, and interoperability gates.
• bitty-mcp is an adapter and integration boundary; it must not silently become the terminal core, plugin host, or source of Terminal Truth.
• Keep exact transports, schemas, authentication mechanisms, client support, and write-capable operations open until accepted by reviewable contracts.

CarryCtx and agents

• Use this repository's CarryCtx state for tasks, teams, dependencies, scopes, sessions, progress, decisions, checkpoints, handoffs, and review.
• Install the carryctx CLI globally for local development (recommended): cargo install carryctx or npm i -g carryctx; the npm package is also declared in package.json for discovery.
• The commander coordinates. Delegate substantial scoped work to focused agents and require an independent reviewer for acceptance.
• Every agent reads its persona and applicable rules, binds a named session to the task, and stays within explicit scopes.
• After the first commit, prefer a dedicated branch and Git worktree for each independent task. Before it, shared-checkout initialization is allowed only for disjoint scopes with CI-equivalent local checks.
• Branch and worktree naming follows ctx-XXXX/<type>-<short-slug> and .worktrees/ctx-XXXX-<type>-<short-slug> (one branch per task; cmd/<slug> is reserved for commander housekeeping).
• Preserve unrelated changes. Do not commit, push, release, or mutate remote state without explicit authorization.
• Fresh clones have no CarryCtx state DB. Restore the local DB from the in-repo snapshot branch with just workflow-import (validate-only: just workflow-import-dry). It fetches refs/heads/carryctx-snapshots, refuses to replace a non-empty local DB without --force, and prints provenance and restored counts. Snapshots are redacted publication artifacts from carryctx export --publication: never merge them back, and rotate at the source any secret that leaked before rotation.