@oxgeneral/orch 1.0.6 → 1.0.8

package/skills/library/unfreeze.md

@@ -0,0 +1,31 @@
+---
+name: unfreeze
+version: 0.1.0
+description: |
+  Clear the freeze boundary set by /freeze, allowing edits to all directories
+  again. Use when you want to widen edit scope without ending the session.
+  Use when asked to "unfreeze", "unlock edits", "remove freeze", or
+  "allow all edits".
+---
+
+# /unfreeze — Clear Freeze Boundary
+
+Remove the edit restriction set by `/freeze`, allowing edits to all directories.
+
+## Clear the boundary
+
+```bash
+STATE_DIR="${CLAUDE_PLUGIN_DATA:-$HOME/.orch}"
+if [ -f "$STATE_DIR/freeze-dir.txt" ]; then
+  PREV=$(cat "$STATE_DIR/freeze-dir.txt")
+  rm -f "$STATE_DIR/freeze-dir.txt"
+  echo "Freeze boundary cleared (was: $PREV). Edits are now allowed everywhere."
+else
+  echo "No freeze boundary was set."
+fi
+```
+
+Tell the user the result. Note that `/freeze` hooks are still registered for the
+session — they will just allow everything since no state file exists. To re-freeze,
+run `/freeze` again.
+

package/skills/library/upgrade.md

