spec-canon 0.1.12 → 0.1.14

package/README.md

@@ -12,6 +12,8 @@ SpecCanon 是一套面向 AI Coding Agent（如 Claude Code）的 **Spec-Driven
 
 核心理念：**先文档后代码，人做判断题，AI 做填空题。**
 
+AI 编程工具本质上是一个把结构化 Spec 转成实现代码的高效转换器。Spec 越清晰、越完整，AI 就越能稳定地产出与系统现状一致、与变更目标对齐的可运行代码。
+
 SpecCanon 的本质是一个**文档状态机**：每份 Spec 文档是一个状态节点，状态转移由人触发，AI 负责生成状态内容。通过持续维护 Domain Spec 作为系统行为的单一事实来源（Single Source of Truth），让 AI 在每次开发时都拥有准确的系统全景。
 
 ## 核心机制
@@ -50,14 +52,21 @@ domain_spec.md（演化更新）
 
 ## 安装
 
+你可以直接运行最新版，也可以先全局安装后再使用 `spec-canon`：
+
+```bash
+npx spec-canon@latest init
+```
+
 ```bash
 npm install -g spec-canon
+spec-canon init
 ```
 
-或直接通过 `npx` 使用（无需全局安装）：
+如果只想先查看命令，也可以运行：
 
 ```bash
-npx spec-canon --help
+npx spec-canon@latest --help
 ```
 
 ## 快速开始
@@ -66,7 +75,7 @@ npx spec-canon --help
 → 阅读 [guide/04_new_project_sop.md](docs/guide/04_new_project_sop.md)，然后使用 `spec-canon prompt guide` 查看决策树
 
 ### 我要在已有项目中开发新需求
-→ 先运行 `spec-canon change start --goal ...` 建立 active change（待命名状态），运行 `ctx` 后 AI 会建议 change 名，再用 `change start -g <goal> -c <name>` 确认命名；然后用 `spec-canon change next` 查看候选步骤
+→ 若暂时还没想好 change 名，先运行 `spec-canon change start --goal ...` 建立 active change（待命名状态）；运行 `ctx` 后 AI 会给出命名建议，再由你确认或修改后执行 `change start -g <goal> -c <name>` 记录命名。若一开始就已明确 change 名，且确认其中序号就是当前 next seq，也可直接使用 `-g -c`；然后用 `spec-canon change next` 查看候选步骤
 
 ### 我要为已有项目引入 SDD
 → 阅读 [guide/05_iterative_project_sop.md](docs/guide/05_iterative_project_sop.md) 的冷启动策略，然后使用 `spec-canon prompt list --stage iterative`
@@ -76,9 +85,11 @@ npx spec-canon --help
 
 ## 常用命令
 
