FET

FET 是一个围绕 OpenSpec 构建的前端开发工作流编排 CLI。它不会直接生成业务代码，而是代理 OpenSpec 命令、维护本地工作流状态、生成可审计的项目上下文，并帮助 Cursor 等 AI 编程工具读取正确的项目资料。

作用

• 统一入口：用 fet <command> 包装 OpenSpec 工作流，避免用户和 AI 工具绕过 FET 的状态记录。
• 生成上下文：扫描项目并生成 AGENTS.md 与 openspec/config.yaml 中的 fet: 配置。
• 管理状态：记录 active change、任务同步、手动验证声明、工具适配状态等本地工作流信息。
• 集成 AI 工具：为 Cursor 生成项目规则和 Skill 说明，引导 AI 读取 OpenSpec 规划产物和项目上下文。
• 保护关键阶段：在 sync / archive 前检查 FET 的 verify 状态，降低未验证变更被归档的风险。

基本原理

FET 是 OpenSpec 的透明代理和本地编排层。用户运行 fet apply、fet archive 等命令时，FET 会先读取项目状态和 change 状态，执行必要的 pre-hook，再调用真实的 openspec CLI，最后根据 OpenSpec 的结果更新 FET 状态。

FET 代理命令会保留 OpenSpec 原生命令名。例如 fet apply --change <id> 会调用 openspec apply --change <id>，fet sync --change <id> 会在 FET verify gate 通过后调用 openspec sync --change <id>。

环境要求

• Node.js 18 或更高版本
• OpenSpec CLI 在 PATH 中可用

安装 OpenSpec：

npm install -g @fission-ai/openspec

安装 FET

npm install -g @nick848/fet

安装后检查：

fet --version
fet --help

快速开始

在需要接入 OpenSpec 的项目根目录运行：

fet init
fet doctor

典型流程：

fet new my-change
fet apply --change my-change
fet verify --change my-change
fet verify --done --change my-change
fet sync --change my-change
fet archive --change my-change

全局参数

| 参数 | 说明 | 示例 | |------|------|------| | --cwd <path> | 指定项目根目录，默认当前目录。 | fet doctor --cwd ./app | | --change <id> | 指定 OpenSpec change。 | fet apply --change add-login | | --yes | 对低风险确认使用默认同意。 | fet init --yes | | --json | 输出机器可读 JSON。 | fet doctor --json | | --verbose | 输出更多诊断信息。 | fet doctor --verbose | | --no-color | 禁用终端颜色。 | fet --no-color doctor |

命令列表

| 命令 | 用法 | 说明 | |------|------|------| | fet init | fet init [--yes] | 初始化 FET 和 OpenSpec；生成上下文文件、状态文件、Cursor 规则和 Skill。 | | fet update-context | fet update-context [--yes] | 重新扫描项目并更新 AGENTS.md 与 openspec/config.yaml 的 FET 托管区域。 | | fet doctor | fet doctor [--fix-lock] | 诊断 OpenSpec、FET 状态、上下文文件、Cursor 集成和锁文件。 | | fet explore | fet explore [...args] [--change <id>] | 代理 OpenSpec 原生 explore 流程，保留交互式需求澄清。 | | fet propose | fet propose <change-id> | 创建新的 OpenSpec change；等价于 FET 高层提案入口。 | | fet new | fet new <change-id> | 创建新的 OpenSpec change。 | | fet continue | fet continue [...args] [--change <id>] | 通过 FET 执行 OpenSpec 原生 continue。 | | fet ff | fet ff [...args] [--change <id>] | 通过 FET 执行 OpenSpec 原生 ff。 | | fet apply | fet apply [...args] [--change <id>] | 通过 FET 执行 OpenSpec 原生 apply，并同步 FET 状态。 | | fet verify | fet verify --change <id> | 生成 .fet/verify-instructions.md 手动验证指令。 | | fet verify --done | fet verify --done --change <id> | 声明已完成手动验证，允许后续 sync / archive。 | | fet verify --auto | fet verify --auto [--yes] | 生成自动验证执行计划；当前版本不执行项目脚本，--yes 会记录授权计划指纹。 | | fet sync | fet sync [...args] [--change <id>] | 在 FET verify gate 通过后，执行 OpenSpec 原生 sync。 | | fet archive | fet archive --change <id> | 在 FET verify gate 通过后，归档 change 并更新 OpenSpec 主规范。 | | fet bulk-archive | fet bulk-archive [...args] [--change <id>] | 通过 FET 执行 OpenSpec 原生 bulk-archive。 | | fet onboard | fet onboard [...args] [--change <id>] | 通过 FET 执行 OpenSpec 原生 onboard。 | | fet passthrough | fet passthrough <command> [...args] | 透传暂未接管的 OpenSpec 命令，不更新 FET 生命周期状态。 |

生成文件

FET 可能创建或更新：

• AGENTS.md
• openspec/config.yaml 的 fet: 命名空间
• openspec/fet-state.json
• openspec/changes/<change-id>/fet-state.json
• openspec/changes/<change-id>/.fet/verify-instructions.md
• .cursor/skills/fet-*/SKILL.md
• .cursor/rules/fet-context.mdc

FET 只拥有明确标记的托管区域，托管区域之外的用户内容应被保留。fet init 还会向 .gitignore 添加 FET 本地状态块，避免把锁文件和本地状态误提交。

安全边界

FET 是本地工作流辅助工具，不是沙箱、CI 强制 gate 或密码学审计系统。直接调用 openspec 可以绕过 FET 的本地 gate。团队如果需要强制执行验证，应在 CI、分支保护或代码审查规则中重复校验。

开发

