---
type: Reference
title: "AGENTS-HUMAN.md — the PMOS kit for a human builder (D58)"
timestamp: 2026-07-18
---

# AGENTS-HUMAN.md — the PMOS kit for a human builder (D58)

You're a person, not an agent — same loop, plain terms, one helper. The full protocol lives in
[AGENTS.md](AGENTS.md); this page is everything you need day-to-day. **Never edit `pmos/state/`
files by hand — use the helper**, which validates and appends (records are append-only; a
correction is a new record, never an edit).

## The loop (per piece of work)

1. **Open the work.** Create `pmos/state/initiatives/<id>.md` with a lane
   (`type: feature | discovery | chore | incident | content`) and its artifact — feature: PRD +
   rubric (copy the templates from `pmos/okf/core/templates/`); discovery: a spike brief; chore:
   an `intent:` line; incident: fix first, record within 48h; content: a content brief. Anchor to
   a KR in `pmos/planning/okrs/` — or, for maintenance work with no honest KR, to a declared
   health budget (`parent_kr: health:<id>` from `pmos/planning/okrs/health-budgets.md`). Always
   one or the other; never unanchored.
2. **Branch `initiative/<id>`, do the work.** For feature work, write your tests first where you
   can — the CI you wired via `templates/product-ci-starter.yml` is your Quality Gate.
3. **Record as you go** (each command prints exactly what it appended):

   ```sh
   pmos/scripts/pmos-log.sh run      <run_id> <initiative_id> [human_corrections]
   pmos/scripts/pmos-log.sh eval     <run_id> <initiative_id> <score 0..1> <PASS|PASS-WITH-FINDINGS|FAIL> <rubric_path>
   pmos/scripts/pmos-log.sh accept   <run_id> <initiative_id> <pass|fail> "note"
   pmos/scripts/pmos-log.sh outcome  <initiative_id> <validated|refuted|inconclusive> "evidence"
   pmos/scripts/pmos-log.sh friction "what fought you"
   ```

   The helper rejects bad values with a clear message (wrong verdict/disposition, a
   validated/refuted outcome with no evidence, malformed score) — the same rules the hosted
   backend enforces.
4. **Merge = the Acceptance Gate.** The **accepting human (the PM)** merges and records it
   (`accept … pass`) — if you built it and someone else accepts, they merge, not you. A solo
   operator is their own PM and merges with that hat on. If
   you declared an `outcome_metric` on the initiative, you're not done until you dispose it at
   its horizon (`outcome …`).
5. **Weekly (15 min):** run `python3 pmos/scripts/metrics.py` and read the red first; skim
   `pmos/state/discoveries.md`.

## Working with an agent sometimes?

Mixed teams are fine: agents follow `AGENTS.md`, you follow this page — both write the same state
through the same conventions, and `metrics.py` doesn't care who built.