Describe the product and the meaning of its code

A specification records what the application is meant to do and what its parts mean. It gives developers and coding agents something more explicit than a collection of implementation files.

The idea

Product specifications explain the decisions behind the work. Engineering specifications explain the business meaning of the implementation. A requirement can guide a build task; a resource specification can explain the fields and operations that labels and documentation describe.

Structured values and stable references make these connections inspectable. The application team still authors the meaning, reviews proposed changes and verifies the behavior they describe.

What you get for free

The framework supplies the family schemas, reference vocabulary, specification builders and the consumers that use them. It also supplies specifications for its own resources and components where registered.

Your application adds its business meaning. That lets development tools work from explicit declarations while your team maintains the implementation those declarations describe.

Where you plug in

Author product-family values in the application’s specifications package and expose the corresponding companion slots. For resources, pair the specification with its actual factory and schema; for interfaces, describe the registered component or view and its relevant layout.

When changing behavior, review its specification in the same change. Then check the application export, relevant validation and the consuming surface—whether a label, a documentation page or a development context response.

For engineers

How it is built

Product intent and implementation semantics

Layer	Typical content	Use
Product definition	Vision, market, requirements, roadmap, domain and build plans	Establish context and relate planned work to its purpose
Resource semantics	Purpose, fields, operations, audience and declared code symbols	Explain a business object to development and documentation tools
Interface semantics	Components, views and layout descriptions	Explain how the application presents its behavior
Application exports	References to the specification values the project supplies	Make those declarations available to the companion

Families have schemas and validators appropriate to their structure. Some checks need reference sets from other families; a local shape check cannot establish that the whole product graph is coherent.

Describe a field in its resource context

This selected field slice is from Wonder Todos’ relationship resource specification. The surrounding resourceSpecification() call supplies the resource factory, base schema, additional semantics and primary scope:

fields: {
  todoId: schemaShape.todoId.foreignKeySpec({
    meaning: 'Source todo endpoint of the relationship.',
    relationshipContext: 'References a Todo in the org.',
    importance: FieldSemanticImportance.PRIMARY,
  }),
  targetTodoId: schemaShape.targetTodoId.foreignKeySpec({
    meaning: 'Target todo endpoint of the relationship.',
    relationshipContext: 'References a different Todo; must not equal `todoId` in validated writes.',
    importance: FieldSemanticImportance.PRIMARY,
  }),
}

The schema describes the field shape. These annotations explain the role of each endpoint and its relationship context. They do not themselves implement the validated-write rule described in the text; the resource’s behavior must enforce it.

A resource specification can also describe operation purpose, outcomes and errors, communication behavior, and the public symbols behind the resource. The application registers those specifications for their consumers rather than relying on the file’s presence alone.

Export the declarations the companion should read

Wonder Todos imports SpecificationsCompanionExports from @wildo-ai/saas-specifications/companion. These selected members of its export connect product snapshots and resource specifications; other members and local imports are omitted:

{
  resourceSpecifications: {
    ...engineResourceSpecificationsByType,
    ...resourceSpecifications,
  },
  marketSpecification: applicationMarketSnapshot,
  visionSpecification: applicationVisionSnapshot,
  requirementsSpecification: applicationRequirementsSnapshot,
  roadmapSpecification: applicationRoadmapSnapshot,
  businessModelLiteSpecification: applicationBusinessModelLiteSnapshot,
}

The engine registry supplies built-in resource meanings; the application’s entries supply its own. The product-family slots expose the imported snapshots under the companion’s contract. Let the specification package compile before expecting a changed export in its served model.

Check connections at the appropriate boundary

The frontend specification builder checks documented structural slots against the merged layout’s sections, wizard steps and groups. Companion-side alignment checks compare resource specifications with the registry and its derived scope. These are specific structural checks, not a universal proof that every sentence matches behavior.

The coherence report examines relationships between product families. It distinguishes references to absent items from coverage gaps, such as a requirement with no planned delivery. Missing family context and malformed input have their own reporting implications; read the findings as well as the summary.

# With the application's companion running:
wildo context list
wildo context info resource-specifications
wildo context info specification-artifacts

# Inspect supported relationships across the product definition.
wildo context coherence

Follow the consumers

Labels use declared meaning and audience. Documentation consumers use supported field and operation descriptions. Development methods read product-family inputs, while the workbench can present the available artifacts for inspection. Each consumer uses a particular projection; none is a substitute for exercising the application itself.

Boundaries and known limits

A specification is an authored semantic layer, not a second implementation of the behavior. A registry can have a resource without authored semantics; adding prose does not create the resource. Cross-family checks need the appropriate context, and a valid declaration still needs meaningful content.

Product acceptance and runtime verification are separate. A reviewed specification records intent; a completed development operation or a committed file does not prove that every intended interaction works. Use the application’s verification evidence for that conclusion.