@caseyharalson/orrery 0.10.0 → 0.12.0

package/HELP.md

@@ -0,0 +1,429 @@
+# Orrery CLI Reference
+
+> Run `orrery manual` to display this document.
+
+Orrery is a workflow planning and orchestration CLI for AI agents. It transforms
+high-level development goals into executable, step-by-step plans that agents
+follow autonomously on isolated branches.
+
+---
+
+## Commands
+
+### Setup
+
+#### `orrery init`
+
+Initialize Orrery: install skills to detected agents.
+
+```
+Options:
+  --agent <agent>  Target agent (claude|codex|gemini|all); defaults to auto-detect
+  --force          Overwrite existing skills
+  --dry-run        Show what would be copied without writing files
+```
+
+Example:
+
+```bash
+orrery init
+orrery init --agent claude --force
+```
+
+#### `orrery install-skills`
+
+Install orrery skills for supported agents. Called automatically by `orrery init`.
+
+```
+Options:
+  --agent <agent>  Target agent (claude|codex|gemini|all); defaults to auto-detect
+  --force          Overwrite existing skills
+  --dry-run        Show what would be copied without writing files
+```
+
+#### `orrery install-devcontainer`
+
+Copy the orrery devcontainer to a target directory for sandboxed execution.
+
+```
+Arguments:
+  [target]    Target directory (default: current directory)
+
+Options:
+  --force     Overwrite existing devcontainer
+  --dry-run   Show what would be copied without writing files
+```
+
+Example:
+
+```bash
+orrery install-devcontainer
+orrery install-devcontainer /path/to/project --force
+```
+
+### Execution
+
+#### `orrery orchestrate` (alias: `exec`)
+
+Run plan orchestration for the current project. Loads plans from
+`.agent-work/plans/`, resolves dependencies, and invokes agents to execute
+each step.
+
+```
+Options:
+  --plan <file>   Process only a specific plan file
+  --dry-run       Show what would be executed without running agents
+  --verbose       Show detailed agent output
+  --resume        Resume orchestration on the current work branch
+  --review        Enable code review loop after each step
+  --parallel      Enable parallel execution with git worktrees for isolation
+  --background    Run orchestration as a detached background process
+```
+
+Only one `exec`/`resume` can run at a time per project. A lock file
+(`exec.lock`) prevents concurrent runs and is automatically cleaned up.
+
+Example:
+
+```bash
+orrery exec
+orrery exec --plan my-feature.yaml --review
+orrery exec --parallel --verbose
+orrery exec --background
+```
+
+#### `orrery resume`
+
+Unblock steps and resume orchestration. Auto-detects the plan for the current
+work branch, resets blocked steps to pending, commits, and resumes.
+
+```
+Options:
+  --plan <file>  Resume a specific plan file (skips branch auto-detection)
+  --step <id>    Unblock a specific step before resuming
+  --all          Unblock all blocked steps (default behavior)
+  --dry-run      Preview what would be unblocked without making changes
+```
+
+When `--plan` is provided, the plan's `work_branch` must match the current
+branch. If the plan hasn't been dispatched yet (no `work_branch`), use
+`orrery exec --plan` first.
+
+Example:
+
+```bash
+orrery resume
+orrery resume --plan my-feature.yaml
+orrery resume --step step-2
+orrery resume --dry-run
+```
+
+### Inspection
+
+#### `orrery status`
+
+Show orchestration status for plans in the current project. Auto-detects the
+plan when on a work branch. Also shows whether an orchestration process is
+currently running (via lock file detection) or if a stale lock exists.
+
+```
+Options:
+  --plan <file>  Show detailed status for a specific plan
+```
+
+Example:
+
+```bash
+orrery status
+orrery status --plan my-feature.yaml
+```
+
+#### `orrery validate-plan`
+
+Validate a plan YAML file and normalize its formatting. Also runs as a hook
+when agents write to plan files.
+
+```
+Arguments:
+  [file]          Path to the plan file (or reads from stdin for hook mode)
+
+Options:
+  --no-resave     Skip re-saving the file after validation
+```
+
+Example:
+
+```bash
+orrery validate-plan .agent-work/plans/my-plan.yaml
+```
+
+#### `orrery ingest-plan`
+
+Validate and import an externally created plan file into the plans directory.
+
+```
+Arguments:
+  <file>       Path to the plan file to ingest (required)
+
+Options:
+  --force      Overwrite existing plan file if it exists
+```
+
+Example:
+
+```bash
+orrery ingest-plan ~/plans/my-feature.yaml
+```
+
+### Information
+
+#### `orrery manual`
+
+Show this full CLI reference manual.
+
+#### `orrery help [command]`
+
+Display help for a specific command or the general command list.
+
+#### `orrery --version` / `orrery -v`
+
+Show the installed version.
+
+---
+
+## Common Workflows
+
+### First-Time Setup
+
+```bash
+npm install -g @caseyharalson/orrery
+cd your-project
+orrery init
+```
+
+### Plan Creation and Execution
+
+```bash
+# 1. Use your agent with the discovery skill to create a plan
+/discovery I want to add user authentication
+
+# 2. (Optional) Refine or simulate the plan
+/refine-plan my-plan
+/simulate-plan my-plan
+
+# 3. Execute the plan
+orrery exec
+```
+
+### Handling Blocked Steps
+
+When the orchestrator encounters an issue it cannot resolve, it marks the step
+as blocked and pauses on the work branch.
+
+```bash
+# Check what's blocked
+orrery status
+
+# Fix the underlying issue, then resume
+orrery resume
+
+# Or unblock a specific step
+orrery resume --step step-2
+
+# Preview before resuming
+orrery resume --dry-run
+```
+
+### External Plan Import
+
+```bash
+# Create a plan following the schema (see Plan File Format below)
+# Then validate and import it
+orrery ingest-plan path/to/your-plan.yaml
+
+# Optionally simulate it
+/simulate-plan your-plan
+
+# Execute
+orrery exec
+```
+
+### Review Loop
+
+Enable iterative code review after each step:
+
+```bash
+orrery exec --review
+# Or via environment variable
+export ORRERY_REVIEW_ENABLED=true
+```
+
+The review agent inspects changes after each step. If issues are found, an edit
+agent applies fixes and verification re-runs, repeating until approval or the
+max iteration limit is reached (default: 3).
+
+### Background Execution
+
+Run orchestration as a detached background process:
+
+```bash
+orrery exec --background
+orrery exec --plan my-feature.yaml --background
+```
+
+The process runs detached and logs output to `<work-dir>/exec.log`. Use
+`orrery status` to check progress. A lock file prevents starting a second
+execution while one is already running.
+
+### Parallel Execution
+
+Run independent steps concurrently using git worktrees for isolation:
+
+```bash
+orrery exec --parallel
+# Or via environment variable
+export ORRERY_PARALLEL_ENABLED=true
+```
+
+Steps marked `parallel: true` with no blocking dependencies run concurrently.
+Each agent gets its own worktree. After completion, commits are cherry-picked
+back to the main work branch. Control concurrency with `ORRERY_PARALLEL_MAX`.
+
+---
+
+## Plan File Format
+
+Plans are YAML files stored in `.agent-work/plans/`. For the full schema and
+detailed guidance on building plans, see the
+[plan reference](docs/externally-building-a-plan-reference.md).
+
+### Metadata Fields
+
+| Field         | Required | Description                                      |
+| :------------ | :------- | :----------------------------------------------- |
+| `created_at`  | Yes      | ISO 8601 timestamp                               |
+| `created_by`  | Yes      | Agent or user that created the plan              |
+| `version`     | No       | Plan version                                     |
+| `source_idea` | No       | Original idea or request                         |
+| `outcomes`    | Yes      | Array of user-visible results this plan delivers |
+| `notes`       | No       | General notes for executing agents               |
+
+### Step Fields
+
+| Field           | Required | Description                                               |
+| :-------------- | :------- | :-------------------------------------------------------- |
+| `id`            | Yes      | Unique step identifier                                    |
+| `description`   | Yes      | What this step accomplishes                               |
+| `status`        | No       | `pending` (default), `in_progress`, `complete`, `blocked` |
+| `deps`          | No       | Array of step IDs this step depends on                    |
+| `parallel`      | No       | Whether this step can run in parallel (default: false)    |
+| `context`       | Yes      | Background info needed to execute the step                |
+| `requirements`  | Yes      | Specific requirements for this step                       |
+| `criteria`      | Yes      | Acceptance criteria for completion                        |
+| `files`         | No       | Files this step will create or modify                     |
+| `context_files` | No       | Files to read for context (not modified)                  |
+| `commands`      | No       | Commands to execute (build, test, etc.)                   |
+| `risk_notes`    | No       | Warnings or edge cases                                    |
+
+### Step Statuses
+
+| Status        | Meaning                                      |
+| :------------ | :------------------------------------------- |
+| `pending`     | Not yet started                              |
+| `in_progress` | Currently being executed by an agent         |
+| `complete`    | Successfully finished                        |
+| `blocked`     | Cannot proceed; requires manual intervention |
+
+### Abbreviated Example
+
+```yaml
+metadata:
+  created_at: "2026-01-15T10:00:00Z"
+  created_by: "Discovery-Agent"
+  outcomes:
+    - "Users can log in with email and password"
+
+steps:
+  - id: "1.1"
+    description: "Create auth service"
+    status: "pending"
+    deps: []
+    context: "Implement authentication logic using bcrypt and JWT."
+    requirements:
+      - "Create src/services/auth.js"
+    criteria:
+      - "Login function returns a valid JWT"
+    files:
+      - "src/services/auth.js"
+
+  - id: "1.2"
+    description: "Add login endpoint"
+    status: "pending"
+    deps: ["1.1"]
+    context: "Wire up the auth service to an Express route."
+    requirements:
+      - "POST /api/login"
+    criteria:
+      - "Returns 200 with token on valid credentials"
+      - "Returns 401 on invalid credentials"
+    files:
+      - "src/routes/auth.js"
+    context_files:
+      - "src/services/auth.js"
+```
+
+---
+
+## Skills
+
+Skills are modular instruction sets installed to your agent's configuration
+directory.
+
+| Skill           | Description                                                 |
+| :-------------- | :---------------------------------------------------------- |
+| `discovery`     | Analyze requirements and generate orchestrator-ready plans  |
+| `refine-plan`   | Analyze and improve an existing plan before execution       |
+| `simulate-plan` | Conversational dialogue to explore plans and identify risks |
+
+---
+
+## Directory Structure
+
+Orrery maintains state in `.agent-work/` (configurable via `ORRERY_WORK_DIR`):
+
+```
+.agent-work/
+  plans/        Active plan files (new and in-progress)
+  reports/      Step-level execution logs and outcomes
+  completed/    Successfully executed plans (archived)
+  exec.lock     Lock file when orchestration is running
+  exec.log      Output log for background execution
+```
+
+When `ORRERY_WORK_DIR` is set, Orrery automatically scopes to a project
+subdirectory (`<project-name>-<hash>`) so multiple projects can share the same
+work directory without plan conflicts.
+
+---
+
+## Environment Variables
+
+| Variable                       | Description                                          | Default               |
+| :----------------------------- | :--------------------------------------------------- | :-------------------- |
+| `ORRERY_AGENT_PRIORITY`        | Comma-separated list of agents for failover priority | `codex,gemini,claude` |
+| `ORRERY_AGENT_TIMEOUT`         | Agent failover timeout in milliseconds               | `900000` (15 min)     |
+| `ORRERY_PARALLEL_ENABLED`      | Enable parallel execution with git worktrees         | `false`               |
+| `ORRERY_PARALLEL_MAX`          | Maximum concurrent parallel agents                   | `3`                   |
+| `ORRERY_REVIEW_ENABLED`        | Enable the review loop                               | `false`               |
+| `ORRERY_REVIEW_MAX_ITERATIONS` | Maximum review-edit loop iterations                  | `3`                   |
+| `ORRERY_WORK_DIR`              | Override the work directory path (project-scoped)    | `.agent-work`         |
+
+---
+
+## Exit Codes
+
+| Code | Meaning                                   |
+| :--- | :---------------------------------------- |
+| `0`  | Success                                   |
+| `1`  | General error                             |
+| `2`  | Validation error (plan validation failed) |