@@ -0,0 +1,220 @@
+---
+name: upgrade
+version: 1.1.0
+description: |
+  Upgrade orch skills to the latest version. Detects global vs vendored install,
+  runs the upgrade, and shows what's new. Use when asked to "upgrade orch",
+  "update orch", or "get latest version".
+---
+
+# /upgrade
+
+Upgrade orch skills to the latest version and show what's new.
+
+## Inline upgrade flow
+
+This section is referenced by all skill preambles when they detect `UPGRADE_AVAILABLE`.
+
+### Step 1: Ask the user (or auto-upgrade)
+
+First, check if auto-upgrade is enabled:
+```bash
+_AUTO=""
+[ "${GSTACK_AUTO_UPGRADE:-}" = "1" ] && _AUTO="true"
+[ -z "$_AUTO" ] && _AUTO=$(# orch config get auto_upgrade 2>/dev/null || true)
+echo "AUTO_UPGRADE=$_AUTO"
+```
+
+**If `AUTO_UPGRADE=true` or `AUTO_UPGRADE=1`:** Skip AskUserQuestion. Log "Auto-upgrading v{old} → v{new}..." and proceed directly to Step 2. If `./setup` fails during auto-upgrade, restore from backup (`.bak` directory) and warn the user: "Auto-upgrade failed — restored previous version. Run `/upgrade` manually to retry."
+
+**Otherwise**, use AskUserQuestion:
+- Question: "**v{new}** is available (you're on v{old}). Upgrade now?"
+- Options: ["Yes, upgrade now", "Always keep me up to date", "Not now", "Never ask again"]
+
+**If "Yes, upgrade now":** Proceed to Step 2.
+
+**If "Always keep me up to date":**
+```bash
+# orch config set auto_upgrade true
+```
+Tell user: "Auto-upgrade enabled. Future updates will install automatically." Then proceed to Step 2.
+
+**If "Not now":** Write snooze state with escalating backoff (first snooze = 24h, second = 48h, third+ = 1 week), then continue with the current skill. Do not mention the upgrade again.
+```bash
+_SNOOZE_FILE=~/.orch/update-snoozed
+_REMOTE_VER="{new}"
+_CUR_LEVEL=0
+if [ -f "$_SNOOZE_FILE" ]; then
+  _SNOOZED_VER=$(awk '{print $1}' "$_SNOOZE_FILE")
+  if [ "$_SNOOZED_VER" = "$_REMOTE_VER" ]; then
+    _CUR_LEVEL=$(awk '{print $2}' "$_SNOOZE_FILE")
+    case "$_CUR_LEVEL" in *[!0-9]*) _CUR_LEVEL=0 ;; esac
+  fi
+fi
+_NEW_LEVEL=$((_CUR_LEVEL + 1))
+[ "$_NEW_LEVEL" -gt 3 ] && _NEW_LEVEL=3
+echo "$_REMOTE_VER $_NEW_LEVEL $(date +%s)" > "$_SNOOZE_FILE"
+```
+Note: `{new}` is the remote version from the `UPGRADE_AVAILABLE` output — substitute it from the update check result.
+
+Tell user the snooze duration: "Next reminder in 24h" (or 48h or 1 week, depending on level). Tip: "Set `auto_upgrade: true` in `~/.orch/config.yaml` for automatic upgrades."
+
+**If "Never ask again":**
+```bash
+# orch config set update_check false
+```
+Tell user: "Update checks disabled. Run `# orch config set update_check true` to re-enable."
+Continue with the current skill.
+
+### Step 2: Detect install type
+
+```bash
+if [ -d "$HOME/.claude/skills/orch/.git" ]; then
+  INSTALL_TYPE="global-git"
+  INSTALL_DIR="$HOME/.claude/skills/orch"
+elif [ -d ".claude/skills/orch/.git" ]; then
+  INSTALL_TYPE="local-git"
+  INSTALL_DIR=".claude/skills/orch"
+elif [ -d ".claude/skills/orch" ]; then
+  INSTALL_TYPE="vendored"
+  INSTALL_DIR=".claude/skills/orch"
+elif [ -d "$HOME/.claude/skills/orch" ]; then
+  INSTALL_TYPE="vendored-global"
+  INSTALL_DIR="$HOME/.claude/skills/orch"
+else
+  echo "ERROR: orch skills not found"
+  exit 1
+fi
+echo "Install type: $INSTALL_TYPE at $INSTALL_DIR"
+```
+
+The install type and directory path printed above will be used in all subsequent steps.
+
+### Step 3: Save old version
+
+Use the install directory from Step 2's output below:
+
+```bash
+OLD_VERSION=$(cat "$INSTALL_DIR/VERSION" 2>/dev/null || echo "unknown")
+```
+
+### Step 4: Upgrade
+
+Use the install type and directory detected in Step 2:
+
+**For git installs** (global-git, local-git):
+```bash
+cd "$INSTALL_DIR"
+STASH_OUTPUT=$(git stash 2>&1)
+git fetch origin
+git reset --hard origin/main
+./setup
+```
+If `$STASH_OUTPUT` contains "Saved working directory", warn the user: "Note: local changes were stashed. Run `git stash pop` in the skill directory to restore them."
+
+**For vendored installs** (vendored, vendored-global):
+```bash
+PARENT=$(dirname "$INSTALL_DIR")
+TMP_DIR=$(mktemp -d)
+git clone --depth 1 <upstream-skill-repo-url> "$TMP_DIR/orch-skills"
+mv "$INSTALL_DIR" "$INSTALL_DIR.bak"
+mv "$TMP_DIR/orch-skills" "$INSTALL_DIR"
+cd "$INSTALL_DIR" && ./setup
+rm -rf "$INSTALL_DIR.bak" "$TMP_DIR"
+```
+
+### Step 4.5: Sync local vendored copy
+
+Use the install directory from Step 2. Check if there's also a local vendored copy that needs updating:
+
+```bash
+_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
+LOCAL_GSTACK=""
+if [ -n "$_ROOT" ] && [ -d "$_ROOT/.claude/skills/orch" ]; then
+  _RESOLVED_LOCAL=$(cd "$_ROOT/.claude/skills/orch" && pwd -P)
+  _RESOLVED_PRIMARY=$(cd "$INSTALL_DIR" && pwd -P)
+  if [ "$_RESOLVED_LOCAL" != "$_RESOLVED_PRIMARY" ]; then
+    LOCAL_GSTACK="$_ROOT/.claude/skills/orch"
+  fi
+fi
+echo "LOCAL_GSTACK=$LOCAL_GSTACK"
+```
+
+If `LOCAL_GSTACK` is non-empty, update it by copying from the freshly-upgraded primary install (same approach as README vendored install):
+```bash
+mv "$LOCAL_GSTACK" "$LOCAL_GSTACK.bak"
+cp -Rf "$INSTALL_DIR" "$LOCAL_GSTACK"
+rm -rf "$LOCAL_GSTACK/.git"
+cd "$LOCAL_GSTACK" && ./setup
+rm -rf "$LOCAL_GSTACK.bak"
+```
+Tell user: "Also updated vendored copy at `$LOCAL_GSTACK` — commit `.claude/skills/orch/` when you're ready."
+
+If `./setup` fails, restore from backup and warn the user:
+```bash
+rm -rf "$LOCAL_GSTACK"
+mv "$LOCAL_GSTACK.bak" "$LOCAL_GSTACK"
+```
+Tell user: "Sync failed — restored previous version at `$LOCAL_GSTACK`. Run `/upgrade` manually to retry."
+
+### Step 5: Write marker + clear cache
+
+```bash
+mkdir -p ~/.orch
+echo "$OLD_VERSION" > ~/.orch/just-upgraded-from
+rm -f ~/.orch/last-update-check
+rm -f ~/.orch/update-snoozed
+```
+
+### Step 6: Show What's New
+
+Read `$INSTALL_DIR/CHANGELOG.md`. Find all version entries between the old version and the new version. Summarize as 5-7 bullets grouped by theme. Don't overwhelm — focus on user-facing changes. Skip internal refactors unless they're significant.
+
+Format:
+```
+v{new} — upgraded from v{old}!
+
+What's new:
+- [bullet 1]
+- [bullet 2]
+- ...
+
+Happy shipping!
+```
+
+### Step 7: Continue
+
+After showing What's New, continue with whatever skill the user originally invoked. The upgrade is done — no further action needed.
+
+---
+
+## Standalone usage
+
+When invoked directly as `/upgrade` (not from a preamble):
+
+1. Force a fresh update check (bypass cache):
+```bash
+# Check for updates (adapt to your update mechanism)
+# Example: compare local VERSION with remote VERSION
+```
+Use the output to determine if an upgrade is available.
+
+2. If `UPGRADE_AVAILABLE <old> <new>`: follow Steps 2-6 above.
+
+3. If no output (primary is up to date): check for a stale local vendored copy.
+
+Run the Step 2 bash block above to detect the primary install type and directory (`INSTALL_TYPE` and `INSTALL_DIR`). Then run the Step 4.5 detection bash block above to check for a local vendored copy (`LOCAL_GSTACK`).
+
+**If `LOCAL_GSTACK` is empty** (no local vendored copy): tell the user "You're already on the latest version (v{version})."
+
+**If `LOCAL_GSTACK` is non-empty**, compare versions:
+```bash
+PRIMARY_VER=$(cat "$INSTALL_DIR/VERSION" 2>/dev/null || echo "unknown")
+LOCAL_VER=$(cat "$LOCAL_GSTACK/VERSION" 2>/dev/null || echo "unknown")
+echo "PRIMARY=$PRIMARY_VER LOCAL=$LOCAL_VER"
+```
+
+**If versions differ:** follow the Step 4.5 sync bash block above to update the local copy from the primary. Tell user: "Global v{PRIMARY_VER} is up to date. Updated local vendored copy from v{LOCAL_VER} → v{PRIMARY_VER}. Commit `.claude/skills/orch/` when you're ready."
+
+**If versions match:** tell the user "You're on the latest version (v{PRIMARY_VER}). Global and local vendored copy are both up to date."
+

