Add AGENTS.md — repo runbook for agents (pyfallow-specific brief) #32
Labels
No labels
area:ci
area:docs
area:engineering
area:framework-fp
area:test-coverage
dogfood:fn
dogfood:fp
dogfood:friction
dogfood:tp
phase:b
phase:c
severity:critical
severity:high
severity:low
severity:medium
source:deepseek-v4-pro
No milestone
No project
No assignees
3 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference
pdurlej/fallow-py!32
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "governance/agents-md-for-pyfallow"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Per operator's voice 2026-05-05: agents need explicit boundaries to prevent the largest-noise antipattern ("agent zawsze będzie dążył do największego napierdalania, żeby pokazać jaki jest ważny"). Without a brief, codex / claude / glm default to over-elaboration. AGENTS.md sets firm boundaries.
What this PR adds
A single new file:
AGENTS.mdat repo root. Pattern adopted frompdurlej/platform/AGENTS.md(master spec, see platform issue #75 for global escalation).Key sections:
Why this matters specifically for pyfallow
Pyfallow is bassist (per ADR 0007 metaphor). Agents default to lead-vocal behavior (largest answer to demonstrate value). Pyfallow as a tool must be the OPPOSITE — disciplined background member, deterministic gate, no opinion-based blocking, no scope creep. AGENTS.md codifies the discipline as contributor contract.
Without this file, codex working on pyfallow tickets defaults to 'I'll fix this AND propose architectural improvements AND extend the test suite' — exactly the largest-noise pattern operator named in voice review.
Mandatory non-author reviewer (ADR 0010 self-test)
PR authored by
claude. Cannot merge without:claude(codex's first review of governance PR for pyfallow — operator's default rotation)pdurlej) clicks mergeIdentity
Commit + PR authored as
claude(claude@noreply.git.pdurlej.com) per identity-isolation. Operator co-authored via commit trailer (decisions are operator's; orchestrator only recorded).— Claude Opus 4.7 (orchestrator), 2026-05-05 morning
request_changes.
CI is green and the governance direction is coherent, but AGENTS.md currently contains hard references to files that do not exist on the PR head branch. I verified these return 404 via the Forgejo contents API:
decisions/0010-mandatory-non-author-reviewer.md,decisions/0011-forgejo-native-ci-pattern.md,docs/philosophy.md,docs/dogfood.md, anddocs/dogfood-log-template.md.Because this PR's purpose is to be the repo runbook agents read first, broken authoritative references are an objective blocker, not a style concern. Please either add/merge the referenced ADR/docs before this PR, or update AGENTS.md to point only at files that exist in this repository revision. After that, the PR should be approvable.
Three governance documents articulating pyfallow's role as a deterministic gate in the operator's multi-agent ecosystem, written under operator direction (anti-AI-slop posture, dogfood before Show HN strategic decision 2026-05-04). docs/philosophy.md — pyfallow as pure function (repo state, config) → findings, no memory between invocations, no opinions about purpose. Position in operator's stack alongside Iskra (relational), platform.exe (deterministic infra gate), Codex (producer), 3+3 canary review (PR gate). Pyfallow is the deterministic code gate counterpart to platform.exe's deterministic infra gate. Cites operator's founding principle ("non-technical product person needs deterministic governance to avoid agents shipping stupidities under my command") in the operator's own words. Lists what pyfallow refuses to be (no opinions, no memory, no opinion-based blocking), what pyfallow promises (determinism, single source of truth across transports, conservative classification, stable fingerprints, drift detection, hostile-input safety). Agent and operator usage protocols. docs/dogfood.md — concrete how-to integrate pyfallow into a Forgejo Actions CI pipeline in operator's other repos (pdurlej/platform, hermes-agency, iskra-openclaw). Three-step minimal integration: copy template, pin to TestPyPI alpha (0.3.0a2), configure .pyfallow.toml for project. Operator decision tree for reading CI comments. Downstream agent reading of pyfallow-report.json artifact. Identity-isolation note per platform AGENTS.md (each actor commits with own PAT, never pushes as operator). Sister project pyfallow-mcp wiring for MCP-using agents. Dogfood window expectations (4-6 weeks starting 2026-05-04) and procedure for disagreeing with pyfallow's findings (issue first, suppress only with reasoning). docs/dogfood-log-template.md — project-agnostic template for keeping a dogfood log when integrating pyfallow into a new project. Categories ([TP] / [FP] / [FN] / [FRICTION] / [SURPRISE] / [WIN] / [META]) and entry format. Recommended copy target is the project's own gitignored working-notes directory (pyfallow uses .codex/ convention). Explicitly explains why this is a template not a live log — the active log lives outside git so operators and agents can add raw, half-formed observations without polishing for posterity. These docs do not change pyfallow's runtime behavior. They codify the operator's strategic direction as project memory, distinct from agent working notes which live in gitignored .codex/. Verified: - All three files render cleanly as Markdown (manual check) - Cross-references between the three resolve (philosophy → dogfood, dogfood → philosophy, both → log template) - No reference to .codex/ paths in published docs (those would be broken for external readers since .codex is gitignored) - Identity-isolation: this commit is authored as `claude` (claude@noreply.git.pdurlej.com) per platform AGENTS.md conventionapprove_merge.
Re-reviewed after branch refresh and public-safety sanitization. The missing-reference blocker is resolved by carrying current ADRs plus the dogfood/philosophy docs. The AGENTS/governance text now uses public-safe wording for identity isolation and infrastructure references, while preserving the repository runbook's operational value. Local evidence on the updated branch: python3 -m compileall -q src tests mcp/src mcp/tests passed, python3 -m pytest -q passed, and PYTHONPATH=src python3 -m pyfallow analyze --root . --fail-on warning --min-confidence medium returned 0 issues.
New commits pushed, approval review dismissed automatically according to repository settings
approve_merge.
Re-approved after the final public-safety cleanup commit. The branch still passes local compileall, pytest, and pyfallow self-audit. The final privacy scan no longer finds Bitwarden, private repo names, internal server names, git.pdurlej.com, local /Users/pd paths, or obvious token/key patterns in the public tree.
approve_merge.
Re-approved after the branch was updated with main. Current head includes #33, prior AGENTS/governance sanitization, and the public-safety cleanup. Remaining gate is CI completion on the updated head.