sparv

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SPARV

Five-phase workflow: Specify → Plan → Act → Review → Vault.

Goal: Complete "requirements → verifiable delivery" in one pass, recording key decisions in external memory instead of relying on assumptions.

五阶段工作流：Specify（明确需求）→ Plan（制定计划）→ Act（执行实施）→ Review（评审验证）→ Vault（归档存储）。

目标：一次性完成“需求→可验证交付”的全流程，将关键决策记录到外部存储器中，而非依赖主观假设。

Core Rules (Mandatory)

核心规则（强制性）

10-Point Specify Gate: Spec score
```
0-10
```
; must be
```
>=9
```
to enter Plan.
2-Action Save: Append an entry to
```
.sparv/journal.md
```
every 2 tool calls.
3-Failure Protocol: Stop and escalate to user after 3 consecutive failures.
EHRB: Require explicit user confirmation when high-risk detected (production/sensitive data/destructive/billing API/security-critical).

Fixed Phase Names:

specify|plan|act|review|vault

(stored in

.sparv/state.yaml:current_phase

10分规格准入门槛：规格评分范围
```
0-10
```
；评分必须
```
>=9
```
才能进入Plan阶段。
双操作保存规则：每执行2次工具调用后，向
```
.sparv/journal.md
```
追加一条记录。
三次失败协议：连续失败3次后，停止操作并向用户升级反馈。
EHRB风险检测：当检测到高风险操作（生产环境/敏感数据/破坏性操作/计费API/安全关键操作）时，需获得用户的明确确认。

固定阶段名称：

specify|plan|act|review|vault

（存储在

.sparv/state.yaml:current_phase

中）。

Enhanced Rules (v1.1)

增强规则（v1.1）

Uncertainty Declaration (G3)

不确定性声明（G3）

When any Specify dimension scores < 2:

Declare:

UNCERTAIN: <what> | ASSUMPTION: <fallback>

List all assumptions in journal before Plan
Offer 2-3 options for ambiguous requirements

Example:

UNCERTAIN: deployment target | ASSUMPTION: Docker container
UNCERTAIN: auth method | OPTIONS: JWT / OAuth2 / Session

当任意规格维度评分<2时：

声明格式：

UNCERTAIN: <不确定内容> | ASSUMPTION: <默认假设>

在进入Plan阶段前，将所有假设记录到日志中
针对模糊需求提供2-3种可选方案

示例：

UNCERTAIN: deployment target | ASSUMPTION: Docker container
UNCERTAIN: auth method | OPTIONS: JWT / OAuth2 / Session

Requirement Routing

需求路由

Mode	Condition	Flow
Quick	score >= 9 AND <= 3 files AND no EHRB	Specify → Act → Review
Full	otherwise	Specify → Plan → Act → Review → Vault

Quick mode skips formal Plan phase but still requires:

Completion promise written to journal
2-action save rule applies
Review phase mandatory

模式	条件	流程
快速模式	评分>=9 且文件数<=3 且无EHRB风险	Specify → Act → Review
完整模式	其他情况	Specify → Plan → Act → Review → Vault

快速模式跳过正式的Plan阶段，但仍需满足：

将完成承诺写入日志
双操作保存规则依然适用
Review阶段为必填项

Context Acquisition (Optional)

上下文获取（可选）

Before Specify scoring:

Check
```
.sparv/kb.md
```
for existing patterns/decisions
If insufficient, scan codebase for relevant files
Document findings in journal under
```
## Context
```

Skip if user explicitly provides full context.

在规格评分前：

检查
```
.sparv/kb.md
```
中是否存在现有模式/决策
若信息不足，扫描代码库查找相关文件
将发现的内容记录到日志的
```
## Context
```
部分

若用户明确提供完整上下文，可跳过此步骤。

Knowledge Base Maintenance

知识库维护

During Vault phase, update

.sparv/kb.md

Patterns: Reusable code patterns discovered
Decisions: Architectural choices + rationale
Gotchas: Common pitfalls + solutions

在Vault阶段，更新

.sparv/kb.md

：

模式：记录可复用的代码模式
决策：记录架构选择及其理由
注意事项：记录常见陷阱及解决方案

CHANGELOG Update

更新CHANGELOG

Use during Review or Vault phase for non-trivial changes:

bash

~/.claude/skills/sparv/scripts/changelog-update.sh --type <Added|Changed|Fixed|Removed> --desc "..."

在Review或Vault阶段，针对非微小变更执行以下操作：

bash

~/.claude/skills/sparv/scripts/changelog-update.sh --type <Added|Changed|Fixed|Removed> --desc "..."

External Memory (Two Files)

外部存储器（两个核心文件）

Initialize (run in project root):

bash

~/.claude/skills/sparv/scripts/init-session.sh --force

File conventions:

.sparv/state.yaml

: State machine (minimum fields:

session_id/current_phase/action_count/consecutive_failures

)

```
.sparv/journal.md
```
: Unified log (Plan/Progress/Findings all go here)
```
.sparv/history/<session_id>/
```
: Archive directory

初始化（在项目根目录执行）：

bash

~/.claude/skills/sparv/scripts/init-session.sh --force

文件规范：

.sparv/state.yaml

：状态机（必填字段：

session_id/current_phase/action_count/consecutive_failures

）

```
.sparv/journal.md
```
：统一日志（计划/进度/发现内容均需记录于此）
```
.sparv/history/<session_id>/
```
：归档目录

Phase 1: Specify (10-Point Scale)

阶段1：Specify（10分制评分）

Each item scores 0/1/2, total 0-10:

Value: Why do it, are benefits/metrics verifiable
Scope: MVP + what's out of scope
Acceptance: Testable acceptance criteria
Boundaries: Error/performance/compatibility/security critical boundaries
Risk: EHRB/dependencies/unknowns + handling approach

score < 9

: Keep asking questions; do not enter Plan.

score >= 9

: Write a clear

completion_promise

(verifiable completion commitment), then enter Plan.

每个项目评分0/1/2，总分0-10：

价值：实施理由，收益/指标是否可验证
范围：最小可行产品（MVP）及排除范围
验收标准：可测试的验收条件
边界限制：错误/性能/兼容性/安全关键边界
风险：EHRB风险/依赖项/未知因素及应对方案

score < 9

：继续询问问题；不得进入Plan阶段。

score >= 9

：撰写清晰的

completion_promise

（可验证的完成承诺），然后进入Plan阶段。

Phase 2: Plan

阶段2：Plan

Break into atomic tasks (2-5 minute granularity), each with a verifiable output/test point.
Write the plan to
```
.sparv/journal.md
```
(Plan section or append directly).

将任务拆解为原子化任务（粒度为2-5分钟），每个任务需具备可验证的输出/测试点。
将计划写入
```
.sparv/journal.md
```
（Plan章节或直接追加）。

Phase 3: Act

阶段3：Act

TDD Rule: No failing test → no production code.
Auto-write journal every 2 actions (PostToolUse hook).
Failure counting (3-Failure Protocol):

bash

~/.claude/skills/sparv/scripts/failure-tracker.sh fail --note "short blocker"
~/.claude/skills/sparv/scripts/failure-tracker.sh reset

TDD规则：无失败测试用例→不得编写生产代码。
每执行2次操作后自动写入日志（通过PostToolUse钩子）。
失败计数（遵循三次失败协议）：

bash

~/.claude/skills/sparv/scripts/failure-tracker.sh fail --note "short blocker"
~/.claude/skills/sparv/scripts/failure-tracker.sh reset

Phase 4: Review

阶段4：Review

Two stages: Spec conformance → Code quality (correctness/performance/security/tests).
Maximum 3 fix rounds; escalate to user if exceeded.

Run 3-question reboot test before session ends:

bash

~/.claude/skills/sparv/scripts/reboot-test.sh --strict

两个阶段：规格一致性检查→代码质量检查（正确性/性能/安全性/测试覆盖）。
最多允许3轮修复；若超出次数，向用户升级反馈。

会话结束前运行三问题重启测试：

bash

~/.claude/skills/sparv/scripts/reboot-test.sh --strict

Phase 5: Vault

阶段5：Vault

Archive current session:

bash

~/.claude/skills/sparv/scripts/archive-session.sh

归档当前会话：

bash

~/.claude/skills/sparv/scripts/archive-session.sh

Script Tools

脚本工具

Script	Purpose
`scripts/init-session.sh`	Initialize `.sparv/` , generate `state.yaml` + `journal.md`
`scripts/save-progress.sh`	Maintain `action_count` , append to `journal.md` every 2 actions
`scripts/check-ehrb.sh`	Scan diff/text, output (optionally write) `ehrb_flags`
`scripts/failure-tracker.sh`	Maintain `consecutive_failures` , exit code 3 when reaching 3
`scripts/reboot-test.sh`	3-question self-check (optional strict mode)
`scripts/archive-session.sh`	Archive `journal.md` + `state.yaml` to `history/`

脚本	用途
`scripts/init-session.sh`	初始化 `.sparv/` 目录，生成 `state.yaml` + `journal.md`
`scripts/save-progress.sh`	维护 `action_count` ，每2次操作后向 `journal.md` 追加记录
`scripts/check-ehrb.sh`	扫描差异/文本，输出（可选写入） `ehrb_flags`
`scripts/failure-tracker.sh`	维护 `consecutive_failures` ，当达到3次时返回退出码3
`scripts/reboot-test.sh`	三问题自检（可选严格模式）
`scripts/archive-session.sh`	将 `journal.md` + `state.yaml` 归档到 `history/` 目录

Auto Hooks

自动钩子

hooks/hooks.json

PostToolUse:
```
save-progress.sh
```
(2-Action save)
PreToolUse:
```
check-ehrb.sh --diff --dry-run
```
(prompt only, no state write)
Stop:
```
reboot-test.sh --strict
```
(3-question self-check)

Quality over speed—iterate until truly complete.

hooks/hooks.json

PostToolUse:
```
save-progress.sh
```
（双操作保存规则）
PreToolUse:
```
check-ehrb.sh --diff --dry-run
```
（仅提示，不修改状态）
Stop:
```
reboot-test.sh --strict
```
（三问题自检）

质量优先于速度——反复迭代直至真正完成。