@givolt/i3-composer-agent 2.2.3 → 2.3.1

package/scripts/ui-prototype-test.js

@@ -0,0 +1,114 @@
+'use strict';
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const installationFile = path.join(__dirname, 'lib/installation.js');
+const skillsDirectory = fs.existsSync(installationFile) ? require(installationFile).loadInstallation().skillsDirectory : path.resolve(__dirname, '../skills');
+const lib = require(path.join(skillsDirectory, 'i3-ui-prototype/scripts/prototype-lib.cjs'));
+
+function fixture(t, template = 'classic-admin') {
+  const project = fs.mkdtempSync(path.join(os.tmpdir(), 'i3-ui-prototype-'));
+  t.after(() => fs.rmSync(project, { recursive: true, force: true }));
+  return lib.initPrototype({ project, id: 'approval-demo', template, expertMode: 'template' }).directory;
+}
+function json(dir, file) { return JSON.parse(fs.readFileSync(path.join(dir, file), 'utf8')); }
+function write(dir, file, value) { fs.mkdirSync(path.dirname(path.join(dir, file)), { recursive: true }); fs.writeFileSync(path.join(dir, file), JSON.stringify(value, null, 2)); }
+function browserEvidence(dir) {
+  const revision = lib.contentManifest(dir);
+  fs.mkdirSync(path.join(dir, 'qa/screenshots'), { recursive: true });
+  fs.writeFileSync(path.join(dir, 'qa/screenshots/test.png'), Buffer.from('test evidence; not a real browser image'));
+  write(dir, 'qa/browser.json', { schemaVersion: 1, revision: revision.revision, digest: revision.digest, status: 'passed', source: 'isolated-test-fixture', screenshots: ['qa/screenshots/test.png'], journeys: [{ id: 'approval-flow', status: 'passed' }], consoleErrors: [], viewports: [1440, 768] });
+}
+test('default professional mode stops on missing dependency without writing a prototype', t => {
+  const project = fs.mkdtempSync(path.join(os.tmpdir(), 'i3-ui-missing-'));
+  t.after(() => fs.rmSync(project, { recursive: true, force: true }));
+  const result = lib.initPrototype({ project, id: 'example', providerRoots: [], discover: false });
+  assert.equal(result.status, 'needs-design-provider');
+  assert.deepEqual(result.choices.map(x => x.id), ['install', 'template', 'prepare']);
+  assert.equal(fs.existsSync(path.join(project, 'prototypes')), false);
+});
+test('template mode has an interactive runnable app and no expert usage claim', t => {
+  const dir = fixture(t);
+  const metadata = json(dir, 'prototype.json');
+  assert.equal(metadata.expertMode, 'template');
+  assert.equal(metadata.expert.status, 'skipped');
+  assert.equal(metadata.review.status, 'pending-review');
+  assert.equal(lib.checkPrototype(dir).status, 'passed');
+  assert.ok(fs.existsSync(path.join(dir, 'app/index.html')));
+  assert.throws(() => lib.initPrototype({ project: path.resolve(dir, '../..'), id: 'approval-demo', expertMode: 'template' }), /exists|已存在/);
+});
+test('all three legacy templates retain their distinct tokens and layouts', t => {
+  const values = lib.listTemplates({ legacy: true }).map(entry => {
+    const dir = fixture(t, entry.id);
+    assert.equal(lib.checkPrototype(dir).status, 'passed');
+    return { layout: json(dir, 'app/config.json').layout, primary: json(dir, 'design-system/tokens.json').semantic['color-primary'] };
+  });
+  assert.equal(values.length, 3);
+  assert.equal(new Set(values.map(v => v.layout)).size, 3);
+  assert.equal(new Set(values.map(v => v.primary)).size, 3);
+});
+test('baseline requires matching browser evidence and human confirmation, and is immutable', t => {
+  const dir = fixture(t);
+  const candidate = lib.contentManifest(dir);
+  assert.throws(() => lib.freezeBaseline(dir, { revision: candidate.revision, digest: candidate.digest, reviewer: 'Test reviewer', statement: 'Approved fixture', source: 'isolated-test' }), /browser|浏览器/);
+  browserEvidence(dir);
+  assert.throws(() => lib.freezeBaseline(dir, {}), /confirm|确认/);
+  const baseline = lib.freezeBaseline(dir, { revision: candidate.revision, digest: candidate.digest, reviewer: 'Test reviewer', statement: 'Approved fixture', source: 'isolated-test' });
+  assert.equal(baseline.digest, candidate.digest);
+  assert.throws(() => lib.freezeBaseline(dir, { revision: candidate.revision, digest: candidate.digest, reviewer: 'Test reviewer', statement: 'Approved fixture', source: 'isolated-test' }), /exists|已存在/);
+  const reviewFile = path.join(dir, 'baselines', candidate.revision, 'review.json');
+  const originalReview = fs.readFileSync(reviewFile);
+  const alteredReview = JSON.parse(originalReview); alteredReview.reviewer = 'Different reviewer';
+  fs.writeFileSync(reviewFile, JSON.stringify(alteredReview));
+  assert.equal(lib.compareBaseline(dir).status, 'corrupt-baseline');
+  fs.writeFileSync(reviewFile, originalReview);
+  fs.appendFileSync(path.join(dir, 'baselines', candidate.revision, 'app/styles.css'), '\n/* altered snapshot */');
+  assert.equal(lib.compareBaseline(dir).status, 'corrupt-baseline');
+});
+test('changed content invalidates old verification and cannot reuse old confirmation', t => {
+  const dir = fixture(t);
+  browserEvidence(dir);
+  const old = lib.contentManifest(dir);
+  fs.appendFileSync(path.join(dir, 'app/styles.css'), '\n/* modified */');
+  assert.throws(() => lib.freezeBaseline(dir, { revision: old.revision, digest: old.digest, reviewer: 'Test', statement: 'Approved', source: 'isolated-test' }), /matching|一致|changed|变化/);
+});
+test('iteration preserves baseline and identifies changes to design constraints', t => {
+  const dir = fixture(t);
+  browserEvidence(dir);
+  const current = lib.contentManifest(dir);
+  lib.freezeBaseline(dir, { revision: current.revision, digest: current.digest, reviewer: 'Test', statement: 'Approved fixture', source: 'isolated-test' });
+  lib.revisePrototype(dir, 'r002');
+  const tokens = json(dir, 'design-system/tokens.json');
+  tokens.semantic['color-primary'] = '#222222';
+  write(dir, 'design-system/tokens.json', tokens);
+  const result = lib.compareBaseline(dir);
+  assert.equal(result.status, 'changed');
+  assert.ok(result.protectedChanges.includes('design-system/tokens.json'));
+  assert.equal(json(dir, 'baseline.json').revision, 'r001');
+  assert.equal(json(dir, 'prototype.json').review.status, 'pending-review');
+});
+test('design token changes must be reflected in the actual runtime stylesheet', t => {
+  const dir = fixture(t);
+  const tokens = json(dir, 'design-system/tokens.json');
+  tokens.semantic['color-primary'] = '#222222';
+  write(dir, 'design-system/tokens.json', tokens);
+  assert.equal(lib.checkPrototype(dir).status, 'failed');
+});
+test('a manually created candidate cannot pass with an uncomputed template digest', t => {
+  const dir = fixture(t);
+  const metadata = json(dir, 'prototype.json');
+  metadata.template.digest = 'manual-init-uncomputed';
+  write(dir, 'prototype.json', metadata);
+  assert.equal(lib.checkPrototype(dir).status, 'failed');
+});
+test('unsafe identifiers and symlinked output parents are rejected before writes', t => {
+  const project = fs.mkdtempSync(path.join(os.tmpdir(), 'i3-ui-path-'));
+  const elsewhere = fs.mkdtempSync(path.join(os.tmpdir(), 'i3-ui-elsewhere-'));
+  t.after(() => { fs.rmSync(project, { recursive: true, force: true }); fs.rmSync(elsewhere, { recursive: true, force: true }); });
+  assert.throws(() => lib.initPrototype({ project, id: '../escape', expertMode: 'template' }), /identifier|标识/);
+  fs.symlinkSync(elsewhere, path.join(project, 'prototypes'), 'dir');
+  assert.throws(() => lib.initPrototype({ project, id: 'safe', expertMode: 'template' }), /symlink|符号链接/);
+  assert.deepEqual(fs.readdirSync(elsewhere), []);
+});

