From b49dad842a7fcfb432c0cd7e33afcaea00e73c42 Mon Sep 17 00:00:00 2001 From: cexll Date: Sat, 24 Jan 2026 14:27:39 +0800 Subject: [PATCH] docs: update do/omo/sparv module READMEs with detailed workflows Generated with SWE-Agent.ai Co-Authored-By: SWE-Agent.ai --- skills/do/README.md | 158 +++++++++++++++++++++++++++------ skills/omo/README.md | 156 +++++++++++++++++++++----------- skills/sparv/README.md | 197 ++++++++++++++++++++++++++++------------- 3 files changed, 367 insertions(+), 144 deletions(-) diff --git a/skills/do/README.md b/skills/do/README.md index 3a28278..45043e2 100644 --- a/skills/do/README.md +++ b/skills/do/README.md @@ -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 + + +## Context Pack +- Phase: <1-7 name> +- Decisions: +- Code-explorer output: +- Code-architect output: +- Code-reviewer output: +- Develop output: +- Open questions: + +## Current Task + + +## Acceptance Criteria + +``` + +## Loop State Management + +When triggered via `/do `, initializes `.claude/do.local.md` with: +- `active: true` +- `current_phase: 1` +- `max_phases: 7` +- `completion_promise: "DO_COMPLETE"` + +After each phase, update frontmatter: +```yaml +current_phase: +phase_name: "" +``` + +When all 7 phases complete, output: +``` +DO_COMPLETE +``` + +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 `DO_COMPLETE` 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 `DO_COMPLETE` when finished - -Manual exit: Set `active` to `false` in the state file. - ## Uninstall ```bash diff --git a/skills/omo/README.md b/skills/omo/README.md index 712deb2..023e402 100644 --- a/skills/omo/README.md +++ b/skills/omo/README.md @@ -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 @@ -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 + + +## Context Pack (include anything relevant; write "None" if absent) +- Explore output: <...> +- Librarian output: <...> +- Oracle output: <...> +- Known constraints: + +## Current Task + + +## Acceptance Criteria + +``` + +## Agent Invocation + +```bash +codeagent-wrapper --agent - <<'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 diff --git a/skills/sparv/README.md b/skills/sparv/README.md index c5d65b5..cba85bb 100644 --- a/skills/sparv/README.md +++ b/skills/sparv/README.md @@ -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 +``` + +## 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: | ASSUMPTION: +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 --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// -├── 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 +```