mirror of
https://github.com/cexll/myclaude.git
synced 2026-02-15 03:32:43 +08:00
docs: update do/omo/sparv module READMEs with detailed workflows
Generated with SWE-Agent.ai Co-Authored-By: SWE-Agent.ai <noreply@swe-agent.ai>
This commit is contained in:
cexll
@@ -1,96 +1,169 @@
|
||||
# SPARV - Unified Development Workflow (Simplified)
|
||||
# sparv - SPARV Workflow
|
||||
|
||||
[]()
|
||||
[]()
|
||||
Minimal 5-phase workflow: **S**pecify → **P**lan → **A**ct → **R**eview → **V**ault.
|
||||
|
||||
**SPARV** is an end-to-end development workflow: maximize delivery quality with minimal rules while avoiding "infinite iteration + self-rationalization."
|
||||
|
||||
```
|
||||
S-Specify → P-Plan → A-Act → R-Review → V-Vault
|
||||
Clarify Plan Execute Review Archive
|
||||
```
|
||||
|
||||
## Key Changes (Over-engineering Removed)
|
||||
|
||||
- External memory merged from 3 files into 1 `.sparv/journal.md`
|
||||
- Specify scoring simplified from 100-point to 10-point scale (threshold `>=9`)
|
||||
- Reboot Test reduced from 5 questions to 3 questions
|
||||
- Removed concurrency locks (Claude is single-threaded; locks only cause failures)
|
||||
Completes "requirements → verifiable delivery" in one pass with external memory.
|
||||
|
||||
## Installation
|
||||
|
||||
SPARV is installed at `~/.claude/skills/sparv/`.
|
||||
|
||||
Install from ZIP:
|
||||
|
||||
```bash
|
||||
unzip sparv.zip -d ~/.claude/skills/
|
||||
python install.py --module sparv
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
Installs to `~/.claude/skills/sparv/`.
|
||||
|
||||
Run in project root:
|
||||
## 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
|
||||
├── journal.md
|
||||
└── history/
|
||||
├── state.yaml # State machine
|
||||
├── journal.md # Unified log
|
||||
├── kb.md # Knowledge base
|
||||
└── history/ # Archive directory
|
||||
```
|
||||
|
||||
## External Memory System (Two Files)
|
||||
|
||||
- `state.yaml`: State (minimum fields: `session_id/current_phase/action_count/consecutive_failures`)
|
||||
- `journal.md`: Unified log (Plan/Progress/Findings all go here)
|
||||
|
||||
After archiving:
|
||||
|
||||
```
|
||||
.sparv/history/<session_id>/
|
||||
├── state.yaml
|
||||
└── journal.md
|
||||
```
|
||||
| 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 |
|
||||
| **12** | Default max iterations (optional safety valve) |
|
||||
|
||||
## 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
|
||||
~/.claude/skills/sparv/scripts/init-session.sh --force
|
||||
~/.claude/skills/sparv/scripts/save-progress.sh "Edit" "done"
|
||||
~/.claude/skills/sparv/scripts/check-ehrb.sh --diff --fail-on-flags
|
||||
~/.claude/skills/sparv/scripts/failure-tracker.sh fail --note "tests are flaky"
|
||||
~/.claude/skills/sparv/scripts/reboot-test.sh --strict
|
||||
~/.claude/skills/sparv/scripts/archive-session.sh
|
||||
# Record failure
|
||||
~/.claude/skills/sparv/scripts/failure-tracker.sh fail --note "short blocker"
|
||||
|
||||
# Reset counter
|
||||
~/.claude/skills/sparv/scripts/failure-tracker.sh reset
|
||||
```
|
||||
|
||||
## Hooks
|
||||
## Uninstall
|
||||
|
||||
Hooks defined in `hooks/hooks.json`:
|
||||
|
||||
- PostToolUse: 2-Action auto-write to `journal.md`
|
||||
- PreToolUse: EHRB risk prompt (default dry-run)
|
||||
- Stop: 3-question reboot test (strict)
|
||||
|
||||
## References
|
||||
|
||||
- `SKILL.md`: Skill definition (for agent use)
|
||||
- `references/methodology.md`: Methodology quick reference
|
||||
|
||||
---
|
||||
|
||||
*Quality over speed—iterate until truly complete.*
|
||||
```bash
|
||||
python install.py --uninstall --module sparv
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user