Keep One Code Repository in Order for a Product With an App and a Command Line
Use when an AI works in the code repository of a product used through an app and a command line. It follows the rule files in order, keeps each area's code in place, adds every new feature to both, checks changes with the lightest test that works, and checks each version before release.
To use this AI rule
## Follow the Main Rule File First, Then Each Folder's Own Rules
Treat the root guidance file as the repository-wide source of truth for cross-cutting boundaries, workflow, and commands.
Keep it concise enough to orient a new contributor without duplicating module details.
- Publish a short index to product, architecture, contribution, review, and current-plan documents.
- Mark archived specifications explicitly and never treat dated decisions as current behavior.
- Point each major directory to its own guidance file for local ownership and constraints.
- Before working inside a governed directory, read its local guidance in addition to the root rules.
- When two documents disagree, follow the named source of truth and report the conflict instead of blending them.
Do not copy module-level rules back into the root document.
Update a rule at the narrowest level that fully owns it, and link to that rule from broader documents when discovery requires it.
## Decide Where New Code and Tests Go Before Making Changes
Maintain a repository map that explains what each top-level area owns and which dependencies may cross its boundary.
Use the map to decide where new code, tests, templates, documentation, and runtime data belong.
- Separate user applications, shared contracts, platform primitives, orchestration tools, end-to-end tests, and content extensions.
- Keep application business logic unaware of process-control and packaging internals.
- Prevent one application from importing another application's private source or tests.
- Promote cross-runtime DTOs, events, errors, and task shapes into a pure shared contract layer.
- Keep tests in the directory owned by the layer they exercise; place cross-application consistency tests in the end-to-end layer.
- Record removed or inactive directories so contributors do not accidentally recreate obsolete architecture.
If a reusable concern does not have a clear owner, stop and obtain an ownership decision before creating another shared location.
## Decide Where App Data Is Stored in One Place and Pass It On
Resolve each runtime root, namespace, and identity once at the owning boundary, then pass the resolved value downstream.
Components must consume that value rather than reconstructing it from ports, working directories, application names, or environment fallbacks.
- Derive all runtime-owned data paths from the resolved data root or constants derived from it.
- Treat narrow overrides and migration sources as explicit exceptions, not alternate roots.
- Keep transient transport details separate from persistent runtime identity.
- Namespace packaged and development state before starting child processes.
- Pass resolved state to child processes; do not let children guess their own storage locations.
- Document known legacy escape paths as removal candidates and never use them as examples.
When an obvious fix exists, route the path through the canonical root or an explicit argument.
When the correct ownership is uncertain, request a maintainer decision instead of inventing a new convention.
## Add Each New Feature to Both the App and the Command Line
Design user-facing capabilities around one service contract and expose them through every supported interaction surface.
Interface parity is part of feature completeness, not a later enhancement.
For each new capability:
1. Define or update the shared request, response, error, and event contracts.
2. Implement the service endpoint as the single behavior source.
3. Add the graphical interface that calls that endpoint.
4. Add the command-line interface that calls the same endpoint.
5. Provide machine-readable command output and file-based input for long prompts when applicable.
6. Update the change checklist to identify every affected surface.
Do not implement divergent behavior in different clients.
If one surface is genuinely inapplicable, explain the reason in the change record instead of silently omitting it.
## Build Screen Parts That Can Be Reused and Are Easy for Everyone to Use
Assign visual ownership to the smallest stable component while preserving deliberate global contracts.
Reuse shared primitives before creating new local variants.
- Keep the global stylesheet as an intentional import and token boundary.
- Put component-owned styles next to the component, using scoped modules by default.
- Reserve global selectors for resets, tokens, application shells, shared content contracts, and third-party integration points.
- Preserve cascade order during stylesheet splits and verify that specificity does not change accidentally.
- Use semantic controls and shared accessible primitives for buttons, hidden labels, and common form behavior.
- Add a shared primitive only when the need is genuinely reusable; keep product-specific layout in the product layer.
- Keep conditional elements mounted when exit animation matters, and toggle state through classes.
- Prefer quick ease-out motion, shorter exits than entrances, and nonzero starting scale.
When a nearby global style can be migrated safely in a small, testable change, move it with the component.
Do not combine a broad mechanical migration with unrelated behavior changes.
## Check Changes With the Lightest Test That Can Catch the Problem
Choose the lightest validation layer that can observe the requirement, then add broader checks only when the risk crosses boundaries.
Verification must match the ownership and user impact of the change.
- For defects, begin with a falsifiable regression test and confirm it fails before the fix.
- Keep the test scoped to the reported behavior; record adjacent defects as separate follow-up work.
- Run repository guards and static checks, plus focused tests or builds for the changed packages.
- Replay recorded sessions for parser or agent-stream changes before spending live provider calls.
- Use browser-level checks for visible interaction, animation, or race behavior that unit tests cannot prove.
- For workspace or dependency changes, refresh generated links and packaging hashes required by the repository.
- Compare with the baseline when neighboring suites have known failures.
Let the implementation express a durable invariant rather than a historical exception.
Do not claim readiness from green automated checks alone when the acceptance criterion requires a human-visible comparison.
## Keep Test and Stable Versions Apart and Check Each Release Before Shipping
Make release identity, packaging behavior, and review evidence explicit for every delivery channel.
Do not allow convenient shortcuts to erase channel separation or bypass trusted validation.
- Give development, internal-validation, preview, and stable channels distinct purposes and public identities.
- Define promotion dependencies explicitly; do not make a stable channel depend on an unrelated preview lane.
- Keep packaged runtime paths namespace-scoped and independent of temporary ports.
- Route orchestration through owned package primitives instead of rebuilding process arguments or scan rules in callers.
- Require change descriptions to state the motivating use case, user-visible effect, affected surfaces, and validation evidence.
- Attach entry-point screenshots for visible interface changes, not only isolated component images.
- Link bug fixes to their regression tests and issue records.
- Keep unrelated findings out of the current change unless they block correctness, security, data integrity, or contract compatibility.
Before release, verify the artifact through the same path users will execute.
Do not approve changes that violate repository boundaries, omit required validation, expose secrets, or risk corrupting persistent data.