openuispec 0.1.44 → 0.1.45

package/README.md

@@ -52,25 +52,91 @@ cd your-project
 openuispec init
 ```
 
-This scaffolds a spec directory, starter tokens, adds rules to `CLAUDE.md` / `AGENTS.md`, and configures the MCP server so AI assistants track spec changes automatically.
-Use `openuispec init --no-configure-targets` if you want to scaffold first and choose target stacks later.
+This scaffolds a spec directory, starter tokens, and **configures the MCP server** for your AI coding agent (Claude Code, VS Code/Copilot, Codex). Use `openuispec init --no-configure-targets` to scaffold first and choose target stacks later.
 
-Then hand your spec to any AI code generator:
+## AI integration (MCP)
 
-> Generate a native iOS app from this OpenUISpec. Follow all contract state machines, apply token ranges for iOS, and implement navigation flows as defined. Use `platform/ios.yaml` for SwiftUI-specific overrides.
+OpenUISpec is designed to be used by AI coding agents. The package includes an **MCP server** that exposes tools AI assistants call automatically during UI work — no manual prompting needed.
+
+### How it works
+
+```
+openuispec init → configures MCP for your agent → AI calls tools automatically
+```
+
+When you ask your AI to "add a settings page" or "update the home feed," the MCP server:
+
+1. **Schema reference** — `openuispec_spec_types` and `openuispec_spec_schema` give the AI the exact format for any spec file it needs to create or edit
+2. **Before generation** — `openuispec_prepare` gives the AI your spec context, platform config, and constraints
+3. **During generation** — `openuispec_read_specs` feeds the AI the actual spec file contents as the authoritative source
+4. **After generation** — `openuispec_check` returns a concrete audit checklist derived from your spec (every contract `must_handle` item, every screen section, every locale key) and the AI verifies its code matches
+
+This replaces the old approach of writing instructions in CLAUDE.md and hoping the AI follows them. MCP tools are called reliably because they're part of the AI's tool-calling loop, not a text instruction it can skip.
+
+### Setup
+
+`openuispec init` and `openuispec update-rules` automatically configure MCP for all supported agents:
+
+| Agent | Config file | Created automatically |
+|-------|------------|----------------------|
+| **Claude Code** | `.mcp.json` | Always |
+| **Codex** | `.codex/config.toml` | Always |
+| **VS Code / Copilot** | `.vscode/mcp.json` | If `.vscode/` exists |
+
+Manual setup (if needed):
+
+**Claude Code** (`.mcp.json`), **VS Code / Copilot** (`.vscode/mcp.json`):
+```json
+{
+  "mcpServers": {
+    "openuispec": {
+      "command": "openuispec",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+**Codex** (`.codex/config.toml`):
+```toml
+[mcp_servers.openuispec]
+command = "openuispec"
+args = ["mcp"]
+```
+
+Or run directly: `openuispec mcp`
+
+### Tools
 
-Before platform code generation, the AI should refresh its understanding of the current target toolchain and platform conventions instead of relying on stale memory. This matters most for project formats, resource wiring, navigation APIs, packaging rules, and other implementation details that change across toolchain versions.
+| Tool | When | What it does |
+|------|------|-------------|
+| `openuispec_spec_types` | Before creating spec files | Lists all available spec types with descriptions — discover what kinds of spec files exist |
+| `openuispec_spec_schema` | Before creating/editing spec files | Returns the full JSON schema for a specific spec type — exact structure, required fields, allowed values |
+| `openuispec_prepare` | Before UI code generation | Returns spec context, platform config, generation constraints |
+| `openuispec_read_specs` | Before and after generation | Loads spec file contents — the authoritative source for tokens, screens, contracts |
+| `openuispec_check` | After generation | Schema validation + concrete audit checklist from your spec |
+| `openuispec_validate` | After spec edits | Schema-only validation, optionally filtered by group |
+| `openuispec_drift` | Before updates | Detect spec drift since last snapshot, with semantic explanation |
+| `openuispec_status` | Anytime | Cross-target summary: baselines, drift, next steps |
+
+The server includes **protocol-level instructions** that trigger on UI-related requests independently of CLAUDE.md rules — so even if CLAUDE.md is buried under other project rules, the MCP enforcement still works.
+
+## Using without MCP
+
+You can also use OpenUISpec with any AI by providing context manually:
+
+> Generate a native iOS app from this OpenUISpec. Follow all contract state machines, apply token ranges for iOS, and implement navigation flows as defined. Use `platform/ios.yaml` for SwiftUI-specific overrides.
 
 For platform generation, treat these as hard output constraints:
 
-- Generate a valid native project or target that actually bundles every required runtime resource. Converting spec inputs into platform-native resource files is insufficient unless those files are attached to the final app target and resolve at runtime.
-- Do not ship unresolved resource identifiers in the UI. Raw localization keys, token references, asset names, or placeholder paths mean the generated output is incomplete.
-- Do not use a container or navigation primitive without defining its behavior for every supported size class and form factor. Master-detail patterns must provide a non-empty compact fallback instead of assuming large-screen behavior.
+- Generate a valid native project that bundles every required runtime resource
+- Do not ship unresolved resource identifiers (raw locale keys, token refs, placeholder paths)
+- Define behavior for every supported size class and form factor
 
-See the examples for concrete reference projects:
+See the examples for reference:
 
-- [TaskFlow](./examples/taskflow/openuispec/) for a compact reference spec covering all 7 contract families, with generated iOS, Android, and web targets under `examples/taskflow/generated/`
-- [Todo Orbit](./examples/todo-orbit/openuispec/) for a bilingual task app with generated iOS, Android, and web targets under `examples/todo-orbit/generated/`
+- [TaskFlow](./examples/taskflow/openuispec/) — compact reference spec covering all 7 contract families
+- [Todo Orbit](./examples/todo-orbit/openuispec/) — bilingual task app with localization, custom contracts, and generated native/web targets
 
 ## Repository structure
 
@@ -117,7 +183,7 @@ openuispec/
 │   ├── index.ts                        # Entry point
 │   └── init.ts                         # Project scaffolding + AI rules
 ├── mcp-server/                          # MCP server (openuispec-mcp)
-│   └── index.ts                        # Stdio transport, 5 tools
+│   └── index.ts                        # Stdio transport, 8 tools
 ├── check/                               # Composite validation command
 │   └── index.ts                        # Schema + semantic + readiness
 ├── drift/                               # Drift detection (spec change tracking)
@@ -245,49 +311,6 @@ to see which targets are already up to date and which ones still need to catch u
 
 `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.
 
-## MCP server
-
-OpenUISpec includes an MCP (Model Context Protocol) server that exposes CLI commands as tools for AI assistants. This is the recommended way to integrate with Claude Code and other MCP-compatible clients — tools are called more reliably than CLAUDE.md instructions.
-
-### Setup
-
-`openuispec init` automatically configures the MCP server for your coding agent. For existing projects, run `openuispec update-rules` or add the config manually:
-
-**Claude Code** (`.mcp.json`), **VS Code / Copilot** (`.vscode/mcp.json`):
-```json
-{
-  "mcpServers": {
-    "openuispec": {
-      "command": "openuispec",
-      "args": ["mcp"]
-    }
-  }
-}
-```
-
-**Codex** (`.codex/config.toml`):
-```toml
-[mcp_servers.openuispec]
-command = "openuispec"
-args = ["mcp"]
-```
-
-Or run directly: `openuispec mcp`
-
-Set `OPENUISPEC_PROJECT_DIR` to override the working directory.
-
-### Tools
-
-| Tool | Description |
-|------|-------------|
-| `openuispec_prepare` | Build AI-ready work bundle for a target. **Call before any UI code generation.** |
-| `openuispec_check` | Schema validation + semantic lint + prepare readiness. Call after spec edits. |
-| `openuispec_status` | Cross-target summary: baselines, drift, next steps. |
-| `openuispec_validate` | Schema-only validation, optionally filtered by group. |
-| `openuispec_drift` | Detect spec drift since last snapshot, with optional semantic explanation. |
-
-All tools return structured JSON. The server includes protocol-level instructions that tell AI assistants to call `openuispec_prepare` before any UI work — this works independently of CLAUDE.md rules.
-
 ## Spec at a glance
 
 | Section | What it defines |

package/cli/init.ts

@@ -268,11 +268,14 @@ When the openuispec MCP server is configured, AI assistants should use these too
 
 | Tool | When to use |
 |------|-------------|
+| \`openuispec_spec_types\` | Discover available spec types and their descriptions. |
+| \`openuispec_spec_schema\` | Get the full JSON schema for a specific spec type — exact structure, required fields, allowed values. |
 | \`openuispec_prepare\` | **Before any UI code generation.** Returns spec context, platform config, and constraints. |
+| \`openuispec_read_specs\` | Load spec file contents — the authoritative source for tokens, screens, contracts. |
 | \`openuispec_check\` | After editing spec files. Validates schema + semantics + readiness. |
-| \`openuispec_status\` | To understand cross-target state (baselines, drift, next steps). |
 | \`openuispec_validate\` | Schema-only validation, optionally by group. |
 | \`openuispec_drift\` | Detect spec changes since last snapshot. |
+| \`openuispec_status\` | To understand cross-target state (baselines, drift, next steps). |
 
 ## CLI commands
 
@@ -337,6 +340,11 @@ Call these MCP tools directly. They return structured JSON with everything you n
    - Navigation targets match flow definitions
 8. Report any real gaps found and fix them before finishing.
 
+**Creating new spec files:**
+- Call \`openuispec_spec_types\` to discover available spec types.
+- Call \`openuispec_spec_schema\` with the specific type to get the full JSON schema.
+- Write the spec file following the schema exactly.
+
 **Other tools:**
 - \`openuispec_status\` — cross-target summary, good starting point
 - \`openuispec_drift\` with \`explain: true\` — property-level spec changes

package/mcp-server/index.ts

@@ -91,6 +91,12 @@ POST-GENERATION (do this EVERY TIME after writing UI code):
    - Navigation targets match flow definitions
    Report any real gaps found and fix them before finishing.
 
+CREATING NEW SPEC FILES:
+When you need to create or edit spec files and are unsure of the format:
+1. Call openuispec_spec_types to discover available spec types.
+2. Call openuispec_spec_schema with the specific type to get the full JSON schema.
+3. Write the spec file following the schema exactly.
+
 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.`,
   }
@@ -363,6 +369,69 @@ server.registerTool(
   }
 );
 
+// ── schema type catalog ─────────────────────────────────────────
+
+const SCHEMA_CATALOG: Record<string, { file: string; title: string; description: string }> = {
+  manifest:         { file: "openuispec.schema.json",            title: "Root Manifest",    description: "Root manifest (openuispec.yaml): project info, includes, generation targets, data model, API endpoints, formatters, mappers" },
+  screen:           { file: "screen.schema.json",                title: "Screen",           description: "Screen composition: layout, sections, navigation, surfaces, data/state bindings, adaptive breakpoints" },
+  flow:             { file: "flow.schema.json",                  title: "Flow",             description: "Navigation flow definitions: steps, transitions, guards, and entry points" },
+  platform:         { file: "platform.schema.json",              title: "Platform",         description: "Platform-specific generation config: architecture, naming, CSS framework, component mapping" },
+  contract:         { file: "contract.schema.json",              title: "Contract",         description: "Built-in UI contract definitions: variants, props, must_handle states, generation hints" },
+  "custom-contract":{ file: "custom-contract.schema.json",       title: "Custom Contract",  description: "User-defined UI contract definitions (x_ prefixed)" },
+  locale:           { file: "locale.schema.json",                title: "Locale",           description: "Locale translation files: flat key-value string maps" },
+  "tokens/color":       { file: "tokens/color.schema.json",       title: "Color Tokens",       description: "Color tokens: brand, surface, text, semantic, border groups with HSL ranges and contrast" },
+  "tokens/typography":  { file: "tokens/typography.schema.json",   title: "Typography Tokens",  description: "Typography tokens: font families, sizes, weights, line heights, letter spacing" },
+  "tokens/spacing":     { file: "tokens/spacing.schema.json",     title: "Spacing Tokens",     description: "Spacing tokens: named spacing scale values" },
+  "tokens/elevation":   { file: "tokens/elevation.schema.json",   title: "Elevation Tokens",   description: "Elevation tokens: shadow definitions per level" },
+  "tokens/motion":      { file: "tokens/motion.schema.json",      title: "Motion Tokens",      description: "Motion tokens: animation duration and easing curves" },
+  "tokens/layout":      { file: "tokens/layout.schema.json",      title: "Layout Tokens",      description: "Layout tokens: radii, breakpoints, max widths, grid columns" },
+  "tokens/themes":      { file: "tokens/themes.schema.json",      title: "Theme Tokens",       description: "Theme definitions: token overrides per theme (e.g. dark mode)" },
+  "tokens/icons":       { file: "tokens/icons.schema.json",       title: "Icon Tokens",        description: "Icon tokens: icon set, size scale, default size" },
+};
+
+// ── tool: openuispec_spec_types ──────────────────────────────────
+
+server.registerTool(
+  "openuispec_spec_types",
+  {
+    description: "List all available OpenUISpec spec types with brief descriptions. Use this to discover what kinds of spec files can be created and what schema format each one follows. Call openuispec_spec_schema with a specific type to get the full JSON schema.",
+  },
+  async () => {
+    const types = Object.entries(SCHEMA_CATALOG).map(([type, info]) => ({
+      type,
+      title: info.title,
+      description: info.description,
+    }));
+    return toolResult(types);
+  }
+);
+
+// ── tool: openuispec_spec_schema ─────────────────────────────────
+
+server.registerTool(
+  "openuispec_spec_schema",
+  {
+    description: "Get the full JSON schema for a specific OpenUISpec spec type. Returns the complete schema definition so you know the exact format when creating or editing spec files. Call openuispec_spec_types first to see available types.",
+    inputSchema: {
+      type: z.string().describe("Spec type to get schema for (e.g. 'screen', 'tokens/color', 'contract'). Use openuispec_spec_types to list all available types."),
+    },
+  },
+  async ({ type }) => {
+    const entry = SCHEMA_CATALOG[type];
+    if (!entry) {
+      return toolError(`Unknown spec type "${type}". Call openuispec_spec_types to see available types.`);
+    }
+    try {
+      const __dirname = dirname(fileURLToPath(import.meta.url));
+      const schemaPath = join(__dirname, "..", "schema", entry.file);
+      const schema = JSON.parse(readFileSync(schemaPath, "utf-8"));
+      return toolResult({ type, title: entry.title, schema });
+    } catch (err) {
+      return toolError(err);
+    }
+  }
+);
+
 // ── start server ─────────────────────────────────────────────────────
 
 export async function startMcpServer() {

package/package.json

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