Product & application specifications

Declare the intended outcome

This illustrative complete vision uses the public specification type. It records an intended product outcome, not observed performance:

import { VisionSnapshotVersion, VisionSuccessHorizon, VisionConstraintKind, type VisionSnapshot } from '@wildo-ai/saas-specifications';

export const applicationVisionSnapshot: VisionSnapshot = {
  version: VisionSnapshotVersion.V1,
  idea: {
    oneLiner: 'Give a small team one shared view of customer follow-up.',
    description: 'A shared workspace for contacts, ownership and dated next steps.',
    notes: [],
  },
  problem: {
    statement: 'Ownership and next steps get lost between inboxes and spreadsheets.',
    affected: 'Small teams sharing customer work.',
    currentAlternatives: ['Inboxes', 'Spreadsheets'],
    consequences: ['Follow-ups are missed.'],
  },
  mission: { mission: 'Make each customer commitment clear and actionable.', principles: [] },
  successCriteria: [{
    ref: 'success-criterion-first-working-pipeline',
    statement: 'A new team reaches a working pipeline in its first day.',
    metric: 'Time from signup to a pipeline containing real contacts',
    target: 'Within one day',
    horizon: VisionSuccessHorizon.SHORT_TERM,
  }],
  constraints: [{
    ref: 'constraint-self-serve-start',
    kind: VisionConstraintKind.BUSINESS,
    statement: 'A team can start without a sales-assisted setup.',
  }],
};

The criterion’s ref remains the link target when its wording improves. Its metric and target describe what the team intends to measure; they do not install telemetry. The constraint records a decision to carry into design and implementation.

Register and inspect the brief

Export the snapshot through visionSpecification in the application’s companion exports and let the specification package compile. The creation methods that request vision context can then read it alongside other product information.

A useful brief can evolve as the team learns. Review changes to its stable criteria and constraints together with the roadmap and requirements that refer to them.

Describe a benefit in context

This illustrative benefit belongs in a surrounding market snapshot. Its profile, pain, job and feature references must identify the corresponding entries:

import { BenefitKanoCategory, BenefitRole, type FeatureBenefitConfig } from '@wildo-ai/saas-specifications';

export const followUpBenefit: FeatureBenefitConfig = {
  ref: 'benefit-clear-next-step',
  claim: 'Know who follows up next, without searching old messages.',
  role: BenefitRole.PAIN_RELIEVER,
  deliveredByFeatureRefs: ['feature-deal-owner', 'feature-dated-next-step'],
  relieves: [{ painRef: 'pain-unowned-follow-up', degree: 9 }],
  creates: [],
  advances: [{ jobRef: 'job-keep-next-step-owned', degree: 9 }],
  importanceByICP: [{
    icpRef: 'icp-small-team',
    weight: 9,
    kanoCategory: BenefitKanoCategory.THRESHOLD,
  }],
  proofRefs: [],
  addressesObjectionRefs: [],
};

The same feature can contribute to several benefits. The profile-specific weight and category record an assessment of its value to that audience. They are authored fit information, not proof of customer demand or automatic build priority.

Keep research, assessment and publication distinct

The market-analysis method admits research, evidence-adequacy and snapshot-production activities. Their eligibility determines what can run; they are not a fixed list executed merely in declaration order.

An empty proofRefs array means no structured proof records are linked. The separate evidence field can hold supporting notes, metrics or a demonstration URL. Review the basis of the claim: neither an authored note nor a linked proof establishes its truth by itself.

Make the context available

Register the snapshot through marketSpecification and compile the application’s specification package. Context consumers can project the relevant profile and feature information for their task. Family validation checks its supported internal relationships; cross-family coherence uses the additional feature and product context.

Write a usable brief

This illustrative brand declaration supplies concrete direction while leaving asset selection open:

import { BrandSnapshotVersion, BrandLogoMarkType, BrandLogoBackgroundTreatment, type BrandSnapshot } from '@wildo-ai/saas-specifications';