+未全局安装时，把下面的 `spec-canon` 替换为 `npx spec-canon@latest`。
+
 ```bash
 spec-canon init
-spec-canon init --domain auth
+spec-canon domain create auth
 spec-canon sync                    # 给已初始化项目安全补齐新骨架
 spec-canon change start -g @docs/prd.md
 spec-canon change status
@@ -104,7 +115,7 @@ docs/
 ├── SOP.md                    ← 导航索引（入口）
 ├── guide/                    ← 方法论（一次性阅读）
 │   ├── 00_introduction.md        SDD 框架综合介绍（对外发布用）
-│   ├── 01_claude_md.md           CLAUDE.md 书写指南
+│   ├── 01_claude_md.md           AI 配置文件指南（CLAUDE.md / AGENTS.md）
 │   ├── 02_spec_overview.md       三层文档体系总览
 │   ├── 03_spec_documents.md      各文档详解
 │   ├── 04_new_project_sop.md     新项目 SOP

package/dist/commands/change.js

@@ -2,7 +2,7 @@ import { join, resolve } from 'node:path';
 import { ActiveChangeError, clearActiveChange, getActiveChangeProgress, ensureSddRoot, getActiveChangeStatus, getChangeDir, readActiveChange, writeActiveChange, } from '../utils/active-change.js';
 import { getChangeSeq, getChangeType, getNextChangeSeq, isValidChangeName, } from '../utils/change.js';
 import { buildChangeNextPlan } from '../utils/change-next.js';
-import { ensureDir } from '../utils/fs.js';
+import { ensureDir, fileExists } from '../utils/fs.js';
 import { logger } from '../utils/logger.js';
 export function registerChangeCommand(program) {
     const change = program
@@ -68,6 +68,17 @@ async function runStart(opts, rootDir) {
         const isIdempotent = existing.goal === opts.goal &&
             existing.change === opts.change;
         if (canConfirmPendingChange) {
+            const requestedSeq = getChangeSeq(opts.change);
+            if (requestedSeq !== existing.changeSeq) {
+                logger.error(`当前 pending active change 的序号是 ${existing.changeSeq}，请使用 <type>-${existing.changeSeq}-<slug>；若不确定 change 名，请先运行 spec-canon prompt show ctx`);
+                process.exitCode = 1;
+                return;
+            }
+            if (await fileExists(getChangeDir(opts.change, rootDir))) {
+                logger.error(`change 目录已存在：spec-canon/changes/${opts.change}。为避免复用旧 change，请改用新的 change 名，或先运行 spec-canon prompt show ctx`);
+                process.exitCode = 1;
+                return;
+            }
             await ensureDir(getChangeDir(opts.change, rootDir));
             await writeActiveChange({
                 ...existing,
@@ -84,12 +95,23 @@ async function runStart(opts, rootDir) {
         process.exitCode = 1;
         return;
     }
+    const nextChangeSeq = await getNextChangeSeq(rootDir);
     const changeSeq = opts.change
         ? getChangeSeq(opts.change)
-        : await getNextChangeSeq(rootDir);
+        : nextChangeSeq;
     const changesDir = join(rootDir, 'spec-canon', 'changes');
     await ensureDir(changesDir);
     if (opts.change) {
+        if (changeSeq !== nextChangeSeq) {
+            logger.error(`change 名中的序号 ${changeSeq} 不是当前可用序号 ${nextChangeSeq}。为避免复用旧 change，请先运行 spec-canon change start -g <goal>，再执行 spec-canon prompt show ctx`);
+            process.exitCode = 1;
+            return;
+        }
+        if (await fileExists(getChangeDir(opts.change, rootDir))) {
+            logger.error(`change 目录已存在：spec-canon/changes/${opts.change}。为避免复用旧 change，请改用新的 change 名，或先运行 spec-canon change start -g <goal> 再执行 spec-canon prompt show ctx`);
+            process.exitCode = 1;
+            return;
+        }
         await ensureDir(getChangeDir(opts.change, rootDir));
     }
     await writeActiveChange({

package/dist/commands/domain.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerDomainCommand(program: Command): void;

package/dist/commands/domain.js

@@ -0,0 +1,38 @@
+import { resolve } from 'node:path';
+import { createDomainScaffold, DomainScaffoldError, } from '../utils/scaffold.js';
+import { logger } from '../utils/logger.js';
+export function registerDomainCommand(program) {
+    const domain = program
+        .command('domain')
+        .description('管理业务域骨架')
+        .option('-d, --dir <path>', '指定 SDD 项目根目录（默认当前目录）');
+    domain
+        .command('create <name>')
+        .description('创建业务域骨架')
+        .action(async (name, _opts, command) => {
+        await runCreate(name, getRootDir(command));
+    });
+}
+async function runCreate(name, rootDir) {
+    try {
+        const result = await createDomainScaffold(rootDir, name);
+        logger.success(`已创建业务域: ${name}`);
+        logger.dim(`  ${result.createdPath}`);
+        if (result.manifestPath) {
+            logger.info(`已更新模板状态清单：${result.manifestPath}`);
+        }
+    }
+    catch (error) {
+        if (error instanceof DomainScaffoldError) {
+            logger.error(error.message);
+            process.exitCode = 1;
+            return;
+        }
+        throw error;
+    }
+}
+function getRootDir(command) {
+    const parent = command.parent;
+    const opts = parent?.opts() ?? {};
+    return resolve(opts.dir ?? process.cwd());
+}

package/dist/commands/init.js

@@ -2,13 +2,13 @@ import { join, resolve } from 'node:path';
 import { loadTemplate } from '../templates/index.js';
 import { fileExists, } from '../utils/fs.js';
 import { logger } from '../utils/logger.js';
-import { SDD_ROOT, TEMPLATE_MANIFEST, buildManagedFiles, ensureBaseScaffoldDirs, reconcileManagedFile, writeTemplateManifest, } from '../utils/scaffold.js';
+import { createDomainScaffold, DomainScaffoldError, SDD_ROOT, TEMPLATE_MANIFEST, buildManagedFiles, ensureBaseScaffoldDirs, reconcileManagedFile, writeTemplateManifest, } from '../utils/scaffold.js';
 export function registerInitCommand(program) {
     program
         .command('init')
         .description('初始化 SDD 文档结构')
         .option('-d, --dir <path>', '目标项目目录', process.cwd())
-        .option('--domain <name>', '同时创建初始业务域')
+        .option('--domain <name>', '兼容入口：同时创建初始业务域（推荐改用 spec-canon domain create）')
         .option('--force', '覆盖已存在的 spec-canon 目录', false)
         .action(async (opts) => {
         await runInit(opts);
@@ -31,10 +31,9 @@ async function runInit(opts) {
     await ensureBaseScaffoldDirs(targetDir);
     const managedFiles = await buildManagedFiles(targetDir, {
         includeClaude: true,
-        extraDomains: opts.domain ? [opts.domain] : [],
     });
     for (const file of managedFiles) {
-        const overwriteExisting = file.relativePath !== 'CLAUDE.md';
+        const overwriteExisting = file.relativePath !== 'CLAUDE.md' && file.relativePath !== 'AGENTS.md';
         const status = await reconcileManagedFile(targetDir, file, {
             overwriteExisting,
         });
@@ -43,21 +42,44 @@ async function runInit(opts) {
             created.push(file.relativePath);
         }
     }
+    const AI_CONFIG_FILES = ['CLAUDE.md', 'AGENTS.md'];
     const sddSection = await loadTemplate('claude-md-section.md');
-    const claudeStatus = statuses.find((status) => status.relativePath === 'CLAUDE.md');
-    if (claudeStatus?.state !== 'created') {
-        logger.warn('CLAUDE.md 已存在，请手动将以下 SDD 协议段添加到文件中：');
+    const createdFiles = AI_CONFIG_FILES.filter((name) => statuses.find((s) => s.relativePath === name)?.state === 'created');
+    const existingFiles = AI_CONFIG_FILES.filter((name) => statuses.find((s) => s.relativePath === name)?.state !== 'created');
+    if (existingFiles.length > 0) {
+        logger.warn(`${existingFiles.join(' / ')} 已存在，请手动将以下 SDD 协议段添加到文件中：`);
         logger.blank();
         logger.dim('─'.repeat(60));
         console.log(sddSection);
         logger.dim('─'.repeat(60));
         logger.blank();
     }
-    else {
-        logger.success('已创建 CLAUDE.md（含 SDD 协议段）');
+    if (createdFiles.length > 0) {
+        logger.success(`已创建 ${createdFiles.join(' + ')}（含 SDD 协议段）`);
     }
     if (opts.domain) {
-        logger.success(`已创建业务域: ${opts.domain}`);
+        try {
+            const result = await createDomainScaffold(targetDir, opts.domain, {
+                writeManifest: false,
+                allowExisting: opts.force,
+                overwriteExisting: opts.force,
+            });
+            if (result.status.state === 'created') {
+                created.push(result.createdPath);
+            }
+            statuses.push(result.status);
+            logger.success(result.status.state === 'created'
+                ? `已创建业务域: ${opts.domain}`
+                : `已刷新业务域: ${opts.domain}`);
+        }
+        catch (error) {
+            if (error instanceof DomainScaffoldError) {
+                logger.error(error.message);
+                process.exitCode = 1;
+                return;
+            }
+            throw error;
+        }
     }
     const manifestAbsolutePath = join(targetDir, SDD_ROOT, TEMPLATE_MANIFEST);
     const manifestExisted = await fileExists(manifestAbsolutePath);
@@ -75,5 +97,16 @@ async function runInit(opts) {
         logger.dim(`  ${file}`);
     }
     logger.blank();
-    logger.info('下一步：编辑 CLAUDE.md 填写项目信息，然后开始你的第一个变更');
+    logger.info(opts.domain
+        ? '下一步：编辑 CLAUDE.md（及 AGENTS.md）填写项目信息，然后开始你的第一个变更'
+        : `下一步：编辑 CLAUDE.md（及 AGENTS.md）填写项目信息；如需先建业务域，运行 ${formatDomainCreateCommand(targetDir)}`);
+}
+function formatDomainCreateCommand(targetDir) {
+    if (targetDir === process.cwd()) {
+        return 'spec-canon domain create <name>';
+    }
+    return `spec-canon domain -d ${quoteShellArg(targetDir)} create <name>`;
+}
+function quoteShellArg(value) {
+    return JSON.stringify(value);
 }

package/dist/commands/sync.js

@@ -97,7 +97,7 @@ export function formatManualReviewItem(item, targetDir) {
         lines.push(`    建议命令: cp ${quotedTemplatePath} ${quotedTargetPath}`);
     }
     if (item.compareMode === 'merge-section') {
-        lines.push('    CLAUDE.md 只需按需合并 SDD 协议段，无需整文件覆盖');
+        lines.push(`    ${item.path} 只需按需合并 SDD 协议段，无需整文件覆盖`);
     }
     return lines;
 }

package/dist/index.js

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
 import updateNotifier from 'update-notifier';
 import { registerChangeCommand } from './commands/change.js';
+import { registerDomainCommand } from './commands/domain.js';
 import { registerInitCommand } from './commands/init.js';
 import { registerPromptCommand } from './commands/prompt.js';
 import { registerSyncCommand } from './commands/sync.js';
@@ -12,6 +13,7 @@ program
     .description('CLI toolkit for Spec-Driven Development (SDD)')
     .version(CLI_VERSION);
 registerInitCommand(program);
+registerDomainCommand(program);
 registerChangeCommand(program);
 registerPromptCommand(program);
 registerSyncCommand(program);

package/dist/utils/scaffold.d.ts

@@ -47,6 +47,8 @@ export interface SyncReport {
 }
 export declare class ScaffoldSyncError extends Error {
 }
+export declare class DomainScaffoldError extends Error {
+}
 export declare function ensureBaseScaffoldDirs(rootDir: string): Promise<void>;
 export declare function loadClaudeSection(): Promise<string>;
 export declare function buildManagedFiles(rootDir: string, opts?: {
@@ -60,3 +62,12 @@ export declare function reconcileManagedFile(rootDir: string, file: ManagedFileD
 export declare function inspectManagedFile(rootDir: string, file: ManagedFileDefinition): Promise<ManagedFileStatus>;
 export declare function writeTemplateManifest(rootDir: string, files: ManagedFileDefinition[], statuses: ManagedFileStatus[]): Promise<string>;
 export declare function syncScaffold(rootDir: string): Promise<SyncReport>;
+export declare function createDomainScaffold(rootDir: string, domain: string, opts?: {
+    writeManifest?: boolean;
+    allowExisting?: boolean;
+    overwriteExisting?: boolean;
+}): Promise<{
+    createdPath: string;
+    status: ManagedFileStatus;
+    manifestPath?: string;
+}>;

package/dist/utils/scaffold.js

@@ -21,8 +21,12 @@ const BASE_DIRS = [
 ];
 const RULES_FILE = join(SDD_ROOT, 'rules', 'RULES.md');
 const LEGACY_RULES_FILE = join(SDD_ROOT, 'skills', 'SKILL.md');
+const LEGACY_RULES_H1 = '# SKILLS.md — 团队规则库';
+const RULES_H1 = '# RULES.md — 团队规则库';
 export class ScaffoldSyncError extends Error {
 }
+export class DomainScaffoldError extends Error {
+}
 export async function ensureBaseScaffoldDirs(rootDir) {
     for (const dir of BASE_DIRS) {
         await ensureDir(join(rootDir, dir));
@@ -69,10 +73,17 @@ export async function buildManagedFiles(rootDir, opts = {}) {
         manualReviewReason: 'spec-canon/domains/README.md 是持续演化的活文档，当前内容与 CLI 初始基线存在差异，已保留，可按需参考基线结构手动比对',
     });
     if (opts.includeClaude) {
+        const aiConfigContent = await buildClaudeMdContent();
+        addManagedFile(files, {
+            relativePath: 'AGENTS.md',
+            sourceId: 'generated:agents-md',
+            desiredContent: aiConfigContent,
+            manualReviewReason: 'AGENTS.md 是用户自定义项目说明文件，CLI 未自动改写；如需吸收新版 SDD 协议，请手动合并当前 CLI 提供的协议段基线',
+        });
         addManagedFile(files, {
             relativePath: 'CLAUDE.md',
             sourceId: 'generated:claude-md',
-            desiredContent: await buildClaudeMdContent(),
+            desiredContent: aiConfigContent,
             manualReviewReason: 'CLAUDE.md 是用户自定义项目说明文件，CLI 未自动改写；如需吸收新版 SDD 协议，请手动合并当前 CLI 提供的协议段基线',
         });
     }
@@ -112,6 +123,16 @@ export async function reconcileManagedFile(rootDir, file, opts = {}) {
 }
 export async function inspectManagedFile(rootDir, file) {
     const absolutePath = join(rootDir, file.relativePath);
+    if (!(await fileExists(absolutePath))) {
+        return {
+            relativePath: file.relativePath,
+            sourceId: file.sourceId,
+            templateHash: hashContent(file.desiredContent),
+            fileHash: hashContent(''),
+            state: 'preserved',
+            manualReviewReason: file.manualReviewReason,
+        };
+    }
     const currentContent = await readFileSafe(absolutePath);
     const state = currentContent === file.desiredContent
         ? 'unchanged'
@@ -186,6 +207,35 @@ export async function syncScaffold(rootDir) {
         manifestPath,
     };
 }
+export async function createDomainScaffold(rootDir, domain, opts = {}) {
+    const sddDir = join(rootDir, SDD_ROOT);
+    if (!(await fileExists(sddDir))) {
+        throw new DomainScaffoldError('未找到 spec-canon/ 目录，请先运行 spec-canon init');
+    }
+    const domainDir = join(rootDir, SDD_ROOT, 'domains', domain);
+    const domainExists = await fileExists(domainDir);
+    if (domainExists && !opts.allowExisting) {
+        throw new DomainScaffoldError(`业务域已存在：${domain}`);
+    }
+    const createdPath = join(SDD_ROOT, 'domains', domain, 'domain_spec.md');
+    const files = await buildManagedFiles(rootDir, {
+        includeClaude: true,
+        includeExistingDomains: true,
+        extraDomains: [domain],
+    });
+    const domainFile = files.find((file) => file.relativePath === createdPath);
+    if (!domainFile) {
+        throw new DomainScaffoldError(`未找到业务域骨架定义：${createdPath}`);
+    }
+    const status = await reconcileManagedFile(rootDir, domainFile, {
+        overwriteExisting: opts.overwriteExisting ?? false,
+    });
+    if (opts.writeManifest === false) {
+        return { createdPath, status };
+    }
+    const manifestPath = await writeTemplateManifest(rootDir, files, [status]);
+    return { createdPath, status, manifestPath };
+}
 async function buildClaudeMdContent() {
     const sddSection = await loadClaudeSection();
     return `${DEFAULT_CLAUDE_MD}\n${sddSection}`;
@@ -218,7 +268,7 @@ function buildManualReviewItem(status) {
         item.compareMode = 'full-file';
         return item;
     }
-    if (status.sourceId === 'generated:claude-md') {
+    if (status.sourceId === 'generated:claude-md' || status.sourceId === 'generated:agents-md') {
         item.sourceKind = 'baseline';
         item.templatePath = getTemplatePath('claude-md-section.md');
         item.compareMode = 'merge-section';
@@ -236,7 +286,8 @@ async function applyLegacyRulesCompatibility(rootDir) {
     }
     const rulesExists = await fileExists(rulesPath);
     if (!rulesExists) {
-        await writeFileSafe(rulesPath, await readFileSafe(legacyRulesPath));
+        const legacyRulesContent = await readFileSafe(legacyRulesPath);
+        await writeFileSafe(rulesPath, normalizeLegacyRulesContent(legacyRulesContent));
         migrated.push({
             path: RULES_FILE,
             fromPath: LEGACY_RULES_FILE,
@@ -251,21 +302,26 @@ async function applyLegacyRulesCompatibility(rootDir) {
             compareMode: 'full-file',
         });
     }
-    const claudePath = join(rootDir, 'CLAUDE.md');
-    if (!(await fileExists(claudePath))) {
-        return { migrated, manualReview };
-    }
-    const claudeContent = await readFileSafe(claudePath);
-    if (!containsLegacyRulesReference(claudeContent)) {
-        return { migrated, manualReview };
+    const aiConfigFiles = [
+        { path: 'CLAUDE.md', name: 'CLAUDE.md' },
+        { path: 'AGENTS.md', name: 'AGENTS.md' },
+    ];
+    for (const file of aiConfigFiles) {
+        const filePath = join(rootDir, file.path);
+        if (!(await fileExists(filePath))) {
+            continue;
+        }
+        const content = await readFileSafe(filePath);
+        if (containsLegacyRulesReference(content)) {
+            manualReview.push({
+                path: file.name,
+                reason: `${file.name} 中仍引用旧规则路径，请将 spec-canon/skills/SKILL.md 更新为 spec-canon/rules/RULES.md`,
+                sourceKind: 'baseline',
+                templatePath: getTemplatePath('claude-md-section.md'),
+                compareMode: 'merge-section',
+            });
+        }
     }
-    manualReview.push({
-        path: 'CLAUDE.md',
-        reason: 'CLAUDE.md 中仍引用旧规则路径，请将 spec-canon/skills/SKILL.md 更新为 spec-canon/rules/RULES.md',
-        sourceKind: 'baseline',
-        templatePath: getTemplatePath('claude-md-section.md'),
-        compareMode: 'merge-section',
-    });
     return { migrated, manualReview };
 }
 function containsLegacyRulesReference(content) {
@@ -275,6 +331,16 @@ function containsLegacyRulesReference(content) {
         'spec-canon/skills/SKILL.md',
     ].some((pattern) => content.includes(pattern));
 }
+function normalizeLegacyRulesContent(content) {
+    if (content === LEGACY_RULES_H1) {
+        return RULES_H1;
+    }
+    const legacyHeadingWithNewline = `${LEGACY_RULES_H1}\n`;
+    if (content.startsWith(legacyHeadingWithNewline)) {
+        return `${RULES_H1}${content.slice(LEGACY_RULES_H1.length)}`;
+    }
+    return content;
+}
 function hashContent(content) {
     return createHash('sha256').update(content).digest('hex');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-canon",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "CLI toolkit for Spec-Driven Development (SDD)",
   "type": "module",
   "license": "MIT",

package/templates/claude-md-section.md

@@ -3,6 +3,7 @@
 ### 角色定义
 你是一名遵循 Spec-Driven Development 协议的高级工程师。
 核心原则：**先文档后代码，人做判断题，AI 做填空题。**
+AI 编程工具本质上是把结构化 Spec 转成实现代码的高效转换器。编码时应以 Spec 为主输入，不应以零散对话替代；若 Spec 不清晰，先补齐或澄清，再进入实现。
 
 ### 核心规则
 - **Context First**：编码前，必须先阅读 `spec-canon/` 下对应的 Spec 文件
@@ -65,9 +66,10 @@ domain_spec 生命周期：变更启动时由 AI 从 change goal 出发，结合
 
 ```bash
 spec-canon sync                          # 给已初始化项目安全补齐 SDD 骨架
