Composition concepts for first-time readers¶

This page is an explanatory guide, not a second semantic authority. It is for readers who can follow a task-oriented walkthrough but want a compact mental model for repository-specific uses of words such as recipe, artifact, component, contract, material, and lock.

Canonical repository terminology remains in docs/glossary.yml. Exact Composition semantics remain in the component descriptors, recipes, schemas, and Composition model. Operational behavior remains in the Composer reference. If this page ever disagrees with those authorities, follow the authority and fix this page.

You do not need to read this page before creating a Website, Web application, or Agent Skill. The first-use walkthroughs remain the primary zero-to-one paths. For a browser-facing product, first use Choose Website or Web application to select the artifact from product identity rather than implementation technology.

Mental model¶

Composition starts from the kind of artifact you want to build and explicit consumer intent. It resolves reusable authorities, then materializes their declared files into a separate consumer repository.

what you want to build
        |
        v
      recipe  +  consumer intent
        |
        v
resolved component closure
    |          |          |          |
    v          v          v          v
artifact   foundation capability  lifecycle
component  components components  components
    |          ^          |          |
    +--requires-+---------+----------+
                         |
                         v
                      Composer
               |
               v
       consumer repository
       |- contracts/
       |- schemas/
       |- ordinary product files
       `- .template-composition/

The important distinction is between selection, semantics, and materialization:

• a recipe is the consumer-facing starting selection;
• components are the reusable source authorities selected directly or transitively;
• components may register contract documents and schemas or materialize other files;
• the Composer resolves the complete component closure and materializes it;
• the Composition lock records the exact resolved state after successful materialization.

Common words with Composition-specific usage¶

Artifact component is not Artifact contract¶

These are deliberately different concepts.

• Artifact component is a Composition authority class: it owns reusable semantics specific to the kind of artifact being produced.
• Artifact contract is a repository-wide Policy-owned classification for requirements that define what a produced artifact must contain or do.

The integrated glossary is the canonical place to disambiguate these terms. Composition must not create a second definition of the Policy-owned Artifact contract merely because the words are similar.

Example: Website and Web application share a Web foundation¶

A browser-facing product first chooses between sibling artifact identities:

• choose website when content/documents, discovery, and navigation are the primary product model;
• choose webapp when tasks, actions, application state, and state transitions are primary.

Both artifacts require foundation.web, so browser identity, generalized routes, and viewport/input semantics have one shared authority. The artifact components then add different identity-specific contracts:

foundation.web
|- browser identity
|- generalized routes
`- viewports

artifact.website-core
|- site structure
|- document metadata
`- discovery

artifact.webapp-core
|- application routes
|- surfaces
`- UI states

A minimal Website can start with no optional components:

{
  "schema_version": 1,
  "recipe": "website",
  "components": {
    "include": [],
    "exclude": []
  },
  "parameters": {}
}

Its shared and Website-specific seed contracts include browser-identity.json, routes.json, viewports.json, site-structure.json, document-metadata.json, and site-discovery.json. It does not receive Webapp-only application-routes.json, surfaces.json, or ui-states.json.

A minimal Web application uses the sibling webapp recipe:

{
  "schema_version": 1,
  "recipe": "webapp",
  "components": {
    "include": [],
    "exclude": []
  },
  "parameters": {}
}

The shared routes.json still owns product-neutral path, canonical/deep-link, and accessibility semantics. Webapp-specific surface, authentication/access-failure, history, and state behavior belongs in application-routes.json; do not put those fields back into the shared route document.

Static generation, server rendering, client rendering, CDN hosting, and the presence of an application runtime do not select between Website and Webapp. capability.pwa is likewise an artifact-neutral optional capability: either artifact can become installable and define offline/update behavior without changing artifact identity.

These contracts describe the product you are building; they are not a complete implementation. Product code, framework choice, storage, tests, and other consumer-owned files are implemented separately. If the product later needs a maintained implementation runtime, packaged CLI, MCP, service, or complete release lifecycle, include the appropriate top-level capability or lifecycle component. The Composer resolves transitive requirements rather than requiring the consumer to enumerate every prerequisite.

Example: Agent Skill¶

The skill recipe selects artifact.skill-core. Its initial material includes the Skill structure and validation needed to begin a separate consumer repository. Application capabilities and most product lifecycle machinery remain opt-in rather than being implied by the fact that the artifact is a Skill.

For example, an instruction-only or knowledge-augmented Skill does not need an application runtime merely because other Skills may expose CLI, MCP, or service behavior.

Where to go next¶

• To choose Website or Web application, use Choose Website or Web application.
• To build a Website now, use the Website product walkthrough.
• To build a Web application now, use the Webapp product walkthrough.
• To build an Agent Skill now, use the Agent Skill first-use walkthrough.
• To choose optional components, use the production catalog guide.
• For strict semantics and ownership rules, use the Composition model.
• For exact commands and diagnostics, use the Composer reference.
• For canonical repository terminology and cross-authority disambiguation, use the integrated glossary generated from provider-owned docs/glossary.yml sources.

Component roles: a practical mental model¶

A recipe is the consumer-facing starting point. It chooses an artifact component—the answer to “what am I building?”—and exposes only optional components that a consumer may deliberately select. A component is the reusable authority that contributes one coherent set of semantics and materials to that resolved product.

Read component roles as four questions, in this order:

1. Foundation — What shared base is required? A foundation is automatically introduced through an artifact dependency. It is mandatory when the artifact needs it, but it is not a product capability to select directly.
2. Artifact — What am I building? An artifact defines the product identity and its identity-specific contracts.
3. Capability — What else can it do? A capability adds an externally observable behavior, such as PWA support, a runtime, a CLI, or an MCP interface.
4. Lifecycle — How is it managed over time? A lifecycle component supplies reusable machinery for validation, evolution, evidence, checkpoints, or release.

The current Website/Webapp split demonstrates the boundary directly. artifact.website-core and artifact.webapp-core are sibling product identities that both require foundation.web; a consumer selects one artifact recipe and may then choose optional PWA or runtime capabilities. The foundation is resolved automatically and is never an include target. The descriptor represents these responsibilities with component_role (foundation, artifact, capability, or lifecycle), while canonical definitions remain in the provider glossary.