export const applicationBrandSnapshot: BrandSnapshot = {
  version: BrandSnapshotVersion.V1,
  name: { brandName: 'Northstar', tagline: 'Keep the next step clear.' },
  logoDirection: {
    markType: BrandLogoMarkType.ABSTRACT_MARK,
    motifs: ['a clear forward direction'],
    symbolism: ['clarity', 'shared momentum'],
    avoid: ['literal robots', 'glossy effects', 'text inside the symbol'],
    backgroundTreatment: BrandLogoBackgroundTreatment.TRANSPARENT_ISOLATED,
  },
  visualTone: {
    styleKeywords: ['calm', 'editorial', 'precise'],
    mood: 'Confident without visual noise.',
    colorIntent: 'Restrained blue with generous neutral space.',
    colorSeeds: [],
  },
  resolvedAssets: [],
};

The name and tagline identify the product. logoDirection guides the kind of mark and its visual constraints. visualTone gives a concise creative direction. resolvedAssets carries selected asset information when available.

Follow the brief to its consumer

The logo-generation service consumes the authored brand brief and can include market voice context. A generated proposal still needs review for the intended purpose and theme. Asset records distinguish details such as composition, purpose and format; keep the accepted files and their recorded roles aligned.

colorIntent is creative guidance, not a CSS theme. Register the brief through brandSpecification so the generation tools can read it.

Put accepted assets on their destinations

Generation and acceptance put the selected assets in the brand source of truth. Propagation copies them to the configured destinations and updates the runtime asset configuration. Run these commands from the application root after accepting the assets:

# Inspect the destination plan without writing files.
wildo brand propagate --dry-run

# Copy accepted assets to their configured consumers.
wildo brand propagate

Inspect the served asset URLs and the application surfaces after propagation. wildo config sync does not replace this step. See derived brand assets for how the accepted source supplies the different visual roles.

Record the product owner’s choices

This illustrative business model deliberately leaves the price unconfirmed:

import { BusinessModelLiteSnapshotVersion, PricingModelAxis, RevenueModelKind, type BusinessModelLiteSnapshot } from '@wildo-ai/saas-specifications';

export const applicationBusinessModelLiteSnapshot: BusinessModelLiteSnapshot = {
  version: BusinessModelLiteSnapshotVersion.V1,
  revenueModel: RevenueModelKind.SUBSCRIPTION,
  plans: [{
    ref: 'pricing-plan-team',
    name: 'Team',
    pricePoint: 'Price to be confirmed with the product owner',
    billingPeriod: 'monthly',
    pricingModel: PricingModelAxis.PER_SEAT,
    includes: 'Shared customer records and assigned follow-up.',
    targetSummary: 'Small teams coordinating customer work.',
    targetIcpRefs: ['icp-small-team'],
    includesRequirementRefs: ['functional-requirement-owned-follow-up'],
  }],
};

revenueModel describes the overall approach. A plan’s pricingModel describes its charging axis. pricePoint is authored product text; it is not a provider price identifier or a typed money amount.

Keep the offer connected to scope

The business-model method consumes market and requirements context. Register the result through businessModelLiteSpecification for the companion. Coherence can relate its references to the available product families.

Implement the commercial behavior separately

The application’s billing catalogue, entitlements and access policies implement the offer. Changing this snapshot does not create provider prices or enforce feature access. Review those runtime configurations alongside a changed offer and test the customer journey they produce.

Make the requirement observable

This illustrative requirement belongs in the surrounding requirements snapshot:

import type { FunctionalRequirementConfig } from '@wildo-ai/saas-specifications';

export const ownedFollowUp: FunctionalRequirementConfig = {
  ref: 'functional-requirement-owned-follow-up',
  statement: 'Every open deal can show an owner and a dated next step.',
  rationale: 'Make customer commitments visible to the whole team.',
  acceptanceCriteria: [
    'A team member can assign an owner to an open deal.',
    'The record displays the next action and its due date.',
    'The team can identify deals missing either value.',
  ],
  icpRefs: ['icp-small-team'],
  jobRefs: ['job-keep-next-step-owned'],
};

The acceptance criteria are statements to verify. They do not become executable tests simply by being declared. Customer and job references connect the behavior to its intended audience.

State the quality of the interaction too

A functional requirement says that a person can record follow-up. A quality requirement can say how easily they should be able to do it. This illustrative target belongs in the snapshot’s nonFunctional collection:

