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
2026-01-24 14:27:39 +08:00
parent d98086c661
commit b49dad842a
3 changed files with 367 additions and 144 deletions

View File

@@ -1,6 +1,6 @@
# do
# do - Feature Development Orchestrator
7-phase feature development workflow, orchestrating multiple agents via codeagent-wrapper.
7-phase feature development workflow orchestrating multiple agents via codeagent-wrapper.
## Installation
@@ -24,30 +24,141 @@ Examples:
/do implement order export to CSV
```
## Workflow Phases
## 7-Phase Workflow
| Phase | Name | Goal |
|-------|------|------|
| 1 | Discovery | Understand requirements |
| 2 | Exploration | Explore codebase |
| 3 | Clarification | Resolve ambiguities (mandatory) |
| 4 | Architecture | Design approach |
| 5 | Implementation | Build (requires approval) |
| 6 | Review | Code review |
| 7 | Summary | Document results |
| Phase | Name | Goal | Key Actions |
|-------|------|------|-------------|
| 1 | Discovery | Understand requirements | AskUserQuestion + code-architect draft |
| 2 | Exploration | Map codebase patterns | 2-3 parallel code-explorer tasks |
| 3 | Clarification | Resolve ambiguities | **MANDATORY** - must answer before proceeding |
| 4 | Architecture | Design implementation | 2 parallel code-architect approaches |
| 5 | Implementation | Build the feature | **Requires approval** - develop agent |
| 6 | Review | Catch defects | 2-3 parallel code-reviewer tasks |
| 7 | Summary | Document results | code-reviewer summary |
## Agents
- `code-explorer` - Code tracing, architecture mapping
- `code-architect` - Design approaches, file planning
- `code-reviewer` - Code review, simplification suggestions
- `develop` - Implement code, run tests
| Agent | Purpose | Prompt Location |
|-------|---------|----------------|
| `code-explorer` | Code tracing, architecture mapping | `agents/code-explorer.md` |
| `code-architect` | Design approaches, file planning | `agents/code-architect.md` |
| `code-reviewer` | Code review, simplification | `agents/code-reviewer.md` |
| `develop` | Implement code, run tests | global config |
Agent prompts are in the `agents/` directory. To customize, create same-named files in `~/.codeagent/agents/` to override.
To customize agents, create same-named files in `~/.codeagent/agents/` to override.
## Hard Constraints
1. **Never write code directly** - delegate all changes to codeagent-wrapper agents
2. **Phase 3 is mandatory** - do not proceed until questions are answered
3. **Phase 5 requires approval** - stop after Phase 4 if not approved
4. **Pass complete context forward** - every agent gets the Context Pack
5. **Parallel-first** - run independent tasks via `codeagent-wrapper --parallel`
6. **Update state after each phase** - keep `.claude/do.local.md` current
## Context Pack Template
```text
## Original User Request
<verbatim request>
## Context Pack
- Phase: <1-7 name>
- Decisions: <requirements/constraints/choices>
- Code-explorer output: <paste or "None">
- Code-architect output: <paste or "None">
- Code-reviewer output: <paste or "None">
- Develop output: <paste or "None">
- Open questions: <list or "None">
## Current Task
<specific task>
## Acceptance Criteria
<checkable outputs>
```
## Loop State Management
When triggered via `/do <task>`, initializes `.claude/do.local.md` with:
- `active: true`
- `current_phase: 1`
- `max_phases: 7`
- `completion_promise: "<promise>DO_COMPLETE</promise>"`
After each phase, update frontmatter:
```yaml
current_phase: <next phase number>
phase_name: "<next phase name>"
```
When all 7 phases complete, output:
```
<promise>DO_COMPLETE</promise>
```
To abort early, set `active: false` in the state file.
## Stop Hook
A Stop hook is registered after installation:
1. Creates `.claude/do.local.md` state file
2. Updates `current_phase` after each phase
3. Stop hook checks state, blocks exit if incomplete
4. Outputs `<promise>DO_COMPLETE</promise>` when finished
Manual exit: Set `active` to `false` in the state file.
## Parallel Execution Examples
### Phase 2: Exploration (3 parallel tasks)
```bash
codeagent-wrapper --parallel <<'EOF'
---TASK---
id: p2_similar_features
agent: code-explorer
workdir: .
---CONTENT---
Find similar features, trace end-to-end.
---TASK---
id: p2_architecture
agent: code-explorer
workdir: .
---CONTENT---
Map architecture for relevant subsystem.
---TASK---
id: p2_conventions
agent: code-explorer
workdir: .
---CONTENT---
Identify testing patterns and conventions.
EOF
```
### Phase 4: Architecture (2 approaches)
```bash
codeagent-wrapper --parallel <<'EOF'
---TASK---
id: p4_minimal
agent: code-architect
workdir: .
---CONTENT---
Propose minimal-change architecture.
---TASK---
id: p4_pragmatic
agent: code-architect
workdir: .
---CONTENT---
Propose pragmatic-clean architecture.
EOF
```
## ~/.codeagent/models.json Configuration
Optional. Uses codeagent-wrapper built-in config by default. To customize agent models:
Optional. Uses codeagent-wrapper built-in config by default. To customize:
```json
{
@@ -68,17 +179,6 @@ Optional. Uses codeagent-wrapper built-in config by default. To customize agent
}
```
## Loop Mechanism
A Stop hook is registered after installation. When `/do` runs:
1. Creates `.claude/do.local.md` state file
2. Updates `current_phase` after each phase
3. Stop hook checks state, blocks exit if incomplete
4. Outputs `<promise>DO_COMPLETE</promise>` when finished
Manual exit: Set `active` to `false` in the state file.
## Uninstall
```bash

