flywheel: Instructions file for Codex

<coding_guidelines>

Flywheel CLI - Agent Instructions

Runtime: Bun (not Node) | TUI: OpenTUI + SolidJS | Config: TOML SolidJS requires the "browser" export condition. bin/flywheel handles this via bun --conditions=browser.

This file is the complete guide for contributors. The maintainer also checks out a small private companion repository at the gitignored private/ folder of the clone. Its @private/AGENTS.maintainer.md adds the rules for the maintainer's shared working tree, publication, and release readiness. That import is optional: a contributor's checkout has no private/ folder, the import then loads nothing, and every rule a contributor needs is in this file.

1. Hard Rules

• MAXIMIZE ELEGANCE, NOT MINIMIZE CHURN! THIS IS THE MOST IMPORTANT PRINCIPLE FOR EVERY DESIGN! Always pick the design that maximizes elegance no matter how big the refactor. Better now than months down the line when there are even more dependencies in place.

• docs/elegance.md is Flywheel's canonical project-specific definition of elegance and the rubric for architecture audits. Read it in full when judging whether the project is maximally elegant. This file operationalizes much of that standard for coding agents, but not in full.

• Handle only reachable states. A state is reachable when a person or an external producer can cause it through a supported entry point: a client surface, the CLI, the published protocol as shipped clients use it, or an external boundary such as a provider stream, a subprocess, or the file system. A state that only a direct internal call or a test fixture can create is hypothetical: add no code for it, and do not treat a test that asserts it as a product requirement. Before you call a failure a regression, trace how a person reaches it. When a test fails on a state that no person can reach, rewrite the test around the reachable flow instead of changing the product.

• This repository opts into the living product-intent authority indexed by docs/product-intent/README.md. Before changing or judging user-observable Flywheel behavior, read the index and the relevant domain file. A conflict with the persisted corpus is a bug or blocker, unless the person states a different intent; then the corpus changes to match it.

• Before judging whether a subscription route follows its provider's terms, read docs/provider-terms.md. This covers the Claude engine route, the sign-in client IDs, the request headers that identify a client, and the use of several accounts of one provider. Flywheel follows precedent: a practice that widely used open-source agents ship publicly is acceptable. The page's section "How a review uses this page" lists the practices that the maintainer settled on that basis. A review or an audit never reports one of them as a finding, a blocker, or a risk, also when it finds provider terms that the page does not quote. Only the reopen events that the page names reopen a question.

• Repository code, comments, and documents name no other coding-agent harness. docs/provider-terms.md is the one place that names such projects as precedent. Credit for borrowed work goes in THIRD-PARTY-NOTICES.md and the license bundles, and a file or directory that a notice cites by path keeps its upstream references. The only other names allowed are external identifiers that Flywheel must spell exactly to interoperate, such as an environment variable, a header, or a model id, and benchmark arms that run another harness as the comparison treatment. README.md and the website home page website/src/pages/index.astro may name other harnesses, because they market Flywheel to their users.

• This repository opts into the living architecture-intent authority indexed by docs/architecture-intent/README.md. Before changing or judging Flywheel's internal organization, read the index and the relevant domain file. A conflict with the persisted corpus is a bug or blocker, unless the person states a different intent; then the corpus changes to match it. docs/terminology.md is the lexicon for Flywheel's terms.