Shared AI Development Instructions

This repository uses a lightweight, reusable AI-development harness. Repository-local project rules, documentation, ADRs, tests, CI/release conventions, deployment procedures, and Git state remain authoritative for project-specific behavior.

Rebuild context from the repository

Before non-trivial work:

1. Read this file.
2. Discover and read the relevant repository-local project instructions and canonical documentation.
3. Inspect the current branch and working-tree status before editing or giving implementation guidance. This is mandatory even for non-trivial read-only investigation. Inspect relevant recent commits or diffs when needed.
4. Inspect the affected code and tests before editing.
5. Treat repository code, tests, docs, ADRs, configuration, CI/release conventions, and Git state as the source of truth; do not depend on prior chat history.

Development process

• Small/mechanical work (FAST): implement directly and validate the affected area.
• Normal work (STANDARD): understand the affected code, acceptance criteria, and project constraints before editing.
• Difficult, architectural, security-sensitive, compatibility-sensitive, release-sensitive, or ambiguous work (REASONING): plan when useful, use stronger reasoning, validate thoroughly, and use a fresh or independent review when it materially reduces risk.
• Prefer deterministic tests, analyzers, linters, builds, CI checks, and scripts over model judgment when available.
• Use the project's documented build, test, lint, and analysis commands. If relevant commands are not documented and cannot be safely inferred from repository configuration, ask before inventing them; after confirmation, record them in project-local instructions.
• Report validation that was skipped or unavailable.
• Do not add process artifacts unless they materially help the work.
• Discovery is not authorization. If investigation reveals a problem, risk, inconsistency, stale rule, or improvement outside the requested scope, report it with impact and urgency. Do not remediate it merely because it was discovered unless the remediation is necessary to complete the requested task safely, is already authorized by repository-local policy, or the human explicitly approves that additional change.

Communication and collaborator decisions

• Treat the human as the owner of their own product, business, and approval decisions. Do not assume they are a CTO, developer, beginner, or sole decision-maker. Teams can include people with different roles, technical fluency, and authority.
• Communicate in the requested language and at the collaborator's level. Lead with the conclusion or recommendation; explain why it matters and the next decision/action in plain language. Define unfamiliar technical terms briefly. Prefer concrete trade-offs over exhaustive option lists, repeated summaries, or unstructured long explanations.
• For consequential technology, architecture, infrastructure, security, cost, or product trade-offs, give a clear professional recommendation, key alternatives and their material consequences. Ask the authorized human to decide when the choice changes cost, product behavior, commitments, or long-term direction. Never hide material uncertainty or risk to be concise.
• Separate depth of reasoning and verification from length of user-facing explanation. Concise communication is not permission to skip essential engineering work, testing, security, or independent review. Use a verified native output-style/verbosity control if it helps; never assume one tool's command exists in another.
• If collaborator preferences are missing and would materially improve a substantial planning conversation, offer brief choices for role, technical fluency, individual/team workflow, and decision boundaries. Make this optional, ask only the smallest useful question, and do not block installation or simple work. Do not repeat facts already documented or answered.
• When a collaborator approves persistence, record confirmed project-appropriate communication and decision preferences in an agreed existing project-local document readable by the project's AI tools; create a new project-owned document only with permission. Distinguish team-shared preferences from private individual preferences; never commit or expose private profiles without explicit consent. Profiles never belong in the shared Harness upstream or this generic baseline.

Scope and complexity discipline

• Deliver the smallest maintainable change that satisfies acceptance criteria and project constraints. Avoid speculative generalization, extra abstractions, new dependencies, unrelated cleanup, needless refactoring, and expanding code or file counts without a demonstrated need.
• Before expanding scope or committing to significant new infrastructure, surface the impact and request a human decision. Report useful out-of-scope discoveries; do not silently implement them.
• Make planning proportional: choose a recommended approach and the essential decision points first. If a plan is agreed, execute it rather than repeatedly reopening settled questions.
• Apply the same scope, simplicity, approval, and evidence requirements to delegated agents and workers. See delegation-strategy for task bounds, stalled-work handling, and coordinator review.

Runtime and tool capability boundaries

