Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。
Agent Context And Documentation Governance
- Reviewed: 2026-08-27
- Scope: repository context, durable memory, documentation types, and decisions
- Status: evidence; repository policy is owned by documentation ownership
Findings
Repository Context
OpenAI's agent-first repository treats AGENTS.md as a map into a structured,
versioned knowledge base. Its reported failure mode for one large instruction
file is the same one observed in Piik: scarce context is crowded out, every
rule appears equally important, stale guidance accumulates, and ownership is
hard to verify. The recommended corrective structure is progressive disclosure,
cross-links, and mechanical freshness/structure checks. Codex concatenates the
applicable project instruction chain until project_doc_max_bytes, whose
default is 32 KiB.
Hermes distinguishes project conventions (AGENTS.md) from user preference,
personality, and learned memory. Its persistent memory is deliberately bounded
and curated; full session history remains searchable on demand rather than being
injected into every prompt. Memory is a frozen session-start snapshot, so it
cannot replace current repository truth. Its context-file limit is configurable
or dynamically derived with a 20,000-character floor, and it recommends staying
below that value and using nested context for genuinely distinct subtrees. Its
bounded-memory guidance starts consolidation at 80% rather than treating the
hard limit as the normal operating target.
Piik therefore warns at 80% of a loader limit, then fails at the loading boundary:
32 KiB for the Codex chain and 20,000 characters for Hermes. The same envelope applies to the
repo Ponytail skill because AGENTS.md requires it for coding work. A failure tells the
maintainer to use nested/path-scoped context, on-demand skills or linked docs,
remove duplication and completed history, and delete stale conclusions; raising
the ceiling is not the default remedy.
Sources:
- OpenAI Harness engineering
- OpenAI Codex
AGENTS.md - Hermes file ownership
- Hermes context files
- Hermes persistent memory
Documentation Shape
Diataxis separates tutorial, how-to, reference, and explanation because mixing reader goals makes each form harder to use. Piik's internal product modules are compact reference; ADRs are explanation of a decision; deployment is a how-to/reference boundary; research is evidence and explanation. The framework does not require creating all four categories when there is no reader need.
An ADR should be a short record of one decision: context, decision, material consequences, status, and links to supporting evidence. If a decision changes, the old record is superseded instead of being expanded into a current manual.
Git commits and pull requests own completed history. Current product and operations documents should not preserve rejected alternatives, release diaries, or agent process solely for chronology.
Sources:
Instructions And Skills
Reviewed: 2026-10-24. These are source-derived design considerations, not a benchmark of agent reliability or another set of mandatory instructions.
OpenAI's current guidance favors task-scoped references, short skill descriptions and explicit completion boundaries. Its documented OSS workflow separates repository policy from reusable skill methods. The Agent Skills community guidance likewise recommends coherent purposes, detail proportional to task fragility, and refinement against real execution. A skill need not carry its own scripts, reference tree or elaborate procedure to be useful.
Codex loads an instruction chain from global scope through the working directory; more specific project instructions follow broader ones. Skill descriptions select workflows whose bodies load on use. Same-named skills are not merged, so Piik links its repo adaptations explicitly. This loading behavior is distinct from project authority: a skill cannot grant a release, change an accepted product contract or weaken a user's task boundary.
The community Ponytail and Stop That Shit approaches support reuse and completion with less speculative work. Piik keeps those principles but evaluates total ownership and the complete experience, rather than line count or the first working implementation. Its Ponytail adaptation removes forced persistence, fixed response length and per-branch test prescriptions; upstream attribution remains in the skill's provenance. New mechanisms still need relevant end-to-end evidence. Required design thinking does not imply a separate design document, review agent or approval for each edit.
OpenCode's instructions make several of these decisions concrete: validate at the owning boundary, extract helpers for real concepts or reuse, test production code, and use existing generation and delivery commands. Piik consolidates these in its existing rule owners rather than adding another rule catalog. Its Bun, Effect, import and loop preferences remain specific to that repository.
The public X discussion, read through linked mirrors, particularly recommends the speculative-complexity rule and its companion about single-use helpers. Replies also distinguish retry correctness from speculative hardening and question unsupported probability estimates. Piik therefore asks for agreement on extra speculative scope, while authorized, reachable defects remain ordinary fixes.
Sources:
- OpenCode AGENTS.md, reviewed revision.
- Dave Kiss's X discussion, public mirror; helper-rule reply, retry-correctness reply and probability-estimate reply.
- OpenAI: Rethinking skills and prompts
- OpenAI: Using skills for OSS maintenance
- Codex instruction discovery and skill loading
- Agent Skills best practices and specification
- Stop That Shit and STSS: complete the responsibility and omit unnecessary work or self-justifying prose.
- Avoid Over-Defensive Programming: fix the producing owner; Piik does not adopt a per-branch reporting procedure.
The earlier community reports about small-task expansion and ignored context motivate inspecting useful output and execution cost; they are anecdotes, not statistical evidence about a model.
Applicability
Piik is small enough that a vector database, memory provider, generated code map, parallel agent-context format, or separate RFC repository would add more ownership than it removes. The useful practices are bounded always-on context, one owner per fact, domain-shaped reference, evidence on demand, short ADRs, link checks, and Git-backed history. Exact repository policy remains in documentation ownership, not in this research note.