package/skills/orch/SKILL.md

@@ -0,0 +1,416 @@
+---
+name: orch
+description: "AI agent orchestrator — manage teams of AI agents that work on your codebase in parallel. Use when the user wants to: run multiple agents, coordinate AI work, deploy agent teams, manage tasks/goals/agents, check orchestrator status, or mentions 'orch', 'orchestry', 'agents team', 'agent orchestration'."
+allowed-tools: Bash, Read, Glob, Grep, Write, Edit, Agent
+argument-hint: "[command or natural language request]"
+---
+
+# ORCH — AI Agent Orchestrator
+
+You are the user's assistant for **ORCH** (`@oxgeneral/orch`) — an AI agent runtime that coordinates teams of LLM agents working on a codebase in parallel.
+
+Your role: interpret user intent and execute the right `orch` CLI commands. The user may speak in natural language — translate their intent into concrete actions.
+
+## How to Work
+
+1. **Natural language → CLI commands**: User says "add a task to refactor auth" → you run `orch task add "Refactor auth module" -d "..." --scope "src/auth/**"`
+2. **Always use `--json` flag** when you need to parse output programmatically
+3. **Chain commands** when the user's request requires multiple steps
+4. **Explain what you're doing** briefly before running commands
+5. **Show results** in a readable format after commands complete
+
+## Quick Start Flow
+
+If the project is not initialized (no `.orchestry/` directory):
+```bash
+orch init --name "project-name"
+```
+
+If there are no agents:
+```bash
+orch agent shop  # or suggest pre-built org templates
+```
+
+## Complete CLI Reference
+
+### Project Setup
+
+```bash
+orch init [--name <name>]          # Initialize .orchestry/ in current directory
+orch doctor                        # Check adapters and dependencies
+orch update [--check]              # Check/install updates
+orch status                        # Show orchestrator overview
+```
+
+### Task Management
+
+```bash
+# Create tasks
+orch task add "<title>" [options]
+  -d, --description <desc>         # Task description
+  -p, --priority <1-4>             # Priority (1=highest, default: 3)
+  -l, --labels <a,b,c>             # Comma-separated labels
+  --depends-on <id1,id2>           # Dependency task IDs
+  --assignee <agent-id>            # Assign to specific agent
+  --scope <patterns>               # File scope globs (e.g. src/auth/**,src/session/**)
+  --review-criteria <criteria>     # Auto-review: test_pass,typecheck,lint
+  --workspace-mode <mode>          # shared|worktree|isolated
+  --goal-id <goalId>               # Link to a goal
+  --attach <paths>                 # Attach files (screenshots, docs)
+  --max-attempts <n>               # Max retry attempts
+  -e, --edit                       # Open $EDITOR for description
+
+# List and view
+orch task list [--status <status>] # List tasks (filter: todo,in_progress,review,done,failed,cancelled)
+orch task show <id>                # Show task details
+
+# Lifecycle
+orch task assign <task-id> <agent-id>  # Assign task to agent
+orch task cancel <id>              # Cancel task (stops agent if running)
+orch task approve <id>             # Approve task in review → done
+orch task reject <id> [-r <reason>] # Reject task → back to todo
+orch task retry <id>               # Retry failed task
+orch task edit <id>                # Edit in $EDITOR
+```
+
+**Task Status Flow:** `todo → in_progress → review → done` with `retrying` and `failed` branches.
+
+### Agent Management
+
+```bash
+# Create agents
+orch agent add "<name>" --adapter <type> [options]
+  --adapter <type>                 # REQUIRED: claude|opencode|codex|cursor|shell
+  --role <description>             # Agent role/expertise
+  --model <model>                  # Model name
+  --command <cmd>                  # Shell command (for shell adapter)
+  --max-turns <n>                  # Max turns per run
+  --timeout <ms>                   # Timeout in milliseconds
+  --approval-policy <policy>       # auto|suggest|manual
+  --workspace-mode <mode>          # shared|worktree|isolated
+  --skills <skills>                # Comma-separated skills
+  -e, --edit                       # Open $EDITOR for role
+
+# Agent shop — pre-built templates
+orch agent shop [--list]           # Browse/install templates
+
+# Manage
+orch agent list                    # List all agents
+orch agent status <id>             # Show agent details + stats
+orch agent edit <id>               # Edit agent
+orch agent remove <id>             # Remove agent
+orch agent disable <id>            # Disable agent
+orch agent enable <id>             # Enable agent
+orch agent autonomous <id> [--on|--off]  # Toggle autonomous mode
+```
+
+**Available Agent Templates:** backend-dev, frontend-dev, qa-engineer, code-reviewer, architect, devops-engineer, bug-hunter, tech-writer, marketer, content-creator, growth-hacker, security-auditor, performance-engineer, data-engineer, fullstack-dev
+
+### Execution
+
+```bash
+orch run <task-id>                 # Run single task
+orch run --all                     # Run all todo tasks
+orch run --watch                   # Continuous orchestration (tick loop)
+orch tui                           # Interactive TUI dashboard
+orch serve [options]               # Headless daemon mode
+  --once                           # Process and exit (CI/CD mode)
+  --tick-interval <ms>             # Override poll interval
+  --log-file <path>                # Tee logs to file
+  --log-format <json|text>         # Log format (default: json)
+  --verbose                        # Include agent:output events
+```
+
+### Goals (High-Level Objectives)
+
+```bash
+orch goal add "<title>" [options]
+  --description <desc>             # Goal description
+  --assignee <agentId>             # Assign to agent for decomposition
+
+orch goal list [--status <status>] # List goals
+orch goal show <id>                # Show goal + progress report
+orch goal status <id> <status>     # Change status: active|paused|achieved|abandoned
+orch goal update <id> [options]    # Update title/description/assignee
+orch goal delete <id>              # Delete goal
+```
+
+### Teams
+
+```bash
+orch team create "<name>" --lead <agent-id> [options]
+  --members <id1,id2>             # Initial members
+  -d, --description <desc>        # Team description
+  --no-auto-claim                 # Disable auto-claiming
+
+orch team list                    # List teams
+orch team show <id>               # Show team details
+orch team join <team-id> <agent-id>    # Add member
+orch team leave <team-id> <agent-id>   # Remove member
+orch team add-task <team-id> <task-id> # Add task to pool
+orch team set-lead <team-id> <agent-id> # Transfer lead
+orch team disband <id>            # Disband team
+```
+
+### Pre-Built Organizations
+
+```bash
+orch org list                     # List available templates
+orch org deploy <template> [--goal "<objective>"]
+```
+
+**Available Templates:**
+- `startup-mvp` — Ship MVP in 48h (CTO + 2 Backend + Frontend + QA + Reviewer)
+- `pr-review-corp` — Auto-review every PR (Security + Performance + Style + QA)
+- `migration-squad` — JS→TS migration (CTO + 3 Migrators + QA + Reviewer)
+- `security-dept` — Multi-layer audit (Lead + Scanner + Secrets + Hunter + Reviewer)
+- `test-factory` — Coverage 40%→80% (Lead + 2 Backend + 3 QA + Reviewer)
+- `bugfix-dept` — 100 issues→0 (Triager + 3 Fixers + QA + Reviewer)
+- `docs-team` — Docs from code (Lead + 2 Writers + Editor + Reviewer)
+- `content-agency` — Content factory (Strategist + 2 Writers + Editor + SEO)
+- `data-lab` — CSVs→executive report (Lead Analyst + Data Engineer)
+- `sales-machine` — Outbound pipeline (Director + 2 SDRs + Copywriter + Growth)
+
+### Inter-Agent Communication
+
+```bash
+# Messages
+orch msg send <to-agent-id> "<body>" [-s <subject>] [--from <id>] [--ttl <ms>]
+orch msg broadcast "<body>" [-s <subject>] [--team <team-id>]
+orch msg inbox <agent-id>          # Pending messages
+orch msg list [--agent <id>]       # All messages
+
+# Shared Context
+orch context set <key> <value> [--ttl <ms>]
+orch context get <key>
+orch context list
+orch context delete <key>
+```
+
+### Configuration
+
+```bash
+orch config get <key>              # Get config value (dot notation)
+orch config set <key> <value>      # Set config value
+orch config edit                   # Edit config.yml in $EDITOR
+
+# Global settings (~/.orchestry/global.yml)
+orch config global get <key>
+orch config global set <key> <value>
+orch config global show
+```
+
+### Logs
+
+```bash
+orch logs [run-id]                 # View run logs
+  --agent <agent-id>               # Filter by agent
+  --task <task-id>                 # Filter by task
+  --follow                         # Live stream
+  --since <duration>               # Time filter (5m, 1h, 1d)
+```
+
+## Common Workflows
+
+### "Set up a team to work on my project"
+1. `orch init` (if needed)
+2. `orch org deploy startup-mvp --goal "Build feature X"` OR manually create agents
+3. `orch tui` or `orch run --watch` to start
+
+### "Add a task and run it"
+1. `orch task add "Fix login bug" -d "The login form crashes on empty email" --scope "src/auth/**" -p 1`
+2. `orch run <task-id>`
+
+### "Check what's happening"
+1. `orch status` — overview
+2. `orch task list --status in_progress` — running tasks
+3. `orch logs --follow` — live output
+
+### "Deploy a review team for PRs"
+1. `orch org deploy pr-review-corp --goal "Review all open PRs"`
+2. Tasks are auto-created and assigned
+
+### "I want to refactor X across the codebase"
+1. Create a goal: `orch goal add "Refactor X" --description "..." --assignee <lead-agent>`
+2. Lead agent decomposes goal into tasks automatically
+3. `orch run --watch` to execute
+
+## Key Concepts
+
+- **Agents** run in isolated git worktrees (no merge conflicts)
+- **Tasks** flow through: todo → in_progress → review → done
+- **Goals** are decomposed into tasks by a lead agent
+- **Teams** coordinate agents with a lead + members
+- **Adapters**: claude, opencode, codex, cursor, shell
+- **All state** stored in `.orchestry/` (YAML/JSON, no database)
+- **IDs** are prefixed: `tsk_`, `agt_`, `run_`, `goal_`, `team_`, `msg_`
+
+## Configuration Reference
+
+```yaml
+# .orchestry/config.yml
+project:
+  name: "my-project"
+defaults:
+  agent:
+    adapter: "claude"           # Default adapter
+    approval_policy: "auto"     # auto|suggest|manual
+    max_turns: 50               # Max LLM turns per run
+    timeout_ms: 3600000         # 1 hour timeout
+    stall_timeout_ms: 600000    # 10 min stall detection
+    workspace_mode: "worktree"  # shared|worktree|isolated
+  task:
+    max_attempts: 3             # Max retries
+    priority: 3                 # Default priority (1-4)
+scheduling:
+  poll_interval_ms: 10000       # Tick interval (10s)
+  max_concurrent_agents: 6      # Parallel agent limit
+  retry_base_delay_ms: 10000    # Retry backoff base
+  retry_max_delay_ms: 300000    # Max retry delay (5min)
+```
+
+## Creating Agents — Sources and Best Practices
+
+### Quick: Use Pre-Built Templates
+
+```bash
+orch agent shop              # Interactive picker — 15 templates
+orch agent shop --list       # Print all templates non-interactively
+orch org deploy <template>   # Deploy a full team with one command
+```
+
+### Agent Shop Templates (src/domain/agent-shop.ts)
+
+Each template includes a detailed role prompt, model, skills, and approval policy:
+
+| Template | Role | Model | Skills |
+|----------|------|-------|--------|
+| `backend-dev` | APIs, services, DB layers | claude-sonnet-4-6 | feature-dev |
+| `frontend-dev` | React UI, components, CSS | claude-sonnet-4-6 | feature-dev, frontend-design |
+| `qa-engineer` | Tests, coverage analysis | claude-sonnet-4-6 | testing-suite |
+| `code-reviewer` | PR review, bugs, security | claude-opus-4-6 | feature-dev:code-reviewer |
+| `architect` | System design, architecture | claude-opus-4-6 | feature-dev:code-architect |
+| `devops-engineer` | CI/CD, infrastructure | claude-sonnet-4-6 | devops-automation |
+| `bug-hunter` | Find bugs, reproduce, fix | claude-sonnet-4-6 | feature-dev |
+| `tech-writer` | Docs, READMEs, API docs | claude-sonnet-4-6 | perfect-readme |
+| `security-auditor` | Security scanning, vulns | claude-opus-4-6 | testing-suite |
+| `performance-engineer` | Optimization, profiling | claude-sonnet-4-6 | testing-suite |
+| `data-engineer` | Data pipelines, ETL | claude-sonnet-4-6 | — |
+| `fullstack-dev` | End-to-end development | claude-sonnet-4-6 | feature-dev |
+| `marketer` | Marketing strategy, copy | claude-sonnet-4-6 | marketing-psychology |
+| `content-creator` | Blog posts, social media | claude-sonnet-4-6 | — |
+| `growth-hacker` | Growth experiments | claude-sonnet-4-6 | marketing-psychology |
+
+### Org Templates (src/domain/org-shop.ts)
+
+Pre-built teams — deploy with `orch org deploy <key> --goal "..."`:
+
+| Template | Agents | Use Case |
+|----------|--------|----------|
+| `startup-mvp` | CTO + 2 Backend + Frontend + QA + Reviewer | Ship MVP fast |
+| `pr-review-corp` | CTO + Security + Performance + Style + QA | Auto-review PRs |
+| `migration-squad` | CTO + 3 Migrators + QA + Reviewer | JS→TS migration |
+| `security-dept` | Lead + Scanner + Secrets + Hunter + Reviewer | Security audit |
+| `test-factory` | Lead + 2 Backend + 3 QA + Reviewer | Coverage boost |
+| `bugfix-dept` | Triager + 3 Fixers + QA + Reviewer | Issue backlog |
+| `docs-team` | Lead + 2 Writers + Editor + Reviewer | Documentation |
+| `content-agency` | Strategist + 2 Writers + Editor + SEO | Content |
+| `data-lab` | Lead Analyst + Data Engineer | Data analysis |
+| `sales-machine` | Director + 2 SDRs + Copywriter + Growth | Outbound |
+
+### Custom Agents: Role Prompt Structure
+
+When creating custom agents with `orch agent add`, follow this proven structure from the shop templates:
+
+```
+# [Role Name]
+
+[One-line description of what this agent does]
+
+## WORKFLOW
+1) READ — understand the task scope
+2) EXPLORE — analyze existing code/data with appropriate skills
+3) PLAN — outline approach before executing
+4) EXECUTE — do the work following conventions
+5) VERIFY — self-review, run tests
+6) REPORT — summarize what was done, flag risks
+
+## RULES
+- [Convention 1]
+- [Convention 2]
+- [Safety guardrail]
+```
+
+### Skills Available for Agents
+
+Assign skills via `--skills` flag or edit agent YAML. You can mix both types: `--skills "review,feature-dev:code-explorer,investigate"`.
+
+#### Library Skills (injected into system prompt — works with ALL adapters)
+
+Content from the skill library is loaded and appended to the agent's system prompt at execution time. Use plain names (no colons):
+
+| Skill | Best For |
+|-------|----------|
+| `review` | Pre-landing code review with auto-fix, checklists, adversarial review |
+| `qa` | Full QA testing + browser testing + bug fixing + health scoring |
+| `qa-only` | QA testing without auto-fixes (report only) |
+| `ship` | Automated ship workflow: merge, test, coverage audit, PR creation |
+| `office-hours` | YC-style product thinking, design docs, premise challenge |
+| `investigate` | Systematic debugging with root cause methodology, 3-strike hypothesis |
+| `careful` | Safety guardrails for destructive commands |
+| `guard` | Full safety mode (careful + freeze combined) |
+| `freeze` | Restrict edits to a specific directory |
+| `unfreeze` | Clear freeze boundary |
+| `design-consultation` | Design system creation, visual language definition |
+| `design-review` | Design review with accessibility, responsiveness checks |
+| `plan-ceo-review` | CEO-level strategic review of plans |
+| `plan-eng-review` | Engineering review of technical plans |
+| `plan-design-review` | Design review of plans |
+| `autoplan` | Auto-review pipeline with decision principles |
+| `land-and-deploy` | Merge PR, wait for CI, verify production health |
+| `canary` | Post-deploy canary monitoring |
+| `document-release` | Auto-update documentation after ship |
+| `retro` | Weekly engineering retrospective with trends |
+| `browse` | Headless browser navigation and testing |
+| `benchmark` | Performance benchmarking with before/after metrics |
+| `codex` | OpenAI Codex cross-review / multi-AI challenge |
+| `setup-deploy` | Configure deployment settings |
+| `setup-browser-cookies` | Import browser cookies for authenticated QA |
+| `upgrade` | Upgrade skills to latest version |
+
+#### Claude Code MCP Skills (native — Claude adapter only)
+
+Handled natively by Claude CLI. Use `package:skill-name` format (with colon):
+
+| Skill | Best For |
+|-------|----------|
+| `feature-dev:feature-dev` | Guided feature development with architecture focus |
+| `feature-dev:code-explorer` | Deep codebase analysis and tracing |
+| `feature-dev:code-architect` | Architecture design and blueprints |
+| `feature-dev:code-reviewer` | Code review with confidence filtering |
+| `testing-suite:generate-tests` | Test generation with edge cases |
+| `testing-suite:test-coverage` | Coverage analysis and gap identification |
+| `testing-suite:e2e-setup` | End-to-end testing configuration |
+| `testing-suite:test-quality-analyzer` | Test suite quality metrics |
+| `devops-automation:cloud-architect` | Cloud infrastructure, Terraform |
+| `frontend-design:frontend-design` | UI/UX design and implementation |
+| `document-skills:frontend-design` | Frontend design (document-skills variant) |
+| `product-manager-toolkit` | RICE prioritization, PRD templates |
+| `marketing-psychology` | Behavioral science for marketing |
+
+### Tips
+
+- Use `claude-opus-4-6` for strategic/review roles (architect, reviewer, lead) — higher quality reasoning
+- Use `claude-sonnet-4-6` for execution roles (developer, QA, writer) — faster, cheaper
+- Set `--approval-policy suggest` for strategic agents so humans review decisions
+- Set `--approval-policy auto` for execution agents for fully autonomous operation
+- Use `--workspace-mode shared` for analysis/strategy agents (they read, don't write code)
+- Use `--workspace-mode worktree` for coding agents (isolated branches, no conflicts)
+
+## Important Notes
+
+- Always run `orch doctor` first if something seems wrong
+- Use `--json` flag for programmatic parsing
+- `orch serve --once` is ideal for CI/CD pipelines
+- Stall timeout default is 10 minutes — increase for complex tasks via `orch config set defaults.agent.stall_timeout_ms 1200000`
+- If tasks are stuck after a crash, the orchestrator auto-cleans stale state on restart (v1.0.6+)