Back to Details

sparv

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

SPARV

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

需求路由

ModeConditionFlow
Quickscore >= 9 AND <= 3 files AND no EHRBSpecify → Act → Review
FullotherwiseSpecify → 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:
  1. Check 
    .sparv/kb.md
    for existing patterns/decisions
  2. If insufficient, scan codebase for relevant files
  3. Document findings in journal under 
    ## Context
Skip if user explicitly provides full context.
在规格评分前：
  1. 检查
    .sparv/kb.md
    中是否存在现有模式/决策
  2. 若信息不足，扫描代码库查找相关文件
  3. 将发现的内容记录到日志的
    ## 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:
  1. Value: Why do it, are benefits/metrics verifiable
  2. Scope: MVP + what's out of scope
  3. Acceptance: Testable acceptance criteria
  4. Boundaries: Error/performance/compatibility/security critical boundaries
  5. 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：
  1. 价值：实施理由，收益/指标是否可验证
  2. 范围：最小可行产品（MVP）及排除范围
  3. 验收标准：可测试的验收条件
  4. 边界限制：错误/性能/兼容性/安全关键边界
  5. 风险：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

脚本工具

ScriptPurpose
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
    （三问题自检）
质量优先于速度——反复迭代直至真正完成。