package/README.md

@@ -88,6 +88,7 @@ For power users, Orrery offers additional capabilities:
 - **External Plan Creation** - Import plans from other tools or LLMs
 - **Review Loop** - Iterative code review after each step with automatic fixes
 - **Parallel Execution** - Run independent steps concurrently with git worktree isolation
+- **Background Execution** - Run orchestration as a detached process and poll status
 - **Handling Blocked Plans** - Recovery workflows when steps cannot complete
 
 See [Advanced Workflows](docs/advanced-workflows.md) for details.
@@ -120,16 +121,18 @@ The Orchestrator (`orrery exec`) is the engine that drives the process. It loads
 
 ## Command Reference
 
-| Command              | Description                                                                                                   |
-| :------------------- | :------------------------------------------------------------------------------------------------------------ |
-| `orrery`             | Command reference.                                                                                            |
-| `orrery init`        | Initialize Orrery: install skills to detected agents.                                                         |
-| `orrery orchestrate` | Executes the active plan. Use `--review` for review loop, `--parallel` for parallel execution. Alias: `exec`. |
-| `orrery status`      | Shows the progress of current plans.                                                                          |
+| Command              | Description                                                                                                                                     |
+| :------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `orrery`             | Command reference.                                                                                                                              |
+| `orrery init`        | Initialize Orrery: install skills to detected agents.                                                                                           |
+| `orrery manual`      | Show the full CLI reference manual.                                                                                                             |
+| `orrery orchestrate` | Executes the active plan. Use `--review` for review loop, `--parallel` for parallel execution, `--background` for detached mode. Alias: `exec`. |
+| `orrery resume`      | Unblock steps and resume orchestration. Use `--plan` to target a specific plan.                                                                 |
+| `orrery status`      | Shows the progress of current plans and active execution status.                                                                                |
 
 ## Directory Structure
 