import { NonFunctionalRequirementKind, type NonFunctionalRequirementConfig } from '@wildo-ai/saas-specifications';

export const quickFollowUp: NonFunctionalRequirementConfig = {
  ref: 'nfr-quick-follow-up',
  kind: NonFunctionalRequirementKind.USABILITY,
  statement: 'A trained teammate can record a next action in under thirty seconds.',
  metric: 'Elapsed time from opening the record to saving the next action in a usability session.',
  acceptanceCriteria: ['Each participant completes the task without assistance within the target time.'],
};

The target and test procedure are product decisions, not measured results. Both functional and quality requirements can be named in a phase’s deliversRequirementRefs and checked for delivery coverage.

Put those commitments into the roadmap

import { RoadmapPhaseHorizon, RoadmapPhaseKind, type RoadmapPhaseConfig } from '@wildo-ai/saas-specifications';

export const firstRelease: RoadmapPhaseConfig = {
  ref: 'roadmap-phase-shared-follow-up',
  sequence: 10,
  title: 'A shared follow-up workspace',
  objective: 'Make customer ownership and the next dated action visible.',
  horizon: RoadmapPhaseHorizon.NOW,
  kind: RoadmapPhaseKind.MVP,
  deliversRequirementRefs: ['functional-requirement-owned-follow-up', 'nfr-quick-follow-up'],
  deliversSuccessCriterionRefs: ['success-criterion-first-working-pipeline'],
};

The phase’s sequence records relative order; its horizon and kind describe planning intent. The reference lists explain what the phase is meant to deliver. They do not report implementation progress.

Review scope and delivery separately

Export the requirement snapshot and roadmap through requirementsSpecification and roadmapSpecification. Their validators check supported structure and references; the coherence report uses family context to inspect coverage and dangling links.

When a requirement moves out of a phase, review the connected success criterion and offer as well. Keep the roadmap honest about intended scope, and use application verification to establish delivered behavior.

Write the intended behavior

This illustrative draft describes an intended feature without creating its runtime definition:

import type { FeatureSpecificationDrafts } from '@wildo-ai/saas-specifications';

export const applicationFeatureSpecificationDrafts: FeatureSpecificationDrafts = {
  schemaVersion: 1,
  drafts: [{
    featureRef: 'feature-deal-owner',
    draft: {
      purpose: 'Make responsibility for each open deal explicit.',
      businessRole: 'Supports the promise of dependable customer follow-up.',
      lifecycleRole: 'Used while the team manages active opportunities.',
      useWhen: 'A deal needs one teammate responsible for moving it forward.',
      avoidWhen: 'The problem requires complex approval chains or territory routing.',
      businessConstraints: ['The owner remains visible in the shared workspace.'],
      availabilityRole: 'Available to members managing customer work.',
    },
  }],
};

featureRef identifies the draft for references such as a benefit’s deliveredByFeatureRefs. The nested draft explains purpose, usage and constraints. Availability prose describes intent; application configuration and authorization implement access.

Validate the connected proposal

The capability-map output combines an updated market snapshot and feature drafts. Its validation considers existing feature references together with the proposed draft references, then checks each half of that output set. This lets the proposed benefit-to-feature links be checked together.

Inspect the proposed market and draft artifacts together with their validation report, so the benefit links and feature intent remain aligned.

Carry the draft into implementation

Register the drafts through featureDraftsSpecification and keep their identities aligned with the later feature definitions. Validation checks the draft’s structure and identities. Review establishes whether it expresses the intended product; implementation and verification establish whether the application delivers that value.

Separate the roles of schema, validation and projection

Families need not have identical structures or generation paths. Human-authored fact sources have different production authority from generated proposals. Typed fields can contain substantial prose; structure makes their identities and connections explicit.

See how a collection becomes inspectable

This selected domain-plan aspect is one member of the family’s aspects array. The enclosing registry declaration is omitted:

{
  key: 'domain-plan.module',
  snapshotPath: 'modules',
  kind: FamilyAspectKind.COLLECTION,
  itemSchema: ModuleBusinessSemanticsSchema,
  businessKey: 'relatedModuleId',
  headlineField: 'relatedModuleId',
  edges: [],
}