+spec-canon domain create checkin         # 显式创建业务域骨架
 spec-canon change start -g @docs/prd.md   # 建立当前 active change（待命名）
-# → 运行 ctx 后 AI 建议 change 名
-spec-canon change start -g @docs/prd.md -c feat-001-checkin  # 确认命名
+# → 运行 ctx 后 AI 会给出命名建议；由你确认或修改后再记录
+spec-canon change start -g @docs/prd.md -c feat-001-checkin  # 确认命名；若名称已明确且序号就是当前 next seq，也可首次直接使用
 spec-canon change status                  # 查看当前进度与推荐下一步
 spec-canon change next                    # 查看当前候选 next prompts
 spec-canon change -d /path status         # 指定目标项目目录

package/templates/prompts/guide.md

@@ -21,12 +21,13 @@
 
 ## 全新项目
 
-1. 运行 `spec-canon init --domain <首个业务域名>` 初始化项目结构
-2. 使用 `change start --goal -c <name>` 建立 active change（新项目跳过 ctx，直接命名）
-3. 可先用 `change next` 查看当前候选步骤
-4. 使用 `req` 生成 01_requirement.md（人工审阅 AC 并 Sign-off）
-5. 依次使用 `iface` → `impl-spec` → `test-spec` → `impl` → `review` 完成首个变更
-6. 使用 `domain-sync` 创建首份 domain_spec（人工审阅后写入；可省略 `-d` 自动发现受影响域）
+1. 运行 `spec-canon init` 初始化项目结构
+2. 运行 `spec-canon domain create <首个业务域名>` 创建首个业务域
+3. 使用 `change start --goal -c <name>` 建立 active change（新项目跳过 ctx，首个 change 通常可直接命名）
+4. 可先用 `change next` 查看当前候选步骤
+5. 使用 `req` 生成 01_requirement.md（人工审阅 AC 并 Sign-off）
+6. 依次使用 `iface` → `impl-spec` → `test-spec` → `impl` → `review` 完成首个变更
+7. 使用 `domain-sync` 创建首份 domain_spec（人工审阅后写入；可省略 `-d` 自动发现受影响域）
 
 > 新项目没有既有系统，00_context（系统现状）无需生成。架构决策自然归入 `impl-spec`（03_implementation）的 Design Decision 段。
 
