Skip to content

armgit / Piik

Public Imported from GitHub
0

Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。

8.4 KB
Raw Blame

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:

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:

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.