View File

@@ -1,14 +1,14 @@
# OmO Multi-Agent Orchestration
# omo - Multi-Agent Orchestration
OmO (Oh-My-OpenCode) is a multi-agent orchestration skill that delegates tasks to specialized agents based on routing signals.
OmO is a multi-agent orchestration skill that routes tasks to specialized agents based on risk signals.
## Installation
```bash
python3 install.py --module omo
python install.py --module omo
```
## Quick Start
## Usage
```
/omo <your task>
@@ -18,59 +18,107 @@ python3 install.py --module omo
| Agent | Role | Backend | Model |
|-------|------|---------|-------|
| oracle | Technical advisor | claude | claude-opus-4-5-20251101 |
| librarian | External research | claude | claude-sonnet-4-5-20250929 |
| explore | Codebase search | opencode | opencode/grok-code |
| develop | Code implementation | codex | gpt-5.2 |
| frontend-ui-ux-engineer | UI/UX specialist | gemini | gemini-3-pro-preview |
| document-writer | Documentation | gemini | gemini-3-flash-preview |
| `oracle` | Technical advisor | claude | claude-opus-4-5 |
| `librarian` | External research | claude | claude-sonnet-4-5 |
| `explore` | Codebase search | opencode | grok-code |
| `develop` | Code implementation | codex | gpt-5.2 |
| `frontend-ui-ux-engineer` | UI/UX specialist | gemini | gemini-3-pro |
| `document-writer` | Documentation | gemini | gemini-3-flash |
## How It Works
## Routing Signals (Not Fixed Pipeline)
1. `/omo` analyzes your request via routing signals
2. Based on task type, it either:
- Answers directly (analysis/explanation tasks - no code changes)
- Delegates to specialized agents (implementation tasks)
- Fires parallel agents (exploration + research)
This skill is **routing-first**, not a mandatory conveyor belt.
| Signal | Add Agent |
|--------|----------|
| Code location/behavior unclear | `explore` |
| External library/API usage unclear | `librarian` |
| Risky change (multi-file, public API, security, perf) | `oracle` |
| Implementation required | `develop` / `frontend-ui-ux-engineer` |
| Documentation needed | `document-writer` |
### Skipping Heuristics
- Skip `explore` when exact file path + line number is known
- Skip `oracle` when change is local + low-risk (single area, clear fix)
- Skip implementation agents when user only wants analysis
## Common Recipes
| Task | Recipe |
|------|--------|
| Explain code | `explore` |
| Small fix with known location | `develop` directly |
| Bug fix, location unknown | `explore → develop` |
| Cross-cutting refactor | `explore → oracle → develop` |
| External API integration | `explore + librarian → oracle → develop` |
| UI-only change | `explore → frontend-ui-ux-engineer` |
| Docs-only change | `explore → document-writer` |
## Context Pack Template
Every agent invocation includes:
```text
## Original User Request
<original request>
## Context Pack (include anything relevant; write "None" if absent)
- Explore output: <...>
- Librarian output: <...>
- Oracle output: <...>
- Known constraints: <tests to run, time budget, repo conventions>
## Current Task
<specific task description>
## Acceptance Criteria
<clear completion conditions>
```
## Agent Invocation
```bash
codeagent-wrapper --agent <agent_name> - <workdir> <<'EOF'
## Original User Request
...
## Context Pack
...
## Current Task
...
## Acceptance Criteria
...
EOF
```
Timeout: 2 hours.
## Examples
```bash
# Refactoring
/omo Help me refactor this authentication module
# Analysis only
/omo how does this function work?
# → explore
# Feature development
/omo I need to add a new payment feature with frontend UI and backend API
# Bug fix with unknown location
/omo fix the authentication bug
# → explore → develop
# Research
/omo What authentication scheme does this project use?
```
# Feature with external API
/omo add Stripe payment integration
# → explore + librarian → oracle → develop
## Agent Delegation
Delegates via codeagent-wrapper with full Context Pack:
```bash
codeagent-wrapper --agent oracle - . <<'EOF'
## Original User Request
Analyze the authentication architecture and recommend improvements.
## Context Pack (include anything relevant; write "None" if absent)
- Explore output: [paste explore output if available]
- Librarian output: None
- Oracle output: None
## Current Task
Review auth architecture, identify risks, propose minimal improvements.
## Acceptance Criteria
Output: recommendation, action plan, risk assessment, effort estimate.
EOF
# UI change
/omo redesign the dashboard layout
# → explore → frontend-ui-ux-engineer
```
## Configuration
Agent-model mappings are configured in `~/.codeagent/models.json`:
Agent-model mappings in `~/.codeagent/models.json`:
```json
{
@@ -80,34 +128,28 @@ Agent-model mappings are configured in `~/.codeagent/models.json`:
"oracle": {
"backend": "claude",
"model": "claude-opus-4-5-20251101",
"description": "Technical advisor",
"yolo": true
},
"librarian": {
"backend": "claude",
"model": "claude-sonnet-4-5-20250929",
"description": "Researcher",
"yolo": true
},
"explore": {
"backend": "opencode",
"model": "opencode/grok-code",
"description": "Code search"
"model": "opencode/grok-code"
},
"frontend-ui-ux-engineer": {
"backend": "gemini",
"model": "gemini-3-pro-preview",
"description": "Frontend engineer"
"model": "gemini-3-pro-preview"
},
"document-writer": {
"backend": "gemini",
"model": "gemini-3-flash-preview",
"description": "Documentation"
"model": "gemini-3-flash-preview"
},
"develop": {
"backend": "codex",
"model": "gpt-5.2",
"description": "codex develop",
"yolo": true,
"reasoning": "xhigh"
}
@@ -115,6 +157,14 @@ Agent-model mappings are configured in `~/.codeagent/models.json`:
}
```
## Hard Constraints
1. **Never write code yourself** - delegate to implementation agents
2. **Always pass context forward** - include original request + prior outputs
3. **No direct grep/glob for non-trivial exploration** - use `explore`
4. **No external docs guessing** - use `librarian`
5. **Use fewest agents possible** - skipping is normal
## Requirements
- codeagent-wrapper with `--agent` support

View File

@@ -1,96 +1,169 @@
# SPARV - Unified Development Workflow (Simplified)
# sparv - SPARV Workflow
[![Skill Version](https://img.shields.io/badge/version-1.0.0-blue.svg)]()
[![Claude Code](https://img.shields.io/badge/Claude%20Code-Compatible-green.svg)]()
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
```