@gordon.gan/specflow 1.2.0-beta → 1.2.0-beta.1

package/README.md

@@ -14,8 +14,10 @@ SpecFlow 把 **OpenSpec**（结构化需求规划）和 **Superpowers**（TDD、
 | Cursor | `specflow:propose` 等命令 | [Cursor 指南](./CURSOR_PACKAGING_AND_USAGE_GUIDE.md) |
 | OpenAI Codex | `$specflow-propose` 等技能 | [Codex 指南](./CODEX_PACKAGING_AND_USAGE_GUIDE.md) |
 | 多语言 / Go Profile | SpecFlow + 语言专项 skills | [语言 Profile 指南](./LANGUAGE_PROFILE_USAGE_GUIDE.md) |
-| 多仓 / 前后端一体需求 | Contract Hub + Spokes + 产物说明 | [多仓完整指南](./MULTI_REPO_GUIDE.md) |
+| 多仓 / 前后端一体需求（**权威**） | Contract Hub + Spokes + 产物与 CLI | [多仓完整指南](./MULTI_REPO_GUIDE.md) |
 | 多仓原生能力（设计） | Store / References / Workset | [多仓技术方案](./MULTI_REPO_TECHNICAL_DESIGN.md) |
+| 多仓场景示例（TALOS） | contracts + api + web 实操路径 | [TALOS 多仓教程](./TALOS_MULTI_REPO_TUTORIAL.md) |
+| TALOS 公共需求详例 | 工作区邀请成员（Hub→BE→FE→联调） | [公共需求 Walkthrough](./docs/TALOS_SHARED_REQUIREMENT_WALKTHROUGH.md) |
 | 产物与作用 | explore / proposal / delta / design / tasks / 主 specs | [产物说明](./SPECFLOW_ARTIFACTS.md) |
 
 ---
@@ -115,7 +117,7 @@ npm install -g @gordon.gan/specflow
 npm install -g github:Gordon-Gan-Jiang/specflow
 
 # 验证
-specflow --version   # 当前 1.1.0
+specflow --version   # 以 npm / package.json 为准（开发中可见 1.2.0-beta）
 specflow --help
 ```
 
@@ -130,13 +132,32 @@ cd specflow && npm install && npm run build && npm link
 
 ```bash
 cd your-project
-specflow init              # 默认：Claude + Cursor
-specflow init --ide codex  # 仅 Codex
-specflow init --ide all    # Claude + Cursor + Codex
+specflow init                                  # 默认：Claude + Cursor，英文产物
+specflow init --artifact-language zh-CN        # 简体中文产物
+specflow init --artifact-language zh           # zh 是 zh-CN 的 CLI 别名
+specflow init --ide codex                      # 仅 Codex
+specflow init --ide all --artifact-language en # Claude + Cursor + Codex
 ```
 
 init 会创建 `specflow/` 目录、写入 `config.yaml`，并按 `--ide` 生成对应托管资产（skills、commands、prompts 等），同时幂等地追加 `.gitignore` 忽略可再生的 prompts/schemas/templates。
 
+产物语言保存在项目配置中：
+
+```yaml
+schema: specflow
+
+artifacts:
+  language: zh-CN # en | zh-CN；未配置时默认为 en
+```
+
+语言配置控制 proposal、spec、design、tasks 等产物的自然语言叙述。SpecFlow
+解析依赖的 `ADDED Requirements`、`Requirement:`、`Scenario:`、`WHEN`、`THEN`
+等协议标记始终保持英文；capability ID、change name、路径、命令和代码也不会翻译。
+
+`init` 对已有 `specflow/config.yaml` 永不覆盖，包括使用
+`--force-assets` 或传入不同的 `--artifact-language`。已有项目需要直接编辑
+`artifacts.language`；修改只影响后续新建或主动重写的内容，不会自动翻译历史产物。
+
 ### 跑通第一个变更
 
 **需求已清晰：**
@@ -247,7 +268,7 @@ CLI 从当前目录**向上查找**项目根（识别 `specflow/config.yaml`）
 
 | 命令 | 说明 |
 |------|------|
-| `specflow init [--ide claude\|cursor\|codex\|both\|all]` | 初始化项目目录与 IDE 托管资产 |
+| `specflow init [--ide claude\|cursor\|codex\|both\|all] [--artifact-language en\|zh-CN]` | 初始化项目目录、产物语言与 IDE 托管资产；`zh` 是 `zh-CN` 的别名 |
 | `specflow sync [--ide ...] [--no-parity-strict]` | 从已安装的 specflow 包同步/更新 IDE 资产（升级后用） |
 | `specflow doctor [--parity] [--json]` | 诊断 IDE 资产是否完整、迁移状态是否正常 |
 | `specflow parity-report [--json]` | 对比 Claude / Cursor / Codex 能力是否一致 |
@@ -393,11 +414,10 @@ specflow doctor --parity
 specflow parity-report
 ```
 
