The Repo

Every change to a requirement is a commit. Every commit has an author, a timestamp, and a message. When a requirement changes after design has started, the change is visible — not discovered when a test fails. When a product decision is challenged three sprints later, the original intent and the reasoning are in the history, not in someone's memory.

A PM proposing changes to requirements creates a branch and opens a pull request. Engineers, designers, and QA can review the changes before they're merged — the same way they review code changes. Comments are attached to specific lines. Discussions are permanent. The agreed-upon requirements are the merged result.

An AI coding agent operating in this repo has the requirements as live context — not a document it was handed a copy of. When a PM asks the agent to generate test cases, create backlog stories, or check for gaps in the acceptance criteria, the agent is working from the authoritative source, not a copy. This is the difference between an agent that can take reliable action and one that produces output that has to be manually verified every time.

PMs writing requirements in this repo are working in the same environment — IDE or CLI with an AI coding agent — where engineers write code, designers reference component specs, and QA engineers review acceptance criteria. This isn't a requirement to learn engineering tools. It's a convergence point: one environment where every role's work lives, where the agent has full context, and where Git provides the coordination layer for all of it.

This is the most important file in the repo. It is the first thing the agent reads and gives it complete context: what ProductHarness is, how the repo is organized, what conventions to follow, which MCP servers are available and when to invoke them, and what the four guiding principles are. It acts as the persistent system-level steering document for every agent interaction in this project.

Why it matters: any agentic coding tool will find and read this file first regardless of tool-specific conventions. It's the universal entry point. Teams don't need to rename or configure anything to get agent orientation — it's there by default.

The agent reads this file when prompted with "finish setting things up." It contains a structured sequence the agent can follow autonomously: checking Node.js, installing dependencies, copying and prompting for environment variables, configuring MCP servers, and verifying the setup is complete. The only human input required is values the agent can't know — API tokens and org identifiers.

Why it matters: setup is a one-time process that every new project goes through. Without SETUP.md, setup requires technical knowledge and manual steps. With it, any team member can get a working harness in one session.

The structured checklist the PM completes before marking work ready for engineering pickup. Covers requirements completeness, acceptance criteria format, open questions, backlog stories, test case generation, and Storybook validation status. It's the explicit accountability mechanism that prevents ambiguous or incomplete work from reaching engineering.

Why it matters: the checklist makes the handoff condition explicit and auditable. Both PM and engineering can see exactly what was verified before handoff — and when something breaks, the checklist is the first place to look for what was or wasn't confirmed.

IaC tool choice, project and stack structure, resource naming conventions, state management, environment separation patterns. Governs how infrastructure-as-code is generated and structured. When a new service needs cloud resources, the agent applies these patterns by default — not whatever it generates from general knowledge.

Approved databases by use case, ORM or query library, migration tooling, naming conventions, indexing standards, connection and pooling patterns. The difference between generated database code that matches production and code that an engineer has to rewrite on every review.

Standard pipeline structure, required gates (lint, test, security scan, build), environment promotion process, approval requirements before production, rollback procedure. Ensures agent-generated CI configuration follows the org's actual deployment process — not a generic template.

Auth provider, token type and handling, session management, RBAC approach, how new services integrate auth from day one. One of the highest-risk standards to get wrong — a new service that implements auth incorrectly creates a security gap that may not surface until it's exploited.

REST vs. GraphQL decision criteria, endpoint naming, HTTP status code usage, error response envelope, versioning strategy, pagination, rate limiting. Governs how API contracts are generated — ensuring every new endpoint follows the same conventions that existing consumers depend on.

Secrets management tool and patterns, required security scanning in CI, dependency vulnerability policy, data classification levels and handling requirements. The most compliance-sensitive standard — may require legal or security team review when updated. Governs how the agent handles any sensitive data or credential-adjacent logic.

Required coverage thresholds, test pyramid ratios, test data strategy, what must pass before a PR is mergeable, performance baseline requirements. The document that converts "tests pass" from a vague signal into a specific standard the agent can generate against and CI can verify.