mirror of
https://github.com/cexll/myclaude.git
synced 2026-02-04 02:20:42 +08:00
170 lines
4.5 KiB
Markdown
170 lines
4.5 KiB
Markdown
# sparv - SPARV Workflow
|
|
|
|
Minimal 5-phase workflow: **S**pecify → **P**lan → **A**ct → **R**eview → **V**ault.
|
|
|
|
Completes "requirements → verifiable delivery" in one pass with external memory.
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
python install.py --module sparv
|
|
```
|
|
|
|
Installs to `~/.claude/skills/sparv/`.
|
|
|
|
## Usage
|
|
|
|
```
|
|
/sparv <task description>
|
|
```
|
|
|
|
## Core Rules (Mandatory)
|
|
|
|
| Rule | Description |
|
|
|------|-------------|
|
|
| **10-Point Specify Gate** | Spec score 0-10; must be >=9 to enter Plan |
|
|
| **2-Action Save** | Append to `.sparv/journal.md` every 2 tool calls |
|
|
| **3-Failure Protocol** | Stop and escalate after 3 consecutive failures |
|
|
| **EHRB** | Explicit confirmation for high-risk (production/sensitive/destructive/billing/security) |
|
|
| **Fixed Phase Names** | `specify|plan|act|review|vault` in `state.yaml` |
|
|
|
|
## 5-Phase Workflow
|
|
|
|
### Phase 1: Specify (10-Point Scale)
|
|
|
|
Each dimension scores 0/1/2, total 0-10:
|
|
|
|
| Dimension | Focus |
|
|
|-----------|-------|
|
|
| Value | Why do it, verifiable benefits/metrics |
|
|
| Scope | MVP + what's out of scope |
|
|
| Acceptance | Testable acceptance criteria |
|
|
| Boundaries | Error/performance/compatibility/security limits |
|
|
| Risk | EHRB/dependencies/unknowns + handling |
|
|
|
|
- `score < 9`: Keep asking questions; do not enter Plan
|
|
- `score >= 9`: Write `completion_promise`, then enter Plan
|
|
|
|
### Phase 2: Plan
|
|
|
|
- Break into atomic tasks (2-5 minute granularity)
|
|
- Each task has verifiable output/test point
|
|
- Write plan to `.sparv/journal.md`
|
|
|
|
### Phase 3: Act
|
|
|
|
- **TDD Rule**: No failing test → no production code
|
|
- Auto-write journal every 2 actions (PostToolUse hook)
|
|
- 3-Failure Protocol enforced
|
|
|
|
### Phase 4: Review
|
|
|
|
- Two stages: Spec conformance → Code quality
|
|
- Maximum 3 fix rounds; escalate if exceeded
|
|
- Run 3-question reboot test before session ends
|
|
|
|
### Phase 5: Vault
|
|
|
|
- Archive current session to `.sparv/history/`
|
|
- Update knowledge base `.sparv/kb.md`
|
|
|
|
## Enhanced Rules (v1.1)
|
|
|
|
### Uncertainty Declaration (G3)
|
|
|
|
When any Specify dimension scores < 2:
|
|
```
|
|
UNCERTAIN: <what> | ASSUMPTION: <fallback>
|
|
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 |
|
|
|
|
### 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
|
|
|
|
For non-trivial changes:
|
|
```bash
|
|
~/.claude/skills/sparv/scripts/changelog-update.sh --type <Added|Changed|Fixed|Removed> --desc "..."
|
|
```
|
|
|
|
## External Memory
|
|
|
|
Initialize (run in project root):
|
|
```bash
|
|
~/.claude/skills/sparv/scripts/init-session.sh --force
|
|
```
|
|
|
|
Creates:
|
|
```
|
|
.sparv/
|
|
├── state.yaml # State machine
|
|
├── journal.md # Unified log
|
|
├── kb.md # Knowledge base
|
|
└── history/ # Archive directory
|
|
```
|
|
|
|
| File | Purpose |
|
|
|------|--------|
|
|
| `state.yaml` | session_id, current_phase, action_count, consecutive_failures |
|
|
| `journal.md` | Plan/Progress/Findings unified log |
|
|
| `kb.md` | patterns/decisions/gotchas |
|
|
| `history/` | Archived sessions |
|
|
|
|
## Key Numbers
|
|
|
|
| Number | Meaning |
|
|
|--------|--------|
|
|
| **9/10** | Specify score passing threshold |
|
|
| **2** | Write to journal every 2 tool calls |
|
|
| **3** | Failure retry limit / Review fix limit |
|
|
| **3** | Reboot Test question count |
|
|
|
|
## Script Tools
|
|
|
|
| Script | Purpose |
|
|
|--------|--------|
|
|
| `init-session.sh` | Initialize `.sparv/`, generate state + journal |
|
|
| `save-progress.sh` | Maintain action_count, append journal |
|
|
| `check-ehrb.sh` | Scan diff/text, output ehrb_flags |
|
|
| `failure-tracker.sh` | Maintain consecutive_failures |
|
|
| `reboot-test.sh` | 3-question self-check |
|
|
| `archive-session.sh` | Archive to history/ |
|
|
| `changelog-update.sh` | Update CHANGELOG.md |
|
|
|
|
## Auto Hooks
|
|
|
|
Configured in `hooks/hooks.json`:
|
|
|
|
- **PostToolUse**: `save-progress.sh` (2-Action save)
|
|
- **PreToolUse**: `check-ehrb.sh --diff --dry-run` (prompt only)
|
|
- **Stop**: `reboot-test.sh --strict` (3-question self-check)
|
|
|
|
## Failure Tracking
|
|
|
|
```bash
|
|
# Record failure
|
|
~/.claude/skills/sparv/scripts/failure-tracker.sh fail --note "short blocker"
|
|
|
|
# Reset counter
|
|
~/.claude/skills/sparv/scripts/failure-tracker.sh reset
|
|
```
|
|
|
|
## Uninstall
|
|
|
|
```bash
|
|
python install.py --uninstall --module sparv
|
|
```
|