openuispec 0.1.27 → 0.1.28

package/README.md

@@ -68,7 +68,7 @@ For platform generation, treat these as hard output constraints:
 
 See the examples for concrete reference projects:
 
-- [TaskFlow](./examples/taskflow/) for a compact spec covering all 7 contract families
+- [TaskFlow](./examples/taskflow/openuispec/) for a compact spec covering all 7 contract families
 - [Todo Orbit](./examples/todo-orbit/openuispec/) for a bilingual task app with generated iOS, Android, and web targets under `examples/todo-orbit/generated/`
 
 ## Repository structure
@@ -154,21 +154,21 @@ Every file type has a corresponding JSON Schema in `schema/`. **Read the schema
 
 | File | Schema | Root key | Example |
 |------|--------|----------|---------|
-| `openuispec.yaml` | `openuispec.schema.json` | `spec_version` | [openuispec.yaml](./examples/taskflow/openuispec.yaml) |
-| `screens/*.yaml` | `screen.schema.json` | `<screen_id>` | [home.yaml](./examples/taskflow/screens/home.yaml) |
-| `flows/*.yaml` | `flow.schema.json` | `<flow_id>` | [create_task.yaml](./examples/taskflow/flows/create_task.yaml) |
-| `platform/*.yaml` | `platform.schema.json` | `platform` | [ios.yaml](./examples/taskflow/platform/ios.yaml) |
-| `locales/*.json` | `locale.schema.json` | (object) | [en.json](./examples/taskflow/locales/en.json) |
-| `contracts/<name>.yaml` | `contract.schema.json` | `<contract_name>` | [input_field.yaml](./examples/taskflow/contracts/input_field.yaml) |
-| `contracts/x_*.yaml` | `custom-contract.schema.json` | `<x_name>` | [x_media_player.yaml](./examples/taskflow/contracts/x_media_player.yaml) |
-| `tokens/color.yaml` | `tokens/color.schema.json` | `color` | [color.yaml](./examples/taskflow/tokens/color.yaml) |
-| `tokens/typography.yaml` | `tokens/typography.schema.json` | `typography` | [typography.yaml](./examples/taskflow/tokens/typography.yaml) |
-| `tokens/spacing.yaml` | `tokens/spacing.schema.json` | `spacing` | [spacing.yaml](./examples/taskflow/tokens/spacing.yaml) |
-| `tokens/elevation.yaml` | `tokens/elevation.schema.json` | `elevation` | [elevation.yaml](./examples/taskflow/tokens/elevation.yaml) |
-| `tokens/motion.yaml` | `tokens/motion.schema.json` | `motion` | [motion.yaml](./examples/taskflow/tokens/motion.yaml) |
-| `tokens/layout.yaml` | `tokens/layout.schema.json` | `layout` | [layout.yaml](./examples/taskflow/tokens/layout.yaml) |
-| `tokens/themes.yaml` | `tokens/themes.schema.json` | `themes` | [themes.yaml](./examples/taskflow/tokens/themes.yaml) |
-| `tokens/icons.yaml` | `tokens/icons.schema.json` | `icons` | [icons.yaml](./examples/taskflow/tokens/icons.yaml) |
+| `openuispec.yaml` | `openuispec.schema.json` | `spec_version` | [openuispec.yaml](./examples/taskflow/openuispec/openuispec.yaml) |
+| `screens/*.yaml` | `screen.schema.json` | `<screen_id>` | [home.yaml](./examples/taskflow/openuispec/screens/home.yaml) |
+| `flows/*.yaml` | `flow.schema.json` | `<flow_id>` | [create_task.yaml](./examples/taskflow/openuispec/flows/create_task.yaml) |
+| `platform/*.yaml` | `platform.schema.json` | `platform` | [ios.yaml](./examples/taskflow/openuispec/platform/ios.yaml) |
+| `locales/*.json` | `locale.schema.json` | (object) | [en.json](./examples/taskflow/openuispec/locales/en.json) |
+| `contracts/<name>.yaml` | `contract.schema.json` | `<contract_name>` | [input_field.yaml](./examples/taskflow/openuispec/contracts/input_field.yaml) |
+| `contracts/x_*.yaml` | `custom-contract.schema.json` | `<x_name>` | [x_media_player.yaml](./examples/taskflow/openuispec/contracts/x_media_player.yaml) |
+| `tokens/color.yaml` | `tokens/color.schema.json` | `color` | [color.yaml](./examples/taskflow/openuispec/tokens/color.yaml) |
+| `tokens/typography.yaml` | `tokens/typography.schema.json` | `typography` | [typography.yaml](./examples/taskflow/openuispec/tokens/typography.yaml) |
+| `tokens/spacing.yaml` | `tokens/spacing.schema.json` | `spacing` | [spacing.yaml](./examples/taskflow/openuispec/tokens/spacing.yaml) |
+| `tokens/elevation.yaml` | `tokens/elevation.schema.json` | `elevation` | [elevation.yaml](./examples/taskflow/openuispec/tokens/elevation.yaml) |
+| `tokens/motion.yaml` | `tokens/motion.schema.json` | `motion` | [motion.yaml](./examples/taskflow/openuispec/tokens/motion.yaml) |
+| `tokens/layout.yaml` | `tokens/layout.schema.json` | `layout` | [layout.yaml](./examples/taskflow/openuispec/tokens/layout.yaml) |
+| `tokens/themes.yaml` | `tokens/themes.schema.json` | `themes` | [themes.yaml](./examples/taskflow/openuispec/tokens/themes.yaml) |
+| `tokens/icons.yaml` | `tokens/icons.schema.json` | `icons` | [icons.yaml](./examples/taskflow/openuispec/tokens/icons.yaml) |
 
 Every token file **must** have a single root wrapper key matching its type:
 