package/scripts/validate-commands-test.js

@@ -214,3 +214,33 @@ test('the TOML directories are not put through the YAML rules', () => {
   assert.equal(result.status, 0, result.stdout);
   assert.doesNotMatch(result.stdout, /\.gemini.*unquoted value/);
 });
+
+
+test('nested metadata descriptions cannot hide command description drift', () => {
+  const root = makeSandbox();
+  writeClaudeCommand(root, 'review', 'metadata:\n  description: Review a change\ndescription: Inspect a change');
+  writeTomlCommand(root, path.join('.gemini', 'commands'), 'review', 'description = "Review a change"');
+  writeTomlCommand(root, 'commands', 'review', 'description = "Review a change"');
+  const result = run(root);
+  assert.equal(result.status, 1, result.stdout + result.stderr);
+  assert.match(result.stdout, /Inspect a change/);
+});
+
+test('matching top-level descriptions pass despite different nested metadata', () => {
+  const root = makeSandbox();
+  writeClaudeCommand(root, 'review', 'metadata:\n  description: Internal metadata\ndescription: Review a change');
+  writeTomlCommand(root, path.join('.gemini', 'commands'), 'review', 'description = "Review a change"');
+  writeTomlCommand(root, 'commands', 'review', 'description = "Review a change"');
+  const result = run(root);
+  assert.equal(result.status, 0, result.stdout + result.stderr);
+});
+
+test('a nested description does not supply a missing command description', () => {
+  const root = makeSandbox();
+  writeClaudeCommand(root, 'review', 'metadata:\n  description: Review a change');
+  writeTomlCommand(root, path.join('.gemini', 'commands'), 'review', 'description = "Review a change"');
+  writeTomlCommand(root, 'commands', 'review', 'description = "Review a change"');
+  const result = run(root);
+  assert.equal(result.status, 1, result.stdout + result.stderr);
+  assert.match(result.stdout, /missing or malformed description/);
+});