-Orrery maintains its state in the `.agent-work/` directory (configurable via `ORRERY_WORK_DIR`).
+Orrery maintains its state in the `.agent-work/` directory (configurable via `ORRERY_WORK_DIR`). When `ORRERY_WORK_DIR` is set, each project gets an isolated subdirectory so multiple projects can share the same work directory.
 
 - `.agent-work/plans/`: **Active Plans.** New and in-progress plan files.
 - `.agent-work/reports/`: **Reports.** Step-level execution logs and outcomes.

package/agent/skills/discovery/SKILL.md

@@ -191,7 +191,15 @@ Use the schema defined in `./schemas/plan-schema.yaml`.
 
 **Output Location:**
 
-- Directory: `.agent-work/plans/`
+First, determine the plans directory by running:
+
+```bash
+orrery plans-dir
+```
+
+This prints the resolved plans directory (respects `ORRERY_WORK_DIR` when set).
+
+- Directory: the path returned by `orrery plans-dir`
 - Filename: `<date>-<plan-name>.yaml`
 - Date format: YYYY-MM-DD (e.g., `2026-01-11`)
 - Plan name: kebab-case description of the task (e.g., `fix-clone-agent-skills`)
@@ -215,7 +223,7 @@ Plans are automatically validated via the PostToolUse hook when written.
 For manual validation, run:
 
 ```bash
-orrery validate-plan .agent-work/plans/<plan>.yaml
+orrery validate-plan <plans-dir>/<plan>.yaml
 ```
 
 This catches common YAML issues like unquoted colons and normalizes formatting.
