dan/skills
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

fix(orch): update docs for globally installed CLI

Browse source 
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 2025-12-16 18:45:19 -08:00
parent 0349d48ef2
commit 45067b07c8
3 changed files with 20 additions and 21 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
.beads/issues.jsonl
View file

@ -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-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-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-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-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-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"}]} {"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-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-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-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-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-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"} {"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"}

10
skills/orch/README.md
View file

@ -15,13 +15,13 @@ Enables agents to query multiple AI models simultaneously and aggregate their pe
```bash ```bash
# Get consensus on a decision # 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 # 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 # 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 ## Files
@ -31,8 +31,8 @@ cd ~/proj/orch && uv run orch consensus "Is this approach correct?" flash gemini
## Prerequisites ## Prerequisites
- `orch` CLI from ~/proj/orch - `orch` CLI installed (via home-manager or system packages)
- API keys for llm library providers - API keys for model providers (OPENROUTER_KEY, GOOGLE_API_KEY, OPENAI_API_KEY)
## Installation ## Installation

28
skills/orch/SKILL.md
View file

@ -22,14 +22,12 @@ Invoke this skill when:
## Invocation ## Invocation
The `orch` CLI must be run from its project directory: The `orch` CLI is available globally:
```bash ```bash
cd ~/proj/orch && uv run orch <command> [args...] orch <command> [args...]
``` ```
All examples below use this pattern.
## Commands ## Commands
### orch consensus ### orch consensus
@ -37,7 +35,7 @@ All examples below use this pattern.
Query multiple models for their verdict on a question. Query multiple models for their verdict on a question.
```bash ```bash
cd ~/proj/orch && uv run orch consensus "PROMPT" MODEL1 MODEL2 [MODEL3...] orch consensus "PROMPT" MODEL1 MODEL2 [MODEL3...]
``` ```
**Model Aliases** (use these): **Model Aliases** (use these):
@ -73,14 +71,14 @@ cd ~/proj/orch && uv run orch consensus "PROMPT" MODEL1 MODEL2 [MODEL3...]
**Stances** (devil's advocate): **Stances** (devil's advocate):
Append `:for`, `:against`, or `:neutral` to bias a model's perspective: Append `:for`, `:against`, or `:neutral` to bias a model's perspective:
```bash ```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 ### orch chat
Single-model conversation (when you don't need consensus): Single-model conversation (when you don't need consensus):
```bash ```bash
cd ~/proj/orch && uv run orch chat "MESSAGE" --model gemini orch chat "MESSAGE" --model gemini
``` ```
## Usage Patterns ## Usage Patterns
@ -88,37 +86,37 @@ cd ~/proj/orch && uv run orch chat "MESSAGE" --model gemini
### Quick Second Opinion ### Quick Second Opinion
When you've reasoned through something and want validation: When you've reasoned through something and want validation:
```bash ```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 ### Architecture Decision
When facing a tradeoff: When facing a tradeoff:
```bash ```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 ### Code Review
Include the code as context: Include the code as context:
```bash ```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 ### Devil's Advocate
Get opposing viewpoints deliberately: Get opposing viewpoints deliberately:
```bash ```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 ### Brainstorm
Generate diverse ideas: Generate diverse ideas:
```bash ```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 ### Critique Your Work
Find weaknesses before presenting: Find weaknesses before presenting:
```bash ```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 ## Output Format
@ -150,8 +148,8 @@ Reasoning: ...
## Requirements ## Requirements
- `orch` CLI source at ~/proj/orch - `orch` CLI installed (via home-manager or system packages)
- API keys configured for llm library (OPENROUTER_KEY, GOOGLE_API_KEY, OPENAI_API_KEY) - API keys configured (OPENROUTER_KEY, GOOGLE_API_KEY, OPENAI_API_KEY)
## Examples ## Examples