@@ -202,12 +202,14 @@ generation:
 
 Paths are relative to `openuispec.yaml`. The `.openuispec-state.json` file is stored inside each output directory and records spec file hashes plus the git baseline commit metadata captured at snapshot time.
 
+`openuispec drift --snapshot --target <target>` requires that target output directory to already exist. If it does not, generate the target code first, then snapshot the accepted baseline.
+
 Use the commands like this:
 - `openuispec validate` checks schema correctness
 - `openuispec validate semantic` checks cross-references such as locale keys, formatters, mappers, contracts, icons, navigation targets, and API endpoints
 - `openuispec drift --target <t> --explain` explains semantic spec changes since that target's accepted baseline
 - `openuispec prepare --target <t>` turns those changes into an AI-ready target update bundle
-- `openuispec status` shows every target's snapshot state, baseline commit, and whether that target is behind the current spec
+- `openuispec status` shows every target's snapshot state, baseline commit, and whether that target is behind the current spec, still needs a baseline, or has not been generated yet
 
 If a target snapshot was created before baseline metadata was added, `--explain` and `status` will tell you to re-run `openuispec drift --snapshot --target <target>` for that target.
 
@@ -220,6 +222,7 @@ openuispec validate
 openuispec drift --target ios --explain
 openuispec prepare --target ios
 # update the ios implementation
