AGENTS.md

This file is the harness-agnostic contract for AI-assisted work in this repository.

The universal baseline ends at the Project Specifics marker.

The Project Specifics section defines how this repository applies the baseline.

Instruction format

• Write one independently testable instruction per bullet.
• Use the section heading to provide context.
• Put rationale in a separate paragraph.
• Put examples in a separate paragraph.
• Keep each Markdown paragraph on one physical line.
• Keep each Markdown list item on one physical line.

Instruction discovery

• Read the nearest AGENTS.md before changing files.
• Treat the nearest AGENTS.md as authoritative for its directory tree.
• Load .agents/roles/leader.md when acting as the primary agent.
• Load .agents/roles/teammate.md when accepting delegated work.
• Load .agents/roles/adjudicator.md when reviewing a disputed or high-consequence decision.
• Load a skill only when the user invokes it or its stated trigger applies.
• Load only the project documents relevant to the approved objective.
• Keep harness-specific instruction files as pointers to this contract.

Project truth

• Treat docs/concept/ as accepted product intent.
• Treat the Project Specifics section as the repository execution contract.
• Treat BUILD_STATE.md as the latest verified repository checkpoint.
• Treat executable evidence as authoritative for implemented behaviour.
• Treat a runtime ledger as authoritative only for live worker state.
• Treat conversation history as non-authoritative context.
• Resolve contradictions in favour of the source that owns the disputed fact.
• Surface unresolved authority conflicts to the user.

Approved objectives

• Treat approval of a bounded implementation objective as authorization to complete that objective.
• Plan the approved objective when no adequate plan exists.
• Update the plan when implementation reveals new in-scope work.
• Continue automatically after planning.
• Continue automatically after an internal task completes.
• Ask the user only when a decision would materially change product intent.
• Ask the user only when a decision would materially expand scope.
• Stop when required authority falls outside the approved objective.

Scope and safety

• Trace every changed line to the approved objective.
• Preserve unrelated user changes.
• Use an isolated checkout when unrelated changes overlap the write area.
• Keep secrets out of tracked files.
• Keep local environment values out of tracked files.
• Leave generated output unchanged unless the objective owns its generation.
• Leave dependency lockfiles unchanged unless the objective changes dependencies.
• Keep debug artifacts out of the completed change.
• Use the project logger for retained diagnostic output.
• Preserve type-system guarantees.
• Validate untrusted values at their boundary.
• Obtain explicit approval before destructive data mutation.
• Obtain explicit approval before destructive history rewriting.
• Obtain explicit approval before deployment.
• Obtain explicit approval before using paid external resources.
• Obtain explicit approval before communicating outside the approved delivery workflow.

Delegation

• Give one writer exclusive ownership of each overlapping write area.
• Use isolated worktrees for concurrent writers.
• Treat teammate output as untrusted until the Leader verifies it.

Validation

• Begin implementation from a known green commit.
• Run focused checks while implementing.
• Run integration checks when independently implemented areas converge.
• Run the complete declared validation suite before final delivery.
• Exercise changed behaviour against the running product when practical.
• Exercise interaction-bearing work from the actor's natural entry point.
• Reach an observable result before accepting interaction-bearing work.
• Treat direct-route tests as supporting evidence.
• Treat isolated component tests as supporting evidence.
• Repair failed validation within the approved objective.
• Stop when validation cannot be restored safely.
• Report every skipped required check.

Delivery

• Keep the integration branch recoverable during execution.
• Create cohesive checkpoint commits when they improve recoverability.
• Update BUILD_STATE.md only at meaningful checkpoints.
• Record material implementation decisions in BUILD_STATE.md.
• Record material deviations in BUILD_STATE.md.
• Finish the approved objective in a clean worktree.
• Finish the approved objective with the declared validation suite passing.

Continuity

• Checkpoint verified state before expected context loss.
• Record active ownership before expected context loss.
• Record the next action before expected context loss.
• Prefer a small reversible implementation choice when the accepted intent permits several options.
• Record a material reversible choice in BUILD_STATE.md.
• Stop before making an unapproved product-policy decision.
• Restore a green state before ending interrupted implementation work.
• Leave an explicit blocker when a green state cannot be restored.

Repository structure

• Store reusable project instructions under .agents/.
• Store role identity contracts under .agents/roles/.
• Store user-invoked procedures under .agents/skills/.
• Author a project skill at the lowest directory level that needs it.
• Keep one BUILD_STATE.md per repository scope.
• Keep workspace state separate from child-project state.

Project Specifics

Descriptor

• Treat this repository as the canonical AI Protocol source.
• Keep the distributed contract harness-agnostic.
• Keep the starter limited to AGENTS.md, LICENSE, three startup roles, and five lifecycle skills.
• Treat repository maintenance as instruction-only work unless the release workflow or helper script changes.
• Require explicit maintainer direction before changing the distributed baseline.
• Require explicit maintainer direction before changing a distributed role.
• Require explicit maintainer direction before changing a distributed skill.

Governance and runtime

• Use BUILD_STATE.md as the latest verified source-release checkpoint.
• Treat this repository as having no runtime control ledger.
• Keep provider-specific routing outside the distributed protocol.

Validation gates

• Run git diff --check before source delivery.
• Run bash -n kickstart.sh before source delivery.
• Validate every canonical skill frontmatter before source delivery.
• Validate every referenced startup role before source delivery.
• Run the atomic-instruction scan before source delivery.
• Run the exact starter archive assertions from .github/workflows/release-starter.yml before source delivery.
• Run a complete ambiguity audit before source delivery.
• Verify the published archive manifest after release publication.
• Verify the published archive checksum after release publication.

Stack-specific rules

• Preserve release asset names expected by kickstart.sh.
• Keep release packaging deterministic.
• Keep symlinks out of the starter archive.
• Keep repository-only documents out of the starter archive.
• Keep repository-only examples out of the starter archive.
• Keep repository-only assets out of the starter archive.
• Update README lifecycle claims when the distributed contract changes materially.
• Update examples when the planning model changes materially.
• Update BUILD_STATE.md at each release checkpoint.