Imported from yumauri/fbrcm (
AGENTS.md). Install upstream withnpx skills add yumauri/fbrcm. Copyright stays with the author.
Repository conventions
Reuse and shared logic
- Before implementing parsing, filtering, sorting, terminal sizing, rendering, confirmation, or Remote Config transformations, search the repository for existing behavior and tests that already define the convention.
- Reuse existing shared and domain helpers whenever the required behavior matches. Do not create command-local copies or slightly different implementations of established behavior.
- When matching logic exists but is not accessible from the new caller, extract it to the lowest appropriate shared package and update existing callers instead of duplicating it.
- Add new local logic only when the behavior is genuinely specific to that component; keep the distinction explicit and covered by tests.
CLI tables
- Every human-readable CLI table must use the same Lip Gloss table style as the existing
get,projects list, andcache listcommands. - Use
lipgloss.NormalBorder(), a header separator, padded cells, the shared colors frominternal/terminal/styles, alternating row backgrounds, andNoColorEnabled()support. - Size every table and column to the narrowest width that fits its full content. Consult
ops/shared.TerminalWidth()only when that natural table would overflow. Choose specific flexible columns and an explicit overflow policy for each: either crop with an ellipsis or wrap into multiline cells, while leaving other columns single-line and content-width whenever possible. Do not assume wrapping is preferred; when the requested behavior is unspecified, identify the likely flexible column and ask the user whether it should wrap or use an ellipsis. Never rely on the terminal to soft-wrap a wider table, and add natural-width plus narrow-terminal regression tests for every new table. - Do not implement CLI tables with
text/tabwriter, manually padded columns, or another ad hoc renderer. - Keep machine-readable output behind the command's JSON flag and free of terminal styling.
CLI confirmations
- Every interactive CLI yes/no confirmation must use
ops/shared.NewConfirmation; do not construct prompt-kit confirmations directly. - Yes must be selected by default for every CLI confirmation. Keep that default centralized in the shared constructor.
CLI documentation
- Update
docs/CLI.mdin the same change whenever the CLI interface surface changes, including commands, subcommands, positional arguments, flags, defaults, output contracts, confirmations, or other user-visible behavior. - Keep both the command tree and the detailed command sections synchronized with the implemented Cobra command structure and its tests.
CLI machine contract
- Every new executable CLI command must follow
docs/cli-contract.md: it must participate in the global versioned--jsonenvelope for success and failure, emit typed DTOs and structured problems, remain non-interactive in JSON mode, use the documented semantic exit statuses, register every successful data DTO withops/contract(or explicitly register no successful data), and expose accurate capability metadata for arguments, flags, schemas, side effects, destructive behavior, idempotency, dry-run/draft support, stdin, and interaction requirements. - Create machine errors as typed errors at their source and classify them with
errors.As; never infer a problem code, category, retryability, or exit status from message wording. Collect non-fatal machine warnings in command context with structured details and safe remediation argv. Mutation DTOs must preserve selection breadth, matched-item count, and no-op provenance. - Keep generated input and response schemas semantic: model enums, bounds, formats, mutual exclusions, conditional requirements, concrete stdin payloads, selector/filter/expression grammars, and reusable definitions. Runtime conformance tests must validate actual success, empty/no-op, typed failure, interaction, partial-publication, warning, redaction, and boundary envelopes against the published Draft 2020-12 schemas.
- Do not add command-local JSON formats,
map[string]anymachine payloads, human tables or usage text on JSON stdout, or prompts, editors, file pickers, and browser launches in JSON mode. Raw content must use the contract artifact DTO. - For every new command or machine-contract change, update
docs/CLI.mdanddocs/cli-contract.md, rungo run ./cmd/schemagen, review the generated schemas andcli/app/testdata/contract_v1_capabilities.golden.json, and add success, failure, interaction, exit-code, and schema/golden coverage appropriate to the command.
Pre-1.0 contract evolution
- Until fbrcm version 1.0.0, breaking changes to persisted configuration and versioned machine contracts are allowed. Keep their format and contract version numbers at
1, and do not add backward-compatibility migrations solely for a pre-1.0 breaking change unless the user explicitly requests them. - Version 1.0.0 freezes those versioned contracts. Treat compatibility, migrations, and version bumps as required design concerns for changes made after that release.
User-visible wording
- Use grammatically correct singular and plural forms in all CLI, TUI, error, log, and documentation text. Never display shortcuts such as
project(s). - Use the shared
core/rc/display.FormatCounthelper for counted nouns, and ensure the surrounding verbs, pronouns, and sentence structure are also correct for both singular and plural counts. - When adding or changing counted text, search for related wording across the repository and add regression coverage for both singular and plural output where practical.
TUI mouse interactions
- Every selectable TUI item must support left-click selection. Double-clicking the same item must invoke the same action as Enter on that item.
- Every visible TUI button must support immediate left-click activation.
- Use the shared
tui/components/mouseutilbehavior for double-click detection and mouse adaptation instead of component-local timing or duplicate implementations. - Keep mouse hit regions aligned with the rendered layout, including popup positions, borders, padding, scrolling, and wrapped or filtered rows. Add regression tests for new or changed mouse interactions.
- Keep mouse reporting disabled while the Logs panel is active and no mouse-interactive popup is open, so terminal-native log text selection continues to work. A mouse-interactive popup may temporarily enable reporting and must capture its mouse events without passing them to the Logs panel.
Remote Config groups
- Preserve empty and description-only parameter groups across all parameter mutations, filtering, condition cleanup, drafts, imports, merges, and promotions.
- Removing or replacing a group must be an explicit group-level operation. In the TUI, group removal must originate from the configured delete action. It opens confirmation when no draft exists and stages immediately when a draft already exists, consistent with other TUI edits.
Validation
- After every implementation change, run the repository-wide
golangci-lint runbefore handing off the result. Do not rely on tests orgo vetalone.