+# ensure the ios output directory already exists
 openuispec drift --snapshot --target ios
 ```
 
@@ -228,7 +231,7 @@ Meaning:
 - `validate semantic` checks cross-reference integrity
 - `drift --explain` shows semantic spec changes since that target's accepted baseline
 - `prepare` packages those changes into an AI/developer work bundle
-- `drift --snapshot` accepts the updated state after the target UI has been updated
+- `drift --snapshot` accepts the updated state after the target UI has been updated and the target output directory exists
 
 Before picking the next platform to update, run:
 
@@ -238,7 +241,7 @@ openuispec status
 
 to see which targets are already up to date and which ones still need to catch up with shared spec changes.
 
-`drift --snapshot` is bookkeeping. It does not prove that the target code matches the spec.
+`drift --snapshot` is bookkeeping. It does not prove that the target code matches the spec, and it will not create a missing target output directory for you.
 
 ## Spec at a glance
 

package/cli/init.ts

@@ -171,7 +171,7 @@ Do NOT guess the file format — skipping this step will produce invalid YAML th
 **Reference files inside the package (read in this order):**
 1. \`README.md\` — schema tables, file format reference, root keys
 2. \`spec/openuispec-v0.1.md\` — full specification (contracts, layout, expressions, etc.)
-3. \`examples/taskflow/\` — complete working example with all file types
+3. \`examples/taskflow/openuispec/\` — complete working example with all file types
 4. \`schema/\` — JSON Schemas for validation
 
 ## CLI commands
@@ -183,7 +183,7 @@ openuispec validate screens     # Validate only screens
 openuispec status               # Show cross-target baseline/drift status
 openuispec drift --target ${targets[0]} --explain   # Explain semantic spec drift
 openuispec prepare --target ${targets[0]}          # Build an AI-ready target update bundle
-openuispec drift --snapshot --target ${targets[0]} # Snapshot current state + git baseline
+openuispec drift --snapshot --target ${targets[0]} # Snapshot current state + git baseline after target output exists
 \`\`\`
 
 ## Learn more
@@ -218,7 +218,7 @@ Do NOT guess the file format — skipping this step will produce invalid YAML th
 **Reference files inside the package (read in this order):**
 1. \`README.md\` — schema tables, file format reference, root wrapper keys
 2. \`spec/openuispec-v0.1.md\` — full specification (contracts, layout, expressions, adaptive, etc.)
-3. \`examples/taskflow/\` — complete working example with all file types
+3. \`examples/taskflow/openuispec/\` — complete working example with all file types
 4. \`schema/\` — JSON Schemas for every file type
 
 These files are updated with each package version. Always read from the installed package,
@@ -276,7 +276,7 @@ Spec-first workflow:
 6. Run \`openuispec drift --target <target> --explain\` to inspect semantic changes since that target's baseline.
 7. Run \`openuispec prepare --target <target>\` to build the AI/developer work bundle for that target.
 8. Verify the affected UI targets build/run if possible.
-9. Only then run \`openuispec drift --snapshot --target <target>\` for affected targets.
+9. Only then run \`openuispec drift --snapshot --target <target>\` for affected targets, after that target output directory exists.
 10. Run \`openuispec drift --target <target> --explain\` again to confirm no spec changes remain for that target.
 11. Use \`openuispec status\` to see which other targets are still behind the updated spec.
 
@@ -302,7 +302,7 @@ Platform-first workflow:
 - \`openuispec validate semantic\` — run semantic cross-reference linting
 - \`openuispec drift --target <t>\` — check for spec drift
 - \`openuispec drift --target <t> --explain\` — explain semantic spec drift since the target baseline
-- \`openuispec drift --snapshot --target <t>\` — snapshot current state
+- \`openuispec drift --snapshot --target <t>\` — snapshot current state after the target output exists
 - \`openuispec prepare --target <t>\` — build an AI-ready target update bundle
 - \`openuispec status\` — show cross-target baseline/drift status
 - \`openuispec update-rules\` — update AI rules to match installed package version
@@ -511,7 +511,7 @@ Getting started (new project):
   2. Create screens in ${specDir}/screens/ (one YAML per screen)
   3. Create flows in ${specDir}/flows/ (multi-step navigation)
   4. Ask AI to generate native code from the spec
-  5. Run \`openuispec drift --snapshot --target ${targets[0]}\` to baseline the first accepted target state
+  5. Run \`openuispec drift --snapshot --target ${targets[0]}\` to baseline the first accepted target state after that target output directory exists
 
 Getting started (existing project):
   1. Ask AI to read your existing UI code and generate spec files:
@@ -527,7 +527,7 @@ Commands:
   openuispec status   Show cross-target baseline/drift status
   openuispec drift --target ios --explain   Explain semantic spec changes
   openuispec prepare --target ios   Build an AI-ready target update bundle
-  openuispec drift --snapshot --target ios   Save current state + git baseline
+  openuispec drift --snapshot --target ios   Save current state + git baseline after target output exists
 
 AI rules have been added to CLAUDE.md and AGENTS.md.
 

package/docs/implementation-notes.md

@@ -86,6 +86,7 @@
 - `openuispec status` is the cross-target overview command.
 - Current output includes, per target:
   - output directory
+  - whether the output directory exists
   - snapshot present or missing
   - snapshot timestamp
   - baseline kind / commit / branch
@@ -95,6 +96,7 @@
   - note for missing or legacy snapshots
 - Important positioning:
   - `status` answers "which targets are behind shared spec changes?"
+  - `status` should distinguish "needs generation" from "needs baseline"
   - `status` does not verify code alignment
 - Real-world behavior to document:
   - if `web` was re-snapshotted after the new baseline metadata was added, but `ios` and `android` still have older state files, `status` should show:
@@ -111,5 +113,7 @@
   5. `openuispec prepare --target <target>`
   6. update target UI code
   7. build/run and review
-  8. `openuispec drift --snapshot --target <target>`
+  8. ensure the target output directory exists
+  9. `openuispec drift --snapshot --target <target>`
 - `drift --snapshot` should continue to be described as bookkeeping/baselining, not as proof that the target implementation matches the spec.
+- If the target output directory does not exist yet, the CLI should direct the user to run code generation first instead of implying that snapshot can initialize an empty target.

package/docs/release-notes-v0.1.28.md

@@ -0,0 +1,25 @@
+# OpenUISpec v0.1.28
+
+This patch supersedes `v0.1.27`.
+
+## Fixes
+
+- Fixed the drift/prepare onboarding dead-end for targets that have not been generated yet.
+  - `drift --snapshot` now keeps the guard against baselining an empty target.
+  - Missing-snapshot guidance now tells users to generate the target output first when the output directory does not exist.
+- Improved `status` to distinguish:
+  - targets that need generation
+  - targets that need a baseline snapshot
+- Updated workflow docs and generated project templates to describe the generation-first requirement before snapshotting.
+- Stabilized the affected CLI tests in this repo by invoking TypeScript entrypoints through the `tsx` loader path instead of the IPC-based binary wrapper.
+
+## Recommended workflow
+
+1. `openuispec validate`
+2. `openuispec validate semantic`
+3. `openuispec status`
+4. `openuispec drift --target <target> --explain`
+5. `openuispec prepare --target <target>`
+6. update target UI
+7. ensure the target output directory exists
+8. `openuispec drift --snapshot --target <target>`

package/docs/stress-test-maturity-report.md

@@ -14,7 +14,7 @@ This assessment stress-tested the project at four layers:
 
 ```bash
 npm ci
