webcodex AGENTS.md

AGENTS.md — WebCodex Repository Guide

These are the always-on rules for ordinary repository work. Read only the linked sections needed for the current task. A deeper AGENTS.md governs its directory.

V1 active development

V2 development is paused; V1 is the active product line and is not feature-frozen. Ordinary V1 work may add explicitly requested capabilities as well as correctness, reliability, and test improvements. Keep changes focused and do not weaken safety, credential, process-tree, transport, durability, or boundedness contracts.

1. Verify and preserve

• Work only in the repository, worktree, and external target authorized by the user.
• At task start, verify the root, branch, HEAD, status, relevant changes, and recent history. Recheck only after a Git operation, an observed concurrent change, or before committing.
• Treat prompt hashes, paths, branches, and runtime state as expectations to verify, never as reasons to overwrite the actual repository.
• Preserve unrelated work. Do not reset, rebase, restore, clean, or rewrite history unless the user explicitly requests that operation.
• Inspect only the implementation, tests, documentation, and diff relevant to the task; do not bulk-read unrelated material.

2. Build the simplest useful product

• Optimize for a workflow that is simple, obvious, and easy to operate.
• Prefer the smallest direct solution. Add abstractions, configuration, modes, compatibility layers, or extension points only for a concrete current need or a demonstrated reliability problem.
• Do not build a general framework for one use case. Wait for a second concrete use case before extracting shared machinery.
• Do not design for hypothetical consumers, tenants, deployment scales, or trust boundaries that the product does not have.
• Protect real boundaries—credentials, public entry points, destructive actions, wrong-target execution, repository history, and published artifacts—without adding policy machinery for imaginary ones.
• A feature that introduces a new externally reachable authority, credential audience, or replaceable runtime target creates a concrete present boundary. Model it explicitly when reusing an existing scope, identity, or lease would broaden existing credentials or allow stale requests to retarget; fewer concepts is not a reason to collapse distinct authority.
• When two designs satisfy the current need, choose the one with fewer concepts, states, configuration paths, and maintenance costs.
• For model-facing execution, prefer structured process/argv and durable Job/observation primitives over shell-text orchestration. Keep shell as an escape hatch; structured lifecycle state is the source of truth for retry safety.
• Keep model-facing ToolSpec/OpenAPI operation descriptions concise and prefer 300 characters or fewer when semantics remain complete. Never delete necessary authority, retry, continuation, uncertainty, safety, or recovery semantics merely for brevity; the canonical tested hard ceiling is MODEL_TOOL_DESCRIPTION_MAX_CHARS.
• Treat demonstrated host features such as MCP App orchestration as optional adapters. Core execution and Job semantics must remain protocol-, UI-, transport-, and OS-neutral.
• Never assume a model-facing HTTP/MCP request has stable model-window or Workflow Session identity. Treat requests as stateless unless that exact adapter/protocol contract explicitly supplies a stable ClientWindow. Stateless MCP 2026 must not derive hidden continuity from Mcp-Session-Id, connection state, credentials, project identity, or prior requests. Transport/audit/session correlation ids are not Workflow Session, model-context-retention, or authority proofs by themselves; use explicit durable identifiers from their owning domain. Connector Tasks, Workflow Sessions, durable Agents/Conversations, and future Agent Tasks are distinct identities and must not be inferred from one another.