Develop a Cross-Platform CLI in a Shared Worktree Without Touching Others' Work

## Search and Edit Only Inside the Current Worktree When development uses worktrees, the current working directory is the complete repository for the active branch. Search, read, build, test, and edit only within that root. - Use relative paths or resolved paths beneath the current root. - Do not assume a parent directory is the repository. - Do not search sibling worktrees for implementations or configuration. - Reject hardcoded developer-home paths. - Resolve fixture and source paths from the active root. Escaping the worktree can mix stale code from another branch into analysis and changes. ## Never Reset or Delete Changes from Other Sessions Assume unfamiliar files and edits may belong to another active session. Never delete, reset, discard, or overwrite work merely because it is outside the current task. - Preserve files you did not create. - Ask before removing untracked files. - Do not run reset, checkout-discard, clean, or stash-deletion operations without explicit approval. - If hooks fail because of untouched files, report the conflict instead of modifying them. - Keep changes limited to the requested scope and inspect the final diff. Treat shared worktree state as user data whose ownership must be resolved before destructive action. ## Add Commands Through a Registry Instead of Scattered Conditionals Use a registry to make commands, providers, and integrations extensible. A new implementation should satisfy a stable interface and register through one canonical path rather than add conditionals across the application. - Define interfaces for major behavior. - Inject dependencies through constructors or fields. - Generate mocks through the repository's supported generator. - Use functional options for extensible configuration with defaults. - Keep one command implementation per focused file. - Add purpose-built packages instead of expanding a generic utility package. Search existing command, execution, and package layers before introducing parallel logic. ## Use Context Only for Cancellation and Deadlines, and Route Flags Through One Parser Use request context only for cancellation, deadlines, and sparse request-scoped values. Pass it first when accepted. Do not use context to hide configuration, dependencies, or ordinary parameters. Model configuration as a deterministic pipeline: 1. load configuration sources; 2. process imports and inheritance; 3. apply precedence from command flags through environment and files to defaults; 4. render supported templates; 5. generate the effective configuration. Route flags and environment binding through the unified parser. Update every owning schema when adding an option, and never bypass the central binding layer. ## Send Pipeable Data and Human Messages to Separate Streams Write pipeable results only to the data stream. Write prompts, progress, warnings, and formatted human messages to the interface stream. Reserve structured logging for system events rather than user-facing output. - Use shared I/O abstractions instead of direct printing. - Let the UI layer own color, icons, Markdown, terminal width, and capability detection. - Degrade automatically when the terminal lacks styling or when execution occurs in continuous integration. - Keep structured data valid when human formatting is disabled. - Apply secret masking consistently and do not capture user data in telemetry. Testing or recording flags may force terminal characteristics, but production defaults should remain environment-aware. ## Keep Functions Small and Wrap Errors with Stable Categories Keep files and functions focused. Extract named steps from high-complexity orchestration so the top-level function reads as a flat pipeline. - Use repository-standard formatting, import grouping, aliases, and comment punctuation. - Preserve helpful comments and update them when behavior changes. - Apply standard performance tracking to meaningful public operations. - Exempt trivial accessors, constructors, pure lookups, and simple delegations when policy allows. - Wrap errors with stable categories and preserve causes. - Combine independent failures without losing either chain. - Check wrapped errors through semantic matching rather than string comparison. Use rich error builders when users need hints, context, or exit semantics. ## Test Behavior with Mocks and Tests That Can Actually Fail Prefer fast unit tests with generated mocks for isolated behavior, then add integration or acceptance coverage where public command behavior crosses real boundaries. - Use table-driven cases for input and error coverage. - Test behavior rather than internal implementation. - Remove stubs, tautological tests, and permanently skipped tests. - For merged collections, mutate both result and source in separate checks to prove two-way isolation. - For slice results, assert representative contents as well as length. - Add negative tests proving recovery does not trigger when its condition is absent. - Use semantic error matching against wrapped failures. Coverage is evidence only when assertions can fail for the behavior being protected. ## Write Tests That Run on Every OS and Fail Clearly When Setup Is Missing Tests must run on supported desktop and server platforms without assuming a shell, path separator, or platform-specific utility. - Build paths from separate components with the standard path library. - Normalize separators only for portable suffix or display comparisons. - Use the test executable or an injected runner instead of platform-specific commands. - Merge subprocess gates into an existing test entry point rather than defining a duplicate. - Resolve fixture roots to absolute paths before walking or counting. - Make prerequisite and fixture-count guards fail loudly when setup is missing. - Add compile-time sentinels for schema fields whose rename must break the test. Verify implicit environment propagation in an explicit prerequisite subtest before testing dependent subprocess behavior. ## Regenerate Snapshots with the Test Tooling Instead of Editing Them by Hand Golden snapshots include invisible formatting, terminal width, styling, and environment-sensitive output. Never edit them manually. - Regenerate snapshots through the supported test flag or generator. - Review the resulting diff before accepting it. - Do not pipe snapshot or terminal tests because redirection can change capability detection. - Regenerate related recordings together when command help or output changes. - Validate recordings for command failure, missing references, and leaked machine-specific paths. - Do not change protected fixtures or test data without explicit scope. Generated output must be changed through its owning source and canonical workflow. ## Document Every New Command and Track Deferred Work as Issues Every new command, flag, parameter, or configuration surface needs user documentation with the repository's required metadata, usage, examples, arguments, flags, and visual evidence. - Verify the declared page identifier instead of guessing a URL from the filename. - Build the documentation site after changes and check links, images, and components. - Regenerate visual captures when command behavior, help, or output changes, not for prose-only edits. - Place requirement documents in their designated location and naming convention. - When work is deferred, create a tracked issue and link its identifier before merge. - Keep release notes, roadmap data, and labels aligned with the change class. Documentation is incomplete when it promises an untracked follow-up. ## Update Reviews Without Bypassing Hooks or Running Destructive Git Commands Use the repository's review workflow and keep recurring maintenance automation session-scoped unless a durable service is explicitly authorized. - Rebase or update only through the approved branch process. - Check continuous integration and address unresolved review threads. - Reply within the original review thread and verify linkage. - Run patch-scoped lint and test coverage before updating the review. - Do not bypass hooks or use no-verification flags. - Do not commit scratch notes, research, or unresolved placeholders. Never run destructive Git commands or remove another session's work without explicit confirmation of what will be lost. ## Reproduce Bugs with a Test First and Fix Failed Checks at the Cause For a bug, first write a reproducing test, observe the failure, implement the smallest fix, and check for regressions. Before completion, confirm: - the project compiles with the pinned toolchain; - changed files pass the canonical formatter and linter; - short tests pass, and full or acceptance tests run when the affected path requires them; - coverage meets the enforced threshold without theatrical assertions; - generated mocks, schemas, snapshots, docs, and visual captures are current; - complexity and file-size limits remain satisfied; - cross-platform paths and subprocess tests are portable; - no secret, user data, or unrelated work entered the diff. Fix the cause of every failed gate instead of weakening the gate.