# Product Thesis

This repository is a template for agent-ready software teams that want repeatable work, not improvised chat transcripts.

The product bet is simple:

- every serious repository needs a visible operating contract for agents
- the contract should be executable where possible, not only described in prose
- reusable thinking patterns should live as skills
- durable execution roles should live as native subagents
- vendor adapters should translate the core contract instead of becoming the contract
- Claude Code compatibility should be visible for adoption and discovery without making Claude-specific files canonical

## Audience

This template is for teams that already care about review quality, security posture, and verification discipline, and now want agent work to meet the same bar.

Primary users:

- founders and staff engineers setting up agent-native engineering systems
- platform teams standardizing how agents operate across repositories
- R&D teams that need fast exploration without losing traceability
- production teams that need small diffs, safety gates, and clear ownership

## Problem

Most repositories give agents scattered instructions:

- one README for humans
- hidden local tool settings
- vendor-specific prompts
- informal team habits
- CI that checks code but not the agent operating contract

That makes agent work brittle. Each task starts with rediscovery, delegation is inconsistent, and safety rules live in memory instead of the repository.

## Positioning

This template treats the repository as the agent control plane.

The canonical surface is:

```text
AGENTS.md          repo-wide operating contract
.codex/            native Codex config, hooks, and subagents
.agents/skills/    reusable thinking and workflow patterns
```

Everything else supports, demonstrates, verifies, or adapts that surface.

## Differentiation

The template is not just a file scaffold. It provides:

- a canonical contract that agents must read first
- deterministic hooks for safety and audit behavior
- subagent roles with bounded responsibility
- skills that encode repeatable work patterns
- bootstrap profiles for downstream adoption
- smoke tests that validate both happy paths and regression failures
- adapter boundaries so optional integrations do not own the core design
- optional Claude Code compatibility through `.claude/` and `CLAUDE.md`

## R&D And Production Fit

R&D work needs speed, hypothesis tracking, and explicit uncertainty.

Production work needs narrow scope, verification, rollout discipline, and rollback clarity.

This template supports both by separating:

- research briefs from production changes
- decisions from implementation
- review posture from execution posture
- reusable workflows from subagent roles

## Success Standard

A repository based on this template should make agent work easier to trust.

Success means:

- agents can discover the rules without hidden local state
- humans can review why a change was made and how it was verified
- unsafe commands and secret access are blocked before execution
- downstream teams can delete optional adapters without breaking the core contract
- the repository demonstrates a repeatable cognitive system, not only a directory layout