# Story: Harden developer best practices for module boundaries and god-file prevention

Backlog Item ID: DEV-BEST-PRACTICES-HARDENING

## User Story

As a technical lead, I want Open Orchestra developer guidance to enforce
pre-write god-file checks and clean module boundaries, so that new code follows
domain/model/service/adapters separation and command files stay nearly
logicless.

## Background

As the project grows, large command and service files can accumulate parsing,
business rules, storage access, formatting, and integration orchestration in the
same place. This increases regression risk and makes agent-generated changes
harder to review.

Developer standards should force agents to check file size and responsibility
before writing code. If a change would grow a god file or add business logic to
an adapter, the agent should create or reuse the correct domain/model/service
module instead.

## Acceptance Criteria

- Developer rules require a pre-write file-size and responsibility check before
  adding code to an existing file.
- Rules define god-file risk thresholds and require extraction when a change
  would materially increase a large or multi-responsibility file.
- Rules define expected boundaries:
  - `model/types`: data contracts and narrow public types;
  - `domain`: pure invariants, policy, and business decisions;
  - `service/use-case`: orchestration of workflows and dependencies;
  - `commands`: CLI adapter for parsing input, calling services, formatting
    output, and converting errors;
  - `web/api`: HTTP/UI adapter behavior;
  - `storage/repository`: persistence and file I/O.
- Command modules are documented as logicless adapters and must not contain deep
  business rules, multi-step workflow policy, direct persistence logic, or
  duplicated hardcoded collections when a domain/service source of truth exists.
- Review guidance requires reviewers to flag command/service files that are
  growing without a boundary decision.
- QA or static validation includes a lightweight check or documented checklist
  for large files, new exports, and adapter logic creep.
- Existing collection standards are referenced so repeated hardcoded values are
  extracted into typed/configurable sources of truth.

## Non-Goals

- Refactoring every existing large file in one change.
- Blocking emergency hotfixes when a follow-up debt task is explicitly created.
- Introducing a heavy architecture framework.

## Suggested Implementation

- Add or update a focused rule file for module boundaries and god-file
  prevention.
- Reference the rule from developer-facing standards and relevant skills.
- Add a checklist to code review/QA standards.
- Add a small validation command or test only if it can be low-noise and
  maintainable.

## T-Shirt Size

S

## Suggested Owners

Architect, Developer, QA.