The projection knows where to read the collection, how to identify an item and which field to present as its headline. An aspect’s edge declarations describe supported references; the family validator and cross-family report perform their own checks.

Make the family available to consumers

Author or produce the value in the specifications package and connect the corresponding companion export. Known landing profiles establish the destination for generated families rather than guessing a source path.

For example, Wonder Todos exports applicationPlacementPlan from its placement-plan module. These selected lines show the import and member of specifications/src/companion-exports.ts; the existing export object, type and other members remain in place:

import { applicationPlacementPlan } from './placement-plan';

// Inside the existing specificationsCompanionExports object:
placementPlanSpecification: applicationPlacementPlan,

The value is authored in specifications/src/placement-plan/index.ts. The named companion slot makes it available to the artifact projection after compilation. This is application registration; the earlier aspect declaration belongs to the framework’s projection machinery.

After compilation, inspect the available artifact view through wildo context info specification-artifacts. Use wildo context coherence for the supported cross-family relationships. A valid local value does not, on its own, establish every external reference or prove that the described behavior is implemented.

Read a concrete module declaration

This module entry comes from Wonder CRM’s domain plan; the surrounding snapshot and other modules are omitted:

    {
      "relatedModuleId": "relationship-records",
      "purpose": "Maintain the shared contact and company records that give workspace teammates a common view of customer and prospect relationships.",
      "businessCapability": "Shared customer relationship record management",
      "businessDomain": "Customer relationship management",
      "primaryActors": [
        "Founder or sales lead",
        "Customer relationship owner"
      ],
      "mainResources": [
        "contact",
        "company"
      ],
      "supportingResources": [
        "interaction"
      ],
      "integrationSurfaces": [
        "web workspace",
        "customer record views"
      ]
    },

mainResources establishes the module’s primary records. supportingResources describes records it uses without turning every reference into another owning module. Actors and integration surfaces explain the business context for that decomposition.

Keep the plan distinct from runtime declarations

Relationship cardinality and ownership intent do not themselves configure access permissions or deletion behavior. Those belong in the application’s actual declarations and implementation.

Carry tenancy into production work

Choose the primary scope for the application’s records:

This selected member of a domain plan chooses shared workspaces:

// Import DomainPlanTenancyModel from @wildo-ai/saas-specifications.
tenancy: DomainPlanTenancyModel.ORGANIZATIONS,

The foundation uses a valid plan’s tenancy first. If it is absent, provide the explicit primary-scope answer, organizations or users; neither source means the foundation refuses to guess. Scope selection guides composition. Resource access rules still need their own declarations and verification.

Register the plan through the application’s domain-plan export and inspect the compiled artifact view. Review the resulting composition and relationships against the intent; the plan is product architecture, not the live resource registry.

Follow a real relationship task

This entry comes from Wonder CRM’s build plan. Its surrounding graph supplies the referenced tasks and requirements:

    {
      "taskRef": "build-task-contact-company-relationship",
      "objective": "Wire relationship contact ↔ company with one-to-many cardinality intent, where contact holds the reference.",
      "target": {
        "kind": BuildPlanTaskTargetKind.RELATIONSHIP,
        "moduleRef": "relationship-records",
        "relationshipRef": "contact-company"
      },
      "produces": [{ "kind": BuildPlanTaskProductKind.RESOURCE_RELATIONSHIP, "relationshipRef": "contact-company", "sourceResourceRef": "contact", "targetResourceRef": "company" }],
      "functionalTopic": MetaWorkflow_FunctionalTopic.MODEL_DOMAIN_GRAPH,
      "skillRefs": [
        "module-relationships"
      ],
      "prerequisiteTaskRefs": [
        "build-task-contact-schema",
        "build-task-company-schema"
      ],
      "servesRefs": [
        "functional-requirement-shared-contact-and-company-records"
      ]
    },

target describes the work scope. produces names the expected semantic artifact, including the relationship endpoints. prerequisiteTaskRefs expresses dependency; skillRefs supplies method context; servesRefs explains product purpose. Each answers a different question.

Validate dependencies as well as names

