AGENTS.md · diff
git:20260319.d56f2f1 to git:20261010.a05d44a
123 added, 4 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
- <!-- BEGIN:nextjs-agent-rules -->
- # This is NOT the Next.js you know
+ # AGENTS.md
- This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices.
- <!-- END:nextjs-agent-rules -->
+ > 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.