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. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。

9.9 KB
Raw Blame

Documentation Ownership

The repository is the durable source across sessions, devices and agents. Use the documentation map to find a topic, then update its owner. Chat, agent summaries and an old branch do not replace current code, contracts and evidence. Task authority stays in AGENTS.md; delivery and verification procedures stay in CONTRIBUTING.md.

Owners

Topic Owner Keep here
Universal constraints and navigation AGENTS.md Short mandatory boundaries and links; no procedure manual
Reusable agent methods .agents/skills/*/SKILL.md Task triggers and methods under project constraints; link to domain rules and delivery rather than repeat them
Branches, review, validation, PRs, releases and cleanup CONTRIBUTING.md Executable workflow
Module boundaries, interface discipline and ablation Engineering Module, contract, lifecycle and source navigation; shared coding rules
Names, terminology and voice Naming and copy Product/tool names, role labels and Chinese/English writing conventions
Translation contributions Translation guide and its Chinese counterpart Catalog editing, new-language registration and translation review
Illustration, palette, motion and accessible layout Visual language Shared Browser/App design grammar
Status projection Media status Which facts each display surface may express
Release identity and compatibility Versioning Version roles, protected interfaces and public-readiness boundary
Current product behavior Rooms, routing, media, lifecycle One owner per domain; promises, boundaries and non-obvious invariants
Architecture decisions docs/adr/ Decision status, rationale and consequences; explicitly supersede changed clauses
Measurements and external evidence docs/research/ Date, sources, observations, inference, limits and license scope
Deployment and configuration docs/deployment.md, docs/operations/, docs/standards/configuration.md Runnable operator reference; no per-release diary
Compact product map docs/project-memory.md Stable summaries and domain navigation, not implementation inventories
Current execution/deployment index docs/status.md Current boundaries and pointers; exact artifact identity stays in release metadata
Remaining work and decisions docs/todo.md One task ledger, with executable work separated from parked ideas
Evidence boundaries docs/verification-status.md Compact limits that affect product claims; no duplicate retest ledger
Completed history Git commits and PRs Changes and outcomes; do not reproduce them in memory or TODO

Source schemas and existing conformance fixtures own exact interface fields; package comments own local lock/resource invariants. The engineering reference links to them instead of copying every field. README and guides explain how to use the product; technical details link to the relevant owner. English/Chinese entry guides are intentional translations and must change together; technical references keep one version.

First-use guides stop at a working room. Detailed controls belong to task guides, symptom-based checks to troubleshooting, and build/release procedures to maintainer references. Remove repaired incident narratives instead of appending them to the reader's path; retain checks for current platform and network limitations.

The public documentation website renders selected repository Markdown without owning another copy. Its reader index serves usage and support; the repository map remains the developer/maintainer entry. The website runbook owns generation and publication. General symptoms and report collection belong to the troubleshooting guide; browser/network connection procedures belong to the network guide. Introductions and the general guide link to those procedures rather than duplicate them.

Updating A Rule

  1. Trace the current product contract, actual callers and relevant evidence. Search hits are leads, not proof of a defect. Separate an implementation mismatch from a historical decision or a still-unaccepted proposal.
  2. Update the existing owner first. Add a new owner only for a distinct topic with real consumers; give it an entry in the documentation map. Delete replaced normative text elsewhere and link to the owner. When an entry point moves or a cross-module responsibility changes, update the engineering index and its links to the relevant verification entry points.
  3. Keep current owners consistent. Update memory/status only when their compact snapshot materially changes; put unresolved work in TODO. Checkpoint and integration timing follows CONTRIBUTING, not an automatic extra commit for every small edit.

When semantics are disputed, record the decision needed and hold only dependent implementation. At handoff or a material phase change, persist accepted rules, remaining work and actual blockers before relying on a conversation summary. Do not store tool transcripts, raw logs, temporary paths or repeated completed checklists as product truth. After an audit, put accepted constraints in their existing owners and unresolved work in TODO, then remove the report and handoff bundle. Do not create dated audit-summary directories or replacement archives of completed work. Remove repaired, sufficiently verified work from TODO and compact snapshots. An unmatched historical report alone does not create a permanent retest task; keep its discussion in the issue and reopen work when new evidence warrants it.

Published copy describes Piik's behavior and design directly. Remove discarded design labels, private operational details and conversational comparisons to other products. Describe visual choices in Piik's own design vocabulary. Retain relevant public technical references beside the claims they support, using accurate names and direct links without implying affiliation or endorsement. Local research inventories do not belong in product copy; keep source provenance accurate rather than relabel private observations as public documentation. Credit reused code and assets through their existing license and notice owners; a reference or thank-you does not replace permission or required attribution. Preserve accepted contributors' authorship under CONTRIBUTING.

Consolidation And Ablation

Keep one owner per fact, with short summaries where navigation needs them. Consolidation is not concatenating documents into one giant manual. Remove stale procedures and duplicated prescriptions; preserve still-consumed behavior, failure boundaries, reasoning and reproducible evidence. An ADR can retain a historical decision when its superseded status is clear.

Document cost is part of engineering ablation. Do not delete a product promise solely to shrink a file. Archive completed work in Git, keep candidate ideas out of active instructions, and never promote an agent suggestion to accepted policy simply by writing it in a checklist.

The top-level context stays a map. Directory-specific instructions belong near the code only when that module exists and the rule is needed every time. The context-governance research owns the external rationale; the existing hygiene scripts own executable limits. Their gardening warnings invite review, not arbitrary compression; hard failures for broken links, required owners and instruction-loading limits remain binding.

Agent Instructions And Skills

Keep broadly applicable project constraints near the top of AGENTS.md, with explicit task triggers for required skills. Domain standards define accepted behavior; skills explain how to do a recurring kind of work. Neither research examples nor skill defaults can expand user authorization or replace a domain decision. Use repo-linked adaptations when a global skill has the same name; names alone do not establish which instructions were loaded.

Give each skill one recognizable purpose and a short description stating when it applies. Keep useful, non-obvious decisions in its body. Link to existing owners for details; add supporting files only when a real workflow needs them. Do not create nested instruction files merely to split a short document, copy the same rules into multiple tool formats, or require every installed skill on every turn. Relevant instructions remain applicable without repeated loading.

When changing instructions, check actual task behavior: would a scoped layout fix trigger unrelated network gates, a review silently authorize edits, or a simplicity rule permit incomplete UX? Check intended triggers and nearby tasks that should not trigger the workflow. Preserve necessary safety and compatibility while removing conflicting or redundant procedures. Use metadata/link checks for structure and representative work for behavior; passing a schema validator does not establish that a skill is effective. Add no permanent prompt test suite or hooks without a demonstrated recurring need.

Checks

For documentation work use the existing link, whitespace and repository-hygiene checks; do not rerun unrelated media benchmarks. The shared required-project-paths.txt lists durable owners for both hygiene entry points. No additional checker is needed for each new convention.

At a meaningful integration boundary check that current documents agree, links resolve, and memory/status/TODO still describe what remains. Expensive evidence retains its measured revision, environment and limits; rerun it when a relevant contract, dependency, platform, workload or unexplained failure changes.