Skip to content

docs(AGENTS.md): relabel product constraints, slim Release Flow, add Development Principles #95

Description

@EtienneLescot

Improvements to AGENTS.md from contributor feedback.

  • Relabel "README tone" -> "Product constraints." The note bundles copy (no upsell language, in README and UI) with a hard product rule (no paywalls / premium tiers). "Tone" is too narrow and reads like it's asking the model to reflect; frame it as a constraint: free forever, no paywalls/premium gating, no upsell copy.
  • Slim the "Release Flow" section. It's ~600 tokens of inline prose loaded into every agent's context. Keep the operational steps (cut RC / promote / manual fallback); move the v1.6.0 incident narrative and the release-branch-freeze contract into the already-referenced .harness/docs/git-workflow.md, leaving a one-line pointer.
  • Add a "Development Principles" section. Encode the intent as concrete rules rather than slogans: simplest readable solution, no speculative abstraction, and stay library-agnostic for now (contributors pick their own state/data lib; don't impose one across the codebase or refactor existing code onto a different one; a single choice may be enforced later). Avoid "one-liner" / minimize-line-count phrasing, which pushes models toward dense unmaintainable code.
  • Optional: make the npm pin rationale explicit in Setup commands (native Swift/C++ helpers built via electron-builder + @electron/rebuild against the npm lockfile; bun/Deno break that path).

Reference pattern: T3's AGENTS.md (Core Priorities / Maintainability sections).

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions