🔶 Speck：受编译器和构建工具启发的 AI 规格驱动代理

规格驱动的代理编译器：使用简单命令完成完整的代理管理，支持可复现且可验证的代码生成，将传统聊天界面移至幕后。

注意： speck 基于 zerostack，并需要可工作的 zerostack 二进制文件位于 PATH 中。

• 三层架构：specs/features/（做什么）→ specs/technical/（怎么做）→ src/（代码）。编辑任一层，其他层保持同步。
• 双向同步：speck apply 通过 BLAKE3 哈希检测变更，并使用专门的 AI 提示在层之间传播更新。
• 从现有项目迁移：speck migrate 从任意代码库反向生成 specs/technical/，再从中衍生出 specs/features/。
• 脚手架：speck init 引导创建新项目，包含规范的 AGENTS.md、ARCHITECTURE.md 和提示模板。
• 冲突解决：当代码和规格都被编辑时，speck 会提示选择优先级（或使用 --prefer-code / --prefer-specs）。
• 代码审查：speck review 通过专用提示执行全面、结构化的审查，输出 Markdown 报告。
• Git 钩子：speck git-hooks 安装 pre-commit、pre-push、post-merge 和 post-checkout 钩子，自动运行 speck apply、speck fmt 或 speck status。
• 技术栈切换：speck switch-lang 破坏性地更改语言/框架，并从功能规格重新构建所有内容。
• 文件管理：speck mv 和 speck rm 移动或删除文件，同时保持哈希数据库同步。
• 变更检测：speck status 列出按层分组的已编辑和未注册文件。

你可以从 Github releases 下载预编译二进制文件。

git clone https://github.com/gi-dellav/speck.git
cd speck
cargo install --path .


# 确保 zerostack 已安装并配置
zerostack --version

# 搭建新的 speck 项目
speck init

# 或迁移现有代码库
speck migrate

# 在规格和代码之间同步编辑
speck apply

# 检查发生了什么变化
speck status

# 完整代码审查
speck review --output report.md

Speck 从项目根目录读取 Speck.toml：

Speck 维护一个三层架构，每一层都是同一产品的不同表示：

speck apply 运行一个 4 步管道：

1. 检测变更——将当前 BLAKE3 哈希与 .speck_hash.toml 进行比较
2. feat2tech——将功能规格编辑向下传播到技术规格
3. tech2code——将技术规格编辑向下传播到源代码
4. code2tech——将源代码编辑向上传播到技术规格

每一步都使用专门的 zerostack 提示，并设置适当的温度（确定性更新为 0，创造性规格扩展则更高）。

当源文件及其对应的技术规格自上次同步以来都被编辑时，speck 无法知道哪一个应该作为权威。它会以交互方式提示：

Both spec and code changed for src/auth.rs — which takes priority?
[1] Code (update specs to match)
[2] Specs (update code to match)

使用 --prefer-code 或 --prefer-specs 可以非交互式地解决所有冲突。

Speck 在 data/prompts/ 中附带五个专门的 zerostack 提示：

这些提示在 speck init 时安装到你的项目中，并可按项目自定义。

Speck 自带了默认的 AGENTS.md 和 ARCHITECTURE.md 模板，在 speck init 时会被搭建到新项目中。这些模板为所有在代码库上工作的代理（包括 zerostack）提供了共享的核心知识。

GPL-3.0-only

Spec-driven agentic compiler: simple commands for complete agent managament, allowing for reproducible and verifiable code generation, moving the traditional chat interface out of the spotlight.

note: speck is a based on zerostack and it requires a working zerostack binary on PATH.

• Three-layer architecture : specs/features/ (what) → specs/technical/ (how) → src/ (code). Edit any layer, the others stay in sync.
• Bidirectional sync : speck apply detects changes via BLAKE3 hashes and propagates them through the layers using specialized AI prompts.
• Migration from existing projects : speck migrate reverse-engineers specs/technical/ from any codebase, then derives specs/features/ from that.
• Scaffolding : speck init bootstraps a new project with canonical AGENTS.md, ARCHITECTURE.md, and prompt templates.
• Conflict resolution : when both code and specs are edited, speck prompts for priority (or use --prefer-code / --prefer-specs).
• Code review : speck review runs a comprehensive, structured review via a specialized prompt, outputting a Markdown report.
• Git hooks : speck git-hooks installs pre-commit, pre-push, post-merge, and post-checkout hooks that run speck apply, speck fmt, or speck status automatically.
• Tech stack switching : speck switch-lang destructively changes language/framework and rebuilds everything from feature specs.
• File management : speck mv and speck rm move or remove files while keeping the hash database in sync.
• Change detection : speck status lists edited and unregistered files grouped by layer.

You can download compiled binaries from Github releases.

git clone https://github.com/gi-dellav/speck.git
cd speck
cargo install --path .


# Ensure zerostack is installed and configured
zerostack --version

# Scaffold a new speck project
speck init

# Or migrate an existing codebase
speck migrate

# Sync edits between specs and code
speck apply

# Check what changed
speck status

# Full code review
speck review --output report.md

Speck reads Speck.toml from the project root:

Speck maintains a three-layer architecture where each layer is a different representation of the same product:

speck apply runs a 4-step pipeline:

1. Detect changes — compare current BLAKE3 hashes against .speck_hash.toml
2. feat2tech — propagate feature spec edits down to technical specs
3. tech2code — propagate technical spec edits down to source code
4. code2tech — propagate source code edits up to technical specs

Each step uses a specialized zerostack prompt at the appropriate temperature (0 for deterministic updates, higher for creative spec expansion).

When both a source file and its corresponding technical spec are edited since the last sync, speck cannot know which is authoritative. It prompts interactively:

Both spec and code changed for src/auth.rs — which takes priority?
[1] Code (update specs to match)
[2] Specs (update code to match)

Use --prefer-code or --prefer-specs to resolve all conflicts non-interactively.

Speck ships with five specialized zerostack prompts in data/prompts/:

These are installed into your project on speck init and can be customized per-project.

Speck ships default AGENTS.md and ARCHITECTURE.md templates that are scaffolded into new projects on speck init. These provide shared core knowledge for all agents (including zerostack) working on the codebase.

GPL-3.0-only