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

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions