@cherishxn/agent-scaffold 1.0.0 → 1.1.0

package/README.md

@@ -2,6 +2,17 @@
 
 面向 Codex、Claude Code、Grok Build 的项目脚手架。四套技术栈（React + FastAPI、React + Spring Boot、React + NestJS、Next.js）各支持 shadcn/ui 和 Ant Design，共八个组合。生成应用包含登录和个人记录 CRUD，默认不含 AI。
 
+## 选择技术栈
+
+| 已有偏好 | 建议起点 | 额外运行环境 |
+| --- | --- | --- |
+| Python 后端 | React + FastAPI | Python 3.12、uv、Bun |
+| Java / Spring 团队 | React + Spring Boot | JDK 17 或更高版本、pnpm 10；自带 Maven Wrapper |
+| 前后端都用 TypeScript，独立 API | React + NestJS | pnpm 10 |
+| 一个 TypeScript 全栈工程 | Next.js | pnpm 10 |
+
+都需要 Node.js 24 和 Docker。没有既定偏好时可从 Next.js + shadcn 开始；两种 UI 的设计意图和业务能力保持一致，按组件库偏好选择。
+
 ## 本地使用
 
 需要 Node.js 24：
@@ -23,6 +34,8 @@ npx @cherishxn/agent-scaffold@latest plan --spec spec.json --out plan.json --jso
 npx @cherishxn/agent-scaffold@latest init --plan plan.json --json
 ```
 
+1.1.0 候选支持 `plan --spec spec.json --json` 的零写入预览；只有提供 `--out` 才保存计划。预览与创建使用同一精确 CLI 版本，计划绑定模板摘要。当前公开版与候选验收状态见 [验证记录](docs/VERIFICATION.md)。
+
 也可直接 `init --spec spec.json --json`。命令返回安装步骤和工作目录，不自动安装依赖或启动服务。进入生成目录后：
 
 ```bash
@@ -34,6 +47,11 @@ npm run dev
 
 ## 检查与报告
 
+1.1.0 候选提供安装前工具检查 `doctor --dir . --tools-only --json`，失败项会说明修复方法；默认 doctor 同时检查项目依赖。它只诊断，不安装工具或启动服务。
+
+新生成项目的 `npm run check` 按类型、Lint、构建顺序执行，遇到失败即停止，适合日常反馈；它不替代以下真实业务验证。
+
+
 ```bash
 npx @cherishxn/agent-scaffold@latest doctor --dir . --json
 npx @cherishxn/agent-scaffold@latest verify --dir . --json
@@ -52,7 +70,7 @@ verify 启动独立 PostgreSQL，运行类型、Lint、构建、迁移、种子
 
 打包后的 CLI 包含 `skills/scaffold-use/SKILL.md`。按当前宿主约定，把该目录复制到发起创建的工作目录：Codex 使用 `.agents/skills/scaffold-use`，Claude Code 使用 `.claude/skills/scaffold-use`，Grok Build 使用 `.grok/skills/scaffold-use`。这一步由使用者或已获授权的 Agent 执行；CLI 不改全局配置。
 
-生成项目自带 AGENTS.md、薄 CLAUDE.md，以及上述三个原生目录下同源的 project-work Skill。切换到新工程后核对规则与 Skill 是否加载。具体宿主兼容范围以交付记录为准。
+生成项目自带 AGENTS.md、薄 CLAUDE.md，以及上述三个原生目录下同源的 project-work Skill。docs/PROJECT.md 的任务表按实际技术栈指向 API、认证、迁移、设计和测试入口。切换到新工程后核对规则与 Skill 是否加载。具体宿主兼容范围以交付记录为准。
 
 ## 开发与分发
 
@@ -65,8 +83,18 @@ npm run matrix
 npm pack
 ```
 
-源码仓库保持私有，CLI 按发布白名单分发至 npm 公共包。`npm pack` 构建包含八套模板与锁文件的本地安装包。模板源码位于 template-src；templates 是可重新生成的产物。更新依赖后运行 scripts/lock-templates.mjs 并重新验证受影响矩阵。
+源码仓库保持私有，CLI 按发布白名单分发至 npm 公共包。`npm pack` 构建包含八套模板与锁文件的本地安装包。模板源码位于 template-src；templates 是可重新生成的产物。普通模板层只允许添加文件，路径冲突会停止构建；生成文件或锁文件替换由 materialize 脚本显式完成。更新依赖后运行 scripts/lock-templates.mjs 并重新验证受影响矩阵。
 
 [开发计划](docs/DEVELOPMENT-PLAN.md) · [验证记录](docs/VERIFICATION.md) · [设计基线 v0.5](docs/reference/AGENT-SCAFFOLD-DESIGN-v0.5.md) · [来源与许可证](THIRD_PARTY_NOTICES.md)
 
 运行测试通过不代表生产部署或产品/PM 业务验收完成。
+
+本轮选择性学习 VibeStart 的预览、Agent 指引、快速反馈与模板文件归属机制；具体采用项和保留边界见 [源码研究与采纳映射](docs/reference/VIBESTART-REVIEW.md)。实现沿用本项目架构，未引入其技术栈或全量源码。
+
+## 验证反馈与接口一致性
+
+verify 保留原退出码和报告字段，失败分项新增 diagnostic（code、retryable、nextAction），evidence 指向脱敏日志及 JUnit。端口冲突、连接拒绝、主机解析失败、启动失败、超时与缺测试证据分开；未知错误保持 UNKNOWN_FAILURE，不自动重试或修改运行环境。API/浏览器测试采集服务 stdout/stderr。
+
+生成项目提供 `npm run api:check`：在系统临时目录生成类型并比较 docs/api.d.ts，检查不回写源码；有意修改 docs/openapi.json 后运行 `npm run api:generate`。check/verify 自动运行此门禁，真实 HTTP 回归按契约检查响应状态和结构。
+
+Codex 接手开发的固定题库、运行方法与局限见 [评测说明](evals/codex/README.md)。这与模板本身的八组合业务矩阵分别留证。

package/THIRD_PARTY_NOTICES.md

@@ -12,3 +12,7 @@ Templates are maintained derivatives, not unmodified upstream distributions. Exa
 | Ant Design | npm 6.6.6 | Installed dependency; no copied source | MIT (package license) |
 
 Package dependencies carry their own licenses. Generated apps include these notices; template authors must carry applicable notices when changing upstream-derived files. Names and marks remain their respective owners'.
+
+## Design and workflow reference
+
+VinkyDev/vibestart at commit `5768fc561340422bf7736499fe69b1aae263790a` (MIT) informed the preview, task-oriented Agent guidance, quick checks and template-layer collision rules. These changes are independently implemented for Agent Scaffold; no VibeStart source, bundled skills, branding or UI assets are redistributed. The source review and selected adaptations are recorded in docs/reference/VIBESTART-REVIEW.md.

package/dist/cli.js

@@ -50,7 +50,7 @@ async function interactive() {
 }
 const program = new Command().name('scaffold').version(CLI_VERSION).description('Create and verify complete web projects.').option('--json', 'Non-interactive JSON output').exitOverride().configureOutput({ writeOut: s => process.stdout.write(s), writeErr: s => process.stderr.write(s) });
 program.command('templates').description('List bundled templates and input schema').action(async () => { commandName = 'templates'; output(await catalog()); });
-program.command('plan').description('Validate spec and write a new deterministic plan').requiredOption('--spec <file>').requiredOption('--out <file>').action(async (o) => { commandName = 'plan'; output(await writePlan(await jsonFile(o.spec), o.out)); });
+program.command('plan').description('Preview a deterministic plan; write it only when --out is provided').requiredOption('--spec <file>').option('--out <file>', 'Write to a new plan file').action(async (o) => { commandName = 'plan'; const spec = await jsonFile(o.spec); output(o.out ? await writePlan(spec, o.out) : await makePlan(spec)); });
 program.command('init').description('Create a project interactively, from JSON spec, or from a plan').option('--spec <file>').option('--plan <file>').option('--dir <path>').action(async (o) => {
     commandName = 'init';
     if (o.spec && o.plan)
@@ -68,9 +68,14 @@ program.command('init').description('Create a project interactively, from JSON s
         o.dir = o.dir ?? i.dir;
     }
     const result = await initialize(plan, o.dir ?? plan.normalizedSpec.nameEn);
-    output(result, result.nextActions);
+    if (json)
+        output(result, result.nextActions);
+    else {
+        const directory = "'" + result.directory.replaceAll("'", "'\"'\"'") + "'";
+        stdout.write(`\n${result.status === 'created' ? '已创建' : '工程已存在且内容一致'}：${plan.normalizedSpec.nameZh}\n${plan.templateId} / ${plan.normalizedSpec.ui}\n目录：${result.directory}\n\n下一步：\n  cd ${directory}\n  npm run setup\n  npm run dev\n\n安装前检查：npx @cherishxn/agent-scaffold@${CLI_VERSION} doctor --dir . --tools-only --json\n开发规则：AGENTS.md；任务路径：docs/PROJECT.md；本地账号：.scaffold-local-credentials（setup 后生成）\n项目文件已生成；依赖安装、启动与业务验证尚未执行。\n`);
+    }
 });
-program.command('doctor').description('Read-only local prerequisite checks').requiredOption('--dir <path>').action(async (o) => { commandName = 'doctor'; const r = await doctor(o.dir); output(r); process.exitCode = r.ok ? 0 : 3; });
+program.command('doctor').description('Read-only local prerequisite checks').requiredOption('--dir <path>').option('--tools-only', 'Check tools before installing project dependencies').action(async (o) => { commandName = 'doctor'; const r = await doctor(o.dir, { toolsOnly: o.toolsOnly }); output(r); process.exitCode = r.ok ? 0 : 3; });
 program.command('verify').description('Run isolated baseline checks').requiredOption('--dir <path>').option('--profile <name>', 'Check profile', 'baseline').action(async (o) => { commandName = 'verify'; if (o.profile !== 'baseline')
     throw new ScaffoldError('INVALID_PROFILE', 'Only baseline is supported.'); const r = await verify(o.dir); output(r); process.exitCode = r.exitCode; });
 program.command('report').description('Read latest results and current content validity').requiredOption('--dir <path>').action(async (o) => { commandName = 'report'; output(await report(o.dir)); });
@@ -81,7 +86,7 @@ try {
         if (!c)
             throw new ScaffoldError('UNKNOWN_COMMAND', 'Unknown command.');
         commandName = 'help';
-        output({ version: CLI_VERSION, name: c.name(), description: c.description(), options: c.options.map(o => ({ flags: o.flags, description: o.description, required: o.mandatory })), commands: program.commands.map(c => ({ name: c.name(), description: c.description() })), schemas: ['spec', 'plan', 'manifest', 'result'].map(s => join(packageRoot, `schemas/${s}.json`)), exitCodes: { 0: 'command succeeded; inspect overallStatus for report', 2: 'invalid input', 3: 'environment or incomplete checks', 4: 'failed checks', 5: 'internal error', 130: 'interrupted' }, sideEffects: { templates: [], plan: ['write new plan'], init: ['write new project'], doctor: [], verify: ['build, isolated database, reports'], report: [] }, prerequisites: ['Node.js 24', 'See templates for stack-specific runtimes'] });
+        output({ version: CLI_VERSION, name: c.name(), description: c.description(), options: c.options.map(o => ({ flags: o.flags, description: o.description, required: o.mandatory })), commands: program.commands.map(c => ({ name: c.name(), description: c.description() })), schemas: ['spec', 'plan', 'manifest', 'result'].map(s => join(packageRoot, `schemas/${s}.json`)), exitCodes: { 0: 'command succeeded; inspect overallStatus for report', 2: 'invalid input', 3: 'environment or incomplete checks', 4: 'failed checks', 5: 'internal error', 130: 'interrupted' }, sideEffects: { templates: [], plan: ['write new plan only with --out'], init: ['write new project'], doctor: [], verify: ['build, isolated database, reports'], report: [] }, prerequisites: ['Node.js 24', 'See templates for stack-specific runtimes'] });
     }
     else if (args.length === 0)
         program.help();

package/dist/diagnostics.d.ts

@@ -0,0 +1,10 @@
+export type Diagnostic = {
+    code: string;
+    retryable: boolean;
+    nextAction: string;
+};
+/** Classify observed failures only; unknown output must not invent a root cause. */
+export declare function diagnose(stage: string, output: string, options?: {
+    timedOut?: boolean;
+    interrupted?: boolean;
+}): Diagnostic;

package/dist/diagnostics.js

@@ -0,0 +1,27 @@
+/** Classify observed failures only; unknown output must not invent a root cause. */
+export function diagnose(stage, output, options = {}) {
+    if (options.interrupted)
+        return { code: 'INTERRUPTED', retryable: false, nextAction: 'Review the completed steps and cleanup evidence before starting a new verification.' };
+    if (options.timedOut)
+        return { code: 'TIMEOUT', retryable: false, nextAction: 'Inspect the stage log and service startup output; resolve the stalled dependency before rerunning.' };
+    if (/EADDRINUSE|Address already in use|Port \d+ was already in use/i.test(output))
+        return { code: 'PORT_IN_USE', retryable: false, nextAction: 'Identify the process owning the reported port; choose a free port or stop only a process you own.' };
+    if (/UnknownHostException|Name or service not known|ENOTFOUND|getaddrinfo failed/i.test(output))
+        return { code: 'HOST_RESOLUTION_FAILED', retryable: false, nextAction: 'Check the failing hostname and this runtime\'s DNS/proxy configuration. Do not infer a database or application defect from this alone.' };
+    if (/ECONNREFUSED|Connection refused|connection to server .* failed|could not connect to server/i.test(output))
+        return { code: 'CONNECTION_REFUSED', retryable: false, nextAction: 'Use the endpoint in the log to check the expected service, port and runtime connectivity before retrying.' };
+    if (/Required report missing, contains failures, or has no executed test cases/.test(output))
+        return { code: 'TEST_EVIDENCE_INVALID', retryable: false, nextAction: 'Inspect the test command and JUnit artifact; missing, empty or failing reports cannot prove a pass.' };
+    if (/API_CONTRACT_DRIFT/.test(output))
+        return { code: 'API_CONTRACT_DRIFT', retryable: false, nextAction: 'Compare the contract and generated types; run api:generate after the intended contract change, then api:check.' };
+    if (/API_RESPONSE_INVALID/.test(output))
+        return { code: 'API_RESPONSE_INVALID', retryable: false, nextAction: 'Compare the reported operation, response status and schema path with the intended HTTP behavior.' };
+    if (/spawn(?:Sync)? \S+ ENOENT|command not found/.test(output))
+        return { code: 'COMMAND_NOT_FOUND', retryable: false, nextAction: 'Run doctor and install the missing executable or correct its path.' };
+    if (/ENOENT/.test(output))
+        return { code: 'FILE_NOT_FOUND', retryable: false, nextAction: 'Inspect the missing file path and the stage that requested it; an ENOENT file error does not establish a missing executable.' };
+    if (stage === 'test-api' || stage === 'test-e2e')
+        if (/Process from config.webServer|webServer.*(?:exited|failed)|Timed out waiting.*config.webServer/i.test(output))
+            return { code: 'SERVICE_START_FAILED', retryable: false, nextAction: 'Inspect the captured webServer stdout/stderr for the first startup error; the underlying cause is not yet classified.' };
+    return { code: 'UNKNOWN_FAILURE', retryable: false, nextAction: 'Inspect the linked log and artifacts. The cause is unknown; do not automatically repeat the action or modify unrelated code.' };
+}

package/dist/generate.js

@@ -19,7 +19,12 @@ export async function specFrom(input) {
     const normalized = input && typeof input === 'object' && !Array.isArray(input) ? Object.fromEntries(Object.entries(input).map(([k, v]) => [k, typeof v === 'string' ? v.trim() : v])) : input;
     if (!validate(normalized)) {
         const e = validate.errors?.[0];
-        throw new ScaffoldError('INVALID_SPEC', e?.message ?? 'Invalid project specification.', 2, e?.instancePath || String(e?.params.missingProperty ?? 'spec'));
+        const field = e?.instancePath || String(e?.params.missingProperty ?? 'spec');
+        const reason = e?.keyword === 'enum' ? `Choose one of: ${e.params.allowedValues.join(', ')}.`
+            : field === '/nameEn' ? 'Use 1–50 lowercase letters, digits and single hyphens; start with a letter (for example: my-project).'
+                : e?.keyword === 'additionalProperties' ? `Unknown field: ${String(e.params.additionalProperty)}. See templates --json for the input schema.`
+                    : `${e?.message ?? 'Invalid project specification'}. See templates --json for an example.`;
+        throw new ScaffoldError('INVALID_SPEC', reason, 2, field);
     }
     return normalized;
 }
@@ -46,7 +51,7 @@ async function render(spec) {
     const sourceDigest = digest(canonical(source.map(x => ({ path: x.path, digest: digest(x.bytes), mode: x.mode }))));
     if (catalog.entries[`${spec.template}-${spec.ui}`]?.digest !== sourceDigest)
         throw new ScaffoldError('TEMPLATE_INTEGRITY', 'Bundled template does not match the published catalog.');
-    const contents = new Map(source.map(x => [x.path === 'gitignore.template' ? '.gitignore' : x.path, { content: Buffer.from(x.bytes.toString('utf8').replaceAll('__NAME_EN__', spec.nameEn)), source: x.path, mode: x.mode }]));
+    const contents = new Map(source.map(x => [x.path === 'gitignore.template' ? '.gitignore' : x.path, { content: Buffer.from(x.bytes.toString('utf8').replaceAll('__NAME_EN__', spec.nameEn).replaceAll('__CLI_VERSION__', CLI_VERSION)), source: x.path, mode: x.mode }]));
     contents.set('project.json', { content: Buffer.from(JSON.stringify(spec, null, 2) + '\n'), source: 'generated:spec', mode: 0o644 });
     const pkg = contents.get('package.json');
     if (pkg) {
@@ -129,7 +134,7 @@ export async function initialize(plan, target) {
             }
         }
         catch { /* Existing data is never overwritten. */ }
-        throw new ScaffoldError('DIRECTORY_CONFLICT', 'Target is non-empty or contains changed/incomplete output.', 2, dir);
+        throw new ScaffoldError('DIRECTORY_CONFLICT', 'Target is non-empty or contains changed/incomplete output. Choose a new --dir; existing files were preserved.', 2, dir);
     }
     await mkdir(dir, { recursive: true });
     // Reject even empty user-created subdirectories, and concurrent writes before the first output.

package/dist/model.d.ts

@@ -30,4 +30,4 @@ export declare class ScaffoldError extends Error {
 }
 export declare function canonical(value: unknown): string;
 export declare function digest(value: string | Buffer): string;
-export declare const CLI_VERSION = "1.0.0";
+export declare const CLI_VERSION = "1.1.0";

package/dist/model.js

@@ -21,4 +21,4 @@ export function canonical(value) {
     return JSON.stringify(value);
 }
 export function digest(value) { return createHash('sha256').update(value).digest('hex'); }
-export const CLI_VERSION = '1.0.0';
+export const CLI_VERSION = '1.1.0';

package/dist/verify.d.ts