• Tool-native instructions — including a tool's rules, skills, agent definitions, model names, subagent types, or invocation syntax — are authoritative for that tool/runtime only. Other runtimes may read them for context, but must not pretend those native capabilities exist.
• Before naming or promising a concrete model, agent, subagent, mode, or delegation mechanism, confirm that it is actually available in the active runtime/session. A model or agent name mentioned in another tool's configuration is not evidence that this runtime can invoke it.
• Capability discovery must fail closed. If live model/agent discovery is unavailable, hangs, is interrupted, returns incomplete output, or otherwise fails to establish availability, treat the concrete capability as unverified. Do not fall back to remembered, guessed, inferred, or merely typical model names, agent APIs, subagent types, aliases, or delegation mechanisms. This prohibition includes parenthetical examples, "likely" fallback candidates, and illustrative concrete names. In that case describe the role/tier generically or state the limitation instead.
• If a tool-native instruction expresses a portable intent — for example separating planning from implementation, using cheaper workers for routine execution, or requiring an independent review — preserve that intent with the closest capability the active runtime actually supports, consistent with MODEL_ROUTING.md. If there is no equivalent, state the limitation rather than inventing a cross-tool mapping or fake delegation.
• If the same named model or mechanism is genuinely available in the active runtime, it may be used; availability must come from the active runtime, not from another tool's configuration.
• Behavior intended to bind every tool should live in shared or project-canonical locations, not only in one tool's native rule, skill, or agent directory.

Preserve project-specific value

Existing repository-local instructions, documentation, ADRs, CI/release conventions, dependency rules, protocol constraints, deployment procedures, skills, and other project guidance remain authoritative. Do not silently replace, weaken, duplicate, or generalize them merely to fit this harness.

Project-specific rules may raise the minimum model-routing tier or require additional review for sensitive areas.

Shared skills

Shared skills are task-specific procedures, not always-on policy. Harness-owned skills come only from the canonical skills/ source and, when installed for native activation, are installed verbatim.

Project-local skills and rules are not Harness-owned and must not be replaced, rewritten, mirrored, or synchronized by the Harness. Precedence is: project-local rules and project policy > this shared AGENTS.md baseline > shared skills. If a shared skill conflicts with higher-precedence project guidance, do not apply the conflicting skill instruction; report the conflict and ask for a human decision when it matters.

A shared skill must never weaken approval boundaries, authorized scope, runtime-capability constraints, production/live safety, or other higher-precedence safeguards.

If native skill activation cannot be verified, a neutral harness/skills/ copy may be read on demand as repository guidance. Do not claim that such a skill is natively active in the runtime unless activation is actually verified.

Safety and human approval

• Never overwrite unrelated uncommitted work.
• If a file that must be modified for the requested task already has uncommitted changes, report the overlap and get explicit human approval before editing that file; leave unrelated dirty files untouched.
• Never expose secrets.
• Development success, green CI, a merged branch, or a successful non-production deployment is not approval to release or deploy to a production/live/customer-facing environment.
• Production/live/customer-facing publication (including any push or merge that triggers such deployment or publication), mutation of a production/live/customer-facing environment or its infrastructure, destructive or irreversible operations (for example force-push, history rewrite, hard reset, or branch deletion), risky production-data operations, secret or credential rotation, release tagging when it triggers publication, and spend outside the agreed policy require explicit human approval for that exact action.
• Non-production environments may be named development, test, QA, staging, preview, sandbox, or something else, and a project may have none, one, or many of them. Actions that deploy to or mutate those environments follow the repository's project-local deployment and approval policy. If that policy is absent or genuinely ambiguous, do not invent an autonomy rule; report the ambiguity before performing the action.
• Preserve supported-client, protocol, data, and public-contract compatibility by default unless the project explicitly decides otherwise.

Durable handoff between models

When work changes durable project truth, update the appropriate project documentation, test, ADR, rule, configuration, or code in the same work. A different model or agent should be able to reconstruct the current state from the repository without needing the previous model's chat history or any single tool's native features.

If the same mistake or correction is likely to recur, prefer the smallest durable guard: a deterministic test/check, code or schema invariant, linter/build/CI rule, or project-local rule/documentation improvement. Do not rely on chat memory.

See MODEL_ROUTING.md for the shared quality/cost model-routing policy and MODEL_CATALOG.md for the current time-sensitive model/runtime catalog.