openuispec 0.1.41 → 0.1.42

package/cli/init.ts

@@ -319,21 +319,28 @@ or any visual/structural change — you MUST use the OpenUISpec tools before wri
 
 Call these MCP tools directly. They return structured JSON with everything you need.
 
-1. **Before ANY UI code generation or modification:**
-   Call \`openuispec_prepare\` with the target platform. This returns the spec context,
-   platform config, generation constraints, and semantic changes. Do not skip this step.
-
-2. **After editing spec files:**
-   Call \`openuispec_check\` to validate schema + semantic lint + prepare readiness.
-
-3. **To understand project state:**
-   Call \`openuispec_status\` for cross-target summary.
-
-4. **To detect what changed:**
-   Call \`openuispec_drift\` with \`explain: true\` to see property-level spec changes.
-
-5. **For schema validation only:**
-   Call \`openuispec_validate\` optionally with specific groups.
+**Pre-generation:**
+1. Call \`openuispec_prepare\` with the target platform — returns spec context, platform config, constraints.
+2. Call \`openuispec_read_specs\` to load spec file contents. Use these as the AUTHORITATIVE source.
+3. If spec changes are needed, update spec files FIRST, then call \`openuispec_check\`.
+4. Generate or update the platform UI code based on the spec contents.
+
+**Post-generation (EVERY TIME after writing UI code):**
+5. Call \`openuispec_check\` to validate spec integrity.
+6. Call \`openuispec_read_specs\` for the screens/contracts you just generated code for.
+7. Audit your generated code against the spec. For each screen, verify:
+   - Every field/action in the spec has a corresponding UI element
+   - Token values (colors, spacing, radii) match exactly — no approximations
+   - Contract \`must_handle\` states are all implemented (loading, error, empty, etc.)
+   - Adaptive breakpoints match the spec's \`size_classes\`
+   - Locale keys match \`$t:\` references
+   - Navigation targets match flow definitions
+8. Report any real gaps found and fix them before finishing.
+
+**Other tools:**
+- \`openuispec_status\` — cross-target summary, good starting point
+- \`openuispec_drift\` with \`explain: true\` — property-level spec changes
+- \`openuispec_validate\` — schema-only validation by group
 
 ### CLI fallback (when MCP is not available)
 

package/mcp-server/index.ts

@@ -69,14 +69,26 @@ const server = new McpServer(
 Spec files (YAML) are the single source of truth for all UI across platforms.
 
 MANDATORY WORKFLOW for any UI-related request (screens, navigation, layout, tokens, flows, localization):
-1. BEFORE writing or modifying any UI code, call openuispec_prepare with the target platform.
-   This returns the spec context, platform config, generation constraints, and the list of spec files.
-2. Then call openuispec_read_specs to load the spec file contents you need for the task.
-   Pass specific paths for targeted work, or omit paths to load everything.
+
+PRE-GENERATION:
+1. Call openuispec_prepare with the target platform.
+2. Call openuispec_read_specs to load the spec file contents you need.
    Use the returned contents as the AUTHORITATIVE source — do NOT paraphrase from memory.
    Cross-reference exact token values, contract must_handle lists, and locale keys from the content.
-3. If the request requires spec changes, update the spec files FIRST, then call openuispec_check to validate.
-4. Only then generate or update the platform UI code based on the spec contents.
+3. If the request requires spec changes, update the spec files FIRST, then call openuispec_check.
+4. Generate or update the platform UI code based on the spec contents.
+
+POST-GENERATION (do this EVERY TIME after writing UI code):
+5. Call openuispec_check to validate spec integrity.
+6. Call openuispec_read_specs for the screens/contracts you just generated code for.
+7. Audit your generated code against the spec contents. For each screen, verify:
+   - Every field/action in the spec has a corresponding UI element
+   - Token values (colors, spacing, radii) match the spec exactly, not approximations
+   - Contract must_handle states are all implemented (loading, error, empty, etc.)
+   - Adaptive breakpoints match the layout size_classes in the spec
+   - Locale keys match $t: references in the spec
+   - Navigation targets match flow definitions
+   Report any real gaps found and fix them before finishing.
 
 Skip these tools ONLY when the request is purely non-UI (API logic, database, infrastructure, etc.)
 or explicitly platform-specific polish that doesn't affect shared UI semantics.`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openuispec",
-  "version": "0.1.41",
+  "version": "0.1.42",
   "license": "MIT",
   "type": "module",
   "description": "A semantic UI specification format for AI-native, platform-native app development",