Product Specification Standard

This directory contains implementation-driving product and engineering specifications. A spec is a shared product contract, not only a technical design. It must make the intended behavior understandable to someone who did not take part in the original discussion and testable by someone who did not implement it.

New specifications start from _template.md. Existing specs should converge on this standard when they are materially revised.

The capability inventory and its implementation evidence live in catalog.json; CATALOG.md is the generated human-readable view. In this SDK repository, run pnpm run validate:specifications after changing a specification or any catalogued path, and pnpm run generate:specifications after changing catalog metadata.

These invocation names are SDK-repository maintenance commands. Consumer specifications must verify actual commands, toolchains and execution directories against their selected immutable project source. A copied example does not establish an installed project script. When an invocation is absent, conflicting or unobserved, retain the required validation outcome and its explicit unresolved prerequisite; do not invent a wrapper or install a script to match an example. Command declarations and structurally valid specifications are separate from executed checks and product acceptance.

Truthful proposed capability bootstrap

A new product repository MAY register prospective SDDs as SDK version-1 proposed capabilities before product implementation exists. Every path field MUST be present as an array. For proposed entries only, entrypoints, code and tests MAY be empty; specs and documentation remain nonempty, and every supplied path MUST satisfy the ordinary existing-file, containment and ownership checks. Workflows retain their existing optional cardinality. Other statuses retain complete implementation-evidence requirements.

Bootstrap the standard, template, Draft SDDs, documentation and truthful catalog through an enabled documentation issue and its Action-owned branch, then review and merge the prerequisites before starting an eligible feature's normal gate. Catalog validation does not make a Draft Ready for implementation or establish executed tests. Preserve unresolved decisions and readiness metadata. Add real entrypoint/source/test evidence as it exists and change status to implemented only with the corresponding reviewed implementation. The recorded verification date for a proposed entry identifies its metadata/document review.

See the greenfield initialization guide for the supported lifecycle and SDK maintenance commands for generation without an application package. Upgrade an older SDK through its reviewed installation route; never manufacture evidence or bypass its validator.

Retrospective (as-built) specifications

An already implemented capability MAY be documented with status As-built baseline. This is not a claim that the feature is perfect or that all historic design choices were intentional. Its purpose is to establish a reviewable contract before subsequent changes.

An as-built baseline MUST:

• label verified repository behavior as observed behavior;
• label the behavior maintainers choose to preserve as the intentional contract;
• record defects, missing evidence, and architectural weaknesses under known debt and limitations;
• mark historic motivation as unknown when evidence does not establish it;
• keep desired improvements separate from the current contract and link them to follow-up work rather than presenting them as implemented;
• cite current code, workflows, tests, and user documentation; and
• use the same UX, architecture, configuration, security, testing, documentation, acceptance, and Definition of Done standard as a prospective specification.

The baseline date and Last verified catalog date identify the repository snapshot that was audited. A behavior-changing implementation MUST update the relevant SDD, catalog evidence, tests, and user documentation in the same change.

1. Core criteria

Every spec must be:

• Product-near: use the names, states, actions, and surfaces that users and operators will actually see.
• Visual where it helps: show multi-step flows, state changes, ownership, or several relationships with a compact diagram, table, timeline, or Markdown wireframe.
• Textually complete: every visual has an adjacent textual equivalent; color, emoji, screenshots, and Mermaid are never the only source of meaning.
• Explicit: distinguish current facts, proposed behavior, recommended defaults, configurable choices, fixed safety limits, non-goals, and open questions.
• End-to-end: include happy paths, alternatives, partial success, failure, retry, cancellation, migration, and cleanup where relevant.
• Verifiable: important statements use normative language and map to an automated test, contract check, or explicit human acceptance artifact.
• Proportional: a concern may be marked not applicable with a reason; it must not disappear silently.

Use MUST, SHOULD, and MAY deliberately. A MUST requires an acceptance scenario. Avoid prescribing implementation details unless they protect product behavior, architecture, interoperability, or safety.

2. Required specification contract

A specification must cover the following concerns or mark them not applicable:

Concern	Required outcome
Decision metadata	Status, date, owners, scope, review gates, and unresolved decisions
Problem and evidence	Current behavior, concrete pain, affected actors, and evidence/source
Goals and limits	Measurable outcomes, non-goals, fixed safety/product invariants
Product journey	Current versus proposed flow, actors, entrypoints, visible surfaces, next actions
Domain model	Shared terminology, invariants, states, transitions, and ownership of facts
Configuration	Recommended defaults, bounded alternatives, validation, precedence, persistence, migration
Architecture	Dependency direction, pure policy, use cases, ports, adapters, presentation, state and trust boundaries
UI/UX and content	Information hierarchy, examples for every primary state, navigation, accessibility, localization
Failure and recovery	Impact, partial-success facts, retryability, idempotency, cleanup, operator action
Security and privacy	Permissions, untrusted input, secrets, execution boundaries, auditability
Observability	User status, operator evidence, logs/metrics, correlation, noise budget
Compatibility and rollout	Existing in-flight state, migration, deprecation, rollout and rollback
Testing	Numeric risk-derived budget, distribution, coverage, fixtures, integration and human evidence
Documentation	User, setup, configuration, recovery, migration, architecture and discoverability
Acceptance and DoD	Observable scenarios, traceability, implementation order, all quality gates

3. Product and GitHub UI/UX standard

GitHub issues, pull requests, reviews, comments, checks, labels, releases, and Job Summaries are product surfaces when a person uses them to understand or operate a feature. CLI output and generated documentation are product surfaces for the same reason.

For each primary state, the first visible content must answer in this order:

