Core Functionality Guidelines

Core functionality implements the product promise established by the README and the first successful journey established by onboarding. It comes after the release and onboarding contracts so implementation has a stable product boundary.

Core is not the collection of everything maintained by the team. It is the smallest coherent system that delivers the product's defining outcomes.

Required outcome

Core functionality must allow intended users to complete the primary README use cases end to end with:

• explicit inputs and outputs;
• durable and understandable state transitions;
• safe defaults;
• predictable failure behavior;
• recovery or retry semantics;
• appropriate authorization;
• sufficient observability;
• no mandatory dependency on optional integrations.

Derive core from user outcomes

Every core capability must trace to a documented product use case. For each capability, identify:

• the user or system actor;
• the initial state;
• the requested outcome;
• inputs and constraints;
• authoritative state;
• successful result;
• failure result;
• recovery path;
• cost, security, and data-integrity boundaries.

If a capability cannot be connected to the product promise, it is not core.

Build vertical workflows

Implement complete vertical workflows before broad collections of partial components. A vertical workflow includes the user interface, validation, domain behavior, persistence, execution, result delivery, errors, and recovery required for one outcome.

Avoid declaring a workflow complete when only a schema, handler, adapter, or happy-path function exists.

Public contracts

Define public contracts before internal abstractions. Contracts include:

• commands and flags;
• API requests and responses;
• configuration fields;
• state models;
• status and error semantics;
• artifact formats;
• identity and authorization requirements;
• idempotency and concurrency behavior.

Public contracts must use stable product terminology from the README. Internal implementation details must not leak into them without a user-visible reason.

State and ownership

For every mutable resource, define:

• the source of truth;
• the owner allowed to mutate it;
• valid states and transitions;
• concurrency control;
• idempotency rules;
• retention and deletion policy;
• recovery after partial failure;
• audit or provenance requirements.

Do not maintain competing sources of truth. Cached or replicated state must identify its authority, freshness, and reconciliation behavior.

Failure semantics

Failure behavior is part of the core contract. Distinguish:

• invalid user input;
• authentication or authorization failure;
• unavailable dependency;
• capacity or quota exhaustion;
• conflict or stale state;
• retryable transient failure;
• permanent execution failure;
• partial completion;
• cancellation and timeout.

Errors must be actionable and stable enough for the intended interface. Retrying must not duplicate irreversible work.

Safety and security

Core functionality must enforce safety at the mutation boundary, not only in the UI.

Define:

• least-privilege identity;
• ownership checks;
• secret handling;
• destructive-operation confirmation;
• cost and resource limits;
• input and path validation;
• isolation between users, jobs, tenants, or environments;
• audit evidence;
• emergency stop or recovery controls where applicable.

Secrets must be referenced and resolved at the trusted execution boundary. They must not be serialized into durable job, event, or log records.

Provider-neutral core

When the product supports multiple providers or tools, core models must express product intent rather than one provider's API. Provider-specific behavior belongs behind an adapter boundary.

The core must define:

• shared capabilities;
• optional capabilities;
• capability discovery;
• unsupported-operation behavior;
• normalized errors;
• provider-specific escape hatches, if any.

Do not reduce the core contract to the accidental intersection of all providers, and do not make every core path depend on the most complex provider.

Configuration

Core configuration must:

• have safe, documented defaults;
• validate before mutation;
• reject unknown or contradictory values;
• distinguish startup configuration from per-request input;
• identify restart requirements;
• avoid silent fallback across security or provider boundaries;
• support an explicit resolved-config view without exposing secrets.

Observability

Every primary workflow must expose enough evidence to answer:

• what was requested;
• who or what requested it;
• what state it is in;
• what decision was made and why;
• what resources were used;
• what result was produced;
• what failed;
• whether retry or operator action is required.

Prefer structured, bounded, low-cardinality signals. Logs must not be the only source of durable business state.

Performance and resource behavior

Define performance only in terms relevant to the product outcome. Document:

• expected workload scale;
• concurrency limits;
• latency-sensitive paths;
• memory, storage, and network bounds;
• backpressure behavior;
• overload and admission policy;
• cleanup and retention behavior.

Avoid speculative optimization. Correctness, bounded resource use, and recoverability come first.

Evolution

Core contracts must have an explicit evolution strategy. Incompatible changes follow the release and versioning policy. Stored-state changes require migration and rollback analysis.

Prefer clean migrations over permanent aliases, duplicate fields, or hidden compatibility branches. Remove obsolete paths when all callers have moved.

Prohibited patterns

Do not:

• implement features before defining the user outcome;
• treat a successful request acceptance as successful completion;
• hide partial functionality behind optimistic wording;
• add provider-specific concepts to shared models without necessity;
• use global mutable state without ownership and concurrency rules;
• swallow dependency or persistence failures;
• create silent fallback credentials, providers, or storage backends;
• serialize secrets for convenience;
• rely on manual database or storage repair as the normal recovery path;
• keep dead compatibility layers after migration.

Completion gate

The core functionality stage is complete only when:

• every README core use case has a complete product path;
• onboarding uses the real core path;
• public contracts and state transitions are explicit;
• success, failure, cancellation, retry, and recovery are defined;
• safety and authorization are enforced at mutation boundaries;
• observability proves outcomes without exposing secrets;
• core behavior works without optional integrations;
• integration adapters can depend on stable core interfaces without redefining them.