-重新初始化（init 检测到已初始化会拒绝，需先删除 `specflow/config.yaml` 等标记文件）：
+刷新已初始化项目的托管资产（不会覆盖 `specflow/config.yaml`）：
 
 ```bash
-rm -rf specflow/config.yaml .claude/specflow/   # 按需清理其他 IDE 目录
-specflow init
+specflow init --force-assets --ide all
 ```
 
 ---

package/dist/cli/commands/init.d.ts

@@ -9,6 +9,7 @@ export interface InitResult {
 }
 export interface InitOptions {
     readonly ide?: InitIdeTarget;
+    readonly artifactLanguage?: string;
     readonly forceAssets?: boolean;
     readonly parityStrict?: boolean;
 }

package/dist/cli/commands/init.js

@@ -7,13 +7,19 @@ import { validateReportAgainstManifest } from '../../integrations/shared/parity-
 import { appendManagedBlock } from '../../integrations/shared/marker-write.js';
 import { getRegeneratableIgnoreLines } from '../../integrations/shared/managed-assets.js';
 import { detectMigrationState } from '../../integrations/shared/migration-state.js';
-const CONFIG_YAML = `schema: specflow
+import { DEFAULT_ARTIFACT_LANGUAGE, requireArtifactLanguage, } from '../../core/artifact-language.js';
+function renderConfigYaml(artifactLanguage) {
+    return `schema: specflow
+
+artifacts:
+  language: ${artifactLanguage}
 
 # Project context (customize for your project)
 # context: |
 #   Tech stack: ...
 #   Architecture: ...
 `;
+}
 function findPackageRoot() {
     const currentFile = fileURLToPath(import.meta.url);
     let dir = join(currentFile, '..');
@@ -32,8 +38,8 @@ async function createDirectoryStructure(projectRoot) {
         fs.mkdir(join(projectRoot, 'specflow', 'specs'), { recursive: true }),
     ]);
 }
-async function writeConfig(projectRoot) {
-    await fs.writeFile(join(projectRoot, 'specflow', 'config.yaml'), CONFIG_YAML, 'utf-8');
+async function writeConfig(projectRoot, artifactLanguage) {
+    await fs.writeFile(join(projectRoot, 'specflow', 'config.yaml'), renderConfigYaml(artifactLanguage), 'utf-8');
 }
 async function pathExists(path) {
     try {
@@ -52,6 +58,9 @@ async function hasIdeAssets(projectRoot, ide) {
     return validateReportAgainstManifest(report).ok;
 }
 export async function initProject(projectRoot, packageRoot, options = {}) {
+    const artifactLanguage = options.artifactLanguage === undefined
+        ? DEFAULT_ARTIFACT_LANGUAGE
+        : requireArtifactLanguage(options.artifactLanguage);
     const ide = options.ide ?? 'both';
     const forceAssets = options.forceAssets ?? false;
     const parityStrict = options.parityStrict ?? true;
@@ -60,14 +69,17 @@ export async function initProject(projectRoot, packageRoot, options = {}) {
     const migrationState = await detectMigrationState(projectRoot);
     if (!initialized) {
         await createDirectoryStructure(projectRoot);
-        await writeConfig(projectRoot);
+        await writeConfig(projectRoot, artifactLanguage);
     }
+    const languageEditMessage = options.artifactLanguage
+        ? ' Edit specflow/config.yaml explicitly to change artifact language in an initialized project.'
+        : '';
     const selectedIdeTargets = adapters.map((a) => a.ide);
     const allTargetsHealthy = (await Promise.all(selectedIdeTargets.map((target) => hasIdeAssets(projectRoot, target)))).every(Boolean);
     if (initialized && !forceAssets && allTargetsHealthy) {
         return {
             status: 'already_initialized',
-            message: `Project at ${projectRoot} is already initialized for ide=${ide} (state=${migrationState}). Use --force-assets to refresh managed assets.`,
+            message: `Project at ${projectRoot} is already initialized for ide=${ide} (state=${migrationState}). Use --force-assets to refresh managed assets.${languageEditMessage}`,
         };
     }
     for (const adapter of adapters) {
@@ -86,7 +98,7 @@ export async function initProject(projectRoot, packageRoot, options = {}) {
     return {
         status: initialized ? 'updated_assets' : 'initialized',
         message: initialized
-            ? `Updated ${ide} assets at ${projectRoot}`
+            ? `Updated ${ide} assets at ${projectRoot}.${languageEditMessage}`
             : `Initialized specflow project at ${projectRoot}`,
     };
 }
@@ -102,6 +114,7 @@ export function registerInitCommand(program) {
         .command('init')
         .description('Initialize a project with specflow directory structure and assets')
         .option('--ide <target>', 'Target IDE assets: claude | cursor | codex | both | all', 'both')
+        .option('--artifact-language <language>', 'Artifact content language: en | zh-CN (alias: zh)')
         .option('--force-assets', 'Refresh managed IDE assets even when project is initialized')
         .option('--no-parity-strict', 'Disable strict parity validation after asset generation')
         .action(async (opts) => {
@@ -109,6 +122,7 @@ export function registerInitCommand(program) {
         const packageRoot = findPackageRoot();
         const result = await initProject(projectRoot, packageRoot, {
             ide: opts.ide ?? 'both',
+            artifactLanguage: opts.artifactLanguage,
             forceAssets: opts.forceAssets ?? false,
             parityStrict: opts.parityStrict ?? true,
         });

package/dist/cli/commands/instructions.js

@@ -26,6 +26,7 @@ function readProjectConfig(projectRoot) {
         const projectConfig = parseProjectConfig(parsed);
         const config = {
             context: projectConfig.context,
+            artifactLanguage: projectConfig.artifactLanguage,
             references: projectConfig.references,
         };
         return { schemaName, config: config };
@@ -56,6 +57,7 @@ async function enrichInstructionConfig(projectRoot, options) {
     });
     return {
         context: parsed.context,
+        artifactLanguage: parsed.artifactLanguage,
         referencedStores,
         rootProvenance: {
             source: resolved.source,
@@ -105,9 +107,11 @@ export function registerInstructionsCommand(program) {
             }
             console.info(`Generates: ${instructions.generates}`);
             console.info(`Description: ${instructions.description}`);
+            console.info(`Artifact language: ${instructions.artifactLanguage}`);
             if (instructions.instruction) {
                 console.info(`\nInstruction:\n${instructions.instruction}`);
             }
+            console.info(`\n${instructions.languageGuidance}`);
             const referenceGuidance = collectReferenceGuidance({ referencedStores: instructions.referencedStores });
             const guidance = referenceGuidance.claude;
             if (guidance) {

package/dist/core/artifact-graph/instruction-loader.d.ts

@@ -1,6 +1,7 @@
 import type { SchemaYaml } from './types.js';
 import type { Diagnostic } from '../diagnostics.js';
 import type { RootSource } from '../root-selection.js';
+import { type ArtifactLanguage } from '../artifact-language.js';
 /**
  * Dependency information included in artifact instructions.
  */
@@ -29,6 +30,10 @@ export interface ArtifactInstructions {
     readonly instruction: string | undefined;
     /** Project context from the config */
     readonly context: string | undefined;
+    /** Canonical language for human-readable artifact content */
+    readonly artifactLanguage: ArtifactLanguage;
+    /** Rendered generation policy for the selected artifact language */
+    readonly languageGuidance: string;
     /** Separately budgeted referenced-store index */
     readonly referencedStores?: ReferencedStoresSection;
     /** Selected planning root provenance */
@@ -45,6 +50,7 @@ export interface ArtifactInstructions {
  */
 export interface ProjectConfig {
     readonly context?: string;
+    readonly artifactLanguage?: ArtifactLanguage;
     readonly referencedStores?: ReferencedStoresSection;
     readonly rootProvenance?: RootProvenanceSection;
     readonly [key: string]: unknown;

package/dist/core/artifact-graph/instruction-loader.js

@@ -1,3 +1,4 @@
+import { DEFAULT_ARTIFACT_LANGUAGE, renderArtifactLanguageGuidance, } from '../artifact-language.js';
 /**
  * Loads enriched instructions for creating an artifact.
  *
@@ -14,9 +15,12 @@ export function loadInstructions(artifactId, changeDir, schema, config) {
         throw new Error(`Artifact '${artifactId}' not found in schema '${schema.name}'`);
     }
     const dependencies = buildDependencyInfo(artifact, schema);
+    const artifactLanguage = config?.artifactLanguage ?? DEFAULT_ARTIFACT_LANGUAGE;
     return {
         instruction: artifact.instruction,
         context: config?.context ?? undefined,
+        artifactLanguage,
+        languageGuidance: renderArtifactLanguageGuidance(artifactLanguage),
         referencedStores: config?.referencedStores,
         rootProvenance: config?.rootProvenance,
         dependencies,

package/dist/core/artifact-graph/types.d.ts

@@ -78,7 +78,6 @@ export declare const SchemaYamlSchema: z.ZodObject<{
     }>>;
 }, "strip", z.ZodTypeAny, {
     version: number;
-    name: string;
     artifacts: {
         id: string;
         generates: string;
@@ -86,6 +85,7 @@ export declare const SchemaYamlSchema: z.ZodObject<{
         requires: string[];
         instruction?: string | undefined;
     }[];
+    name: string;
     apply?: {
         requires: string[];
         instruction?: string | undefined;
@@ -94,7 +94,6 @@ export declare const SchemaYamlSchema: z.ZodObject<{
     description?: string | undefined;
 }, {
     version: number;
-    name: string;
     artifacts: {
         id: string;
         generates: string;
@@ -102,6 +101,7 @@ export declare const SchemaYamlSchema: z.ZodObject<{
         instruction?: string | undefined;
         requires?: string[] | undefined;
     }[];
+    name: string;
     apply?: {
         requires: string[];
         instruction?: string | undefined;

package/dist/core/artifact-language.d.ts

@@ -0,0 +1,7 @@
+export declare const ARTIFACT_LANGUAGES: readonly ["en", "zh-CN"];
+export type ArtifactLanguage = (typeof ARTIFACT_LANGUAGES)[number];
+export declare const DEFAULT_ARTIFACT_LANGUAGE: ArtifactLanguage;
+export declare function isArtifactLanguage(value: unknown): value is ArtifactLanguage;
+export declare function normalizeArtifactLanguage(value: unknown): ArtifactLanguage | undefined;
+export declare function requireArtifactLanguage(value: unknown): ArtifactLanguage;
+export declare function renderArtifactLanguageGuidance(language: ArtifactLanguage): string;

package/dist/core/artifact-language.js

@@ -0,0 +1,33 @@
+export const ARTIFACT_LANGUAGES = ['en', 'zh-CN'];
+export const DEFAULT_ARTIFACT_LANGUAGE = 'en';
+export function isArtifactLanguage(value) {
+    return value === 'en' || value === 'zh-CN';
+}
+export function normalizeArtifactLanguage(value) {
+    if (value === 'zh') {
+        return 'zh-CN';
+    }
+    return isArtifactLanguage(value) ? value : undefined;
+}
+export function requireArtifactLanguage(value) {
+    const language = normalizeArtifactLanguage(value);
+    if (language) {
+        return language;
+    }
+    throw new Error(`Unsupported artifact language ${JSON.stringify(value)}. Supported values: en, zh-CN (alias: zh).`);
+}
+export function renderArtifactLanguageGuidance(language) {
+    const narrativeLanguage = language === 'zh-CN' ? 'Simplified Chinese' : 'English';
+    return [
+        '## Artifact language policy',
+        '',
+        `Write human-readable artifact content in ${narrativeLanguage}.`,
+        '',
+        'Keep SpecFlow protocol markers unchanged, including:',
+        '- `ADDED Requirements`, `MODIFIED Requirements`, `REMOVED Requirements`, and `RENAMED Requirements`',
+        '- `Requirement:`, `Scenario:`, `WHEN`, and `THEN`',
+        '',
+        'Keep capability IDs, change names, file paths, commands, code, and symbols unchanged.',
+        'When modifying an existing requirement, preserve its exact name when delta matching requires it.',
+    ].join('\n');
+}

package/dist/core/project-config.d.ts

@@ -1,4 +1,5 @@
 import type { Diagnostic } from './diagnostics.js';
+import { type ArtifactLanguage } from './artifact-language.js';
 export interface NormalizedReference {
     readonly id: string;
     readonly remote?: string;
@@ -6,6 +7,7 @@ export interface NormalizedReference {
 export interface ParsedProjectConfig {
     readonly schema: string;
     readonly context?: string;
+    readonly artifactLanguage: ArtifactLanguage;
     readonly store?: string;
     readonly references: readonly NormalizedReference[];
     readonly diagnostics: readonly Diagnostic[];

package/dist/core/project-config.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { DEFAULT_ARTIFACT_LANGUAGE, isArtifactLanguage, } from './artifact-language.js';
 const KEBAB_CASE_ID = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
 const ReferenceObjectSchema = z
     .object({
@@ -20,6 +21,29 @@ export function parseProjectConfig(raw) {
     const record = typeof raw === 'object' && raw !== null ? raw : {};
     const schema = typeof record.schema === 'string' ? record.schema : 'specflow';
     const context = typeof record.context === 'string' ? record.context : undefined;
+    let artifactLanguage = DEFAULT_ARTIFACT_LANGUAGE;
+    if (record.artifacts !== undefined) {
+        const artifacts = typeof record.artifacts === 'object' &&
+            record.artifacts !== null &&
+            !Array.isArray(record.artifacts)
+            ? record.artifacts
+            : undefined;
+        const configuredLanguage = artifacts?.language;
+        if (!artifacts ||
+            (configuredLanguage !== undefined &&
+                !isArtifactLanguage(configuredLanguage))) {
+            diagnostics.push({
+                severity: 'error',
+                code: 'invalid_artifact_language',
+                message: "Project artifact language must be one of: 'en', 'zh-CN'.",
+                target: 'config.artifacts.language',
+                fix: "Set artifacts.language to 'en' or 'zh-CN'.",
+            });
+        }
+        else if (isArtifactLanguage(configuredLanguage)) {
+            artifactLanguage = configuredLanguage;
+        }
+    }
     let store;
     if (record.store !== undefined) {
         if (typeof record.store === 'string' && KEBAB_CASE_ID.test(record.store)) {
@@ -66,7 +90,14 @@ export function parseProjectConfig(raw) {
             });
         }
     }
-    return { schema, context, store, references, diagnostics };
+    return {
+        schema,
+        context,
+        artifactLanguage,
+        store,
+        references,
+        diagnostics,
+    };
 }
 export function loadProjectConfigFromObject(raw) {
     return parseProjectConfig(raw);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gordon.gan/specflow",
-  "version": "1.2.0-beta",
+  "version": "1.2.0-beta.1",
   "type": "module",
   "description": "SpecFlow — unified spec-driven development: OpenSpec planning + Superpowers execution in one CLI and cross-IDE workflow",
   "keywords": [

package/prompts/shared/artifact-language.md

@@ -0,0 +1,30 @@
+# Artifact Language Policy
+
+Before creating or rewriting any SpecFlow artifact:
+
+1. Read `specflow/config.yaml` from the active planning root.
+2. Resolve `artifacts.language`:
+   - `en` → write human-readable artifact content in English.
+   - `zh-CN` → write human-readable artifact content in Simplified Chinese.
+   - Missing → default to `en`.
+   - Invalid → report the invalid value and use `en`; do not invent another language.
+3. Apply the selected language consistently to narrative prose, requirement and scenario descriptions, design rationale, and task descriptions.
+
+## Protected Protocol
+
+Language selection never changes SpecFlow's machine-readable protocol. Keep these tokens exactly as written:
+
+- `## ADDED Requirements`
+- `## MODIFIED Requirements`
+- `## REMOVED Requirements`
+- `## RENAMED Requirements`
+- `### Requirement:`
+- `#### Scenario:`
+- `- **WHEN**`
+- `- **THEN**`
+- `FROM:`
+- `TO:`
+
+Also preserve capability IDs, change names, file paths, commands, code, symbols, and established technical identifiers.
+
+When modifying an existing requirement, preserve its exact requirement name if delta matching depends on that name. Do not translate historical artifacts automatically; the configured language applies prospectively to content created or intentionally rewritten in the current workflow.