-npm run validate                                # from examples/taskflow (workspace script)
+npm run validate                                # from examples/taskflow/openuispec (workspace script)
 npx tsx ../../../schema/validate.ts            # from examples/todo-orbit/openuispec
 npx tsc --noEmit
 for t in ios android web; do

package/drift/index.ts

@@ -466,6 +466,26 @@ export function stateFilePath(projectDir: string, projectName: string, target: s
   return join(resolveOutputDir(projectDir, projectName, target), STATE_FILE);
 }
 
+function missingSnapshotMessage(
+  cwd: string,
+  projectDir: string,
+  projectName: string,
+  target: string
+): string {
+  const outDir = resolveOutputDir(projectDir, projectName, target);
+  if (!existsSync(outDir)) {
+    return (
+      `No snapshot found for target "${target}".\n` +
+      `Output directory not found: ${relative(cwd, outDir)}\n` +
+      `Run code generation for "${target}" first, then run: openuispec drift --snapshot --target ${target}`
+    );
+  }
+  return (
+    `No snapshot found for target "${target}".\n` +
+    `Run: openuispec drift --snapshot --target ${target}`
+  );
+}
+
 export function discoverTargets(projectDir: string, projectName: string): string[] {
   const outputDirs = readOutputDirs(projectDir);
   const targets: string[] = [];
@@ -626,10 +646,7 @@ export function loadTargetDrift(
   const projectName = readProjectName(projectDir);
   const statePath = stateFilePath(projectDir, projectName, target);
   if (!existsSync(statePath)) {
-    console.error(
-      `No snapshot found for target "${target}".\n` +
-        `Run: openuispec drift --snapshot --target ${target}`
-    );
+    console.error(missingSnapshotMessage(cwd, projectDir, projectName, target));
     process.exit(1);
   }
 

package/examples/taskflow/AGENTS.md

@@ -0,0 +1,112 @@
+<!-- openuispec-rules-start -->
+<!-- openuispec-rules-version: 0.1.28 -->
+# OpenUISpec — AI Assistant Rules
+# ================================
+# This project uses OpenUISpec to define UI as a semantic spec.
+# Spec files are the single source of truth for all UI across platforms.
+# Targets: "ios", "android", "web"
+
+## IMPORTANT — Read the specification before working with spec files
+
+The spec format, file schemas, and generation rules are defined in the installed `openuispec` package.
+You MUST read the reference files listed below before creating, editing, or generating from any spec file.
+Do NOT guess the file format — skipping this step will produce invalid YAML that fails validation.
+
+**Find the package in this order:**
+1. `node_modules/openuispec/` (project dependency)
+2. Run `npm root -g` → `<prefix>/openuispec/` (global install)
+3. Online: `https://openuispec.rsteam.uz/llms-full.txt` (if not installed)
+
+**Reference files inside the package (read in this order):**
+1. `README.md` — schema tables, file format reference, root wrapper keys
+2. `spec/openuispec-v0.1.md` — full specification (contracts, layout, expressions, adaptive, etc.)
+3. `examples/taskflow/openuispec/` — complete working example with all file types
+4. `schema/` — JSON Schemas for every file type
+
+These files are updated with each package version. Always read from the installed package,
+not from cached or memorized content, to ensure you use the latest spec.
+
+## What is OpenUISpec
+OpenUISpec is a YAML-based spec format that describes an app's UI semantically — tokens, screens, flows, and platform overrides. AI reads the spec and generates native code (SwiftUI, Compose, React). AI reads native code and updates the spec. The spec is the sync layer between platforms.
+
+## Spec location
+- Spec root: `openuispec/`
+- Manifest: `openuispec/openuispec.yaml` — always read this first.
+- Tokens: `openuispec/tokens/`
+- Screens: `openuispec/screens/`
+- Flows: `openuispec/flows/`
+- Contracts: `openuispec/contracts/`
+- Platform: `openuispec/platform/`
+- Locales: `openuispec/locales/`
+
+**Note:** These are the default paths. Actual paths are in `includes:` in `openuispec.yaml` and may use relative paths. Always read `openuispec.yaml` to find the real directories.
+
+## If spec directories are empty (first-time setup)
+This means the project has existing UI code but hasn't been specced yet. Your job:
+
+1. **Read the spec first** — find and read `spec/openuispec-v0.1.md` from the installed package.
+2. **Find existing screens** — scan the codebase for UI screen files.
+3. **Create stubs** — for each screen, create `openuispec/screens/<name>.yaml` with:
+   ```yaml
+   screen_name:
+     semantic: "Brief description of what this screen does"
+     status: stub
+     layout:
+       type: scroll_vertical
+   ```
+4. **Extract tokens** — scan for colors, fonts, spacing and create files in `openuispec/tokens/`.
+5. **Update the manifest** — fill in `data_model` and `api.endpoints` in `openuispec/openuispec.yaml`.
+
+## OpenUISpec Source Of Truth
+
+OpenUISpec spec files are the primary source of truth for UI behavior across platforms.
+
+### Start from spec when:
+- the request changes screen structure
+- the request changes navigation
+- the request changes fields, actions, validation, or data binding
+- the request changes tokens, variants, contracts, flows, or localization
+- the request affects more than one platform
+- the request is phrased in product/UI terms rather than platform-code terms
+
+Spec-first workflow:
+1. Read `openuispec/openuispec.yaml` and the relevant spec files first.
+2. Update the spec first.
+3. Update the affected generated/native UI code to match the spec.
+4. Run `openuispec validate`.
+5. Run `openuispec validate semantic`.
+6. Run `openuispec drift --target <target> --explain` to inspect semantic changes since that target's baseline.
+7. Run `openuispec prepare --target <target>` to build the AI/developer work bundle for that target.
+8. Verify the affected UI targets build/run if possible.
+9. Only then run `openuispec drift --snapshot --target <target>` for affected targets, after that target output directory exists.
+10. Run `openuispec drift --target <target> --explain` again to confirm no spec changes remain for that target.
+11. Use `openuispec status` to see which other targets are still behind the updated spec.
+
+### Start from platform code when:
+- the change is platform-specific polish
+- the change is a local bug fix that does not alter shared semantic behavior
+- the request explicitly asks for an iOS-only, Android-only, or web-only adjustment
+
+Platform-first workflow:
+1. Update native/platform code.
+2. If the change affects shared semantics, sync the spec afterward.
+3. If the change is intentionally platform-specific, document it in `platform/*.yaml` when appropriate.
+
+### Never do this:
+- Do not snapshot drift immediately after changing spec unless the UI code has also been updated.
+- Do not treat `openuispec drift` as proof that generated UI matches the spec.
+- Do not skip `--explain` / `prepare` when another platform needs to catch up with shared spec changes.
+- Do not modify generated UI without checking whether the spec must change first.
+
+## CLI commands
+- `openuispec init` — scaffold a new spec project
+- `openuispec validate [group...]` — validate spec files against schemas
+- `openuispec validate semantic` — run semantic cross-reference linting
+- `openuispec drift --target <t>` — check for spec drift
+- `openuispec drift --target <t> --explain` — explain semantic spec drift since the target baseline
+- `openuispec drift --snapshot --target <t>` — snapshot current state after the target output exists
+- `openuispec prepare --target <t>` — build an AI-ready target update bundle
+- `openuispec status` — show cross-target baseline/drift status
+- `openuispec update-rules` — update AI rules to match installed package version
+- `openuispec drift --all` — include stubs in drift check
+<!-- openuispec-rules-end -->

package/examples/taskflow/CLAUDE.md

@@ -0,0 +1,112 @@
+<!-- openuispec-rules-start -->
+<!-- openuispec-rules-version: 0.1.28 -->
+# OpenUISpec — AI Assistant Rules
+# ================================
+# This project uses OpenUISpec to define UI as a semantic spec.
+# Spec files are the single source of truth for all UI across platforms.
+# Targets: "ios", "android", "web"
+
+## IMPORTANT — Read the specification before working with spec files
+
+The spec format, file schemas, and generation rules are defined in the installed `openuispec` package.
+You MUST read the reference files listed below before creating, editing, or generating from any spec file.
+Do NOT guess the file format — skipping this step will produce invalid YAML that fails validation.
+
+**Find the package in this order:**
+1. `node_modules/openuispec/` (project dependency)
+2. Run `npm root -g` → `<prefix>/openuispec/` (global install)
+3. Online: `https://openuispec.rsteam.uz/llms-full.txt` (if not installed)
+
+**Reference files inside the package (read in this order):**
+1. `README.md` — schema tables, file format reference, root wrapper keys
+2. `spec/openuispec-v0.1.md` — full specification (contracts, layout, expressions, adaptive, etc.)
+3. `examples/taskflow/openuispec/` — complete working example with all file types
+4. `schema/` — JSON Schemas for every file type
+
+These files are updated with each package version. Always read from the installed package,
+not from cached or memorized content, to ensure you use the latest spec.
+
+## What is OpenUISpec
+OpenUISpec is a YAML-based spec format that describes an app's UI semantically — tokens, screens, flows, and platform overrides. AI reads the spec and generates native code (SwiftUI, Compose, React). AI reads native code and updates the spec. The spec is the sync layer between platforms.
+
+## Spec location
+- Spec root: `openuispec/`
+- Manifest: `openuispec/openuispec.yaml` — always read this first.
+- Tokens: `openuispec/tokens/`
+- Screens: `openuispec/screens/`
+- Flows: `openuispec/flows/`
+- Contracts: `openuispec/contracts/`
+- Platform: `openuispec/platform/`
+- Locales: `openuispec/locales/`
+
+**Note:** These are the default paths. Actual paths are in `includes:` in `openuispec.yaml` and may use relative paths. Always read `openuispec.yaml` to find the real directories.
+
+## If spec directories are empty (first-time setup)
+This means the project has existing UI code but hasn't been specced yet. Your job:
+
+1. **Read the spec first** — find and read `spec/openuispec-v0.1.md` from the installed package.
+2. **Find existing screens** — scan the codebase for UI screen files.
+3. **Create stubs** — for each screen, create `openuispec/screens/<name>.yaml` with:
+   ```yaml
+   screen_name:
+     semantic: "Brief description of what this screen does"
+     status: stub
+     layout:
+       type: scroll_vertical
+   ```
+4. **Extract tokens** — scan for colors, fonts, spacing and create files in `openuispec/tokens/`.
+5. **Update the manifest** — fill in `data_model` and `api.endpoints` in `openuispec/openuispec.yaml`.
+
+## OpenUISpec Source Of Truth
+
+OpenUISpec spec files are the primary source of truth for UI behavior across platforms.
+
+### Start from spec when:
+- the request changes screen structure
+- the request changes navigation
+- the request changes fields, actions, validation, or data binding
+- the request changes tokens, variants, contracts, flows, or localization
+- the request affects more than one platform
+- the request is phrased in product/UI terms rather than platform-code terms
+
+Spec-first workflow:
+1. Read `openuispec/openuispec.yaml` and the relevant spec files first.
+2. Update the spec first.
+3. Update the affected generated/native UI code to match the spec.
+4. Run `openuispec validate`.
+5. Run `openuispec validate semantic`.
+6. Run `openuispec drift --target <target> --explain` to inspect semantic changes since that target's baseline.
+7. Run `openuispec prepare --target <target>` to build the AI/developer work bundle for that target.
+8. Verify the affected UI targets build/run if possible.
+9. Only then run `openuispec drift --snapshot --target <target>` for affected targets, after that target output directory exists.
+10. Run `openuispec drift --target <target> --explain` again to confirm no spec changes remain for that target.
+11. Use `openuispec status` to see which other targets are still behind the updated spec.
+
+### Start from platform code when:
+- the change is platform-specific polish
+- the change is a local bug fix that does not alter shared semantic behavior
+- the request explicitly asks for an iOS-only, Android-only, or web-only adjustment
+
+Platform-first workflow:
+1. Update native/platform code.
+2. If the change affects shared semantics, sync the spec afterward.
+3. If the change is intentionally platform-specific, document it in `platform/*.yaml` when appropriate.
+
+### Never do this:
+- Do not snapshot drift immediately after changing spec unless the UI code has also been updated.
+- Do not treat `openuispec drift` as proof that generated UI matches the spec.
+- Do not skip `--explain` / `prepare` when another platform needs to catch up with shared spec changes.
+- Do not modify generated UI without checking whether the spec must change first.
+
+## CLI commands
+- `openuispec init` — scaffold a new spec project
+- `openuispec validate [group...]` — validate spec files against schemas
+- `openuispec validate semantic` — run semantic cross-reference linting
+- `openuispec drift --target <t>` — check for spec drift
+- `openuispec drift --target <t> --explain` — explain semantic spec drift since the target baseline
+- `openuispec drift --snapshot --target <t>` — snapshot current state after the target output exists
+- `openuispec prepare --target <t>` — build an AI-ready target update bundle
+- `openuispec status` — show cross-target baseline/drift status
+- `openuispec update-rules` — update AI rules to match installed package version
+- `openuispec drift --all` — include stubs in drift check
+<!-- openuispec-rules-end -->

package/examples/taskflow/generated/android/TaskFlow/README.md

@@ -0,0 +1,43 @@
+# TaskFlow Android Target
+
+This Android target was generated directly from the local `openuispec/` TaskFlow specification, without copying another sample project's output.
+
+## What is included
+
+- A lean Jetpack Compose app scaffold under `app/`
+- Adaptive navigation using spec breakpoints:
+  - `compact`: bottom navigation
+  - `regular` and `expanded`: navigation rail
+- Spec-derived screens:
+  - Home
+  - Task detail
+  - Projects
+  - Project detail
+  - Calendar stub
+  - Settings
+  - Profile edit
+- Spec-derived flows:
+  - Create task
+  - Edit task
+  - Assign task
+  - New project
+- Local sample data matching the spec's data model
+- English string resources derived from `openuispec/locales/en.json`
+- Theme colors based on `openuispec/tokens/color.yaml` and `themes.yaml`
+
+## Project notes
+
+- This is intentionally lean. It favors clear generated structure over a fully productionized architecture.
+- The app uses local Compose state instead of wiring real API clients.
+- The media-player custom contract is acknowledged in the spec but not implemented here because no screen in this minimal target renders a concrete media attachment asset.
+- No Gradle wrapper is checked in. Use a local Gradle installation or import the project into Android Studio and let it create the wrapper if needed.
+
+## Suggested verification
+
+From this directory:
+
+```bash
+gradle :app:assembleDebug
+```
+
+Or open `generated/android/TaskFlow` in Android Studio and run the app on an emulator.

package/examples/taskflow/generated/android/TaskFlow/app/build.gradle.kts

@@ -0,0 +1,76 @@
+plugins {
+    id("com.android.application")
+    id("org.jetbrains.kotlin.android")
+    id("org.jetbrains.kotlin.plugin.compose")
+}
+
+import org.jetbrains.kotlin.gradle.dsl.JvmTarget
+
+android {
+    namespace = "uz.rsteam.taskflow"
+    compileSdk = 35
+
+    defaultConfig {
+        applicationId = "uz.rsteam.taskflow"
+        minSdk = 26
+        targetSdk = 35
+        versionCode = 1
+        versionName = "1.0.0"
+
+        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
+        vectorDrawables {
+            useSupportLibrary = true
+        }
+    }
+
+    buildTypes {
+        release {
+            isMinifyEnabled = false
+            proguardFiles(
+                getDefaultProguardFile("proguard-android-optimize.txt"),
+                "proguard-rules.pro"
+            )
+        }
+    }
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+
+    buildFeatures {
+        compose = true
+    }
+
+    packaging {
+        resources {
+            excludes += "/META-INF/{AL2.0,LGPL2.1}"
+        }
+    }
+}
+
+kotlin {
+    compilerOptions {
+        jvmTarget.set(JvmTarget.JVM_17)
+    }
+}
+
+dependencies {
+    val composeBom = platform("androidx.compose:compose-bom:2024.10.01")
+
+    implementation(composeBom)
+    androidTestImplementation(composeBom)
+
+    implementation("androidx.core:core-ktx:1.15.0")
+    implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.8.7")
+    implementation("androidx.activity:activity-compose:1.9.3")
+    implementation("androidx.compose.ui:ui")
+    implementation("androidx.compose.ui:ui-graphics")
+    implementation("androidx.compose.ui:ui-tooling-preview")
+    implementation("androidx.compose.material3:material3")
+    implementation("androidx.compose.material:material-icons-extended")
+    implementation("androidx.compose.foundation:foundation")
+
+    debugImplementation("androidx.compose.ui:ui-tooling")
+    debugImplementation("androidx.compose.ui:ui-test-manifest")
+}

package/examples/taskflow/generated/android/TaskFlow/app/proguard-rules.pro

@@ -0,0 +1 @@
+# Generated sample app. No custom ProGuard rules required.

package/examples/taskflow/generated/android/TaskFlow/app/src/main/AndroidManifest.xml

@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <application
+        android:allowBackup="true"
+        android:label="@string/app_name"
+        android:supportsRtl="true"
+        android:theme="@style/Theme.TaskFlow">
+        <activity
+            android:name=".MainActivity"
+            android:exported="true"
+            android:theme="@style/Theme.TaskFlow">
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+
+                <category android:name="android.intent.category.LAUNCHER" />
+            </intent-filter>
+        </activity>
+    </application>
+
+</manifest>

package/examples/taskflow/generated/android/TaskFlow/app/src/main/java/uz/rsteam/taskflow/MainActivity.kt

@@ -0,0 +1,19 @@
+package uz.rsteam.taskflow
+
+import android.os.Bundle
+import androidx.activity.ComponentActivity
+import androidx.activity.compose.setContent
+import androidx.activity.enableEdgeToEdge
+import uz.rsteam.taskflow.ui.theme.TaskFlowTheme
+
+class MainActivity : ComponentActivity() {
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        enableEdgeToEdge()
+        setContent {
+            TaskFlowTheme {
+                TaskFlowApp()
+            }
+        }
+    }
+}