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.

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).

Enhanced Rules (v1.1)

Uncertainty Declaration (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

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

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.

Knowledge Base Maintenance

During Vault phase, update .sparv/kb.md:

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

CHANGELOG Update

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

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

External Memory (Two Files)

Initialize (run in project root):

~/.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

Phase 1: Specify (10-Point Scale)

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.

Phase 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).

Phase 3: Act

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

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

Phase 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:

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

Phase 5: Vault

Archive current session:

~/.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/

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.