Repository structure and rules

Technology-neutral ownership, dependency, production, testing, Git, and scaffold rules for projects bootstrapped with woostack.

Woostack defines engineering outcomes for new projects created through woostack-bootstrap, not a built-in technology stack. Bootstrap researches current named options, requires explicit approval, and records the selected technologies and live-resolved versions. Existing repository conventions and history remain authoritative for brownfield work, which routes to Build, Fix, or Change.

Repository-owned structure

Follow the approved stack's native structure in a new repository and the established structure in an existing one.
Keep product code in the deployable application or unit that owns it.
Keep business logic, data access, authentication, observability, UI, utilities, and vendor integrations with that owner.
Extract only the smallest coherent implementation or contract genuinely shared by multiple applications, place and name it according to repository conventions, and remove local duplicates.
Create only directories and modules required by the approved product.
Do not create placeholder packages, speculative abstractions, pass-through wrappers, duplicate tooling, or a second convention beside the repository's own.

Application internals

Group code according to the selected technology and repository conventions. An application may need boundary adapters, contracts, services, UI, layouts, or validation, but those role names do not mandate a directory tree.

Boundary adapters map wire or vendor representations to domain models and isolate transport errors; see Application-boundary adapters.

APIs and application boundaries

API compatibility

Within the repository's supported compatibility window:

Existing route or operation identifiers remain stable.
Inputs may gain optional fields; do not remove or rename existing fields.
Outputs may gain fields; do not remove existing fields or change their meaning or type.
Existing error codes retain their meaning; add distinct codes for new conditions.
An approved breaking change uses the repository's documented versioning mechanism.

Application-boundary adapters

When data crosses application boundaries (HTTP/RPC server-client, service-to-service, webhooks, queues/events, or third-party APIs in either direction):

Keep transport, client, and vendor formats out of domain and business logic through boundary adapters.
Adapters own input validation/narrowing, wire/domain bidirectional mapping, and transport error translation.
Place adapters in the owning application; extract them only when multiple applications share the exact contract or implementation.
Functions or modules satisfy the pattern; classes are not required.
Do not add identity-only or no-op wrappers when a deliberately shared contract is already the domain model shape.
Apply the rule to new and materially touched boundary flows; untouched legacy flows remain unchanged.
Review blocks concrete changed-code transport leaks or missing boundary validation/error translation, but does not police naming, implementation style, or justified identity mapping omissions.

See patterns.md §3 for the canonical pattern.

Technology selection and dependencies

Gather relevant product, scale, traffic, hosting, data, identity, compliance, integration, budget, and team constraints before selecting technologies.
Validate a user-specified stack with current sources. Compare cohesive alternatives when material technology tradeoffs remain unresolved.
Obtain explicit approval of the complete stack and architecture before scaffolding. Do not infer a default for an undecided category.
Record the exact selected technologies, material choices, and live-resolved versions in the root README.
Resolve every dependency version live from its authoritative registry; never use model memory.
Use stable releases unless the approved design explicitly requires a prerelease.
Each application declares the dependencies required by its runtime in its own manifest.
Shared code declares its own dependency categories when the selected ecosystem supports them.
Keep only genuine repository-wide tooling at the root.
Enable lifecycle scripts only for dependencies whose required installation behavior has been verified.
Resolve peer or compatibility warnings in each consumer, verify local shared-code resolution, and check dependency support for the target runtime.
Preserve the approved package manager's lockfile and integrity metadata.

Type safety

Use the approved stack's strongest practical static and runtime type-safety mechanisms.
Validate or narrow untrusted values at trust boundaries before application code consumes them.
Derive related contract types from one source of truth when the selected technology supports it.
Do not bypass type checks without a narrow, documented reason.
Keep type and contract helpers application-local; extract only definitions shared by multiple applications.

Data, identity, and observability

Data and migrations

Keep every schema mutation discrete, ordered, version-controlled, and reproducible with the approved data tooling.
Do not run production migrations directly from a developer machine; use controlled deployment automation with observable failure and recovery behavior.
Configure connection limits, pooling, retries, backups, restoration, and destructive-change safeguards to match the selected database and runtime.
Add a project-owned interface around a vendor client only when it provides real portability, testability, isolation, or reuse; do not add a pass-through abstraction.
Centralize client or connection instantiation when shared lifecycle, pooling, or rate-limit control requires it.

Authentication

Wrap a third-party identity client only when a project-owned interface provides real portability, testability, isolation, or reuse.
Verify tokens and sessions only in trusted server-side contexts and keep authorization decisions explicit at protected boundaries.

Observability

Emit structured, queryable events with consistent time, severity, message, service, and environment fields.
Capture unhandled failures through the approved monitoring path.
Redact credentials, authorization material, personal data, and other secrets before transmitting telemetry.

Environment and secrets

Use the approved production secret store or managed runtime configuration as the production source of truth.
Keep local development secrets out of source control and provide a non-secret inventory of required configuration names.
Ensure ignore rules cover local secret files used by the selected stack.
Validate required configuration at startup and fail with descriptive, non-secret errors.