package/scripts/validate-commands.js

@@ -25,12 +25,11 @@ const fs   = require('fs');
 const path = require('path');
 
 // The same frontmatter-validity rules validate-skills applies to SKILL.md.
-// `descriptionFromMd` below splits each line on its first colon, exactly as the
-// skill reader used to, so a command whose frontmatter is not valid YAML passes
-// every check here — and Claude Code parses that frontmatter when the command is
-// loaded. The #494 thread verified all 25 SKILL.md files AND the command files by
-// hand; this makes the second half a check too.
-const { frontmatterYamlErrors } = require(path.join(__dirname, 'lib', 'skill-lint.js'));
+// Description extraction shares the top-level frontmatter reader with skills.
+// YAML validity is checked separately because Claude Code parses frontmatter
+// when the command is loaded. The #494 thread verified all 25 SKILL.md files
+// and the command files by hand; this makes the second half a check too.
+const { frontmatterYamlErrors, parseFrontmatter } = require(path.join(__dirname, 'lib', 'skill-lint.js'));
 
 // ─── Config ───────────────────────────────────────────────────────────────────
 
@@ -56,16 +55,7 @@ const NAME_MAP_REVERSE = Object.fromEntries(
 
 function descriptionFromMd(filePath) {
   const content = fs.readFileSync(filePath, 'utf8');
-  const match   = content.match(/^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*\r?\n/);
-  if (!match) return null;
-  for (const line of match[1].split(/\r?\n/)) {
-    const colonIdx = line.indexOf(':');
-    if (colonIdx === -1) continue;
-    if (line.slice(0, colonIdx).trim() === 'description') {
-      return line.slice(colonIdx + 1).trim().replace(/^['"]|['"]$/g, '');
-    }
-  }
-  return null;
+  return parseFrontmatter(content)?.description ?? null;
 }
 
 function descriptionFromToml(filePath) {

package/scripts/validate-reference-links-test.js

@@ -493,3 +493,21 @@ test('a missing file is reported once, not again for its anchor', () => {
   assert.match(result.stdout, /L1: references\/renamed\.md — resolves to skills\/hardening\/references\/renamed\.md, which does not exist/);
   assert.match(result.stdout, /1 skills checked — 1 error\(s\) — FAILED/);
 });
+
+
+test('heading slugs remain unique when a literal suffix collides with an allocated slug', () => {
+  const root = makeSandbox();
+  hardeningSkill(root, 'references/patterns.md#example-1-1');
+  // A hyphen in the literal heading makes its base slug collide with Example's suffix.
+  writeFile(root, 'skills/hardening/references/patterns.md', '## Example\n\n## Example\n\n## Example-1\n');
+  const result = run(root);
+  assert.equal(result.status, 0, result.stdout + result.stderr);
+});
+
+test('a duplicate skips a slug occupied by an earlier literal heading', () => {
+  const root = makeSandbox();
+  hardeningSkill(root, 'references/patterns.md#example-2');
+  writeFile(root, 'skills/hardening/references/patterns.md', '## Example\n\n## Example-1\n\n## Example\n');
+  const result = run(root);
+  assert.equal(result.status, 0, result.stdout + result.stderr);
+});

package/scripts/validate-reference-links.js

@@ -77,8 +77,10 @@ function headingAnchors(file) {
     const match = line.match(/^ {0,3}#{1,6}[ \t]+(.*?)(?:[ \t]+#+)?[ \t]*$/);
     if (!match) continue;
     const slug = slugify(match[1]);
-    const count = seen.get(slug) || 0;
-    anchors.add(count === 0 ? slug : `${slug}-${count}`);
+    let count = seen.get(slug) || 0;
+    let anchor = count === 0 ? slug : `${slug}-${count}`;
+    while (anchors.has(anchor)) anchor = `${slug}-${++count}`;
+    anchors.add(anchor);
     seen.set(slug, count + 1);
   }
   return anchors;

package/scripts/validate-skills.js

@@ -3,7 +3,8 @@
  * validate-skills.js
  *
  * CLI that validates every skill in skills/ against the rules in
- * docs/skill-anatomy.md. The rules themselves live in scripts/lib/skill-lint.js
+ * docs/skill-anatomy.md, and every persona in agents/ against the three rules
+ * in docs/agents.md. The rules themselves live in scripts/lib/skill-lint.js
  * (a single source of truth, importable and unit-testable); this file is a thin
  * wrapper that walks the skills directory, runs the linter, prints the report,
  * and sets the exit code.
@@ -16,9 +17,10 @@
 const fs   = require('fs');
 const path = require('path');
 
-const { lintSkill } = require('./lib/skill-lint');
+const { lintSkill, lintPersona } = require('./lib/skill-lint');
 
 const SKILLS_DIR = path.resolve(__dirname, '..', 'skills');
+const AGENTS_DIR = path.resolve(__dirname, '..', 'agents');
 
 // ─── Main ────────────────────────────────────────────────────────────────────
 
@@ -54,8 +56,29 @@ function main() {
     }
   }
 
+  // ── Personas ─────────────────────────────────────────────────────────────
+  // agents/<name>.md files are consumed as subagents and spawned by name from
+  // commands, so they get the same frontmatter contract plus a closing
+  // Composition section (docs/agents.md). An index file such as README.md is
+  // not a persona and is skipped.
+  const personaFiles = fs.existsSync(AGENTS_DIR)
+    ? fs.readdirSync(AGENTS_DIR).filter(f => f.endsWith('.md') && !/^readme\.md$/i.test(f)).sort()
+    : [];
+
+  if (personaFiles.length > 0) console.log('');
+  for (const fileName of personaFiles) {
+    const { errors } = lintPersona(fileName, AGENTS_DIR);
+    totalErrors += errors.length;
+    if (errors.length === 0) {
+      console.log(`  ✓  agents/${fileName}`);
+    } else {
+      console.log(`  ✗  agents/${fileName}`);
+      for (const msg of errors) console.log(`       ERROR: ${msg}`);
+    }
+  }
+
   const status = totalErrors > 0 ? 'FAILED' : totalWarnings > 0 ? 'PASSED WITH WARNINGS' : 'PASSED';
-  console.log(`\n${skillDirs.length} skills checked — ${totalErrors} error(s), ${totalWarnings} warning(s) — ${status}`);
+  console.log(`\n${skillDirs.length} skills and ${personaFiles.length} personas checked — ${totalErrors} error(s), ${totalWarnings} warning(s) — ${status}`);
 
   if (totalErrors > 0) process.exit(1);
 }

package/skills/i3-documentation-and-adrs/SKILL.md

@@ -268,6 +268,14 @@ Special consideration for AI agent context:
 - **ADRs** — Help agents understand why past decisions were made (prevents re-deciding)
 - **Inline gotchas** — Prevent agents from falling into known traps
 
+## Prose Review
+
+After checking the technical content, review the prose for the people who will use it. Clearer wording must not change the decision or its limits.
+
+1. Mark the details that must survive the edit: names, numbers and units, commands, paths, links, conditions, trade-offs, and uncertainty. Check them against the available code and decision context; flag anything you cannot substantiate.
+2. Replace stock introductions, promotional adjectives, and repeated summaries with the concrete information the reader needs. Do not replace an unsupported claim with an invented example or a stronger guarantee. Keep necessary technical repetition and the project's established terminology.
+3. Compare the edited document with the original and its sources. Restore any lost qualifier or caveat, verify command and code examples still work as documented, and explain any unresolved factual question rather than polishing it away.
+
 ## Common Rationalizations
 
 | Rationalization | Reality |
@@ -298,3 +306,4 @@ After documenting:
 - [ ] Known gotchas are documented inline where they matter
 - [ ] No commented-out code remains
 - [ ] Rules files (CLAUDE.md etc.) are current and accurate
+- [ ] Prose edits preserve source details, decision trade-offs, and qualifiers without adding unsupported guarantees

package/skills/i3-frontend-ui-engineering/SKILL.md

@@ -29,6 +29,10 @@ Build production-quality user interfaces that are accessible, performant, and vi
 - Adding interactivity or state management
 - Fixing visual or UX issues
 
+## Applicable Prototype Baselines
+
+When the project has `.i3-ui-prototypes.json`, read the prototype entry applicable to the UI module being changed, then its `baseline.json`, `design-system/MASTER.md`, tokens and page rules. Preserve approved design and interaction decisions; explain conflicts with new requirements instead of silently changing them. New pages reuse the selected template and component conventions. Changes to global tokens, navigation, component behavior or business states go through the `i3-ui-prototype` workflow and corresponding review. HTML review prototypes need explicit component mapping when implemented in another framework. Verify affected production pages in the browser; a prototype manifest check alone does not prove production fidelity. Projects without an applicable baseline retain this skill's existing workflow.
+
 ## Component Architecture
 
 ### File Structure
@@ -91,7 +95,7 @@ export function TaskItem({ task, onToggle, onDelete }: TaskItemProps) {
 ```tsx
 // Container: handles data
 export function TaskListContainer() {
-  const { tasks, isLoading, error } = useTasks();
+  const { tasks, isLoading, error, refetch } = useTasks();
 
   if (isLoading) return <TaskListSkeleton />;
   if (error) return <ErrorState message="Failed to load tasks" retry={refetch} />;

package/skills/i3-idea-refine/SKILL.md

@@ -17,8 +17,18 @@ Skill/Command/Agent 标识、文件路径、命令参数、代码/API 名称、
 
 # Idea Refine
 
+## Overview
+
 Refines raw ideas into sharp, actionable concepts worth building through structured divergent and convergent thinking.
 
+## When to Use
+
+- Use when an idea is still vague and needs shaping before it can become a plan
+- Use when you need to stress-test assumptions before committing to a direction
+- Use when you want to expand options before converging on one
+- Trigger phrases: "Help me refine this idea", "Ideate on [concept]", "Stress-test my plan"
+- Not for: a user who is unsure what they want at all (use `i3-interview-me`), or a direction already chosen that needs a spec (use `i3-spec-driven-development`)
+
 ## How It Works
 
 1.  **Understand & Expand (Divergent):** Restate the idea, ask sharpening questions, and generate variations.
@@ -34,11 +44,6 @@ This skill is primarily an interactive dialogue. Invoke it with an idea, and the
 bash skills/i3-idea-refine/scripts/idea-refine.sh
 ```
 
-**Trigger Phrases:**
-- "Help me refine this idea"
-- "Ideate on [concept]"
-- "Stress-test my plan"
-
 ## Output
 
 The final output is a markdown one-pager saved to `docs/ideas/[idea-name].md` (after user confirmation), containing:
@@ -167,6 +172,16 @@ Direct, thoughtful, slightly provocative. You're a sharp thinking partner, not a
 
 Read `examples.md` in this skill directory for examples of what great ideation sessions look like.
 
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| I'll generate 20+ ideas to cover all bases | 5-8 well-considered variations beat 20 shallow ones. Quality over quantity. |
+| The user just needs encouragement, not critique | A yes-machine produces weak ideas. Push back with specificity and kindness. |
+| Who this is for is obvious — no need to ask | Every good idea starts with a person and their problem. Skipping it means designing for nobody. |
+| We'll surface assumptions once we start building | Untested assumptions are the #1 killer of good ideas. Surface them before committing. |
+| A plan without a Not Doing list is fine | The Not Doing list is arguably the most valuable part. Make trade-offs explicit. |
+
 ## Red Flags
 
 - Generating 20+ shallow variations instead of 5-8 considered ones

package/skills/i3-incremental-implementation/SKILL.md

@@ -192,6 +192,10 @@ Each increment should be independently revertable:
 - Database migrations should have corresponding rollback migrations
 - Avoid deleting something in one commit and replacing it in the same commit — separate them
 
+## UI Slices with Prototype Baselines
+
+For a UI slice, check `.i3-ui-prototypes.json` for an applicable approved prototype. Read its design contract, business mapping and baseline before implementation, and include affected interaction/visual checks in the slice acceptance. Preserve prior snapshots; coordinate contract changes through `i3-ui-prototype`. Backend-only slices and projects without a baseline continue the existing increment workflow.
+
 ## Working with Agents
 
 When directing an agent to implement incrementally:

package/skills/i3-performance-optimization/SKILL.md

@@ -57,12 +57,12 @@ Two complementary approaches — use both:
 - **RUM (web-vitals library, CrUX):** Real user data in real conditions. Required to validate that a fix actually improved user experience.
 
 **Frontend:**
-```bash
-# Synthetic: Lighthouse in Chrome DevTools (or CI)
-# Chrome DevTools → Performance tab → Record
-# Chrome DevTools MCP → Performance trace
+```javascript
+// Synthetic: Lighthouse in Chrome DevTools (or CI)
+// Chrome DevTools → Performance tab → Record
+// Chrome DevTools MCP → Performance trace
 
-# RUM: Web Vitals library in code
+// RUM: Web Vitals library in code
 import { onLCP, onINP, onCLS } from 'web-vitals';
 
 onLCP(console.log);
@@ -71,12 +71,12 @@ onCLS(console.log);
 ```
 
 **Backend:**
-```bash
-# Response time logging
-# Application Performance Monitoring (APM)
-# Database query logging with timing
+```javascript
+// Response time logging
+// Application Performance Monitoring (APM)
+// Database query logging with timing
 
-# Simple timing
+// Simple timing
 console.time('db-query');
 const result = await db.query(...);
 console.timeEnd('db-query');

package/skills/i3-security-and-hardening/references/hardening-patterns.md

@@ -167,7 +167,7 @@ The `range() !== 'unicast'` check covers loopback, link-local `169.254.169.254`
 import { z } from 'zod';
 
 const CreateTaskSchema = z.object({
-  title: z.string().min(1).max(200).trim(),
+  title: z.string().max(200).trim().min(1),
   description: z.string().max(2000).optional(),
   priority: z.enum(['low', 'medium', 'high']).default('medium'),
   dueDate: z.string().datetime().optional(),

package/skills/i3-shipping-and-launch/SKILL.md

@@ -202,6 +202,12 @@ Client metrics:
 ```typescript
 // Set up error boundary with reporting
 class ErrorBoundary extends React.Component {
+  state = { hasError: false };
+
+  static getDerivedStateFromError() {
+    return { hasError: true };
+  }
+
   componentDidCatch(error: Error, info: React.ErrorInfo) {
     // Report to error tracking service
     reportError(error, {

package/skills/i3-test-driven-development/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: i3-test-driven-development
-description: "执行测试先行的红绿重构循环。适用于实现逻辑、修复缺陷、修改行为、复现报错及证明改动有效；缺陷修复使用先证明失败的 Prove-It 模式。"
-# i3-description-source: "description: Drives development with tests using the red-green-refactor loop. Use when implementing any logic, fixing any bug, or changing any behavior. Use when you need to prove that code works, when a bug report arrives, or when you're about to modify existing functionality."
+description: "执行测试先行的红绿重构循环。适用于实现逻辑、修复缺陷、修改行为、复现报错及证明改动有效；也用于为函数补测试、修复或修改直接粘贴的代码，即使请求未提到测试；缺陷修复使用先证明失败的 Prove-It 模式。"
+# i3-description-source: "description: Drives development with tests using the red-green-refactor loop. Use when implementing any logic, fixing any bug, or changing any behavior. Use when you need to prove that code works, when a bug report arrives, or when you're about to modify existing functionality. Use when asked to add tests to a function, fix a bug in it or change its behavior, even when the code is pasted inline and the request does not mention tests."
 ---
 
 <!-- i3:zh-CN:start -->
@@ -12,7 +12,7 @@ description: "执行测试先行的红绿重构循环。适用于实现逻辑、
 Skill/Command/Agent 标识、文件路径、命令参数、代码/API 名称、工具调用参数、JSON 键/类型/枚举、机器状态、测试期望字面量及引用原文保持原样。生成文档正文用中文，SPEC.md、tasks/plan.md、tasks/todo.md、CONSTRAINTS.md 等约定路径不改名。
 严重程度按原规则判断，面向用户可写“严重（Critical）”“必须修复（Required）”“小问题（Nit）”“可选（Optional）”“建议考虑（Consider）”“仅供参考（FYI）”；High/Medium/Low、APPROVE/REQUEST CHANGES 和 GO/NO-GO 保留其原始语义与机器值。不得因翻译降低门槛，角色不能互相委派。
 
-适用说明：执行测试先行的红绿重构循环。适用于实现逻辑、修复缺陷、修改行为、复现报错及证明改动有效；缺陷修复使用先证明失败的 Prove-It 模式。
+适用说明：执行测试先行的红绿重构循环。适用于实现逻辑、修复缺陷、修改行为、复现报错及证明改动有效；也用于为函数补测试、修复或修改直接粘贴的代码，即使请求未提到测试；缺陷修复使用先证明失败的 Prove-It 模式。
 <!-- i3:zh-CN:end -->
 
 # Test-Driven Development

package/skills/i3-ui-prototype/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: i3-ui-prototype
+description: "根据业务需求选择 UI 模板，生成、评审并迭代交互原型。适用于选择原型模板、制作可操作审查原型、检查原型一致性及维护已确认的原型基线。"
+# i3-description-source: "description: Creates and iterates reviewable interactive UI prototypes from selected templates and business requirements. Use when choosing UI prototype templates, generating interactive prototypes for review, inspecting prototype fidelity, or maintaining approved prototype baselines."
+---
+
+<!-- i3:zh-CN:start -->
+## 中文交互与输出
+
+默认使用简体中文回复，包括追问、选项说明、阶段进度、分析、规格、计划、验收、代码审查与发布报告。只有用户明确要求其他语言时才切换；输入中出现英文术语、代码或引用不构成切换语言的要求。
+下文的工程步骤、审批要求、退出条件和工具约束完整有效。英文示例中的人类可读标题、说明和占位内容在实际输出时应译为中文；保留原有信息与验证标准，不删减方法。
+Skill/Command/Agent 标识、文件路径、命令参数、代码/API 名称、工具调用参数、JSON 键/类型/枚举、机器状态、测试期望字面量及引用原文保持原样。生成文档正文用中文，SPEC.md、tasks/plan.md、tasks/todo.md、CONSTRAINTS.md 等约定路径不改名。
+严重程度按原规则判断，面向用户可写“严重（Critical）”“必须修复（Required）”“小问题（Nit）”“可选（Optional）”“建议考虑（Consider）”“仅供参考（FYI）”；High/Medium/Low、APPROVE/REQUEST CHANGES 和 GO/NO-GO 保留其原始语义与机器值。不得因翻译降低门槛，角色不能互相委派。
+
+适用说明：根据业务需求选择 UI 模板，生成、评审并迭代交互原型。适用于选择原型模板、制作可操作审查原型、检查原型一致性及维护已确认的原型基线。
+<!-- i3:zh-CN:end -->
+
+# UI Prototype
+
+## Overview
+
+基于业务需求与选定模板交付可操作、可评审的 HTML 原型，保留设计决策、业务映射、浏览器证据和已确认基线。默认使用专业增强模式；用户明确选择后可使用模板模式。原型认可、正式规格、生产开发与发布分别处理。
+
+## When to Use
+
+- 选择 UI 原型模板，按业务需求生成交互原型。
+- 根据评审意见修改原型，检查与既有基线的一致性。
+- 确认具体原型版本，维护后续迭代使用的设计基线。
+
+仅实现已有设计的生产组件时 use the `i3-frontend-ui-engineering` skill。普通排错、纯后端工作和不涉及原型的代码评审继续使用对应工程技能。
+
+## Process
+
+### 1. 读取上下文与选择操作
+
+读取项目规则、实际需求和技术栈，以及项目根 `.i3-ui-prototypes.json` 指向的相关原型。没有正式规格时先整理最小业务范围与待确认项，不能补造审批权限或把演示规则写成已确认需求。
+
+选择 `create`、`revise`、`inspect` 或 `confirm-baseline`；无参数默认 `create`。操作契约及产物规则见 [workflow-contract.md](references/workflow-contract.md) 和 [artifact-contract.md](references/artifact-contract.md)。
+
+### 2. 检测专业能力并继续模板预览
+
+新增原型默认 `professional`（专业增强模式）。优先使用当前宿主暴露的 UI/UX Pro Max 技能位置，运行 `scripts/check-design-provider.cjs --provider <实际技能根>`；也可传入明确的 `--host` 和 `--project` 自动检测项目、全局 Skill 和已启用插件。项目安装的本技能可直接复用同一宿主的全局 UI/UX Pro Max，无需再复制到项目。不能硬编码缓存版本、借用另一宿主安装，或仅凭目录存在判断可执行。明确指定的 provider 失败时报告该路径，不自动换成别的副本。
+
+检测不阻断模板预览，先继续展示模板并记录选择。自动检测遇到不可用项目副本时继续检测全局副本；运行探测通过后使用。缺少宿主信息时补充宿主或实际技能路径；已安装但停用、资源不全、查询失败、发现信息不完整时分别提示启用、修复或定位，不能一律要求重新安装。确认当前宿主未安装时提供安装入口；始终允许明确选择“模板模式继续”或“先整理需求和模板选择”，默认不降级。用户选择安装后按该宿主的官方方法安装并验证；已有授权或已选择模板模式时不重复确认。安装系统运行环境需根据实际缺项处理，不能静默改动操作系统。
+
+模板模式使用 `template`，仍使用同一套业务和浏览器验收标准。不得静默切换，交付记录必须说明实际模式。专业接入的查询与建议适配见 [expert-adapter.md](references/expert-adapter.md)。
+
+### 3. 选择模板并固定版本
+
+运行 `node <skill-root>/scripts/init-prototype.cjs templates` 查看四类：企业管理后台、AI 工作台、数字孪生大屏、移动端应用。按 availability 区分可操作模板与 planned；不能把待建设类型生成成其他类型。通过 `node <skill-root>/assets/templates/serve-gallery.cjs` 打开选择页。企业后台使用 i3-Composer 品牌的完整 HTML 审查版，当前可供人工测试，其余三类待后续实施。已有模板选择时沿用。
+
+选择页只切换预览，不创建或确认业务实例。可生成模板使用 catalog/manifest 显式指定运行层；未知或缺失 adapter 不回退到 common。资源组织、独立模板扩展与旧实例兼容见 [template-adapters.md](references/template-adapters.md)。
+
+企业后台保留原 EASEL 的全部页面、样式、控件和交互；预览及新实例的页面标题、导航、示例项目和相关说明统一使用 i3-Composer，来源快照与内部兼容标识保留。审查整套模板时显式使用 `--purpose template-review`；为新业务生成时沿用默认 business-prototype，替换项目菜单、字段、状态、角色、数据和需求映射，完成后才将 business.status 标为 adapted。旧 classic-admin、modern-workspace、data-operations 仅保留兼容和历史样例迭代，不再作为新项目首选。框架工程保持既有设计规则，交接包含真实组件映射，HTML 审查版不等于真实 Vue/React 组件工程。
+
+创建示例：
+
+```sh
+node <skill-root>/scripts/init-prototype.cjs --project <project-root> --id enterprise-review --template enterprise-admin --purpose template-review --provider <uiux-skill-root>
+# 仅在用户明确选择模板模式后：
+node <skill-root>/scripts/init-prototype.cjs --project <project-root> --id enterprise-review --template enterprise-admin --purpose template-review --expert-mode template
+```
+
+企业后台初始化保留完整 i3-Composer 示例。template-review 用于本次模板人工审查；business-prototype 初始为 needs-adaptation，未完成实际业务适配时验收守卫拒绝通过。复制的 app/qa 是历史来源材料，本次验收使用原型根 qa/。目标已存在时使用迭代流程，不覆盖。完整复用、来源核对与响应式规则见 [enterprise-admin.md](references/enterprise-admin.md)。
+
+### 4. 专业设计与业务实现
+
+将需求编号映射到页面、字段、操作、角色、可见范围、状态与验收场景。专业增强模式加载已发现的 UI/UX Pro Max 指令，运行真实查询并核对匹配；建议不能覆盖选定模板、需求或已认可的规则。查询失配时缩小问题重试一次，仍失配则拒绝并记录依据。
+
+专业建议的采用/拒绝写入 `qa/design-advice.json`，包括查询、结果身份、原因和验证条件。被采用规则写入 `design-system/MASTER.md`、token 或页面规则。基础工程与业务映射始终由 i3 维护。
+
+有实际查询及适用建议采用记录后，将 prototype.json 的 expert.status 更新为 used；没有适用结果时记录 no-match。HANDOFF.md 同步本次真实使用情况，不能保留初始化时“专业建议待适配”的描述冒充已完成。
+
+Follow the `i3-frontend-ui-engineering` skill 实现原型。固定模板版本和 token，新增页面复用组件约定。演示数据、状态切换和本地权限模拟必须可复现；普通按钮反馈不能代替完整的业务流程。修改 token 后同步 `app/tokens.css`。
+
+### 5. 验证并交付候选
+
+运行 `node <skill-root>/scripts/check-prototype.cjs <prototype-root>`，再启动 `node app/serve.cjs`。Follow the `i3-browser-testing-with-devtools` skill 或当前宿主可用的等效真实浏览器能力，检查需求映射中的主流程、校验、权限演示、失败反馈、窄屏、键盘焦点和控制台。
+
+先取 `manage-baseline.cjs manifest <prototype-root>` 的版本与内容摘要，将实际浏览器结果、场景 ID、视口和截图保存到 `qa/browser.json`，绑定同一摘要。运行 `check-prototype.cjs <prototype-root> --acceptance` 核对证据与覆盖；有修改则旧证据失效。
+
+没有实际浏览器证据时交付待验证候选，不能填写 `passed`。本地通过仍是 `pending-review`。提供可打开的预览、模式、范围、待确认问题、检查结果和 `HANDOFF.md`；关键检查失败时明确阻断项。
+
+实际验收通过后，将 prototype.json 的 verification 更新为 passed 并记录对应 digest；review 保持 pending-review。文件再变化时重新验证，不能只修改状态字段。
+
+### 6. 迭代与确认
+
+`revise` 先运行 `manage-baseline.cjs revise <prototype-root> --revision r002`，读取当前设计契约和旧基线，按反馈产生新候选并重新验证受影响场景。保留旧基线和其确认记录；修改全局设计或业务状态规则必须说明差异。
+
+`confirm-baseline` 只能依据用户对明确版本的认可。确认 JSON 含 `revision`、`digest`、`reviewer`、`statement`、`source`，记录用户原意和来源，不能由代理自我认可。先通过当前验收，再运行 `manage-baseline.cjs confirm-baseline <prototype-root> --confirmation <record.json>`。版本或摘要不符、必需证据缺失、旧基线已存在时脚本拒绝。
+
+后续 UI 实现读取项目清单、适用基线及页面规则，运行差异检查。`check-prototype.cjs --enforce-baseline` 可作为设计契约变更检查；它检查原型及其契约，不自动证明任意生产代码的视觉一致性。需要强制合并门禁时由项目实际 Hook/CI 接入并验证。
+
+## Common Rationalizations
+
+| 想法 | 要求 |
+| --- | --- |
+| 专业技能缺失就直接换成模板模式 | 先提示安装或修复，用户明确选择后才切换 |
+| 搜索返回了配色和首页结构就全部采用 | 核对产品与页面匹配，业务界面不能被营销结构替换 |
+| 通用演示生成成功就是完成用户业务 | 按实际需求实现并更新业务映射与验收 |
+| 测试通过可以标记用户已批准 | 本地验证与具体版本的用户认可分别记录 |
+| 更新参考截图即可消除设计差异 | 先解释变更并评审，再更新对应基线 |
+
+## Red Flags
+
+- 未说明模式变化，声称使用了未安装或没有实际采用建议的专业技能。
+- 保留通用演示数据却报告真实业务完成，或把演示授权当服务端权限。
+- 文件变化后继续使用旧的浏览器报告或用户确认。
+- 覆盖已认可的快照、随意更换模板，或为了检查通过降低原有门槛。
+- 用结构校验、词法路由或截图文件存在冒充浏览器和宿主执行证据。
+
+## Verification
+
+- [ ] 模板、版本、运行形态、模式和专业能力实际使用有记录。
+- [ ] 业务映射完整，原型行为与本次范围一致；待确认项可见。
+- [ ] 专业建议已核对并形成具体规则；模板模式明确记录未使用。
+- [ ] 结构校验通过，实际浏览器覆盖必要场景并绑定当前内容摘要。
+- [ ] 候选交付待评审；冻结仅依据同一版本的人类确认。
+- [ ] 迭代读取适用基线，设计变更和工程交接保持可追溯。