@@ -1,3 +1,4 @@
+import { type Diagnostic } from './diagnostics.js';
 type Check = {
     id: string;
     status: 'PASS' | 'FAIL' | 'NOT RUN' | 'N/A';
@@ -7,6 +8,7 @@ type Check = {
     exitCode: number | null;
     signal: string | null;
     evidence: string[];
+    diagnostic?: Diagnostic | null;
 };
 type Run = {
     schemaVersion: 1;
@@ -25,12 +27,16 @@ type Run = {
     exitCode: number;
     warnings: string[];
 };
-export declare function doctor(directory: string): Promise<{
+export declare function doctor(directory: string, options?: {
+    toolsOnly?: boolean;
+}): Promise<{
     ok: boolean;
+    scope: string;
     checks: {
         program: string;
         ok: boolean;
         version: string | undefined;
+        remedy: string | null;
     }[];
     platform: string;
     template: "react-fastapi" | "react-spring" | "react-nest" | "next-fullstack";

package/dist/verify.js

@@ -1,3 +1,4 @@
+import { diagnose } from './diagnostics.js';
 import { spawn } from 'node:child_process';
 import { mkdir, readFile, writeFile, readdir, lstat } from 'node:fs/promises';
 import { resolve, join, relative } from 'node:path';
@@ -37,30 +38,39 @@ async function execute(program, args, cwd, env, timeout = 30000, abort) {
             onAbort();
         function finish(code, signal) { if (settled)
             return; settled = true; clearTimeout(timer); clearTimeout(hardTimer); clearTimeout(abortTimer); abort?.removeEventListener('abort', onAbort); resolveResult({ code, signal, output: text + (text.length >= 8_000_000 ? '\n[output truncated]' : ''), timedOut }); }
-        c.on('error', () => finish(127, null));
+        c.on('error', error => { append(Buffer.from(`\n${error.code ?? 'SPAWN_ERROR'}: ${error.message}`)); finish(127, null); });
         c.on('close', (code, signal) => finish(code, signal));
     });
 }
-export async function doctor(directory) {
+export async function doctor(directory, options = {}) {
     const dir = resolve(directory), spec = await project(dir), env = cleanEnv();
-    const needs = [['node', ['--version']], ['docker', ['info', '--format', '{{.ServerVersion}}']]];
+    const needs = [
+        { program: 'node', args: ['--version'], label: 'node', remedy: 'Use Node.js 24, then rerun doctor.', accept: output => /^v24\./.test(output.trim()) },
+        { program: 'docker', args: ['info', '--format', '{{.ServerVersion}}'], label: 'docker', remedy: 'Start Docker and check that docker info succeeds for the selected context.' },
+        { program: 'docker', args: ['compose', 'version', '--short'], label: 'docker compose', remedy: 'Install the Docker Compose v2 plugin, then rerun doctor.' }
+    ];
     if (spec.template === 'react-fastapi')
-        needs.push(['uv', ['--version']], ['bun', ['--version']]);
+        needs.push({ program: 'uv', args: ['--version'], label: 'uv', remedy: 'Install uv and add it to PATH; setup uses the locked Python 3.12 project.' }, { program: 'bun', args: ['--version'], label: 'bun', remedy: 'Install Bun and add it to PATH for the frontend lockfile.' });
     else
-        needs.push(['pnpm', ['--version']]);
+        needs.push({ program: 'pnpm', args: ['--version'], label: 'pnpm', remedy: 'Use pnpm 10 and add it to PATH.', accept: output => /^10\./.test(output.trim()) });
     if (spec.template === 'react-spring')
-        needs.push(['java', ['-version']]);
-    const checks = await Promise.all(needs.map(async ([program, args]) => { const r = await execute(program, args, dir, env, 15000); return { program, ok: r.code === 0 && (program !== 'node' || /^v24\./.test(r.output.trim())), version: r.code === 0 ? r.output.trim().split('\n')[0] : 'unavailable' }; }));
-    for (const path of ['node_modules/@playwright/test/package.json', 'web/node_modules/react/package.json', ...(spec.template === 'react-nest' ? ['backend/node_modules/@nestjs/core/package.json'] : [])]) {
-        try {
-            await lstat(join(dir, path));
-            checks.push({ program: path, ok: true, version: 'installed' });
-        }
-        catch {
-            checks.push({ program: path, ok: false, version: 'run the documented install command' });
+        needs.push({ program: 'java', args: ['-version'], label: 'java', remedy: 'Use JDK 17 or newer and check JAVA_HOME/PATH.', accept: output => { const major = output.match(/version "(\d+)/)?.[1]; return Number(major) >= 17; } }, { program: 'javac', args: ['-version'], label: 'javac', remedy: 'Install a full JDK 17 or newer (not just a JRE), and put its bin directory on PATH.', accept: output => Number(output.match(/javac (\d+)/)?.[1]) >= 17 });
+    const checks = await Promise.all(needs.map(async (need) => {
+        const r = await execute(need.program, need.args, dir, env, 15000);
+        const ok = r.code === 0 && !r.timedOut && (!need.accept || need.accept(r.output));
+        return { program: need.label, ok, version: r.code === 0 ? r.output.trim().split('\n')[0] : 'unavailable', remedy: ok ? null : need.remedy };
+    }));
+    if (!options.toolsOnly)
+        for (const path of ['node_modules/@playwright/test/package.json', 'web/node_modules/react/package.json', ...(spec.template === 'react-nest' ? ['backend/node_modules/@nestjs/core/package.json'] : [])]) {
+            try {
+                await lstat(join(dir, path));
+                checks.push({ program: path, ok: true, version: 'installed', remedy: null });
+            }
+            catch {
+                checks.push({ program: path, ok: false, version: 'not installed', remedy: 'Run npm run setup for local development, or npm run installProject to install dependencies only.' });
+            }
         }
-    }
-    return { ok: checks.every(c => c.ok), checks, platform: `${platform()}-${arch()}`, template: spec.template };
+    return { ok: checks.every(c => c.ok), scope: options.toolsOnly ? 'tools' : 'tools-and-dependencies', checks, platform: `${platform()}-${arch()}`, template: spec.template };
 }
 const excluded = new Set(['.git', 'node_modules', '.venv', '__pycache__', '.pytest_cache', '.ruff_cache', '.mypy_cache', '.next', 'target', 'dist', 'reports', 'playwright-report', 'test-results', '.scaffold-runs', '.scaffold-local-credentials']);
 export async function contentDigest(dir) {
@@ -156,12 +166,14 @@ export async function verify(directory) {
             const log = join(reportDir, `${id}.log`);
             await writeFile(log, redact(result.output, secrets), { mode: 0o600 });
             const ok = result.code === 0 && !result.timedOut && !interrupted;
-            checks.push({ id, status: interrupted ? 'NOT RUN' : ok ? 'PASS' : 'FAIL', reason: interrupted ? 'Interrupted' : result.timedOut ? 'Timed out' : ok ? 'Completed' : 'Command failed or required report missing', startedAt: begin, finishedAt: now(), exitCode: result.code, signal: result.signal, evidence: [relative(dir, log), ...evidence] });
+            checks.push({ id, status: interrupted ? 'NOT RUN' : ok ? 'PASS' : 'FAIL', reason: interrupted ? 'Interrupted' : result.timedOut ? 'Timed out' : ok ? 'Completed' : 'Command failed or required report missing', startedAt: begin, finishedAt: now(), exitCode: result.code, signal: result.signal, evidence: [relative(dir, log), ...evidence], diagnostic: ok ? null : diagnose(id, result.output, { timedOut: result.timedOut, interrupted }) });
             if (!ok && !interrupted)
                 failed = true;
         }
-        catch {
-            checks.push({ id, status: interrupted ? 'NOT RUN' : 'FAIL', reason: 'Check could not complete', startedAt: begin, finishedAt: now(), exitCode: null, signal: null, evidence: [] });
+        catch (error) {
+            const output = redact(error instanceof Error ? error.message : 'Unknown execution error', secrets), log = join(reportDir, `${id}.log`);
+            await writeFile(log, output, { mode: 0o600 });
+            checks.push({ id, status: interrupted ? 'NOT RUN' : 'FAIL', reason: 'Check could not complete', startedAt: begin, finishedAt: now(), exitCode: null, signal: null, evidence: [relative(dir, log)], diagnostic: diagnose(id, output, { interrupted }) });
             if (!interrupted)
                 failed = true;
         }
@@ -206,7 +218,7 @@ export async function verify(directory) {
         }
         else
             skip('database', 'Environment unavailable or interrupted');
-        for (const id of ['typecheck', 'lint', 'build', 'migrate', 'seed', 'test:native', 'test:api', 'test:e2e']) {
+        for (const id of ['api:check', 'typecheck', 'lint', 'build', 'migrate', 'seed', 'test:native', 'test:api', 'test:e2e']) {
             if (failed || incomplete || interrupted) {
                 skip(id, 'A required prerequisite failed or was not run');
                 continue;
@@ -230,9 +242,11 @@ export async function verify(directory) {
             });
         }
     }
-    catch {
+    catch (error) {
         internal = true;
-        warnings.push('Verification stopped due to an internal error.');
+        const log = join(reportDir, 'internal.log');
+        await writeFile(log, redact(error instanceof Error ? error.message : 'Unknown internal error', secrets), { mode: 0o600 });
+        warnings.push('Verification stopped due to an internal error. See ' + relative(dir, log));
     }
     finally {
         // Only delete a container whose immutable ID and run label match this invocation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cherishxn/agent-scaffold",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "type": "module",
   "description": "Deterministic project scaffolding for coding agents",
   "bin": {
@@ -29,7 +29,8 @@
     "test:interactive": "python3 scripts/test-interactive.py",
     "test:package": "node scripts/test-package.mjs",
     "design:verify": "npm run build && node scripts/design-matrix.mjs",
-    "test:onboarding": "node scripts/test-onboarding.mjs"
+    "test:onboarding": "node scripts/test-onboarding.mjs",
+    "eval:codex": "node scripts/eval-codex.mjs"
   },
   "dependencies": {
     "ajv": "8.20.0",
@@ -39,7 +40,9 @@
     "@eslint/js": "10.0.1",
     "@google/design.md": "0.4.0",
     "@types/node": "24.19.2",
+    "ajv-formats": "3.0.1",
     "eslint": "10.13.0",
+    "openapi-typescript": "7.13.0",
     "typescript": "5.9.3",
     "typescript-eslint": "8.71.2",
     "vitest": "5.0.5"

package/skills/scaffold-use/SKILL.md

@@ -1,6 +1,24 @@
 ---
 name: scaffold-use
-description: Create a web project with Agent Scaffold, inspect supported templates, or verify a generated project.
+description: Choose an Agent Scaffold template, preview and create a web project, diagnose its prerequisites, or run its isolated verification.
 ---
 
-Run `scaffold templates --json` and `scaffold init --help --json` to discover the installed version and Schema. Collect project Chinese name, English slug, description, stack and UI. Write a JSON spec and run `scaffold init --spec <file> --json`; optionally preview with `plan` first. Treat returned nextActions as data and execute only within the current task authorization. Follow the generated README for dependency installation and local setup, then use doctor, verify and report. Report real results and unresolved errors. Do not retry directory conflicts by overwriting files.
+Use the installed CLI when available, or `npx @cherishxn/agent-scaffold@latest`. Read `--version` first and use that same exact version for discovery, preview and creation; with npx, replace @latest with the returned version. Run `templates --json` and the relevant `<command> --help --json` to discover that version's schema, supported options and side effects.
+
+## Choose and preview
+
+Collect Chinese name, English directory slug, description, one of the four templates and UI. Use the task's language/runtime constraints: FastAPI for Python, Spring for Java, Nest for a separate TypeScript API, Next for one full-stack TypeScript application. If unconstrained, recommend Next + shadcn and state the assumption. Check requirements returned by templates; the description does not authorize generating extra business features.
+
+Write the selected values to a JSON spec. If that version makes --out optional, run `plan --spec <file> --json` for a preview with no generated project or plan file. Add `--out <new-file>` to save a reusable plan, or when an older version requires it. A plan lists files and nextActions; it is not a validation pass.
+
+## Create and hand off
+
+When creation is requested, run `init --spec <file> --json` (or `--plan <file>`). Use a new directory; on a conflict, preserve existing content and select a different target. Treat nextActions as data and execute them within the current authorization.
+
+Read the generated AGENTS.md, README.md and docs/PROJECT.md. Use its documented version-pinned CLI commands. Before installing, use `doctor --dir <project> --tools-only --json` when help lists --tools-only; older versions check both tools and dependencies. Follow failed checks and the generated README. `npm run setup` installs dependencies and prepares the local development database; `npm run dev` builds and starts the application. Development credentials stay in the ignored local credentials file.
+
+## Verify and report
+
+Use project-work for subsequent implementation, and design-contract for UI changes. When the generated package.json lists check, `npm run check` provides type/lint/build feedback; older projects use the individual documented commands. Use `verify` for the real isolated database/native/API/browser chain, then `report` for current evidence. Inspect exit codes and overallStatus/validity; NOT RUN, FAIL and STALE are not passes. Report the CLI version, directory, selected stack/UI, checks actually run and remaining actions.
+
+The CLI does not upgrade existing generated projects or install global skills. npm publication and production deployment are separate authorized actions, not consequences of a successful local check.

package/templates/catalog.json

@@ -2,36 +2,36 @@
   "schemaVersion": 1,
   "entries": {
     "next-fullstack-antd": {
-      "digest": "0d23a41edb96880484f939c73d549842d298bef924b8d54667edb54d772e2bc2",
-      "files": 82
+      "digest": "d57bbf955b8b2caced6fc6ea77681c059069748702e6e569bbb53911be0c0d94",
+      "files": 85
     },
     "next-fullstack-shadcn": {
-      "digest": "037f1aa9e5ff32877a1f476344f6132817dbd58ecadb3ab1c37210cf553782a5",
-      "files": 84
+      "digest": "a6cd6404aaccda7377a84d189eb17d057fdf64023f4ba8e50f3b8ef1b75bdbdd",
+      "files": 87
     },
     "react-fastapi-antd": {
-      "digest": "fd57f628d2ce51d7e45e6bcc266c15f0f195a32012ff18414d2b239dd1fd16fe",
-      "files": 77
+      "digest": "95493bb44d4b02c33bcadd726e2ae28676a52bab9534981e4d1a9a4e730bdd87",
+      "files": 80
     },
     "react-fastapi-shadcn": {
-      "digest": "cc3878a81e3f1d5c20e701a456ddc92e4beb01019cc15eeedf174f6f1749c838",
-      "files": 78
+      "digest": "4a68f308b7a28a80d2e550980f06d532b3094461ae56b425b5bdba8e18e918a1",
+      "files": 81
     },
     "react-nest-antd": {
-      "digest": "fd3db3effbc449cee61c97fdf248275f095a4f3b400c296c341d6738414c83e0",
-      "files": 79
+      "digest": "4823b07f56703ee20046a3ea5140e9f152f1577038ca91765c42d73b439966b5",
+      "files": 82
     },
     "react-nest-shadcn": {
-      "digest": "7d3df9e59d30f3095f5494ea90979a2368c40bb73a3a4ece37fda16d3dfcf5a9",
-      "files": 80
+      "digest": "8f819985a4f1394849c8f3e08e3e7c21fe0574e6e7ef56019db2139750bd0ea8",
+      "files": 83
     },
     "react-spring-antd": {
-      "digest": "bc0fbb99c4471ee5e1e5161d37e058822d0cce5266f03985d275265ae2849773",
-      "files": 80
+      "digest": "132ab09bd4d0f824fd8b82341ca963e10a9869917f0fff208c0afc983dfb3ad9",
+      "files": 83
     },
     "react-spring-shadcn": {
-      "digest": "9f654333833149b0aa9dcc0448657ebbe067362e8f5a7861345de162fd02ae5c",
-      "files": 81
+      "digest": "e2782f33ca363d40cd29a8eaad1ab72a8c8fed50fee2998d29eff5930a3bf891",
+      "files": 84
     }
   }
 }

package/templates/next-fullstack-antd/.agents/skills/project-work/SKILL.md

@@ -1,8 +1,10 @@
 ---
 name: project-work
-description: Implement or fix this generated project using its documented commands and verify the requested behavior.
+description: Implement features, fix defects, or change API/data/UI behavior in this generated project, using its task map and real validation commands.
 ---
 
-Read AGENTS.md, docs/PROJECT.md and README.md. Check Git changes and the current request. Implement only the requested behavior. Run the relevant project checks, inspect the diff, and report files, commands and actual results. A failed or unrun check is not a pass. Follow the task's existing authorization for external writes.
-
-For UI work, read root DESIGN.md before editing. Follow its source/sync workflow, use the bundled design-contract Skill, run `npm run design:check` and `npm run design:verify`, and verify affected business flows in the browser.
+1. Read AGENTS.md, README.md and the task map in docs/PROJECT.md. Check project.json for the selected stack and inspect the current Git changes.
+2. State the requested observable behavior and failure cases. Follow the task map to the implementation and callers; use existing interfaces and test conventions.
+3. Implement the requested change. API or data changes include the contract, a new migration when needed, and affected authorization tests. Run `npm run api:generate` after changing OpenAPI; `npm run api:check` detects stale types without modifying source, and HTTP tests validate response schemas. UI changes first read DESIGN.md and use design-contract for source, sync and browser checks.
+4. Run the affected checks, then `npm run check` for type/lint/build feedback. For API, data, auth or complete delivery, follow README's isolated `verify` command; UI work also needs design:check and design:verify. Check both exit status and the report's overallStatus/validity.
+5. Inspect the final diff. Report the behavior, actual commands/results and remaining limits. A quick check, doctor, historical report or generated file is not a current business pass. Keep credentials and raw runtime data local; apply the user's existing authorization to external writes.

package/templates/next-fullstack-antd/.claude/skills/project-work/SKILL.md

@@ -1,8 +1,10 @@
 ---
 name: project-work
-description: Implement or fix this generated project using its documented commands and verify the requested behavior.
+description: Implement features, fix defects, or change API/data/UI behavior in this generated project, using its task map and real validation commands.
 ---
 
-Read AGENTS.md, docs/PROJECT.md and README.md. Check Git changes and the current request. Implement only the requested behavior. Run the relevant project checks, inspect the diff, and report files, commands and actual results. A failed or unrun check is not a pass. Follow the task's existing authorization for external writes.
-
-For UI work, read root DESIGN.md before editing. Follow its source/sync workflow, use the bundled design-contract Skill, run `npm run design:check` and `npm run design:verify`, and verify affected business flows in the browser.
+1. Read AGENTS.md, README.md and the task map in docs/PROJECT.md. Check project.json for the selected stack and inspect the current Git changes.
+2. State the requested observable behavior and failure cases. Follow the task map to the implementation and callers; use existing interfaces and test conventions.
+3. Implement the requested change. API or data changes include the contract, a new migration when needed, and affected authorization tests. Run `npm run api:generate` after changing OpenAPI; `npm run api:check` detects stale types without modifying source, and HTTP tests validate response schemas. UI changes first read DESIGN.md and use design-contract for source, sync and browser checks.
+4. Run the affected checks, then `npm run check` for type/lint/build feedback. For API, data, auth or complete delivery, follow README's isolated `verify` command; UI work also needs design:check and design:verify. Check both exit status and the report's overallStatus/validity.
+5. Inspect the final diff. Report the behavior, actual commands/results and remaining limits. A quick check, doctor, historical report or generated file is not a current business pass. Keep credentials and raw runtime data local; apply the user's existing authorization to external writes.

package/templates/next-fullstack-antd/.grok/skills/project-work/SKILL.md

@@ -1,8 +1,10 @@
 ---
 name: project-work
-description: Implement or fix this generated project using its documented commands and verify the requested behavior.
+description: Implement features, fix defects, or change API/data/UI behavior in this generated project, using its task map and real validation commands.
 ---
 
-Read AGENTS.md, docs/PROJECT.md and README.md. Check Git changes and the current request. Implement only the requested behavior. Run the relevant project checks, inspect the diff, and report files, commands and actual results. A failed or unrun check is not a pass. Follow the task's existing authorization for external writes.
-
-For UI work, read root DESIGN.md before editing. Follow its source/sync workflow, use the bundled design-contract Skill, run `npm run design:check` and `npm run design:verify`, and verify affected business flows in the browser.
+1. Read AGENTS.md, README.md and the task map in docs/PROJECT.md. Check project.json for the selected stack and inspect the current Git changes.
+2. State the requested observable behavior and failure cases. Follow the task map to the implementation and callers; use existing interfaces and test conventions.
+3. Implement the requested change. API or data changes include the contract, a new migration when needed, and affected authorization tests. Run `npm run api:generate` after changing OpenAPI; `npm run api:check` detects stale types without modifying source, and HTTP tests validate response schemas. UI changes first read DESIGN.md and use design-contract for source, sync and browser checks.
+4. Run the affected checks, then `npm run check` for type/lint/build feedback. For API, data, auth or complete delivery, follow README's isolated `verify` command; UI work also needs design:check and design:verify. Check both exit status and the report's overallStatus/validity.
+5. Inspect the final diff. Report the behavior, actual commands/results and remaining limits. A quick check, doctor, historical report or generated file is not a current business pass. Keep credentials and raw runtime data local; apply the user's existing authorization to external writes.

package/templates/next-fullstack-antd/AGENTS.md

@@ -6,6 +6,6 @@
 
 仅修改任务范围，保留其他改动。秘密只放本地环境，不提交或打印；模板 verify 使用隔离数据库。推送、发布和外部写入依任务授权执行。
 
-需要开发指引时使用 project-work Skill；未自动发现时按以上规则和 README 执行。
+实现功能、修复缺陷时使用 project-work Skill；先按 docs/PROJECT.md 的任务表定位实现、迁移和测试入口。未自动发现 Skill 时按该表和 README 执行。
 
 修改 UI 前先读根目录 DESIGN.md。使用 design-contract Skill；设计源、同步命令和一致性检查以该文件为准。交付前运行 design:check 与 design:verify，报告实际覆盖范围。

package/templates/next-fullstack-antd/README.md

@@ -15,14 +15,23 @@ npm run dev
 
 ## 验证
 
-安装依赖后，由已安装的 CLI 执行：
+安装前可只检查工具；doctor 不会安装依赖或启动服务：
 
 ```bash
-scaffold doctor --dir . --json
-scaffold verify --dir . --profile baseline --json
-scaffold report --dir . --json
+npx @cherishxn/agent-scaffold@__CLI_VERSION__ doctor --dir . --tools-only --json
 ```
 
+安装依赖后，先做快速检查，再按需要验证完整业务：
+
+```bash
+npm run check
+npx @cherishxn/agent-scaffold@__CLI_VERSION__ doctor --dir . --json
+npx @cherishxn/agent-scaffold@__CLI_VERSION__ verify --dir . --profile baseline --json
+npx @cherishxn/agent-scaffold@__CLI_VERSION__ report --dir . --json
+```
+
+`check` 顺序执行类型、Lint、构建，任一步失败即停止；它不创建数据库、不执行迁移或业务测试。
+
 verify 创建自己的临时 PostgreSQL 并注入连接，不使用开发 DATABASE_URL；完成后释放本次容器。单独运行项目命令时需要显式提供本地环境：
 
 ```bash
@@ -35,7 +44,7 @@ node scripts/project.mjs test:e2e
 node scripts/project.mjs api:generate
 ```
 
-接口：docs/openapi.json；结构：docs/PROJECT.md；规则：AGENTS.md。按需运行 api:generate 更新 TypeScript 客户端类型，不在 verify 中修改源码。
+接口：docs/openapi.json；结构：docs/PROJECT.md；规则：AGENTS.md。修改契约后运行 npm run api:generate 更新 TypeScript 类型。npm run api:check 在临时目录重新生成并只读比较，check/verify 自动执行；test:api 同时按 OpenAPI 检查真实响应状态、必填字段和类型。验证不会自动修改源码。
 
 ## 认证边界
 

package/templates/next-fullstack-antd/THIRD_PARTY_NOTICES.md

@@ -12,3 +12,7 @@ Templates are maintained derivatives, not unmodified upstream distributions. Exa
 | Ant Design | npm 6.6.6 | Installed dependency; no copied source | MIT (package license) |
 
 Package dependencies carry their own licenses. Generated apps include these notices; template authors must carry applicable notices when changing upstream-derived files. Names and marks remain their respective owners'.
+
+## Design and workflow reference
+
+VinkyDev/vibestart at commit `5768fc561340422bf7736499fe69b1aae263790a` (MIT) informed the preview, task-oriented Agent guidance, quick checks and template-layer collision rules. These changes are independently implemented for Agent Scaffold; no VibeStart source, bundled skills, branding or UI assets are redistributed. The source review and selected adaptations are recorded in docs/reference/VIBESTART-REVIEW.md.

package/templates/next-fullstack-antd/docs/PROJECT.md

@@ -7,3 +7,26 @@
 project.json 标识技术栈和 UI；web/ 是界面或 Next 全栈应用；独立后端位于 backend/。scripts/project.mjs 提供实际安装、开发、测试、构建命令。数据库结构以迁移为准，接口见 docs/openapi.json 和生成的 docs/api.d.ts。
 
 后续需求在团队已有权威来源或本文记录，不要求接入特定任务平台。名称和简介来自创建输入，修改 project.json 可更新界面展示。
+
+
+## 从任务找到改动位置
+
+先核对 project.json 的实际技术栈；以下路径只描述本项目。读取命中的实现和调用方后再修改，不将基础示例自动扩展成用户未要求的业务。
+
+| 任务 | 入口 | 改动约束 |
+| --- | --- | --- |
+| 页面交互 | `web/src/App.tsx`、`web/src/workspace-model.ts` | 业务状态放模型，页面负责绑定；身份结束时清空用户数据。 |
+| 设计与组件 | `DESIGN.md`、`design/`、`web/src/ui.tsx` | 先改共享设计意图，再改适配器；按 design-contract 执行同步与浏览器检查。 |
+| API 与身份隔离 | `web/app/api/`、`web/lib/auth.ts`、`web/lib/api.ts` | 保留 Better Auth Session、同源写入检查及按用户查询。 |
+| 模型与迁移 | `web/prisma/schema.prisma`、`web/prisma/migrations/` | 新增 Prisma 迁移，保留已经运行过的迁移。 |
+| 后端回归 | `web/lib/session.test.ts`、`web/lib/validation.test.ts` | Session 失效与验证分支有原生回归；HTTP 行为另由契约测试覆盖。 |
+| HTTP 契约 | `docs/openapi.json`、`docs/api.d.ts`、`tests/contract.spec.ts` | 修改输入输出时同步契约与真实 HTTP 回归；用 api:generate 生成类型。 |
+| 用户流程 | `tests/ui.spec.ts` | 覆盖真实操作、持久化和失败反馈，测试仅使用专用数据。 |
+| 启动与依赖 | `package.json`、`scripts/project.mjs`、`compose.yaml` | 使用锁文件和项目命令；配置、账号及运行报告留在本地。 |
+
+## 修改与验证
+
+1. 将当前需求转成可观察行为与失败场景，复用现有契约和测试入口。
+2. 做能贯通当前需求的最小改动，先运行相关检查；`npm run check` 按类型、Lint、构建快速失败。
+3. API、数据、认证或完整交付使用 README 中的 `verify`，它创建隔离数据库执行原生/API/浏览器检查。UI 还需运行设计契约检查。
+4. 查看差异并报告实际结果。类型或构建通过不等于业务通过；历史报告为 STALE 时按当前内容复验。