CI/CD and deployment

Use the repository's approved automation and commands.
Run every applicable formatting, static-analysis, type/compile, build, and test check defined by the scaffold on pull requests.
Match deployment architecture to runtime duration, scaling, latency, state, networking, and regional requirements.
Automate preview/staging and production deployments, migrations, rollback, and release credential handling according to the approved delivery model.
Never report a nonexistent or unobserved command as passing.

Testing

Follow Red → Green → Refactor and write the failing test first for new implementation.
Use the repository's approved test runner, file layout, and naming conventions.
Cover observable behavior, boundaries, invariants, transitions, precedence, and real failure paths.
A change is incomplete until its required verification passes.

Least code, still safe

Before adding code, stop at the first rung that works:

Confirm the code is needed.
Reuse an in-tree helper or pattern.
Use standard facilities.
Use a native platform feature.
Use an already-installed dependency.
Use a direct one-line implementation.
Add the minimum new implementation.

Additional rules:

Trace the affected flow before choosing the smallest solution.
When approaches are equally small, choose the edge-case-correct one.
Prefer deletion over addition and boring code over clever code.
Never remove validation, error handling, security, accessibility, or data-loss protection to make code smaller.
Preserve deliberate defense in depth; it is not ordinary DRY duplication.
Keep a regression test for a behavior-changing simplification.
Give a deliberate known limitation a why comment that names its ceiling and upgrade path.
Document user-facing components and procedures with the repository's native convention.
Comments explain non-obvious reasons, constraints, workarounds, or invariants—not what the code already states.
Replace unexplained repeated or policy-bearing literals with descriptively named constants using the repository's naming convention.

See Least code, still safe for the rationale and review behavior.

Greenfield admission and scaffolding

Before creating a repository:

Preflight the target read-only before committing to a design.
Complete the live research and explicit technology-approval gate above before writes.
Refresh the collision check immediately before scaffolding.
Proceed only when the path is absent or an empty non-Git directory.
Reject symlinks, populated directories, existing repositories or worktrees, unreadable paths, ambiguous results, and paths owned by another run.
Never reset, clean, delete, overwrite, or scaffold around an existing target.

For every approved surface:

Resolve exact dependency versions live.
Use the smallest supported scaffold for the selected stack.
Remove demo and example code outside the approved product.
Establish each application's native structure and only the shared code the approved surfaces need.
Implement only the minimum vertical slice needed to prove the architecture.
Configure environment validation without including secret values.
Add required security, error, accessibility, data-loss, migration, and observability protections.
Keep generated output and runtime evidence out of source control.

Git and workspace initialization

Initialize Git only after creating the approved scaffold in the verified target.
Configure the canonical remote without embedding credentials.
Configure the intended integration branch.
Initialize .woostack/ through woostack-init.
Do not create .woostack/specs/, .woostack/plans/, .woostack/fixes/, or a shadow development ledger.
The initial greenfield scaffold is the only primary-worktree exception.
Use isolated worktrees and Graphite for every later feature or fix.
Do not commit or push until generated files, environment files, lockfiles, ignore rules, and code ownership have been classified.

Branching

main represents production.
Each repository configures its integration branch; staging is only an example.
A feature/<name> branch represents one change and one PR.
Cut feature branches from the resolved integration branch, not automatically from main.
Target feature PRs at the integration branch.
Promote the integration branch to main after integration testing and according to the release cadence.
Do not open a PR directly against main except for an emergency hotfix.
Cherry-pick an emergency hotfix back into the integration branch immediately.
Never force-push to main or the integration branch.
Use Graphite to manage branch stacks.
Merge authority remains human-only.

Required README

Write the root README after the scaffold works. Include:

product purpose and approved deployable surfaces;
architecture and application-local/shared-code placement decisions;
exact selected technologies and live-resolved versions;
setup prerequisites and non-secret configuration names;
development, build, test, analysis, format, migration, and boot commands that actually exist;
deployment and observability assumptions;
rationale for material choices; and
an artifact link only when persistence was explicitly selected and verified.

Do not copy Woostack's complete internal workflow or artifact protocol into the application README.

Required verification

A bootstrap is incomplete until it runs every applicable command defined by the approved scaffold:

dependency installation and lockfile generation, format/check mode, static analysis, type checking or compilation, tests, production build, boot/smoke verification of every deployable surface, and at least one vertical path through each surface.

The final tree inspection rejects committed secrets, local secret files, generated build output, leftover examples, premature or duplicated shared code, unexpected files, missing lockfiles, or dirty formatter output. A nonexistent command cannot be reported as passing.

Existing repositories

Woostack does not impose greenfield architecture on an existing repository. Existing conventions and history own brownfield work:

bugs, regressions, and root-cause work route to Fix;
bounded one-PR enhancements and refactors route to Change; and
larger initiatives route to Build.

Canonical sources

This page summarizes the project contract. The executable skill and references remain authoritative:

Repository structure and rules

On this page