Hierarchy of Product Creation

Product work must follow a fixed sequence. Each stage defines the contract for the stages that follow it. A later stage must not begin until the preceding stage is complete and internally consistent.

If an earlier stage changes, every affected downstream stage must be reviewed and updated before the product can be considered complete.

Mandatory order

1. README
2. Release and versioning
3. Onboarding
4. Core functionalities
5. Integrations with other tools
6. Examples
7. Tests

1. README

The README is the first product artifact and the source of truth for the product's intent.

It must establish:

• the problem the product solves;
• the intended users;
• the primary value proposition;
• the product's scope and explicit non-goals;
• the main user workflows;
• the expected installation and usage model;
• the vocabulary used throughout the product.

The README must describe the product clearly enough that implementation decisions can be evaluated against it. Development must not proceed while the product's purpose or boundaries remain ambiguous.

2. Release and versioning

The release model must be defined before user-facing workflows or functionality are built. Users and operators need to know what version they are running, how it was produced, and how it can be upgraded or rolled back.

This stage must define:

• the versioning scheme;
• the canonical source of the version number;
• the release artifact format;
• the release publication process;
• release notes or changelog expectations;
• compatibility and upgrade guarantees;
• rollback and recovery rules;
• the policy for immutable versus moving release references.

Every shipped artifact must be attributable to an exact source revision and an exact product version.

3. Onboarding

Onboarding must be designed before core functionality. A product is not usable if a new user cannot reach the first successful outcome without hidden knowledge.

Onboarding must explain:

• prerequisites;
• installation;
• the minimum required configuration;
• credentials and permissions, when applicable;
• the first command or action;
• the first expected successful result;
• how to diagnose and recover from common setup failures;
• where to find more detailed help;
• dynamic progression from live product, identity, permission, and entitlement state;
• the versioned multi-screen journey graph and automatic routing rules;
• focused user questions, declared intent, and permitted interest or engagement signals;
• distinct product-activation, paywall, checkout, entitlement, first-success, and retained-use funnel stages;
• the paywall and the free-to-paid capability boundary;
• the A/B testing contract, including control, variants, assignment, exposure, outcomes, guardrails, and stopping rules;

The zero-state experience must be intentional. Starting the product without prior configuration should provide safe, actionable guidance rather than an unexplained error. Human onboarding must use an automated, multi-screen journey that adapts to declared intent and live state, measures screen-level engagement and distinct conversion stages, presents a truthful commercial boundary, and produces attributable experiment evidence without weakening safety, accessibility, privacy, or entitlement enforcement.

4. Core functionalities

Core functionality may be implemented only after the product contract, release model, and onboarding path are defined.

Core work must prioritize complete user outcomes rather than isolated features. Each primary workflow must work end to end, including state transitions, failure handling, recovery, and observable results.

Core functionality must remain focused on the product promise established in the README. Features that do not directly support that promise belong outside the core.

5. Integrations with other tools

Integrations come after the core product is stable. An integration must extend an existing product capability rather than define the product's fundamental behavior.

Each integration must:

• depend on a stable core interface;
• remain optional unless explicitly part of the product promise;
• preserve provider-neutral or tool-neutral core behavior;
• fail without corrupting core state;
• document required credentials, permissions, and external dependencies;
• define compatibility and version constraints;
• expose clear diagnostics when the external tool is unavailable.

Integration-specific behavior must not leak into unrelated core workflows.

6. Examples

Examples are created after core functionality and integrations have defined the complete supported product surface. They turn every distinct supported application outcome into a safe, complete, executable user task.

The example catalog must:

• live in one canonical top-level examples/ directory;
• map every README use case, public interface, integration, lifecycle, operational, recovery, and meaningful failure outcome;
• use real public boundaries and copy-paste runnable commands or code;
• declare preconditions, risks, side effects, verification, failure behavior, cleanup, and the next adjacent task;
• demonstrate secure credential handling and safe defaults;
• distinguish executed evidence from drafts or controlled provider/device work.

Examples do not replace tests. They prove that the documented user path is understandable and executable; tests provide repeatable regression evidence.

7. Tests

Tests are created after the preceding product layers, including the canonical examples, and their contracts are defined. They formalize the completed behavior rather than inventing product behavior indirectly.

The test suite must cover:

• the README's promised user outcomes;
• release and version reporting;
• first-run onboarding from a clean environment;
• core workflows and their failure paths;
• integration boundaries and unavailable dependencies;
• compatibility, upgrade, rollback, and recovery contracts;
• canonical examples and their documented success and failure paths;
• security and data-integrity invariants.

Tests must exercise observable behavior. They must not rely on source-text assertions, implementation trivia, or mocks that bypass the real product boundary being tested.

Completion rule

A product is not complete because its core code exists. It is complete only when all seven stages agree with one another:

• the README states the promise;
• release and versioning make the product identifiable and recoverable;
• onboarding leads a new user to a successful result;
• core functionality fulfills the promise;
• integrations extend the stable core safely;
• examples illustrate every distinct supported application outcome;
• tests defend the resulting contracts and executable user paths.