From 80448bd6120db6e95aa776b605715c8b4d7a098d Mon Sep 17 00:00:00 2001 From: dan Date: Sun, 25 Jan 2026 12:44:40 -0800 Subject: [PATCH] docs(orch): sync SKILL.md with CLI implementation - Remove undocumented features: --serial, --strategy, --synthesize, --allow-expensive - Add actual CLI options: --enhance, --enhance-model, --image, --resume - Fix default model for chat (flash, not gemini) - Update work doc with completed W002 --- docs/work/2026-01-25-quick-wins-batch.md | 5 ++-- skills/orch/SKILL.md | 32 ++++++++++-------------- 2 files changed, 15 insertions(+), 22 deletions(-) diff --git a/docs/work/2026-01-25-quick-wins-batch.md b/docs/work/2026-01-25-quick-wins-batch.md index e2bdd41..268515f 100644 --- a/docs/work/2026-01-25-quick-wins-batch.md +++ b/docs/work/2026-01-25-quick-wins-batch.md @@ -15,9 +15,8 @@ Execute each as an atomic unit. Most are small fixes or deployments. ### Documentation -- [ ] **W002**: Sync orch skill documentation with CLI implementation (skills-q75m) +- [x] **W002**: Sync orch skill documentation with CLI implementation (skills-q75m) - Verification: `diff skills/orch/SKILL.md` matches current `orch --help` output - - **BLOCKED**: Skill docs describe features not in CLI (--serial, --strategy, --synthesize, --allow-expensive). Need to decide: remove from docs or implement in CLI? ### Skill Deployment @@ -30,7 +29,7 @@ Execute each as an atomic unit. Most are small fixes or deployments. ## Verification Evidence - (2026-01-25) W001: Added issues.jsonl to .beads/.gitignore, ran `git rm --cached`, file still exists locally -- (2026-01-25) W002: BLOCKED - skill docs describe features not in CLI (--serial, --strategy, --synthesize, --allow-expensive) +- (2026-01-25) W002: Stripped undocumented features from SKILL.md (--serial, --strategy, --synthesize, --allow-expensive), added --enhance, --image, --resume - (2026-01-25) W003: Added brave-search to claudeCodeSkills, openCodeSkills, codexSkills in dotfiles/home/claude.nix - (2026-01-25) W004: Added browser-tools to all three skill lists in dotfiles/home/claude.nix diff --git a/skills/orch/SKILL.md b/skills/orch/SKILL.md index c659817..2ea59b8 100644 --- a/skills/orch/SKILL.md +++ b/skills/orch/SKILL.md @@ -65,7 +65,7 @@ Use `orch models` to see all available models with pricing and status. **Standard consensus**: Use `flash gemini deepseek` for balanced perspectives across providers. Default for most decisions. -**Deep analysis**: Include `r1` or `gpt` when stakes are high or reasoning is complex. These models think longer but cost more. Use `--allow-expensive` for r1/opus. +**Deep analysis**: Include `r1` or `gpt` when stakes are high or reasoning is complex. These models think longer but cost more. **Diverse viewpoints**: Mix providers (Google + DeepSeek + OpenAI + Anthropic) rather than multiple models from one provider. Different training leads to genuinely different perspectives. @@ -78,12 +78,10 @@ Use `orch models` to see all available models with pricing and status. - `--mode open` - Freeform responses, no structured output - `--temperature 0.1` - Lower = more focused (default 0.1) - `--file PATH` - Include file as context (can use multiple times) -- `--websearch` - Enable web search (Gemini models only) -- `--serial` - Run models in sequence instead of parallel -- `--strategy` - Serial strategy: neutral (default), refine, debate, brainstorm -- `--synthesize MODEL` - Aggregate all responses into summary using MODEL -- `--allow-expensive` - Allow expensive/slow models (opus, r1) +- `--websearch` / `--no-websearch` - Toggle web search grounding - `--timeout SECS` - Timeout per model (default 300) +- `--enhance` - Use a planner model to enhance the prompt first +- `--enhance-model MODEL` - Model for prompt enhancement (default: flash) **Stances** (devil's advocate): Append `:for`, `:against`, or `:neutral` to bias a model's perspective: @@ -104,12 +102,14 @@ orch chat "MESSAGE" --model gemini ``` Options: -- `--model MODEL` - Model to use (default: gemini) +- `--model MODEL` - Model to use (default: flash) - `--session ID` - Continue an existing session -- `--format json` - Return structured output with session_id -- `--file PATH` - Attach file -- `--websearch` / `--no-websearch` - Toggle search (default: on) -- `--allow-expensive` - Allow expensive models +- `--resume TOKEN` - Resume a session using its resume token +- `--format text|json` - Output format (default: text) +- `--file PATH` - Attach file(s) as context +- `--image PATH` - Attach image file(s) for vision models +- `--websearch` / `--no-websearch` - Toggle web search grounding +- `--temperature FLOAT` - Temperature (default: 0.75 for creative mode) Use chat instead of consensus when: - You need iterative refinement through follow-up questions @@ -172,16 +172,10 @@ Find weaknesses before presenting: orch consensus "What are the flaws in this API design?" flash gemini --file api-spec.yaml --mode critique ``` -### Synthesize Responses -Get a unified summary from multiple perspectives: -```bash -orch consensus "Evaluate this architecture" flash gemini gpt --synthesize gemini -``` - ### Use Reasoning Models For complex analysis requiring deep thinking: ```bash -orch consensus "Analyze the security implications" r1 gemini --allow-expensive +orch consensus "Analyze the security implications" r1 gemini ``` ## Conversational Patterns @@ -306,7 +300,7 @@ Reasoning: ... 3. **Choose models wisely** - flash/qwen-fast for quick checks, r1/opus for complex reasoning 4. **Consider stances** - Devil's advocate is powerful for stress-testing ideas 5. **Parse the reasoning** - The verdict matters less than understanding the reasoning -6. **Mind the cost** - opus and r1 require `--allow-expensive`; use cheaper models for iteration +6. **Mind the cost** - opus and r1 are expensive; use cheaper models for iteration ## Requirements