@@ -39,8 +40,8 @@
 1. 运行 `spec-canon init` 初始化结构
 2. 使用 `change start --goal` 建立 active change
 3. 可先用 `change next` 查看当前候选步骤
-4. 使用 `ctx` 生成 00_context.md，AI 自动识别主域并建议 change 名
-5. 用 `change start -g <goal> -c <name>` 确认命名
+4. 使用 `ctx` 生成 00_context.md，AI 自动识别主域并给出 change 名建议
+5. 用 `change start -g <goal> -c <name>` 记录确认后的 change 名（可采纳或修改 AI 建议）
 6. 按日常流程完成变更（req → iface → impl-spec → test-spec → impl → review）
 7. 在 Archive 步骤使用 `domain-sync` 创建首份 domain_spec（可省略 `-d` 自动发现受影响域）
 
@@ -70,7 +71,7 @@
 | Step -1 | `change start --goal` | 建立 active change | 确认 goal 描述准确；若未确认 change 名，先接受待命名状态 |
 | Step -0.5 | `change next` | 查看候选 next prompts | 关注默认宽松模式下保留的 `iface` / `domain-sync` 候选，自己做判断 |
 | Step 0 | `ctx` | 生成 00_context.md | 审阅系统现状快照，确认 AI 自动识别的域、模块和待补充项 |
-| Step 0.5 | `change start -g <goal> -c <name>` | 确认 change 名 | AI 在 ctx 中建议的名称是否准确 |
+| Step 0.5 | `change start -g <goal> -c <name>` | 确认 change 名 | 采纳或修改 ctx 给出的建议；若名称已明确且序号就是当前 next seq，也可一开始直接用 `-g -c` |
 | Step 1 | `req` | 生成 01_requirement.md | 审阅 AC，Sign-off |
 | Step 2 | `iface` → `impl-spec` → `test-spec` | 生成 02/03/04 文档 | 审阅文件路径、步骤顺序 |
 | Step 3 | `impl` | 分步编码 | 逐步确认 |