@@ -405,11 +413,11 @@ Discovery is complete when:
 When the plan is complete and validated, output the plan file path and present the user with their next options:
 
 ```
-Plan created: .agent-work/plans/<date>-<plan-name>.yaml
+Plan created: <plans-dir>/<date>-<plan-name>.yaml
 
 Next steps:
-- /refine-plan .agent-work/plans/<plan-file> — Analyze and improve the plan before execution
-- /simulate-plan .agent-work/plans/<plan-file> — Explore the plan through dialogue, ask "what if" questions
+- /refine-plan <plans-dir>/<plan-file> — Analyze and improve the plan before execution
+- /simulate-plan <plans-dir>/<plan-file> — Explore the plan through dialogue, ask "what if" questions
 - orrery exec — (Command run from the terminal) Execute the plan with the orrery orchestrator
 ```
 

package/agent/skills/orrery-execute/SKILL.md

@@ -39,7 +39,7 @@ These guidelines override generic examples in this skill. For example, if a guid
 
 ### Git State
 
-The orchestrator modifies `.agent-work/` files before you start (marking steps `in_progress`, creating temp files). This is expected. **Ignore changes in `.agent-work/`** when checking git status - these are orchestrator bookkeeping files, not unexpected changes.
+The orchestrator modifies plan and work directory files before you start (marking steps `in_progress`, creating temp files). This is expected. **Ignore changes in the orchestrator work directory** (e.g., `.agent-work/` or the path from `orrery plans-dir`) when checking git status - these are orchestrator bookkeeping files, not unexpected changes.
 
 ### Step 1: Read the Plan
 

package/agent/skills/refine-plan/SKILL.md

@@ -3,7 +3,8 @@ name: refine-plan
 description: >
   Analyze and improve an existing plan file. Reviews plan structure, dependencies,
   context quality, and acceptance criteria, then implements improvements directly.
-  Requires a plan file argument (e.g., /refine-plan .agent-work/plans/my-plan.yaml).
+  Requires a plan file argument (e.g., /refine-plan my-plan.yaml).
+  Run `orrery plans-dir` to find the plans directory.
 hooks:
   PostToolUse:
     - matcher: "Write"
