@caseyharalson/orrery 0.7.1

package/.devcontainer.example/Dockerfile

@@ -0,0 +1,149 @@
+FROM mcr.microsoft.com/devcontainers/base:ubuntu-22.04
+
+# ---- Base config ----
+ARG TZ=America/Chicago
+ENV TZ="${TZ}"
+ENV DEVCONTAINER=true
+
+ARG USERNAME=vscode
+ENV HOME=/home/${USERNAME}
+
+# Use bash with pipefail for build RUN steps by default (safer than /bin/sh)
+SHELL ["/bin/bash", "-o", "pipefail", "-c"]
+
+# ---- OS packages ----
+RUN apt-get update \
+  && export DEBIAN_FRONTEND=noninteractive \
+  && apt-get -y install --no-install-recommends \
+    ca-certificates \
+    curl \
+    dnsutils \
+    fzf \
+    gh \
+    git \
+    gnupg2 \
+    iproute2 \
+    ipset \
+    iptables \
+    jq \
+    less \
+    man-db \
+    nano \
+    procps \
+    sudo \
+    unzip \
+    vim \
+    wget \
+    zsh \
+    aggregate \
+  && apt-get autoremove -y \
+  && apt-get clean -y \
+  && rm -rf /var/lib/apt/lists/*
+
+# ---- Workspace + config dirs + persistent history ----
+RUN mkdir -p /workspace \
+    /commandhistory \
+    "${HOME}/.claude" \
+    "${HOME}/.codex" \
+    "${HOME}/.gemini" \
+  && touch /commandhistory/.bash_history \
+  && chown -R "${USERNAME}:${USERNAME}" \
+    /workspace \
+    /commandhistory \
+    "${HOME}/.claude" \
+    "${HOME}/.codex" \
+    "${HOME}/.gemini"
+
+# Persist bash history (devcontainer orientation)
+RUN echo "export PROMPT_COMMAND='history -a' && export HISTFILE=/commandhistory/.bash_history" \
+    > /etc/profile.d/00-devcontainer-history.sh \
+  && chmod 0644 /etc/profile.d/00-devcontainer-history.sh
+
+# ---- git-delta ----
+ARG GIT_DELTA_VERSION=0.18.2
+RUN ARCH="$(dpkg --print-architecture)" \
+  && wget -q "https://github.com/dandavison/delta/releases/download/${GIT_DELTA_VERSION}/git-delta_${GIT_DELTA_VERSION}_${ARCH}.deb" \
+  && dpkg -i "git-delta_${GIT_DELTA_VERSION}_${ARCH}.deb" \
+  && rm -f "git-delta_${GIT_DELTA_VERSION}_${ARCH}.deb"
+
+# ---- Switch to vscode user for user-scoped tool installs ----
+USER ${USERNAME}
+
+# Use bash -lc for nvm-driven commands (nvm.sh expects bash-ish behavior)
+SHELL ["/bin/bash", "-lc"]
+
+# ---- nvm + Node LTS ----
+ARG NVM_VERSION=v0.39.7
+RUN curl -fsSL "https://raw.githubusercontent.com/nvm-sh/nvm/${NVM_VERSION}/install.sh" | bash \
+  && export NVM_DIR="$HOME/.nvm" \
+  && source "$NVM_DIR/nvm.sh" \
+  && nvm install --lts \
+  && nvm alias default lts/* \
+  && nvm use default \
+  && npm --version \
+  && node --version
+
+# Make nvm available in interactive shells (bash + zsh)
+RUN echo 'export NVM_DIR="$HOME/.nvm"' >> "${HOME}/.bashrc" \
+  && echo '[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"' >> "${HOME}/.bashrc" \
+  && echo '[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"' >> "${HOME}/.bashrc" \
+  && echo 'export NVM_DIR="$HOME/.nvm"' >> "${HOME}/.zshrc" \
+  && echo '[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"' >> "${HOME}/.zshrc" \
+  && echo '[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"' >> "${HOME}/.zshrc"
+
+# ---- uv ----
+RUN curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Ensure uv is on PATH for vscode user
+ENV PATH="${HOME}/.cargo/bin:${PATH}"
+
+# ---- zsh + powerlevel10k (zsh-in-docker) ----
+ARG ZSH_IN_DOCKER_VERSION=1.2.0
+RUN sh -c "$(wget -qO- "https://github.com/deluan/zsh-in-docker/releases/download/v${ZSH_IN_DOCKER_VERSION}/zsh-in-docker.sh")" -- \
+  -p git \
+  -a "export PROMPT_COMMAND='history -a' && export HISTFILE=/commandhistory/.bash_history" \
+  -a 'export NVM_DIR="$HOME/.nvm"' \
+  -a '[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"' \
+  -a '[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"' \
+  -a "setopt nonomatch" \
+  -x
+
+# ---- fzf shell integration (manual) ----
+RUN mkdir -p "${HOME}/.fzf" \
+  && wget -qO "${HOME}/.fzf/key-bindings.zsh" https://raw.githubusercontent.com/junegunn/fzf/master/shell/key-bindings.zsh \
+  && wget -qO "${HOME}/.fzf/completion.zsh" https://raw.githubusercontent.com/junegunn/fzf/master/shell/completion.zsh \
+  && echo '[ -f ~/.fzf/key-bindings.zsh ] && source ~/.fzf/key-bindings.zsh' >> "${HOME}/.zshrc" \
+  && echo '[ -f ~/.fzf/completion.zsh ] && source ~/.fzf/completion.zsh' >> "${HOME}/.zshrc"
+
+# ---- Install CLI tools via npm (Claude, Codex, Gemini, Orrery) ----
+ARG CLAUDE_CODE_VERSION=latest
+ARG CODEX_VERSION=latest
+ARG GEMINI_VERSION=latest
+ARG ORRERY_VERSION=latest
+
+RUN export NVM_DIR="$HOME/.nvm" \
+  && source "$NVM_DIR/nvm.sh" \
+  && nvm use default \
+  && npm install -g \
+      "@anthropic-ai/claude-code@${CLAUDE_CODE_VERSION}" \
+      "@openai/codex@${CODEX_VERSION}" \
+      "@google/gemini-cli@${GEMINI_VERSION}" \
+      "@caseyharalson/orrery@${ORRERY_VERSION}"
+
+# ---- Back to root for firewall script setup ----
+USER root
+SHELL ["/bin/bash", "-o", "pipefail", "-c"]
+
+COPY init-firewall.sh /usr/local/bin/init-firewall.sh
+RUN chmod +x /usr/local/bin/init-firewall.sh \
+  && echo "${USERNAME} ALL=(root) NOPASSWD: /usr/local/bin/init-firewall.sh" > /etc/sudoers.d/${USERNAME}-firewall \
+  && chmod 0440 /etc/sudoers.d/${USERNAME}-firewall
+
+# ---- Defaults ----
+WORKDIR /workspace
+USER ${USERNAME}
+
+# Keep zsh as the default interactive shell
+ENV SHELL=/bin/zsh
+ENV EDITOR=nano
+ENV VISUAL=nano

package/.devcontainer.example/devcontainer.json

@@ -0,0 +1,61 @@
+{
+  "name": "Orrery Dev Container",
+  "build": {
+    "dockerfile": "Dockerfile",
+    "args": {
+      "TZ": "${localEnv:TZ:America/Chicago}",
+      "CLAUDE_CODE_VERSION": "latest",
+      "CODEX_VERSION": "latest",
+      "GEMINI_VERSION": "latest",
+      "ORRERY_VERSION": "latest",
+      "GIT_DELTA_VERSION": "0.18.2",
+      "ZSH_IN_DOCKER_VERSION": "1.2.0"
+    }
+  },
+  "runArgs": ["--cap-add=NET_ADMIN", "--cap-add=NET_RAW"],
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "anthropic.claude-code",
+        "dbaeumer.vscode-eslint",
+        "esbenp.prettier-vscode",
+        "eamodio.gitlens",
+        "ms-azuretools.vscode-docker"
+      ],
+      "settings": {
+        "editor.formatOnSave": true,
+        "editor.defaultFormatter": "esbenp.prettier-vscode",
+        "editor.codeActionsOnSave": {
+          "source.fixAll.eslint": "explicit"
+        },
+        "terminal.integrated.defaultProfile.linux": "zsh",
+        "terminal.integrated.profiles.linux": {
+          "bash": {
+            "path": "bash",
+            "icon": "terminal-bash"
+          },
+          "zsh": {
+            "path": "zsh"
+          }
+        }
+      }
+    }
+  },
+  "remoteUser": "vscode",
+  "mounts": [
+    "source=orrery-bashhistory-${devcontainerId},target=/commandhistory,type=volume",
+    "source=shared-sandbox-claude-code-config,target=/home/vscode/.claude,type=volume",
+    "source=shared-sandbox-codex-config,target=/home/vscode/.codex,type=volume",
+    "source=shared-sandbox-gemini-config,target=/home/vscode/.gemini,type=volume"
+  ],
+  "containerEnv": {
+    "NODE_OPTIONS": "--max-old-space-size=4096",
+    "CLAUDE_CONFIG_DIR": "/home/vscode/.claude",
+    "CODEX_HOME": "/home/vscode/.codex",
+    "POWERLEVEL9K_DISABLE_GITSTATUS": "true",
+    "ORRERY_AGENT_PRIORITY": "codex,gemini,claude",
+    "ORRERY_REVIEW_ENABLED": "true"
+  },
+  "workspaceMount": "source=${localWorkspaceFolder},target=/workspace,type=bind,consistency=delegated",
+  "workspaceFolder": "/workspace"
+}

package/.devcontainer.example/init-firewall.sh

@@ -0,0 +1,175 @@
+#!/bin/bash
+set -euo pipefail  # Exit on error, undefined vars, and pipeline failures
+IFS=$'\n\t'       # Stricter word splitting
+
+# 1. Extract Docker DNS info BEFORE any flushing
+DOCKER_DNS_RULES=$(iptables-save -t nat | grep "127\.0\.0\.11" || true)
+
+# Flush existing rules and delete existing ipsets
+iptables -F
+iptables -X
+iptables -t nat -F
+iptables -t nat -X
+iptables -t mangle -F
+iptables -t mangle -X
+ipset destroy allowed-domains 2>/dev/null || true
+
+# 2. Selectively restore ONLY internal Docker DNS resolution
+if [ -n "$DOCKER_DNS_RULES" ]; then
+    echo "Restoring Docker DNS rules..."
+    iptables -t nat -N DOCKER_OUTPUT 2>/dev/null || true
+    iptables -t nat -N DOCKER_POSTROUTING 2>/dev/null || true
+    echo "$DOCKER_DNS_RULES" | xargs -L 1 iptables -t nat
+else
+    echo "No Docker DNS rules to restore"
+fi
+
+# First allow DNS and localhost before any restrictions
+# Allow outbound DNS
+iptables -A OUTPUT -p udp --dport 53 -j ACCEPT
+# Allow inbound DNS responses
+iptables -A INPUT -p udp --sport 53 -j ACCEPT
+# Allow outbound SSH
+iptables -A OUTPUT -p tcp --dport 22 -j ACCEPT
+# Allow inbound SSH responses
+iptables -A INPUT -p tcp --sport 22 -m state --state ESTABLISHED -j ACCEPT
+# Allow localhost
+iptables -A INPUT -i lo -j ACCEPT
+iptables -A OUTPUT -o lo -j ACCEPT
+
+# Create ipset with CIDR support
+ipset create allowed-domains hash:net
+
+# Fetch GitHub meta information and aggregate + add their IP ranges
+echo "Fetching GitHub IP ranges..."
+gh_ranges=$(curl -s https://api.github.com/meta)
+if [ -z "$gh_ranges" ]; then
+    echo "ERROR: Failed to fetch GitHub IP ranges"
+    exit 1
+fi
+
+if ! echo "$gh_ranges" | jq -e '.web and .api and .git' >/dev/null; then
+    echo "ERROR: GitHub API response missing required fields"
+    exit 1
+fi
+
+echo "Processing GitHub IPs..."
+while read -r cidr; do
+    if [[ ! "$cidr" =~ ^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}/[0-9]{1,2}$ ]]; then
+        echo "ERROR: Invalid CIDR range from GitHub meta: $cidr"
+        exit 1
+    fi
+    echo "Adding GitHub range $cidr"
+    ipset add allowed-domains "$cidr"
+done < <(echo "$gh_ranges" | jq -r '(.web + .api + .git)[]' | aggregate -q)
+
+# Resolve and add other allowed domains
+for domain in \
+    "registry.npmjs.org" \
+    "sentry.io" \
+    "statsig.com" \
+    "api.anthropic.com" \
+    "statsig.anthropic.com" \
+    "code.claude.com" \
+    "api.openai.com" \
+    "auth.openai.com" \
+    "platform.openai.com" \
+    "chatgpt.com" \
+    "www.googleapis.com" \
+    "oauth2.googleapis.com" \
+    "marketplace.visualstudio.com" \
+    "vscode.blob.core.windows.net" \
+    "update.code.visualstudio.com"; do
+    echo "Resolving $domain..."
+    ips=$(dig +noall +answer A "$domain" | awk '$4 == "A" {print $5}')
+    if [ -z "$ips" ]; then
+        echo "ERROR: Failed to resolve $domain"
+        exit 1
+    fi
+    
+    while read -r ip; do
+        if [[ ! "$ip" =~ ^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}$ ]]; then
+            echo "ERROR: Invalid IP from DNS for $domain: $ip"
+            exit 1
+        fi
+        echo "Adding $ip for $domain"
+        ipset add allowed-domains "$ip"
+    done < <(echo "$ips")
+done
+
+# Get host IP from default route
+HOST_IP=$(ip route | grep default | cut -d" " -f3)
+if [ -z "$HOST_IP" ]; then
+    echo "ERROR: Failed to detect host IP"
+    exit 1
+fi
+
+HOST_NETWORK=$(echo "$HOST_IP" | sed "s/\.[0-9]*$/.0\/24/")
+echo "Host network detected as: $HOST_NETWORK"
+
+# Set up remaining iptables rules
+iptables -A INPUT -s "$HOST_NETWORK" -j ACCEPT
+iptables -A OUTPUT -d "$HOST_NETWORK" -j ACCEPT
+
+# Set default policies to DROP first
+iptables -P INPUT DROP
+iptables -P FORWARD DROP
+iptables -P OUTPUT DROP
+
+# First allow established connections for already approved traffic
+iptables -A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
+iptables -A OUTPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
+
+# Then allow only specific outbound traffic to allowed domains
+iptables -A OUTPUT -m set --match-set allowed-domains dst -j ACCEPT
+
+# Explicitly REJECT all other outbound traffic for immediate feedback
+iptables -A OUTPUT -j REJECT --reject-with icmp-admin-prohibited
+
+echo "Firewall configuration complete"
+echo "Verifying firewall rules..."
+if curl --connect-timeout 5 https://example.com >/dev/null 2>&1; then
+    echo "ERROR: Firewall verification failed - was able to reach https://example.com"
+    exit 1
+else
+    echo "Firewall verification passed - unable to reach https://example.com as expected"
+fi
+
+# Verify GitHub API access
+if ! curl --connect-timeout 5 https://api.github.com/zen >/dev/null 2>&1; then
+    echo "ERROR: Firewall verification failed - unable to reach https://api.github.com"
+    exit 1
+else
+    echo "Firewall verification passed - able to reach https://api.github.com as expected"
+fi
+
+# Verify Anthropic API access
+if ! curl --connect-timeout 5 https://api.anthropic.com >/dev/null 2>&1; then
+    echo "ERROR: Firewall verification failed - unable to reach https://api.anthropic.com"
+    exit 1
+else
+    echo "Firewall verification passed - able to reach https://api.anthropic.com as expected"
+fi
+
+# Verify OpenAI API access
+if ! curl --connect-timeout 5 https://api.openai.com >/dev/null 2>&1; then
+    echo "ERROR: Firewall verification failed - unable to reach https://api.openai.com/"
+    exit 1
+else
+    echo "Firewall verification passed - able to reach https://api.openai.com/ as expected"
+fi
+
+# Verify Gemini API access
+if ! curl --connect-timeout 5 https://www.googleapis.com >/dev/null 2>&1; then
+    echo "ERROR: Firewall verification failed - unable to reach https://www.googleapis.com/"
+    exit 1
+else
+    echo "Firewall verification passed - able to reach https://www.googleapis.com/ as expected"
+fi
+
+# Cloudflare reachability probe
+if ! curl --connect-timeout 5 https://www.cloudflare.com/cdn-cgi/trace >/dev/null 2>&1; then
+    echo "WARN: Could not reach Cloudflare trace endpoint; check ranges and DNS."
+else
+    echo "Cloudflare verification passed."
+fi

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Casey Haralson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,139 @@
+# Orrery
+
+**Workflow planning and orchestration CLI for AI agents**
+
+Orrery is a CLI tool designed to transform high-level development goals into executable, traceable, and engineered workflows. It turns high-level goals ("Add a user login system") into executable, step-by-step plans that agents follow autonomously, ensuring consistent and high-quality results.
+
+## When to Use Orrery
+
+**Good fit:**
+
+- Multi-step features requiring coordinated changes across many files
+- You want to review a plan before letting it run autonomously
+- Tasks with clear dependencies between implementation steps
+
+**Use your AI agent directly when:**
+
+- Quick fixes or small changes
+- Exploratory development where you're discovering as you go
+- You want to stay interactive with every decision
+
+See [Comparison](docs/COMPARISON.md) for a detailed analysis.
+
+## Installation
+
+Prerequisites:
+
+- Node.js
+- Git
+- Initialized Git repository (your project where you want work done)
+- Access to LLM agent tools (Claude Code, Codex cli, or Gemini cli)
+
+### Global Installation
+
+To install Orrery globally on your system:
+
+```bash
+npm install -g @caseyharalson/orrery
+```
+
+## Quick Start
+
+Follow this workflow to go from a high-level goal to finished code.
+
+### 1. Initialize Orrery
+
+Install the necessary "Skills" into your global agent configuration directories (e.g., `~/.claude/skills`). Orrery will auto-detect which agents you have installed.
+
+```bash
+orrery init
+```
+
+### 2. Create a Plan
+
+Navigate to your project directory and use your AI agent (now equipped with the `discovery` skill) to generate a plan.
+
+```bash
+# Using the skill shorthand
+/discovery I want to [goal]
+
+# Or prompt your agent
+"I want to [goal]. Please activate the discovery skill and create a plan."
+```
+
+### 3. Execute
+
+Back in the terminal, run the orrery orchestrator to execute the plan steps. Orrery will create a dedicated work branch and manage agent interactions.
+
+```bash
+orrery exec
+```
+
+## Important: Autonomous Execution
+
+When you run `orrery exec`, agents execute plan steps **autonomously without step-by-step confirmation**. This enables fully automated workflows but means agents can modify files and run commands without asking.
+
+**Built-in safeguards:**
+
+- All work happens on an isolated branch (not your main branch)
+
+**For additional isolation**, run Orrery inside a devcontainer. This provides a sandboxed environment where agent actions are contained. See [Devcontainer Setup](docs/advanced-workflows.md#devcontainer-setup) in Advanced Workflows.
+
+## Advanced Workflows
+
+For power users, Orrery offers additional capabilities:
+
+- **Plan Refinement & Simulation** - Analyze, improve, and explore plans before execution
+- **Devcontainer Setup** - Isolated, reproducible development environments
+- **External Plan Creation** - Import plans from other tools or LLMs
+- **Review Loop** - Iterative code review after each step with automatic fixes
+- **Handling Blocked Plans** - Recovery workflows when steps cannot complete
+
+See [Advanced Workflows](docs/advanced-workflows.md) for details.
+
+---
+
+## Core Concepts
+
+### Skills
+
+Skills are modular instruction sets that teach an agent how to perform specific phases of work.
+
+- **Discovery:** Analyze requirements and generate plans.
+- **Refine-Plan:** Analyze and improve an existing plan by fixing oversights, improving context quality, and strengthening acceptance criteria.
+- **Simulate-Plan:** Conversational dialogue to explore plans, identify risks, and verify approaches before execution.
+
+### Plans
+
+Plans are YAML files that define the "contract" for the work. They break down complex goals into ordered steps with:
+
+- **Dependencies:** Pre-requisites for execution.
+- **Acceptance Criteria:** explicit conditions for success.
+- **Context:** Instructions and file paths relevant to the step.
+
+### The Orchestrator
+
+The Orchestrator (`orrery exec`) is the engine that drives the process. It loads plans, resolves dependencies, invokes the appropriate agents, and manages the lifecycle of the task, including reporting and archiving.
+
+---
+
+## Command Reference
+
+| Command              | Description                                                                        |
+| :------------------- | :--------------------------------------------------------------------------------- |
+| `orrery`             | Command reference.                                                                 |
+| `orrery init`        | Initialize Orrery: install skills to detected agents.                              |
+| `orrery orchestrate` | Executes the active plan. Use `--review` to enable the review loop. Alias: `exec`. |
+| `orrery status`      | Shows the progress of current plans.                                               |
+
+## Directory Structure
+
+Orrery maintains its state in the `.agent-work/` directory (configurable via `ORRERY_WORK_DIR`).
+
+- `.agent-work/plans/`: **Active Plans.** New and in-progress plan files.
+- `.agent-work/reports/`: **Reports.** Step-level execution logs and outcomes.
+- `.agent-work/completed/`: **Archive.** Successfully executed plans are moved here.
+
+---
+
+_Happy Building!_ ❤️