@haaaiawd/anws 2.0.0 → 2.0.2

package/README.md

@@ -3,8 +3,8 @@
 <img src="assets/logo-cli.png" width="260" alt="Anws">
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-[![Version](https://img.shields.io/badge/version-v2.0.0-7FB5B6)](https://github.com/Haaaiawd/Anws/releases)
-[![Targets](https://img.shields.io/badge/Targets-Windsurf%20%7C%20Claude%20Code%20%7C%20Copilot%20%7C%20Cursor%20%7C%20Codex%20Preview%20%7C%20OpenCode-blueviolet)](https://github.com/Haaaiawd/Anws)
+[![Version](https://img.shields.io/badge/version-v2.0.2-7FB5B6)](https://github.com/Haaaiawd/Anws/releases)
+[![Targets](https://img.shields.io/badge/Targets-Windsurf%20%7C%20Claude%20Code%20%7C%20Copilot%20%7C%20Cursor%20%7C%20Codex%20Preview%20%7C%20OpenCode%20%7C%20Trae%20%7C%20Qoder%20%7C%20Kilo%20Code-blueviolet)](https://github.com/Haaaiawd/Anws)
 
 [English](./README.md) | [中文](./README_CN.md)
 
@@ -14,15 +14,15 @@
 
 # Anws
 
-**Anws** is a spec-driven workflow framework for AI-assisted software development.
+**Anws** is a spec-driven workflow framework for AI-assisted development across modern AI IDEs and coding tools.
 
-It gives coding agents a disciplined path:
+It helps teams build production-ready software through a disciplined path:
 
 `PRD -> Architecture -> ADR -> Tasks -> Review -> Code -> Upgrade`
 
-Instead of letting AI jump straight into implementation, Anws forces design, preserves context in files, and projects the right workflow assets into the native layout of your target AI IDE.
+Anws enforces design-first principles, preserves context in files, and prevents architectural drift across multi-tool AI coding workflows.
 
-> **TL;DR**: stop treating AI like an autocomplete toy. Give it architecture, constraints, and a lifecycle.
+> **TL;DR**: a design-first workflow framework for AI coding tools that turns vibe coding into production-oriented engineering.
 
 ## ANWS
 
@@ -79,8 +79,13 @@ Anws addresses those problems with:
 - **Codex projection strategy update**
   - Codex is now treated as **Preview**
   - because Codex prompts are no longer available, Anws now packages workflow guidance into `.codex/skills/anws-system/`
-  - `/quickstart` maps to `SKILL.md`
-  - the rest of the workflow docs are exposed as `references/*.md` under the same aggregated skill
+  - `SKILL.md` is the navigation shell for the bundle
+  - workflow details, including `/quickstart`, now live under `references/*.md`
+
+- **Trae / Qoder / Kilo Code support**
+  - Trae follows the same skills-only bundle family as Codex via `.trae/skills/anws-system/`
+  - Qoder adds native `.qoder/commands/` + `.qoder/skills/`
+  - Kilo Code adds native `.kilocode/workflows/` + `.kilocode/skills/`
 
 - **OpenCode support**
   - adds native projection support for `.opencode/commands/` and `.opencode/skills/`
@@ -135,6 +140,7 @@ anws update
 - **State source**
   - `anws update` reads `.anws/install-lock.json`
   - if the lock is missing or invalid, it falls back to directory scan
+  - a real `anws update` can rebuild `.anws/install-lock.json` from detected targets when fallback is active
 
 - **`AGENTS.md` behavior**
   - marker-based file -> update stable sections, preserve `AUTO` block
@@ -171,16 +177,28 @@ If you maintain old docs or release notes, update those references before publis
 ## Compatibility
 
 Anws keeps a **single canonical workflow / skill source**, then projects it into the native directory structure expected by each tool.
+Every supported target now receives:
+
+- a root `AGENTS.md`
+- a target-native `skills/` projection
+- one target-native workflow entry surface, depending on the tool:
+  - `workflows`
+  - `commands`
+  - `prompts`
+  - aggregated `skills` for Codex / Trae skills-only bundles
 
 | Environment | Status | Layout |
 | --- | --- | --- |
-| **Windsurf** | ✅ Full Support | `.windsurf/workflows/` + `.windsurf/skills/` |
+| **Windsurf** | ✅ Full Support | `AGENTS.md` + `.windsurf/workflows/` + `.windsurf/skills/` |
 | **Antigravity** | ✅ Full Support | `.agents/workflows/` + `.agents/skills/` + `AGENTS.md` |
-| **Claude Code** | ✅ Full Support | `.claude/commands/` |
-| **GitHub Copilot** | ✅ Full Support | `.github/agents/` + `.github/prompts/` |
-| **Cursor** | ✅ Supported | `.cursor/commands/` |
-| **Codex** | ⚠️ Preview | `.codex/skills/anws-system/` + `.codex/skills/<skill>/` |
-| **OpenCode** | ✅ Supported | `.opencode/commands/` + `.opencode/skills/` |
+| **Claude Code** | ✅ Full Support | `AGENTS.md` + `.claude/commands/` + `.claude/skills/` |
+| **GitHub Copilot** | ✅ Full Support | `AGENTS.md` + `.github/prompts/` + `.github/skills/` |
+| **Cursor** | ✅ Supported | `AGENTS.md` + `.cursor/commands/` + `.cursor/skills/` |
+| **Codex** | ⚠️ Preview | `AGENTS.md` + `.codex/skills/anws-system/` + `.codex/skills/<skill>/` |
+| **OpenCode** | ✅ Supported | `AGENTS.md` + `.opencode/commands/` + `.opencode/skills/` |
+| **Trae** | ✅ Supported | `AGENTS.md` + `.trae/skills/anws-system/` + `.trae/skills/<skill>/` |
+| **Qoder** | ✅ Supported | `AGENTS.md` + `.qoder/commands/` + `.qoder/skills/` |
+| **Kilo Code** | ✅ Supported | `AGENTS.md` + `.kilocode/workflows/` + `.kilocode/skills/` |
 
 ---
 
@@ -234,21 +252,45 @@ your-project/
 │   ├── install-lock.json
 │   ├── changelog/
 │   └── v{N}/
+├── AGENTS.md
 ├── .windsurf/
 │   ├── workflows/
 │   └── skills/
 ├── .agents/
 │   ├── workflows/
 │   └── skills/
-├── AGENTS.md
-├── .cursor/commands/
-├── .claude/commands/
+├── .cursor/
+│   ├── commands/
+│   └── skills/
+├── .claude/
+│   ├── commands/
+│   └── skills/
 ├── .github/
-│   ├── agents/
-│   └── prompts/
+│   ├── prompts/
+│   └── skills/
+├── .opencode/
+│   ├── commands/
+│   └── skills/
+├── .qoder/
+│   ├── commands/
+│   └── skills/
+├── .kilocode/
+│   ├── workflows/
+│   └── skills/
+├── .trae/
+│   └── skills/
+│       ├── anws-system/
+│       │   ├── SKILL.md
+│       │   └── references/
+│       └── <skill>/
+│           └── SKILL.md
 └── .codex/
-    ├── prompts/
-    └── skills/
+    ├── skills/
+    │   ├── anws-system/
+    │   │   ├── SKILL.md
+    │   │   └── references/
+    │   └── <skill>/
+    │       └── SKILL.md
 ```
 
 > One source model. Multiple target layouts. Explicit ownership on disk.

package/bin/cli.js

@@ -23,12 +23,24 @@ OPTIONS
   -v, --version   Print version number
   -h, --help      Show this help message
   --target        Target AI IDE(s) for \`init\`, comma-separated (${TARGET_IDS.join(', ')})
-  --check         Preview grouped update diffs without writing files or install-lock state
+  --check         Preview grouped update diffs without writing files or rebuilding install-lock state
+
+SUPPORTED TARGETS
+  windsurf     workflows + skills
+  antigravity  workflows + skills
+  cursor       commands + skills
+  claude       commands + skills
+  copilot      prompts + skills
+  codex        preview, skills-only bundle via anws-system
+  opencode     commands + skills
+  trae         skills-only bundle via anws-system
+  qoder        commands + skills
+  kilo         workflows + skills
 
 EXAMPLES
   anws init                       # Choose target IDEs and install their managed workflow projections
-  anws init --target windsurf,codex
-  anws update                     # Update all matched targets from install-lock or directory scan
+  anws init --target windsurf,codex,opencode
+  anws update                     # Update all matched targets from install-lock or directory scan fallback
   anws update --check             # Preview grouped changes per target without writing files
 `.trimStart();
 

package/lib/adapters/index.js

@@ -7,7 +7,7 @@ const TARGETS = {
   windsurf: {
     id: 'windsurf',
     label: 'Windsurf',
-    rootAgentFile: false,
+    rootAgentFile: true,
     projectionTypes: {
       workflow: ['workflows'],
       skill: ['skills']
@@ -35,7 +35,7 @@ const TARGETS = {
   cursor: {
     id: 'cursor',
     label: 'Cursor',
-    rootAgentFile: false,
+    rootAgentFile: true,
     projectionTypes: {
       workflow: ['commands'],
       skill: ['skills']
@@ -49,7 +49,7 @@ const TARGETS = {
   claude: {
     id: 'claude',
     label: 'Claude',
-    rootAgentFile: false,
+    rootAgentFile: true,
     projectionTypes: {
       workflow: ['commands'],
       skill: ['skills']
@@ -63,7 +63,7 @@ const TARGETS = {
   copilot: {
     id: 'copilot',
     label: 'GitHub Copilot',
-    rootAgentFile: false,
+    rootAgentFile: true,
     projectionTypes: {
       workflow: ['prompts'],
       skill: ['skills']
@@ -77,7 +77,7 @@ const TARGETS = {
   codex: {
     id: 'codex',
     label: 'Codex (Preview)',
-    rootAgentFile: false,
+    rootAgentFile: true,
     projectionTypes: {
       workflow: ['skills'],
       skill: ['skills']
@@ -87,10 +87,51 @@ const TARGETS = {
     },
     detect: ['.codex/skills/anws-system/SKILL.md']
   },
+  trae: {
+    id: 'trae',
+    label: 'Trae (Preview)',
+    rootAgentFile: true,
+    projectionTypes: {
+      workflow: ['skills'],
+      skill: ['skills']
+    },
+    projections: {
+      skills: '.trae/skills'
+    },
+    detect: ['.trae/skills/anws-system/SKILL.md']
+  },
+  qoder: {
+    id: 'qoder',
+    label: 'Qoder',
+    rootAgentFile: true,
+    projectionTypes: {
+      workflow: ['commands'],
+      skill: ['skills']
+    },
+    projections: {
+      commands: '.qoder/commands',
+      skills: '.qoder/skills'
+    },
+    detect: ['.qoder/commands/genesis.md']
+  },
+  kilo: {
+    id: 'kilo',
+    label: 'Kilo Code',
+    rootAgentFile: true,
+    projectionTypes: {
+      workflow: ['workflows'],
+      skill: ['skills']
+    },
+    projections: {
+      workflows: '.kilocode/workflows',
+      skills: '.kilocode/skills'
+    },
+    detect: ['.kilocode/workflows/genesis.md']
+  },
   opencode: {
     id: 'opencode',
     label: 'OpenCode',
-    rootAgentFile: false,
+    rootAgentFile: true,
     projectionTypes: {
       workflow: ['commands'],
       skill: ['skills']

package/lib/init.js

@@ -1,9 +1,10 @@
 'use strict';
 
 const path = require('node:path');
+const fs = require('node:fs/promises');
 const { buildProjectionPlan } = require('./manifest');
 const { getTarget, listTargets } = require('./adapters');
-const { resolveAgentsInstall, printLegacyMigrationWarning, pathExists } = require('./agents');
+const { planAgentsUpdate, resolveAgentsInstall, printLegacyMigrationWarning, pathExists } = require('./agents');
 const { ensureChangelogDir } = require('./changelog');
 const { ROOT_AGENTS_FILE, resolveCanonicalSource } = require('./resources');
 const { writeTargetFiles } = require('./copy');
@@ -35,9 +36,11 @@ async function init() {
   const skipped = [];
   const successfulTargets = [];
   const failedTargets = [];
+  const sessionWrittenFiles = new Set();
 
   for (const targetPlan of targetPlans) {
     const target = getTarget(targetPlan.targetId);
+    const rootAgentsExists = await pathExists(path.join(cwd, 'AGENTS.md'));
     const agentsDecision = target.id === 'antigravity'
       ? await resolveAgentsInstall({
         cwd,
@@ -45,11 +48,19 @@ async function init() {
         forceYes: !!global.__ANWS_FORCE_YES
       })
       : {
-        shouldWriteRootAgents: false,
-        shouldWarnMigration: false
+        shouldWriteRootAgents: true,
+        shouldWarnMigration: false,
+        rootExists: rootAgentsExists
       };
 
-    const conflicting = await findConflicts(cwd, targetPlan.managedFiles);
+    let agentsUpdatePlan = null;
+    if (agentsDecision.shouldWriteRootAgents && agentsDecision.rootExists) {
+      const templateContent = await fs.readFile(srcAgents, 'utf8');
+      const existingContent = await fs.readFile(path.join(cwd, 'AGENTS.md'), 'utf8');
+      agentsUpdatePlan = planAgentsUpdate({ templateContent, existingContent });
+    }
+
+    const conflicting = await findConflicts(cwd, targetPlan.managedFiles, sessionWrittenFiles);
     if (conflicting.length > 0) {
       const confirmed = await askOverwrite(conflicting.length, target.label);
       if (!confirmed) {
@@ -68,10 +79,14 @@ async function init() {
       protectedFiles: targetPlan.userProtectedFiles,
       srcAgents,
       shouldWriteRootAgents: agentsDecision.shouldWriteRootAgents,
+      agentsUpdatePlan,
       resolveCanonicalSource
     });
 
     written.push(...result.written);
+    for (const rel of result.written) {
+      sessionWrittenFiles.add(rel);
+    }
     skipped.push(...result.skipped);
     successfulTargets.push(summarizeTargetState(targetPlan, cliVersion));
 
@@ -122,9 +137,12 @@ async function init() {
  * 找出 cwd 中已存在的托管文件列表。
  * @returns {Promise<string[]>} 已存在的托管文件相对路径数组
  */
-async function findConflicts(cwd, managedFiles) {
+async function findConflicts(cwd, managedFiles, sessionWrittenFiles = new Set()) {
   const conflicts = [];
   for (const rel of managedFiles) {
+    if (sessionWrittenFiles.has(rel)) {
+      continue;
+    }
     const abs = path.join(cwd, rel);
     const exists = await pathExists(abs);
     if (exists) conflicts.push(rel);
@@ -236,4 +254,4 @@ function printTargetSummary(successfulTargets, failedTargets) {
 }
 
 module.exports = init;
-
+

package/lib/install-state.js

@@ -166,16 +166,24 @@ async function detectInstallState(cwd) {
   const lockResult = await readInstallLock(cwd);
   const scannedTargets = await detectInstalledTargets(cwd);
   const lockTargets = lockResult.lock?.targets || [];
+  const needsFallback = !lockResult.exists || !!lockResult.error;
+  const fallbackReason = !needsFallback
+    ? null
+    : (!lockResult.exists ? 'missing_lock' : 'invalid_lock');
   const selectedTargets = lockTargets.length > 0
     ? lockTargets.map((item) => item.targetId)
     : scannedTargets.map((item) => item.id);
+  const drift = detectLockDrift(lockResult.lock, scannedTargets);
 
   return {
     lockResult,
     scannedTargets,
     selectedTargets,
-    drift: detectLockDrift(lockResult.lock, scannedTargets),
-    needsFallback: !lockResult.exists || !!lockResult.error
+    drift,
+    needsFallback,
+    fallbackReason,
+    stateSource: needsFallback ? 'directory_scan_fallback' : 'install_lock',
+    canRebuildLock: needsFallback && selectedTargets.length > 0
   };
 }
 

package/lib/manifest.js

@@ -19,6 +19,7 @@ const RESOURCE_REGISTRY = [
   { id: 'probe', type: 'workflow', source: '.agents/workflows/probe.md', fileName: 'probe.md' },
   { id: 'quickstart', type: 'workflow', source: '.agents/workflows/quickstart.md', fileName: 'quickstart.md' },
   { id: 'upgrade', type: 'workflow', source: '.agents/workflows/upgrade.md', fileName: 'upgrade.md' },
+  { id: 'anws-system', type: 'skill', source: '.agents/skills/anws-system/SKILL.md', fileName: 'anws-system/SKILL.md', targets: ['codex', 'trae'] },
   { id: 'concept-modeler', type: 'skill', source: '.agents/skills/concept-modeler/SKILL.md', fileName: 'concept-modeler/SKILL.md' },
   { id: 'design-reviewer', type: 'skill', source: '.agents/skills/design-reviewer/SKILL.md', fileName: 'design-reviewer/SKILL.md' },
   { id: 'nexus-mapper', type: 'skill', source: '.agents/skills/nexus-mapper/SKILL.md', fileName: 'nexus-mapper/SKILL.md' },
@@ -53,10 +54,8 @@ function toArray(value) {
 }
 
 function toProjectionFileName(resource, projectionType, targetId) {
-  if (targetId === 'codex' && projectionType === 'skills' && resource.type === 'workflow') {
-    return resource.id === 'quickstart'
-      ? 'anws-system/SKILL.md'
-      : `anws-system/references/${resource.id}.md`;
+  if ((targetId === 'codex' || targetId === 'trae') && projectionType === 'skills' && resource.type === 'workflow') {
+    return `anws-system/references/${resource.id}.md`;
   }
   if (projectionType === 'commands') {
     return `${resource.id}.md`;
@@ -75,6 +74,9 @@ function buildProjectionEntries(targetId) {
   const typeMap = target.projectionTypes;
 
   return RESOURCE_REGISTRY.flatMap((resource) => {
+    if (resource.targets && !resource.targets.includes(target.id)) {
+      return [];
+    }
     const projectionTypes = typeMap[resource.type];
     if (!projectionTypes) {
       return [];
@@ -129,6 +131,9 @@ function buildProjectionPlan(targetIds = ['antigravity'], resources = RESOURCE_R
     const target = getTarget(targetId);
     const typeMap = target.projectionTypes;
     const projectionEntries = resources.flatMap((resource) => {
+      if (resource.targets && !resource.targets.includes(target.id)) {
+        return [];
+      }
       const projectionTypes = typeMap[resource.type];
       if (!projectionTypes) {
         return [];

package/lib/update.js

@@ -128,6 +128,21 @@ async function update(options = {}) {
       logo();
       blank();
     }
+    printTargetSelection(installState, targetContexts.map((context) => context.target));
+    if (!check && installState.needsFallback && selectedTargetIds.length > 0) {
+      const generatedAt = new Date().toISOString();
+      await writeInstallLock(cwd, createInstallLock({
+        cliVersion: version,
+        generatedAt,
+        targets: dedupeTargets(targetPlans.map((targetPlan) => summarizeTargetState(targetPlan, version))),
+        lastUpdateSummary: {
+          successfulTargets: [],
+          failedTargets: [],
+          updatedAt: generatedAt
+        }
+      }));
+      info('Rebuilt .anws/install-lock.json from the detected target layout.');
+    }
     info(`Already up to date. Latest recorded version is v${versionState.latestVersion || version}.`);
     return;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haaaiawd/anws",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Anws — A spec-driven workflow framework for AI-assisted development. Empowers prompt engineers to build production-ready software through structured PRD → Architecture → Task decomposition. Works with Claude Code, GitHub Copilot, Cursor, Windsurf, and any tool that reads AGENTS.md.",
   "keywords": [
     "anws",

package/templates/.agents/skills/anws-system/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: anws-system
+description: 当用户在 skills-only 环境中需要判断应该从哪个 anws 工作流开始，或需要在 forge / change / genesis / probe / blueprint / challenge / upgrade 之间路由时使用。它是 anws 工作流集合的导航入口。
+---
+
+# ANWS System Router Manual
+
+你是 **ANWS Router**。
+
+你的职责不是直接替代所有工作流，而是作为 **skills-only 模式** 下的统一导航入口：
+
+- 判断当前请求应路由到哪个工作流
+- 告诉模型还需要读取哪个 `references/*.md`
+- 在开始执行前明确权限边界，避免把 `/forge`、`/change`、`/genesis` 混用
+
+## 激活规则
+
+出现以下任一情况时使用本 Skill：
+
+1. 用户不知道该从哪个工作流开始
+2. 用户明确提到 `/quickstart`、`/forge`、`/change`、`/genesis` 等工作流，但当前环境只有 skills
+3. 用户请求涉及“下一步该走哪个流程”
+4. 用户请求跨越设计、任务、实现多个阶段，需要先判断阶段边界
+
+## 首次激活的强制步骤
+
+1. 先读取 `references/quickstart.md`
+2. 判断当前请求更接近哪一种场景
+3. 再按需读取对应 workflow reference
+4. 没有读完对应 reference 前，不得直接执行该 workflow 的写操作
+
+## Workflow Map
+
+- `references/quickstart.md`
+  - 用途：总入口。用于判断项目目前处于哪一阶段，以及应先调用哪个工作流
+- `references/probe.md`
+  - 用途：接手遗留项目、重大改动前做系统风险探测
+- `references/genesis.md`
+  - 用途：新项目、重大重构、架构升级、需要新版本时使用
+- `references/design-system.md`
+  - 用途：为单个系统补详细设计文档
+- `references/blueprint.md`
+  - 用途：将架构设计拆成可执行的 `05_TASKS.md`
+- `references/challenge.md`
+  - 用途：在编码前系统性挑战设计或任务清单
+- `references/forge.md`
+  - 用途：按 `05_TASKS.md` 执行编码任务，并维护 Wave 进度
+- `references/change.md`
+  - 用途：只微调已有任务定义，不创建新任务，不推进实现状态
+- `references/explore.md`
+  - 用途：做调研、探索、方案发散与收敛
+- `references/craft.md`
+  - 用途：创建新的 workflow、skill 或 prompt
+- `references/upgrade.md`
+  - 用途：处理 `anws update` 之后的升级编排
+
+## 路由规则
+
+### Route 1: 不确定起点
+
+如果用户不知道从哪里开始，或你对当前阶段没有把握：
+
+1. 读取 `references/quickstart.md`
+2. 根据项目状态判断入口
+3. 给出建议 workflow，并说明理由
+4. 等待用户确认
+
+### Route 2: 请求是“开始编码 / 继续实现 / 做当前波次”
+
+1. 读取 `references/forge.md`
+2. 检查 `.anws/v{N}/05_TASKS.md` 是否存在且任务已定义
+3. 若缺任务清单，不得直接实现，先回到 `blueprint` 或 `genesis`
+
+### Route 3: 请求是“微调现有任务 / 修正文案 / 调整验收标准”
+
+1. 读取 `references/change.md`
+2. 确认只修改已有任务，不新增任务
+3. 若需要新增任务或超出 PRD，改走 `genesis`
+
+### Route 4: 请求是“新项目 / 大重构 / 新版本 / 架构升级”
+
+1. 读取 `references/genesis.md`
+2. 进入版本化架构流程
+
+### Route 5: 请求是“先调研 / 先探测风险”
+
+- 遗留项目或重大变更前 → `references/probe.md`
+- 技术调研或方案发散 → `references/explore.md`
+
+## 边界守则
+
+1. 你是导航层，不是所有 workflow 的替身
+2. 每次只路由到一个主 workflow；如需串联，必须说明顺序
+3. 未读取目标 workflow reference 前，不得假装已经遵循该流程
+4. 若用户请求同时跨越设计与实现，先收敛边界，再决定 `/change` 或 `/genesis`
+5. skills-only 模式下，workflow 详情全部位于 `references/`
+
+## 输出格式
+
+当你完成路由判断时，输出应包含：
+
+- 当前判断的阶段
+- 建议读取的 reference
+- 建议进入的 workflow
+- 为什么不是其他 workflow
+- 是否需要等待用户确认

package/templates/.agents/skills/sequential-thinking/SKILL.md

@@ -1,166 +1,179 @@
----
-name: sequential-thinking
-description: 当复杂问题需要系统性逐步推理时使用。适用于多阶段分析、设计规划、问题分解，或初始范围不明确且可能需要修正、分支与动态调整思考范围的任务。
-license: MIT
----
-
-# Sequential Thinking
-
-通过可修正、可分支、可动态扩展的顺序推理，帮助 AI 处理复杂问题。
-
-## Core Capabilities
-
-- **迭代推理**: 将复杂问题拆解为连续的 thought 步骤
-- **动态范围**: 随着理解深入调整 `totalThoughts`
-- **修正能力**: 当新证据出现时回看并修正早期判断
-- **分支探索**: 从关键分叉点探索替代路径
-- **上下文保持**: 在整个推理过程中维持清晰的思考链条
-
-## When to Use
-
-在以下场景使用：
-- 问题需要多个相互关联的推理步骤
-- 初始范围或方法不明确
-- 需要在复杂性中找到核心问题
-- 可能需要回溯或修正早期结论
-- 想探索替代方案路径
-
-**不适用场景**: 简单查询、直接事实、单步任务，或解决路径已经非常明确的问题。
-
-## Basic Usage
-
-按如下 JSON 形态组织思考步骤。
-
-### Required Fields
-
-- `thought` (string): 当前推理内容
-- `nextThoughtNeeded` (boolean): 是否还需要继续推理
-- `thoughtNumber` (integer): 当前 thought 编号，从 `1` 开始
-- `totalThoughts` (integer): 当前预估总步数，可动态调整
-
-### Optional Fields
-
-- `isRevision` (boolean): 标记当前 thought 是否在修正先前思路
-- `revisesThought` (integer): 指明修正的是哪一个 thought
-- `branchFromThought` (integer): 指明从哪一个 thought 开始分支
-- `branchId` (string): 当前分支标识符
-
-## Workflow Pattern
-
-```
-1. 从 `thoughtNumber: 1` 开始。
-2. 每一步：
-   - 在 `thought` 中表达当前推理
-   - 用 `totalThoughts` 估计整体范围，必要时调整
-   - 若还需继续，设置 `nextThoughtNeeded: true`
-3. 当结论已经足够清晰时，设置 `nextThoughtNeeded: false`
-```
-
-## Example 1: 基础推演 (Baseline Reasoning)
-
-```typescript
-// First thought
-{
-  thought: "问题表面上是“查询性能下降”，但先不要急着选优化手段。需要先把问题拆成三层：是单条 SQL 退化、接口级 N+1、还是更上层的调用放大。若根因没分清，后面的缓存、索引、重写都可能只是补丁。",
-  thoughtNumber: 1,
-  totalThoughts: 4,
-  nextThoughtNeeded: true
-}
-
-// Second thought
-{
-  thought: "从查询日志看，用户详情接口在一次请求里触发了大量重复读取，已经出现明显的 N+1 信号。但还不能直接下结论，因为重复查询也可能只是症状；需要继续确认慢点究竟来自“查询次数过多”，还是“某条关键查询本身很慢”。因此总步数上调一档。",
-  thoughtNumber: 2,
-  totalThoughts: 6,
-  nextThoughtNeeded: true
-}
-
-// Final thought
-{
-  thought: "结论可以收敛了：主因是列表页批量加载时触发的 N+1，次因是关联字段缺少索引放大了单次查询成本。优化顺序应该先消除 N+1，再补索引验证尾延迟；这样既先打掉主矛盾，也避免一上来引入缓存复杂度。",
-  thoughtNumber: 6,
-  totalThoughts: 6,
-  nextThoughtNeeded: false
-}
-```
-
-## Example 2: 修正前提 (Revision in Flight)
-
-```typescript
-{
-  thought: "回看 profiling 结果后，前面的判断需要修正：真正拖垮接口的不是 N+1 本身，而是关联列缺少索引，导致每次关联查询都在放大全表扫描成本。也就是说，N+1 仍然存在，但它不是第一性瓶颈，优先级应该后移。",
-  thoughtNumber: 4,
-  totalThoughts: 6,
-  isRevision: true,
-  revisesThought: 2,
-  nextThoughtNeeded: true
-}
-```
-
-## Example 3: 复杂变更拆解 (Structured Impact Analysis)
-
-```typescript
-{
-  thought: "用户一次性提出了多项规则修改，不该把它们当成同一种改动处理。先拆开看：有的是机制原则调整，有的是数值平衡，有的是接口语义变化，还有的是文档与实现脱节。如果不先分型，后面会把“该改 ADR 的”“该改设计文档的”“该补代码契约的”混成一锅。",
-  thoughtNumber: 1,
-  totalThoughts: 3,
-  nextThoughtNeeded: true
-}
-
-{
-  thought: "先做影响矩阵。机制原则类改动通常会回流到 ADR 和 System Design；数值平衡会影响规则表、配置与测试基线；接口语义变化最危险，因为它会悄悄破坏调用方的假设。这里最该警惕的不是改动数量，而是有没有改到“被多个模块默认依赖、但文档里没写清楚”的隐性契约。",
-  thoughtNumber: 2,
-  totalThoughts: 3,
-  nextThoughtNeeded: true
-}
-
-{
-  thought: "可以收敛了：先处理那些会改变系统边界或调用语义的项，再处理数值与体验层面的项。顺序上应优先修正文档与契约，再讨论平衡性；否则后续所有实现和评审都会建立在漂移的前提上。结论不是“先改最显眼的”，而是“先修最容易污染系统认知的”。",
-  thoughtNumber: 3,
-  totalThoughts: 3,
-  nextThoughtNeeded: false
-}
-```
-
-## Example 4: 分支比较 (Branching Trade-offs)
-
-```typescript
-// Branch A
-{
-  thought: "方案 A：先引入缓存削峰。好处是见效快、对接口层侵入小，适合先止血；坏处是会把问题从“数据库慢”转成“缓存一致性与失效策略复杂”，如果根因其实是查询设计不合理，这条路容易把偶然复杂度永久留在系统里。",
-  thoughtNumber: 3,
-  totalThoughts: 7,
-  branchFromThought: 2,
-  branchId: "cache",
-  nextThoughtNeeded: true
-}
-
-// Branch B
-{
-  thought: "方案 B：直接做索引优化和查询重写。好处是从根上消除瓶颈，长期结构更干净；代价是需要更仔细验证写入放大、锁竞争和回归风险。这条路更慢，但如果业务模型稳定，通常比提前上缓存更符合简单优先的原则。",
-  thoughtNumber: 3,
-  totalThoughts: 7,
-  branchFromThought: 2,
-  branchId: "query",
-  nextThoughtNeeded: true
-}
-```
-
-## Heuristic Reminders
-
-以下提醒是**辅助思考的启发式问题**，不是硬约束。按任务性质选择性使用即可。
-
-- **问题定义提醒**: 你现在是在描述现象，还是在定位根因？
-- **证据提醒**: 当前判断基于事实、观察结果，还是基于猜测与假设？
-- **边界提醒**: 当前问题影响的是局部模块、单系统，还是跨系统结构？
-- **复杂度提醒**: 你是在消除本质复杂度，还是在增加偶然复杂度？
-- **收敛提醒**: 当前是否已经足够形成结论，还是仍在无效发散？
-
-## Tips
-
-- 先给出粗略的 `totalThoughts`，随着理解深入再调整
-- 当早期假设被证伪时，优先修正，不要沿着错误前提继续推进
-- 当存在明确替代路径时，可以用分支并行比较
-- 在 `thought` 中明确表达不确定性，比过早下结论更可靠
-- 最后一个 thought 应明确给出结论，必要时补充下一步行动
-
+---
+name: sequential-thinking
+description: 当复杂问题需要系统性逐步推理时使用。适用于多阶段分析、设计规划、问题分解，或初始范围不明确且需要受控收敛的任务。
+license: MIT
+---
+
+# Sequential Thinking
+
+这个 skill 的核心不是“多写几段 thought”，而是让 AI 在复杂问题里**持续推进、允许修正，并最终收敛成结论**。CLI 只是执行载体；skill 本身负责定义什么时候该进入这种思考方式，以及如何避免把顺序思考退化成松散输出。
+
+## Mission
+
+这个 skill 用来把复杂问题处理成一个**有边界、可修正、可复核的推理过程**：
+
+- 先澄清问题，而不是急着给答案
+- 在推进过程中允许修正和调整判断
+- 在复杂度上升时比较替代路径，而不是单线硬推
+- 在有限步数内收敛成结论与建议
+- 最后保留可回放的推理轨迹
+
+它解决的不是“不会想”，而是“想得太散、太早下结论、太难复核”。
+
+## Core Capabilities
+
+- **迭代推进**: 把复杂问题拆成连续步骤，而不是试图一口气得到完整答案
+- **动态修正**: 当新证据出现时，允许回看并修正前面的判断
+- **分支比较**: 当存在替代路径时，允许先比较再收敛
+- **上下文保持**: 在多步推理中维持清晰的问题边界与目标
+- **结论收束**: 最终必须形成判断，而不是无限发散
+
+## When to Use
+
+在以下场景调用：
+
+- 问题需要多个相互关联的推理步骤
+- 初始范围或方法不明确，需要先拆问题、再形成方法
+- 需要在有限候选方案之间做比较，而不是无限发散
+- 需要回看已有判断、识别漏洞、证据不足与隐含假设
+- 需要留下可回放、可导出的推理轨迹
+
+**不适用场景**：
+
+- 简单事实查询
+- 单步即可完成的任务
+- 路径已经非常明确、无需多步推演的问题
+- 纯头脑风暴且暂时不要求收敛的场景
+
+## Working Philosophy
+
+- **先找主问题，再找答案**：不要把现象描述误当作根因定位
+- **允许修正，而不是硬撑前提**：前面想错了，就回头修，不要带着错误前提继续推进
+- **先消除复杂度，再堆解决方案**：优先识别主矛盾，而不是抢着给补丁
+- **每一步只推进一步**：当前步只表达当前判断，不重复整套背景
+- **最终必须落到结论**：不能把“我还能继续想”当作默认出口
+
+## Installation & Runtime Model
+
+这个 skill 面向 agent 交付思考方式与调用约束；CLI 通过 npm 分发。
+
+在使用前，应先确保本地已安装对应 CLI：
+
+```bash
+npm install -g sequential-thinking-cli
+
+# 或
+pnpm add -g sequential-thinking-cli
+```
+
+安装后，使用 `sthink` 作为命令入口。
+
+## CLI Contract
+
+本 skill 不再要求 AI 手写 thought JSON。执行层通过 CLI 主路径动作完成：
+
+- `start`
+- `step`
+- `replay`
+
+### `start`
+
+只接受四个输入：
+
+- `name`
+- `goal`
+- `mode`
+- `totalSteps`
+
+约束：
+
+- `mode` 仅允许 `explore`、`branch`、`audit`
+- `totalSteps` 仅允许 `5` 或 `8`
+
+如果你不确定该选哪种模式，默认用 `explore`。只有在任务明显是在比较候选路径时才用 `branch`；只有在任务明显是在审查既有判断时才用 `audit`。
+
+### `step`
+
+只接受：
+
+- `content`
+
+其余上下文应由 runtime 自动恢复并注入。
+
+### `replay`
+
+用于读取已完成会话并生成 replay 文档；如需要，可额外导出到当前目录。
+
+## Recommended Workflow
+
+```text
+1. 先判断问题是否真的需要 sequential-thinking，而不是默认套用。
+2. 如需要，先安装或确认本地已有 npm CLI。
+3. 用 `sthink start` 给出 `name`、`goal`、`mode`、`totalSteps`。
+4. 用 `sthink step` 逐步推进，每一步只写当前推进内容。
+5. 当出现新证据时，允许修正，而不是硬撑旧判断。
+6. 到收敛阶段时，必须输出结论、风险与下一步建议。
+7. 完成后按需使用 `sthink replay` 生成与导出回放文档。
+```
+
+## Examples
+
+以下示例不是为了让你回去手写 JSON，而是为了说明这种 skill 真正有价值的地方：**如何推进、如何修正、如何收敛**。
+
+### Example 1: 基础推演
+
+```bash
+sthink start --name "query-diagnosis" --goal "定位查询性能下降的主因" --mode explore --totalSteps 5
+sthink step --sessionPath "<session-path>" --content "先不要急着选优化手段。需要先把问题拆成几层：是单条 SQL 退化、接口级 N+1，还是更上层的调用放大。若根因没分清，后面的缓存、索引、重写都可能只是补丁。"
+sthink step --sessionPath "<session-path>" --content "从查询日志看，用户详情接口在一次请求里触发了大量重复读取，已经出现明显的 N+1 信号。但还不能直接下结论，因为重复查询也可能只是症状；需要继续确认慢点究竟来自“查询次数过多”，还是“某条关键查询本身很慢”。因此总步数上调一档。"
+sthink step --sessionPath "<session-path>" --content "结论可以收敛了：主因是列表页批量加载时触发的 N+1，次因是关联字段缺少索引放大了单次查询成本。优化顺序应该先消除 N+1，再补索引验证尾延迟；这样既先打掉主矛盾，也避免一上来引入缓存复杂度。"
+```
+
+### Example 2: 修正前提
+
+```bash
+sthink step --sessionPath "<session-path>" --content "回看 profiling 结果后，前面的判断需要修正：真正拖垮接口的不是 N+1 本身，而是关联列缺少索引，导致每次关联查询都在放大全表扫描成本。也就是说，N+1 仍然存在，但它不是第一性瓶颈，优先级应该后移。"
+```
+
+### Example 3: 复杂变更拆解
+
+```bash
+sthink start --name "change-impact-analysis" --goal "拆解复杂变更的影响与优先级" --mode explore --totalSteps 5
+sthink step --sessionPath "<session-path>" --content "用户一次性提出了多项规则修改，不该把它们当成同一种改动处理。先拆开看：有的是机制原则调整，有的是数值平衡，有的是接口语义变化，还有的是文档与实现脱节。如果不先分型，后面会把“该改 ADR 的”“该改设计文档的”“该补代码契约的”混成一锅。"
+sthink step --sessionPath "<session-path>" --content "先做影响矩阵。机制原则类改动通常会回流到 ADR 和 System Design；数值平衡会影响规则表、配置与测试基线；接口语义变化最危险，因为它会悄悄破坏调用方的假设。这里最该警惕的不是改动数量，而是有没有改到“被多个模块默认依赖、但文档里没写清楚”的隐性契约。"
+sthink step --sessionPath "<session-path>" --content "可以收敛了：先处理那些会改变系统边界或调用语义的项，再处理数值与体验层面的项。顺序上应优先修正文档与契约，再讨论平衡性；否则后续所有实现和评审都会建立在漂移的前提上。结论不是“先改最显眼的”，而是“先修最容易污染系统认知的”。"
+```
+
+### Example 4: 分支比较
+
+```bash
+sthink start --name "performance-tradeoff" --goal "比较缓存止血与查询优化的优先级" --mode branch --totalSteps 5
+sthink step --sessionPath "<session-path>" --content "方案 A：先引入缓存削峰。好处是见效快、对接口层侵入小，适合先止血；坏处是会把问题从“数据库慢”转成“缓存一致性与失效策略复杂”，如果根因其实是查询设计不合理，这条路容易把偶然复杂度永久留在系统里。与此同时，方案 B：直接做索引优化和查询重写。好处是从根上消除瓶颈，长期结构更干净；代价是需要更仔细验证写入放大、锁竞争和回归风险。这条路更慢，但如果业务模型稳定，通常比提前上缓存更符合简单优先的原则。"
+```
+
+## Storage & Export Boundary
+
+- runtime 会自动保存会话状态与步骤记录
+- 完成态可生成 replay 文档
+- `replay` 支持导出到当前目录，便于审阅与复用
+
+## Heuristic Reminders
+
+以下提醒是启发式问题，不是硬约束。真正重要的是：它们能帮助你减少空转，逼近结论。
+
+- **问题定义提醒**: 你现在是在描述现象，还是在定位根因？
+- **证据提醒**: 当前判断基于事实、观察结果，还是基于猜测与假设？
+- **边界提醒**: 当前问题影响的是局部模块、单系统，还是跨系统结构？
+- **复杂度提醒**: 你是在消除本质复杂度，还是在增加偶然复杂度？
+- **收敛提醒**: 当前是否已经足够形成结论，还是仍在无效发散？
+
+## Tips
+
+- 不要再手写 thought JSON；让 CLI runtime 负责节奏、落盘与 replay
+- 不要把 sequential-thinking 当成默认模式，只在真正需要多步收敛时调用
+- 如果不确定模式，先用 `explore`
+- `step` 的 `content` 只表达当前推进内容，不要重复补全系统上下文
+- 如果发现前提错了，就明确修正，不要硬撑
+- 到收敛阶段时，应明确输出结论、风险和下一步动作
+- 只有已完成会话才能执行 `replay`
+

package/templates/.agents/workflows/change.md

@@ -15,6 +15,7 @@ description: "处理微调级变更请求，仅允许修改已有任务的细节
 - **忠于 Blueprint** - 所有修改必须在 `01_PRD.md` 已定义的需求范围内
 - **人类审批** - 所有写操作必须先展示计划，经人类确认后才能执行
 - **可追溯** - 所有变更都记录在 CHANGELOG
+- **不维护完成状态** - `/change` 只修改任务定义，不负责回填 `05_TASKS.md` checkbox
 
 **Output Goal**: 
 - 更新 `.anws/v{N}/05_TASKS.md` (仅修改已有任务)
@@ -35,6 +36,8 @@ description: "处理微调级变更请求，仅允许修改已有任务的细节
 > | 调整已有任务的估时 | ✅ | |
 > | 标记任务阻塞/重分优先级 | ✅ | |
 > | 微调 `04_SYSTEM_DESIGN/` 中已有文件的细节 | ✅ | |
+> | 更新任务说明字段，但不改变完成状态 | ✅ | |
+> | **回填 `05_TASKS.md` checkbox** | | ❌ |
 > | **创建新任务 (T{X}.{Y}.{Z})** | | ❌ |
 > | **创建新文件** | | ❌ |
 > | **添加 AI 自认为好的功能** | | ❌ |
@@ -43,8 +46,6 @@ description: "处理微调级变更请求，仅允许修改已有任务的细节
 > | **修改 `02_ARCHITECTURE_OVERVIEW.md`** | | ❌ |
 > | **修改 `03_ADR/` 中的任何文件** | | ❌ |
 >
-> **单次 /change 最多影响 3 个已有任务 + 对应的设计文件微调。**
->
 > **违反以上任何一条 → 变更无效，引导用户运行 `/genesis`。**
 
 ---
@@ -158,8 +159,8 @@ description: "处理微调级变更请求，仅允许修改已有任务的细节
 
 3.  **定位任务**:
     - 找到与变更相关的已有任务 (如 `T2.1.3`)
-    - **最多 3 个任务**受影响
-    - 如果超过 3 个 → 跳转 Step 4
+    - 记录所有实际受影响的已有任务
+    - 如果需要创建新任务才能承接变更 → 跳转 Step 4
 
 4.  **定位相关设计文件** (如需要):
     - 检查 `{TARGET_DIR}/04_SYSTEM_DESIGN/` 中是否有对应的系统设计文件
@@ -230,7 +231,9 @@ description: "处理微调级变更请求，仅允许修改已有任务的细节
 ### Step 3.1: 执行修改 (仅在人类批准后)
 
 1.  **修改任务清单**:
-    使用 `replace_file_content` 修改 `{TARGET_DIR}/05_TASKS.md` 中的对应任务
+    使用 `replace_file_content` 修改 `{TARGET_DIR}/05_TASKS.md` 中的对应任务定义
+    - 仅允许修改任务描述、验收标准、估时、优先级、阻塞说明等定义字段
+    - **禁止**在 `/change` 中将 `- [ ]` 改为 `- [x]` 或反向修改 checkbox
 
 2.  **记录变更日志**:
     读取并追加到 `{TARGET_DIR}/06_CHANGELOG.md`:

package/templates/.agents/workflows/forge.md

@@ -225,6 +225,15 @@ T{X.Y.Z}, T{X.Y.Z}, T{X.Y.Z}
 读取该任务 `**输入**` 字段指定的文档和章节。
 如果任务依赖已完成的前置任务，浏览相关已有代码了解接口。
 
+> [!IMPORTANT]
+> **开始写代码前，必须对本波次每个任务都完成一次依赖读取。**
+>
+> - 至少读取该任务 `**输入**` 字段指定的文档/章节
+> - 如任务依赖其他任务，补读前置任务相关接口或实现代码
+> - 未完成该任务的依赖读取，不得开始该任务编码
+>
+> **为什么？** `/forge` 允许按本波次批量推进和批量回填 checkbox，但前提是每个任务都已完成最小上下文装载，不能只看标题就动手。
+
 ---
 
 ### 3.2 Think Before Code (编码前思考)
@@ -331,7 +340,10 @@ T{X.Y.Z}, T{X.Y.Z}, T{X.Y.Z}
    > 下次加载 TASKS.md 就能看到精确进度。
    > 配合 AGENTS.md 的 Wave 块形成**双层恢复机制**: 粗粒度(Wave) + 细粒度(Task checkbox)。
 
-   - 将该任务的 `- [ ]` 改为 `- [x]`
+   - 本波次允许批量回填已全部验证通过的任务 checkbox
+   - 仅按 **Task ID** 精确定位并更新状态，禁止按标题模糊匹配
+   - 将对应任务的 `- [ ]` 改为 `- [x]`
+   - 不得顺手修改未完成、未验证或不在当前波次内的任务
    - 确保回写后的 `05_TASKS.md` 与实际进度一致
 
 3. **继续下一个任务** → 回到 3.1