# AI Pair Programmer: Collaboration Protocol (TMS v2.0)

## ⚡ Critical Rules (Always Apply)

- **Tech Stack**: TypeScript 5.9 strict, Node.js ESM, Nx monorepo, Vitest, AJV (JSON Schema), `yaml`, `chalk`. No runtime framework — this is a CLI tool.
- **Conventions**: Composition over inheritance. Port-based DI (services implement interfaces consumed by the kernel). Hexagonal architecture — provider CLIs are adapters, never imported by domain/application layers.
- **Types**: ALWAYS use strict TypeScript. No `any` in source files. No `@ts-ignore`. Use `import type` for type-only imports (`consistent-type-imports` is enforced).
- **Errors**: NEVER throw raw strings or `new Error("message")` for structured failures. Use `ERROR_CODES` from `apps/control-plane/src/core/error-codes.ts` and return `fail(ERROR_CODES.XXX, ...)` via the `response.ts` helpers.
- **Logic**: Before implementing business logic, check `docs/core/DOMAIN-LOGIC.md`. Before writing code, check `docs/core/PATTERNS.md` for canonical examples.

## 🏗️ Technical Map (Read Order)

AI agents MUST follow this order before proposing or writing code:

1. `NEXT-TASKS.md` (Current context — what work is planned and why)
2. `docs/core/DOMAIN-LOGIC.md` (Invariants, state machine rules, kernel guarantees)
3. `docs/core/PATTERNS.md` (Canonical implementation examples for this codebase)
4. `docs/core/ARCHITECTURE.md` (Component map and data flow)
5. `docs/core/DECISIONS.md` (ADRs — why certain technical choices were made)
6. `docs/core/TROUBLESHOOTING.md` (Known gotchas and non-obvious workarounds)

## 🚫 Prohibitions

<!-- AI-DRAFT: Review before treating as canonical -->

- **Never** store secrets, API keys, or tokens in source code. Provider credentials come from environment variables only.
- **Never** bypass linting (`--max-warnings 0` is enforced) or type-checking (`tsc --noEmit` must pass).
- **Never** use `console.log` in source files under `apps/control-plane/src/`. Only `console.warn` and `console.error` are permitted (ESLint `no-console` is enforced). `console.log` is allowed only in CLI entry points and scripts.
- **Never** use `any` in source files. ESLint `no-explicit-any` is an error.
- **Never** leave floating promises. `no-floating-promises` and `no-misused-promises` are errors — always `await` or explicitly handle.
- **Never** implement features not present in `NEXT-TASKS.md` without asking first.
- **Never** add new commands or flags to the CLI without updating ALL FIVE required files: `types.ts`, `cli-argument-parser.ts`, `bootstrap.ts`, `help-command-handler.ts`, and `CLAUDE.md` / `AGENTS.md`.
- **Never** use `new Error(...)` for domain failures — use `fail()` + `ERROR_CODES` from `core/error-codes.ts`.
- **Never** call provider CLI details (command templates, flags) from domain or application layers. Keep them in `providers/provider-defaults.ts`.

## 🧪 Operational Loop

<!-- AI-DRAFT: Review before treating as canonical -->

1. Read `NEXT-TASKS.md` to understand the "Why" and "What."
2. Check `docs/core/DOMAIN-LOGIC.md` for invariants that must be preserved.
3. Check `docs/core/PATTERNS.md` for canonical examples to follow.
4. Propose change → Justify against domain logic → Recommend implementation approach.
5. After completing any meaningful change, append an entry to `spec-files/progress.md` (see `CLAUDE.md` for format).

## ✔️ Pre-Submission Checklist

<!-- AI-DRAFT: Review before treating as canonical -->

- [ ] Logic verified against `docs/core/DOMAIN-LOGIC.md` invariants.
- [ ] Code follows patterns in `docs/core/PATTERNS.md`.
- [ ] Tests added/updated and passing (`npm run test`).
- [ ] No `console.log` statements in source (`apps/control-plane/src/`).
- [ ] No `any` types introduced in source.
- [ ] `npm run lint` passes with zero warnings.
- [ ] `npm run typecheck` passes clean.
- [ ] `npm run verify` passes clean.
- [ ] `spec-files/progress.md` updated with a new entry.

## Dependency and navigation policy

This repository includes an automatically generated dependency and navigation index produced by **IntentGraph**. You must use it as the primary source of truth for repository relationship questions.

### Required behavior

Use the IntentGraph index first whenever you need to understand:

- Dependency chains between files or modules
- Reverse dependencies
- Import or require relationships
- Likely impact surfaces of a code change
- Which files should be opened next for implementation work

### Index location

- `./docs/core/intentgraph.index.json`

### Required workflow

1. Consult the IntentGraph index to identify the smallest relevant set of files.
2. Open only those files needed to confirm implementation details.
3. Avoid broad repo scanning when the index already answers the relationship question.
4. If the index is missing, stale, or insufficient, regenerate it or explicitly state that analysis is proceeding without a fresh index.

### Token-efficiency rule

Do not load or paste the full IntentGraph output into context. Use only the relevant dependency edges, path segments, or file subsets needed for the task.

### Staleness rule

If the index contradicts the code, assume the index is stale until proven otherwise.

<!-- @cortex-tms-version 4.0.2 -->
