# AGENTS.md

> A "README for agents" — the context a coding agent needs to work on this project.
> This starter was generated by `3pwr init`. Fill in the `[bracketed]` parts for your project, and keep
> it accurate as the code evolves. For a richer, project-analyzed version, run your `create-agentsmd`
> skill/prompt. Format: <https://agents.md/>.

## Project Overview

[Brief description of what this project does, its architecture, and the key technologies/frameworks.]

## Setup Commands

- Install dependencies: `[package manager] install`
- Start the dev server: `[command]`
- Build for production: `[command]`

## Testing Instructions

- Run all tests: `[command]`
- [Test locations, naming conventions, and coverage expectations.]
- Add or update tests for the code you change, even if nobody asked.

## Code Style

- [Language/framework conventions, linter + formatter commands, file organization.]

## 3Powers — the trust workflow (use `3pwr` as the main command)

This repository is governed by **3Powers**: the spec is the law, agents execute, and an independent
judiciary (an oracle, a deterministic gate suite, and a human sign-off) decides whether the code obeys.
**`3pwr` is the primary command for delivering change here** — not ad-hoc edits.

- **Author + drive work through the lifecycle.** Prefer the one command:
  `3pwr run "<what you want built>" --mode auto` — the native executive dispatches each stage to a
  headless agent and stops only at the two human gates (spec approval, final sign-off). Or drive stages
  by hand: `3pwr oracle` → `3pwr gate run` → `3pwr verify` → `3pwr signoff` → `3pwr advance`.
- **Gate your change before hand-off:** `3pwr gate run --path <dir> --spec <spec> --tier <tier>` emits one
  normalized verdict; `3pwr verify` re-checks the signed ledger offline; `3pwr advance --stage ship`
  refuses without a green verdict **and** a human sign-off.
- **On an existing codebase**, start with `3pwr characterize --module <path>` and adopt gradually
  (`--report-only` → `--diff-scope`).

### Hard rules for agents (non-negotiable)

- **The spec is the law.** Don't put implementation detail (a named DB, framework, or stack) into spec
  text. When in doubt, re-read the spec; don't infer scope.
- **Stay within a task's declared file scope.** Editing outside it is a signal to stop and re-spec.
- **Don't author the oracle if you are the coder.** The oracle (acceptance tests from the spec) must come
  from a different model family and must not read the implementation.
- **Don't game gates** — no inline lint-disables, type suppressions, deleted assertions, or weakened
  thresholds. Attempts are flagged for human review, never silently absorbed.
- **Don't approve your own work.** A human — not the agent's prompter — signs off on the spec and the
  residual.
- **Hand off committed artifacts, never chat summaries.**

## Pull Request Guidelines

- Work on a **feature branch**, never directly on the default branch.
- Title format: `[component] Brief description`; reference the requirement ID(s) the change traces to.
- Required before hand-off: `[lint command]`, `[test command]`, and a green `3pwr gate run`.

## Additional Notes

- [Project-specific gotchas, environment variables, or troubleshooting tips.]
