fix(orch): update docs for globally installed CLI
orch is now installed via home-manager, no longer needs to be run from source directory with uv run.
This commit is contained in:
dan
parent
0349d48ef2
commit
45067b07c8
|
|
@ -26,7 +26,7 @@
|
|||
{"id":"skills-cnc","title":"Add direnv helper for per-repo skill deployment","description":"Create sourceable helper script and documentation for the standard per-repo skill deployment pattern using direnv + nix build.","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-11-30T12:19:20.71056749-08:00","updated_at":"2025-11-30T12:37:47.22638278-08:00","closed_at":"2025-11-30T12:37:47.22638278-08:00"}
|
||||
{"id":"skills-czz","title":"Research OpenCode agents for skill integration","description":"DEPLOYMENT.md:218 has TODO to research OpenCode agents. Need to understand how Build/Plan/custom agents work and whether skills need agent-specific handling.","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-30T11:58:24.855701141-08:00","updated_at":"2025-11-30T11:58:24.855701141-08:00"}
|
||||
{"id":"skills-d6r","title":"Design: orch as local agent framework","description":"# Orch Evolution: From Consensus Tool to Agent Framework\n\n## Current State\n- `orch consensus` - multi-model queries\n- `orch chat` - single model queries\n- No state, no pipelines, no retries\n\n## Proposed Extensions\n\n### Pipeline Mode\n```bash\norch pipeline config.yaml\n```\nWhere config.yaml defines:\n- Stages (triage → specialists → verify)\n- Routing logic (if triage finds X, run specialist Y)\n- Retry policy\n\n### Evaluate Mode (doc-review specific)\n```bash\norch evaluate doc.md --rubrics=1,4,7 --output=patches/\n```\n- Applies specific rubrics to document\n- Outputs JSON or patches\n\n### Parallel Mode\n```bash\norch parallel --fan-out=5 --template=\"evaluate {rubric}\" rubrics.txt\n```\n- Fan-out to multiple parallel calls\n- Aggregate results\n\n## Open Questions\n1. Does this belong in orch or a separate tool?\n2. Should orch pipelines be YAML-defined or code-defined?\n3. How does this relate to Claude Code Task subagents?\n4. What's the minimal viable extension?\n\n## Context\nEmerged from doc-review skill design - need multi-pass evaluation but don't want to adopt heavy framework (LangGraph, etc.)","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-04T16:06:56.681282678-08:00","updated_at":"2025-12-04T16:44:08.652185174-08:00","closed_at":"2025-12-04T16:44:08.652185174-08:00"}
|
||||
{"id":"skills-d87","title":"orch skill is documentation-only, needs working invocation mechanism","description":"The orch skill provides SKILL.md documentation but no working invocation mechanism.\n\n**Resolution**: Install orch globally via home-manager (dotfiles-3to). The skill documents a system tool, doesn't need to bundle it.\n\n**Blocked by**: dotfiles-3to (Add orch CLI to home-manager packages)","status":"open","priority":2,"issue_type":"bug","created_at":"2025-12-14T11:54:03.157039164-08:00","updated_at":"2025-12-14T12:05:26.427975702-08:00"}
|
||||
{"id":"skills-d87","title":"orch skill is documentation-only, needs working invocation mechanism","description":"The orch skill provides SKILL.md documentation but no working invocation mechanism.\n\n**Resolution**: Install orch globally via home-manager (dotfiles-3to). The skill documents a system tool, doesn't need to bundle it.\n\n**Blocked by**: dotfiles-3to (Add orch CLI to home-manager packages)","status":"in_progress","priority":2,"issue_type":"bug","created_at":"2025-12-14T11:54:03.157039164-08:00","updated_at":"2025-12-16T18:42:35.142600518-08:00"}
|
||||
{"id":"skills-dpw","title":"orch: add command to show available/configured models","description":"## Problem\n\nWhen trying to use orch, you have to trial-and-error through models to find which ones have API keys configured. Each failure looks like:\n\n```\nError: GEMINI_API_KEY not set. Required for Google Gemini models.\n```\n\nNo way to know upfront which models are usable.\n\n## Proposed Solution\n\nAdd `orch models` or `orch status` command:\n\n```bash\n$ orch models\nAvailable models:\n ✓ flash (GEMINI_API_KEY set)\n ✓ gemini (GEMINI_API_KEY set)\n ✗ deepseek (OPENROUTER_KEY not set)\n ✗ qwen (OPENROUTER_KEY not set)\n ✓ gpt (OPENAI_API_KEY set)\n```\n\nOr at minimum, on failure suggest alternatives:\n```\nError: GEMINI_API_KEY not set. Try --model gpt or --model deepseek instead.\n```\n\n## Context\n\nHit this while trying to brainstorm with high-temp gemini - had to try 4 models before realizing none were configured in this environment.","status":"closed","priority":3,"issue_type":"feature","created_at":"2025-12-04T14:10:07.069103175-08:00","updated_at":"2025-12-04T14:11:05.49122538-08:00","closed_at":"2025-12-04T14:11:05.49122538-08:00"}
|
||||
{"id":"skills-ebh","title":"Compare bd-issue-tracking skill files with upstream","description":"Fetch upstream beads skill files and compare with our condensed versions to identify differences","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-03T20:14:07.886535859-08:00","updated_at":"2025-12-03T20:19:37.579815337-08:00","closed_at":"2025-12-03T20:19:37.579815337-08:00"}
|
||||
{"id":"skills-fo3","title":"Compare WORKFLOWS.md with upstream","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-03T20:15:54.283175561-08:00","updated_at":"2025-12-03T20:19:28.897037199-08:00","closed_at":"2025-12-03T20:19:28.897037199-08:00","dependencies":[{"issue_id":"skills-fo3","depends_on_id":"skills-ebh","type":"discovered-from","created_at":"2025-12-03T20:15:54.286009672-08:00","created_by":"daemon"}]}
|
||||
|
|
@ -40,6 +40,7 @@
|
|||
{"id":"skills-mx3","title":"spec-review: Define consensus thresholds and decision rules","description":"'Use judgment' for mixed results leads to inconsistent decisions.\n\nDefine:\n- What constitutes consensus (2/3? unanimous?)\n- How to handle NEUTRAL votes\n- Tie-break rules\n- When human override is acceptable and how to document it","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-15T00:23:24.121175736-08:00","updated_at":"2025-12-15T13:58:04.339283238-08:00","closed_at":"2025-12-15T13:58:04.339283238-08:00"}
|
||||
{"id":"skills-pu4","title":"Clean up stale beads.left.jsonl merge artifact","description":"bd doctor flagged multiple JSONL files. beads.left.jsonl is empty merge artifact that should be removed: git rm .beads/beads.left.jsonl","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-30T11:58:33.292221449-08:00","updated_at":"2025-11-30T12:37:49.916795223-08:00","closed_at":"2025-11-30T12:37:49.916795223-08:00"}
|
||||
{"id":"skills-qeh","title":"Add README.md for web-research skill","description":"web-research skill has SKILL.md and scripts but no README.md. AGENTS.md says README.md is for humans, contains installation instructions, usage examples, prerequisites.","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-30T11:58:14.475647113-08:00","updated_at":"2025-11-30T12:00:30.309340468-08:00","dependencies":[{"issue_id":"skills-qeh","depends_on_id":"skills-vb5","type":"blocks","created_at":"2025-11-30T12:01:30.278784381-08:00","created_by":"daemon"}]}
|
||||
{"id":"skills-rpf","title":"Implement playwright-visit skill for browser automation","description":"## Overview\nBrowser automation skill using Playwright to visit web pages, take screenshots, and extract content.\n\n## Key Findings (from dotfiles investigation)\n\n### Working Setup\n- Use `python312Packages.playwright` from nixpkgs (handles Node driver binary patching for NixOS)\n- Use `executable_path='/run/current-system/sw/bin/chromium'` to use system chromium\n- No `playwright install` needed - no browser binary downloads\n\n### Profile Behavior\n- Fresh/blank profile every launch by default\n- No cookies, history, or logins from user's browser\n- Can persist state with `storage_state` parameter if needed\n\n### Example Code\n```python\nfrom playwright.sync_api import sync_playwright\n\nwith sync_playwright() as p:\n browser = p.chromium.launch(\n executable_path='/run/current-system/sw/bin/chromium',\n headless=True\n )\n page = browser.new_page()\n page.goto('https://example.com')\n print(page.title())\n browser.close()\n```\n\n### Why Not uv/pip?\n- Playwright pip package bundles a Node.js driver binary\n- NixOS can't run dynamically linked executables without patching\n- nixpkgs playwright handles this properly\n\n## Implementation Plan\n1. Create `skills/playwright-visit/` directory\n2. Add flake.nix with devShell providing playwright\n3. Create CLI script with subcommands:\n - `screenshot \u003curl\u003e \u003coutput.png\u003e` - capture page\n - `text \u003curl\u003e` - extract text content \n - `html \u003curl\u003e` - get rendered HTML\n - `pdf \u003curl\u003e \u003coutput.pdf\u003e` - save as PDF\n4. Create skill definition for Claude Code integration\n5. Document usage in skill README\n\n## Dependencies\n- nixpkgs python312Packages.playwright\n- System chromium (already in dotfiles)\n\n## Related\n- dotfiles issue dotfiles-m09 (playwright skill request)","status":"open","priority":2,"issue_type":"feature","created_at":"2025-12-16T16:02:28.577381007-08:00","updated_at":"2025-12-16T16:02:28.577381007-08:00"}
|
||||
{"id":"skills-uz4","title":"Compare RESUMABILITY.md with upstream","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-03T20:15:54.897754095-08:00","updated_at":"2025-12-03T20:19:29.384645842-08:00","closed_at":"2025-12-03T20:19:29.384645842-08:00","dependencies":[{"issue_id":"skills-uz4","depends_on_id":"skills-ebh","type":"discovered-from","created_at":"2025-12-03T20:15:54.899671178-08:00","created_by":"daemon"}]}
|
||||
{"id":"skills-vb5","title":"Resolve web search design questions","description":"web_search_brainstorm.md has unanswered design questions: single smart skill vs explicit flags, specific sources priority, raw links vs summaries. Need user input to finalize web-search/web-research direction.","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-30T11:58:33.482270742-08:00","updated_at":"2025-11-30T11:58:33.482270742-08:00"}
|
||||
{"id":"skills-x2l","title":"Investigate hooks for parallel orch queries","description":"When using orch skill, it would be useful to spin off multiple model queries in parallel automatically (e.g., gemini + gpt simultaneously). Explore if Claude Code hooks can trigger parallel background processes when the orch skill is invoked.","status":"open","priority":2,"issue_type":"feature","created_at":"2025-12-06T19:29:00.165752425-08:00","updated_at":"2025-12-06T19:29:00.165752425-08:00"}
|
||||
|
|
|
|||
|
|
@ -15,13 +15,13 @@ Enables agents to query multiple AI models simultaneously and aggregate their pe
|
|||
|
||||
```bash
|
||||
# Get consensus on a decision
|
||||
cd ~/proj/orch && uv run orch consensus "Should we use SQLite or PostgreSQL for this use case?" flash gemini claude
|
||||
orch consensus "Should we use SQLite or PostgreSQL for this use case?" flash gemini claude
|
||||
|
||||
# Devil's advocate
|
||||
cd ~/proj/orch && uv run orch consensus "Should we adopt microservices?" gpt5:for claude:against flash:neutral
|
||||
orch consensus "Should we adopt microservices?" gpt5:for claude:against flash:neutral
|
||||
|
||||
# Code review with file context
|
||||
cd ~/proj/orch && uv run orch consensus "Is this approach correct?" flash gemini --file src/handler.py --mode critique
|
||||
orch consensus "Is this approach correct?" flash gemini --file src/handler.py --mode critique
|
||||
```
|
||||
|
||||
## Files
|
||||
|
|
@ -31,8 +31,8 @@ cd ~/proj/orch && uv run orch consensus "Is this approach correct?" flash gemini
|
|||
|
||||
## Prerequisites
|
||||
|
||||
- `orch` CLI from ~/proj/orch
|
||||
- API keys for llm library providers
|
||||
- `orch` CLI installed (via home-manager or system packages)
|
||||
- API keys for model providers (OPENROUTER_KEY, GOOGLE_API_KEY, OPENAI_API_KEY)
|
||||
|
||||
## Installation
|
||||
|
||||
|
|
|
|||
|
|
@ -22,14 +22,12 @@ Invoke this skill when:
|
|||
|
||||
## Invocation
|
||||
|
||||
The `orch` CLI must be run from its project directory:
|
||||
The `orch` CLI is available globally:
|
||||
|
||||
```bash
|
||||
cd ~/proj/orch && uv run orch <command> [args...]
|
||||
orch <command> [args...]
|
||||
```
|
||||
|
||||
All examples below use this pattern.
|
||||
|
||||
## Commands
|
||||
|
||||
### orch consensus
|
||||
|
|
@ -37,7 +35,7 @@ All examples below use this pattern.
|
|||
Query multiple models for their verdict on a question.
|
||||
|
||||
```bash
|
||||
cd ~/proj/orch && uv run orch consensus "PROMPT" MODEL1 MODEL2 [MODEL3...]
|
||||
orch consensus "PROMPT" MODEL1 MODEL2 [MODEL3...]
|
||||
```
|
||||
|
||||
**Model Aliases** (use these):
|
||||
|
|
@ -73,14 +71,14 @@ cd ~/proj/orch && uv run orch consensus "PROMPT" MODEL1 MODEL2 [MODEL3...]
|
|||
**Stances** (devil's advocate):
|
||||
Append `:for`, `:against`, or `:neutral` to bias a model's perspective:
|
||||
```bash
|
||||
cd ~/proj/orch && uv run orch consensus "Should we rewrite in Rust?" gpt5:for deepseek:against gemini:neutral
|
||||
orch consensus "Should we rewrite in Rust?" gpt5:for deepseek:against gemini:neutral
|
||||
```
|
||||
|
||||
### orch chat
|
||||
|
||||
Single-model conversation (when you don't need consensus):
|
||||
```bash
|
||||
cd ~/proj/orch && uv run orch chat "MESSAGE" --model gemini
|
||||
orch chat "MESSAGE" --model gemini
|
||||
```
|
||||
|
||||
## Usage Patterns
|
||||
|
|
@ -88,37 +86,37 @@ cd ~/proj/orch && uv run orch chat "MESSAGE" --model gemini
|
|||
### Quick Second Opinion
|
||||
When you've reasoned through something and want validation:
|
||||
```bash
|
||||
cd ~/proj/orch && uv run orch consensus "I think we should use SQLite for this because [reasons]. Is this sound?" flash gemini
|
||||
orch consensus "I think we should use SQLite for this because [reasons]. Is this sound?" flash gemini
|
||||
```
|
||||
|
||||
### Architecture Decision
|
||||
When facing a tradeoff:
|
||||
```bash
|
||||
cd ~/proj/orch && uv run orch consensus "Microservices vs monolith for a 3-person team building an e-commerce site?" flash gemini deepseek --mode vote
|
||||
orch consensus "Microservices vs monolith for a 3-person team building an e-commerce site?" flash gemini deepseek --mode vote
|
||||
```
|
||||
|
||||
### Code Review
|
||||
Include the code as context:
|
||||
```bash
|
||||
cd ~/proj/orch && uv run orch consensus "Is this error handling approach correct and complete?" flash gemini --file src/handler.py
|
||||
orch consensus "Is this error handling approach correct and complete?" flash gemini --file src/handler.py
|
||||
```
|
||||
|
||||
### Devil's Advocate
|
||||
Get opposing viewpoints deliberately:
|
||||
```bash
|
||||
cd ~/proj/orch && uv run orch consensus "Should we adopt Kubernetes?" gpt5:for deepseek:against flash:neutral
|
||||
orch consensus "Should we adopt Kubernetes?" gpt5:for deepseek:against flash:neutral
|
||||
```
|
||||
|
||||
### Brainstorm
|
||||
Generate diverse ideas:
|
||||
```bash
|
||||
cd ~/proj/orch && uv run orch consensus "How could we improve the CI/CD pipeline?" flash gemini deepseek --mode brainstorm
|
||||
orch consensus "How could we improve the CI/CD pipeline?" flash gemini deepseek --mode brainstorm
|
||||
```
|
||||
|
||||
### Critique Your Work
|
||||
Find weaknesses before presenting:
|
||||
```bash
|
||||
cd ~/proj/orch && uv run orch consensus "What are the flaws in this API design?" flash gemini --file api-spec.yaml --mode critique
|
||||
orch consensus "What are the flaws in this API design?" flash gemini --file api-spec.yaml --mode critique
|
||||
```
|
||||
|
||||
## Output Format
|
||||
|
|
@ -150,8 +148,8 @@ Reasoning: ...
|
|||
|
||||
## Requirements
|
||||
|
||||
- `orch` CLI source at ~/proj/orch
|
||||
- API keys configured for llm library (OPENROUTER_KEY, GOOGLE_API_KEY, OPENAI_API_KEY)
|
||||
- `orch` CLI installed (via home-manager or system packages)
|
||||
- API keys configured (OPENROUTER_KEY, GOOGLE_API_KEY, OPENAI_API_KEY)
|
||||
|
||||
## Examples
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue