ff-cli AGENTS.md

AGENTS.md — ff-cli Repository Contract

This file is the repository-level contract for humans and coding agents working in ff-cli.

It defines how work is done in this repo. Tool-specific details live in .cursor/, opencode.json, and shared review prompts.

Repository overview

• Project: ff-cli
• Purpose: a Node.js CLI for FF1 computational art workflows, DP-1 envelopes, playlist validation, playlist publishing, and FF1 device operations
• Primary runtime: Node.js + TypeScript
• Domain terms to keep consistent: FF1, DP-1 envelope, DP-1 conformance, computational art playlist, channel endorsement, FF1 device

Portable operating model

Default sequence:

spec -> design -> tasks -> tests -> implementation -> verification -> review -> merge

TDD is the default discipline for behavior changes. For small, low-risk fixes, the sequence can be compressed, but work must still remain scoped, verified, reviewed, and traceable.

Non-negotiables

• Prefer replacing or deleting flawed code paths over narrow local patches when that yields a clearer design.
• Do not preserve legacy behavior, compatibility shims, migrations, or transitional paths unless explicitly requested.
• Keep functions small, single-purpose, and testable. Break up functions that exceed roughly 30 lines, carry multiple concerns, or hide business rules in branching.
• Use TypeScript for new or updated source when practical. Legacy .js files may remain until intentionally migrated.
• Prefer comments that carry durable engineering context for future amendment by later agent sessions.
• When code is non-obvious, store design intent, trade-offs, invariants, edge cases, and coding constraints in comments near the code they govern.
• Update JSDoc whenever a function changes. New or updated functions should have complete JSDoc.

Coding style and comments

• Follow a Go-style documentation standard for comments even though the repo is TypeScript-first.
• Write comments as clear sentences. Start doc comments with the symbol name when documenting a function, type, constant, or module.
• Prefer comments that explain why, why now, why this shape, and what must not change over comments that restate syntax.
• Add comments generously when the code encodes business rules, validation invariants, protocol expectations, fallback behavior, security assumptions, or trade-offs that would be easy for a later agent to break.
• Keep short obvious code paths uncommented. Extra comments are encouraged only when they add future maintenance value.
• When a compromise is intentional, record the constraint and rejected alternative in the comment.
• When behavior depends on external systems or repo conventions, record that dependency in the comment so a later agent can amend safely.
• Preserve high-signal comments during refactors. Update them when the reasoning changes.