@@ -273,7 +274,7 @@ Ready for execution.
 ## Example Dialogue
 
 ```
-User: /refine-plan .agent-work/plans/analytics-dashboard.yaml
+User: /refine-plan analytics-dashboard.yaml
 
 Agent: I've loaded the analytics dashboard plan. It has 6 steps delivering
 two outcomes. Let me analyze it for improvements.

package/agent/skills/simulate-plan/SKILL.md

@@ -2,7 +2,8 @@
 name: simulate-plan
 description: >
   Explore a plan through conversational dialogue before committing to execution.
-  Requires a plan file argument (e.g., /simulate-plan .agent-work/plans/my-plan.yaml, /simulate-plan my-plan).
+  Requires a plan file argument (e.g., /simulate-plan my-plan.yaml, /simulate-plan my-plan).
+  Run `orrery plans-dir` to find the plans directory.
   Ask "what if" questions, trace dependencies, and build intuition about what you're building.
 ---
 
@@ -164,7 +165,7 @@ Only discuss what's in the plan. If asked about implementation details not cover
 ## Example Dialogue
 
 ```
-User: /simulate .agent-work/plans/analytics-dashboard.yaml
+User: /simulate-plan analytics-dashboard.yaml
 
 Agent: I've loaded the analytics dashboard plan. It has 6 steps delivering
 two outcomes: "Users can see usage trends" and "Admins can export reports."

package/lib/cli/commands/manual.js

@@ -0,0 +1,22 @@
+const fs = require("fs");
+const path = require("path");
+
+module.exports = function registerManualCommand(program) {
+  program
+    .command("manual")
+    .description("Show the full CLI reference manual")
+    .action(() => {
+      const helpPath = path.join(__dirname, "..", "..", "..", "HELP.md");
+      let content;
+      try {
+        content = fs.readFileSync(helpPath, "utf8");
+      } catch {
+        console.error(
+          "HELP.md not found. The reference manual may not be included in this installation."
+        );
+        process.exitCode = 1;
+        return;
+      }
+      process.stdout.write(content);
+    });
+};

package/lib/cli/commands/orchestrate.js

@@ -1,4 +1,9 @@
+const { spawn } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+
 const { orchestrate } = require("../../orchestration");
+const { getWorkDir } = require("../../utils/paths");
 
 module.exports = function registerOrchestrateCommand(program) {
   program
@@ -14,7 +19,54 @@ module.exports = function registerOrchestrateCommand(program) {
       "--parallel",
       "Enable parallel execution with git worktrees for isolation"
     )
+    .option(
+      "--background",
+      "Run orchestration as a detached background process"
+    )
     .action(async (options) => {
+      // Background mode: re-spawn as detached process
+      if (options.background) {
+        if (options.dryRun) {
+          console.log(
+            "Note: --background with --dry-run runs in foreground.\n"
+          );
+          // Fall through to normal execution
+        } else {
+          const args = [];
+          if (options.plan) args.push("--plan", options.plan);
+          if (options.verbose) args.push("--verbose");
+          if (options.resume) args.push("--resume");
+          if (options.review) args.push("--review");
+          if (options.parallel) args.push("--parallel");
+
+          const logFile = path.join(getWorkDir(), "exec.log");
+          const logFd = fs.openSync(logFile, "a");
+
+          const binPath = path.join(
+            __dirname,
+            "..",
+            "..",
+            "..",
+            "bin",
+            "orrery.js"
+          );
+          const child = spawn(process.execPath, [binPath, "exec", ...args], {
+            detached: true,
+            stdio: ["ignore", logFd, logFd],
+            cwd: process.cwd(),
+            env: process.env
+          });
+
+          child.unref();
+          fs.closeSync(logFd);
+
+          console.log(`Background execution started (PID ${child.pid})`);
+          console.log(`Log file: ${logFile}`);
+          console.log("\nUse 'orrery status' to check progress.");
+          return;
+        }
+      }
+
       try {
         await orchestrate({
           plan: options.plan,

package/lib/cli/commands/plans-dir.js

@@ -0,0 +1,10 @@
+const { getPlansDir } = require("../../utils/paths");
+
+module.exports = function registerPlansDirCommand(program) {
+  program
+    .command("plans-dir")
+    .description("Print the resolved plans directory path")
+    .action(() => {
+      console.log(getPlansDir());
+    });
+};