# AGENTS.md

> Read automatically by Jules — and by Cursor, Copilot, and most other
> AGENTS.md-aware tools — at the start of every task. This is the persistent
> version of the "Standing Rules" block in
> `docs/designs/2026-07-08-jules- prompts.md`. Once this file is committed to
> the repo root, you no longer need to paste that block before each prompt.
>
> This file is the cross-tool entry point. `.ai/agents.md` remains the internal,
> MCP/skill-oriented convention for IDE agents working in a local checkout
> (Antigravity, Cursor, VS Code) — the two complement each other and should not
> drift apart. Deeper per-workstream detail lives in `docs/designs/` and in each
> PROMPT's own text; this file stays short on purpose.

## Commands

```bash
npm run check-types && npm test && npm run validate:skills   # run + paste output before opening any PR
npm run format:check && npm run lint                          # must also pass
```

## Stack quirks

This project pins a Next.js version with breaking changes from what most
training data expects — APIs, conventions, and file structure may differ. Read
the relevant guide in `node_modules/next/dist/docs/` before writing any Next.js
code. Heed deprecation notices. This is Pillar 1 in practice: ground decisions
in what's actually installed, not what's familiar.

`packages/core/src/install/{surfaces,reconcile,refresh,lock,version}.mjs` run
inside the MCP server at every start (they refresh users' installed editor
files): async I/O only (a test fails on any `*Sync(` call), stderr only, and
TS files that core Jest loads must not import them (Jest cannot require `.mjs`).

## MCP tool naming & skill acquisition contract

If your client connects to the `tech-lead-stack` MCP server (e.g. Cursor,
Antigravity, or a web chat UI) and a tool call like `get_skills` or
`verify_mission_alignment` fails as "not found," the client may have prefixed
the tool name — check for `mcp_tech-lead-stack_<tool>` or
`tech-lead-stack_<tool>` in your available tools list and call the resolved
name. Not applicable if your environment doesn't connect to this MCP server.

**Strict Skill Acquisition Contract (NON-NEGOTIABLE):**
All calls to `get_skills` or `get_skill` MUST supply the required 4-tuple:
`{ skillName: string, projectName: string, model: string, agent: string }`.
Omission of these parameters corrupts telemetry tracking and is strictly prohibited.
**No Workflow Conflation:** Workflow files in `.agents/workflows/` are launcher
entry points, NOT skill definitions. Reading a workflow file via `view_file` or
`cat` does NOT satisfy Phase 0. You MUST execute the MCP `get_skills` tool call
as your very first action to load the full skill specification and initialize
mission telemetry.

## Four Pillars — non-negotiable, and how your output is graded

1. **G-Stack / Diagnosis-First** — Phase 0 before any code: read `package.json`,
   `tsconfig.json`, `prisma/schema.prisma`, and the files named in your task.
   Ground every decision in what actually exists here.
2. **MinimumCD / Atomic Batches** — vertical slices under 100 LOC per commit,
   each independently verifiable. Never one big-bang commit.
3. **Production-Grade Ethos** — no "tests later," no "seems right." Every slice
   ends with real command output pasted into the PR. Catching yourself
   rationalizing a shortcut is the signal to stop and do it properly instead.
4. **Modern Web Guidance** — UI/web-facing code uses Server Components, Zod
   validation, semantic HTML/ARIA. No legacy workarounds.

## Policies & Execution

Agent policies and constraints are centrally enforced across the entire AI lifecycle. Note these critical architecture changes:
- **Nine Phases**: All work is categorized into exactly nine phases (intent, specify, plan, build, maintain, review, scale, deploy, polish). Every skill frontmatter and telemetry metadata payload MUST declare a valid phase.
- **Typed Artifact Handoffs**: Skills no longer pass arbitrary context. Deliverables (spec, plan, diff, etc.) are explicitly typed and handed off via Knowledge Items (KIs).
- **New MCP Tools**: We've introduced `plan_pipeline` to sequence orchestrators and `approve_knowledge_item` to formalize KI handoffs. Note that `get_skill` now appends a dependency graph footer outlining upstream/downstream connections.
- **Dynamic Policies (`.ai/policies`)**: Policy documents are loaded dynamically into agent contexts to guide operational decisions without hardcoding logic.
- **Hooks Layer (`.ai/hooks`)**: Ownership gates and capability boundaries are strictly enforced at MCP call-time and validated in CI via a dedicated hooks enforcer.
- **Execution Targets**: You operate under one of four execution tiers (`local`, `sub-pro`, `sub-max`, `byo`). Each has specific latency, context, and capability budgets (e.g., `local` enforces single-lane pipeline).

## Model & env freshness check

Model ids go stale silently: a retired or mistyped id fails only at call time,
and the fallback paths then hide it. Run this check when it is **due** (on or
after *Next due* below) or **at once** when a call fails with a model error —
`404`/`not_found` for a model, "model … not supported/deprecated/retired", a
schema error naming a model id, or `API key not valid`. Keep it cheap: no model
calls, no full-repo reads.

1. Inventory — model names only, never print key values:
   ```bash
   grep -rnoE "['\"](claude|gemini|gpt)-[a-z0-9.-]+['\"]" packages/core/src packages/core/scripts apps/dashboard/src --include='*.ts' | grep -vE "test|__tests__"
   grep -E '^[A-Z_]*MODEL[A-Z_]*=' .env
   ```
2. Check each id against the free model-list endpoints (Anthropic
   `GET /v1/models`, Gemini `GET /v1beta/models`, OpenAI `GET /v1/models`) or,
   without a key, the vendor's deprecations page.
3. Replace only ids that are missing, deprecated or a generation behind. Keep
   both `MODELS` copies (`packages/core/src/lib/ai/constants.ts`,
   `apps/dashboard/src/app/api/chat/constants.ts`), `MODEL_CATALOG`, the routing
   `LADDERS` and both pricing tables (`telemetry-service.ts`,
   `reflexion/pricing.ts`) in step. Never drop a catalog id that saved
   `User`/`Project` settings still use. Keep critic ≠ planner (model
   separation). Claude 5.x ids need `@ai-sdk/anthropic` ≥ 4 (older versions
   force tool use, which those models reject).
4. Update the dates below in the same PR.

Last verified: 2026-10-03 · Next due: 2027-01-03. Known upcoming: Gemini Flash
prices double 2027-01-01; `claude-haiku-4-5` retires no sooner than 2026-10-15;
`claude-opus-4-6` / `claude-sonnet-4-6` no sooner than February 2027.

## Git discipline

Work only on the feature branch named in your task. Never merge, never touch
`main`, never force-push. Deliver via a single PR. (Extends `.ai/agents.md`,
which forbids `git push`/`git add` for agents in local checkouts — as a cloud
agent you may commit, but to **your own branch only**.)

## Code style

Strict TypeScript, no `any` without a justifying comment, early returns, Zod
validation on every API payload and external input.

## Scope

Don't rename, move, or "improve" files outside your task. If something
out-of-scope looks broken, write it in the PR under **"Observed friction"**
instead of fixing it — friction reports are first-class input here, not noise.