npm install
npm run typecheck
npm run test
npm run build
npm run release:check

运行真实 OpenSpec 烟测：

$env:FET_REAL_OPENSPEC='1'; npm run test:real-openspec

许可证

MIT

English

FET is a frontend development workflow orchestration CLI built around OpenSpec. It does not generate business code directly. Instead, it proxies OpenSpec commands, maintains local workflow state, generates auditable project context, and helps AI coding tools such as Cursor and Codex load the right files.

What It Does

• Provides one entry point through fet <command> for OpenSpec workflows.
• Generates AGENTS.md and the fet: namespace in openspec/config.yaml.
• Tracks local workflow state such as active changes, synced tasks, manual verification declarations, and tool adapter state.
• Integrates with AI tools by generating Cursor project rules, Cursor Skill instructions, and Codex-readable FET workflow guides.
• Guards important stages by checking FET verification state before sync and archive.

How It Works

FET is a transparent proxy and local orchestration layer for OpenSpec. When you run commands such as fet apply or fet archive, FET loads project and change state, runs pre-hooks, calls the real openspec CLI, and then updates FET state based on the result.

FET proxy commands keep the OpenSpec command name intact. For example, fet apply --change <id> calls openspec apply --change <id>, and fet sync --change <id> calls openspec sync --change <id> after FET's verification gate passes.

Requirements

• Node.js 18 or newer
• OpenSpec CLI available on PATH

Install OpenSpec:

npm install -g @fission-ai/openspec

Installation

npm install -g @nick848/fet

Check the installation:

fet --version
fet --help

Quick Start

Run this in a project root:

fet init
fet doctor

Typical workflow:

fet new my-change
fet apply --change my-change
fet verify --change my-change
fet verify --done --change my-change
fet sync --change my-change
fet archive --change my-change

Global Options

| Option | Description | Example | |--------|-------------|---------| | --cwd <path> | Set project root. Defaults to current directory. | fet doctor --cwd ./app | | --change <id> | Select an OpenSpec change. | fet apply --change add-login | | --yes | Accept low-risk confirmations. | fet init --yes | | --json | Print machine-readable JSON. | fet doctor --json | | --verbose | Print more diagnostics. | fet doctor --verbose | | --no-color | Disable terminal colors. | fet --no-color doctor |

Commands

| Command | Usage | Description | |---------|-------|-------------| | fet init | fet init [--yes] | Initialize FET and OpenSpec; generate context, state, Cursor rules and Skills, plus Codex workflow guides. | | fet update-context | fet update-context [--yes] | Rescan the project and update FET-managed regions in AGENTS.md and openspec/config.yaml. | | fet fill-context | fet fill-context [--yes] | Refresh IDE handoff commands that ask Cursor/Codex/OpenCode-style AI to replace AGENTS.md placeholders. | | fet doctor | fet doctor [--fix-lock] | Diagnose OpenSpec, FET state, context files, Cursor and Codex integration, and lock files. | | fet explore | fet explore [...args] [--change <id>] | Run native OpenSpec explore through FET so clarification prompts stay interactive. | | fet propose | fet propose <change-id> | Create a new OpenSpec change through FET's proposal entry point. | | fet new | fet new <change-id> | Create a new OpenSpec change. | | fet continue | fet continue [...args] [--change <id>] | Run native OpenSpec continue through FET. | | fet ff | fet ff [...args] [--change <id>] | Run native OpenSpec ff through FET. | | fet apply | fet apply [...args] [--change <id>] | Run native OpenSpec apply through FET and update FET state. | | fet verify | fet verify --change <id> | Generate .fet/verify-instructions.md for manual verification. | | fet verify --done | fet verify --done --change <id> | Declare manual verification complete and allow sync / archive. | | fet verify --auto | fet verify --auto [--yes] | Generate an automatic verification plan. This version does not run project scripts; --yes records the plan fingerprint. | | fet sync | fet sync [...args] [--change <id>] | After FET verify gate passes, run native OpenSpec sync. | | fet archive | fet archive --change <id> | After FET verify gate passes, archive the change and append the change summary to CHANGELOG.md. | | fet bulk-archive | fet bulk-archive [...args] [--change <id>] | Run native OpenSpec bulk-archive through FET. | | fet onboard | fet onboard [...args] [--change <id>] | Run native OpenSpec onboard through FET. | | fet passthrough | fet passthrough <command> [...args] | Pass through unmanaged OpenSpec commands without updating FET lifecycle state. |

Generated Files

FET may create or update:

• AGENTS.md
• the fet: namespace in openspec/config.yaml
• openspec/fet-state.json
• openspec/changes/<change-id>/fet-state.json
• openspec/changes/<change-id>/.fet/verify-instructions.md
• CHANGELOG.md
• .cursor/skills/fet-*/SKILL.md
• .cursor/rules/fet-context.mdc
• .codex/fet/context.md
• .codex/fet/commands/*.md
• $CODEX_HOME/prompts/fet-*.md for Codex native slash commands. If CODEX_HOME is not set, FET uses ~/.codex.
• .fet/fill-context.md as a generic IDE handoff for tools without native command support.

FET only owns explicitly marked managed regions. User content outside those regions should be preserved. During fet init, FET also adds a managed .gitignore block for local workflow state.

Safety Model

FET is a local workflow helper. It is not a sandbox, mandatory CI gate, or cryptographic audit system. Direct openspec calls can bypass FET local gates. Teams that require enforcement should repeat validation in CI, branch protection, or review policy.

Development

npm install
npm run typecheck
npm run test
npm run build
npm run release:check

Run the real OpenSpec smoke test:

$env:FET_REAL_OPENSPEC='1'; npm run test:real-openspec

License

MIT