# AWP Specification and Mockup Sequence **Date:** 2026-08-19 **Status:** **Binding product-quality sequence.** **Specification authority:** [`AWP-FULL-SPECIFICATION-RATIFICATION.md`](AWP-FULL-SPECIFICATION-RATIFICATION.md). **Implementation authority:** [`AWP-INCREMENTAL-DELIVERY-PLAN.md`](AWP-INCREMENTAL-DELIVERY-PLAN.md). **Purpose:** Prevent accidental architecture/UI and vision drift while preserving end-to-end incremental implementation. ## 1. Product-quality premise AWP is not another Overdeck-style experiment. Two rules are simultaneously binding: ```text FULL TARGET SPECIFICATION BEFORE IMPLEMENTATION AND INCREMENTAL END-TO-END IMPLEMENTATION ``` Neither is allowed to erase the other. ## 2. Full specification before implementation Before Increment 0 implementation materially begins, complete the canonical target-state specification system across: ```text Architecture Domains Major workflows UI/pages + whole-product information architecture Schemas/contracts/adapters Decisions / ADRs / cross-links Increment Realization I0..I9 ``` Every active canonical spec has a full human HTML companion. The target behavior/seams for later increments must be explicit now. Later implementation mechanics may still evolve behind those seams when evidence justifies it. See [`AWP-FULL-SPECIFICATION-RATIFICATION.md`](AWP-FULL-SPECIFICATION-RATIFICATION.md). ## 3. Full specification does not change implementation order The following remains explicitly rejected as implementation order: ```text Planning -> Project -> Factory / Agent -> CI -> CD ``` Implementation is still by coherent vertical increment: ```text I0 foundation I1 Project -> Plan -> Task -> FactoryRun -> AgentRun -> ChangeSet -> Review -> Merge I2 Real Planning I3 Decisions/Approvals/autonomy I4 Factory observability I5 CI control plane I6 Release/Deployment I7 Cluster product surface I8 self-healing I9 external/enterprise + formal reliability/SLO ``` The capability-level timing is binding in [`AWP-INCREMENT-REALIZATION-MATRIX.md`](AWP-INCREMENT-REALIZATION-MATRIX.md). ## 4. Required structure of every spec Every canonical spec must make future intent visible from current implementation: ```text Target State Invariants From Day 1 Increment Realization Current Implementation State Deferred Realization Temporary Dogfood Behavior Decisions / ADRs ``` Do not split one concept into incompatible `minimal now` and `real later` models. ## 5. Specification authoring order Write the full spec system in dependency order for coherence: ```text architecture / trust / persistence / provider seams -> complete domain model and primitive relationships -> cross-domain workflows -> UI/page behavior + product information architecture -> schemas/contracts/adapter contracts -> Decision/ADR reconciliation -> I0..I9 realization cross-check -> human HTML/render/link completeness pass ``` This is specification authoring order only. It does not authorize implementation outside the active increment. ## 6. Why specs precede high-fidelity mockups Detailed mockups need real answers about: ```text state permissions data ownership workflow transitions failure/waiting behavior inheritance/defaults reversibility connection requirements responsive behavior valid actions future page relationships ``` Full page behavior and product information architecture are therefore specified before final high-fi is treated as product authority. ## 7. Why high-fidelity still precedes UI implementation AWP UI must not be invented in JSX/CSS. Before a user-facing state is implemented, the user must be able to inspect and reject the exact intended product visually. Approved high-fidelity mockups are mandatory for the states being implemented in the current increment. Important distinction: ```text full page behavior / IA specified now exact high-fi frames approved before their implementation increment implementation incremental ``` ## 8. Whole-product visual coherence before Slice 1 Before the first user-facing implementation, the specification/design system must already define: ```text product shell navigation model major page relationships shared design system / visual language whole-product information architecture ``` This prevents I1 from producing a polished shell that becomes a dead end for I2 Planning, I5 CI, I6 Release/CD or I8 Incidents. Exact future-page high-fi can still be created when its increment approaches, but its place in the product cannot be undefined. ## 9. Page evolution across increments The same page may reveal more already-specified capability over time. Example: ```text Plan target spec complete final behavior now I1 realization narrow polished Plan/Task start surface I2 realization full Simple/Expert Planning workspace integration later realization CI/release/deployment/incident context appears as planned ``` Later approved high-fi replaces earlier visual authority for the affected state. Historical mockups remain traceability evidence only. ## 10. Increment-scoped high-fidelity coverage For every user-facing state actually shipped in an increment, cover materially different states such as: ```text normal populated waiting/blocked failure/recovery permission/approval loading/empty when materially distinct responsive/narrow state where applicable high-risk confirmation when applicable ``` Avoid redundant frames, but never rely on one happy-path screenshot when the interaction materially changes under failure or risk. ## 11. Spec/mockup convergence loop ```text full target spec -> high-fi for current realization -> human review | +-- behavioral gap -> amend target spec -> update mockup +-- visual/UX gap -> update mockup -> verify spec still holds +-- realization conflict -> amend matrix/Decision first +-- no material gap -> approve current increment design ``` ## 12. Full-specification completion gate Before I0 implementation materially begins: ```text full architecture target specs complete full domain target specs complete full major workflow specs complete full UI/page target specs complete whole-product IA/navigation defined schemas/contracts ownership defined all active specs have HTML companions INDEX.html links all active specs/plans all specs carry Increment Realization material Decisions/ADRs linked cross-spec contradictions/missing seams reviewed ``` ## 13. Per-increment Design Complete gate After the full baseline exists, an increment may enter implementation when: ```text increment goal / complete user journey explicit its realization boundary matches the matrix current code plan preserves target invariants exact user-facing states being shipped are high-fi approved failure/waiting/permission/responsive behavior covered spec and mockups agree temporary dogfood shortcuts explicit + removal/deepening increment known remaining unknowns are implementation-local ``` ## 14. Human-readable specification requirement All canonical specs follow [`../specs/SPEC-PRESENTATION-STANDARD.md`](../specs/SPEC-PRESENTATION-STANDARD.md): ```text canonical Markdown technical source + generated committed HTML companion + diagrams/flowcharts + stable hyperlinks/cross-references + Increment Realization navigation + Decision/ADR links + approved mockups for applicable UI states + human INDEX.html root ``` The human HTML form contains the complete technical contract, not an executive summary. ## 15. Role of UX research/design methods UX-researcher/UX-designer methods remain reasoning tools for us. They do not become mandatory owner-facing ceremony. Real-user research remains conditional when uncertainty/consequence justifies it. ## 16. Accepted engineering-practice integration The full spec set must define all accepted practices now while preserving their realization timing: ```text R1 architecture conformance operational I0 onward R2 threat modeling AWP before privileged I1; Planning capability I2 R3 SBOM/provenance when artifacts first distribute; productized I6 R4 compatibility policy specified now; gates when stable consumers exist; CI integration I5 R5 reliability/SLO/error budgets fully specified target; operationally parked until I9 ``` ## 17. Current design target The current phase is no longer `spec only what I0/1 needs`. It is: ```text FULL AWP SPECIFICATION PROGRAM -> all HTML companions + diagrams + cross-links -> Increment Realization cross-check -> contradiction / missing-seam / Decision traceability review -> I0/I1 exact high-fi states U1..U6 -> consolidated review -> I0 implementation -> I1 end-to-end dogfood ``` Rich Planning behavior is fully specified now but remains operationally I2.