The graph checks task references, duplicate product identities and invalid dependencies. Resource-stage validation checks both the existence of a predecessor and whether it is in the task’s transitive prerequisites. The semantic authority distinguishes hard ordering faults from warnings about a missing predecessor that may already exist outside a partial plan.

Framework generation tasks have a separate completion path. Label, email-template and logo generation use the outputs defined by their pipelines; database migrations use the schema-plan-in-sync condition. A migration file’s mere presence is not that condition, and these generation tasks do not need a coding task’s produces declaration.

For other tasks without a declared product, the dispatcher can advance from a durable completed run while marking the result as unverifiable. Do not read every advanced task as a product-proven result.

Inspect the implementation outcome

Check the actual changes and relevant behavior after a task runs. Scope is not a security guarantee by itself, and a relationship declaration is not proof of the whole customer workflow. The task’s product and requirement references help select the verification that matters.

Read a placement decision

This illustrative decision uses the current public shape. The surrounding plan must declare the grouped sidebar address. The origin value describes an attributed decision, not proof that a review took place:

import { PlacementDisposition, PlacementDecisionOrigin, PlacementSubjectKind, PlacementSurface,
  type PlacementDecision } from '@wildo-ai/saas-specifications';

const contactListPlacement: PlacementDecision = {
  decisionRef: 'placement-contact-list',
  disposition: PlacementDisposition.PLACED,
  origin: PlacementDecisionOrigin.DELIBERATED,
  subject: {
    kind: PlacementSubjectKind.RESOURCE_OPERATION,
    moduleRef: 'relationship-records',
    resourceRef: 'contact',
    operation: 'list',
  },
  address: {
    surface: PlacementSurface.SIDEBAR,
    groupRef: 'customer-work',
    order: 10,
  },
  rationale: 'Keep shared customer records beside the work that depends on them.',
};

A placed decision carries an address. A declined decision carries its reason without an address. A revision records the rationale it supersedes, preserving the distinction between the original judgment and the changed one.

Use the surface’s actual structure

The validator checks the plan’s supported structural rules and reports coverage or ordering concerns. The semantic authority supplies the known engine settings destinations, so unknown engine destination references can be rejected. Application view and resource-operation existence need their own consumer context; do not infer those checks from the engine catalogue.

Inspect an application-owned plan

Wonder Todos exports applicationPlacementPlan from its specifications package and supplies it through placementPlanSpecification in the companion export. Its plan places the task list in the personal-work sidebar group and explains the triage purpose behind that decision. This is an existing application declaration; the contact example above illustrates the same contract with a different product.

Implement the planned navigation

The plan is a specification of placement, not automatic menu rendering. Apply the decision through the relevant shell configuration and review the resulting destination, labels and access behavior. A rationale explains the product choice; the rendered application establishes whether it is usable.

Read the posture method’s declared prerequisite

These selected fields come from the posture playbook definition. Method guidance and the longer output description are omitted:

{
  "preconditions": [
    { "kind": "artifact_exists", "selector": { "family": "vision-brief" } },
    { "kind": "step_available", "ref": "compliance-adequacy", "requires": { "path": "verdict", "equals": "adequate" } }
  ],
  "inputs": [{ "family": "vision-brief" }],
  "outputs": [{
    "family": "vision-brief",
    "schemaRef": "saas-specifications:VisionSnapshot",
    "description": "The existing vision refined with compliance constraints."
  }]
}

The prerequisite names the adequacy result the method expects. Its output refines the vision’s relevant constraints while retaining the rest of the product intent. The shortened description above summarizes the authored definition rather than quoting it verbatim.

Follow the distinct outputs

The research umbrella admits research, adequacy and posture activities. Conception is a separate method. Research and adequacy results are not themselves the same file family as the accepted programme.

Keep claims attached to their basis

Product declarations, runtime evidence, creator decisions and qualified reviews are different kinds of support. A producer’s authority label is attribution; it does not automatically prove the statement it accompanies.

Programme choices must connect to the application’s actual controls and evidence. Candidate documents and publication have their own review and release lifecycle. Use the document-facts guide for that connection; a generated policy statement is not a certification of the application.

Give the fact an identity and authority

