From 9b181a937bccced300039fc364ce7c08bc94e91e Mon Sep 17 00:00:00 2001 From: Ty Balascio Date: Sat, 19 Sep 2026 13:24:41 -0700 Subject: [PATCH] docs(agents): focus AGENTS.md on agent-operational rules The file restated facts owned by other docs and carried personal references. - Drop the status section, the agent-context block, the M3 scope prose, and the 14-bullet invariants list; each restated docs/README.md, docs/MILESTONES.md, or a docs/REQUIREMENTS.md row. - Replace the ports and hosts paragraph with a pointer to docs/DEPLOYMENT.md and deploy/INVENTORY.md. - Correct the subagent rule to the real constraint: one at a time on the single GPU. Subagents do coding work. - Remove the name references. - Keep the structure contract, the change-a-requirement procedure, and the gate commands. --- AGENTS.md | 63 +++++++++++++++++++------------------------------------ 1 file changed, 22 insertions(+), 41 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index c023db6..eada9d2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,54 +1,35 @@ # AGENTS.md -## Status — Phase 2 reconciliation complete +`docs/REQUIREMENTS.md` is the only normative text. All other docs cite IDs; none define requirements. -`docs/REQUIREMENTS.md` (153 rows) is the only normative text; scope is the M3 ID subset in `docs/MILESTONES.md`. -Capability and contract docs live in `docs/capabilities/` and `docs/contracts/`. -Reconciliation evidence is archived under `.audit/archive/`; the coverage ledger and matrices are in `.audit/coverage/`. -Starting implementation is Ty's call; when it starts, implement only the M3 ID subset. +## Structure contract (read before creating or moving any doc) -## Structure contract (read before creating any doc) - -Requirements live only in `docs/REQUIREMENTS.md`; milestone scope in `docs/MILESTONES.md`. -Before creating or moving any doc, look up its home in `docs/STRUCTURE.md` (artifact registry + namespace routing). -If no home exists, stop and ask Ty — do not create a new artifact. -Run `python tools/check_requirements.py` after any docs change; it must pass. +- Requirements live only in `docs/REQUIREMENTS.md`; milestone scope in `docs/MILESTONES.md`. +- Before creating or moving any doc under `docs/`, look up its home in `docs/STRUCTURE.md`. +- If no home exists, stop — do not create a new artifact. +- To change a requirement: edit the single row in `REQUIREMENTS.md`; update `Test`; if scope changed, update `MILESTONES.md`. Do not create a doc. +- Run `python tools/check_requirements.py` after any docs change; it must pass. ## Agent runtime rules -- Subagents (`explore`, `general`) run on a single local GPU and cannot handle concurrency. Invoke only one subagent at a time; never issue parallel subagent calls. -- Subagents are for mechanical extraction only (read and list). They never write and never set a disposition; rulings stay with Ty. +- Subagents run on one local GPU and cannot handle concurrency. Invoke one at a time; never in parallel. -## Agent context +## Gates (must pass before claiming work complete) -Read `docs/README.md` first, then this file, `docs/capabilities/CAPTURE.md`, `docs/capabilities/PHOTOS.md`, and `docs/capabilities/CREATE.md`. +Run from repo root: -Implement **Milestone 3** only. Specification: `docs/capabilities/CREATE.md`. -Product overview: `docs/PRODUCT.md`. +``` +python tools/check_requirements.py +python tools/check_coverage.py +``` -**M3 scope** (what is in vs out) comes from Ty conversations and the reconciled `docs/MILESTONES.md` + `docs/REQUIREMENTS.md`. -**Behavior** for Woo sync, metadata, pricing, and inference is in `docs/capabilities/CREATE.md` and the `docs/contracts/` set. `docs/REQUIREMENTS.md` is the only normative text. +Exit 0 on both = pass. -Do not implement work outside the M3 requirement subset unless Ty expands scope in chat. -Ports `10880`–`10889` are allocated to this project on ubudual5060; `:10880` itself is taken by Ty's local Node/SvelteKit and must not be bound. The dev-test environment runs on ubudual5060 `:10881` (or another free port in the block) and must be reachable from any machine on `192.168.1.0/24` (bind `0.0.0.0`, e.g. `http://192.168.1.202:10881`). +## Pointers (read these for everything else) -## Milestones and capabilities - -Scope and exit criteria: `docs/MILESTONES.md`. Capability specs: `docs/capabilities/`. Interfaces: `docs/contracts/`. - -## Invariants - -- Quantity per listing is one. -- User enters length, thickness, and SKU. -- App may propose remaining listing fields. User reviews before create. -- Non-math fields remain editable until create. -- `bdft = sqft × thickness_in` -- Price proposal is `bdft × species $/bdft`. User may replace it. Missing rate leaves price empty. -- User-entered length, thickness, SKU, price, and taxonomy override computed or inferred values. -- **Woo Slab Taxonomy** means synced species and wood categories; Edge, Figure, Grade, Thickness, Moisture; `fig-*` and `feat-*`. Store is source of truth. -- Woo auth is WordPress application password (server-side). `WOO_BASE_URL` is compose/env. Inference URL is Settings. -- SKUs matching `SLAB-UAT-*` create as Woo draft. -- Create works with inference off. -- Source below the PNG size floor requires a new photo. -- Existing store SKU blocks create. -- Dimension overlay orientation follows the user-approved length axis from Milestone 1. +- Docs map and shipped status: `docs/README.md` +- Scope and ID subsets: `docs/MILESTONES.md` +- M3 behavior: `docs/capabilities/CREATE.md` +- Hosts, ports, UAT environment: `docs/DEPLOYMENT.md` and `deploy/INVENTORY.md` +- Task ordering for M3: `.planning/milestones/v0.5/M3/task_breakdown.md` +- Product invariants and acceptance criteria: the requirement rows in `docs/REQUIREMENTS.md` (cite by ID)