1. What is happening now?
2. What completed already?
3. What happens next?
4. Is human action required?
5. What is the impact, especially for partial success or failure?
6. Where can the result or transition be inspected?
7. Where are technical details available?

A spec affecting these surfaces must include representative rendered Markdown or a wireframe for at least pending, action-required, blocked/failed, partially complete, and complete states. Use actual product terminology and plausible data. Do not specify only abstract fields such as status, message, and url.

The UX contract must define, when applicable:

• one primary status and one primary action;
• progress/state representation and the facts behind it;
• deterministic titles, headings, labels, and durable markers;
• descriptive links to the issue, PR, comparison, commit, run, artifact, release, package, documentation, and recovery action;
• progressive disclosure: user meaning first, technical diagnostics later;
• error content in impact -> cause -> action -> retained state order;
• idempotent update behavior and a bounded comment/notification budget;
• locale source, supported locales, and fallback behavior;
• narrow/mobile readability, light/dark themes, and logical heading/table use;
• sanitization of mentions, commands, Markdown, HTML markers, URLs, and diagrams; and
• a textual fallback for Mermaid, images, icons, and other visual elements.

For a flow with three or more dependent transitions, include one overview visual. For a user-facing issue or PR change, include at least one concrete content mockup. Screenshots can supplement these artifacts but cannot replace the semantic written contract.

4. Clean Architecture standard

Apply Clean Architecture to the repository's real boundaries rather than inventing a parallel folder taxonomy. A design must identify:

• domain entities, value objects, invariants, and pure policies;
• application use cases and narrow immutable input/output contracts;
• semantic ports that express capabilities without provider DTOs;
• data/provider adapters and their error mappings;
• infrastructure and composition ownership;
• entrypoint responsibility and trusted/untrusted event boundaries;
• presentation view models and renderers, separate from mutation policy;
• durable state, concurrency, idempotency, and migration ownership; and
• forbidden dependency directions that can be enforced automatically.

Use a component/dependency diagram when three or more layers or external systems interact. Use a sequence or state diagram when ordering, retries, asynchronous events, or partial completion affect correctness.

Architecture requirements are incomplete without executable constraints. The spec must state which dependency, contract, cycle, schema, or workflow checks will prevent boundary erosion.

5. Configuration standard

Configuration exists to support legitimate product variation, not to make every implementation detail optional. Every input must define:

Field	Required information
Name and type	Stable public name, type, and owning surface
Recommended default	Safe default and why it is recommended
Allowed values/range	Bounded choices with observable semantics
Validation	Invalid values and invalid cross-field combinations
Scope and precedence	Project/repository/operation scope and override order
Persistence	Whether an in-flight operation snapshots or rereads the value
Migration	Behavior for absent, retired, renamed, or future values
Security	Values that must never accept arbitrary code, refs, URLs, or secrets

Show at least one recommended configuration and one meaningful alternative. State which correctness and safety invariants are intentionally not configurable.

6. Test budget standard

Every implementation-driving spec must contain a numeric test budget. Derive it from the behavior and risk inventory; do not reuse one universal count for small and large changes.

The budget table must distribute a minimum number of distinct cases across the applicable areas:

• domain/configuration/pure planning;
• state transitions, idempotency, replay, cancellation, and races;
• application use cases;
• adapters and provider error mapping;
• workflows, permissions, schemas, and setup contracts;
• presentation states, links, localization, accessibility, and sanitization;
• integration/end-to-end and compatibility/migration; and
• security/abuse cases.

Each it/test case counts once. Parameterized rows count separately only when they represent distinct behavior. The number is a floor, not a substitute for covering every requirement and failure mode.

The spec must also define:

• repository-wide thresholds that remain in force;
• higher branch coverage for new pure policy where justified;
• changed-module expectations;
• deterministic fakes instead of real waits or live services;
• fixtures/golden output without relying only on snapshots;
• workflow/contract checks that parse structure rather than grep prose;
• required manual UX evidence that automation cannot establish; and
• a traceability mapping from each normative requirement to tests or evidence.

7. Documentation standard

Documentation is an implementation deliverable. Identify the applicable audiences and artifacts:

• user journey and recommended default;
• setup, permissions, environments, credentials, and external prerequisites;
• complete configuration reference and examples;
• operator state model, troubleshooting, recovery, replay, and cleanup;
• upgrade, migration, compatibility, deprecation, and rollback;
• architecture, contracts, trust boundaries, and contributor guidance; and
• route/navigation registration, links, assets, examples, and validation jobs.

Lead documentation with the normal path and one helpful visual, then disclose configuration, failures, and internals progressively. Examples must be checked against implementation fixtures or contract tests whenever practical.

8. Acceptance, traceability, and review

Acceptance scenarios describe observable behavior, not implementation activity. Cover normal, alternative, boundary, invalid, duplicate, out-of-order, partial, failure, recovery, migration, security, UX, and accessibility behavior as applicable.

Maintain a traceability table for substantial specs:

Requirement -> domain/policy/use case/adapter/presentation -> test or evidence -> documentation

Before changing a spec to Ready for implementation, reviewers must be able to answer yes to the following:

• Is the origin/current behavior supported by evidence?
• Can a user understand the proposed product without reading implementation code?
• Are product defaults and non-configurable safety limits explicit?
• Are architecture boundaries and executable constraints clear?
• Is the numeric test budget proportional and complete?
• Are documentation and migration deliverables named?
• Do UI examples cover pending, action, error/partial, and completed states?
• Can status and required action be understood quickly without logs?
• Are security, idempotency, retries, concurrency, and cleanup addressed?
• Does every MUST map to acceptance and verification?
• Are material decisions resolved or explicitly blocking readiness?

The Definition of Done must repeat these gates. A concern mentioned only in an introductory paragraph is not an enforceable delivery requirement.