The document-facts family carries versioned declarations, governance scope, sensitivity, authority and either a known value or a reason it does not apply. This selected Wonder CRM declaration records the service consent setting, its value and source authority. The clause below cites this same fact.

"declarationRef": "document-fact-declaration:service-consent-gate",
"declarationVersion": 1,
"factRef": "document-fact:service-consent-gate",
"factVersion": 1,
"governanceScope": {
  "subjectKind": GovernedDocumentGovernanceSubjectKind.APPLICATION_OPERATOR,
  "subjectRef": "operator:wonder-software-sas",
  "scopeRef": "scope:wonder-software-sas-application",
  "scopeVersion": 1,
  "participantRefs": [],
  "precedenceRuleRefs": []
},
"sensitivityRef": "sensitivity:public",
"authority": {
  "authorityRef": "document-fact-authority:service-consent-gate",
  "authorityVersion": 1,
  "factAuthorityKind": AssuranceDocumentFactAuthorityKind.APPLICATION_SPECIFICATION
},
"resolutionKind": ApplicationAssuranceDocumentFactContributionResolutionKind.KNOWN,
"value": "Use of the service is not gated on consent. This is a service-wide consent-gate configuration and does not state a lawful basis for processing."

A generated specification fact cannot simply claim qualified-review authority. Authored decision/review facts have separate schemas. Qualified-review declarations require different author and reviewer references, qualification references and an independence disclosure. The reference inequality guard does not establish that two references identify different people or that the reviewer is independent. Those substantive checks belong to review; the schema preserves their declared attribution.

Cite the fact from a reader-facing clause

This actual clause in the demonstration notice references the consent-gate fact, with no duplicate policy citation:

{
  "clauseRef": "clause:service-wide-consent-gate",
  "order": 1,
  "bodyMarkdown": "Use of Wonder CRM is not gated on service-wide consent. This configured gate status does not identify a lawful basis for processing.",
  "completeness": ComplianceStatementCompleteness.DERIVED,
  "factRefs": [
    "document-fact:service-consent-gate"
  ],
  "sourcePolicyRefs": [],
  "claimGuardRefs": [
    "claim-guard:no-consent-basis-conflation",
    "claim-guard:known-fact-only"
  ]
},

factRefs names established source facts; sourcePolicyRefs names policy areas when needed. A clause must cite at least one source across those fields. claimGuardRefs records constraints for the reviewer, not an automatic proof of semantic truth.

Validate the connection

The candidate fact-binding validator checks cited facts against declared availability, including both clauses and variant selections. A known fact needs a substantive value; an explicit not-applicable declaration has its own reason. The resulting document remains a reviewable content artifact. Its presence is not publication or approval, and source consistency is not a substitute for checking the prose’s meaning.

Check what the document owes as well as what it cites

A document can cite only valid facts and still omit a required subject. Coverage distinguishes an uncited required fact from one discussed only in an incomplete clause. The landing consumer scopes that check to declared facts; an unavailable blueprint or fact set is not proof of complete coverage.

This illustrative clause records an unresolved operating decision. Its policy and guard references must be chosen for the surrounding candidate:

import { ComplianceStatementCompleteness, type ComplianceDocumentCandidateClause } from '@wildo-ai/saas-specifications';

export const retentionDecision: ComplianceDocumentCandidateClause = {
  clauseRef: 'clause:retention-decision',
  order: 1,
  bodyMarkdown: 'The retention duration requires an operator decision.',
  completeness: ComplianceStatementCompleteness.NEEDS_DECISION,
  incompleteness: {
    needs: 'The retention duration for customer records.',
    closedBy: 'The operator responsible for the retention policy.',
  },
  factRefs: [],
  sourcePolicyRefs: ['policy:retention'],
  claimGuardRefs: ['claim-guard:retention-decision'],
};

A non-derived clause requires incompleteness; a derived clause must not carry it. When a known fact’s arrival would resolve the gap, name it in awaitingFactRefs so stale gap statements can be detected. Keep facts awaiting a human decision or qualified review in their authored family; regenerating application-derived facts must not replace those decisions. A marked draft is useful work for review, not permission to publish an unsupported statement.