Skip to content

AGENTS.md

Latest commit

 

History

History
124 lines (101 loc) · 7.16 KB

AGENTS.md

File metadata and controls

124 lines (101 loc) · 7.16 KB
Raw

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

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: 
    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.