package/skills/specflow-apply/SKILL.md

@@ -18,6 +18,13 @@ description: "Two-phase apply — task rewrite + subagent TDD execution"
 - Existing `tasks.md` is present (coarse first-iteration from `/specflow:propose`, or a refine-updated version).
 - `specflow` CLI is available on PATH.
 
+## Artifact Language Setup
+
+Before Phase A rewrites `tasks.md`, read
+`.claude/specflow/prompts/shared/artifact-language.md` and resolve the active
+planning root's `specflow/config.yaml`. Apply the policy to rewritten task
+descriptions while preserving paths, commands, code, and symbols.
+
 ---
 
 ## Phase A: Task Rewrite

package/skills/specflow-explore/SKILL.md

@@ -33,6 +33,12 @@ Skip explore when you already know exactly what to build — run `/specflow:prop
 - `specflow/` exists (suggest `specflow init` if missing)
 - `specflow` CLI available on PATH
 
+## Artifact Language Setup
+
+Read `.claude/specflow/prompts/shared/artifact-language.md` and resolve the active
+planning root's `specflow/config.yaml` before writing or rewriting `explore.md`.
+Apply that policy to every artifact created by this workflow.
+
 ## Stage 1: Create or Reuse Change
 
 If no active change directory exists for this work:

package/skills/specflow-propose/SKILL.md

@@ -18,6 +18,12 @@ Treat every artifact here as "v1, to be iterated on" — depth matters, but so d
 - `specflow/specs/` directory should exist, indicating this is a specflow-initialized project. For a brand-new greenfield change with no existing specs, proceed — the prompt handles that case. If `specflow/` itself does not exist, suggest running `specflow init` first.
 - `specflow` CLI must be available on PATH.
 
+## Artifact Language Setup
+
+Read `.claude/specflow/prompts/shared/artifact-language.md` and resolve the active
+planning root's `specflow/config.yaml` before generating proposal, specs, design,
+or tasks. Reuse the resolved policy for all four artifacts.
+
 ## Stage 0: Explore Handoff (when explore.md exists)
 
 Before creating a new change or generating a proposal, check for an existing exploration artifact:

package/skills/specflow-refine/SKILL.md

@@ -26,6 +26,12 @@ emits a round diff summary.
 
 If any precondition fails, stop and instruct the user to run `/specflow:propose` first.
 
+## Artifact Language Setup
+
+Read `.claude/specflow/prompts/shared/artifact-language.md` and resolve the active
+planning root's `specflow/config.yaml` before refining any artifact. Preserve
+existing requirement names where delta matching requires exact identity.
+
 ## Stage 1: Pre-loop setup
 
 Read, in order:

package/skills/specflow-snap/SKILL.md

@@ -10,6 +10,12 @@ description: "Post-hoc change documentation from git diff"
 - Git repository must have uncommitted or recent committed changes to document.
 - `specflow` CLI must be available on PATH.
 
+## Artifact Language Setup
+
+Read `.claude/specflow/prompts/shared/artifact-language.md` and resolve the active
+planning root's `specflow/config.yaml` before synthesizing proposal, specs, or
+tasks. Reuse the resolved policy for every generated artifact.
+
 ## Stage 1: Analyze Changes
 
 Run `git diff` and `git log` to capture what changed.