Repository Guide

Agent Foundation is built on Harness, an embeddable agent execution foundation. Harness UI is its interactive playground for individuals and trusted small teams; Service is the managed-agent runtime. Both embed Harness and own distinct access, persistence, and execution lifecycles.

Sources of Truth

• CONTRIBUTING.md owns contribution workflow, setup, and validation. Read the sections relevant to the requested change and handoff.
• DEVELOPMENT.md owns code quality principles and component engineering standards. Apply Code Quality and Design to features, bug fixes, refactoring, and reviews; read the component rules and owning specifications relevant to the change.
• Before changing browser UI, shared components, or UI review fixtures, read and follow the shared design system and applicable product guide: Console or Harness WebUI. For interaction changes, also read the behavior contract linked by that guide; for shared changes, check affected consumers.
• spec/repository-model.md owns repository structure and workflow boundaries. Read it before changing either.
• spec/README.md leads to the accepted product and architecture contracts. Keep proposals, discussion, and progress in GitHub Issues; changes are reviewed through pull requests.
• docs/ contains Markdown user documentation and its meta.json navigation; the Fumadocs site in frontend/apps/a13n-docs publishes it. Documentation Changes owns authoring conventions.
• MAINTAINERS.md owns semantic reviewer routing.

Read the relevant contribution and engineering sections before changing that surface. Reuse sections already read unless they changed. This guide and skills summarize operational rules; they do not replace the owning contracts. Do not turn personal preferences or tool-specific defaults into repository requirements without an explicit project decision.

Write canonical repository content in English; localized user documentation and UI translation resources use their target language, as required by CONTRIBUTING.md.

For local Service work, use the stable Make targets and discover checkout-specific ports with make dev-status; dev/service/README.md owns lifecycle and data boundaries. New or changed Service JSON query endpoints default to explicit MCP admission; follow MCP Query Endpoints for the marker, scope exclusions and validation.

Scope and Authorization

When drafting or updating Issue and PR titles and bodies, follow Writing Issues and Pull Requests, including its requirement to read and follow the applicable repository Issue template before creation through browser, CLI, or API. This writing guidance is mandatory for agents and discretionary for human contributors.

• Carry requested changes through implementation and relevant validation. Resolve routine choices from the request and repository evidence; ask only when missing information materially affects correctness, scope, or authorization. Existing authorization carries across follow-ups.
• An audit or review is read-only unless fixes are requested. Local editing does not itself authorize committing, pushing, GitHub writes, merging, deploying, or releasing. Each action must be covered by the request or established authorization; loading a skill grants none of these permissions.
• Preserve unrelated work and secrets. History rewrites, destructive cleanup, and changes to shared or deployed state require authorization covering the concrete operation and target.
• Unresolved product, architecture, security, compatibility, or scope decisions follow the Issue-to-PR workflow. Complete independent, authorized work while those decisions remain open. Routine corrections do not require a new Issue, and the workflow does not authorize posting one on the user's behalf.
• Explicit user instructions take precedence over skill guidelines, subject to system and developer instructions. Resolve apparent conflicts using the request and existing authorization. If work remains blocked by an applicable skill instruction, link its SKILL.md, quote the requirement, and explain the missing decision or authority while continuing independent authorized work.

Keep diffs focused and update affected contracts, implementation, tests, docs, and automation together. Report the outcome, changed files, validation, and material limitations concisely.

Package and Release Boundaries

Python 3.13 and packages/* use uv; Rust crates live under crates/. Component source directories and distributions use canonical a13n- names, while Python imports replace hyphens with underscores (for example, packages/a13n-stream-protocol, a13n-stream-protocol, and a13n_stream_protocol). Service SDKs and the companion remote CLI belong to independent repositories. Optional checkouts under ignored sdk/ are not inputs to this repository's workspaces or validation; follow each SDK repository's own guide for SDK work.

For packaging and release changes, read repository boundaries, release rules, and the owning workflow. The Harness group includes Harness and Stream Protocol at one exact release version; Harness UI and Service release independently with exact Harness-group pins and bounded independent dependencies; Harness pins Pydantic AI to a reviewed minor line. Source workspace dependencies remain unversioned and project versions stay 0.0.0; each consuming manifest owns cross-group bounds in [tool.a13n.release-dependencies], injected only for publication. See dependency compatibility lines before changing those bounds. frontend/apps/a13n-harness-ui is private build input included in the UI wheel and sdist, and frontend/apps/a13n-console likewise in the Service wheel, sdist and image, with no independent release or committed build output; rebuilding either wheel from its sdist requires no Node.js. RC releases never advance Docker or npm latest.

When releasing Harness, review whether Service and Harness UI should advance their exact Harness and Stream Protocol pins together, and validate each updated consumer before its release.

High-Risk Engineering Rules

Retain these constraints and read DEVELOPMENT.md for the full service engineering contract:

• Keep service I/O async and use canonical storage helpers. Never hold a database session or transaction across agent execution, external I/O, waits, background work, or streams. Streaming routes must not receive yielded database sessions, including through authentication dependencies.
• Generate migrations with the owning Make target against a disposable database, then review rollout safety; never write revisions from scratch. The worker role never migrates. The all and control roles auto-migrate under bounded PostgreSQL advisory locking; a dedicated migration job disables replica auto migration.
• Build one non-root service image with runtime role selection. Libraries use namespaced a13n-logging loggers; executables configure logging once.
• Keep model-visible and user-trace identifiers concise and kind-prefixed. Preserve entropy where unpredictability is part of a security or protocol contract.

Validation

Follow CONTRIBUTING.md for validation scope, required gates, and Make targets. Reuse successful checks whose relevant inputs remain unchanged. Report commands, outcomes, and unavailable checks accurately; do not claim a gate passed when it did not run.

For visual changes, inspect affected rendered states and viewport sizes. Small copy or style edits need a focused check; exhaustive visual audits and full suites are not routine prerequisites.

Choose local validation from the changed behavior and its actual dependency impact. Use make verify VERIFY_ARGS=--dry-run to inspect automatic selection, or run focused Make targets/test files directly when the necessary scope is already known. Review broad fallbacks before executing them. Include downstream tests when a shared behavior or contract affects them; a shared-package path alone does not require all consumer suites. Reuse passing checks and stop once the affected risks are covered. Do not add full suites, builds, image smoke tests, or impact-map recording merely for handoff or because a file is included in a shipped artifact. CI retains the complete applicable gates. See the owning validation policy for cache controls and cases requiring broader checks.